apcore-js 0.1.0

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

@@ -0,0 +1,157 @@
+# Task: Dependencies
+
+## Goal
+
+Implement `resolveDependencies()` using Kahn's topological sort algorithm to determine a valid module load order. The function builds a directed acyclic graph from module dependency lists, processes nodes in zero-in-degree order (sorted for determinism), detects cycles with path extraction, and throws descriptive errors for missing required dependencies.
+
+## Files Involved
+
+- `src/registry/dependencies.ts` -- Dependency resolution implementation
+- `src/registry/types.ts` -- `DependencyInfo` interface
+- `src/errors.ts` -- `CircularDependencyError`, `ModuleLoadError`
+- `tests/registry/test-dependencies.test.ts` -- Dependency resolution tests
+
+## Steps (TDD)
+
+### Step 1: Basic topological sort with no dependencies
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { resolveDependencies } from '../../src/registry/dependencies.js';
+
+describe('resolveDependencies', () => {
+  it('should return all modules in sorted order when no dependencies exist', () => {
+    const modules: Array<[string, []]> = [
+      ['mod.c', []],
+      ['mod.a', []],
+      ['mod.b', []],
+    ];
+    const order = resolveDependencies(modules);
+    expect(order).toEqual(['mod.a', 'mod.b', 'mod.c']);
+  });
+
+  it('should return empty array for empty input', () => {
+    expect(resolveDependencies([])).toEqual([]);
+  });
+});
+```
+
+### Step 2: Linear dependency chain
+
+```typescript
+it('should resolve linear dependency chain', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.c', [{ moduleId: 'mod.b', version: null, optional: false }]],
+    ['mod.b', [{ moduleId: 'mod.a', version: null, optional: false }]],
+    ['mod.a', []],
+  ];
+  const order = resolveDependencies(modules);
+  expect(order).toEqual(['mod.a', 'mod.b', 'mod.c']);
+});
+```
+
+### Step 3: Diamond dependency pattern
+
+```typescript
+it('should handle diamond dependency pattern', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.d', [
+      { moduleId: 'mod.b', version: null, optional: false },
+      { moduleId: 'mod.c', version: null, optional: false },
+    ]],
+    ['mod.b', [{ moduleId: 'mod.a', version: null, optional: false }]],
+    ['mod.c', [{ moduleId: 'mod.a', version: null, optional: false }]],
+    ['mod.a', []],
+  ];
+  const order = resolveDependencies(modules);
+  expect(order.indexOf('mod.a')).toBeLessThan(order.indexOf('mod.b'));
+  expect(order.indexOf('mod.a')).toBeLessThan(order.indexOf('mod.c'));
+  expect(order.indexOf('mod.b')).toBeLessThan(order.indexOf('mod.d'));
+  expect(order.indexOf('mod.c')).toBeLessThan(order.indexOf('mod.d'));
+});
+```
+
+### Step 4: Circular dependency detection
+
+```typescript
+it('should throw CircularDependencyError for circular dependencies', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.a', [{ moduleId: 'mod.b', version: null, optional: false }]],
+    ['mod.b', [{ moduleId: 'mod.a', version: null, optional: false }]],
+  ];
+  expect(() => resolveDependencies(modules)).toThrow(/[Cc]ircular/);
+});
+
+it('should detect three-node cycle', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.a', [{ moduleId: 'mod.b', version: null, optional: false }]],
+    ['mod.b', [{ moduleId: 'mod.c', version: null, optional: false }]],
+    ['mod.c', [{ moduleId: 'mod.a', version: null, optional: false }]],
+  ];
+  expect(() => resolveDependencies(modules)).toThrow(/[Cc]ircular/);
+});
+```
+
+### Step 5: Missing required dependency
+
+```typescript
+it('should throw ModuleLoadError for missing required dependency', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.a', [{ moduleId: 'mod.missing', version: null, optional: false }]],
+  ];
+  expect(() => resolveDependencies(modules)).toThrow(/not found/);
+});
+```
+
+### Step 6: Optional missing dependency is silently ignored
+
+```typescript
+it('should skip optional dependencies that are not in known IDs', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['mod.a', [{ moduleId: 'mod.optional', version: null, optional: true }]],
+  ];
+  const order = resolveDependencies(modules);
+  expect(order).toEqual(['mod.a']);
+});
+```
+
+### Step 7: Implement extractCycle() for cycle path reporting
+
+The `extractCycle()` helper traces from a remaining node through its dependency edges to find and return the cycle path. This cycle path is included in the `CircularDependencyError` for debugging.
+
+```typescript
+it('should include cycle path in error message', () => {
+  const modules: Array<[string, Array<{ moduleId: string; version: string | null; optional: boolean }>]> = [
+    ['a', [{ moduleId: 'b', version: null, optional: false }]],
+    ['b', [{ moduleId: 'a', version: null, optional: false }]],
+    ['c', []],
+  ];
+  try {
+    resolveDependencies(modules);
+  } catch (e) {
+    const msg = (e as Error).message;
+    expect(msg).toMatch(/a.*b|b.*a/);
+  }
+});
+```
+
+## Acceptance Criteria
+
+- [x] Independent modules are returned in alphabetically sorted order
+- [x] Linear dependency chains are resolved in correct order
+- [x] Diamond dependency patterns are resolved with all constraints satisfied
+- [x] `CircularDependencyError` is thrown for two-node, three-node, and larger cycles
+- [x] `CircularDependencyError` includes the extracted cycle path
+- [x] `ModuleLoadError` is thrown for missing required dependencies
+- [x] Optional missing dependencies are silently skipped
+- [x] Zero-in-degree nodes and dependents are processed in sorted order for determinism
+- [x] Empty input returns empty array
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `types` task (DependencyInfo interface)
+
+## Estimated Time
+
+3 hours

package/planning/registry-system/tasks/entry-point.md

@@ -0,0 +1,148 @@
+# Task: Entry Point
+
+## Goal
+
+Implement `resolveEntryPoint()` which uses async `import()` to dynamically load a TypeScript/JavaScript module file and resolve the appropriate module object. Supports three resolution strategies: (1) metadata-driven class name override via `entry_point` key, (2) default export auto-detection, (3) single named export auto-detection. Includes `snakeToPascal()` utility and `isModuleClass()` duck-type checker.
+
+## Files Involved
+
+- `src/registry/entry-point.ts` -- Entry point resolution implementation
+- `src/registry/validation.ts` -- `validateModule()` (imported for reference)
+- `src/errors.ts` -- `ModuleLoadError`
+- `tests/registry/test-entry-point.test.ts` -- Entry point tests with dynamic module fixtures
+
+## Steps (TDD)
+
+### Step 1: Implement snakeToPascal() utility
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { snakeToPascal } from '../../src/registry/entry-point.js';
+
+describe('snakeToPascal', () => {
+  it('should convert snake_case to PascalCase', () => {
+    expect(snakeToPascal('hello_world')).toBe('HelloWorld');
+    expect(snakeToPascal('my_module_name')).toBe('MyModuleName');
+  });
+
+  it('should handle single word', () => {
+    expect(snakeToPascal('hello')).toBe('Hello');
+  });
+
+  it('should return empty string for empty input', () => {
+    expect(snakeToPascal('')).toBe('');
+  });
+});
+```
+
+### Step 2: Implement isModuleClass() duck-type checker
+
+The checker validates that an object has `inputSchema` (object), `outputSchema` (object), `description` (string), and `execute` (function):
+
+```typescript
+// isModuleClass is private, tested indirectly through resolveEntryPoint
+// but its logic is:
+function isModuleClass(obj: unknown): boolean {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const record = obj as Record<string, unknown>;
+  return (
+    record['inputSchema'] != null &&
+    typeof record['inputSchema'] === 'object' &&
+    record['outputSchema'] != null &&
+    typeof record['outputSchema'] === 'object' &&
+    typeof record['description'] === 'string' &&
+    typeof record['execute'] === 'function'
+  );
+}
+```
+
+### Step 3: Resolve default export
+
+```typescript
+import { resolveEntryPoint } from '../../src/registry/entry-point.js';
+
+describe('resolveEntryPoint', () => {
+  it('should resolve default export that passes isModuleClass', async () => {
+    // Given a .ts file with a default export containing inputSchema,
+    // outputSchema, description, and execute
+    const mod = await resolveEntryPoint('/path/to/valid_default_module.ts');
+    expect(mod).toBeDefined();
+    const obj = mod as Record<string, unknown>;
+    expect(typeof obj['execute']).toBe('function');
+  });
+});
+```
+
+### Step 4: Resolve single named export
+
+```typescript
+it('should resolve single named export when no valid default exists', async () => {
+  // Given a .ts file with one named export that passes isModuleClass
+  const mod = await resolveEntryPoint('/path/to/named_export_module.ts');
+  expect(mod).toBeDefined();
+});
+```
+
+### Step 5: Metadata entry_point override
+
+```typescript
+it('should use metadata entry_point to select specific export', async () => {
+  const meta = { entry_point: 'module:MyModule' };
+  const mod = await resolveEntryPoint('/path/to/multi_export.ts', meta);
+  expect(mod).toBeDefined();
+});
+```
+
+### Step 6: Throw on import failure
+
+```typescript
+it('should throw ModuleLoadError when import fails', async () => {
+  await expect(
+    resolveEntryPoint('/nonexistent/module.ts'),
+  ).rejects.toThrow(/Failed to import/);
+});
+```
+
+### Step 7: Throw on no module class found
+
+```typescript
+it('should throw ModuleLoadError when no Module subclass found', async () => {
+  // Given a .ts file with no exports matching isModuleClass
+  await expect(
+    resolveEntryPoint('/path/to/no_module.ts'),
+  ).rejects.toThrow(/No Module subclass found/);
+});
+```
+
+### Step 8: Throw on ambiguous multiple candidates
+
+```typescript
+it('should throw ModuleLoadError for ambiguous multiple exports', async () => {
+  // Given a .ts file with two named exports both matching isModuleClass
+  await expect(
+    resolveEntryPoint('/path/to/ambiguous_module.ts'),
+  ).rejects.toThrow(/Ambiguous entry point/);
+});
+```
+
+## Acceptance Criteria
+
+- [x] `snakeToPascal()` correctly converts snake_case to PascalCase
+- [x] `isModuleClass()` checks for inputSchema (object), outputSchema (object), description (string), execute (function)
+- [x] Default export is preferred if it passes `isModuleClass()`
+- [x] Single named export is resolved when default export is not a valid module
+- [x] Metadata `entry_point` override selects a specific named export by class name
+- [x] `ModuleLoadError` thrown when async `import()` fails
+- [x] `ModuleLoadError` thrown when no module class is found in exports
+- [x] `ModuleLoadError` thrown when multiple ambiguous candidates exist
+- [x] Function is async, returning `Promise<unknown>`
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `types` task (interfaces for context)
+- `validation` task (structural validation reference)
+
+## Estimated Time
+
+2 hours

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

@@ -0,0 +1,198 @@
+# Task: Metadata
+
+## Goal
+
+Implement YAML metadata loading and merging functions: `loadMetadata()` for parsing `_meta.yaml` companion files, `parseDependencies()` for converting raw dependency arrays to typed `DependencyInfo[]`, `mergeModuleMetadata()` for resolving code-level vs YAML-level property conflicts, and `loadIdMap()` for loading canonical ID override mappings from a YAML file.
+
+## Files Involved
+
+- `src/registry/metadata.ts` -- Metadata function implementations
+- `src/registry/types.ts` -- `DependencyInfo` interface
+- `src/errors.ts` -- `ConfigError`, `ConfigNotFoundError`
+- `tests/registry/test-metadata.test.ts` -- Metadata tests with temp YAML fixtures
+
+## Steps (TDD)
+
+### Step 1: Implement loadMetadata() for YAML parsing
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadMetadata } from '../../src/registry/metadata.js';
+
+describe('loadMetadata', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'meta-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should parse valid YAML metadata file', () => {
+    const metaPath = join(tempDir, 'mod_meta.yaml');
+    writeFileSync(metaPath, 'description: A test module\nversion: "2.0.0"\ntags:\n  - math\n');
+    const meta = loadMetadata(metaPath);
+    expect(meta['description']).toBe('A test module');
+    expect(meta['version']).toBe('2.0.0');
+    expect(meta['tags']).toEqual(['math']);
+  });
+
+  it('should return empty record for missing file', () => {
+    const meta = loadMetadata('/nonexistent/path.yaml');
+    expect(meta).toEqual({});
+  });
+
+  it('should throw ConfigError for invalid YAML', () => {
+    const metaPath = join(tempDir, 'bad_meta.yaml');
+    writeFileSync(metaPath, '{ invalid yaml [[[');
+    expect(() => loadMetadata(metaPath)).toThrow();
+  });
+
+  it('should throw ConfigError for non-mapping YAML', () => {
+    const metaPath = join(tempDir, 'list_meta.yaml');
+    writeFileSync(metaPath, '- item1\n- item2\n');
+    expect(() => loadMetadata(metaPath)).toThrow();
+  });
+});
+```
+
+### Step 2: Implement parseDependencies()
+
+```typescript
+import { parseDependencies } from '../../src/registry/metadata.js';
+
+describe('parseDependencies', () => {
+  it('should convert raw dependency array to DependencyInfo[]', () => {
+    const raw = [
+      { module_id: 'core.auth', version: '1.0.0', optional: false },
+      { module_id: 'utils.logger', optional: true },
+    ];
+    const deps = parseDependencies(raw);
+    expect(deps).toHaveLength(2);
+    expect(deps[0]).toEqual({ moduleId: 'core.auth', version: '1.0.0', optional: false });
+    expect(deps[1]).toEqual({ moduleId: 'utils.logger', version: null, optional: true });
+  });
+
+  it('should skip entries without module_id', () => {
+    const raw = [{ version: '1.0.0' }, { module_id: 'valid' }];
+    const deps = parseDependencies(raw as Array<Record<string, unknown>>);
+    expect(deps).toHaveLength(1);
+    expect(deps[0].moduleId).toBe('valid');
+  });
+
+  it('should return empty array for empty input', () => {
+    expect(parseDependencies([])).toEqual([]);
+  });
+});
+```
+
+### Step 3: Implement mergeModuleMetadata()
+
+```typescript
+import { mergeModuleMetadata } from '../../src/registry/metadata.js';
+
+describe('mergeModuleMetadata', () => {
+  it('should prefer YAML metadata over code-level properties', () => {
+    const moduleObj = {
+      description: 'Code description',
+      name: 'CodeName',
+      version: '1.0.0',
+      tags: ['code-tag'],
+    };
+    const meta = {
+      description: 'YAML description',
+      name: 'YAMLName',
+      version: '2.0.0',
+      tags: ['yaml-tag'],
+    };
+    const merged = mergeModuleMetadata(moduleObj, meta);
+    expect(merged['description']).toBe('YAML description');
+    expect(merged['name']).toBe('YAMLName');
+    expect(merged['version']).toBe('2.0.0');
+    expect(merged['tags']).toEqual(['yaml-tag']);
+  });
+
+  it('should fall back to code-level properties when YAML is empty', () => {
+    const moduleObj = {
+      description: 'Code desc',
+      name: 'CodeName',
+      version: '1.5.0',
+      tags: ['fallback'],
+    };
+    const merged = mergeModuleMetadata(moduleObj, {});
+    expect(merged['description']).toBe('Code desc');
+    expect(merged['name']).toBe('CodeName');
+    expect(merged['version']).toBe('1.5.0');
+  });
+
+  it('should shallow-merge metadata records', () => {
+    const moduleObj = { metadata: { author: 'dev', env: 'prod' } };
+    const meta = { metadata: { env: 'staging', team: 'backend' } };
+    const merged = mergeModuleMetadata(
+      moduleObj as Record<string, unknown>,
+      meta as Record<string, unknown>,
+    );
+    const mergedMeta = merged['metadata'] as Record<string, unknown>;
+    expect(mergedMeta['author']).toBe('dev');
+    expect(mergedMeta['env']).toBe('staging');
+    expect(mergedMeta['team']).toBe('backend');
+  });
+});
+```
+
+### Step 4: Implement loadIdMap()
+
+```typescript
+import { loadIdMap } from '../../src/registry/metadata.js';
+
+describe('loadIdMap', () => {
+  it('should load YAML ID map with mappings list', () => {
+    const mapPath = join(tempDir, 'id_map.yaml');
+    writeFileSync(
+      mapPath,
+      'mappings:\n  - file: math/add.ts\n    id: custom.add\n  - file: utils/log.ts\n    id: custom.log\n',
+    );
+    const idMap = loadIdMap(mapPath);
+    expect(idMap['math/add.ts']['id']).toBe('custom.add');
+    expect(idMap['utils/log.ts']['id']).toBe('custom.log');
+  });
+
+  it('should throw ConfigNotFoundError for missing file', () => {
+    expect(() => loadIdMap('/nonexistent/id_map.yaml')).toThrow();
+  });
+
+  it('should throw ConfigError for missing mappings key', () => {
+    const mapPath = join(tempDir, 'bad_map.yaml');
+    writeFileSync(mapPath, 'other_key: value\n');
+    expect(() => loadIdMap(mapPath)).toThrow(/mappings/);
+  });
+});
+```
+
+## Acceptance Criteria
+
+- [x] `loadMetadata()` parses valid YAML into a `Record<string, unknown>`
+- [x] `loadMetadata()` returns `{}` for non-existent files
+- [x] `loadMetadata()` throws `ConfigError` for invalid YAML or non-mapping content
+- [x] `parseDependencies()` converts raw arrays to typed `DependencyInfo[]`
+- [x] `parseDependencies()` skips entries without `module_id`
+- [x] `parseDependencies()` defaults `version` to `null` and `optional` to `false`
+- [x] `mergeModuleMetadata()` prefers YAML values over code values for description, name, tags, version, annotations, examples, documentation
+- [x] `mergeModuleMetadata()` shallow-merges metadata records (code spread first, then YAML)
+- [x] `loadIdMap()` parses YAML with `mappings` list into file-to-record map
+- [x] `loadIdMap()` throws `ConfigNotFoundError` for missing files
+- [x] `loadIdMap()` throws `ConfigError` for missing or non-array `mappings` key
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `types` task (DependencyInfo interface)
+
+## Estimated Time
+
+2 hours