apcore-js 0.1.0

package/tests/test-bindings.test.ts

@@ -0,0 +1,227 @@
+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 { BindingLoader } from '../src/bindings.js';
+import { Registry } from '../src/registry/registry.js';
+import {
+  BindingInvalidTargetError,
+  BindingFileInvalidError,
+  BindingModuleNotFoundError,
+  BindingCallableNotFoundError,
+  BindingNotCallableError,
+} from '../src/errors.js';
+
+let tmpDir: string;
+let loader: BindingLoader;
+let registry: Registry;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'apcore-binding-test-'));
+  loader = new BindingLoader();
+  registry = new Registry();
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function writeTempModule(filename: string, content: string): string {
+  const filePath = join(tmpDir, filename);
+  writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}
+
+function writeTempYaml(filename: string, content: string): string {
+  const filePath = join(tmpDir, filename);
+  writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}
+
+describe('BindingLoader', () => {
+  describe('instantiation', () => {
+    it('creates a new instance', () => {
+      expect(new BindingLoader()).toBeInstanceOf(BindingLoader);
+    });
+
+    it('has loadBindings, loadBindingDir, and resolveTarget methods', () => {
+      const bl = new BindingLoader();
+      expect(typeof bl.loadBindings).toBe('function');
+      expect(typeof bl.loadBindingDir).toBe('function');
+      expect(typeof bl.resolveTarget).toBe('function');
+    });
+  });
+
+  describe('resolveTarget', () => {
+    it('throws BindingInvalidTargetError for target without colon', async () => {
+      await expect(loader.resolveTarget('no_colon_here')).rejects.toThrow(BindingInvalidTargetError);
+    });
+
+    it('throws BindingModuleNotFoundError for non-existent module path', async () => {
+      await expect(
+        loader.resolveTarget('/nonexistent/path/to/module.mjs:someFunc'),
+      ).rejects.toThrow(BindingModuleNotFoundError);
+    });
+
+    it('successfully resolves a function export from a real JS module', async () => {
+      const modPath = writeTempModule(
+        'func_export.mjs',
+        'export function greet(name) { return `Hello, ${name}`; }\n',
+      );
+      const fn = await loader.resolveTarget(`${modPath}:greet`);
+      expect(typeof fn).toBe('function');
+      expect(fn('World')).toBe('Hello, World');
+    });
+
+    it('successfully resolves a class method', async () => {
+      const modPath = writeTempModule(
+        'class_export.mjs',
+        `export class Calculator {\n  add(a, b) { return a + b; }\n}\n`,
+      );
+      const fn = await loader.resolveTarget(`${modPath}:Calculator.add`);
+      expect(typeof fn).toBe('function');
+      expect(fn(2, 3)).toBe(5);
+    });
+
+    it('throws BindingCallableNotFoundError for missing callable', async () => {
+      const modPath = writeTempModule('missing_callable.mjs', 'export function exists() { return true; }\n');
+      await expect(loader.resolveTarget(`${modPath}:doesNotExist`)).rejects.toThrow(BindingCallableNotFoundError);
+    });
+
+    it('throws BindingNotCallableError for non-function export', async () => {
+      const modPath = writeTempModule('non_callable.mjs', 'export const MY_CONSTANT = 42;\n');
+      await expect(loader.resolveTarget(`${modPath}:MY_CONSTANT`)).rejects.toThrow(BindingNotCallableError);
+    });
+  });
+
+  describe('loadBindings', () => {
+    it('throws BindingFileInvalidError for non-existent file', async () => {
+      await expect(
+        loader.loadBindings('/nonexistent/path/binding.yaml', registry),
+      ).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for invalid YAML', async () => {
+      const yamlPath = writeTempYaml('invalid.binding.yaml', '{ invalid yaml: [unclosed');
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for empty file', async () => {
+      const yamlPath = writeTempYaml('empty.binding.yaml', '');
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for missing bindings key', async () => {
+      const yamlPath = writeTempYaml('nokey.binding.yaml', 'other_key: value\n');
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for non-array bindings value', async () => {
+      const yamlPath = writeTempYaml('notarray.binding.yaml', 'bindings: "not an array"\n');
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for binding entry missing module_id', async () => {
+      const modPath = writeTempModule('dummy_mod.mjs', 'export function dummy() { return {}; }\n');
+      const yamlPath = writeTempYaml('noid.binding.yaml', `bindings:\n  - target: "${modPath}:dummy"\n`);
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('throws BindingFileInvalidError for binding entry missing target', async () => {
+      const yamlPath = writeTempYaml('notarget.binding.yaml', 'bindings:\n  - module_id: "test.module"\n');
+      await expect(loader.loadBindings(yamlPath, registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('successfully loads valid binding with inline schemas', async () => {
+      const modPath = writeTempModule(
+        'inline_schema_mod.mjs',
+        'export function process(inputs) { return { result: inputs.name }; }\n',
+      );
+      const yamlPath = writeTempYaml(
+        'inline.binding.yaml',
+        `bindings:\n  - module_id: "test.inline"\n    target: "${modPath}:process"\n    description: "Inline schema test"\n    version: "2.0.0"\n    tags:\n      - demo\n    input_schema:\n      type: object\n      properties:\n        name:\n          type: string\n    output_schema:\n      type: object\n      properties:\n        result:\n          type: string\n`,
+      );
+      const results = await loader.loadBindings(yamlPath, registry);
+      expect(results).toHaveLength(1);
+      expect(results[0].moduleId).toBe('test.inline');
+      expect(results[0].description).toBe('Inline schema test');
+      expect(results[0].version).toBe('2.0.0');
+    });
+
+    it('successfully loads binding with permissive fallback (no schema)', async () => {
+      const modPath = writeTempModule('permissive_mod.mjs', 'export function loose(inputs) { return { ok: true }; }\n');
+      const yamlPath = writeTempYaml(
+        'permissive.binding.yaml',
+        `bindings:\n  - module_id: "test.permissive"\n    target: "${modPath}:loose"\n`,
+      );
+      const results = await loader.loadBindings(yamlPath, registry);
+      expect(results).toHaveLength(1);
+      expect(results[0].moduleId).toBe('test.permissive');
+      expect(results[0].inputSchema).toBeDefined();
+      expect(results[0].outputSchema).toBeDefined();
+    });
+
+    it('registers modules in the registry', async () => {
+      const modPath = writeTempModule('registered_mod.mjs', 'export function handler() { return {}; }\n');
+      const yamlPath = writeTempYaml(
+        'register.binding.yaml',
+        `bindings:\n  - module_id: "test.registered"\n    target: "${modPath}:handler"\n`,
+      );
+      await loader.loadBindings(yamlPath, registry);
+      expect(registry.has('test.registered')).toBe(true);
+    });
+
+    it('loads multiple binding entries from single file', async () => {
+      const modPath = writeTempModule(
+        'multi_mod.mjs',
+        `export function funcA() { return { a: true }; }\nexport function funcB() { return { b: true }; }\n`,
+      );
+      const yamlPath = writeTempYaml(
+        'multi.binding.yaml',
+        `bindings:\n  - module_id: "test.multi.a"\n    target: "${modPath}:funcA"\n  - module_id: "test.multi.b"\n    target: "${modPath}:funcB"\n`,
+      );
+      const results = await loader.loadBindings(yamlPath, registry);
+      expect(results).toHaveLength(2);
+      expect(registry.has('test.multi.a')).toBe(true);
+      expect(registry.has('test.multi.b')).toBe(true);
+    });
+  });
+
+  describe('loadBindingDir', () => {
+    it('throws BindingFileInvalidError for non-existent directory', async () => {
+      await expect(loader.loadBindingDir('/nonexistent/dir/path', registry)).rejects.toThrow(BindingFileInvalidError);
+    });
+
+    it('loads all *.binding.yaml files in directory', async () => {
+      const bindDir = join(tmpDir, 'bindings');
+      mkdirSync(bindDir);
+
+      const modPath = writeTempModule(
+        'dir_mod.mjs',
+        `export function alpha() { return { alpha: true }; }\nexport function beta() { return { beta: true }; }\n`,
+      );
+
+      writeTempYaml(
+        join('bindings', 'alpha.binding.yaml'),
+        `bindings:\n  - module_id: "dir.alpha"\n    target: "${modPath}:alpha"\n`,
+      );
+      writeTempYaml(
+        join('bindings', 'beta.binding.yaml'),
+        `bindings:\n  - module_id: "dir.beta"\n    target: "${modPath}:beta"\n`,
+      );
+
+      const results = await loader.loadBindingDir(bindDir, registry);
+      expect(results).toHaveLength(2);
+      expect(registry.has('dir.alpha')).toBe(true);
+      expect(registry.has('dir.beta')).toBe(true);
+    });
+
+    it('returns empty array for directory with no binding files', async () => {
+      const emptyDir = join(tmpDir, 'empty');
+      mkdirSync(emptyDir);
+
+      const results = await loader.loadBindingDir(emptyDir, registry);
+      expect(results).toHaveLength(0);
+    });
+  });
+});

package/tests/test-config.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { Config } from '../src/config.js';
+
+describe('Config', () => {
+  it('creates with provided data', () => {
+    const cfg = new Config({ name: 'test' });
+    expect(cfg.get('name')).toBe('test');
+  });
+
+  it('creates with no arguments', () => {
+    const cfg = new Config();
+    expect(cfg.get('anything')).toBeUndefined();
+  });
+
+  it('returns various value types', () => {
+    const cfg = new Config({
+      str: 'hello',
+      num: 42,
+      bool: true,
+      arr: [1, 2, 3],
+      obj: { nested: true },
+      nil: null,
+    });
+    expect(cfg.get('str')).toBe('hello');
+    expect(cfg.get('num')).toBe(42);
+    expect(cfg.get('bool')).toBe(true);
+    expect(cfg.get('arr')).toEqual([1, 2, 3]);
+    expect(cfg.get('obj')).toEqual({ nested: true });
+    expect(cfg.get('nil')).toBeNull();
+  });
+
+  it('traverses nested objects with dot-path', () => {
+    const cfg = new Config({
+      database: {
+        host: 'db.example.com',
+        port: 5432,
+        credentials: { user: 'admin', password: 'secret' },
+      },
+    });
+    expect(cfg.get('database.host')).toBe('db.example.com');
+    expect(cfg.get('database.port')).toBe(5432);
+    expect(cfg.get('database.credentials.user')).toBe('admin');
+  });
+
+  it('returns nested object for partial path', () => {
+    const cfg = new Config({ a: { b: { c: 'deep' } } });
+    expect(cfg.get('a.b')).toEqual({ c: 'deep' });
+  });
+
+  it('returns undefined when key missing and no default', () => {
+    const cfg = new Config({ x: 1 });
+    expect(cfg.get('y')).toBeUndefined();
+  });
+
+  it('returns default value when key missing', () => {
+    const cfg = new Config({ x: 1 });
+    expect(cfg.get('y', 'fallback')).toBe('fallback');
+    expect(cfg.get('y', 42)).toBe(42);
+  });
+
+  it('returns default when dot-path partially exists', () => {
+    const cfg = new Config({ a: { b: 1 } });
+    expect(cfg.get('a.c', 'default')).toBe('default');
+    expect(cfg.get('a.b.c.d', 'deep-default')).toBe('deep-default');
+  });
+
+  it('returns default when traversal hits non-object', () => {
+    const cfg = new Config({ a: 'string-value' });
+    expect(cfg.get('a.b', 'default')).toBe('default');
+  });
+
+  it('returns default when traversal hits null', () => {
+    const cfg = new Config({ a: null });
+    expect(cfg.get('a.b', 'default')).toBe('default');
+  });
+});

package/tests/test-context.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from 'vitest';
+import { Context, createIdentity } from '../src/context.js';
+import type { Identity } from '../src/context.js';
+
+describe('createIdentity', () => {
+  it('creates identity with defaults', () => {
+    const id = createIdentity('user1');
+    expect(id.id).toBe('user1');
+    expect(id.type).toBe('user');
+    expect(id.roles).toEqual([]);
+    expect(id.attrs).toEqual({});
+  });
+
+  it('creates identity with all fields', () => {
+    const id = createIdentity('admin1', 'admin', ['superuser'], { org: 'acme' });
+    expect(id.id).toBe('admin1');
+    expect(id.type).toBe('admin');
+    expect(id.roles).toEqual(['superuser']);
+    expect(id.attrs).toEqual({ org: 'acme' });
+  });
+
+  it('returns frozen object', () => {
+    const id = createIdentity('u1');
+    expect(Object.isFrozen(id)).toBe(true);
+    expect(Object.isFrozen(id.roles)).toBe(true);
+    expect(Object.isFrozen(id.attrs)).toBe(true);
+  });
+});
+
+describe('Context.create()', () => {
+  it('creates context with unique traceId', () => {
+    const ctx1 = Context.create();
+    const ctx2 = Context.create();
+    expect(ctx1.traceId).toBeDefined();
+    expect(ctx2.traceId).toBeDefined();
+    expect(ctx1.traceId).not.toBe(ctx2.traceId);
+  });
+
+  it('has null callerId by default', () => {
+    const ctx = Context.create();
+    expect(ctx.callerId).toBeNull();
+  });
+
+  it('has empty callChain by default', () => {
+    const ctx = Context.create();
+    expect(ctx.callChain).toEqual([]);
+  });
+
+  it('accepts executor and identity', () => {
+    const identity = createIdentity('u1', 'admin');
+    const executor = { name: 'test-executor' };
+    const ctx = Context.create(executor, identity);
+    expect(ctx.executor).toBe(executor);
+    expect(ctx.identity).toBe(identity);
+  });
+
+  it('defaults identity to null', () => {
+    const ctx = Context.create();
+    expect(ctx.identity).toBeNull();
+  });
+
+  it('defaults executor to null', () => {
+    const ctx = Context.create();
+    expect(ctx.executor).toBeNull();
+  });
+
+  it('defaults data to empty object', () => {
+    const ctx = Context.create();
+    expect(ctx.data).toEqual({});
+  });
+
+  it('accepts custom data', () => {
+    const ctx = Context.create(null, null, { key: 'value' });
+    expect(ctx.data).toEqual({ key: 'value' });
+  });
+
+  it('has null redactedInputs by default', () => {
+    const ctx = Context.create();
+    expect(ctx.redactedInputs).toBeNull();
+  });
+});
+
+describe('Context.child()', () => {
+  it('preserves traceId from parent', () => {
+    const parent = Context.create();
+    const child = parent.child('module.a');
+    expect(child.traceId).toBe(parent.traceId);
+  });
+
+  it('sets callerId to null when parent callChain is empty', () => {
+    const parent = Context.create();
+    const child = parent.child('module.a');
+    expect(child.callerId).toBeNull();
+  });
+
+  it('sets callerId to last element of parent callChain', () => {
+    const parent = Context.create();
+    const child1 = parent.child('module.a');
+    expect(child1.callChain).toEqual(['module.a']);
+
+    const child2 = child1.child('module.b');
+    expect(child2.callerId).toBe('module.a');
+    expect(child2.callChain).toEqual(['module.a', 'module.b']);
+  });
+
+  it('builds up callChain through multiple levels', () => {
+    const root = Context.create();
+    const c1 = root.child('a');
+    const c2 = c1.child('b');
+    const c3 = c2.child('c');
+    expect(c3.callChain).toEqual(['a', 'b', 'c']);
+    expect(c3.callerId).toBe('b');
+  });
+
+  it('shares data reference with parent', () => {
+    const parent = Context.create(null, null, { shared: true });
+    const child = parent.child('mod');
+    expect(child.data).toBe(parent.data);
+
+    child.data['newKey'] = 'newValue';
+    expect(parent.data['newKey']).toBe('newValue');
+  });
+
+  it('preserves executor from parent', () => {
+    const executor = { id: 'exec' };
+    const parent = Context.create(executor);
+    const child = parent.child('mod');
+    expect(child.executor).toBe(executor);
+  });
+
+  it('preserves identity from parent', () => {
+    const identity = createIdentity('u1', 'admin', ['role1']);
+    const parent = Context.create(null, identity);
+    const child = parent.child('mod');
+    expect(child.identity).toBe(identity);
+  });
+
+  it('resets redactedInputs to null', () => {
+    const parent = Context.create();
+    parent.redactedInputs = { field: '***' };
+    const child = parent.child('mod');
+    expect(child.redactedInputs).toBeNull();
+  });
+
+  it('does not modify parent callChain', () => {
+    const parent = Context.create();
+    const chainBefore = [...parent.callChain];
+    parent.child('mod.a');
+    expect(parent.callChain).toEqual(chainBefore);
+  });
+});

package/tests/test-decorator.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { FunctionModule, module, normalizeResult, makeAutoId } from '../src/decorator.js';
+import { Context, createIdentity } from '../src/context.js';
+import { Registry } from '../src/registry/registry.js';
+
+const inputSchema = Type.Object({ name: Type.String() });
+const outputSchema = Type.Object({ greeting: Type.String() });
+
+describe('FunctionModule', () => {
+  it('wraps an execute function', async () => {
+    const fm = new FunctionModule({
+      execute: (inputs) => ({ greeting: `Hello, ${inputs['name']}!` }),
+      moduleId: 'greet.hello',
+      inputSchema,
+      outputSchema,
+      description: 'Says hello',
+    });
+    const ctx = Context.create(null, createIdentity('test-user'));
+    const result = await fm.execute({ name: 'World' }, ctx);
+    expect(result).toEqual({ greeting: 'Hello, World!' });
+  });
+
+  it('exposes correct properties', () => {
+    const fm = new FunctionModule({
+      execute: () => ({}),
+      moduleId: 'test.props',
+      inputSchema,
+      outputSchema,
+      description: 'Test props',
+      documentation: 'Some docs',
+      tags: ['tag1', 'tag2'],
+      version: '2.0.0',
+    });
+    expect(fm.moduleId).toBe('test.props');
+    expect(fm.description).toBe('Test props');
+    expect(fm.documentation).toBe('Some docs');
+    expect(fm.tags).toEqual(['tag1', 'tag2']);
+    expect(fm.version).toBe('2.0.0');
+  });
+
+  it('uses sensible defaults', () => {
+    const fm = new FunctionModule({
+      execute: () => ({}),
+      moduleId: 'test.defaults',
+      inputSchema,
+      outputSchema,
+    });
+    expect(fm.description).toBe('Module test.defaults');
+    expect(fm.documentation).toBeNull();
+    expect(fm.tags).toBeNull();
+    expect(fm.version).toBe('1.0.0');
+    expect(fm.annotations).toBeNull();
+    expect(fm.metadata).toBeNull();
+    expect(fm.examples).toBeNull();
+  });
+
+  it('normalizes null return value', async () => {
+    const fm = new FunctionModule({
+      execute: () => null as unknown as Record<string, unknown>,
+      moduleId: 'test.normalize',
+      inputSchema,
+      outputSchema,
+    });
+    const ctx = Context.create(null, createIdentity('test-user'));
+    const result = await fm.execute({}, ctx);
+    expect(result).toEqual({});
+  });
+});
+
+describe('normalizeResult', () => {
+  it('null returns empty object', () => {
+    expect(normalizeResult(null)).toEqual({});
+  });
+
+  it('undefined returns empty object', () => {
+    expect(normalizeResult(undefined)).toEqual({});
+  });
+
+  it('plain object passes through', () => {
+    const obj = { a: 1, b: 'two' };
+    expect(normalizeResult(obj)).toBe(obj);
+  });
+
+  it('string is wrapped in { result }', () => {
+    expect(normalizeResult('hello')).toEqual({ result: 'hello' });
+  });
+
+  it('number is wrapped in { result }', () => {
+    expect(normalizeResult(42)).toEqual({ result: 42 });
+  });
+
+  it('boolean is wrapped in { result }', () => {
+    expect(normalizeResult(true)).toEqual({ result: true });
+  });
+
+  it('array is wrapped in { result }', () => {
+    expect(normalizeResult([1, 2, 3])).toEqual({ result: [1, 2, 3] });
+  });
+});
+
+describe('module() factory', () => {
+  it('creates FunctionModule with correct properties', () => {
+    const fm = module({
+      id: 'factory.test',
+      inputSchema,
+      outputSchema,
+      description: 'Factory module',
+      execute: () => ({ greeting: 'hi' }),
+    });
+    expect(fm).toBeInstanceOf(FunctionModule);
+    expect(fm.moduleId).toBe('factory.test');
+    expect(fm.description).toBe('Factory module');
+  });
+
+  it('generates auto ID when not provided', () => {
+    const fm = module({
+      inputSchema,
+      outputSchema,
+      execute: () => ({}),
+    });
+    expect(fm.moduleId).toBe('anonymous');
+  });
+
+  it('passes through optional fields', () => {
+    const fm = module({
+      id: 'opts.check',
+      inputSchema,
+      outputSchema,
+      description: 'desc',
+      documentation: 'docs here',
+      tags: ['t1'],
+      version: '3.0.0',
+      metadata: { key: 'val' },
+      execute: () => ({}),
+    });
+    expect(fm.documentation).toBe('docs here');
+    expect(fm.tags).toEqual(['t1']);
+    expect(fm.version).toBe('3.0.0');
+    expect(fm.metadata).toEqual({ key: 'val' });
+  });
+
+  it('auto-registers with registry', () => {
+    const registry = new Registry();
+    const fm = module({
+      id: 'auto.registered',
+      inputSchema,
+      outputSchema,
+      execute: () => ({ ok: true }),
+      registry,
+    });
+    expect(registry.has('auto.registered')).toBe(true);
+    expect(registry.get('auto.registered')).toBe(fm);
+  });
+});
+
+describe('makeAutoId', () => {
+  it('lowercases and replaces non-alphanumeric', () => {
+    expect(makeAutoId('Hello World')).toBe('hello_world');
+  });
+
+  it('preserves dots', () => {
+    expect(makeAutoId('my.module.name')).toBe('my.module.name');
+  });
+
+  it('prefixes digit-leading segments', () => {
+    expect(makeAutoId('2fast.4you')).toBe('_2fast._4you');
+  });
+
+  it('handles valid IDs unchanged', () => {
+    expect(makeAutoId('valid_id')).toBe('valid_id');
+  });
+});