codebase-onboarder 0.1.0

package/server/tools/registry.js

@@ -0,0 +1,212 @@
+// The registry: what each engine is for, where to find it, and how to run it.
+//
+// This is data, deliberately — the engine in `tools.js` walks it and asserts
+// every entry is well-formed, and the UI renders it as the "available tools"
+// list. A new analyzer is a new entry here and a new parser in `parse.js`;
+// nothing else should have to know about it.
+
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  parseDepcheck, parseGitleaks, parseKnip, parseSemgrep, parseVulture,
+} from './parse.js';
+
+// `rel` turns a tool's absolute path into the repo-relative path the whole app
+// uses. Tools report paths rooted wherever they ran from.
+const makeRel = (root) => (p) => {
+  const s = String(p || '');
+  const win = s.startsWith(root + '\\') ? s.slice(root.length + 1) : null;
+  if (win) return win.replace(/\\/g, '/');
+  return s.startsWith(root + '/') ? s.slice(root.length + 1) : s.replace(/^[/\\]+/, '');
+};
+
+// Gitleaks writes its JSON to a *file* (`--report-path`); the old code pointed
+// that at `/dev/stdout`, a path Windows does not have. Every run gets a real
+// temp file instead, which `scan.js` reads and removes afterwards.
+function defaultReportPath() {
+  return path.join(os.tmpdir(), `onboarder-gitleaks-${process.pid}.json`);
+}
+
+// The options schema is data for two consumers. The GUI renders it as a small
+// per-engine form (select, checkbox, number) so a person can use what each
+// tool actually offers without a terminal; the server's `sanitizeOptions`
+// walks the same list and drops anything else, so an option the registry does
+// not declare can never reach a command line.
+
+export const TOOL_DEFS = [
+  {
+    id: 'semgrep',
+    label: 'Semgrep',
+    kind: 'security',
+    purpose: 'Deep static analysis — injection, crypto, auth — across 30+ languages.',
+    commands: [
+      { kind: 'direct', bin: 'semgrep' },
+      { kind: 'direct', bin: 'opengrep' }, // the OSS fork, drop-in compatible
+      { kind: 'uvx', pkg: 'semgrep', bin: 'semgrep' },
+    ],
+    install: ['Install with: pip install semgrep  (or: brew install semgrep, or uv tool install semgrep).'],
+    options: [
+      {
+        key: 'config', label: 'Rule set', type: 'enum',
+        values: ['p/default', 'p/security-audit', 'p/secrets', 'p/ci', 'auto'],
+        default: 'p/default',
+        hint: '“auto” downloads the recommended set — it needs network access.',
+      },
+      {
+        key: 'severity', label: 'Minimum severity', type: 'enum',
+        values: ['all', 'WARNING', 'ERROR'],
+        default: 'all',
+        hint: 'ERROR only keeps the findings Semgrep itself calls errors.',
+      },
+    ],
+    // `--config auto` needs network; the offline path is `--config p/default`.
+    // We run offline by default: self-host means the box may not be online.
+    argv: (root, options = {}) => {
+      const args = ['scan', '--json', '--quiet', '--no-git-ignore', '--timeout', '60',
+        '--config', options.config || 'p/default'];
+      if (options.severity === 'WARNING') args.push('--severity', 'WARNING', '--severity', 'ERROR');
+      if (options.severity === 'ERROR') args.push('--severity', 'ERROR');
+      args.push(root);
+      return args;
+    },
+    parse: (text, root) => parseSemgrep(JSON.parse(text), makeRel(root)),
+  },
+  {
+    id: 'gitleaks',
+    label: 'Gitleaks',
+    kind: 'security',
+    purpose: 'Secrets — committed keys, tokens, private keys.',
+    commands: [{ kind: 'direct', bin: 'gitleaks' }],
+    install: ['Install with: brew install gitleaks  (or download the binary from its GitHub releases).'],
+    options: [
+      {
+        key: 'history', label: 'Scan git history too', type: 'boolean',
+        default: false,
+        hint: 'Slower, but finds secrets that were committed and later deleted.',
+      },
+      {
+        key: 'redact', label: 'Redact secrets in output', type: 'boolean',
+        default: true,
+        hint: 'The parser never relays a secret either way; this hides it in the raw report too.',
+      },
+    ],
+    usesReportFile: true,
+    argv: (root, options = {}, ctx = {}) => {
+      const args = ['detect', '--source', root,
+        '--report-format', 'json', '--report-path', ctx.reportPath || defaultReportPath(),
+        '--exit-code', '0'];
+      if (!options.history) args.push('--no-git');
+      if (options.redact !== false) args.push('--redact');
+      return args;
+    },
+    parse: (text, root) => parseGitleaks(JSON.parse(text), makeRel(root)),
+  },
+  {
+    id: 'knip',
+    label: 'Knip',
+    kind: 'dead-code',
+    purpose: 'Dead code for JS/TS — unused files, exports and dependencies.',
+    commands: [
+      { kind: 'direct', bin: 'knip' },
+      { kind: 'npx', pkg: 'knip' },
+    ],
+    install: ['Install with: npm install -g knip  (or run it through npx, which this will do for you).'],
+    options: [
+      {
+        key: 'include', label: 'Issue types', type: 'multi',
+        values: ['files', 'dependencies', 'exports', 'types', 'duplicates'],
+        default: [],
+        hint: 'Nothing checked means Knip reports every kind it knows.',
+      },
+    ],
+    argv: (root, options = {}) => {
+      const args = ['--reporter', 'json', '--directory', root, '--no-progress'];
+      const include = Array.isArray(options.include) ? options.include.filter(Boolean) : [];
+      if (include.length) args.push('--include', include.join(','));
+      return args;
+    },
+    parse: (text, root) => parseKnip(JSON.parse(text), makeRel(root)),
+  },
+  {
+    id: 'vulture',
+    label: 'Vulture',
+    kind: 'dead-code',
+    purpose: 'Dead code for Python — unused functions, classes, variables.',
+    commands: [
+      { kind: 'direct', bin: 'vulture' },
+      { kind: 'uvx', pkg: 'vulture', bin: 'vulture' },
+    ],
+    install: ['Install with: pip install vulture  (or run it through uvx, which this will do for you).'],
+    options: [
+      {
+        key: 'minConfidence', label: 'Minimum confidence (%)', type: 'number',
+        min: 1, max: 100, default: 60,
+        hint: 'Lower finds more, and guesses more. 60 is Vulture’s own default.',
+      },
+    ],
+    argv: (root, options = {}) => {
+      const n = Number(options.minConfidence);
+      const confidence = Number.isFinite(n) ? Math.min(100, Math.max(1, Math.round(n))) : 60;
+      return [root, '--min-confidence', String(confidence)];
+    },
+    parse: (text, root) => parseVulture(text, makeRel(root)),
+    textOutput: true,
+  },
+  {
+    id: 'depcheck',
+    label: 'Depcheck',
+    kind: 'dead-code',
+    purpose: 'Unused npm dependencies (a narrower, faster slice of Knip).',
+    commands: [
+      { kind: 'direct', bin: 'depcheck' },
+      { kind: 'npx', pkg: 'depcheck' },
+    ],
+    install: ['Install with: npm install -g depcheck  (or run it through npx).'],
+    options: [
+      {
+        key: 'skipMissing', label: 'Skip “missing from package.json” reports', type: 'boolean',
+        default: false,
+        hint: 'Useful when imports are resolved by a bundler depcheck cannot see.',
+      },
+    ],
+    argv: (root, options = {}) => {
+      const args = ['--json'];
+      if (options.skipMissing) args.push('--skip-missing=true');
+      return args;
+    },
+    cwd: true, // depcheck reads the package.json in its working directory
+    parse: (text) => parseDepcheck(JSON.parse(text)),
+  },
+];
+
+// Turn a raw `options` object from a request body into one the registry
+// trusts: only declared keys, values coerced to the declared type, enum and
+// multi values restricted to the declared lists. Anything else falls back to
+// the default — the GUI sends well-formed values, and anything else is noise.
+export function sanitizeOptions(def, raw) {
+  const clean = {};
+  const input = raw && typeof raw === 'object' ? raw : {};
+  for (const opt of def.options || []) {
+    const value = input[opt.key];
+    if (opt.type === 'boolean') {
+      clean[opt.key] = value === undefined ? opt.default : Boolean(value);
+    } else if (opt.type === 'enum') {
+      clean[opt.key] = opt.values.includes(value) ? value : opt.default;
+    } else if (opt.type === 'multi') {
+      clean[opt.key] = Array.isArray(value) ? value.filter((v) => opt.values.includes(v)) : [...opt.default];
+    } else if (opt.type === 'number') {
+      const n = Number(value);
+      clean[opt.key] = Number.isFinite(n)
+        ? Math.min(opt.max, Math.max(opt.min, Math.round(n)))
+        : opt.default;
+    }
+  }
+  return clean;
+}
+
+// The schema with every default filled in — what the GUI renders before the
+// person touches anything.
+export function defaultOptions(def) {
+  return sanitizeOptions(def, {});
+}

package/server/tools/scan.js

@@ -0,0 +1,136 @@
+// The orchestrator: detect what is on the machine, run each available analyzer
+// against the scanned root, and hand back one normalized report.
+//
+// Two promises drive the shape. First, detection is *honest*: the report always
+// lists every tool and whether it ran, so "no security issues" and "no security
+// tool installed" are never the same sentence. Second, failure is *local*: a
+// tool that hangs, crashes or prints garbage fails its own pass and nothing
+// else — the scan the person asked for already succeeded, and this is a bonus
+// layer over it, exactly the way `collectHistory` treats git.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { emptyPass, runTool, toolArgv, TOOL_TIMEOUT_MS } from '../tools.js';
+import { defaultOptions, sanitizeOptions, TOOL_DEFS } from './registry.js';
+import { mergeFindings } from './parse.js';
+
+// What is installed, for the UI's "engines" panel. Detection is cached by
+// `which`, so asking is cheap. The payload also carries each tool's option
+// schema and defaults, so the GUI can render a form for what the engine
+// actually offers without hard-coding a flag anywhere in the front end.
+export function toolsStatus() {
+  const out = {};
+  for (const def of TOOL_DEFS) {
+    const resolved = toolArgv(def, '.');
+    out[def.id] = {
+      id: def.id,
+      label: def.label,
+      kind: def.kind,
+      purpose: def.purpose,
+      available: !!resolved,
+      how: resolved ? resolved.how : null,
+      command: resolved ? resolved.display : null,
+      reason: resolved ? null : unavailableReason(def),
+      options: def.options || [],
+      defaults: defaultOptions(def),
+      installable: true,
+      platform: process.platform,
+    };
+  }
+  return out;
+}
+
+function unavailableReason(def) {
+  return (def.install && def.install.length) ? def.install.join(' ') : 'Not found on PATH.';
+}
+
+async function runOneTool(def, root, toolOptions = {}) {
+  // A tool that reports through a file (gitleaks) gets a per-run temp path —
+  // never /dev/stdout, which does not exist on Windows, and never a fixed
+  // name, so two concurrent runs cannot read each other's report.
+  const ctx = {};
+  if (def.usesReportFile) {
+    ctx.reportPath = path.join(os.tmpdir(), `onboarder-${def.id}-${Date.now()}-${Math.floor(Math.random() * 1e6)}.json`);
+  }
+
+  const resolved = toolArgv(def, root, toolOptions, ctx);
+  if (!resolved) {
+    return emptyPass(def.id, def.label, unavailableReason(def));
+  }
+
+  const started = Date.now();
+  const result = await runTool(resolved.argv, {
+    cwd: def.cwd ? root : undefined,
+    timeout: TOOL_TIMEOUT_MS,
+  });
+
+  // Read and remove the report file whatever happened above.
+  let reportText = null;
+  if (ctx.reportPath) {
+    try {
+      reportText = fs.readFileSync(ctx.reportPath, 'utf8');
+    } catch {
+      reportText = null; // a crashed tool may never have written it
+    }
+    try { fs.unlinkSync(ctx.reportPath); } catch { /* already gone */ }
+  }
+
+  if (result.timedOut) return { ...emptyPass(def.id, def.label, result.error), available: true };
+  if (!result.ok) {
+    return { ...emptyPass(def.id, def.label, result.error || 'The tool could not be run.'), available: true };
+  }
+
+  const stdout = (def.usesReportFile ? (reportText || '') : (result.stdout || '')).trim();
+  if (!stdout) {
+    // A clean pass: the tool ran and found nothing. That is a real answer, and
+    // worth saying — "Gitleaks: no secrets" is the outcome a self-hosting user
+    // runs the tool to hear.
+    return passResult(def, resolved, [], started);
+  }
+
+  try {
+    const findings = def.parse(stdout, root);
+    return passResult(def, resolved, findings, started);
+  } catch (err) {
+    return { ...emptyPass(def.id, def.label, 'Its output could not be read: ' + err.message), available: true };
+  }
+}
+
+function passResult(def, resolved, findings, started) {
+  return {
+    id: def.id, label: def.label, kind: def.kind, ok: true, available: true,
+    findings, source: 'external', tool: def.id, how: resolved.how, ms: Date.now() - started,
+  };
+}
+
+// Tools run concurrently — a scan is I/O-bound and the analyzers are
+// independent — but a repo with zero analyzers still gets a well-formed report,
+// so the frontend renders the built-in floor and the "what to install" list.
+// `kinds` narrows by purpose, `tools` narrows to named engines; both exist so
+// the UI can offer "run just the secrets scan" as readily as "run everything".
+// `options` is per-engine GUI settings, sanitized against the registry schema
+// before any of it touches a command line.
+export async function runExternalAnalysis(root, options = {}) {
+  const kinds = options.kinds ? new Set(options.kinds) : null;
+  const tools = options.tools ? new Set(options.tools) : null;
+  const rawOptions = options.options && typeof options.options === 'object' ? options.options : {};
+  const defs = TOOL_DEFS.filter((d) => (!kinds || kinds.has(d.kind)) && (!tools || tools.has(d.id)));
+
+  const started = Date.now();
+  const passes = await Promise.all(defs.map((def) => runOneTool(def, root, sanitizeOptions(def, rawOptions[def.id]))));
+
+  const ran = passes.filter((p) => p.ok);
+  const findings = mergeFindings(...passes.map((p) => p.findings));
+
+  return {
+    ms: Date.now() - started,
+    passes,
+    findings,
+    ranCount: ran.length,
+    totalTools: defs.length,
+    unavailable: passes.filter((p) => !p.available).map((p) => ({ id: p.id, label: p.label, reason: p.reason })),
+    source: ran.length ? 'external' : 'none',
+  };
+}

package/server/tools.js

@@ -0,0 +1,212 @@
+// The deep-analysis engine: Onboarder becomes the frontend, and the sharpest
+// open-source analyzers become its backend.
+//
+// The idea, stated once: this tool's built-in scanner (`shared/analyzer/`) is
+// deliberately a *local, zero-dependency* pass — regex rules, import graphs,
+// metrics. It is honest about what it is. But the best answers to "is this
+// safe?" and "is this dead?" come from real engines: **Semgrep** and
+// **Gitleaks** for security, **Knip** / **Vulture** for dead code. Those are
+// command-line programs, which is exactly the right seam for a self-hosted,
+// zero-npm-dep project: we never import them, we *run* them, read their JSON
+// or SARIF, and normalize everything into one finding shape the UI already
+// knows how to draw.
+//
+// The rules that keep this self-host-first and safe:
+//
+//   * **Optional, always.** No tool is required. Every analyzer the engine
+//     detects is a bonus; every one it cannot find is a graceful absence, and
+//     the built-in scanner is the floor that never goes away. The scan payload
+//     reports `source: 'builtin'` or `'external'` per pass so the UI can say
+//     which engine answered, instead of pretending.
+//
+//   * **Detect, never install.** We look for tools on PATH (plus a few named
+//     fallbacks — `uvx`, `npx`, `opengrep` — the ways these tools are actually
+//     distributed) and report what is there. We do not download or `pip install`
+//     anything behind a scan; the person self-hosting this decides what to put
+//     on the machine.
+//
+//   * **Run, never eval.** Every tool is spawned with an argument array — never
+//     a shell — the same discipline `gitClone.js` uses, so a crafted path or a
+//     malicious filename becomes an argument, not a command. No tool output is
+//     ever executed; it is parsed as data.
+//
+//   * **Bounded.** A tool gets a hard timeout and a capped buffer. A hung or
+//     pathological analyzer fails that pass and nothing else; it cannot hold the
+//     server open.
+//
+// Each tool is a descriptor (`TOOL_DEFS`): how to find it, how to invoke it,
+// and how to turn its output into findings. `scan.js` (this folder) parses;
+// this file owns process lifecycle. `shared/` stays isomorphic — none of this
+// lives there, because none of it can run in a browser tab.
+
+import { spawn } from 'node:child_process';
+import { findOnPath, spawnArgv } from './tools/platform.js';
+
+// ---- the registry ----------------------------------------------------------
+//
+// What the engine can drive. `id` is the key the rest of the app talks about;
+// `commands` is the preference order for locating the binary. `invocation` and
+// `parse` are filled in by the per-tool modules so this file stays about
+// lifecycle, not dialects. The whole list is data, which is what lets a test
+// walk it and assert every tool is well-formed.
+
+export const TOOL_IDS = ['semgrep', 'gitleaks', 'knip', 'vulture', 'depcheck'];
+
+// Where a binary can come from. `direct` is a tool on PATH. `uvx` and `npx`
+// run a tool without a pre-installed binary, which is how a self-hosting user
+// who has neither semgrep nor a Python env still gets a run — the fallback is
+// declared, not hidden in a shell string. Detection goes through `findOnPath`
+// (PATH split + PATHEXT on Windows + the Onboarder bin dir), not the Unix
+// `which`, so the same code answers on macOS, Linux and Windows.
+const WHICH_CACHE = new Map();
+
+function which(cmd) {
+  if (WHICH_CACHE.has(cmd)) return WHICH_CACHE.get(cmd);
+  const found = findOnPath(cmd);
+  WHICH_CACHE.set(cmd, found);
+  return found;
+}
+
+// An install from the GUI changes what is on disk; the cache must forget, or
+// the engine would keep reporting "not installed" until a server restart.
+export function clearDetectionCache() {
+  WHICH_CACHE.clear();
+}
+
+// Does the runtime have a way to run a tool that is not installed? uvx ships
+// with `uv`, npx ships with npm; both can fetch-and-run. Detected once.
+export function detectRunners() {
+  return {
+    uvx: which('uvx'),
+    npx: which('npx'),
+  };
+}
+
+// What is actually on this machine, per tool. The UI reads this to grey out
+// what is unavailable and to say *why* — "install semgrep" beats silence.
+export function detectTools(defs) {
+  const runners = detectRunners();
+  const out = {};
+  for (const def of defs) {
+    const resolution = resolveTool(def, runners);
+    out[def.id] = {
+      id: def.id,
+      label: def.label,
+      purpose: def.purpose,
+      available: !!resolution,
+      how: resolution ? resolution.how : null,
+      command: resolution ? resolution.display : null,
+      reason: resolution ? null : unavailableReason(def, runners),
+    };
+  }
+  return out;
+}
+
+function unavailableReason(def, runners) {
+  const parts = def.install ? def.install : [];
+  if (!runners.uvx && !runners.npx) {
+    return parts.length
+      ? `Not found. ${parts.join(' ')}`
+      : 'Not found on PATH, and no uvx/npx to run it with.';
+  }
+  return parts.length ? `Not found. ${parts.join(' ')}` : 'Not found.';
+}
+
+// Prefer a real binary on PATH; fall back to a runner that can fetch it. The
+// returned `{ prefix }` is prepended to the tool's own arguments — a plain
+// array, never a string, so nothing reaches a shell.
+function resolveTool(def, runners) {
+  for (const cmd of def.commands) {
+    if (cmd.kind === 'direct') {
+      const found = which(cmd.bin);
+      // The absolute path, not the bare name: on Windows the suffix is how
+      // `spawnArgv` knows a shim needs cmd.exe, and `npm.cmd` on PATH is how
+      // knip and depcheck usually arrive there.
+      if (found) return { how: 'path', display: cmd.bin, prefix: [found] };
+    } else if (cmd.kind === 'uvx' && runners.uvx) {
+      return { how: 'uvx', display: `uvx ${cmd.pkg}`, prefix: [runners.uvx, '--from', cmd.pkg, cmd.bin] };
+    } else if (cmd.kind === 'npx' && runners.npx) {
+      return { how: 'npx', display: `npx ${cmd.pkg}`, prefix: [runners.npx, '--yes', cmd.pkg] };
+    }
+  }
+  return null;
+}
+
+// The full command line for a tool against a root, or null if it cannot be run.
+// Detection and spawning both go through this, so "available" can never mean a
+// command we then fail to build. `toolOptions` are the GUI-tunable settings the
+// registry declares; `ctx` carries run-time necessities like a report path for
+// tools that cannot write JSON to stdout on every platform (gitleaks).
+export function toolArgv(def, root, toolOptions = {}, ctx = {}) {
+  const resolution = resolveTool(def, detectRunners());
+  if (!resolution) return null;
+  return {
+    argv: [...resolution.prefix, ...def.argv(root, toolOptions, ctx)],
+    how: resolution.how,
+    display: resolution.display,
+  };
+}
+
+// ---- running ---------------------------------------------------------------
+
+export const TOOL_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+
+// Spawn a tool with an argument array and collect stdout. Deliberately mirrors
+// `gitClone.run`: no shell, a timeout, a capped buffer, and a settled promise
+// that resolves with whatever was captured — a non-zero exit from an analyzer
+// is information ("knip found dead code exits 1"), not an exception.
+// `spawnArgv` handles the one platform wrinkle: a `.cmd` shim (npm-installed
+// CLIs on Windows) may only run through cmd.exe, with the arguments quoted
+// into a single command string by the helper — never user-authored text.
+export function runTool(argv, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const timeout = options.timeout || TOOL_TIMEOUT_MS;
+  const { command, args } = spawnArgv(argv);
+
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: options.env });
+    } catch (err) {
+      resolve({ ok: false, status: -1, stdout: '', stderr: String(err && err.message || err), timedOut: false });
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (extra) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ status: child.exitCode, stdout, stderr, ...extra });
+    };
+
+    const cap = (chunk, into) => {
+      const next = into + chunk;
+      return next.length > MAX_OUTPUT_BYTES ? next.slice(0, MAX_OUTPUT_BYTES) : next;
+    };
+    child.stdout.on('data', (c) => { stdout = cap(c.toString(), stdout); });
+    child.stderr.on('data', (c) => { stderr = cap(c.toString(), stderr).slice(-4000); });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish({ ok: false, timedOut: true, error: `${argv[0]} took too long and was stopped.` });
+    }, timeout);
+
+    child.on('error', (err) => {
+      finish({ ok: false, timedOut: false, error: 'Could not run ' + argv[0] + ': ' + err.message });
+    });
+    child.on('close', () => finish({ ok: true, timedOut: false }));
+  });
+}
+
+// The contract every analyzer hands back: findings normalized to the shape the
+// built-in scanner already uses (`rule`, `severity`, `category`, `message`,
+// `line`, `excerpt`), plus a `source` so the UI can attribute them. A tool that
+// produced nothing parseable is an `ok:false` pass with a reason, never a crash.
+export function emptyPass(id, label, reason) {
+  return { id, label, ok: false, available: false, findings: [], reason, source: 'external', tool: id };
+}
+

package/server/tunnel.js

@@ -0,0 +1,92 @@
+// The two tunnels this server knows how to sit behind, and nothing else.
+//
+// A tunnel here is not a feature of the server — it is another program the
+// person runs that forwards a public name to our port. What this module owns
+// is everything we can honestly say about that arrangement: whether the tool
+// is installed, the exact command that would expose the current settings, and
+// the install hint for when it isn't. The CLI (`onboarder tunnel`) is what
+// actually spawns anything; the HTTP layer only ever reads this status.
+
+import { spawnSync } from 'node:child_process';
+
+import { isLoopbackHost, normalizeSettings } from './config.js';
+
+// `spawnSync` on a missing binary resolves with an ENOENT error rather than
+// throwing, which is exactly the signal we need. `--version` is a flag every
+// CLI here answers; anything that doesn't is treated as absent.
+export function findOnPath(name) {
+  try {
+    const res = spawnSync(name, ['--version'], { encoding: 'utf8', timeout: 5000 });
+    if (res.error) return { installed: false };
+    const first = String(res.stdout || res.stderr || '').trim().split('\n')[0] || '';
+    return { installed: true, version: first.slice(0, 120) };
+  } catch {
+    return { installed: false };
+  }
+}
+
+// The one address a tunnel should forward to. Tunnels always dial loopback —
+// that is what makes "loopback behind a tunnel" a safe self-hosted layout, so
+// even a 0.0.0.0 bind is proxied from 127.0.0.1.
+export function tunnelTarget(settings) {
+  const s = normalizeSettings(settings);
+  return `http://127.0.0.1:${s.port}`;
+}
+
+export function cloudflareCommand(settings) {
+  // A "quick tunnel": no account, no DNS edit, a random trycloudflare.com name
+  // that lives as long as the process. The named-tunnel route (a fixed domain
+  // on the person's own Cloudflare account) is a `cloudflared tunnel` setup of
+  // its own; the wizard says so rather than pretending one command covers both.
+  return `cloudflared tunnel --url ${tunnelTarget(settings)}`;
+}
+
+export function tailscaleCommand(settings) {
+  const s = normalizeSettings(settings);
+  // serve puts the machine's tailnet name (https://host.tailnet.ts.net) in
+  // front of the port, visible only to the tailnet. funnel would go further
+  // and publish it to the internet — mentioned, never run for you.
+  return `tailscale serve --bg --https=443 ${tunnelTarget(s)}`;
+}
+
+export function installHint(name) {
+  if (name === 'cloudflared') {
+    return process.platform === 'darwin'
+      ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'
+      : 'See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+  }
+  return process.platform === 'darwin'
+    ? 'brew install --cask tailscale  (or see https://tailscale.com/download)'
+    : 'See https://tailscale.com/download';
+}
+
+// The settings drawer's tunnel section and `onboarder doctor` both render this:
+// what is enabled, what is installed, and what to run. Never spawns anything.
+export function tunnelStatus(settings) {
+  const s = normalizeSettings(settings);
+  const cf = findOnPath('cloudflared');
+  const ts = findOnPath('tailscale');
+  return {
+    target: tunnelTarget(s),
+    cloudflare: {
+      enabled: s.tunnel.cloudflare,
+      installed: cf.installed,
+      version: cf.version || '',
+      command: cloudflareCommand(s),
+      install: cf.installed ? '' : installHint('cloudflared'),
+    },
+    tailscale: {
+      enabled: s.tunnel.tailscale,
+      installed: ts.installed,
+      version: ts.version || '',
+      command: tailscaleCommand(s),
+      install: ts.installed ? '' : installHint('tailscale'),
+    },
+    // A tunnel answering a bind the server refused is the classic misread of
+    // "self-hosted": the tunnel terminates TLS and dials loopback, so the bind
+    // stays 127.0.0.1. Worth one explicit line everywhere the status is shown.
+    note: isLoopbackHost(s.host)
+      ? 'Loopback bind — a tunnel is the right way to reach this server remotely.'
+      : 'Network bind — a tunnel is optional; the access key is not.',
+  };
+}