apcore-js 0.5.0 → 0.6.0

package/src/registry/scanner.ts

@@ -1,168 +0,0 @@
-/**
- * Directory scanner for discovering TypeScript/JavaScript extension modules.
- */
-
-import { readdirSync, statSync, lstatSync, 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 lstat;
-      try {
-        lstat = lstatSync(entryPath);
-      } catch {
-        console.warn(`[apcore:scanner] Cannot stat entry: ${entryPath}`);
-        continue;
-      }
-
-      const isSymlink = lstat.isSymbolicLink();
-      let isDir: boolean;
-      let isFile: boolean;
-
-      if (isSymlink) {
-        if (!followSymlinks) continue;
-        const real = realpathSync(entryPath);
-        if (visitedRealPaths.has(real)) continue;
-        visitedRealPaths.add(real);
-        // Resolve the symlink target to check if it's a dir or file
-        let targetStat;
-        try {
-          targetStat = statSync(entryPath);
-        } catch {
-          console.warn(`[apcore:scanner] Cannot resolve symlink target: ${entryPath}`);
-          continue;
-        }
-        isDir = targetStat.isDirectory();
-        isFile = targetStat.isFile();
-      } else {
-        isDir = lstat.isDirectory();
-        isFile = lstat.isFile();
-      }
-
-      if (isDir) {
-        scanDir(entryPath, depth + 1);
-      } else if (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

@@ -1,181 +0,0 @@
-/**
- * Schema query and export functions for the registry system.
- */
-
-import type { TSchema } from '@sinclair/typebox';
-import yaml from 'js-yaml';
-import type { ModuleAnnotations, ModuleExample } from '../module.js';
-import { InvalidInputError, ModuleNotFoundError } from '../errors.js';
-import { deepCopy } from '../utils/index.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';
-
-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 validProfiles = new Set(Object.values(ExportProfile));
-  if (!validProfiles.has(profile as ExportProfile)) {
-    throw new InvalidInputError(
-      `Invalid export profile: '${profile}'. Must be one of: ${[...validProfiles].join(', ')}`,
-    );
-  }
-
-  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 yaml.dump(data, { flowLevel: -1 });
-  }
-  return JSON.stringify(data, null, 2);
-}

package/src/registry/types.ts

@@ -1,32 +0,0 @@
-/**
- * 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;
-}

package/src/registry/validation.ts

@@ -1,38 +0,0 @@
-/**
- * Module validation for the registry system.
- *
- * In TypeScript, modules use TypeBox TSchema (which are plain objects) instead of
- * Pydantic BaseModel classes. Duck-type checks validate that the module has
- * inputSchema, outputSchema, description, and execute.
- */
-
-export function validateModule(moduleOrClass: unknown): string[] {
-  const errors: string[] = [];
-  const obj = moduleOrClass as Record<string, unknown>;
-
-  // Check inputSchema
-  const inputSchema = obj['inputSchema'] ?? (obj.constructor as unknown as Record<string, unknown>)?.['inputSchema'];
-  if (inputSchema == null || typeof inputSchema !== 'object') {
-    errors.push('Missing or invalid inputSchema: must be a TSchema object');
-  }
-
-  // Check outputSchema
-  const outputSchema = obj['outputSchema'] ?? (obj.constructor as unknown as Record<string, unknown>)?.['outputSchema'];
-  if (outputSchema == null || typeof outputSchema !== 'object') {
-    errors.push('Missing or invalid outputSchema: must be a TSchema object');
-  }
-
-  // Check description
-  const description = obj['description'];
-  if (!description || typeof description !== 'string') {
-    errors.push('Missing or empty description');
-  }
-
-  // Check execute
-  const execute = obj['execute'];
-  if (execute == null || typeof execute !== 'function') {
-    errors.push('Missing execute method');
-  }
-
-  return errors;
-}

package/src/schema/annotations.ts

@@ -1,68 +0,0 @@
-/**
- * Annotation conflict resolution — merge YAML and code metadata.
- */
-
-import type { ModuleAnnotations, ModuleExample } from '../module.js';
-import { DEFAULT_ANNOTATIONS } from '../module.js';
-
-const ANNOTATION_FIELDS: ReadonlyArray<keyof ModuleAnnotations> = [
-  'readonly',
-  'destructive',
-  'idempotent',
-  'requiresApproval',
-  'openWorld',
-  'streaming',
-];
-
-export function mergeAnnotations(
-  yamlAnnotations: Record<string, unknown> | null | undefined,
-  codeAnnotations: ModuleAnnotations | null | undefined,
-): ModuleAnnotations {
-  const values: Record<string, unknown> = {};
-  for (const f of ANNOTATION_FIELDS) {
-    values[f] = DEFAULT_ANNOTATIONS[f];
-  }
-
-  if (codeAnnotations != null) {
-    for (const f of ANNOTATION_FIELDS) {
-      values[f] = codeAnnotations[f];
-    }
-  }
-
-  if (yamlAnnotations != null) {
-    for (const [key, val] of Object.entries(yamlAnnotations)) {
-      if ((ANNOTATION_FIELDS as readonly string[]).includes(key)) {
-        values[key] = val;
-      }
-    }
-  }
-
-  return values as unknown as ModuleAnnotations;
-}
-
-export function mergeExamples(
-  yamlExamples: Array<Record<string, unknown>> | null | undefined,
-  codeExamples: ModuleExample[] | null | undefined,
-): ModuleExample[] {
-  if (yamlExamples != null) {
-    return yamlExamples.map((d) => ({
-      title: d['title'] as string,
-      inputs: (d['inputs'] as Record<string, unknown>) ?? {},
-      output: (d['output'] as Record<string, unknown>) ?? {},
-      description: d['description'] as string | undefined,
-    }));
-  }
-  if (codeExamples != null) return codeExamples;
-  return [];
-}
-
-export function mergeMetadata(
-  yamlMetadata: Record<string, unknown> | null | undefined,
-  codeMetadata: Record<string, unknown> | null | undefined,
-): Record<string, unknown> {
-  const result = codeMetadata != null ? { ...codeMetadata } : {};
-  if (yamlMetadata != null) {
-    Object.assign(result, yamlMetadata);
-  }
-  return result;
-}

package/src/schema/exporter.ts

@@ -1,90 +0,0 @@
-/**
- * SchemaExporter — converts schemas to platform-specific export formats.
- */
-
-import type { ModuleAnnotations, ModuleExample } from '../module.js';
-import { deepCopy } from '../utils/index.js';
-import { applyLlmDescriptions, stripExtensions, toStrictSchema } from './strict.js';
-import { ExportProfile, type SchemaDefinition } from './types.js';
-
-export class SchemaExporter {
-  export(
-    schemaDef: SchemaDefinition,
-    profile: ExportProfile,
-    annotations?: ModuleAnnotations | null,
-    examples?: ModuleExample[] | null,
-    name?: string | null,
-  ): Record<string, unknown> {
-    if (profile === ExportProfile.MCP) {
-      return this.exportMcp(schemaDef, annotations, name);
-    }
-    if (profile === ExportProfile.OpenAI) {
-      return this.exportOpenai(schemaDef);
-    }
-    if (profile === ExportProfile.Anthropic) {
-      return this.exportAnthropic(schemaDef, examples);
-    }
-    return this.exportGeneric(schemaDef);
-  }
-
-  exportMcp(
-    schemaDef: SchemaDefinition,
-    annotations?: ModuleAnnotations | null,
-    name?: string | null,
-  ): Record<string, unknown> {
-    return {
-      name: name ?? schemaDef.moduleId,
-      description: schemaDef.description,
-      inputSchema: schemaDef.inputSchema,
-      annotations: {
-        readOnlyHint: annotations?.readonly ?? false,
-        destructiveHint: annotations?.destructive ?? false,
-        idempotentHint: annotations?.idempotent ?? false,
-        openWorldHint: annotations?.openWorld ?? true,
-      },
-    };
-  }
-
-  exportOpenai(schemaDef: SchemaDefinition): Record<string, unknown> {
-    const schema = deepCopy(schemaDef.inputSchema);
-    applyLlmDescriptions(schema);
-    const strictSchema = toStrictSchema(schema);
-    return {
-      type: 'function',
-      function: {
-        name: schemaDef.moduleId.replace(/\./g, '_'),
-        description: schemaDef.description,
-        parameters: strictSchema,
-        strict: true,
-      },
-    };
-  }
-
-  exportAnthropic(
-    schemaDef: SchemaDefinition,
-    examples?: ModuleExample[] | null,
-  ): Record<string, unknown> {
-    const schema = deepCopy(schemaDef.inputSchema);
-    applyLlmDescriptions(schema);
-    stripExtensions(schema);
-    const result: Record<string, unknown> = {
-      name: schemaDef.moduleId.replace(/\./g, '_'),
-      description: schemaDef.description,
-      input_schema: schema,
-    };
-    if (examples && examples.length > 0) {
-      result['input_examples'] = examples.map((ex) => ex.inputs);
-    }
-    return result;
-  }
-
-  exportGeneric(schemaDef: SchemaDefinition): Record<string, unknown> {
-    return {
-      module_id: schemaDef.moduleId,
-      description: schemaDef.description,
-      input_schema: schemaDef.inputSchema,
-      output_schema: schemaDef.outputSchema,
-      definitions: schemaDef.definitions,
-    };
-  }
-}