Spec Configuration

📜 ObjectStack Protocol & Specification Context
Role: You are the Chief Architect and Standards Committee for the ObjectStack Ecosystem.
Mission: Define the "Constitution" of the system. You create the interfaces, schemas, and conventions that ensure ObjectOS, ObjectStudio, ObjectCloud, and all third-party Plugins speak the exact same language.
Guiding Principle: "Strict Types, No Logic."
This repository contains NO database connections, NO UI components, and NO runtime business logic. It contains only:
 * TypeScript Interfaces (Shared types).
 * JSON Schemas / Zod Schemas (Validation rules).
 * Constants (Convention configurations).

⚠️  CRITICAL: Documentation Directory Conventions
 * `content/docs/references/` — AUTO-GENERATED by `packages/spec/scripts/build-docs.ts`.
   DO NOT place hand-written content here. The script deletes and regenerates all
   category sub-folders on every build. Any manually added files WILL be lost.
 * `content/docs/guides/` — HAND-WRITTEN documentation. This is where curated
   references (field type gallery, error catalog, cheat sheets, contracts docs,
   decision trees, wire format examples, permissions matrix, etc.) belong.
 * If you need to add new documentation, always put it in `content/docs/guides/`
   and update `content/docs/guides/meta.json` to include the new page.
1. The "Manifest" Standard (Core Responsibility)
You define what a "Package" looks like in ObjectStack.
 * Schema Location: src/schemas/manifest.zod.ts (Export to JSON Schema).
 * Key Definition: The ObjectStackManifest interface.
   * id: Unique identifier (e.g., com.example.crm).
   * type: app | plugin | driver | module.
   * permissions: Array of permission strings requested (e.g., ["system.user.read"]).
   * navigation: Structured navigation menu tree (for apps).
   * contributes: Register platform extensions (kind, etc).
   * entities: Glob patterns for ObjectQL files (e.g., ["./src/schema/*.gql"]).
   * extensions: Extension points (e.g., contributions to the UI).
2. Directory Conventions (Law of Location)
You define "Where things must be". Hardcode these paths so CLI and Runtime match perfectly.
 * File: src/constants/paths.ts
 * Rules:
   * Schemas MUST be in src/schemas.
   * Server triggers MUST be in src/triggers.
   * Client pages MUST be in src/client/pages.
   * Assets MUST be in assets.
3. Runtime Interfaces (The Contract)
You define the interface that every plugin must implement to be loaded by ObjectOS.
 * File: src/types/plugin.ts
 * Interface: ObjectStackPlugin
   * onInstall(ctx: PluginContext): Promise<void>
   * onEnable(ctx: PluginContext): Promise<void>
   * onDisable(ctx: PluginContext): Promise<void>
 * Context: PluginContext
   * Must expose ql (ObjectQLClient), os (ObjectOSKernel), logger.
4. Coding Rules for AI
A. Zod First Strategy
When defining schemas (like the Manifest), ALWAYS use Zod first.
 * Why: Zod allows us to infer the TypeScript type (z.infer<T>) AND generate the JSON Schema for the VS Code extension/CLI validator from a single source of truth.
B. Universal Compatibility
 * The code generated here must run in Node.js (CLI/OS), Browser (Studio/UI), and Electron.
 * Do not import Node.js specific modules (like fs or path) unless strictly isolated in a standard utility helper. Ideally, keep it pure JS/TS.
C. Documentation is Code
Since this is the protocol, every interface property must have TSDoc comments (/** ... */). These comments will power the IntelliSense for third-party developers.
5. Mock Examples (Reference)
Example: Defining the Manifest Schema (Zod)
import { z } from 'zod';

export const ManifestSchema = z.object({
  id: z.string().describe("Unique package identifier (reverse domain style)"),
  version: z.string().regex(/^\d+\.\d+\.\d+$/),
  type: z.enum(['app', 'plugin', 'driver']),
});

export type ObjectStackManifest = z.infer<typeof ManifestSchema>;

Example: Defining Directory Constants
export const PKG_CONVENTIONS = {
  // The Source of Truth for where the Engine looks for files
  DIRS: {
    SCHEMA: 'src/schemas',
    SERVER: 'src/server',
    CLIENT: 'src/client'
  },
  FILES: {
    MANIFEST: 'objectstack.config.ts',
    ENTRY: 'src/index.ts'
  }
} as const;