apcore-js 0.1.0

package/src/registry/registry.ts

@@ -0,0 +1,314 @@
+/**
+ * Central module registry for discovering, registering, and querying modules.
+ */
+
+import { resolve } from 'node:path';
+import type { Config } from '../config.js';
+import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
+import type { ModuleAnnotations, ModuleExample } from '../module.js';
+import { resolveDependencies } from './dependencies.js';
+import { resolveEntryPoint } from './entry-point.js';
+import { loadIdMap, loadMetadata, mergeModuleMetadata, parseDependencies } from './metadata.js';
+import { scanExtensions, scanMultiRoot } from './scanner.js';
+import type { DependencyInfo, ModuleDescriptor } from './types.js';
+import { validateModule } from './validation.js';
+
+type EventCallback = (moduleId: string, module: unknown) => void;
+
+export class Registry {
+  private _extensionRoots: Array<Record<string, unknown>>;
+  private _modules: Map<string, unknown> = new Map();
+  private _moduleMeta: Map<string, Record<string, unknown>> = new Map();
+  private _callbacks: Map<string, EventCallback[]> = new Map([
+    ['register', []],
+    ['unregister', []],
+  ]);
+  private _idMap: Record<string, Record<string, unknown>> = {};
+  private _schemaCache: Map<string, Record<string, unknown>> = new Map();
+  private _config: Config | null;
+
+  constructor(options?: {
+    config?: Config | null;
+    extensionsDir?: string | null;
+    extensionsDirs?: Array<string | Record<string, unknown>> | null;
+    idMapPath?: string | null;
+  }) {
+    const config = options?.config ?? null;
+    const extensionsDir = options?.extensionsDir ?? null;
+    const extensionsDirs = options?.extensionsDirs ?? null;
+    const idMapPath = options?.idMapPath ?? null;
+
+    if (extensionsDir !== null && extensionsDirs !== null) {
+      throw new InvalidInputError('Cannot specify both extensionsDir and extensionsDirs');
+    }
+
+    if (extensionsDir !== null) {
+      this._extensionRoots = [{ root: extensionsDir }];
+    } else if (extensionsDirs !== null) {
+      this._extensionRoots = extensionsDirs.map((item) =>
+        typeof item === 'string' ? { root: item } : item,
+      );
+    } else if (config !== null) {
+      const extRoot = config.get('extensions.root') as string | undefined;
+      this._extensionRoots = [{ root: extRoot ?? './extensions' }];
+    } else {
+      this._extensionRoots = [{ root: './extensions' }];
+    }
+
+    this._config = config;
+
+    if (idMapPath !== null) {
+      this._idMap = loadIdMap(idMapPath);
+    }
+  }
+
+  async discover(): Promise<number> {
+    let maxDepth = 8;
+    let followSymlinks = false;
+    if (this._config !== null) {
+      maxDepth = (this._config.get('extensions.max_depth', 8) as number);
+      followSymlinks = (this._config.get('extensions.follow_symlinks', false) as boolean);
+    }
+
+    // Step 1: Scan extension roots
+    const hasNamespace = this._extensionRoots.some((r) => 'namespace' in r);
+    let discovered;
+    if (this._extensionRoots.length > 1 || hasNamespace) {
+      discovered = scanMultiRoot(this._extensionRoots, maxDepth, followSymlinks);
+    } else {
+      const rootPath = this._extensionRoots[0]['root'] as string;
+      discovered = scanExtensions(rootPath, maxDepth, followSymlinks);
+    }
+
+    // Step 2: Apply ID Map overrides
+    if (Object.keys(this._idMap).length > 0) {
+      const resolvedRoots = this._extensionRoots.map((r) => resolve(r['root'] as string));
+      for (const dm of discovered) {
+        for (const root of resolvedRoots) {
+          try {
+            const relPath = dm.filePath.startsWith(root)
+              ? dm.filePath.slice(root.length + 1)
+              : null;
+            if (relPath && relPath in this._idMap) {
+              dm.canonicalId = this._idMap[relPath]['id'] as string;
+              break;
+            }
+          } catch {
+            continue;
+          }
+        }
+      }
+    }
+
+    // Step 3: Load metadata
+    const rawMetadata = new Map<string, Record<string, unknown>>();
+    for (const dm of discovered) {
+      rawMetadata.set(
+        dm.canonicalId,
+        dm.metaPath ? loadMetadata(dm.metaPath) : {},
+      );
+    }
+
+    // Step 4: Resolve entry points
+    const resolvedModules = new Map<string, unknown>();
+    for (const dm of discovered) {
+      const meta = rawMetadata.get(dm.canonicalId) ?? {};
+      try {
+        const mod = await resolveEntryPoint(dm.filePath, meta);
+        resolvedModules.set(dm.canonicalId, mod);
+      } catch {
+        continue;
+      }
+    }
+
+    // Step 5: Validate modules
+    const validModules = new Map<string, unknown>();
+    for (const [modId, mod] of resolvedModules) {
+      const errors = validateModule(mod);
+      if (errors.length === 0) {
+        validModules.set(modId, mod);
+      }
+    }
+
+    // Step 6: Collect dependencies
+    const modulesWithDeps: Array<[string, DependencyInfo[]]> = [];
+    for (const modId of validModules.keys()) {
+      const meta = rawMetadata.get(modId) ?? {};
+      const depsRaw = (meta['dependencies'] as Array<Record<string, unknown>>) ?? [];
+      const deps = depsRaw.length > 0 ? parseDependencies(depsRaw) : [];
+      modulesWithDeps.push([modId, deps]);
+    }
+
+    // Step 7: Resolve dependency order
+    const knownIds = new Set(modulesWithDeps.map(([id]) => id));
+    const loadOrder = resolveDependencies(modulesWithDeps, knownIds);
+
+    // Step 8: Register in dependency order
+    let registeredCount = 0;
+    for (const modId of loadOrder) {
+      const mod = validModules.get(modId)!;
+      const meta = rawMetadata.get(modId) ?? {};
+
+      const modObj = mod as Record<string, unknown>;
+      const mergedMeta = mergeModuleMetadata(modObj, meta);
+
+      this._modules.set(modId, mod);
+      this._moduleMeta.set(modId, mergedMeta);
+
+      // Call onLoad if available
+      if (typeof modObj['onLoad'] === 'function') {
+        try {
+          (modObj['onLoad'] as () => void)();
+        } catch {
+          this._modules.delete(modId);
+          this._moduleMeta.delete(modId);
+          continue;
+        }
+      }
+
+      this._triggerEvent('register', modId, mod);
+      registeredCount++;
+    }
+
+    return registeredCount;
+  }
+
+  register(moduleId: string, module: unknown): void {
+    if (!moduleId) {
+      throw new InvalidInputError('module_id must be a non-empty string');
+    }
+
+    if (this._modules.has(moduleId)) {
+      throw new InvalidInputError(`Module already exists: ${moduleId}`);
+    }
+
+    this._modules.set(moduleId, module);
+
+    // Call onLoad if available
+    const modObj = module as Record<string, unknown>;
+    if (typeof modObj['onLoad'] === 'function') {
+      try {
+        (modObj['onLoad'] as () => void)();
+      } catch (e) {
+        this._modules.delete(moduleId);
+        throw e;
+      }
+    }
+
+    this._triggerEvent('register', moduleId, module);
+  }
+
+  unregister(moduleId: string): boolean {
+    if (!this._modules.has(moduleId)) return false;
+
+    const module = this._modules.get(moduleId)!;
+    this._modules.delete(moduleId);
+    this._moduleMeta.delete(moduleId);
+    this._schemaCache.delete(moduleId);
+
+    // Call onUnload if available
+    const modObj = module as Record<string, unknown>;
+    if (typeof modObj['onUnload'] === 'function') {
+      try {
+        (modObj['onUnload'] as () => void)();
+      } catch {
+        // Swallow
+      }
+    }
+
+    this._triggerEvent('unregister', moduleId, module);
+    return true;
+  }
+
+  get(moduleId: string): unknown | null {
+    if (moduleId === '') {
+      throw new ModuleNotFoundError('');
+    }
+    return this._modules.get(moduleId) ?? null;
+  }
+
+  has(moduleId: string): boolean {
+    return this._modules.has(moduleId);
+  }
+
+  list(options?: { tags?: string[]; prefix?: string }): string[] {
+    let ids = [...this._modules.keys()];
+
+    if (options?.prefix != null) {
+      ids = ids.filter((id) => id.startsWith(options.prefix!));
+    }
+
+    if (options?.tags != null) {
+      const tagSet = new Set(options.tags);
+      ids = ids.filter((id) => {
+        const mod = this._modules.get(id) as Record<string, unknown>;
+        const modTags = new Set((mod['tags'] as string[]) ?? []);
+        const metaTags = (this._moduleMeta.get(id) ?? {})['tags'];
+        if (Array.isArray(metaTags)) {
+          for (const t of metaTags) modTags.add(t as string);
+        }
+        for (const t of tagSet) {
+          if (!modTags.has(t)) return false;
+        }
+        return true;
+      });
+    }
+
+    return ids.sort();
+  }
+
+  iter(): IterableIterator<[string, unknown]> {
+    return this._modules.entries();
+  }
+
+  get count(): number {
+    return this._modules.size;
+  }
+
+  get moduleIds(): string[] {
+    return [...this._modules.keys()].sort();
+  }
+
+  getDefinition(moduleId: string): ModuleDescriptor | null {
+    const module = this._modules.get(moduleId);
+    if (module == null) return null;
+    const meta = this._moduleMeta.get(moduleId) ?? {};
+    const mod = module as Record<string, unknown>;
+
+    return {
+      moduleId,
+      name: ((meta['name'] as string) ?? (mod['name'] as string)) ?? null,
+      description: ((meta['description'] as string) ?? (mod['description'] as string)) ?? '',
+      documentation: ((meta['documentation'] as string) ?? (mod['documentation'] as string)) ?? null,
+      inputSchema: (mod['inputSchema'] as Record<string, unknown>) ?? {},
+      outputSchema: (mod['outputSchema'] as Record<string, unknown>) ?? {},
+      version: ((meta['version'] as string) ?? (mod['version'] as string)) ?? '1.0.0',
+      tags: (meta['tags'] as string[]) ?? (mod['tags'] as string[]) ?? [],
+      annotations: (mod['annotations'] as ModuleAnnotations) ?? null,
+      examples: (mod['examples'] as ModuleExample[]) ?? [],
+      metadata: (meta['metadata'] as Record<string, unknown>) ?? {},
+    };
+  }
+
+  on(event: string, callback: EventCallback): void {
+    if (!this._callbacks.has(event)) {
+      throw new InvalidInputError(`Invalid event: ${event}. Must be 'register' or 'unregister'`);
+    }
+    this._callbacks.get(event)!.push(callback);
+  }
+
+  private _triggerEvent(event: string, moduleId: string, module: unknown): void {
+    const callbacks = this._callbacks.get(event) ?? [];
+    for (const cb of callbacks) {
+      try {
+        cb(moduleId, module);
+      } catch {
+        // Swallow callback errors
+      }
+    }
+  }
+
+  clearCache(): void {
+    this._schemaCache.clear();
+  }
+}

package/src/registry/scanner.ts

@@ -0,0 +1,150 @@
+/**
+ * Directory scanner for discovering TypeScript/JavaScript extension modules.
+ */
+
+import { readdirSync, statSync, realpathSync } from 'node:fs';
+import { resolve, relative, join, extname, basename, sep } from 'node:path';
+import { ConfigError, ConfigNotFoundError } from '../errors.js';
+import type { DiscoveredModule } from './types.js';
+
+const SKIP_DIR_NAMES = new Set(['node_modules', '__pycache__']);
+const VALID_EXTENSIONS = new Set(['.ts', '.js']);
+const SKIP_SUFFIXES = ['.d.ts', '.test.ts', '.test.js', '.spec.ts', '.spec.js'];
+
+function existsAndIsDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function scanExtensions(
+  root: string,
+  maxDepth: number = 8,
+  followSymlinks: boolean = false,
+): DiscoveredModule[] {
+  const rootResolved = resolve(root);
+  if (!existsAndIsDir(rootResolved)) {
+    throw new ConfigNotFoundError(rootResolved);
+  }
+
+  const visitedRealPaths = new Set([realpathSync(rootResolved)]);
+  const results: DiscoveredModule[] = [];
+  const seenIds = new Map<string, string>();
+  const seenIdsLower = new Map<string, string>();
+
+  function scanDir(dirPath: string, depth: number): void {
+    if (depth > maxDepth) {
+      console.warn(`[apcore:scanner] Max depth ${maxDepth} exceeded at: ${dirPath}`);
+      return;
+    }
+
+    let entries: string[];
+    try {
+      entries = readdirSync(dirPath);
+    } catch {
+      console.warn(`[apcore:scanner] Cannot read directory: ${dirPath}`);
+      return;
+    }
+
+    for (const name of entries) {
+      if (name.startsWith('.') || name.startsWith('_')) continue;
+      if (SKIP_DIR_NAMES.has(name)) continue;
+
+      const entryPath = join(dirPath, name);
+      let stat;
+      try {
+        stat = statSync(entryPath);
+      } catch {
+        console.warn(`[apcore:scanner] Cannot stat entry: ${entryPath}`);
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        if (stat.isSymbolicLink()) {
+          if (!followSymlinks) continue;
+          const real = realpathSync(entryPath);
+          if (visitedRealPaths.has(real)) continue;
+          visitedRealPaths.add(real);
+        }
+        scanDir(entryPath, depth + 1);
+      } else if (stat.isFile()) {
+        const ext = extname(name);
+        if (!VALID_EXTENSIONS.has(ext)) continue;
+        if (SKIP_SUFFIXES.some((s) => name.endsWith(s))) continue;
+
+        const rel = relative(rootResolved, entryPath);
+        const canonicalId = rel
+          .replace(new RegExp(`\\${sep}`, 'g'), '.')
+          .replace(/\.(ts|js)$/, '');
+
+        if (seenIds.has(canonicalId)) {
+          console.warn(`[apcore:scanner] Duplicate module ID '${canonicalId}', skipping: ${entryPath}`);
+          continue;
+        }
+
+        const lowerId = canonicalId.toLowerCase();
+        if (seenIdsLower.has(lowerId) && seenIdsLower.get(lowerId) !== canonicalId) {
+          console.warn(`[apcore:scanner] Case collision: '${canonicalId}' vs '${seenIdsLower.get(lowerId)}'`);
+        }
+
+        // Check for companion metadata file
+        const stem = basename(entryPath, ext);
+        const metaPath = join(dirPath, stem + '_meta.yaml');
+        let metaPathResult: string | null = null;
+        try {
+          if (statSync(metaPath).isFile()) metaPathResult = metaPath;
+        } catch {
+          // no meta file
+        }
+
+        seenIds.set(canonicalId, entryPath);
+        seenIdsLower.set(lowerId, canonicalId);
+        results.push({
+          filePath: entryPath,
+          canonicalId,
+          metaPath: metaPathResult,
+          namespace: null,
+        });
+      }
+    }
+  }
+
+  scanDir(rootResolved, 1);
+  return results;
+}
+
+export function scanMultiRoot(
+  roots: Array<Record<string, unknown>>,
+  maxDepth: number = 8,
+  followSymlinks: boolean = false,
+): DiscoveredModule[] {
+  const allResults: DiscoveredModule[] = [];
+  const seenNamespaces = new Set<string>();
+
+  const resolved: Array<[string, string]> = [];
+  for (const entry of roots) {
+    const rootPath = entry['root'] as string;
+    const namespace = (entry['namespace'] as string) || basename(rootPath);
+    if (seenNamespaces.has(namespace)) {
+      throw new ConfigError(`Duplicate namespace: '${namespace}'`);
+    }
+    seenNamespaces.add(namespace);
+    resolved.push([rootPath, namespace]);
+  }
+
+  for (const [rootPath, namespace] of resolved) {
+    const modules = scanExtensions(rootPath, maxDepth, followSymlinks);
+    for (const m of modules) {
+      allResults.push({
+        filePath: m.filePath,
+        canonicalId: `${namespace}.${m.canonicalId}`,
+        metaPath: m.metaPath,
+        namespace,
+      });
+    }
+  }
+
+  return allResults;
+}

package/src/registry/schema-export.ts

@@ -0,0 +1,177 @@
+/**
+ * Schema query and export functions for the registry system.
+ */
+
+import type { TSchema } from '@sinclair/typebox';
+import json from 'js-yaml';
+import type { ModuleAnnotations, ModuleExample } from '../module.js';
+import { ModuleNotFoundError } from '../errors.js';
+import { SchemaExporter } from '../schema/exporter.js';
+import { stripExtensions, toStrictSchema } from '../schema/strict.js';
+import { ExportProfile, type SchemaDefinition } from '../schema/types.js';
+import type { Registry } from './registry.js';
+
+function deepCopy<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+export function getSchema(registry: Registry, moduleId: string): Record<string, unknown> | null {
+  const module = registry.get(moduleId);
+  if (module === null) return null;
+
+  const mod = module as Record<string, unknown>;
+
+  // TypeBox schemas are already JSON Schema
+  const inputSchemaDict = mod['inputSchema'] as Record<string, unknown> ?? {};
+  const outputSchemaDict = mod['outputSchema'] as Record<string, unknown> ?? {};
+
+  const annotations = mod['annotations'] as ModuleAnnotations | undefined;
+  let annotationsDict: Record<string, unknown> | null = null;
+  if (annotations) {
+    annotationsDict = { ...annotations };
+  }
+
+  const examplesRaw = (mod['examples'] as ModuleExample[] | undefined) ?? [];
+  const examplesList = examplesRaw.map((ex) => ({ ...ex }));
+
+  return {
+    module_id: moduleId,
+    name: (mod['name'] as string) ?? null,
+    description: (mod['description'] as string) ?? '',
+    version: (mod['version'] as string) ?? '1.0.0',
+    tags: [...((mod['tags'] as string[]) ?? [])],
+    input_schema: inputSchemaDict,
+    output_schema: outputSchemaDict,
+    annotations: annotationsDict,
+    examples: examplesList,
+  };
+}
+
+export function exportSchema(
+  registry: Registry,
+  moduleId: string,
+  format: string = 'json',
+  strict: boolean = false,
+  compact: boolean = false,
+  profile?: string | null,
+): string {
+  const schemaDict = getSchema(registry, moduleId);
+  if (schemaDict === null) {
+    throw new ModuleNotFoundError(moduleId);
+  }
+
+  if (profile != null) {
+    return exportWithProfile(registry, moduleId, schemaDict, profile, format);
+  }
+
+  const result = deepCopy(schemaDict);
+
+  if (strict) {
+    result['input_schema'] = toStrictSchema(result['input_schema'] as Record<string, unknown>);
+    result['output_schema'] = toStrictSchema(result['output_schema'] as Record<string, unknown>);
+  } else if (compact) {
+    applyCompact(result);
+  }
+
+  return serialize(result, format);
+}
+
+export function getAllSchemas(registry: Registry): Record<string, Record<string, unknown>> {
+  const result: Record<string, Record<string, unknown>> = {};
+  for (const moduleId of registry.moduleIds) {
+    const schema = getSchema(registry, moduleId);
+    if (schema !== null) {
+      result[moduleId] = schema;
+    }
+  }
+  return result;
+}
+
+export function exportAllSchemas(
+  registry: Registry,
+  format: string = 'json',
+  strict: boolean = false,
+  compact: boolean = false,
+  profile?: string | null,
+): string {
+  const allSchemas = getAllSchemas(registry);
+
+  if (strict || compact) {
+    for (const [moduleId, schema] of Object.entries(allSchemas)) {
+      const result = deepCopy(schema);
+      if (strict) {
+        result['input_schema'] = toStrictSchema(result['input_schema'] as Record<string, unknown>);
+        result['output_schema'] = toStrictSchema(result['output_schema'] as Record<string, unknown>);
+      } else if (compact) {
+        applyCompact(result);
+      }
+      allSchemas[moduleId] = result;
+    }
+  }
+
+  return serialize(allSchemas, format);
+}
+
+function exportWithProfile(
+  registry: Registry,
+  moduleId: string,
+  schemaDict: Record<string, unknown>,
+  profile: string,
+  format: string,
+): string {
+  const schemaDef: SchemaDefinition = {
+    moduleId,
+    description: schemaDict['description'] as string,
+    inputSchema: schemaDict['input_schema'] as Record<string, unknown>,
+    outputSchema: schemaDict['output_schema'] as Record<string, unknown>,
+    definitions: {},
+    version: (schemaDict['version'] as string) ?? '1.0.0',
+  };
+  const module = registry.get(moduleId);
+  const annotations = module ? (module as Record<string, unknown>)['annotations'] as ModuleAnnotations | undefined : undefined;
+  const examples = module ? ((module as Record<string, unknown>)['examples'] as ModuleExample[]) ?? [] : [];
+  const name = module ? (module as Record<string, unknown>)['name'] as string | undefined : undefined;
+
+  const exported = new SchemaExporter().export(
+    schemaDef,
+    profile as ExportProfile,
+    annotations,
+    examples,
+    name,
+  );
+  return serialize(exported, format);
+}
+
+function applyCompact(schemaDict: Record<string, unknown>): void {
+  const desc = schemaDict['description'] as string;
+  if (desc) {
+    schemaDict['description'] = truncateDescription(desc);
+  }
+  stripExtensions(schemaDict['input_schema'] as Record<string, unknown> ?? {});
+  stripExtensions(schemaDict['output_schema'] as Record<string, unknown> ?? {});
+  delete schemaDict['documentation'];
+  delete schemaDict['examples'];
+}
+
+function truncateDescription(description: string): string {
+  const dotSpace = description.indexOf('. ');
+  const newline = description.indexOf('\n');
+
+  const candidates: number[] = [];
+  if (dotSpace >= 0) candidates.push(dotSpace + 1);
+  if (newline >= 0) candidates.push(newline);
+
+  if (candidates.length > 0) {
+    const cut = Math.min(...candidates);
+    return description.slice(0, cut).trimEnd();
+  }
+
+  return description;
+}
+
+function serialize(data: unknown, format: string): string {
+  if (format === 'yaml') {
+    return json.dump(data, { flowLevel: -1 });
+  }
+  return JSON.stringify(data, null, 2);
+}

package/src/registry/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Registry types: ModuleDescriptor, DiscoveredModule, DependencyInfo.
+ */
+
+import type { ModuleAnnotations, ModuleExample } from '../module.js';
+
+export interface ModuleDescriptor {
+  moduleId: string;
+  name: string | null;
+  description: string;
+  documentation: string | null;
+  inputSchema: Record<string, unknown>;
+  outputSchema: Record<string, unknown>;
+  version: string;
+  tags: string[];
+  annotations: ModuleAnnotations | null;
+  examples: ModuleExample[];
+  metadata: Record<string, unknown>;
+}
+
+export interface DiscoveredModule {
+  filePath: string;
+  canonicalId: string;
+  metaPath: string | null;
+  namespace: string | null;
+}
+
+export interface DependencyInfo {
+  moduleId: string;
+  version: string | null;
+  optional: boolean;
+}