fix(engine): substitute {bin} in next actions, diagnostics, and presentation prose

[wmadden-electric]

Not ready to merge

pnpm check:conformance fails on this branch with 6 tarball/engine-pin-mismatch findings. @prisma/composer-cli and @prisma/orm-toolchain peer @prisma/cli-engine 0.6.1, and this change ships 0.6.2.

The repository's process for an engine version transition is two entries in exceptions in packages/cli/scripts/conformance.ts. #280 did that for 0.6.1, and #291 removed the entries when the transition ended.

That edit is not in this pull request. The automation's permission system refuses it, so a maintainer must add it. These are the two entries:

      exceptions: [
        {
          familyPackage: "@prisma/composer-cli",
          familyPin: "0.6.1",
          shellPin: "0.6.2",
          reason: "engine 0.6.2 must publish before composer-cli can peer it",
          removeWhen:
            "composer-cli releases peering 0.6.2 and the follow-up bump PR pins that release",
        },
        {
          familyPackage: "@prisma/orm-toolchain",
          familyPin: "0.6.1",
          shellPin: "0.6.2",
          reason: "engine 0.6.2 must publish before orm-toolchain can peer it",
          removeWhen:
            "orm-toolchain releases peering 0.6.2 and the follow-up bump PR pins that release",
        },
      ],

The entries must be removed once both packages release against engine 0.6.2 and this repository pins those releases. The dev channel (PUBLISH_CHANNEL=dev) was not checked and may need its own entries.

Symptom

The CLI prints a literal {bin} in hints and messages. For example, prisma migration plan ends with:

→ Apply the migration: {bin} db migrate

The same text appears in the --json envelope and in --format markdown output.

Cause

Command families write {bin} on purpose and expect the renderer to substitute the name of the binary the user ran. That substitution lived in the ORM's standalone CLI. It was deleted in prisma/orm#30005 when the ORM moved to the unified CLI. The engine only ever substituted {bin} in help examples and redirect replacements (resolveExample).

Fix

The engine now substitutes {bin} with the CLI name when a run settles, so human, JSON, and markdown output carry the same text. resolveExample and the new code share one function, substituteBinName.

Substituted:

• Next actions: command and commands.
• Diagnostics and errors: summary, why, and their nested next actions. This includes the envelope's top-level nextActions.
• Next actions of a command that settles with a child process status.
• Config section warnings.
• Presentation blocks of kind summary and list.

Left as written, because they can hold user data:

• Presentation blocks of kind fields, table, tree, and drawing.
• The JSON result, the outcome data, and the stdout lines.
• Diagnostic meta.
• Stream events, and errors the engine writes itself (unknown command, internal error).

The engine version moves from 0.6.1 to 0.6.2 through pnpm bump-cli-engine-version patch.

Checks

Command	Result
pnpm build	5 of 5 tasks passed
pnpm typecheck	9 of 9 tasks passed
pnpm lint	no findings
pnpm test --concurrency=1	9 of 9 tasks passed. Engine: 969 of 969 tests. CLI: 1021 passed, 2 skipped.
pnpm test:scripts	passed
pnpm check:grammar	11 of 11 tests passed
pnpm check:error-reference	lists all 130 known codes
pnpm check:skill-packaging	OK
node scripts/check-engine-version.mjs origin/main	engine version 0.6.2 is consistent
pnpm check:conformance	failed, 6 tarball/engine-pin-mismatch findings (see above)

The new test file packages/cli-engine/tests/bin-placeholder.test.ts failed on all 7 cases before the fix. It also asserts that a table cell, a field value, the JSON result, and meta containing {bin} stay unchanged.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/@prisma/cli@313

npx https://pkg.pr.new/@prisma/cli-engine@313

commit: 71a5d84