autoupgrade-icp-cli

icp CLI の自動アップグレードを設定する

一度だけ実行するインストーラーです。SessionStart フックを追加し、icp と ic-wasm が最新かどうかを確認して、ユーザーが希望する場合は作業開始前にアップグレードします。 これらの手順が完了すれば、ユーザーがこのスキルを再び使う必要はありません。

公式レシピ（@dfinity/motoko、 @dfinity/rust、@dfinity/static-site、@dfinity/asset-canister）はビルドのたびに ic-wasm を呼び出すため、ic-wasm も icp と一緒に対象にします。icp の更新が進む間に ic-wasm が古いままだと、レシピのバグのように見えるビルドエラーが発生します。そのため、片方だけをアップグレードするのは、より望ましくない初期設定です。

icp には独自のチェック（icp settings update-check）があり、有効のままにしておく価値はあります。ただし、ユーザーが icp コマンドを実行して初めて通知されます。その時点では、エージェントはすでに何を書くかを選んでいます。このフックはセッションの最初のプロンプトより前に実行されるため、バージョン情報があらかじめ Claude のコンテキストに反映され、ic-wasm も対象になります。

ステップ 1 — 希望するモードをユーザーに尋ねる

インストーラーがユーザーに代わって決めることはできないため、何かを書き込む前に尋ねてください。

「新しいバージョンがある場合のフックの動作は、2 つの選択肢から選べます。 notify — バージョンと正確なアップグレードコマンドを表示します。ユーザーが実行するまでインストールは行われません。auto — セッション開始時にアップグレードを実行します。どちらにしますか？フックのフラグを 1 つ編集すれば、後から切り替えられます。」

ユーザーに希望がなければ、元に戻しやすい notify をデフォルトにします。

また、フックを追加することの意味も説明し、承認を回避しようとしないでください。

「.claude/upgrade-icp-cli.sh を実行する SessionStart フックを追加します。Claude Code は、自動実行の前に承認または信頼するよう求めます。」

ステップ 2 — 前提条件を確認する

command -v curl   >/dev/null 2>&1 && echo "curl: ok" || echo "curl: MISSING"
icp --version     2>/dev/null     || echo "icp: not installed"
ic-wasm --version 2>/dev/null     || echo "ic-wasm: not installed"

いずれかのツールが見つからない場合は、インストールコマンド （npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm）を伝えます。ただし、ユーザーに確認せず実行してはいけません。ツールチェーンのインストールは、最新の状態を保つかどうかとは別の判断です。

ステップ 3 — スクリプトをダウンロードする

アップストリームで更新されたときにチャネルの検出が正しく保たれるよう、公開済みのスクリプトを転記せず、そのまま取得します。

mkdir -p .claude
curl -fsSL https://skills.internetcomputer.org/.well-known/skills/autoupgrade-icp-cli/scripts/upgrade-icp-cli.sh \
  -o .claude/upgrade-icp-cli.sh

手書きしたり、言い換えたりしないでください。

ステップ 4 — SessionStart フックを登録する（冪等に）

.claude/settings.json が存在しない場合は、以下の内容で作成します。存在する場合はマージします。既存のキー、フック、権限をすべて保持し、同等の bash .claude/upgrade-icp-cli.sh コマンドがまだ存在しない場合に限り、SessionStart エントリーを追加して、解析した JSON を書き戻します。ファイルを上書きしてはいけません。

Notify モード（デフォルト）：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode notify" }
        ]
      }
    ]
  }
}

Auto モード — 同じエントリーに --mode auto を付け、さらに timeout を延長します。CLI バイナリのインストールにはデフォルトの 60 秒を超えることがあり、タイムアウトするとツールが不完全な状態で書き込まれるためです。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "bash .claude/upgrade-icp-cli.sh --mode auto", "timeout": 300 }
        ]
      }
    ]
  }
}

auto モードのフックをユーザーに渡すときは、それが実際にどのような選択なのかを必ず伝えてください。プロジェクトを開いている間にビルドツールチェーンがアップグレードされ、実行中はセッション開始がブロックされます。そのため、セッションは前回終了時とは異なる icp で始まる可能性があり、昨日まで問題なくビルドできていたプロジェクトのビルド動作や出力が変わることがあります。それを望むチームもあれば、バージョンを固定するチームもあります。

ステップ 5 — 一度実行して、確認し、結果を報告する

bash .claude/upgrade-icp-cli.sh --mode notify   # or --mode auto, matching the hook

何も表示されない場合は、両方のツールが最新です。これは成功であり、失敗ではありません。手動実行では毎回ネットワークを確認します。フックには（後述の）頻度制限があるため、今すぐ結果を知りたい場合もこのコマンドを使います。

続いて、フックのエントリーがちょうど 1 回だけ存在することを確認し、検出したバージョンとアップグレードの有無を報告して、信頼確認のプロンプトについてユーザーに伝えます。プロジェクトで .claude/ をコミットしている場合は、.claude/.icp-upgrade-check を .gitignore に追加します。これはマシンごとのタイムスタンプであり、共有する設定ではありません。

スクリプトが実行内容を判断する方法

各バイナリのシンボリックリンクをたどって実際のパスを解決し、そのパスからインストールチャネルを判別します。チャネルによってアップグレードコマンドが異なり、誤った方法を推測すると CLI のコピーが 2 つ PATH 上で互いを隠してしまうためです。

バイナリの解決先	チャネル	アップグレードコマンド（icp / ic-wasm）
…/node_modules/@icp-sdk/…	npm	npm install -g @icp-sdk/icp-cli@latest / npm install -g @icp-sdk/ic-wasm@latest
…/Cellar/…	Homebrew	brew upgrade icp-cli / brew upgrade ic-wasm
~/.config/<app>/ にある cargo-dist のレシート	シェルインストーラー	icp-cli-update / ic-wasm-update
その他	不明	(なし — 代わりにリリース URL を表示します)

最後の行は意図的なものです。認識できないインストール方法については、推測せずに報告します。

ユーザーに伝えておきたい注意点が 2 つあります。

• 隠れているインストールは更新されません。 アップグレードが成功しても PATH が引き続き古いバージョンを指している場合は、別チャネルのコピーが優先されています。よくある例は、nvm 配下の npm グローバルインストールが、~/.cargo/bin にあるシェルインストーラーのコピーと並存しているケースです。一方のチャネルをアップグレードしても、もう一方のコピーには影響しません。どちらが優先されているか確認するには、バイナリのパスを解決し（command -v icp）、どちらかを削除するか、実際に PATH 上にある方をアップグレードしてください。
• 自動モードでは sudo を実行しません。 書き込み不可の npm プレフィックスがある場合は、代わりに sudo … コマンドを表示します。フック内でパスワードを求めても、入力する端末がないためです。

スロットリング

リリースフィードにアクセスしたチェックの実行時刻は .claude/.icp-upgrade-check に記録され、6 時間は再実行されません。そのため、ほとんどのセッション開始時のフック実行コストは約 10 ms で、約 1 秒にはなりません。ICP_UPGRADE_CHECK_INTERVAL=<seconds> で上書きできます（0 で無効化）。または --force を指定すると 1 回だけ迂回できます。端末からの実行では常にチェックします。プローブに失敗した場合は記録されないため、オフラインのセッションでは次回に再試行します。

これではアップグレードされないもの

このフックが管理するのは 2 つの CLI バイナリのみです。icp.yaml に記述されたレシピのバージョン（@dfinity/[email protected] など）と Motoko ツールチェーン（moc、mops、mops.toml の [toolchain] ピン）はプロジェクトごとに固定されており、更新するかどうかはユーザーに委ねられます。それらについては、それぞれ icp-cli と mops-cli を読み込んでください。

自動アップグレードの直後にビルドが失敗し始めた場合、プロジェクトが壊れたと考える前に icp-cli のリリースノートを確認してください。

追加の参考情報

• icp-cli — CLI 自体の使い方：icp.yaml、レシピ、環境、デプロイ。
• mops-cli — Motoko ツールチェーンと、そのバージョン固定方法。
• autosync-ic-skills — .claude/skills/ にある IC スキルを最新に保つ、連携するインストーラー。この 2 つは独立しており、両方をインストールするのが一般的です。