docs(adr): ADR-0050 records that Composer runs as prisma deploy and prisma dev; ADR-0049 gains its rejected alternatives

[wmadden-electric]

A reader of ADR-0003 today is told:

prisma-composer deploy src/module.ts

That command no longer exists. What actually runs is:

prisma deploy src/module.ts       # deploy
prisma dev src/module.ts          # run locally
# teardown and logs: the destroy and log operations from @prisma/composer/control, called from a script

Decision

This PR adds ADR-0050: Composer runs as prisma deploy and prisma dev; it has no binary of its own. It records a decision that was already implemented in #331 but never written down, and amends the ADRs that still describe the old binary. Separately, it adds to ADR-0049's alternatives the rejected ways to keep a Composer-owned effect check, marked as an amendment.

What the ADR records

1. @prisma/composer-cli declares no bin. It ships only the command family that the prisma CLI (prisma/prisma-cli) mounts. The prisma CLI mounts exactly two Composer commands: prisma deploy <entry> and prisma dev <entry>.
2. deploy and dev are mounted at the root as bare verbs on purpose, like prisma init, rather than under a noun (prisma project deploy). Most prisma commands are noun then verb (prisma auth login).
3. destroy and log have no command. They stay as operations on @prisma/composer/control, and the guides show a short script for each. A teardown script needs PRISMA_SERVICE_TOKEN and PRISMA_WORKSPACE_ID; it cannot use the prisma auth login session.
4. Mounting destroy was rejected. The CLI's destructive verb is delete, and no Composer command takes --production (prisma deploy targets production by leaving out --stage). Where teardown and logs belong in the prisma command tree is not decided; that is tracked in TML-3521. Until then agents, like users, need a script to read prisma dev logs, and the ADR records that cost against the Agent-first principle.
5. Inside this repository, examples and CI run the published prisma CLI with a root pnpm override pointing @prisma/composer-cli at the workspace. CI teardown is scripts/composer-destroy.ts. The example destroy scripts keep --production / --stage; those flags only name the operation's two targets for this repository's scripts and are not a public command grammar. The ADR records that this was accepted.
6. scripts/lint-retired-binary-name.mjs fails CI on the old binary name in user-facing files. docs/design/ is not scanned, so ADRs can keep their history.

What else changes

• Amendment notes under the title of ADR-0003, ADR-0006, ADR-0007, ADR-0024, ADR-0041 and ADR-0043, as ADR-0017 carries for ADR-0049. Inline notes stay only where the old text would otherwise mislead: ADR-0006 (--name), ADR-0024 (the "destroy names its target" rule) and ADR-0043 (the CLI renders two of the four operations). History in the bodies is untouched.
• ADR index: a new ADR-0050 entry, and amendment annotations on the entries for ADR-0003, 0006, 0007, 0024, 0041 and 0043.
• ADR-0049 alternatives, marked with an amendment note under its title: adds the rejected alternatives to failing fast on a broken effect tree (an engine veto hook, Composer loading the config itself, an import-time check in @prisma/composer/config, lazy Alchemy imports in the /control entries), and states the exit code (2) of CLI.CONFIG_UNREADABLE.
• Domain docs (deploy-cli.md, local-dev.md, 10-domains/README.md, core-model.md, module-composition.md, glossary.md): command names updated to prisma deploy / prisma dev, and destroy / log described as operations. These are living docs, so they are edited in place. Every remaining description of prisma-composer.config.ts as Composer's config file, in deploy-cli.md, core-model.md and module-composition.md, now says the composer section of prisma.config.ts, per ADR-0049. No doc under docs/design/ outside the ADR bodies still names the old file. deploy-cli.md also lists all four deploy flags and the CONFIG.FIELD_RETIRED / CONFIG.FILE_RETIRED errors. local-dev.md now gives log's real tail default (0), drops a claimed pointer from dev to log that the code does not print, and describes local Postgres as the @prisma/dev servers the emulator hosts, not the ORM CLI's prisma dev command.

Docs only. Checks: pnpm lint (exit 0; existing warnings only), pnpm lint:retired-binary-name (clean), and a relative-link check over the changed docs (no new broken links).

Alternatives considered

• Amend the ADRs without a new ADR: rejected. The retirement and the resulting command surface are a durable decision with their own reasoning (why deploy and dev are bare, why destroy has no command). This repository's rule is that a decision future readers need to understand gets an ADR (docs/design/90-decisions/README.md).
• Rewrite the old ADRs' examples to the new commands: rejected. ADRs are append-only; amendment notes keep the record honest about what was decided when.

Refs: TML-3340, TML-3521 (where teardown and logs go in the command tree). Related: #331 (binary removed), prisma/prisma-cli#330 (first pinned the host to Composer 0.26.0, the first version without the binary; the host now pins 0.28.0).

Agent: saruman-38

🤖 Generated with Claude Code

[prisma-gizmo]

✅ Gizmo reviewed a317dad — posted 0 inline comment(s) this pass.

Open findings: none

Change walkthrough

This PR writes down a decision that #331 implemented but never recorded: Composer has no binary of its own — the prisma CLI mounts exactly two Composer commands, prisma deploy <entry> and prisma dev <entry>. It adds ADR-0050, amends the ADRs that still describe the retired prisma-composer binary, and updates the living domain docs to match.

ADRs. ADR-0050 records the two-command surface, why deploy/dev are mounted as bare root verbs, why a destroy command was rejected, and that destroy/log remain @prisma/composer/control operations called from scripts — with TML-3521 tracking where they land in the command tree. ADR-0049 gains the rejected alternatives for keeping a Composer-owned effect check. ADRs are treated as append-only: ADR-0003, 0006, 0007, 0024, 0041 and 0043 get amendment notes under their titles, with inline corrections only where the old text would mislead.

Domain docs. deploy-cli.md, local-dev.md, the 10-domains index, core-model, module-composition and the glossary are edited in place: new command names, destroy/log described as operations, and every stale prisma-composer.config.ts description replaced with the composer section of prisma.config.ts per ADR-0049. local-dev.md fixes log's real tail default and describes the Postgres emulator as @prisma/dev servers.

CI. scripts/lint-retired-binary-name.mjs fails CI on the old binary name in user-facing files while exempting docs/design/ so ADR history survives.

Delta since the last pass. The glossary's provisioning-plane entry was refreshed to alchemy@2.0.0-beta.81 / effect@^4.0.0, consistent with the merge from main that moved the public packages from exact effect pins to alchemy's semver range, and the 10-domains index now says deploy-cli.md and local-dev.md rest on ADR-0049 and ADR-0050.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 34337c8b-8e3b-4455-8d2d-0e70a55134fe

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[prisma-gizmo]

New findings: 🟡 1 minor · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

Still open from previous reviews: 🟡 1 minor

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.