feat: require --prod for production deploys

[luanvdw]

Summary

• resolve/create the deploy Branch through the Management API and use typed branch.role as the only production authority
• add the production deploy gate: first production deploy auto-promotes; later production deploys require --prod; --prod --yes skips the prompt; --yes alone does not authorize production
• update CLI docs/help/error metadata and add focused gate/provider/controller tests
• extracted the gate into lib/app/production-deploy-gate after thermonuclear review so the app controller stays orchestration-focused

Validation

• corepack pnpm --filter @prisma/cli exec vitest run tests/production-deploy-gate.test.ts tests/app-provider.test.ts tests/app-controller.test.ts tests/app-env-vars.test.ts
• corepack pnpm --filter @prisma/cli test
• corepack pnpm --filter @prisma/cli build

Note: the full suite needs localhost binding for auth-login callback tests; it passed with sandbox escalation. The build still emits the existing tsdown define warning.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5aa2e16b-9fd3-4219-b03a-e1443c48a57f

📥 Commits

Reviewing files that changed from the base of the PR and between b9a0aab and 39f1034.

📒 Files selected for processing (11)

• docs/product/command-spec.md
• docs/product/error-conventions.md
• packages/cli/src/commands/app/index.ts
• packages/cli/src/controllers/app.ts
• packages/cli/src/lib/app/preview-provider.ts
• packages/cli/src/lib/app/production-deploy-gate.ts
• packages/cli/src/shell/command-meta.ts
• packages/cli/tests/app-controller.test.ts
• packages/cli/tests/app-env-vars.test.ts
• packages/cli/tests/app-provider.test.ts
• packages/cli/tests/production-deploy-gate.test.ts

---

Summary by CodeRabbit

Release Notes

• New Features

  • Added --prod flag to app deploy command to explicitly authorize production deployments
  • First production deployment now auto-promotes without requiring --prod
  • Subsequent production deployments require --prod flag; missing it produces validation error
  • --yes flag now only skips confirmation when --prod is also present

• Documentation

  • Updated deployment command documentation with --prod flag details and examples
  • Added production deployment validation error guidelines

Walkthrough

This PR adds a --prod flag to prisma-cli app deploy to enforce explicit production deployment intent. The provider interface gains a resolveBranch method to resolve branch roles from the remote provider, replacing local-only name-based derivation. A new production deployment gate enforces that subsequent production deploys require --prod, auto-promotes the first production deploy, and handles interactive confirmation. The controller integrates the gate and updates all project-resolution paths to use remote branch roles.

Changes

Production Deployment Gate Feature

Layer / File(s)	Summary
Provider contract and branch resolution packages/cli/src/lib/app/preview-provider.ts, packages/cli/tests/app-provider.test.ts	PreviewBranchRecord interface added with id, name, role. PreviewAppProvider now exports resolveBranch(projectId, { branchName, signal? }) method. Internal RawBranchRecord includes role field; listBranches and resolveOrCreateBranch now explicitly map and propagate role from API. Test validates resolveBranch behavior.
Production deployment gate enforcement packages/cli/src/lib/app/production-deploy-gate.ts, packages/cli/tests/production-deploy-gate.test.ts	enforceProductionDeployGate implemented as async CLI gate deciding deployment eligibility: auto-promotes first production deploy (no appId or no live deployment), requires --prod flag for subsequent deployments with existing live deployment, handles interactive confirmation via confirmPrompt when TTY available, throws structured CliError (with code PROD_DEPLOY_REQUIRES_FLAG, etc.) and renders status/confirmation to stderr. Helper functions format deployment age, render user messages, and construct typed errors. Comprehensive test suite validates preview/production branch flows, auto-promotion, confirmation prompting, and error conditions.
Controller integration and branch resolution packages/cli/src/controllers/app.ts, packages/cli/tests/app-controller.test.ts	runAppDeploy options extended with prod?: boolean. Controller imports enforceProductionDeployGate and calls it after branch/app resolution. resolveDeployProjectContext updated across all project paths (explicit, created, env-selected, local-pin, platform-mapped, interactive) to use new withRemoteDeployBranch helper instead of withDeployBranch, ensuring branch.kind is derived from remote provider role. New test added for "production" branch name (asserts it is preview branch, avoids deployment listing); existing test updated to assert branch kind is "preview". Tests mock resolveBranch and branches endpoint.
CLI flag definition and parsing packages/cli/src/commands/app/index.ts, packages/cli/tests/app-env-vars.test.ts	app deploy command adds --prod boolean flag option. Action handler extracts prod from CLI options and passes prod: true/false to runAppDeploy. Tests verify --prod flag is parsed and propagated in call arguments to controller.
Documentation and examples docs/product/command-spec.md, docs/product/error-conventions.md, packages/cli/src/shell/command-meta.ts	Command spec updated to include --prod in prisma-cli app deploy synopsis. Production-authority rules clarified: authority tied to resolved Branch role; first production deploy auto-promoted without flag; subsequent production deploys require --prod; --yes only bypasses confirmation when --prod present. Error conventions document adds PROD_DEPLOY_REQUIRES_FLAG error code definition. Command examples include new prisma-cli app deploy --prod --yes usage.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'feat: require --prod for production deploys' clearly and concisely summarizes the main feature addition, which is the production deploy gate requiring the --prod flag for production deployments.
Description check	✅ Passed	The PR description is directly related to the changeset, providing a clear summary of the implementation approach, validation steps, and the extracted gate module for production deployment authorization.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/j1-prod-deploy-gate-prework

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/j1-prod-deploy-gate-prework

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}