Adopt result errors for local pin reads

[rtbenfield]

Adds the Better Result error-handling adoption plan and implements the first local-pin read slice so invalid local state is typed before reaching command output boundaries.

Changes

• Planning: Adds the staged Better Result migration spec and implementation plan under .agents/projects, with Phase 1 marked implemented and later phases preserved for follow-up.
• Local pin reads: Converts .prisma/local.json reads in packages/cli/src/lib/project/local-pin.ts to return Result values with local TaggedError variants for invalid JSON, invalid shape, cancellation, and unexpected failures.
• Migration bridges: Updates project resolution, project list, and app deploy callers to exhaustively convert the new local-pin read errors while preserving existing LOCAL_STATE_STALE, LOCAL_PROJECT_WORKSPACE_MISMATCH, and local binding outputs.
• Guardrails: Tightens AGENTS.md error-handling rules for result-returning functions, abort mapping, and Result.gen composition.

Why

This starts the migration on the smallest read-only project context boundary. Missing local pins remain successful absence, while parse and shape failures are now modeled errors that must be exhaustively handled as the remaining command boundaries migrate.

Verification

• pnpm --filter @prisma/cli exec vitest run tests/project-resolution.test.ts tests/project.test.ts tests/app-controller.test.ts --testTimeout 15000
• pnpm --filter @prisma/cli exec tsc -p tsconfig.json --pretty false still fails on existing unrelated type errors in branch database, branch controller, project real-mode tests, helper typing, and script declaration imports.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 525d4f5b-1a41-4a37-9569-3d07348b4ac9

📥 Commits

Reviewing files that changed from the base of the PR and between 101d8cf and 59f72f6.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (10)

• .agents/projects/better-result-error-handling.plan.md
• .agents/projects/better-result-error-handling.spec.md
• AGENTS.md
• packages/cli/package.json
• packages/cli/src/controllers/app.ts
• packages/cli/src/controllers/project.ts
• packages/cli/src/lib/project/local-pin.ts
• packages/cli/src/lib/project/resolution.ts
• packages/cli/tests/project-resolution.test.ts
• packages/cli/tests/project.test.ts

---

Summary by CodeRabbit

• Documentation

  • Added comprehensive adoption plan and specification for improved CLI error handling architecture.
  • Added error-handling guidelines to repository standards.

• Dependencies

  • Added better-result package for enhanced error handling.

• Improvements

  • Strengthened error handling in deploy and project resolution commands.
  • Improved validation and error reporting for local project configuration files.

• Tests

  • Added test coverage for invalid configuration file scenarios.

Walkthrough

This PR launches incremental adoption of better-result error handling in the Prisma CLI, beginning with local resolution pin read/write operations. It adds foundational planning documents and repo-wide error handling governance, establishes a new dependency on better-result, refactors readLocalResolutionPin to return typed Results with tagged error variants instead of throwing, and integrates the new error types throughout the project resolution and app deployment controllers with exhaustive error mapping. Tests verify that invalid local pin JSON is properly rejected in project target resolution and reported as an invalid binding status in project list output.

🚥 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 directly and concisely describes the main change: converting local pin reads to use result-based error handling, which matches the primary implementation focus of the PR.
Description check	✅ Passed	The description comprehensively relates to the changeset, covering the planning documents, local pin read conversion, migration bridges for callers, and guardrails—all of which are present in the PR.
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 docs/better-result-error-handling-plan

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/better-result-error-handling-plan

---

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