codebase-onboarder 0.3.0 → 0.4.0

package/server/http.js

@@ -37,8 +37,8 @@ export function readBody(req, limit = MAX_BODY_BYTES) {
   });
 }
 
-export function sendJSON(res, status, data) {
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+export function sendJSON(res, status, data, headers = {}) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });
   res.end(JSON.stringify(data));
 }
 

package/server/httpGuards.js

@@ -43,6 +43,7 @@ export function rebindingReason(req, extraHosts = []) {
   const name = hostnameOf(host);
   if (LOOPBACK_HOSTS.has(name)) return null;
   for (const extra of extraHosts) {
+    if (extra === 'ip:*' && net.isIP(name.replace(/^\[|\]$/g, '')) > 0) return null;
     if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;
     if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6) return null;
     if (extra.startsWith('*.')) {

package/server/index.js

@@ -23,7 +23,8 @@ import { createLogger } from './logger.js';
 import { createMcpRunner } from './mcp/runner.js';
 import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
 import { tunnelStatus } from './tunnel.js';
-import { pidIsAlive, readPidFile, removePidFile, writePidFile } from './pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, writePidFile, writeRunInfo, runInfoPath } from './pidfile.js';
+import { logPath } from './daemon.js';
 
 const logger = createLogger();
 
@@ -82,7 +83,7 @@ export function startupBanner(settings, { configFile } = {}) {
     }
   }
   if (settings.mode === 'self-hosted' && settings.accessKey) {
-    lines.push('  Browser this URL is opened with the access key automatically; the key is removed from the address bar.');
+    lines.push('  Remote browsers show an access-key sign-in page; the key is never put in the URL.');
   }
   if (settings.mode === 'self-hosted' && !settings.accessKey) {
     lines.push('  WARNING self-hosted with no access key — every API call is refused until one is set.');
@@ -164,20 +165,39 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     throw listenError(error, { host, port, pid: recorded && pidIsAlive(recorded) ? recorded : null });
   }
 
+  // The process record is optional by design, so each write is guarded on its
+  // own: a read-only config directory must not stop a server that has already
+  // bound its port, but a *programming* error here would otherwise be swallowed
+  // and look like "it started, but nothing recorded it".
+  try { writePidFile(configFile); } catch { /* read-only config dir */ }
+  // How this process was launched. `background` is a detached child with a log
+  // file; `startup` is one the OS supervisor started at login (also with a log
+  // file); anything else is a person typing `onboarder start` in a terminal.
+  const mode = process.env.ONBOARDER_LAUNCH || (process.env.ONBOARDER_BACKGROUND ? 'background' : 'foreground');
+  const logFile = mode === 'foreground' ? null : logPath(configFile);
   try {
-    writePidFile(configFile);
-    server.once('close', () => removePidFile(configFile));
-    process.once('exit', () => removePidFile(configFile));
-  } catch {
-    // The server is useful even when a read-only config directory cannot hold
-    // the optional process record; binding and serving are the real contract.
+    // Beside the pid: how this instance was launched and where its log goes, so
+    // `onboarder status` answers "how long has it been up, and how do I see its
+    // output" from a record instead of guessing.
+    writeRunInfo(configFile, {
+      mode,
+      host,
+      port,
+      url: serverUrls(live).local,
+      log: logFile,
+      node: process.version,
+    });
+  } catch (error) {
+    logger.warn('could not write the run record', { file: runInfoPath(configFile), error: error.message });
   }
+  server.once('close', () => removePidFile(configFile));
+  process.once('exit', () => removePidFile(configFile));
 
   log(startupBanner(live, { configFile }));
 
   const shouldOpen = openBrowser ?? (live.autoOpen && process.stdout.isTTY && !process.env.NO_OPEN);
-  // The browser adopts a self-hosted key from the query string, stores it locally,
-  // and removes the secret from the visible URL before any API request.
+  // Local requests never need a credential. Remote browsers are sent to the
+  // themed login page and exchange the key for an HttpOnly session cookie.
   if (shouldOpen) openInBrowser(browserUrl(live));
   return { server, settings: live, host, port };
 }

package/server/logger.js

@@ -1,22 +1,103 @@
+// Every line Onboarder writes, in two faces.
+//
+// The entry itself is data — `{ ts, time, level, msg, ...fields }` — and the
+// renderer decides how it looks. JSON goes to pipes, log files and anything
+// parsing us; the aligned human line goes to a terminal. Picking the face once,
+// here, is what keeps a log file readable *and* machine-parseable instead of
+// half one thing.
+//
+// A `time` field (local HH:MM:SS.mmm) rides along with the ISO `ts` on purpose:
+// tailing a file gives you the string, not a Date, and a reader wants their own
+// clock, not UTC.
+
 const levels = { debug: 0, info: 1, warn: 2, error: 3 };
 
-export function createLogger(level = process.env.LOG_LEVEL || 'info') {
+// Worst first — the order any summary or sort should use.
+export const SEVERITY = { error: 0, warn: 1, info: 2, debug: 3 };
+
+const CODES = { red: 31, green: 32, yellow: 33, cyan: 36, gray: 90 };
+const LEVEL_COLOR = { debug: 'gray', info: 'cyan', warn: 'yellow', error: 'red' };
+
+// The server sits *under* the CLI, so it cannot import `cli/ui.js` without
+// inverting the dependency. These three lines of ANSI are the whole price.
+function paint(text, color, enabled) {
+  return enabled && color ? `\x1b[${CODES[color]}m${text}\x1b[0m` : String(text);
+}
+
+// Fields that are part of the envelope or already rendered into the message.
+const ENVELOPE = new Set(['ts', 'time', 'level', 'msg', 'method', 'path', 'status', 'ms', 'line', 'scope']);
+
+// One line, no styling: what a log file holds and what a test asserts on.
+export function formatMessage(entry) {
+  if (entry.line) return `${entry.msg ?? ''} ${entry.line}`.trim();
+  if (entry.method) {
+    const status = entry.status === undefined ? '' : ` ${entry.status}`;
+    const took = entry.ms === undefined ? '' : ` (${entry.ms}ms)`;
+    return `${entry.method} ${entry.path}${status}${took}`;
+  }
+  const extra = Object.entries(entry)
+    .filter(([key, value]) => !ENVELOPE.has(key) && value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+  return [entry.msg ?? '', ...extra].filter(Boolean).join(' ');
+}
+
+// Every log line is `time  LEVEL  message`, with the level in a fixed 5-wide
+// column so the messages of an `INFO` and a `ERROR` line start at the same
+// offset. That alignment is the entire point: a wall of request logs is only
+// scannable if the eye can find the message column without reading.
+const LEVEL_WIDTH = 5;
+const GUTTER = '  ';
+
+export function formatEntry(entry) {
+  const time = String(entry.time || String(entry.ts || '').slice(11, 23));
+  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+  return `${time}${GUTTER}${level}${GUTTER}${formatMessage(entry)}`;
+}
+
+export function renderEntry(entry, { color = false } = {}) {
+  const time = String(entry.time || String(entry.ts || '').slice(11, 19));
+  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+  return paint(time, 'gray', color) + GUTTER + paint(level, LEVEL_COLOR[entry.level] || 'gray', color) + GUTTER + formatMessage(entry);
+}
+
+export function logEntry(level, msg, extra = {}) {
+  const now = new Date();
+  return {
+    ts: now.toISOString(),
+    // Built from the local parts, not `toTimeString()`: that carries a timezone
+    // abbreviation whose width changes (`GMT` vs ` PDT`), which is exactly what
+    // makes a log column ragged. Always 12 characters, always the reader's clock.
+    time: [now.getHours(), now.getMinutes(), now.getSeconds()]
+      .map((part) => String(part).padStart(2, '0'))
+      .join(':') + '.' + String(now.getMilliseconds()).padStart(3, '0'),
+    level,
+    msg,
+    ...extra,
+  };
+}
+
+export function createLogger(level = process.env.LOG_LEVEL || 'info', options = {}) {
   const minLevel = levels[level] ?? levels.info;
-  
+  // `pretty` is the default for a terminal *and* for a log file (aligned text is
+  // what a person reads at 2am); `ONBOARDER_LOG=json` is the machine escape
+  // hatch, and so is a non-TTY consumer that parses stdout.
+  const format = options.format || process.env.ONBOARDER_LOG || 'pretty';
+  const color = options.color ?? (Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
+  const out = options.stdout || process.stdout;
+  const err = options.stderr || process.stderr;
+
+  function write(entry) {
+    if (format === 'json') {
+      const line = JSON.stringify(entry) + '\n';
+      (entry.level === 'warn' || entry.level === 'error' ? err : out).write(line);
+      return;
+    }
+    (entry.level === 'warn' || entry.level === 'error' ? err : out).write(renderEntry(entry, { color }) + '\n');
+  }
+
   function log(lvl, msg, extra = {}) {
     if (levels[lvl] < minLevel) return;
-    const entry = {
-      ts: new Date().toISOString(),
-      level: lvl,
-      msg,
-      ...extra
-    };
-    const out = JSON.stringify(entry) + '\\n';
-    if (lvl === 'warn' || lvl === 'error') {
-      process.stderr.write(out);
-    } else {
-      process.stdout.write(out);
-    }
+    write(logEntry(lvl, msg, extra));
   }
 
   return {
@@ -24,6 +105,6 @@ export function createLogger(level = process.env.LOG_LEVEL || 'info') {
     info: (msg, extra) => log('info', msg, extra),
     warn: (msg, extra) => log('warn', msg, extra),
     error: (msg, extra) => log('error', msg, extra),
-    http: (req) => log('info', 'HTTP Request', req)
+    http: (req) => log(req.status >= 500 ? 'error' : 'info', 'http', req),
   };
 }

package/server/pidfile.js

@@ -45,5 +45,42 @@ export function writePidFile(configFile) {
 // Remove the file only when it still points at `pid` — a second server that
 // rewrote the file must not lose its record because the first one exited.
 export function removePidFile(configFile, pid = process.pid) {
-  if (readPidFile(configFile) === pid) fs.rmSync(pidPath(configFile), { force: true });
+  if (readPidFile(configFile) === pid) {
+    fs.rmSync(pidPath(configFile), { force: true });
+    removeRunInfo(configFile);
+  }
+}
+
+// The pid answers "is it running?"; it cannot answer "how is it running?".
+// Which mode a live server was launched in (foreground, background, a login
+// item), where its log file is, and when it booted are all things `onboarder
+// status` should be able to print without guessing — so they are written
+// beside the pid, best effort, exactly like the pid itself.
+export function runInfoPath(configFile) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.run.json');
+}
+
+export function writeRunInfo(configFile, info = {}) {
+  try {
+    fs.writeFileSync(runInfoPath(configFile), JSON.stringify({
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      ...info,
+    }, null, 2) + '\n', { mode: 0o600 });
+  } catch {
+    // A read-only config dir must never stop a server from booting.
+  }
+}
+
+export function readRunInfo(configFile) {
+  try {
+    const value = JSON.parse(fs.readFileSync(runInfoPath(configFile), 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function removeRunInfo(configFile) {
+  try { fs.rmSync(runInfoPath(configFile), { force: true }); } catch { /* nothing to clean */ }
 }

package/server/router.js

@@ -1,16 +1,14 @@
-// The route table and the two gates in front of it.
+// The route table and the gates in front of it.
 //
 // Everything arrives here: one function decides whether a request is allowed to
 // be answered at all, then which handler answers it. The routes are a list rather
 // than a ladder of `if` statements so that the whole surface of the server is
-// visible in one screen — six endpoints, and everything else is a static file.
+// visible in one screen, and everything else is a static file.
 //
-// Neither gate is authentication. A local server with no accounts cannot
-// authenticate anyone; what it can do is refuse requests that a browser on some
-// other site made on the person's behalf. `server/httpGuards.js` explains both
-// attacks; the short version is that `Host` stops DNS rebinding from turning
-// `evil.com` into our own origin, and `Origin`/`Sec-Fetch-Site` stops a page the
-// person happened to have open from driving the API.
+// There are three concerns. Local mode relies on `Host`, `Origin`, and
+// `Sec-Fetch-Site` to stop another page and DNS rebinding from driving it.
+// Self-hosted mode adds real access-key authentication: local browser requests
+// stay open, remote browsers get a signed session, and API clients use Bearer.
 
 import { handleDocs } from './apiDocs.js';
 import { handleFile } from './apiFile.js';
@@ -25,7 +23,9 @@ import { handleDiff, handleDiffRefs } from './apiDiff.js';
 import { handleToolsInstall, handleToolsRun, handleToolsStatus } from './apiTools.js';
 import { handleMcpStart, handleMcpStatus, handleMcpStop, handleMcpCommand } from './apiMcp.js';
 import { handleGetSettings, handleRotateAccessKey, handleUpdateSettings } from './apiSettings.js';
-import { allowedHosts, authReason, DEFAULT_SETTINGS } from './config.js';
+import { handleAuthStatus, handleLogin, handleLogout } from './apiAuth.js';
+import { accessKeysMatch, allowedHosts, authReason, bearerToken, DEFAULT_SETTINGS } from './config.js';
+import { hasValidSession } from './auth.js';
 
 const ROUTES = [
   {
@@ -110,6 +110,18 @@ const ROUTES = [
     method: 'GET', path: '/api/health',
     run: ({ res }) => sendJSON(res, 200, { ok: true }),
   },
+  {
+    method: 'GET', path: '/api/auth/status', sameOrigin: true,
+    run: ({ req, res, settings }) => handleAuthStatus(req, res, settings),
+  },
+  {
+    method: 'POST', path: '/api/auth/login', body: true, sameOrigin: true,
+    run: ({ req, res, body, settings }) => handleLogin(req, res, body, settings),
+  },
+  {
+    method: 'POST', path: '/api/auth/logout', body: true, sameOrigin: true,
+    run: ({ req, res }) => handleLogout(req, res),
+  },
   {
     // The settings drawer and the CLI read the same public shape: everything
     // about the configuration except the access key itself.
@@ -128,7 +140,7 @@ const ROUTES = [
     // this response, never readable again. In self-hosted mode this endpoint
     // is itself behind the current key, so rotation requires possession.
     method: 'POST', path: '/api/settings/access-key', body: true,
-    run: ({ res, config }) => handleRotateAccessKey(res, config),
+    run: ({ req, res, config }) => handleRotateAccessKey(req, res, config),
   },
 ];
 
@@ -184,6 +196,7 @@ export function createRouter(config) {
       }
 
       const found = matchRoute(req.method, url.pathname);
+      const publicAuthRoute = ['/api/health', '/api/auth/status', '/api/auth/login', '/api/auth/logout'].includes(url.pathname);
       if (req.method !== 'GET' || found?.route.sameOrigin) {
         const foreign = crossOriginReason(req);
         if (foreign) {
@@ -191,18 +204,34 @@ export function createRouter(config) {
         }
       }
 
-      // The self-hosted gate. It is authentication, unlike the two guards
-      // above: the mode says the network can reach us, so every API call
-      // proves it holds the access key. `/api/health` stays open — a tunnel
-      // or uptime check has no key and tells an attacker nothing.
-      if (found && url.pathname.startsWith('/api/') && url.pathname !== '/api/health') {
-        const denied = authReason(req, settings);
-        if (denied) return sendError(res, 401, denied);
+      // Bearer clients keep their existing API contract. A browser gets a signed,
+      // HttpOnly session from the login form instead of storing the raw key.
+      const bearerClient = accessKeysMatch(settings.accessKey, bearerToken(req));
+      const browserAuthenticated = hasValidSession(req, settings);
+      const authDenied = authReason(req, settings);
+      const locallyExempt = !authDenied;
+      const authenticated = bearerClient || browserAuthenticated || locallyExempt;
+      const remoteSelfHosted = settings.mode === 'self-hosted' && Boolean(authDenied);
+
+      if (remoteSelfHosted && !authenticated && !publicAuthRoute) {
+        // API callers keep a machine-readable 401. A browser navigation gets the
+        // themed sign-in document so the user never has to paste JSON into a tab.
+        const accepts = String(req.headers?.accept || '');
+        if (req.method === 'GET' && (url.pathname === '/' || accepts.includes('text/html'))) {
+          res.statusCode = 200;
+          return await serveStatic(res, '/login.html', config);
+        }
+        return sendError(res, 401, authDenied || 'Sign in with the Onboarder access key first.');
+      }
+
+      if (url.pathname === '/api/auth/logout') {
+        // Always clear the browser cookie, even if it had already expired.
+        return handleLogout(req, res);
       }
 
       if (found) {
         const body = found.route.body ? await readBody(req) : null;
-        return await found.route.run({ req, res, url, body, rest: found.rest, config });
+        return await found.route.run({ req, res, url, body, rest: found.rest, config, settings });
       }
 
       if (req.method === 'GET') return await serveStatic(res, url.pathname, config);

package/server/startup.js

@@ -0,0 +1,261 @@
+// Start Onboarder when the machine boots, the way a person actually wants a
+// server they always want running to behave.
+//
+// "Startup" is three different mechanisms wearing one name, so this module
+// detects the platform and speaks its dialect — and, importantly, the *file
+// writing* is separated from the *service loading* so both are testable without
+// a Mac or a systemd:
+//
+//   macOS    ~/Library/LaunchAgents/<label>.plist   → launchctl bootstrap
+//   Linux    ~/.config/systemd/user/<unit>.service  → systemctl --user enable --now
+//   Windows  %APPDATA%\...\Startup\Onboarder.cmd   → being there is enough
+//   other    nothing; we say so rather than pretending
+//
+// Every artifact is generated from the *same* command line a person would type
+// (`<node> <cli> start background --config <file>`), so a login-started server
+// is indistinguishable from a hand-started one — same config, same pid file,
+// same `onboarder stop`.
+//
+// Deliberately no `sudo`, no writing into launchd's system domain, and nothing
+// outside the user's own home. A login item is a convenience; it must never be
+// the thing that needs an administrator password.
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { configPath } from './config.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export const LABEL = 'com.onboarder.server';
+export const UNIT = 'onboarder.service';
+
+export function cliEntry() {
+  // `bin/onboarder.js` next to `server/`, whether we were run from a checkout
+  // or from a global install. The env override is what lets a test point the
+  // generated unit at a fixture instead of the real machine.
+  return process.env.ONBOARDER_CLI || path.resolve(HERE, '..', 'bin', 'onboarder.js');
+}
+
+// The argv a login item runs.
+//
+// Note what is *not* here: `background`. launchd and systemd are already
+// supervisors — they hold the process, restart it, and capture its output. A
+// login item that spawned a detached grandchild and exited immediately would
+// leave the supervisor watching a corpse, which defeats `KeepAlive` and turns a
+// busy port into a respawn loop. So the generated command is a plain foreground
+// `start`, and the OS owns the lifecycle from there.
+export function startupCommand(configFile = configPath(), { node = process.execPath, entry = cliEntry() } = {}) {
+  return [node, entry, 'start', '--config', configFile];
+}
+
+function xmlEscape(value) {
+  const map = { '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' };
+  return String(value).replace(/[<>&'"]/g, (c) => map[c]);
+}
+
+function argList(args) {
+  return args.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+}
+
+export function renderLaunchAgent({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  const streams = log
+    ? `  <key>StandardOutPath</key>\n  <string>${xmlEscape(log)}</string>\n  <key>StandardErrorPath</key>\n  <string>${xmlEscape(log)}</string>\n`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argList(args)}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+${streams}  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(process.env.PATH || '/usr/local/bin:/usr/bin:/bin')}</string>
+    <key>ONBOARDER_LAUNCH</key>
+    <string>startup</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function renderSystemdUnit({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  // `Restart=always` would fight `onboarder stop`: a deliberate stop must stay
+  // stopped, so only a *failed* exit is restarted. `on-failure` is the honest
+  // setting here, and `SuccessfulExit=false` above is its launchd spelling.
+  const exec = args.map((a) => (/[\s"]/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return `[Unit]
+Description=Onboarder — codebase visualizer and onboarding map
+Documentation=https://github.com/Amitpandey88/onboarder
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Restart=on-failure
+RestartSec=3
+${log ? `StandardOutput=append:${log}\nStandardError=append:${log}\n` : ''}Environment=NO_COLOR=1
+Environment=ONBOARDER_LAUNCH=startup
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function renderWindowsStartup({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  const line = args.map((a) => `"${a}"`).join(' ');
+  return `@echo off\r\nrem Managed by "onboarder start startup". Edits are replaced.\r\nstart "" /b ${line}${log ? ` >> "${log}" 2>&1` : ''}\r\n`;
+}
+
+// The target carries its own platform, so every message about it can name the
+// platform it was resolved for rather than the one this process happens to run
+// on. A test (or a future cross-platform installer) resolves a plan9 target on a
+// Mac; saying "darwin" in that error would be a lie.
+export function startupTarget({ platform = process.platform, home = os.homedir(), env = process.env } = {}) {
+  // The per-user launchd domain. The system domain needs root, which this tool
+  // never asks for.
+  const domain = `gui/${process.getuid?.() ?? 501}`;
+  if (platform === 'darwin') {
+    return {
+      kind: 'launchd',
+      platform,
+      label: LABEL,
+      path: path.join(home, 'Library', 'LaunchAgents', LABEL + '.plist'),
+      render: renderLaunchAgent,
+      load: ['launchctl', 'bootstrap', domain, '{file}'],
+      unload: ['launchctl', 'bootout', `${domain}/{label}`],
+      status: ['launchctl', 'print', `${domain}/{label}`],
+      hint: 'launchd agent in ~/Library/LaunchAgents',
+    };
+  }
+  if (platform === 'linux') {
+    const configHome = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    return {
+      kind: 'systemd',
+      platform,
+      label: UNIT,
+      path: path.join(configHome, 'systemd', 'user', UNIT),
+      render: renderSystemdUnit,
+      daemonReload: ['systemctl', '--user', 'daemon-reload'],
+      load: ['systemctl', '--user', 'enable', '--now', UNIT],
+      unload: ['systemctl', '--user', 'disable', '--now', UNIT],
+      status: ['systemctl', '--user', 'is-active', UNIT],
+      hint: 'systemd --user unit (no root; starts with your session)',
+    };
+  }
+  if (platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    // Native separators throughout: this string goes into a .cmd file and into
+    // the Startup folder itself, and `path.join` would emit `\` mixed with `/`
+    // — which Windows tolerates in a file path but no one should have to read.
+    return {
+      kind: 'startup-folder',
+      platform,
+      label: 'Onboarder.cmd',
+      path: [
+        appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup', 'Onboarder.cmd',
+      ].join('\\'),
+      render: renderWindowsStartup,
+      load: null,   // the file *is* the registration
+      unload: null,
+      status: null,
+      hint: 'script in the Windows Startup folder',
+    };
+  }
+  return { kind: 'unsupported', platform, label: '', path: '', render: null, load: null, unload: null, status: null, hint: '' };
+}
+
+// Substitute `{file}` / `{label}` and run without a shell — an argument is an
+// argument, never a command line somebody else gets to compose. `spawn` is
+// injected so a test can assert on the argv without touching launchd.
+function exec(argv, { spawn = spawnSync } = {}) {
+  const result = spawn(argv[0], argv.slice(1), { encoding: 'utf8' });
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status ?? null,
+    output: String(result.stdout || result.stderr || '').trim(),
+    error: result.error?.message || '',
+  };
+}
+
+const fill = (argv, target) => argv
+  .map((a) => a.replace('{file}', target.path).replace('{label}', target.label));
+
+export async function startupInstalled(target = startupTarget()) {
+  if (!target.path) return false;
+  try { await fs.access(target.path); return true; } catch { return false; }
+}
+
+export async function startupStatus(target = startupTarget(), { run = spawnSync } = {}) {
+  const installed = await startupInstalled(target);
+  let active = null;
+  if (installed && target.status) {
+    const result = exec(fill(target.status, target), { spawn: run });
+    // systemd answers `active`/`inactive` on stdout; `launchctl print` succeeds
+    // only for a job that is actually loaded. Both answer "is it live now".
+    const text = result.output.toLowerCase();
+    active = target.kind === 'systemd'
+      ? text.includes('active') && !text.includes('inactive')
+      : result.ok;
+  }
+  return {
+    kind: target.kind,
+    supported: target.kind !== 'unsupported',
+    label: target.label,
+    path: target.path,
+    installed,
+    active,
+    detail: target.kind === 'unsupported'
+      ? `no automatic-startup mechanism for ${target.platform || process.platform}`
+      : installed
+        ? (active ? `running — ${target.hint}` : `installed, not running — ${target.hint}`)
+        : 'not installed',
+    hint: target.hint,
+  };
+}
+
+export async function installStartup({ configFile = configPath(), log = '', target = startupTarget(), run = spawnSync } = {}) {
+  if (target.kind === 'unsupported') {
+    return { ok: false, reason: `There is no automatic-startup mechanism Onboarder knows how to write on ${target.platform || process.platform}. Start it with \`onboarder start background\` from whatever your machine runs at boot.` };
+  }
+  await fs.mkdir(path.dirname(target.path), { recursive: true });
+  await fs.writeFile(target.path, target.render({ configFile, log }), { encoding: 'utf8', mode: 0o600 });
+  if (target.kind === 'systemd' && target.daemonReload) exec(fill(target.daemonReload, target), { spawn: run });
+  if (!target.load) return { ok: true, path: target.path, loaded: true, output: '' };
+  const result = exec(fill(target.load, target), { spawn: run });
+  // A unit that is already loaded is a success, not a failure — installing twice
+  // has to be idempotent, and `launchctl` says so in three different ways.
+  const already = /already (been )?(loaded|active|exists|running)|115|unit .*already/i.test(result.output);
+  if (!result.ok && !already) {
+    return { ok: false, path: target.path, output: result.output || result.error, error: result.error };
+  }
+  return { ok: true, path: target.path, loaded: true, output: result.output };
+}
+
+export async function removeStartup({ target = startupTarget(), run = spawnSync } = {}) {
+  if (target.kind === 'unsupported') return { ok: false, reason: 'Nothing is installed for this platform.' };
+  let output = '';
+  if (target.unload) output = exec(fill(target.unload, target), { spawn: run }).output;
+  await fs.rm(target.path, { force: true });
+  if (target.kind === 'systemd' && target.daemonReload) exec(fill(target.daemonReload, target), { spawn: run });
+  return { ok: true, path: target.path, output };
+}