Skip to content

Add a CLI compatibility contract: version guard, canary, matrix - #13

Merged
kristof-siket merged 1 commit into
fix/current-prisma-clifrom
policy/cli-compatibility
Aug 25, 2026
Merged

Add a CLI compatibility contract: version guard, canary, matrix#13
kristof-siket merged 1 commit into
fix/current-prisma-clifrom
policy/cli-compatibility

Conversation

@kristof-siket

Copy link
Copy Markdown
Collaborator

Stacked on #12 (base is fix/current-prisma-cli; retarget to main once #12 merges).

Why

The 8.0.0-rc.8 command rename broke every released action version at once (v1.0.0–v1.5.0, the floating v1, and main), because the action floats against whatever CLI it finds — the repository's prisma devDependency preferred, an unmaintained fallback otherwise — with no compatibility contract. Users found out via CLI.UNKNOWN_COMMAND in their deploy logs.

What

  • Version guard (cli.mjs, main.mjs): before deploying with a repository's own prisma devDependency, the action probes prisma --version and fails with an error naming the supported range (>= 8.0.0-rc.8, top-level prisma deploy) when the CLI falls outside it. An unreadable or unparseable version is a warning, never a blocker — the guard must not break a working deploy over output formatting. The bunx fallback is not probed; its version is the release's own pinned default.
  • Canary workflow (.github/workflows/canary.yml): daily + on-demand, probes prisma@next for the exact command shape the action invokes. Subtlety verified against the real CLI: --help exits 0 even for unknown commands (falls back to the general help, whose Examples section even contains a bare $ prisma deploy), so the probe greps for the deploy-specific usage line $ prisma deploy [options] rather than trusting exit codes. It also asserts the version guard accepts prisma@next (a guard that rejects the upcoming release would block users the day it ships), and posts a non-failing notice the day a top-level destroy appears so mode: destroy can be wired back up.
  • Compatibility matrix in the README, stating the policy and the supported range per release line.

Verified

  • 53 tests pass (node --test tests/*.test.mjs), including new coverage for version extraction (JSON envelope, human line, dev-build suffix) and range checks (rc.7 rejected, rc.8/rc.9/stable/later accepted, pre-8 rejected).
  • All three canary probes dry-run green locally against prisma@next (currently 8.0.0-rc.9).

🤖 Generated with Claude Code

@kristof-siket
kristof-siket force-pushed the fix/current-prisma-cli branch from 0f2a5c4 to e81bbfd Compare August 25, 2026 10:14
The 8.0.0-rc.8 command rename broke every released action version at
once because releases float against whatever CLI they find, with no
compatibility contract. Three guardrails:

- A version guard: before deploying with a repository's own prisma
  devDependency, check its version and fail with an error naming the
  supported range (>= 8.0.0-rc.8) instead of CLI.UNKNOWN_COMMAND. An
  unreadable or unparseable version only warns — the guard must never
  break a working deploy over output formatting.
- A daily canary workflow probing prisma@next for the command shape
  the action invokes. `--help` exits 0 even for unknown commands (the
  CLI falls back to the general help), so the probe greps for the
  deploy-specific usage line. It also checks the version guard accepts
  prisma@next, and posts a notice the day a destroy command appears.
- A compatibility matrix and the policy, documented in the README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@kristof-siket
kristof-siket force-pushed the policy/cli-compatibility branch from c8274fe to eea4fcd Compare August 25, 2026 10:16
@kristof-siket
kristof-siket marked this pull request as ready for review August 25, 2026 10:39
@kristof-siket
kristof-siket merged commit a5ca38f into fix/current-prisma-cli Aug 25, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant