feat: GitHub auth and API client layer

Token resolution (GITHUB_TOKEN → GH_TOKEN → gh CLI fallback), cached
Octokit REST + GraphQL clients, asyncPool for parallel API calls,
local repo remote resolution from git origin.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AlbinoGeek

src/server/github-auth.ts

@@ -0,0 +1,60 @@
+import { execFileSync } from "node:child_process";
+
+interface AuthOk {
+  ok: true;
+  token: string;
+}
+
+interface AuthError {
+  ok: false;
+  body: Record<string, unknown>;
+}
+
+type AuthResult = AuthOk | AuthError;
+
+let cached: AuthResult | undefined;
+
+/**
+ * Resolve a GitHub personal access token.
+ *
+ * Priority: GITHUB_TOKEN env → GH_TOKEN env → `gh auth token` subprocess.
+ * Result is cached after first call.
+ */
+export function gateAuth(): AuthResult {
+  if (cached) return cached;
+
+  const envToken = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+  if (envToken) {
+    cached = { ok: true, token: envToken };
+    return cached;
+  }
+
+  // Fallback: try `gh auth token`
+  try {
+    const token = execFileSync("gh", ["auth", "token"], {
+      encoding: "utf8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (token) {
+      cached = { ok: true, token };
+      return cached;
+    }
+  } catch {
+    // gh not installed or not authenticated — fall through
+  }
+
+  cached = {
+    ok: false,
+    body: {
+      error: "github_auth_missing",
+      hint: "Set GITHUB_TOKEN or GH_TOKEN, or run `gh auth login`.",
+    },
+  };
+  return cached;
+}
+
+/** Clear the cached auth result (useful for testing). */
+export function resetAuthCache(): void {
+  cached = undefined;
+}

src/server/github-client.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from "node:child_process";
+import { graphql as octokitGraphql } from "@octokit/graphql";
+import { Octokit } from "@octokit/rest";
+
+import { gateAuth } from "./github-auth.js";
+
+let cachedOctokit: Octokit | undefined;
+let cachedGraphql: typeof octokitGraphql | undefined;
+
+function baseUrl(): string {
+  return process.env.GITHUB_API_URL || "https://api.github.com";
+}
+
+/** Get the shared Octokit REST client. Throws if auth is not available. */
+export function getOctokit(): Octokit {
+  if (cachedOctokit) return cachedOctokit;
+  const auth = gateAuth();
+  if (!auth.ok) throw new Error("GitHub auth not available");
+  cachedOctokit = new Octokit({ auth: auth.token, baseUrl: baseUrl() });
+  return cachedOctokit;
+}
+
+/** Run a typed GraphQL query against the GitHub API. */
+export async function graphqlQuery<T = Record<string, unknown>>(
+  query: string,
+  variables?: Record<string, unknown>,
+): Promise<T> {
+  if (!cachedGraphql) {
+    const auth = gateAuth();
+    if (!auth.ok) throw new Error("GitHub auth not available");
+    const graphqlUrl = process.env.GITHUB_GRAPHQL_URL;
+    cachedGraphql = octokitGraphql.defaults({
+      headers: { authorization: `token ${auth.token}` },
+      ...(graphqlUrl ? { baseUrl: graphqlUrl } : {}),
+    });
+  }
+  return (await cachedGraphql(query, variables ?? {})) as T;
+}
+
+/**
+ * Run up to `concurrency` async tasks in parallel from an iterable.
+ * Identical pattern to mcp-multi-root-git's asyncPool.
+ */
+export async function asyncPool<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  const executing = new Set<Promise<void>>();
+
+  for (const item of items) {
+    const p = fn(item).then((r) => {
+      results.push(r);
+    });
+    const wrapped = p.then(() => {
+      executing.delete(wrapped);
+    });
+    executing.add(wrapped);
+
+    if (executing.size >= concurrency) {
+      await Promise.race(executing);
+    }
+  }
+
+  await Promise.all(executing);
+  return results;
+}
+
+const GITHUB_API_PARALLELISM = 4;
+
+/** Convenience: run API calls in parallel with default concurrency. */
+export async function parallelApi<T, R>(
+  items: readonly T[],
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  return asyncPool(items, GITHUB_API_PARALLELISM, fn);
+}
+
+/**
+ * Resolve a local git clone's GitHub remote to owner/repo.
+ * Parses the `origin` remote URL.
+ */
+export function resolveLocalRepoRemote(
+  localPath: string,
+): { owner: string; repo: string } | undefined {
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd: localPath,
+      encoding: "utf8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    // SSH: git@github.com:owner/repo.git
+    const ssh = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/.exec(url);
+    if (ssh?.[1] && ssh[2]) return { owner: ssh[1], repo: ssh[2] };
+
+    // HTTPS: https://github.com/owner/repo.git
+    const https = /github\.com\/([^/]+)\/([^/.]+?)(?:\.git)?$/.exec(url);
+    if (https?.[1] && https[2]) return { owner: https[1], repo: https[2] };
+  } catch {
+    // Not a git repo or no origin
+  }
+  return undefined;
+}