apcore-js 0.1.0

package/tests/test-errors.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ModuleError,
+  ModuleNotFoundError,
+  ModuleTimeoutError,
+  SchemaValidationError,
+  ACLDeniedError,
+  CallDepthExceededError,
+  CircularCallError,
+  CallFrequencyExceededError,
+  ConfigNotFoundError,
+  ConfigError,
+  InvalidInputError,
+  BindingInvalidTargetError,
+  BindingModuleNotFoundError,
+  BindingCallableNotFoundError,
+  BindingNotCallableError,
+  BindingSchemaMissingError,
+  BindingFileInvalidError,
+  CircularDependencyError,
+  ModuleLoadError,
+  SchemaNotFoundError,
+  SchemaParseError,
+  SchemaCircularRefError,
+  ACLRuleError,
+} from '../src/errors.js';
+
+describe('ModuleError', () => {
+  it('creates with code and message', () => {
+    const err = new ModuleError('TEST_CODE', 'test message');
+    expect(err.code).toBe('TEST_CODE');
+    expect(err.message).toBe('test message');
+    expect(err.name).toBe('ModuleError');
+    expect(err.details).toEqual({});
+    expect(err.timestamp).toBeDefined();
+  });
+
+  it('toString includes code and message', () => {
+    const err = new ModuleError('ERR', 'something failed');
+    expect(err.toString()).toBe('[ERR] something failed');
+  });
+
+  it('accepts details, cause, and traceId', () => {
+    const cause = new Error('root cause');
+    const err = new ModuleError('X', 'msg', { key: 'val' }, cause, 'trace-123');
+    expect(err.details).toEqual({ key: 'val' });
+    expect(err.cause).toBe(cause);
+    expect(err.traceId).toBe('trace-123');
+  });
+
+  it('is an instance of Error', () => {
+    const err = new ModuleError('X', 'msg');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ModuleError);
+  });
+});
+
+describe('Error subclasses', () => {
+  it('ModuleNotFoundError', () => {
+    const err = new ModuleNotFoundError('mod.x');
+    expect(err.name).toBe('ModuleNotFoundError');
+    expect(err.code).toBe('MODULE_NOT_FOUND');
+    expect(err.message).toContain('mod.x');
+    expect(err.details['moduleId']).toBe('mod.x');
+  });
+
+  it('ModuleTimeoutError', () => {
+    const err = new ModuleTimeoutError('mod.x', 5000);
+    expect(err.name).toBe('ModuleTimeoutError');
+    expect(err.code).toBe('MODULE_TIMEOUT');
+    expect(err.moduleId).toBe('mod.x');
+    expect(err.timeoutMs).toBe(5000);
+  });
+
+  it('SchemaValidationError', () => {
+    const err = new SchemaValidationError('bad data', [{ path: '/x' }]);
+    expect(err.name).toBe('SchemaValidationError');
+    expect(err.code).toBe('SCHEMA_VALIDATION_ERROR');
+    expect(err.details['errors']).toHaveLength(1);
+  });
+
+  it('ACLDeniedError', () => {
+    const err = new ACLDeniedError('caller.a', 'target.b');
+    expect(err.name).toBe('ACLDeniedError');
+    expect(err.code).toBe('ACL_DENIED');
+    expect(err.callerId).toBe('caller.a');
+    expect(err.targetId).toBe('target.b');
+  });
+
+  it('CallDepthExceededError', () => {
+    const err = new CallDepthExceededError(33, 32, ['a', 'b']);
+    expect(err.name).toBe('CallDepthExceededError');
+    expect(err.code).toBe('CALL_DEPTH_EXCEEDED');
+    expect(err.currentDepth).toBe(33);
+    expect(err.maxDepth).toBe(32);
+  });
+
+  it('CircularCallError', () => {
+    const err = new CircularCallError('mod.a', ['mod.a', 'mod.b', 'mod.a']);
+    expect(err.name).toBe('CircularCallError');
+    expect(err.code).toBe('CIRCULAR_CALL');
+    expect(err.moduleId).toBe('mod.a');
+  });
+
+  it('CallFrequencyExceededError', () => {
+    const err = new CallFrequencyExceededError('mod.a', 4, 3, ['mod.a', 'mod.a', 'mod.a', 'mod.a']);
+    expect(err.name).toBe('CallFrequencyExceededError');
+    expect(err.code).toBe('CALL_FREQUENCY_EXCEEDED');
+    expect(err.moduleId).toBe('mod.a');
+    expect(err.count).toBe(4);
+    expect(err.maxRepeat).toBe(3);
+  });
+
+  it('ConfigNotFoundError', () => {
+    const err = new ConfigNotFoundError('/path/to/config');
+    expect(err.name).toBe('ConfigNotFoundError');
+    expect(err.code).toBe('CONFIG_NOT_FOUND');
+  });
+
+  it('ConfigError', () => {
+    const err = new ConfigError('bad config');
+    expect(err.name).toBe('ConfigError');
+    expect(err.code).toBe('CONFIG_INVALID');
+  });
+
+  it('InvalidInputError', () => {
+    const err = new InvalidInputError('bad input');
+    expect(err.name).toBe('InvalidInputError');
+    expect(err.code).toBe('GENERAL_INVALID_INPUT');
+  });
+
+  it('BindingInvalidTargetError', () => {
+    const err = new BindingInvalidTargetError('bad:target:format');
+    expect(err.name).toBe('BindingInvalidTargetError');
+    expect(err.code).toBe('BINDING_INVALID_TARGET');
+  });
+
+  it('BindingModuleNotFoundError', () => {
+    const err = new BindingModuleNotFoundError('some.module');
+    expect(err.name).toBe('BindingModuleNotFoundError');
+    expect(err.code).toBe('BINDING_MODULE_NOT_FOUND');
+  });
+
+  it('BindingCallableNotFoundError', () => {
+    const err = new BindingCallableNotFoundError('fn', 'some.module');
+    expect(err.name).toBe('BindingCallableNotFoundError');
+    expect(err.code).toBe('BINDING_CALLABLE_NOT_FOUND');
+  });
+
+  it('BindingNotCallableError', () => {
+    const err = new BindingNotCallableError('some:target');
+    expect(err.name).toBe('BindingNotCallableError');
+    expect(err.code).toBe('BINDING_NOT_CALLABLE');
+  });
+
+  it('BindingSchemaMissingError', () => {
+    const err = new BindingSchemaMissingError('some:target');
+    expect(err.name).toBe('BindingSchemaMissingError');
+    expect(err.code).toBe('BINDING_SCHEMA_MISSING');
+  });
+
+  it('BindingFileInvalidError', () => {
+    const err = new BindingFileInvalidError('/path/file.yaml', 'parse error');
+    expect(err.name).toBe('BindingFileInvalidError');
+    expect(err.code).toBe('BINDING_FILE_INVALID');
+  });
+
+  it('CircularDependencyError', () => {
+    const err = new CircularDependencyError(['a', 'b', 'a']);
+    expect(err.name).toBe('CircularDependencyError');
+    expect(err.code).toBe('CIRCULAR_DEPENDENCY');
+    expect(err.message).toContain('a -> b -> a');
+  });
+
+  it('ModuleLoadError', () => {
+    const err = new ModuleLoadError('mod.a', 'file not found');
+    expect(err.name).toBe('ModuleLoadError');
+    expect(err.code).toBe('MODULE_LOAD_ERROR');
+  });
+
+  it('SchemaNotFoundError', () => {
+    const err = new SchemaNotFoundError('schema.x');
+    expect(err.name).toBe('SchemaNotFoundError');
+    expect(err.code).toBe('SCHEMA_NOT_FOUND');
+  });
+
+  it('SchemaParseError', () => {
+    const err = new SchemaParseError('invalid yaml');
+    expect(err.name).toBe('SchemaParseError');
+    expect(err.code).toBe('SCHEMA_PARSE_ERROR');
+  });
+
+  it('SchemaCircularRefError', () => {
+    const err = new SchemaCircularRefError('#/definitions/A');
+    expect(err.name).toBe('SchemaCircularRefError');
+    expect(err.code).toBe('SCHEMA_CIRCULAR_REF');
+  });
+
+  it('ACLRuleError', () => {
+    const err = new ACLRuleError('bad rule');
+    expect(err.name).toBe('ACLRuleError');
+    expect(err.code).toBe('ACL_RULE_ERROR');
+  });
+});

package/tests/test-executor.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { Context, createIdentity } from '../src/context.js';
+import { Executor, redactSensitive, REDACTED_VALUE } from '../src/executor.js';
+import { FunctionModule } from '../src/decorator.js';
+import { Registry } from '../src/registry/registry.js';
+import { ACL } from '../src/acl.js';
+import { Middleware } from '../src/middleware/base.js';
+import {
+  ModuleNotFoundError,
+  ACLDeniedError,
+  CallDepthExceededError,
+  CircularCallError,
+  CallFrequencyExceededError,
+  SchemaValidationError,
+} from '../src/errors.js';
+
+function createSimpleModule(id: string): FunctionModule {
+  return new FunctionModule({
+    execute: (inputs) => ({ greeting: `Hello, ${inputs['name'] ?? 'world'}!` }),
+    moduleId: id,
+    inputSchema: Type.Object({ name: Type.Optional(Type.String()) }),
+    outputSchema: Type.Object({ greeting: Type.String() }),
+    description: 'Greet module',
+  });
+}
+
+describe('redactSensitive', () => {
+  it('redacts fields marked x-sensitive', () => {
+    const data = { name: 'Alice', password: 'secret123' };
+    const schema = {
+      properties: {
+        name: { type: 'string' },
+        password: { type: 'string', 'x-sensitive': true },
+      },
+    };
+    const result = redactSensitive(data, schema);
+    expect(result['name']).toBe('Alice');
+    expect(result['password']).toBe(REDACTED_VALUE);
+  });
+
+  it('redacts _secret_ prefix keys', () => {
+    const data = { _secret_token: 'abc123', name: 'Bob' };
+    const schema = { properties: { name: { type: 'string' } } };
+    const result = redactSensitive(data, schema);
+    expect(result['_secret_token']).toBe(REDACTED_VALUE);
+    expect(result['name']).toBe('Bob');
+  });
+
+  it('does not modify original data', () => {
+    const data = { password: 'secret' };
+    const schema = { properties: { password: { type: 'string', 'x-sensitive': true } } };
+    redactSensitive(data, schema);
+    expect(data['password']).toBe('secret');
+  });
+
+  it('handles nested objects', () => {
+    const data = { user: { name: 'Alice', token: 'abc' } };
+    const schema = {
+      properties: {
+        user: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            token: { type: 'string', 'x-sensitive': true },
+          },
+        },
+      },
+    };
+    const result = redactSensitive(data, schema);
+    expect((result['user'] as Record<string, unknown>)['name']).toBe('Alice');
+    expect((result['user'] as Record<string, unknown>)['token']).toBe(REDACTED_VALUE);
+  });
+});
+
+describe('Executor', () => {
+  it('executes a simple module', async () => {
+    const registry = new Registry();
+    const mod = createSimpleModule('greet');
+    registry.register('greet', mod);
+
+    const executor = new Executor({ registry });
+    const result = await executor.call('greet', { name: 'Alice' });
+    expect(result['greeting']).toBe('Hello, Alice!');
+  });
+
+  it('throws ModuleNotFoundError for unknown module', async () => {
+    const registry = new Registry();
+    const executor = new Executor({ registry });
+
+    await expect(executor.call('nonexistent')).rejects.toThrow(ModuleNotFoundError);
+  });
+
+  it('validates input against schema', async () => {
+    const registry = new Registry();
+    const mod = new FunctionModule({
+      execute: (inputs) => ({ result: inputs['count'] }),
+      moduleId: 'strict',
+      inputSchema: Type.Object({ count: Type.Number() }),
+      outputSchema: Type.Object({ result: Type.Number() }),
+      description: 'Strict module',
+    });
+    registry.register('strict', mod);
+
+    const executor = new Executor({ registry });
+    await expect(executor.call('strict', { count: 'not-a-number' })).rejects.toThrow(SchemaValidationError);
+  });
+
+  it('enforces ACL deny', async () => {
+    const registry = new Registry();
+    registry.register('secret', createSimpleModule('secret'));
+
+    const acl = new ACL([
+      { callers: ['@external'], targets: ['secret'], effect: 'deny', description: 'deny all' },
+    ], 'deny');
+
+    const executor = new Executor({ registry, acl });
+    await expect(executor.call('secret')).rejects.toThrow(ACLDeniedError);
+  });
+
+  it('enforces ACL allow', async () => {
+    const registry = new Registry();
+    registry.register('public', createSimpleModule('public'));
+
+    const acl = new ACL([
+      { callers: ['*'], targets: ['*'], effect: 'allow', description: 'allow all' },
+    ], 'deny');
+
+    const executor = new Executor({ registry, acl });
+    const result = await executor.call('public', { name: 'World' });
+    expect(result['greeting']).toBe('Hello, World!');
+  });
+
+  it('calls middleware before and after', async () => {
+    const registry = new Registry();
+    registry.register('echo', createSimpleModule('echo'));
+
+    const calls: string[] = [];
+    class TrackingMiddleware extends Middleware {
+      override before() { calls.push('before'); return null; }
+      override after() { calls.push('after'); return null; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new TrackingMiddleware()] });
+    await executor.call('echo');
+    expect(calls).toEqual(['before', 'after']);
+  });
+
+  it('runs middleware onError on execution failure', async () => {
+    const registry = new Registry();
+    const failMod = new FunctionModule({
+      execute: () => { throw new Error('boom'); },
+      moduleId: 'fail',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({}),
+      description: 'Failing module',
+    });
+    registry.register('fail', failMod);
+
+    let errorSeen = false;
+    class ErrorTracker extends Middleware {
+      override onError() { errorSeen = true; return null; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new ErrorTracker()] });
+    await expect(executor.call('fail')).rejects.toThrow('boom');
+    expect(errorSeen).toBe(true);
+  });
+
+  it('middleware onError can recover', async () => {
+    const registry = new Registry();
+    const failMod = new FunctionModule({
+      execute: () => { throw new Error('boom'); },
+      moduleId: 'fail',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({}),
+      description: 'Failing module',
+    });
+    registry.register('fail', failMod);
+
+    class RecoveryMiddleware extends Middleware {
+      override onError() { return { recovered: true }; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new RecoveryMiddleware()] });
+    const result = await executor.call('fail');
+    expect(result['recovered']).toBe(true);
+  });
+
+  it('validate() checks inputs without executing', () => {
+    const registry = new Registry();
+    const mod = new FunctionModule({
+      execute: () => ({ ok: true }),
+      moduleId: 'v',
+      inputSchema: Type.Object({ x: Type.Number() }),
+      outputSchema: Type.Object({ ok: Type.Boolean() }),
+      description: 'Validate test',
+    });
+    registry.register('v', mod);
+
+    const executor = new Executor({ registry });
+    const valid = executor.validate('v', { x: 42 });
+    expect(valid.valid).toBe(true);
+
+    const invalid = executor.validate('v', { x: 'not-a-number' });
+    expect(invalid.valid).toBe(false);
+    expect(invalid.errors.length).toBeGreaterThan(0);
+  });
+
+  it('auto-creates context when none provided', async () => {
+    const registry = new Registry();
+    registry.register('ctx', createSimpleModule('ctx'));
+
+    const executor = new Executor({ registry });
+    const result = await executor.call('ctx');
+    expect(result['greeting']).toBeDefined();
+  });
+
+  it('uses provided context', async () => {
+    const registry = new Registry();
+    let capturedCtx: Context | null = null;
+    const mod = new FunctionModule({
+      execute: (_inputs, ctx) => { capturedCtx = ctx; return { ok: true }; },
+      moduleId: 'ctx-test',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ ok: Type.Boolean() }),
+      description: 'Context capture',
+    });
+    registry.register('ctx-test', mod);
+
+    const executor = new Executor({ registry });
+    const ctx = Context.create(executor, createIdentity('user1'));
+    await executor.call('ctx-test', {}, ctx);
+
+    expect(capturedCtx).not.toBeNull();
+    expect(capturedCtx!.traceId).toBe(ctx.traceId);
+    expect(capturedCtx!.identity?.id).toBe('user1');
+  });
+
+  it('use/remove middleware chaining', () => {
+    const registry = new Registry();
+    const executor = new Executor({ registry });
+    const mw = new Middleware();
+
+    const result = executor.use(mw);
+    expect(result).toBe(executor);
+    expect(executor.middlewares).toHaveLength(1);
+
+    executor.remove(mw);
+    expect(executor.middlewares).toHaveLength(0);
+  });
+});

package/tests/test-middleware-manager.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import { Middleware } from '../src/middleware/base.js';
+import { MiddlewareManager, MiddlewareChainError } from '../src/middleware/manager.js';
+import { Context, createIdentity } from '../src/context.js';
+
+function makeContext(): Context {
+  return Context.create(null, createIdentity('test-user'));
+}
+
+class TaggingMiddleware extends Middleware {
+  readonly tag: string;
+
+  constructor(tag: string) {
+    super();
+    this.tag = tag;
+  }
+
+  override before(
+    _moduleId: string,
+    inputs: Record<string, unknown>,
+  ): Record<string, unknown> | null {
+    const trail = ((inputs['trail'] as string) ?? '') + this.tag;
+    return { ...inputs, trail };
+  }
+
+  override after(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+  ): Record<string, unknown> | null {
+    const trail = ((output['trail'] as string) ?? '') + this.tag;
+    return { ...output, trail };
+  }
+}
+
+class RecoveringMiddleware extends Middleware {
+  readonly recovery: Record<string, unknown>;
+
+  constructor(recovery: Record<string, unknown>) {
+    super();
+    this.recovery = recovery;
+  }
+
+  override onError(): Record<string, unknown> | null {
+    return this.recovery;
+  }
+}
+
+describe('MiddlewareManager', () => {
+  it('starts empty', () => {
+    const mgr = new MiddlewareManager();
+    expect(mgr.snapshot()).toEqual([]);
+  });
+
+  it('add and snapshot', () => {
+    const mgr = new MiddlewareManager();
+    const mw1 = new Middleware();
+    const mw2 = new Middleware();
+    mgr.add(mw1);
+    mgr.add(mw2);
+    expect(mgr.snapshot()).toHaveLength(2);
+  });
+
+  it('snapshot returns a copy', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new Middleware());
+    const snap = mgr.snapshot();
+    snap.pop();
+    expect(mgr.snapshot()).toHaveLength(1);
+  });
+
+  it('remove by identity', () => {
+    const mgr = new MiddlewareManager();
+    const mw1 = new Middleware();
+    const mw2 = new Middleware();
+    mgr.add(mw1);
+    mgr.add(mw2);
+    expect(mgr.remove(mw1)).toBe(true);
+    expect(mgr.snapshot()).toEqual([mw2]);
+  });
+
+  it('remove returns false when not found', () => {
+    const mgr = new MiddlewareManager();
+    expect(mgr.remove(new Middleware())).toBe(false);
+  });
+
+  it('executeBefore runs in forward order', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new TaggingMiddleware('A'));
+    mgr.add(new TaggingMiddleware('B'));
+    mgr.add(new TaggingMiddleware('C'));
+    const ctx = makeContext();
+    const [result, executed] = mgr.executeBefore('mod.test', { trail: '' }, ctx);
+    expect(result['trail']).toBe('ABC');
+    expect(executed).toHaveLength(3);
+  });
+
+  it('executeBefore passes original inputs when all return null', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new Middleware());
+    mgr.add(new Middleware());
+    const ctx = makeContext();
+    const [result] = mgr.executeBefore('mod.test', { x: 42 }, ctx);
+    expect(result).toEqual({ x: 42 });
+  });
+
+  it('executeAfter runs in reverse order', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new TaggingMiddleware('A'));
+    mgr.add(new TaggingMiddleware('B'));
+    mgr.add(new TaggingMiddleware('C'));
+    const ctx = makeContext();
+    const result = mgr.executeAfter('mod.test', {}, { trail: '' }, ctx);
+    expect(result['trail']).toBe('CBA');
+  });
+
+  it('executeAfter passes original output when all return null', () => {
+    const mgr = new MiddlewareManager();
+    mgr.add(new Middleware());
+    const ctx = makeContext();
+    const result = mgr.executeAfter('mod.test', {}, { y: 99 }, ctx);
+    expect(result).toEqual({ y: 99 });
+  });
+
+  it('executeOnError returns first non-null recovery (reverse order)', () => {
+    const mgr = new MiddlewareManager();
+    const mwA = new RecoveringMiddleware({ recovered: 'A' });
+    const mwB = new RecoveringMiddleware({ recovered: 'B' });
+    mgr.add(mwA);
+    mgr.add(mwB);
+    const ctx = makeContext();
+    const result = mgr.executeOnError('mod.test', {}, new Error('oops'), ctx, [mwA, mwB]);
+    expect(result).toEqual({ recovered: 'B' });
+  });
+
+  it('executeOnError returns null when no recovery', () => {
+    const mgr = new MiddlewareManager();
+    const mw = new Middleware();
+    mgr.add(mw);
+    const ctx = makeContext();
+    const result = mgr.executeOnError('mod.test', {}, new Error('oops'), ctx, [mw]);
+    expect(result).toBeNull();
+  });
+
+  it('executeOnError swallows errors in onError handlers', () => {
+    class ThrowingOnError extends Middleware {
+      override onError(): Record<string, unknown> | null {
+        throw new Error('onError also failed');
+      }
+    }
+    const mgr = new MiddlewareManager();
+    const mwRecover = new RecoveringMiddleware({ safe: true });
+    const mwThrow = new ThrowingOnError();
+    mgr.add(mwRecover);
+    mgr.add(mwThrow);
+    const ctx = makeContext();
+    const result = mgr.executeOnError('mod.test', {}, new Error('original'), ctx, [mwRecover, mwThrow]);
+    expect(result).toEqual({ safe: true });
+  });
+
+  it('MiddlewareChainError wraps before() failure', () => {
+    class FailingBefore extends Middleware {
+      override before(): Record<string, unknown> | null {
+        throw new Error('before exploded');
+      }
+    }
+    const mgr = new MiddlewareManager();
+    const ok = new TaggingMiddleware('A');
+    const fail = new FailingBefore();
+    mgr.add(ok);
+    mgr.add(fail);
+    const ctx = makeContext();
+
+    let caught: MiddlewareChainError | undefined;
+    try {
+      mgr.executeBefore('mod.test', { trail: '' }, ctx);
+    } catch (e) {
+      caught = e as MiddlewareChainError;
+    }
+
+    expect(caught).toBeInstanceOf(MiddlewareChainError);
+    expect(caught!.original.message).toBe('before exploded');
+    expect(caught!.executedMiddlewares).toHaveLength(2);
+  });
+});