@aaac/contracts 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -1,9 +1,344 @@
-/** Package version string. */
-declare const version = "0.0.1";
-/** Minimal contract definition placeholder. */
-interface ContractDefinition {
+import { z } from 'zod';
+
+/** Supported AaaC schema versions (compiler accepts only these). */
+declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["aaac/0.1"];
+/** Pattern for schema version field: `aaac/x.y` */
+declare const SCHEMA_VERSION_PATTERN: RegExp;
+declare const JSONSchemaRefSchema: z.ZodUnion<readonly [z.ZodObject<{
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    $ref: z.ZodString;
+}, z.core.$strip>]>;
+declare const OptionSchema: z.ZodObject<{
+    name: z.ZodString;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ArtifactSlotValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    artifact: z.ZodString;
+    direction: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        readwrite: "readwrite";
+    }>;
+}, z.core.$strip>]>;
+declare const OperationSchema: z.ZodObject<{
+    description: z.ZodString;
+    agentWorkflow: z.ZodOptional<z.ZodString>;
+    agentTask: z.ZodOptional<z.ZodString>;
+    handler: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    input: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        $ref: z.ZodString;
+    }, z.core.$strip>]>>;
+    output: z.ZodObject<{
+        success: z.ZodUnion<readonly [z.ZodObject<{
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strip>]>;
+        failed: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>;
+    artifactSlots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        artifact: z.ZodString;
+        direction: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            readwrite: "readwrite";
+        }>;
+    }, z.core.$strip>]>>>;
+    riskLevel: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    idempotent: z.ZodOptional<z.ZodBoolean>;
+    requiresConfirmation: z.ZodOptional<z.ZodBoolean>;
+    execution: z.ZodOptional<z.ZodObject<{
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        costCeilingUsd: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    memoryRef: z.ZodOptional<z.ZodObject<{
+        input: z.ZodOptional<z.ZodBoolean>;
+        output: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const ComponentSchema: z.ZodObject<{
+    schema: z.ZodString;
+    info: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    implementation: z.ZodOptional<z.ZodString>;
+    projections: z.ZodArray<z.ZodEnum<{
+        library: "library";
+        cli: "cli";
+        mcp: "mcp";
+        claude: "claude";
+        openai: "openai";
+    }>>;
+    operations: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        agentWorkflow: z.ZodOptional<z.ZodString>;
+        agentTask: z.ZodOptional<z.ZodString>;
+        handler: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        input: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodObject<{
+            $ref: z.ZodString;
+        }, z.core.$strip>]>>;
+        output: z.ZodObject<{
+            success: z.ZodUnion<readonly [z.ZodObject<{
+                schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>, z.ZodObject<{
+                $ref: z.ZodString;
+            }, z.core.$strip>]>;
+            failed: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>, z.ZodObject<{
+                $ref: z.ZodString;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>;
+        artifactSlots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            artifact: z.ZodString;
+            direction: z.ZodEnum<{
+                read: "read";
+                write: "write";
+                readwrite: "readwrite";
+            }>;
+        }, z.core.$strip>]>>>;
+        riskLevel: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+        idempotent: z.ZodOptional<z.ZodBoolean>;
+        requiresConfirmation: z.ZodOptional<z.ZodBoolean>;
+        execution: z.ZodOptional<z.ZodObject<{
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            costCeilingUsd: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        memoryRef: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodBoolean>;
+            output: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ComponentDSL = z.infer<typeof ComponentSchema>;
+type OperationDSL = z.infer<typeof OperationSchema>;
+type OptionDSL = z.infer<typeof OptionSchema>;
+type JSONSchemaRefDSL = z.infer<typeof JSONSchemaRefSchema>;
+
+declare class ComponentParseError extends Error {
+    readonly filePath?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, filePath?: string | undefined, cause?: unknown | undefined);
+}
+/**
+ * Parse and validate a component YAML string.
+ * When `filePath` is provided, `$ref` pointers resolve relative to its directory.
+ */
+declare function parseComponentString(content: string, filePath?: string): ComponentDSL;
+/**
+ * Read a component YAML file, resolve `$ref` pointers, and validate.
+ */
+declare function parseComponentFile(filePath: string): Promise<ComponentDSL>;
+
+/** JSON Schema object (resolved, JSON-serializable). */
+type JSONSchema = Record<string, unknown>;
+/** Resolved JSON Schema reference — inline schema or resolved $ref target. */
+type JSONSchemaRef = {
+    schema: JSONSchema;
+} | {
+    $ref: string;
+} | JSONSchema;
+type ProjectionTarget = "library" | "cli" | "mcp" | "claude" | "openai";
+type ArtifactDirection = "read" | "write" | "readwrite";
+type RiskLevel = "low" | "medium" | "high";
+interface OptionIR {
     name: string;
-    version: string;
+    schema: JSONSchema;
+    required: boolean;
+    description?: string;
+}
+interface OperationMemoryRefConfig {
+    input?: boolean;
+    output?: boolean;
+}
+interface OperationIR {
+    description: string;
+    agentWorkflow?: string;
+    agentTask?: string;
+    handler?: string;
+    memoryRef?: OperationMemoryRefConfig;
+    options: OptionIR[];
+    input?: JSONSchemaRef;
+    output: {
+        success: JSONSchemaRef;
+        failed?: JSONSchemaRef;
+    };
+    errorModel: {
+        failureClasses: string[];
+    };
+    artifactSlots: Record<string, {
+        artifact: string;
+        direction: ArtifactDirection;
+    }>;
+    riskLevel: RiskLevel;
+    idempotent: boolean;
+    requiresConfirmation: boolean;
+    execution: {
+        timeoutMs?: number;
+        costCeilingUsd?: number;
+    };
+}
+interface ComponentIR {
+    schema: string;
+    info: {
+        id: string;
+        version: string;
+        description?: string;
+    };
+    implementation?: string;
+    projections: ProjectionTarget[];
+    operations: Record<string, OperationIR>;
+}
+
+declare class ComponentCompileError extends Error {
+    constructor(message: string);
+}
+declare class ComponentValidationError extends ComponentCompileError {
+    constructor(message: string);
+}
+
+/**
+ * Extract failure class names from a resolved failed output schema.
+ *
+ * Checks, in order:
+ * 1. Top-level `failure_classes` array
+ * 2. `properties.failure_class.enum`
+ * 3. `oneOf` entries with `const` or `properties.failure_class.const`
+ */
+declare function extractFailureClasses(failedRef: JSONSchemaRef | undefined): string[];
+interface CompileComponentOptions {
+    basePath?: string;
+    /** When true (default), validate implementation file and agent workflow/task IDs. */
+    validate?: boolean;
+}
+/**
+ * Compile a validated Component DSL into Component IR.
+ */
+declare function compileComponent(dsl: ComponentDSL, options?: CompileComponentOptions): ComponentIR;
+/**
+ * Compile a validated Component DSL into Component IR, optionally validating
+ * implementation references.
+ */
+declare function compileComponentAsync(dsl: ComponentDSL, options?: CompileComponentOptions): Promise<ComponentIR>;
+/**
+ * Parse a component YAML file and compile it to IR.
+ */
+declare function compileComponentFile(filePath: string, options?: Omit<CompileComponentOptions, "basePath">): Promise<ComponentIR>;
+
+interface ValidationOptions {
+    /** Base directory for resolving relative implementation paths. */
+    basePath: string;
+}
+interface ImplementationIds {
+    workflowIds: string[];
+    taskIds: string[];
 }
+/**
+ * Extract workflow and task IDs from a parsed agent-contracts DSL document.
+ *
+ * Looks for top-level `workflows` / `tasks` keys (map of ID → definition).
+ */
+declare function extractImplementationIds(content: unknown): ImplementationIds;
+/**
+ * Validate a compiled Component IR against its implementation DSL.
+ *
+ * Checks:
+ * - implementation file exists (when specified)
+ * - agentWorkflow IDs exist in implementation DSL
+ * - agentTask IDs exist in implementation DSL
+ */
+declare function validateComponent(ir: ComponentIR, options: ValidationOptions): Promise<void>;
+
+declare class RefResolutionError extends Error {
+    readonly ref: string;
+    constructor(ref: string, message: string);
+}
+interface ResolveRefsOptions {
+    basePath?: string;
+}
+/**
+ * Resolves `$ref` pointers within a value tree.
+ *
+ * - Internal refs (`#/path/to/key`) resolve against `root`.
+ * - External file refs (`./path/file.yaml` or `./file.yaml#/pointer`) resolve
+ *   relative to `basePath`.
+ */
+declare function resolveRefs<T>(value: T, options?: ResolveRefsOptions): T;
+
+interface GeneratedFile {
+    path: string;
+    content: string;
+    overwrite: boolean;
+    /** Set when a file is skipped (e.g. existing handler). */
+    warning?: string;
+}
+interface GenerateOptions {
+    outputDir: string;
+    componentPath: string;
+}
+interface Generator {
+    generate(ir: ComponentIR, options: GenerateOptions): GeneratedFile[];
+}
+
+declare const typesGenerator: Generator;
+
+declare const clientGenerator: Generator;
+
+declare const runtimeGenerator: Generator;
+
+declare const cliGenerator: Generator;
+
+declare const handlerGenerator: Generator;
+
+/**
+ * Run all code generators for a compiled Component IR.
+ */
+declare function generateAll(ir: ComponentIR, options: GenerateOptions): GeneratedFile[];
+/**
+ * Write generated files to disk, respecting overwrite policy.
+ * - `overwrite: true` — always write (generated/ artifacts)
+ * - `overwrite: false` — skip if target already exists (handlers, cli stub)
+ */
+declare function writeGeneratedFiles(files: GeneratedFile[], outputDir: string): Promise<{
+    written: string[];
+    skipped: string[];
+    warnings: string[];
+}>;
+
+/** Package version string. */
+declare const version: string;
 
-export { type ContractDefinition, version };
+export { type ArtifactDirection, ArtifactSlotValueSchema, type CompileComponentOptions, ComponentCompileError, type ComponentDSL, type ComponentIR, ComponentParseError, ComponentSchema, ComponentValidationError, type GenerateOptions, type GeneratedFile, type Generator, type ImplementationIds, type JSONSchema, type JSONSchemaRef, type JSONSchemaRefDSL, JSONSchemaRefSchema, type OperationDSL, type OperationIR, OperationSchema, type OptionDSL, type OptionIR, OptionSchema, type ProjectionTarget, RefResolutionError, type RiskLevel, SCHEMA_VERSION_PATTERN, SUPPORTED_SCHEMA_VERSIONS, type ValidationOptions, cliGenerator, clientGenerator, compileComponent, compileComponentAsync, compileComponentFile, extractFailureClasses, extractImplementationIds, generateAll, handlerGenerator, parseComponentFile, parseComponentString, resolveRefs, runtimeGenerator, typesGenerator, validateComponent, version, writeGeneratedFiles };

package/dist/index.js

@@ -1,6 +1,66 @@
+import {
+  ArtifactSlotValueSchema,
+  ComponentCompileError,
+  ComponentParseError,
+  ComponentSchema,
+  ComponentValidationError,
+  JSONSchemaRefSchema,
+  OperationSchema,
+  OptionSchema,
+  RefResolutionError,
+  SCHEMA_VERSION_PATTERN,
+  SUPPORTED_SCHEMA_VERSIONS,
+  cliGenerator,
+  clientGenerator,
+  compileComponent,
+  compileComponentAsync,
+  compileComponentFile,
+  extractFailureClasses,
+  extractImplementationIds,
+  generateAll,
+  handlerGenerator,
+  parseComponentFile,
+  parseComponentString,
+  resolveRefs,
+  runtimeGenerator,
+  typesGenerator,
+  validateComponent,
+  writeGeneratedFiles
+} from "./chunk-MMFA6S5O.js";
+
 // src/index.ts
-var version = "0.0.1";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var version = pkg.version;
 export {
-  version
+  ArtifactSlotValueSchema,
+  ComponentCompileError,
+  ComponentParseError,
+  ComponentSchema,
+  ComponentValidationError,
+  JSONSchemaRefSchema,
+  OperationSchema,
+  OptionSchema,
+  RefResolutionError,
+  SCHEMA_VERSION_PATTERN,
+  SUPPORTED_SCHEMA_VERSIONS,
+  cliGenerator,
+  clientGenerator,
+  compileComponent,
+  compileComponentAsync,
+  compileComponentFile,
+  extractFailureClasses,
+  extractImplementationIds,
+  generateAll,
+  handlerGenerator,
+  parseComponentFile,
+  parseComponentString,
+  resolveRefs,
+  runtimeGenerator,
+  typesGenerator,
+  validateComponent,
+  version,
+  writeGeneratedFiles
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/** Package version string. */\nexport const version = \"0.0.1\";\n\n/** Minimal contract definition placeholder. */\nexport interface ContractDefinition {\n  name: string;\n  version: string;\n}\n"],"mappings":";AACO,IAAM,UAAU;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createRequire } from \"node:module\";\n\nconst require = createRequire(import.meta.url);\nconst pkg = require(\"../package.json\") as { version: string };\n\n/** Package version string. */\nexport const version = pkg.version;\n\nexport {\n  ComponentSchema,\n  OperationSchema,\n  OptionSchema,\n  JSONSchemaRefSchema,\n  ArtifactSlotValueSchema,\n  SUPPORTED_SCHEMA_VERSIONS,\n  SCHEMA_VERSION_PATTERN,\n  type ComponentDSL,\n  type OperationDSL,\n  type OptionDSL,\n  type JSONSchemaRefDSL,\n} from \"./schema.js\";\n\nexport {\n  parseComponentFile,\n  parseComponentString,\n  ComponentParseError,\n} from \"./parser.js\";\n\nexport type {\n  ComponentIR,\n  OperationIR,\n  OptionIR,\n  JSONSchema,\n  JSONSchemaRef,\n  ProjectionTarget,\n  ArtifactDirection,\n  RiskLevel,\n} from \"./ir.js\";\n\nexport {\n  compileComponent,\n  compileComponentAsync,\n  compileComponentFile,\n  extractFailureClasses,\n  ComponentCompileError,\n  type CompileComponentOptions,\n} from \"./compiler.js\";\n\nexport {\n  validateComponent,\n  extractImplementationIds,\n  ComponentValidationError,\n  type ValidationOptions,\n  type ImplementationIds,\n} from \"./validation.js\";\n\nexport { resolveRefs, RefResolutionError } from \"./ref-resolver.js\";\n\nexport {\n  generateAll,\n  writeGeneratedFiles,\n  typesGenerator,\n  clientGenerator,\n  runtimeGenerator,\n  cliGenerator,\n  handlerGenerator,\n  type GeneratedFile,\n  type GenerateOptions,\n  type Generator,\n} from \"./generators/index.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,SAAS,qBAAqB;AAE9B,IAAMA,WAAU,cAAc,YAAY,GAAG;AAC7C,IAAM,MAAMA,SAAQ,iBAAiB;AAG9B,IAAM,UAAU,IAAI;","names":["require"]}

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@aaac/contracts",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Contract definitions for the AAAC (Agent-Assisted Architecture Contracts) toolchain",
   "type": "module",
+  "bin": {
+    "aaac": "./dist/cli/index.js"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -20,6 +23,8 @@
     "build": "tsup",
     "clean": "rm -rf dist",
     "test": "vitest run",
+    "contract:validate": "cli-contracts validate",
+    "contract:generate": "cli-contracts generate",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "publishConfig": {
@@ -33,5 +38,16 @@
   "license": "MIT",
   "engines": {
     "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "cli-contracts": "^0.32.3",
+    "commander": "^15.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
   }
 }