migraguard 0.8.1 → 0.8.3

package/README.md

@@ -605,6 +605,8 @@ No. `verify` creates a temporary shadow DB, applies migrations twice, then drops
 
 ## Detailed Documentation
 
+- [docs/cli-reference.md](docs/cli-reference.md) — Generated CLI reference (commands, options, exit codes, AI agent policies)
+- [cli-contract.yaml](cli-contract.yaml) — Machine-readable CLI contract ([CLI Contracts](https://www.npmjs.com/package/cli-contracts) format)
 - [docs/commands.md](docs/commands.md) — Full command reference with options and examples
 - [docs/state-model.md](docs/state-model.md) — Apply/check/resolve/squash flows, INSERT-only design, regression detection
 - [docs/dag-internals.md](docs/dag-internals.md) — Dependency analysis, explicit declarations, DAG migration compatibility

package/cli-contract.yaml

@@ -0,0 +1,706 @@
+# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
+cliContracts: 0.1.0
+
+info:
+  title: migraguard CLI
+  version: 0.8.3
+  description: >-
+    PostgreSQL-first schema-aware deployment control — idempotent SQL migrations
+    with CI-enforced integrity checks, expand/contract migration orchestration,
+    schema drift detection, and unified gating across database, application,
+    and infrastructure rollouts. MySQL and SQLite supported as secondary dialects.
+  license:
+    name: MIT
+
+commandSets:
+  migraguard:
+    summary: Schema-aware deployment control for SQL migrations.
+    executable: migraguard
+
+    globalOptions:
+      - name: version
+        aliases: [V]
+        description: Print version and exit.
+        schema:
+          type: boolean
+
+      - name: help
+        aliases: [h]
+        description: Show help and exit.
+        schema:
+          type: boolean
+
+    commands:
+      # ── new ──────────────────────────────────────────
+      new:
+        summary: Create a new migration SQL file with UTC timestamp.
+        description: >-
+          Generates a timestamped SQL migration file in the configured migrations
+          directory. With --expand-contract, creates a migration group directory
+          containing phased files (expand, backfill, switch, contract).
+        usage:
+          - migraguard new create_users_table
+          - migraguard new --expand-contract rename_username_to_handle
+
+        arguments:
+          - name: name
+            index: 0
+            required: true
+            description: Migration name (alphanumeric and underscores).
+            schema:
+              type: string
+
+        options:
+          - name: expand-contract
+            description: Create an expand/contract migration group (Class B).
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: Migration file (or group directory) created successfully.
+            stdout:
+              format: text
+            files:
+              - path: db/migrations/{timestamp}__{name}.sql
+                required: false
+                mediaType: application/sql
+                encoding: utf-8
+                description: Single migration file (Class A).
+              - path: db/migrations/{timestamp}__{name}/1_expand.sql
+                required: false
+                mediaType: application/sql
+                encoding: utf-8
+                description: Expand phase file (Class B, with --expand-contract).
+
+          '1':
+            description: Creation failed (config error or naming conflict).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: false
+          sideEffects:
+            - file_write
+
+      # ── apply ────────────────────────────────────────
+      apply:
+        summary: Apply pending migrations via native database CLI.
+        description: >-
+          Executes pending migrations using the database's native CLI
+          (psql, mysql, or sqlite3). Uses advisory locks to prevent
+          concurrent execution. Records each application attempt in
+          the schema_migrations table.
+        usage:
+          - migraguard apply
+          - migraguard apply --with-drift-check
+          - migraguard apply --from-baseline
+
+        options:
+          - name: with-drift-check
+            description: Check schema drift before apply and update dump after.
+            schema:
+              type: boolean
+              default: false
+
+          - name: from-baseline
+            description: Apply schema.sql first, then remaining migrations.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: All pending migrations applied successfully.
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Apply failed (migration error, drift detected, regression
+              detected, or advisory lock conflict).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: high
+          requiresConfirmation: true
+          idempotent: false
+          sideEffects:
+            - database_write
+          recommendedBeforeUse:
+            - Run migraguard check to verify metadata integrity.
+            - Run migraguard lint to check for unsafe DDL patterns.
+            - Consider running with --with-drift-check for local development.
+
+      # ── check ────────────────────────────────────────
+      check:
+        summary: Verify metadata integrity (no DB connection required).
+        description: >-
+          Validates file list and checksums in metadata.json against the
+          actual migration files on disk. Detects tampered, missing, or
+          extra files. Runs offline without a database connection, making
+          it suitable for CI/CD PR checks.
+        usage:
+          - migraguard check
+
+        exits:
+          '0':
+            description: Metadata integrity verified. All checksums match.
+            stdout:
+              format: text
+
+          '1':
+            description: Integrity check failed (tampered, missing, or extra files).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── squash ───────────────────────────────────────
+      squash:
+        summary: Squash multiple new migration files into one.
+        description: >-
+          Merges pending (unapplied) migration files into a single file
+          for release. Ensures one release = one file, simplifying error
+          recovery and hotfix workflows.
+        usage:
+          - migraguard squash
+
+        exits:
+          '0':
+            description: Migration files squashed successfully.
+            stdout:
+              format: text
+            files:
+              - path: db/migrations/{timestamp}__{description}.sql
+                required: true
+                mediaType: application/sql
+                encoding: utf-8
+                description: Squashed migration file.
+
+          '1':
+            description: Squash failed (nothing to squash or conflict).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: medium
+          requiresConfirmation: false
+          idempotent: false
+          sideEffects:
+            - file_write
+            - file_delete
+          recommendedBeforeUse:
+            - Ensure all pending files are ready for release.
+
+      # ── lint ─────────────────────────────────────────
+      lint:
+        summary: Run built-in safety rules on migration files.
+        description: >-
+          Performs AST-based lint analysis on migration SQL files using
+          libpg-query (38 rules for PostgreSQL) or node-sql-parser
+          (17 generic rules for MySQL/SQLite). Detects unsafe DDL patterns
+          such as missing IF NOT EXISTS, non-concurrent index creation,
+          missing lock timeouts, and prohibited operations.
+        usage:
+          - migraguard lint
+
+        exits:
+          '0':
+            description: All lint rules passed.
+            stdout:
+              format: text
+
+          '1':
+            description: Lint violations found.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── dump ─────────────────────────────────────────
+      dump:
+        summary: Dump and normalize current DB schema.
+        description: >-
+          Executes pg_dump (PostgreSQL), mysqldump (MySQL), or sqlite3 .schema
+          (SQLite) to capture the current database schema, then normalizes the
+          output and saves it to schema.sql.
+        usage:
+          - migraguard dump
+
+        exits:
+          '0':
+            description: Schema dump saved successfully.
+            stdout:
+              format: text
+            files:
+              - path: db/schema.sql
+                required: true
+                mediaType: application/sql
+                encoding: utf-8
+                description: Normalized schema dump.
+
+          '1':
+            description: Dump failed (connection error or CLI not found).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects:
+            - file_write
+
+      # ── diff ─────────────────────────────────────────
+      diff:
+        summary: Show diff between current DB schema and saved schema.sql.
+        description: >-
+          Dumps the current database schema, normalizes it, and compares
+          it against the saved schema.sql file. Exits with code 1 if
+          differences are found, enabling CI gating for schema drift.
+        usage:
+          - migraguard diff
+
+        exits:
+          '0':
+            description: No differences found. DB schema matches schema.sql.
+            stdout:
+              format: text
+
+          '1':
+            description: Differences found between DB schema and schema.sql.
+            stdout:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── status ───────────────────────────────────────
+      status:
+        summary: Show migration status (applied / pending / failed / skipped).
+        description: >-
+          Queries the schema_migrations table and cross-references with
+          migration files on disk to display the status of each migration.
+        usage:
+          - migraguard status
+
+        exits:
+          '0':
+            description: Status displayed successfully.
+            stdout:
+              format: text
+
+          '1':
+            description: Failed to retrieve status (connection error).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── resolve ──────────────────────────────────────
+      resolve:
+        summary: Mark a failed migration as skipped (requires human judgment).
+        description: >-
+          Records a 'skipped' entry in schema_migrations for the specified
+          failed migration file. This unblocks subsequent migrations but
+          requires explicit human judgment that the failure has been
+          addressed by other means.
+        usage:
+          - migraguard resolve 20260301_120000__create_users_table.sql
+
+        arguments:
+          - name: file
+            index: 0
+            required: true
+            description: Failed migration file name to resolve.
+            schema:
+              type: string
+
+        exits:
+          '0':
+            description: Migration marked as skipped.
+            stdout:
+              format: text
+
+          '1':
+            description: Resolve failed (file not found or not in failed state).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: high
+          requiresConfirmation: true
+          idempotent: false
+          sideEffects:
+            - database_write
+          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.
+
+      # ── editable ─────────────────────────────────────
+      editable:
+        summary: List migration files that are currently editable.
+        description: >-
+          Shows which migration files can be safely modified. In linear mode,
+          only the tail file is editable. In DAG mode, all leaf nodes are editable.
+        usage:
+          - migraguard editable
+
+        exits:
+          '0':
+            description: Editable files listed.
+            stdout:
+              format: text
+
+          '1':
+            description: Failed to determine editable files.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── verify ───────────────────────────────────────
+      verify:
+        summary: Verify migration idempotency using a shadow DB.
+        description: >-
+          Creates a temporary shadow database, applies migrations twice,
+          and confirms no errors or schema differences occur. Proves that
+          migrations are safely re-executable. The shadow DB is dropped
+          after verification.
+        usage:
+          - migraguard verify
+          - migraguard verify --all
+
+        options:
+          - name: all
+            description: Verify all migrations from scratch, not only pending.
+            schema:
+              type: boolean
+              default: false
+
+        exits:
+          '0':
+            description: All migrations verified as idempotent.
+            stdout:
+              format: text
+
+          '1':
+            description: One or more migrations failed idempotency verification.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects:
+            - database_write
+          recommendedBeforeUse:
+            - Ensure the database server is running and accessible.
+
+      # ── group-status ─────────────────────────────────
+      group-status:
+        path: [group-status]
+        summary: Show migration group state (expand/contract phases).
+        description: >-
+          Displays the current phase state of migration groups. When a
+          group name is specified, shows detailed state for that group.
+          Without arguments, shows all groups.
+        usage:
+          - migraguard group-status
+          - migraguard group-status rename_username_to_handle
+
+        arguments:
+          - name: group
+            index: 0
+            required: false
+            description: Specific group name. Shows all groups if omitted.
+            schema:
+              type: string
+
+        exits:
+          '0':
+            description: Group status displayed.
+            stdout:
+              format: text
+
+          '1':
+            description: Failed to retrieve group status.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── baseline ─────────────────────────────────────
+      baseline:
+        summary: Squash applied migrations into schema.sql baseline.
+        description: >-
+          Consolidates all applied migrations into schema.sql and
+          removes the original files. Optionally keeps migration files
+          from a specified point forward using --keep-since.
+        usage:
+          - migraguard baseline
+          - migraguard baseline --keep-since 20260301_120000__create_users_table.sql
+
+        options:
+          - name: keep-since
+            description: Keep migration files from this point forward.
+            valueName: file
+            repeatable: true
+            schema:
+              type: string
+
+        exits:
+          '0':
+            description: Baseline created successfully.
+            stdout:
+              format: text
+
+          '1':
+            description: Baseline failed.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: high
+          requiresConfirmation: true
+          idempotent: false
+          sideEffects:
+            - file_write
+            - file_delete
+          recommendedBeforeUse:
+            - Ensure all migrations have been applied to all environments.
+            - Back up migration files before running.
+
+      # ── advance ──────────────────────────────────────
+      advance:
+        summary: Record a phase state transition (for external executor).
+        description: >-
+          Updates the state of a migration group phase. Used by external
+          executors to record phase transitions in the expand/contract workflow.
+          Valid phases: expand, backfill, switch, contract.
+          Valid statuses: running, completed, failed.
+        usage:
+          - migraguard advance rename_username_to_handle expand completed
+          - migraguard advance rename_username_to_handle backfill running
+
+        arguments:
+          - name: group
+            index: 0
+            required: true
+            description: Migration group name.
+            schema:
+              type: string
+
+          - name: phase
+            index: 1
+            required: true
+            description: Phase to advance.
+            schema:
+              type: string
+              enum: [expand, backfill, switch, contract]
+
+          - name: status
+            index: 2
+            required: true
+            description: New status for the phase.
+            schema:
+              type: string
+              enum: [running, completed, failed]
+
+        exits:
+          '0':
+            description: Phase state transition recorded.
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Advance failed (invalid phase/status, group not found,
+              or invalid state transition).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: medium
+          requiresConfirmation: true
+          idempotent: false
+          sideEffects:
+            - database_write
+
+      # ── apply-phase ──────────────────────────────────
+      apply-phase:
+        path: [apply-phase]
+        summary: Apply a specific phase of a migration group via native CLI.
+        description: >-
+          Executes the SQL file for a specific phase of a migration group
+          using the database's native CLI (psql, mysql, or sqlite3).
+          Valid phases: expand, backfill, switch, contract.
+        usage:
+          - migraguard apply-phase rename_username_to_handle expand
+          - migraguard apply-phase rename_username_to_handle contract
+
+        arguments:
+          - name: group
+            index: 0
+            required: true
+            description: Migration group name.
+            schema:
+              type: string
+
+          - name: phase
+            index: 1
+            required: true
+            description: Phase to apply.
+            schema:
+              type: string
+              enum: [expand, backfill, switch, contract]
+
+        exits:
+          '0':
+            description: Phase applied successfully.
+            stdout:
+              format: text
+
+          '1':
+            description: >-
+              Phase apply failed (SQL error, group not found,
+              or invalid phase for current state).
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: high
+          requiresConfirmation: true
+          idempotent: false
+          sideEffects:
+            - database_write
+          recommendedBeforeUse:
+            - Run migraguard group-status to verify current phase state.
+
+      # ── gate ─────────────────────────────────────────
+      gate:
+        summary: Evaluate deployment gate conditions against migration group states.
+        description: >-
+          Checks whether the current migration group states satisfy
+          the specified deployment gate conditions. Used in CI/CD pipelines
+          to gate deployments on schema state. Conditions can be specified
+          via CLI options or a JSON contract file.
+        usage:
+          - 'migraguard gate --require "group:rename_username_to_handle.expand_applied"'
+          - 'migraguard gate --forbid "group:rename_username_to_handle.contract_pending"'
+          - migraguard gate --contract-file deploy-gates.json
+
+        options:
+          - name: require
+            description: Required schema state conditions.
+            valueName: condition
+            repeatable: true
+            schema:
+              type: string
+
+          - name: forbid
+            description: Forbidden schema state conditions.
+            valueName: condition
+            repeatable: true
+            schema:
+              type: string
+
+          - name: contract-file
+            description: JSON file with schema requirements.
+            valueName: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: true
+              mediaType: application/json
+              encoding: utf-8
+
+        exits:
+          '0':
+            description: All gate conditions satisfied.
+            stdout:
+              format: text
+
+          '1':
+            description: One or more gate conditions not satisfied.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects: []
+
+      # ── deps ─────────────────────────────────────────
+      deps:
+        summary: Analyze and display migration dependency graph.
+        description: >-
+          Parses migration SQL files to extract object creation/reference
+          relationships and builds a dependency graph. In DAG mode, shows
+          the full dependency tree. Optionally outputs as an interactive
+          HTML visualization.
+        usage:
+          - migraguard deps
+          - migraguard deps --html deps.html
+
+        options:
+          - name: html
+            description: Output as HTML file with interactive visualization.
+            valueName: path
+            schema:
+              type: string
+
+        exits:
+          '0':
+            description: Dependency graph displayed or HTML file generated.
+            stdout:
+              format: text
+            files:
+              - path: '{options.html}'
+                required: false
+                mediaType: text/html
+                encoding: utf-8
+                description: HTML dependency visualization (when --html specified).
+
+          '1':
+            description: Dependency analysis failed.
+            stderr:
+              format: text
+
+        x-agent:
+          riskLevel: low
+          requiresConfirmation: false
+          idempotent: true
+          sideEffects:
+            - file_write