diff --git a/cli-contract.yaml b/cli-contract.yaml index 0a84953..2068729 100644 --- a/cli-contract.yaml +++ b/cli-contract.yaml @@ -3,7 +3,7 @@ cli_contracts: 0.1.0 info: title: micro-contracts CLI - version: 0.15.0 + version: 0.17.10 description: >- Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients @@ -933,6 +933,7 @@ command_sets: idempotent: true x-agent: + dsl_task: audit-openapi-design expectedDurationMs: 120000 retryableExitCodes: [12] @@ -1061,6 +1062,7 @@ command_sets: idempotent: true x-agent: + dsl_task: audit-published-api expectedDurationMs: 120000 retryableExitCodes: [12] @@ -1190,6 +1192,7 @@ command_sets: idempotent: true x-agent: + dsl_task: propose-overlay-candidates expectedDurationMs: 120000 retryableExitCodes: [12] @@ -1323,6 +1326,7 @@ command_sets: idempotent: true x-agent: + dsl_task: audit-guardrails-coverage expectedDurationMs: 120000 retryableExitCodes: [12] diff --git a/docs/cli-reference.md b/docs/cli-reference.md index f8240ca..bbfb295 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -2,7 +2,7 @@ Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients from OpenAPI specifications with enforceable guardrails. -**Version:** 0.15.0 +**Version:** 0.17.10 ## Table of Contents @@ -630,6 +630,7 @@ micro-contracts audit-openapi --show-prompt ```yaml x-agent: + dsl_task: audit-openapi-design expectedDurationMs: 120000 retryableExitCodes: - 12 @@ -698,6 +699,7 @@ micro-contracts review-published --adapter claude --report-format json ```yaml x-agent: + dsl_task: audit-published-api expectedDurationMs: 120000 retryableExitCodes: - 12 @@ -766,6 +768,7 @@ micro-contracts propose-overlays --adapter openai --report-format json ```yaml x-agent: + dsl_task: propose-overlay-candidates expectedDurationMs: 120000 retryableExitCodes: - 12 @@ -831,6 +834,7 @@ micro-contracts audit-guardrails --adapter mock --report-format json ```yaml x-agent: + dsl_task: audit-guardrails-coverage expectedDurationMs: 120000 retryableExitCodes: - 12 diff --git a/examples/packages/.generated-manifest.json b/examples/packages/.generated-manifest.json index 5bcc7f3..d78ed53 100644 --- a/examples/packages/.generated-manifest.json +++ b/examples/packages/.generated-manifest.json @@ -1,6 +1,6 @@ { "version": "1.0", - "generatorVersion": "0.17.9", + "generatorVersion": "0.17.10", "files": { "contract-published/billing/docs/api-reference.html": { "sha256": "5b69e88fc9f60578261a8231132678550a40a70eb52dfcc611f48937f448ca44" @@ -144,6 +144,6 @@ "sha256": "d791f51b36215aba3e7cf7c5f69fc4b9fd6d4f2cf515718fdc93589fa05e2608" } }, - "inputHash": "b0a2477d56cac19d923f7bc82fafcdae5e8c1fda2f6d2d333e1803457279da72", - "updatedAt": "2026-06-06T17:28:35.552Z" + "inputHash": "dc8b577380034ddd95c7deda27cf6084a16dc879af579db1d9fba2b7b24c61de", + "updatedAt": "2026-06-07T06:02:07.134Z" } diff --git a/package.json b/package.json index d211760..e1b17db 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "micro-contracts", - "version": "0.17.9", + "version": "0.17.10", "description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation", "type": "module", "main": "dist/index.js", diff --git a/src/agents/index.ts b/src/agents/index.ts index 9ad6a0b..2b9e31b 100644 --- a/src/agents/index.ts +++ b/src/agents/index.ts @@ -1,4 +1,5 @@ export { runAgentTask, EXIT_RUNTIME_MISSING, EXIT_ADAPTER_ERROR } from "./orchestrator.js"; export { computeExitCode, formatResultText, formatResultJson, formatResultYaml, formatResult, writeOutput } from "./formatter.js"; export type { ReportFormat } from "./formatter.js"; +export { TASK_IDS } from "./types.js"; export type { TaskId, AuditConfig, AuditOptions, AuditRunResult } from "./types.js"; diff --git a/src/agents/types.ts b/src/agents/types.ts index 2bbe7a5..76b9f4a 100644 --- a/src/agents/types.ts +++ b/src/agents/types.ts @@ -1,10 +1,14 @@ import type { OpenapiAuditResult } from "../generated/dsl/handoffs.js"; +import { taskRegistry } from "../generated/dsl/tasks.js"; -export type TaskId = - | "audit-openapi-design" - | "audit-published-api" - | "propose-overlay-candidates" - | "audit-guardrails-coverage"; +export type TaskId = keyof typeof taskRegistry; + +export const TASK_IDS = { + auditOpenapi: "audit-openapi-design", + reviewPublished: "audit-published-api", + proposeOverlays: "propose-overlay-candidates", + auditGuardrails: "audit-guardrails-coverage", +} as const satisfies Record; export interface AuditConfig { adapter?: string; diff --git a/src/commands/audit-guardrails.ts b/src/commands/audit-guardrails.ts index ef25ba6..8087561 100644 --- a/src/commands/audit-guardrails.ts +++ b/src/commands/audit-guardrails.ts @@ -2,6 +2,7 @@ import chalk from "chalk"; import { buildAuditGuardrailsContext } from "../agents/context-builder.js"; import { runAgentTask, + TASK_IDS, computeExitCode, formatResult, writeOutput, @@ -40,7 +41,7 @@ export async function commandAuditGuardrails(opts: CommandAuditGuardrailsOptions try { const result = await runAgentTask( context, - "audit-guardrails-coverage", + TASK_IDS.auditGuardrails, auditConfig, auditOpts, ); diff --git a/src/commands/audit-openapi.ts b/src/commands/audit-openapi.ts index 7ff23c1..905f51f 100644 --- a/src/commands/audit-openapi.ts +++ b/src/commands/audit-openapi.ts @@ -2,6 +2,7 @@ import chalk from "chalk"; import { buildAuditOpenapiContext } from "../agents/context-builder.js"; import { runAgentTask, + TASK_IDS, computeExitCode, formatResult, writeOutput, @@ -40,7 +41,7 @@ export async function commandAuditOpenapi(opts: CommandAuditOpenapiOptions): Pro try { const result = await runAgentTask( context, - "audit-openapi-design", + TASK_IDS.auditOpenapi, auditConfig, auditOpts, ); diff --git a/src/commands/propose-overlays.ts b/src/commands/propose-overlays.ts index 6a27773..85a956b 100644 --- a/src/commands/propose-overlays.ts +++ b/src/commands/propose-overlays.ts @@ -2,6 +2,7 @@ import chalk from "chalk"; import { buildProposeOverlaysContext } from "../agents/context-builder.js"; import { runAgentTask, + TASK_IDS, computeExitCode, formatResult, writeOutput, @@ -40,7 +41,7 @@ export async function commandProposeOverlays(opts: CommandProposeOverlaysOptions try { const result = await runAgentTask( context, - "propose-overlay-candidates", + TASK_IDS.proposeOverlays, auditConfig, auditOpts, ); diff --git a/src/commands/review-published.ts b/src/commands/review-published.ts index e3c9f23..619b12d 100644 --- a/src/commands/review-published.ts +++ b/src/commands/review-published.ts @@ -2,6 +2,7 @@ import chalk from "chalk"; import { buildReviewPublishedContext } from "../agents/context-builder.js"; import { runAgentTask, + TASK_IDS, computeExitCode, formatResult, writeOutput, @@ -40,7 +41,7 @@ export async function commandReviewPublished(opts: CommandReviewPublishedOptions try { const result = await runAgentTask( context, - "audit-published-api", + TASK_IDS.reviewPublished, auditConfig, auditOpts, ); diff --git a/src/generated/contract.ts b/src/generated/contract.ts index ecda913..ec4e6f9 100644 --- a/src/generated/contract.ts +++ b/src/generated/contract.ts @@ -1,6 +1,6 @@ // Auto-generated by cli-contracts. Do not edit. // Embedded contract for the extract subcommand. -export const CONTRACT_YAML: string = "# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\ncli_contracts: 0.1.0\n\ninfo:\n title: micro-contracts CLI\n version: 0.15.0\n description: >-\n Contract-first OpenAPI toolchain for TypeScript Web/API systems.\n Generates contract packages, server routes, and frontend clients\n from OpenAPI specifications with enforceable guardrails.\n license:\n name: MIT\n contact:\n name: foo-log-inc\n url: https://github.com/foo-log-inc/micro-contracts\n\nartifact_slots:\n openapi-specs:\n direction: read\n description: OpenAPI specification files\n config:\n direction: read\n description: micro-contracts.config.yaml configuration\n generated-packages:\n direction: write\n description: Generated contract packages, server routes, and frontend clients\n guardrails-config:\n direction: read\n description: guardrails.yaml configuration\n manifest:\n direction: write\n description: Generated manifest (.generated-manifest.json)\n\ncommand_sets:\n micro-contracts:\n summary: Contract-first OpenAPI toolchain for TypeScript.\n executable: micro-contracts\n\n global_options:\n - name: version\n aliases: [V]\n description: Print version and exit.\n schema:\n type: boolean\n\n - name: help\n aliases: [h]\n description: Show help and exit.\n schema:\n type: boolean\n\n commands:\n # ── generate ─────────────────────────────────────\n generate:\n summary: Generate code from OpenAPI specifications.\n description: >-\n Loads the multi-module config, applies overlays, runs Spectral\n linting (unless skipped), and generates contract packages, server\n routes, frontend clients, and documentation from OpenAPI specs.\n Supports input-hash caching to skip unnecessary regeneration.\n usage:\n - micro-contracts generate\n - micro-contracts generate -c my-config.yaml\n - micro-contracts generate -m core,billing\n - micro-contracts generate --contracts-only\n - micro-contracts generate --force\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module names, comma-separated. Generates all modules if omitted.\n value_name: names\n schema:\n type: string\n\n - name: contracts-only\n description: Generate contract packages only.\n schema:\n type: boolean\n default: false\n\n - name: server-only\n description: Generate server routes only.\n schema:\n type: boolean\n default: false\n\n - name: frontend-only\n description: Generate frontend clients only.\n schema:\n type: boolean\n default: false\n\n - name: docs-only\n description: Generate documentation only.\n schema:\n type: boolean\n default: false\n\n - name: skip-lint\n description: Skip Spectral linting before generation.\n schema:\n type: boolean\n default: false\n\n - name: manifest\n description: >-\n Generate manifest after generation. Enabled by default when\n guardrails.yaml has a generated section. Use --no-manifest to disable.\n schema:\n type: boolean\n default: true\n\n - name: manifest-dir\n description: Directory for manifest output.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: force\n description: Bypass input hash cache and always regenerate.\n schema:\n type: boolean\n default: false\n\n - name: cache\n description: >-\n Enable input hash caching. Enabled by default.\n Use --no-cache to disable both reading and writing cache.\n schema:\n type: boolean\n default: true\n\n exits:\n '0':\n description: Generation succeeded.\n stdout:\n format: text\n files:\n - path: packages/contract/{module}/**/*.ts\n required: true\n media_type: text/x-typescript\n encoding: utf-8\n description: Generated contract packages.\n - path: packages/contract-published/{module}/**/*.ts\n required: false\n media_type: text/x-typescript\n encoding: utf-8\n description: Generated public contract packages.\n\n '1':\n description: Generation failed (config not found, spec invalid, or generation error).\n stderr:\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n recommended_before_use:\n - Ensure micro-contracts.config.yaml exists.\n - Verify OpenAPI specs are valid.\n\n # ── lint ─────────────────────────────────────────\n lint:\n summary: Lint OpenAPI specification.\n description: >-\n Validates an OpenAPI specification for x-micro-contracts extension\n violations and structural issues using Spectral rules.\n usage:\n - micro-contracts lint spec/core/openapi/core.yaml\n - micro-contracts lint spec/core/openapi/core.yaml --strict\n\n arguments:\n - name: input\n index: 0\n required: true\n description: Path to OpenAPI spec file.\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: application/yaml\n encoding: utf-8\n\n options:\n - name: strict\n description: Treat warnings as errors.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Spec is valid. No lint errors found.\n stdout:\n format: text\n\n '1':\n description: Lint failed. Errors or warnings (in strict mode) found.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── init ─────────────────────────────────────────\n init:\n summary: Initialize a new module structure with starter templates.\n description: >-\n Creates the directory structure, starter Handlebars templates,\n shared schemas, Spectral rules, and optional config file for\n a new module. Can also process an existing OpenAPI spec to\n auto-add x-micro-contracts extensions.\n usage:\n - micro-contracts init core\n - micro-contracts init core --openapi path/to/spec.yaml\n - micro-contracts init myScreens --screens\n - micro-contracts init users --skip-templates\n\n arguments:\n - name: name\n index: 0\n required: true\n description: Module name (e.g., core, users, billing).\n schema:\n type: string\n\n options:\n - name: dir\n aliases: [d]\n description: Base directory for server/frontend files.\n value_name: path\n schema:\n type: string\n default: src\n\n - name: openapi\n aliases: [i]\n description: OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: application/yaml\n encoding: utf-8\n\n - name: output\n aliases: [o]\n description: Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.\n value_name: path\n schema:\n type: string\n\n - name: skip-templates\n description: Skip creating starter Handlebars templates.\n schema:\n type: boolean\n default: false\n\n - name: screens\n description: Initialize as screen spec module (generates screen templates and starter spec).\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Module initialized successfully.\n stdout:\n format: text\n files:\n - path: spec/{name}/openapi/{name}.yaml\n required: false\n media_type: application/yaml\n encoding: utf-8\n description: OpenAPI spec (created when --openapi provided or --screens used).\n - path: spec/default/templates/*.hbs\n required: false\n media_type: text/x-handlebars-template\n encoding: utf-8\n description: Starter Handlebars templates.\n - path: micro-contracts.config.yaml\n required: false\n media_type: application/yaml\n encoding: utf-8\n description: Config file (created if not already present).\n\n '1':\n description: Initialization failed (OpenAPI file not found or write error).\n stderr:\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n - directory_create\n\n # ── check ────────────────────────────────────────\n check:\n summary: Run guardrail checks.\n description: >-\n Runs AI guardrail checks against generated code and config.\n Supports gating (1-5), selective check execution, auto-fix,\n and CI integration via changed-files input.\n usage:\n - micro-contracts check\n - micro-contracts check --gate 1,2\n - micro-contracts check --only drift,manifest\n - micro-contracts check --fix\n - micro-contracts check --list\n - micro-contracts check --list-gates\n\n options:\n - name: only\n description: Run only specific checks (comma-separated check names).\n value_name: checks\n schema:\n type: string\n\n - name: skip\n description: Skip specific checks (comma-separated check names).\n value_name: checks\n schema:\n type: string\n\n - name: gate\n description: Run checks for specific gates only (comma-separated, 1-5).\n value_name: gates\n schema:\n type: string\n\n - name: verbose\n aliases: [v]\n description: Enable verbose output.\n schema:\n type: boolean\n default: false\n\n - name: fix\n description: Auto-fix issues where possible.\n schema:\n type: boolean\n default: false\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: generated-dir\n aliases: [d]\n description: Path to generated files directory.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: changed-files\n description: Path to file containing list of changed files (for CI).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: text/plain\n encoding: utf-8\n\n - name: list\n description: List available checks and exit.\n schema:\n type: boolean\n default: false\n\n - name: list-gates\n description: List available gates and exit.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: All checks passed (or --list/--list-gates output).\n stdout:\n format: text\n\n '1':\n description: One or more checks failed.\n stdout:\n format: text\n stderr:\n required: false\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n recommended_before_use:\n - Run generate first so generated files exist.\n\n # ── pipeline ─────────────────────────────────────\n pipeline:\n summary: Run full guardrails pipeline.\n description: >-\n Executes the complete contract-first pipeline in order:\n Gate 1,2 (pre-generation checks) → Generate → Gate 3,4,5\n (post-generation checks). Supports --continue-on-error to\n run all steps regardless of failures.\n usage:\n - micro-contracts pipeline\n - micro-contracts pipeline --verbose\n - micro-contracts pipeline --continue-on-error\n - micro-contracts pipeline --contracts-only --skip-lint\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: verbose\n aliases: [v]\n description: Enable verbose output (show detailed logs).\n schema:\n type: boolean\n default: false\n\n - name: skip\n description: Skip specific checks (comma-separated).\n value_name: checks\n schema:\n type: string\n\n - name: continue-on-error\n description: Continue running even if a step fails.\n schema:\n type: boolean\n default: false\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: generated-dir\n aliases: [d]\n description: Path to generated files directory.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: manifest\n description: >-\n Generate manifest after generation. Enabled by default.\n Use --no-manifest to disable.\n schema:\n type: boolean\n default: true\n\n - name: skip-lint\n description: Skip Spectral linting before generation.\n schema:\n type: boolean\n default: false\n\n - name: contracts-only\n description: Generate contract packages only.\n schema:\n type: boolean\n default: false\n\n - name: server-only\n description: Generate server routes only.\n schema:\n type: boolean\n default: false\n\n - name: frontend-only\n description: Generate frontend clients only.\n schema:\n type: boolean\n default: false\n\n - name: docs-only\n description: Generate documentation only.\n schema:\n type: boolean\n default: false\n\n - name: force\n description: Bypass input hash cache and always regenerate.\n schema:\n type: boolean\n default: false\n\n - name: cache\n description: >-\n Enable input hash caching. Enabled by default.\n Use --no-cache to disable both reading and writing cache.\n schema:\n type: boolean\n default: true\n\n exits:\n '0':\n description: Pipeline completed successfully. All gates passed and generation succeeded.\n stdout:\n format: text\n\n '1':\n description: Pipeline failed. One or more steps had errors.\n stdout:\n format: text\n stderr:\n required: false\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n recommended_before_use:\n - Ensure micro-contracts.config.yaml and guardrails.yaml exist.\n - Verify OpenAPI specs are valid.\n\n # ── deps ─────────────────────────────────────────\n deps:\n summary: Analyze module dependencies.\n description: >-\n Reads x-micro-contracts-depend-on declarations from OpenAPI specs\n and config dependsOn fields. Can output dependency graphs (Mermaid),\n impact analysis, reverse lookups, and validation results.\n usage:\n - micro-contracts deps\n - micro-contracts deps --graph\n - micro-contracts deps --module billing\n - micro-contracts deps --impact core.User.getUsers\n - micro-contracts deps --who-depends-on core\n - micro-contracts deps --validate\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module to analyze.\n value_name: name\n schema:\n type: string\n\n - name: graph\n description: Output dependency graph in Mermaid format.\n schema:\n type: boolean\n default: false\n\n - name: impact\n description: Analyze impact of changing a specific API (e.g., core.User.getUsers).\n value_name: ref\n schema:\n type: string\n\n - name: who-depends-on\n description: Find modules that depend on a specific API.\n value_name: ref\n schema:\n type: string\n\n - name: validate\n description: Validate dependencies against OpenAPI declarations.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Dependency analysis completed successfully.\n stdout:\n format: text\n\n '1':\n description: Analysis failed or validation errors found.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── insights ─────────────────────────────────────\n insights:\n summary: Emit ExternalInsight JSON for agent-contracts-analyzer.\n description: >-\n Reads x-micro-contracts-depend-on from OpenAPI specs and outputs\n structured dependency edges and anchor mappings as JSON on stdout.\n Used by agent-contracts-analyzer CommandProvider integration.\n usage:\n - micro-contracts insights --format json\n - micro-contracts insights --format json --project-root .\n\n options:\n - name: format\n description: Output format (json only).\n value_name: format\n schema:\n type: string\n default: json\n\n - name: project-root\n description: Project root directory containing micro-contracts.config.yaml.\n value_name: path\n schema:\n type: string\n default: .\n\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n exits:\n '0':\n description: ExternalInsight JSON written to stdout.\n stdout:\n format: json\n\n '1':\n description: Insights generation failed.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── guardrails-init ──────────────────────────────\n guardrails-init:\n path: [guardrails-init]\n summary: Create a guardrails.yaml configuration file.\n description: >-\n Generates a starter guardrails.yaml with default check\n configuration. Fails if the target file already exists.\n usage:\n - micro-contracts guardrails-init\n - micro-contracts guardrails-init -o custom-guardrails.yaml\n\n options:\n - name: output\n aliases: [o]\n description: Output path for guardrails.yaml.\n value_name: path\n schema:\n type: string\n default: guardrails.yaml\n\n exits:\n '0':\n description: guardrails.yaml created successfully.\n stdout:\n format: text\n files:\n - path: '{options.output}'\n required: true\n media_type: application/yaml\n encoding: utf-8\n\n '1':\n description: Failed to create (file already exists or write error).\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: false\n side_effects:\n - file_write\n\n # ── manifest ─────────────────────────────────────\n manifest:\n summary: Generate or verify manifest for generated artifacts.\n description: >-\n Scans a directory of generated files and produces a\n .generated-manifest.json containing file hashes. In verify\n mode, checks that existing files match the manifest.\n usage:\n - micro-contracts manifest\n - micro-contracts manifest -d packages/\n - micro-contracts manifest --verify\n - micro-contracts manifest -o custom-manifest.json\n\n options:\n - name: dir\n aliases: [d]\n description: Directory to scan.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: verify\n description: Verify existing manifest instead of generating.\n schema:\n type: boolean\n default: false\n\n - name: output\n aliases: [o]\n description: Output manifest path. Defaults to {dir}/.generated-manifest.json.\n value_name: path\n schema:\n type: string\n\n exits:\n '0':\n description: Manifest generated or verification passed.\n stdout:\n format: text\n files:\n - path: '{options.dir}/.generated-manifest.json'\n required: false\n media_type: application/json\n encoding: utf-8\n description: Generated manifest (not created in verify mode).\n\n '1':\n description: Directory not found, manifest generation failed, or verification failed.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n\n # ── audit-openapi ──────────────────────────────\n audit-openapi:\n path: [audit-openapi]\n summary: Run LLM-based OpenAPI design quality audit.\n description: >-\n Performs a semantic review of OpenAPI specification design quality\n using an LLM agent. Evaluates path design, module boundary alignment,\n schema bloat, CRUD vs use-case orientation, and cross-cutting\n concern coverage. Requires agent-contracts-runtime.\n usage:\n - micro-contracts audit-openapi\n - micro-contracts audit-openapi -m core\n - micro-contracts audit-openapi --adapter claude --report-format text\n - micro-contracts audit-openapi --show-prompt\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to audit (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the audit report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Audit completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OpenApiAuditResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed (config not found, spec invalid).\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OpenApiAuditResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── review-published ───────────────────────────\n review-published:\n path: [review-published]\n summary: Review published API surface for internal leakage.\n description: >-\n Analyzes the published (public-facing) API specification for\n internal type leakage, backward compatibility risks, and\n x-micro-contracts-non-exportable violations.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts review-published\n - micro-contracts review-published -m billing\n - micro-contracts review-published --adapter claude --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to review (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the review report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Review completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/PublishedReviewResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed.\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/PublishedReviewResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config, generated-packages]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── propose-overlays ───────────────────────────\n propose-overlays:\n path: [propose-overlays]\n summary: Propose cross-cutting overlay candidates.\n description: >-\n Analyzes the OpenAPI specification and proposes cross-cutting\n overlay candidates for authentication, tenancy, rate limiting,\n audit logging, and other patterns. Verifies proposals do not\n conflict with existing overlay definitions.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts propose-overlays\n - micro-contracts propose-overlays -m core\n - micro-contracts propose-overlays --adapter openai --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to analyze (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the proposal report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: json\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Proposal generated successfully.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OverlayProposalResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed.\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OverlayProposalResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── audit-guardrails ───────────────────────────\n audit-guardrails:\n path: [audit-guardrails]\n summary: Audit guardrails configuration for drift and lint coverage.\n description: >-\n Checks that guardrails.yaml configuration covers all generated\n output directories for drift detection and that OpenAPI lint\n rules are properly configured. Note: file permission and\n editing checks have been moved to artifact-contracts.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts audit-guardrails\n - micro-contracts audit-guardrails --adapter mock --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the audit report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Audit completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/GuardrailsAuditResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed (guardrails.yaml not found).\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/GuardrailsAuditResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [guardrails-config, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\ncomponents:\n schemas:\n # ── AI Agent Interoperability Schemas ──────────────────\n AgentEvidence:\n $ref: 'components.yaml#/schemas/agent-evidence'\n AgentFinding:\n $ref: 'components.yaml#/schemas/agent-finding'\n AgentRecommendedAction:\n $ref: 'components.yaml#/schemas/agent-recommended-action'\n OpenApiAuditResult:\n $ref: 'components.yaml#/schemas/agent-audit-result'\n\n PublishedReviewResult:\n type: object\n description: >-\n Result from review-published command. Contains published endpoint\n enumeration and internal type leakage analysis.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [publishedEndpoints, leakedInternalTypes]\n properties:\n publishedEndpoints:\n type: array\n items:\n type: object\n required: [operationId, path, method]\n properties:\n operationId:\n type: string\n path:\n type: string\n method:\n type: string\n leakedInternalTypes:\n type: array\n items:\n type: object\n required: [schemaName, referencedBy, reason]\n properties:\n schemaName:\n type: string\n referencedBy:\n type: string\n reason:\n type: string\n\n OverlayProposalResult:\n type: object\n description: >-\n Result from propose-overlays command. Contains overlay candidate\n proposals with endpoint, type, rationale, and suggested config.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [overlayCandidates]\n properties:\n overlayCandidates:\n type: array\n items:\n type: object\n required: [endpoint, overlayType, rationale]\n properties:\n endpoint:\n type: string\n overlayType:\n type: string\n enum: [auth, tenancy, rateLimit, auditLog, custom]\n rationale:\n type: string\n suggestedConfig:\n type: object\n additionalProperties: true\n\n GuardrailsAuditResult:\n type: object\n description: >-\n Result from audit-guardrails command. Contains drift detection\n and lint rule coverage analysis.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [coveredPaths, uncoveredPaths]\n properties:\n coveredPaths:\n type: array\n items:\n type: string\n uncoveredPaths:\n type: array\n items:\n type: string\n"; +export const CONTRACT_YAML: string = "# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\ncli_contracts: 0.1.0\n\ninfo:\n title: micro-contracts CLI\n version: 0.17.10\n description: >-\n Contract-first OpenAPI toolchain for TypeScript Web/API systems.\n Generates contract packages, server routes, and frontend clients\n from OpenAPI specifications with enforceable guardrails.\n license:\n name: MIT\n contact:\n name: foo-log-inc\n url: https://github.com/foo-log-inc/micro-contracts\n\nartifact_slots:\n openapi-specs:\n direction: read\n description: OpenAPI specification files\n config:\n direction: read\n description: micro-contracts.config.yaml configuration\n generated-packages:\n direction: write\n description: Generated contract packages, server routes, and frontend clients\n guardrails-config:\n direction: read\n description: guardrails.yaml configuration\n manifest:\n direction: write\n description: Generated manifest (.generated-manifest.json)\n\ncommand_sets:\n micro-contracts:\n summary: Contract-first OpenAPI toolchain for TypeScript.\n executable: micro-contracts\n\n global_options:\n - name: version\n aliases: [V]\n description: Print version and exit.\n schema:\n type: boolean\n\n - name: help\n aliases: [h]\n description: Show help and exit.\n schema:\n type: boolean\n\n commands:\n # ── generate ─────────────────────────────────────\n generate:\n summary: Generate code from OpenAPI specifications.\n description: >-\n Loads the multi-module config, applies overlays, runs Spectral\n linting (unless skipped), and generates contract packages, server\n routes, frontend clients, and documentation from OpenAPI specs.\n Supports input-hash caching to skip unnecessary regeneration.\n usage:\n - micro-contracts generate\n - micro-contracts generate -c my-config.yaml\n - micro-contracts generate -m core,billing\n - micro-contracts generate --contracts-only\n - micro-contracts generate --force\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module names, comma-separated. Generates all modules if omitted.\n value_name: names\n schema:\n type: string\n\n - name: contracts-only\n description: Generate contract packages only.\n schema:\n type: boolean\n default: false\n\n - name: server-only\n description: Generate server routes only.\n schema:\n type: boolean\n default: false\n\n - name: frontend-only\n description: Generate frontend clients only.\n schema:\n type: boolean\n default: false\n\n - name: docs-only\n description: Generate documentation only.\n schema:\n type: boolean\n default: false\n\n - name: skip-lint\n description: Skip Spectral linting before generation.\n schema:\n type: boolean\n default: false\n\n - name: manifest\n description: >-\n Generate manifest after generation. Enabled by default when\n guardrails.yaml has a generated section. Use --no-manifest to disable.\n schema:\n type: boolean\n default: true\n\n - name: manifest-dir\n description: Directory for manifest output.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: force\n description: Bypass input hash cache and always regenerate.\n schema:\n type: boolean\n default: false\n\n - name: cache\n description: >-\n Enable input hash caching. Enabled by default.\n Use --no-cache to disable both reading and writing cache.\n schema:\n type: boolean\n default: true\n\n exits:\n '0':\n description: Generation succeeded.\n stdout:\n format: text\n files:\n - path: packages/contract/{module}/**/*.ts\n required: true\n media_type: text/x-typescript\n encoding: utf-8\n description: Generated contract packages.\n - path: packages/contract-published/{module}/**/*.ts\n required: false\n media_type: text/x-typescript\n encoding: utf-8\n description: Generated public contract packages.\n\n '1':\n description: Generation failed (config not found, spec invalid, or generation error).\n stderr:\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n recommended_before_use:\n - Ensure micro-contracts.config.yaml exists.\n - Verify OpenAPI specs are valid.\n\n # ── lint ─────────────────────────────────────────\n lint:\n summary: Lint OpenAPI specification.\n description: >-\n Validates an OpenAPI specification for x-micro-contracts extension\n violations and structural issues using Spectral rules.\n usage:\n - micro-contracts lint spec/core/openapi/core.yaml\n - micro-contracts lint spec/core/openapi/core.yaml --strict\n\n arguments:\n - name: input\n index: 0\n required: true\n description: Path to OpenAPI spec file.\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: application/yaml\n encoding: utf-8\n\n options:\n - name: strict\n description: Treat warnings as errors.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Spec is valid. No lint errors found.\n stdout:\n format: text\n\n '1':\n description: Lint failed. Errors or warnings (in strict mode) found.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── init ─────────────────────────────────────────\n init:\n summary: Initialize a new module structure with starter templates.\n description: >-\n Creates the directory structure, starter Handlebars templates,\n shared schemas, Spectral rules, and optional config file for\n a new module. Can also process an existing OpenAPI spec to\n auto-add x-micro-contracts extensions.\n usage:\n - micro-contracts init core\n - micro-contracts init core --openapi path/to/spec.yaml\n - micro-contracts init myScreens --screens\n - micro-contracts init users --skip-templates\n\n arguments:\n - name: name\n index: 0\n required: true\n description: Module name (e.g., core, users, billing).\n schema:\n type: string\n\n options:\n - name: dir\n aliases: [d]\n description: Base directory for server/frontend files.\n value_name: path\n schema:\n type: string\n default: src\n\n - name: openapi\n aliases: [i]\n description: OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: application/yaml\n encoding: utf-8\n\n - name: output\n aliases: [o]\n description: Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.\n value_name: path\n schema:\n type: string\n\n - name: skip-templates\n description: Skip creating starter Handlebars templates.\n schema:\n type: boolean\n default: false\n\n - name: screens\n description: Initialize as screen spec module (generates screen templates and starter spec).\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Module initialized successfully.\n stdout:\n format: text\n files:\n - path: spec/{name}/openapi/{name}.yaml\n required: false\n media_type: application/yaml\n encoding: utf-8\n description: OpenAPI spec (created when --openapi provided or --screens used).\n - path: spec/default/templates/*.hbs\n required: false\n media_type: text/x-handlebars-template\n encoding: utf-8\n description: Starter Handlebars templates.\n - path: micro-contracts.config.yaml\n required: false\n media_type: application/yaml\n encoding: utf-8\n description: Config file (created if not already present).\n\n '1':\n description: Initialization failed (OpenAPI file not found or write error).\n stderr:\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n - directory_create\n\n # ── check ────────────────────────────────────────\n check:\n summary: Run guardrail checks.\n description: >-\n Runs AI guardrail checks against generated code and config.\n Supports gating (1-5), selective check execution, auto-fix,\n and CI integration via changed-files input.\n usage:\n - micro-contracts check\n - micro-contracts check --gate 1,2\n - micro-contracts check --only drift,manifest\n - micro-contracts check --fix\n - micro-contracts check --list\n - micro-contracts check --list-gates\n\n options:\n - name: only\n description: Run only specific checks (comma-separated check names).\n value_name: checks\n schema:\n type: string\n\n - name: skip\n description: Skip specific checks (comma-separated check names).\n value_name: checks\n schema:\n type: string\n\n - name: gate\n description: Run checks for specific gates only (comma-separated, 1-5).\n value_name: gates\n schema:\n type: string\n\n - name: verbose\n aliases: [v]\n description: Enable verbose output.\n schema:\n type: boolean\n default: false\n\n - name: fix\n description: Auto-fix issues where possible.\n schema:\n type: boolean\n default: false\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: generated-dir\n aliases: [d]\n description: Path to generated files directory.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: changed-files\n description: Path to file containing list of changed files (for CI).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: true\n media_type: text/plain\n encoding: utf-8\n\n - name: list\n description: List available checks and exit.\n schema:\n type: boolean\n default: false\n\n - name: list-gates\n description: List available gates and exit.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: All checks passed (or --list/--list-gates output).\n stdout:\n format: text\n\n '1':\n description: One or more checks failed.\n stdout:\n format: text\n stderr:\n required: false\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n recommended_before_use:\n - Run generate first so generated files exist.\n\n # ── pipeline ─────────────────────────────────────\n pipeline:\n summary: Run full guardrails pipeline.\n description: >-\n Executes the complete contract-first pipeline in order:\n Gate 1,2 (pre-generation checks) → Generate → Gate 3,4,5\n (post-generation checks). Supports --continue-on-error to\n run all steps regardless of failures.\n usage:\n - micro-contracts pipeline\n - micro-contracts pipeline --verbose\n - micro-contracts pipeline --continue-on-error\n - micro-contracts pipeline --contracts-only --skip-lint\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: verbose\n aliases: [v]\n description: Enable verbose output (show detailed logs).\n schema:\n type: boolean\n default: false\n\n - name: skip\n description: Skip specific checks (comma-separated).\n value_name: checks\n schema:\n type: string\n\n - name: continue-on-error\n description: Continue running even if a step fails.\n schema:\n type: boolean\n default: false\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: generated-dir\n aliases: [d]\n description: Path to generated files directory.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: manifest\n description: >-\n Generate manifest after generation. Enabled by default.\n Use --no-manifest to disable.\n schema:\n type: boolean\n default: true\n\n - name: skip-lint\n description: Skip Spectral linting before generation.\n schema:\n type: boolean\n default: false\n\n - name: contracts-only\n description: Generate contract packages only.\n schema:\n type: boolean\n default: false\n\n - name: server-only\n description: Generate server routes only.\n schema:\n type: boolean\n default: false\n\n - name: frontend-only\n description: Generate frontend clients only.\n schema:\n type: boolean\n default: false\n\n - name: docs-only\n description: Generate documentation only.\n schema:\n type: boolean\n default: false\n\n - name: force\n description: Bypass input hash cache and always regenerate.\n schema:\n type: boolean\n default: false\n\n - name: cache\n description: >-\n Enable input hash caching. Enabled by default.\n Use --no-cache to disable both reading and writing cache.\n schema:\n type: boolean\n default: true\n\n exits:\n '0':\n description: Pipeline completed successfully. All gates passed and generation succeeded.\n stdout:\n format: text\n\n '1':\n description: Pipeline failed. One or more steps had errors.\n stdout:\n format: text\n stderr:\n required: false\n format: text\n\n x-agent:\n risk_level: medium\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n recommended_before_use:\n - Ensure micro-contracts.config.yaml and guardrails.yaml exist.\n - Verify OpenAPI specs are valid.\n\n # ── deps ─────────────────────────────────────────\n deps:\n summary: Analyze module dependencies.\n description: >-\n Reads x-micro-contracts-depend-on declarations from OpenAPI specs\n and config dependsOn fields. Can output dependency graphs (Mermaid),\n impact analysis, reverse lookups, and validation results.\n usage:\n - micro-contracts deps\n - micro-contracts deps --graph\n - micro-contracts deps --module billing\n - micro-contracts deps --impact core.User.getUsers\n - micro-contracts deps --who-depends-on core\n - micro-contracts deps --validate\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module to analyze.\n value_name: name\n schema:\n type: string\n\n - name: graph\n description: Output dependency graph in Mermaid format.\n schema:\n type: boolean\n default: false\n\n - name: impact\n description: Analyze impact of changing a specific API (e.g., core.User.getUsers).\n value_name: ref\n schema:\n type: string\n\n - name: who-depends-on\n description: Find modules that depend on a specific API.\n value_name: ref\n schema:\n type: string\n\n - name: validate\n description: Validate dependencies against OpenAPI declarations.\n schema:\n type: boolean\n default: false\n\n exits:\n '0':\n description: Dependency analysis completed successfully.\n stdout:\n format: text\n\n '1':\n description: Analysis failed or validation errors found.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── insights ─────────────────────────────────────\n insights:\n summary: Emit ExternalInsight JSON for agent-contracts-analyzer.\n description: >-\n Reads x-micro-contracts-depend-on from OpenAPI specs and outputs\n structured dependency edges and anchor mappings as JSON on stdout.\n Used by agent-contracts-analyzer CommandProvider integration.\n usage:\n - micro-contracts insights --format json\n - micro-contracts insights --format json --project-root .\n\n options:\n - name: format\n description: Output format (json only).\n value_name: format\n schema:\n type: string\n default: json\n\n - name: project-root\n description: Project root directory containing micro-contracts.config.yaml.\n value_name: path\n schema:\n type: string\n default: .\n\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n exits:\n '0':\n description: ExternalInsight JSON written to stdout.\n stdout:\n format: json\n\n '1':\n description: Insights generation failed.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects: []\n\n # ── guardrails-init ──────────────────────────────\n guardrails-init:\n path: [guardrails-init]\n summary: Create a guardrails.yaml configuration file.\n description: >-\n Generates a starter guardrails.yaml with default check\n configuration. Fails if the target file already exists.\n usage:\n - micro-contracts guardrails-init\n - micro-contracts guardrails-init -o custom-guardrails.yaml\n\n options:\n - name: output\n aliases: [o]\n description: Output path for guardrails.yaml.\n value_name: path\n schema:\n type: string\n default: guardrails.yaml\n\n exits:\n '0':\n description: guardrails.yaml created successfully.\n stdout:\n format: text\n files:\n - path: '{options.output}'\n required: true\n media_type: application/yaml\n encoding: utf-8\n\n '1':\n description: Failed to create (file already exists or write error).\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: false\n side_effects:\n - file_write\n\n # ── manifest ─────────────────────────────────────\n manifest:\n summary: Generate or verify manifest for generated artifacts.\n description: >-\n Scans a directory of generated files and produces a\n .generated-manifest.json containing file hashes. In verify\n mode, checks that existing files match the manifest.\n usage:\n - micro-contracts manifest\n - micro-contracts manifest -d packages/\n - micro-contracts manifest --verify\n - micro-contracts manifest -o custom-manifest.json\n\n options:\n - name: dir\n aliases: [d]\n description: Directory to scan.\n value_name: path\n schema:\n type: string\n default: packages/\n\n - name: verify\n description: Verify existing manifest instead of generating.\n schema:\n type: boolean\n default: false\n\n - name: output\n aliases: [o]\n description: Output manifest path. Defaults to {dir}/.generated-manifest.json.\n value_name: path\n schema:\n type: string\n\n exits:\n '0':\n description: Manifest generated or verification passed.\n stdout:\n format: text\n files:\n - path: '{options.dir}/.generated-manifest.json'\n required: false\n media_type: application/json\n encoding: utf-8\n description: Generated manifest (not created in verify mode).\n\n '1':\n description: Directory not found, manifest generation failed, or verification failed.\n stderr:\n format: text\n\n x-agent:\n risk_level: low\n requires_confirmation: false\n idempotent: true\n side_effects:\n - file_write\n\n # ── audit-openapi ──────────────────────────────\n audit-openapi:\n path: [audit-openapi]\n summary: Run LLM-based OpenAPI design quality audit.\n description: >-\n Performs a semantic review of OpenAPI specification design quality\n using an LLM agent. Evaluates path design, module boundary alignment,\n schema bloat, CRUD vs use-case orientation, and cross-cutting\n concern coverage. Requires agent-contracts-runtime.\n usage:\n - micro-contracts audit-openapi\n - micro-contracts audit-openapi -m core\n - micro-contracts audit-openapi --adapter claude --report-format text\n - micro-contracts audit-openapi --show-prompt\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to audit (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the audit report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Audit completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OpenApiAuditResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed (config not found, spec invalid).\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OpenApiAuditResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n dsl_task: audit-openapi-design\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── review-published ───────────────────────────\n review-published:\n path: [review-published]\n summary: Review published API surface for internal leakage.\n description: >-\n Analyzes the published (public-facing) API specification for\n internal type leakage, backward compatibility risks, and\n x-micro-contracts-non-exportable violations.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts review-published\n - micro-contracts review-published -m billing\n - micro-contracts review-published --adapter claude --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to review (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the review report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Review completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/PublishedReviewResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed.\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/PublishedReviewResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config, generated-packages]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n dsl_task: audit-published-api\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── propose-overlays ───────────────────────────\n propose-overlays:\n path: [propose-overlays]\n summary: Propose cross-cutting overlay candidates.\n description: >-\n Analyzes the OpenAPI specification and proposes cross-cutting\n overlay candidates for authentication, tenancy, rate limiting,\n audit logging, and other patterns. Verifies proposals do not\n conflict with existing overlay definitions.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts propose-overlays\n - micro-contracts propose-overlays -m core\n - micro-contracts propose-overlays --adapter openai --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: module\n aliases: [m]\n description: Module name to analyze (default is all modules).\n value_name: name\n schema:\n type: string\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the proposal report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: json\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Proposal generated successfully.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OverlayProposalResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed.\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/OverlayProposalResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [openapi-specs, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n dsl_task: propose-overlay-candidates\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\n # ── audit-guardrails ───────────────────────────\n audit-guardrails:\n path: [audit-guardrails]\n summary: Audit guardrails configuration for drift and lint coverage.\n description: >-\n Checks that guardrails.yaml configuration covers all generated\n output directories for drift detection and that OpenAPI lint\n rules are properly configured. Note: file permission and\n editing checks have been moved to artifact-contracts.\n Requires agent-contracts-runtime.\n usage:\n - micro-contracts audit-guardrails\n - micro-contracts audit-guardrails --adapter mock --report-format json\n\n options:\n - name: config\n aliases: [c]\n description: Path to config file (micro-contracts.config.yaml).\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: guardrails\n aliases: [g]\n description: Path to guardrails.yaml.\n value_name: path\n schema:\n type: string\n file:\n mode: read\n exists: false\n media_type: application/yaml\n encoding: utf-8\n\n - name: adapter\n aliases: [a]\n description: SDK adapter to use for LLM execution.\n value_name: name\n schema:\n type: string\n enum: [claude, openai, gemini, mock]\n\n - name: model\n description: LLM model override.\n value_name: name\n schema:\n type: string\n\n - name: fail-on\n description: Minimum severity that causes a non-zero exit.\n value_name: level\n schema:\n type: string\n enum: [warning, error, critical]\n default: error\n\n - name: output\n aliases: [o]\n description: Write result to a file instead of stdout.\n value_name: file\n schema:\n type: string\n file:\n mode: write\n media_type: application/json\n encoding: utf-8\n\n - name: report-format\n description: Output format for the audit report.\n value_name: fmt\n schema:\n type: string\n enum: [json, text, yaml]\n default: text\n\n - name: log-file\n aliases: [l]\n description: Write agent progress log to this file path.\n schema:\n type: string\n\n exits:\n '0':\n description: Audit completed, no blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/GuardrailsAuditResult'\n\n '1':\n description: Unexpected error.\n stderr:\n format: text\n\n '3':\n description: Input validation failed (guardrails.yaml not found).\n stderr:\n format: text\n\n '10':\n description: Completed with blocking findings.\n stdout:\n format: '{options.report-format}'\n schema:\n $ref: '#/components/schemas/GuardrailsAuditResult'\n\n '11':\n description: Runtime dependency missing (agent-contracts-runtime).\n stderr:\n format: text\n\n '12':\n description: LLM provider or adapter error.\n stderr:\n format: text\n\n effects:\n reads: [guardrails-config, config]\n writes: []\n network:\n description: LLM API calls when adapter is not mock\n requires_secrets: []\n idempotent: true\n\n x-agent:\n dsl_task: audit-guardrails-coverage\n expectedDurationMs: 120000\n retryableExitCodes: [12]\n\ncomponents:\n schemas:\n # ── AI Agent Interoperability Schemas ──────────────────\n AgentEvidence:\n $ref: 'components.yaml#/schemas/agent-evidence'\n AgentFinding:\n $ref: 'components.yaml#/schemas/agent-finding'\n AgentRecommendedAction:\n $ref: 'components.yaml#/schemas/agent-recommended-action'\n OpenApiAuditResult:\n $ref: 'components.yaml#/schemas/agent-audit-result'\n\n PublishedReviewResult:\n type: object\n description: >-\n Result from review-published command. Contains published endpoint\n enumeration and internal type leakage analysis.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [publishedEndpoints, leakedInternalTypes]\n properties:\n publishedEndpoints:\n type: array\n items:\n type: object\n required: [operationId, path, method]\n properties:\n operationId:\n type: string\n path:\n type: string\n method:\n type: string\n leakedInternalTypes:\n type: array\n items:\n type: object\n required: [schemaName, referencedBy, reason]\n properties:\n schemaName:\n type: string\n referencedBy:\n type: string\n reason:\n type: string\n\n OverlayProposalResult:\n type: object\n description: >-\n Result from propose-overlays command. Contains overlay candidate\n proposals with endpoint, type, rationale, and suggested config.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [overlayCandidates]\n properties:\n overlayCandidates:\n type: array\n items:\n type: object\n required: [endpoint, overlayType, rationale]\n properties:\n endpoint:\n type: string\n overlayType:\n type: string\n enum: [auth, tenancy, rateLimit, auditLog, custom]\n rationale:\n type: string\n suggestedConfig:\n type: object\n additionalProperties: true\n\n GuardrailsAuditResult:\n type: object\n description: >-\n Result from audit-guardrails command. Contains drift detection\n and lint rule coverage analysis.\n allOf:\n - $ref: 'components.yaml#/schemas/agent-audit-result'\n - type: object\n required: [coveredPaths, uncoveredPaths]\n properties:\n coveredPaths:\n type: array\n items:\n type: string\n uncoveredPaths:\n type: array\n items:\n type: string\n"; -export const CONTRACT_JSON_STR: string = "{\n \"cli_contracts\": \"0.1.0\",\n \"info\": {\n \"title\": \"micro-contracts CLI\",\n \"version\": \"0.15.0\",\n \"description\": \"Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients from OpenAPI specifications with enforceable guardrails.\",\n \"license\": {\n \"name\": \"MIT\"\n },\n \"contact\": {\n \"name\": \"foo-log-inc\",\n \"url\": \"https://github.com/foo-log-inc/micro-contracts\"\n }\n },\n \"artifact_slots\": {\n \"openapi-specs\": {\n \"direction\": \"read\",\n \"description\": \"OpenAPI specification files\"\n },\n \"config\": {\n \"direction\": \"read\",\n \"description\": \"micro-contracts.config.yaml configuration\"\n },\n \"generated-packages\": {\n \"direction\": \"write\",\n \"description\": \"Generated contract packages, server routes, and frontend clients\"\n },\n \"guardrails-config\": {\n \"direction\": \"read\",\n \"description\": \"guardrails.yaml configuration\"\n },\n \"manifest\": {\n \"direction\": \"write\",\n \"description\": \"Generated manifest (.generated-manifest.json)\"\n }\n },\n \"command_sets\": {\n \"micro-contracts\": {\n \"summary\": \"Contract-first OpenAPI toolchain for TypeScript.\",\n \"executable\": \"micro-contracts\",\n \"global_options\": [\n {\n \"name\": \"version\",\n \"aliases\": [\n \"V\"\n ],\n \"description\": \"Print version and exit.\",\n \"schema\": {\n \"type\": \"boolean\"\n }\n },\n {\n \"name\": \"help\",\n \"aliases\": [\n \"h\"\n ],\n \"description\": \"Show help and exit.\",\n \"schema\": {\n \"type\": \"boolean\"\n }\n }\n ],\n \"commands\": {\n \"generate\": {\n \"summary\": \"Generate code from OpenAPI specifications.\",\n \"description\": \"Loads the multi-module config, applies overlays, runs Spectral linting (unless skipped), and generates contract packages, server routes, frontend clients, and documentation from OpenAPI specs. Supports input-hash caching to skip unnecessary regeneration.\",\n \"usage\": [\n \"micro-contracts generate\",\n \"micro-contracts generate -c my-config.yaml\",\n \"micro-contracts generate -m core,billing\",\n \"micro-contracts generate --contracts-only\",\n \"micro-contracts generate --force\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module names, comma-separated. Generates all modules if omitted.\",\n \"value_name\": \"names\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"contracts-only\",\n \"description\": \"Generate contract packages only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"server-only\",\n \"description\": \"Generate server routes only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"frontend-only\",\n \"description\": \"Generate frontend clients only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"docs-only\",\n \"description\": \"Generate documentation only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"skip-lint\",\n \"description\": \"Skip Spectral linting before generation.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"manifest\",\n \"description\": \"Generate manifest after generation. Enabled by default when guardrails.yaml has a generated section. Use --no-manifest to disable.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n },\n {\n \"name\": \"manifest-dir\",\n \"description\": \"Directory for manifest output.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"force\",\n \"description\": \"Bypass input hash cache and always regenerate.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"cache\",\n \"description\": \"Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Generation succeeded.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"packages/contract/{module}/**/*.ts\",\n \"required\": true,\n \"media_type\": \"text/x-typescript\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated contract packages.\"\n },\n {\n \"path\": \"packages/contract-published/{module}/**/*.ts\",\n \"required\": false,\n \"media_type\": \"text/x-typescript\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated public contract packages.\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Generation failed (config not found, spec invalid, or generation error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ],\n \"recommended_before_use\": [\n \"Ensure micro-contracts.config.yaml exists.\",\n \"Verify OpenAPI specs are valid.\"\n ]\n }\n },\n \"lint\": {\n \"summary\": \"Lint OpenAPI specification.\",\n \"description\": \"Validates an OpenAPI specification for x-micro-contracts extension violations and structural issues using Spectral rules.\",\n \"usage\": [\n \"micro-contracts lint spec/core/openapi/core.yaml\",\n \"micro-contracts lint spec/core/openapi/core.yaml --strict\"\n ],\n \"arguments\": [\n {\n \"name\": \"input\",\n \"index\": 0,\n \"required\": true,\n \"description\": \"Path to OpenAPI spec file.\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n }\n ],\n \"options\": [\n {\n \"name\": \"strict\",\n \"description\": \"Treat warnings as errors.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Spec is valid. No lint errors found.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Lint failed. Errors or warnings (in strict mode) found.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"init\": {\n \"summary\": \"Initialize a new module structure with starter templates.\",\n \"description\": \"Creates the directory structure, starter Handlebars templates, shared schemas, Spectral rules, and optional config file for a new module. Can also process an existing OpenAPI spec to auto-add x-micro-contracts extensions.\",\n \"usage\": [\n \"micro-contracts init core\",\n \"micro-contracts init core --openapi path/to/spec.yaml\",\n \"micro-contracts init myScreens --screens\",\n \"micro-contracts init users --skip-templates\"\n ],\n \"arguments\": [\n {\n \"name\": \"name\",\n \"index\": 0,\n \"required\": true,\n \"description\": \"Module name (e.g., core, users, billing).\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"options\": [\n {\n \"name\": \"dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Base directory for server/frontend files.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"src\"\n }\n },\n {\n \"name\": \"openapi\",\n \"aliases\": [\n \"i\"\n ],\n \"description\": \"OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"skip-templates\",\n \"description\": \"Skip creating starter Handlebars templates.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"screens\",\n \"description\": \"Initialize as screen spec module (generates screen templates and starter spec).\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Module initialized successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"spec/{name}/openapi/{name}.yaml\",\n \"required\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\",\n \"description\": \"OpenAPI spec (created when --openapi provided or --screens used).\"\n },\n {\n \"path\": \"spec/default/templates/*.hbs\",\n \"required\": false,\n \"media_type\": \"text/x-handlebars-template\",\n \"encoding\": \"utf-8\",\n \"description\": \"Starter Handlebars templates.\"\n },\n {\n \"path\": \"micro-contracts.config.yaml\",\n \"required\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\",\n \"description\": \"Config file (created if not already present).\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Initialization failed (OpenAPI file not found or write error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\",\n \"directory_create\"\n ]\n }\n },\n \"check\": {\n \"summary\": \"Run guardrail checks.\",\n \"description\": \"Runs AI guardrail checks against generated code and config. Supports gating (1-5), selective check execution, auto-fix, and CI integration via changed-files input.\",\n \"usage\": [\n \"micro-contracts check\",\n \"micro-contracts check --gate 1,2\",\n \"micro-contracts check --only drift,manifest\",\n \"micro-contracts check --fix\",\n \"micro-contracts check --list\",\n \"micro-contracts check --list-gates\"\n ],\n \"options\": [\n {\n \"name\": \"only\",\n \"description\": \"Run only specific checks (comma-separated check names).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"skip\",\n \"description\": \"Skip specific checks (comma-separated check names).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"gate\",\n \"description\": \"Run checks for specific gates only (comma-separated, 1-5).\",\n \"value_name\": \"gates\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"verbose\",\n \"aliases\": [\n \"v\"\n ],\n \"description\": \"Enable verbose output.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"fix\",\n \"description\": \"Auto-fix issues where possible.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"generated-dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Path to generated files directory.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"changed-files\",\n \"description\": \"Path to file containing list of changed files (for CI).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"text/plain\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"list\",\n \"description\": \"List available checks and exit.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"list-gates\",\n \"description\": \"List available gates and exit.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"All checks passed (or --list/--list-gates output).\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"One or more checks failed.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"stderr\": {\n \"required\": false,\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [],\n \"recommended_before_use\": [\n \"Run generate first so generated files exist.\"\n ]\n }\n },\n \"pipeline\": {\n \"summary\": \"Run full guardrails pipeline.\",\n \"description\": \"Executes the complete contract-first pipeline in order: Gate 1,2 (pre-generation checks) → Generate → Gate 3,4,5 (post-generation checks). Supports --continue-on-error to run all steps regardless of failures.\",\n \"usage\": [\n \"micro-contracts pipeline\",\n \"micro-contracts pipeline --verbose\",\n \"micro-contracts pipeline --continue-on-error\",\n \"micro-contracts pipeline --contracts-only --skip-lint\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"verbose\",\n \"aliases\": [\n \"v\"\n ],\n \"description\": \"Enable verbose output (show detailed logs).\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"skip\",\n \"description\": \"Skip specific checks (comma-separated).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"continue-on-error\",\n \"description\": \"Continue running even if a step fails.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"generated-dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Path to generated files directory.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"manifest\",\n \"description\": \"Generate manifest after generation. Enabled by default. Use --no-manifest to disable.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n },\n {\n \"name\": \"skip-lint\",\n \"description\": \"Skip Spectral linting before generation.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"contracts-only\",\n \"description\": \"Generate contract packages only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"server-only\",\n \"description\": \"Generate server routes only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"frontend-only\",\n \"description\": \"Generate frontend clients only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"docs-only\",\n \"description\": \"Generate documentation only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"force\",\n \"description\": \"Bypass input hash cache and always regenerate.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"cache\",\n \"description\": \"Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Pipeline completed successfully. All gates passed and generation succeeded.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Pipeline failed. One or more steps had errors.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"stderr\": {\n \"required\": false,\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ],\n \"recommended_before_use\": [\n \"Ensure micro-contracts.config.yaml and guardrails.yaml exist.\",\n \"Verify OpenAPI specs are valid.\"\n ]\n }\n },\n \"deps\": {\n \"summary\": \"Analyze module dependencies.\",\n \"description\": \"Reads x-micro-contracts-depend-on declarations from OpenAPI specs and config dependsOn fields. Can output dependency graphs (Mermaid), impact analysis, reverse lookups, and validation results.\",\n \"usage\": [\n \"micro-contracts deps\",\n \"micro-contracts deps --graph\",\n \"micro-contracts deps --module billing\",\n \"micro-contracts deps --impact core.User.getUsers\",\n \"micro-contracts deps --who-depends-on core\",\n \"micro-contracts deps --validate\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module to analyze.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"graph\",\n \"description\": \"Output dependency graph in Mermaid format.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"impact\",\n \"description\": \"Analyze impact of changing a specific API (e.g., core.User.getUsers).\",\n \"value_name\": \"ref\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"who-depends-on\",\n \"description\": \"Find modules that depend on a specific API.\",\n \"value_name\": \"ref\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"validate\",\n \"description\": \"Validate dependencies against OpenAPI declarations.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Dependency analysis completed successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Analysis failed or validation errors found.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"insights\": {\n \"summary\": \"Emit ExternalInsight JSON for agent-contracts-analyzer.\",\n \"description\": \"Reads x-micro-contracts-depend-on from OpenAPI specs and outputs structured dependency edges and anchor mappings as JSON on stdout. Used by agent-contracts-analyzer CommandProvider integration.\",\n \"usage\": [\n \"micro-contracts insights --format json\",\n \"micro-contracts insights --format json --project-root .\"\n ],\n \"options\": [\n {\n \"name\": \"format\",\n \"description\": \"Output format (json only).\",\n \"value_name\": \"format\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"json\"\n }\n },\n {\n \"name\": \"project-root\",\n \"description\": \"Project root directory containing micro-contracts.config.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \".\"\n }\n },\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"ExternalInsight JSON written to stdout.\",\n \"stdout\": {\n \"format\": \"json\"\n }\n },\n \"1\": {\n \"description\": \"Insights generation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"guardrails-init\": {\n \"path\": [\n \"guardrails-init\"\n ],\n \"summary\": \"Create a guardrails.yaml configuration file.\",\n \"description\": \"Generates a starter guardrails.yaml with default check configuration. Fails if the target file already exists.\",\n \"usage\": [\n \"micro-contracts guardrails-init\",\n \"micro-contracts guardrails-init -o custom-guardrails.yaml\"\n ],\n \"options\": [\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output path for guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"guardrails.yaml\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"guardrails.yaml created successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"{options.output}\",\n \"required\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Failed to create (file already exists or write error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": false,\n \"side_effects\": [\n \"file_write\"\n ]\n }\n },\n \"manifest\": {\n \"summary\": \"Generate or verify manifest for generated artifacts.\",\n \"description\": \"Scans a directory of generated files and produces a .generated-manifest.json containing file hashes. In verify mode, checks that existing files match the manifest.\",\n \"usage\": [\n \"micro-contracts manifest\",\n \"micro-contracts manifest -d packages/\",\n \"micro-contracts manifest --verify\",\n \"micro-contracts manifest -o custom-manifest.json\"\n ],\n \"options\": [\n {\n \"name\": \"dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Directory to scan.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"verify\",\n \"description\": \"Verify existing manifest instead of generating.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output manifest path. Defaults to {dir}/.generated-manifest.json.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Manifest generated or verification passed.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"{options.dir}/.generated-manifest.json\",\n \"required\": false,\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated manifest (not created in verify mode).\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Directory not found, manifest generation failed, or verification failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ]\n }\n },\n \"audit-openapi\": {\n \"path\": [\n \"audit-openapi\"\n ],\n \"summary\": \"Run LLM-based OpenAPI design quality audit.\",\n \"description\": \"Performs a semantic review of OpenAPI specification design quality using an LLM agent. Evaluates path design, module boundary alignment, schema bloat, CRUD vs use-case orientation, and cross-cutting concern coverage. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts audit-openapi\",\n \"micro-contracts audit-openapi -m core\",\n \"micro-contracts audit-openapi --adapter claude --report-format text\",\n \"micro-contracts audit-openapi --show-prompt\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to audit (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the audit report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Audit completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OpenApiAuditResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed (config not found, spec invalid).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OpenApiAuditResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"review-published\": {\n \"path\": [\n \"review-published\"\n ],\n \"summary\": \"Review published API surface for internal leakage.\",\n \"description\": \"Analyzes the published (public-facing) API specification for internal type leakage, backward compatibility risks, and x-micro-contracts-non-exportable violations. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts review-published\",\n \"micro-contracts review-published -m billing\",\n \"micro-contracts review-published --adapter claude --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to review (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the review report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Review completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/PublishedReviewResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/PublishedReviewResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\",\n \"generated-packages\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"propose-overlays\": {\n \"path\": [\n \"propose-overlays\"\n ],\n \"summary\": \"Propose cross-cutting overlay candidates.\",\n \"description\": \"Analyzes the OpenAPI specification and proposes cross-cutting overlay candidates for authentication, tenancy, rate limiting, audit logging, and other patterns. Verifies proposals do not conflict with existing overlay definitions. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts propose-overlays\",\n \"micro-contracts propose-overlays -m core\",\n \"micro-contracts propose-overlays --adapter openai --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to analyze (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the proposal report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"json\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Proposal generated successfully.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OverlayProposalResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OverlayProposalResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"audit-guardrails\": {\n \"path\": [\n \"audit-guardrails\"\n ],\n \"summary\": \"Audit guardrails configuration for drift and lint coverage.\",\n \"description\": \"Checks that guardrails.yaml configuration covers all generated output directories for drift detection and that OpenAPI lint rules are properly configured. Note: file permission and editing checks have been moved to artifact-contracts. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts audit-guardrails\",\n \"micro-contracts audit-guardrails --adapter mock --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the audit report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Audit completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/GuardrailsAuditResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed (guardrails.yaml not found).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/GuardrailsAuditResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"guardrails-config\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n }\n }\n }\n },\n \"components\": {\n \"schemas\": {\n \"AgentEvidence\": {\n \"$ref\": \"components.yaml#/schemas/agent-evidence\"\n },\n \"AgentFinding\": {\n \"$ref\": \"components.yaml#/schemas/agent-finding\"\n },\n \"AgentRecommendedAction\": {\n \"$ref\": \"components.yaml#/schemas/agent-recommended-action\"\n },\n \"OpenApiAuditResult\": {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n \"PublishedReviewResult\": {\n \"type\": \"object\",\n \"description\": \"Result from review-published command. Contains published endpoint enumeration and internal type leakage analysis.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"publishedEndpoints\",\n \"leakedInternalTypes\"\n ],\n \"properties\": {\n \"publishedEndpoints\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"operationId\",\n \"path\",\n \"method\"\n ],\n \"properties\": {\n \"operationId\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"leakedInternalTypes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"schemaName\",\n \"referencedBy\",\n \"reason\"\n ],\n \"properties\": {\n \"schemaName\": {\n \"type\": \"string\"\n },\n \"referencedBy\": {\n \"type\": \"string\"\n },\n \"reason\": {\n \"type\": \"string\"\n }\n }\n }\n }\n }\n }\n ]\n },\n \"OverlayProposalResult\": {\n \"type\": \"object\",\n \"description\": \"Result from propose-overlays command. Contains overlay candidate proposals with endpoint, type, rationale, and suggested config.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"overlayCandidates\"\n ],\n \"properties\": {\n \"overlayCandidates\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"endpoint\",\n \"overlayType\",\n \"rationale\"\n ],\n \"properties\": {\n \"endpoint\": {\n \"type\": \"string\"\n },\n \"overlayType\": {\n \"type\": \"string\",\n \"enum\": [\n \"auth\",\n \"tenancy\",\n \"rateLimit\",\n \"auditLog\",\n \"custom\"\n ]\n },\n \"rationale\": {\n \"type\": \"string\"\n },\n \"suggestedConfig\": {\n \"type\": \"object\",\n \"additionalProperties\": true\n }\n }\n }\n }\n }\n }\n ]\n },\n \"GuardrailsAuditResult\": {\n \"type\": \"object\",\n \"description\": \"Result from audit-guardrails command. Contains drift detection and lint rule coverage analysis.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"coveredPaths\",\n \"uncoveredPaths\"\n ],\n \"properties\": {\n \"coveredPaths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"uncoveredPaths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n }\n }\n ]\n }\n }\n }\n}"; +export const CONTRACT_JSON_STR: string = "{\n \"cli_contracts\": \"0.1.0\",\n \"info\": {\n \"title\": \"micro-contracts CLI\",\n \"version\": \"0.17.10\",\n \"description\": \"Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients from OpenAPI specifications with enforceable guardrails.\",\n \"license\": {\n \"name\": \"MIT\"\n },\n \"contact\": {\n \"name\": \"foo-log-inc\",\n \"url\": \"https://github.com/foo-log-inc/micro-contracts\"\n }\n },\n \"artifact_slots\": {\n \"openapi-specs\": {\n \"direction\": \"read\",\n \"description\": \"OpenAPI specification files\"\n },\n \"config\": {\n \"direction\": \"read\",\n \"description\": \"micro-contracts.config.yaml configuration\"\n },\n \"generated-packages\": {\n \"direction\": \"write\",\n \"description\": \"Generated contract packages, server routes, and frontend clients\"\n },\n \"guardrails-config\": {\n \"direction\": \"read\",\n \"description\": \"guardrails.yaml configuration\"\n },\n \"manifest\": {\n \"direction\": \"write\",\n \"description\": \"Generated manifest (.generated-manifest.json)\"\n }\n },\n \"command_sets\": {\n \"micro-contracts\": {\n \"summary\": \"Contract-first OpenAPI toolchain for TypeScript.\",\n \"executable\": \"micro-contracts\",\n \"global_options\": [\n {\n \"name\": \"version\",\n \"aliases\": [\n \"V\"\n ],\n \"description\": \"Print version and exit.\",\n \"schema\": {\n \"type\": \"boolean\"\n }\n },\n {\n \"name\": \"help\",\n \"aliases\": [\n \"h\"\n ],\n \"description\": \"Show help and exit.\",\n \"schema\": {\n \"type\": \"boolean\"\n }\n }\n ],\n \"commands\": {\n \"generate\": {\n \"summary\": \"Generate code from OpenAPI specifications.\",\n \"description\": \"Loads the multi-module config, applies overlays, runs Spectral linting (unless skipped), and generates contract packages, server routes, frontend clients, and documentation from OpenAPI specs. Supports input-hash caching to skip unnecessary regeneration.\",\n \"usage\": [\n \"micro-contracts generate\",\n \"micro-contracts generate -c my-config.yaml\",\n \"micro-contracts generate -m core,billing\",\n \"micro-contracts generate --contracts-only\",\n \"micro-contracts generate --force\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module names, comma-separated. Generates all modules if omitted.\",\n \"value_name\": \"names\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"contracts-only\",\n \"description\": \"Generate contract packages only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"server-only\",\n \"description\": \"Generate server routes only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"frontend-only\",\n \"description\": \"Generate frontend clients only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"docs-only\",\n \"description\": \"Generate documentation only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"skip-lint\",\n \"description\": \"Skip Spectral linting before generation.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"manifest\",\n \"description\": \"Generate manifest after generation. Enabled by default when guardrails.yaml has a generated section. Use --no-manifest to disable.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n },\n {\n \"name\": \"manifest-dir\",\n \"description\": \"Directory for manifest output.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"force\",\n \"description\": \"Bypass input hash cache and always regenerate.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"cache\",\n \"description\": \"Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Generation succeeded.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"packages/contract/{module}/**/*.ts\",\n \"required\": true,\n \"media_type\": \"text/x-typescript\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated contract packages.\"\n },\n {\n \"path\": \"packages/contract-published/{module}/**/*.ts\",\n \"required\": false,\n \"media_type\": \"text/x-typescript\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated public contract packages.\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Generation failed (config not found, spec invalid, or generation error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ],\n \"recommended_before_use\": [\n \"Ensure micro-contracts.config.yaml exists.\",\n \"Verify OpenAPI specs are valid.\"\n ]\n }\n },\n \"lint\": {\n \"summary\": \"Lint OpenAPI specification.\",\n \"description\": \"Validates an OpenAPI specification for x-micro-contracts extension violations and structural issues using Spectral rules.\",\n \"usage\": [\n \"micro-contracts lint spec/core/openapi/core.yaml\",\n \"micro-contracts lint spec/core/openapi/core.yaml --strict\"\n ],\n \"arguments\": [\n {\n \"name\": \"input\",\n \"index\": 0,\n \"required\": true,\n \"description\": \"Path to OpenAPI spec file.\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n }\n ],\n \"options\": [\n {\n \"name\": \"strict\",\n \"description\": \"Treat warnings as errors.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Spec is valid. No lint errors found.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Lint failed. Errors or warnings (in strict mode) found.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"init\": {\n \"summary\": \"Initialize a new module structure with starter templates.\",\n \"description\": \"Creates the directory structure, starter Handlebars templates, shared schemas, Spectral rules, and optional config file for a new module. Can also process an existing OpenAPI spec to auto-add x-micro-contracts extensions.\",\n \"usage\": [\n \"micro-contracts init core\",\n \"micro-contracts init core --openapi path/to/spec.yaml\",\n \"micro-contracts init myScreens --screens\",\n \"micro-contracts init users --skip-templates\"\n ],\n \"arguments\": [\n {\n \"name\": \"name\",\n \"index\": 0,\n \"required\": true,\n \"description\": \"Module name (e.g., core, users, billing).\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"options\": [\n {\n \"name\": \"dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Base directory for server/frontend files.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"src\"\n }\n },\n {\n \"name\": \"openapi\",\n \"aliases\": [\n \"i\"\n ],\n \"description\": \"OpenAPI spec to process (auto-adds x-micro-contracts-service/method extensions).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output path for processed OpenAPI. Defaults to spec/{name}/openapi/{name}.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"skip-templates\",\n \"description\": \"Skip creating starter Handlebars templates.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"screens\",\n \"description\": \"Initialize as screen spec module (generates screen templates and starter spec).\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Module initialized successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"spec/{name}/openapi/{name}.yaml\",\n \"required\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\",\n \"description\": \"OpenAPI spec (created when --openapi provided or --screens used).\"\n },\n {\n \"path\": \"spec/default/templates/*.hbs\",\n \"required\": false,\n \"media_type\": \"text/x-handlebars-template\",\n \"encoding\": \"utf-8\",\n \"description\": \"Starter Handlebars templates.\"\n },\n {\n \"path\": \"micro-contracts.config.yaml\",\n \"required\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\",\n \"description\": \"Config file (created if not already present).\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Initialization failed (OpenAPI file not found or write error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\",\n \"directory_create\"\n ]\n }\n },\n \"check\": {\n \"summary\": \"Run guardrail checks.\",\n \"description\": \"Runs AI guardrail checks against generated code and config. Supports gating (1-5), selective check execution, auto-fix, and CI integration via changed-files input.\",\n \"usage\": [\n \"micro-contracts check\",\n \"micro-contracts check --gate 1,2\",\n \"micro-contracts check --only drift,manifest\",\n \"micro-contracts check --fix\",\n \"micro-contracts check --list\",\n \"micro-contracts check --list-gates\"\n ],\n \"options\": [\n {\n \"name\": \"only\",\n \"description\": \"Run only specific checks (comma-separated check names).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"skip\",\n \"description\": \"Skip specific checks (comma-separated check names).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"gate\",\n \"description\": \"Run checks for specific gates only (comma-separated, 1-5).\",\n \"value_name\": \"gates\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"verbose\",\n \"aliases\": [\n \"v\"\n ],\n \"description\": \"Enable verbose output.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"fix\",\n \"description\": \"Auto-fix issues where possible.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"generated-dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Path to generated files directory.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"changed-files\",\n \"description\": \"Path to file containing list of changed files (for CI).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": true,\n \"media_type\": \"text/plain\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"list\",\n \"description\": \"List available checks and exit.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"list-gates\",\n \"description\": \"List available gates and exit.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"All checks passed (or --list/--list-gates output).\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"One or more checks failed.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"stderr\": {\n \"required\": false,\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [],\n \"recommended_before_use\": [\n \"Run generate first so generated files exist.\"\n ]\n }\n },\n \"pipeline\": {\n \"summary\": \"Run full guardrails pipeline.\",\n \"description\": \"Executes the complete contract-first pipeline in order: Gate 1,2 (pre-generation checks) → Generate → Gate 3,4,5 (post-generation checks). Supports --continue-on-error to run all steps regardless of failures.\",\n \"usage\": [\n \"micro-contracts pipeline\",\n \"micro-contracts pipeline --verbose\",\n \"micro-contracts pipeline --continue-on-error\",\n \"micro-contracts pipeline --contracts-only --skip-lint\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"verbose\",\n \"aliases\": [\n \"v\"\n ],\n \"description\": \"Enable verbose output (show detailed logs).\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"skip\",\n \"description\": \"Skip specific checks (comma-separated).\",\n \"value_name\": \"checks\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"continue-on-error\",\n \"description\": \"Continue running even if a step fails.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"generated-dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Path to generated files directory.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"manifest\",\n \"description\": \"Generate manifest after generation. Enabled by default. Use --no-manifest to disable.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n },\n {\n \"name\": \"skip-lint\",\n \"description\": \"Skip Spectral linting before generation.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"contracts-only\",\n \"description\": \"Generate contract packages only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"server-only\",\n \"description\": \"Generate server routes only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"frontend-only\",\n \"description\": \"Generate frontend clients only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"docs-only\",\n \"description\": \"Generate documentation only.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"force\",\n \"description\": \"Bypass input hash cache and always regenerate.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"cache\",\n \"description\": \"Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Pipeline completed successfully. All gates passed and generation succeeded.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Pipeline failed. One or more steps had errors.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"stderr\": {\n \"required\": false,\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"medium\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ],\n \"recommended_before_use\": [\n \"Ensure micro-contracts.config.yaml and guardrails.yaml exist.\",\n \"Verify OpenAPI specs are valid.\"\n ]\n }\n },\n \"deps\": {\n \"summary\": \"Analyze module dependencies.\",\n \"description\": \"Reads x-micro-contracts-depend-on declarations from OpenAPI specs and config dependsOn fields. Can output dependency graphs (Mermaid), impact analysis, reverse lookups, and validation results.\",\n \"usage\": [\n \"micro-contracts deps\",\n \"micro-contracts deps --graph\",\n \"micro-contracts deps --module billing\",\n \"micro-contracts deps --impact core.User.getUsers\",\n \"micro-contracts deps --who-depends-on core\",\n \"micro-contracts deps --validate\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module to analyze.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"graph\",\n \"description\": \"Output dependency graph in Mermaid format.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"impact\",\n \"description\": \"Analyze impact of changing a specific API (e.g., core.User.getUsers).\",\n \"value_name\": \"ref\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"who-depends-on\",\n \"description\": \"Find modules that depend on a specific API.\",\n \"value_name\": \"ref\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"validate\",\n \"description\": \"Validate dependencies against OpenAPI declarations.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Dependency analysis completed successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n }\n },\n \"1\": {\n \"description\": \"Analysis failed or validation errors found.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"insights\": {\n \"summary\": \"Emit ExternalInsight JSON for agent-contracts-analyzer.\",\n \"description\": \"Reads x-micro-contracts-depend-on from OpenAPI specs and outputs structured dependency edges and anchor mappings as JSON on stdout. Used by agent-contracts-analyzer CommandProvider integration.\",\n \"usage\": [\n \"micro-contracts insights --format json\",\n \"micro-contracts insights --format json --project-root .\"\n ],\n \"options\": [\n {\n \"name\": \"format\",\n \"description\": \"Output format (json only).\",\n \"value_name\": \"format\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"json\"\n }\n },\n {\n \"name\": \"project-root\",\n \"description\": \"Project root directory containing micro-contracts.config.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \".\"\n }\n },\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"ExternalInsight JSON written to stdout.\",\n \"stdout\": {\n \"format\": \"json\"\n }\n },\n \"1\": {\n \"description\": \"Insights generation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": []\n }\n },\n \"guardrails-init\": {\n \"path\": [\n \"guardrails-init\"\n ],\n \"summary\": \"Create a guardrails.yaml configuration file.\",\n \"description\": \"Generates a starter guardrails.yaml with default check configuration. Fails if the target file already exists.\",\n \"usage\": [\n \"micro-contracts guardrails-init\",\n \"micro-contracts guardrails-init -o custom-guardrails.yaml\"\n ],\n \"options\": [\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output path for guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"guardrails.yaml\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"guardrails.yaml created successfully.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"{options.output}\",\n \"required\": true,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Failed to create (file already exists or write error).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": false,\n \"side_effects\": [\n \"file_write\"\n ]\n }\n },\n \"manifest\": {\n \"summary\": \"Generate or verify manifest for generated artifacts.\",\n \"description\": \"Scans a directory of generated files and produces a .generated-manifest.json containing file hashes. In verify mode, checks that existing files match the manifest.\",\n \"usage\": [\n \"micro-contracts manifest\",\n \"micro-contracts manifest -d packages/\",\n \"micro-contracts manifest --verify\",\n \"micro-contracts manifest -o custom-manifest.json\"\n ],\n \"options\": [\n {\n \"name\": \"dir\",\n \"aliases\": [\n \"d\"\n ],\n \"description\": \"Directory to scan.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\",\n \"default\": \"packages/\"\n }\n },\n {\n \"name\": \"verify\",\n \"description\": \"Verify existing manifest instead of generating.\",\n \"schema\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Output manifest path. Defaults to {dir}/.generated-manifest.json.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Manifest generated or verification passed.\",\n \"stdout\": {\n \"format\": \"text\"\n },\n \"files\": [\n {\n \"path\": \"{options.dir}/.generated-manifest.json\",\n \"required\": false,\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\",\n \"description\": \"Generated manifest (not created in verify mode).\"\n }\n ]\n },\n \"1\": {\n \"description\": \"Directory not found, manifest generation failed, or verification failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"x-agent\": {\n \"risk_level\": \"low\",\n \"requires_confirmation\": false,\n \"idempotent\": true,\n \"side_effects\": [\n \"file_write\"\n ]\n }\n },\n \"audit-openapi\": {\n \"path\": [\n \"audit-openapi\"\n ],\n \"summary\": \"Run LLM-based OpenAPI design quality audit.\",\n \"description\": \"Performs a semantic review of OpenAPI specification design quality using an LLM agent. Evaluates path design, module boundary alignment, schema bloat, CRUD vs use-case orientation, and cross-cutting concern coverage. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts audit-openapi\",\n \"micro-contracts audit-openapi -m core\",\n \"micro-contracts audit-openapi --adapter claude --report-format text\",\n \"micro-contracts audit-openapi --show-prompt\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to audit (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the audit report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Audit completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OpenApiAuditResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed (config not found, spec invalid).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OpenApiAuditResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"dsl_task\": \"audit-openapi-design\",\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"review-published\": {\n \"path\": [\n \"review-published\"\n ],\n \"summary\": \"Review published API surface for internal leakage.\",\n \"description\": \"Analyzes the published (public-facing) API specification for internal type leakage, backward compatibility risks, and x-micro-contracts-non-exportable violations. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts review-published\",\n \"micro-contracts review-published -m billing\",\n \"micro-contracts review-published --adapter claude --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to review (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the review report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Review completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/PublishedReviewResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/PublishedReviewResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\",\n \"generated-packages\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"dsl_task\": \"audit-published-api\",\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"propose-overlays\": {\n \"path\": [\n \"propose-overlays\"\n ],\n \"summary\": \"Propose cross-cutting overlay candidates.\",\n \"description\": \"Analyzes the OpenAPI specification and proposes cross-cutting overlay candidates for authentication, tenancy, rate limiting, audit logging, and other patterns. Verifies proposals do not conflict with existing overlay definitions. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts propose-overlays\",\n \"micro-contracts propose-overlays -m core\",\n \"micro-contracts propose-overlays --adapter openai --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"module\",\n \"aliases\": [\n \"m\"\n ],\n \"description\": \"Module name to analyze (default is all modules).\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the proposal report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"json\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Proposal generated successfully.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OverlayProposalResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/OverlayProposalResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"openapi-specs\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"dsl_task\": \"propose-overlay-candidates\",\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n },\n \"audit-guardrails\": {\n \"path\": [\n \"audit-guardrails\"\n ],\n \"summary\": \"Audit guardrails configuration for drift and lint coverage.\",\n \"description\": \"Checks that guardrails.yaml configuration covers all generated output directories for drift detection and that OpenAPI lint rules are properly configured. Note: file permission and editing checks have been moved to artifact-contracts. Requires agent-contracts-runtime.\",\n \"usage\": [\n \"micro-contracts audit-guardrails\",\n \"micro-contracts audit-guardrails --adapter mock --report-format json\"\n ],\n \"options\": [\n {\n \"name\": \"config\",\n \"aliases\": [\n \"c\"\n ],\n \"description\": \"Path to config file (micro-contracts.config.yaml).\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"guardrails\",\n \"aliases\": [\n \"g\"\n ],\n \"description\": \"Path to guardrails.yaml.\",\n \"value_name\": \"path\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"read\",\n \"exists\": false,\n \"media_type\": \"application/yaml\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"adapter\",\n \"aliases\": [\n \"a\"\n ],\n \"description\": \"SDK adapter to use for LLM execution.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"claude\",\n \"openai\",\n \"gemini\",\n \"mock\"\n ]\n }\n },\n {\n \"name\": \"model\",\n \"description\": \"LLM model override.\",\n \"value_name\": \"name\",\n \"schema\": {\n \"type\": \"string\"\n }\n },\n {\n \"name\": \"fail-on\",\n \"description\": \"Minimum severity that causes a non-zero exit.\",\n \"value_name\": \"level\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"warning\",\n \"error\",\n \"critical\"\n ],\n \"default\": \"error\"\n }\n },\n {\n \"name\": \"output\",\n \"aliases\": [\n \"o\"\n ],\n \"description\": \"Write result to a file instead of stdout.\",\n \"value_name\": \"file\",\n \"schema\": {\n \"type\": \"string\"\n },\n \"file\": {\n \"mode\": \"write\",\n \"media_type\": \"application/json\",\n \"encoding\": \"utf-8\"\n }\n },\n {\n \"name\": \"report-format\",\n \"description\": \"Output format for the audit report.\",\n \"value_name\": \"fmt\",\n \"schema\": {\n \"type\": \"string\",\n \"enum\": [\n \"json\",\n \"text\",\n \"yaml\"\n ],\n \"default\": \"text\"\n }\n },\n {\n \"name\": \"log-file\",\n \"aliases\": [\n \"l\"\n ],\n \"description\": \"Write agent progress log to this file path.\",\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"exits\": {\n \"0\": {\n \"description\": \"Audit completed, no blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/GuardrailsAuditResult\"\n }\n }\n },\n \"1\": {\n \"description\": \"Unexpected error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"3\": {\n \"description\": \"Input validation failed (guardrails.yaml not found).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"10\": {\n \"description\": \"Completed with blocking findings.\",\n \"stdout\": {\n \"format\": \"{options.report-format}\",\n \"schema\": {\n \"$ref\": \"#/components/schemas/GuardrailsAuditResult\"\n }\n }\n },\n \"11\": {\n \"description\": \"Runtime dependency missing (agent-contracts-runtime).\",\n \"stderr\": {\n \"format\": \"text\"\n }\n },\n \"12\": {\n \"description\": \"LLM provider or adapter error.\",\n \"stderr\": {\n \"format\": \"text\"\n }\n }\n },\n \"effects\": {\n \"reads\": [\n \"guardrails-config\",\n \"config\"\n ],\n \"writes\": [],\n \"network\": {\n \"description\": \"LLM API calls when adapter is not mock\",\n \"requires_secrets\": [],\n \"idempotent\": true\n }\n },\n \"x-agent\": {\n \"dsl_task\": \"audit-guardrails-coverage\",\n \"expectedDurationMs\": 120000,\n \"retryableExitCodes\": [\n 12\n ]\n }\n }\n }\n }\n },\n \"components\": {\n \"schemas\": {\n \"AgentEvidence\": {\n \"$ref\": \"components.yaml#/schemas/agent-evidence\"\n },\n \"AgentFinding\": {\n \"$ref\": \"components.yaml#/schemas/agent-finding\"\n },\n \"AgentRecommendedAction\": {\n \"$ref\": \"components.yaml#/schemas/agent-recommended-action\"\n },\n \"OpenApiAuditResult\": {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n \"PublishedReviewResult\": {\n \"type\": \"object\",\n \"description\": \"Result from review-published command. Contains published endpoint enumeration and internal type leakage analysis.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"publishedEndpoints\",\n \"leakedInternalTypes\"\n ],\n \"properties\": {\n \"publishedEndpoints\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"operationId\",\n \"path\",\n \"method\"\n ],\n \"properties\": {\n \"operationId\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n }\n }\n }\n },\n \"leakedInternalTypes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"schemaName\",\n \"referencedBy\",\n \"reason\"\n ],\n \"properties\": {\n \"schemaName\": {\n \"type\": \"string\"\n },\n \"referencedBy\": {\n \"type\": \"string\"\n },\n \"reason\": {\n \"type\": \"string\"\n }\n }\n }\n }\n }\n }\n ]\n },\n \"OverlayProposalResult\": {\n \"type\": \"object\",\n \"description\": \"Result from propose-overlays command. Contains overlay candidate proposals with endpoint, type, rationale, and suggested config.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"overlayCandidates\"\n ],\n \"properties\": {\n \"overlayCandidates\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\n \"endpoint\",\n \"overlayType\",\n \"rationale\"\n ],\n \"properties\": {\n \"endpoint\": {\n \"type\": \"string\"\n },\n \"overlayType\": {\n \"type\": \"string\",\n \"enum\": [\n \"auth\",\n \"tenancy\",\n \"rateLimit\",\n \"auditLog\",\n \"custom\"\n ]\n },\n \"rationale\": {\n \"type\": \"string\"\n },\n \"suggestedConfig\": {\n \"type\": \"object\",\n \"additionalProperties\": true\n }\n }\n }\n }\n }\n }\n ]\n },\n \"GuardrailsAuditResult\": {\n \"type\": \"object\",\n \"description\": \"Result from audit-guardrails command. Contains drift detection and lint rule coverage analysis.\",\n \"allOf\": [\n {\n \"$ref\": \"components.yaml#/schemas/agent-audit-result\"\n },\n {\n \"type\": \"object\",\n \"required\": [\n \"coveredPaths\",\n \"uncoveredPaths\"\n ],\n \"properties\": {\n \"coveredPaths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"uncoveredPaths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n }\n }\n ]\n }\n }\n }\n}"; diff --git a/tests/agents/dsl-task-binding.test.ts b/tests/agents/dsl-task-binding.test.ts new file mode 100644 index 0000000..dad4f05 --- /dev/null +++ b/tests/agents/dsl-task-binding.test.ts @@ -0,0 +1,56 @@ +import { describe, it, expect } from "vitest"; +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { parse as parseYaml } from "yaml"; +import { taskRegistry } from "../../src/generated/dsl/tasks.js"; +import { TASK_IDS } from "../../src/agents/types.js"; + +const contractPath = resolve(import.meta.dirname, "../../cli-contract.yaml"); +const contract = parseYaml(readFileSync(contractPath, "utf8")); + +function getCommands(): Record { + const sets = contract.command_sets ?? {}; + const commands: Record = {}; + for (const setDef of Object.values(sets) as Array<{ commands?: Record }>) { + if (setDef.commands) { + Object.assign(commands, setDef.commands); + } + } + return commands; +} + +describe("dsl_task binding consistency", () => { + const commands = getCommands(); + + const llmCommands = Object.entries(commands).filter( + ([, cmd]) => cmd["x-agent"]?.dsl_task, + ); + + it("all LLM commands declare dsl_task in x-agent", () => { + expect(llmCommands.length).toBe(4); + }); + + it.each(llmCommands)( + "%s x-agent.dsl_task matches DSL task registry", + (cmdName, cmd) => { + const dslTask = cmd["x-agent"]!.dsl_task!; + expect(taskRegistry[dslTask]).toBeDefined(); + expect(taskRegistry[dslTask].id).toBe(dslTask); + }, + ); + + it("TASK_IDS values all exist in the DSL task registry", () => { + for (const [key, taskId] of Object.entries(TASK_IDS)) { + expect(taskRegistry[taskId]).toBeDefined(); + expect(taskRegistry[taskId].id).toBe(taskId); + } + }); + + it("TASK_IDS covers all dsl_task declarations in the contract", () => { + const contractTaskIds = llmCommands.map(([, cmd]) => cmd["x-agent"]!.dsl_task!); + const registeredTaskIds = Object.values(TASK_IDS); + for (const taskId of contractTaskIds) { + expect(registeredTaskIds).toContain(taskId); + } + }); +});