Port ref set|delete|list and format onto the engine - #29980

Stacked on #29978. Review that first; this diff is the four commands and their tests.

What this looks like in practice

ref list, through the engine binary against examples/prisma-8-demo. The commander printed one line per ref; the engine renders a self-sizing table, and the Invariants column appears only when some ref carries any:

Ref      Contract
head     3d2c56a
staging  0b4bec6

Ref names render green, hashes cyan, and with NO_COLOR=1 every escape is stripped and the column widths still hold.

The decision

Four more commands ported as engine result commands — ref set, ref delete, ref list, format — following the template migration list set. Still additive: the commander CLI keeps working and keeps owning the prisma-next binary.

The one judgement call worth surfacing: these commands now write nothing to stdout in human mode. Two contract rules disagreed. The earlier one named ref set|delete|list among the commands whose payload lines move to the stdout presentation; the later one — written after the design discussion that established what the machine channel is for — says stdout carries only lines another program parses, and a command supplies it only where it has such lines. Set ref "x" → <hash> is a rendering for a reader, not a document. The later rule wins, so those lines are human output on stderr, and the same reasoning applies to format's success line. Recorded in the findings file so the divergence entry quotes the rule that was applied rather than the one it superseded.

Divergences from the commander CLI

• --config is no longer declared by any of the four (it is the engine's shared flag); --format pretty is --format human.
• Human output moves to stderr; zero bytes on stdout in human mode, where the commander wrote its confirmation lines there.
• --json is the engine's result frame ({"kind":"result","envelope":{…}}) rather than the bare document. The documents themselves are unchanged inside envelope.result. The contract predicted "pretty-printed"; the engine frames compactly instead, which is engine-owned and identical for every ported command — recorded so the divergence file words it correctly.
• ref list renders a table instead of one name → hash [invariants: …] line per ref. The empty case keeps its wording as an info summary.
• format loses its styled header card; the success line keeps its wording and gains the engine's ✔. format --quiet now renders it.
• Error envelopes carry typed nextActions and a docs URL instead of fix prose. Exit codes unchanged; no error codes added or changed.
• No header card was added to any ref command — the inventory records that none prints one today, so none was invented.

Reviewer notes

A module mock in the package's own suite silently broke the ported tests, in both directions. test/commands/ref.test.ts mocked @internal/migration-tools/refs and then dynamically imported the operation module under that mock. With isolate: false the operation stayed cached bound to the stubbed writeRef, so engine-level ref set wrote nothing — and the reverse file ordering defeated the old file's mock instead. That file only ever drove the operation layer, so its coverage moved wholesale onto createTestCli and the file is deleted. One case did not move: a writeRef rejection proving the temp-file-and-rename is atomic, which is @internal/migration-tools' own contract and belongs in its package.

This is the second time in this port that isolate: false plus a module mock has produced a test passing for the wrong reason. Worth remembering as a class.

Verification

pnpm build, pnpm --filter @internal/cli test (133 files, 1589 tests), pnpm typecheck, pnpm lint, pnpm lint:deps, check:error-reference (277 codes, unchanged), plus the six journey files covering these commands and the ref-pointer integration suite. Each command was run through the built binary against a real example project and diffed against the commander CLI, piped and through a pty, with colour and with NO_COLOR=1. Both CLIs' format produce an identical rewrite of the demo's contract.prisma.

🤖 Generated with Claude Code