macos-menubar-tuist-app

macos-menubar-tuist-app

Tuist を中心としたワークフローと安定した起動スクリプトを使用して、macOS のメニューバーアプリをビルド、保守します。厳格なアーキテクチャ境界を維持し、ネットワーキング、状態、UI のテスト容易性と予測可能性を確保します。

基本ルール

• 明示的に指示されない限り、アプリはメニューバー専用にします。デフォルトで LSUIElement = true を使用します。
• 通信処理とデコード処理はビューの外に置きます。SwiftUI のビュー本体からネットワーキングを呼び出さないでください。
• 状態遷移は行やビューの表示コードではなく、ストア層（@Observable または同等の仕組み）に置きます。
• モデルのデコードは API の変更に耐えられるようにします。フィールドはオプションとし、安全なフォールバックと防御的な解析を行います。
• Tuist のマニフェストを信頼できる唯一の情報源として扱います。手動で編集した生成済みの Xcode 成果物に依存しないでください。
• macOS のターゲット／デバイス解決で tuist run が不安定な場合は、ローカルでの反復作業にスクリプト経由の起動を優先します。
• ローカルの実行スクリプトで生成済みプロジェクトをビルドする場合は、素の xcodebuild より tuist xcodebuild build を優先します。

想定するファイル構成

デフォルトでは、次の配置を使用します。

• Project.swift：アプリのターゲット、設定、リソース、Info.plist のキー
• Sources/*Model*.swift：API／ドメインモデルとデコード
• Sources/*Client*.swift：リクエスト、レスポンスのマッピング、通信関連処理
• Sources/*Store*.swift：監視可能な状態、更新ポリシー、フィルタリング、キャッシュ
• Sources/*Menu*View*.swift：メニューの構成とトップレベルの UI 状態
• Sources/*Row*View*.swift：行の描画と軽量なインタラクション
• run-menubar.sh：ローカルでの再起動／ビルド／起動に使用する標準スクリプト
• stop-menubar.sh：必要に応じて使用する明示的な停止用ヘルパー

ワークフロー

1. Tuist が管理元であることを確認する

• Tuist.swift と Project.swift（またはワークスペースのマニフェスト）が存在することを確認します。
• 起動方法を変更する前に、既存の実行スクリプトを読みます。

2. 実装上の前提を置く前に、バックエンドの動作を調べる

• curl を使用して、エンドポイントの形式、認証要件、ページネーションの動作を確認します。
• エンドポイントが limit/page を無視する場合は、ストア内でローカルに件数を絞り込む全件処理を実装します。

3. 下層から上層へレイヤーを実装する

• まずモデルを定義／調整します。
• クライアントのリクエスト／デコード処理を追加または更新します。
• ストアの更新、フィルタリング、キャッシュのポリシーを更新します。
• 最後にビューを接続します。

4. アプリの配線を最小限に保つ

• アプリのエントリーポイントは、シーン／メニューの配線と依存性注入に集中させます。
• App やメニューシーンの宣言にビジネスロジックを埋め込まないでください。

5. 起動方法を標準化する

• 再起動前に、実行スクリプトが既存のインスタンスを終了するようにします。
• 実行スクリプトの副作用として Xcode を開かないようにします。
• 生成が必要な場合は tuist generate --no-open を使用します。
• 実行スクリプトで生成済みプロジェクトをビルドする場合は、素の xcodebuild を直接呼び出すのではなく、TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build ... を優先します。

検証マトリクス

編集後に検証を実行します。

TUIST_SKIP_UPDATE_CHECK=1 tuist xcodebuild build -scheme <TargetName> -configuration Debug

起動ワークフローを変更した場合：

./run-menubar.sh

シェルスクリプトを変更した場合：

bash -n run-menubar.sh
bash -n stop-menubar.sh
./run-menubar.sh

よくある問題と対処方針

• tuist run で macOS の実行先を解決できない： ローカルでの標準的な実行方法として、実行／停止スクリプトを使用します。

• 更新後にメニュー UI の動作が遅い、または一貫しない： 導出状態とフィルタリングをストアに移し、ビューは描画のみにします。

• API ペイロードの変更でデコードに失敗する： フィールドをオプションにし、デフォルト値を設定してモデルのデコードを柔軟にします。不足データは UI で安全に表示します。

• 機能追加で UI の簡易修正を求められた： 行／メニューの表示を変更する前に、モデル／クライアント／ストアを調べて根本原因を特定します。

完了チェックリスト

• 明示的に変更されない限り、メニューバー専用の動作を維持します。
• ネットワーク処理と状態管理のロジックを SwiftUI のビュー本体に置きません。
• Tuist のマニフェストと実行スクリプトを、実際のビルド／実行フローに合わせます。
• 変更した領域に対して検証マトリクスを実行します。
• 実行したコマンドと結果を具体的に報告します。