@objectstack/spec 0.1.0 → 0.1.2

package/README.md

@@ -1,154 +1,167 @@
-# 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:
+## 📦 Architecture
+
+The specification is divided into three protocols:
+
+### 1. Data Protocol (`src/data`)
+*Core Business Logic & Data Modeling*
+*   `Object`, `Field`, `Validation`
+*   `Query` (AST), `Mapping` (ETL)
+*   `Permission`, `Sharing`, `Flow`
+
+### 2. UI Protocol (`src/ui`)
+*Presentation & Interaction*
+*   `App`, `Page`, `View` (Grid/Kanban)
+*   `Dashboard` (Widgets), `Report`
+*   `Action` (Triggers)
+
+### 3. System Protocol (`src/system`)
+*Runtime Configuration & Security*
+*   `Manifest` (Config), `Datasource`
+*   `Role` (Hierarchy), `Identity` (Auth)
+*   `Webhook` (Integration), `Policy` (Compliance)
+
+## 📚 Usage
+
+### Validation (Runtime)
+
 ```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
+import { ObjectSchema } from '@objectstack/spec';
+
+const result = ObjectSchema.safeParse(userConfig);
+if (!result.success) {
+  console.error("Invalid Object definition", result.error);
 }
 ```
 
-#### `ObjectView`
-Represents a view configuration for presenting entity data:
+### Type Definitions (Compile Time)
+
 ```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
-}
+import type { Object, Field } from '@objectstack/spec';
+
+const myObject: Object = {
+  name: "project_task",
+  fields: { ... }
+};
 ```
 
-## Usage
+### 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.
+
+## 🛠️ Development
 
-### Installation
+### Build & Generate
 
 ```bash
-npm install @objectstack/spec
+# Generate JSON Schemas + Markdown Docs + Compile TS
+pnpm build
 ```
 
-### Importing Types
+### Testing
 
-```typescript
-// Import all metamodel types
-import { ObjectEntity, ObjectField, ObjectView, FieldType } from '@objectstack/spec';
+This package includes comprehensive test coverage for all Zod schemas using **Vitest**.
 
-// Or import specific types
-import type { ObjectEntity } from '@objectstack/spec';
-```
+```bash
+# Run tests once
+pnpm test
 
-### Example: Defining an Entity
+# Run tests in watch mode
+pnpm test:watch
 
-```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'
-};
+# Run tests with coverage report
+pnpm test:coverage
 ```
 
-## Building
-
-```bash
-npm install
-npm run build
+#### Test Structure
+
+Tests are co-located with schema files using the `.test.ts` suffix:
+
+```text
+src/
+├── data/
+│   ├── field.zod.ts       # Schema definition
+│   ├── field.test.ts      # Tests
+│   ├── object.zod.ts
+│   └── object.test.ts
+├── ui/
+│   ├── view.zod.ts
+│   └── view.test.ts
+└── system/
+    ├── manifest.zod.ts
+    └── manifest.test.ts
 ```
 
-This will compile TypeScript files to JavaScript and generate type declarations in the `dist/` directory.
+#### Test Coverage
 
-## Philosophy
+Each test file includes:
+*   **Schema Validation Tests**: Verify valid inputs pass and invalid inputs fail
+*   **Default Value Tests**: Ensure default values are applied correctly
+*   **Type Tests**: Test discriminated unions and type narrowing
+*   **Constraint Tests**: Validate naming conventions (snake_case), regex patterns, enums
+*   **Real-World Examples**: Complete, realistic examples from CRM, HR, Sales domains
 
-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
+**Current Coverage**: 263 tests across 13 test files with 100% coverage for tested schemas.
 
-## License
+#### Writing Tests
 
-MIT
+When adding new schemas, follow these patterns:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { YourSchema } from './your-schema.zod';
+
+describe('YourSchema', () => {
+  it('should accept valid data', () => {
+    const valid = { /* valid data */ };
+    expect(() => YourSchema.parse(valid)).not.toThrow();
+  });
+
+  it('should reject invalid data', () => {
+    const invalid = { /* invalid data */ };
+    expect(() => YourSchema.parse(invalid)).toThrow();
+  });
+
+  it('should apply defaults', () => {
+    const result = YourSchema.parse({ /* minimal data */ });
+    expect(result.someField).toBe('default-value');
+  });
+});
+```
+
+### Directory Structure
+
+```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
+└── vitest.config.ts    # Test configuration
+```

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'),
+});