apcore-js 0.1.0

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * apcore - Schema-driven module development framework.
+ */
+
+// Core
+export { Context, createIdentity } from './context.js';
+export type { Identity } from './context.js';
+export { Registry } from './registry/registry.js';
+export { Executor, redactSensitive, REDACTED_VALUE } from './executor.js';
+
+// Module types
+export { DEFAULT_ANNOTATIONS } from './module.js';
+export type { ModuleAnnotations, ModuleExample, ValidationResult, Module } from './module.js';
+
+// Config
+export { Config } from './config.js';
+
+// Errors
+export {
+  ModuleError,
+  ConfigNotFoundError,
+  ConfigError,
+  ACLRuleError,
+  ACLDeniedError,
+  ModuleNotFoundError,
+  ModuleTimeoutError,
+  SchemaValidationError,
+  SchemaNotFoundError,
+  SchemaParseError,
+  SchemaCircularRefError,
+  CallDepthExceededError,
+  CircularCallError,
+  CallFrequencyExceededError,
+  InvalidInputError,
+  FuncMissingTypeHintError,
+  FuncMissingReturnTypeError,
+  BindingInvalidTargetError,
+  BindingModuleNotFoundError,
+  BindingCallableNotFoundError,
+  BindingNotCallableError,
+  BindingSchemaMissingError,
+  BindingFileInvalidError,
+  CircularDependencyError,
+  ModuleLoadError,
+} from './errors.js';
+
+// ACL
+export { ACL } from './acl.js';
+export type { ACLRule } from './acl.js';
+
+// Middleware
+export { Middleware, MiddlewareManager, MiddlewareChainError, BeforeMiddleware, AfterMiddleware, LoggingMiddleware } from './middleware/index.js';
+
+// Decorator
+export { module, FunctionModule, normalizeResult, makeAutoId } from './decorator.js';
+
+// Bindings
+export { BindingLoader } from './bindings.js';
+
+// Utils
+export { matchPattern } from './utils/pattern.js';
+
+// Schema
+export { SchemaLoader, jsonSchemaToTypeBox } from './schema/loader.js';
+export { SchemaValidator } from './schema/validator.js';
+export { SchemaExporter } from './schema/exporter.js';
+export { SchemaStrategy, ExportProfile } from './schema/types.js';
+export type { SchemaDefinition, ResolvedSchema, SchemaValidationErrorDetail, SchemaValidationResult } from './schema/types.js';
+export { RefResolver } from './schema/ref-resolver.js';
+export { toStrictSchema, applyLlmDescriptions, stripExtensions } from './schema/strict.js';
+
+// Registry types
+export type { ModuleDescriptor, DiscoveredModule, DependencyInfo } from './registry/types.js';
+
+// Observability
+export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './observability/tracing.js';
+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';

package/src/middleware/adapters.ts

@@ -0,0 +1,54 @@
+/**
+ * Function adapter classes for the middleware system.
+ */
+
+import type { Context } from '../context.js';
+import { Middleware } from './base.js';
+
+export type BeforeCallback = (
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  context: Context,
+) => Record<string, unknown> | null;
+
+export type AfterCallback = (
+  moduleId: string,
+  inputs: Record<string, unknown>,
+  output: Record<string, unknown>,
+  context: Context,
+) => Record<string, unknown> | null;
+
+export class BeforeMiddleware extends Middleware {
+  private _callback: BeforeCallback;
+
+  constructor(callback: BeforeCallback) {
+    super();
+    this._callback = callback;
+  }
+
+  override before(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context,
+  ): Record<string, unknown> | null {
+    return this._callback(moduleId, inputs, context);
+  }
+}
+
+export class AfterMiddleware extends Middleware {
+  private _callback: AfterCallback;
+
+  constructor(callback: AfterCallback) {
+    super();
+    this._callback = callback;
+  }
+
+  override after(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+    context: Context,
+  ): Record<string, unknown> | null {
+    return this._callback(moduleId, inputs, output, context);
+  }
+}

package/src/middleware/base.ts

@@ -0,0 +1,33 @@
+/**
+ * Middleware base class for apcore.
+ */
+
+import type { Context } from '../context.js';
+
+export class Middleware {
+  before(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+
+  after(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _output: Record<string, unknown>,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+
+  onError(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    _error: Error,
+    _context: Context,
+  ): Record<string, unknown> | null {
+    return null;
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,6 @@
+export { Middleware } from './base.js';
+export { MiddlewareManager, MiddlewareChainError } from './manager.js';
+export { BeforeMiddleware, AfterMiddleware } from './adapters.js';
+export type { BeforeCallback, AfterCallback } from './adapters.js';
+export { LoggingMiddleware } from './logging.js';
+export type { Logger } from './logging.js';

package/src/middleware/logging.ts

@@ -0,0 +1,103 @@
+/**
+ * LoggingMiddleware for structured module call logging.
+ */
+
+import type { Context } from '../context.js';
+import { Middleware } from './base.js';
+
+export interface Logger {
+  info(message: string, extra?: Record<string, unknown>): void;
+  error(message: string, extra?: Record<string, unknown>): void;
+}
+
+const defaultLogger: Logger = {
+  info(message: string, extra?: Record<string, unknown>) {
+    console.log(message, extra ?? '');
+  },
+  error(message: string, extra?: Record<string, unknown>) {
+    console.error(message, extra ?? '');
+  },
+};
+
+export class LoggingMiddleware extends Middleware {
+  private _logger: Logger;
+  private _logInputs: boolean;
+  private _logOutputs: boolean;
+  private _logErrors: boolean;
+
+  constructor(options?: {
+    logger?: Logger;
+    logInputs?: boolean;
+    logOutputs?: boolean;
+    logErrors?: boolean;
+  }) {
+    super();
+    this._logger = options?.logger ?? defaultLogger;
+    this._logInputs = options?.logInputs ?? true;
+    this._logOutputs = options?.logOutputs ?? true;
+    this._logErrors = options?.logErrors ?? true;
+  }
+
+  override before(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context,
+  ): null {
+    context.data['_logging_mw_start'] = performance.now();
+
+    if (this._logInputs) {
+      const redacted = context.redactedInputs ?? inputs;
+      this._logger.info(`[${context.traceId}] START ${moduleId}`, {
+        traceId: context.traceId,
+        moduleId,
+        callerId: context.callerId,
+        inputs: redacted,
+      });
+    }
+
+    return null;
+  }
+
+  override after(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const startTime = (context.data['_logging_mw_start'] as number) ?? performance.now();
+    const durationMs = performance.now() - startTime;
+
+    if (this._logOutputs) {
+      this._logger.info(
+        `[${context.traceId}] END ${moduleId} (${durationMs.toFixed(2)}ms)`,
+        {
+          traceId: context.traceId,
+          moduleId,
+          durationMs,
+          output,
+        },
+      );
+    }
+
+    return null;
+  }
+
+  override onError(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    error: Error,
+    context: Context,
+  ): null {
+    if (this._logErrors) {
+      const redacted = context.redactedInputs ?? inputs;
+      this._logger.error(`[${context.traceId}] ERROR ${moduleId}: ${error}`, {
+        traceId: context.traceId,
+        moduleId,
+        error: String(error),
+        inputs: redacted,
+      });
+    }
+
+    return null;
+  }
+}

package/src/middleware/manager.ts

@@ -0,0 +1,105 @@
+/**
+ * MiddlewareManager -- onion model execution engine for the middleware pipeline.
+ */
+
+import type { Context } from '../context.js';
+import { ModuleError } from '../errors.js';
+import { Middleware } from './base.js';
+
+export class MiddlewareChainError extends ModuleError {
+  readonly original: Error;
+  readonly executedMiddlewares: Middleware[];
+
+  constructor(original: Error, executedMiddlewares: Middleware[]) {
+    super('MIDDLEWARE_CHAIN_ERROR', String(original));
+    this.name = 'MiddlewareChainError';
+    this.original = original;
+    this.executedMiddlewares = executedMiddlewares;
+  }
+}
+
+export class MiddlewareManager {
+  private _middlewares: Middleware[] = [];
+
+  add(middleware: Middleware): void {
+    this._middlewares.push(middleware);
+  }
+
+  remove(middleware: Middleware): boolean {
+    for (let i = 0; i < this._middlewares.length; i++) {
+      if (this._middlewares[i] === middleware) {
+        this._middlewares.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  snapshot(): Middleware[] {
+    return [...this._middlewares];
+  }
+
+  executeBefore(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context,
+  ): [Record<string, unknown>, Middleware[]] {
+    let currentInputs = inputs;
+    const executedMiddlewares: Middleware[] = [];
+    const middlewares = this.snapshot();
+
+    for (const mw of middlewares) {
+      executedMiddlewares.push(mw);
+      try {
+        const result = mw.before(moduleId, currentInputs, context);
+        if (result !== null) {
+          currentInputs = result;
+        }
+      } catch (e) {
+        throw new MiddlewareChainError(e as Error, executedMiddlewares);
+      }
+    }
+
+    return [currentInputs, executedMiddlewares];
+  }
+
+  executeAfter(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+    context: Context,
+  ): Record<string, unknown> {
+    let currentOutput = output;
+    const middlewares = this.snapshot();
+
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+      const result = middlewares[i].after(moduleId, inputs, currentOutput, context);
+      if (result !== null) {
+        currentOutput = result;
+      }
+    }
+
+    return currentOutput;
+  }
+
+  executeOnError(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    error: Error,
+    context: Context,
+    executedMiddlewares: Middleware[],
+  ): Record<string, unknown> | null {
+    for (let i = executedMiddlewares.length - 1; i >= 0; i--) {
+      try {
+        const result = executedMiddlewares[i].onError(moduleId, inputs, error, context);
+        if (result !== null) {
+          return result;
+        }
+      } catch {
+        // Swallow errors in onError handlers
+        continue;
+      }
+    }
+    return null;
+  }
+}

package/src/module.ts

@@ -0,0 +1,41 @@
+/**
+ * Module interface and related data types.
+ */
+
+import type { TSchema } from '@sinclair/typebox';
+import type { Context } from './context.js';
+
+export interface ModuleAnnotations {
+  readonly readonly: boolean;
+  readonly destructive: boolean;
+  readonly idempotent: boolean;
+  readonly requiresApproval: boolean;
+  readonly openWorld: boolean;
+}
+
+export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
+  readonly: false,
+  destructive: false,
+  idempotent: false,
+  requiresApproval: false,
+  openWorld: true,
+});
+
+export interface ModuleExample {
+  title: string;
+  inputs: Record<string, unknown>;
+  output: Record<string, unknown>;
+  description?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: Array<Record<string, string>>;
+}
+
+export interface Module {
+  inputSchema: TSchema;
+  outputSchema: TSchema;
+  description: string;
+  execute(inputs: Record<string, unknown>, context: Context): Promise<Record<string, unknown>> | Record<string, unknown>;
+}

package/src/observability/context-logger.ts

@@ -0,0 +1,201 @@
+/**
+ * Structured logging: ContextLogger and ObsLoggingMiddleware.
+ */
+
+import type { Context } from '../context.js';
+import { Middleware } from '../middleware/base.js';
+
+const LEVELS: Record<string, number> = {
+  trace: 0,
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50,
+};
+
+const REDACTED = '***REDACTED***';
+
+interface WritableOutput {
+  write(s: string): void;
+}
+
+export class ContextLogger {
+  private _name: string;
+  private _format: string;
+  private _level: string;
+  private _levelValue: number;
+  private _redactSensitive: boolean;
+  private _output: WritableOutput;
+  private _traceId: string | null = null;
+  private _moduleId: string | null = null;
+  private _callerId: string | null = null;
+
+  constructor(options?: {
+    name?: string;
+    format?: string;
+    level?: string;
+    redactSensitive?: boolean;
+    output?: WritableOutput;
+  }) {
+    this._name = options?.name ?? 'apcore';
+    this._format = options?.format ?? 'json';
+    this._level = options?.level ?? 'info';
+    this._levelValue = LEVELS[this._level] ?? 20;
+    this._redactSensitive = options?.redactSensitive ?? true;
+    this._output = options?.output ?? { write: (s: string) => process.stderr.write(s) };
+  }
+
+  static fromContext(context: Context, name: string, options?: {
+    format?: string;
+    level?: string;
+    redactSensitive?: boolean;
+    output?: WritableOutput;
+  }): ContextLogger {
+    const logger = new ContextLogger({ name, ...options });
+    logger._traceId = context.traceId;
+    logger._moduleId = context.callChain.length > 0 ? context.callChain[context.callChain.length - 1] : null;
+    logger._callerId = context.callerId;
+    return logger;
+  }
+
+  private _emit(levelName: string, message: string, extra?: Record<string, unknown> | null): void {
+    const levelValue = LEVELS[levelName] ?? 20;
+    if (levelValue < this._levelValue) return;
+
+    let redactedExtra = extra ?? null;
+    if (extra != null && this._redactSensitive) {
+      redactedExtra = {};
+      for (const [k, v] of Object.entries(extra)) {
+        (redactedExtra as Record<string, unknown>)[k] = k.startsWith('_secret_') ? REDACTED : v;
+      }
+    }
+
+    const now = new Date();
+    const entry: Record<string, unknown> = {
+      timestamp: now.toISOString(),
+      level: levelName,
+      message,
+      trace_id: this._traceId,
+      module_id: this._moduleId,
+      caller_id: this._callerId,
+      logger: this._name,
+      extra: redactedExtra,
+    };
+
+    if (this._format === 'json') {
+      this._output.write(JSON.stringify(entry) + '\n');
+    } else {
+      const ts = now.toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
+      const lvl = levelName.toUpperCase();
+      const trace = this._traceId ?? 'none';
+      const mod = this._moduleId ?? 'none';
+      let extrasStr = '';
+      if (redactedExtra) {
+        extrasStr = ' ' + Object.entries(redactedExtra).map(([k, v]) => `${k}=${v}`).join(' ');
+      }
+      this._output.write(`${ts} [${lvl}] [trace=${trace}] [module=${mod}] ${message}${extrasStr}\n`);
+    }
+  }
+
+  trace(message: string, extra?: Record<string, unknown>): void {
+    this._emit('trace', message, extra);
+  }
+
+  debug(message: string, extra?: Record<string, unknown>): void {
+    this._emit('debug', message, extra);
+  }
+
+  info(message: string, extra?: Record<string, unknown>): void {
+    this._emit('info', message, extra);
+  }
+
+  warn(message: string, extra?: Record<string, unknown>): void {
+    this._emit('warn', message, extra);
+  }
+
+  error(message: string, extra?: Record<string, unknown>): void {
+    this._emit('error', message, extra);
+  }
+
+  fatal(message: string, extra?: Record<string, unknown>): void {
+    this._emit('fatal', message, extra);
+  }
+}
+
+export class ObsLoggingMiddleware extends Middleware {
+  private _logger: ContextLogger;
+  private _logInputs: boolean;
+  private _logOutputs: boolean;
+
+  constructor(options?: {
+    logger?: ContextLogger;
+    logInputs?: boolean;
+    logOutputs?: boolean;
+  }) {
+    super();
+    this._logger = options?.logger ?? new ContextLogger({ name: 'apcore.obs_logging' });
+    this._logInputs = options?.logInputs ?? true;
+    this._logOutputs = options?.logOutputs ?? true;
+  }
+
+  override before(
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const starts = (context.data['_obs_logging_starts'] as number[]) ?? [];
+    starts.push(performance.now());
+    context.data['_obs_logging_starts'] = starts;
+
+    const extra: Record<string, unknown> = {
+      module_id: moduleId,
+      caller_id: context.callerId,
+    };
+    if (this._logInputs) {
+      extra['inputs'] = context.redactedInputs ?? inputs;
+    }
+    this._logger.info('Module call started', extra);
+    return null;
+  }
+
+  override after(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    output: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const starts = context.data['_obs_logging_starts'] as number[];
+    const startTime = starts.pop()!;
+    const durationMs = performance.now() - startTime;
+
+    const extra: Record<string, unknown> = {
+      module_id: moduleId,
+      duration_ms: durationMs,
+    };
+    if (this._logOutputs) {
+      extra['output'] = output;
+    }
+    this._logger.info('Module call completed', extra);
+    return null;
+  }
+
+  override onError(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    error: Error,
+    context: Context,
+  ): null {
+    const starts = context.data['_obs_logging_starts'] as number[];
+    const startTime = starts.pop()!;
+    const durationMs = performance.now() - startTime;
+
+    this._logger.error('Module call failed', {
+      module_id: moduleId,
+      duration_ms: durationMs,
+      error_type: error.constructor.name,
+      error_message: String(error),
+    });
+    return null;
+  }
+}

package/src/observability/index.ts

@@ -0,0 +1,4 @@
+export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './tracing.js';
+export type { Span, SpanExporter } from './tracing.js';
+export { MetricsCollector, MetricsMiddleware } from './metrics.js';
+export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';