apcore-js 0.1.1 → 0.2.0

package/.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(npm test:*)",
       "Bash(npx tsc:*)",
       "Bash(wc:*)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "Skill(code-forge:review)"
     ]
   }
 }

package/.pre-commit-config.yaml

@@ -5,13 +5,13 @@ repos:
     hooks:
       - id: check-chars
         name: apdev-js check-chars
-        entry: apdev-js check-chars
+        entry: npx apdev-js check-chars
         language: system
         types_or: [text, ts, javascript]
 
       - id: check-imports
         name: apdev-js check-imports
-        entry: apdev-js check-imports
+        entry: npx apdev-js check-imports --package apcore-js
         language: system
         pass_filenames: false
         always_run: true

package/CHANGELOG.md

@@ -5,6 +5,69 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-20
+
+### Added
+
+- **Error classes and constants**
+  - `ModuleExecuteError` — New error class for module execution failures
+  - `InternalError` — New error class for general internal errors
+  - `ErrorCodes` — Frozen object with all 26 error code strings for consistent error code usage
+  - `ErrorCode` — Type definition for all error codes
+- **Registry constants**
+  - `REGISTRY_EVENTS` — Frozen object with standard event names (`register`, `unregister`)
+  - `MODULE_ID_PATTERN` — Regex pattern enforcing lowercase/digits/underscores/dots for module IDs (no hyphens allowed to ensure bijective MCP tool name normalization)
+- **Executor methods**
+  - `Executor.callAsync()` — Alias for `call()` for compatibility with MCP bridge packages
+
+### Changed
+
+- **Module ID validation** — Registry now validates module IDs against `MODULE_ID_PATTERN` on registration, rejecting IDs with hyphens or invalid characters
+- **Event handling** — Registry event validation now uses `REGISTRY_EVENTS` constants instead of hardcoded strings
+- **Test updates** — Updated tests to use underscore-separated module IDs instead of hyphens (e.g., `math.add_ten` instead of `math.addTen`, `ctx_test` instead of `ctx-test`)
+
+### Fixed
+
+- **String literals in Registry** — Replaced hardcoded `'register'` and `'unregister'` strings with `REGISTRY_EVENTS.REGISTER` and `REGISTRY_EVENTS.UNREGISTER` constants in event triggers for consistency
+
+## [0.1.2] - 2026-02-18
+
+### Fixed
+
+- **Timer leak in executor** — `_executeWithTimeout` now calls `clearTimeout` in `.finally()` to prevent timer leak on normal completion
+- **Path traversal protection** — `resolveTarget` in binding loader rejects module paths containing `..` segments before dynamic `import()`
+- **Bare catch blocks** — 6 silent `catch {}` blocks in registry and middleware manager now log warnings with `[apcore:<subsystem>]` prefix
+- **Python-style error messages** — Fixed `FuncMissingTypeHintError` and `FuncMissingReturnTypeError` to use TypeScript syntax (`: string`, `: Record<string, unknown>`)
+- **Console.log in production** — Replaced `console.log` with `console.info` in logging middleware and `process.stdout.write` in tracing exporter
+
+### Changed
+
+- **Long method decomposition** — Broke up 4 oversized methods to meet ≤50 line guideline:
+  - `Executor.call()` (108 → 6 private helpers)
+  - `Registry.discover()` (110 → 7 private helpers)
+  - `ACL.load()` (71 → extracted `parseAclRule`)
+  - `jsonSchemaToTypeBox()` (80 → 5 converter helpers)
+- **Deeply readonly callChain** — `Context.callChain` type narrowed from `readonly string[]` to `readonly (readonly string[])` preventing mutation via push/splice
+- **Consolidated `deepCopy`** — Removed 4 duplicate `deepCopy` implementations; single shared version now lives in `src/utils/index.ts`
+
+### Added
+
+- **42 new tests** for previously uncovered modules:
+  - `tests/schema/test-annotations.test.ts` — 16 tests for `mergeAnnotations`, `mergeExamples`, `mergeMetadata`
+  - `tests/schema/test-exporter.test.ts` — 14 tests for `SchemaExporter` across all 4 export profiles
+  - `tests/test-logging-middleware.test.ts` — 12 tests for `LoggingMiddleware` before/after/onError
+
+## [0.1.1] - 2026-02-17
+
+### Fixed
+
+- Updated logo URL in README
+
+### Changed
+
+- Renamed package from `apcore` to `apcore-js`
+- Updated installation instructions
+
 ## [0.1.0] - 2026-02-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",

package/planning/overview.md

@@ -3,7 +3,7 @@
 ## Overall Progress
 
 ```
-[████████████████████████████████████████] 42/42 tasks (100%)
+[>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] 42/42 tasks (100%)
 ```
 
 | Status | Count |

package/src/acl.ts

@@ -16,6 +16,42 @@ export interface ACLRule {
   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;
@@ -56,44 +92,7 @@ export class ACL {
     }
 
     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 rules = rawRules.map((raw, i) => parseAclRule(raw, i));
 
     const acl = new ACL(rules, defaultEffect);
     acl._yamlPath = yamlPath;

package/src/bindings.ts

@@ -3,7 +3,7 @@
  */
 
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { resolve, dirname, join, basename } from 'node:path';
+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';
@@ -18,19 +18,6 @@ import {
 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);
@@ -113,6 +100,12 @@ export class BindingLoader {
 
     const [modulePath, callableName] = targetString.split(':', 2);
 
+    if (modulePath.includes('..')) {
+      throw new BindingInvalidTargetError(
+        `Module path '${modulePath}' must not contain '..' segments`,
+      );
+    }
+
     let mod: Record<string, unknown>;
     try {
       mod = await import(modulePath);
@@ -165,8 +158,8 @@ export class BindingLoader {
     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);
+      inputSchema = jsonSchemaToTypeBox(inputSchemaDict);
+      outputSchema = jsonSchemaToTypeBox(outputSchemaDict);
     } else if ('schema_ref' in binding) {
       const refPath = resolve(bindingFileDir, binding['schema_ref'] as string);
       if (!existsSync(refPath)) {
@@ -178,10 +171,10 @@ export class BindingLoader {
       } catch (e) {
         throw new BindingFileInvalidError(refPath, `YAML parse error: ${e}`);
       }
-      inputSchema = buildSchemaFromJsonSchema(
+      inputSchema = jsonSchemaToTypeBox(
         (refData['input_schema'] as Record<string, unknown>) ?? {},
       );
-      outputSchema = buildSchemaFromJsonSchema(
+      outputSchema = jsonSchemaToTypeBox(
         (refData['output_schema'] as Record<string, unknown>) ?? {},
       );
     } else {

package/src/context.ts

@@ -21,7 +21,7 @@ export function createIdentity(
 export class Context {
   readonly traceId: string;
   readonly callerId: string | null;
-  readonly callChain: string[];
+  readonly callChain: readonly string[];
   readonly executor: unknown;
   readonly identity: Identity | null;
   redactedInputs: Record<string, unknown> | null;

package/src/errors.ts

@@ -242,7 +242,7 @@ export class FuncMissingTypeHintError extends ModuleError {
   constructor(functionName: string, parameterName: string, options?: { cause?: Error; traceId?: string }) {
     super(
       'FUNC_MISSING_TYPE_HINT',
-      `Parameter '${parameterName}' in function '${functionName}' has no type annotation. Add a type hint like '${parameterName}: str'.`,
+      `Parameter '${parameterName}' in function '${functionName}' has no type annotation. Add a type annotation like '${parameterName}: string'.`,
       { functionName, parameterName },
       options?.cause,
       options?.traceId,
@@ -255,7 +255,7 @@ export class FuncMissingReturnTypeError extends ModuleError {
   constructor(functionName: string, options?: { cause?: Error; traceId?: string }) {
     super(
       'FUNC_MISSING_RETURN_TYPE',
-      `Function '${functionName}' has no return type annotation. Add a return type like '-> dict'.`,
+      `Function '${functionName}' has no return type annotation. Add a return type like ': Record<string, unknown>'.`,
       { functionName },
       options?.cause,
       options?.traceId,
@@ -367,3 +367,58 @@ export class ModuleLoadError extends ModuleError {
     this.name = 'ModuleLoadError';
   }
 }
+
+export class ModuleExecuteError extends ModuleError {
+  constructor(moduleId: string, reason: string, options?: { cause?: Error; traceId?: string }) {
+    super(
+      'MODULE_EXECUTE_ERROR',
+      `Failed to execute module '${moduleId}': ${reason}`,
+      { moduleId, reason },
+      options?.cause,
+      options?.traceId,
+    );
+    this.name = 'ModuleExecuteError';
+  }
+}
+
+export class InternalError extends ModuleError {
+  constructor(message: string = 'Internal error', options?: { cause?: Error; traceId?: string }) {
+    super('GENERAL_INTERNAL_ERROR', message, {}, options?.cause, options?.traceId);
+    this.name = 'InternalError';
+  }
+}
+
+/**
+ * All framework error codes as constants.
+ * Use these instead of hardcoding error code strings.
+ */
+export const ErrorCodes = Object.freeze({
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_INVALID: "CONFIG_INVALID",
+  ACL_RULE_ERROR: "ACL_RULE_ERROR",
+  ACL_DENIED: "ACL_DENIED",
+  MODULE_NOT_FOUND: "MODULE_NOT_FOUND",
+  MODULE_TIMEOUT: "MODULE_TIMEOUT",
+  MODULE_LOAD_ERROR: "MODULE_LOAD_ERROR",
+  MODULE_EXECUTE_ERROR: "MODULE_EXECUTE_ERROR",
+  SCHEMA_VALIDATION_ERROR: "SCHEMA_VALIDATION_ERROR",
+  SCHEMA_NOT_FOUND: "SCHEMA_NOT_FOUND",
+  SCHEMA_PARSE_ERROR: "SCHEMA_PARSE_ERROR",
+  SCHEMA_CIRCULAR_REF: "SCHEMA_CIRCULAR_REF",
+  CALL_DEPTH_EXCEEDED: "CALL_DEPTH_EXCEEDED",
+  CIRCULAR_CALL: "CIRCULAR_CALL",
+  CALL_FREQUENCY_EXCEEDED: "CALL_FREQUENCY_EXCEEDED",
+  GENERAL_INVALID_INPUT: "GENERAL_INVALID_INPUT",
+  GENERAL_INTERNAL_ERROR: "GENERAL_INTERNAL_ERROR",
+  FUNC_MISSING_TYPE_HINT: "FUNC_MISSING_TYPE_HINT",
+  FUNC_MISSING_RETURN_TYPE: "FUNC_MISSING_RETURN_TYPE",
+  BINDING_INVALID_TARGET: "BINDING_INVALID_TARGET",
+  BINDING_MODULE_NOT_FOUND: "BINDING_MODULE_NOT_FOUND",
+  BINDING_CALLABLE_NOT_FOUND: "BINDING_CALLABLE_NOT_FOUND",
+  BINDING_NOT_CALLABLE: "BINDING_NOT_CALLABLE",
+  BINDING_SCHEMA_MISSING: "BINDING_SCHEMA_MISSING",
+  BINDING_FILE_INVALID: "BINDING_FILE_INVALID",
+  CIRCULAR_DEPENDENCY: "CIRCULAR_DEPENDENCY",
+} as const);
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/src/executor.ts

@@ -157,60 +157,97 @@ export class Executor {
     context?: Context | null,
   ): Promise<Record<string, unknown>> {
     let effectiveInputs = inputs ?? {};
+    const ctx = this._createContext(moduleId, context);
+    this._checkSafety(moduleId, ctx);
+
+    const mod = this._lookupModule(moduleId);
+    this._checkAcl(moduleId, ctx);
+
+    effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
+
+    return this._executeWithMiddleware(mod, moduleId, effectiveInputs, ctx);
+  }
+
+  /**
+   * Alias for call(). Provided for compatibility with MCP bridge packages
+   * that may call callAsync() by convention.
+   */
+  async callAsync(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): Promise<Record<string, unknown>> {
+    return this.call(moduleId, inputs, context);
+  }
 
-    // Step 1 -- Context
-    let ctx: Context;
+  private _createContext(moduleId: string, context?: Context | null): Context {
     if (context == null) {
-      ctx = Context.create(this);
-      ctx = ctx.child(moduleId);
-    } else {
-      ctx = context.child(moduleId);
+      return Context.create(this).child(moduleId);
     }
+    return context.child(moduleId);
+  }
 
-    // Step 2 -- Safety Checks
-    this._checkSafety(moduleId, ctx);
-
-    // Step 3 -- Lookup
+  private _lookupModule(moduleId: string): Record<string, unknown> {
     const module = this._registry.get(moduleId);
     if (module === null) {
       throw new ModuleNotFoundError(moduleId);
     }
+    return module as Record<string, unknown>;
+  }
 
-    const mod = module as Record<string, unknown>;
-
-    // Step 4 -- ACL
+  private _checkAcl(moduleId: string, ctx: Context): void {
     if (this._acl !== null) {
       const allowed = this._acl.check(ctx.callerId, moduleId, ctx);
       if (!allowed) {
         throw new ACLDeniedError(ctx.callerId, moduleId);
       }
     }
+  }
 
-    // Step 5 -- Input Validation and Redaction
+  private _validateInputs(
+    mod: Record<string, unknown>,
+    inputs: Record<string, unknown>,
+    ctx: Context,
+  ): Record<string, unknown> {
     const inputSchema = mod['inputSchema'] as TSchema | undefined;
-    if (inputSchema != null) {
-      if (!Value.Check(inputSchema, effectiveInputs)) {
-        const errors: Array<Record<string, unknown>> = [];
-        for (const error of Value.Errors(inputSchema, effectiveInputs)) {
-          errors.push({
-            field: error.path || '/',
-            code: String(error.type),
-            message: error.message,
-          });
-        }
-        throw new SchemaValidationError('Input validation failed', errors);
-      }
+    if (inputSchema == null) return inputs;
+
+    this._validateSchema(inputSchema, inputs, 'Input');
+    ctx.redactedInputs = redactSensitive(
+      inputs,
+      inputSchema as unknown as Record<string, unknown>,
+    );
+    return inputs;
+  }
+
+  private _validateSchema(
+    schema: TSchema,
+    data: Record<string, unknown>,
+    direction: string,
+  ): void {
+    if (Value.Check(schema, data)) return;
 
-      ctx.redactedInputs = redactSensitive(
-        effectiveInputs,
-        inputSchema as unknown as Record<string, unknown>,
-      );
+    const errors: Array<Record<string, unknown>> = [];
+    for (const error of Value.Errors(schema, data)) {
+      errors.push({
+        field: error.path || '/',
+        code: String(error.type),
+        message: error.message,
+      });
     }
+    throw new SchemaValidationError(`${direction} validation failed`, errors);
+  }
 
+  private async _executeWithMiddleware(
+    mod: Record<string, unknown>,
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    ctx: Context,
+  ): Promise<Record<string, unknown>> {
+    let effectiveInputs = inputs;
     let executedMiddlewares: Middleware[] = [];
 
     try {
-      // Step 6 -- Middleware Before
       try {
         [effectiveInputs, executedMiddlewares] = this._middlewareManager.executeBefore(moduleId, effectiveInputs, ctx);
       } catch (e) {
@@ -226,29 +263,14 @@ export class Executor {
         throw e;
       }
 
-      // Step 7 -- Execute with timeout
       let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
 
-      // Step 8 -- Output Validation
       const outputSchema = mod['outputSchema'] as TSchema | undefined;
       if (outputSchema != null) {
-        if (!Value.Check(outputSchema, output)) {
-          const errors: Array<Record<string, unknown>> = [];
-          for (const error of Value.Errors(outputSchema, output)) {
-            errors.push({
-              field: error.path || '/',
-              code: String(error.type),
-              message: error.message,
-            });
-          }
-          throw new SchemaValidationError('Output validation failed', errors);
-        }
+        this._validateSchema(outputSchema, output, 'Output');
       }
 
-      // Step 9 -- Middleware After
       output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
-
-      // Step 10 -- Return
       return output;
     } catch (exc) {
       if (executedMiddlewares.length > 0) {
@@ -337,12 +359,15 @@ export class Executor {
       return executionPromise;
     }
 
+    let timer: ReturnType<typeof setTimeout>;
     const timeoutPromise = new Promise<never>((_, reject) => {
-      setTimeout(() => {
+      timer = setTimeout(() => {
         reject(new ModuleTimeoutError(moduleId, timeoutMs));
       }, timeoutMs);
     });
 
-    return Promise.race([executionPromise, timeoutPromise]);
+    return Promise.race([executionPromise, timeoutPromise]).finally(() => {
+      clearTimeout(timer);
+    });
   }
 }

package/src/index.ts

@@ -5,7 +5,7 @@
 // Core
 export { Context, createIdentity } from './context.js';
 export type { Identity } from './context.js';
-export { Registry } from './registry/registry.js';
+export { Registry, REGISTRY_EVENTS, MODULE_ID_PATTERN } from './registry/registry.js';
 export { Executor, redactSensitive, REDACTED_VALUE } from './executor.js';
 
 // Module types
@@ -42,7 +42,11 @@ export {
   BindingFileInvalidError,
   CircularDependencyError,
   ModuleLoadError,
+  ModuleExecuteError,
+  InternalError,
+  ErrorCodes,
 } from './errors.js';
+export type { ErrorCode } from './errors.js';
 
 // ACL
 export { ACL } from './acl.js';
@@ -78,4 +82,4 @@ export type { Span, SpanExporter } from './observability/tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './observability/metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './observability/context-logger.js';
 
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.2';

package/src/middleware/logging.ts

@@ -12,7 +12,7 @@ export interface Logger {
 
 const defaultLogger: Logger = {
   info(message: string, extra?: Record<string, unknown>) {
-    console.log(message, extra ?? '');
+    console.info(message, extra ?? '');
   },
   error(message: string, extra?: Record<string, unknown>) {
     console.error(message, extra ?? '');

package/src/middleware/manager.ts

@@ -95,8 +95,8 @@ export class MiddlewareManager {
         if (result !== null) {
           return result;
         }
-      } catch {
-        // Swallow errors in onError handlers
+      } catch (e) {
+        console.warn('[apcore:middleware] Error in onError handler, continuing:', e);
         continue;
       }
     }

package/src/observability/tracing.ts

@@ -45,7 +45,7 @@ export interface SpanExporter {
 
 export class StdoutExporter implements SpanExporter {
   export(span: Span): void {
-    console.log(JSON.stringify(span));
+    process.stdout.write(JSON.stringify(span) + '\n');
   }
 }