fix(local): resolve Prisma dev through the exported CLI manifest

[AmanVarshney01]

Fix

Fix the local Postgres resolver and tell users which dependency is actually missing.

• Resolve the CLI-relative fallback through its exported prisma/package.json, not the JavaScript root. Prisma 8 has no root export, so the old lookup failed with ERR_PACKAGE_PATH_NOT_EXPORTED even though prisma was installed.
• Keep the app's direct @prisma/dev dependency as the first choice and retain the CLI-relative compatibility fallback for installations that supply the runtime there.
• If the runtime cannot be resolved or imported, say to add @prisma/dev to the devDependencies of the project where Composer runs. Correct the message in both the resolver and emulator daemon.
• Update the local-dev guide and agent skill. Reuse existing resolver and daemon tests; no new cases, test files, or CI jobs.

Dependency ownership and related PRs

Prisma 8 does not include @prisma/dev. The CLI design treats it as an optional, project-owned dependency. This PR does not change that ownership or install/download anything.

prisma/create-prisma#102 adds the runtime to generated PostgreSQL projects, at the root for monorepos. That scaffolding fix works with the current published Composer release; this PR fixes the upstream fallback and error message independently.

Do not treat prisma/prisma-cli#270 as a prerequisite. That alternative packages the runtime into every CLI installation and is on hold. The earlier description requiring both PRs was based on an incorrect assumption about the v8 packaging design.

Verification

• Based on main 1c4db78d; no conflicts.
• Full build: 38 tasks passed.
• Local-target tests: 15 passed. Existing exported-manifest fixture exercises the missing-root-export regression; existing missing-runtime fixture now uses the real Prisma 8 export shape.
• Postgres daemon tests: 11 passed, including the error response with the corrected install instruction.
• Both changed packages typecheck; Biome passes on all changed TypeScript files.
• Fresh actual create-prisma CLI scaffolds with the companion change: Bun + Turborepo + TypeScript and pnpm + minimal + PSL.
• With published prisma@8.0.0-rc.15 and app Composer 0.19.0, both generated projects start local Postgres, apply migrations, and serve seeded users. Repeated HTTP requests retain the same three user IDs. No patched CLI or app source is needed.
• Previously verified the exported-manifest fallback end to end with packed Composer and a CLI carrying its own runtime. That proves fallback compatibility, not a requirement to change CLI packaging.
• Verification telemetry disabled; no cloud resources changed.

[prisma-gizmo]

✅ Gizmo reviewed e13cf19 — posted 0 inline comment(s) this pass.

Open findings: none

Change walkthrough

This PR fixes local Postgres dependency resolution for Prisma 8, which ships the prisma CLI without a JavaScript root export, so Composer could no longer fall back through the CLI's module tree even when @prisma/dev was present. It also corrects the install hint users get when the runtime is missing.

Local-target resolver — postgres.ts keeps step 1 (resolve @prisma/dev from the app's own node_modules) and rewrites step 2 to resolve the CLI's exported prisma/package.json and resolve the runtime relative to that manifest. This works for Prisma 8's exports-only manifest while still resolving unrestricted subpaths on older CLIs without an exports field, and it behaves correctly under nested, hoisted, and pnpm-store layouts (symlinks are realpathed by default). The doc comment was updated to match the new step 2 and the Prisma-8 ownership model.

Error surface — the pinned "missing runtime" message in the resolver and the daemon's NOT_INSTALLED_MESSAGE are now byte-identical and tell users to add @prisma/dev to the devDependencies of the project where Composer runs, replacing the outdated "add prisma" advice. The daemon's usage sites only append parenthetical diagnostics, so no behavior changes there.

Tests — the module-resolution suite reuses its existing four cases: the fallback and missing-runtime fixtures now write the Prisma-8 manifest shape (exports: { './package.json': './package.json' }), reproducing the ERR_PACKAGE_PATH_NOT_EXPORTED regression, and both pinned-error assertions expect the corrected wording. The daemon test's assertion was updated to the new message substring, which still satisfies its no-path-leak invariant since @prisma/dev contains no absolute path segments.

Docs and skill — running-locally.md and SKILL.md document the new dependency ownership (@prisma/dev is project-owned, not shipped by Prisma 8), the app-first-then-CLI-manifest resolution order, and that cloud deployments and Postgres-less local apps need nothing — all consistent with the implementation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Essentials

Run ID: e3058a20-0a6c-45a4-8bc8-12c0a4fc9848

📥 Commits

Reviewing files that changed from the base of the PR and between 1c4db78 and e13cf19.

📒 Files selected for processing (6)

• docs/guides/running-locally.md
• packages/1-prisma-cloud/0-lowering/dev-emulators/src/__tests__/postgres.test.ts
• packages/1-prisma-cloud/0-lowering/dev-emulators/src/postgres-main.ts
• packages/1-prisma-cloud/0-lowering/local-target/src/__tests__/postgres-module-resolution.test.ts
• packages/1-prisma-cloud/0-lowering/local-target/src/postgres.ts
• skills/prisma-composer-core-concepts/SKILL.md

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

Summary by CodeRabbit

• Documentation

  • Updated local development guidance for projects using Local Postgres.
  • Clarified that @prisma/dev must be included in development dependencies; cloud deployments and apps without Postgres do not require it.
  • Documented how dependency resolution works when multiple Prisma packages are available.

• Bug Fixes

  • Improved dependency detection and error messages when Local Postgres requirements are missing.
  • Added support for resolving the development package through Prisma’s package metadata.

Walkthrough

Local Postgres resolution now requires @prisma/dev and falls back through prisma/package.json. Error messages and tests use the updated dependency guidance. The local-running guide and Composer skill documentation describe the requirement, resolution order, and cases that do not require the dependency.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to e13cf

The change preserves local Postgres resolution for app-owned and Prisma CLI-associated installations, with actionable guidance when the dependency is absent.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files. (2 skipped: 2…	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 main change: resolving Prisma development runtime through the exported CLI manifest.
Description check	✅ Passed	The description directly explains the resolver fix, corrected dependency guidance, documentation updates, tests, and verification.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-local-postgres-runtime

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch codex/fix-local-postgres-runtime

---

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@296

npm i https://pkg.pr.new/@prisma/composer-cli@296

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@296

commit: e13cf19

[prisma-gizmo]

New findings: 🟡 1 minor · trace

Findings outside the diff

• 🟡 Minor · consistency docs/design/10-domains/local-dev.md — local-dev spec's error-surface table still says to add prisma, contradicting the corrected @prisma/dev message
  The PR corrects the user-facing message in both postgres.ts and postgres-main.ts to name @prisma/dev as the project-owned dependency, and updates the guide and skill — but the local-dev spec's "Error surface" table (docs/design/10-domains/local-dev.md, line 260) still documents the old contract: row "no installed prisma bin (the local-Postgres emulator)" says the error tells the user "what was searched for and to add prisma to devDependencies". AGENTS.md treats the design docs as binding, and the resolver's own doc comment cites this spec ("local-dev spec § 4") as the pinning contract, so the spec of record now contradicts the shipped behavior and the dependency-ownership model this PR establishes.
  Recommended fix: Update the row in docs/design/10-domains/local-dev.md to match the new contract, e.g. key it on @prisma/dev being unresolvable (from the app or the CLI's exported prisma/package.json) and say the error tells the user to add @prisma/dev to the devDependencies of the project where Composer runs.

[prisma-gizmo]

All Gizmo review threads are resolved and the head commit has been reviewed. Approving.