prisma-next-upgrade

Prisma Next のアップグレード（ユーザーアプリ）

このスキルは、公開パッケージ API（@prisma-next/postgres、@prisma-next/mongo、prisma/ 内のコントラクトファイルなど）を通じて Prisma Next を利用するプロジェクトをアップグレードします。プロジェクト自体が Prisma Next の拡張機能である場合は、代わりに prisma-next-extension-upgrade スキルを使用してください。リポジトリにアプリと拡張機能パッケージの両方が含まれている場合は、両方を使用してください。

ステップ 0 — スキルが最新であることを確認する

何よりも先に、このスキルが @latest でインストールされていることを確認して再読み込みしてください。以前のバージョン移行手順に対するバグ修正は、累積セットの一部として最新のスキルリリースに含まれます。古いスキルを使って実行すると、既知の不具合がある移行を適用するおそれがあります。

エージェントのランタイムがセッション中の再読み込みに対応している場合は、今すぐ実行してください。対応していない場合は終了し、ユーザーに再インストール（pnpm dlx skills add prisma/prisma-next/skills/upgrade --all）を依頼してから、再度実行してください。アップグレードスキルのサブパスは意図的にバージョンを固定していません（常に main）。累積された手順一式が信頼できる情報源であり、最新リリースの修正は過去のすべての移行にも適用されます。

事前確認 — 拡張機能との互換性

コードを変更する前に、インストールされている拡張機能が固定している Prisma Next のバージョンを超えてアップグレードしないでください。Prisma Next の拡張機能は、すべての @prisma-next/* 依存関係を単一の厳密なバージョンに固定しています（キャレットや範囲指定はありません）。この固定バージョンは、拡張機能が検証済みの最高バージョンです。ユーザーアプリをそのバージョンより新しくすると、拡張機能の型の識別性とアプリの型の識別性が、気付かないうちに一致しなくなります。

手順：

1. prisma-next.config.ts（またはプロジェクトルートにある、TypeScript で検出可能な同等のファイル）を読み込み、インポートされている拡張機能パッケージの一覧を確認します。各 extensions: [...] エントリーは、インストール済みの npm パッケージに対応します。
2. 各拡張機能について、node_modules/<extension-package-name>/package.json にあるインストール済みの package.json を読み込み、dependencies、peerDependencies、または optionalDependencies 内の @prisma-next/* エントリーを確認します。構成上、これらのエントリーは厳密なバージョンに固定されています（例："0.7.0"）。固定するバージョンは、拡張機能の作者が最後にアップグレードを実行した時点で設定されたものです。
3. すべての拡張機能の固定バージョンのうち、最も低いバージョンを算出します。 これが、現在の拡張機能セットでこのアプリが到達できる Prisma Next の最高バージョンです。
4. ユーザーの目標バージョンと比較します。 目標バージョンが最も低い固定バージョンを超える場合は、遅れている拡張機能とその固定バージョンをそれぞれ示す構造化メッセージを表示して停止し、次の 2 つの方法を提示します。
   • (a) 遅れている拡張機能が互換性のあるリリースを公開するまで待ってから、再実行する。
   • (b) --to=<highest-reachable>（またはユーザーが目標バージョンの指定に使用しているフラグ／オプション）を付けて再実行する。

目標バージョンを自動的に下げてはいけません。遅れている拡張機能をスキップしてはいけません。そのバージョンを超えてはいけません。ユーザーが明示的に停止を解除した場合は、まずリスクを明確に伝えてください。

prisma-next.config.ts が存在しない場合、または拡張機能が指定されていない場合は、事前確認をスキップしてください。

役割の判定

このスキルは、プロジェクトが Prisma Next を利用する場合に適用されます。

• package.json の dependencies／devDependencies に 1 つ以上の @prisma-next/* パッケージが宣言されている。
• かつ、そのパッケージ自体が拡張機能ではない（dependencies／peerDependencies に @prisma-next/contract（または他の SPI）がない、名前が ^@.*/extension- に一致しない、兄弟アプリの prisma-next.config.ts から参照されていない）。

プロジェクトが拡張機能の作者の役割にも該当する場合は、prisma-next-extension-upgrade スキル（pnpm dlx skills add prisma/prisma-next/skills/extension-author --all）をインストールし、このフローを先に実行してから、同じセッションで拡張機能用のフローを実行してください。判定が曖昧な場合は、ユーザーに確認してください。

バージョンの検出

• 移行元バージョン。 pnpm-lock.yaml（または package-lock.json / yarn.lock）を確認し、任意の @prisma-next/* パッケージで解決されたバージョンから、現在インストールされている Prisma Next のバージョンを読み取ります。ロックファイルに異なるマイナーバージョンの @prisma-next/* パッケージが複数記載されている場合（すでに不整合な状態）、移行元バージョンには最も低いマイナーバージョンを使用します。
• 移行先バージョン。 ユーザーが指定したバージョン、または npm view @prisma-next/postgres dist-tags.latest で取得した最新の安定版です。

続行する前に、両方のバージョンをユーザーに報告してください。

移行チェーン

移行元と移行先の差が複数のマイナーバージョンにわたる場合（例：0.6 → 0.8）、1 マイナーバージョンずつ進めるチェーンを作成します。

0.6 → 0.7 → 0.8

各ステップを順番に、完全に実行してください。次のステップに進む前に、バージョン更新、インストール、手順の実行、検証、コミットをすべて完了します。最初に失敗したステップでチェーンを停止し、先に進まないでください。

チェーンの順序は、インストールされている拡張機能によって変わりません。事前チェックで、移行先に到達可能であることはすでに確認されています。

各ステップのフロー

チェーン内の各 (from, to) ステップについて、次の手順を実行します。

1. @prisma-next/* の依存関係を更新します。 プロジェクトの package.json にあるすべての @prisma-next/* エントリーを、正確な <to> バージョンに書き換えます（キャレットやチルダは付けません）。すべてのエントリーを同じバージョンに更新してください。dependencies と devDependencies の両方を対象にします。アップグレードスキル自体は pnpm dlx skills add で提供され、.agents/skills/prisma-next-upgrade/（または同等の CLI 管理ディレクトリ）に配置されます。更新対象となる @prisma-next/upgrade-skill の npm エントリーはありません。

2. インストールします。 pnpm install（またはプロジェクトのロックファイルを管理するコマンド）を実行します。プロジェクトのコードは新しい型に対して不整合な状態になります。<from> → <to> のアップグレード手順は、この不整合を修正するためのものです。

3. アップグレード手順を読み込みます。 このスキルパッケージから upgrades/<from>-to-<to>/instructions.md を読み込みます。YAML フロントマターを解析し、特に changes[] 配列を確認します。

4. 各変更を適用します。 changes[] の各エントリーについて、次の手順を実行します。

   • エントリーに detection ブロック（glob + コンテンツの述語）がある場合は、それを実行します。一致するファイルがなければ変更をスキップします。detection がない場合は、無条件で適用します。
   • エントリーに script:（instructions.md と同じディレクトリにある相対パス）が指定されている場合は、プロジェクトのルートから実行します。*.ts は pnpm exec tsx <path>、*.sh は bash <path> で実行し、codemod はスクリプト自体の説明に従います。script がない場合は、本文の説明に直接従います。

   changes[] が空の場合（ユーザー側に破壊的変更がない移行用のプレースホルダー形式）は、何もせず検証に進みます。

5. 検証します。 pnpm typecheck && pnpm test（またはプロジェクトで相当するコマンド）を実行します。コマンドはプロジェクトの package.json の scripts フィールドを調べて特定します。失敗があれば、チェーンを停止します。自動でロールバックしないでください。失敗した変更の id（フロントマターから取得）、その変更が操作したファイルパス、推定される対処方法をユーザーに報告します。

6. コミットします。 各ステップについて、package.json のバージョン更新、ロックファイルの変更、ソースの書き換えを含むコミットを 1 つ作成します。

   chore: upgrade @prisma-next/* to <to-version>
   

   （または、プロジェクト独自のコミットメッセージ規約に従います。）ステップをまとめて squash しないでください。マージ時にユーザーが squash することはできますが、進行中の履歴はステップごとに分け、失敗したステップを bisect できる状態にしてください。

その後、次のステップに進みます。

チェーン完了後

適用したステップ数、作成したコミットの SHA、未解決のフォローアップ（例：アップグレード前から失敗しており、現在も失敗しているテスト）をユーザーに報告します。

失敗時の対応

ステップが失敗した場合は、コード PN-UPGRADE-NNNN、失敗した変更の id、変更を加えたファイルパス（またはロックファイル、検証コマンド）、推定される対処方法を含む構造化エラーをユーザーに提示します。自動で再試行したり、ロールバックしたりしないでください。プロジェクトを元の状態に戻したい場合、ユーザーは自身で変更を取り消せます。

事前チェックで停止した場合は、何もバージョン更新せず、プロジェクトを変更しないでください。