@objectstack/spec 0.1.0 → 0.1.1

package/README.md

@@ -1,154 +1,95 @@
-# ObjectStack Specification
+# @objectstack/spec
 
-The ObjectStack Protocol & Specification repository defines the core type definitions and interfaces for the ObjectStack ecosystem. This repository serves as the "Constitution" of the system, providing the contract between backend (ObjectQL) parsers and frontend (ObjectUI) renderers.
+ObjectStack Protocol & Specification — The "Constitution" of the Ecosystem.
 
-## Purpose
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-This repository contains:
-- **TypeScript Interfaces**: Shared types for the entire ObjectStack ecosystem
-- **No Logic**: Only type definitions, no runtime code or business logic
-- **Universal Compatibility**: Works in Node.js, Browser, and Electron environments
+## 📜 Mission
 
-## Metamodel Interfaces
+This package defines the **DNA** of ObjectStack. It contains:
+1.  **Zod Schemas**: Runtime validation for the Kernel and CLI.
+2.  **TypeScript Interfaces**: `z.infer<>` types for the IDE and Plugin developers.
+3.  **JSON Schemas**: Auto-generated schemas for VS Code IntelliSense.
 
-The metamodel defines the structure for describing data models in ObjectStack:
+**Guiding Principle:** *"Strict Types, No Logic"*
 
-### Core Interfaces
+## 🚀 Installation
 
-#### `FieldType`
-Defines the available field data types:
-- Text types: `text`, `textarea`, `email`, `url`
-- Numeric types: `number`, `currency`, `percentage`
-- Date/Time types: `date`, `datetime`
-- Relation types: `lookup`
-- Selection types: `select`, `multiselect`
-- Special types: `boolean`, `json`, `file`, `image`
-
-#### `ObjectField`
-Represents a field definition within an entity:
-```typescript
-interface ObjectField {
-  name: string;           // Field identifier
-  label: string;          // Display label
-  type: FieldType;        // Data type
-  required?: boolean;     // Validation
-  unique?: boolean;       // Constraint
-  lookupEntity?: string;  // For lookup fields
-  // ... and more options
-}
+```bash
+pnpm install @objectstack/spec
 ```
 
-#### `ObjectEntity`
-Represents a complete entity (data model) definition:
-```typescript
-interface ObjectEntity {
-  name: string;           // Entity identifier
-  label: string;          // Singular display label
-  pluralLabel: string;    // Plural display label
-  fields: ObjectField[];  // Field definitions
-  primaryKey?: string;    // Primary key field
-  displayField?: string;  // Display field for lookups
-  // ... and more options
-}
-```
+## 📦 Architecture
 
-#### `ObjectView`
-Represents a view configuration for presenting entity data:
-```typescript
-interface ObjectView {
-  name: string;           // View identifier
-  label: string;          // Display label
-  entityName: string;     // Target entity
-  type: ViewType;         // Presentation type (list, form, detail, etc.)
-  fields?: string[];      // Fields to display
-  columns?: ViewColumn[]; // Column configuration
-  filters?: ViewFilter[]; // Default filters
-  sort?: ViewSort[];      // Default sort order
-  // ... and more options
-}
-```
+The specification is divided into three protocols:
 
-## Usage
+### 1. Data Protocol (`src/data`)
+*Core Business Logic & Data Modeling*
+*   `Object`, `Field`, `Validation`
+*   `Query` (AST), `Mapping` (ETL)
+*   `Permission`, `Sharing`, `Flow`
 
-### Installation
+### 2. UI Protocol (`src/ui`)
+*Presentation & Interaction*
+*   `App`, `Page`, `View` (Grid/Kanban)
+*   `Dashboard` (Widgets), `Report`
+*   `Action` (Triggers)
 
-```bash
-npm install @objectstack/spec
-```
+### 3. System Protocol (`src/system`)
+*Runtime Configuration & Security*
+*   `Manifest` (Config), `Datasource`
+*   `Role` (Hierarchy), `Identity` (Auth)
+*   `Webhook` (Integration), `Policy` (Compliance)
+
+## 📚 Usage
 
-### Importing Types
+### Validation (Runtime)
 
 ```typescript
-// Import all metamodel types
-import { ObjectEntity, ObjectField, ObjectView, FieldType } from '@objectstack/spec';
+import { ObjectSchema } from '@objectstack/spec';
 
-// Or import specific types
-import type { ObjectEntity } from '@objectstack/spec';
+const result = ObjectSchema.safeParse(userConfig);
+if (!result.success) {
+  console.error("Invalid Object definition", result.error);
+}
 ```
 
-### Example: Defining an Entity
+### Type Definitions (Compile Time)
 
 ```typescript
-import { ObjectEntity, ObjectField } from '@objectstack/spec';
-
-const userEntity: ObjectEntity = {
-  name: 'User',
-  label: 'User',
-  pluralLabel: 'Users',
-  description: 'System user account',
-  fields: [
-    {
-      name: 'id',
-      label: 'ID',
-      type: 'text',
-      required: true,
-      readonly: true
-    },
-    {
-      name: 'email',
-      label: 'Email',
-      type: 'email',
-      required: true,
-      unique: true
-    },
-    {
-      name: 'name',
-      label: 'Full Name',
-      type: 'text',
-      required: true
-    },
-    {
-      name: 'role',
-      label: 'Role',
-      type: 'select',
-      required: true,
-      options: [
-        { value: 'admin', label: 'Administrator' },
-        { value: 'user', label: 'User' }
-      ]
-    }
-  ],
-  primaryKey: 'id',
-  displayField: 'name'
+import type { Object, Field } from '@objectstack/spec';
+
+const myObject: Object = {
+  name: "project_task",
+  fields: { ... }
 };
 ```
 
-## Building
-
-```bash
-npm install
-npm run build
-```
+### JSON Schema (Tooling)
+The package includes valid JSON Schemas in the `/json-schema` directory.
+These can be used with:
+*   [Ajv](https://ajv.js.org/) (High-performance validator)
+*   [React Json Schema Form](https://rjsf-team.github.io/) (Auto-forms)
+*   VS Code `json.schemas` setting for IntelliSense.
 
-This will compile TypeScript files to JavaScript and generate type declarations in the `dist/` directory.
+## 🛠️ Development
 
-## Philosophy
+### Build & Generate
 
-Following the ObjectStack Protocol:
-- **Strict Types, No Logic**: This repository contains only type definitions
-- **Documentation as Code**: Every interface property has TSDoc comments for IntelliSense
-- **Universal Compatibility**: Pure TypeScript with no platform-specific dependencies
+```bash
+# Generate JSON Schemas + Markdown Docs + Compile TS
+pnpm build
+```
 
-## License
+### Directory Structure
 
-MIT
+```text
+packages/spec/
+├── src/                # Source Truth (Zod)
+│   ├── data/           # ObjectQL Protocol
+│   ├── ui/             # ObjectUI Protocol
+│   └── system/         # ObjectOS Protocol
+├── json-schema/        # Auto-generated (npm run gen:schema)
+└── dist/               # Compiled JS/D.TS
+```

package/dist/ai/agent.zod.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+/**
+ * AI Model Configuration
+ */
+export declare const AIModelConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<["openai", "azure_openai", "anthropic", "local"]>>;
+    model: z.ZodString;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    provider: "openai" | "azure_openai" | "anthropic" | "local";
+    model: string;
+    temperature: number;
+    maxTokens?: number | undefined;
+    topP?: number | undefined;
+}, {
+    model: string;
+    provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    topP?: number | undefined;
+}>;
+/**
+ * AI Tool Definition
+ * References to Actions, Flows, or Objects available to the Agent.
+ */
+export declare const AIToolSchema: z.ZodObject<{
+    type: z.ZodEnum<["action", "flow", "query", "vector_search"]>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "action" | "flow" | "query" | "vector_search";
+    name: string;
+    description?: string | undefined;
+}, {
+    type: "action" | "flow" | "query" | "vector_search";
+    name: string;
+    description?: string | undefined;
+}>;
+/**
+ * AI Knowledge Base
+ * RAG configuration.
+ */
+export declare const AIKnowledgeSchema: z.ZodObject<{
+    topics: z.ZodArray<z.ZodString, "many">;
+    indexes: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    indexes: string[];
+    topics: string[];
+}, {
+    indexes: string[];
+    topics: string[];
+}>;
+/**
+ * AI Agent Schema
+ * Definition of an autonomous agent specialized for a domain.
+ */
+export declare const AgentSchema: z.ZodObject<{
+    /** Identity */
+    name: z.ZodString;
+    label: z.ZodString;
+    avatar: z.ZodOptional<z.ZodString>;
+    role: z.ZodString;
+    /** Cognition */
+    instructions: z.ZodString;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodEnum<["openai", "azure_openai", "anthropic", "local"]>>;
+        model: z.ZodString;
+        temperature: z.ZodDefault<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        provider: "openai" | "azure_openai" | "anthropic" | "local";
+        model: string;
+        temperature: number;
+        maxTokens?: number | undefined;
+        topP?: number | undefined;
+    }, {
+        model: string;
+        provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        topP?: number | undefined;
+    }>>;
+    /** Capabilities */
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["action", "flow", "query", "vector_search"]>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "action" | "flow" | "query" | "vector_search";
+        name: string;
+        description?: string | undefined;
+    }, {
+        type: "action" | "flow" | "query" | "vector_search";
+        name: string;
+        description?: string | undefined;
+    }>, "many">>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        topics: z.ZodArray<z.ZodString, "many">;
+        indexes: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        indexes: string[];
+        topics: string[];
+    }, {
+        indexes: string[];
+        topics: string[];
+    }>>;
+    /** Interface */
+    active: z.ZodDefault<z.ZodBoolean>;
+    access: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    name: string;
+    active: boolean;
+    role: string;
+    instructions: string;
+    avatar?: string | undefined;
+    model?: {
+        provider: "openai" | "azure_openai" | "anthropic" | "local";
+        model: string;
+        temperature: number;
+        maxTokens?: number | undefined;
+        topP?: number | undefined;
+    } | undefined;
+    tools?: {
+        type: "action" | "flow" | "query" | "vector_search";
+        name: string;
+        description?: string | undefined;
+    }[] | undefined;
+    knowledge?: {
+        indexes: string[];
+        topics: string[];
+    } | undefined;
+    access?: string[] | undefined;
+}, {
+    label: string;
+    name: string;
+    role: string;
+    instructions: string;
+    avatar?: string | undefined;
+    active?: boolean | undefined;
+    model?: {
+        model: string;
+        provider?: "openai" | "azure_openai" | "anthropic" | "local" | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        topP?: number | undefined;
+    } | undefined;
+    tools?: {
+        type: "action" | "flow" | "query" | "vector_search";
+        name: string;
+        description?: string | undefined;
+    }[] | undefined;
+    knowledge?: {
+        indexes: string[];
+        topics: string[];
+    } | undefined;
+    access?: string[] | undefined;
+}>;
+export type Agent = z.infer<typeof AgentSchema>;
+export type AITool = z.infer<typeof AIToolSchema>;
+//# sourceMappingURL=agent.zod.d.ts.map

package/dist/ai/agent.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.zod.d.ts","sourceRoot":"","sources":["../../src/ai/agent.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;EAM9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;EAIvB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,eAAe;;;;;IAMf,gBAAgB;;;;;;;;;;;;;;;;;;;;;IAIhB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;IAInB,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/ai/agent.zod.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentSchema = exports.AIKnowledgeSchema = exports.AIToolSchema = exports.AIModelConfigSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * AI Model Configuration
+ */
+exports.AIModelConfigSchema = zod_1.z.object({
+    provider: zod_1.z.enum(['openai', 'azure_openai', 'anthropic', 'local']).default('openai'),
+    model: zod_1.z.string().describe('Model name (e.g. gpt-4, claude-3-opus)'),
+    temperature: zod_1.z.number().min(0).max(2).default(0.7),
+    maxTokens: zod_1.z.number().optional(),
+    topP: zod_1.z.number().optional(),
+});
+/**
+ * AI Tool Definition
+ * References to Actions, Flows, or Objects available to the Agent.
+ */
+exports.AIToolSchema = zod_1.z.object({
+    type: zod_1.z.enum(['action', 'flow', 'query', 'vector_search']),
+    name: zod_1.z.string().describe('Reference name (Action Name, Flow Name)'),
+    description: zod_1.z.string().optional().describe('Override description for the LLM'),
+});
+/**
+ * AI Knowledge Base
+ * RAG configuration.
+ */
+exports.AIKnowledgeSchema = zod_1.z.object({
+    topics: zod_1.z.array(zod_1.z.string()).describe('Topics/Tags to recruit knowledge from'),
+    indexes: zod_1.z.array(zod_1.z.string()).describe('Vector Store Indexes'),
+});
+/**
+ * AI Agent Schema
+ * Definition of an autonomous agent specialized for a domain.
+ */
+exports.AgentSchema = zod_1.z.object({
+    /** Identity */
+    name: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Agent unique identifier'),
+    label: zod_1.z.string().describe('Agent display name'),
+    avatar: zod_1.z.string().optional(),
+    role: zod_1.z.string().describe('The persona/role (e.g. "Senior Support Engineer")'),
+    /** Cognition */
+    instructions: zod_1.z.string().describe('System Prompt / Prime Directives'),
+    model: exports.AIModelConfigSchema.optional(),
+    /** Capabilities */
+    tools: zod_1.z.array(exports.AIToolSchema).optional().describe('Available tools'),
+    knowledge: exports.AIKnowledgeSchema.optional().describe('RAG access'),
+    /** Interface */
+    active: zod_1.z.boolean().default(true),
+    access: zod_1.z.array(zod_1.z.string()).optional().describe('Who can chat with this agent'),
+});

package/dist/data/dataset.zod.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * Data Import Strategy
+ * Defines how the engine handles existing records.
+ */
+export declare const DatasetMode: z.ZodEnum<["insert", "update", "upsert", "replace", "ignore"]>;
+/**
+ * Dataset Schema (Seed Data / Fixtures)
+ *
+ * Standardized format for transporting data.
+ * Used for:
+ * 1. System Bootstrapping (Admin accounts, Standard Roles)
+ * 2. Reference Data (Countries, Currencies)
+ * 3. Demo/Test Data
+ */
+export declare const DatasetSchema: z.ZodObject<{
+    /**
+     * Target Object
+     * The machine name of the object to populate.
+     */
+    object: z.ZodString;
+    /**
+     * Idempotency Key (The "Upsert" Key)
+     * The field used to check if a record already exists.
+     * Best Practice: Use a natural key like 'code', 'slug', 'username' or 'external_id'.
+     * Standard: '_id' (internal ID) is rarely used for portable seed data.
+     */
+    externalId: z.ZodDefault<z.ZodString>;
+    /**
+     * Import Strategy
+     */
+    mode: z.ZodDefault<z.ZodEnum<["insert", "update", "upsert", "replace", "ignore"]>>;
+    /**
+     * Environment Scope
+     * - 'all': Always load
+     * - 'dev': Only for development/demo
+     * - 'test': Only for CI/CD tests
+     */
+    env: z.ZodDefault<z.ZodArray<z.ZodEnum<["prod", "dev", "test"]>, "many">>;
+    /**
+     * The Payload
+     * Array of raw JSON objects matching the Object Schema.
+     */
+    records: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    externalId: string;
+    mode: "insert" | "update" | "upsert" | "replace" | "ignore";
+    env: ("prod" | "dev" | "test")[];
+    records: Record<string, any>[];
+}, {
+    object: string;
+    records: Record<string, any>[];
+    externalId?: string | undefined;
+    mode?: "insert" | "update" | "upsert" | "replace" | "ignore" | undefined;
+    env?: ("prod" | "dev" | "test")[] | undefined;
+}>;
+export type Dataset = z.infer<typeof DatasetSchema>;
+export type DatasetImportMode = z.infer<typeof DatasetMode>;
+//# sourceMappingURL=dataset.zod.d.ts.map

package/dist/data/dataset.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.zod.d.ts","sourceRoot":"","sources":["../../src/data/dataset.zod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,WAAW,gEAMtB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;IACxB;;;OAGG;;IAGH;;;;;OAKG;;IAGH;;OAEG;;IAGH;;;;;OAKG;;IAGH;;;OAGG;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACpD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/data/dataset.zod.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatasetSchema = exports.DatasetMode = void 0;
+const zod_1 = require("zod");
+/**
+ * Data Import Strategy
+ * Defines how the engine handles existing records.
+ */
+exports.DatasetMode = zod_1.z.enum([
+    'insert', // Try to insert, fail on duplicate
+    'update', // Only update found records, ignore new
+    'upsert', // Create new or Update existing (Standard)
+    'replace', // Delete ALL records in object then insert (Dangerous - use for cache tables)
+    'ignore' // Try to insert, silently skip duplicates
+]);
+/**
+ * Dataset Schema (Seed Data / Fixtures)
+ *
+ * Standardized format for transporting data.
+ * Used for:
+ * 1. System Bootstrapping (Admin accounts, Standard Roles)
+ * 2. Reference Data (Countries, Currencies)
+ * 3. Demo/Test Data
+ */
+exports.DatasetSchema = zod_1.z.object({
+    /**
+     * Target Object
+     * The machine name of the object to populate.
+     */
+    object: zod_1.z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Target Object Name'),
+    /**
+     * Idempotency Key (The "Upsert" Key)
+     * The field used to check if a record already exists.
+     * Best Practice: Use a natural key like 'code', 'slug', 'username' or 'external_id'.
+     * Standard: '_id' (internal ID) is rarely used for portable seed data.
+     */
+    externalId: zod_1.z.string().default('name').describe('Field match for uniqueness check'),
+    /**
+     * Import Strategy
+     */
+    mode: exports.DatasetMode.default('upsert').describe('Conflict resolution strategy'),
+    /**
+     * Environment Scope
+     * - 'all': Always load
+     * - 'dev': Only for development/demo
+     * - 'test': Only for CI/CD tests
+     */
+    env: zod_1.z.array(zod_1.z.enum(['prod', 'dev', 'test'])).default(['prod', 'dev', 'test']).describe('Applicable environments'),
+    /**
+     * The Payload
+     * Array of raw JSON objects matching the Object Schema.
+     */
+    records: zod_1.z.array(zod_1.z.record(zod_1.z.any())).describe('Data records'),
+});