apcore-js 0.5.0 → 0.7.0

package/src/acl.ts

@@ -1,200 +0,0 @@
-/**
- * ACL (Access Control List) types and implementation for apcore.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import yaml from 'js-yaml';
-import type { Context } from './context.js';
-import { ACLRuleError, ConfigNotFoundError } from './errors.js';
-import { matchPattern } from './utils/pattern.js';
-
-export interface ACLRule {
-  callers: string[];
-  targets: string[];
-  effect: string;
-  description: string;
-  conditions?: Record<string, unknown> | null;
-}
-
-function parseAclRule(rawRule: unknown, index: number): ACLRule {
-  if (typeof rawRule !== 'object' || rawRule === null || Array.isArray(rawRule)) {
-    throw new ACLRuleError(`Rule ${index} must be a mapping, got ${typeof rawRule}`);
-  }
-
-  const ruleObj = rawRule as Record<string, unknown>;
-  for (const key of ['callers', 'targets', 'effect']) {
-    if (!(key in ruleObj)) {
-      throw new ACLRuleError(`Rule ${index} missing required key '${key}'`);
-    }
-  }
-
-  const effect = ruleObj['effect'] as string;
-  if (effect !== 'allow' && effect !== 'deny') {
-    throw new ACLRuleError(`Rule ${index} has invalid effect '${effect}', must be 'allow' or 'deny'`);
-  }
-
-  const callers = ruleObj['callers'];
-  if (!Array.isArray(callers)) {
-    throw new ACLRuleError(`Rule ${index} 'callers' must be a list, got ${typeof callers}`);
-  }
-
-  const targets = ruleObj['targets'];
-  if (!Array.isArray(targets)) {
-    throw new ACLRuleError(`Rule ${index} 'targets' must be a list, got ${typeof targets}`);
-  }
-
-  return {
-    callers: callers as string[],
-    targets: targets as string[],
-    effect,
-    description: (ruleObj['description'] as string) ?? '',
-    conditions: (ruleObj['conditions'] as Record<string, unknown>) ?? null,
-  };
-}
-
-export class ACL {
-  private _rules: ACLRule[];
-  private _defaultEffect: string;
-  private _yamlPath: string | null = null;
-  debug: boolean = false;
-
-  constructor(rules: ACLRule[], defaultEffect: string = 'deny') {
-    if (defaultEffect !== 'allow' && defaultEffect !== 'deny') {
-      throw new ACLRuleError(`Invalid default_effect '${defaultEffect}', must be 'allow' or 'deny'`);
-    }
-    this._rules = [...rules];
-    this._defaultEffect = defaultEffect;
-  }
-
-  static load(yamlPath: string): ACL {
-    if (!existsSync(yamlPath)) {
-      throw new ConfigNotFoundError(yamlPath);
-    }
-
-    let data: unknown;
-    try {
-      const content = readFileSync(yamlPath, 'utf-8');
-      data = yaml.load(content);
-    } catch (e) {
-      if (e instanceof ConfigNotFoundError) throw e;
-      throw new ACLRuleError(`Invalid YAML in ${yamlPath}: ${e}`);
-    }
-
-    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
-      throw new ACLRuleError(`ACL config must be a mapping, got ${typeof data}`);
-    }
-
-    const dataObj = data as Record<string, unknown>;
-    if (!('rules' in dataObj)) {
-      throw new ACLRuleError("ACL config missing required 'rules' key");
-    }
-
-    const rawRules = dataObj['rules'];
-    if (!Array.isArray(rawRules)) {
-      throw new ACLRuleError(`'rules' must be a list, got ${typeof rawRules}`);
-    }
-
-    const defaultEffect = (dataObj['default_effect'] as string) ?? 'deny';
-    const rules = rawRules.map((raw, i) => parseAclRule(raw, i));
-
-    const acl = new ACL(rules, defaultEffect);
-    acl._yamlPath = yamlPath;
-    return acl;
-  }
-
-  check(callerId: string | null, targetId: string, context?: Context | null): boolean {
-    const effectiveCaller = callerId === null ? '@external' : callerId;
-
-    for (const rule of this._rules) {
-      if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
-        return rule.effect === 'allow';
-      }
-    }
-
-    return this._defaultEffect === 'allow';
-  }
-
-  private _matchPattern(pattern: string, value: string, context: Context | null): boolean {
-    if (pattern === '@external') return value === '@external';
-    if (pattern === '@system') {
-      return context !== null && context.identity !== null && context.identity.type === 'system';
-    }
-    return matchPattern(pattern, value);
-  }
-
-  private _matchesRule(rule: ACLRule, caller: string, target: string, context: Context | null): boolean {
-    const callerMatch = rule.callers.some((p) => this._matchPattern(p, caller, context));
-    if (!callerMatch) return false;
-
-    const targetMatch = rule.targets.some((p) => this._matchPattern(p, target, context));
-    if (!targetMatch) return false;
-
-    if (rule.conditions != null) {
-      if (!this._checkConditions(rule.conditions, context)) return false;
-    }
-
-    return true;
-  }
-
-  private _checkConditions(conditions: Record<string, unknown>, context: Context | null): boolean {
-    if (context === null) return false;
-
-    if ('identity_types' in conditions) {
-      const types = conditions['identity_types'];
-      if (!Array.isArray(types)) {
-        console.warn('[apcore:acl] identity_types condition must be an array');
-        return false;
-      }
-      if (context.identity === null || !types.includes(context.identity.type)) return false;
-    }
-
-    if ('roles' in conditions) {
-      const roles = conditions['roles'];
-      if (!Array.isArray(roles)) {
-        console.warn('[apcore:acl] roles condition must be an array');
-        return false;
-      }
-      if (context.identity === null) return false;
-      const identityRoles = new Set(context.identity.roles);
-      if (!roles.some((r: string) => identityRoles.has(r))) return false;
-    }
-
-    if ('max_call_depth' in conditions) {
-      const maxDepth = conditions['max_call_depth'];
-      if (typeof maxDepth !== 'number') {
-        console.warn('[apcore:acl] max_call_depth condition must be a number');
-        return false;
-      }
-      if (context.callChain.length > maxDepth) return false;
-    }
-
-    return true;
-  }
-
-  addRule(rule: ACLRule): void {
-    this._rules.unshift(rule);
-  }
-
-  removeRule(callers: string[], targets: string[]): boolean {
-    for (let i = 0; i < this._rules.length; i++) {
-      const rule = this._rules[i];
-      if (
-        JSON.stringify(rule.callers) === JSON.stringify(callers) &&
-        JSON.stringify(rule.targets) === JSON.stringify(targets)
-      ) {
-        this._rules.splice(i, 1);
-        return true;
-      }
-    }
-    return false;
-  }
-
-  reload(): void {
-    if (this._yamlPath === null) {
-      throw new ACLRuleError('Cannot reload: ACL was not loaded from a YAML file');
-    }
-    const reloaded = ACL.load(this._yamlPath);
-    this._rules = reloaded._rules;
-    this._defaultEffect = reloaded._defaultEffect;
-  }
-}

package/src/async-task.ts

@@ -1,267 +0,0 @@
-/**
- * Async task manager for background module execution.
- */
-
-import { v4 as uuidv4 } from 'uuid';
-import type { Context } from './context.js';
-import type { Executor } from './executor.js';
-
-export enum TaskStatus {
-  PENDING = 'pending',
-  RUNNING = 'running',
-  COMPLETED = 'completed',
-  FAILED = 'failed',
-  CANCELLED = 'cancelled',
-}
-
-export interface TaskInfo {
-  readonly taskId: string;
-  readonly moduleId: string;
-  readonly status: TaskStatus;
-  readonly submittedAt: number;
-  readonly startedAt: number | null;
-  readonly completedAt: number | null;
-  readonly result: Record<string, unknown> | null;
-  readonly error: string | null;
-}
-
-type InternalTaskInfo = { -readonly [K in keyof TaskInfo]: TaskInfo[K] };
-
-interface InternalTask {
-  info: InternalTaskInfo;
-  promise: Promise<void>;
-  cancelled: boolean;
-  resolve: () => void;
-}
-
-/**
- * Manages background execution of modules via Promises.
- *
- * Uses a simple counter-based concurrency limiter instead of a semaphore.
- */
-export class AsyncTaskManager {
-  private readonly _executor: Executor;
-  private readonly _maxConcurrent: number;
-  private readonly _maxTasks: number;
-  private readonly _tasks: Map<string, InternalTask> = new Map();
-  private _runningCount: number = 0;
-  private readonly _waitQueue: Array<() => void> = [];
-
-  constructor(executor: Executor, maxConcurrent: number = 10, maxTasks: number = 1000) {
-    this._executor = executor;
-    this._maxConcurrent = maxConcurrent;
-    this._maxTasks = maxTasks;
-  }
-
-  /**
-   * Submit a module for background execution.
-   *
-   * Returns the generated task_id immediately.
-   */
-  submit(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context?: Context | null,
-  ): string {
-    if (this._tasks.size >= this._maxTasks) {
-      throw new Error(`Task limit reached (${this._maxTasks})`);
-    }
-    const taskId = uuidv4();
-    const info: InternalTaskInfo = {
-      taskId,
-      moduleId,
-      status: TaskStatus.PENDING,
-      submittedAt: Date.now() / 1000,
-      startedAt: null,
-      completedAt: null,
-      result: null,
-      error: null,
-    };
-
-    let resolvePromise!: () => void;
-    const promise = new Promise<void>((resolve) => {
-      resolvePromise = resolve;
-    });
-
-    const internal: InternalTask = {
-      info,
-      promise,
-      cancelled: false,
-      resolve: resolvePromise,
-    };
-
-    this._tasks.set(taskId, internal);
-    this._enqueue(taskId, moduleId, inputs, context ?? null);
-    return taskId;
-  }
-
-  /**
-   * Return the TaskInfo for a task, or null if not found.
-   */
-  getStatus(taskId: string): TaskInfo | null {
-    const internal = this._tasks.get(taskId);
-    return internal ? { ...internal.info } : null;
-  }
-
-  /**
-   * Return the result of a completed task.
-   *
-   * Throws if the task is not found or not in COMPLETED status.
-   */
-  getResult(taskId: string): Record<string, unknown> {
-    const internal = this._tasks.get(taskId);
-    if (!internal) {
-      throw new Error(`Task not found: ${taskId}`);
-    }
-    if (internal.info.status !== TaskStatus.COMPLETED) {
-      throw new Error(`Task ${taskId} is not completed (status=${internal.info.status})`);
-    }
-    return internal.info.result!;
-  }
-
-  /**
-   * Cancel a running or pending task.
-   *
-   * Sets the cancelled flag and updates status immediately.
-   * The underlying execution may still be in-flight but its result
-   * will be discarded when it completes.
-   *
-   * Returns true if the task was successfully marked as cancelled.
-   */
-  cancel(taskId: string): boolean {
-    const internal = this._tasks.get(taskId);
-    if (!internal) return false;
-
-    const { info } = internal;
-    if (info.status !== TaskStatus.PENDING && info.status !== TaskStatus.RUNNING) {
-      return false;
-    }
-
-    internal.cancelled = true;
-    info.status = TaskStatus.CANCELLED;
-    info.completedAt = Date.now() / 1000;
-    return true;
-  }
-
-  /**
-   * Return all tasks, optionally filtered by status.
-   */
-  listTasks(status?: TaskStatus): TaskInfo[] {
-    const tasks = [...this._tasks.values()];
-    const filtered = status ? tasks.filter(t => t.info.status === status) : tasks;
-    return filtered.map(t => ({ ...t.info }));
-  }
-
-  /**
-   * Remove terminal-state tasks older than maxAgeSeconds seconds.
-   *
-   * Terminal states: COMPLETED, FAILED, CANCELLED.
-   * Returns the number of tasks removed.
-   */
-  cleanup(maxAgeSeconds: number = 3600): number {
-    const terminal = new Set([TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.CANCELLED]);
-    const now = Date.now() / 1000;
-    let removed = 0;
-
-    for (const [taskId, internal] of this._tasks.entries()) {
-      if (!terminal.has(internal.info.status)) continue;
-      const refTime = internal.info.completedAt ?? internal.info.submittedAt;
-      if ((now - refTime) >= maxAgeSeconds) {
-        this._tasks.delete(taskId);
-        removed++;
-      }
-    }
-
-    return removed;
-  }
-
-  /**
-   * Cancel all pending and running tasks.
-   */
-  shutdown(): void {
-    for (const [taskId, task] of this._tasks) {
-      if (task.info.status === TaskStatus.PENDING || task.info.status === TaskStatus.RUNNING) {
-        this.cancel(taskId);
-      }
-    }
-  }
-
-  /**
-   * Acquire a concurrency slot. Resolves when a slot is available.
-   */
-  private _acquireSlot(): Promise<void> {
-    if (this._runningCount < this._maxConcurrent) {
-      this._runningCount++;
-      return Promise.resolve();
-    }
-    return new Promise<void>((resolve) => {
-      this._waitQueue.push(() => {
-        this._runningCount++;
-        resolve();
-      });
-    });
-  }
-
-  /**
-   * Release a concurrency slot and notify the next waiter.
-   */
-  private _releaseSlot(): void {
-    this._runningCount--;
-    if (this._waitQueue.length > 0) {
-      const next = this._waitQueue.shift()!;
-      next();
-    }
-  }
-
-  /**
-   * Enqueue the task for execution under the concurrency limit.
-   */
-  private _enqueue(
-    taskId: string,
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context | null,
-  ): void {
-    const run = async (): Promise<void> => {
-      const internal = this._tasks.get(taskId);
-      if (!internal) return;
-
-      try {
-        await this._acquireSlot();
-
-        // Check if cancelled while waiting for a slot
-        if (internal.cancelled) {
-          return; // finally block handles releaseSlot + resolve
-        }
-
-        internal.info.status = TaskStatus.RUNNING;
-        internal.info.startedAt = Date.now() / 1000;
-
-        const result = await this._executor.call(moduleId, inputs, context);
-
-        // Check if cancelled during execution
-        if (internal.cancelled) {
-          return; // finally block handles releaseSlot + resolve
-        }
-
-        internal.info.status = TaskStatus.COMPLETED;
-        internal.info.completedAt = Date.now() / 1000;
-        internal.info.result = result;
-      } catch (err) {
-        if (!internal.cancelled) {
-          internal.info.status = TaskStatus.FAILED;
-          internal.info.completedAt = Date.now() / 1000;
-          internal.info.error = err instanceof Error ? err.message : String(err);
-        }
-      } finally {
-        this._releaseSlot();
-        internal.resolve();
-      }
-    };
-
-    // Fire and forget -- errors are captured inside run()
-    run().catch((err) => {
-      console.warn('[apcore:async-task] Unexpected error in task runner:', err);
-    });
-  }
-}

package/src/bindings.ts

@@ -1,207 +0,0 @@
-/**
- * YAML binding loader for zero-code-modification module integration.
- */
-
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { resolve, dirname, join, basename, isAbsolute } from 'node:path';
-import { Type, type TSchema } from '@sinclair/typebox';
-import yaml from 'js-yaml';
-import { FunctionModule } from './decorator.js';
-import {
-  BindingCallableNotFoundError,
-  BindingFileInvalidError,
-  BindingInvalidTargetError,
-  BindingModuleNotFoundError,
-  BindingNotCallableError,
-  BindingSchemaMissingError,
-} from './errors.js';
-import type { Registry } from './registry/registry.js';
-import { jsonSchemaToTypeBox } from './schema/loader.js';
-
-export class BindingLoader {
-  async loadBindings(filePath: string, registry: Registry): Promise<FunctionModule[]> {
-    const bindingFileDir = dirname(filePath);
-
-    let content: string;
-    try {
-      content = readFileSync(filePath, 'utf-8');
-    } catch (e) {
-      throw new BindingFileInvalidError(filePath, String(e));
-    }
-
-    let data: unknown;
-    try {
-      data = yaml.load(content);
-    } catch (e) {
-      throw new BindingFileInvalidError(filePath, `YAML parse error: ${e}`);
-    }
-
-    if (data === null || data === undefined) {
-      throw new BindingFileInvalidError(filePath, 'File is empty');
-    }
-
-    const dataObj = data as Record<string, unknown>;
-    if (!('bindings' in dataObj)) {
-      throw new BindingFileInvalidError(filePath, "Missing 'bindings' key");
-    }
-
-    const bindings = dataObj['bindings'];
-    if (!Array.isArray(bindings)) {
-      throw new BindingFileInvalidError(filePath, "'bindings' must be a list");
-    }
-
-    const results: FunctionModule[] = [];
-    for (const entry of bindings) {
-      const entryObj = entry as Record<string, unknown>;
-      if (!('module_id' in entryObj)) {
-        throw new BindingFileInvalidError(filePath, "Binding entry missing 'module_id'");
-      }
-      if (!('target' in entryObj)) {
-        throw new BindingFileInvalidError(filePath, "Binding entry missing 'target'");
-      }
-
-      const fm = await this._createModuleFromBinding(entryObj, bindingFileDir);
-      registry.register(entryObj['module_id'] as string, fm);
-      results.push(fm);
-    }
-
-    return results;
-  }
-
-  async loadBindingDir(
-    dirPath: string,
-    registry: Registry,
-    pattern: string = '*.binding.yaml',
-  ): Promise<FunctionModule[]> {
-    if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) {
-      throw new BindingFileInvalidError(dirPath, 'Directory does not exist');
-    }
-
-    const files = readdirSync(dirPath)
-      .filter((f) => {
-        // Simple glob matching for *.binding.yaml
-        const suffix = pattern.replace('*', '');
-        return f.endsWith(suffix);
-      })
-      .sort();
-
-    const results: FunctionModule[] = [];
-    for (const f of files) {
-      const fms = await this.loadBindings(join(dirPath, f), registry);
-      results.push(...fms);
-    }
-    return results;
-  }
-
-  async resolveTarget(targetString: string): Promise<(...args: unknown[]) => unknown> {
-    if (!targetString.includes(':')) {
-      throw new BindingInvalidTargetError(targetString);
-    }
-
-    const [modulePath, callableName] = targetString.split(':', 2);
-
-    if (modulePath.includes('..')) {
-      throw new BindingInvalidTargetError(
-        `Module path '${modulePath}' must not contain '..' segments`,
-      );
-    }
-
-    if (modulePath.startsWith('file:')) {
-      throw new BindingInvalidTargetError(
-        `Module path '${modulePath}' must not use file: URLs`,
-      );
-    }
-
-    let mod: Record<string, unknown>;
-    try {
-      mod = await import(modulePath);
-    } catch (e) {
-      throw new BindingModuleNotFoundError(modulePath);
-    }
-
-    if (callableName.includes('.')) {
-      const [className, methodName] = callableName.split('.', 2);
-      const cls = mod[className];
-      if (cls == null) {
-        throw new BindingCallableNotFoundError(className, modulePath);
-      }
-      let instance: Record<string, unknown>;
-      try {
-        instance = new (cls as new () => Record<string, unknown>)();
-      } catch {
-        throw new BindingCallableNotFoundError(callableName, modulePath);
-      }
-      const method = instance[methodName];
-      if (method == null) {
-        throw new BindingCallableNotFoundError(callableName, modulePath);
-      }
-      if (typeof method !== 'function') {
-        throw new BindingNotCallableError(targetString);
-      }
-      return method.bind(instance) as (...args: unknown[]) => unknown;
-    }
-
-    const result = mod[callableName];
-    if (result == null) {
-      throw new BindingCallableNotFoundError(callableName, modulePath);
-    }
-    if (typeof result !== 'function') {
-      throw new BindingNotCallableError(targetString);
-    }
-    return result as (...args: unknown[]) => unknown;
-  }
-
-  private async _createModuleFromBinding(
-    binding: Record<string, unknown>,
-    bindingFileDir: string,
-  ): Promise<FunctionModule> {
-    const func = await this.resolveTarget(binding['target'] as string);
-    const moduleId = binding['module_id'] as string;
-
-    let inputSchema: TSchema;
-    let outputSchema: TSchema;
-
-    if ('input_schema' in binding || 'output_schema' in binding) {
-      const inputSchemaDict = (binding['input_schema'] as Record<string, unknown>) ?? {};
-      const outputSchemaDict = (binding['output_schema'] as Record<string, unknown>) ?? {};
-      inputSchema = jsonSchemaToTypeBox(inputSchemaDict);
-      outputSchema = jsonSchemaToTypeBox(outputSchemaDict);
-    } else if ('schema_ref' in binding) {
-      const refPath = resolve(bindingFileDir, binding['schema_ref'] as string);
-      if (!existsSync(refPath)) {
-        throw new BindingFileInvalidError(refPath, 'Schema reference file not found');
-      }
-      let refData: Record<string, unknown>;
-      try {
-        refData = (yaml.load(readFileSync(refPath, 'utf-8')) as Record<string, unknown>) ?? {};
-      } catch (e) {
-        throw new BindingFileInvalidError(refPath, `YAML parse error: ${e}`);
-      }
-      inputSchema = jsonSchemaToTypeBox(
-        (refData['input_schema'] as Record<string, unknown>) ?? {},
-      );
-      outputSchema = jsonSchemaToTypeBox(
-        (refData['output_schema'] as Record<string, unknown>) ?? {},
-      );
-    } else {
-      // No schema, use permissive
-      inputSchema = Type.Record(Type.String(), Type.Unknown());
-      outputSchema = Type.Record(Type.String(), Type.Unknown());
-    }
-
-    return new FunctionModule({
-      execute: async (inputs, context) => {
-        const result = await func(inputs, context);
-        if (result === null || result === undefined) return {};
-        if (typeof result === 'object' && !Array.isArray(result)) return result as Record<string, unknown>;
-        return { result };
-      },
-      moduleId,
-      inputSchema,
-      outputSchema,
-      description: (binding['description'] as string) ?? undefined,
-      tags: (binding['tags'] as string[]) ?? null,
-      version: (binding['version'] as string) ?? '1.0.0',
-    });
-  }
-}

package/src/cancel.ts

@@ -1,32 +0,0 @@
-/**
- * Cooperative cancellation support for apcore module execution.
- */
-
-export class ExecutionCancelledError extends Error {
-  constructor(message: string = "Execution was cancelled") {
-    super(message);
-    this.name = "ExecutionCancelledError";
-  }
-}
-
-export class CancelToken {
-  private _cancelled: boolean = false;
-
-  get isCancelled(): boolean {
-    return this._cancelled;
-  }
-
-  cancel(): void {
-    this._cancelled = true;
-  }
-
-  check(): void {
-    if (this._cancelled) {
-      throw new ExecutionCancelledError();
-    }
-  }
-
-  reset(): void {
-    this._cancelled = false;
-  }
-}