apcore-js 0.1.0

package/src/observability/metrics.ts

@@ -0,0 +1,212 @@
+/**
+ * In-memory metrics collection with Prometheus export.
+ */
+
+import type { Context } from '../context.js';
+import { ModuleError } from '../errors.js';
+import { Middleware } from '../middleware/base.js';
+
+const DESCRIPTIONS: Record<string, string> = {
+  apcore_module_calls_total: 'Total module calls',
+  apcore_module_errors_total: 'Total module errors',
+  apcore_module_duration_seconds: 'Module execution duration',
+};
+
+function labelsKey(labels: Record<string, string>): string {
+  return Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(',');
+}
+
+export class MetricsCollector {
+  static readonly DEFAULT_BUCKETS: number[] = [
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
+  ];
+
+  private _buckets: number[];
+  private _counters: Map<string, number> = new Map();
+  private _histogramSums: Map<string, number> = new Map();
+  private _histogramCounts: Map<string, number> = new Map();
+  private _histogramBuckets: Map<string, number> = new Map();
+
+  constructor(buckets?: number[]) {
+    this._buckets = buckets ? [...buckets].sort((a, b) => a - b) : [...MetricsCollector.DEFAULT_BUCKETS];
+  }
+
+  increment(name: string, labels: Record<string, string>, amount: number = 1): void {
+    const key = `${name}|${labelsKey(labels)}`;
+    this._counters.set(key, (this._counters.get(key) ?? 0) + amount);
+  }
+
+  observe(name: string, labels: Record<string, string>, value: number): void {
+    const lk = labelsKey(labels);
+    const key = `${name}|${lk}`;
+
+    this._histogramSums.set(key, (this._histogramSums.get(key) ?? 0) + value);
+    this._histogramCounts.set(key, (this._histogramCounts.get(key) ?? 0) + 1);
+
+    for (const b of this._buckets) {
+      if (value <= b) {
+        const bkey = `${name}|${lk}|${b}`;
+        this._histogramBuckets.set(bkey, (this._histogramBuckets.get(bkey) ?? 0) + 1);
+      }
+    }
+    // +Inf bucket
+    const infKey = `${name}|${lk}|Inf`;
+    this._histogramBuckets.set(infKey, (this._histogramBuckets.get(infKey) ?? 0) + 1);
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {
+      counters: Object.fromEntries(this._counters),
+      histograms: {
+        sums: Object.fromEntries(this._histogramSums),
+        counts: Object.fromEntries(this._histogramCounts),
+        buckets: Object.fromEntries(this._histogramBuckets),
+      },
+    };
+  }
+
+  reset(): void {
+    this._counters.clear();
+    this._histogramSums.clear();
+    this._histogramCounts.clear();
+    this._histogramBuckets.clear();
+  }
+
+  exportPrometheus(): string {
+    const lines: string[] = [];
+    const counterNames = new Set<string>();
+    const histNames = new Set<string>();
+
+    // Counters
+    for (const [compositeKey, value] of [...this._counters.entries()].sort()) {
+      const [name, lk] = compositeKey.split('|', 2);
+      if (!counterNames.has(name)) {
+        const desc = DESCRIPTIONS[name] ?? name;
+        lines.push(`# HELP ${name} ${desc}`);
+        lines.push(`# TYPE ${name} counter`);
+        counterNames.add(name);
+      }
+      const labelsStr = formatLabels(parseLabels(lk));
+      lines.push(`${name}${labelsStr} ${value}`);
+    }
+
+    // Histograms
+    const histKeys = [...this._histogramSums.keys()].sort();
+    for (const compositeKey of histKeys) {
+      const [name, lk] = compositeKey.split('|', 2);
+      if (!histNames.has(name)) {
+        const desc = DESCRIPTIONS[name] ?? name;
+        lines.push(`# HELP ${name} ${desc}`);
+        lines.push(`# TYPE ${name} histogram`);
+        histNames.add(name);
+      }
+
+      const labelsDict = parseLabels(lk);
+      const labelsStr = formatLabels(labelsDict);
+
+      for (const b of this._buckets) {
+        const bkey = `${name}|${lk}|${b}`;
+        const count = this._histogramBuckets.get(bkey) ?? 0;
+        const leStr = String(b);
+        const leLabels = { ...labelsDict, le: leStr };
+        lines.push(`${name}_bucket${formatLabels(leLabels)} ${count}`);
+      }
+
+      const infKey = `${name}|${lk}|Inf`;
+      const infCount = this._histogramBuckets.get(infKey) ?? 0;
+      const infLabels = { ...labelsDict, le: '+Inf' };
+      lines.push(`${name}_bucket${formatLabels(infLabels)} ${infCount}`);
+
+      const sumVal = this._histogramSums.get(compositeKey) ?? 0;
+      const countVal = this._histogramCounts.get(compositeKey) ?? 0;
+      lines.push(`${name}_sum${labelsStr} ${sumVal}`);
+      lines.push(`${name}_count${labelsStr} ${countVal}`);
+    }
+
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+  }
+
+  incrementCalls(moduleId: string, status: string): void {
+    this.increment('apcore_module_calls_total', { module_id: moduleId, status });
+  }
+
+  incrementErrors(moduleId: string, errorCode: string): void {
+    this.increment('apcore_module_errors_total', { module_id: moduleId, error_code: errorCode });
+  }
+
+  observeDuration(moduleId: string, durationSeconds: number): void {
+    this.observe('apcore_module_duration_seconds', { module_id: moduleId }, durationSeconds);
+  }
+}
+
+function parseLabels(lk: string): Record<string, string> {
+  if (!lk) return {};
+  const result: Record<string, string> = {};
+  for (const pair of lk.split(',')) {
+    const [k, v] = pair.split('=', 2);
+    if (k) result[k] = v ?? '';
+  }
+  return result;
+}
+
+function formatLabels(labels: Record<string, string>): string {
+  const entries = Object.entries(labels);
+  if (entries.length === 0) return '';
+  const sorted = entries.sort(([a], [b]) => {
+    if (a === 'le') return 1;
+    if (b === 'le') return -1;
+    return a.localeCompare(b);
+  });
+  const pairs = sorted.map(([k, v]) => `${k}="${v}"`).join(',');
+  return `{${pairs}}`;
+}
+
+export class MetricsMiddleware extends Middleware {
+  private _collector: MetricsCollector;
+
+  constructor(collector: MetricsCollector) {
+    super();
+    this._collector = collector;
+  }
+
+  override before(
+    _moduleId: string,
+    _inputs: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const starts = (context.data['_metrics_starts'] as number[]) ?? [];
+    starts.push(performance.now());
+    context.data['_metrics_starts'] = starts;
+    return null;
+  }
+
+  override after(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    _output: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const starts = context.data['_metrics_starts'] as number[];
+    const startTime = starts.pop()!;
+    const durationS = (performance.now() - startTime) / 1000;
+    this._collector.incrementCalls(moduleId, 'success');
+    this._collector.observeDuration(moduleId, durationS);
+    return null;
+  }
+
+  override onError(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    error: Error,
+    context: Context,
+  ): null {
+    const starts = context.data['_metrics_starts'] as number[];
+    const startTime = starts.pop()!;
+    const durationS = (performance.now() - startTime) / 1000;
+    const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;
+    this._collector.incrementCalls(moduleId, 'error');
+    this._collector.incrementErrors(moduleId, errorCode);
+    this._collector.observeDuration(moduleId, durationS);
+    return null;
+  }
+}

package/src/observability/tracing.ts

@@ -0,0 +1,187 @@
+/**
+ * Tracing system: Span, SpanExporter implementations, and TracingMiddleware.
+ */
+
+import { randomBytes } from 'node:crypto';
+import type { Context } from '../context.js';
+import { Middleware } from '../middleware/base.js';
+
+export interface Span {
+  traceId: string;
+  name: string;
+  startTime: number;
+  spanId: string;
+  parentSpanId: string | null;
+  attributes: Record<string, unknown>;
+  endTime: number | null;
+  status: string;
+  events: Array<Record<string, unknown>>;
+}
+
+export function createSpan(options: {
+  traceId: string;
+  name: string;
+  startTime: number;
+  spanId?: string;
+  parentSpanId?: string | null;
+  attributes?: Record<string, unknown>;
+}): Span {
+  return {
+    traceId: options.traceId,
+    name: options.name,
+    startTime: options.startTime,
+    spanId: options.spanId ?? randomBytes(8).toString('hex'),
+    parentSpanId: options.parentSpanId ?? null,
+    attributes: options.attributes ?? {},
+    endTime: null,
+    status: 'ok',
+    events: [],
+  };
+}
+
+export interface SpanExporter {
+  export(span: Span): void;
+}
+
+export class StdoutExporter implements SpanExporter {
+  export(span: Span): void {
+    console.log(JSON.stringify(span));
+  }
+}
+
+export class InMemoryExporter implements SpanExporter {
+  private _spans: Span[] = [];
+  private _maxSpans: number;
+
+  constructor(maxSpans: number = 10_000) {
+    this._maxSpans = maxSpans;
+  }
+
+  export(span: Span): void {
+    this._spans.push(span);
+    while (this._spans.length > this._maxSpans) {
+      this._spans.shift();
+    }
+  }
+
+  getSpans(): Span[] {
+    return [...this._spans];
+  }
+
+  clear(): void {
+    this._spans = [];
+  }
+}
+
+const VALID_STRATEGIES = new Set(['full', 'proportional', 'error_first', 'off']);
+
+export class TracingMiddleware extends Middleware {
+  private _exporter: SpanExporter;
+  private _samplingRate: number;
+  private _samplingStrategy: string;
+
+  constructor(
+    exporter: SpanExporter,
+    samplingRate: number = 1.0,
+    samplingStrategy: string = 'full',
+  ) {
+    super();
+    if (samplingRate < 0.0 || samplingRate > 1.0) {
+      throw new Error(`sampling_rate must be between 0.0 and 1.0, got ${samplingRate}`);
+    }
+    if (!VALID_STRATEGIES.has(samplingStrategy)) {
+      throw new Error(`sampling_strategy must be one of ${[...VALID_STRATEGIES].join(', ')}, got '${samplingStrategy}'`);
+    }
+    this._exporter = exporter;
+    this._samplingRate = samplingRate;
+    this._samplingStrategy = samplingStrategy;
+  }
+
+  private _shouldSample(context: Context): boolean {
+    const existing = context.data['_tracing_sampled'];
+    if (typeof existing === 'boolean') return existing;
+
+    let decision: boolean;
+    if (this._samplingStrategy === 'full') {
+      decision = true;
+    } else if (this._samplingStrategy === 'off') {
+      decision = false;
+    } else {
+      decision = Math.random() < this._samplingRate;
+    }
+
+    context.data['_tracing_sampled'] = decision;
+    return decision;
+  }
+
+  override before(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    context: Context,
+  ): null {
+    this._shouldSample(context);
+
+    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
+    context.data['_tracing_spans'] = spansStack;
+    const parentSpanId = spansStack.length > 0 ? spansStack[spansStack.length - 1].spanId : null;
+
+    const span = createSpan({
+      traceId: context.traceId,
+      name: 'apcore.module.execute',
+      startTime: performance.now(),
+      parentSpanId,
+      attributes: {
+        moduleId,
+        method: 'execute',
+        callerId: context.callerId,
+      },
+    });
+    spansStack.push(span);
+    return null;
+  }
+
+  override after(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    _output: Record<string, unknown>,
+    context: Context,
+  ): null {
+    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
+    if (spansStack.length === 0) return null;
+
+    const span = spansStack.pop()!;
+    span.endTime = performance.now();
+    span.status = 'ok';
+    span.attributes['duration_ms'] = span.endTime - span.startTime;
+    span.attributes['success'] = true;
+
+    if (context.data['_tracing_sampled']) {
+      this._exporter.export(span);
+    }
+    return null;
+  }
+
+  override onError(
+    moduleId: string,
+    _inputs: Record<string, unknown>,
+    error: Error,
+    context: Context,
+  ): null {
+    const spansStack = (context.data['_tracing_spans'] as Span[]) ?? [];
+    if (spansStack.length === 0) return null;
+
+    const span = spansStack.pop()!;
+    span.endTime = performance.now();
+    span.status = 'error';
+    span.attributes['duration_ms'] = span.endTime - span.startTime;
+    span.attributes['success'] = false;
+    span.attributes['error_code'] = (error as unknown as Record<string, unknown>)['code'] ?? error.constructor.name;
+
+    const shouldExport =
+      this._samplingStrategy === 'error_first' || context.data['_tracing_sampled'];
+    if (shouldExport) {
+      this._exporter.export(span);
+    }
+    return null;
+  }
+}

package/src/registry/dependencies.ts

@@ -0,0 +1,99 @@
+/**
+ * Dependency resolution via Kahn's topological sort.
+ */
+
+import { CircularDependencyError, ModuleLoadError } from '../errors.js';
+import type { DependencyInfo } from './types.js';
+
+export function resolveDependencies(
+  modules: Array<[string, DependencyInfo[]]>,
+  knownIds?: Set<string> | null,
+): string[] {
+  if (modules.length === 0) return [];
+
+  const ids = knownIds ?? new Set(modules.map(([id]) => id));
+
+  // Build graph and in-degree
+  const graph = new Map<string, Set<string>>();
+  const inDegree = new Map<string, number>();
+
+  for (const [modId] of modules) {
+    inDegree.set(modId, 0);
+  }
+
+  for (const [moduleId, deps] of modules) {
+    for (const dep of deps) {
+      if (!ids.has(dep.moduleId)) {
+        if (dep.optional) continue;
+        throw new ModuleLoadError(moduleId, `Required dependency '${dep.moduleId}' not found`);
+      }
+      if (!graph.has(dep.moduleId)) graph.set(dep.moduleId, new Set());
+      graph.get(dep.moduleId)!.add(moduleId);
+      inDegree.set(moduleId, (inDegree.get(moduleId) ?? 0) + 1);
+    }
+  }
+
+  // Initialize queue with zero-in-degree nodes (sorted for determinism)
+  const queue: string[] = [...inDegree.entries()]
+    .filter(([, deg]) => deg === 0)
+    .map(([id]) => id)
+    .sort();
+
+  const loadOrder: string[] = [];
+  while (queue.length > 0) {
+    const modId = queue.shift()!;
+    loadOrder.push(modId);
+    const dependents = graph.get(modId);
+    if (dependents) {
+      for (const dependent of [...dependents].sort()) {
+        const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+        inDegree.set(dependent, newDeg);
+        if (newDeg === 0) {
+          queue.push(dependent);
+        }
+      }
+    }
+  }
+
+  // Check for cycles
+  if (loadOrder.length < modules.length) {
+    const ordered = new Set(loadOrder);
+    const remaining = new Set(modules.filter(([id]) => !ordered.has(id)).map(([id]) => id));
+    const cyclePath = extractCycle(modules, remaining);
+    throw new CircularDependencyError(cyclePath);
+  }
+
+  return loadOrder;
+}
+
+function extractCycle(
+  modules: Array<[string, DependencyInfo[]]>,
+  remaining: Set<string>,
+): string[] {
+  const depMap = new Map<string, string[]>();
+  for (const [modId, deps] of modules) {
+    if (remaining.has(modId)) {
+      depMap.set(modId, deps.filter((d) => remaining.has(d.moduleId)).map((d) => d.moduleId));
+    }
+  }
+
+  const start = remaining.values().next().value as string;
+  const visited: string[] = [start];
+  const visitedSet = new Set([start]);
+  let current = start;
+
+  while (true) {
+    const nexts = depMap.get(current) ?? [];
+    if (nexts.length === 0) break;
+    const nxt = nexts[0];
+    if (visitedSet.has(nxt)) {
+      const idx = visited.indexOf(nxt);
+      return [...visited.slice(idx), nxt];
+    }
+    visited.push(nxt);
+    visitedSet.add(nxt);
+    current = nxt;
+  }
+
+  return [...remaining, remaining.values().next().value as string];
+}

package/src/registry/entry-point.ts

@@ -0,0 +1,64 @@
+/**
+ * Entry point resolution for discovered module files.
+ */
+
+import { ModuleLoadError } from '../errors.js';
+import { validateModule } from './validation.js';
+
+export function snakeToPascal(name: string): string {
+  if (!name) return '';
+  return name.split('_').map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}
+
+function isModuleClass(obj: unknown): boolean {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const record = obj as Record<string, unknown>;
+  return (
+    record['inputSchema'] != null &&
+    typeof record['inputSchema'] === 'object' &&
+    record['outputSchema'] != null &&
+    typeof record['outputSchema'] === 'object' &&
+    typeof record['description'] === 'string' &&
+    typeof record['execute'] === 'function'
+  );
+}
+
+export async function resolveEntryPoint(
+  filePath: string,
+  meta?: Record<string, unknown> | null,
+): Promise<unknown> {
+  let loaded: Record<string, unknown>;
+  try {
+    loaded = await import(filePath);
+  } catch (e) {
+    throw new ModuleLoadError(filePath, `Failed to import module: ${e}`);
+  }
+
+  // Meta override mode
+  if (meta && 'entry_point' in meta) {
+    const className = (meta['entry_point'] as string).split(':').pop()!;
+    const cls = loaded[className];
+    if (cls == null) {
+      throw new ModuleLoadError(filePath, `Entry point class '${className}' not found`);
+    }
+    return cls;
+  }
+
+  // Auto-infer: look for default export first, then named exports
+  if (loaded['default'] && isModuleClass(loaded['default'])) {
+    return loaded['default'];
+  }
+
+  const candidates: unknown[] = [];
+  for (const [, value] of Object.entries(loaded)) {
+    if (isModuleClass(value)) {
+      candidates.push(value);
+    }
+  }
+
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) {
+    throw new ModuleLoadError(filePath, 'No Module subclass found in file');
+  }
+  throw new ModuleLoadError(filePath, 'Ambiguous entry point: multiple Module subclasses found');
+}

package/src/registry/index.ts

@@ -0,0 +1,8 @@
+export { Registry } from './registry.js';
+export type { ModuleDescriptor, DiscoveredModule, DependencyInfo } from './types.js';
+export { validateModule } from './validation.js';
+export { resolveDependencies } from './dependencies.js';
+export { scanExtensions, scanMultiRoot } from './scanner.js';
+export { resolveEntryPoint, snakeToPascal } from './entry-point.js';
+export { loadMetadata, parseDependencies, mergeModuleMetadata, loadIdMap } from './metadata.js';
+export { getSchema, exportSchema, getAllSchemas, exportAllSchemas } from './schema-export.js';

package/src/registry/metadata.ts

@@ -0,0 +1,111 @@
+/**
+ * Metadata and ID map loading for the registry system.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { ConfigError, ConfigNotFoundError } from '../errors.js';
+import type { DependencyInfo } from './types.js';
+
+export function loadMetadata(metaPath: string): Record<string, unknown> {
+  if (!existsSync(metaPath)) return {};
+
+  const content = readFileSync(metaPath, 'utf-8');
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(content);
+  } catch (e) {
+    throw new ConfigError(`Invalid YAML in metadata file: ${metaPath}`);
+  }
+
+  if (parsed === null || parsed === undefined) return {};
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new ConfigError(`Metadata file must be a YAML mapping: ${metaPath}`);
+  }
+
+  return parsed as Record<string, unknown>;
+}
+
+export function parseDependencies(depsRaw: Array<Record<string, unknown>>): DependencyInfo[] {
+  if (!depsRaw || depsRaw.length === 0) return [];
+
+  const result: DependencyInfo[] = [];
+  for (const dep of depsRaw) {
+    const moduleId = dep['module_id'] as string | undefined;
+    if (!moduleId) {
+      console.warn(`[apcore:metadata] Dependency entry missing 'module_id', skipping`);
+      continue;
+    }
+    result.push({
+      moduleId,
+      version: (dep['version'] as string) ?? null,
+      optional: (dep['optional'] as boolean) ?? false,
+    });
+  }
+  return result;
+}
+
+export function mergeModuleMetadata(
+  moduleObj: Record<string, unknown>,
+  meta: Record<string, unknown>,
+): Record<string, unknown> {
+  const codeDesc = (moduleObj['description'] as string) ?? '';
+  const codeName = (moduleObj['name'] as string) ?? null;
+  const codeTags = (moduleObj['tags'] as string[]) ?? [];
+  const codeVersion = (moduleObj['version'] as string) ?? '1.0.0';
+  const codeAnnotations = moduleObj['annotations'] ?? null;
+  const codeExamples = (moduleObj['examples'] as unknown[]) ?? [];
+  const codeMetadata = (moduleObj['metadata'] as Record<string, unknown>) ?? {};
+  const codeDocs = (moduleObj['documentation'] as string) ?? null;
+
+  const yamlMetadata = (meta['metadata'] as Record<string, unknown>) ?? {};
+  const mergedMetadata = { ...codeMetadata, ...yamlMetadata };
+
+  return {
+    description: (meta['description'] as string) || codeDesc,
+    name: (meta['name'] as string) || codeName,
+    tags: meta['tags'] != null ? meta['tags'] : codeTags || [],
+    version: (meta['version'] as string) || codeVersion,
+    annotations: meta['annotations'] != null ? meta['annotations'] : codeAnnotations,
+    examples: meta['examples'] != null ? meta['examples'] : codeExamples || [],
+    metadata: mergedMetadata,
+    documentation: (meta['documentation'] as string) || codeDocs,
+  };
+}
+
+export function loadIdMap(idMapPath: string): Record<string, Record<string, unknown>> {
+  if (!existsSync(idMapPath)) {
+    throw new ConfigNotFoundError(idMapPath);
+  }
+
+  const content = readFileSync(idMapPath, 'utf-8');
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(content);
+  } catch (e) {
+    throw new ConfigError(`Invalid YAML in ID map file: ${idMapPath}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || !('mappings' in (parsed as Record<string, unknown>))) {
+    throw new ConfigError("ID map must contain a 'mappings' list");
+  }
+
+  const mappings = (parsed as Record<string, unknown>)['mappings'];
+  if (!Array.isArray(mappings)) {
+    throw new ConfigError("ID map must contain a 'mappings' list");
+  }
+
+  const result: Record<string, Record<string, unknown>> = {};
+  for (const entry of mappings) {
+    const filePath = (entry as Record<string, unknown>)['file'] as string;
+    if (!filePath) {
+      console.warn(`[apcore:metadata] ID map entry missing 'file' field, skipping`);
+      continue;
+    }
+    result[filePath] = {
+      id: ((entry as Record<string, unknown>)['id'] as string) ?? filePath,
+      class: (entry as Record<string, unknown>)['class'] ?? null,
+    };
+  }
+  return result;
+}