codebase-onboarder 0.1.0

package/public/js/analysisPanel.js

@@ -0,0 +1,270 @@
+// The deep-analysis store, and the panel the Security view draws from it.
+//
+// Onboarder's built-in scanner is a fast, zero-dependency first pass. This is
+// the second pass — it runs the real analyzers the machine has (Semgrep,
+// Gitleaks, Knip, Vulture, Depcheck) through the server, and merges what they
+// find into the scan so the security grade includes them.
+//
+// Two consumers now share one store: this file's panel in the Security view's
+// inspector, and the full Deep Analysis view
+// (`deepAnalysisView.js`). Putting the run in one place is what keeps them
+// from disagreeing — a run started from either surface lands in
+// `state.tools`, merges identically, and notifies both to repaint. The
+// alternative (each surface calling the API itself) is how you end up with two
+// buttons that produce two different grades.
+//
+// The contract, in three lines:
+//
+//   * Nothing is required. Both surfaces render with zero engines installed and
+//     say which to install — "no deep analysis" and "no findings" are never the
+//     same sentence.
+//   * Server-side scans only. A browser-picked folder never touches the disk
+//     from the server's point of view, so there is no root to point a tool at;
+//     both surfaces explain that instead of pretending.
+//   * Findings merge into the same shape the built-in scanner uses, with
+//     `source: 'builtin'|'external'` kept, so the attribution stays visible.
+
+import { escapeHtml } from './html.js';
+import { fetchToolsStatus, runAnalysisTools, streamToolInstall } from './api.js';
+import { state } from './state.js';
+import { engineRows, engineSummary } from './analysisReport.js';
+import { mergeFindingsIntoScan, summarizeSecurity } from '/shared/analyzer/security.js';
+
+// ---- the store -------------------------------------------------------------
+
+// Who wants to know when a run starts, finishes or fails. The inspector panel
+// and the Deep Analysis view both subscribe; neither polls.
+const listeners = new Set();
+
+export function subscribeAnalysis(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function notify() {
+  for (const listener of listeners) listener();
+}
+
+// Which engines are installed. Asked once per repo and cached on the session —
+// detection spawns `which`, and the answer does not change mid-scan.
+export async function ensureToolsStatus(force = false) {
+  if (state.tools.running) return state.tools.status;
+  if (state.tools.status && !force) return state.tools.status;
+  if (state.tools.loading) return state.tools.status;
+  state.tools.loading = true;
+  notify();
+  try {
+    const status = await fetchToolsStatus();
+    if (status) state.tools.status = status;
+  } finally {
+    state.tools.loading = false;
+    notify();
+  }
+  return state.tools.status;
+}
+
+// The per-engine option values the Configure panels hold, shaped for the API:
+// only engines that have a form contribute, and every run gets the full set —
+// the server picks out what its `tools`/`kinds` filter selected.
+function collectToolOptions() {
+  const out = {};
+  const status = state.tools.status || {};
+  for (const id of Object.keys(status)) {
+    if ((status[id].options || []).length) out[id] = state.tools.options[id] || {};
+  }
+  return out;
+}
+
+// Run the engines. `kinds` narrows by purpose (security / dead-code), `tools`
+// to named engines — the view offers all three scopes.
+//
+// The merge happens here rather than in either caller, so the grade can never
+// depend on which button was pressed. `mergeFindingsIntoScan` is idempotent
+// (it dedups on path+line+rule), so re-running a subset after a full run adds
+// nothing twice.
+export async function runDeepAnalysis(options = {}) {
+  if (state.tools.running) return null;
+  if (!state.scanId) return null;
+
+  state.tools.running = true;
+  state.tools.error = null;
+  notify();
+
+  try {
+    const report = await runAnalysisTools(state.scanId, { ...options, options: collectToolOptions() });
+    state.tools.report = report;
+    state.tools.findings = report.findings || [];
+    state.tools.merged = mergeFindingsIntoScan(state.scan, state.tools.findings);
+    state.security = summarizeSecurity(state.scan);
+    return report;
+  } catch (err) {
+    state.tools.error = err.message;
+    return null;
+  } finally {
+    state.tools.running = false;
+    notify();
+  }
+}
+
+// Install a missing engine without leaving the GUI. The server streams log
+// lines, which collect on `state.tools.install[id]` so both surfaces can show
+// a live console; on success the status is re-fetched (the install cleared
+// the server's detection cache) and the card flips from "not installed" to
+// "ready" without a restart.
+export async function installEngine(id) {
+  const entry = state.tools.install[id];
+  if (entry && entry.running) return null;
+  state.tools.install[id] = { running: true, log: [], ok: null, error: null };
+  notify();
+
+  try {
+    const done = await streamToolInstall(id, (event) => {
+      const slot = state.tools.install[id];
+      if (event.type === 'log') slot.log.push(event.line);
+      if (slot.log.length > 400) slot.log.splice(0, slot.log.length - 400);
+      notify();
+    });
+    const slot = state.tools.install[id];
+    slot.running = false;
+    slot.ok = !!done.ok;
+    slot.error = done.ok ? null : (done.error || 'The install did not finish.');
+    if (done.ok) await ensureToolsStatus(true);
+    notify();
+    return done;
+  } catch (err) {
+    state.tools.install[id] = { running: false, log: state.tools.install[id].log, ok: false, error: err.message };
+    notify();
+    return null;
+  }
+}
+
+// A sentence for whoever pressed the button. Kept out of the store proper —
+// toasting is the caller's business, and the store has no hooks.
+export function runOutcomeMessage(report) {
+  if (!report) return 'Deep analysis did not finish.';
+  if (!report.ranCount) {
+    return report.unavailable && report.unavailable.length
+      ? 'No engine is installed — see the list for what to install.'
+      : 'No engine managed to run.';
+  }
+  const n = (report.findings || []).length;
+  return `${report.ranCount} engine${report.ranCount === 1 ? '' : 's'} ran — ${n} finding${n === 1 ? '' : 's'} merged.`;
+}
+
+// ---- the inspector panel ---------------------------------------------------
+
+let host = null;
+let hooks = { onToast: () => {}, onOpenFile: () => {} };
+
+export function initAnalysisPanel(options) {
+  host = options.host;
+  hooks = { ...hooks, ...options };
+
+  host.addEventListener('click', (event) => {
+    const install = event.target.closest('[data-engine-install]');
+    if (install) {
+      installEngine(install.dataset.engineInstall).then((done) => {
+        if (done && done.ok) hooks.onToast(`${install.dataset.engineInstall} installed — it is ready to run.`);
+        else if (done && done.error) hooks.onToast(done.error);
+      });
+      return;
+    }
+    const run = event.target.closest('[data-run-tools]');
+    if (run) {
+      const scope = run.dataset.runTools;
+      runTools(scope ? { tools: [scope] } : {});
+      return;
+    }
+    const kind = event.target.closest('[data-run-kind]');
+    if (kind) runTools({ kinds: [kind.dataset.runKind] });
+  });
+
+  subscribeAnalysis(() => paint());
+}
+
+async function runTools(options) {
+  const report = await runDeepAnalysis(options);
+  hooks.onToast(runOutcomeMessage(report));
+}
+
+// Renders into the security view's inspector. Also the place the "not a
+// server-side scan" case is explained, since that is a property of the repo.
+export function renderAnalysisPanel() {
+  if (!host) return;
+  if (!state.scanId) {
+    host.innerHTML = `<div class="tools-note">Deep analysis runs on a scanned folder or clone. A folder picked in the browser never leaves this tab, so there is nothing on the server for an external engine to read — the built-in scan is the whole story for this repo.</div>`;
+    return;
+  }
+  if (!state.tools.status && !state.tools.loading) void ensureToolsStatus();
+  paint();
+}
+
+// The panel is the summary; the Deep Analysis view is where you go to read the
+// whole report. So this stays tight: the engines, one button, and an outcome
+// line — no findings table here.
+function paint() {
+  if (!host) return;
+  const { status, report, running, loading, error } = state.tools;
+  const rows = engineRows(status, report);
+
+  const head = `<div class="tools-head">
+    <h4>Deep analysis <span class="tools-sub">external engines</span></h4>
+    <button class="btn btn-ghost tools-run" data-run-tools ${running ? 'disabled' : ''}>
+      ${running ? 'Running…' : 'Run deep analysis'}
+    </button>
+  </div>`;
+
+  let body = '';
+  if (error) body += `<div class="tools-err">${escapeHtml(error)}</div>`;
+
+  if (!rows.length) {
+    body += `<div class="tools-note">${loading ? 'Checking which engines are available…' : 'No engine table yet.'}</div>`;
+  } else {
+    body += '<ul class="tools-list">' + rows.map(engineCard).join('') + '</ul>';
+  }
+
+  const summary = engineSummary(report, rows);
+  if (report || rows.length) {
+    body += `<div class="tools-summary is-${escapeHtml(summary.tone)}">${escapeHtml(summary.text)}</div>`;
+  }
+
+  if (rows.some((r) => r.ran)) {
+    body += '<div class="tools-more">Every finding, with links to the file and line, is in the <b>Deep Analysis</b> tab.</div>';
+  }
+
+  host.innerHTML = head + body;
+}
+
+// One engine card. The badge is the whole story at a glance: did it run, what
+// did it find, and if it could not run, why not. A missing engine gets an
+// Install button — the person stays in the GUI, and the log lands in the Deep
+// Analysis view's console.
+function engineCard(engine) {
+  const installing = state.tools.install[engine.id];
+  let badge;
+  if (installing && installing.running) badge = '<span class="tools-badge is-running">installing…</span>';
+  else if (!engine.available) badge = '<span class="tools-badge is-missing">not installed</span>';
+  else if (state.tools.running) badge = '<span class="tools-badge is-running">running…</span>';
+  else if (engine.ran) badge = `<span class="tools-badge is-ran">${engine.findings} · ${engine.ms}ms</span>`;
+  else if (engine.failed) badge = '<span class="tools-badge is-failed">failed</span>';
+  else badge = `<span class="tools-badge is-ready">ready${engine.how ? ' · ' + escapeHtml(engine.how) : ''}</span>`;
+
+  const note = !engine.available && engine.reason
+    ? `<span class="tools-reason">${escapeHtml(engine.reason)}</span>`
+    : (engine.failure ? `<span class="tools-reason">${escapeHtml(engine.failure)}</span>` : '');
+
+  const installBtn = !engine.available && engine.installable
+    ? `<button class="btn btn-ghost btn-sm" data-engine-install="${escapeHtml(engine.id)}" ${installing && installing.running ? 'disabled' : ''}>${installing && installing.running ? 'Installing…' : 'Install'}</button>`
+    : '';
+
+  return `<li class="tools-item${engine.available ? '' : ' is-missing'}">
+    <div class="tools-item-main">
+      <span class="tools-name">${escapeHtml(engine.label)}</span>
+      ${badge}
+      ${installBtn}
+      <span class="tools-purpose">${escapeHtml(engine.purpose)}</span>
+    </div>
+    ${note}
+  </li>`;
+}
+

package/public/js/analysisReport.js

@@ -0,0 +1,154 @@
+// Shaping an analysis report for the Deep Analysis view — pure, DOM-free, and
+// therefore testable in Node.
+//
+// Three questions get answered here, and nowhere else:
+//
+//   * What findings do we actually have? The built-in scanner's findings live
+//     under `security.files[].findings`; the external engines' findings are
+//     merged into the same place, tagged `source: 'external'`. Flattening them
+//     into rows is the only place that difference is spelled out, so every view
+//     downstream can stop caring which engine answered.
+//   * What is the shape of the report? Counts by severity, by tool and by
+//     category are what the header chips and the AI prompt both run on.
+//   * What survives a filter? Severity, engine and free text, applied as one
+//     predicate so the counts above and the table below can never disagree
+//     about what is being shown.
+
+export const SEV_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
+
+export function sevRank(severity) {
+  const at = SEV_ORDER.indexOf(severity);
+  return at === -1 ? SEV_ORDER.length : at;
+}
+
+export const BUILTIN_TOOL = 'built-in';
+
+// One flat list of findings, worst first. `security` is the roll-up from
+// `summarizeSecurity`, which is also what the Security panel draws.
+export function findingsFromSecurity(security) {
+  const rows = [];
+  // The parenthesised default is hoisted rather than inlined: `for (const x of
+  // (a || []))` reads as a call to a function named `of` to the front end's
+  // dangling-call lint, and the lint is right to be suspicious of that shape.
+  const files = (security && security.files) || [];
+  for (const file of files) {
+    for (const finding of file.findings || []) {
+      rows.push({
+        path: file.path,
+        name: file.name || String(file.path || '').split('/').pop(),
+        line: finding.line || 1,
+        severity: SEV_ORDER.includes(finding.severity) ? finding.severity : 'info',
+        rule: finding.rule || 'unknown',
+        category: finding.category || 'other',
+        message: finding.message || '',
+        excerpt: finding.excerpt || '',
+        tool: finding.source === 'external' ? (finding.tool || 'external') : BUILTIN_TOOL,
+      });
+    }
+  }
+  return rows.sort((a, b) => sevRank(a.severity) - sevRank(b.severity)
+    || a.path.localeCompare(b.path)
+    || a.line - b.line);
+}
+
+// Counts for the header and the prompt. `external` vs `builtin` is kept because
+// "the built-in regex scanner said so" and "Semgrep said so" carry different
+// weight, and the UI should be able to say which.
+export function tabulate(rows) {
+  const bySeverity = {};
+  const byTool = {};
+  const byCategory = {};
+  for (const row of rows) {
+    bySeverity[row.severity] = (bySeverity[row.severity] || 0) + 1;
+    byTool[row.tool] = (byTool[row.tool] || 0) + 1;
+    byCategory[row.category] = (byCategory[row.category] || 0) + 1;
+  }
+  const external = rows.filter((r) => r.tool !== BUILTIN_TOOL).length;
+  return {
+    total: rows.length,
+    bySeverity,
+    byTool,
+    byCategory,
+    external,
+    builtin: rows.length - external,
+    critical: bySeverity.critical || 0,
+    high: bySeverity.high || 0,
+    medium: bySeverity.medium || 0,
+    low: (bySeverity.low || 0) + (bySeverity.info || 0),
+  };
+}
+
+// The filter is one predicate over three independent axes. `all` on an axis
+// means "do not filter on this", which is why the default object is usable as-is.
+export function filterFindings(rows, { severity = 'all', tool = 'all', q = '' } = {}) {
+  const needle = String(q || '').trim().toLowerCase();
+  return rows.filter((row) => {
+    if (severity !== 'all' && row.severity !== severity) return false;
+    if (tool !== 'all' && row.tool !== tool) return false;
+    if (!needle) return true;
+    return row.path.toLowerCase().includes(needle)
+      || row.message.toLowerCase().includes(needle)
+      || row.rule.toLowerCase().includes(needle)
+      || row.category.toLowerCase().includes(needle);
+  });
+}
+
+// The engine table: what each tool is, whether it is installed, and what it did
+// last time it ran. `status` comes from `GET /api/tools`, `report` from the last
+// `POST /api/tools/run` — they are joined here so the view has one list to draw
+// instead of two to reconcile.
+export function engineRows(status, report) {
+  const passes = (report && report.passes) || [];
+  return Object.keys(status || {}).map((id) => {
+    const meta = status[id] || {};
+    const pass = passes.find((p) => p.id === id) || null;
+    return {
+      id,
+      label: meta.label || id,
+      kind: meta.kind || 'security',
+      purpose: meta.purpose || '',
+      available: !!meta.available,
+      how: meta.how || null,
+      reason: meta.reason || null,
+      // The option schema and its defaults, for the Configure form; `installable`
+      // is whether the server knows how to install this engine from the GUI.
+      options: Array.isArray(meta.options) ? meta.options : [],
+      defaults: meta.defaults || {},
+      installable: meta.installable !== false,
+      ran: !!(pass && pass.ok),
+      failed: !!(pass && !pass.ok && pass.available),
+      findings: pass && pass.ok ? (pass.findings || []).length : 0,
+      ms: pass && pass.ok ? pass.ms : null,
+      failure: pass && !pass.ok && pass.available ? pass.reason : null,
+    };
+  });
+}
+
+// The one-line verdict under the engine list. Written here rather than in the
+// view because "nothing ran" and "nothing found" must never be confused, and
+// that distinction is the whole point of the panel.
+export function engineSummary(report, rows) {
+  if (!report) {
+    return { tone: 'idle', text: 'No run yet. The built-in scanner is the whole story until you run an engine.' };
+  }
+  const ran = rows.filter((r) => r.ran).length;
+  const missing = rows.filter((r) => !r.available).length;
+  const failed = rows.filter((r) => r.failed).length;
+
+  if (!ran) {
+    return {
+      tone: 'none',
+      text: missing === rows.length && rows.length
+        ? 'No engine is installed on this machine. Install any of the ones below and run again — the built-in scan still stands.'
+        : 'No engine managed to run. The reasons are listed above.',
+    };
+  }
+
+  const findings = (report.findings || []).length;
+  const parts = [`${ran} of ${rows.length} engines ran in ${report.ms}ms`];
+  parts.push(findings ? `${findings} finding${findings === 1 ? '' : 's'} came back` : 'none of them found anything');
+  if (failed) parts.push(`${failed} failed`);
+  if (missing) parts.push(`${missing} not installed`);
+  return { tone: findings ? 'found' : 'clean', text: parts.join(' · ') + '.' };
+}
+

package/public/js/api.js

@@ -0,0 +1,264 @@
+// Server round-trips. Thin and honest: JSON in, JSON (or an SSE stream) out,
+// server error messages surfaced untouched.
+
+// ---------------------------------------------------------------- access key --
+//
+// A self-hosted server gates every API route behind a Bearer key. The browser
+// learns it one of two ways: the startup banner links here with `?key=…` in
+// the URL (adopted once, then stripped so it does not linger in history), or
+// the person pastes it into the Server drawer. Either way it lives in
+// localStorage and rides along as an Authorization header from then on. Local
+// mode ignores the header entirely, so sending it is harmless.
+
+const ACCESS_KEY_STORAGE = 'onboarder.accessKey';
+
+let urlKeyChecked = false;
+
+// Lazy on purpose, and a function declaration for the same reason: running
+// this at import would touch `window`, and the front-end test suite requires
+// every module to be importable from Node. The first API call is still early
+// enough — the key is adopted before any request leaves.
+function adoptKeyFromUrl() {
+  if (urlKeyChecked) return;
+  urlKeyChecked = true;
+  try {
+    const url = new URL(window.location.href);
+    const key = url.searchParams.get('key');
+    if (!key) return;
+    localStorage.setItem(ACCESS_KEY_STORAGE, key);
+    url.searchParams.delete('key');
+    window.history.replaceState(null, '', url);
+  } catch {
+    /* no usable URL API — the drawer can still take the key by hand */
+  }
+}
+
+export function getAccessKey() {
+  adoptKeyFromUrl();
+  return localStorage.getItem(ACCESS_KEY_STORAGE) || '';
+}
+
+export function setAccessKey(key) {
+  const trimmed = String(key || '').trim();
+  if (trimmed) localStorage.setItem(ACCESS_KEY_STORAGE, trimmed);
+  else localStorage.removeItem(ACCESS_KEY_STORAGE);
+}
+
+function authHeaders() {
+  const key = getAccessKey();
+  return key ? { authorization: `Bearer ${key}` } : {};
+}
+
+async function postJSON(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...authHeaders() },
+    body: JSON.stringify(body),
+  });
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    /* error path handled below with a generic message */
+  }
+  if (!res.ok) {
+    throw new Error(data?.error || `The server said ${res.status}.`);
+  }
+  return data;
+}
+
+export function scanOnServer(payload) {
+  return postJSON('/api/scan', payload);
+}
+
+export async function cleanupClone(cloneId) {
+  try {
+    await fetch('/api/scan/' + encodeURIComponent(cloneId), { method: 'DELETE', headers: authHeaders() });
+  } catch {
+    /* best-effort: the temp dir expires on its own eventually */
+  }
+}
+
+export async function fetchFileText(scanId, path) {
+  const res = await fetch('/api/file?scan=' + encodeURIComponent(scanId) + '&path=' + encodeURIComponent(path), { headers: authHeaders() });
+  if (!res.ok) throw new Error('Could not read that file from the server.');
+  return res.text();
+}
+
+// Which deep analyzers this machine can run, and how. Server-side scans only —
+// a browser-picked folder has no scan id and no server-visible root to point a
+// tool at, and this returns that honestly instead of pretending.
+export async function fetchToolsStatus() {
+  try {
+    const res = await fetch('/api/tools', { headers: authHeaders() });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data && data.tools ? data.tools : null;
+  } catch {
+    return null; // an unreachable server is just "no deep analysis here"
+  }
+}
+
+// Run the available analyzers against a live scan. `kinds`/`tools` narrow which
+// engines run; `options` carries the per-engine GUI settings, validated against
+// the registry schema on the server. The report normalizes every finding into
+// the shape the security view already draws, plus a per-engine pass list so
+// the UI can say which tool answered and which are missing.
+export function runAnalysisTools(scanId, options = {}) {
+  return postJSON('/api/tools/run', {
+    scanId,
+    kinds: options.kinds || undefined,
+    tools: options.tools || undefined,
+    options: options.options || undefined,
+  });
+}
+
+// Install a missing engine, streaming progress events. The server emits SSE
+// frames shaped like the explain stream, minus the OpenAI envelope:
+//   { type: 'log', line } / { type: 'plan', label } / { type: 'done', ok, … }
+// `onEvent` gets each one as it arrives; the promise resolves with the final
+// `done` event (or throws if the request itself failed).
+export async function streamToolInstall(tool, onEvent) {
+  const emit = typeof onEvent === 'function' ? onEvent : () => {};
+  const res = await fetch('/api/tools/install', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...authHeaders() },
+    body: JSON.stringify({ tool }),
+  });
+  if (!res.ok || !res.body) {
+    let detail = '';
+    try { detail = (await res.json()).error || ''; } catch { /* generic below */ }
+    throw new Error(detail || `The server said ${res.status}.`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let done = null;
+  while (true) {
+    const { done: ended, value } = await reader.read();
+    if (ended) break;
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split('\n\n');
+    buffer = frames.pop();
+    for (const frame of frames) {
+      for (const line of frame.split('\n')) {
+        if (!line.startsWith('data:')) continue;
+        try {
+          const event = JSON.parse(line.slice(5).trim());
+          emit(event);
+          if (event.type === 'done') done = event;
+        } catch { /* a partial frame — the next chunk completes it */ }
+      }
+    }
+  }
+  return done || { type: 'done', ok: false, error: 'The install stream ended without a verdict.' };
+}
+
+// The MCP button's three round-trips. The status one is a plain GET like
+// `/api/tools`; start and stop are POSTs because each one changes a process on
+// this machine, which is exactly the side effect `postJSON` is here for.
+export async function fetchMcpStatus() {
+  try {
+    const res = await fetch('/api/mcp', { headers: authHeaders() });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null; // no server means no button state, not an error to shout about
+  }
+}
+
+export function startMcpServer() {
+  return postJSON('/api/mcp/start', {});
+}
+
+export function stopMcpServer() {
+  return postJSON('/api/mcp/stop', {});
+}
+
+// The command an agent harness is configured with. Kept separate from the status
+// fetch because it never changes, so it is read once when the panel opens rather
+// than on every poll.
+export async function fetchMcpCommand() {
+  try {
+    const res = await fetch('/api/mcp/command', { headers: authHeaders() });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+// Streams an OpenAI-compatible chat completion through the local proxy.
+// Yields text deltas as they arrive; throws with the provider's message on
+// a non-200 from upstream.
+export async function* streamExplain({ baseUrl, apiKey, model, messages, maxTokens = 1200, providerOptions = {} }) {
+  const res = await fetch('/api/explain', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...authHeaders() },
+    body: JSON.stringify({ baseUrl, apiKey, model, messages, stream: true, max_tokens: maxTokens, ...providerOptions }),
+  });
+
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const data = await res.json();
+      detail = data.detail || data.error || '';
+    } catch {
+      /* keep the generic line */
+    }
+    throw new Error(detail || `The provider said ${res.status}.`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split('\n\n');
+    buffer = frames.pop();
+    for (const frame of frames) {
+      for (const line of frame.split('\n')) {
+        if (!line.startsWith('data:')) continue;
+        const payload = line.slice(5).trim();
+        if (payload === '[DONE]') return;
+        try {
+          const json = JSON.parse(payload);
+          const delta = json.choices?.[0]?.delta?.content;
+          if (delta) yield delta;
+        } catch {
+          /* a partial JSON frame — the next chunk completes it */
+        }
+      }
+    }
+  }
+}
+
+// The Server drawer's three round-trips. The read is a GET that comes back
+// with the secret masked; writes go through PUT with only the changed keys;
+// rotation is a POST because it mints a new key on the server — the one and
+// only time a key ever crosses the wire in the clear.
+export async function fetchServerSettings() {
+  const res = await fetch('/api/settings', { headers: authHeaders() });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) throw new Error(data?.error || `The server said ${res.status}.`);
+  return data;
+}
+
+export async function updateServerSettings(patch) {
+  const res = await fetch('/api/settings', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json', ...authHeaders() },
+    body: JSON.stringify(patch),
+  });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) throw new Error(data?.error || `The server said ${res.status}.`);
+  return data;
+}
+
+export function rotateServerAccessKey() {
+  return postJSON('/api/settings/access-key', {});
+}
+