apcore-js 0.1.0

package/src/registry/validation.ts

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1,67 @@
+/**
+ * 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',
+];
+
+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

@@ -0,0 +1,93 @@
+/**
+ * SchemaExporter — converts schemas to platform-specific export formats.
+ */
+
+import type { ModuleAnnotations, ModuleExample } from '../module.js';
+import { applyLlmDescriptions, stripExtensions, toStrictSchema } from './strict.js';
+import { ExportProfile, type SchemaDefinition } from './types.js';
+
+function deepCopy<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+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/index.ts

@@ -0,0 +1,14 @@
+export { SchemaStrategy, ExportProfile, validationResultToError } from './types.js';
+export type {
+  SchemaDefinition,
+  ResolvedSchema,
+  SchemaValidationErrorDetail,
+  SchemaValidationResult,
+  LLMExtensions,
+} from './types.js';
+export { RefResolver } from './ref-resolver.js';
+export { toStrictSchema, applyLlmDescriptions, stripExtensions } from './strict.js';
+export { mergeAnnotations, mergeExamples, mergeMetadata } from './annotations.js';
+export { SchemaLoader, jsonSchemaToTypeBox } from './loader.js';
+export { SchemaValidator } from './validator.js';
+export { SchemaExporter } from './exporter.js';

package/src/schema/loader.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 strategy = SchemaStrategy[
+      (this._config.get('schema.strategy', 'yaml_first') as string)
+        .replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())
+        .replace(/^./, (c) => c.toUpperCase()) as keyof typeof SchemaStrategy
+    ] ?? 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;
+
+  if (schemaType === 'object') {
+    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());
+  }
+
+  if (schemaType === 'array') {
+    const items = schema['items'] as Record<string, unknown> | undefined;
+    if (items) {
+      return Type.Array(jsonSchemaToTypeBox(items));
+    }
+    return Type.Array(Type.Unknown());
+  }
+
+  if (schemaType === 'string') {
+    const opts: Record<string, unknown> = {};
+    if ('minLength' in schema) opts['minLength'] = schema['minLength'];
+    if ('maxLength' in schema) opts['maxLength'] = schema['maxLength'];
+    if ('pattern' in schema) opts['pattern'] = schema['pattern'];
+    if ('format' in schema) opts['format'] = schema['format'];
+    return Type.String(opts);
+  }
+
+  if (schemaType === 'integer') {
+    const opts: Record<string, unknown> = {};
+    if ('minimum' in schema) opts['minimum'] = schema['minimum'];
+    if ('maximum' in schema) opts['maximum'] = schema['maximum'];
+    if ('exclusiveMinimum' in schema) opts['exclusiveMinimum'] = schema['exclusiveMinimum'];
+    if ('exclusiveMaximum' in schema) opts['exclusiveMaximum'] = schema['exclusiveMaximum'];
+    if ('multipleOf' in schema) opts['multipleOf'] = schema['multipleOf'];
+    return Type.Integer(opts);
+  }
+
+  if (schemaType === 'number') {
+    const opts: Record<string, unknown> = {};
+    if ('minimum' in schema) opts['minimum'] = schema['minimum'];
+    if ('maximum' in schema) opts['maximum'] = schema['maximum'];
+    if ('exclusiveMinimum' in schema) opts['exclusiveMinimum'] = schema['exclusiveMinimum'];
+    if ('exclusiveMaximum' in schema) opts['exclusiveMaximum'] = schema['exclusiveMaximum'];
+    if ('multipleOf' in schema) opts['multipleOf'] = schema['multipleOf'];
+    return Type.Number(opts);
+  }
+
+  if (schemaType === 'boolean') return Type.Boolean();
+  if (schemaType === 'null') return Type.Null();
+
+  if ('enum' in schema) {
+    const values = schema['enum'] as unknown[];
+    return Type.Union(values.map((v) => Type.Literal(v as string | number | boolean)));
+  }
+
+  if ('oneOf' in schema) {
+    const schemas = schema['oneOf'] as Record<string, unknown>[];
+    return Type.Union(schemas.map((s) => jsonSchemaToTypeBox(s)));
+  }
+
+  if ('anyOf' in schema) {
+    const schemas = schema['anyOf'] as Record<string, unknown>[];
+    return Type.Union(schemas.map((s) => jsonSchemaToTypeBox(s)));
+  }
+
+  if ('allOf' in schema) {
+    const schemas = schema['allOf'] as Record<string, unknown>[];
+    return Type.Intersect(schemas.map((s) => jsonSchemaToTypeBox(s)));
+  }
+
+  return Type.Unknown();
+}