feat: let create-prisma target a specific Prisma Next release

[wmadden]

After this PR, you can scaffold against an exact Prisma Next version through the canonical entry point:

create-prisma --name my-app --template hono --prisma-next-version 0.10.0
# every @prisma-next/* dep in package.json pinned to 0.10.0
# `prisma-next init` invoked as `npx --yes prisma-next@0.10.0 init …`
# agent skills resolved from prisma/prisma-next/skills#v0.10.0

Closes TML-2692.

Why

create-prisma@next hard-codes the Prisma Next dependency spec to "latest". The moment a new Prisma Next version ships, the previous one becomes unreachable through the canonical scaffold path, which means we cannot reproduce user-filed issues against the exact version they were filed on, smoke-test release candidates before they get the latest tag, or dogfood open PRs end-to-end. The onboarding audit needs all three.

What <spec> accepts

The simplest case is a published version, used for regression and bisect work:

create-prisma --prisma-next-version 0.10.0
create-prisma --prisma-next-version 0.11.0-dev.9

The next is an npm dist-tag, used to smoke-test release candidates before they get the latest tag:

create-prisma --prisma-next-version dev   # or `next`, `canary`, …

These two cases work uniformly across every supported package manager (npm, pnpm, yarn, bun, deno) and across the existing skill-install path: prisma-next init already derives the skills ref from the installed CLI's package.json#version, so installing @prisma-next/cli@0.10.0 automatically pulls prisma/prisma-next/skills#v0.10.0.

The third case is a pkg.pr.new ref, used to dogfood open PRs:

create-prisma --prisma-next-version pkg-pr-new:bad6795
# rewrites every @prisma-next/* install to
# https://pkg.pr.new/prisma/prisma-next/<package>@bad6795

This case is partial in this PR — see Scope below.

Omitting the flag preserves today's behaviour exactly.

What changed under the hood

The Prisma Next version is no longer a module-level constant. It's a ResolvedPrismaNextSpec produced once at startup by parsePrismaNextVersionSpec(input.prismaNextVersion) and threaded through PrismaSetupContext, the dep-writing helpers, and the prisma-next init invocation. The two helpers that previously hard-coded \"latest\" now take the resolved spec and emit either name@<spec> or the pkg.pr.new URL form — package managers accept URL specifiers in both install argv and package.json, so the URL flows through unchanged.

Telemetry on the create command gains prisma-next-version-kind (default | npm-tag | npm-version | pkg-pr-new) and the verbatim prisma-next-version-spec, so the audit can see which escape hatch users reach for.

Scope of this PR

Cases 1 and 2 (version pin, dist-tag) ship end-to-end across every package manager. Acceptance criteria from TML-2692 met: pinned scaffold has every @prisma-next/* and prisma-next dep at the requested version, the init invocation uses the same version, skills resolve from the matching tag.

Case 3 (pkg.pr.new) ships partially. The URL form is emitted everywhere it should be, including package.json deps for every package manager. The npx --yes <URL> init path works end-to-end on npm. Two follow-ups are needed to make case 3 fully usable:

• TML-2694 — prisma-next init needs a PRISMA_NEXT_SKILLS_REF env-var override so the skills ref can be derived from a SHA rather than a v<version> git tag (which doesn't exist for pkg.pr.new tarballs).
• TML-2695 — bunx <URL>, pnpm dlx <URL>, yarn dlx <URL>, and deno run npm:<URL> don't accept URL specifiers the way npx does. Non-npm package managers need a two-step (install-then-local-bin) shape for the init invocation when the spec is pkg.pr.new.

Both are flat tickets in [PN] Onboarding Audit, related to TML-2692.

Test plan

bun run test:unit covers the spec parser, the threading from the new flag down to package.json writes (including the pkg.pr.new URL form for every Prisma Next dep), and the telemetry classifier across all four kinds (31 tests, including a regression test that the default path still writes \"latest\"). Smoke-tested against the built CLI for the default path, --prisma-next-version 0.10.0 with --package-manager bun, and --prisma-next-version pkg-pr-new:<ref> with --package-manager npm.

Alternatives considered

• Keep PRISMA_NEXT_PACKAGE_VERSION as a module-level mutable singleton that the CLI entry sets once. Smaller diff than the threaded approach, but create-prisma also exports a programmatic create() API; a mutable singleton becomes racy if anyone ever calls it twice in the same process with different specs. Explicit threading keeps the helpers pure and the version a property of a request, not of the process.
• Ship all three cases in this PR by resolving pkg.pr.new refs to SHAs at scaffold time and shipping the bunx/dlx/deno workarounds inline. Doable, but the SHA resolution introduces a network dependency at scaffold time, and the workaround for non-npm runtimes is non-trivial. The ticket explicitly classed case 3 as stretch and called out filing the prisma-next-side change as a separate follow-up; doing the same on the create-prisma side keeps this PR small and unblocks cases 1+2 immediately.
• Validate the spec string against a semver grammar before passing it through. Rejected because dist-tags (dev, next, …) and prereleases (0.11.0-dev.9) must round-trip unchanged; npm itself doesn't validate tag syntax, and over-validating in create-prisma would lock us out of tags Prisma Next may introduce later.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9e90ef46-d733-4869-b477-895cfdef0a80

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tml-2692-create-prisma-accept-prisma-next-version-to-target-a

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch tml-2692-create-prisma-accept-prisma-next-version-to-target-a

---

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

[github-actions]

PR preview published

• Version: 0.4.2-pr.40.103.1
• Tag: pr40
• Run with Bun: bunx create-prisma@pr40
• Run with npm: npx create-prisma@pr40
• Run with Yarn: yarn dlx create-prisma@pr40
• Run with pnpm: pnpm dlx create-prisma@pr40
• Run with Deno: deno run -A npm:create-prisma@pr40
• Workflow run: https://github.com/prisma/create-prisma/actions/runs/26517244318