docs(spec): the engine renders — palette, tables, trees, drawings, width

[wmadden-electric]

What is broken

The engine ships a common renderer that does almost no rendering.

# auth workspace list, from the golden suite today
name  id  status
Acme Inc  ws_1  current
Globex  ws_2

That is renderBlock doing columns.join(" ") — no sizing, no padding. The tree block emits two-space indents with no connectors and has zero users. makeUi emits exactly two escape sequences, bold and dim, so the entire v8 CLI is unstyled. And OutputStream is { write(text) }, so the engine cannot learn the terminal width even from the bin.

Both consumers have already lost rendering to this. The platform port flattened auth workspace list, project list and agent status from aligned rail-and-card renderings, recorded as accepted divergences. The ORM's renderers ship colourless, and two of them call createColors({ useColor: true }) to force colour past NO_COLOR because there is no other way to get any.

The decision

The engine renders; a command describes. This fixes the renderer rather than giving commands an open canvas:

• table aligns — the engine sizes columns to content and pads. That alone restores every flattened platform table.
• tree draws connectors and status glyphs — ├─ ✘ table user, as the style guide has specified all along.
• drawing is added as the escape hatch for layout the engine cannot derive — the migration DAG's lane gutter, where lane assignment comes from a BFS over the graph and one hue must reach the gutter cell, the node glyph and the label alike.
• One palette, consolidated from what both CLIs colour today: semantic tones plus indexed colours for series. A command says color-3 for a branch lane and never learns what colour that is.
• Text = string | Span[] everywhere a block takes display text. Spans carry tone, never escape sequences, so the engine measures on text and colour cannot break alignment — the pad-versus-colour trap in shipped code becomes unrepresentable.
• ui.width is the width of the stream being printed to, unbounded when that is not a terminal. Only the command knows what to sacrifice, so it is told the room it has; if it overruns anyway the engine prints it unmodified.

Two corrections ride along. Colour resolution currently keys off stdout while blocks render to stderr, so cmd > file disables colour for output a human is watching — it now follows the printing stream. And with the palette engine-owned there is no per-renderer colour switch left, so the NO_COLOR bypass disappears by construction.

What this PR is

The implementation spec only — .drive/projects/prisma-cli-v8/specs/engine-colour.md — for handoff to an implementer. Its vocabulary and its list of what draws come from surveying both CLIs' renderers, not from taste.

Alternatives considered

A separate graphic presenter alongside human — rejected: a drawing is human output, so it belongs in the human channel's grammar, and a parallel presenter would need its own channel and colour handling.

Routing rich renderings through Presentations.stdout — rejected: that is the machine channel, and a drawing's consumer is a human.

Letting commands draw tables and trees themselves — rejected: if every command reimplements every form of rendering on an open canvas, the common renderer has no purpose.

🤖 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: 52 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: 968701f8-a164-44ab-9322-d16076612c32

📥 Commits

Reviewing files that changed from the base of the PR and between 2ebddb1 and a68ea8e.

📒 Files selected for processing (1)

• .drive/projects/prisma-cli-v8/specs/engine-colour.md

---

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.}

[pkg-pr-new]

Open in StackBlitz

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

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

commit: a68ea8e

[wmadden-electric]

Superseded by #153, which carries this spec plus the implementation.

The spec landed there with four amendments, all from surveying what prisma/prisma and prisma/composer already ship rather than deciding by taste — six indexed colours instead of eight (the ORM's lane rotation is six and deliberately excludes red), Status split out of Tone so a tree node can be a failure painted in its branch lane's colour, the fields card restored because it is the most-used block and lost the most, and an explicit --color beating NO_COLOR. They are recorded in §8 of the spec on that branch.

Closing this one so the spec does not merge ahead of the code that implements it.