codebase-onboarder 0.4.1 → 0.5.0

package/README.md

@@ -22,8 +22,11 @@ Onboarder reads a software repository the way a senior engineer would: starting
 # Install from npm (Node 20+, zero runtime dependencies)
 npm install -g codebase-onboarder
 
-# First run: a short setup wizard, then the server
+# Explore the repo you are standing in, right in your terminal
 onboarder
+
+# …or start the web UI instead
+onboarder start
 ```
 
 Or from source:
@@ -36,12 +39,53 @@ npm start
 
 Open **http://localhost:4310** in your browser (the CLI opens it for you).
 
+- **Two front doors, one engine.** `onboarder` opens an interactive terminal session; `onboarder start` opens the web UI. Both run the *same* analyzer, so they can never disagree about a repository.
 - **Zero build steps**: Native ES modules.
 - **Zero runtime dependencies**: Powered by Node.js built-ins (`node:http`, `node:fs`, `node:crypto`).
 - **Offline ready**: Vendored Mermaid.js and Monaco Editor builds are included in `public/vendor/`.
 
 ---
 
+## 🖥️ The terminal app
+
+Type `onboarder` in any repo and you get the website, in your terminal. No server, no browser, no network — it reads the folder directly.
+
+```bash
+onboarder                 # explore the current directory
+onboarder explore ~/work/some-repo
+onboarder --server        # force the web UI (what bare `onboarder` used to do)
+```
+
+It lands on a `map` of the repo, then waits:
+
+```
+  codebase > tour
+  codebase > find resolveImport
+  codebase > deps logger.js
+  codebase > show logger.js
+  codebase > exit
+```
+
+| | |
+|---|---|
+| **map · tour · explain** | What this is, the reading order for a new teammate, and a file or folder explained in prose |
+| **tree · find · show · deps** | Browse it, search it, read it, and trace what it connects to |
+| **health · hubs · layers · patterns** | The analysis, in the same words the site uses |
+| **stats · security · stack · entry · externals** | Numbers, findings, dependencies, and drift |
+| **cd · rescan · web** | Switch repo, reload from disk, or start the web UI without leaving |
+
+**It is the website's engine, not a reimplementation.** `onboarder explore` runs the same modules in the same order as `POST /api/scan` — `scanRepo` → `detectManifest` → `computeFacts` → `buildSearchIndex` — and the same projections the browser's views are projections of. A second implementation would drift, and a drifted map is worse than no map.
+
+Details worth knowing:
+
+- **Forgiving paths.** `show logger.js` finds `server/logger.js`. A genuinely ambiguous name (`index.js`) lists the candidates instead of guessing — silently picking the wrong file is how a map loses your trust.
+- **The site's search language.** `find ext:rs -test`, `find "exact phrase"`, `find /regex/` all work because it is the same query parser the web palette uses.
+- **Fits your terminal.** Every line is fitted to the current width and re-fits on resize; prose wraps instead of running off the edge. `NO_COLOR` and `COLUMNS` are honored.
+- **It refuses to hang.** Without a TTY, `onboarder explore` explains itself and exits rather than waiting for input that will never come. Scripts and CI keep working.
+- **Bridges to the web.** `web` starts the UI in the background and prints the URL, without ending your session.
+
+---
+
 ## 🚀 Ways to Load a Repository
 
 1. **Local Directory** — Enter any absolute path (`/Users/you/projects/repo` or `~/work/repo`). Analyzed in-place without copying files.
@@ -312,6 +356,13 @@ Cloudflare quick tunnels and Tailscale remain supported. They terminate TLS and
 codebase-onboarder/
 ├── bin/             # npm entry point (shebang trampoline) & postinstall note
 ├── cli/             # Onboarding wizard, config commands, doctor, tunnels
+│   ├── main.js      # argv → command; bare `onboarder` picks explorer vs server
+│   ├── ui.js        # Terminal paint; --no-color / NO_COLOR strip it in one place
+│   └── explorer/    # The terminal app
+│       ├── app.js     # The readline session, TTY guards, `web` bridge
+│       ├── session.js # Loads a repo exactly as POST /api/scan does
+│       ├── views.js   # The site's screens, drawn as text (pure functions)
+│       └── commands.js# One command table: dispatch, help, and tests share it
 ├── server/          # Zero-dependency Node.js HTTP server
 │   ├── index.js     # createServer / startServer / startup banner
 │   ├── config.js    # Settings schema, normalization, atomic 0600 writes
@@ -339,7 +390,7 @@ codebase-onboarder/
 │   ├── vendor/      # Vendored Mermaid & Monaco Editor (Offline)
 │   ├── index.html   # Main application interface
 │   └── login.html   # Self-hosted access-key sign-in
-└── tests/           # Comprehensive node:test suite (565 tests)
+└── tests/           # Comprehensive node:test suite
 ```
 
 ---

package/cli/explorer/app.js

@@ -0,0 +1,295 @@
+// The interactive session.
+//
+// This is a prompt, not a full-screen TUI, and that is a deliberate choice.
+// A curses app takes the scrollback, the selection, and copy-paste away, and it
+// behaves badly over SSH and inside a tmux pane — which is exactly where people
+// read a codebase. A readline session keeps all of that, prints scrollable
+// output you can select, and degrades to something scriptable. The research
+// agrees: a CLI is a conversation, and a TUI earns its cost only when you are
+// manipulating state with the keyboard rather than reading.
+//
+// Two rules from the design research are load-bearing here:
+//   * TTY detection. A session that needs a terminal must never be started by a
+//     pipe, a cron job, or CI — so `runExplore` refuses and explains instead of
+//     hanging forever waiting for input nobody is there to type.
+//   * Flags → env → config precedence. `NO_COLOR` and `COLUMNS` are honored
+//     before anything is drawn, so a redirect gets plain, fitted text.
+
+import readline from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { openRepo } from './session.js';
+import { CLEAR, EXIT, commandNames, helpText, lookup, tokenize } from './commands.js';
+import { overview } from './views.js';
+import { bold, cyan, dim, ok, bad, paint } from '../ui.js';
+import { configPath, readSettings, serverUrls } from '../../server/config.js';
+import { readPidFile, pidIsAlive } from '../../server/pidfile.js';
+
+const VERSION = JSON.parse(
+  fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+// The one-time note. `onboarder` used to start a web server; now it opens this.
+// Someone who upgrades and has muscle memory for the old thing deserves to be
+// told once where the server went, and then never again.
+const HINT_MARKER = 'explorer-hint-v1';
+
+export async function runExplore({ target = '.', flags = {}, out = console.log, err = console.error, version = VERSION } = {}) {
+  // The guard. `stdin` matters as much as `stdout`: a session with no input
+  // source is a hang, and a hang in CI is worse than any error.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    out('');
+    out('  The terminal explorer needs an interactive terminal.');
+    out(dim('    In a script or a pipe, use these instead:'));
+    out(dim('      onboarder start              start the web UI'));
+    out(dim('      onboarder start background   start it detached'));
+    out(dim('      onboarder status | stop      manage a running one'));
+    out(dim('      onboarder --help             everything else'));
+    out('');
+    return 0;
+  }
+
+  let repo;
+  try {
+    repo = await openRepo(target, { onProgress: progressReporter(out) });
+  } catch (e) {
+    err('  ' + bad((e.message || String(e))));
+    err(dim('    Point it at a folder: onboarder explore /path/to/repo'));
+    return 1;
+  }
+
+  out('');
+  out(overview(repo));
+  out('');
+  if (await shouldShowHint(flags)) {
+    out(dim('  Note: `onboarder` used to start the web server. That is now `onboarder start`'));
+    out(dim('        (or the `web` command here) — this session reads the repo directly,'));
+    out(dim('        so it needs no server and works offline.'));
+    out('');
+  }
+  return session({ repo, flags, out, err, version });
+}
+
+// Scanning a large monorepo is the one genuinely slow thing this does, so it
+// says so. A silent eight seconds is indistinguishable from a hang.
+function progressReporter(out) {
+  let last = 0;
+  return ({ phase, done }) => {
+    if (!process.stdout.isTTY) return;
+    const now = Date.now();
+    if (phase === 'parse' && done && now - last > 400) {
+      last = now;
+      out(dim(`\r  scanning… ${done} files`));
+    }
+  };
+}
+
+async function shouldShowHint(flags) {
+  if (process.env.ONBOARDER_NO_HINT) return false;
+  try {
+    const marker = path.join(path.dirname(flags.config || configPath()), HINT_MARKER);
+    const seen = await fs.promises.stat(marker).then(() => true).catch(() => false);
+    if (seen) return false;
+    await fs.promises.mkdir(path.dirname(marker), { recursive: true });
+    await fs.promises.writeFile(marker, 'shown\n');
+    return true;
+  } catch {
+    // A read-only config home is not a reason to nag on every launch.
+    return false;
+  }
+}
+
+// The read loop. Commands are queued rather than awaited inline, because
+// readline emits the next line while a slow command is still running and two
+// interleaved `cd`s would leave the session pointing at a repo nobody asked
+// for.
+function session({ repo, flags, out, err, version }) {
+  const ctx = {
+    repo,
+    version,
+    flags,
+    help: (topic) => helpText(ctx, topic),
+    rescan: () => reload(ctx, ctx.repo.root),
+    loadRepo: (where) => reload(ctx, where),
+    web: () => startWeb(ctx),
+  };
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: promptFor(repo),
+    terminal: true,
+    historySize: 200,
+  });
+
+  let queue = Promise.resolve();
+  let closed = false;
+  let interrupts = 0;
+
+  rl.on('line', (line) => {
+    queue = queue.then(() => handleLine(ctx, line, rl, out, err));
+  });
+
+  // Ctrl-D on an empty line is the universal "I'm done". On a line with text,
+  // readline handles it itself; this only sees the empty-line case.
+  //
+  // Closing does NOT end the session. A piped or fast-typed sequence of commands
+  // can already be queued when the last line arrives, and resolving here would
+  // throw those away mid-flight — which is exactly what happens to `tour` when
+  // its input is followed immediately by `exit`. The exit waits on the queue.
+  rl.on('close', () => {
+    closed = true;
+    process.stdout.off('resize', onResize);
+  });
+
+  // Ctrl-C twice leaves. Once clears the line, which is what readline already
+  // does, and matches every other REPL people use.
+  rl.on('SIGINT', () => {
+    if (closed) return;
+    interrupts++;
+    if (interrupts >= 2) {
+      rl.close();
+      return;
+    }
+    out(dim('\n  Ctrl-C again to leave.'));
+    rl.setPrompt(promptFor(ctx.repo));
+    rl.prompt();
+  });
+
+  // A resize redraws rather than leaving the prompt stranded mid-wrap.
+  const onResize = () => {
+    if (!closed) rl.write(null, { ctrl: true, name: 'l' });
+  };
+  process.stdout.on('resize', onResize);
+
+  queue = queue.then(() => rl.prompt());
+
+  return new Promise((resolve) => {
+    const poll = setInterval(() => {
+      if (!closed) return;
+      clearInterval(poll);
+      // Drain whatever is still running, then say goodbye. A command that throws
+      // has already been caught in `handleLine`, so this cannot reject.
+      queue.then(() => {
+        out('');
+        out(dim('  bye.'));
+        resolve(0);
+      });
+    }, 20);
+  });
+}
+
+function promptFor(repo) {
+  return paint('  ', 'cyan') + bold(repo.name.slice(0, 24)) + paint(' > ', 'gray');
+}
+
+async function handleLine(ctx, line, rl, out, err) {
+  const words = tokenize(line);
+  if (!words.length) {
+    rl.prompt();
+    return;
+  }
+  const [name, ...args] = words;
+  const cmd = lookup(name);
+
+  if (!cmd) {
+    // The nearest command by edit distance is almost always what was meant, and
+    // a one-line "did you mean" beats a paragraph about `help`.
+    const near = nearest(name);
+    err('  ' + bad('Unknown command: ' + name) + (near ? dim('  did you mean `' + near + '`?') : dim('  try `help`')));
+    rl.prompt();
+    return;
+  }
+
+  try {
+    const result = await cmd.run(ctx, args);
+    if (result === EXIT) {
+      rl.close();
+      return;
+    }
+    if (result === CLEAR) {
+      out('\x1b[2J\x1b[3J\x1b[H');
+    } else if (result) {
+      out(result);
+    }
+  } catch (e) {
+    err('  ' + bad((e.message || String(e))));
+  }
+  // The prompt carries the repo name, and `cd` can change which repo that is.
+  // Re-reading it after every command is cheaper than tracking which commands
+  // swap the repo, and it cannot go stale.
+  rl.setPrompt(promptFor(ctx.repo));
+  rl.prompt();
+}
+
+// Swap the loaded repo. Used by `cd` and `rescan`; the scan is the slow part,
+// so the new name reaches the prompt only after it succeeds.
+async function reload(ctx, where) {
+  const target = String(where || '').trim();
+  if (!target) return '  cd needs a folder — `cd ../other-repo`.';
+  const next = await openRepo(target, { onProgress: () => {} });
+  ctx.repo = next;
+  return '\n' + overview(next);
+}
+
+// The bridge between the two surfaces. If the server is already up this just
+// prints where it is; if not, it starts it detached, so the person keeps their
+// session. The URL is the same one `onboarder start` would print, because it
+// comes from the same `serverUrls` the CLI and the banner use.
+async function startWeb(ctx) {
+  const file = ctx.flags.config || configPath();
+  const settings = await readSettings(file).catch(() => null);
+  const urls = serverUrls(settings || undefined);
+  const recorded = readPidFile(file);
+
+  if (recorded && pidIsAlive(recorded)) {
+    return ['  ' + ok('Already running.') + dim(`  PID ${recorded.pid}`), '    ' + cyan(urls.local)].join('\n');
+  }
+
+  const { runStartBackground } = await import('../commands.js');
+  const code = await runStartBackground({
+    flags: { ...ctx.flags, json: true },
+    out: () => {},
+    err: () => {},
+  });
+  if (code !== 0) return '  ' + bad('Could not start the web UI.') + dim('  Try `onboarder doctor`.');
+  return [
+    '  ' + ok('Web UI started in the background.'),
+    '    ' + cyan(urls.local),
+    dim('    onboarder logs -f to watch it · onboarder stop to shut it down'),
+  ].join('\n');
+}
+
+// Cheap "did you mean": plain Levenshtein over the command names, with a
+// distance cap of 2 so a wildly misspelled word gets "try `help`" instead of a
+// confident wrong suggestion. A wrong suggestion is worse than none.
+function nearest(word) {
+  const w = String(word).toLowerCase();
+  let best = null;
+  let bestScore = Infinity;
+  for (const name of commandNames()) {
+    const d = distance(w, name);
+    if (d < bestScore) {
+      bestScore = d;
+      best = name;
+    }
+  }
+  return bestScore <= 2 ? best : null;
+}
+
+function distance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}

package/cli/explorer/commands.js

@@ -0,0 +1,197 @@
+// The command table.
+//
+// One list, used three ways: to dispatch what someone typed, to build the `help`
+// screen, and to assert in the tests that every command is reachable, has a
+// summary, and is wired to a real view. A command that exists in one of those
+// places but not the others is the kind of thing nobody notices until a user
+// types it, so the table is the only place a command is defined at all.
+//
+// `run(ctx, args)` returns a string to print, or a marker the app layer acts on
+// (`EXIT`, `CLEAR`). `args` is an array of already-parsed words, so quoting is
+// handled once, in the tokenizer, and every command sees the same shape.
+
+import * as V from './views.js';
+
+export const EXIT = Symbol('exit');
+export const CLEAR = Symbol('clear');
+
+export const COMMANDS = [
+  {
+    name: 'help', aliases: ['?'], group: 'basics',
+    usage: 'help', summary: 'This list.',
+    run: (ctx) => ctx.help(),
+  },
+  {
+    name: 'map', aliases: ['overview', 'home'], group: 'basics',
+    usage: 'map', summary: 'What this repo is, and where to start.',
+    run: (ctx) => V.overview(ctx.repo),
+  },
+  {
+    name: 'tour', aliases: ['start', 'onboarding'], group: 'basics',
+    usage: 'tour', summary: 'The reading order a new teammate should follow.',
+    run: (ctx) => V.tour(ctx.repo),
+  },
+  {
+    name: 'explain', aliases: ['why', 'what'], group: 'basics',
+    usage: 'explain [file|folder]', summary: 'This repo, or one file/folder, in prose. No AI key needed.',
+    run: (ctx, args) => V.explain(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'tree', aliases: ['ls', 'files'], group: 'navigate',
+    usage: 'tree [folder] [depth]', summary: 'The file tree, with entries and hubs marked.',
+    run: (ctx, args) => {
+      // A lone number is the depth, not a folder called "2". `tree 3` is what
+      // everyone types when they want to see more; making them spell
+      // `tree . 3` would be pedantry in a tool built to be forgiving.
+      const onlyDepth = args.length === 1 && /^\d+$/.test(args[0]);
+      return V.tree(ctx.repo, {
+        sub: onlyDepth ? '' : (args[0] || ''),
+        depth: onlyDepth ? Number(args[0]) : (Number(args[1]) || 2),
+      });
+    },
+  },
+  {
+    name: 'find', aliases: ['search', 'grep'], group: 'navigate',
+    usage: 'find <query>', summary: 'Search. Supports ext:js, -exclude, "phrases", /regex/.',
+    run: (ctx, args) => V.find(ctx.repo, { query: args.join(' ') }),
+  },
+  {
+    name: 'show', aliases: ['open', 'cat', 'read'], group: 'navigate',
+    usage: 'show <file> [from] [count]', summary: 'Read a file. Name it loosely: `show logger.js` works.',
+    run: (ctx, args) => V.show(ctx.repo, { target: args[0] || '', from: Number(args[1]) || 0, count: Number(args[2]) || 0 }),
+  },
+  {
+    name: 'deps', aliases: ['connections', 'graph'], group: 'navigate',
+    usage: 'deps <file>', summary: 'What a file imports, and what imports it.',
+    run: (ctx, args) => V.deps(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'health', aliases: ['grade'], group: 'analyze',
+    usage: 'health', summary: 'Health grade, riskiest files, debt.',
+    run: (ctx) => V.health(ctx.repo),
+  },
+  {
+    name: 'hubs', aliases: ['core'], group: 'analyze',
+    usage: 'hubs', summary: 'The most depended-on files.',
+    run: (ctx) => V.hubs(ctx.repo),
+  },
+  {
+    name: 'layers', aliases: ['depth'], group: 'analyze',
+    usage: 'layers', summary: 'Import depth, shallowest first.',
+    run: (ctx) => V.layers(ctx.repo),
+  },
+  {
+    name: 'patterns', aliases: ['architecture'], group: 'analyze',
+    usage: 'patterns', summary: 'What the architecture looks like, in prose.',
+    run: (ctx) => V.patterns(ctx.repo),
+  },
+  {
+    name: 'stats', aliases: ['numbers'], group: 'analyze',
+    usage: 'stats', summary: 'Languages, biggest folders and files, complexity.',
+    run: (ctx) => V.stats(ctx.repo),
+  },
+  {
+    name: 'security', aliases: ['audit'], group: 'analyze',
+    usage: 'security', summary: 'Heuristic findings from the built-in rules.',
+    run: (ctx) => V.security(ctx.repo),
+  },
+  {
+    name: 'stack', aliases: ['packages'], group: 'analyze',
+    usage: 'stack', summary: 'Declared dependencies and frameworks.',
+    run: (ctx) => V.stack(ctx.repo),
+  },
+  {
+    name: 'entry', aliases: ['entries'], group: 'analyze',
+    usage: 'entry', summary: 'Recognized entry points and how far they reach.',
+    run: (ctx) => V.entry(ctx.repo),
+  },
+  {
+    name: 'externals', aliases: ['drift'], group: 'analyze',
+    usage: 'externals', summary: 'External packages, plus dependency drift.',
+    run: (ctx) => V.externals(ctx.repo),
+  },
+  {
+    name: 'about', aliases: ['version'], group: 'session',
+    usage: 'about', summary: 'Version, repo path, and what is indexed.',
+    run: (ctx) => V.about(ctx.repo, ctx.version),
+  },
+  {
+    name: 'rescan', aliases: ['reload'], group: 'session',
+    usage: 'rescan', summary: 'Re-read the repo from disk.',
+    run: (ctx) => ctx.rescan(),
+  },
+  {
+    name: 'cd', aliases: ['open-repo', 'use'], group: 'session',
+    usage: 'cd <folder>', summary: 'Load a different repository.',
+    run: (ctx, args) => ctx.loadRepo(args.join(' ')),
+  },
+  {
+    name: 'web', aliases: ['site', 'serve'], group: 'session',
+    usage: 'web', summary: 'Start the web UI and print its URL.',
+    run: (ctx) => ctx.web(),
+  },
+  {
+    name: 'clear', aliases: ['cls'], group: 'session',
+    usage: 'clear', summary: 'Clear the screen.',
+    run: () => CLEAR,
+  },
+  {
+    name: 'exit', aliases: ['quit', 'q'], group: 'session',
+    usage: 'exit', summary: 'Leave. Ctrl-D does the same.',
+    run: () => EXIT,
+  },
+];
+
+// One lookup for every spelling a person might type, built once at import.
+const BY_NAME = new Map();
+for (const cmd of COMMANDS) {
+  BY_NAME.set(cmd.name, cmd);
+  for (const a of cmd.aliases) BY_NAME.set(a, cmd);
+}
+
+export function lookup(word) {
+  return BY_NAME.get(String(word || '').toLowerCase());
+}
+
+// Every canonical name, for "did you mean" matching. Aliases are deliberately
+// excluded: suggesting `open` when someone typed `sho` is less useful than
+// suggesting `show`, which is the word they were reaching for.
+export function commandNames() {
+  return COMMANDS.map((c) => c.name);
+}
+
+// `help <command>` answers about one command; bare `help` lists them, grouped so
+// the shape of the tool is visible rather than alphabetical.
+export function helpText(ctx, topic = '') {
+  if (topic) {
+    const cmd = lookup(topic);
+    if (!cmd) return `  No command called "${topic}". Try \`help\`.`;
+    const also = cmd.aliases.length ? `  (also: ${cmd.aliases.join(', ')})` : '';
+    return ['  ' + cmd.usage + also, '    ' + cmd.summary].join('\n');
+  }
+  const groups = new Map();
+  for (const cmd of COMMANDS) {
+    if (!groups.has(cmd.group)) groups.set(cmd.group, []);
+    groups.get(cmd.group).push(cmd);
+  }
+  const room = Math.max(...COMMANDS.map((c) => c.usage.length));
+  const out = [];
+  for (const [group, list] of groups) {
+    out.push('  ' + group.toUpperCase());
+    for (const c of list) out.push('    ' + c.usage.padEnd(room) + '  ' + c.summary);
+  }
+  out.push('');
+  out.push('  ' + (ctx?.repo ? ctx.repo.name : 'onboarder') + ' · Ctrl-D or `exit` to leave · Ctrl-C twice to quit');
+  return out.join('\n');
+}
+
+// Split a typed line into words, honoring quotes so `find "exact phrase"` and
+// `show "my file.js"` arrive as one argument each. Done once, here, so no
+// command has to re-implement it.
+export function tokenize(line) {
+  const out = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(String(line || '')))) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}