feat: deploy a stage as an isolated Prisma Cloud Branch (ADR-0022/0023)

[wmadden-electric]

What

prisma-app deploy --stage <name> now provisions the whole topology into an isolated Branch of the app's single Prisma Cloud Project — its own compute, database, config, and Alchemy state — so an app can run production plus staging plus per-PR previews side by side.

Implements ADR-0022 (a Prisma App is one Project; a Stage is a Branch) and ADR-0023 (a stage is a deploy-time environment; the CLI resolves Project + Branch outside Alchemy before the stack runs).

Model

• A Prisma App = one Project. Its Systems become Apps (compute services) + Databases inside that Project.
• A Stage = a Branch. No --stage → the project-level production environment (unchanged). --stage X → an isolated Branch X.
• Two-phase deploy: the CLI ensures the Project and Branch via the Management API before Alchemy, injecting PRISMA_PROJECT_ID / PRISMA_BRANCH_ID into the alchemy child; the target then provisions resources within them. Neither container is an Alchemy resource (a Branch can't live inside the state namespace named after it; the Project is shared across all stages).
• Config class = branchId ? 'preview' : 'production', mechanical — never a role lookup.

Changes

• @prisma/alchemy — resolveContainer (adopt-oldest-by-name Project resolution + create-if-absent Branch, ensure flag for find-only destroy); deleteBranch; Database/ComputeService gain branchId (Database attaches via PATCH, ComputeService via the create body — see note).
• @prisma/app-cli — resolves + injects the ids for deploy and destroy; destroy requires an explicit target (--stage <name> or --production; a bare destroy errors, so an omitted stage can never silently tear down production); git-ref stage-name validation; soft-deletes the named-stage Branch after teardown.
• @prisma/app-cloud — the target references the injected Project instead of minting one, and threads branchId/class through every resource.
• Docs — ADR-0022/0019, the slice spec/plan, and a design-decisions log.

Proven live

Deployed examples/storefront-auth against a real workspace:

Step	Result
deploy (production)	24 resources on the main branch
deploy --stage staging	isolated staging branch — own compute + own empty Postgres
staging auth.verify()	{ok:true} (reaching its own DB)
staging config	all env vars class:preview + branchId
re-deploy	no-op (idempotent)
destroy --stage staging	staging Branch soft-deleted; production untouched + still {ok:true}
destroy --production	prod resources gone; main branch survives

The live test also caught a real bug missed by unit tests + code review: compute-service names are unique per Branch, so a project-scoped create collided with production on main — fixed by creating on the Branch via the create body (design-decision #3).

Note

Supersedes #37 — that PR's ADR-0016 is the same "App=Project, Stage=Branch" decision, renumbered here to ADR-0022 (main independently took ADR-0016–0021 after that branch forked). #37 is being closed as superseded.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

@prisma/alchemy

npm i https://pkg.pr.new/@prisma/alchemy@42

@prisma/app

npm i https://pkg.pr.new/@prisma/app@42

@prisma/app-assemble

npm i https://pkg.pr.new/@prisma/app-assemble@42

@prisma/app-cli

npm i https://pkg.pr.new/@prisma/app-cli@42

@prisma/app-cloud

npm i https://pkg.pr.new/@prisma/app-cloud@42

@prisma/app-nextjs

npm i https://pkg.pr.new/@prisma/app-nextjs@42

@prisma/app-node

npm i https://pkg.pr.new/@prisma/app-node@42

@prisma/app-rpc

npm i https://pkg.pr.new/@prisma/app-rpc@42

prisma-app

npm i https://pkg.pr.new/prisma-app@42

commit: ce59644

[wmadden]

Preemptively approved. Fix comments first

[wmadden]

This deserves to be documented in the domains/ documentation. We're introducing important, long-lived concepts: a stage (which equates to a Branch on PDP) and in the Alchemy domain, we're altering its state store logic.

[wmadden-electric]

Documented in 4a9d533: 10-domains/deploy-cli.md gains the container-resolution pipeline step and a "Stages and containers" section (explicit-destroy contract included); 03-domain-model/glossary.md gains Stage and Container — Project/Branch entries; the Alchemy-domain facts landed in 05-prisma-cloud/alchemy-lowering.md (Branch-per-stage placement, the resolveContainer/deleteBranch client and its reuse of the state-bootstrap idiom, and state keying unchanged — Project = stack, Branch = stage); two stale claims in pdp-data-model.md ("only ever touches the production branch", "future stages story") corrected. This ADR is now ADR-0024. On "altering its state store logic": the state store itself is unchanged by this slice — @prisma/alchemy gained the sibling container-resolution client, which shares the store bootstrap's client and adopt-oldest idiom; the docs say exactly that.

[wmadden]

Why aren't we using the Prisma management API client/sdk?

[wmadden-electric]

We are — client here is @prisma/management-api-sdk's createManagementApiClient (its typed openapi-fetch surface), constructed once from PRISMA_SERVICE_TOKEN in packages/alchemy/src/client.ts and provided to every provider through the ManagementClient service. The client.GET/POST/PATCH('/v1/…', { params }) calls are that SDK's calling convention (path-template + typed params), not hand-rolled HTTP.

[wmadden]

This looks like Prisma CLoud config leaking into the framework

[wmadden-electric]

Agreed — the PRISMA_PROJECT_ID/PRISMA_BRANCH_ID names here (and the resolveContainer import in ensure-containers.ts) are Prisma Cloud specifics living in the otherwise target-agnostic CLI. It is the accepted MVP shape of ADR-0024's "CLI ensures containers" decision. Recorded the durable fix as a Drive deferred item in this PR (68d7d77, .drive/deferred.md): a deploy-plane hook on the extension descriptor — the extension resolves its own containers and supplies the child env; the CLI stays generic.

[wmadden]

Both these ADRs are walls of text, impenetrable to the poor reader

[wmadden-electric]

Rewritten in 7a05ac0 (and its pair in the same commit). Both ADRs now open with a grounding example — this one the system() snippet plus the Workspace → Project → Branch tree it lowers to — lead with the decision, and end with alternatives. Cut as transient: the "current mapping / remaining work" pre-implementation snapshot and the Open Questions section (every question in it had been answered by the companion ADR). ~40% shorter. Note: renumbered to ADR-0023 — main took 0022 (data-deps contract) while this was in review.