APIと実装要件
このページは「Codebase API」で議論した7つの責務を、実装する機能要件として定義します。現在のルートの棚卸しではなく、Forgeが到達すべき契約です。未実装のエンドポイント名や提供済みであることを断定するものではありません。
① 同期の実行・更新追従 — 最優先
- 同期要求を永続ジョブとして受理し、HTTP接続と独立して実行する。受理時は原則
202 Acceptedとジョブを追跡する識別子を返す。 - 待機付き要求は、待機時間を超えても処理を中断せず、同じジョブの状態を後から取得できる。
- ジョブに対象リポジトリ、要求元、対象ref、状態、試行回数、開始・完了時刻、資格情報を含まない失敗理由を持たせる。ジョブ状態とミラーの準備状態を分ける。
- プロセス再起動後に未完了ジョブを復旧し、一時的な失敗はバックオフ付きで自動再試行する。再試行不能な失敗を区別する。
- GitHubの更新通知から同期を起動し、重複イベント・重複要求・同一リポジトリへの並行更新を安全に扱う。
- 複数リポジトリの同期をサーバーが管理する。ブラウザ内の逐次ループに完了責任を持たせない。
到達条件： 画面を閉じても同期が完了する。実行中のプロセスを再起動しても復旧できる。GitHub更新が反映され、再接続したUIでジョブ状態と最終反映コミットを確認できる。
② Gitの保存・配信 — 最優先
- ワークスペース・リポジトリ・コミットを識別してGitオブジェクトとrefsを保持する。
- 閲覧のたびに全bundleをダウンロード・展開しない保存・読み取り方式を用意する。差分更新と連続読み取りでデータを再利用する。
- 更新中も直前の完成済み世代を閲覧でき、同期完了時に整合したrefsへ切り替わる。
- 保存世代、未参照オブジェクト、失敗した同期の一時データを整理する。利用中の世代を削除しない。
- 容量、実行時間、並行実行数、保持期間をサービスの制約として定義し、超過を明確に返す。100 MiB・120秒という現行定数の引き上げだけで完了にしない。
- ダウンロードや閲覧の再利用時にも、ワークスペース境界と最新のアクセス権を守る。
到達条件： 合意したサイズ・並行数のリポジトリで、連続閲覧が全量復元に依存しない。中断した同期で既存の閲覧可能世代を壊さず、世代整理後も参照中のデータが読める。数値目標は実測をもとに確定する。
③ ファイル・履歴の読み取り
| 操作 | 必要な契約 |
|---|---|
| ツリー・ファイル・README | repository、refまたはcommit SHA、path → 子項目、本文、種別、サイズ |
| 履歴 | ref/pathと継続カーソル → コミット一覧、次カーソル |
| コミット詳細 | SHA → 作成者、日時、メッセージ、親、変更ファイル、増減 |
| 差分比較 | base/head → ファイル、hunk、行位置、バイナリ・サイズ制限 |
| 特定時点の閲覧 | ブランチの移動に影響されないcommit SHAによる読み取り |
到達条件： 履歴UIから20件より古い履歴へ進める。コミット詳細・差分・その時点のファイルを同じリポジトリの実データで往復できる。
④ 所有・権限・管理
ワークスペース所有と read / write / admin を、リポジトリの共同作業者・アクセス確認UIへ接続する。権限の一覧、付与、変更、解除はサーバーで認可する。
同期解除とリポジトリ削除を別操作として定義する。解除後の自動同期停止、データの保持、実行中ジョブ、既発行資格情報の扱いを決める。削除はForge側とGitHub側の対象を明示し、GitHubの正本を暗黙に消さない。
到達条件： 権限変更が閲覧・同期・ダウンロードへ反映され、共同作業者UIに実ユーザーを表示する。同期解除・削除後に新しいジョブや資格情報が古い権限で利用されない。
⑤ Clone・Agentへの受け渡し
Forge自身のGit HTTPS配信を用意する。Codeメニュー、CLI、Agentは、GitHubへの直接CloneではなくForgeのリポジトリを取得できる。
リポジトリ・操作・有効期限を制限した短命資格情報の発行、検証、失効を定義する。ブラウザセッション専用APIと、CLI／Agentから利用する認証方式を分ける。資格情報をURLやログへ漏らさない。bundleは取得手段として残せるが、継続的なGit配信の代替にはしない。
到達条件： CLI／AgentがブラウザCookieをコピーせずForgeからclone/fetchでき、期限切れ・失効・権限不足が拒否される。
⑥ PR・レビュー・Checks
GitHubのPR一覧、詳細、base/head、変更ファイル、差分、コメント、レビュー、Checksを実データとして取得し、共通UIへ接続する。ページ送りと更新時刻を含める。
最初は読み取り連携を完成させる。コメント投稿、レビュー送信、マージは書き込みの権限・反映先を定義した後に有効化する。
到達条件： 製品のPR画面が実データで機能し、未接続のfixtureや無効な送信操作を公開しない。
⑦ 書き込み・正本の切り替え — 別段階
新規リポジトリ作成、commit/push、merge、書き込み方向の切り替えを将来の機能要件として持つ。読み取り専用ミラーの完了条件には含めない。
着手前に、GitHubとForgeのどちらが正本か、許可する書き込み方向、競合、保護ブランチ、Checks、古いheadへの操作、監査と復旧を決める。write 権限データの存在をGit書き込み対応の完了とみなさない。
実装の順序と参照
①＋② → ③＋④ → ⑤ → ⑥ → ⑦ の順で進める。URL・具体的なschemaは、この要件に沿ってOpenAPIで確定する。既存のHTTP契約をこの文書だけで変更しない。
ユーザー提示の Cursor Sync Mirror仕様を、非同期受理・待機終了後の継続の参照とする。Cursorと同じ容量上限・可用性SLAを持つとは断定しない。
現状確認には openapi/spec3.yaml、apps/server/src/modules/forge/、packages/contracts/src/forge.ts を用いる。短期キャッシュなど個別の改善が入っても、上記のサービス全体の到達条件で完了を判断する。