tiltup

Tilt を起動する

原則（常に適用）

Tiltfile、Tilt のエラー、または開発環境のブートストラップに取り組む際は、常に以下を適用します。

症状ではなく Tiltfile を修正する

• ソース設定を直接修正する - Tiltfile、Dockerfile、k8s マニフェスト、または Helm の値
• シェルで回避しない - ラッパースクリプト、|| true、try/except pass は使用しません
• 動的であるべきポート、パス、ホスト名、イメージタグ、コンテナ名をハードコードしない
• 実際のエラーを覆い隠すフォールバックを追加しない - リソースに問題が発生した場合、その失敗が見える状態にします
• 不安定な依存関係に対するスリープ／再試行ループを追加しない - resource_deps() または k8s_resource(deps=) で依存関係の順序を修正します
• Tilt がすでに処理している準備状況のポーリングを追加しない - k8s_resource(readiness_probe=) またはプローブ設定を使用します

依存関係を宣言的に表現する

• ポートの競合：別のポートを選ぶのではなく、ポート割り当て元を修正します
• リソースの起動順序：順次起動スクリプトではなく、resource_deps() を使用します
• 環境変数：インラインのデフォルト値ではなく、silo.toml または gen-env の出力を使用します
• イメージの利用可能性：準備完了までスリープするのではなく、image_deps または deps を使用します

Tilt のライブリロード

Tiltfile を編集すると、Tilt は変更を自動的に反映します。以下の場合に tilt up を再起動しないでください。

• Tiltfile の編集
• ソースコードの変更
• Kubernetes マニフェストの更新

再起動するのは、Tilt のバージョンアップグレード、ポート／ホスト設定の変更、クラッシュ、クラスターコンテキストの切り替えの場合のみです。

ワークフロー（Tilt を明示的に起動する場合）

ステップ 1：現在の状態を確認する

1. tilt がすでに実行中か確認します。

   PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
   zmx list --short 2>/dev/null | grep -q "^${PROJECT}-tilt$"
   

   実行中の場合は、tilt get uiresources -o json でヘルス状態を確認し、ステップ 3 に進みます。

2. 必要な環境ファイル（.localnet.env、.env.local、silo.toml）を確認します。

   • silo.toml がある場合は、silo up の手順を使用します
   • gen-env スクリプトがある場合は、まず実行します
   • どちらもない場合は、プロジェクトの README でブートストラップ手順を確認します

3. k3d クラスターまたは Docker の前提条件を確認します。

ステップ 2：zmx で Tilt を起動する

zmx スキルのパターンに従います。

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
SESSION="${PROJECT}-tilt"

if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
  echo "Tilt session already exists: $SESSION"
else
  zmx run "$SESSION" 'tilt up'
  echo "Started tilt in zmx session: $SESSION"
fi

silo プロジェクトでは、tilt up の代わりに silo up を実行します。

ステップ 3：ブートストラップを監視する

収束するまでポーリングします。

1. 初期リソース登録のために 10 秒待ちます
2. 15 秒ごとに最大 20 回ポーリングします。docker-compose コンテナのヘルス状態も含めます （composeResourceInfo.healthStatus）。Up (unhealthy) の compose コンテナは runtimeStatus=ok のままで、ほかの方法では見えません。そのため、ブートストラップが 完了したように見えても、canton/splice/postgres が HEALTHCHECK にひそかに失敗している 可能性があります。

   tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending" or .status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus) compose=\(.status.composeResourceInfo.healthStatus // "-")"'
   

3. リソースを追跡します：pending -> in_progress -> ok
4. 成功の条件：すべてのリソースが runtime=ok, update=ok（または not_applicable）に到達し、 かつ docker-compose リソースの composeResourceInfo.healthStatus == "unhealthy" がないこと
5. リソースが error のまま安定する場合、または compose リソースが unhealthy のままの場合は、 ステップ 4 に進みます。compose のプローブが unhealthy の場合は、 docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' で実際の原因を確認します。 マウントされたヘルスチェック用スクリプトが、イメージに含まれていない CLI を呼び出していることがよくあります （サービス自体は稼働しています。チェックを無効にするのではなく、プローブスクリプトを修正します）。

ステップ 4：エラーを診断して修正する

エラー状態の各リソースについて、次の手順を行います。

1. ログを読みます：tilt logs <resource> --since 2m
2. Tiltfile と関連する k8s マニフェストを読みます
3. 実行中のプロセスではなく、設定内の根本原因を特定します
4. 上記の原則に従って修正を適用します
5. Tilt はライブリロードします。ステータスを再度ポーリングして確認します

進展がないまま同じリソースに対して修正を 3 回繰り返した場合：

• 完全なログとともにエラーを報告します
• Tiltfile のバグ、上流の依存関係、またはインフラストラクチャの問題のいずれかを特定します
• リソースを黙ってスキップしたり無効にしたりしないでください

ステップ 5：報告する

## Tilt Status: <healthy|degraded|errored>

**Resources**: X/Y ok
**Session**: zmx $SESSION

### Errors (if any)
- <resource>: <root cause> — <what was fixed or what remains>