codebase-onboarder 0.1.0

package/public/js/serverSettings.js

@@ -0,0 +1,169 @@
+// The Server drawer: the web face of the same config file the CLI wizard
+// writes. Reads come back with the key masked; saves send only the changed
+// keys; rotation reveals the new key once and stores it in this browser.
+//
+// The module owns its own DOM and its own round-trips. What it borrows from
+// app.js is the drawer choreography — one scrim at a time, Escape to close —
+// which is why it returns open/close/isOpen instead of wiring the topbar
+// button itself.
+
+import { getAccessKey, setAccessKey, fetchServerSettings, updateServerSettings, rotateServerAccessKey } from '/js/api.js';
+
+// A function declaration, not a const arrow: the import-time DOM check in
+// tests/frontend.test.js blanks top-level function bodies but reads const
+// bodies, and this module must stay importable from Node.
+function $(id) {
+  return document.getElementById(id);
+}
+
+const MODE_NOTES = {
+  local: 'Local mode answers only this machine. No key, no network — the safe default.',
+  'self-hosted': 'Self-hosted answers whoever can reach the port, so every API call needs the access key below.',
+};
+
+export function createServerDrawer(options = {}) {
+  // Pulled out of the parameter list on purpose: the front-end static check
+  // in tests/frontend.test.js only understands plain params, and `toast` must
+  // show up as a declaration, not a dangling call.
+  const toast = typeof options.toast === 'function' ? options.toast : () => {};
+  const dom = {};
+  [
+    'serverDrawer', 'serverScrim', 'serverClose', 'serverModeNote', 'srvMode', 'srvHost', 'srvPort',
+    'srvDomain', 'srvDomainField', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
+    'srvFreshKeyRow', 'srvFreshKey', 'srvCopyKey', 'srvKeyHint', 'srvName', 'srvEmail',
+    'srvTunnelCloudflare', 'srvTunnelCloudflareStatus', 'srvTunnelTailscale', 'srvTunnelTailscaleStatus',
+    'srvSave', 'srvStatus', 'srvConfigPath',
+  ].forEach((id) => (dom[id] = $(id)));
+
+  let current = null; // the last settings body the server sent
+
+  function status(text, cls = '') {
+    dom.srvStatus.className = 'drawer-status' + (cls ? ' ' + cls : '');
+    dom.srvStatus.textContent = text;
+  }
+
+  function tunnelLine(el, t) {
+    if (!t) { el.textContent = ''; return; }
+    if (!t.enabled) {
+      el.textContent = t.installed ? 'Off.' : `Off — and ${t.install || 'the binary is not installed'}.`;
+      return;
+    }
+    el.textContent = t.installed
+      ? `On. Start it with: ${t.command}`
+      : `On, but the binary is missing — ${t.install || 'install it first'}.`;
+  }
+
+  function render(data) {
+    current = data;
+    const s = data.settings;
+    dom.srvMode.value = s.mode;
+    dom.serverModeNote.textContent = MODE_NOTES[s.mode] || '';
+    dom.srvHost.value = s.host;
+    dom.srvPort.value = s.port;
+    dom.srvDomain.value = s.domain || '';
+    dom.srvAutoOpen.checked = Boolean(s.autoOpen);
+    dom.srvName.value = s.account?.name || '';
+    dom.srvEmail.value = s.account?.email || '';
+    dom.srvTunnelCloudflare.checked = Boolean(s.tunnel?.cloudflare);
+    dom.srvTunnelTailscale.checked = Boolean(s.tunnel?.tailscale);
+    tunnelLine(dom.srvTunnelCloudflareStatus, data.tunnels?.cloudflare);
+    tunnelLine(dom.srvTunnelTailscaleStatus, data.tunnels?.tailscale);
+    dom.srvConfigPath.textContent = `Config file: ${data.configFile}`;
+    dom.srvKeyMasked.value = s.accessKeyMasked || (s.hasAccessKey ? '' : '(none set — the API refuses every call)');
+    dom.srvKeyHint.textContent = getAccessKey()
+      ? 'This browser holds a key and sends it with every request.'
+      : 'This browser has no key saved. Paste one via rotate, or open the link from the startup banner.';
+    applyModeVisibility();
+  }
+
+  // Mode drives which rows even make sense: local wipes the network/security
+  // fields in the schema, so asking for them here would be collecting lies.
+  function applyModeVisibility() {
+    const remote = dom.srvMode.value === 'self-hosted';
+    dom.srvKeySection.hidden = !remote;
+    dom.srvDomainField.hidden = !remote;
+    dom.serverModeNote.textContent = MODE_NOTES[dom.srvMode.value] || '';
+  }
+
+  async function open() {
+    dom.serverDrawer.hidden = false;
+    dom.serverScrim.hidden = false;
+    dom.srvFreshKeyRow.hidden = true;
+    status('Reading the server…');
+    try {
+      render(await fetchServerSettings());
+      status('');
+    } catch (err) {
+      status(err.message, 'err');
+    }
+  }
+
+  function close() {
+    dom.serverDrawer.hidden = true;
+    dom.serverScrim.hidden = true;
+  }
+
+
+  async function save() {
+    const patch = {
+      mode: dom.srvMode.value,
+      host: dom.srvHost.value.trim() || '127.0.0.1',
+      port: Number(dom.srvPort.value),
+      autoOpen: dom.srvAutoOpen.checked,
+      account: { name: dom.srvName.value.trim(), email: dom.srvEmail.value.trim() },
+      tunnel: { cloudflare: dom.srvTunnelCloudflare.checked, tailscale: dom.srvTunnelTailscale.checked },
+    };
+    if (patch.mode === 'self-hosted') patch.domain = dom.srvDomain.value.trim();
+    status('Saving…');
+    try {
+      const data = await updateServerSettings(patch);
+      render({ ...current, settings: data.settings });
+      const restart = (data.restartRequired || []).join(' and ');
+      status(
+        restart
+          ? `Saved. The ${restart} change takes effect after a restart — the running socket cannot move.`
+          : 'Saved — live already.',
+        'ok',
+      );
+    } catch (err) {
+      status(err.message, 'err');
+    }
+  }
+
+  async function rotate() {
+    status('Rotating…');
+    try {
+      const data = await rotateServerAccessKey();
+      // The one moment a key is ever shown. It goes straight into this
+      // browser's localStorage too, so this tab keeps working without a paste.
+      setAccessKey(data.accessKey);
+      render({ ...current, settings: data.settings });
+      dom.srvFreshKey.value = data.accessKey;
+      dom.srvFreshKeyRow.hidden = false; // render() does not know about the reveal
+      status('Rotated. The old key is dead; update every other device.', 'ok');
+    } catch (err) {
+      status(err.message, 'err');
+    }
+  }
+
+  dom.srvMode.addEventListener('change', applyModeVisibility);
+  dom.srvSave.addEventListener('click', save);
+  dom.srvRotate.addEventListener('click', rotate);
+  dom.serverClose.addEventListener('click', close);
+  dom.serverScrim.addEventListener('click', close);
+  dom.srvCopyKey.addEventListener('click', async () => {
+    try {
+      await navigator.clipboard.writeText(dom.srvFreshKey.value);
+      toast('Key copied');
+    } catch {
+      dom.srvFreshKey.select(); // clipboard refused — select so a Ctrl+C works
+    }
+  });
+
+  return {
+    open,
+    close,
+    isOpen: () => !dom.serverDrawer.hidden,
+  };
+}
+

package/public/js/state.js

@@ -0,0 +1,192 @@
+// The application's state, in one place.
+//
+// This is a plain mutable object, not a reactive store, and that is deliberate.
+// Rendering here is expensive and stateful — the canvas holds a pan/zoom
+// transform, the code tab holds a Monaco editor — so "every mutation triggers a
+// re-render" would be both slow and destructive. Callers still decide what to
+// redraw. What this module does own is the state's *invariants*, which used to
+// be maintained by convention in a 2,400-line file and are now enforced in one
+// place that can be tested.
+//
+// No DOM, no imports from the view layer: importable in Node.
+
+// The views that share the Explorer tab and its canvas.
+export const EXPLORER_VIEWS = ['map', 'files', 'patterns', 'health', 'security', 'history', 'services', 'tour', 'atlas'];
+
+// Views whose default inspector panel is their own, rather than the overview.
+const PANEL_VIEWS = { patterns: 'patterns', health: 'health', security: 'security', history: 'history' };
+
+// Per-repo state, rebuilt by `loadRepo`. Split out from the rest so "what has
+// to be reset when a new repo arrives" is a list in one place rather than a
+// thing you remember — forgetting an entry here is how a new repo inherits the
+// previous one's open tabs.
+function perRepo() {
+  return {
+    scan: null,
+    facts: null,
+    manifest: null,
+    stack: null,
+    health: null,
+    security: null,
+    history: null,
+    patterns: null,
+    treeData: null,
+    scanId: null,
+    cloneId: null,
+    browserSource: null,
+    view: 'map',
+    lastExplorer: 'map',
+    folder: '',
+    detail: null,        // file open in deep-dive, if any
+    selected: null,      // the focused FILE (the inspector's current subject)
+    focusedFolder: null, // the focused FOLDER subject, when it's a folder
+    tour: { stops: [], idx: 0 },
+    currentDiagram: { source: '', nodes: {} },
+    aiDiagrams: {},      // viewKey -> { body, caption } — unthemed, composed at render
+    aiActiveKey: null,   // which viewKey is currently showing its AI draft
+    docs: { rendered: false, writing: false, tabs: new Map(), active: 'overview' },
+    about: { rendered: false },
+    mm: { expanded: new Set(['dir:']) }, // tree map: open folder/file cells
+    filters: { text: '', showTests: true, depth: 0 },
+    atlas: { built: false, items: [] },
+    atlasOpen: null,     // an atlas card currently open on the canvas
+    code: { path: null, history: [], idx: -1, cache: {} }, // the Code tab
+    // Deep-analysis engines (semgrep, gitleaks, knip…). `status` is which are
+    // installed; `report` is the last run; `findings` merge into the security
+    // view. Only ever filled for a server-side scan — a browser-picked folder
+    // has no server-visible root for a tool to read.
+    //
+    // `install` is per-engine GUI install state ({ running, log, ok, error });
+    // `options` is the per-engine form values the Configure panel edits.
+    tools: {
+      status: null, report: null, running: false, loading: false,
+      findings: [], merged: 0, error: null,
+      install: {}, options: {},
+    },
+    // The Deep Analysis view's own controls: which findings are on screen, and
+    // whatever the AI has said about the report so far. Per-repo, so a new scan
+    // does not inherit the previous repo's filters or its explanation.
+    analysis: {
+      severity: 'all', tool: 'all', q: '',
+      ai: { text: '', error: '', running: false, question: '' },
+    },
+    history: null,
+  };
+}
+
+export const state = perRepo();
+
+// Replaces the per-repo state wholesale. Anything not listed in `perRepo()`
+// survives, which is what you want for preferences like the theme.
+export function loadRepo({ scan, facts, manifest, history, scanId, cloneId }, extra = {}) {
+  Object.assign(state, perRepo(), {
+    scan,
+    facts,
+    manifest: manifest || { services: [] },
+    history: history || null,
+    scanId: scanId || null,
+    cloneId: cloneId || null,
+  }, extra);
+  return state;
+}
+
+export function unloadRepo() {
+  Object.assign(state, perRepo());
+}
+
+// Focus: a file and a folder are alternatives, never both. Every selection path
+// in the app funnels through these, so the inspector can trust that reading
+// `selected` first and `focusedFolder` second gives an unambiguous subject.
+export function focusFile(path) {
+  state.selected = path;
+  state.focusedFolder = null;
+}
+
+export function focusFolder(path) {
+  state.focusedFolder = path;
+  state.selected = null;
+}
+
+export function clearFocus() {
+  state.selected = null;
+  state.focusedFolder = null;
+  state.detail = null;
+}
+
+// Which subject the inspector should show, and the label for the "back" control
+// that returns to the view's own panel. Pure function of state, so the panel
+// and the canvas can never disagree about what is focused.
+export function inspectorSubject(s = state) {
+  const backLabel = inspectorBackLabel(s);
+  if (s.selected && s.facts && s.facts.fanIn[s.selected] !== undefined) {
+    return { kind: 'file', path: s.selected, backLabel };
+  }
+  if (s.focusedFolder !== null && s.focusedFolder !== undefined) {
+    return { kind: 'folder', path: s.focusedFolder, backLabel };
+  }
+  if (PANEL_VIEWS[s.view]) return { kind: s.view, backLabel: null };
+  if (s.view === 'files') return { kind: 'folder', path: s.folder, backLabel };
+  return { kind: 'overview', backLabel: null };
+}
+
+export function inspectorBackLabel(s = state) {
+  if (s.view === 'tour') return null; // the tour drives its own focus
+  if (s.view === 'files') return s.folder ? 'the folder' : 'the overview';
+  if (PANEL_VIEWS[s.view]) return PANEL_VIEWS[s.view];
+  return 'the overview';
+}
+
+export function isExplorerView(view) {
+  return EXPLORER_VIEWS.includes(view);
+}
+
+// Which slot in `aiDiagrams` the current view's AI draft belongs to. Two views
+// that show different pictures must never share a key, or one's draft appears
+// over the other's diagram.
+export function aiViewKey(s = state) {
+  // A tour draft belongs to the stop, not to whatever file was last selected.
+  if (s.view === 'tour') return `tour:${s.tour.idx}`;
+  if (s.view === 'atlas') {
+    return s.atlasOpen ? `atlas:${s.atlasOpen.kind}:${s.atlasOpen.path}` : 'atlas:';
+  }
+  return `${s.view}:${s.detail || s.folder || ''}`;
+}
+
+// ---- the Code tab's history ------------------------------------------------
+//
+// A browser-style back/forward stack over the files opened in the Code tab.
+// `idx` is a cursor into `history`, not always its last entry: after going back,
+// opening a new file has to discard the entries in front of the cursor, exactly
+// as a browser drops the forward stack. That rule is the whole reason this lives
+// here with a test rather than inline in a render function.
+
+// Which file the Code tab should show when it is asked to render. The chain is
+// most-specific-first: what the tab already had, then whatever the rest of the
+// app is looking at, then the repo's own front door, then anything at all.
+export function defaultCodePath(s = state) {
+  const { scan, facts, code } = s;
+  // `facts.entries` holds plain path strings — `graph.js` builds it by mapping
+  // files to `f.path`. (`facts.hubs`, confusingly, holds objects.) An earlier
+  // version of this accepted either shape for `entries`; nothing has ever
+  // produced the object one, and pretending otherwise hid the asymmetry.
+  return code.path || s.detail || s.selected || facts?.entries?.[0]
+    || scan?.files?.[0]?.path || scan?.allFiles?.[0] || null;
+}
+
+export function pushCodeHistory(path, s = state) {
+  const h = s.code.history;
+  if (h[s.code.idx] === path) return; // re-opening the current file is not a move
+  h.length = s.code.idx + 1;          // drop any forward entries
+  h.push(path);
+  s.code.idx = h.length - 1;
+}
+
+// Moves the cursor by `delta` and reports where it landed, or null if that would
+// step off either end. The caller opens the returned path; refusing to move and
+// returning null is how the disabled arrow buttons stay honest.
+export function codeHistoryTarget(delta, s = state) {
+  const next = s.code.idx + delta;
+  if (next < 0 || next >= s.code.history.length) return null;
+  s.code.idx = next;
+  return s.code.history[next];
+}

package/public/js/tour.js

@@ -0,0 +1,17 @@
+// The guided walk, as the browser sees it.
+//
+// The ordering itself moved to `shared/analyzer/tour.js`: the MCP server hands the
+// same list to an agent, and two copies of "which eight files should a newcomer
+// read first" would eventually disagree. This module keeps only what is genuinely
+// the view's — the label the tour bar draws.
+
+import { buildTourStops, tourStopTitle } from '/shared/analyzer/tour.js';
+
+export { buildTourStops };
+
+export function describeStop(stop, index, total) {
+  return {
+    title: tourStopTitle(stop),
+    count: `${index + 1} / ${total}`,
+  };
+}

package/public/js/transitions.js

@@ -0,0 +1,15 @@
+export function withTransition(callback) {
+  if (document.startViewTransition) {
+    document.startViewTransition(callback);
+  } else {
+    callback();
+  }
+}
+
+export function setupViewTransitionNames(elements) {
+  // Utility for adding transition names if needed
+  Object.entries(elements).forEach(([id, name]) => {
+    const el = document.getElementById(id);
+    if (el) el.style.viewTransitionName = name;
+  });
+}

package/public/js/tree.js

@@ -0,0 +1,200 @@
+// Sidebar file tree. Built from the plain path list, rendered with
+// collapsible folders, badges for entries and hubs, and a substring filter.
+
+import { escapeHtml } from './html.js';
+
+export function buildTree(allFiles) {
+  const root = { name: '', path: '', dirs: new Map(), files: [] };
+  for (const path of allFiles) {
+    const parts = path.split('/');
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const name = parts[i];
+      if (!node.dirs.has(name)) {
+        const dirPath = parts.slice(0, i + 1).join('/');
+        node.dirs.set(name, { name, path: dirPath, dirs: new Map(), files: [] });
+      }
+      node = node.dirs.get(name);
+    }
+    node.files.push(path);
+  }
+  return root;
+}
+
+// The folder node at `path`, or null if no such folder exists. `''` is the root,
+// which is a real folder here and not "no folder" — several callers pass the
+// empty string on purpose.
+export function findNode(root, path) {
+  if (!path) return root;
+  let node = root;
+  for (const part of path.split('/')) {
+    node = node.dirs?.get(part);
+    if (!node) return null;
+  }
+  return node;
+}
+
+// Files at or below a node. Used to rank folders by size when choosing which
+// ones are worth documenting.
+export function countFiles(node) {
+  if (!node) return 0;
+  let n = node.files.length;
+  for (const dir of node.dirs.values()) n += countFiles(dir);
+  return n;
+}
+
+// A copy of the tree with the filtered-out files removed, and with folders that
+// end up holding nothing removed too — otherwise the tree map fills with empty
+// scaffolding whose labels no longer match anything inside them.
+//
+// `include` is a predicate over file paths, and `matchesFolder` an optional one
+// over folder paths: a folder whose own name matches keeps its whole branch,
+// because searching for "lib" should show you lib's contents rather than an empty
+// folder named lib. The root always survives, even when nothing matches, so the
+// caller has something to render instead of null.
+//
+// The predicates are passed in rather than built here: this file has to stay
+// importable in Node to be testable, which rules out reaching into `/shared/`.
+export function pruneTree(root, include, matchesFolder = null) {
+  if (!include) return root;
+  const walk = (node) => {
+    if (node.path && matchesFolder?.(node.path)) return node;
+    const dirs = new Map();
+    for (const [name, child] of node.dirs) {
+      const pruned = walk(child);
+      if (pruned) dirs.set(name, pruned);
+    }
+    const files = node.files.filter(include);
+    if (!node.path) return { ...node, dirs, files }; // the root always survives
+    if (!dirs.size && !files.length) return null;
+    return { ...node, dirs, files };
+  };
+  return walk(root);
+}
+
+// The set of folder ids to treat as open when the reader picks a depth from the
+// stage's depth selector. Ids are `dir:` + path, which is the vocabulary the tree
+// map's cells use; `dir:` alone is the root.
+export function expandedToDepth(root, maxDepth) {
+  const out = new Set();
+  const walk = (node, depth) => {
+    if (depth > maxDepth) return;
+    out.add('dir:' + node.path);
+    for (const d of node.dirs.values()) walk(d, depth + 1);
+  };
+  walk(root, 0);
+  return out;
+}
+
+const openState = new Set();
+
+export function resetOpenState() {
+  openState.clear();
+}
+
+export function renderTree(container, tree, ctx) {
+  const { facts, filter = '', selected, onFile, onFolder } = ctx;
+  container.innerHTML = '';
+  const parsedSet = new Set(ctx.parsedPaths || []);
+  const hubSet = new Set((facts?.hubs || []).filter((h) => h.fanIn >= 4).map((h) => h.path));
+  const entrySet = new Set(facts?.entries || []);
+  const needle = filter.trim().toLowerCase();
+
+  const frag = document.createDocumentFragment();
+
+  const renderDir = (node, parent) => {
+    const dirNames = [...node.dirs.keys()].sort();
+    const filePaths = node.files.slice().sort();
+
+    for (const name of dirNames) {
+      const child = node.dirs.get(name);
+      if (needle && !subtreeHas(child, needle)) continue;
+
+      const wrap = document.createElement('div');
+      wrap.className = 'tree-dir' + (openState.has(child.path) || needle ? ' is-open' : '');
+
+      const head = document.createElement('div');
+      head.className = 'tree-dir-head';
+      const count = countFiles(child);
+      head.innerHTML = `<span class="tree-caret">▸</span><span>${escapeHtml(name)}/</span><span class="tree-count">${count}</span>`;
+      head.addEventListener('click', () => {
+        if (openState.has(child.path)) openState.delete(child.path);
+        else openState.add(child.path);
+        wrap.classList.toggle('is-open');
+        onFolder?.(child.path);
+      });
+      wrap.appendChild(head);
+
+      const kids = document.createElement('div');
+      kids.className = 'tree-children';
+      renderDir(child, kids);
+      wrap.appendChild(kids);
+      parent.appendChild(wrap);
+    }
+
+    for (const path of filePaths) {
+      const name = path.split('/').pop();
+      if (needle && !path.toLowerCase().includes(needle)) continue;
+      const el = document.createElement('div');
+      el.className = 'tree-file' + (path === selected ? ' is-selected' : '');
+      el.dataset.path = path;
+
+      const dot = document.createElement('span');
+      dot.className = 'tree-dot';
+      dot.style.backgroundColor = getExtColor(path);
+      el.appendChild(dot);
+
+      const label = document.createElement('span');
+      label.textContent = name;
+      if (!parsedSet.has(path)) label.style.color = 'var(--faint)';
+      el.appendChild(label);
+
+      if (entrySet.has(path)) {
+        el.appendChild(badge('in', 'is-entry'));
+      } else if (hubSet.has(path)) {
+        el.appendChild(badge('hub', 'is-hub'));
+      }
+      el.addEventListener('click', () => onFile?.(path));
+      parent.appendChild(el);
+    }
+  };
+
+  renderDir(tree, frag);
+  container.appendChild(frag);
+
+  if (!container.children.length) {
+    container.innerHTML = '<p style="padding:10px;color:var(--faint)">Nothing matches that filter.</p>';
+  }
+}
+
+function subtreeHas(node, needle) {
+  if (node.path.toLowerCase().includes(needle)) return true;
+  for (const f of node.files) if (f.toLowerCase().includes(needle)) return true;
+  for (const child of node.dirs.values()) if (subtreeHas(child, needle)) return true;
+  return false;
+}
+
+function badge(text, cls) {
+  const b = document.createElement('span');
+  b.className = 'tree-badge ' + cls;
+  b.textContent = text;
+  return b;
+}
+
+function getExtColor(path) {
+  const ext = (path.match(/\.([A-Za-z0-9]+)$/) || [, ''])[1].toLowerCase();
+  switch (ext) {
+    case 'ts': case 'tsx': return '#3178c6';
+    case 'js': case 'jsx': case 'mjs': case 'cjs': return '#f7df1e';
+    case 'py': return '#3572A5';
+    case 'rs': return '#dea584';
+    case 'go': return '#00ADD8';
+    case 'java': return '#b07219';
+    case 'cs': return '#178600';
+    case 'html': return '#e34c26';
+    case 'css': return '#563d7c';
+    case 'json': return '#cbcb41';
+    case 'md': return '#083fa1';
+    default: return 'var(--faint)';
+  }
+}