prisma-next-extension-upgrade

# Upgrade Prisma Next (extension) This skill upgrades a project that **is** a Prisma Next extension — a package that consumes the framework SPI (`@prisma-next/contract`, `@prisma-next/framework-components`, `@prisma-next/migration-tools`, etc.) and exposes contract / middleware / codec / migration surfaces that downstream apps install via `prisma-next.config.ts`. If the project you are upgrading is a consumer **app** (it imports `@prisma-next/postgres` or `@prisma-next/mongo` from its application code), use the `prisma-next-upgrade` skill instead — or both, if the repo contains both a consumer app and an extension package, in which case run the user flow first then the extension flow in the same session. ## Step 0 — Ensure the skill is up to date Before doing anything else, ensure this skill is installed at `@latest` and reload it. Bug fixes to *old* per-transition upgrade instructions ship in the latest skill release as part of its cumulative set; running against a stale skill can apply a known-broken translation. Concretely: if the agent runtime supports an in-session refresh, perform it now. Otherwise, exit and ask the user to re-install: ```bash pnpm dlx skills add prisma/prisma-next/skills/extension-author --all ``` The extension-author skill subpath is intentionally unpinned (always `main`) — the cumulative instruction set is the source of truth and the latest release fixes apply to every prior transition. Then re-invoke this skill before proceeding. ## Role detection This skill applies when the project **is** a Prisma Next extension. Heuristics: - `package.json` declares `@prisma-next/contract` (or another SPI package) under `dependencies` or `peerDependencies`, and - the package's `name` matches `^@.*/extension-` (the in-tree convention used by `@prisma-next/extension-pgvector`, etc.), or - the package is referenced as an `extensions` entry from a sibling app's `prisma-next.config.ts` in the same monorepo. If the project additionally consumes Prisma Next from its own app code, install the `prisma-next-upgrade` skill (`pnpm dlx skills add prisma/prisma-next/skills/upgrade --all`) and run the user flow first, then this flow in the same session. If detection is ambiguous, ask the user which role to operate under. ## Version detection - **From-version.** Read the currently-installed Prisma Next version from `pnpm-lock.yaml` (or `package-lock.json` / `yarn.lock`) by inspecting the resolved version of any `@prisma-next/*` entry. If the lockfile shows multiple `@prisma-next/*` packages at different minors, the lowest minor is the from-version. - **To-version.** Either the version the user specified, or the latest stable from `npm view @prisma-next/contract dist-tags.latest`. Report both back to the user before continuing. ## Transition chain If the from-to delta spans multiple minor versions (e.g. `0.6 → 0.8`), build the chain of one-minor steps: ```text 0.6 → 0.7 → 0.8 ``` Apply each step in order, fully: bump, install, run instructions, check pins, validate, commit — before moving to the next. Halt the chain on the first failed step. ## Per-step flow This flow assumes you are an **external extension author** — your extension lives in its own repo and consumes `@prisma-next/*` from npm. (Extensions inside the `prisma/prisma-next` monorepo itself are bumped via `pnpm bump-minor` / `scripts/set-version.ts`, which rewrites every `workspace:<X.Y.Z>` spec in lockstep with the root version; they do not run this skill.) For each `(from, to)` step in the chain: 1. **Bump `@prisma-next/*` deps.** Rewrite every `@prisma-next/*` entry in the extension's `package.json` to the exact `<to>` version (e.g. `"0.8.0"` — no caret, no tilde, no range, no `workspace:` specifier; the exact-pin rule below details why). All entries advance to the same version. Cover whichever dep field(s) the extension uses today — `dependencies` and/or `peerDependencies` — and any `optionalDependencies`. The extension-upgrade skill itself ships via `pnpm dlx skills add` (see Step 0); there is no `@prisma-next/extension-upgrade-skill` npm entry to bump. The companion CLI tool is `@prisma-next/extension-author-tools` — leave its pin at the version the extension's CI is currently using; bumping it is independent of the framework upgrade and is normally a no-op. 2. **Install.** Run `pnpm install` (or the project's lockfile-managing command). The extension's source is now broken against the new SPI — the upgrade instructions for `<from> → <to>` exist to fix it. 3. **Check pins.** Run `pnpm exec prisma-next-check-pins` (shipped by `@prisma-next/extension-author-tools`). This sanity check asserts that every `@prisma-next/*` entry across `dependencies`, `peerDependencies`, and `optionalDependencies` is a single exact-version string and that all entries share the same version. If the check fails, the bump step did not rewrite every spec — fix the offending entries and re-run before proceeding. 4. **Read the upgrade instructions.** Load `upgrades/<from>-to-<to>/instructions.md` from this skill package. Parse the YAML frontmatter and pay particular attention to its `changes[]` array. 5. **Apply each change.** For each entry in `changes[]`: - If the entry has a `detection` block (a glob + content predicate), run it. If no files match, skip this change. - If the entry has no `detection`, apply unconditionally. - If the entry names a `script:` (a relative path next to `instructions.md`), invoke it from the project root: - `*.ts` → `pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>` - `*.sh` → `bash <skill>/upgrades/<from>-to-<to>/<script>` - codemods → invoke per the script's own `instructions.md` prose. - If the entry has no `script`, follow the prose body in `instructions.md` directly. If `changes[]` is empty (the placeholder shape for transitions with no extension-side breaking changes), this sub-step is a no-op — proceed to validation. 6. **Validate.** Run `pnpm build && pnpm test` (or the project's equivalent — the `scripts` field of the extension's `package.json` is the discovery surface). If anything is red, halt the chain. Do **not** auto-roll-back; surface the failure to the user with the failing change's `id` (from the frontmatter), the file paths the change operated on, and the inferred remediation. 7. **Commit.** Create one commit containing this step's changes: the `package.json` bump, the lockfile churn from `pnpm install`, and any source-file rewrites from the applied changes. Use the message: ```text chore: upgrade @prisma-next/* to <to-version> ``` (Or the extension's own commit-message convention, if it has one.) One commit per step — never squash steps. Move on to the next step. Repeat. ## Exact-pin rule Prisma Next extensions pin every `@prisma-next/*` dependency to a single **exact** version (no `^`, no `~`, no range, no wildcard, no `workspace:` specifier in the published `package.json`). All `@prisma-next/*` entries share the same version. The pin advances only after a successful upgrade run against the new minor. `prisma-next-check-pins` (shipped by `@prisma-next/extension-author-tools` — install with `pnpm add -D @prisma-next/extension-author-tools`) enforces the rule. Run it locally with: ```bash pnpm exec prisma-next-check-pins ``` Wire it into the extension's CI alongside the build/test step so an accidental range pin fails the PR before it lands. ## When the chain is done Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups. ## Failure surfaces When a step fails: - Surface a structured error with code `PN-UPGRADE-NNNN`, the failing change's `id`, the file paths the change touched (or the lockfile, or the pin check, or the validation command), and the inferred remediation. - Do not retry automatically. - Do not auto-roll-back the commit. The user can revert if they want a clean slate.