feat: ADR-0011 PR-E5 — token 自動 refresh + E2E + docs

[shomatan]

Summary

ADR-0011 完了 PR: buildMcpServers が expiry 近接 token を transparent に refresh し、PR-E1 〜 PR-E4 の統合シナリオを E2E テストで通す。docs を整備して ADR-0011 を Accepted に確定。

• token 自動 refresh: expiresAt - now ≤ 5 min + refreshToken あり → refreshAccessToken を発火 → store 書き戻し → 新 access_token を header に注入
• E2E テスト: orchestrator → loopback callback → token store → buildMcpServers → header の 1 シナリオ + 透過 refresh の 1 シナリオ
• docs: README に Atlassian OAuth セットアップ手順、ADR-0011 を Accepted に確定

ADR-0011 ロードマップ完了

• PR-E1 (feat: ADR-0011 PR-E1 — OAuth schema + token store の土台 (issue #28) #29): schema + token store
• PR-E2 (feat(ai-engine): ADR-0011 PR-E2 — OAuthClient + LoopbackCallbackServer #30): OAuthClient + LoopbackCallbackServer
• PR-E3a (feat(ai-engine): ADR-0011 PR-E3a — OAuthFlowOrchestrator #31): OAuthFlowOrchestrator
• PR-E3b (feat(ai-engine,frontend): ADR-0011 PR-E3b — OAuth Route Handler + AuthRequestCard 改修 #32): Route Handler + AuthRequestCard 改修
• PR-E4 (feat: ADR-0011 PR-E4 — chat-runner OAuth 削除 + token 注入 #33): chat-runner OAuth removal + buildMcpServers token 注入
• PR-E5 (本 PR): token refresh + E2E + docs

主な変更点

buildMcpServers 透過 refresh

新ヘルパ loadUsableToken で 1 server 分の取得を切り出し、以下の制御フロー:

1. token なし → null (header なし)
2. expiresAt 不明 / 期限十分先 → そのまま注入
3. expiresAt が REFRESH_BUFFER (5 min) 以内 + refreshToken なし → 過去なら null、まだ有効ならそのまま注入
4. expiresAt が 5 min 以内 + refreshToken あり → refreshAccessToken を発火
   • 成功: 新 token を store に書き戻し + 注入
   • 失敗 (4xx / network): 過去なら null、まだ有効ならそのまま注入

provider が refresh 時に新 refresh_token を返さない (rotate 無し) 場合は旧 refresh_token を保持 (RFC 6749 §6 互換)。

E2E テスト (oauth-e2e.test.ts)

• token endpoint だけ mock、loopback callback への fetch は real fetch に流す
• シナリオ 1: orchestrator start → callback fetch → token 永続化 → buildMcpServers が同 store から読んで Authorization header 構築
• シナリオ 2: 期限切れ間近の token を直接 store に書き、buildMcpServers が透過 refresh して header に新 access_token を載せる + store に書き戻す

docs

• README.md: 「外部 MCP (Atlassian) の OAuth セットアップ」section 追加。redirect URI は Tally が表示する実ポートを Atlassian developer console に登録する旨を明記 (port=0 静的登録は不可、RFC 8252 対応待ち)
• docs/adr/0011-tally-managed-oauth-flow.md:
  • status を Accepted (PR-E5 merge をもって確定) に
  • PR 分割実績テーブルを実状に合わせて更新 (E3 を E3a/E3b に分割した経緯を含む)
  • 「完了後の確定事項」セクション追加 (refresh 設計、削除されたもの、AuthRequestCard 配置、Connect ボタン描画条件)

codex セカンドオピニオン対応

1. Major feat: プロジェクトストレージ再設計（codebases[] + registry + folder picker） #1 (expires_in 計算): refresh の HTTP ラウンドトリップ後に Date.now() を再取得して expiresAt を計算 (古い now を使うと数秒早く期限切れに見える)
2. Major feat(frontend): プロジェクト作成/インポートのUX改善 (2026.4.22.1) #2 (write race): chat-runner / agent-runner 並走時の race を comment 化。MVP 単一ユーザー前提で last-write-wins 許容、multi-tenant 化時に mutex 必要と明記
3. Minor chore(deps): 主要依存を最新メジャーへ更新 #3 (README): redirect URI の port を実ポートで登録する旨を明記
4. Minor ノードをアコーディオン化し、メインのパネルではノードのつながりが見えやすいようにしたい #4 (ADR status): Accepted (PR-E5 merge をもって確定) と hedge

Test plan

• ai-engine 242 pass (+7: refresh path 5 / E2E 2)
• core 94 / storage 97 / frontend 282 pass (PR-E5 範囲では変更なし)
• typecheck (core / storage / ai-engine / frontend) clean
• biome lint clean
• 実環境で OAuth 認証 → token expiry を待って transparent refresh 動作を確認 (手動 QA、別タスク)

Summary by CodeRabbit

リリースノート

• 新機能

  • 外部 MCP サーバー（Atlassian）のアクセストークンが自動的にリフレッシュされるようになりました。トークン有効期限が近づいている場合、システムが透過的に更新を試みます。

• ドキュメント

  • Atlassian OAuth セットアップの手順を起動方法セクションに追加しました。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 423c12dc-9362-49fe-b2a8-100fd647b91c

📥 Commits

Reviewing files that changed from the base of the PR and between 907e623 and f296b5f.

📒 Files selected for processing (5)

• README.md
• docs/adr/0011-tally-managed-oauth-flow.md
• packages/ai-engine/src/mcp/build-mcp-servers.test.ts
• packages/ai-engine/src/mcp/build-mcp-servers.ts
• packages/ai-engine/src/oauth/oauth-e2e.test.ts

---

📝 Walkthrough

Walkthrough

ADR-0011 の Tally 管理 OAuth フローの実装をドキュメント化・完成させるPRです。OAuth token refresh 機能を buildMcpServers に追加し、セットアップ手順をREADMEに記載し、ユニットテスト・E2Eテストで検証します。

Changes

OAuth Token Refresh 実装

Layer / File(s)	Summary
ドキュメント更新 docs/adr/0011-tally-managed-oauth-flow.md, README.md	ADR-0011 のステータスを「Proposed」から「Accepted」に更新。PR-E1〜E5の実装段階テーブルを追加。README に Atlassian OAuth クライアント設定とMCP サーバー認証手順を記載。
Token Refresh 核実装 packages/ai-engine/src/mcp/build-mcp-servers.ts	新たに loadUsableToken ヘルパーを追加。Token がrefresh buffer に達したら refreshAccessToken で透過的に更新。更新済みtoken を oauthStore に永続化。Refresh 失敗時は Authorization header を省略してUI再認証をトリガー。
テストインフラ拡張 packages/ai-engine/src/mcp/build-mcp-servers.test.ts	OAuthStore テストヘルパーを stateful 設計へ刷新（current map で mutable state を管理）。afterEach でmock 破棄。PR-E5 refresh テストスイートを追加：buffer内refresh、refresh 失敗、refreshToken 不在など複数ケース検証。
E2Eテスト検証 packages/ai-engine/src/oauth/oauth-e2e.test.ts	OAuth authorize → callback → token 永続化 → buildMcpServers header injection パイプラインの全体フロー検証。Refresh-on-expiry 動作確認テスト（pre-seeded token での透過的更新検証）を追加。

Sequence Diagram

sequenceDiagram
    actor User as ユーザー
    participant UI as Tally UI
    participant OAuthOrch as OAuthFlowOrchestrator
    participant AtlassianOAuth as Atlassian OAuth Provider
    participant Store as FileSystemOAuthStore
    participant MCP as buildMcpServers

    User->>UI: 🔓 認証ボタンをクリック
    UI->>OAuthOrch: authorize() 呼び出し
    OAuthOrch-->>UI: authorizationUrl 返却
    UI->>AtlassianOAuth: authorize URL に遷移
    User->>AtlassianOAuth: 認可承認
    AtlassianOAuth-->>UI: redirect (code + state)
    UI->>OAuthOrch: callback fetch (code/state)
    OAuthOrch->>AtlassianOAuth: token endpoint (code 交換)
    AtlassianOAuth-->>OAuthOrch: access_token, refresh_token
    OAuthOrch->>Store: token 書き込み
    Store-->>OAuthOrch: 完了
    
    Note over UI,Store: 通常の MCP 呼び出し時

    UI->>MCP: buildMcpServers() 呼び出し
    MCP->>Store: loadUsableToken() で token 読込
    
    alt Token 内 refresh buffer
        MCP->>AtlassianOAuth: refreshAccessToken (refresh_token)
        AtlassianOAuth-->>MCP: 新 access_token
        MCP->>Store: 更新 token 書き込み
    else Token 有効期限切れ / refresh 失敗
        MCP-->>MCP: null (header 省略)
    end
    
    MCP-->>UI: MCP config (Authorization: Bearer token)
    UI->>User: ツール呼び出し完了 / 再認証促進

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(ai-engine): ADR-0011 PR-E2 — OAuthClient + LoopbackCallbackServer #30: Token refresh ロジックと OAUTH_REGISTRY、Atlassian OAuth 設定の使用が、feat(ai-engine): ADR-0011 PR-E2 — OAuthClient + LoopbackCallbackServer #30 で導入された OAuth クライアントおよび provider 型に直接依存している。
• feat: ADR-0011 PR-E1 — OAuth schema + token store の土台 (issue #28) #29: main PR が #29 で導入された OAuth スキーマ・ストレージとレジストリを拡張（token refresh、buildMcpServers での OAuthStore 使用、E2Eテスト）している。
• feat(ai-engine): ADR-0011 PR-E3a — OAuthFlowOrchestrator #31: 同じ ADR-0011 OAuth ワークストリームの異なる部位を実装（feat(ai-engine): ADR-0011 PR-E3a — OAuthFlowOrchestrator #31 では OAuthFlowOrchestrator APIs と フロー状態管理、main PR は token 永続化・refresh と E2Eテスト統合）。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	プルリクエストのタイトルは、ADR-0011 PR-E5 における token 自動 refresh、E2E テスト、ドキュメント整備という主要な変更内容を簡潔かつ明確に要約しており、チェンジセット全体の中心的な変更を適切に反映している。
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/oauth-refresh-and-docs-pr-e5

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}