feat(github-app): per-repo Octokit resolution and multi-installation queries (#283 PR 2/7) (#296)

## Summary

Issue #283 の実装 stack **PR 2/7** — query / mutation / Octokit 解決層を複数 installation 対応にする。アプリケーションの動作はまだ変えない（fallback で互換維持）。

設計根拠: [`docs/rdd/issue-283-multiple-github-accounts.md`](./docs/rdd/issue-283-multiple-github-accounts.md)
作業計画: [`docs/rdd/issue-283-work-plan.md`](./docs/rdd/issue-283-work-plan.md)

依存: #288 (PR 1: schema)

## 変更内容

### query 層 (`app/services/github-integration-queries.server.ts`)

- `getGithubAppLinks(orgId)` 配列返却（ORDER BY createdAt ASC で決定的順序）
- `getGithubAppLinkByInstallationId(installationId)` 追加
- `assertInstallationBelongsToOrg(orgId, installationId)` 追加 — クライアント由来の `installationId` をサーバ側で検証する境界 guard
- `getGithubAppLink()` は最古の active link を返す互換 shim（`@deprecated`）

### mutation 層 (`app/services/github-app-mutations.server.ts`)

- `disconnectGithubAppLink(orgId, installationId)` 追加 — 単一 installation の soft-delete + 最後の active を失った時のみ `method='token'` に戻す + audit log 書き込み
- 1 transaction 内で完結（idempotent）
- `disconnectGithubApp()` は legacy UI 互換 wrapper として 1 transaction で全 link 一括 soft-delete に書き換え（`@deprecated`）

### audit log writer (`app/services/github-app-link-events.server.ts`) 新規追加

- `logGithubAppLinkEvent()` helper
- event_type / source / status の string union 型を export
- `Kysely<DB> | Transaction<DB>` を受け取り、呼び出し側のトランザクションに乗せられる
- PR 1 で追加した `github_app_link_events` table の **初回 writer**（disconnect 経由）

### Octokit 解決 (`app/services/github-octokit.server.ts`)

- `resolveOctokitForInstallation(installationId)` 追加
- `resolveOctokitForRepository({ integration, githubAppLinks, repository })` 追加 — repository ごとの解決
  - `repository.githubInstallationId` がセットされている場合は厳密にそれを使う（suspended は弾く）
  - `github_app` モードで未割当の repository に対する移行期間 fallback:
    - active link 1 件 → そのまま使う
    - 0 件 → エラー（**PAT 自動 fallback はしない**、RDD ルール）
    - 2+ 件 → エラー（曖昧、明示的な assignment が必要）
  - `token` モード: `privateToken` があれば PAT、無ければ未接続エラー
- `IntegrationForOctokit.method` を `'token' | 'github_app' | (string & {})` のユニオンに型を絞る
- `resolveOctokitFromOrg()` は legacy 互換 wrapper（`@deprecated`、PR 4 で削除予定）

### batch shape 更新 (`batch/db/queries.ts`)

- `getGithubAppLinkByOrgId` → `getGithubAppLinksByOrgId`（配列返却）
- `getAllGithubAppLinks` を `Map.groupBy` で書き換え
- `getOrganization()` / `listAllOrganizations()` が `githubAppLinks: []` を返すよう変更

### crawl / backfill ジョブ (`app/services/jobs/{crawl,backfill}.server.ts`)

- 単一 Octokit 共有から per-repository 解決に変更
- `load-organization` step 内で `github_app + active 0` / `token + privateToken null` の早期エラー検出
- repository ループ内で `resolveOctokitForRepository()` を呼び、解決失敗時は warn ログ + skip（crawl 全体は止めない）

### tsconfig

- `lib` を `ES2024` に bump（`Map.groupBy` を使うため）

### tests

- `app/services/github-octokit.server.test.ts` に `resolveOctokitForRepository` の 11 ケース追加
  - 明示 installation id (一致 / 不一致 / suspended)
  - 移行期間 fallback (active 1 / 0 / 2+ / suspended 除外)
  - token モード (PAT あり / なし)
  - integration null

## 満たす受入条件

- **#6**: `crawl.server.ts` / `backfill.server.ts` が repository ごとに対応 installation の Octokit を使う

## Stack 位置

```text
PR 1 (#288): schema
└ [PR 2: query/octokit] ← this PR
  └ PR 3 (webhook/membership)
    └ PR 4 (UI)
      └ PR 5 (repo UI)
        └ PR 6 (backfill)
          └ PR 7 (strict)
```

## 後続 PR への影響

- PR 3: webhook handler 群がここで追加した `getGithubAppLinkByInstallationId` / `logGithubAppLinkEvent` / canonical reassignment helper（PR 3 で実装）を使う
- PR 4: UI loader / action から `getGithubAppLink()` を `getGithubAppLinks()` に移行 + `assertInstallationBelongsToOrg` を loader 境界で呼ぶ
- PR 7: 移行期間 fallback (`activeLinks.length === 1` 分岐) を削除し、`github_installation_id IS NULL` を strict エラーにする

## テスト

- [x] \`pnpm validate\` (lint / format / typecheck / build / test 全 331 tests)
- [x] \`resolveOctokitForRepository\` の主要 11 ケースをユニットテストで検証

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

## リリースノート

* **新機能**
  * GitHub Appのリンク接続・切断イベントに対する監査ログ機能を追加しました。

* **バグ修正**
  * リポジトリごとのGitHub認証解決ロジックを改善し、複数のアクティブなリンク存在時のエラーハンドリングを強化しました。
  * GitHub Appの削除状態をより厳密に追跡するようにしました。

* **改善**
  * GitHub統合に関する検証とエラー処理を堅牢化しました。
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: coji

app/services/github-app-link-events.server.ts

@@ -0,0 +1,58 @@
+import type { Kysely, Transaction } from 'kysely'
+import { db } from '~/app/services/db.server'
+import type { DB } from '~/app/services/type'
+import type { OrganizationId } from '~/app/types/organization'
+
+export type GithubAppLinkEventType =
+  | 'link_created'
+  | 'link_deleted'
+  | 'link_suspended'
+  | 'link_unsuspended'
+  | 'membership_initialized'
+  | 'membership_repaired'
+  | 'canonical_reassigned'
+  | 'canonical_cleared'
+  | 'assignment_required'
+
+export type GithubAppLinkEventSource =
+  | 'setup_callback'
+  | 'installation_webhook'
+  | 'installation_repositories_webhook'
+  | 'user_disconnect'
+  | 'crawl_repair'
+  | 'manual_reassign'
+  | 'cli_repair'
+
+export type GithubAppLinkEventStatus = 'success' | 'failed' | 'skipped'
+
+export type LogGithubAppLinkEventInput = {
+  organizationId: OrganizationId
+  installationId: number
+  eventType: GithubAppLinkEventType
+  source: GithubAppLinkEventSource
+  status: GithubAppLinkEventStatus
+  details?: Record<string, unknown>
+}
+
+/**
+ * Append an entry to the `github_app_link_events` audit log.
+ *
+ * Pass a transaction to commit the log together with the underlying mutation;
+ * otherwise it writes against the default connection.
+ */
+export const logGithubAppLinkEvent = async (
+  input: LogGithubAppLinkEventInput,
+  dbOrTrx: Kysely<DB> | Transaction<DB> = db,
+): Promise<void> => {
+  await dbOrTrx
+    .insertInto('githubAppLinkEvents')
+    .values({
+      organizationId: input.organizationId,
+      installationId: input.installationId,
+      eventType: input.eventType,
+      source: input.source,
+      status: input.status,
+      detailsJson: input.details ? JSON.stringify(input.details) : null,
+    })
+    .execute()
+}

app/services/github-app-mutations.server.ts

@@ -1,26 +1,117 @@
 import { clearOrgCache } from '~/app/services/cache.server'
 import { db } from '~/app/services/db.server'
+import { logGithubAppLinkEvent } from '~/app/services/github-app-link-events.server'
 import type { OrganizationId } from '~/app/types/organization'
 
 /**
- * Soft-delete the org's GitHub App link and revert integration to token method.
- * Clears appSuspendedAt so a prior suspend flag cannot linger after disconnect.
+ * Soft-delete a single GitHub App installation link.
+ *
+ * Reverts `integrations.method` to `'token'` (and clears `app_suspended_at`)
+ * only when the deleted link was the last active one for the org.
+ *
+ * Writes a `link_deleted` audit log event with `source='user_disconnect'`.
+ *
+ * Idempotent: a no-op if the link is already deleted or does not exist.
  */
-export async function disconnectGithubApp(organizationId: OrganizationId) {
+export async function disconnectGithubAppLink(
+  organizationId: OrganizationId,
+  installationId: number,
+) {
   const now = new Date().toISOString()
+
   await db.transaction().execute(async (trx) => {
-    await trx
+    const updateResult = await trx
       .updateTable('githubAppLinks')
       .set({ deletedAt: now, updatedAt: now })
       .where('organizationId', '=', organizationId)
+      .where('installationId', '=', installationId)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst()
+
+    if (updateResult.numUpdatedRows === 0n) return
+
+    const remaining = await trx
+      .selectFrom('githubAppLinks')
+      .select('installationId')
+      .where('organizationId', '=', organizationId)
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst()
+
+    const revertedToToken = !remaining
+    if (revertedToToken) {
+      await trx
+        .updateTable('integrations')
+        .set({ method: 'token', appSuspendedAt: null, updatedAt: now })
+        .where('organizationId', '=', organizationId)
+        .execute()
+    }
+
+    await logGithubAppLinkEvent(
+      {
+        organizationId,
+        installationId,
+        eventType: 'link_deleted',
+        source: 'user_disconnect',
+        status: 'success',
+        details: { revertedToToken },
+      },
+      trx,
+    )
+  })
+
+  clearOrgCache(organizationId)
+}
+
+/**
+ * Soft-delete every active GitHub App link for the org in a single transaction
+ * and revert integration to token method. Convenience for legacy "disconnect all"
+ * UI flows that treat GitHub App as a single org-wide connection.
+ *
+ * Writes one `link_deleted` audit log entry per affected installation.
+ *
+ * @deprecated Prefer {@link disconnectGithubAppLink} for installation-scoped
+ *   disconnects.
+ */
+export async function disconnectGithubApp(organizationId: OrganizationId) {
+  const now = new Date().toISOString()
+
+  await db.transaction().execute(async (trx) => {
+    const links = await trx
+      .selectFrom('githubAppLinks')
+      .select('installationId')
+      .where('organizationId', '=', organizationId)
       .where('deletedAt', 'is', null)
       .execute()
 
+    if (links.length > 0) {
+      await trx
+        .updateTable('githubAppLinks')
+        .set({ deletedAt: now, updatedAt: now })
+        .where('organizationId', '=', organizationId)
+        .where('deletedAt', 'is', null)
+        .execute()
+    }
+
     await trx
       .updateTable('integrations')
       .set({ method: 'token', appSuspendedAt: null, updatedAt: now })
       .where('organizationId', '=', organizationId)
       .execute()
+
+    for (const link of links) {
+      await logGithubAppLinkEvent(
+        {
+          organizationId,
+          installationId: link.installationId,
+          eventType: 'link_deleted',
+          source: 'user_disconnect',
+          status: 'success',
+          details: { revertedToToken: true },
+        },
+        trx,
+      )
+    }
   })
+
   clearOrgCache(organizationId)
 }

app/services/github-integration-queries.server.ts

@@ -1,6 +1,17 @@
 import { db } from '~/app/services/db.server'
 import type { OrganizationId } from '~/app/types/organization'
 
+const githubAppLinkColumns = [
+  'organizationId',
+  'installationId',
+  'githubAccountId',
+  'githubAccountType',
+  'githubOrg',
+  'appRepositorySelection',
+  'suspendedAt',
+  'membershipInitializedAt',
+] as const
+
 export const getIntegration = async (organizationId: OrganizationId) => {
   return await db
     .selectFrom('integrations')
@@ -9,13 +20,72 @@ export const getIntegration = async (organizationId: OrganizationId) => {
     .executeTakeFirst()
 }
 
+/**
+ * All active (not deleted) GitHub App links for an organization, ordered by
+ * `createdAt` for deterministic iteration.
+ */
+export const getGithubAppLinks = async (organizationId: OrganizationId) => {
+  return await db
+    .selectFrom('githubAppLinks')
+    .select(githubAppLinkColumns)
+    .where('organizationId', '=', organizationId)
+    .where('deletedAt', 'is', null)
+    .orderBy('createdAt', 'asc')
+    .execute()
+}
+
+/**
+ * Oldest active GitHub App link for an organization, or null.
+ *
+ * @deprecated Returns an arbitrary link when an org has multiple active
+ *   installations. Use {@link getGithubAppLinks} and operate per-installation.
+ */
 export const getGithubAppLink = async (organizationId: OrganizationId) => {
+  const links = await getGithubAppLinks(organizationId)
+  return links[0] ?? null
+}
+
+export const getGithubAppLinkByInstallationId = async (
+  installationId: number,
+) => {
   return (
     (await db
       .selectFrom('githubAppLinks')
-      .select(['githubOrg', 'appRepositorySelection', 'installationId'])
-      .where('organizationId', '=', organizationId)
+      .select([...githubAppLinkColumns, 'deletedAt'])
+      .where('installationId', '=', installationId)
       .where('deletedAt', 'is', null)
       .executeTakeFirst()) ?? null
   )
 }
+
+/**
+ * Boundary guard for client-provided `installationId`. Throws if the
+ * installation does not belong to the given org or is deleted/suspended.
+ *
+ * The query is constrained by `organizationId` first so the database can never
+ * leak the existence of installations from other organizations — even the
+ * "not found" branch only fires when the row is missing *for this org*.
+ */
+export const assertInstallationBelongsToOrg = async (
+  organizationId: OrganizationId,
+  installationId: number,
+): Promise<void> => {
+  const link = await db
+    .selectFrom('githubAppLinks')
+    .select(['suspendedAt', 'deletedAt'])
+    .where('organizationId', '=', organizationId)
+    .where('installationId', '=', installationId)
+    .executeTakeFirst()
+
+  if (!link) {
+    throw new Error(
+      `Installation ${installationId} does not belong to this organization`,
+    )
+  }
+  if (link.deletedAt !== null) {
+    throw new Error(`Installation ${installationId} is disconnected`)
+  }
+  if (link.suspendedAt !== null) {
+    throw new Error(`Installation ${installationId} is suspended`)
+  }
+}