# Takumi Guard のセットアップスクリプト v0.5.0 でサブコマンドと「端末あたり 1 トークン」配信に対応

Takumi Guard のセットアップスクリプト v0.5.0 で、配信フローを管理者側で組み立てるための 5 つのプリミティブサブコマンドが追加されました。あわせて、これらを用いた「端末あたり 1 トークン」の配信スクリプト例も新たに公開しています。v0.4.x までの呼び出し方法は引き続きそのまま動作するため、既存の配信構成はそのままアップグレードできます。

## 概要

v0.5.0 では、セットアップスクリプトに 5 つのプリミティブサブコマンドが追加されました。それぞれのサブコマンドが、これまで 1 つの呼び出しに固まっていたセットアップ処理の中の 1 ステップを担うため、管理者側で自由に組み合わせて配信フローを設計できるようになっています。

| サブコマンド               | 役割                                                                                   | API 呼び出し |
| -------------------------- | -------------------------------------------------------------------------------------- | ------------ |
| `precheck [SCOPES]`        | 端末上に設定対象が存在するかどうかを判定する                                           | なし         |
| `discover`                 | 端末上のローカル設定ファイルから既存の Guard トークンを列挙する                        | なし         |
| `verify <TOKEN>`           | トークンを Guard API に問い合わせ、`active`・`revoked`・`unknown` のいずれかに分類する | あり         |
| `issue <USER_IDENTIFIER>`  | 指定された識別子で新しいトークンを発行する                                             | あり         |
| `install <TOKEN> [SCOPES]` | 対象スコープのパッケージマネージャー設定にトークンを書き込む                           | なし         |

Bot の API 認証情報が必要なのは `verify` と `issue` のみです。そのため、各開発者のシェル側には API キーを渡さず、`discover` や `install` だけをそれぞれのシェル内で動かす設計も可能になっています。標準出力・標準エラー・終了コードの詳細は[サブコマンドモードの I/O コントラクト](/docs/ja/t/guard/features/admin-deployment#setup-script)を参照してください。

それぞれのサブコマンドの呼び出し例は以下の通りです。

```sh
# precheck -- 端末上に設定対象が存在するか判定する（API 呼び出しなし）
./setup.sh precheck

# discover -- 端末上のローカル設定から既存の Guard トークンを列挙する
./setup.sh discover

# verify -- トークンの状態を Guard API に問い合わせる（bot 認証情報が必要）
TG_BOT_ID=BTxxxxxxxxxxxxxxxxxxxxxxxxxxx \
TG_BOT_API_KEY=shisho_apikey_xxxxxxxxxxxxx \
  ./setup.sh verify tg_org_xxxxxxxxxxxxxxxxx

# issue -- 新しいトークンを発行する（bot 認証情報が必要）
TG_BOT_ID=BTxxxxxxxxxxxxxxxxxxxxxxxxxxx \
TG_BOT_API_KEY=shisho_apikey_xxxxxxxxxxxxx \
  ./setup.sh issue acme-laptop-042

# install -- 取得済みのトークンを各パッケージマネージャーの設定に書き込む
./setup.sh install tg_org_xxxxxxxxxxxxxxxxx
./setup.sh install tg_org_xxxxxxxxxxxxxxxxx npm,pypi
```

## 補足: 「端末あたり 1 トークン」配信例の公開

これまでのセットアップスクリプトは「端末 × ユーザー」単位で 1 トークンを発行する設計でした。1 台の端末に複数の開発者アカウントが同居する環境（複数のエンジニアが交代で利用する共用ワークステーション、MDM 管理用アカウントと開発者本人のアカウントが共存するノート PC、IdP 経由でプロビジョニングされたアカウントと端末ローカルアカウントが併存する環境など）では、消費ライセンス数が物理的な端末数を超えやすく、ライセンス計画とのズレが発生していました。

v0.5.0 では、上記のサブコマンドを組み合わせて構築した「**端末あたり 1 トークン**」の配信スクリプト例を新たに公開しました。このラッパーは、端末上の各ユーザープロファイルを順に走査して既存の有効なトークンを探し、見つかった場合は再利用、見つからない場合のみ 1 つだけ新しいトークンを発行したうえで、その同じトークンを端末上の全開発者アカウントに配布します。

具体的なスクリプトは[配信例（端末あたり 1 トークン）](/docs/ja/t/guard/features/admin-deployment#deployment-examples-shared)を参照してください。これまでの[配信例（端末のユーザー毎に個別トークン）](/docs/ja/t/guard/features/admin-deployment#deployment-examples)もそのまま残っており、どちらの配信例も有効なトークンを検出した場合は再発行を行わずに再利用するため、Jamf や Intune、Ansible などの管理ツールから定期実行しても安全です。

## 補足: 後方互換性

v0.4.x からアップグレードする場合、管理者側の追加作業は不要です。v0.5.0 以前の `BOT_ID USER_IDENTIFIER [SCOPES]` という 3 つの位置引数による呼び出しはそのまま動作し、標準出力のログ・終了コード・バックアップとロールバックの挙動を含めて、出力はこれまでと完全に同じです。ユーザー単位モデルで過去に発行したトークンも引き続き有効で、次回実行時に再利用されます。どのタイミングで「端末あたり 1 トークン」のラッパーに切り替えても、端末上にすでに存在する有効なトークンを検出して再利用するため、移行時にライセンスが無駄に消費されることはありません。