apcore-js 0.1.0

package/src/acl.ts

@@ -0,0 +1,188 @@
+/**
+ * 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;
+}
+
+export class ACL {
+  private _rules: ACLRule[];
+  private _defaultEffect: string;
+  private _yamlPath: string | null = null;
+  debug: boolean = false;
+
+  constructor(rules: ACLRule[], defaultEffect: string = '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: ACLRule[] = [];
+
+    for (let i = 0; i < rawRules.length; i++) {
+      const rawRule = rawRules[i];
+      if (typeof rawRule !== 'object' || rawRule === null || Array.isArray(rawRule)) {
+        throw new ACLRuleError(`Rule ${i} 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 ${i} missing required key '${key}'`);
+        }
+      }
+
+      const effect = ruleObj['effect'] as string;
+      if (effect !== 'allow' && effect !== 'deny') {
+        throw new ACLRuleError(`Rule ${i} has invalid effect '${effect}', must be 'allow' or 'deny'`);
+      }
+
+      const callers = ruleObj['callers'];
+      if (!Array.isArray(callers)) {
+        throw new ACLRuleError(`Rule ${i} 'callers' must be a list, got ${typeof callers}`);
+      }
+
+      const targets = ruleObj['targets'];
+      if (!Array.isArray(targets)) {
+        throw new ACLRuleError(`Rule ${i} 'targets' must be a list, got ${typeof targets}`);
+      }
+
+      rules.push({
+        callers: callers as string[],
+        targets: targets as string[],
+        effect,
+        description: (ruleObj['description'] as string) ?? '',
+        conditions: (ruleObj['conditions'] as Record<string, unknown>) ?? null,
+      });
+    }
+
+    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;
+    const rules = [...this._rules];
+    const defaultEffect = this._defaultEffect;
+
+    for (const rule of rules) {
+      if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
+        return rule.effect === 'allow';
+      }
+    }
+
+    return 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'] as string[];
+      if (context.identity === null || !types.includes(context.identity.type)) return false;
+    }
+
+    if ('roles' in conditions) {
+      const roles = conditions['roles'] as string[];
+      if (context.identity === null) return false;
+      const identityRoles = new Set(context.identity.roles);
+      if (!roles.some((r) => identityRoles.has(r))) return false;
+    }
+
+    if ('max_call_depth' in conditions) {
+      const maxDepth = conditions['max_call_depth'] as number;
+      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

@@ -0,0 +1,208 @@
+/**
+ * YAML binding loader for zero-code-modification module integration.
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join, basename } 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';
+
+const JSON_SCHEMA_TYPE_MAP: Record<string, () => TSchema> = {
+  string: () => Type.String(),
+  integer: () => Type.Integer(),
+  number: () => Type.Number(),
+  boolean: () => Type.Boolean(),
+  array: () => Type.Array(Type.Unknown()),
+  object: () => Type.Record(Type.String(), Type.Unknown()),
+};
+
+function buildSchemaFromJsonSchema(schema: Record<string, unknown>): TSchema {
+  return jsonSchemaToTypeBox(schema);
+}
+
+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);
+
+    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 = buildSchemaFromJsonSchema(inputSchemaDict);
+      outputSchema = buildSchemaFromJsonSchema(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 = buildSchemaFromJsonSchema(
+        (refData['input_schema'] as Record<string, unknown>) ?? {},
+      );
+      outputSchema = buildSchemaFromJsonSchema(
+        (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

@@ -0,0 +1,24 @@
+/**
+ * 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

@@ -0,0 +1,75 @@
+/**
+ * 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: 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 = 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(
+      crypto.randomUUID(),
+      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

@@ -0,0 +1,110 @@
+/**
+ * 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;
+}