widgets-state-security-distribution

ウィジェット、状態、設定、セキュリティ、配布

TUI に製品レベルの操作パターン、堅牢なアプリケーション状態、安全なターミナル処理、ユーザーによるカスタマイズ、または配布のガイダンスが必要な場合に、このスキルを使用してください。

ウィジェット設計の原則

• すべてのウィジェットには、状態、フォーカスルール、キーボード操作、サポートしている場合はマウス操作、バリデーション、アクセシビリティ上の代替手段、スナップショットテストが必要です。
• 操作は予測しやすいものにします。リストでは項目を移動し、テーブルでは並べ替え、フィルタリング、ページ移動を行い、フォームではフィールドの近くにエラーを表示し、ダイアログではフォーカスをトラップし、コマンドパレットではコマンドを検索できるようにします。スクロールバーは位置を示しますが、操作に必須であってはなりません。
• 大規模なリスト、テーブル、ツリーは仮想化し、ビューポートのオフセット、選択状態、展開されたノードを状態として保持します。
• グラフ、プログレスバー、スピナー、ダッシュボードには、テキストによる概要と、動きを抑えたモード／アニメーションなしのモードを用意します。

状態とイベントのアーキテクチャ

明示的なモデル・更新・ビュー、またはリデューサーアーキテクチャを推奨します。

1. モデルはドメイン状態と UI 状態を保持します。
2. イベント／メッセージは、キー、マウス、貼り付け、リサイズ、タイマー、ワーカーの結果、エラーを表します。
3. 更新処理は状態を変換し、副作用をスケジュールします。
4. ビューは状態とサイズから描画します。
5. エフェクトは非同期で実行され、メッセージを返します。

これにより描画が決定的になり、テストのコストを抑えられ、バックグラウンドタスクがターミナルへ直接書き込むのを防げます。

設定とカスタマイズ

• 適切な場合は Unix 系システムで XDG ベースディレクトリを使用し、Windows と macOS ではプラットフォーム標準の設定、キャッシュ、状態の保存場所を使用します。
• 上級ユーザーや、tmux/Zellij のようにキーが競合しやすい環境向けに、キー割り当ての変更を可能にします。
• テーマはウィジェット固有の色ではなく、セマンティックなロールとして保存します。
• 設定ファイルを厳密に検証し、TUI を起動できない場合は、プレーンテキストで対処方法が分かるエラーを表示します。

ターミナルのセキュリティ

ターミナル出力はインタープリターです。信頼できないテキストをターミナルや、後でターミナル上で表示される可能性のあるログに書き込む前に、サニタイズします。エスケープシーケンスの挿入により、タイトルの変更、クリップボードへのデータ書き込み、プロンプトの偽装、テキストの非表示、表示状態の破損が引き起こされる可能性があります。

• 意図的に描画する場合を除き、信頼できないデータに含まれる制御文字を削除するか、視認できる形でエスケープします。
• 貼り付けたテキストはコマンドではなく、データとして扱います。
• 貼り付け可能な長さに上限を設け、貼り付け完了後に検証します。
• 信頼できないコンテンツから OSC 52 でクリップボードへ自動書き込みすることは避けます。
• ハイパーリンクは見えるようにし、誤解を招くリンクテキストは避けます。

配布ルール

• サポートするターミナルと代替手段を文書化します。
• 自動化、アクセシビリティ、インシデント復旧のために、--no-tui の実行方法を用意します。
• プラットフォームの慣習に従ってパッケージ化します。可能であれば静的バイナリを使用し、必要に応じて Homebrew/Scoop/Winget/MSI/パッケージ、シェル補完、man ページ、チェックサムを用意します。
• コンテナ内では TTY がないことを検出し、行指向の動作を提供します。
• クラッシュ時のクリーンアップが開発時だけでなく、リリースビルドでも機能するようにします。

参考ファイル

• references/widget-patterns.md - 一般的なターミナルウィジェット、動作の仕様、アンチパターンです。
• references/state-config-distribution-security.md - MVU 状態管理、非同期エフェクト、設定、パッケージ化、ターミナルのセキュリティです。