apcore-js 0.4.0 → 0.6.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/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/config.ts

@@ -1,24 +0,0 @@
-/**
- * Configuration accessor with dot-path key support.
- */
-
-export class Config {
-  private _data: Record<string, unknown>;
-
-  constructor(data?: Record<string, unknown>) {
-    this._data = data ?? {};
-  }
-
-  get(key: string, defaultValue?: unknown): unknown {
-    const parts = key.split('.');
-    let current: unknown = this._data;
-    for (const part of parts) {
-      if (current !== null && typeof current === 'object' && part in (current as Record<string, unknown>)) {
-        current = (current as Record<string, unknown>)[part];
-      } else {
-        return defaultValue;
-      }
-    }
-    return current;
-  }
-}

package/src/context.ts

@@ -1,78 +0,0 @@
-
-import { v4 as uuidv4 } from 'uuid';
-
-/**
- * Execution context, identity, and context creation.
- */
-
-export interface Identity {
-  readonly id: string;
-  readonly type: string;
-  readonly roles: readonly string[];
-  readonly attrs: Readonly<Record<string, unknown>>;
-}
-
-export function createIdentity(
-  id: string,
-  type: string = 'user',
-  roles: string[] = [],
-  attrs: Record<string, unknown> = {},
-): Identity {
-  return Object.freeze({ id, type, roles: Object.freeze([...roles]), attrs: Object.freeze({ ...attrs }) });
-}
-
-export class Context {
-  readonly traceId: string;
-  readonly callerId: string | null;
-  readonly callChain: readonly string[];
-  readonly executor: unknown;
-  readonly identity: Identity | null;
-  redactedInputs: Record<string, unknown> | null;
-  readonly data: Record<string, unknown>;
-
-  constructor(
-    traceId: string,
-    callerId: string | null = null,
-    callChain: string[] = [],
-    executor: unknown = null,
-    identity: Identity | null = null,
-    redactedInputs: Record<string, unknown> | null = null,
-    data: Record<string, unknown> = {},
-  ) {
-    this.traceId = traceId;
-    this.callerId = callerId;
-    this.callChain = Object.freeze([...callChain]);
-    this.executor = executor;
-    this.identity = identity;
-    this.redactedInputs = redactedInputs;
-    this.data = data;
-  }
-
-  static create(
-    executor: unknown = null,
-    identity: Identity | null = null,
-    data?: Record<string, unknown>,
-  ): Context {
-    return new Context(
-      uuidv4(),
-      null,
-      [],
-      executor,
-      identity,
-      null,
-      data ?? {},
-    );
-  }
-
-  child(targetModuleId: string): Context {
-    return new Context(
-      this.traceId,
-      this.callChain.length > 0 ? this.callChain[this.callChain.length - 1] : null,
-      [...this.callChain, targetModuleId],
-      this.executor,
-      this.identity,
-      null,
-      this.data, // shared reference
-    );
-  }
-}

package/src/decorator.ts

@@ -1,110 +0,0 @@
-/**
- * Module factory, FunctionModule wrapper.
- *
- * TypeScript version uses explicit TypeBox schemas instead of runtime type inference.
- */
-
-import type { TSchema } from '@sinclair/typebox';
-import type { Context } from './context.js';
-import type { ModuleAnnotations, ModuleExample } from './module.js';
-
-export function normalizeResult(result: unknown): Record<string, unknown> {
-  if (result === null || result === undefined) return {};
-  if (typeof result === 'object' && !Array.isArray(result)) return result as Record<string, unknown>;
-  return { result };
-}
-
-export class FunctionModule {
-  readonly moduleId: string;
-  readonly inputSchema: TSchema;
-  readonly outputSchema: TSchema;
-  readonly description: string;
-  readonly documentation: string | null;
-  readonly tags: string[] | null;
-  readonly version: string;
-  readonly annotations: ModuleAnnotations | null;
-  readonly metadata: Record<string, unknown> | null;
-  readonly examples: ModuleExample[] | null;
-
-  private _executeFn: (inputs: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>> | Record<string, unknown>;
-
-  constructor(options: {
-    execute: (inputs: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>> | Record<string, unknown>;
-    moduleId: string;
-    inputSchema: TSchema;
-    outputSchema: TSchema;
-    description?: string;
-    documentation?: string | null;
-    tags?: string[] | null;
-    version?: string;
-    annotations?: ModuleAnnotations | null;
-    metadata?: Record<string, unknown> | null;
-    examples?: ModuleExample[] | null;
-  }) {
-    this.moduleId = options.moduleId;
-    this.inputSchema = options.inputSchema;
-    this.outputSchema = options.outputSchema;
-    this.description = options.description ?? `Module ${options.moduleId}`;
-    this.documentation = options.documentation ?? null;
-    this.tags = options.tags ?? null;
-    this.version = options.version ?? '1.0.0';
-    this.annotations = options.annotations ?? null;
-    this.metadata = options.metadata ?? null;
-    this.examples = options.examples ?? null;
-    this._executeFn = options.execute;
-  }
-
-  async execute(inputs: Record<string, unknown>, context: Context): Promise<Record<string, unknown>> {
-    const result = await this._executeFn(inputs, context);
-    return normalizeResult(result);
-  }
-}
-
-export function makeAutoId(name: string): string {
-  let raw = name.toLowerCase();
-  raw = raw.replace(/[^a-z0-9_.]/g, '_');
-  const segments = raw.split('.');
-  return segments
-    .map((s) => (s && s[0] >= '0' && s[0] <= '9' ? '_' + s : s))
-    .join('.');
-}
-
-/**
- * Create a FunctionModule from options. TypeScript version requires explicit schemas.
- */
-export function module(options: {
-  id?: string;
-  inputSchema: TSchema;
-  outputSchema: TSchema;
-  description?: string;
-  documentation?: string | null;
-  annotations?: ModuleAnnotations | null;
-  tags?: string[] | null;
-  version?: string;
-  metadata?: Record<string, unknown> | null;
-  examples?: ModuleExample[] | null;
-  execute: (inputs: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>> | Record<string, unknown>;
-  registry?: { register(moduleId: string, module: unknown): void } | null;
-}): FunctionModule {
-  const moduleId = options.id ?? makeAutoId('anonymous');
-
-  const fm = new FunctionModule({
-    execute: options.execute,
-    moduleId,
-    inputSchema: options.inputSchema,
-    outputSchema: options.outputSchema,
-    description: options.description,
-    documentation: options.documentation,
-    tags: options.tags,
-    version: options.version,
-    annotations: options.annotations,
-    metadata: options.metadata,
-    examples: options.examples,
-  });
-
-  if (options.registry) {
-    options.registry.register(fm.moduleId, fm);
-  }
-
-  return fm;
-}