Add ObjectStack Protocol and Specification Context

Define the ObjectStack Protocol, including standards for package structure, directory conventions, and runtime interfaces.

Author: hotlong

.cursorrules

@@ -0,0 +1,74 @@
+📜 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).
+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"]).
+   * menus: Navigation structure injection.
+   * 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']),
+  menus: z.array(z.object({
+    label: z.string(),
+    path: z.string(),
+    icon: z.string().optional()
+  })).optional()
+});
+
+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;