日本語

English

日本語

English

外観

ブログ ·

debuff のパッケージを 1 つのコマンドでまとめてアップグレード ​

0.21 からは、npx debuff upgrade 1 回でプロジェクトを最新の debuff に移せます。package.json にある @debuffjp/* のパッケージをすべて新しいリリースにそろえ、プロジェクトのパッケージマネージャーでインストールし、最後に新しいバージョンの doctor --fix を実行します。これがプロジェクトのエージェント用スキルも、そのバージョン向けに書き直します。--dry-run で先に計画を確かめられます。

text
●  @debuffjp/audio ^0.19.0 → ^0.20.0
●  @debuffjp/core ^0.19.0 → ^0.20.0
●  @debuffjp/input ^0.19.0 → ^0.20.0
●  @debuffjp/juice ^0.19.0 → ^0.20.0
●  @debuffjp/cli ^0.19.0 → ^0.20.0
●  @debuffjp/dev ^0.19.0 → ^0.20.0

[debuff] would move to 0.20.0
         what changed: https://github.com/debuffjp/debuff/blob/main/tooling/cli/CHANGELOG.md

パッケージをまとめて動かす理由 ​

debuff のパッケージは、すべて同じバージョンの 1 セットとしてリリースされ、互いの振る舞いをそのまま前提にしています。@debuffjp/core が 0.20 で @debuffjp/dev が 0.19 のプロジェクトは、ゲームのバグのように見える形で壊れることがあるので、debuff doctor はバージョンのずれを直すべき問題として扱います。手で 1 つずつ上げていくと、ちょうどその状態を通ります。upgrade はすべてを 1 回の書き込みで変えます。

変えるもの、変えないもの ​

  • debuff のセットのパッケージすべて：dependencies と devDependencies にある @debuffjp/* と create-debuff。ほかのパッケージは、独自のスケジュールでリリースされる @debuffjp/tenten も含めて、そのままです。
  • 選んだ範囲の書き方：^0.19.0 は ^0.20.0 に、固定の 0.19.0 は 0.20.0 になり、~ は ~ のままです。
  • ダウングレードはしない：最新リリースより新しいもの（試しているプレリリースなど）をすでに指定しているパッケージはそのままです。--to <version> なら、古いものも含めて意図したバージョンを選べます。
  • ワークスペースとファイルのリンク：workspace: と file: の指定には触れないので、モノレポの中でも安全に実行できます。

仕上げは新しいバージョンが行う ​

コマンドを実行しているのは、手元にある CLI、つまり古いほうです。そこでインストールのあと、新しくインストールされた CLI に引き継いで、その doctor --fix を実行します。新しいリリースのチェックを知り、そのスキルを持っているのはこのバージョンなので、プロジェクトの .claude/skills/ と .agents/skills/ は、いま動いている debuff を説明する内容になります。そのあとも必須のチェックが失敗していれば、upgrade は終了コード 2 で終わり、修正方法を見るために doctor を実行するよう伝えます。

エージェント向けには、npx debuff upgrade --json が計画、実行したインストールコマンド、doctor の結果を 1 つの JSON にして返します。新しいリリースで振る舞いが変わることもあります。そのためプロジェクトのエージェント用ガイドは、アップグレードの前に人へ確認するよう伝えています。

アップグレードできるものがあると知る ​

npx debuff doctor は、新しい debuff が出ていると助言として伝えるようになりました。チェックの失敗にはなりません。さらに 1 日 1 回、コマンドの終わりに、新しいリリースがあれば CLI が標準エラー出力に 1 行出します。

text
debuff 0.21.0 is out (you have 0.20.0): npx debuff upgrade

こうした 1 行が邪魔になる場所では出しません。--json のとき、CI の中、そしてすでにそれを扱う dev、create、doctor、upgrade のあとです。DEBUFF_UPDATE_CHECK=0 で止められます。チェックは短いタイムアウトで npm レジストリに最新バージョンを問い合わせ、つながらなければ何も言いません。

プロジェクトで試してみてください。

bash
npx debuff upgrade --dry-run