@objectstack/spec 0.3.1 → 0.3.3

package/json-schema/ui/ViewData.json

@@ -0,0 +1,142 @@
+{
+  "$ref": "#/definitions/ViewData",
+  "definitions": {
+    "ViewData": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "const": "object"
+            },
+            "object": {
+              "type": "string",
+              "description": "Target object name"
+            }
+          },
+          "required": [
+            "provider",
+            "object"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "const": "api"
+            },
+            "read": {
+              "type": "object",
+              "properties": {
+                "url": {
+                  "type": "string",
+                  "description": "API endpoint URL"
+                },
+                "method": {
+                  "type": "string",
+                  "enum": [
+                    "GET",
+                    "POST",
+                    "PUT",
+                    "PATCH",
+                    "DELETE"
+                  ],
+                  "default": "GET",
+                  "description": "HTTP method"
+                },
+                "headers": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Custom HTTP headers"
+                },
+                "params": {
+                  "type": "object",
+                  "additionalProperties": {},
+                  "description": "Query parameters"
+                },
+                "body": {
+                  "description": "Request body for POST/PUT/PATCH"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "additionalProperties": false,
+              "description": "Configuration for fetching data"
+            },
+            "write": {
+              "type": "object",
+              "properties": {
+                "url": {
+                  "type": "string",
+                  "description": "API endpoint URL"
+                },
+                "method": {
+                  "type": "string",
+                  "enum": [
+                    "GET",
+                    "POST",
+                    "PUT",
+                    "PATCH",
+                    "DELETE"
+                  ],
+                  "default": "GET",
+                  "description": "HTTP method"
+                },
+                "headers": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Custom HTTP headers"
+                },
+                "params": {
+                  "type": "object",
+                  "additionalProperties": {},
+                  "description": "Query parameters"
+                },
+                "body": {
+                  "description": "Request body for POST/PUT/PATCH"
+                }
+              },
+              "required": [
+                "url"
+              ],
+              "additionalProperties": false,
+              "description": "Configuration for submitting data (for forms/editable tables)"
+            }
+          },
+          "required": [
+            "provider"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "const": "value"
+            },
+            "items": {
+              "type": "array",
+              "items": {},
+              "description": "Static data array"
+            }
+          },
+          "required": [
+            "provider",
+            "items"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/llms.txt

@@ -0,0 +1,182 @@
+# @objectstack/spec Context for AI Agents
+
+> **SYSTEM NOTE**: This file provides a high-level summary of the ObjectStack Protocol to help LLMs understand the codebase structure and intent.
+
+## 1. Architecture Overview (The "Three-Layer Model")
+
+ObjectStack is a metadata-driven "Post-SaaS Operating System".
+It is divided into three layers, reflected in the import paths:
+
+### Layer 1: ObjectQL (`@objectstack/spec/data`)
+**The Business Kernel**. Defines "What Data Exists".
+- **`ObjectSchema`**: Defines database tables (postgres/mongo agnostic).
+- **`FieldSchema`**: Defines columns with types (`text`, `number`, `lookup`, `formula`).
+- **`QuerySchema`**: A JSON-based AST for querying data (replaces SQL).
+- **`DriverInterface`**: The contract for database adapters.
+
+### Layer 2: ObjectOS (`@objectstack/spec/system` & `@objectstack/spec/api`)
+**The Runtime Kernel**. Defines "How System Operates".
+- **`ManifestSchema`**: `objectstack.config.ts` configuration.
+- **`IdentitySchema`**: Users, Roles, and Authentication.
+- **`EventSchema`**: System bus and Webhooks.
+- **`EndpointSchema`**: API Gateway configuration.
+
+### Layer 3: ObjectUI (`@objectstack/spec/ui`)
+**The Presentation Layer**. Defines "How Users Interact".
+- **`AppSchema`**: Navigation menus and branding.
+- **`ViewSchema`**: Layouts for data (Grid, Kanban, Calendar).
+- **`ActionSchema`**: Buttons and triggers.
+
+---
+
+## 2. Coding Patterns (Zod First)
+
+All definitions are virtually **Zod Schemas**.
+- **Configuration Keys**: `camelCase` (e.g., `maxLength`, `referenceFilters`).
+- **Data Values**: `snake_case` (e.g., `object: 'project_task'`, `type: 'lookup'`).
+
+### Example: Defining an Object
+```typescript
+import { ObjectSchema } from '@objectstack/spec/data';
+
+// Describes a "Task" object
+const taskObject = {
+  name: 'project_task',  // snake_case table name
+  label: 'Project Task',
+  fields: {
+    status: { type: 'select', options: ['todo', 'done'] },
+    priority: { type: 'number', defaultValue: 0 }
+  }
+};
+```
+
+### Example: Building a Query
+```typescript
+import { QuerySchema } from '@objectstack/spec/data';
+
+// JSON-based SQL alternative
+const query = {
+  object: 'project_task',
+  filters: [
+    ['status', '=', 'todo'],
+    'and',
+    ['priority', '>', 1]
+  ],
+  sort: [{ field: 'created_at', order: 'desc' }],
+  top: 10
+};
+```
+
+---
+
+## 3. Key exports by Namespace
+
+### `import * as Data from '@objectstack/spec/data'`
+- `ObjectSchema`, `FieldSchema`: Logic & Storage definition.
+- `QuerySchema`, `FilterSchema`: Data retrieval AST.
+- `DriverInterface`, `DatasourceSchema`: Database connectivity.
+- `WorkflowSchema`, `FlowSchema`: Automation logic.
+
+### `import * as UI from '@objectstack/spec/ui'`
+- `ViewSchema`: `type: 'grid' | 'kanban' | 'calendar'`.
+- `FormSchema`: `layout: 'simple' | 'tabbed'`.
+- `DashboardSchema`: Widget composition.
+
+### `import * as System from '@objectstack/spec/system'`
+- `PluginSchema`: Module lifecycle.
+- `EventSchema`: Pub/Sub definitions.
+- `PolicySchema`: Security rules.
+
+---
+
+## 4. Implementing the Protocol (Engine Devs)
+
+If you are building an ObjectQL engine or Driver in another repository:
+
+### ObjectQL Implementation (Data Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectql.md`*
+
+Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
+
+```typescript
+import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
+// ...
+```
+
+### ObjectOS Implementation (System Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectos.md`*
+
+The Runtime Kernel must be bootstrapped from the Manifest.
+
+```typescript
+import { ManifestSchema, IdentitySchema } from '@objectstack/spec/system';
+import { type RequestEnvelope } from '@objectstack/spec/api';
+
+// 1. Boot: Validate Config
+const config = ManifestSchema.parse(rawConfig);
+
+// 2. Runtime: Validate Identity
+function handleRequest(user: z.infer<typeof IdentitySchema>) { ... }
+```
+
+### ObjectUI Implementation (View Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectui.md`*
+
+The UI must be Server-Driven (SDUI), rendering structures defined by the protocol.
+
+```typescript
+import { ViewSchema, ActionSchema } from '@objectstack/spec/ui';
+
+// ✅ Valid: Components accept Schema Props
+function GridView({ config }: { config: z.infer<typeof ViewSchema> }) {
+  // Render based on config.columns, config.filters...
+}
+```
+
+### ObjectAI Implementation (Intelligence Layer)
+*Reference: `node_modules/@objectstack/spec/prompts/implement-objectai.md`*
+
+AI Agents and RAG pipelines must be schema-aware and permission-safe.
+
+```typescript
+import { AgentSchema, RAGPipelineSchema } from '@objectstack/spec/ai';
+
+// Agents are configured via Protocol, not arbitrary prompts
+const supportAgent = AgentSchema.parse({
+  role: 'support',
+  tools: ['search_knowledge_base', 'create_ticket']
+});
+```
+
+### 1. Strict Type Compliance
+Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
+
+```typescript
+import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
+import { z } from 'zod';
+
+// ✅ CORRECT: Implementing the interface strictly
+export class PostgresDriver implements DriverInterface {
+  name = 'postgres';
+  version = '1.0.0';
+  supports = { transactions: true, ... };
+  
+  // Implementation matches the Zod schema exactly
+  async find(object: string, query: z.infer<typeof QuerySchema>) {
+    // ...
+  }
+}
+```
+
+### 2. Runtime Validation
+The engine **MUST** validate inputs against the Zod schemas before processing.
+
+```typescript
+import { ObjectSchema } from '@objectstack/spec/data';
+
+function registerObject(rawConfig: unknown) {
+  // CRITICAL: Parse strictly throws if protocol is violated
+  const config = ObjectSchema.parse(rawConfig);
+  // ... proceed
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/spec",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,42 +9,54 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./driver": {
+      "types": "./dist/driver/index.d.ts",
+      "default": "./dist/driver/index.js"
+    },
     "./data": {
       "types": "./dist/data/index.d.ts",
       "default": "./dist/data/index.js"
     },
-    "./ui": {
-      "types": "./dist/ui/index.d.ts",
-      "default": "./dist/ui/index.js"
-    },
     "./system": {
       "types": "./dist/system/index.d.ts",
       "default": "./dist/system/index.js"
     },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "default": "./dist/kernel/index.js"
+    },
+    "./hub": {
+      "types": "./dist/hub/index.d.ts",
+      "default": "./dist/hub/index.js"
+    },
     "./ai": {
       "types": "./dist/ai/index.d.ts",
       "default": "./dist/ai/index.js"
     },
+    "./automation": {
+      "types": "./dist/automation/index.d.ts",
+      "default": "./dist/automation/index.js"
+    },
     "./api": {
       "types": "./dist/api/index.d.ts",
       "default": "./dist/api/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
     }
   },
   "files": [
     "dist",
     "json-schema",
+    "prompts",
+    "llms.txt",
     "README.md"
   ],
-  "scripts": {
-    "build": "pnpm gen:schema && pnpm gen:docs && tsc",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist",
-    "gen:schema": "tsx scripts/build-schemas.ts",
-    "gen:docs": "tsx scripts/build-docs.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
-  },
   "keywords": [
     "objectstack",
     "protocol",
@@ -70,5 +82,15 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm gen:schema && pnpm gen:docs && tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "gen:schema": "tsx scripts/build-schemas.ts",
+    "gen:docs": "tsx scripts/build-docs.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/prompts/README.md

@@ -0,0 +1,18 @@
+# AI Context & Prompts
+
+This directory contains architectural context and system prompts designed to help AI Agents (Copilot, Cursor, OpenAI) understand the ObjectStack protocol.
+
+## Usage
+
+If you are building an AI-assisted tool or just want your IDE AI to be smarter about ObjectStack, you can feed these files into the context window.
+
+*   **`architecture.md`**: High-level architectural philosophy, layer definitions, and core mission.
+*   **`instructions.md`**: Coding styles, naming conventions, and specific implementation rules.
+
+## Example (System Prompt)
+
+```text
+You are an expert ObjectStack developer.
+Use the context provided in @objectstack/spec/prompts/architecture.md to understand the system design.
+Follow the rules in @objectstack/spec/prompts/instructions.md when writing code.
+```

package/prompts/architecture.md

@@ -0,0 +1,81 @@
+🌌 ObjectStack Master Architecture Context
+
+Role: You are the Chief Architect and CPO of ObjectStack Inc.
+
+Mission: Build the "Post-SaaS Operating System" — an open-core, local-first ecosystem that virtualizes data (SQL/Redis/Excel) and unifies business logic.
+1. The "Galaxy" Architecture (Monorepo Structure)
+We use a Monorepo (pnpm + Turborepo) to manage the ecosystem, but components are designed to be published independently.
+Directory Structure & Responsibilities
+ * packages/protocol (The Constitution) [Apache 2.0]
+   * CRITICAL: Contains the shared manifest.schema.json, TypeScript interfaces, and plugin lifecycle hooks (onInstall, onEnable).
+   * Rule: All other packages depend on this. No circular dependencies.
+ * packages/objectql (Data Engine) [Apache 2.0]
+   * Universal Data Protocol. Compiles GraphQL-like queries into SQL/Redis commands.
+ * packages/objectos (Business Kernel) [AGPL v3]
+   * The Crown Jewel. Identity, RBAC, Workflow, and Audit Logging.
+   * License Note: Strict AGPL to prevent SaaS wrapping by competitors.
+ * packages/objectui (Projection Engine) [MIT]
+   * React/Shadcn UI components for Server-Driven UI (SDUI).
+ * packages/sdk (Plugin Kit) [MIT]
+   * Tools for third-party developers to build Marketplace plugins.
+ * drivers/* [Apache 2.0]
+   * driver-postgres, driver-redis, driver-excel.
+   * Must implement interfaces defined in packages/protocol.
+Commercial & Apps
+ * apps/www (Official Website): Marketing, Landing Pages, "Platform" Showcase.
+ * apps/marketplace (Public Storefront): SEO-optimized Registry for plugins/drivers.
+ * apps/cloud (SaaS Console): Multi-tenant management dashboard (Private).
+ * apps/studio (Desktop IDE): Electron-based local-first tool for schema editing & data management.
+ * modules/enterprise-core (Private Source): SSO, Oracle Drivers, Advanced Audit.
+
+2. Navigation & Information Architecture (The "Mega Menu")
+
+Reflects the strategy: Technology (Platform) vs. Service (Enterprise).
+Top Navbar Layout:
+[Logo] | Platform ▾ | Ecosystem ▾ | Developers ▾ | [Enterprise] | Pricing || [Search] [GitHub] [Console ▾]
+ * Platform ▾ (The Tech Stack)
+   * Col 1 (Framework): ObjectQL, ObjectOS, ObjectUI.
+   * Col 2 (Tools): Object Studio (Highlight: Local-First IDE), ObjectCloud, CLI.
+   * Footer: "Community vs. Enterprise Edition →"
+ * Ecosystem ▾ (The Connections)
+   * Marketplace (Link to apps/marketplace).
+   * Drivers: Icons for Postgres, Redis, Excel, Salesforce.
+ * Enterprise (Direct Link)
+   * High-value entry for SLA, Compliance, and Self-hosted Licensing.
+ * Console ▾ (Auth Entry)
+   * ObjectCloud (SaaS Login).
+   * Enterprise Portal (License Management).
+   * 
+3. The Packaging Protocol (The "Manifest")
+
+We do not rely solely on package.json. We use a strict ObjectStack Manifest standard.
+File: objectstack.config.ts (or strict JSON inside package.json)
+Schema Location: packages/protocol/schemas/manifest.schema.json
+Key Fields:
+ * type: app | plugin | driver
+ * navigation: Structured navigation menu tree.
+ * contributes: Register platform extensions (e.g., custom kinds).
+ * permissions: Array of requested capabilities (e.g., finance.read).
+ * entities: Path patterns to auto-load Schema files (e.g., ./src/schemas/*.gql).
+ * lifecycle: Hooks for onInstall, onEnable.
+4. Strategic Rules for AI Generation
+A. Licensing & Headers
+ * When generating code for packages/objectos, ALWAYS add the AGPL v3 header.
+ * When generating code for packages/objectql, use Apache 2.0.
+ * When generating code for apps/studio or apps/www, use MIT.
+B. Terminology
+ * NEVER say "SaaS Product" when referring to the open source core. Call it the "Framework" or "Engine".
+ * ALWAYS emphasize "Polyglot Data". We are not just a SQL wrapper; we handle Redis and Excel native files.
+ * Studio vs. Cloud: Studio is for "Local Data & Development". Cloud is for "Deployment & Collaboration".
+C. Coding Style
+ * Monorepo: Use generic imports (e.g., import { User } from '@objectstack/protocol') instead of relative paths like ../../packages/protocol.
+ * UI: Use Shadcn UI + Tailwind CSS. Dark mode default for developer tools (Studio/Console).
+ * Data Fetching: All UI components must be Server-Driven or strongly typed against the Schema.
+5. Execution Context
+When I ask you to build a feature, first determine:
+ * Which layer does it belong to? (Protocol? Engine? UI?)
+ * Is it Open Source or Commercial?
+ * Does it require updating the Protocol Manifest?
+Example:
+User: "Add a CRM plugin."
+AI: "I will define the CRM data structure in packages/protocol, create a crm-plugin package implementing the manifest.json standard, and register the 'Customer' menu item."

package/prompts/implement-objectai.md

@@ -0,0 +1,39 @@
+# ObjectAI Implementation Agent
+
+**Role:** You are the Lead AI Engineer building the `objectai` intelligent layer.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Protocol-Driven Intelligence
+AI Agents must be defined using `ai/agent.zod.ts`.
+- Do not create ad-hoc agent configurations.
+- Agents must expose their capabilities via standard `tools` definitions.
+
+### Rule #2: Schema-Aware RAG
+The RAG pipeline (`ai/rag-pipeline.zod.ts`) must obey ObjectQL security rules.
+- When retrieving documents, the AI **MUST** enforce `PermissionSchema`.
+- Do not allow the LLM to access data the user cannot see (RLS Enforcement).
+
+### Rule #3: Orchestration & chaining
+Complex workflows are orchestrated using `ai/orchestration.zod.ts`.
+- Steps must be strongly typed (input/output validated by Zod).
+- Use `ModelRegistrySchema` to select LLM providers (OpenAI, Anthropic, Local).
+
+## 3. Workflow
+
+1.  **Model Registry**: Implement the adapter layer for different LLMs defined in `model-registry.zod.ts`.
+2.  **Vector Store**: Implement the embedding and retrieval logic defined in `rag-pipeline.zod.ts`.
+3.  **Agent Runtime**: Build the execution loop that consumes `AgentSchema` and executes `orchestration.zod.ts` plans.
+
+## 4. Key Files to Watch
+
+- `ai/agent.zod.ts`: The Agent definition.
+- `ai/model-registry.zod.ts`: LLM provider configuration.
+- `ai/rag-pipeline.zod.ts`: Vector search and retrieval.
+- `ai/orchestration.zod.ts`: Tool execution and planning.

package/prompts/implement-objectos.md

@@ -0,0 +1,48 @@
+# ObjectOS Implementation Agent
+
+**Role:** You are the System Architect building the `objectos` runtime kernel.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Manifest Driven Boot
+The system MUST boot by loading and validating the `objectstack.config.ts`.
+```typescript
+import { ManifestSchema } from '@objectstack/spec/system';
+// The kernel starts here
+const config = ManifestSchema.parse(loadedConfig);
+```
+
+### Rule #2: Security First (Identity & Policy)
+All request handlers must validate against `IdentitySchema`.
+No operation proceeds without checking `PolicySchema`.
+```typescript
+import { IdentitySchema, PolicySchema } from '@objectstack/spec/system';
+```
+
+### Rule #3: API Gateway Contract
+The HTTP/Gateway layer must perform strict request/response validation using `api/contract.zod.ts` and `api/endpoint.zod.ts`.
+- Incoming requests -> Validate `RequestEnvelope`
+- Outgoing responses -> Wrap in `ResponseEnvelope`
+
+### Rule #4: Event Driven Architecture
+System state changes (User created, Schema changed) MUST emit events defined in `EventSchema`.
+Do not invent event formats. Use the standard CloudEvents-compatible structure.
+
+## 3. Workflow
+
+1.  **Define Configuration**: Start by mapping `ManifestSchema` to your runtime config.
+2.  **Initialize Identity**: Implement the Auth Provider using `IdentitySchema`.
+3.  **Setup Gateway**: Configure routes based on `ApiRoutesSchema` (from `api/discovery.zod.ts`).
+
+## 4. Key Files to Watch
+
+- `system/manifest.zod.ts`: The "Kernel Configuration".
+- `system/identity.zod.ts`: The "Security Context".
+- `system/events.zod.ts`: The "System Bus".
+- `api/contract.zod.ts`: The "Wire Protocol".

package/prompts/implement-objectql.md

@@ -0,0 +1,39 @@
+# ObjectQL Implementation Agent
+
+**Role:** You are the Lead Engineer building the `objectql` engine.
+**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
+
+## 1. Setup
+
+You are working in a repository that depends on `@objectstack/spec`.
+Your source of truth is `node_modules/@objectstack/spec`.
+
+## 2. Implementation Rules
+
+### Rule #1: Never Redefine Types
+Do not create your own interfaces for `Object`, `Field`, or `Query`.
+ALWAYS import them:
+```typescript
+import { type Object, ObjectSchema } from '@objectstack/spec/data';
+```
+
+### Rule #2: Schema-First Validation
+Every public method in the Engine must invoke the corresponding Zod parser.
+If the Input does not match `QuerySchema`, the engine must throw a ZodError.
+
+### Rule #3: Driver Compliance
+Drivers must implement `DriverInterface` exactly.
+- Do not add public methods to drivers that are not in the spec.
+- If a feature (like `vectorSearch`) is defined in `DriverCapabilities`, you must check that flag before executing logic.
+
+## 3. Workflow
+
+1.  **Read the Spec**: Before writing logic, read the relevant `.zod.ts` file in `@objectstack/spec`.
+2.  **Scaffold Types**: Create classes that `implements` the imported types.
+3.  **Implement Logic**: Write the code to satisfy the interface.
+
+## 4. Key Files to Watch
+
+- `data/query.zod.ts`: The AST you need to parse.
+- `data/driver.zod.ts`: The interface you need to call.
+- `data/object.zod.ts`: The metadata structure you need to store.