cmux-sidebar-builder

cmux サイドバーの作成

cmux のカスタムサイドバービューを作成または変更するタスクでは、このスキルを使用します。これらは ~/.config/cmux/sidebars/ にあるユーザー／エージェント作成の .swift ファイルで、コンパイル済みのアプリコードではなく、cmux の実行時 SwiftUI 風インタープリターによってレンダリングされます。主な実地検証の場所は、cmux sidebar open <name> で開く通常の Bonsplit ペインタブです。左サイドバーのピッカーはプレビューに引き続き便利です。

概要

• この機能の元となった作業は、Aziz Albahar による PR https://github.com/manaflow-ai/cmux/pull/5254 です。
• この機能は、UserDefaults に保存されるキー customSidebars.beta.enabled でオプトインします。
• カスタムサイドバーは ~/.config/cmux/sidebars/ に置きます。通常の Bonsplit ペインタブとして cmux sidebar open <name> で開けます。また、ベータ版が有効な場合は左サイドバーのピッカーに表示されます。
• まず、cmux アプリのチェックアウトにあるドキュメントを確認してください：repo/docs/custom-sidebars.md。

cmux ソースの主なエントリーポイント：

• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/SwiftViewInterpreter.swift
• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ExpressionEvaluator.swift
• repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/RenderNode.swift
• repo/Packages/CmuxSwiftRenderUI/Sources/CmuxSwiftRenderUI/Sidebar/CustomSidebarView.swift
• repo/Sources/ContentView.swift の customSidebarsDirectory、customSidebarDataContext、CustomSidebarView(...) 付近。
• Bonsplit ペインのホストについては repo/Sources/Panels/CustomSidebarPanel.swift を参照してください。
• cmux sidebar open <name> の処理については repo/Sources/Workspace+CustomSidebarPane.swift と repo/Sources/TerminalController+CustomSidebarCommands.swift を参照してください。

必要に応じて確認する、後続の実装ブランチ：

• より幅広い SwiftUI 風プリミティブのサポート状況については、origin/feat-interpreter-primitives を参照してください。
• プロセス外でクラッシュを分離するインタープリターワーカーについては、origin/feat-sidebar-interpreter-isolation を参照してください。

ワークフロー

1. 作成に取り掛かる前に、現在のアプリドキュメントとインタープリターの対応範囲を確認します：

   sed -n '1,220p' repo/docs/custom-sidebars.md
   rg -n "struct SwiftViewInterpreter|func evaluate|func parse|enum RenderNode|customSidebarDataContext|customSidebarsDirectory" repo/Packages/CmuxSwiftRender repo/Packages/CmuxSwiftRenderUI repo/Sources/ContentView.swift
   

2. ユーザーの設定ディレクトリにあるサイドバーファイルを作成または編集します：

   mkdir -p ~/.config/cmux/sidebars
   $EDITOR ~/.config/cmux/sidebars/<name>.swift
   

3. インタープリターが対応する範囲内で作業します。シンプルな SwiftUI 風の式、たとえば VStack、HStack、Text、Image、Button、ForEach、条件分岐、対応するモディファイア、提供されたコンテキストのデータを優先します。任意の Swift、インポート、非同期処理、ファイルシステムへのアクセス、ネットワーク通信、カスタム型、コンパイル済みの依存関係が利用できるとは想定しないでください。

4. シェルコマンドを実行するのではなく、提供されたデータコンテキストを使用します。サイドバーに公開されていないデータが必要な場合は、customSidebarDataContext に不足しているフィールドを特定し、cmux の作業用ツリーでのアプリコード変更として対応します。

5. アプリ／ランタイムコードを変更する場合は、cmux リポジトリのワークフローに従います。作業用ツリーを作成し、リポジトリ内の手順を確認し、ユーザー向け文字列をローカライズし、適切にテストしてから、実地検証の引き継ぎ前にタグを指定して再読み込みします。設定のみのサイドバー .swift の編集では、アプリの再ビルドは不要です。

作成ルール

• カスタムサイドバーには、cmux right-sidebar set <name>や右サイドバーの設定を使用しないでください。ユーザーが作業画面の横にサイドバーを表示したい場合、カスタムサイドバーはcmux sidebar open <name>を使ってBonsplitペインに表示してください。
• 左サイドバーのピッカーはプレビュー／選択用の画面です。右サイドバーをカスタムサイドバーのホストとして扱わないでください。
• ユーザーがその画面を明示的に求めない限り、ExtensionKitを使用しないでください。
• カスタムサイドバーのファイルは小さく、内容を確認しやすい状態にしてください。設計が複雑になる場合は、インタープリターがサポートしているときに限り、動作を単純なヘルパー関数に分割してください。
• サポートされているButtonアクションのペイロードを使って、画面上の各アクションを明示してください。repo/Packages/CmuxSwiftRender/Sources/CmuxSwiftRender/ActionCommand.swiftとアプリのディスパッチ処理を確認せずに、アクションIDを独自に作らないでください。
• cmuxのコンテキストから実際のワークスペース、サーフェス、通知、ポート、git、進捗の各フィールドを優先して使用してください。タスクがモックアップのみの場合を除き、プレースホルダーのダッシュボードは避けてください。
• レンダリングに失敗した場合は、再現に必要な最小のサイドバーファイルに簡素化してから、CmuxSwiftRenderのテストおよびコーパスの例と比較してください。

検証

設定のみのサイドバーの場合：

ls ~/.config/cmux/sidebars
cmux sidebar validate <name>
cmux sidebar open <name>

通常の作成作業では、ユーザーが選択しているサイドバーやデフォルトのサイドバーを変更しないでください。ユーザーがカスタムサイドバーの有効化を明示的に求めない限り、元のワークスペースサイドバーをデフォルトのままにしてください。

開いた後、カスタムサイドバーが右サイドバーではなくペインサーフェスであることを確認してください。

cmux identify --json --id-format both
cmux tree --workspace <workspace-ref> --json --id-format both
cmux right-sidebar set <name>   # should fail on current builds; do not use this for setup

タグ付きのdogfoodテストでは、タグに紐付いた開発CLIとソケットを使用してください。たとえば、~/.local/bin/cmux-dev --socket /tmp/cmux-debug-<tag>.sock sidebar open <name> --jsonを実行し、フォーカス中のサーフェスでsurface_type: customSidebarが報告されることを確認してください。

実行中のcmuxビルドが対応している場合は、選択せずに有効なカスタムサイドバーを再読み込みしてください。

cmux sidebar reload --all

サイドバーファイルを編集しただけでは、再読み込みのシグナルとして扱わないでください。書き込みが完了してからCLIの再読み込みコマンドを使用し、書き込み途中のファイルでマウント済みのサイドバーが置き換わらないようにしてください。

ユーザーがカスタムサイドバーの有効化を明示的に求めた場合に限り、検証して選択してください。

cmux sidebar select <name>

cmux sidebarがない古いcmuxビルドの場合は、左サイドバーのピッカーから指定のサイドバーを選ぶようユーザーに案内してください。ユーザーが一時的なローカルdogfoodテスト用の設定を明示的に求めない限り、サイドバーの選択にはdefaults writeを使用しないでください。使用する場合は、それが製品のデフォルトではないことを伝えてください。

インタープリターやアプリに変更を加える場合は、CmuxSwiftRenderの対象を絞ったパッケージテストと、必要最小限の実機dogfood再読み込みを優先してください。ローカルのcmuxでxcodebuild ... testを実行しないでください。プロジェクトのリモートまたはCIテストのガイダンスに従ってください。