ompchamber 3.1.1 → 3.3.0

package/src/server/lib/assets/fonts.server.ts

@@ -4,13 +4,14 @@
  */
 
 /**
- * Font files served straight from the installed packages.
+ * Font files served straight from the installed packages — plus the one the
+ * chamber vendors itself (`src/shared/lib/fonts`, the Nerd Font symbols face).
  *
  * The client stylesheet reaches its `@font-face` sources through the bundler's
  * CSS loader (`lib/bundler/css.ts`), which rewrites every one of them to
- * `<FONT_ROUTE_PREFIX><basename>`. Nothing copies them into the repository: a
- * font is addressed by its own basename, and this module resolves that basename
- * back to the package that ships it.
+ * `<FONT_ROUTE_PREFIX><basename>`. Nothing is copied at build time: a font is
+ * addressed by its own basename, and this module resolves that basename back to
+ * the directory that ships it.
  *
  * A directory index rather than a path built from the request, because the
  * request must never choose a directory. The index is built once, lazily, by
@@ -35,6 +36,10 @@ export const FONT_ROUTE_PREFIX = '/fonts/';
 const FONT_SOURCES = [
   'node_modules/katex/dist/fonts',
   'node_modules/@fontsource/fira-code/files',
+  // The one font the chamber vendors itself rather than borrowing from a
+  // package: the Nerd Font symbols face the terminal falls back to. See
+  // `src/shared/lib/fonts/nerd-symbols.css`.
+  'src/shared/lib/fonts',
 ] as const;
 
 /**

package/src/server/lib/bundler/build-errors.server.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Why the shell's bundle failed, in the terms the person who broke it needs.
+ *
+ * Bun renders an HTML route by bundling it. When the bundle fails, the route
+ * answers with Bun's own "Build Failed" page, which holds the file, line,
+ * message and offending source line — but only inside a JavaScript payload the
+ * page decodes at runtime (`Uint8Array.from(atob(…))`, a private binary format
+ * with no server-side reader). Scraping that would be a bet on Bun's internals.
+ *
+ * `Bun.build` is the supported way to the same facts: a probe over the same
+ * entrypoint with the same plugins returns `logs` carrying `message` and
+ * `position {file,line,column,lineText}`. What it reports is what `Bun.build`
+ * rejects, and that set covers every shape the route 500s on — measured against
+ * the route on Bun 1.4.2, an unresolved import that survives tree shaking and a
+ * syntax error both fail the route and are both reported here. It is not a
+ * subset of the route's failures, and deliberately so: a missing named export is
+ * answered `200` by the route while Bun serves a 104-byte stub that only calls
+ * `location.reload()` in place of the bundle, so the page cannot run. That is a
+ * real failure of the bundle and is reported as one.
+ *
+ * `target: 'browser'` because that is the bundle the page is served; `bun`
+ * agreed with it on every case measured.
+ *
+ * Runs only after the shell has already failed, so its cost lands on a page that
+ * is broken anyway and never on a healthy request.
+ */
+
+import { join, relative } from 'path';
+import type { BuildOutput, BunPlugin } from 'bun';
+
+import { packageRoot } from '@/server/lib/assets/fonts.server';
+
+/** The shell bundle's entrypoint, relative to the package root. */
+const SHELL_ENTRYPOINT = 'index.html';
+
+/** Bun's own config file, and the section naming the bundle's plugins. */
+const BUNFIG = 'bunfig.toml';
+
+type BundleLog = BuildOutput['logs'][number];
+
+/**
+ * The plugin list Bun uses for this bundle, read from the file Bun reads.
+ *
+ * The probe has to bundle what the route bundles: a plugin missing here would
+ * make it describe a build nobody is served — or succeed where the route fails,
+ * which reports nothing at all.
+ */
+async function bundlePlugins(root: string): Promise<BunPlugin[]> {
+  const path = join(root, BUNFIG);
+  if (!(await Bun.file(path).exists())) return [];
+
+  let configured: unknown;
+  try {
+    const config = Bun.TOML.parse(await Bun.file(path).text()) as {
+      serve?: { static?: { plugins?: unknown } };
+    };
+    configured = config.serve?.static?.plugins;
+  } catch {
+    // A config Bun cannot parse is the build's own error to report.
+    return [];
+  }
+  if (!Array.isArray(configured)) return [];
+
+  const plugins: BunPlugin[] = [];
+  for (const entry of configured) {
+    if (typeof entry !== 'string') continue;
+    // A relative path is resolved from the package root; a bare specifier is
+    // left to the resolver, exactly as Bun reads it. Dynamic because the
+    // specifier is whatever the config names, not a module known here.
+    const specifier = entry.startsWith('.') ? join(root, entry) : entry;
+    try {
+      const module = (await import(specifier)) as { default?: BunPlugin };
+      if (module.default) plugins.push(module.default);
+    } catch {
+      // Same: an unimportable plugin surfaces through the build, not here.
+    }
+  }
+  return plugins;
+}
+
+/**
+ * A path as the reader knows it: relative to the package root, falling back to
+ * the absolute path when the file is not under it. The fallback matters on
+ * macOS, where `tmpdir()` is `/var/…` while the same file resolves to
+ * `/private/var/…` — a lexically-relative path there is `../../../private/var/…`,
+ * which is longer than what it replaces.
+ */
+function displayPath(file: string, root: string): string {
+  const relativePath = relative(root, file);
+  return relativePath && !relativePath.startsWith('..') ? relativePath : file;
+}
+
+/** One error as `file:line:column  message` plus the offending source line. */
+function formatLog(log: BundleLog, root: string): string {
+  const position = log.position;
+  if (!position?.file) return log.message;
+  const where = `${displayPath(position.file, root)}:${position.line}:${position.column}`;
+  const source = position.lineText.trim();
+  // The source line travels with the position: a file and column alone still
+  // leave the reader hunting for the edit.
+  return source ? `${where}  ${log.message}\n    ${source}` : `${where}  ${log.message}`;
+}
+
+/**
+ * The bundle errors behind a shell that would not render, or null when this
+ * build is not the reason (a clean bundle means the failure lies elsewhere).
+ */
+export async function describeShellBuildFailure(root = packageRoot()): Promise<string | null> {
+  const entrypoint = join(root, SHELL_ENTRYPOINT);
+  if (!(await Bun.file(entrypoint).exists())) return null;
+
+  let result: BuildOutput;
+  try {
+    result = await Bun.build({
+      entrypoints: [entrypoint],
+      target: 'browser',
+      plugins: await bundlePlugins(root),
+      // `throw: false` is what makes the failures readable: it returns them as
+      // `logs` instead of rejecting with an AggregateError, and keeps the probe
+      // from printing a second copy of an error Bun has already printed.
+      throw: false,
+    });
+  } catch (error) {
+    return `Rebuilding the client bundle failed: ${error instanceof Error ? error.message : String(error)}`;
+  }
+  if (result.success) return null;
+
+  const errors = result.logs.filter((log) => log.level === 'error');
+  if (errors.length === 0) return null;
+  return errors.map((log) => formatLog(log, root)).join('\n');
+}

package/src/server/lib/bundler/build-errors.test.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { describeShellBuildFailure } from '@/server/lib/bundler/build-errors.server';
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'omp-build-errors-'));
+  Bun.write(join(root, 'index.html'), '<!doctype html><html><body><script type="module" src="./entry.ts"></script></body></html>');
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe('describeShellBuildFailure', () => {
+  test('names the file, position and message of a syntax error', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'const a = 1;\nexport const broken = ;\n');
+
+    const detail = await describeShellBuildFailure(root);
+
+    expect(detail).toContain('entry.ts:2:23');
+    expect(detail).toContain('Unexpected ;');
+    // The offending source line travels with the message: a file and column
+    // alone still leave the reader hunting for the edit.
+    expect(detail).toContain('export const broken = ;');
+  });
+
+  test('reports an unresolved import that the bundle would use', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'import { a } from "./nowhere";\nconsole.log(a);\n');
+
+    expect(await describeShellBuildFailure(root)).toContain('Could not resolve: "./nowhere"');
+  });
+
+  test('reports a missing named export, which the route serves as a reload stub', async () => {
+    // The route answers 200 for this, so a status-only check calls it healthy —
+    // but Bun replaces the bundle with a 104-byte stub that only calls
+    // `location.reload()`, so the page cannot run. It is a real failure of the
+    // bundle and is reported as one.
+    await Bun.write(join(root, 'dep.ts'), 'export const a = 1;\n');
+    await Bun.write(join(root, 'entry.ts'), 'import { zzz } from "./dep";\nconsole.log(zzz);\n');
+
+    expect(await describeShellBuildFailure(root)).toContain('No matching export');
+  });
+
+  test('stays silent for an unresolved import the bundle would drop anyway', async () => {
+    // Tree-shaken away, so the route serves the page fine (verified: 200). A
+    // probe that reported it would send the reader after a build error that is
+    // not why the page is broken.
+    await Bun.write(join(root, 'entry.ts'), 'import x from "./nowhere";\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('returns null for a bundle that builds, so the reason stays the status alone', async () => {
+    await Bun.write(join(root, 'entry.ts'), 'console.log("ok");\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('returns null when there is no shell entrypoint to build', async () => {
+    rmSync(join(root, 'index.html'));
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+
+  test('loads the plugins named in bunfig.toml, as the route does', async () => {
+    // A plugin that fails a file the route would bundle: if the probe ignored
+    // bunfig it would report a clean build and hide the real failure.
+    await Bun.write(
+      join(root, 'probe-plugin.ts'),
+      `import type { BunPlugin } from 'bun';
+const plugin: BunPlugin = {
+  name: 'probe',
+  setup(build) {
+    build.onLoad({ filter: /\\.probe\\.ts$/ }, () => ({ contents: 'export const = ;', loader: 'ts' }));
+  },
+};
+export default plugin;
+`,
+    );
+    await Bun.write(join(root, 'bunfig.toml'), '[serve.static]\nplugins = ["./probe-plugin.ts"]\n');
+    await Bun.write(join(root, 'entry.ts'), 'import "./thing.probe";\n');
+    await Bun.write(join(root, 'thing.probe.ts'), 'export const ok = 1;\n');
+
+    expect(await describeShellBuildFailure(root)).not.toBeNull();
+  });
+
+  test('survives a bunfig it cannot parse', async () => {
+    await Bun.write(join(root, 'bunfig.toml'), '[serve.static\nplugins = broken\n');
+    await Bun.write(join(root, 'entry.ts'), 'console.log("ok");\n');
+
+    expect(await describeShellBuildFailure(root)).toBeNull();
+  });
+});

package/src/server/lib/bundler/dependencies.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Every bare import in `src/` must resolve from a published install.
+ *
+ * The bundler plugin (`css.ts`) is **runtime server code**, not build tooling:
+ * `bunfig.toml` names it in `[serve.static].plugins`, so `Bun.serve` loads it
+ * whenever an HTML route is bundled — which is every `ompchamber serve` in
+ * development and every `bun run start`. It therefore has to be loadable from
+ * an install that carries only `dependencies`.
+ *
+ * It was not. `@tailwindcss/postcss` was declared a devDependency and `postcss`
+ * was declared nowhere at all, which no local run could reveal — a source
+ * checkout and the developer's own `bun install` both have the whole tree — but
+ * the published package does not. Measured against a production-only install of
+ * the published tarball: the server came up and answered `503` on every page,
+ * with `error: Failed to load plugins for Bun.serve: Cannot find package
+ * 'postcss'` in its log and nothing in the shell to say why. The same install
+ * from `bun add -g` failed one dependency later on `@tailwindcss/postcss`.
+ *
+ * The invariant is therefore: a module reachable from a runtime entry point may
+ * only import a bare specifier that `dependencies` declares (or a Node/Bun
+ * builtin). `devDependencies` is the wrong home for anything the running server
+ * loads, however build-shaped it looks.
+ *
+ * Scope is deliberately `src/**` rather than "what the bundler reaches": the
+ * published tarball ships all of `src` and the CLI executes from it too, so a
+ * static import anywhere in the tree is a real requirement. Type-only imports
+ * are excluded because `scanImports` erases them — they cost nothing at runtime.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { builtinModules } from 'node:module';
+import { join } from 'node:path';
+
+import { packageRoot } from '@/server/lib/assets/fonts.server';
+
+/** Files whose imports are not part of any runtime path. */
+const EXCLUDED = /\.test\.|\.test-util\.|test-util\./;
+
+/** `@scope/name` keeps two segments; a bare package keeps one. */
+function packageName(specifier: string): string {
+  const segments = specifier.split('/');
+  return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
+
+const BUILTINS = new Set(builtinModules);
+
+/**
+ * Resolved from the running module, not the cwd — the same helper the bundler
+ * plugin uses, so this test answers the same question whether it is run from the
+ * repo root, from `dist/client`, or through `bun test <path>` elsewhere.
+ */
+const ROOT = packageRoot();
+
+const pkg = (await Bun.file(join(ROOT, 'package.json')).json()) as {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const RUNTIME = new Set(Object.keys(pkg.dependencies ?? {}));
+const DEV = new Set(Object.keys(pkg.devDependencies ?? {}));
+
+/**
+ * Bun's transpiler is the parser here, so the answer matches what the bundler
+ * itself sees: `@/` aliases, relative paths and `node:`/`bun:` prefixes are
+ * filtered below, and a type-only import never appears at all.
+ */
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+  tsconfig: readFileSync(join(ROOT, 'tsconfig.json'), 'utf8'),
+});
+
+const sources = [...new Bun.Glob('src/**/*.{ts,tsx,js}').scanSync({ cwd: ROOT })]
+  .filter((file) => !EXCLUDED.test(file));
+
+/** Every bare specifier each file imports, keyed by the file that imports it. */
+async function bareImports(file: string): Promise<string[]> {
+  let imports: Bun.Import[];
+  try {
+    imports = transpiler.scanImports(readFileSync(join(ROOT, file), 'utf8'));
+  } catch {
+    // A shebang line (`src/cli/ompchamber.js`) is not parseable as a module;
+    // its imports are covered by the files it imports.
+    return [];
+  }
+  return imports
+    // `require-call` entries are the JSX runtime Bun injects into the scan, not
+    // a specifier the source names; the runtime itself is `preact`, which is
+    // declared.
+    .filter((entry) => entry.kind !== 'require-call')
+    .map((entry) => entry.path)
+    .filter((path) => !path.startsWith('.') && !path.startsWith('@/'))
+    .filter((path) => !path.startsWith('bun:') && !path.startsWith('node:'))
+    .filter((path) => !BUILTINS.has(packageName(path)));
+}
+
+describe('runtime imports are declared as dependencies', () => {
+  test('no shipped module imports a bare specifier the package does not declare', async () => {
+    const violations: string[] = [];
+
+    for (const file of sources) {
+      for (const specifier of await bareImports(file)) {
+        const name = packageName(specifier);
+        if (RUNTIME.has(name)) continue;
+        violations.push(`${file} imports '${specifier}' — ${DEV.has(name) ? 'declared in devDependencies' : 'not declared in package.json'}`);
+      }
+    }
+
+    // Printed rather than merely counted: the fix is per-specifier, and the
+    // message has to say which list to move it to.
+    expect(violations).toEqual([]);
+  });
+
+  test('the bundler plugin is a runtime dependency of the server', () => {
+    // The specific regression, pinned by name. `bunfig.toml` is what makes the
+    // plugin runtime code, so the two are read together: if the plugin ever
+    // stops being a `serve.static` entry, this assertion is what says the
+    // dependency placement no longer has to hold.
+    const bunfig = Bun.TOML.parse(readFileSync(join(ROOT, 'bunfig.toml'), 'utf8')) as {
+      serve?: { static?: { plugins?: string[] } };
+    };
+    expect(bunfig.serve?.static?.plugins).toContain('./src/server/lib/bundler/css.ts');
+
+    for (const name of ['@tailwindcss/postcss', 'postcss']) {
+      expect(RUNTIME.has(name)).toBe(true);
+      expect(DEV.has(name)).toBe(false);
+    }
+  });
+});

package/src/server/lib/db/client.ts

@@ -44,7 +44,11 @@ export function createDb(path: string): DbClient {
       return prep(sql).all(...(params as never[])) as T[];
     },
     async run(sql: string, params: any[] = []) {
-      const result = raw.run(sql, params as never);
+      // Through `prep`, like `get`/`all`: `Database.run` does not cache its
+      // query (it prepares and finalizes per call), which cost every INSERT /
+      // UPDATE / DELETE a compile — measured 0.881 µs/op against 0.627 µs/op
+      // for the cached statement.
+      const result = prep(sql).run(...(params as never[]));
       return { changes: result.changes, lastID: Number(result.lastInsertRowid) };
     },
     async exec(sql: string) {

package/src/server/lib/fs/git-diff.ts

@@ -2,20 +2,32 @@ import path from 'path';
 import type { FileDiffData } from '@/shared/types/git';
 import { runShell, shellOk } from '@/server/lib/fs/shell';
 
+/**
+ * Context lines requested when the reader wants the whole file rather than the
+ * hunks. `--unified` takes any count, so this is a cap on the FILE, not on the
+ * change: git emits every line it can reach around the edits.
+ */
+const FULL_CONTEXT = 1000000;
+
 /** Runs one git diff probe and returns its stdout ('' on failure). */
-async function gitOut(command: string, cwd: string, timeout: number): Promise<string> {
-  const result = await runShell(command, { cwd, timeout, maxBuffer: 1024 * 1024 * 2 });
+async function gitOut(command: string, cwd: string, timeout: number, maxBuffer: number = 1024 * 1024 * 2): Promise<string> {
+  const result = await runShell(command, { cwd, timeout, maxBuffer });
   return shellOk(result) ? result.stdout : '';
 }
 
 /**
  * Fetch git diff for a specific file in the working directory or index.
+ *
+ * `fullContext` asks git for the entire file rather than the surrounding hunks,
+ * which is what the panel's "Full Code" mode renders — the diff comes back in
+ * the same unified format, so no second rendering path exists.
  */
 export async function fetchWorkingFileDiff(
   targetDir: string,
   file: string,
   staged: boolean = false,
-  requestedStatus?: string
+  requestedStatus?: string,
+  fullContext: boolean = false
 ): Promise<FileDiffData> {
   const cleanFile = file.replace(/^[./\\]+/, '').replace(/\\/g, '/');
   const fullPath = path.join(targetDir, cleanFile);
@@ -45,21 +57,33 @@ export async function fetchWorkingFileDiff(
     oldContent = await gitOut(`git show HEAD:"${cleanFile}"`, targetDir, 5000)
       || await gitOut(`git show :0:"${cleanFile}"`, targetDir, 5000);
 
+    // `-U<n>` on every probe: the full-code mode asks for the whole file, and
+    // the diff-only mode keeps git's own default by passing no flag at all.
+    const ctx = fullContext ? ` -U${FULL_CONTEXT}` : '';
+    // Full-context output is the file, not the change, so a fixed buffer would
+    // truncate a large file's diff — and a killed process is not a success, so
+    // `gitOut` reports it as no diff at all and the synthesized whole-file
+    // rewrite below takes over silently. Sized off the content already read, so
+    // it cannot exceed roughly twice the file.
+    const buf = fullContext
+      ? Math.max(1024 * 1024 * 16, (oldContent.length + newContent.length) * 2 + 1024 * 1024)
+      : 1024 * 1024 * 2;
+
     if (staged) {
       // 1. Try staged diff (index vs HEAD), 2. HEAD diff, 3. unstaged diff
-      diff = await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000);
+      diff = await gitOut(`git diff${ctx} --cached -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} HEAD -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} -- "${cleanFile}"`, targetDir, 10000, buf);
     } else if (status === '??' || status === 'U' || status === '?') {
       // Untracked file: --no-index exits 1 when a diff exists, so read stdout
       // directly instead of relying on the exit code.
-      const untracked = await runShell(`git diff --no-index /dev/null "${cleanFile}"`, { cwd: targetDir, timeout: 10000, maxBuffer: 1024 * 1024 * 2 });
+      const untracked = await runShell(`git diff${ctx} --no-index /dev/null "${cleanFile}"`, { cwd: targetDir, timeout: 10000, maxBuffer: buf });
       diff = untracked.stdout.trim() ? untracked.stdout : '';
     } else {
       // 1. Working tree diff, 2. cached diff, 3. HEAD diff
-      diff = await gitOut(`git diff -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff --cached -- "${cleanFile}"`, targetDir, 10000)
-        || await gitOut(`git diff HEAD -- "${cleanFile}"`, targetDir, 10000);
+      diff = await gitOut(`git diff${ctx} -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} --cached -- "${cleanFile}"`, targetDir, 10000, buf)
+        || await gitOut(`git diff${ctx} HEAD -- "${cleanFile}"`, targetDir, 10000, buf);
     }
 
     // 4. If git diff is still empty but new content exists:

package/src/server/lib/fs/git-repos.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Nested-repository discovery for the right-panel repo picker.
+ *
+ * A workspace is often a folder OF repositories (`projects/<name>/<sub>/.git`),
+ * so the picker lists every repo under the scoped root. The walk is expensive
+ * on a deep tree, so it runs in the BACKGROUND after the loader has already
+ * answered with the root's own status; the client polls until `pending` clears.
+ * Results are cached per scoped root for the life of the process.
+ *
+ * The `find` prunes `node_modules` (the one directory guaranteed to hold
+ * unrelated `.git` directories, and the one that makes the walk unbounded).
+ */
+
+import { runShell } from '@/server/lib/fs/shell';
+
+const MAX_GIT_DEPTH = 8;
+
+async function getRepos(rootDir: string): Promise<string[]> {
+  try {
+    // Search deep enough to discover nested/child git repos inside a monorepo
+    // workspace (e.g. projects/<name>/<sub>/.git) while pruning node_modules.
+    const result = await runShell(
+      `find . -maxdepth ${MAX_GIT_DEPTH} -name node_modules -prune -o -name .git -type d -print`,
+      { cwd: rootDir, timeout: 12000, maxBuffer: 1024 * 1024 }
+    );
+    const discovered = result.stdout
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map(line => {
+        const cleaned = line.replace(/^\.\//, '').replace(/\/\.git$/, '');
+        return cleaned === '.git' || !cleaned ? '.' : cleaned;
+      });
+
+    const uniqueRepos = Array.from(new Set(discovered));
+    if (uniqueRepos.includes('.')) {
+      return ['.', ...uniqueRepos.filter(r => r !== '.')];
+    }
+    return uniqueRepos.length ? uniqueRepos : ['.'];
+  } catch {
+    return ['.'];
+  }
+}
+
+interface RepoDiscovery {
+  repos: string[];
+  done: boolean;
+}
+
+const repoDiscovery = new Map<string, RepoDiscovery>();
+
+/** Begin the background walk for `rootDir`; a no-op once one has started. */
+export function startRepoScan(rootDir: string): void {
+  if (repoDiscovery.has(rootDir)) return;
+  const d: RepoDiscovery = { repos: ['.'], done: false };
+  repoDiscovery.set(rootDir, d);
+  void getRepos(rootDir)
+    .then(repos => { d.repos = repos; d.done = true; })
+    .catch(() => { d.repos = ['.']; d.done = true; });
+}
+
+/**
+ * Drop the cached result for `rootDir` and start a fresh walk. Used by the
+ * repo-switcher's refresh button, which must not serve the previous answer.
+ */
+export function rescanRepos(rootDir: string): void {
+  repoDiscovery.delete(rootDir);
+  startRepoScan(rootDir);
+}
+
+/** The discovered repos for `rootDir`, and whether the walk is still running. */
+export function discoveredRepos(rootDir: string): { repos: string[]; pending: boolean } {
+  const d = repoDiscovery.get(rootDir);
+  if (!d) return { repos: ['.'], pending: false };
+  return { repos: d.done ? d.repos : ['.'], pending: !d.done };
+}