Add agent-legible project setup next actions

[luanvdw]

Summary

• add structured nextActions to JSON success and error envelopes while preserving nextSteps
• keep human project setup output calm with Not linked plus explicit link/create commands
• expose agent-legible Project setup choice guidance for project show/list and PROJECT_SETUP_REQUIRED
• add concrete Next.js standalone-output recovery actions for deploy build failures
• encode the human-vs-agent rendering principle in product docs

Review

• Ran local thermonuclear review against origin/main...HEAD
• Verdict: pass after extracting command-argument formatting into a shared shell helper

Validation

• corepack pnpm --filter @prisma/cli build
• corepack pnpm --filter @prisma/cli test
• git diff --check
• targeted grep for removed human-output stop-gate language

[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 29 minutes and 23 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: 5a4677b9-2d71-4b71-9e79-3dfa4aeeab30

📥 Commits

Reviewing files that changed from the base of the PR and between 2a1d8cb and 4987110.

📒 Files selected for processing (3)

• packages/cli/src/lib/project/resolution.ts
• packages/cli/src/shell/command-arguments.ts
• packages/cli/tests/shell.test.ts

Walkthrough

This PR introduces a structured NextActions system to the Prisma CLI, enabling agents and users to understand actionable follow-up steps through a unified model. The changes span type definitions, error handling, project command workflows, deployment error detection, output rendering, and comprehensive test coverage.

Changes

NextActions System and Integration

Layer / File(s)	Summary
NextAction type definitions packages/cli/src/shell/next-actions.ts	Defines NextActionKind (run-command, user-choice, edit-file, done), NextActionJourney (project-setup, deploy-app, inspect, recover), and NextAction interface with required kind/journey/label and optional command/commands/reason fields.
Error and success response containers packages/cli/src/shell/errors.ts, packages/cli/src/shell/output.ts	Extends CliError and CommandSuccess to carry nextActions[], and updates writeJsonSuccess/writeJsonError to emit nextActions in JSON payloads.
Streaming command transport packages/cli/src/shell/command-runner.ts	Updates runStreamingCommand to include nextActions field in both success (empty array) and error JSON events.
Shell command formatting utility packages/cli/src/shell/command-arguments.ts	Adds formatCommandArgument helper to safely format and escape command-line arguments.
Project setup action builder packages/cli/src/lib/project/resolution.ts, packages/cli/src/lib/project/setup.ts	Implements buildProjectSetupNextActions to construct user-choice, link, create, and retry actions for project workflows; updates inspectProjectBinding to track localBinding.status; re-exports formatCommandArgument.
Project result type contracts packages/cli/src/types/project.ts	Introduces ProjectLocalBindingState type and extends ProjectListResult with optional localBinding and UnboundProjectShowResult with required localBinding: { status: "not-linked" }.
Project list/show command handlers packages/cli/src/controllers/project.ts	Adds readProjectListLocalBinding resolver, updates runProjectList and runProjectShow to detect binding status (linked/invalid/not-linked) and compute nextActions based on whether the directory is linked to a Project.
Project output rendering packages/cli/src/presenters/project.ts	Renders project list/show with binding-aware next-step sections; replaces prior "unbound" formatting with clear link/create instructions using formatCommandArgument.
App deploy error handling packages/cli/src/controllers/app.ts	Detects Next.js standalone-output build failures and adds specific recovery actions (edit next.config, rerun deploy); enhances projectSetupRequiredError with structured nextActions for Project selection workflows.
Output conventions and specification documentation docs/product/output-conventions.md, docs/product/command-spec.md, docs/product/error-conventions.md, docs/product/cli-style-guide.md, docs/product/command-principles.md	Documents nextActions as always-present JSON field, specifies NextAction type shape, clarifies user-choice semantics without encoding targets, and updates human-mode message examples to use "not linked" labels; updates command specs and styling rules.
Comprehensive test assertion updates packages/cli/tests/app-controller.test.ts, packages/cli/tests/project.test.ts, packages/cli/tests/auth.test.ts, packages/cli/tests/branch.test.ts, and others	Asserts nextActions presence and structure across app deploy (standalone failure, project setup), project list/show (local binding states), auth, branch, and version commands; validates action kinds, journeys, and command payloads.

---

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 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 'Add agent-legible project setup next actions' accurately summarizes the main change—introducing structured next actions for agents to interpret project setup guidance.
Description check	✅ Passed	The description is directly related to the changeset, detailing the addition of structured nextActions to JSON envelopes, human-friendly project setup output, agent-legible guidance, and recovery actions for build failures.
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/agent-legible-next-actions

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/agent-legible-next-actions

---

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: 2

🤖 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 `@packages/cli/src/lib/project/resolution.ts`:
- Around line 177-228: Update buildProjectSetupNextActions so the
user-choice.commands array is derived from the existing helper
buildProjectRecoveryCommands instead of hardcoding the "prisma-cli project link"
and "--project" templates: call
buildProjectRecoveryCommands(options.commandName) (or similar) to obtain the
link/--project entries, then prepend or merge the always-present "prisma-cli
project list" entry into NextAction.commands; adjust references in the
user-choice NextAction (in function buildProjectSetupNextActions) to use that
derived array so the link/--project templates cannot drift from the shared
helper.

In `@packages/cli/src/shell/command-arguments.ts`:
- Around line 1-3: formatCommandArgument currently returns JSON.stringify for
unsafe values and lets strings that match /^[A-Za-z0-9._/-]+$/ through, which is
not POSIX shell-safe and also allows values starting with '-' to be emitted
unquoted; update formatCommandArgument to instead: treat a value as safe only if
it matches the allowlist AND does NOT start with '-' (so names like "-rf" are
quoted), otherwise return a single-quoted shell-safe string where every embedded
single quote is escaped using the standard '\'' sequence (i.e., replace each '
with '\'' and wrap the result in single quotes); keep the function name
formatCommandArgument and its return type string.

🪄 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: 0ed2cdcd-e08a-401e-a413-59fd85db87d2

📥 Commits

Reviewing files that changed from the base of the PR and between 5daaa40 and 2a1d8cb.

📒 Files selected for processing (25)

• docs/product/cli-style-guide.md
• docs/product/command-principles.md
• docs/product/command-spec.md
• docs/product/error-conventions.md
• docs/product/output-conventions.md
• packages/cli/src/controllers/app.ts
• packages/cli/src/controllers/project.ts
• packages/cli/src/lib/project/resolution.ts
• packages/cli/src/lib/project/setup.ts
• packages/cli/src/presenters/project.ts
• packages/cli/src/shell/command-arguments.ts
• packages/cli/src/shell/command-runner.ts
• packages/cli/src/shell/errors.ts
• packages/cli/src/shell/next-actions.ts
• packages/cli/src/shell/output.ts
• packages/cli/src/types/project.ts
• packages/cli/tests/app-controller.test.ts
• packages/cli/tests/app-env-vars.test.ts
• packages/cli/tests/auth-real-mode.test.ts
• packages/cli/tests/auth.test.ts
• packages/cli/tests/branch.test.ts
• packages/cli/tests/project-controller.test.ts
• packages/cli/tests/project-real-mode.test.ts
• packages/cli/tests/project.test.ts
• packages/cli/tests/version.test.ts