@polderlabs/bizar 4.5.0 → 4.5.2

package/bizar-dash/src/web/views/memory/SemanticSearchPanel.tsx

@@ -0,0 +1,194 @@
+// src/web/views/memory/SemanticSearchPanel.tsx — cross-source search (LightRAG + Obsidian).
+import { useEffect, useMemo, useState } from 'react';
+import { Brain, FileText, Loader2, Search as SearchIcon, X } from 'lucide-react';
+import { Button } from '../../components/Button';
+import { Card, CardMeta, CardTitle } from '../../components/Card';
+import { EmptyState } from '../../components/EmptyState';
+import { Spinner } from '../../components/Spinner';
+import { useToast } from '../../components/Toast';
+import { api } from '../../lib/api';
+import { cn } from '../../lib/utils';
+
+type Result = {
+  source: 'lightrag' | 'obsidian';
+  relPath: string | null;
+  snippet: string;
+  score: number;
+  mtime: number | null;
+  raw?: unknown;
+  error?: string;
+};
+
+type Props = { refreshKey: number };
+
+export function SemanticSearchPanel({ refreshKey }: Props) {
+  const toast = useToast();
+  const [q, setQ] = useState('');
+  const [sources, setSources] = useState<{ lightrag: boolean; obsidian: boolean }>({ lightrag: true, obsidian: true });
+  const [results, setResults] = useState<Result[] | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [lastQuery, setLastQuery] = useState('');
+
+  const onSearch = async (query: string) => {
+    if (!query.trim()) return;
+    setLoading(true);
+    setLastQuery(query);
+    try {
+      const activeSources = [
+        ...(sources.lightrag ? ['lightrag' as const] : []),
+        ...(sources.obsidian ? ['obsidian' as const] : []),
+      ];
+      const r = await api.post<{ query: string; count: number; results: Result[] }>(
+        '/memory/semantic-search',
+        { query, limit: 20, sources: activeSources },
+      );
+      setResults(r.results || []);
+    } catch (err) {
+      toast.error(`Search failed: ${(err as Error).message}`);
+      setResults([]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Re-run when sources toggle (if there's a last query).
+  useEffect(() => {
+    if (lastQuery) onSearch(lastQuery);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sources]);
+
+  // Re-run when the panel is re-mounted.
+  useEffect(() => {
+    if (lastQuery) onSearch(lastQuery);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [refreshKey]);
+
+  const grouped = useMemo(() => {
+    const obs = (results || []).filter((r) => r.source === 'obsidian');
+    const lr = (results || []).filter((r) => r.source === 'lightrag');
+    return { obs, lr };
+  }, [results]);
+
+  return (
+    <div className="memory-panel-content">
+      <Card variant="elevated">
+        <CardTitle>
+          <SearchIcon size={14} /> Semantic search
+        </CardTitle>
+        <CardMeta>Query both LightRAG (graph-based) and the Obsidian vault in one shot.</CardMeta>
+        <div className="memory-search-row">
+          <input
+            type="text"
+            className="input"
+            placeholder="e.g. how are notes indexed?"
+            value={q}
+            onChange={(e) => setQ(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') onSearch(q);
+            }}
+            disabled={loading}
+          />
+          <Button variant="primary" onClick={() => onSearch(q)} disabled={loading || !q.trim()}>
+            {loading ? <Loader2 size={12} className="memory-spin" /> : <SearchIcon size={12} />}
+            Search
+          </Button>
+        </div>
+        <div className="memory-source-toggle-row">
+          <ToggleChip
+            active={sources.obsidian}
+            onToggle={() => setSources((s) => ({ ...s, obsidian: !s.obsidian }))}
+            label="Obsidian"
+            icon={<FileText size={11} />}
+          />
+          <ToggleChip
+            active={sources.lightrag}
+            onToggle={() => setSources((s) => ({ ...s, lightrag: !s.lightrag }))}
+            label="LightRAG"
+            icon={<Brain size={11} />}
+          />
+          {q && (
+            <button type="button" className="icon-btn" onClick={() => { setQ(''); setResults(null); setLastQuery(''); }} aria-label="Clear">
+              <X size={12} />
+            </button>
+          )}
+        </div>
+      </Card>
+
+      {loading && (
+        <div className="view-loading">
+          <Spinner size="md" />
+        </div>
+      )}
+
+      {!loading && results && results.length === 0 && (
+        <EmptyState
+          icon={<SearchIcon size={28} />}
+          title="No matches"
+          message={`Nothing in scope matched "${lastQuery}".`}
+        />
+      )}
+
+      {grouped.obs.length > 0 && (
+        <Card>
+          <CardTitle>
+            <FileText size={14} /> Obsidian ({grouped.obs.length})
+          </CardTitle>
+          <ul className="memory-search-result-list">
+            {grouped.obs.map((r, i) => (
+              <li key={`obs-${i}`} className="memory-search-result">
+                <div className="memory-search-result-head">
+                  <code>{r.relPath}</code>
+                  <span className="muted text-xs">score {r.score.toFixed(1)}</span>
+                </div>
+                <p className="muted text-sm">{r.snippet}</p>
+              </li>
+            ))}
+          </ul>
+        </Card>
+      )}
+
+      {grouped.lr.length > 0 && (
+        <Card>
+          <CardTitle>
+            <Brain size={14} /> LightRAG ({grouped.lr.length})
+          </CardTitle>
+          <div className="memory-search-result-list">
+            {grouped.lr.map((r, i) => (
+              <div key={`lr-${i}`} className="memory-search-result">
+                <div className="memory-search-result-head">
+                  <span className="memory-source-pill"><Brain size={11} /> LightRAG</span>
+                  {r.error && <span className="muted text-xs">error: {r.error}</span>}
+                </div>
+                <p className="text-sm">{r.snippet}</p>
+              </div>
+            ))}
+          </div>
+        </Card>
+      )}
+    </div>
+  );
+}
+
+function ToggleChip({
+  active,
+  onToggle,
+  label,
+  icon,
+}: {
+  active: boolean;
+  onToggle: () => void;
+  label: string;
+  icon: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      className={cn('memory-toggle-chip', active && 'memory-toggle-chip-active')}
+      onClick={onToggle}
+      aria-pressed={active}
+    >
+      {icon}
+      <span>{label}</span>
+    </button>
+  );
+}

package/bizar-dash/tests/cli-bugfixes.test.mjs

@@ -0,0 +1,151 @@
+/**
+ * tests/cli-bugfixes.test.mjs — regression tests for CLI + installer bug fixes.
+ *
+ * Covers:
+ *   B1 — parseWithModsFlag exits with code 2 when no value follows --with-mods
+ *   B7 — check-deps.mjs uses path.join() (Windows fix) + covers all deps
+ *   B9 — --json flag works for `bizar doctor --json`
+ *   B10 — --debug flag sets DEBUG env var
+ *
+ * Run with: node --test bizar-dash/tests/cli-bugfixes.test.mjs
+ */
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+const REPO = join(process.cwd());
+
+// ─── B1: parseWithModsFlag exits with code 2 on missing value ──────────────────
+
+describe('B1 — parseWithModsFlag', () => {
+  it('exits with code 2 when --with-mods is the last arg', async () => {
+    // Import fresh each time to avoid module-level side effects
+    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    let exitCode = null;
+    const origExit = process.exit;
+    // Mock process.exit to capture the code without terminating the test
+    try {
+      process.exit = (code) => { exitCode = code; throw new Error('exit:' + code); };
+      parseWithModsFlag(['install', '--with-mods']);
+    } catch (err) {
+      if (err.message.startsWith('exit:')) exitCode = parseInt(err.message.split(':')[1]);
+    } finally {
+      process.exit = origExit;
+    }
+    assert.strictEqual(exitCode, 2, 'should have called process.exit(2)');
+  });
+
+  it('exits with code 2 when next arg is another flag', async () => {
+    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    let exitCode = null;
+    const origExit = process.exit;
+    try {
+      process.exit = (code) => { exitCode = code; throw new Error('exit:' + code); };
+      parseWithModsFlag(['install', '--with-mods', '--force']);
+    } catch (err) {
+      if (err.message.startsWith('exit:')) exitCode = parseInt(err.message.split(':')[1]);
+    } finally {
+      process.exit = origExit;
+    }
+    assert.strictEqual(exitCode, 2);
+  });
+
+  it('returns null when --with-mods is not present', async () => {
+    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    let exitCode = null;
+    const origExit = process.exit;
+    try {
+      process.exit = (code) => { exitCode = code; throw new Error('exit:' + code); };
+      const result = parseWithModsFlag(['install', '--force']);
+      assert.strictEqual(result, null);
+      assert.strictEqual(exitCode, null);
+    } finally {
+      process.exit = origExit;
+    }
+  });
+
+  it('returns array of mod ids when value is provided', async () => {
+    const { parseWithModsFlag } = await import('../../cli/bin.mjs');
+    let exitCode = null;
+    const origExit = process.exit;
+    try {
+      process.exit = (code) => { exitCode = code; throw new Error('exit:' + code); };
+      const result = parseWithModsFlag(['install', '--with-mods', 'a,b,c']);
+      assert.deepStrictEqual(result, ['a', 'b', 'c']);
+      assert.strictEqual(exitCode, null);
+    } finally {
+      process.exit = origExit;
+    }
+  });
+});
+
+// ─── B7: check-deps.mjs cross-platform path joining ───────────────────────────
+
+describe('B7 — check-deps.mjs which() uses path.join()', () => {
+  it('covers all required dependencies', async () => {
+    const { checkDeps } = await import('../../scripts/check-deps.mjs');
+    const result = await checkDeps({ strict: false });
+    const names = [...result.present, ...result.missing].map(d => d.name);
+    const required = ['node', 'bun', 'opencode', 'tmux', 'git', 'python3', 'pip', 'jq', 'gh', 'headroom', 'semble', 'skills'];
+    for (const dep of required) {
+      assert.ok(names.includes(dep), `expected ${dep} to be checked`);
+    }
+  });
+
+  it('which() uses join() from node:path for path construction', async () => {
+    const { readFileSync } = await import('node:fs');
+    const src = readFileSync(join(process.cwd(), 'scripts', 'check-deps.mjs'), 'utf8');
+    assert.ok(src.includes("import { join } from 'node:path'"), 'should import join from node:path');
+    assert.ok(src.includes('join(dir, cmd + ext)'), 'should use join() for path construction');
+  });
+});
+
+// ─── B9: --json flag for doctor ───────────────────────────────────────────────
+
+describe('B9 — --json flag', () => {
+  it('doctor --json outputs valid JSON', async () => {
+    const { spawnSync } = await import('node:child_process');
+    const bin = join(REPO, 'cli', 'bin.mjs');
+    const result = spawnSync('node', [bin, 'doctor', '--json'], {
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+    const out = result.stdout.trim();
+    // Should be parseable as JSON
+    let parsed;
+    try {
+      parsed = JSON.parse(out);
+    } catch {
+      assert.fail(`expected JSON output, got: ${out.slice(0, 200)}`);
+      return;
+    }
+    assert.ok('passed' in parsed, 'JSON should have passed field');
+    assert.ok('failed' in parsed, 'JSON should have failed field');
+    assert.ok('results' in parsed, 'JSON should have results field');
+    assert.ok(Array.isArray(parsed.results), 'results should be an array');
+  });
+});
+
+// ─── B10: --debug flag sets DEBUG env var ──────────────────────────────────────
+
+describe('B10 — --debug flag', () => {
+  it('dbg() helper is defined in bin.mjs', async () => {
+    const { readFileSync } = await import('node:fs');
+    const src = readFileSync(join(REPO, 'cli', 'bin.mjs'), 'utf8');
+    assert.ok(src.includes('function dbg('), 'dbg() helper should be defined');
+    assert.ok(src.includes("process.env.DEBUG = 'bizar:*'"), '--debug should set DEBUG=bizar:*');
+    assert.ok(src.includes("process.env.BIZAR_DEBUG = '1'"), '--debug should set BIZAR_DEBUG=1');
+  });
+
+  it('--debug flag is accepted without error', async () => {
+    const { spawnSync } = await import('node:child_process');
+    const bin = join(REPO, 'cli', 'bin.mjs');
+    // Just verify --debug doesn't cause a parse error or unknown flag
+    const result = spawnSync('node', [bin, '--help', '--debug'], {
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    // --debug should not cause an error (help should print)
+    assert.ok(result.status === 0 || result.stdout.includes('bizar'), '--debug should not error');
+  });
+});

package/bizar-dash/tests/frontend-bugfixes.test.mjs

@@ -0,0 +1,151 @@
+// bizar-dash/tests/frontend-bugfixes.test.mjs
+// Lightweight verification of dashboard web + build bug fixes.
+// Run with: node --test bizar-dash/tests/frontend-bugfixes.test.mjs
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+
+// import.meta.dirname = /.../BizarHarness/bizar-dash/tests
+// So project root is up 2 levels
+const ROOT    = import.meta.dirname;                              // .../BizarHarness/bizar-dash/tests
+const PROJECT = resolve(ROOT, '..', '..');                        // .../BizarHarness/
+const DASH    = resolve(ROOT, '..');                             // .../BizarHarness/bizar-dash/
+
+function read(file) {
+  return readFileSync(resolve(PROJECT, file), 'utf-8');
+}
+function dash(file) {
+  return readFileSync(resolve(DASH, file), 'utf-8');
+}
+
+describe('W1: vite.config.ts sourcemap: hidden', () => {
+  it("sourcemap is 'hidden'", () => {
+    const content = read('vite.config.ts');
+    if (!content.includes("sourcemap: 'hidden'")) {
+      throw new Error("vite.config.ts missing sourcemap: 'hidden'");
+    }
+    if (content.includes('sourcemap: true')) {
+      throw new Error('vite.config.ts still contains sourcemap: true');
+    }
+  });
+});
+
+describe('W2: .npmignore excludes source maps and tests', () => {
+  it('excludes .map files from dist', () => {
+    const c = read('.npmignore');
+    if (!c.includes('bizar-dash/dist/**/*.map')) throw new Error('.npmignore missing bizar-dash/dist/**/*.map');
+  });
+  it('excludes **/__tests__/', () => {
+    const c = read('.npmignore');
+    if (!c.includes('**/__tests__/')) throw new Error('.npmignore missing **/__tests__/');
+  });
+  it('excludes **/*.test.mjs', () => {
+    const c = read('.npmignore');
+    if (!c.includes('**/*.test.mjs')) throw new Error('.npmignore missing **/*.test.mjs');
+  });
+  it('excludes **/*.test.ts', () => {
+    const c = read('.npmignore');
+    if (!c.includes('**/*.test.ts')) throw new Error('.npmignore missing **/*.test.ts');
+  });
+  it('excludes **/*.test.tsx', () => {
+    const c = read('.npmignore');
+    if (!c.includes('**/*.test.tsx')) throw new Error('.npmignore missing **/*.test.tsx');
+  });
+});
+
+describe('W3: Toast.tsx accessibility', () => {
+  it('ToastItem has role="alert"', () => {
+    const c = dash('src/web/components/Toast.tsx');
+    if (!c.includes('role="alert"')) throw new Error('Toast.tsx missing role="alert"');
+  });
+  it('ToastItem has aria-live="assertive"', () => {
+    const c = dash('src/web/components/Toast.tsx');
+    if (!c.includes('aria-live="assertive"')) throw new Error('Toast.tsx missing aria-live="assertive"');
+  });
+  it('ToastItem has aria-atomic="true"', () => {
+    const c = dash('src/web/components/Toast.tsx');
+    if (!c.includes('aria-atomic="true"')) throw new Error('Toast.tsx missing aria-atomic="true"');
+  });
+});
+
+describe('W4: App.tsx Suspense wrapper', () => {
+  it('Suspense imported from react', () => {
+    const c = dash('src/web/App.tsx');
+    if (!c.includes('Suspense')) throw new Error('App.tsx missing Suspense import');
+  });
+  it('renderedView wrapped in Suspense', () => {
+    const c = dash('src/web/App.tsx');
+    if (!c.includes('<Suspense')) throw new Error('App.tsx missing <Suspense> wrapper');
+  });
+});
+
+describe('W5: React.memo on view components', () => {
+  const views = [
+    ['Tasks',       dash('src/web/views/Tasks.tsx')],
+    ['Settings',    dash('src/web/views/Settings.tsx')],
+    ['Memory',      dash('src/web/views/Memory.tsx')],
+    ['Overview',    dash('src/web/views/Overview.tsx')],
+    ['Skills',      dash('src/web/views/Skills.tsx')],
+    ['MiniMaxUsage',dash('src/web/views/MiniMaxUsage.tsx')],
+  ];
+  for (const [name, content] of views) {
+    it(`${name} is wrapped in React.memo`, () => {
+      // Pattern: const Name = React.memo(...) or export const Name = React.memo(...)
+      if (!content.includes('React.memo(')) {
+        throw new Error(`${name} is not wrapped in React.memo`);
+      }
+    });
+  }
+});
+
+describe('W6: Topbar ARIA roles', () => {
+  const c = dash('src/web/components/Topbar.tsx');
+  it('tabs-row has role="tablist"', () => { if (!c.includes('role="tablist"')) throw new Error('Topbar missing role="tablist"'); });
+  it('tabs-row has aria-label="Primary tabs"', () => { if (!c.includes('aria-label="Primary tabs"')) throw new Error('Topbar missing aria-label="Primary tabs"'); });
+  it('tab buttons have role="tab"', () => { if (!c.includes('role="tab"')) throw new Error('Topbar missing role="tab"'); });
+  it('tab buttons have aria-selected', () => { if (!c.includes('aria-selected=')) throw new Error('Topbar missing aria-selected on tabs'); });
+});
+
+describe('F1: Manual snapshot refetch removed from file change WS event', () => {
+  it("'change' WS handler no longer calls api.get('/snapshot')", () => {
+    const c = dash('src/web/App.tsx');
+    const idx = c.indexOf("msg.type === 'change'");
+    if (idx === -1) throw new Error("msg.type === 'change' not found");
+    const block = c.slice(idx, idx + 600);
+    if (block.includes("api.get<Snapshot>('/snapshot')") || block.includes('api.get("/snapshot")')) {
+      throw new Error("Manual api.get('/snapshot') still present in 'change' handler");
+    }
+  });
+});
+
+describe('F2: content-visibility: auto on list items', () => {
+  it('.activity-item has content-visibility: auto (main.css)', () => {
+    const c = dash('src/web/styles/main.css');
+    const i = c.indexOf('.activity-item');
+    if (!c.slice(i, i + 500).includes('content-visibility: auto')) {
+      throw new Error('.activity-item missing content-visibility: auto in main.css');
+    }
+  });
+  it('.task-card has content-visibility: auto (main.css)', () => {
+    const c = dash('src/web/styles/main.css');
+    const i = c.indexOf('.task-card');
+    if (!c.slice(i, i + 500).includes('content-visibility: auto')) {
+      throw new Error('.task-card missing content-visibility: auto in main.css');
+    }
+  });
+  it('.chat-message has content-visibility: auto (chat.css)', () => {
+    const c = dash('src/web/styles/chat.css');
+    const i = c.indexOf('.chat-message');
+    if (!c.slice(i, i + 300).includes('content-visibility: auto')) {
+      throw new Error('.chat-message missing content-visibility: auto in chat.css');
+    }
+  });
+  it('.task-card has content-visibility: auto (tasks.css)', () => {
+    const c = dash('src/web/styles/tasks.css');
+    const i = c.indexOf('.task-card');
+    if (!c.slice(i, i + 500).includes('content-visibility: auto')) {
+      throw new Error('.task-card missing content-visibility: auto in tasks.css');
+    }
+  });
+});

package/bizar-dash/tests/headroom-install.test.mjs

@@ -0,0 +1,173 @@
+/**
+ * tests/headroom-install.test.mjs
+ *
+ * Tests for installHeadroom(), wrapOpencode(), unwrapOpencode(), startProxy(), stopProxy().
+ * Uses real commands when available, mocks when not.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, rmSync, writeFileSync, existsSync, unlinkSync, readFileSync } from 'node:fs';
+import http from 'node:http';
+
+// ── Run command helper ──────────────────────────────────────────────────────
+
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { timeout: 5000, ...opts });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (d) => { stdout += d.toString(); });
+    child.stderr?.on('data', (d) => { stderr += d.toString(); });
+    child.on('close', (code) => resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0 }));
+    child.on('error', (err) => resolve({ stdout: '', stderr: err.message, exitCode: 1 }));
+  });
+}
+
+// ── Install tests ────────────────────────────────────────────────────────────
+
+test('installHeadroom returns correct shape', async () => {
+  const { installHeadroom } = await import('../src/server/headroom.mjs');
+  const result = await installHeadroom({ force: false });
+
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(typeof result.installed === 'boolean', 'installed is boolean');
+  assert.ok(typeof result.version === 'string' || result.version === null, 'version is string|null');
+  assert.ok(typeof result.method === 'string', 'method is string');
+});
+
+test('installHeadroom returns already-installed when headroom is on PATH', async () => {
+  const { installed } = await runCmd('headroom', ['--version']);
+  if (installed !== 0) {
+    // headroom not installed — skip
+    return;
+  }
+
+  const { installHeadroom } = await import('../src/server/headroom.mjs');
+  const result = await installHeadroom({ force: false });
+
+  assert.strictEqual(result.installed, true, 'should report already installed');
+  assert.strictEqual(result.method, 'already-installed', 'method should be already-installed');
+});
+
+test('installHeadroom.force reinstalls even when already installed', async () => {
+  const { installHeadroom } = await import('../src/server/headroom.mjs');
+  const result = await installHeadroom({ force: true });
+
+  // Returns the shape regardless of outcome
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(typeof result.installed === 'boolean', 'installed is boolean');
+  assert.ok(typeof result.method === 'string', 'method is string');
+});
+
+// ── Wrap / Unwrap tests ─────────────────────────────────────────────────────
+
+test('wrapOpencode returns correct shape', async () => {
+  const { wrapOpencode } = await import('../src/server/headroom.mjs');
+  const result = await wrapOpencode({ port: 8787 });
+
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(typeof result.port === 'number', 'port is number');
+  assert.ok(typeof result.log === 'string', 'log is string');
+  assert.strictEqual(result.port, 8787, 'port is 8787');
+});
+
+test('unwrapOpencode returns correct shape', async () => {
+  const { unwrapOpencode } = await import('../src/server/headroom.mjs');
+  const result = await unwrapOpencode();
+
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(typeof result.log === 'string', 'log is string');
+});
+
+// ── Proxy tests ─────────────────────────────────────────────────────────────
+
+test('startProxy returns correct shape', async () => {
+  const { startProxy } = await import('../src/server/headroom.mjs');
+  const result = await startProxy({ port: 18787, host: '127.0.0.1' });
+
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(typeof result.pid === 'number' || result.pid === null, 'pid is number|null');
+  assert.ok(typeof result.port === 'number', 'port is number');
+  assert.ok(typeof result.logPath === 'string', 'logPath is string');
+});
+
+test('stopProxy returns correct shape', async () => {
+  const { stopProxy } = await import('../src/server/headroom.mjs');
+  const result = await stopProxy();
+
+  assert.ok(typeof result.ok === 'boolean', 'ok is boolean');
+  assert.ok(Array.isArray(result.killed), 'killed is array');
+});
+
+// ── getOpencodeConfig tests ──────────────────────────────────────────────────
+
+test('getOpencodeConfig returns correct shape', async () => {
+  const { getOpencodeConfig } = await import('../src/server/headroom.mjs');
+  const result = await getOpencodeConfig();
+
+  assert.ok(typeof result.configPath === 'string', 'configPath is string');
+  assert.ok(typeof result.hasHeadroomProvider === 'boolean', 'hasHeadroomProvider is boolean');
+  assert.ok(result.configPath.includes('opencode.json'), 'configPath points to opencode.json');
+});
+
+// ── withHeadroomProxy tests ──────────────────────────────────────────────────
+
+test('withHeadroomProxy returns URL unchanged when disabled', async () => {
+  const { withHeadroomProxy } = await import('../src/server/headroom.mjs');
+  const url = 'https://api.anthropic.com/v1/messages';
+  // When headroom is not in settings (default), returns URL unchanged
+  const result = withHeadroomProxy(url, { port: 8787 });
+  // Result depends on settings — just verify it's a string
+  assert.ok(typeof result === 'string', 'result is string');
+  assert.ok(result.length > 0, 'result is non-empty');
+});
+
+// ── /api/headroom/install endpoint ──────────────────────────────────────────
+
+async function buildApp() {
+  const { createHeadroomRouter } = await import('../src/server/routes/headroom.mjs');
+  const express = (await import('express')).default;
+  const app = express();
+  app.use(express.json());
+  // Mount at /api/headroom so routes like /status become /api/headroom/status
+  app.use('/api/headroom', await createHeadroomRouter());
+  return app;
+}
+
+test('POST /api/headroom/install returns result', async () => {
+  const app = await buildApp();
+  const server = app.listen(0);
+  const { port } = server.address();
+
+  const httpPost = () =>
+    new Promise((resolve, reject) => {
+      const data = JSON.stringify({ force: false });
+      const req = http.request(
+        { hostname: 'localhost', port, path: '/api/headroom/install', method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) } },
+        (res) => {
+          let body = '';
+          res.on('data', (c) => (body += c));
+          res.on('end', () => {
+            try { resolve({ status: res.statusCode, body: JSON.parse(body || '{}') }); }
+            catch { resolve({ status: res.statusCode, body }); }
+          });
+        },
+      );
+      req.on('error', reject);
+      req.write(data);
+      req.end();
+    });
+
+  try {
+    const res = await httpPost();
+    assert.strictEqual(res.status, 200, 'status should be 200');
+    assert.ok(typeof res.body.ok === 'boolean', 'ok is boolean');
+    assert.ok(typeof res.body.installed === 'boolean', 'installed is boolean');
+  } finally {
+    server.close();
+  }
+});