codebase-onboarder 0.3.1 → 0.4.1

package/server/logger.js

@@ -1,22 +1,322 @@
+// 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.
+// `summary` is here so the suppressed-noise footer does not print itself as
+// `summary=true` — it is a rendering flag, not data.
+const ENVELOPE = new Set(['ts', 'time', 'level', 'msg', 'method', 'path', 'status', 'ms', 'line', 'scope', 'summary']);
+
+// Request classification — the difference between a person doing something and
+// a browser fetching a file.
+//
+// This is the single most important thing about Onboarder's logs. A page load
+// pulls ~90 ES modules, a stylesheet, and two vendored libraries: 90 log lines
+// describing zero user actions, repeated on every reload and on every auth
+// check. The MCP status poll adds one more line every nine seconds, forever. Log
+// all of it and the real events — a scan, a login, a 500 — are buried.
+//
+// So: a request is an **action** if it is an API call, and **noise** if it is a
+// static asset. Noise is not thrown away, it is *counted* (see `NoiseCounter`),
+// because "nothing happened" and "90 files were served" are different facts and
+// only one of them is interesting most of the time.
+export function classifyPath(pathname = '') {
+  const path = String(pathname).split('?')[0];
+  if (path === '/api/health') return 'poll';      // uptime checks
+  if (path.startsWith('/api/')) return 'action';
+  return 'noise';
+}
+
+export function classifyRequest(req = {}) {
+  const kind = classifyPath(req.path);
+  // A failure is always an action, whatever it was: a 404 on a missing asset is
+  // a broken build, and a 500 is a bug. Neither is noise to be summarized away.
+  if (Number(req.status) >= 400) return 'action';
+  if (req.method && req.method !== 'GET' && req.method !== 'HEAD') return 'action';
+  return kind;
+}
+
+// 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 = '  ';
+
+// The part of a path that identifies it: the filename with its extension. When
+// a line has to be cut, this is what must survive — `…typescript.js` is useful,
+// `…script` is not. A path with no filename (`/` or `/a/`) falls back to its tail.
+export function identifyingTail(text) {
+  const value = String(text);
+  const name = value.slice(value.lastIndexOf('/') + 1);
+  return name.length >= 4 ? name : value.slice(-8);
+}
+
+// How the message area adapts to the terminal. Wide terminals get the whole
+// path; narrow ones get the part that identifies it, elided in the middle — the
+// tail of a path is the informative half, so it survives and the boring prefix
+// is what gets dropped.
+export function fitPath(text, max) {
+  const value = String(text);
+  if (max <= 0) return '';
+  if (value.length <= max) return value;
+  if (max === 1) return '…';
+  // An ellipsis stands in for the dropped prefix, so do not also add a leading
+  // slash: `/…/file.js` reads as a path, `//file.js` reads as a typo. The kept
+  // tail is the filename, so a long path loses its directories rather than
+  // losing its extension — `…typescript.js` is useful, `…typescript` is not.
+  const tail = identifyingTail(value);
+  if (tail.length + 1 <= max) return '…' + tail;
+  return '…' + value.slice(-(max - 1));
+}
+
+// How much room the message gets, and whether the level column is affordable.
+//
+// The fixed prefix is the time, two gutters, and the level column. On a narrow
+// terminal that fixed cost eats the whole line, so two things give way: below 52
+// columns the level column is dropped, and below 24 the timestamp reduces to
+// HH:MM. Below 12 there is no room for any prefix at all, so both are dropped.
+//
+// Crucially the prefix never exceeds the terminal. An earlier version floored
+// `messageWidth` at 12, which meant a 20-column line asked for 20 columns of
+// message, overflowed, and got clamped from the front — producing `pt.js 200`,
+// the tail of a line with its head cut off. The prefix is the part that must
+// yield, not the message.
+export const LEVEL_MIN_COLUMNS = 52;
+export const SHORT_TIME_COLUMNS = 24;
+export const NO_TIME_COLUMNS = 12;
+
+export function showLevel(columns) {
+  return (columns || 80) >= LEVEL_MIN_COLUMNS;
+}
+
+export function showFullTime(columns) {
+  return (columns || 80) >= SHORT_TIME_COLUMNS;
+}
+
+export function showTime(columns) {
+  return (columns || 80) >= NO_TIME_COLUMNS;
+}
+
+// The time as it will actually be printed, so callers do not re-derive the same
+// decision and get it subtly wrong.
+export function timeColumn(entry, columns) {
+  if (!showTime(columns)) return '';
+  const raw = String(entry.time || String(entry.ts || '').slice(11, 19));
+  return showFullTime(columns) ? raw : raw.slice(0, 5);
+}
+
+// Everything before the message: time + gutter + optional level + gutter.
+//
+// Deliberately computed from the *width* alone, not from an entry: an earlier
+// version asked `timeColumn({}, columns)`, which has no timestamp and so
+// reported a zero-width prefix — and then every line was built 19 columns too
+// long and overflowed. The prefix is a property of the terminal, not of the log
+// line, so it is computed from the terminal.
+export function prefixWidth(columns) {
+  if (!showTime(columns)) return 0;
+  const time = showFullTime(columns) ? 12 : 5;
+  return time + GUTTER.length + (showLevel(columns) ? LEVEL_WIDTH + GUTTER.length : 0);
+}
+
+export function messageWidth(columns) {
+  const total = columns || 80;
+  return Math.max(0, total - prefixWidth(total));
+}
+
+export function formatEntry(entry, { columns } = {}) {
+  const time = timeColumn(entry, columns);
+  const level = showLevel(columns) ? entryLevel(entry) + GUTTER : '';
+  const head = time ? time + GUTTER + level : '';
+  // The message was already fitted to `messageWidth` and the head is exactly
+  // `prefixWidth`, so the line is exactly the terminal width by construction —
+  // no trailing clamp, and therefore no risk of cutting a word in half.
+  return head + fitMessage(entry, columns);
+}
+
+// One line, fitted to the terminal.
+//
+// What gets sacrificed as space runs out, in order: the timing, then the HTTP
+// status, then the level column, then the *method* — and the path's tail is
+// protected, because the filename is the one thing that still identifies the
+// request. A 40-column terminal gets `…zer/languages/typescript.js` (the
+// extension intact); an 80-column one gets the whole sentence.
+function fitMessage(entry, columns) {
+  const text = formatMessage(entry);
+  const room = messageWidth(columns);
+  if (text.length <= room) return text;
+  if (!entry.method || !entry.path) return fitPath(text, room);
+
+  const status = entry.status === undefined ? '' : ` ${entry.status}`;
+  const method = `${entry.method} `;
+  // Drop the status before the method, and the method before any of the path.
+  const withStatus = method + fitPath(entry.path, room - method.length - status.length) + status;
+  if (withStatus.length <= room) return withStatus;
+  const withoutStatus = method + fitPath(entry.path, room - method.length);
+  if (withoutStatus.length <= room) return withoutStatus;
+  // Last resort: the path alone, at exactly the room available. `fitPath` is
+  // given the exact width, so this is always exactly `room` — never over, which
+  // is what would make the caller's clamp cut the *front* of the line and leave
+  // an unreadable tail like `pt.js 200`.
+  return fitPath(entry.path, room);
+}
+
+// A summary of suppressed noise renders as a footnote, not an event: dim, and
+// with no level column, so the eye skips it while scanning for real lines. It
+// occupies the same time gutter so it still lines up in the scrollback.
+export function renderEntry(entry, { color = false, columns } = {}) {
+  const message = fitMessage(entry, columns);
+  const limit = Math.max(8, columns || 80);
+  if (entry.summary) {
+    const pad = showLevel(columns) ? ' '.repeat(LEVEL_WIDTH) + GUTTER : '';
+    return paint(timeColumn(entry, columns), 'gray', color)
+      + GUTTER + paint(GUTTER + pad + message, 'gray', color);
+  }
+  const painted = paint(timeColumn(entry, columns), 'gray', color) + GUTTER
+    + (showLevel(columns) ? paint(entryLevel(entry), LEVEL_COLOR[entry.level] || 'gray', color) + GUTTER : '')
+    + message;
+  // Clamp on *visible* width: the ANSI codes cost nothing on screen, so slicing
+  // the painted string by character count would cut a real character and leave
+  // the escape sequence unterminated.
+  return visibleWidth(painted) <= limit ? painted : trimVisible(painted, limit);
+}
+
+// Visible width, ANSI excluded.
+function visibleWidth(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// Cut a painted string to `max` visible columns, passing escape sequences through
+// and never splitting one, then resetting so the terminal is left clean.
+function trimVisible(text, max) {
+  const pattern = /\x1b\[[0-9;]*m/g;
+  let out = '';
+  let seen = 0;
+  let last = 0;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    const chunk = text.slice(last, match.index);
+    if (seen + chunk.length >= max) return out + chunk.slice(0, Math.max(0, max - seen)) + '\x1b[0m';
+    out += chunk + match[0];
+    seen += chunk.length;
+    last = pattern.lastIndex;
+  }
+  const rest = text.slice(last);
+  return out + (seen + rest.length > max ? rest.slice(0, max - seen) : rest);
+}
+
+function entryLevel(entry) {
+  return String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+}
+
+// A human summary of suppressed noise, so silence is never ambiguous. "Nothing
+// happened" and "94 files were served" are different facts; printing the second
+// as one line every so often keeps the first honest.
+export function noiseSummary(count, ms = 0) {
+  const files = `${count} static file${count === 1 ? '' : 's'}`;
+  const took = ms >= 1000 ? ` in ${(ms / 1000).toFixed(1)}s` : ms ? ` in ${ms}ms` : '';
+  return `served ${files}${took}`;
+}
+
+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;
+
+  // The noise policy. `info` (the default) drops successful static assets and
+  // uptime polls; `debug` shows every request, which is what you want when you
+  // are debugging the server rather than watching it. ONBOARDER_LOG_VERBOSE=1 is
+  // the same escape hatch without changing the level.
+  const quiet = options.quiet ?? (minLevel > levels.debug && process.env.ONBOARDER_LOG_VERBOSE !== '1');
+  // Read the terminal width per write, not once at construction: a log line
+  // printed after the user resized their window should use the new width.
+  const columns = options.columns ?? (() => out.columns || undefined);
+
+  // Suppressed-asset accounting. Assets are counted, not printed, and the tally
+  // is flushed as ONE dim summary line once it reaches `flushAt` — so a page
+  // load that serves 94 files produces one line, and a terminal that is idle
+  // still admits the server is busy rather than looking dead.
+  const flushAt = options.flushAt ?? 40;
+  let suppressed = 0;
+  let since = Date.now();
+
+  function flush(force = false) {
+    if (!suppressed) return;
+    if (!force && suppressed < flushAt) return;
+    write(logEntry('info', noiseSummary(suppressed, Date.now() - since), { summary: true }));
+    suppressed = 0;
+    since = Date.now();
+  }
+
+  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, columns: columns() }) + '\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 +324,20 @@ 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)
+    // The one place the noise policy lives. A successful GET of a static file is
+    // counted, not printed; a scan, a login, or any failure is printed.
+    http: (req) => {
+      if (quiet && classifyRequest(req) === 'noise') {
+        suppressed += 1;
+        flush();
+        return;
+      }
+      if (quiet && classifyPath(req.path) === 'poll') return;
+      flush();
+      log(Number(req.status) >= 500 ? 'error' : 'info', 'http', req);
+    },
+    // Let a shutdown path (or a test) get the tally out before the process dies.
+    flush: () => flush(true),
+    suppressed: () => suppressed,
   };
 }

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/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 };
+}

package/shared/analyzer/graph.js

@@ -52,9 +52,14 @@ export function computeFacts(scan, manifest = {}) {
     .map((f) => f.path)
     .sort();
 
+  // A hub is a file other files depend on. The threshold is 2, not 3: in a
+  // repo with 20 files, "imported by two others" *is* the most-depended-upon
+  // file, and a threshold of 3 reported no hubs at all for a whole small project
+  // — the map of a small repo is exactly where a hub is most useful. Two is the
+  // lowest value that still means "more than one other file reaches for this".
   const hubs = files
     .map((f) => ({ path: f.path, fanIn: fanIn.get(f.path) || 0, fanOut: fanOut.get(f.path) || 0 }))
-    .filter((h) => h.fanIn >= 3)
+    .filter((h) => h.fanIn >= 2)
     .sort((a, b) => b.fanIn - a.fanIn);
 
   const orphans = files