apcore-js 0.5.0 → 0.7.0

package/src/schema/types.ts

@@ -1,73 +0,0 @@
-/**
- * Schema type definitions and data structures for the apcore schema system.
- */
-
-import type { TSchema } from '@sinclair/typebox';
-import { SchemaValidationError } from '../errors.js';
-
-export enum SchemaStrategy {
-  YamlFirst = 'yaml_first',
-  NativeFirst = 'native_first',
-  YamlOnly = 'yaml_only',
-}
-
-export enum ExportProfile {
-  MCP = 'mcp',
-  OpenAI = 'openai',
-  Anthropic = 'anthropic',
-  Generic = 'generic',
-}
-
-export interface SchemaDefinition {
-  moduleId: string;
-  description: string;
-  inputSchema: Record<string, unknown>;
-  outputSchema: Record<string, unknown>;
-  errorSchema?: Record<string, unknown> | null;
-  definitions: Record<string, unknown>;
-  version: string;
-  documentation?: string | null;
-  schemaUrl?: string | null;
-}
-
-export interface ResolvedSchema {
-  jsonSchema: Record<string, unknown>;
-  schema: TSchema;
-  moduleId: string;
-  direction: string;
-}
-
-export interface SchemaValidationErrorDetail {
-  path: string;
-  message: string;
-  constraint?: string | null;
-  expected?: unknown;
-  actual?: unknown;
-}
-
-export interface SchemaValidationResult {
-  valid: boolean;
-  errors: SchemaValidationErrorDetail[];
-}
-
-export function validationResultToError(result: SchemaValidationResult): SchemaValidationError {
-  if (result.valid) {
-    throw new Error('Cannot convert valid result to error');
-  }
-  const errorDicts = result.errors.map((e) => ({
-    path: e.path,
-    message: e.message,
-    constraint: e.constraint ?? null,
-    expected: e.expected ?? null,
-    actual: e.actual ?? null,
-  }));
-  return new SchemaValidationError('Schema validation failed', errorDicts);
-}
-
-export interface LLMExtensions {
-  llmDescription?: string | null;
-  examples?: unknown[] | null;
-  sensitive: boolean;
-  constraints?: string | null;
-  deprecated?: Record<string, unknown> | null;
-}

package/src/schema/validator.ts

@@ -1,82 +0,0 @@
-/**
- * SchemaValidator — validates runtime data against TypeBox schemas.
- */
-
-import { type TSchema } from '@sinclair/typebox';
-import { Value, type ValueError } from '@sinclair/typebox/value';
-import type { SchemaValidationErrorDetail, SchemaValidationResult } from './types.js';
-import { validationResultToError } from './types.js';
-
-export class SchemaValidator {
-  private _coerceTypes: boolean;
-
-  constructor(coerceTypes: boolean = true) {
-    this._coerceTypes = coerceTypes;
-  }
-
-  validate(data: Record<string, unknown>, schema: TSchema): SchemaValidationResult {
-    if (this._coerceTypes) {
-      try {
-        Value.Decode(schema, data);
-        return { valid: true, errors: [] };
-      } catch {
-        return { valid: false, errors: this._collectErrors(schema, data) };
-      }
-    }
-
-    if (Value.Check(schema, data)) {
-      return { valid: true, errors: [] };
-    }
-    return { valid: false, errors: this._collectErrors(schema, data) };
-  }
-
-  validateInput(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    return this._validateAndReturn(data, schema);
-  }
-
-  validateOutput(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    return this._validateAndReturn(data, schema);
-  }
-
-  private _validateAndReturn(data: Record<string, unknown>, schema: TSchema): Record<string, unknown> {
-    if (this._coerceTypes) {
-      try {
-        return Value.Decode(schema, data) as Record<string, unknown>;
-      } catch {
-        const result: SchemaValidationResult = {
-          valid: false,
-          errors: this._collectErrors(schema, data),
-        };
-        throw validationResultToError(result);
-      }
-    }
-
-    if (Value.Check(schema, data)) {
-      return data;
-    }
-
-    const result: SchemaValidationResult = {
-      valid: false,
-      errors: this._collectErrors(schema, data),
-    };
-    throw validationResultToError(result);
-  }
-
-  private _collectErrors(schema: TSchema, data: unknown): SchemaValidationErrorDetail[] {
-    const errors: SchemaValidationErrorDetail[] = [];
-    for (const error of Value.Errors(schema, data)) {
-      errors.push(this._typeboxErrorToDetail(error));
-    }
-    return errors;
-  }
-
-  private _typeboxErrorToDetail(error: ValueError): SchemaValidationErrorDetail {
-    return {
-      path: error.path || '/',
-      message: error.message,
-      constraint: String(error.type),
-      expected: error.schema,
-      actual: error.value,
-    };
-  }
-}

package/src/trace-context.ts

@@ -1,102 +0,0 @@
-/**
- * W3C Trace Context support: TraceParent parsing and TraceContext injection/extraction.
- */
-
-import { randomBytes } from 'node:crypto';
-import type { Context } from './context.js';
-import type { Span } from './observability/tracing.js';
-
-const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
-
-export interface TraceParent {
-  readonly version: string;   // "00"
-  readonly traceId: string;   // 32 lowercase hex chars
-  readonly parentId: string;  // 16 lowercase hex chars
-  readonly traceFlags: string; // "01" (sampled) or "00"
-}
-
-export class TraceContext {
-  /**
-   * Build a traceparent header dict from an apcore Context.
-   *
-   * Converts `context.traceId` (UUID with dashes) to the 32-hex
-   * format required by the W3C traceparent spec. Uses the last span's
-   * `spanId` from the tracing stack if available, otherwise generates
-   * a random 16-hex parent id.
-   */
-  static inject(context: Context): Record<string, string> {
-    const traceIdHex = context.traceId.replace(/-/g, '');
-
-    const spansStack = context.data['_tracing_spans'] as Span[] | undefined;
-    let parentId: string;
-    if (spansStack && spansStack.length > 0) {
-      parentId = spansStack[spansStack.length - 1].spanId;
-    } else {
-      parentId = randomBytes(8).toString('hex');
-    }
-
-    const traceparent = `00-${traceIdHex}-${parentId}-01`;
-    return { traceparent };
-  }
-
-  /**
-   * Parse the `traceparent` header from the given headers object.
-   *
-   * Returns `null` if the header is missing or malformed.
-   */
-  static extract(headers: Record<string, string>): TraceParent | null {
-    const raw = headers['traceparent'];
-    if (raw === undefined) {
-      return null;
-    }
-    const match = TRACEPARENT_RE.exec(raw.trim().toLowerCase());
-    if (match === null) {
-      return null;
-    }
-    const version = match[1];
-    const traceId = match[2];
-    const parentId = match[3];
-    if (version === 'ff') {
-      return null;
-    }
-    if (traceId === '0'.repeat(32) || parentId === '0'.repeat(16)) {
-      return null;
-    }
-    return Object.freeze({
-      version,
-      traceId,
-      parentId,
-      traceFlags: match[4],
-    });
-  }
-
-  /**
-   * Strictly parse a traceparent string, throwing on invalid format.
-   *
-   * @throws {Error} If the traceparent does not match the expected
-   *   `00-<32 hex>-<16 hex>-<2 hex>` format.
-   */
-  static fromTraceparent(traceparent: string): TraceParent {
-    const match = TRACEPARENT_RE.exec(traceparent.trim().toLowerCase());
-    if (match === null) {
-      throw new Error(
-        `Malformed traceparent: ${JSON.stringify(traceparent.slice(0, 100))}. Expected format: 00-<32 hex>-<16 hex>-<2 hex>`,
-      );
-    }
-    const version = match[1];
-    const traceId = match[2];
-    const parentId = match[3];
-    if (version === 'ff') {
-      throw new Error('Invalid traceparent: version ff is not allowed');
-    }
-    if (traceId === '0'.repeat(32) || parentId === '0'.repeat(16)) {
-      throw new Error('Invalid traceparent: all-zero trace_id or parent_id');
-    }
-    return Object.freeze({
-      version,
-      traceId,
-      parentId,
-      traceFlags: match[4],
-    });
-  }
-}

package/src/utils/index.ts

@@ -1,5 +0,0 @@
-export { matchPattern } from './pattern.js';
-
-export function deepCopy<T>(obj: T): T {
-  return JSON.parse(JSON.stringify(obj));
-}

package/src/utils/pattern.ts

@@ -1,30 +0,0 @@
-/**
- * Wildcard pattern matching for module IDs (Algorithm A08).
- */
-
-export function matchPattern(pattern: string, moduleId: string): boolean {
-  if (pattern === '*') return true;
-  if (!pattern.includes('*')) return pattern === moduleId;
-
-  const segments = pattern.split('*');
-  let pos = 0;
-
-  if (!pattern.startsWith('*')) {
-    if (!moduleId.startsWith(segments[0])) return false;
-    pos = segments[0].length;
-  }
-
-  for (let i = 1; i < segments.length; i++) {
-    const segment = segments[i];
-    if (!segment) continue;
-    const idx = moduleId.indexOf(segment, pos);
-    if (idx === -1) return false;
-    pos = idx + segment.length;
-  }
-
-  if (!pattern.endsWith('*')) {
-    if (!moduleId.endsWith(segments[segments.length - 1])) return false;
-  }
-
-  return true;
-}

package/tests/async-task.test.ts

@@ -1,335 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { Type } from '@sinclair/typebox';
-import { AsyncTaskManager, TaskStatus } from '../src/async-task.js';
-import type { TaskInfo } from '../src/async-task.js';
-import { Executor } from '../src/executor.js';
-import { FunctionModule } from '../src/decorator.js';
-import { Registry } from '../src/registry/registry.js';
-
-function createRegistry(): Registry {
-  const registry = new Registry();
-
-  const simpleModule = new FunctionModule({
-    execute: (inputs) => ({ value: (inputs['x'] as number) ?? 0 }),
-    moduleId: 'test.simple',
-    inputSchema: Type.Object({ x: Type.Optional(Type.Number()) }),
-    outputSchema: Type.Object({ value: Type.Number() }),
-    description: 'Simple module',
-  });
-
-  const failingModule = new FunctionModule({
-    execute: () => { throw new Error('intentional failure'); },
-    moduleId: 'test.failing',
-    inputSchema: Type.Object({}),
-    outputSchema: Type.Object({}),
-    description: 'Failing module',
-  });
-
-  const slowModule = new FunctionModule({
-    execute: async (inputs) => {
-      const ms = (inputs['delay'] as number) ?? 1000;
-      await new Promise((resolve) => setTimeout(resolve, ms));
-      return { done: true };
-    },
-    moduleId: 'test.slow',
-    inputSchema: Type.Object({ delay: Type.Optional(Type.Number()) }),
-    outputSchema: Type.Object({ done: Type.Boolean() }),
-    description: 'Slow module',
-  });
-
-  registry.register('test.simple', simpleModule);
-  registry.register('test.failing', failingModule);
-  registry.register('test.slow', slowModule);
-
-  return registry;
-}
-
-function createManager(maxConcurrent: number = 10): { manager: AsyncTaskManager; executor: Executor } {
-  const registry = createRegistry();
-  const executor = new Executor({ registry });
-  const manager = new AsyncTaskManager(executor, maxConcurrent);
-  return { manager, executor };
-}
-
-function wait(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-describe('TaskStatus', () => {
-  it('has correct enum values', () => {
-    expect(TaskStatus.PENDING).toBe('pending');
-    expect(TaskStatus.RUNNING).toBe('running');
-    expect(TaskStatus.COMPLETED).toBe('completed');
-    expect(TaskStatus.FAILED).toBe('failed');
-    expect(TaskStatus.CANCELLED).toBe('cancelled');
-  });
-});
-
-describe('AsyncTaskManager', () => {
-  describe('submit and status transitions', () => {
-    it('submits a task and transitions to COMPLETED', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.simple', { x: 42 });
-
-      const info = manager.getStatus(taskId);
-      expect(info).not.toBeNull();
-      expect(info!.moduleId).toBe('test.simple');
-
-      await wait(100);
-
-      const completed = manager.getStatus(taskId);
-      expect(completed).not.toBeNull();
-      expect(completed!.status).toBe(TaskStatus.COMPLETED);
-      expect(completed!.result).toEqual({ value: 42 });
-      expect(completed!.startedAt).not.toBeNull();
-      expect(completed!.completedAt).not.toBeNull();
-      expect(completed!.error).toBeNull();
-    });
-
-    it('returns a unique task id', () => {
-      const { manager } = createManager();
-      const id1 = manager.submit('test.simple', { x: 1 });
-      const id2 = manager.submit('test.simple', { x: 2 });
-      expect(id1).not.toBe(id2);
-    });
-  });
-
-  describe('task failure', () => {
-    it('sets status to FAILED with error message', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.failing', {});
-
-      await wait(100);
-
-      const info = manager.getStatus(taskId);
-      expect(info).not.toBeNull();
-      expect(info!.status).toBe(TaskStatus.FAILED);
-      expect(info!.error).toContain('intentional failure');
-      expect(info!.completedAt).not.toBeNull();
-      expect(info!.result).toBeNull();
-    });
-  });
-
-  describe('task cancellation', () => {
-    it('cancels a running task', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.slow', { delay: 60000 });
-
-      await wait(100);
-
-      const info = manager.getStatus(taskId);
-      expect(info).not.toBeNull();
-      expect(info!.status).toBe(TaskStatus.RUNNING);
-
-      const cancelled = manager.cancel(taskId);
-      expect(cancelled).toBe(true);
-
-      const after = manager.getStatus(taskId);
-      expect(after).not.toBeNull();
-      expect(after!.status).toBe(TaskStatus.CANCELLED);
-      expect(after!.completedAt).not.toBeNull();
-    });
-
-    it('returns false for nonexistent task', () => {
-      const { manager } = createManager();
-      const result = manager.cancel('no-such-id');
-      expect(result).toBe(false);
-    });
-
-    it('returns false for already completed task', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.simple', { x: 1 });
-      await wait(100);
-
-      expect(manager.getStatus(taskId)!.status).toBe(TaskStatus.COMPLETED);
-
-      const result = manager.cancel(taskId);
-      expect(result).toBe(false);
-    });
-  });
-
-  describe('concurrency limit', () => {
-    it('limits concurrent executions to maxConcurrent', async () => {
-      const { manager } = createManager(2);
-
-      const taskIds: string[] = [];
-      for (let i = 0; i < 4; i++) {
-        taskIds.push(manager.submit('test.slow', { delay: 60000 }));
-      }
-
-      await wait(200);
-
-      const running = manager.listTasks(TaskStatus.RUNNING);
-      const pending = manager.listTasks(TaskStatus.PENDING);
-
-      expect(running.length).toBeLessThanOrEqual(2);
-      expect(running.length + pending.length).toBe(4);
-
-      // Cleanup: cancel all (synchronous, no need to await)
-      for (const id of taskIds) {
-        manager.cancel(id);
-      }
-    });
-  });
-
-  describe('getResult', () => {
-    it('returns result for completed task', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.simple', { x: 99 });
-      await wait(100);
-
-      const result = manager.getResult(taskId);
-      expect(result).toEqual({ value: 99 });
-    });
-
-    it('throws for unknown task', () => {
-      const { manager } = createManager();
-      expect(() => manager.getResult('no-such-task')).toThrow('Task not found');
-    });
-
-    it('throws for non-completed task', () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.slow', { delay: 60000 });
-
-      expect(() => manager.getResult(taskId)).toThrow('not completed');
-
-      manager.cancel(taskId);
-    });
-  });
-
-  describe('getStatus', () => {
-    it('returns null for unknown task', () => {
-      const { manager } = createManager();
-      expect(manager.getStatus('nonexistent')).toBeNull();
-    });
-  });
-
-  describe('listTasks', () => {
-    it('returns all tasks', async () => {
-      const { manager } = createManager();
-      manager.submit('test.simple', { x: 1 });
-      manager.submit('test.simple', { x: 2 });
-      await wait(100);
-
-      const all = manager.listTasks();
-      expect(all.length).toBe(2);
-    });
-
-    it('filters tasks by status', async () => {
-      const { manager } = createManager();
-      manager.submit('test.simple', { x: 1 });
-      manager.submit('test.failing', {});
-      await wait(100);
-
-      const completed = manager.listTasks(TaskStatus.COMPLETED);
-      const failed = manager.listTasks(TaskStatus.FAILED);
-      expect(completed.length).toBe(1);
-      expect(failed.length).toBe(1);
-    });
-  });
-
-  describe('max tasks limit', () => {
-    it('throws when task limit is exceeded', () => {
-      const { manager } = createManager();
-      // Create a manager with a small limit
-      const registry = createRegistry();
-      const executor = new Executor({ registry });
-      const limitedManager = new AsyncTaskManager(executor, 10, 3);
-
-      limitedManager.submit('test.simple', { x: 1 });
-      limitedManager.submit('test.simple', { x: 2 });
-      limitedManager.submit('test.simple', { x: 3 });
-
-      expect(() => limitedManager.submit('test.simple', { x: 4 })).toThrow(
-        'Task limit reached (3)',
-      );
-    });
-
-    it('allows submissions after cleanup frees slots', async () => {
-      const registry = createRegistry();
-      const executor = new Executor({ registry });
-      const limitedManager = new AsyncTaskManager(executor, 10, 2);
-
-      limitedManager.submit('test.simple', { x: 1 });
-      limitedManager.submit('test.simple', { x: 2 });
-
-      await wait(100);
-      limitedManager.cleanup(0);
-
-      // Should succeed after cleanup
-      const taskId = limitedManager.submit('test.simple', { x: 3 });
-      expect(taskId).toBeDefined();
-    });
-  });
-
-  describe('double release fix', () => {
-    it('does not corrupt concurrency counter when cancelling a queued task', async () => {
-      // Use maxConcurrent=1 so the second task queues behind the first
-      const registry = createRegistry();
-      const executor = new Executor({ registry });
-      const mgr = new AsyncTaskManager(executor, 1);
-
-      // Submit a short task to fill the single slot
-      const firstId = mgr.submit('test.slow', { delay: 50 });
-      await wait(10);
-
-      // Submit a second task -- it will be waiting in the queue
-      const queuedId = mgr.submit('test.slow', { delay: 50 });
-      await wait(10);
-
-      // The queued task should still be PENDING
-      expect(mgr.getStatus(queuedId)!.status).toBe(TaskStatus.PENDING);
-
-      // Cancel the queued task while it's waiting for a slot
-      mgr.cancel(queuedId);
-
-      // Wait for the first task to complete, which releases the slot
-      // and wakes the cancelled queued task. The queued task should
-      // see cancelled=true and return; finally releases the slot once.
-      await wait(200);
-
-      // The running count should be 0 (not negative from double release)
-      const runningCount = (mgr as unknown as { _runningCount: number })._runningCount;
-      expect(runningCount).toBe(0);
-
-      // Also verify the first task completed successfully
-      expect(mgr.getStatus(firstId)!.status).toBe(TaskStatus.COMPLETED);
-      expect(mgr.getStatus(queuedId)!.status).toBe(TaskStatus.CANCELLED);
-    });
-  });
-
-  describe('cleanup', () => {
-    it('removes old completed tasks', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.simple', { x: 1 });
-      await wait(100);
-
-      expect(manager.getStatus(taskId)!.status).toBe(TaskStatus.COMPLETED);
-
-      const removed = manager.cleanup(0);
-      expect(removed).toBe(1);
-      expect(manager.getStatus(taskId)).toBeNull();
-    });
-
-    it('preserves recent tasks', async () => {
-      const { manager } = createManager();
-      manager.submit('test.simple', { x: 1 });
-      await wait(100);
-
-      const removed = manager.cleanup(3600);
-      expect(removed).toBe(0);
-      expect(manager.listTasks().length).toBe(1);
-    });
-
-    it('preserves running tasks', async () => {
-      const { manager } = createManager();
-      const taskId = manager.submit('test.slow', { delay: 60000 });
-      await wait(100);
-
-      const removed = manager.cleanup(0);
-      expect(removed).toBe(0);
-
-      manager.cancel(taskId);
-    });
-  });
-});

package/tests/helpers.ts

@@ -1,30 +0,0 @@
-/**
- * Shared test fixtures and helpers.
- */
-
-import { Type } from '@sinclair/typebox';
-import { Context, createIdentity } from '../src/context.js';
-import { FunctionModule } from '../src/decorator.js';
-import { Registry } from '../src/registry/registry.js';
-
-export function createTestModule(options?: {
-  moduleId?: string;
-  description?: string;
-  execute?: (inputs: Record<string, unknown>, context: Context) => Record<string, unknown>;
-}): FunctionModule {
-  return new FunctionModule({
-    execute: options?.execute ?? ((inputs) => ({ echo: inputs['name'] ?? 'world' })),
-    moduleId: options?.moduleId ?? 'test.module',
-    inputSchema: Type.Object({ name: Type.Optional(Type.String()) }),
-    outputSchema: Type.Object({ echo: Type.String() }),
-    description: options?.description ?? 'A test module',
-  });
-}
-
-export function createTestRegistry(): Registry {
-  return new Registry();
-}
-
-export function createTestContext(executor?: unknown): Context {
-  return Context.create(executor, createIdentity('test-user'));
-}