serve server.ts の段階的分割

目標

daemon の動作を変更せずに、packages/cli/src/serve/server.ts を段階的に分割します。最初の段階では、境界がすでに明確になっている共有ヘルパーとルートグループを抽出しますが、createServeApp() はミドルウェアの配線、ステートフルな依存関係、トランスポートのマウント、および最終的なエラー処理を担当し続けます。

ミドルウェアとルートの順序

アプリケーションの組み立て順序はパブリックな動作の一部であり、安定している必要があります。

同一オリジンの Origin の削除
CORS とホストの許可リスト
許可されたループバック設定における認証前の /health と /demo
アクセスログ
Web Shell の静的アセット
Bearer 認証
レート制限
JSON ボディパーサーと JSON パーサーエラーマッパー
必要に応じた認証後の /health と /demo
daemon テレメトリ
REST ルートグループ
ACP HTTP および WebSocket ルート
Web Shell のフォールバック
最終エラーハンドラー

抽出された境界

server/request-helpers.ts は、リクエストボディのサニタイズ、クライアント ID の解析、ループバックの検出、パス/クエリのバリデーター、および権限投票ボディの解析を担当します。ルートモジュールは、server.ts からインポートするのではなく、このファイルに依存します。

server/error-response.ts は、ブリッジエラーの分類と HTTP レスポンスのマッピングを担当します。エクスポートされるラッパーはオプションの daemon ロガーを受け取るため、ルートモジュールは既存の stderr と daemon-log の動作を維持できます。

server/session-list.ts は、REST と ACP HTTP の両方の呼び出し元で使用される、永続化済みとライブのセッションリストのマージを担当します。

server/fs-factory.ts は、デフォルトのワークスペースファイルシステムファクトリの構築と、fs 監査警告の発行を担当します。

server/telemetry.ts は、ルートの分類と daemon HTTP テレメトリミドルウェアを担当します。

server/prompt-deadline.ts は、プロンプトのデッドライン解決とその中止センチネルクラスを担当します。

ルートモジュールは既存の registerXRoutes(app, deps) スタイルに従います。これらは、単一の巨大なコンテキストではなく、必要な依存関係のみを受け取ります。

対象外のこと

この段階では、レスポンスボディ、ステータスコード、ヘッダー、SSE フレーム形式、認証順序、またはエラー分類を変更しません。status.ts、event-bus.ts、in-memory-channel.ts などの互換性再エクスポート用シムを削除しません。過去のドキュメントの名前変更や、無関係なキャメルケースのパスのクリーンアップも行いません。

この段階の後、server.ts は 200 行を超えるままになる可能性があります。受け入れ基準は、後続のセッションと SSE の抽出を機械的に行えるようにする、安定した境界です。

監査ノート

ラウンド 1 ではアーキテクチャの境界を確認し、既存のルートモジュールがすでに直接 registerXRoutes(app, deps) 関数を使用しているため、新しい Router 抽象化を却下しました。

ラウンド 2 では障害パスを確認し、ルート抽出時に HTTP ステータスコードが意図せず変更されないように、エラー分類を 1 つのヘルパーに保持しました。

ラウンド 3 では互換性を確認し、run-qwen-serve.ts、ACP HTTP ディスパッチ、およびテストによって消費されるパブリックなエクスポートを維持します。

ラウンド 4 ではテスト戦略を確認し、ユーザーに見える動作の変更がない構造的なリファクタリングであるため、焦点を絞った server.test.ts、ACP HTTP、およびルートのテストに依存します。