apcore-js 0.1.0

package/planning/registry-system/tasks/schema-export.md

@@ -0,0 +1,261 @@
+# Task: Schema Export
+
+## Goal
+
+Implement schema query and export functions that extract module schema information from the registry and serialize it in JSON or YAML formats. Supports strict mode (via `toStrictSchema()` for OpenAI function calling compatibility), compact mode (truncated descriptions, stripped extensions), and LLM export profiles (MCP, OpenAI, Anthropic, Generic) through the `SchemaExporter` class. Functions operate on individual modules or across all registered modules.
+
+## Files Involved
+
+- `src/registry/schema-export.ts` -- Schema export function implementations
+- `src/registry/registry.ts` -- `Registry` class (consumed as dependency)
+- `src/schema/exporter.ts` -- `SchemaExporter` class
+- `src/schema/strict.ts` -- `toStrictSchema()`, `stripExtensions()`
+- `src/schema/types.ts` -- `ExportProfile`, `SchemaDefinition`
+- `src/module.ts` -- `ModuleAnnotations`, `ModuleExample`
+- `src/errors.ts` -- `ModuleNotFoundError`
+- `tests/registry/test-schema-export.test.ts` -- Schema export tests
+
+## Steps (TDD)
+
+### Step 1: Implement getSchema() for single module
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Registry } from '../../src/registry/registry.js';
+import { getSchema } from '../../src/registry/schema-export.js';
+
+describe('getSchema', () => {
+  it('should extract schema record from registered module', () => {
+    const reg = new Registry();
+    const mod = {
+      name: 'Adder',
+      description: 'Adds two numbers',
+      version: '1.0.0',
+      tags: ['math'],
+      inputSchema: { type: 'object', properties: { a: { type: 'number' } } },
+      outputSchema: { type: 'object', properties: { result: { type: 'number' } } },
+      annotations: null,
+      examples: [],
+    };
+    reg.register('math.add', mod);
+    const schema = getSchema(reg, 'math.add');
+
+    expect(schema).not.toBeNull();
+    expect(schema!['module_id']).toBe('math.add');
+    expect(schema!['name']).toBe('Adder');
+    expect(schema!['description']).toBe('Adds two numbers');
+    expect(schema!['version']).toBe('1.0.0');
+    expect(schema!['tags']).toEqual(['math']);
+    expect(schema!['input_schema']).toEqual(mod.inputSchema);
+    expect(schema!['output_schema']).toEqual(mod.outputSchema);
+  });
+
+  it('should return null for non-existent module', () => {
+    const reg = new Registry();
+    expect(getSchema(reg, 'nonexistent')).toBeNull();
+  });
+});
+```
+
+### Step 2: Implement exportSchema() with JSON serialization
+
+```typescript
+import { exportSchema } from '../../src/registry/schema-export.js';
+
+describe('exportSchema', () => {
+  it('should export schema as formatted JSON string', () => {
+    const reg = new Registry();
+    reg.register('test.mod', {
+      description: 'Test',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    const json = exportSchema(reg, 'test.mod', 'json');
+    const parsed = JSON.parse(json);
+    expect(parsed['module_id']).toBe('test.mod');
+    expect(parsed['description']).toBe('Test');
+  });
+
+  it('should throw ModuleNotFoundError for missing module', () => {
+    const reg = new Registry();
+    expect(() => exportSchema(reg, 'missing')).toThrow();
+  });
+});
+```
+
+### Step 3: YAML format serialization
+
+```typescript
+it('should export schema as YAML string', () => {
+  const reg = new Registry();
+  reg.register('yaml.mod', {
+    description: 'YAML test',
+    inputSchema: { type: 'object' },
+    outputSchema: { type: 'object' },
+    execute: async () => ({}),
+  });
+  const yamlStr = exportSchema(reg, 'yaml.mod', 'yaml');
+  expect(yamlStr).toContain('module_id');
+  expect(yamlStr).toContain('yaml.mod');
+});
+```
+
+### Step 4: Strict mode with toStrictSchema()
+
+```typescript
+it('should apply strict mode transformations', () => {
+  const reg = new Registry();
+  reg.register('strict.mod', {
+    description: 'Strict test',
+    inputSchema: {
+      type: 'object',
+      properties: { a: { type: 'number' } },
+    },
+    outputSchema: { type: 'object' },
+    execute: async () => ({}),
+  });
+  const json = exportSchema(reg, 'strict.mod', 'json', true);
+  const parsed = JSON.parse(json);
+  // Strict mode adds additionalProperties: false, required arrays
+  expect(parsed['input_schema']).toBeDefined();
+});
+```
+
+### Step 5: Compact mode with truncated descriptions
+
+```typescript
+it('should apply compact mode transformations', () => {
+  const reg = new Registry();
+  reg.register('compact.mod', {
+    description: 'First sentence. Second sentence with more details.',
+    inputSchema: { type: 'object' },
+    outputSchema: { type: 'object' },
+    execute: async () => ({}),
+  });
+  const json = exportSchema(reg, 'compact.mod', 'json', false, true);
+  const parsed = JSON.parse(json);
+  expect(parsed['description']).toBe('First sentence.');
+  expect(parsed['documentation']).toBeUndefined();
+  expect(parsed['examples']).toBeUndefined();
+});
+```
+
+### Step 6: LLM export profile support
+
+```typescript
+it('should export with LLM profile', () => {
+  const reg = new Registry();
+  reg.register('profile.mod', {
+    description: 'Profile test',
+    inputSchema: { type: 'object', properties: {} },
+    outputSchema: { type: 'object' },
+    execute: async () => ({}),
+  });
+  const json = exportSchema(reg, 'profile.mod', 'json', false, false, 'generic');
+  const parsed = JSON.parse(json);
+  expect(parsed).toBeDefined();
+});
+```
+
+### Step 7: Implement getAllSchemas()
+
+```typescript
+import { getAllSchemas } from '../../src/registry/schema-export.js';
+
+describe('getAllSchemas', () => {
+  it('should return schema records for all registered modules', () => {
+    const reg = new Registry();
+    reg.register('mod.a', {
+      description: 'A',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    reg.register('mod.b', {
+      description: 'B',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    const schemas = getAllSchemas(reg);
+    expect(Object.keys(schemas)).toHaveLength(2);
+    expect(schemas['mod.a']['module_id']).toBe('mod.a');
+    expect(schemas['mod.b']['module_id']).toBe('mod.b');
+  });
+
+  it('should return empty object for empty registry', () => {
+    const reg = new Registry();
+    expect(getAllSchemas(reg)).toEqual({});
+  });
+});
+```
+
+### Step 8: Implement exportAllSchemas()
+
+```typescript
+import { exportAllSchemas } from '../../src/registry/schema-export.js';
+
+describe('exportAllSchemas', () => {
+  it('should export all schemas as JSON string', () => {
+    const reg = new Registry();
+    reg.register('all.a', {
+      description: 'A',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    const json = exportAllSchemas(reg);
+    const parsed = JSON.parse(json);
+    expect(parsed['all.a']).toBeDefined();
+  });
+
+  it('should apply strict mode to all schemas', () => {
+    const reg = new Registry();
+    reg.register('strict.all', {
+      description: 'Strict all',
+      inputSchema: { type: 'object', properties: { x: { type: 'string' } } },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    const json = exportAllSchemas(reg, 'json', true);
+    const parsed = JSON.parse(json);
+    expect(parsed['strict.all']).toBeDefined();
+  });
+
+  it('should export all schemas as YAML', () => {
+    const reg = new Registry();
+    reg.register('yaml.all', {
+      description: 'YAML',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      execute: async () => ({}),
+    });
+    const yamlStr = exportAllSchemas(reg, 'yaml');
+    expect(yamlStr).toContain('yaml.all');
+  });
+});
+```
+
+## Acceptance Criteria
+
+- [x] `getSchema()` extracts module_id, name, description, version, tags, input_schema, output_schema, annotations, examples
+- [x] `getSchema()` returns null for non-existent modules
+- [x] `exportSchema()` serializes to JSON (default) and YAML formats
+- [x] `exportSchema()` throws `ModuleNotFoundError` for missing modules
+- [x] Strict mode applies `toStrictSchema()` to input and output schemas
+- [x] Compact mode truncates description at first sentence boundary and strips extensions/documentation/examples
+- [x] LLM export profiles (MCP, OpenAI, Anthropic, Generic) are delegated to `SchemaExporter`
+- [x] `getAllSchemas()` returns schema records keyed by module ID for all registered modules
+- [x] `exportAllSchemas()` serializes all schemas with optional strict/compact/profile modes
+- [x] Strict and compact modes are mutually exclusive (strict takes precedence)
+- [x] `deepCopy()` prevents mutation of source module data during transformation
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `registry-core` task (Registry class)
+
+## Estimated Time
+
+3 hours

package/planning/registry-system/tasks/types.md

@@ -0,0 +1,124 @@
+# Task: Types
+
+## Goal
+
+Define the core TypeScript interfaces for the registry system: `ModuleDescriptor` (complete module definition record), `DiscoveredModule` (scanner output representing a found file), and `DependencyInfo` (parsed dependency entry). These interfaces are consumed by every other registry component and provide the type-safe foundation for the entire module lifecycle.
+
+## Files Involved
+
+- `src/registry/types.ts` -- Interface definitions
+- `src/module.ts` -- Imports `ModuleAnnotations` and `ModuleExample` types
+- `tests/registry/test-types.test.ts` -- Type-level and runtime tests
+
+## Steps (TDD)
+
+### Step 1: Define DiscoveredModule interface
+
+Write a test that creates a `DiscoveredModule` object and asserts all fields are accessible:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { DiscoveredModule } from '../../src/registry/types.js';
+
+describe('DiscoveredModule', () => {
+  it('should represent a discovered file with canonical ID', () => {
+    const dm: DiscoveredModule = {
+      filePath: '/extensions/math/add.ts',
+      canonicalId: 'math.add',
+      metaPath: '/extensions/math/add_meta.yaml',
+      namespace: null,
+    };
+    expect(dm.filePath).toBe('/extensions/math/add.ts');
+    expect(dm.canonicalId).toBe('math.add');
+    expect(dm.metaPath).toBe('/extensions/math/add_meta.yaml');
+    expect(dm.namespace).toBeNull();
+  });
+
+  it('should support namespace for multi-root scanning', () => {
+    const dm: DiscoveredModule = {
+      filePath: '/plugins/greet.ts',
+      canonicalId: 'plugins.greet',
+      metaPath: null,
+      namespace: 'plugins',
+    };
+    expect(dm.namespace).toBe('plugins');
+  });
+});
+```
+
+Implement the interface with `filePath: string`, `canonicalId: string`, `metaPath: string | null`, `namespace: string | null`.
+
+### Step 2: Define DependencyInfo interface
+
+Write a test for `DependencyInfo`:
+
+```typescript
+describe('DependencyInfo', () => {
+  it('should represent a module dependency', () => {
+    const dep: DependencyInfo = {
+      moduleId: 'core.auth',
+      version: '2.0.0',
+      optional: false,
+    };
+    expect(dep.moduleId).toBe('core.auth');
+    expect(dep.version).toBe('2.0.0');
+    expect(dep.optional).toBe(false);
+  });
+
+  it('should allow null version for unversioned dependencies', () => {
+    const dep: DependencyInfo = {
+      moduleId: 'utils.logger',
+      version: null,
+      optional: true,
+    };
+    expect(dep.version).toBeNull();
+    expect(dep.optional).toBe(true);
+  });
+});
+```
+
+Implement with `moduleId: string`, `version: string | null`, `optional: boolean`.
+
+### Step 3: Define ModuleDescriptor interface
+
+Write a test for `ModuleDescriptor`:
+
+```typescript
+describe('ModuleDescriptor', () => {
+  it('should represent a complete module definition', () => {
+    const desc: ModuleDescriptor = {
+      moduleId: 'math.add',
+      name: 'Add Numbers',
+      description: 'Adds two numbers together',
+      documentation: 'Detailed usage guide...',
+      inputSchema: { type: 'object', properties: { a: { type: 'number' } } },
+      outputSchema: { type: 'object', properties: { result: { type: 'number' } } },
+      version: '1.0.0',
+      tags: ['math', 'arithmetic'],
+      annotations: null,
+      examples: [],
+      metadata: {},
+    };
+    expect(desc.moduleId).toBe('math.add');
+    expect(desc.tags).toContain('math');
+  });
+});
+```
+
+Implement with all fields including `annotations: ModuleAnnotations | null` and `examples: ModuleExample[]` imported from `../module.js`.
+
+## Acceptance Criteria
+
+- [x] `ModuleDescriptor` interface has all 11 fields: moduleId, name, description, documentation, inputSchema, outputSchema, version, tags, annotations, examples, metadata
+- [x] `DiscoveredModule` interface has 4 fields: filePath, canonicalId, metaPath, namespace
+- [x] `DependencyInfo` interface has 3 fields: moduleId, version, optional
+- [x] All interfaces compile under `tsc --noEmit` with strict mode
+- [x] Types are re-exported from `src/registry/index.ts`
+
+## Dependencies
+
+- `src/module.ts` must define `ModuleAnnotations` and `ModuleExample` types
+
+## Estimated Time
+
+1 hour

package/planning/registry-system/tasks/validation.md

@@ -0,0 +1,177 @@
+# Task: Validation
+
+## Goal
+
+Implement `validateModule()` which performs duck-type structural validation on a module object. Checks that the module has `inputSchema` (non-null object), `outputSchema` (non-null object), `description` (non-empty string), and `execute` (function). Returns an array of error strings -- empty array means valid. Unlike Python's `issubclass` checks, TypeScript uses duck typing to validate structural conformance.
+
+## Files Involved
+
+- `src/registry/validation.ts` -- Validation implementation
+- `tests/registry/test-validation.test.ts` -- Validation tests
+
+## Steps (TDD)
+
+### Step 1: Valid module returns empty error array
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { validateModule } from '../../src/registry/validation.js';
+
+describe('validateModule', () => {
+  it('should return empty array for a valid module', () => {
+    const validModule = {
+      inputSchema: { type: 'object', properties: {} },
+      outputSchema: { type: 'object', properties: {} },
+      description: 'A valid module',
+      execute: async () => ({}),
+    };
+    const errors = validateModule(validModule);
+    expect(errors).toEqual([]);
+  });
+});
+```
+
+### Step 2: Missing inputSchema
+
+```typescript
+it('should report missing inputSchema', () => {
+  const mod = {
+    outputSchema: { type: 'object' },
+    description: 'Test',
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors).toHaveLength(1);
+  expect(errors[0]).toContain('inputSchema');
+});
+```
+
+### Step 3: Missing outputSchema
+
+```typescript
+it('should report missing outputSchema', () => {
+  const mod = {
+    inputSchema: { type: 'object' },
+    description: 'Test',
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors).toHaveLength(1);
+  expect(errors[0]).toContain('outputSchema');
+});
+```
+
+### Step 4: Missing or empty description
+
+```typescript
+it('should report missing description', () => {
+  const mod = {
+    inputSchema: { type: 'object' },
+    outputSchema: { type: 'object' },
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors.some((e) => e.includes('description'))).toBe(true);
+});
+
+it('should report empty string description', () => {
+  const mod = {
+    inputSchema: { type: 'object' },
+    outputSchema: { type: 'object' },
+    description: '',
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors.some((e) => e.includes('description'))).toBe(true);
+});
+```
+
+### Step 5: Missing execute method
+
+```typescript
+it('should report missing execute method', () => {
+  const mod = {
+    inputSchema: { type: 'object' },
+    outputSchema: { type: 'object' },
+    description: 'Test module',
+  };
+  const errors = validateModule(mod);
+  expect(errors.some((e) => e.includes('execute'))).toBe(true);
+});
+```
+
+### Step 6: Multiple validation errors
+
+```typescript
+it('should accumulate all validation errors', () => {
+  const errors = validateModule({});
+  expect(errors.length).toBeGreaterThanOrEqual(3);
+  expect(errors.some((e) => e.includes('inputSchema'))).toBe(true);
+  expect(errors.some((e) => e.includes('outputSchema'))).toBe(true);
+  expect(errors.some((e) => e.includes('description'))).toBe(true);
+  expect(errors.some((e) => e.includes('execute'))).toBe(true);
+});
+```
+
+### Step 7: Non-object inputSchema/outputSchema
+
+```typescript
+it('should reject non-object inputSchema', () => {
+  const mod = {
+    inputSchema: 'not an object',
+    outputSchema: { type: 'object' },
+    description: 'Test',
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors.some((e) => e.includes('inputSchema'))).toBe(true);
+});
+
+it('should reject null inputSchema', () => {
+  const mod = {
+    inputSchema: null,
+    outputSchema: { type: 'object' },
+    description: 'Test',
+    execute: async () => ({}),
+  };
+  const errors = validateModule(mod);
+  expect(errors.some((e) => e.includes('inputSchema'))).toBe(true);
+});
+```
+
+### Step 8: Constructor fallback for class-based modules
+
+```typescript
+it('should check constructor for schema when instance lacks it', () => {
+  class MyModule {
+    static inputSchema = { type: 'object' };
+    static outputSchema = { type: 'object' };
+    description = 'Class-based module';
+    execute = async () => ({});
+  }
+  const instance = new MyModule();
+  const errors = validateModule(instance);
+  expect(errors).toEqual([]);
+});
+```
+
+## Acceptance Criteria
+
+- [x] Valid module with inputSchema (object), outputSchema (object), description (string), execute (function) returns `[]`
+- [x] Missing `inputSchema` produces descriptive error string
+- [x] Missing `outputSchema` produces descriptive error string
+- [x] Missing or empty `description` produces descriptive error string
+- [x] Missing `execute` method produces descriptive error string
+- [x] Non-object `inputSchema`/`outputSchema` (string, null, number) produces error
+- [x] All errors are accumulated and returned together
+- [x] Constructor properties are checked as fallback for class instances
+- [x] Function accepts `unknown` type parameter for flexibility
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `types` task (interfaces for context)
+
+## Estimated Time
+
+1 hour

package/planning/schema-system/overview.md

@@ -0,0 +1,56 @@
+# Feature: Schema System
+
+## Overview
+
+The Schema System is the foundational type infrastructure for apcore. It handles schema loading from YAML files, `$ref` resolution across documents, conversion to TypeBox `TSchema` objects, runtime validation via TypeBox `Value.Check()`/`Value.Decode()`, and export to LLM provider formats (MCP, OpenAI, Anthropic, Generic). The system supports three schema resolution strategies (`yaml_first`, `native_first`, `yaml_only`), annotation merging between YAML and code-defined metadata, and strict-mode transformations for OpenAI function calling compatibility.
+
+## Scope
+
+### Included
+
+- `SchemaDefinition`, `ResolvedSchema`, `SchemaValidationResult`, and `LLMExtensions` interfaces
+- `SchemaStrategy` and `ExportProfile` enums for runtime configuration
+- `SchemaLoader` class with YAML file loading, `jsonSchemaToTypeBox()` conversion, two-level caching (definition + resolved), and strategy-based schema selection
+- `RefResolver` class with `$ref` resolution supporting local pointers, relative file paths, `apcore://` canonical URIs, circular reference detection, and configurable max depth
+- `jsonSchemaToTypeBox()` recursive converter from JSON Schema dictionaries to TypeBox `TSchema` objects
+- `SchemaValidator` class with coercion toggle, `validate()`, `validateInput()`, and `validateOutput()` methods backed by TypeBox `Value.Check()`/`Value.Decode()`/`Value.Errors()`
+- `SchemaExporter` class with four export profiles: MCP (with annotations), OpenAI (strict mode), Anthropic (with examples), Generic (passthrough)
+- `toStrictSchema()`, `stripExtensions()`, `applyLlmDescriptions()` strict-mode utilities
+- `mergeAnnotations()`, `mergeExamples()`, `mergeMetadata()` for YAML/code conflict resolution
+
+### Excluded
+
+- Executor pipeline integration (consumed by `core-executor`)
+- Registry module discovery (consumed by `registry-system`)
+- Decorator-based schema generation (consumed by `decorator-bindings`)
+- YAML schema file authoring and schema directory management
+
+## Technology Stack
+
+- **TypeScript 5.5+** with strict mode
+- **@sinclair/typebox >= 0.34.0** for schema representation and runtime validation
+- **js-yaml** for YAML file parsing
+- **Node.js >= 18.0.0** with ES Module support (`node:fs`, `node:path`)
+- **vitest** for unit testing
+
+## Task Execution Order
+
+| # | Task File | Description | Status |
+|---|-----------|-------------|--------|
+| 1 | [types-and-annotations](./tasks/types-and-annotations.md) | Core interfaces, enums, validation result types, annotation merging | completed |
+| 2 | [loader](./tasks/loader.md) | SchemaLoader with YAML loading, caching, strategy selection | completed |
+| 3 | [ref-resolver](./tasks/ref-resolver.md) | RefResolver with $ref resolution, apcore:// URIs, circular detection | completed |
+| 4 | [typebox-generation](./tasks/typebox-generation.md) | jsonSchemaToTypeBox() recursive JSON Schema to TypeBox conversion | completed |
+| 5 | [validator](./tasks/validator.md) | SchemaValidator with TypeBox validation, coercion toggle, error mapping | completed |
+| 6 | [exporter](./tasks/exporter.md) | SchemaExporter with MCP, OpenAI, Anthropic, Generic export profiles | completed |
+| 7 | [strict-mode](./tasks/strict-mode.md) | toStrictSchema(), stripExtensions(), applyLlmDescriptions() utilities | completed |
+
+## Progress
+
+| Total | Completed | In Progress | Pending |
+|-------|-----------|-------------|---------|
+| 7     | 7         | 0           | 0       |
+
+## Reference Documents
+
+- [Schema System Feature Specification](../../features/schema-system.md)