migraguard 0.9.1 → 0.10.0

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cliContracts: 0.1.0
 
 info:
   title: migraguard CLI
-  version: 0.8.4
+  version: 0.10.0
   description: >-
     PostgreSQL-first schema-aware deployment control — idempotent SQL migrations
     with CI-enforced integrity checks, expand/contract migration orchestration,
@@ -77,9 +77,16 @@ commandSets:
               type: boolean
               default: false
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be created without writing files.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Migration file (or group directory) created successfully.
+            description: Migration file (or group directory) created successfully (or dry-run preview completed).
             stdout:
               format: text
             files:
@@ -105,6 +112,10 @@ commandSets:
           idempotent: false
           sideEffects:
             - file_write
+          sideEffectNote: Creates migration SQL file(s) in the configured migrations directory.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 1000
+          retryableExitCodes: []
 
       # ── apply ────────────────────────────────────────
       apply:
@@ -168,7 +179,12 @@ commandSets:
             requires writing a compensating migration or restoring from backup.
           sideEffects:
             - database_write
+          sideEffectNote: >-
+            Executes SQL via native CLI and records results in schema_migrations.
+            Uses advisory lock to prevent concurrent execution.
           safeDryRunOption: dry-run
+          expectedDurationMs: 60000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Run migraguard check to verify metadata integrity.
             - Run migraguard lint to check for unsafe DDL patterns.
@@ -192,6 +208,11 @@ commandSets:
               format: text
 
           '1':
+            description: Unexpected error (file read failure, parse error).
+            stderr:
+              format: text
+
+          '10':
             description: Integrity check failed (tampered, missing, or extra files).
             stderr:
               format: text
@@ -201,6 +222,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Compares metadata.json against files on disk.
+          expectedDurationMs: 2000
+          retryableExitCodes: []
 
       # ── squash ───────────────────────────────────────
       squash:
@@ -211,6 +235,15 @@ commandSets:
           recovery and hotfix workflows. Original migration files are deleted.
         usage:
           - migraguard squash
+          - migraguard squash --dry-run
+
+        options:
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be squashed without writing files.
+            schema:
+              type: boolean
+              default: false
 
         exits:
           '0':
@@ -240,6 +273,12 @@ commandSets:
           sideEffects:
             - file_write
             - file_delete
+          sideEffectNote: >-
+            Merges migration files into one and deletes originals.
+            Updates metadata.json.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 3000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Ensure all pending files are ready for release.
             - Confirm no uncommitted changes to migration files.
@@ -290,6 +329,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Scans migration files against safety rules.
+          expectedDurationMs: 3000
+          retryableExitCodes: []
 
       # ── dump ─────────────────────────────────────────
       dump:
@@ -300,6 +342,15 @@ commandSets:
           output and saves it to schema.sql.
         usage:
           - migraguard dump
+          - migraguard dump --dry-run
+
+        options:
+          - name: dry-run
+            aliases: [n]
+            description: Output normalized schema to stdout without writing schema.sql.
+            schema:
+              type: boolean
+              default: false
 
         exits:
           '0':
@@ -325,6 +376,12 @@ commandSets:
           sideEffects:
             - database_read
             - file_write
+          sideEffectNote: >-
+            Reads DB schema via pg_dump/mysqldump and writes normalized
+            output to schema.sql.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 10000
+          retryableExitCodes: [1]
 
       # ── diff ─────────────────────────────────────────
       diff:
@@ -369,6 +426,11 @@ commandSets:
           idempotent: true
           sideEffects:
             - database_read
+          sideEffectNote: >-
+            Reads DB schema via pg_dump/mysqldump and compares with
+            saved schema.sql. No writes.
+          expectedDurationMs: 10000
+          retryableExitCodes: [1]
 
       # ── status ───────────────────────────────────────
       status:
@@ -406,6 +468,9 @@ commandSets:
           idempotent: true
           sideEffects:
             - database_read
+          sideEffectNote: Reads schema_migrations table and compares with local files.
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
 
       # ── resolve ──────────────────────────────────────
       resolve:
@@ -417,6 +482,7 @@ commandSets:
           addressed by other means.
         usage:
           - migraguard resolve 20260301_120000__create_users_table.sql
+          - migraguard resolve --dry-run 20260301_120000__create_users_table.sql
 
         arguments:
           - name: file
@@ -426,6 +492,14 @@ commandSets:
             schema:
               type: string
 
+        options:
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be resolved without writing to DB.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
             description: Migration marked as skipped.
@@ -447,6 +521,10 @@ commandSets:
             Re-apply the migration manually if needed.
           sideEffects:
             - database_write
+          sideEffectNote: Inserts a 'skipped' record into schema_migrations for the given file.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 3000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Verify that the failure has been addressed by a subsequent migration or manual fix.
             - Run migraguard status to confirm the file is in failed state.
@@ -476,6 +554,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Lists leaf/latest migration files from metadata.
+          expectedDurationMs: 1000
+          retryableExitCodes: []
 
       # ── verify ───────────────────────────────────────
       verify:
@@ -512,7 +593,14 @@ commandSets:
               format: '{options.format}'
 
           '1':
+            description: Unexpected error (connection error, file parse failure).
+            stderr:
+              format: text
+
+          '10':
             description: One or more migrations failed idempotency verification.
+            stdout:
+              format: '{options.format}'
             stderr:
               format: text
 
@@ -523,6 +611,11 @@ commandSets:
           sideEffects:
             - database_read
             - database_write
+          sideEffectNote: >-
+            Creates and destroys a temporary shadow database to verify
+            idempotency. Does not modify the primary database.
+          expectedDurationMs: 60000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Ensure the database server is running and accessible.
 
@@ -562,6 +655,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Derives group state from schema_migrations records.
+          expectedDurationMs: 3000
+          retryableExitCodes: [1]
 
       # ── baseline ─────────────────────────────────────
       baseline:
@@ -573,6 +669,7 @@ commandSets:
         usage:
           - migraguard baseline
           - migraguard baseline --keep-since 20260301_120000__create_users_table.sql
+          - migraguard baseline --dry-run
 
         options:
           - name: keep-since
@@ -582,9 +679,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be baselined without writing files.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Baseline created successfully.
+            description: Baseline created successfully (or dry-run preview completed).
             stdout:
               format: text
 
@@ -604,6 +708,12 @@ commandSets:
           sideEffects:
             - file_write
             - file_delete
+          sideEffectNote: >-
+            Dumps current DB schema to schema.sql, deletes squashed migration
+            files, updates metadata.json, and rewrites depends-on references.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 30000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Ensure all migrations have been applied to all environments.
             - Back up migration files before running.
@@ -650,9 +760,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be recorded without writing to DB.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Phase state transition recorded.
+            description: Phase state transition recorded (or dry-run preview completed).
             stdout:
               format: text
 
@@ -673,6 +790,10 @@ commandSets:
             status value to manually correct, or reset group state in the database.
           sideEffects:
             - database_write
+          sideEffectNote: Inserts a phase state transition record into schema_migrations.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
           recommendedBeforeUse:
             - Run migraguard group-status <group> to verify current phase state before advancing.
 
@@ -710,9 +831,16 @@ commandSets:
             schema:
               type: string
 
+          - name: dry-run
+            aliases: [n]
+            description: Show what would be applied without executing SQL.
+            schema:
+              type: boolean
+              default: false
+
         exits:
           '0':
-            description: Phase applied successfully.
+            description: Phase applied successfully (or dry-run preview completed).
             stdout:
               format: text
 
@@ -733,6 +861,12 @@ commandSets:
             migration or restore from backup if rollback is needed.
           sideEffects:
             - database_write
+          sideEffectNote: >-
+            Executes a phase SQL file via native CLI and records the
+            result in schema_migrations. Uses advisory lock.
+          safeDryRunOption: dry-run
+          expectedDurationMs: 30000
+          retryableExitCodes: []
           recommendedBeforeUse:
             - Run migraguard group-status to verify current phase state.
 
@@ -790,6 +924,11 @@ commandSets:
               format: text
 
           '1':
+            description: Unexpected error (connection error, invalid condition syntax).
+            stderr:
+              format: text
+
+          '10':
             description: One or more gate conditions not satisfied.
             stderr:
               format: text
@@ -799,6 +938,9 @@ commandSets:
           requiresConfirmation: false
           idempotent: true
           sideEffects: []
+          sideEffectNote: Read-only. Evaluates gate conditions against schema_migrations state.
+          expectedDurationMs: 5000
+          retryableExitCodes: [1]
 
       # ── deps ─────────────────────────────────────────
       deps:
@@ -845,6 +987,11 @@ commandSets:
           idempotent: true
           sideEffects:
             - file_write
+          sideEffectNote: >-
+            Reads migration files and outputs dependency graph.
+            Writes HTML file only when --html is specified.
+          expectedDurationMs: 3000
+          retryableExitCodes: []
 
       # ── audit ─────────────────────────────────────────
       audit:
@@ -917,7 +1064,7 @@ commandSets:
             schema:
               type: string
               enum: [json, text, yaml]
-              default: text
+              default: json
 
         exits:
           '0':
@@ -964,7 +1111,7 @@ commandSets:
             Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
       # ── propose-expand-contract ───────────────────────
       propose-expand-contract:
@@ -1092,7 +1239,7 @@ commandSets:
             Filesystem write when --output or --output-dir is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
       # ── explain ───────────────────────────────────────
       explain:
@@ -1208,227 +1355,96 @@ commandSets:
             Filesystem write only when --output is specified.
           safeDryRunOption: dry-run
           expectedDurationMs: 120000
-          retryableExitCodes: [1, 12]
+          retryableExitCodes: [12]
 
 components:
   schemas:
-    # ── AI Agent Interoperability Schemas (SSoT) ─────────
-
+    # ── AI Agent Interoperability Schemas ──────────────────
+    # Canonical definitions copied from agent-contracts dsl_base/components.yaml.
+    # Keep components.yaml in sync when upgrading agent-contracts.
     AgentEvidence:
-      type: object
-      description: Evidence supporting an agent finding.
-      required: [kind]
-      properties:
-        kind:
-          type: string
-          enum: [file, command, schema, diff, stdout, stderr, text]
-        target:
-          type: string
-          description: Target identifier (file path, command ID, schema name).
-        location:
-          type: string
-          description: Location within the target (line number, JSON pointer).
-        excerpt:
-          type: string
-          description: Relevant excerpt from the target.
-
+      $ref: 'components.yaml#/schemas/agent-evidence'
     AgentFinding:
-      type: object
-      description: A single finding from a migration audit.
-      required: [severity, category, message]
-      properties:
-        id:
-          type: string
-          description: Unique finding identifier.
-        severity:
-          type: string
-          enum: [info, warning, error, critical]
-        category:
-          type: string
-          description: >-
-            Finding category. Migration-specific categories:
-            lock_risk, idempotency, expand_contract, backfill_safety,
-            rollback_risk, deploy_order, allow_directive.
-        target:
-          type: string
-          description: Target of the finding (file path, SQL statement).
-        location:
-          type: string
-          description: Location within the target.
-        message:
-          type: string
-        recommendation:
-          type: string
-        confidence:
-          type: number
-          minimum: 0
-          maximum: 1
-          description: Confidence score (0-1) for LLM-generated findings.
-        evidence:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentEvidence'
-        details:
-          type: object
-          additionalProperties: true
-
+      $ref: 'components.yaml#/schemas/agent-finding'
     AgentRecommendedAction:
-      type: object
-      description: A recommended action from a migration audit.
-      required: [kind, title]
-      properties:
-        kind:
-          type: string
-          enum: [run_command, edit_file, review, confirm, block, ignore]
-        title:
-          type: string
-        command:
-          type: string
-          description: CLI command to run (for run_command kind).
-        target:
-          type: string
-          description: Target file or resource.
-        rationale:
-          type: string
-
+      $ref: 'components.yaml#/schemas/agent-recommended-action'
     MigrationAuditResult:
-      type: object
-      description: >-
-        Top-level result from a migration safety audit.
-        Conforms to cli-contracts AgentAuditResult reference schema.
-      required: [summary, riskLevel, findings]
-      properties:
-        summary:
-          type: string
-        riskLevel:
-          type: string
-          enum: [low, medium, high, critical]
-        findings:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentFinding'
-        recommendedActions:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentRecommendedAction'
-        metadata:
-          type: object
-          properties:
-            tool:
-              type: string
-            command:
-              type: string
-            version:
-              type: string
-            generatedAt:
-              type: string
-            adapter:
-              type: string
-            model:
-              type: string
+      $ref: 'components.yaml#/schemas/agent-audit-result'
 
     ExpandContractProposal:
       type: object
       description: >-
         Result from propose-expand-contract command. Contains the proposed
         phased migration group with SQL for each phase.
-      required: [summary, riskLevel, findings, phases]
-      properties:
-        summary:
-          type: string
-          description: Overview of the proposed decomposition.
-        riskLevel:
-          type: string
-          enum: [low, medium, high, critical]
-          description: Risk level of the original unsafe DDL.
-        findings:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentFinding'
-          description: Issues found in the original migration.
-        phases:
-          type: array
-          items:
-            type: object
-            required: [name, sql, description]
-            properties:
-              name:
-                type: string
-                enum: [expand, backfill, switch, contract]
-              sql:
-                type: string
-                description: SQL content for this phase.
-              description:
-                type: string
-                description: Human-readable description of what this phase does.
-              deploymentGate:
-                type: string
-                description: Gate condition to verify before proceeding to next phase.
-          description: Ordered list of migration phases.
-        recommendedActions:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentRecommendedAction'
-        metadata:
-          type: object
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [phases]
           properties:
-            tool:
-              type: string
-            command:
-              type: string
-            version:
-              type: string
-            generatedAt:
-              type: string
-            adapter:
+            summary:
               type: string
-            model:
+              description: Overview of the proposed decomposition.
+            riskLevel:
               type: string
+              enum: [low, medium, high, critical]
+              description: Risk level of the original unsafe DDL.
+            findings:
+              type: array
+              items:
+                $ref: '#/components/schemas/AgentFinding'
+              description: Issues found in the original migration.
+            phases:
+              type: array
+              items:
+                type: object
+                required: [name, sql, description]
+                properties:
+                  name:
+                    type: string
+                    enum: [expand, backfill, switch, contract]
+                  sql:
+                    type: string
+                    description: SQL content for this phase.
+                  description:
+                    type: string
+                    description: Human-readable description of what this phase does.
+                  deploymentGate:
+                    type: string
+                    description: Gate condition to verify before proceeding to next phase.
+              description: Ordered list of migration phases.
 
     ExplainResult:
       type: object
       description: >-
         Result from explain command. Contains a human-readable explanation
         of another command's output, suitable for PR comments or release decisions.
-      required: [summary, riskLevel, explanation]
-      properties:
-        summary:
-          type: string
-          description: One-line summary for quick scanning.
-        riskLevel:
-          type: string
-          enum: [low, medium, high, critical]
-          description: Assessed urgency of the underlying issue.
-        explanation:
-          type: string
-          description: >-
-            Multi-paragraph human-readable explanation in Markdown format.
-            Written for non-DBA audiences.
-        findings:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentFinding'
-          description: Key points extracted from the command output.
-        recommendedActions:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentRecommendedAction'
-          description: Concrete next steps for the reader.
-        sourceCommand:
-          type: string
-          description: The command that produced the input (e.g. "migraguard lint").
-        metadata:
-          type: object
+      allOf:
+        - $ref: 'components.yaml#/schemas/agent-audit-result'
+        - type: object
+          required: [explanation]
           properties:
-            tool:
-              type: string
-            command:
-              type: string
-            version:
+            summary:
               type: string
-            generatedAt:
+              description: One-line summary for quick scanning.
+            riskLevel:
               type: string
-            adapter:
+              enum: [low, medium, high, critical]
+              description: Assessed urgency of the underlying issue.
+            explanation:
               type: string
-            model:
+              description: >-
+                Multi-paragraph human-readable explanation in Markdown format.
+                Written for non-DBA audiences.
+            findings:
+              type: array
+              items:
+                $ref: '#/components/schemas/AgentFinding'
+              description: Key points extracted from the command output.
+            recommendedActions:
+              type: array
+              items:
+                $ref: '#/components/schemas/AgentRecommendedAction'
+              description: Concrete next steps for the reader.
+            sourceCommand:
               type: string
+              description: The command that produced the input (e.g. "migraguard lint").