prisma-next-extension-upgrade

Prisma Next（拡張機能）のアップグレード

このスキルは、Prisma Next の拡張機能であるプロジェクトをアップグレードします。つまり、フレームワーク SPI（@prisma-next/contract、@prisma-next/framework-components、@prisma-next/migration-tools など）を利用し、下流アプリが prisma-next.config.ts 経由でインストールするコントラクト／ミドルウェア／コーデック／マイグレーションのインターフェースを公開するパッケージです。

アップグレードするプロジェクトがコンシューマー アプリ（アプリケーションコードから @prisma-next/postgres または @prisma-next/mongo をインポートするもの）の場合は、代わりに prisma-next-upgrade スキルを使用してください。リポジトリにコンシューマーアプリと拡張機能パッケージの両方が含まれている場合は、両方を使用します。その場合、同じセッション内で、まずユーザーフローを実行してから拡張機能のフローを実行してください。

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

他の作業を始める前に、このスキルが @latest でインストールされていることを確認し、再読み込みしてください。過去の移行手順に対するバグ修正は、累積セットの一部として最新のスキルリリースに含まれます。古いスキルで実行すると、既知の不具合がある移行を適用してしまう可能性があります。

具体的には、エージェントのランタイムがセッション中の更新に対応している場合は、今すぐ実行してください。対応していない場合は終了し、ユーザーに再インストールを依頼してください。

pnpm dlx skills add prisma/prisma-next/skills/extension-author --all

拡張機能作成者向けのスキルのサブパスは、意図的にバージョン固定されず（常に main）、累積された指示セットを信頼できる情報源としており、最新リリースの修正は過去のすべての移行に適用されます。

その後、続行する前にこのスキルを再度呼び出してください。

ロールの判定

このスキルは、プロジェクトが Prisma Next の拡張機能である場合に適用されます。判定の手がかり：

• package.json の dependencies または peerDependencies に @prisma-next/contract（または別の SPI パッケージ）が宣言されており、かつ
• パッケージの name が ^@.*/extension- に一致する（@prisma-next/extension-pgvector などで使われるリポジトリ内の慣例）、または
• 同じモノレポ内の兄弟アプリの prisma-next.config.ts で extensions エントリーとして参照されている。

プロジェクトが独自のアプリコードから Prisma Next も利用している場合は、prisma-next-upgrade スキル（pnpm dlx skills add prisma/prisma-next/skills/upgrade --all）をインストールし、同じセッション内で、まずユーザーフローを実行してからこのフローを実行してください。

判定が曖昧な場合は、どのロールで作業するかユーザーに確認してください。

バージョンの判定

• アップグレード元のバージョン。 pnpm-lock.yaml（または package-lock.json／yarn.lock）を読み、いずれかの @prisma-next/* エントリーの解決済みバージョンを確認して、現在インストールされている Prisma Next のバージョンを特定します。ロックファイルに異なるマイナーバージョンの @prisma-next/* パッケージが複数ある場合は、最も低いマイナーバージョンをアップグレード元のバージョンとします。
• アップグレード先のバージョン。 ユーザーが指定したバージョン、または npm view @prisma-next/contract dist-tags.latest で取得できる最新の安定版です。

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

移行チェーン

アップグレード元からアップグレード先までの差分が複数のマイナーバージョンにまたがる場合（例：0.6 → 0.8）、マイナーバージョンごとの手順に分割します。

0.6 → 0.7 → 0.8

各手順を順番に、最後まで実行してください。つまり、次の手順に進む前に、バージョンを上げ、インストールし、手順を実行し、バージョン固定を確認し、検証してコミットします。最初に失敗した手順でチェーンを停止してください。

各ステップのフロー

このフローでは、外部の拡張機能作成者を想定しています。拡張機能は独自のリポジトリにあり、npm から @prisma-next/* を利用します。（prisma/prisma-next モノレポ内の拡張機能は、ルートのバージョンに合わせてすべての workspace:<X.Y.Z> 仕様を書き換える pnpm bump-minor / scripts/set-version.ts で更新するため、このスキルは実行しません。）

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

1. @prisma-next/* の依存関係を更新します。 拡張機能の package.json にあるすべての @prisma-next/* エントリを、正確な <to> バージョン（例："0.8.0"）に書き換えます。キャレット、チルダ、範囲指定、workspace: 指定子は使用しません。正確なバージョンに固定する理由については、以下の固定ルールで詳しく説明します。すべてのエントリを同じバージョンに更新します。拡張機能で現在使用している依存関係フィールド（dependencies、peerDependencies、またはその両方）と、optionalDependencies を対象にします。拡張機能アップグレードスキル自体は pnpm dlx skills add で提供されるため（ステップ 0 を参照）、更新対象となる @prisma-next/extension-upgrade-skill の npm エントリはありません。付属の CLI ツールは @prisma-next/extension-author-tools です。拡張機能の CI が現在使用しているバージョンに固定したままにしてください。このツールの更新はフレームワークのアップグレードとは別であり、通常は変更不要です。

2. インストールします。 pnpm install（またはプロジェクトでロックファイルを管理するコマンド）を実行します。これで拡張機能のソースは新しい SPI に対応しなくなります。<from> → <to> のアップグレード手順は、この問題を修正するために用意されています。

3. バージョン固定を確認します。 pnpm exec prisma-next-check-pins（@prisma-next/extension-author-tools に含まれています）を実行します。このチェックでは、dependencies、peerDependencies、optionalDependencies にあるすべての @prisma-next/* エントリが単一の正確なバージョン文字列であり、すべてのエントリで同じバージョンが使われていることを確認します。チェックに失敗した場合、更新時にすべての指定を書き換えられていません。該当するエントリを修正し、先に進む前に再実行してください。

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

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

   • エントリに detection ブロック（glob とコンテンツ述語）がある場合は、実行します。一致するファイルがない場合、この変更はスキップします。
   • エントリに detection がない場合は、無条件に適用します。
   • エントリに script:（instructions.md と同じ場所にある相対パス）の指定がある場合は、プロジェクトのルートから次のように実行します。
     • *.ts → pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
     • *.sh → bash <skill>/upgrades/<from>-to-<to>/<script>
     • codemod → スクリプト自身の instructions.md の説明に従って実行します。
   • エントリに script がない場合は、instructions.md の本文にある説明に従ってください。

   changes[] が空（拡張機能側に破壊的変更がない移行用のプレースホルダー形式）の場合、このサブステップでは何も行わず、検証に進みます。

6. 検証します。 pnpm build && pnpm test（またはプロジェクトに相当するコマンド。拡張機能の package.json の scripts フィールドがコマンドを確認する場所です）を実行します。エラーが発生した場合は、チェーンを中断してください。自動でロールバックしないでください。 失敗した変更の id（フロントマターから取得）、変更が操作したファイルパス、および推定される対処方法をユーザーに提示してください。

7. コミットします。 このステップでの変更をすべて含むコミットを 1 つ作成します。対象は package.json の更新、pnpm install によるロックファイルの変更、適用した変更によるソースファイルの書き換えです。コミットメッセージには次を使用します。

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

   （拡張機能に独自のコミットメッセージ規約がある場合は、それに従ってください。）ステップごとにコミットを 1 つ作成します。ステップをまとめて squash しないでください。

次のステップに進み、同じ手順を繰り返します。

Exact-pin ルール

Prisma Next 拡張機能では、すべての @prisma-next/* 依存関係を単一の完全一致バージョンに固定します（公開される package.json では、^、~、範囲指定、ワイルドカード、workspace: 指定子は使用しません）。すべての @prisma-next/* エントリーで同じバージョンを使用します。固定バージョンを更新するのは、新しいマイナーバージョンに対するアップグレードの実行が成功した後だけです。

prisma-next-check-pins（@prisma-next/extension-author-tools に同梱されています。pnpm add -D @prisma-next/extension-author-tools でインストールしてください）でルールを適用します。ローカルで実行するには、次のコマンドを使用します。

pnpm exec prisma-next-check-pins

拡張機能の CI に、ビルド／テストのステップと合わせて組み込み、誤って範囲指定で固定した場合に、PR がマージされる前に失敗するようにしてください。

一連の処理が完了したら

適用したステップ数、作成したコミットの SHA、未解決のフォローアップ事項をユーザーに報告してください。

失敗時の対応

ステップが失敗した場合：

• PN-UPGRADE-NNNN 形式のコード、失敗した変更の id、その変更が変更したファイルパス（またはロックファイル、ピンのチェック、検証コマンドに関する情報）、および推定される対処方法を含む構造化エラーを提示します。
• 自動的に再試行しないでください。
• コミットを自動的にロールバックしないでください。きれいな状態に戻したい場合は、ユーザーが元に戻せます。