# 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
```

## パッケージをまとめて動かす理由 {#why-the-packages-move-together}

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

## 変えるもの、変えないもの {#what-it-changes-and-what-it-leaves-alone}

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

## 仕上げは新しいバージョンが行う {#the-new-version-finishes-the-job}

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

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

## アップグレードできるものがあると知る {#knowing-when-there-s-something-to-upgrade-to}

`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
```