apcore-js 0.1.0

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

@@ -0,0 +1,323 @@
+# Task: Registry Core
+
+## Goal
+
+Implement the central `Registry` class that orchestrates the full 8-step async discovery pipeline and provides module query, registration, event, and cache management APIs. The constructor accepts optional configuration for extension roots and ID maps. The async `discover()` method coordinates scanning, metadata loading, entry point resolution, validation, dependency resolution, and ordered registration. Manual `register()`/`unregister()` methods support programmatic module management with lifecycle hooks (`onLoad`/`onUnload`) and event callbacks.
+
+## Files Involved
+
+- `src/registry/registry.ts` -- Registry class implementation
+- `src/registry/scanner.ts` -- `scanExtensions()`, `scanMultiRoot()`
+- `src/registry/metadata.ts` -- `loadMetadata()`, `mergeModuleMetadata()`, `loadIdMap()`, `parseDependencies()`
+- `src/registry/dependencies.ts` -- `resolveDependencies()`
+- `src/registry/entry-point.ts` -- `resolveEntryPoint()`
+- `src/registry/validation.ts` -- `validateModule()`
+- `src/registry/types.ts` -- `ModuleDescriptor`, `DependencyInfo`
+- `src/config.ts` -- `Config` class
+- `src/errors.ts` -- `InvalidInputError`, `ModuleNotFoundError`
+- `tests/registry/test-registry.test.ts` -- Registry integration tests
+
+## Steps (TDD)
+
+### Step 1: Constructor with extension root options
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Registry } from '../../src/registry/registry.js';
+
+describe('Registry constructor', () => {
+  it('should default to ./extensions root', () => {
+    const reg = new Registry();
+    expect(reg.count).toBe(0);
+  });
+
+  it('should accept extensionsDir option', () => {
+    const reg = new Registry({ extensionsDir: '/custom/path' });
+    expect(reg.count).toBe(0);
+  });
+
+  it('should throw when both extensionsDir and extensionsDirs are provided', () => {
+    expect(
+      () => new Registry({ extensionsDir: '/a', extensionsDirs: ['/b'] }),
+    ).toThrow(/Cannot specify both/);
+  });
+});
+```
+
+### Step 2: Manual register() and unregister()
+
+```typescript
+describe('register/unregister', () => {
+  it('should register a module and make it queryable', () => {
+    const reg = new Registry();
+    const mod = {
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      description: 'Test',
+      execute: async () => ({}),
+    };
+    reg.register('test.mod', mod);
+    expect(reg.has('test.mod')).toBe(true);
+    expect(reg.get('test.mod')).toBe(mod);
+    expect(reg.count).toBe(1);
+  });
+
+  it('should throw on duplicate registration', () => {
+    const reg = new Registry();
+    const mod = { execute: async () => ({}) };
+    reg.register('dup', mod);
+    expect(() => reg.register('dup', mod)).toThrow(/already exists/);
+  });
+
+  it('should throw on empty module ID', () => {
+    const reg = new Registry();
+    expect(() => reg.register('', {})).toThrow(/non-empty/);
+  });
+
+  it('should unregister and return true', () => {
+    const reg = new Registry();
+    reg.register('mod', {});
+    expect(reg.unregister('mod')).toBe(true);
+    expect(reg.has('mod')).toBe(false);
+    expect(reg.count).toBe(0);
+  });
+
+  it('should return false for unregistering non-existent module', () => {
+    const reg = new Registry();
+    expect(reg.unregister('nonexistent')).toBe(false);
+  });
+});
+```
+
+### Step 3: Lifecycle hooks (onLoad/onUnload)
+
+```typescript
+describe('lifecycle hooks', () => {
+  it('should call onLoad during register()', () => {
+    const reg = new Registry();
+    let loaded = false;
+    const mod = { onLoad: () => { loaded = true; } };
+    reg.register('hook.mod', mod);
+    expect(loaded).toBe(true);
+  });
+
+  it('should rollback registration if onLoad throws', () => {
+    const reg = new Registry();
+    const mod = { onLoad: () => { throw new Error('init failed'); } };
+    expect(() => reg.register('fail.mod', mod)).toThrow('init failed');
+    expect(reg.has('fail.mod')).toBe(false);
+  });
+
+  it('should call onUnload during unregister()', () => {
+    const reg = new Registry();
+    let unloaded = false;
+    const mod = { onUnload: () => { unloaded = true; } };
+    reg.register('unload.mod', mod);
+    reg.unregister('unload.mod');
+    expect(unloaded).toBe(true);
+  });
+
+  it('should swallow onUnload errors', () => {
+    const reg = new Registry();
+    const mod = { onUnload: () => { throw new Error('cleanup failed'); } };
+    reg.register('err.mod', mod);
+    expect(() => reg.unregister('err.mod')).not.toThrow();
+  });
+});
+```
+
+### Step 4: Query methods (get, has, list, iter, count, moduleIds)
+
+```typescript
+describe('query methods', () => {
+  it('should return null for non-existent module via get()', () => {
+    const reg = new Registry();
+    expect(reg.get('nope')).toBeNull();
+  });
+
+  it('should throw ModuleNotFoundError for empty string via get()', () => {
+    const reg = new Registry();
+    expect(() => reg.get('')).toThrow();
+  });
+
+  it('should list module IDs in sorted order', () => {
+    const reg = new Registry();
+    reg.register('z.mod', {});
+    reg.register('a.mod', {});
+    reg.register('m.mod', {});
+    expect(reg.list()).toEqual(['a.mod', 'm.mod', 'z.mod']);
+  });
+
+  it('should filter list by prefix', () => {
+    const reg = new Registry();
+    reg.register('math.add', {});
+    reg.register('math.sub', {});
+    reg.register('text.upper', {});
+    expect(reg.list({ prefix: 'math.' })).toEqual(['math.add', 'math.sub']);
+  });
+
+  it('should filter list by tags', () => {
+    const reg = new Registry();
+    reg.register('tagged', { tags: ['math', 'core'] });
+    reg.register('untagged', {});
+    expect(reg.list({ tags: ['math'] })).toEqual(['tagged']);
+  });
+
+  it('should iterate over modules via iter()', () => {
+    const reg = new Registry();
+    reg.register('a', { value: 1 });
+    reg.register('b', { value: 2 });
+    const entries = [...reg.iter()];
+    expect(entries).toHaveLength(2);
+  });
+
+  it('should return sorted moduleIds', () => {
+    const reg = new Registry();
+    reg.register('z', {});
+    reg.register('a', {});
+    expect(reg.moduleIds).toEqual(['a', 'z']);
+  });
+});
+```
+
+### Step 5: getDefinition() returns ModuleDescriptor
+
+```typescript
+describe('getDefinition', () => {
+  it('should return ModuleDescriptor for registered module', () => {
+    const reg = new Registry();
+    const mod = {
+      name: 'Adder',
+      description: 'Adds numbers',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      version: '2.0.0',
+      tags: ['math'],
+    };
+    reg.register('math.add', mod);
+    const def = reg.getDefinition('math.add');
+    expect(def).not.toBeNull();
+    expect(def!.moduleId).toBe('math.add');
+    expect(def!.name).toBe('Adder');
+    expect(def!.description).toBe('Adds numbers');
+    expect(def!.version).toBe('2.0.0');
+  });
+
+  it('should return null for non-existent module', () => {
+    const reg = new Registry();
+    expect(reg.getDefinition('nope')).toBeNull();
+  });
+});
+```
+
+### Step 6: Event system via on()
+
+```typescript
+describe('event system', () => {
+  it('should fire register event callback', () => {
+    const reg = new Registry();
+    const events: string[] = [];
+    reg.on('register', (id) => events.push(id));
+    reg.register('evented', {});
+    expect(events).toEqual(['evented']);
+  });
+
+  it('should fire unregister event callback', () => {
+    const reg = new Registry();
+    const events: string[] = [];
+    reg.on('unregister', (id) => events.push(id));
+    reg.register('temp', {});
+    reg.unregister('temp');
+    expect(events).toEqual(['temp']);
+  });
+
+  it('should throw on invalid event name', () => {
+    const reg = new Registry();
+    expect(() => reg.on('invalid', () => {})).toThrow(/Invalid event/);
+  });
+
+  it('should swallow callback errors silently', () => {
+    const reg = new Registry();
+    reg.on('register', () => { throw new Error('callback failed'); });
+    expect(() => reg.register('safe', {})).not.toThrow();
+  });
+});
+```
+
+### Step 7: clearCache()
+
+```typescript
+describe('clearCache', () => {
+  it('should clear the schema cache without affecting modules', () => {
+    const reg = new Registry();
+    reg.register('cached', {});
+    reg.clearCache();
+    expect(reg.has('cached')).toBe(true);
+  });
+});
+```
+
+### Step 8: Async discover() pipeline (integration)
+
+```typescript
+describe('discover', () => {
+  it('should execute the 8-step pipeline and return registered count', async () => {
+    // Create temp directory with valid module files
+    // const reg = new Registry({ extensionsDir: tempDir });
+    // const count = await reg.discover();
+    // expect(count).toBeGreaterThanOrEqual(0);
+    // expect(reg.count).toBe(count);
+  });
+});
+```
+
+The 8-step `discover()` pipeline:
+
+```typescript
+async discover(): Promise<number> {
+  // Step 1: Scan extension roots (scanExtensions or scanMultiRoot)
+  // Step 2: Apply ID map overrides
+  // Step 3: Load metadata (loadMetadata for each discovered module)
+  // Step 4: Resolve entry points (await resolveEntryPoint for each)
+  // Step 5: Validate modules (validateModule, drop invalid)
+  // Step 6: Collect dependencies (parseDependencies from metadata)
+  // Step 7: Resolve dependency order (resolveDependencies via Kahn's sort)
+  // Step 8: Register in dependency order (mergeModuleMetadata, onLoad, trigger events)
+  return registeredCount;
+}
+```
+
+## Acceptance Criteria
+
+- [x] Constructor accepts optional `config`, `extensionsDir`, `extensionsDirs`, `idMapPath`
+- [x] `extensionsDir` and `extensionsDirs` are mutually exclusive (throws `InvalidInputError`)
+- [x] `discover()` is async, returns `Promise<number>` of registered modules
+- [x] `discover()` executes all 8 pipeline steps in order
+- [x] `register()` adds modules with `onLoad` lifecycle hook
+- [x] `register()` throws on empty ID or duplicate ID
+- [x] `register()` rolls back on `onLoad` failure
+- [x] `unregister()` removes module, clears metadata and schema cache, calls `onUnload`
+- [x] `unregister()` swallows `onUnload` errors
+- [x] `get()` returns module or null; throws `ModuleNotFoundError` for empty string
+- [x] `has()` returns boolean for module existence
+- [x] `list()` returns sorted IDs with optional prefix and tags filtering
+- [x] `iter()` returns `IterableIterator<[string, unknown]>`
+- [x] `count` getter returns module count
+- [x] `moduleIds` getter returns sorted ID array
+- [x] `getDefinition()` returns `ModuleDescriptor` or null
+- [x] `on()` registers event callbacks for 'register' and 'unregister'
+- [x] Event callbacks that throw are silently swallowed
+- [x] `clearCache()` clears schema cache without affecting registered modules
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `scanner` task
+- `metadata` task
+- `dependencies` task
+- `entry-point` task
+- `validation` task
+
+## Estimated Time
+
+5 hours

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

@@ -0,0 +1,172 @@
+# Task: Scanner
+
+## Goal
+
+Implement `scanExtensions()` and `scanMultiRoot()` functions that recursively walk extension directories, discover `.ts`/`.js` module files, build dot-notation canonical IDs from relative paths, detect companion `_meta.yaml` files, handle case collisions, and support configurable depth limits and symlink following. `scanMultiRoot()` coordinates multiple extension roots with namespace prefixing and uniqueness enforcement.
+
+## Files Involved
+
+- `src/registry/scanner.ts` -- Scanner implementation
+- `src/registry/types.ts` -- `DiscoveredModule` interface
+- `src/errors.ts` -- `ConfigError`, `ConfigNotFoundError`
+- `tests/registry/test-scanner.test.ts` -- Scanner tests with temp directory fixtures
+
+## Steps (TDD)
+
+### Step 1: Implement scanExtensions() basic file discovery
+
+Write a test that creates a temp directory with `.ts` files and verifies discovery:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { scanExtensions } from '../../src/registry/scanner.js';
+
+describe('scanExtensions', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'scan-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should discover .ts and .js files', () => {
+    writeFileSync(join(tempDir, 'add.ts'), 'export default {}');
+    writeFileSync(join(tempDir, 'sub.js'), 'module.exports = {}');
+    const results = scanExtensions(tempDir);
+    const ids = results.map((r) => r.canonicalId).sort();
+    expect(ids).toEqual(['add', 'sub']);
+  });
+});
+```
+
+Implement the recursive directory walker with `readdirSync`/`statSync`, filtering valid extensions.
+
+### Step 2: Skip .d.ts, test files, dot/underscore prefixed entries
+
+```typescript
+it('should skip declaration and test files', () => {
+  writeFileSync(join(tempDir, 'types.d.ts'), '');
+  writeFileSync(join(tempDir, 'foo.test.ts'), '');
+  writeFileSync(join(tempDir, 'bar.spec.js'), '');
+  writeFileSync(join(tempDir, 'valid.ts'), 'export default {}');
+  const results = scanExtensions(tempDir);
+  expect(results).toHaveLength(1);
+  expect(results[0].canonicalId).toBe('valid');
+});
+
+it('should skip dot-prefixed and underscore-prefixed entries', () => {
+  writeFileSync(join(tempDir, '.hidden.ts'), '');
+  writeFileSync(join(tempDir, '_private.ts'), '');
+  writeFileSync(join(tempDir, 'public.ts'), 'export default {}');
+  const results = scanExtensions(tempDir);
+  expect(results).toHaveLength(1);
+});
+```
+
+Add `SKIP_SUFFIXES` array and entry name filters.
+
+### Step 3: Build canonical IDs with dot notation from nested paths
+
+```typescript
+it('should build dot-notation canonical IDs from nested directories', () => {
+  mkdirSync(join(tempDir, 'math'), { recursive: true });
+  writeFileSync(join(tempDir, 'math', 'add.ts'), 'export default {}');
+  const results = scanExtensions(tempDir);
+  expect(results[0].canonicalId).toBe('math.add');
+});
+```
+
+Use `relative()` and replace path separators with dots, strip extensions.
+
+### Step 4: Detect companion _meta.yaml files
+
+```typescript
+it('should detect companion _meta.yaml metadata files', () => {
+  writeFileSync(join(tempDir, 'greet.ts'), 'export default {}');
+  writeFileSync(join(tempDir, 'greet_meta.yaml'), 'description: Hello');
+  const results = scanExtensions(tempDir);
+  expect(results[0].metaPath).toContain('greet_meta.yaml');
+});
+```
+
+### Step 5: Respect maxDepth configuration
+
+```typescript
+it('should respect maxDepth limit', () => {
+  const deep = join(tempDir, 'a', 'b', 'c');
+  mkdirSync(deep, { recursive: true });
+  writeFileSync(join(deep, 'mod.ts'), 'export default {}');
+  const shallow = scanExtensions(tempDir, 2);
+  expect(shallow).toHaveLength(0);
+  const deeper = scanExtensions(tempDir, 4);
+  expect(deeper).toHaveLength(1);
+});
+```
+
+### Step 6: Throw ConfigNotFoundError for missing root directory
+
+```typescript
+it('should throw ConfigNotFoundError for non-existent directory', () => {
+  expect(() => scanExtensions('/nonexistent/path')).toThrow();
+});
+```
+
+### Step 7: Implement scanMultiRoot() with namespace prefixing
+
+```typescript
+import { scanMultiRoot } from '../../src/registry/scanner.js';
+
+describe('scanMultiRoot', () => {
+  it('should prepend namespace to canonical IDs', () => {
+    const root1 = mkdtempSync(join(tmpdir(), 'root1-'));
+    writeFileSync(join(root1, 'add.ts'), 'export default {}');
+    const roots = [{ root: root1, namespace: 'math' }];
+    const results = scanMultiRoot(roots);
+    expect(results[0].canonicalId).toBe('math.add');
+    expect(results[0].namespace).toBe('math');
+    rmSync(root1, { recursive: true, force: true });
+  });
+
+  it('should throw on duplicate namespaces', () => {
+    const root1 = mkdtempSync(join(tmpdir(), 'dup1-'));
+    const root2 = mkdtempSync(join(tmpdir(), 'dup2-'));
+    const roots = [
+      { root: root1, namespace: 'ns' },
+      { root: root2, namespace: 'ns' },
+    ];
+    expect(() => scanMultiRoot(roots)).toThrow(/Duplicate namespace/);
+    rmSync(root1, { recursive: true, force: true });
+    rmSync(root2, { recursive: true, force: true });
+  });
+});
+```
+
+## Acceptance Criteria
+
+- [x] `scanExtensions()` discovers `.ts` and `.js` files recursively
+- [x] `.d.ts`, `.test.ts`, `.test.js`, `.spec.ts`, `.spec.js` files are skipped
+- [x] Dot-prefixed and underscore-prefixed entries are skipped
+- [x] `node_modules` and `__pycache__` directories are skipped
+- [x] Canonical IDs use dot notation derived from relative paths
+- [x] Case collisions are detected (warning-level, not blocking)
+- [x] Companion `_meta.yaml` files are detected and recorded in `metaPath`
+- [x] `maxDepth` parameter limits recursion depth
+- [x] `followSymlinks` parameter controls symlink traversal (note: `statSync` bug)
+- [x] `ConfigNotFoundError` thrown for non-existent root directories
+- [x] `scanMultiRoot()` prepends namespace to canonical IDs
+- [x] `scanMultiRoot()` throws `ConfigError` on duplicate namespaces
+- [x] All tests pass with `vitest`
+
+## Dependencies
+
+- `types` task (DiscoveredModule interface)
+
+## Estimated Time
+
+3 hours