apcore-js 0.4.0 → 0.6.0

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,
-    };
-  }
-}

package/src/schema/loader.ts

@@ -1,273 +0,0 @@
-/**
- * SchemaLoader — primary entry point for the schema system.
- *
- * Uses TypeBox for schema representation. Since TypeBox schemas ARE JSON Schema,
- * the conversion layer is minimal.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { Type, type TSchema } from '@sinclair/typebox';
-import yaml from 'js-yaml';
-import type { Config } from '../config.js';
-import { SchemaNotFoundError, SchemaParseError } from '../errors.js';
-import { RefResolver } from './ref-resolver.js';
-import type { ResolvedSchema, SchemaDefinition } from './types.js';
-import { SchemaStrategy } from './types.js';
-
-export class SchemaLoader {
-  private _config: Config;
-  private _schemasDir: string;
-  private _resolver: RefResolver;
-  private _schemaCache: Map<string, SchemaDefinition> = new Map();
-  private _modelCache: Map<string, [ResolvedSchema, ResolvedSchema]> = new Map();
-
-  constructor(config: Config, schemasDir?: string | null) {
-    this._config = config;
-    if (schemasDir != null) {
-      this._schemasDir = resolve(schemasDir);
-    } else {
-      this._schemasDir = resolve(config.get('schema.root', './schemas') as string);
-    }
-    const maxDepth = (config.get('schema.max_ref_depth', 32) as number);
-    this._resolver = new RefResolver(this._schemasDir, maxDepth);
-  }
-
-  load(moduleId: string): SchemaDefinition {
-    const cached = this._schemaCache.get(moduleId);
-    if (cached) return cached;
-
-    const filePath = join(this._schemasDir, moduleId.replace(/\./g, '/') + '.schema.yaml');
-    if (!existsSync(filePath)) {
-      throw new SchemaNotFoundError(moduleId);
-    }
-
-    let data: unknown;
-    try {
-      data = yaml.load(readFileSync(filePath, 'utf-8'));
-    } catch (e) {
-      throw new SchemaParseError(`Invalid YAML in schema for '${moduleId}': ${e}`);
-    }
-
-    if (data === null || data === undefined || typeof data !== 'object' || Array.isArray(data)) {
-      throw new SchemaParseError(`Schema file for '${moduleId}' is empty or not a mapping`);
-    }
-
-    const dataObj = data as Record<string, unknown>;
-    for (const fieldName of ['input_schema', 'output_schema', 'description']) {
-      if (!(fieldName in dataObj)) {
-        throw new SchemaParseError(`Missing required field: ${fieldName} in schema for '${moduleId}'`);
-      }
-    }
-
-    const definitions: Record<string, unknown> = {
-      ...((dataObj['definitions'] as Record<string, unknown>) ?? {}),
-      ...((dataObj['$defs'] as Record<string, unknown>) ?? {}),
-    };
-
-    const sd: SchemaDefinition = {
-      moduleId: (dataObj['module_id'] as string) ?? moduleId,
-      description: dataObj['description'] as string,
-      inputSchema: dataObj['input_schema'] as Record<string, unknown>,
-      outputSchema: dataObj['output_schema'] as Record<string, unknown>,
-      errorSchema: (dataObj['error_schema'] as Record<string, unknown>) ?? null,
-      definitions,
-      version: (dataObj['version'] as string) ?? '1.0.0',
-      documentation: (dataObj['documentation'] as string) ?? null,
-      schemaUrl: (dataObj['$schema'] as string) ?? null,
-    };
-
-    this._schemaCache.set(moduleId, sd);
-    return sd;
-  }
-
-  resolve(schemaDef: SchemaDefinition): [ResolvedSchema, ResolvedSchema] {
-    const resolvedInput = this._resolver.resolve(schemaDef.inputSchema);
-    const resolvedOutput = this._resolver.resolve(schemaDef.outputSchema);
-
-    const inputSchema = jsonSchemaToTypeBox(resolvedInput);
-    const outputSchema = jsonSchemaToTypeBox(resolvedOutput);
-
-    const inputRs: ResolvedSchema = {
-      jsonSchema: resolvedInput,
-      schema: inputSchema,
-      moduleId: schemaDef.moduleId,
-      direction: 'input',
-    };
-    const outputRs: ResolvedSchema = {
-      jsonSchema: resolvedOutput,
-      schema: outputSchema,
-      moduleId: schemaDef.moduleId,
-      direction: 'output',
-    };
-    return [inputRs, outputRs];
-  }
-
-  getSchema(
-    moduleId: string,
-    nativeInputSchema?: TSchema | null,
-    nativeOutputSchema?: TSchema | null,
-  ): [ResolvedSchema, ResolvedSchema] {
-    const cached = this._modelCache.get(moduleId);
-    if (cached) return cached;
-
-    const strategyMap: Record<string, SchemaStrategy> = {
-      yaml_first: SchemaStrategy.YamlFirst,
-      native_first: SchemaStrategy.NativeFirst,
-      yaml_only: SchemaStrategy.YamlOnly,
-    };
-    const rawStrategy = this._config.get('schema.strategy', 'yaml_first') as string;
-    const strategy = strategyMap[rawStrategy] ?? SchemaStrategy.YamlFirst;
-
-    let result: [ResolvedSchema, ResolvedSchema] | null = null;
-
-    if (strategy === SchemaStrategy.YamlFirst) {
-      try {
-        result = this._loadAndResolve(moduleId);
-      } catch (e) {
-        if (e instanceof SchemaNotFoundError && nativeInputSchema && nativeOutputSchema) {
-          result = this._wrapNative(moduleId, nativeInputSchema, nativeOutputSchema);
-        } else {
-          throw e;
-        }
-      }
-    } else if (strategy === SchemaStrategy.NativeFirst) {
-      if (nativeInputSchema && nativeOutputSchema) {
-        result = this._wrapNative(moduleId, nativeInputSchema, nativeOutputSchema);
-      } else {
-        result = this._loadAndResolve(moduleId);
-      }
-    } else if (strategy === SchemaStrategy.YamlOnly) {
-      result = this._loadAndResolve(moduleId);
-    }
-
-    if (result === null) {
-      throw new SchemaNotFoundError(moduleId);
-    }
-
-    this._modelCache.set(moduleId, result);
-    return result;
-  }
-
-  private _loadAndResolve(moduleId: string): [ResolvedSchema, ResolvedSchema] {
-    const cached = this._modelCache.get(moduleId);
-    if (cached) return cached;
-    const sd = this.load(moduleId);
-    const result = this.resolve(sd);
-    this._modelCache.set(moduleId, result);
-    return result;
-  }
-
-  private _wrapNative(
-    moduleId: string,
-    inputSchema: TSchema,
-    outputSchema: TSchema,
-  ): [ResolvedSchema, ResolvedSchema] {
-    const inputRs: ResolvedSchema = {
-      jsonSchema: inputSchema as unknown as Record<string, unknown>,
-      schema: inputSchema,
-      moduleId,
-      direction: 'input',
-    };
-    const outputRs: ResolvedSchema = {
-      jsonSchema: outputSchema as unknown as Record<string, unknown>,
-      schema: outputSchema,
-      moduleId,
-      direction: 'output',
-    };
-    return [inputRs, outputRs];
-  }
-
-  clearCache(): void {
-    this._schemaCache.clear();
-    this._modelCache.clear();
-    this._resolver.clearCache();
-  }
-}
-
-/**
- * Convert a JSON Schema dict to a TypeBox TSchema.
- * Since TypeBox schemas ARE JSON Schema, this wraps the raw object
- * so it can be used with Value.Check/Value.Decode.
- */
-export function jsonSchemaToTypeBox(schema: Record<string, unknown>): TSchema {
-  const schemaType = schema['type'] as string | undefined;
-
-  let result: TSchema;
-  if (schemaType === 'object') result = convertObjectSchema(schema);
-  else if (schemaType === 'array') result = convertArraySchema(schema);
-  else if (schemaType === 'string') result = convertStringSchema(schema);
-  else if (schemaType === 'integer') result = convertNumericSchema(schema, Type.Integer);
-  else if (schemaType === 'number') result = convertNumericSchema(schema, Type.Number);
-  else if (schemaType === 'boolean') result = Type.Boolean();
-  else if (schemaType === 'null') result = Type.Null();
-  else result = convertCombinatorSchema(schema);
-
-  // Preserve JSON Schema metadata
-  if (typeof schema['description'] === 'string') result['description'] = schema['description'];
-  if (typeof schema['title'] === 'string') result['title'] = schema['title'];
-
-  return result;
-}
-
-function convertObjectSchema(schema: Record<string, unknown>): TSchema {
-  const properties = schema['properties'] as Record<string, Record<string, unknown>> | undefined;
-  const required = new Set((schema['required'] as string[]) ?? []);
-
-  if (properties) {
-    const typeboxProps: Record<string, TSchema> = {};
-    for (const [name, propSchema] of Object.entries(properties)) {
-      const propType = jsonSchemaToTypeBox(propSchema);
-      typeboxProps[name] = required.has(name) ? propType : Type.Optional(propType);
-    }
-    return Type.Object(typeboxProps);
-  }
-  return Type.Record(Type.String(), Type.Unknown());
-}
-
-function convertArraySchema(schema: Record<string, unknown>): TSchema {
-  const items = schema['items'] as Record<string, unknown> | undefined;
-  return items ? Type.Array(jsonSchemaToTypeBox(items)) : Type.Array(Type.Unknown());
-}
-
-function convertStringSchema(schema: Record<string, unknown>): TSchema {
-  const opts: Record<string, unknown> = {};
-  for (const key of ['minLength', 'maxLength', 'pattern', 'format']) {
-    if (key in schema) opts[key] = schema[key];
-  }
-  return Type.String(opts);
-}
-
-function convertNumericSchema(
-  schema: Record<string, unknown>,
-  factory: (opts?: Record<string, unknown>) => TSchema,
-): TSchema {
-  const opts: Record<string, unknown> = {};
-  for (const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf']) {
-    if (key in schema) opts[key] = schema[key];
-  }
-  return factory(opts);
-}
-
-function convertCombinatorSchema(schema: Record<string, unknown>): TSchema {
-  if ('enum' in schema) {
-    const values = schema['enum'] as unknown[];
-    return Type.Union(values.map((v) =>
-      v === null ? Type.Null() : Type.Literal(v as string | number | boolean),
-    ));
-  }
-  if ('const' in schema) {
-    const value = schema['const'];
-    return value === null ? Type.Null() : Type.Literal(value as string | number | boolean);
-  }
-  if ('oneOf' in schema) {
-    return Type.Union((schema['oneOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  if ('anyOf' in schema) {
-    return Type.Union((schema['anyOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  if ('allOf' in schema) {
-    return Type.Intersect((schema['allOf'] as Record<string, unknown>[]).map(jsonSchemaToTypeBox));
-  }
-  return Type.Unknown();
-}