micro-contracts 0.14.4 → 0.15.1

package/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.14.2
+**Version:** 0.15.0
 
 ## Table of Contents
 
@@ -15,6 +15,10 @@ Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contr
   - [deps](#micro-contracts-deps)
   - [guardrails-init](#micro-contracts-guardrails-init)
   - [manifest](#micro-contracts-manifest)
+  - [audit-openapi](#micro-contracts-audit-openapi)
+  - [review-published](#micro-contracts-review-published)
+  - [propose-overlays](#micro-contracts-propose-overlays)
+  - [audit-guardrails](#micro-contracts-audit-guardrails)
 
 ---
 
@@ -87,12 +91,12 @@ micro-contracts generate --force
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
+  risk_level: medium
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
     - file_write
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure micro-contracts.config.yaml exists.
     - Verify OpenAPI specs are valid.
 ```
@@ -140,10 +144,10 @@ micro-contracts lint spec/core/openapi/core.yaml --strict
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  risk_level: low
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
 
 ```
 
@@ -205,10 +209,10 @@ micro-contracts init users --skip-templates
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
+  risk_level: medium
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
     - file_write
     - directory_create
 ```
@@ -273,12 +277,12 @@ micro-contracts check --list-gates
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  risk_level: low
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
 
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Run generate first so generated files exist.
 ```
 
@@ -340,12 +344,12 @@ micro-contracts pipeline --contracts-only --skip-lint
 
 ```yaml
 x-agent: 
-  riskLevel: medium
-  requiresConfirmation: false
+  risk_level: medium
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
     - file_write
-  recommendedBeforeUse: 
+  recommended_before_use: 
     - Ensure micro-contracts.config.yaml and guardrails.yaml exist.
     - Verify OpenAPI specs are valid.
 ```
@@ -404,10 +408,10 @@ micro-contracts deps --validate
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  risk_level: low
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
 
 ```
 
@@ -451,10 +455,10 @@ micro-contracts guardrails-init -o custom-guardrails.yaml
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  risk_level: low
+  requires_confirmation: false
   idempotent: false
-  sideEffects: 
+  side_effects: 
     - file_write
 ```
 
@@ -506,11 +510,307 @@ micro-contracts manifest -o custom-manifest.json
 
 ```yaml
 x-agent: 
-  riskLevel: low
-  requiresConfirmation: false
+  risk_level: low
+  requires_confirmation: false
   idempotent: true
-  sideEffects: 
+  side_effects: 
     - file_write
 ```
 
 ---
+
+### audit-openapi
+
+Run LLM-based OpenAPI design quality audit.
+
+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.
+
+**Usage:**
+
+```
+micro-contracts audit-openapi
+```
+```
+micro-contracts audit-openapi -m core
+```
+```
+micro-contracts audit-openapi --adapter cursor --report-format text
+```
+```
+micro-contracts audit-openapi --show-prompt
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file (micro-contracts.config.yaml). |
+| `--module` | -m | No |  | Module name to audit (default is all modules). |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"text"` | Output format for the audit report. |
+
+#### Exit Codes
+
+**Exit 0:** Audit completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 3:** Input validation failed (config not found, spec invalid).
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  risk_level: low
+  requires_confirmation: false
+  idempotent: true
+  side_effects: 
+    - network
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write only when --output is specified.
+  safe_dry_run_option: show-prompt
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### review-published
+
+Review published API surface for internal leakage.
+
+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.
+
+**Usage:**
+
+```
+micro-contracts review-published
+```
+```
+micro-contracts review-published -m billing
+```
+```
+micro-contracts review-published --adapter claude --report-format json
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file (micro-contracts.config.yaml). |
+| `--module` | -m | No |  | Module name to review (default is all modules). |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"text"` | Output format for the review report. |
+
+#### Exit Codes
+
+**Exit 0:** Review completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 3:** Input validation failed.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  risk_level: low
+  requires_confirmation: false
+  idempotent: true
+  side_effects: 
+    - network
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write only when --output is specified.
+  safe_dry_run_option: show-prompt
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### propose-overlays
+
+Propose cross-cutting overlay candidates.
+
+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.
+
+**Usage:**
+
+```
+micro-contracts propose-overlays
+```
+```
+micro-contracts propose-overlays -m core
+```
+```
+micro-contracts propose-overlays --adapter openai --report-format json
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file (micro-contracts.config.yaml). |
+| `--module` | -m | No |  | Module name to analyze (default is all modules). |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"json"` | Output format for the proposal report. |
+
+#### Exit Codes
+
+**Exit 0:** Proposal generated successfully.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 3:** Input validation failed.
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  risk_level: low
+  requires_confirmation: false
+  idempotent: true
+  side_effects: 
+    - network
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write only when --output is specified.
+  safe_dry_run_option: show-prompt
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---
+
+### audit-guardrails
+
+Audit guardrails configuration for drift and lint coverage.
+
+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.
+
+**Usage:**
+
+```
+micro-contracts audit-guardrails
+```
+```
+micro-contracts audit-guardrails --adapter mock --report-format json
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to config file (micro-contracts.config.yaml). |
+| `--guardrails` | -g | No |  | Path to guardrails.yaml. |
+| `--adapter` | -a | No |  | SDK adapter to use for LLM execution. |
+| `--model` |  | No |  | LLM model override. |
+| `--fail-on` |  | No | `"error"` | Minimum severity that causes a non-zero exit. |
+| `--output` | -o | No |  | Write result to a file instead of stdout. |
+| `--report-format` |  | No | `"text"` | Output format for the audit report. |
+
+#### Exit Codes
+
+**Exit 0:** Audit completed, no blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 1:** Unexpected error.
+
+- **stderr:** format=`text`
+
+**Exit 3:** Input validation failed (guardrails.yaml not found).
+
+- **stderr:** format=`text`
+
+**Exit 10:** Completed with blocking findings.
+
+- **stdout:** format=`{options.report-format}`
+
+**Exit 11:** Runtime dependency missing (agent-contracts-runtime).
+
+- **stderr:** format=`text`
+
+**Exit 12:** LLM provider or adapter error.
+
+- **stderr:** format=`text`
+
+#### Extensions
+
+```yaml
+x-agent: 
+  risk_level: low
+  requires_confirmation: false
+  idempotent: true
+  side_effects: 
+    - network
+  sideEffectNote: Network calls to LLM provider when adapter is not mock. Filesystem write only when --output is specified.
+  safe_dry_run_option: show-prompt
+  expectedDurationMs: 120000
+  retryableExitCodes: 
+    - 12
+```
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micro-contracts",
-  "version": "0.14.4",
+  "version": "0.15.1",
   "description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "generate": "tsx src/cli.ts generate",
+    "contract:validate": "npx cli-contracts validate",
+    "contract:generate": "npx cli-contracts generate",
+    "dsl:generate": "npx agent-runtime generate --config dsl/agent-runtime.config.yaml",
     "docs:sync": "npx embedoc build",
     "docs:check": "npx embedoc build && git diff --exit-code README.md docs/",
     "prepublishOnly": "npm run build && npm test"
@@ -47,16 +50,31 @@
     "url": "https://github.com/foo-ogawa/micro-contracts/issues"
   },
   "dependencies": {
+    "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "glob": "^10.3.10",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^3.22.0"
+  },
+  "peerDependencies": {
+    "agent-contracts-runtime": ">=0.30.0"
+  },
+  "peerDependenciesMeta": {
+    "agent-contracts-runtime": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@cursor/sdk": "^1.0.13",
+    "@google/genai": "^2.4.0",
+    "@openai/agents": "^0.11.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.0",
-    "cli-contracts": "^0.7.2",
+    "agent-contracts": "^0.30.1",
+    "agent-contracts-runtime": "^0.30.0",
+    "cli-contracts": "^0.30.2",
     "embedoc": "^0.9.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3",