Add @prisma/cli-engine — one library owns argv to exit code — proven end to end on auth whoami

[wmadden-electric]

This is what writing a command looks like when this PR's engine owns everything between argv and the exit code:

import { defineCommand } from "@prisma/cli-engine";
import { ok } from "@prisma/cli-engine/protocol";

export const authWhoamiCommand = defineCommand({
  help: {
    summary: "Show the authenticated user and accessible workspace",
    examples: ["auth whoami", "auth whoami --json"],
  },
  handler: async (_args, ctx) => {
    const state = await readAuthState(ctx.env, ctx.signal);
    return ok(
      ctx.present(
        { data: state },
        {
          human: () => [
            { kind: "summary", tone: "info", text: "Showing the current authenticated identity." },
            { kind: "fields", rows: fieldRows(state) },
          ],
          stdout: () => fieldRows(state).map((r) => `${r.label}: ${r.value}`),
          next: () => (state.authenticated ? [] : [SIGN_IN]),
        },
      ),
    );
  },
});

The command declares words and a handler; the engine does the rest. The same definition produces the human card on stderr with pipeable payload lines on stdout, and — with --json, or automatically when stdout is not a TTY — a machine stream ending in one result envelope:

{"kind":"result","envelope":{"ok":true,"commandId":"auth.whoami","result":{"authenticated":false,...},"exitCode":0,"diagnostics":[],"nextActions":[{"kind":"run-command","label":"Sign in","command":"prisma-cli auth login"}]},"commandId":"auth.whoami","timestamp":"..."}

The decision

Prisma ships three CLIs today (prisma-next, prisma-composer, @prisma/cli) with three config files and three unrelated help/output/error dialects. We are consolidating them into one prisma binary, and this PR makes the foundational move: a single library, @prisma/cli-engine, owns every CLI mechanic — parsing, preconditions, context, presentation, envelopes, exit codes, prompts, signals, config loading — so that a product package contributes only command definitions, handlers, and words. To prove the design is real rather than aspirational, the PR also ports one real command (auth whoami) end to end through an unpublished bin.

How the engine models a command

A command settles like a promise. It either completes — possibly unsuccessfully: findings travel as typed diagnostics inside a completed envelope with a documented exit code — or it errors, aborting with a structured error the engine renders. This one distinction drives everything downstream: envelopes, exit codes (0 completed / 1 bug / 2 errored / 3 user cancel / 4–99 documented / 130,143 signals), and rendering.

Around that core, the engine owns:

• Formats and channels. --format human|json (auto-json on non-TTY stdout). Human mode: presentation to stderr, machine-usable payload lines to stdout — human mode is pipe-clean. Json mode: one frame per line on stdout, exactly one terminal envelope.
• Preconditions (needs). Credentials, config sections, optional dependencies, interactivity — checked before the handler loads, failing early with engine-phrased structured errors.
• Prompts (defaults accepted by --yes; consent structurally undefaultable), events (a fixed vocabulary with a per-command data extension), log levels (--quiet and --verbose are aliases on one severity scale).
• Config. prisma.config.ts is discovered and evaluated once; defineConfig stamps a version marker; a Prisma 7 config fails early with a typed migration error. A broken config only fails commands that need config.
• Process boundaries. The engine never touches process globals: streams, env, TTY flags, signals, and exit arrive injected via a Runtime. First Ctrl-C aborts gracefully; a second force-exits. This is also what makes it fully testable.

Products plug in as a CommandFamily — the unit of contribution and ownership: commands by name, at most one config section, a docs base URL. The shell owns the tree (paths, groups); a command may only require its own family's config section, enforced at construction.

Proving it

• @prisma/cli-engine/testing ships createTestCli: argv-in/bytes-out harness testing with injected credentials, config, clock, prompt answers, and signals. The package's 145 tests byte-assert human output, json frames, exit codes, prompt semantics, signal handling, and config loading — including permanent compile-verified type-tests (a stale @ts-expect-error fails the build).
• prisma-v8 (unpublished, tsx-run: pnpm prisma-v8 auth whoami) mounts the ported command over the existing token storage. Behavioral differences from prisma-cli auth whoami are enumerated, not discovered: the divergence record.

What this PR does not do

Nothing ships to users: the engine is unpublished, the bin is not wired into any package's bin, and the published @prisma/cli build is untouched. The other ~60 platform commands, auth-library extraction, Composer and ORM adoption, and the release pipeline are later slices (plan).

Alternatives considered

• Clipanion (powers two of the three CLIs today) vs stricli for the internal parser: stricli 1.3.0, exact-pinned and fully hidden — nothing stricli-shaped appears in the public surface (comparison record).
• Bundling the parser vs an ordinary dependency: ordinary exact-pinned dependency — bundling is unusual for a library and blinds security audit.
• Lazily imported handler modules (handler: () => import(...)): rejected — handlers are direct function references; the indirection bought startup weight savings we didn't need at the cost of a circular typing pattern.
• Result-wrapped prompt returns: rejected — prompts return plain values or throw; the engine settles failures uniformly (cancel → exit 3).
• Schema-library validation (e.g. Arktype) for construction checks: deferred — a heavy dependency against minimal validation needs; revisit if the checks grow.

The full interface record, including every amendment made during implementation, is the normative draft at .drive/projects/prisma-cli-v8/assets/engine/engine-interface-draft.ts; requirements live in docs/architecture/cli-engine-requirements.md (merged via #128).

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@wmadden-electric, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b51f878e-9958-4791-ab84-76bd83bc765f

📥 Commits

Reviewing files that changed from the base of the PR and between 15dfbe3 and 28c1ac5.

📒 Files selected for processing (22)

• .drive/projects/prisma-cli-v8/assets/engine/engine-interface-draft.ts
• .gitignore
• biome.jsonc
• package.json
• packages/cli-engine/src/commands.ts
• packages/cli-engine/src/execution/command-tree.ts
• packages/cli-engine/src/execution/engine.ts
• packages/cli-engine/src/execution/needs.ts
• packages/cli-engine/src/execution/prompts.ts
• packages/cli-engine/src/execution/rendering.ts
• packages/cli-engine/src/execution/shared-flags.ts
• packages/cli-engine/src/execution/stricli-adapter.ts
• packages/cli-engine/src/presentation.ts
• packages/cli-engine/src/protocol.ts
• packages/cli-engine/tests/command-families.test.ts
• packages/cli-engine/tests/engine.test.ts
• packages/cli-engine/tests/execution.test.ts
• packages/cli-engine/tests/lifetimes.test.ts
• packages/cli-engine/tests/protocol.test.ts
• packages/cli/src/v8/runtime.ts
• packages/cli/tests/v8-bin.test.ts
• turbo.json

Summary by CodeRabbit

• New Features

  • Added the Prisma v8 CLI foundation with command families, structured diagnostics, JSON output, interactive prompts, signal handling, and human-readable rendering.
  • Added auth whoami, showing authentication, user, provider, and workspace details with human and JSON output.
  • Added Prisma configuration loading and validation through prisma.config.ts.
  • Added guidance and documentation links to relevant errors and next actions.

• Bug Fixes

  • Blank service-token configuration now produces a clear, structured authentication error with corrective guidance.

• Chores

  • Improved repository-wide build, test, and type-check workflows.

Walkthrough

This change adds the @prisma/cli-engine package and its public command, configuration, runtime, protocol, presentation, and testing APIs. It implements command-tree validation, execution, prompts, signals, structured errors, rendering, and settlement. It adds the v8 auth whoami command and executable runtime adapter. It adds workspace build orchestration, CI updates, tests, fixtures, and rollout documentation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.48% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the new CLI engine and its end-to-end validation through the auth whoami command.
Description check	✅ Passed	The description directly explains the CLI engine, auth whoami integration, design decisions, testing, and scope of the changes.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch s1-engine-vertical

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch s1-engine-vertical

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

The base branch was changed.

[coderabbitai]

Actionable comments posted: 30

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.drive/projects/prisma-cli-v8/assets/briefs/s1-handover.md:
- Around line 11-31: Update the handover to reflect completed S1 state,
including D6 completion and the current verification counts from the final
implementation. Replace the four obsolete open items covering channel rendering,
remediation events, config-error scope, and successful-validation diagnostics
with their settled rulings recorded in the parity-divergences document. Remove
guidance that could reopen resolved behavior, or mark this brief superseded and
link to the final handover.

In @.drive/projects/prisma-cli-v8/assets/engine/whoami-parity-divergences.md:
- Line 52: Update the three output code fences in
.drive/projects/prisma-cli-v8/assets/engine/whoami-parity-divergences.md at
lines 52-52, 65-65, and 73-73 to use the text language identifier on each
opening fence.

In @.drive/projects/prisma-cli-v8/assets/rollout-plan.md:
- Around line 36-40: Update the prisma7 rollout entry to specify the exact npm
dist-tag used when publishing prisma@8.0.0-rc1; if both next and rc must resolve
to that version, document the post-publish npm dist-tag add step for the second
tag, otherwise identify the single supported install channel.

In @.github/workflows/preview-cli-package.yml:
- Around line 47-52: Update the “Build workspace packages” step in the workflow
to use a single dependency-aware build path, avoiding duplicate compilation of
`@prisma/cli` and `@prisma/compute` with the later build steps around the existing
status reporting. Either remove those later package-specific builds or replace
this step with a filtered Turbo build that preserves the required status
reporting.

In `@package.json`:
- Line 10: Update the package.json build:cli script to run Turbo with the
`@prisma/cli`... filter, ensuring the CLI build includes its dependency closure
instead of invoking pnpm’s package-only build.

In `@packages/cli-engine/src/commands.ts`:
- Around line 272-282: Extend the server-command handler io type near handler to
include readonly env, matching the env surface in CommandContext. At the server
dispatch site in engine, pass invocation.runtime.env alongside cwd so server
handlers can access the runtime environment without reading process.env.

In `@packages/cli-engine/src/execution/engine.ts`:
- Around line 341-351: Update RESERVED_FLAG_NAMES in shared-flags.ts to include
"version", ensuring validateFlags rejects commands that declare a flag
intercepted by versionRequested. Leave versionRequested and other reserved flag
behavior unchanged.
- Around line 325-337: Validate the value returned by the server handler before
assigning it to state.settledExitCode in executeServer. Require a finite integer
in the valid process-exit range 0–255, and route invalid values through the same
engine-boundary failure handling used by settleCompleted rather than returning
them to the host.

In `@packages/cli-engine/src/execution/needs.ts`:
- Around line 46-130: Split checkNeeds into four focused helpers for
interaction, dependencies, credentials, and configuration, each returning
NeedsOutcome | undefined when that requirement fails and undefined otherwise.
Preserve the current check order and behavior, including credential error
handling and config diagnostic validation, then have checkNeeds invoke the
helpers sequentially and return the first defined outcome before falling back to
the existing ok result.
- Around line 191-198: Update dependencyResolvable to normalize cwd to an
absolute path before passing the probe filename to createRequire, using
resolve(cwd, "__cli_engine_probe__.js") or equivalent. Preserve the existing
dependency-resolution return behavior, and add coverage proving a relative
working directory correctly resolves an available dependency.

In `@packages/cli-engine/src/execution/prompts.ts`:
- Around line 173-174: Replace the nested ternary assigned to hint in the prompt
logic with an explicit conditional or lookup-based implementation, preserving
the existing "(y/n)", "(Y/n)", and "(y/N)" results for undefined, truthy, and
falsy fallback values respectively.

In `@packages/cli-engine/src/execution/rendering.ts`:
- Around line 152-160: Update withDocsUrl to normalize the join between
state.docsBaseUrl and diagnostic.code, ensuring exactly the required separator
is present when constructing docsUrl. Preserve the existing early returns for
diagnostics with docsUrl or missing docsBaseUrl.
- Around line 11-16: Update STEP_OUTCOME_SYMBOL to use the step outcome union as
its Record key type, and update TONE_SYMBOL to use Block’s summary tone union
instead of string. Preserve the existing symbol mappings while making
unsupported outcomes or tones fail compile-time checks like DIAGNOSTIC_SYMBOL.

In `@packages/cli-engine/src/execution/settlement.ts`:
- Around line 175-192: Update settleBug to preserve internal-error stack details
when state.logLevel is verbose: write the original Error stack to stderr or
include it in the emitted diagnostic meta, while retaining the existing
firstLine summary and behavior for non-Error causes.

In `@packages/cli-engine/src/execution/stricli-adapter.ts`:
- Around line 44-50: Update parseNumberInput to reject blank or whitespace-only
input before converting it with Number, so empty numeric arguments throw the
existing usage error instead of being accepted as zero; preserve valid numeric
parsing and the current non-finite validation.

In `@packages/cli-engine/src/exports/index.ts`:
- Around line 1-9: Update the main barrel in
packages/cli-engine/src/exports/index.ts to re-export ok, notOk, okVoid, Result,
Diagnostic, NextAction, CliStructuredError, and CliErrorEnvelope from the
existing ./protocol module, while preserving ./protocol as the shared
cross-package/process entrypoint.

In `@packages/cli-engine/src/exports/testing.ts`:
- Line 5: Configure a scoped lint override for the noBarrelFile rule covering
src/exports/, including the testing.ts, index.ts, and protocol.ts entrypoints.
Keep the existing re-export hub structure unchanged and ensure the override
suppresses only this rule within that directory.

In `@packages/cli-engine/src/presentation.ts`:
- Around line 81-88: Update the row object type in the fields member of Block so
its label, value, and optional sensitive properties are explicitly readonly,
preserving the existing ReadonlyArray and union structure.

In `@packages/cli-engine/src/protocol.ts`:
- Around line 63-89: Add an optional cause field to the options accepted by the
CliStructuredError constructor, pass it through the Error superclass
initialization, and leave toEnvelope unchanged so cause remains out of the
serialized envelope.

In `@packages/cli-engine/src/testing.ts`:
- Around line 132-154: The abort wiring around engine.execute must preserve
signals delivered before runtime.onSignal subscribes. Update the signal delivery
flow and runtime.onSignal subscription so an early abort reason is stored as
pending and replayed immediately when a listener is registered, while retaining
normal delivery for signals received after subscription.

In `@packages/cli-engine/tests/command-families.test.ts`:
- Around line 139-141: Update the stderr expectation in the command-family test
to use one template literal containing both the error text and the docs URL,
removing the string concatenation while preserving the exact expected output.

In `@packages/cli-engine/tests/engine.type-test.ts`:
- Around line 375-389: Replace the double-cast undefined value in
runtimeShape.stdin with a realistic async-iterator InputStream stub, following
the existing pattern in config.test.ts. Remove the InputStream import if
runtimeShape no longer references it elsewhere.

In `@packages/cli-engine/tests/execution.test.ts`:
- Around line 521-555: Extract the repeated Runtime literals in the affected
tests into a local makeRuntime(overrides) helper returning a complete default
Runtime. Move shared stdin, stderr, cwd, env, isTty, exit, onSignal, config,
getCredentials, and packageManager setup into the helper, then replace all three
inline constructions with makeRuntime calls that override only test-specific
fields such as stdout, credentials, interactive state, and diagnostics.

In `@packages/cli-engine/tests/lifetimes.test.ts`:
- Around line 405-416: Update the lsp fixture handler to flush the TextDecoder
after the stdin loop and append any final decoded text to received. Compute the
Content-Length header from the UTF-8 byte length of the complete response body
rather than received.length, while preserving the existing response framing.
- Around line 228-235: Update the floating promise created by stuckCli().run in
the “a second SIGTERM exits 143” test to attach an explicit rejection handler,
while preserving the test’s existing signal-delivery and exit assertions.

In `@packages/cli-engine/tests/prompts.test.ts`:
- Around line 116-125: Add test cases alongside “CI suppresses interactivity
even on a TTY” covering CI values "1" and "false". Assert the intended detection
behavior for each value, including the resulting prompt interaction, exit code,
presented data, and stderr as appropriate, so future changes to the CI detection
rule remain pinned.

In `@packages/cli-engine/tests/protocol.type-test.ts`:
- Around line 35-36: Update the envelopeFromError type assertion to use the
existing MutuallyAssignable helper, comparing CliErrorEnvelope with
ReturnType<CliStructuredError["toEnvelope"]> so the test verifies assignability
in both directions.

In `@packages/cli/src/v8/runtime.ts`:
- Around line 47-53: Update makeGetCredentials to distinguish an unset
SERVICE_TOKEN_ENV_VAR from a present-but-blank value: detect variable presence
before trimming, return unauthenticated for blank/whitespace values, and only
call FileTokenStorage.getTokens when the variable is truly absent.

In `@packages/cli/tests/v8-bin.test.ts`:
- Around line 144-150: Update the test around makeGetCredentials so it no longer
creates an unused local AbortController; either remove the abort setup and
rename the test to describe a normal stored-token read, or pass the aborted run
signal through the actual credential-retrieval runtime and retain the
aborted-signal behavior assertion.

In `@turbo.json`:
- Around line 4-23: Include the shared packages/tsconfig/** files in Turbo cache
hashing by adding them to globalDependencies or to the explicit inputs for the
affected build, test, and typecheck tasks. Update the task configuration around
build, test, and typecheck so changes to `@repo/tsconfig` are detected without
altering other task behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c0e13edd-4761-4fe3-b747-dff1dd0f0cac

📥 Commits

Reviewing files that changed from the base of the PR and between 6abc20f and 15dfbe3.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (73)

• .drive/projects/prisma-cli-v8/assets/briefs/s1-handover.md
• .drive/projects/prisma-cli-v8/assets/engine/engine-interface-draft.ts
• .drive/projects/prisma-cli-v8/assets/engine/whoami-parity-divergences.md
• .drive/projects/prisma-cli-v8/assets/rollout-plan.md
• .drive/projects/prisma-cli-v8/design-notes.md
• .drive/projects/prisma-cli-v8/plan.md
• .drive/projects/prisma-cli-v8/plans/s1-engine-vertical.md
• .drive/projects/prisma-cli-v8/spec.md
• .drive/projects/prisma-cli-v8/specs/s1-engine-vertical.md
• .github/workflows/pr-quality.yml
• .github/workflows/preview-cli-package.yml
• .github/workflows/test.yml
• package.json
• packages/cli-engine/package.json
• packages/cli-engine/src/args.ts
• packages/cli-engine/src/cli.ts
• packages/cli-engine/src/command-family.ts
• packages/cli-engine/src/commands.ts
• packages/cli-engine/src/config-loader.ts
• packages/cli-engine/src/config-section.ts
• packages/cli-engine/src/context.ts
• packages/cli-engine/src/events.ts
• packages/cli-engine/src/execution/command-context.ts
• packages/cli-engine/src/execution/command-tree.ts
• packages/cli-engine/src/execution/engine.ts
• packages/cli-engine/src/execution/needs.ts
• packages/cli-engine/src/execution/prompts.ts
• packages/cli-engine/src/execution/rendering.ts
• packages/cli-engine/src/execution/reporting.ts
• packages/cli-engine/src/execution/settlement.ts
• packages/cli-engine/src/execution/shared-flags.ts
• packages/cli-engine/src/execution/stricli-adapter.ts
• packages/cli-engine/src/exports/index.ts
• packages/cli-engine/src/exports/protocol.ts
• packages/cli-engine/src/exports/testing.ts
• packages/cli-engine/src/presentation.ts
• packages/cli-engine/src/protocol.ts
• packages/cli-engine/src/runtime.ts
• packages/cli-engine/src/testing.ts
• packages/cli-engine/tests/command-families.test.ts
• packages/cli-engine/tests/config.test.ts
• packages/cli-engine/tests/engine.test.ts
• packages/cli-engine/tests/engine.type-test.ts
• packages/cli-engine/tests/events.test.ts
• packages/cli-engine/tests/execution.test.ts
• packages/cli-engine/tests/fixtures/config/marked/nested/.gitkeep
• packages/cli-engine/tests/fixtures/config/marked/prisma.config.ts
• packages/cli-engine/tests/fixtures/config/unmarked/prisma.config.ts
• packages/cli-engine/tests/fixtures/config/unreadable/prisma.config.ts
• packages/cli-engine/tests/fixtures/config/wrong-version/prisma.config.ts
• packages/cli-engine/tests/lifetimes.test.ts
• packages/cli-engine/tests/prompts.test.ts
• packages/cli-engine/tests/protocol.test.ts
• packages/cli-engine/tests/protocol.type-test.ts
• packages/cli-engine/tsconfig.json
• packages/cli-engine/tsdown.config.ts
• packages/cli-engine/vitest.config.ts
• packages/cli/package.json
• packages/cli/src/lib/auth/auth-ops.ts
• packages/cli/src/shell/command-runner.ts
• packages/cli/src/v8/auth/whoami.ts
• packages/cli/src/v8/bin.ts
• packages/cli/src/v8/cli.ts
• packages/cli/src/v8/main.ts
• packages/cli/src/v8/runtime.ts
• packages/cli/tests/v8-bin.test.ts
• packages/cli/tests/v8-whoami.test.ts
• packages/cli/tsconfig.json
• packages/compute/package.json
• packages/compute/tsconfig.json
• packages/tsconfig/base.json
• packages/tsconfig/package.json
• turbo.json