apcore-js 0.4.0 → 0.5.0

package/src/registry/registry.ts

@@ -2,7 +2,8 @@
  * Central module registry for discovering, registering, and querying modules.
  */
 
-import { resolve } from 'node:path';
+import { watch as fsWatch, accessSync } from 'node:fs';
+import { resolve, join, basename, extname } from 'node:path';
 import type { Config } from '../config.js';
 import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
 import type { ModuleAnnotations, ModuleExample } from '../module.js';
@@ -27,6 +28,30 @@ export const REGISTRY_EVENTS = Object.freeze({
  */
 export const MODULE_ID_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 
+/**
+ * Maximum allowed length for a module ID.
+ */
+export const MAX_MODULE_ID_LENGTH = 128;
+
+/**
+ * Reserved words that cannot appear as any segment of a module ID.
+ */
+export const RESERVED_WORDS = new Set(['system', 'internal', 'core', 'apcore', 'plugin', 'schema', 'acl']);
+
+/**
+ * Interface for custom module discovery.
+ */
+export interface Discoverer {
+  discover(roots: string[]): Array<{ moduleId: string; module: unknown }> | Promise<Array<{ moduleId: string; module: unknown }>>;
+}
+
+/**
+ * Interface for custom module validation.
+ */
+export interface ModuleValidator {
+  validate(module: unknown): string[] | Promise<string[]>;
+}
+
 type EventCallback = (moduleId: string, module: unknown) => void;
 
 export class Registry {
@@ -40,6 +65,10 @@ export class Registry {
   private _idMap: Record<string, Record<string, unknown>> = {};
   private _schemaCache: Map<string, Record<string, unknown>> = new Map();
   private _config: Config | null;
+  private _watchers?: Array<{ close(): void }>;
+  private _debounceTimers?: Map<string, number>;
+  private _customDiscoverer: Discoverer | null = null;
+  private _customValidator: ModuleValidator | null = null;
 
   constructor(options?: {
     config?: Config | null;
@@ -76,13 +105,58 @@ export class Registry {
     }
   }
 
+  setDiscoverer(discoverer: Discoverer): void {
+    this._customDiscoverer = discoverer;
+  }
+
+  setValidator(validator: ModuleValidator): void {
+    this._customValidator = validator;
+  }
+
   async discover(): Promise<number> {
+    if (this._customDiscoverer !== null) {
+      return this._discoverCustom();
+    }
+    return this._discoverDefault();
+  }
+
+  private async _discoverCustom(): Promise<number> {
+    const rootPaths = this._extensionRoots.map((r) => r['root'] as string);
+    const customModules = await this._customDiscoverer!.discover(rootPaths);
+
+    let count = 0;
+    for (const entry of customModules) {
+      const { moduleId, module: mod } = entry;
+
+      // Apply custom validator if set
+      if (this._customValidator !== null) {
+        const errors = await this._customValidator.validate(mod);
+        if (errors.length > 0) {
+          console.warn(
+            `[apcore:registry] Custom validator rejected module '${moduleId}': ${errors.join('; ')}`,
+          );
+          continue;
+        }
+      }
+
+      try {
+        this.register(moduleId, mod);
+        count++;
+      } catch (e) {
+        console.warn(`[apcore:registry] Failed to register custom-discovered module '${moduleId}':`, e);
+      }
+    }
+
+    return count;
+  }
+
+  private async _discoverDefault(): Promise<number> {
     const discovered = this._scanRoots();
     this._applyIdMapOverrides(discovered);
 
     const rawMetadata = this._loadAllMetadata(discovered);
     const resolvedModules = await this._resolveAllEntryPoints(discovered, rawMetadata);
-    const validModules = this._validateAll(resolvedModules);
+    const validModules = await this._validateAll(resolvedModules);
     const loadOrder = this._resolveLoadOrder(validModules, rawMetadata);
 
     return this._registerInOrder(loadOrder, validModules, rawMetadata);
@@ -152,10 +226,15 @@ export class Registry {
     return resolvedModules;
   }
 
-  private _validateAll(resolvedModules: Map<string, unknown>): Map<string, unknown> {
+  private async _validateAll(resolvedModules: Map<string, unknown>): Promise<Map<string, unknown>> {
     const validModules = new Map<string, unknown>();
     for (const [modId, mod] of resolvedModules) {
-      if (validateModule(mod).length === 0) {
+      if (this._customValidator !== null) {
+        const errors = await this._customValidator.validate(mod);
+        if (errors.length === 0) {
+          validModules.set(modId, mod);
+        }
+      } else if (validateModule(mod).length === 0) {
         validModules.set(modId, mod);
       }
     }
@@ -217,6 +296,16 @@ export class Registry {
       );
     }
 
+    const parts = moduleId.split('.');
+    for (const part of parts) {
+      if (RESERVED_WORDS.has(part)) {
+        throw new InvalidInputError(`Module ID contains reserved word: '${part}'`);
+      }
+    }
+    if (moduleId.length > MAX_MODULE_ID_LENGTH) {
+      throw new InvalidInputError(`Module ID exceeds maximum length of ${MAX_MODULE_ID_LENGTH}: ${moduleId.length}`);
+    }
+
     if (this._modules.has(moduleId)) {
       throw new InvalidInputError(`Module already exists: ${moduleId}`);
     }
@@ -333,6 +422,49 @@ export class Registry {
     };
   }
 
+  describe(moduleId: string): string {
+    const module = this.get(moduleId);
+    if (module === null) {
+      throw new ModuleNotFoundError(moduleId);
+    }
+
+    // Check for custom describe method
+    const modObj = module as Record<string, unknown>;
+    if (typeof modObj['describe'] === 'function') {
+      return (modObj['describe'] as () => string)();
+    }
+
+    // Auto-generate from descriptor
+    const descriptor = this.getDefinition(moduleId);
+    if (descriptor === null) {
+      return `Module: ${moduleId}\n\nNo description available.`;
+    }
+
+    const lines: string[] = [`# ${descriptor.moduleId}`];
+    if (descriptor.description) {
+      lines.push(`\n${descriptor.description}`);
+    }
+    if (descriptor.tags.length > 0) {
+      lines.push(`\n**Tags:** ${descriptor.tags.join(', ')}`);
+    }
+    const props = descriptor.inputSchema['properties'] as Record<string, Record<string, unknown>> | undefined;
+    if (props && Object.keys(props).length > 0) {
+      lines.push('\n**Parameters:**');
+      const requiredFields = (descriptor.inputSchema['required'] as string[]) ?? [];
+      for (const [param, schema] of Object.entries(props)) {
+        const paramType = (schema['type'] as string) ?? 'any';
+        const paramDesc = (schema['description'] as string) ?? '';
+        const isRequired = requiredFields.includes(param);
+        const reqMarker = isRequired ? ' (required)' : '';
+        lines.push(`- \`${param}\` (${paramType})${reqMarker}: ${paramDesc}`);
+      }
+    }
+    if (descriptor.documentation) {
+      lines.push(`\n**Documentation:**\n${descriptor.documentation}`);
+    }
+    return lines.join('\n');
+  }
+
   on(event: string, callback: EventCallback): void {
     const validEvents = Object.values(REGISTRY_EVENTS) as string[];
     if (!validEvents.includes(event)) {
@@ -354,6 +486,94 @@ export class Registry {
     }
   }
 
+  watch(): void {
+    if (this._watchers && this._watchers.length > 0) {
+      return; // Already watching
+    }
+
+    this._watchers = [];
+    this._debounceTimers = new Map<string, number>();
+
+    for (const root of this._extensionRoots) {
+      const rootPath = typeof root === "string" ? root : (root as Record<string, unknown>).root as string;
+      if (!rootPath) continue;
+
+      try {
+        const watcher = fsWatch(rootPath, { recursive: true }, (eventType: string, filename: string | null) => {
+          if (!filename) return;
+          if (!filename.endsWith(".ts") && !filename.endsWith(".js")) return;
+
+          const fullPath = join(rootPath, filename);
+          const now = Date.now();
+          const last = this._debounceTimers?.get(fullPath) ?? 0;
+          if (now - last < 300) return;
+          this._debounceTimers?.set(fullPath, now);
+
+          if (eventType === "rename") {
+            // Could be create or delete
+            try {
+              accessSync(fullPath);
+              this._handleFileChange(fullPath);
+            } catch {
+              this._handleFileDeletion(fullPath);
+            }
+          } else {
+            this._handleFileChange(fullPath);
+          }
+        });
+        this._watchers.push(watcher);
+      } catch {
+        // Skip directories that don't exist
+      }
+    }
+  }
+
+  unwatch(): void {
+    if (this._watchers) {
+      for (const watcher of this._watchers) {
+        watcher.close();
+      }
+      this._watchers = [];
+    }
+    this._debounceTimers = undefined;
+  }
+
+  private _handleFileChange(filePath: string): void {
+    const moduleId = this._pathToModuleId(filePath);
+
+    if (moduleId && this.has(moduleId)) {
+      const oldModule = this.get(moduleId) as Record<string, unknown> | null;
+      if (oldModule && typeof oldModule.onUnload === "function") {
+        try { oldModule.onUnload(); } catch { /* ignore */ }
+      }
+      this.unregister(moduleId);
+    }
+
+    // Re-import is complex in ES modules - emit event for user to handle
+    this._triggerEvent("register", moduleId ?? basename(filePath, extname(filePath)), null);
+  }
+
+  private _handleFileDeletion(path: string): void {
+    const moduleId = this._pathToModuleId(path);
+    if (moduleId && this.has(moduleId)) {
+      const module = this.get(moduleId) as Record<string, unknown> | null;
+      if (module && typeof module.onUnload === "function") {
+        try { module.onUnload(); } catch { /* ignore */ }
+      }
+      this.unregister(moduleId);
+    }
+  }
+
+  private _pathToModuleId(filePath: string): string | null {
+    const base = basename(filePath, extname(filePath));
+    for (const mid of this.moduleIds) {
+      if (mid.endsWith(base) || mid === base) {
+        return mid;
+      }
+    }
+    return null;
+  }
+
   clearCache(): void {
     this._schemaCache.clear();
   }

package/src/trace-context.ts

@@ -0,0 +1,102 @@
+/**
+ * W3C Trace Context support: TraceParent parsing and TraceContext injection/extraction.
+ */
+
+import { randomBytes } from 'node:crypto';
+import type { Context } from './context.js';
+import type { Span } from './observability/tracing.js';
+
+const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+export interface TraceParent {
+  readonly version: string;   // "00"
+  readonly traceId: string;   // 32 lowercase hex chars
+  readonly parentId: string;  // 16 lowercase hex chars
+  readonly traceFlags: string; // "01" (sampled) or "00"
+}
+
+export class TraceContext {
+  /**
+   * Build a traceparent header dict from an apcore Context.
+   *
+   * Converts `context.traceId` (UUID with dashes) to the 32-hex
+   * format required by the W3C traceparent spec. Uses the last span's
+   * `spanId` from the tracing stack if available, otherwise generates
+   * a random 16-hex parent id.
+   */
+  static inject(context: Context): Record<string, string> {
+    const traceIdHex = context.traceId.replace(/-/g, '');
+
+    const spansStack = context.data['_tracing_spans'] as Span[] | undefined;
+    let parentId: string;
+    if (spansStack && spansStack.length > 0) {
+      parentId = spansStack[spansStack.length - 1].spanId;
+    } else {
+      parentId = randomBytes(8).toString('hex');
+    }
+
+    const traceparent = `00-${traceIdHex}-${parentId}-01`;
+    return { traceparent };
+  }
+
+  /**
+   * Parse the `traceparent` header from the given headers object.
+   *
+   * Returns `null` if the header is missing or malformed.
+   */
+  static extract(headers: Record<string, string>): TraceParent | null {
+    const raw = headers['traceparent'];
+    if (raw === undefined) {
+      return null;
+    }
+    const match = TRACEPARENT_RE.exec(raw.trim().toLowerCase());
+    if (match === null) {
+      return null;
+    }
+    const version = match[1];
+    const traceId = match[2];
+    const parentId = match[3];
+    if (version === 'ff') {
+      return null;
+    }
+    if (traceId === '0'.repeat(32) || parentId === '0'.repeat(16)) {
+      return null;
+    }
+    return Object.freeze({
+      version,
+      traceId,
+      parentId,
+      traceFlags: match[4],
+    });
+  }
+
+  /**
+   * Strictly parse a traceparent string, throwing on invalid format.
+   *
+   * @throws {Error} If the traceparent does not match the expected
+   *   `00-<32 hex>-<16 hex>-<2 hex>` format.
+   */
+  static fromTraceparent(traceparent: string): TraceParent {
+    const match = TRACEPARENT_RE.exec(traceparent.trim().toLowerCase());
+    if (match === null) {
+      throw new Error(
+        `Malformed traceparent: ${JSON.stringify(traceparent.slice(0, 100))}. Expected format: 00-<32 hex>-<16 hex>-<2 hex>`,
+      );
+    }
+    const version = match[1];
+    const traceId = match[2];
+    const parentId = match[3];
+    if (version === 'ff') {
+      throw new Error('Invalid traceparent: version ff is not allowed');
+    }
+    if (traceId === '0'.repeat(32) || parentId === '0'.repeat(16)) {
+      throw new Error('Invalid traceparent: all-zero trace_id or parent_id');
+    }
+    return Object.freeze({
+      version,
+      traceId,
+      parentId,
+      traceFlags: match[4],
+    });
+  }
+}