apcore-js 0.1.0 → 0.1.2

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,44 @@ 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.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/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="./apcore-logo.svg" alt="apcore logo" width="200"/>
+  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-typescript/main/apcore-logo.svg" alt="apcore logo" width="200"/>
 </div>
 
 # apcore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,14 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aipartnerup/apcore-typescript.git"
+  },
+  "homepage": "https://github.com/aipartnerup",
+  "bugs": {
+    "url": "https://github.com/aipartnerup/apcore-typescript/issues"
+  },
   "license": "MIT",
   "dependencies": {
     "@sinclair/typebox": "^0.34.0",

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,

package/src/executor.ts

@@ -157,60 +157,85 @@ 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);
+  }
 
-    // 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 +251,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 +347,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

@@ -78,4 +78,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');
   }
 }