refactor(web/server): consolidate GitHub utilities into single module (#436)

2026-02-16 22:58:56 +02:00
parent 4fce1c9f9f
commit 58b27fa621
8 changed files with 89 additions and 19 deletions
@@ -0,0 +1,47 @@
+# GitHub Module Documentation
+
+## Purpose
+This module provides GitHub authentication, OAuth device flow, Octokit client factory, and repository URL parsing utilities for the web server runtime.
+
+## Entrypoints and structure
+- `packages/web/server/lib/github/index.js`: public entrypoint imported by `packages/web/server/index.js`.
+- `packages/web/server/lib/github/auth.js`: auth storage, multi-account support, and client ID/scope configuration.
+- `packages/web/server/lib/github/device-flow.js`: OAuth device code flow implementation for browserless auth.
+- `packages/web/server/lib/github/octokit.js`: Octokit client factory backed by current auth.
+- `packages/web/server/lib/github/repo/index.js`: GitHub remote URL parser and directory-to-repo resolver.
+
+## Public exports (from index.js)
+
+### Auth (`auth.js`)
+- `getGitHubAuth()`: Returns current auth entry (accessToken, user, scope, accountId).
+- `getGitHubAuthAccounts()`: Returns list of all configured accounts.
+- `setGitHubAuth({ accessToken, scope, tokenType, user, accountId })`: Stores or updates auth entry.
+- `activateGitHubAuth(accountId)`: Sets specified account as current.
+- `clearGitHubAuth()`: Removes current account or deletes storage file if last account.
+- `getGitHubClientId()`: Resolves client ID from env var, settings.json, or default.
+- `getGitHubScopes()`: Resolves scopes from env var, settings.json, or default.
+- `GITHUB_AUTH_FILE`: Storage file path constant.
+
+### Device flow (`device-flow.js`)
+- `startDeviceFlow({ clientId, scope })`: Requests device code from GitHub.
+- `exchangeDeviceCode({ clientId, deviceCode })`: Polls for access token.
+
+### Octokit (`octokit.js`)
+- `getOctokitOrNull()`: Returns configured Octokit instance or null if no auth.
+
+### Repo (`repo/index.js`)
+- `parseGitHubRemoteUrl(raw)`: Parses SSH/HTTPS URLs into `{ owner, repo, url }`.
+- `resolveGitHubRepoFromDirectory(directory, remoteName)`: Resolves GitHub repo from git remote.
+
+## Storage and configuration
+- Auth storage: `~/.config/openchamber/github-auth.json` (atomic writes, mode 0o600).
+- Client ID: `OPENCHAMBER_GITHUB_CLIENT_ID` env var → `settings.json` → default.
+- Scopes: `OPENCHAMBER_GITHUB_SCOPES` env var → `settings.json` → default.
+
+## Account resolution
+Account IDs are resolved in priority order: explicit `accountId` → user login → user ID → token prefix.
+
+## Notes for contributors
+- All auth operations use atomic file writes for safe multi-instance sharing.
+- Device flow handles GitHub's `authorization_pending` responses at caller level.
+- Repo parser supports `git@github.com:`, `ssh://git@github.com/`, and `https://github.com/` URL formats.