From da29fae98a218827089ed17bdd7db42c21d5605f Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 12 Aug 2026 18:57:47 +0200 Subject: [PATCH] drive(prisma-cli-v8): brief for the S5 cutover - retire prisma/prisma's own shell The ports are merged but prisma-next still runs the commander shell, with the clipanion migration CLI beside it and two open PRs (#29984, #29985 in prisma/prisma) conflicting ahead of the cutover. The brief hands an agent the mandate (land the two PRs, rewire the bin, delete the old shells, keep the orm-toolchain publish surface), the reading order with absolute paths, the warning that no s5-orm.md contract exists anywhere, and the standing process rules. Co-Authored-By: Claude Fable 5 Signed-off-by: willbot Signed-off-by: Will Madden --- .../assets/briefs/s5-cutover-handover.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 .drive/projects/prisma-cli-v8/assets/briefs/s5-cutover-handover.md diff --git a/.drive/projects/prisma-cli-v8/assets/briefs/s5-cutover-handover.md b/.drive/projects/prisma-cli-v8/assets/briefs/s5-cutover-handover.md new file mode 100644 index 00000000..8c388a10 --- /dev/null +++ b/.drive/projects/prisma-cli-v8/assets/briefs/s5-cutover-handover.md @@ -0,0 +1,63 @@ +# S5 cutover handover — retire prisma/prisma's own CLI shell + +Written 2026-08-12 for an agent with NO prior context. The operator is Will Madden. All disk paths are absolute paths on the operator's machine. The drive project directory lives in the prisma-cli repo; clone or use the checkout at `/Users/wmadden/Projects/prisma/prisma-cli`. + +## 1. Context + +The prisma-cli-v8 project builds one unified `prisma` CLI on `@prisma/cli-engine`, replacing three CLIs (`@prisma/cli` 3.x platform, `prisma-composer`, `prisma-next` ORM). State as of 2026-08-12: the unified binary shipped (prisma-cli PR #164) and `@prisma/cli@8.0.0-rc.1` is published on npm under the `next` dist-tag — it mounts the platform, composer, and ORM command families, the ORM family arriving via `@prisma/orm-toolchain@8.0.0-rc.1-dev.40`, which is built from prisma/prisma's `packages/1-framework/3-tooling/cli` sources. + +What never landed is the S5 slice's tail in **prisma/prisma**: its own CLI package (`@internal/cli`, bin `prisma-next`) still runs the OLD shell. `packages/1-framework/3-tooling/cli/src/cli.ts` is the commander shell, `src/migration-cli.ts` is the clipanion migration CLI, and `package.json` still depends on `commander ^15` and `clipanion 4.0.0-rc.4` — while the ported engine-based commands sit finished next to them in `src/orm/`. The rollout plan rules "prisma/prisma retires its own CLI at S5". That retirement is your job. + +## 2. The mandate + +1. **Land the two open port PRs first** — both are `CONFLICTING` against main and block the cutover: + - https://github.com/prisma/prisma/pull/29984 — "db verify, db sign and migration check exit 4 on findings, 2 on errors". Approved; rebase, keep it green, merge. + - https://github.com/prisma/prisma/pull/29985 — "Port lsp onto the engine by giving the language server an injectable transport". Needs review; rebase, get it reviewed, merge. +2. **The cutover PR**: rewire `@internal/cli`'s `prisma-next` bin from the commander shell to the engine tree (the `src/orm/` family mounted on `@prisma/cli-engine`), delete `src/cli.ts`'s commander shell and `src/migration-cli.ts`'s clipanion CLI, and remove the `commander` and `clipanion` dependencies. Whatever the old shells provided that the engine tree does not is a parity divergence to enumerate, not silently drop. +3. **Do not break the publish surface.** `@prisma/orm-toolchain` publishes from these sources and the unified CLI pins it exactly. Find the publish mechanism (search prisma/prisma for how `@internal/cli` becomes `@prisma/orm-toolchain` — likely `@internal/publish-surface`), and prove the family export (`./cli` subpath: `ormCommandFamily`, `ormConfigSection`) survives your deletion. +4. **Record divergences** in a new file `/Users/wmadden/Projects/prisma/prisma-cli/.drive/projects/prisma-cli-v8/assets/s2/parity-divergences-s5-cutover.md` (same entry format as the sibling files in that directory). + +## 3. Explicitly NOT yours + +- The `prisma-next` npm name handoff (trusted-publisher config moving to prisma-cli) — operator-owned, rollout plan step 3. +- Publishing anything to npm. Never. +- Engine changes (`packages/cli-engine` in prisma-cli). A gap in the engine is a STOP-and-surface with a recommendation, never an improvised change. +- Engine-pin convergence (orm-toolchain pins `@prisma/cli-engine@0.0.9`; the workspace ships `8.0.0-rc.1`). Deferred by operator ruling 2026-08-12 until the pins converge at release time — do not bump pins unless the operator says so. + +## 4. Where the documents live + +Drive project directory (canonical, in the prisma-cli repo): `/Users/wmadden/Projects/prisma/prisma-cli/.drive/projects/prisma-cli-v8/` + +Read in this order: + +1. `plan.md` in that directory — project frame, slice list, dependency graph, coverage ledger. §S5 and §S7. +2. `spec.md` — project requirements and DoD. FR6 (parity bar), FR7 (product integration), the non-goals. +3. `specs/s2-overview.md` — the standing rulings that bind every slice. +4. `assets/rollout-plan.md` — the npm rollout: names, dist-tags (RC line publishes under `next`, ruling 2026-08-12), the handoff steps. +5. `assets/briefs/s5-orm-handover.md` — the brief the original S5 agent worked from: scope, reading order, mechanics. Still the best statement of S5's intent. +6. `assets/briefs/1b-leftovers-prisma-prisma.md` — the older prisma/prisma leftovers brief S5 was meant to close out. +7. `deferred.md` — everything carried between slices, including the pin-convergence entry and the two flaky-test entries. +8. `specs/s7-release.md` — the S7 contract; its §2 records what the ORM family exports and how the unified CLI consumes it. +9. Engine design docs in `assets/engine/`: `engine-interface-draft.ts` (the normative interface with commentary) and `credential-manager-design.md` (the auth model). The ORM commands are mostly local; where one needs platform auth it declares `needs.credentials` and uses `ctx.api`, nothing else. + +**A warning about the S5 contract:** no `specs/s5-orm.md` exists — not in this directory, not in prisma/prisma. The S5 requirement numbers you will meet in citations (R-S5-23 redirects, R-S5-28 pinning) survive only in other documents' references. The real record of what S5 built is the merged PR descriptions and the code. Verify claims against source; do not trust a requirement number you cannot ground. + +prisma/prisma side: the repo has its own drive methodology docs under `drive/` at the repo root (process roles, DoD/DoR calibration) — read `drive/README.md` if you use the drive process there. ADRs live under `docs/architecture docs/adrs/`; ADR 239 (as amended by S4, 2026-08-11: findings as diagnostics in completed envelopes, typed nextActions) and ADR 245 govern the error/result conventions your cutover must preserve. + +Merged S5-era PRs worth reading for shape (all prisma/prisma): #29970 (foundations + first command), #29973, #29980, #29981, #29982, #29983, #29986, #29987 (the ports), #29957/#29958 (the S4 ADR amendments). + +## 5. Process rules (operator-enforced, non-negotiable) + +- Git identity is the `wmadden-electric` bot. Stage explicitly by path (never `git add -A`; never anything under `wip/`). Commit: `git commit -s --trailer "Signed-off-by: Will Madden "`, body ending `Co-Authored-By:` line naming your model. Push only to `git@github-wmadden-electric:prisma/prisma.git` remotes. Never force-push a pushed branch — if a rebase would require it, rebuild the branch as remote tip + merge, or cut a fresh branch. +- The bot has push access to prisma/prisma (dozens of merged PRs prove it). +- Tests before implementation. No `vi.mock`/`vi.doMock`. pnpm only. +- Working files go under `wip/` inside the worktree, never `/tmp`. +- Verification per dispatch: the touched packages' suites, `pnpm typecheck`, repo lint — measured as the tool's own exit codes. +- PR descriptions: grounding example first (a real command run, before/after), then the decision, then the narrative, alternatives last. No internal process codes. +- Address every CodeRabbit thread — fix or decline with verified evidence — reply and resolve each before merging. +- Reports to the operator: plain English, short, full sentences. No invented jargon. Banned words: "load-bearing", "smoking gun", "belt and suspenders", "gate". Bring questions to decide, not decisions to ratify. Never use the question UI. Point at files with absolute disk paths and branch-qualified GitHub URLs. +- A merged PR is the deliverable. Do not end a dispatch with finished work sitting unpushed. + +## 6. Your first report + +Confirm you read the documents in §4; state the rebase status of #29984 and #29985 and what their conflicts touch; state where `@prisma/orm-toolchain`'s publish mechanism lives and what your cutover must preserve; name anything in the old shells (commander help output, migration-cli interactivity, exit codes) you believe has no equivalent on the engine tree — each is either a divergence entry or a STOP. Then your dispatch plan.