@algochad/archcoder 2.0.2

package/server/lib/github/DOCUMENTATION.md

@@ -0,0 +1,170 @@
+# GitHub Module Documentation
+
+## Purpose
+
+- This module owns GitHub auth, Octokit access, repo resolution, and Pull Request status resolution for OpenChamber.
+- From user perspective, this is the layer that lets the app know which PR belongs to a local branch and keeps that UI feeling current.
+
+## Entrypoints and structure
+
+- `packages/web/server/lib/github/index.js`: public server entrypoint.
+- `packages/web/server/lib/github/auth.js`: auth storage, multi-account support, client id, scope config.
+- `packages/web/server/lib/github/device-flow.js`: OAuth device flow.
+- `packages/web/server/lib/github/octokit.js`: Octokit factory for the current auth.
+- `packages/web/server/lib/github/repo/index.js`: remote URL parsing and directory-to-repo resolution.
+- `packages/web/server/lib/github/pr-status.js`: PR lookup across remotes, forks, and upstreams.
+- `packages/web/server/index.js`: API route layer that calls this module.
+- `packages/web/src/api/github.ts`: web client wrapper for GitHub endpoints.
+
+## Public exports
+
+### Auth
+
+- `getGitHubAuth()`: current auth entry.
+- `getGitHubAuthAccounts()`: all configured accounts.
+- `setGitHubAuth({ accessToken, scope, tokenType, user, accountId })`: save or update account.
+- `activateGitHubAuth(accountId)`: switch active account.
+- `clearGitHubAuth()`: clear current account.
+- `getGitHubClientId()`: resolve client id.
+- `getGitHubScopes()`: resolve scopes.
+- `GITHUB_AUTH_FILE`: auth file path.
+
+### Device flow
+
+- `startDeviceFlow({ clientId, scope })`: request device code.
+- `exchangeDeviceCode({ clientId, deviceCode })`: poll for access token.
+
+### Octokit
+
+- `getOctokitOrNull()`: current Octokit or `null`.
+
+### Repo
+
+- `parseGitHubRemoteUrl(raw)`: parse SSH or HTTPS remote URL into `{ owner, repo, url }`.
+- `resolveGitHubRepoFromDirectory(directory, remoteName)`: resolve GitHub repo from a local git remote.
+
+## Auth storage and config
+
+- Auth storage: `~/.config/openchamber/github-auth.json`
+- Writes are atomic and file mode is `0o600`.
+- Client ID resolution order: `OPENCHAMBER_GITHUB_CLIENT_ID` -> `settings.json` -> default.
+- Scope resolution order: `OPENCHAMBER_GITHUB_SCOPES` -> `settings.json` -> default.
+- Account id resolution order: explicit `accountId` -> user login -> user id -> token prefix.
+
+## PR integration overview
+
+- The UI asks `github.prStatus(directory, branch, remote?)` from `packages/web/src/api/github.ts`.
+- That hits `GET /api/github/pr/status` in `packages/web/server/index.js`.
+- The route calls `resolveGitHubPrStatus(...)` in `packages/web/server/lib/github/pr-status.js`.
+- The resolver finds the most likely repo and PR for a local branch.
+- The route then enriches that result with checks, mergeability, and permission-related fields.
+- The client caches and shares the result between sidebar and Git view.
+
+## Consumers of PR data
+
+- `packages/ui/src/components/session/SessionSidebar.tsx` reads all PR entries and maps them to `directory::branch`.
+- `packages/ui/src/components/session/sidebar/SessionGroupSection.tsx` renders the compact badge, PR number, title, checks summary, and GitHub link.
+- `packages/ui/src/components/views/git/PullRequestSection.tsx` uses the same shared entry for the full PR workflow.
+- `packages/ui/src/components/ui/MemoryDebugPanel.tsx` reads request counters for debugging.
+
+## How PR resolution works
+
+- It reads local git status and remotes first.
+- It ranks remotes in this order: explicit remote, tracking remote, `origin`, `upstream`, then the rest.
+- It resolves those remotes into GitHub repos.
+- It expands each repo through `parent` and `source` so PRs in upstream repos can still be found.
+- It skips PR lookup when the current branch matches that repo's default branch.
+- It first searches for PRs by likely source owner plus exact head branch.
+- If that fails, it falls back to broader GitHub search for the branch name.
+- `403` and `404` during repo lookups are treated as expected gaps, not hard errors.
+
+## Shared client state model
+
+- Client key is effectively `directory::branch`.
+- One entry stores last known status, loading state, error, timestamps, watcher count, identity, and resolved remote.
+- Requests are deduplicated by branch signature, not by component instance.
+- This keeps sidebar and Git view aligned and avoids duplicated fetches.
+
+## Persistence
+
+- PR state is persisted in local storage under `openchamber.github-pr-status`.
+- Persisted fields include status, timestamps, identity, and resolved remote.
+- Runtime-only details are not persisted.
+- Persisted entries expire after 12 hours.
+- On reload, users get last known state first, then background refresh resumes.
+
+## Polling and refresh model
+
+- There are two layers: entry-level polling in `useGitHubPrStatusStore` and repo scanning in `useGitHubPrBackgroundTracking`.
+- Entry-level polling decides when a known branch should revalidate PR state.
+- Background tracking decides which directories and branches should even be watched.
+
+## Entry-level polling rules
+
+- Start watching -> immediate refresh.
+- If no PR is found yet -> retry after `2s` and `5s`.
+- Still no PR -> discovery refresh every `5m`.
+- Open PR with pending checks -> refresh about every `1m`.
+- Open PR with non-pending checks -> refresh about every `5m`.
+- Open PR without a stable checks signal -> refresh about every `2m`.
+- Closed or merged PR -> stop regular polling.
+- Hidden tab -> skip polling.
+- Non-forced refreshes use a `90s` TTL.
+
+## Background tracking rules
+
+- Track up to `50` likely directories.
+- Sources are current directory, projects, worktrees, active sessions, and archived sessions.
+- Active directory branch TTL is `15s`.
+- Background directory branch TTL is `2m`.
+- Background scan wakes every `15s`, but only fetches directories whose TTL expired.
+- Each scan reads `branch`, `tracking`, `ahead`, and `behind` from git status.
+- If any of those branch signals change, that branch's PR status refreshes immediately.
+- After that, one more delayed refresh runs after `5s` to catch GitHub eventual consistency.
+
+## UI refresh triggers
+
+- App or tab becomes visible.
+- Window regains focus.
+- Current branch changes.
+- Tracking branch changes.
+- Ahead or behind changes.
+- User selects a different remote in Git view.
+- GitHub auth state changes.
+
+## Action-based refreshes in Git view
+
+- After `Create PR` -> refresh now, then after `2s` and `5s`.
+- After `Merge PR` -> refresh now, then after `2s` and `5s`.
+- After `Mark ready for review` -> refresh now, then after `2s` and `5s`.
+- After `Update PR` -> refresh now, then after `2s` and `5s`.
+
+## Sidebar behavior
+
+- Sidebar shows only compact PR state.
+- Aggregation is by `directory::branch`, so multiple sessions on one branch share one signal.
+- If multiple entries exist, sidebar keeps the strongest visible PR state.
+- Visual state is based on PR health, not merge permissions.
+
+## Git view behavior
+
+- Git view watches one branch directly.
+- It supports create, edit, mark ready, and merge.
+- It can probe alternate remotes so fork-heavy setups still find the right PR.
+- It uses the same shared store as the sidebar.
+
+## Failure handling
+
+- If GitHub is disconnected, API returns `connected: false`.
+- If a repo is private or inaccessible, resolver calls may quietly return no PR.
+- Sidebar stays quiet on missing or inaccessible PR state.
+- Git view is where explicit PR-level problems should be shown.
+
+## Notes for contributors
+
+- Keep the UI calm. Do not add noisy diagnostics to the sidebar.
+- Prefer shared state over per-component fetches.
+- Prefer event-shaped refreshes over blind frequent polling.
+- Prefer correctness for fork and multi-remote setups over assuming `origin` is enough.
+- Device flow handles GitHub `authorization_pending` at caller level.
+- Repo parser supports `git@github.com:`, `ssh://git@github.com/`, and `https://github.com/`.

package/server/lib/github/auth.js

@@ -0,0 +1,307 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const ARCHCODER_DATA_DIR = process.env.ARCHCODER_DATA_DIR
+  ? path.resolve(process.env.ARCHCODER_DATA_DIR)
+  : path.join(os.homedir(), '.config', 'archcoder');
+
+const STORAGE_DIR = ARCHCODER_DATA_DIR;
+const STORAGE_FILE = path.join(STORAGE_DIR, 'github-auth.json');
+const SETTINGS_FILE = path.join(ARCHCODER_DATA_DIR, 'settings.json');
+
+const DEFAULT_GITHUB_CLIENT_ID = 'Ov23lizomPOC3eFYo56r';
+const DEFAULT_GITHUB_SCOPES = 'repo read:org workflow read:user user:email';
+
+function ensureStorageDir() {
+  if (!fs.existsSync(STORAGE_DIR)) {
+    fs.mkdirSync(STORAGE_DIR, { recursive: true });
+  }
+}
+
+function readJsonFile() {
+  ensureStorageDir();
+  if (!fs.existsSync(STORAGE_FILE)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(STORAGE_FILE, 'utf8');
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      return null;
+    }
+    const parsed = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    console.error('Failed to read GitHub auth file:', error);
+    return null;
+  }
+}
+
+function writeJsonFile(payload) {
+  ensureStorageDir();
+
+  // Atomic write so multiple ArchCoder instances can safely share the same file.
+  const tmpFile = `${STORAGE_FILE}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpFile, JSON.stringify(payload, null, 2), 'utf8');
+  try {
+    fs.chmodSync(tmpFile, 0o600);
+  } catch {
+    // best-effort
+  }
+
+  fs.renameSync(tmpFile, STORAGE_FILE);
+  try {
+    fs.chmodSync(STORAGE_FILE, 0o600);
+  } catch {
+    // best-effort
+  }
+}
+
+function resolveAccountId({ user, accessToken, accountId }) {
+  if (typeof accountId === 'string' && accountId.trim()) {
+    return accountId.trim();
+  }
+  if (user && typeof user.login === 'string' && user.login.trim()) {
+    return user.login.trim();
+  }
+  if (user && typeof user.id === 'number') {
+    return String(user.id);
+  }
+  if (typeof accessToken === 'string' && accessToken.trim()) {
+    return `token:${accessToken.slice(0, 8)}`;
+  }
+  return '';
+}
+
+function normalizeAuthEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const accessToken = typeof entry.accessToken === 'string' ? entry.accessToken : '';
+  if (!accessToken) return null;
+  const user = entry.user && typeof entry.user === 'object'
+    ? {
+      login: typeof entry.user.login === 'string' ? entry.user.login : null,
+      avatarUrl: typeof entry.user.avatarUrl === 'string' ? entry.user.avatarUrl : null,
+      id: typeof entry.user.id === 'number' ? entry.user.id : null,
+      name: typeof entry.user.name === 'string' ? entry.user.name : null,
+      email: typeof entry.user.email === 'string' ? entry.user.email : null,
+    }
+    : null;
+
+  const accountId = resolveAccountId({
+    user,
+    accessToken,
+    accountId: typeof entry.accountId === 'string' ? entry.accountId : '',
+  });
+
+  return {
+    accessToken,
+    scope: typeof entry.scope === 'string' ? entry.scope : '',
+    tokenType: typeof entry.tokenType === 'string' ? entry.tokenType : 'bearer',
+    createdAt: typeof entry.createdAt === 'number' ? entry.createdAt : null,
+    user,
+    current: Boolean(entry.current),
+    accountId,
+  };
+}
+
+function normalizeAuthList(raw) {
+  const list = (Array.isArray(raw) ? raw : [raw])
+    .map((entry) => normalizeAuthEntry(entry))
+    .filter(Boolean);
+
+  if (!list.length) {
+    return { list: [], changed: false };
+  }
+
+  let changed = false;
+  let currentFound = false;
+  list.forEach((entry) => {
+    if (entry.current && !currentFound) {
+      currentFound = true;
+    } else if (entry.current && currentFound) {
+      entry.current = false;
+      changed = true;
+    }
+  });
+
+  if (!currentFound && list[0]) {
+    list[0].current = true;
+    changed = true;
+  }
+
+  list.forEach((entry) => {
+    if (!entry.accountId) {
+      entry.accountId = resolveAccountId(entry);
+      changed = true;
+    }
+  });
+
+  return { list, changed };
+}
+
+function readAuthList() {
+  const data = readJsonFile();
+  if (!data) {
+    return [];
+  }
+  const { list, changed } = normalizeAuthList(data);
+  if (changed) {
+    writeJsonFile(list);
+  }
+  return list;
+}
+
+function writeAuthList(list) {
+  writeJsonFile(list);
+}
+
+export function getGitHubAuth() {
+  const list = readAuthList();
+  if (!list.length) {
+    return null;
+  }
+  const current = list.find((entry) => entry.current) || list[0];
+  if (!current?.accessToken) {
+    return null;
+  }
+  return current;
+}
+
+export function getGitHubAuthAccounts() {
+  const list = readAuthList();
+  return list
+    .filter((entry) => entry?.user && entry.accountId)
+    .map((entry) => ({
+      id: entry.accountId,
+      user: entry.user,
+      scope: entry.scope || '',
+      current: Boolean(entry.current),
+    }));
+}
+
+export function setGitHubAuth({ accessToken, scope, tokenType, user, accountId }) {
+  if (!accessToken || typeof accessToken !== 'string') {
+    throw new Error('accessToken is required');
+  }
+  const normalizedUser = user && typeof user === 'object'
+    ? {
+      login: typeof user.login === 'string' ? user.login : undefined,
+      avatarUrl: typeof user.avatarUrl === 'string' ? user.avatarUrl : undefined,
+      id: typeof user.id === 'number' ? user.id : undefined,
+      name: typeof user.name === 'string' ? user.name : undefined,
+      email: typeof user.email === 'string' ? user.email : undefined,
+    }
+    : undefined;
+
+  const resolvedAccountId = resolveAccountId({
+    user: normalizedUser,
+    accessToken,
+    accountId,
+  });
+
+  const list = readAuthList();
+  const existingIndex = list.findIndex((entry) => entry.accountId === resolvedAccountId);
+  const nextEntry = {
+    accessToken,
+    scope: typeof scope === 'string' ? scope : '',
+    tokenType: typeof tokenType === 'string' ? tokenType : 'bearer',
+    createdAt: Date.now(),
+    user: normalizedUser || null,
+    current: true,
+    accountId: resolvedAccountId,
+  };
+
+  if (existingIndex >= 0) {
+    list[existingIndex] = nextEntry;
+  } else {
+    list.push(nextEntry);
+  }
+
+  list.forEach((entry, index) => {
+    entry.current = index === (existingIndex >= 0 ? existingIndex : list.length - 1);
+  });
+  writeAuthList(list);
+  return nextEntry;
+}
+
+export function activateGitHubAuth(accountId) {
+  if (typeof accountId !== 'string' || !accountId.trim()) {
+    return false;
+  }
+  const list = readAuthList();
+  const index = list.findIndex((entry) => entry.accountId === accountId.trim());
+  if (index === -1) {
+    return false;
+  }
+  list.forEach((entry, idx) => {
+    entry.current = idx === index;
+  });
+  writeAuthList(list);
+  return true;
+}
+
+export function clearGitHubAuth() {
+  try {
+    const list = readAuthList();
+    if (!list.length) {
+      return true;
+    }
+    const remaining = list.filter((entry) => !entry.current);
+    if (!remaining.length) {
+      if (fs.existsSync(STORAGE_FILE)) {
+        fs.unlinkSync(STORAGE_FILE);
+      }
+      return true;
+    }
+    remaining.forEach((entry, index) => {
+      entry.current = index === 0;
+    });
+    writeAuthList(remaining);
+    return true;
+  } catch (error) {
+    console.error('Failed to clear GitHub auth file:', error);
+    return false;
+  }
+}
+
+export function getGitHubClientId() {
+  const raw = process.env.OPENCHAMBER_GITHUB_CLIENT_ID;
+  const clientId = typeof raw === 'string' ? raw.trim() : '';
+  if (clientId) return clientId;
+
+  try {
+    if (fs.existsSync(SETTINGS_FILE)) {
+      const parsed = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+      const stored = typeof parsed?.githubClientId === 'string' ? parsed.githubClientId.trim() : '';
+      if (stored) return stored;
+    }
+  } catch {
+    // ignore
+  }
+
+  return DEFAULT_GITHUB_CLIENT_ID;
+}
+
+export function getGitHubScopes() {
+  const raw = process.env.OPENCHAMBER_GITHUB_SCOPES;
+  const fromEnv = typeof raw === 'string' ? raw.trim() : '';
+  if (fromEnv) return fromEnv;
+
+  try {
+    if (fs.existsSync(SETTINGS_FILE)) {
+      const parsed = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+      const stored = typeof parsed?.githubScopes === 'string' ? parsed.githubScopes.trim() : '';
+      if (stored) return stored;
+    }
+  } catch {
+    // ignore
+  }
+
+  return DEFAULT_GITHUB_SCOPES;
+}
+
+export const GITHUB_AUTH_FILE = STORAGE_FILE;

package/server/lib/github/device-flow.js

@@ -0,0 +1,50 @@
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+const encodeForm = (params) => {
+  const body = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value == null) continue;
+    body.set(key, String(value));
+  }
+  return body.toString();
+};
+
+async function postForm(url, params) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: encodeForm(params),
+  });
+
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    const message = payload?.error_description || payload?.error || response.statusText;
+    const error = new Error(message || 'GitHub request failed');
+    error.status = response.status;
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+export async function startDeviceFlow({ clientId, scope }) {
+  return postForm(DEVICE_CODE_URL, {
+    client_id: clientId,
+    scope,
+  });
+}
+
+export async function exchangeDeviceCode({ clientId, deviceCode }) {
+  // GitHub returns 200 with {error: 'authorization_pending'|...} for non-success states.
+  const payload = await postForm(ACCESS_TOKEN_URL, {
+    client_id: clientId,
+    device_code: deviceCode,
+    grant_type: DEVICE_GRANT_TYPE,
+  });
+  return payload;
+}

package/server/lib/github/index.js

@@ -0,0 +1,24 @@
+export {
+  getGitHubAuth,
+  getGitHubAuthAccounts,
+  setGitHubAuth,
+  activateGitHubAuth,
+  clearGitHubAuth,
+  getGitHubClientId,
+  getGitHubScopes,
+  GITHUB_AUTH_FILE,
+} from './auth.js';
+
+export {
+  startDeviceFlow,
+  exchangeDeviceCode,
+} from './device-flow.js';
+
+export {
+  getOctokitOrNull,
+} from './octokit.js';
+
+export {
+  parseGitHubRemoteUrl,
+  resolveGitHubRepoFromDirectory,
+} from './repo/index.js';

package/server/lib/github/octokit.js

@@ -0,0 +1,10 @@
+import { Octokit } from '@octokit/rest';
+import { getGitHubAuth } from './auth.js';
+
+export function getOctokitOrNull() {
+  const auth = getGitHubAuth();
+  if (!auth?.accessToken) {
+    return null;
+  }
+  return new Octokit({ auth: auth.accessToken });
+}