feat: list platform branch roles

[luanvdw]

Overview

This makes branch inspection real while keeping the branch command surface intentionally small. Reviewers should read this as an inspect-only slice: users and agents can see Platform branches and roles, but this does not add branch mutation or local branch-context switching.

Changes

• packages/cli/src/commands/branch/index.ts and packages/cli/src/shell/command-meta.ts now register only branch list, so help output no longer advertises placeholder commands.
• packages/cli/src/controllers/branch.ts resolves auth and project context, then paginates GET /v1/projects/{projectId}/branches so the command lists the full remote branch set.
• packages/cli/src/types/branch.ts, packages/cli/src/presenters/branch.ts, and packages/cli/src/use-cases/branch.ts collapse the old local-context shape into the direct list contract: projectId, projectName, and branch rows with id, name, role, and envMap.
• Product docs and CLI fixtures/tests were updated so docs, help, fixture mode, human output, and JSON output all describe the same reduced branch surface.

Why

Starting with inspection avoids committing to a production-branch mutation contract before that workflow is designed. envMap is derived directly from branch role, which keeps this command cheap and avoids extra env-var API calls for override annotations that the API does not support yet. Removing show and use also avoids a misleading local-context model while Branch remains a platform-backed primitive.

[coderabbitai]

Warning

Review limit reached

@luanvdw, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 18 minutes and 19 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2e5a6252-8f12-4da3-9fb2-7f90a628964f

📥 Commits

Reviewing files that changed from the base of the PR and between 594a2d8 and 63bdf7f.

📒 Files selected for processing (6)

• docs/product/command-spec.md
• packages/cli/src/controllers/branch.ts
• packages/cli/src/shell/command-meta.ts
• packages/cli/tests/branch-controller.test.ts
• packages/cli/tests/branch.test.ts
• packages/cli/tests/shell.test.ts

Walkthrough

This PR removes the branch show and branch use subcommands from the Prisma CLI and refactors the branch listing command to use a new BranchRole-based type system with Management API integration. The changes include type restructuring, command surface simplification, use-case refactoring, real-mode API support, presenter updates, documentation revisions, and comprehensive test rewrites.

Changes

Branch Command Simplification and Role-Based Metadata System

Layer / File(s)	Summary
Type system and contract restructuring packages/cli/src/types/branch.ts, packages/cli/src/use-cases/contracts.ts	Introduces BranchRole type (`"preview"
Command surface removal and mock fixture updates packages/cli/src/commands/branch/index.ts, packages/cli/src/shell/command-meta.ts, packages/cli/fixtures/mock-api.json, packages/cli/src/adapters/mock-api.ts	Removes branch show and branch use subcommands, keeping only branch list. Updates command descriptors and examples. Adds role field ("preview" or "production") to mock branch fixtures and updates the BranchRecord type to require the new role property.
Use-case and gateway refactoring packages/cli/src/use-cases/branch.ts, packages/cli/src/use-cases/create-cli-gateways.ts	Simplifies the branch use-case surface to expose only the list() method. Replaces BranchStateGateway dependency with BranchGateway. Implements buildBranchSummaries helper to transform remote branch records into the new summary shape with role and envMap. Updates branch ordering to use role instead of name. Returns raw branch data without augmentation.
Controller real-mode Management API integration packages/cli/src/controllers/branch.ts	Adds real-mode branch listing by integrating the Management API: listRealBranches authenticates and orchestrates fetching, listBranches paginates through API responses, toBranchSummary transforms API data to CLI shape. Introduces RawBranchRecord interface, ApiErrorBody for error payloads, and branchApiError error-handling helper. Non-real-mode paths continue using existing use-cases.
Presenter rendering and serialization packages/cli/src/presenters/branch.ts	Replaces renderBranchShow and serializeBranchShow with renderBranchList and serializeBranchList. Implements new inline UI construction using formatDescriptorLabel and formatColumns for direct formatting. serializeBranchList returns projectId, projectName, and the branches array.
Documentation and README updates docs/product/command-principles.md, docs/product/command-spec.md, docs/product/output-conventions.md, docs/product/resource-model.md, packages/cli/README.md	Clarifies that branch commands do not use use; targeting is via explicit flags or source context. Updates branch context resolution order to explicit argument, then Git branch, then main. Documents that branch list exposes role and envMap. Removes branch show from command spec and pattern mappings. Updates README examples to use branch list.
Test suite updates packages/cli/tests/branch-controller.test.ts, packages/cli/tests/branch-usecases.test.ts, packages/cli/tests/branch.test.ts, packages/cli/tests/use-case-helpers.ts	Rewrites controller tests with mock API client and local pin fixtures, validating real-mode pagination and result structure. Updates use-case tests to expect role and envMap metadata. Updates command tests to validate new human output and JSON schema (projectId, projectName, branches array). Removes activeBranch from test helpers and simplifies state management.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Title check	✅ Passed	The title 'feat: list platform branch roles' accurately describes the main change: implementing branch listing with role information.
Description check	✅ Passed	The description clearly explains the changes, rationale, and scope of the PR—implementing inspect-only branch listing without mutations.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/branch-list-roles

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/branch-list-roles

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@docs/product/command-spec.md`:
- Around line 541-543: Clarify that the "resolved env map" shown is the
role-derived default template, not branch-specific overrides: update the
description text that currently says "shows each branch's name, role, and
resolved env map" to explicitly state that envMap is derived from the branch's
role (role -> envMap) and represents the default environment template for that
role, and also adjust/remove the ambiguous sentence about "does not expose ...
env override annotations yet" so it reads that branch-specific env overrides are
not included in this view; reference symbols: envMap, role, branch.

In `@packages/cli/src/controllers/branch.ts`:
- Around line 68-72: The returned branches are using the raw API order; call the
existing sortBranches function on branches before mapping to toBranchSummary so
production branches and then name-sorted order is applied in real mode as well.
Locate where branches are referenced in the return object (the branches variable
used with toBranchSummary) and replace branches.map(toBranchSummary) with a
mapping over sortBranches(branches) (i.e., compute sorted =
sortBranches(branches) then map sorted with toBranchSummary) so both
fixture/use-case and real modes share the same deterministic ordering.

In `@packages/cli/src/shell/command-meta.ts`:
- Around line 69-72: Update the branch command help to remove the word “active”
from its description(s): locate the command meta entry with id "branch" and path
["prisma","branch"] and change the description value from "View your active
Platform branches" to something like "View your Platform branches"; also update
the other occurrence of the same help text (the second description around the
same id/command) so both descriptions no longer assert the filter. Ensure
examples and other fields stay unchanged.

🪄 Autofix (Beta)

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

Run ID: 29ba5e3d-3bbb-4779-b86f-8730aa09440f

📥 Commits

Reviewing files that changed from the base of the PR and between 8930881 and 594a2d8.

📒 Files selected for processing (19)

• docs/product/command-principles.md
• docs/product/command-spec.md
• docs/product/output-conventions.md
• docs/product/resource-model.md
• packages/cli/README.md
• packages/cli/fixtures/mock-api.json
• packages/cli/src/adapters/mock-api.ts
• packages/cli/src/commands/branch/index.ts
• packages/cli/src/controllers/branch.ts
• packages/cli/src/presenters/branch.ts
• packages/cli/src/shell/command-meta.ts
• packages/cli/src/types/branch.ts
• packages/cli/src/use-cases/branch.ts
• packages/cli/src/use-cases/contracts.ts
• packages/cli/src/use-cases/create-cli-gateways.ts
• packages/cli/tests/branch-controller.test.ts
• packages/cli/tests/branch-usecases.test.ts
• packages/cli/tests/branch.test.ts
• packages/cli/tests/use-case-helpers.ts

💤 Files with no reviewable changes (1)

• docs/product/output-conventions.md