hot-updater

Hot Updater CLI

タスクに Hot Updater の CLI、hot-updater.config.ts、React Native の OTA デプロイ、パッチ成果物、バンドル操作、ロールバック、リリースチャネル管理、コード署名キー、データベース移行、フィンガープリント、または診断が関係する場合に、このスキルを使用します。

運用ルール

• ユーザーが別のアプリディレクトリを指定していない限り、プロジェクトのルートから開始します。
• プロバイダーの動作を推測する前に、ローカルの hot-updater.config.ts を読みます。
• CLI の例とユーザー向けの手順には npx hot-updater ... を使用します。
• ユーザーに代わって npx hot-updater init を実行しないでください。このコマンドは対話形式で、プロバイダー、ビルド、およびプロジェクト固有の選択を求めます。ユーザー自身が実行し、セットアップのドキュメントに従うよう案内してください。
• サーバー／インフラのチェックのために npx hot-updater doctor を実行する前に、サーバーのベース URL が利用可能であることを確認してください。ユーザーから提示されておらず、ローカル設定からも明らかでない場合は、まず更新サーバーの URL を尋ねてください。
• doctor の修復ループでは、まず npx hot-updater doctor --json を実行します。fixability: "auto" とマークされた問題はローカルのプロジェクトファイルを編集して修正し、fixability: "command" とマークされた問題については、表示された commands を実行し、対象を絞った変更を行うたびに doctor を再実行します。doctor が合格するか、残りの問題が fixability: "blocked" とマークされるまで続けます。
• fixability: "blocked" は、自動で行うローカルのループの対象外として扱ってください。サーバーインフラの修復には、通常、プロバイダーの認証情報、環境変数、再デプロイの権限が必要です。移行を実行したり、プロバイダーの設定を変更したりせず、阻害要因を要約してください。
• deploy、patch、bundle enable、bundle disable、bundle update、bundle delete、bundle promote、rollback、channel set、keys export-public、keys remove、および db migrate は、状態を変更する操作として扱ってください。
• keys generate と db generate は、ローカルのファイル／成果物を書き込む操作として扱ってください。
• --json は、ここに記載されている対応コマンドでのみ使用してください。状態を変更するコマンドでは、--json は、要求された変更がすでに許可された後の出力形式だけを変更します。対象プロジェクトがこのオプションに対応していない古い CLI を使用している場合は、人間が読みやすい出力に切り替えてください。
• 対話形式でないシェルでは、ユーザーが具体的な変更をすでに要求しており、対象が明確な場合に限り、-y を使用してください。
• バンドルの状態を変更した後は、bundle list または関連するプロバイダーの状態を確認してください。
• deploy が失敗した場合は、デプロイのワークフローを中止してください。ユーザーが追加対応を明示的に求めない限り、修正を繰り返したり、セットアップを編集したり、認証情報を変更したり、依存関係をインストールしたり、移行を実行したりしないでください。失敗したコマンド、関連する出力、考えられる原因、および次に確認すべき項目の提案のみを分析してください。
• ユーザーが明示的に依頼しない限り、プロバイダーの認証情報を編集しないでください。認証情報は通常 .env.hotupdater に保存されていますが、プロジェクトによっては異なる環境読み込みの設定を使用する場合があります。

自然言語での依頼

ユーザーは、次のようなプロンプトでこのスキルを呼び出すことがあります。

$hot-updater deploy using the current app version
$hot-updater deploy the current iOS app version to production
$hot-updater roll back the most recently deployed bundle
$hot-updater list iOS bundles on the production channel
$hot-updater update rollout cohort count for bundle <bundle-id> to 500
$hot-updater promote bundle <bundle-id> to staging
$hot-updater create a patch from bundle <old-id> to <new-id>
$hot-updater export the code signing public key
$hot-updater run doctor with server URL https://updates.example.com/api/check-update
$hot-updater fix local doctor issues that do not require server credentials

依頼を、最も安全な CLI の手順に置き換えます。状態を変更する前に、必要なチャネル、プラットフォーム、バンドルの対象、パッチのベース、移行先のチャネル、またはサーバー URL が不足しており、ローカルの情報からも推測できない場合は、簡潔な質問を 1 つしてください。deploy と patch のチャネルには、ユーザーが別のチャネルを指定している場合、またはローカルの情報からチャネルが明確に示されている場合を除き、CLI のデフォルトである production を使用してください。

現在のアプリバージョンのデプロイ

ユーザーが現在のアプリバージョン向けのデプロイを依頼した場合:

1. サポートされていれば npx hot-updater app-version --json を実行します。そうでなければ npx hot-updater app-version を実行します。
2. 利用可能であれば JSON から ios または android（あるいはその両方）を抽出し、 フォールバックとして人間が読める出力から抽出します。
3. プラットフォームが見つからない場合は、iOS、Android、またはその両方のどれをデプロイするかを尋ねます。
4. -t <version> を指定してデプロイします:

npx hot-updater deploy -p ios -t <ios-app-version>
npx hot-updater deploy -p android -t <android-app-version>

両方のプラットフォームをデプロイする場合は、一度に 1 つのプラットフォームずつ実行し、各結果を サポートされていれば npx hot-updater bundle list -p <platform> --limit 5 --json で、 そうでなければ --json なしで検証します。

デプロイコマンドが失敗した場合は、次のプラットフォームへ進んだり、自動修復を試みたりしないでください。 失敗の分析を報告し、新しいユーザーからのリクエストを待ちます。

直近のバンドルのロールバック

ユーザーがバンドルを指定せずに直近のデプロイのロールバックを依頼した場合:

1. npx hot-updater bundle list --json --limit 10 を実行します。
2. JSON の結果から、有効な最新のバンドルを選択します。
3. そのバンドルの channel、platform、id を使用してスコープ付きロールバックを行います:

npx hot-updater rollback <channel> -p <platform> --target <bundle-id> -y

最新のバンドルがすでに無効になっている場合は、その旨をユーザーに伝え、次に有効なバンドルを ロールバックするかどうかを尋ねます。ロールバック後は、次で検証します:

npx hot-updater bundle list -c <channel> -p <platform> --limit 5 --json

--json が利用できない場合は、同じコマンドを --json なしで再実行します。

コアコマンド

セットアップと診断

npx hot-updater init
npx hot-updater doctor --server-base-url <update-server-url>
npx hot-updater doctor --json
npx hot-updater doctor --server-base-url <update-server-url> --json
npx hot-updater fingerprint
npx hot-updater fingerprint create
npx hot-updater app-version
npx hot-updater app-version --json
npx hot-updater console

• init はプロジェクト設定を作成または更新します。対話形式であるため、ユーザーの代わりに回答を 選ぶのではなく、直接実行するようユーザーに伝えてください。
• doctor はローカルセットアップとサーバーの健全性をチェックします。--server-base-url を指定してください。 このコマンドはサーバーチェックのために /version を付加します。ユーザーが指定していない場合は、 コマンドを実行する前にそれを尋ねてください。
• doctor --json はエージェント向けの推奨インターフェースです。安定した問題コード、関連パス、 fixability、およびローカルでの反復的な修復のためのコマンドヒントを返します。JSON が利用可能な場合は、 人間が読める doctor の出力を解析しないでください。
• fingerprint と fingerprint create はアプリのフィンガープリントを生成します。
• app-version はネイティブの iOS および Android アプリのバージョンを読み取ります。--json は、 それをサポートする CLI では { "android": string | null, "ios": string | null } を返します。
• console はローカルの管理コンソールを開きます。

デプロイ

npx hot-updater deploy -p <ios|android>
npx hot-updater deploy -p ios -c production -r 25
npx hot-updater deploy -p android -f
npx hot-updater deploy -p ios -d
npx hot-updater deploy -p ios -o ./hot-updater-output

重要なオプション:

オプション	意味
-p, --platform <platform>	対象の ios または android。
-c, --channel <channel>	リリースチャネル。デフォルトは production。
-t, --target-app-version <range>	1.2.3 や 1.x.x のようなアプリバージョン範囲。
-r, --rollout <percentage>	0 から 100 までの初期ロールアウト率。
-f, --force-update	クライアントの更新時に即座に適用します。
-d, --disabled	後で有効化するために無効化してアップロードします。
-o, --bundle-output-path <path>	バンドルアーカイブが生成されるディレクトリ。
-m, --message <message>	カスタムのデプロイメッセージ。
-i, --interactive	ガイド付きのデプロイフロー。

パッチアーティファクト

npx hot-updater patch -b <bundle-id> --base-bundle-id <base-bundle-id> -p ios
npx hot-updater patch -b <bundle-id> --base-bundle-id <base-bundle-id> -p android -c production
npx hot-updater patch -i

重要なオプション:

オプション	意味
-b, --bundle-id <bundleId>	パッチアーティファクトを受け取る対象のバンドル id。
--base-bundle-id <baseBundleId>	パッチのベースとして使用する古いバンドル id。
-p, --platform <platform>	対象の ios または android。
-c, --channel <channel>	設定の読み込みに使用するチャネル。デフォルトは production。
-i, --interactive	ガイド付きのパッチフロー。

バンドルの一覧と状態

npx hot-updater bundle list
npx hot-updater bundle list -c production -p ios --limit 10
npx hot-updater bundle list -c production -p ios --limit 10 --json
npx hot-updater bundle list --json
npx hot-updater bundle show <bundle-id>
npx hot-updater bundle show <bundle-id> --json
npx hot-updater bundle disable <bundle-id>
npx hot-updater bundle enable <bundle-id>
npx hot-updater bundle update <bundle-id> --rollout-cohort-count 500
npx hot-updater bundle update <bundle-id> --force-update true --json
npx hot-updater bundle update <bundle-id> --target-cohorts 1,2,3
npx hot-updater bundle update <bundle-id> --clear-target-cohorts
npx hot-updater bundle delete <bundle-id>
npx hot-updater bundle promote <bundle-id> -t staging
npx hot-updater bundle promote <bundle-id> -t staging -a move

• bundle list では、最新のバンドルから順に表示されます。
• bundle list --limit <n> のデフォルト値は 20 です。
• --json は、対応している CLI の bundle list、bundle show、bundle update で使用できます。
• bundle disable と bundle enable は、バンドルを読み込み、有効状態を変更して変更をコミットした後、再度読み込んで確認します。
• bundle update では、ロールアウトのコホート数を 0 から 1000 まで設定し、メタデータを強制的に更新して、対象のコホートを指定できます。
• bundle delete は、IDでバンドルのレコードを削除します。
• bundle promote は、デフォルトで対象チャネルにコピーします。同じバンドル ID を維持したままチャネルを移動することをユーザーが明示的に希望する場合に限り、-a move を使用してください。
• CI またはその他の非対話型シェルでは、enable または disable に -y を渡してください。update、delete、promote に -y を渡すのも、要求された変更対象が明確な場合に限ります。

ロールバック

npx hot-updater rollback <channel>
npx hot-updater rollback production -p ios
npx hot-updater rollback production -p ios --target <bundle-id> -y

• ロールバックすると、チャネル上で直近に有効化されたバンドルが無効になります。
• -p を指定しない場合、ロールバックは iOS と Android の両方に適用されます。
• 同じチャネルとプラットフォームで次に新しい有効なバンドルが、フォールバック先になります。
• 以前に有効だったバンドルがない場合、アプリはネイティブバイナリに同梱された JavaScript バンドルにフォールバックします。
• 1つのバンドルだけを対象に部分的なロールバックを再試行するには、--target <bundle-id> を使用してください。

チャネル

npx hot-updater channel set <channel>

これにより、デフォルトのチャネルがネイティブ iOS および Android プロジェクトのファイルに書き込まれます。この埋め込みチャネルを変更するには、ネイティブの再ビルドが必要です。

コード署名キー

npx hot-updater keys generate
npx hot-updater keys generate -o ./keys -k 4096
npx hot-updater keys export-public
npx hot-updater keys export-public -i ./keys/private.pem --print-only
npx hot-updater keys remove

• keys generate は RSA キーペアを書き込みます。デフォルトの出力ディレクトリは ./keys です。サポートされているキーサイズは 2048 と 4096 で、デフォルトは 4096 です。
• keys export-public は、-i または hot-updater.config.ts の signing.privateKeyPath から秘密鍵を読み込み、--print-only を使用しない限り、ネイティブの公開鍵設定を書き込みます。
• keys remove は、ネイティブ設定ファイルから公開鍵を削除します。
• ネイティブファイルへの書き込みに -y を使用するのは、ユーザーがその操作を明示的に要求した場合に限ってください。

データベース

npx hot-updater db generate [configPath] [outputDir]
npx hot-updater db generate --sql
npx hot-updater db generate --sql postgresql
npx hot-updater db migrate [configPath]

• db generate は、適用せずにマイグレーションの出力を作成します。デフォルトの出力ディレクトリは hot-updater_migrations です。
• db generate --sql [provider] は、設定を読み込まずにスタンドアロンの SQL ファイルを作成します。サポートされているプロバイダーは postgresql、mysql、sqlite です。プロバイダーを省略すると、対話形式で選択できます。
• db migrate は、設定済みのデータベースプラグインを通じて最新のマイグレーションを適用します。
• 書き込みまたはマイグレーションをユーザーが明示的に要求した場合に限り、-y を渡してください。