@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/usage/vendor-balance.server.ts

@@ -0,0 +1,284 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Provider-reported BALANCE endpoints, for vendors that expose one to a plain
+ * API key.
+ *
+ * This is a deliberately narrow complement to `omp usage --json`, not a
+ * replacement: omp ships ~20 usage adapters, but they cover subscription plans
+ * (rolling 5h/7d windows). Pay-as-you-go vendors are not among them, and a
+ * credit balance is the only "quota" they have — so those are fetched here.
+ *
+ * Every endpoint below was verified to exist and to accept an ordinary API key
+ * (a bogus key returns 401, not 404). Anthropic and OpenAI are NOT here on
+ * purpose: their usage/cost reports require an org ADMIN key
+ * (`sk-ant-admin01-…`) that a normal workspace key cannot substitute, so the
+ * Kabmo cannot read them with the credential the user actually configured.
+ *
+ * Results are shaped as `UsageLimitWindow[]` so the existing quota renderer
+ * draws them — a balance is just a window whose unit is USD.
+ */
+
+import { readOmpProviderApiKey } from '@/server/lib/omp/core/auth-credentials';
+import { loadProviderEntries } from '@/server/lib/usage/provider-key';
+import { isRecord } from '@/shared/lib/util/guards';
+import type { UsageLimitWindow, UsageWindowStatus } from '@/shared/types';
+
+const FETCH_TIMEOUT_MS = 10_000;
+const MASKED_KEY_PATTERN = /•{3,}/;
+
+/** A vendor balance adapter: where to ask, and how to read the answer. */
+interface BalanceAdapter {
+  /** Provider slug as omp spells it. */
+  slug: string;
+  /** Env var omp reads for this provider, used when no stored key exists. */
+  envKey: string;
+  url: string;
+  /** Map the parsed JSON body into quota windows. Throws on an unusable body. */
+  parse: (payload: unknown) => UsageLimitWindow[];
+}
+
+function num(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+/** Status for a credit window: exhausted at zero remaining, else ok. */
+function balanceStatus(remaining: number | undefined): UsageWindowStatus {
+  if (remaining === undefined) return 'unknown';
+  return remaining <= 0 ? 'exhausted' : 'ok';
+}
+
+/** One USD window from a balance; `limit` is omitted when the vendor has none. */
+function usdWindow(input: {
+  id: string;
+  label: string;
+  used?: number;
+  limit?: number;
+  remaining?: number;
+  note?: string;
+}): UsageLimitWindow {
+  const usedFraction = input.limit && input.limit > 0 && input.used !== undefined
+    ? input.used / input.limit
+    : undefined;
+  return {
+    id: input.id,
+    label: input.label,
+    unit: 'usd',
+    status: balanceStatus(input.remaining),
+    ...(input.used !== undefined ? { used: input.used } : {}),
+    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+    ...(input.remaining !== undefined ? { remaining: input.remaining } : {}),
+    ...(usedFraction !== undefined ? { usedFraction } : {}),
+    ...(input.note ? { notes: [input.note] } : {}),
+  };
+}
+
+/** Pull `data` (or the root) out of a vendor envelope. */
+function envelope(payload: unknown): Record<string, unknown> {
+  if (!isRecord(payload)) throw new Error('unexpected balance response');
+  return isRecord(payload.data) ? payload.data : payload;
+}
+
+const ADAPTERS: readonly BalanceAdapter[] = [
+  {
+    // Documented at openrouter.ai/docs — GET /api/v1/key returns the CURRENT
+    // key's own limit/usage, so no management key is needed (unlike /credits).
+    slug: 'openrouter',
+    envKey: 'OPENROUTER_API_KEY',
+    url: 'https://openrouter.ai/api/v1/key',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const limit = num(data.limit);
+      const usage = num(data.usage);
+      const remaining = num(data.limit_remaining);
+      const reset = typeof data.limit_reset === 'string' ? data.limit_reset : undefined;
+      const windows = [
+        usdWindow({
+          id: 'openrouter:credits',
+          label: 'Key credits',
+          used: usage,
+          limit,
+          remaining,
+          note: limit === undefined ? 'No credit limit is set on this key.' : undefined,
+        }),
+      ];
+      const daily = num(data.usage_daily);
+      if (daily !== undefined) {
+        windows.push(usdWindow({ id: 'openrouter:daily', label: `Spent today${reset ? ` (${reset})` : ''}`, used: daily }));
+      }
+      return windows;
+    },
+  },
+  {
+    // Moonshot / Kimi Open Platform: GET /v1/users/me/balance with a Bearer key.
+    slug: 'moonshot',
+    envKey: 'MOONSHOT_API_KEY',
+    url: 'https://api.moonshot.ai/v1/users/me/balance',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const available = num(data.available_balance);
+      const voucher = num(data.voucher_balance);
+      const cash = num(data.cash_balance);
+      const windows = [
+        usdWindow({ id: 'moonshot:available', label: 'Available balance', remaining: available }),
+      ];
+      if (voucher !== undefined) {
+        windows.push(usdWindow({ id: 'moonshot:voucher', label: 'Voucher balance', remaining: voucher }));
+      }
+      if (cash !== undefined) {
+        windows.push(usdWindow({ id: 'moonshot:cash', label: 'Cash balance', remaining: cash }));
+      }
+      return windows;
+    },
+  },
+  {
+    // SiliconFlow: GET /v1/user/info → data.balance / chargeBalance / totalBalance.
+    slug: 'siliconflow',
+    envKey: 'SILICONFLOW_API_KEY',
+    url: 'https://api.siliconflow.com/v1/user/info',
+    parse: (payload) => {
+      const data = envelope(payload);
+      const total = num(data.totalBalance);
+      const charge = num(data.chargeBalance);
+      const windows = [
+        usdWindow({ id: 'siliconflow:total', label: 'Total balance', remaining: total }),
+      ];
+      if (charge !== undefined) {
+        windows.push(usdWindow({ id: 'siliconflow:charge', label: 'Topped-up balance', remaining: charge }));
+      }
+      return windows;
+    },
+  },
+  {
+    // Novita: GET /openapi/v1/billing/balance/detail. Amounts are in 1/10000 USD.
+    slug: 'novita',
+    envKey: 'NOVITA_API_KEY',
+    url: 'https://api.novita.ai/openapi/v1/billing/balance/detail',
+    parse: (payload) => {
+      if (!isRecord(payload)) throw new Error('unexpected balance response');
+      const scale = 1 / 10_000;
+      const available = num(payload.availableBalance);
+      const cash = num(payload.cashBalance);
+      const creditLimit = num(payload.creditLimit);
+      const windows = [
+        usdWindow({
+          id: 'novita:available',
+          label: 'Available balance',
+          remaining: available !== undefined ? available * scale : undefined,
+          limit: creditLimit !== undefined ? creditLimit * scale : undefined,
+        }),
+      ];
+      if (cash !== undefined) {
+        windows.push(usdWindow({ id: 'novita:cash', label: 'Topped-up balance', remaining: cash * scale }));
+      }
+      return windows;
+    },
+  },
+  {
+    // DeepInfra: GET /payment/key-limits → one entry per API key with the
+    // monthly spending limit and what that key has spent this month.
+    slug: 'deepinfra',
+    envKey: 'DEEPINFRA_TOKEN',
+    url: 'https://api.deepinfra.com/payment/key-limits',
+    parse: (payload) => {
+      if (!Array.isArray(payload)) throw new Error('unexpected balance response');
+      const windows: UsageLimitWindow[] = [];
+      for (const entry of payload) {
+        if (!isRecord(entry)) continue;
+        const name = typeof entry.name === 'string' && entry.name ? entry.name : 'API key';
+        const limit = num(entry.limit);
+        const spend = num(entry.spend);
+        windows.push(usdWindow({
+          id: `deepinfra:${typeof entry.token_id === 'string' ? entry.token_id : name}`,
+          label: `${name} · monthly`,
+          used: spend,
+          limit,
+          remaining: limit !== undefined && spend !== undefined ? Math.max(0, limit - spend) : undefined,
+          note: limit === undefined ? 'No monthly limit is set on this key.' : undefined,
+        }));
+      }
+      return windows;
+    },
+  },
+];
+
+/** Balance adapters keyed by slug, for callers that need the table. */
+export const BALANCE_ADAPTER_SLUGS: readonly string[] = ADAPTERS.map((adapter) => adapter.slug);
+
+function adapterFor(slug: string): BalanceAdapter | undefined {
+  return ADAPTERS.find((adapter) => adapter.slug === slug);
+}
+
+/**
+ * Map a vendor's balance payload into quota windows, or null when the slug has
+ * no adapter. Exported so the field mapping (the part that breaks when a vendor
+ * changes its schema) is unit-testable without a network call.
+ */
+export function parseVendorBalance(slug: string, payload: unknown): UsageLimitWindow[] | null {
+  const adapter = adapterFor(slug);
+  if (!adapter) return null;
+  return adapter.parse(payload);
+}
+
+/**
+ * The provider's key: Kabmo overlay first, then omp's own stores, then
+ * the environment variable omp itself reads. The env fallback matters because a
+ * key can live only in the user's shell (omp picks it up there), which no store
+ * on disk would reveal.
+ */
+async function resolveVendorKey(adapter: BalanceAdapter): Promise<string | null> {
+  for (const entry of await loadProviderEntries()) {
+    const slug = (entry.slug || entry.name).trim().toLowerCase();
+    const key = entry.apiKey.trim();
+    if (slug === adapter.slug && key && !MASKED_KEY_PATTERN.test(key)) return key;
+  }
+  const stored = await readOmpProviderApiKey(adapter.slug);
+  if (stored) return stored;
+  const fromEnv = Bun.env[adapter.envKey];
+  return fromEnv && fromEnv.trim() ? fromEnv.trim() : null;
+}
+
+export interface VendorBalance {
+  limits: UsageLimitWindow[];
+  error?: string;
+}
+
+/**
+ * Fetch a vendor balance. Returns null when the provider has no balance
+ * adapter, or when no credential could be resolved (a provider omp reports
+ * through an env var Kabmo was not launched with is a silent miss, not an
+ * error — the caller already knows the credential exists somewhere).
+ */
+export async function fetchVendorBalance(slug: string): Promise<VendorBalance | null> {
+  const adapter = adapterFor(slug);
+  if (!adapter) return null;
+  const apiKey = await resolveVendorKey(adapter);
+  if (!apiKey) return null;
+  try {
+    const response = await fetch(adapter.url, {
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (response.status === 401 || response.status === 403) {
+      return { limits: [], error: `${adapter.slug} rejected the API key (HTTP ${response.status}).` };
+    }
+    if (response.status < 200 || response.status >= 300) {
+      return { limits: [], error: `${adapter.slug} balance request failed (HTTP ${response.status}).` };
+    }
+    const limits = adapter.parse(await response.json());
+    return { limits };
+  } catch (error) {
+    return {
+      limits: [],
+      error: error instanceof Error ? error.message : `${adapter.slug} balance request failed`,
+    };
+  }
+}

package/src/server/lib/wiki/git.test.ts

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The wiki read path is a git spawn plus a cache, and both fail silently when
+ * they are wrong: a wiki path with a space that reaches a shell as a string is
+ * mangled, a credential prompt with no terminal to answer it hangs the read to
+ * its timeout, and a mirror keyed by the remote URL rather than by host+slug
+ * would fetch the same wiki twice under its https and ssh spellings. These
+ * tests pin the argv/env shape of `gitRun` and the four ways a fetch is
+ * classified; the reads that come back out of the mirror are `mirror-reads`.
+ *
+ * No network: `git` is replaced by a compiled stub on PATH (`@/test-support/
+ * fake-git`), which starts on Windows too.
+ */
+
+import { afterAll, afterEach, describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { firstLine, gitRun } from '@/server/lib/wiki/git';
+import { detectWikiProvider } from '@/server/lib/wiki/provider.server';
+import { testPosix } from '@/test-support/platform';
+import {
+  cleanupFakeGit,
+  FAKE_GIT_ENV_KEYS,
+  fakeGitTempDir,
+  gitCalls,
+  realPath,
+  useFakeGit,
+} from '@/test-support/fake-git';
+import { ensureWikiMirror } from '@/server/lib/wiki/mirror.server';
+
+/** Point the mirror cache at a throwaway data directory. */
+function useWikiDataDir(): void {
+  process.env.KABMO_DATA_DIR = fakeGitTempDir('omp-wiki-data-');
+}
+
+afterEach(() => {
+  process.env.PATH = realPath;
+  globalThis.__kabmoWikiCache = undefined;
+  globalThis.__kabmoWikiProviders = undefined;
+  for (const key of FAKE_GIT_ENV_KEYS) delete process.env[key];
+});
+
+afterAll(() => {
+  delete process.env.KABMO_DATA_DIR;
+  cleanupFakeGit();
+});
+
+describe('gitRun', () => {
+  test('passes every argument as argv, so no shell can rewrite a path', async () => {
+    await useFakeGit();
+
+    const result = await gitRun(['log', 'Setting up notes.md', 'a b"c$d'], { timeoutMs: 5_000 });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.split('\n').filter(Boolean)).toEqual(['log', 'Setting up notes.md', 'a b"c$d', 'ENV=0']);
+  });
+
+  test('sets GIT_TERMINAL_PROMPT=0 so a private wiki cannot block on a prompt', async () => {
+    await useFakeGit();
+
+    const result = await gitRun(['fetch', 'origin'], { timeoutMs: 5_000 });
+
+    expect(result.stdout).toContain('ENV=0');
+  });
+
+  test('reports a real git version with a zero exit code', async () => {
+    const result = await gitRun(['--version'], { timeoutMs: 5_000 });
+
+    expect(result.failed).toBe(false);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.startsWith('git version')).toBe(true);
+  });
+
+  test('reports a process that could not start as failed with no exit code', async () => {
+    const result = await gitRun(['--version'], { cwd: join(tmpdir(), 'omp-missing-cwd-xyz'), timeoutMs: 5_000 });
+
+    expect(result.failed).toBe(true);
+    expect(result.exitCode).toBe(null);
+    expect(result.stderr.length).toBeGreaterThan(0);
+  });
+
+  // POSIX-only: the case asserts that a CHILD killed by a signal is reported as
+  // failed, and Windows has no signals — `TerminateProcess` reports an ordinary
+  // exit code with `signalCode` null. The portable half of the same rule (our own
+  // timeout kill) is the case below, which is detected by a flag rather than by
+  // `signalCode` for exactly this reason.
+  testPosix('reports a signalled process as failed', async () => {
+    await useFakeGit();
+    process.env.FAKE_GIT_SIGNAL = 'TERM';
+
+    const result = await gitRun(['log'], { timeoutMs: 5_000 });
+
+    expect(result.failed).toBe(true);
+  });
+
+  // Portable, and the half that Windows needs: the budget is enforced by a kill
+  // WE perform, so the failure is a flag we set rather than a `signalCode` only
+  // POSIX reports. Without it a timed-out `git` on Windows reads as a success
+  // and the wiki fetch is cached as an empty mirror.
+  test('reports a process that outlived its budget as failed on every platform', async () => {
+    await useFakeGit();
+    process.env.FAKE_GIT_SLEEP = '5000';
+
+    const started = Date.now();
+    const result = await gitRun(['log'], { timeoutMs: 200 });
+
+    expect(result.failed).toBe(true);
+    expect(Date.now() - started).toBeLessThan(4_000);
+  });
+});
+
+describe('firstLine', () => {
+  test('keeps only the first trimmed line of git output', () => {
+    expect(firstLine('  fatal: nope  \nsecond line\n')).toBe('fatal: nope');
+    expect(firstLine('only')).toBe('only');
+    expect(firstLine('')).toBe('');
+    expect(firstLine('\n\n')).toBe('');
+  });
+});
+
+// Portable: `byName` answers the two public hosts without a request, and the
+// probe for an unknown host is a `fetch`, not a `git` spawn — so nothing here
+// reaches the compiled stub the rest of this file needs.
+describe('detectWikiProvider', () => {
+  test('decides the two public hosts by name, with no request', async () => {
+    for (const host of ['github.com', 'GitHub.com', 'www.github.com']) {
+      expect(await detectWikiProvider(host)).toBe('github');
+    }
+    for (const host of ['gitlab.com', 'sub.gitlab.com', 'gitlab.example.com', 'my-gitlab-host.io']) {
+      expect(await detectWikiProvider(host)).toBe('gitlab');
+    }
+  });
+
+  test('uses a cached verdict for an unknown host instead of probing again', async () => {
+    globalThis.__kabmoWikiProviders = {
+      hosts: new Map([['probe.example.test', { provider: 'gitlab', at: Date.now() }]]),
+    };
+
+    expect(await detectWikiProvider('probe.example.test')).toBe('gitlab');
+  });
+});
+
+describe('ensureWikiMirror', () => {
+  test('fetches into a bare mirror keyed by host and slug', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+
+    const result = await ensureWikiMirror('github.com', 'o/n', 'https://github.com/o/n.wiki.git');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.mirror).toEqual({
+      repoDir: join(process.env.KABMO_DATA_DIR as string, 'wiki', 'github.com__o__n'),
+      revision: 'abc123',
+      updatedAt: '2026-01-02T03:04:05Z',
+    });
+    expect(gitCalls().filter((args) => args[2] === 'fetch')).toEqual([
+      [
+        '--git-dir',
+        result.mirror.repoDir,
+        'fetch',
+        '--no-write-fetch-head',
+        '--depth',
+        '1',
+        '--force',
+        '--quiet',
+        'https://github.com/o/n.wiki.git',
+        'HEAD:refs/wiki/latest',
+      ],
+    ]);
+  });
+
+  test('shares one mirror between the https and ssh spellings of a remote', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+
+    const first = await ensureWikiMirror('gitlab.com', 'g/p', 'https://gitlab.com/g/p.wiki.git');
+    const second = await ensureWikiMirror('gitlab.com', 'g/p', 'git@gitlab.com:g/p.wiki.git');
+    expect(first.ok && second.ok).toBe(true);
+    expect(gitCalls().filter((args) => args[2] === 'fetch')).toHaveLength(1);
+
+    const forced = await ensureWikiMirror('gitlab.com', 'g/p', 'git@gitlab.com:g/p.wiki.git', true);
+    expect(forced.ok).toBe(true);
+    const fetches = gitCalls().filter((args) => args[2] === 'fetch');
+    expect(fetches).toHaveLength(2);
+    expect(fetches[1]?.[8]).toBe('git@gitlab.com:g/p.wiki.git');
+  });
+
+  test('classifies a missing repository as no-wiki', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+    process.env.FAKE_GIT_FETCH_FAIL =
+      "remote: Repository not found.\nfatal: repository 'https://github.com/o/n.wiki.git/' not found";
+
+    const result = await ensureWikiMirror('missing.test', 'o/n', 'https://missing.test/o/n.wiki.git');
+
+    expect(result).toEqual({ ok: false, reason: 'no-wiki', detail: 'remote: Repository not found.' });
+  });
+
+  test('classifies a transport failure as unreachable', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+    process.env.FAKE_GIT_FETCH_FAIL = "fatal: unable to access 'https://x/': Could not resolve host: x";
+
+    const result = await ensureWikiMirror('other.test', 'o/n', 'https://other.test/o/n.wiki.git');
+
+    expect(result).toEqual({
+      ok: false,
+      reason: 'unreachable',
+      detail: "fatal: unable to access 'https://x/': Could not resolve host: x",
+    });
+  });
+
+  // POSIX-only for the same reason as `reports a signalled process as failed`:
+  // the stub kills ITSELF with SIGTERM, which Windows cannot express.
+  testPosix('classifies a killed fetch as unreachable with a timeout detail', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+    process.env.FAKE_GIT_FETCH_KILL = '1';
+
+    const result = await ensureWikiMirror('slow.test', 'o/n', 'https://slow.test/o/n.wiki.git');
+
+    expect(result).toEqual({ ok: false, reason: 'unreachable', detail: 'The wiki fetch timed out' });
+  });
+
+  test('reports an empty wiki when the fetched ref holds no revision', async () => {
+    await useFakeGit();
+    useWikiDataDir();
+    process.env.FAKE_GIT_LOG_FAIL = '1';
+
+    const result = await ensureWikiMirror('empty.test', 'o/n', 'https://empty.test/o/n.wiki.git');
+
+    expect(result).toEqual({ ok: false, reason: 'no-wiki', detail: 'The wiki repository holds no pages' });
+  });
+});

package/src/server/lib/wiki/git.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one `git` spawn the wiki reader uses.
+ *
+ * **argv, never a shell string.** A wiki path is author-chosen and does hold
+ * spaces (`Setting-up-a-OneDrive-project-to-use-with-diagrams.net.md`); a
+ * checkout path is user-chosen and may hold a quote or a `$`. Passing them as
+ * argv elements means there is no shell to escape them against, which is why
+ * this does not go through `runShell`.
+ *
+ * `GIT_TERMINAL_PROMPT=0` is set on every call: without it a private wiki blocks
+ * on a credential prompt with no terminal to answer it, and the read hangs to
+ * its timeout instead of reporting that the wiki is not readable.
+ */
+
+export interface GitRun {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  /** True when the process was killed (timeout) or could not be started. */
+  failed: boolean;
+}
+
+export interface GitRunOptions {
+  cwd?: string;
+  timeoutMs: number;
+}
+
+export async function gitRun(args: string[], { cwd, timeoutMs }: GitRunOptions): Promise<GitRun> {
+  let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>;
+  try {
+    proc = Bun.spawn({
+      cmd: ['git', ...args],
+      cwd,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: { ...Bun.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+  } catch (error) {
+    // `git` is not on PATH. A wiki read is a convenience, so this reports an
+    // unreachable wiki rather than throwing through the route.
+    return { stdout: '', stderr: error instanceof Error ? error.message : String(error), exitCode: null, failed: true };
+  }
+
+  // The timeout is OURS, not `Bun.spawn`'s `timeout` option, because the kill it
+  // performs is only observable through `signalCode` on POSIX. Windows has no
+  // signals: a `TerminateProcess` there reports an ordinary exit code, so
+  // `signalCode` stays null and a timed-out `git` would read as a success — the
+  // wiki fetch would be classified `unreachable` with no timeout detail, and
+  // `ensureWikiMirror` would cache the empty mirror it never got. A flag we set
+  // ourselves is the one thing both platforms agree on.
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill('SIGTERM');
+    } catch {
+      // Already gone: the command finished inside its own budget.
+    }
+  }, timeoutMs);
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  clearTimeout(timer);
+  return { stdout, stderr, exitCode, failed: timedOut || exitCode === null || proc.signalCode != null };
+}
+
+/** One line of git's own message, for a response's `detail`. */
+export function firstLine(value: string): string {
+  return value.trim().split('\n')[0]?.trim() ?? '';
+}

package/src/server/lib/wiki/mirror-reads.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The reads that come back out of a wiki mirror: the tree, one page, one asset.
+ *
+ * Split from `git.test.ts` (which pins the spawn and the fetch classification)
+ * because both files build real state and the pair crossed the 350-line ceiling
+ * together. Nothing here reaches the fake `git` stub: the fixture is a REAL
+ * bare repository, which is the only way to prove `git show <ref>:<path>`
+ * answers the bytes the wiki holds.
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { listWikiPaths, readWikiAsset, readWikiPage } from '@/server/lib/wiki/mirror.server';
+import { cleanupFakeGit, fakeGitTempDir } from '@/test-support/fake-git';
+
+/** Real-git helper for the local fixture repository. */
+function git(cwd: string, args: string[]): void {
+  const proc = Bun.spawnSync(['git', '-C', cwd, ...args], { stdout: 'pipe', stderr: 'pipe' });
+  if (proc.exitCode !== 0) throw new Error(`git ${args.join(' ')}: ${proc.stderr.toString()}`);
+}
+
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);
+let bareRepo = '';
+
+afterAll(() => {
+  cleanupFakeGit();
+});
+
+describe('mirror reads', () => {
+  test('lists every path in the tree, keeping a space in the name', async () => {
+    await buildFixture();
+
+    expect((await listWikiPaths(bareRepo)).sort()).toEqual(['Home.md', 'Setting up notes.md', 'images/schema.png']);
+  });
+
+  test('reads a page at the ref and reports a missing one', async () => {
+    await buildFixture();
+
+    expect(await readWikiPage(bareRepo, 'Home.md')).toEqual({ ok: true, text: 'Home\n', truncated: false });
+    expect(await readWikiPage(bareRepo, 'Nope.md')).toEqual({ ok: false, error: 'Page not found: Nope.md' });
+  });
+
+  test('reads an asset as bytes and refuses a missing one', async () => {
+    await buildFixture();
+
+    expect(await readWikiAsset(bareRepo, 'images/schema.png')).toEqual(PNG_BYTES);
+    expect(await readWikiAsset(bareRepo, 'images/nope.png')).toBe(null);
+  });
+});
+
+async function buildFixture(): Promise<void> {
+  if (bareRepo) return;
+  const work = join(fakeGitTempDir('omp-wiki-work-'), 'repo');
+  mkdirSync(join(work, 'images'), { recursive: true });
+  writeFileSync(join(work, 'Home.md'), 'Home\n');
+  writeFileSync(join(work, 'Setting up notes.md'), 'notes\n');
+  writeFileSync(join(work, 'images', 'schema.png'), PNG_BYTES);
+  git(work, ['init', '-q']);
+  // Byte-exact blobs: Git for Windows defaults `core.autocrlf` to true, which
+  // rewrites a committed CRLF into LF — the fixture's PNG header (0d 0a) came
+  // back as 0a and the asset read failed for a reason the code under test has
+  // nothing to do with. A wiki mirror holds blobs authored elsewhere, so the
+  // production read path is unaffected; the fixture must simply not normalise.
+  git(work, ['config', 'core.autocrlf', 'false']);
+  git(work, ['add', '-A']);
+  git(work, ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']);
+  bareRepo = join(fakeGitTempDir('omp-wiki-bare-'), 'bare.git');
+  const clone = Bun.spawnSync(['git', 'clone', '-q', '--bare', work, bareRepo], { stdout: 'pipe', stderr: 'pipe' });
+  if (clone.exitCode !== 0) throw new Error(clone.stderr.toString());
+  git(bareRepo, ['update-ref', 'refs/wiki/latest', 'HEAD']);
+}