codebase-onboarder 0.5.0 → 0.6.0

package/cli/explorer/views.js

@@ -11,8 +11,10 @@
 // every other panel in this project is, including after a resize.
 
 import { bold, cyan, dim, ok, warn, bad, panel, row, fit, termWidth } from '../ui.js';
+import { labelled } from './graphs.js';
 import { fileFacts, readRepoFile, resolveTarget, searchRepo, explainRepoFile, explainRepoFolder, explainRepoOverview } from './session.js';
 import { scanCaveats } from '../../shared/analyzer/explainLocal.js';
+import { wrapText } from './wrap.js';
 
 const MAX = 200; // a ceiling on any list, so one command cannot flood a terminal
 
@@ -27,7 +29,12 @@ const GLYPHS = process.platform === 'win32' && !process.env.WT_SESSION
 // — it is the first thing printed, so it sets the impression of everything else.
 // On a narrow terminal it drops hints rather than wrapping.
 function hintBar(hints) {
-  const room = Math.max(8, termWidth() - 2);
+  // The room is the terminal minus the 2-space lead. The `Math.max(8, …)` that
+  // used to be here was a floor *above* the available width on an 8-column
+  // terminal, which guarantees an overflow — the exact opposite of what a
+  // hint bar is for. Below the width of one hint, the hint is cut to fit
+  // rather than allowed to wrap.
+  const room = Math.max(1, termWidth() - 2);
   const parts = [];
   for (const h of hints) {
     const next = parts.length ? parts.join(' · ') + ' · ' + h : h;
@@ -38,41 +45,7 @@ function hintBar(hints) {
   return dim('  ' + line);
 }
 
-// Word-wrap plain text to the terminal, preserving the indent on continuation
-// lines. Applied *before* painting, so the wrap never has to understand ANSI —
-// the styled string is built from already-wrapped plain text.
-//
-// This is what keeps a long caveat or a paragraph of explanation from running
-// off the right edge. The engine's own messages are written as sentences for a
-// browser panel; a terminal needs them folded.
-function wrapText(text, indent = '  ', room = termWidth() - indent.length) {
-  const out = [];
-  for (const para of String(text).split('\n')) {
-    if (!para.trim()) {
-      out.push('');
-      continue;
-    }
-    let line = '';
-    for (const word of para.split(/\s+/)) {
-      if (!line) {
-        line = word;
-      } else if (line.length + 1 + word.length <= room) {
-        line += ' ' + word;
-      } else {
-        out.push(indent + line);
-        line = word;
-      }
-      // A single word longer than the room is hard-split rather than allowed to
-      // overflow — a long import specifier is exactly the case that shows up.
-      while (line.length > room) {
-        out.push(indent + line.slice(0, room));
-        line = line.slice(room);
-      }
-    }
-    out.push(indent + line);
-  }
-  return out.join('\n');
-}
+// `wrapText` now lives in `./wrap.js`, shared with the command table's help screen.
 
 // -------------------------------------------------------------- overview ---
 
@@ -148,29 +121,34 @@ export function tree(repo, { sub = '', depth = 2, limit = MAX } = {}) {
   const walk = (node, depthLeft, indent) => {
     for (const child of [...node.dirs.values()].sort((a, b) => a.name.localeCompare(b.name))) {
       if (budget <= 0) return;
-      const room = Math.max(8, termWidth() - indent.length - 12);
-      lines.push(indent + dim(GLYPHS.dir + ' ') + cyan(fit(child.name, room)) + dim(`  ${countUnder(child)}`));
+      const room = Math.max(4, termWidth() - indent.length - 2 - 4);
+      lines.push(labelled(dim(GLYPHS.dir + ' '), child.name, dim(`  ${countUnder(child)}`), { pad: indent.length }));
       budget--;
       if (depthLeft > 1) walk(child, depthLeft - 1, indent + '  ');
     }
     for (const f of node.files) {
       if (budget <= 0) return;
-      lines.push(indent + fileLine(repo, f));
+      lines.push(fileLine(repo, f, indent.length));
       budget--;
     }
   };
   walk(root, Math.max(1, Number(depth) || 2), '  ');
 
-  const out = [bold('  tree · ' + (prefix || '.')) + dim(`  ${scoped.length} files, depth ${Math.max(1, Number(depth) || 2)}`), lines.join('\n')];
-  if (budget <= 0) out.push(dim('  … list stopped early — tree <folder> <depth> to go deeper'));
+  const out = [dim(fit(`  tree · ${prefix || '.'}  ${scoped.length} files, depth ${Math.max(1, Number(depth) || 2)}`, Math.max(4, termWidth() - 2))), lines.join('\n')];
+  if (budget <= 0) out.push(dim(wrapText('… list stopped early — tree <folder> <depth> to go deeper', '  ')));
   return out.join('\n');
 }
 
-function fileLine(repo, f) {
+function fileLine(repo, f, indent = 2) {
   const role = fileFacts(repo, f).role;
   const badge = role === 'entry' ? ok(GLYPHS.entry) : role === 'hub' ? warn(GLYPHS.hub) : dim(GLYPHS.file);
-  const room = Math.max(10, termWidth() - 22);
-  return badge + ' ' + fit(f.name, room) + '  ' + dim(String(f.ext || '').padEnd(6)) + dim(String(f.loc || 0).padStart(5));
+  // The name is the identifying part; the extension and line count are the first
+  // things to go when there is no room. `tree` on a phone-width terminal should
+  // still list the files, just less verbosely.
+  const tail = ' ' + dim(String(f.ext || '').padEnd(6)) + dim(String(f.loc || 0).padStart(5));
+  // The depth indent is part of the budget — it used to be prepended by the
+  // caller, which made every nested row as many cells too wide as its depth.
+  return labelled(badge + ' ', f.name, tail, { pad: indent });
 }
 
 function countUnder(node) {
@@ -187,21 +165,25 @@ function countUnder(node) {
 // identifies the hit.
 export function find(repo, { query = '', limit = 12 } = {}) {
   if (!String(query).trim()) {
-    return dim('  Try: find resolveImport   ·   find ext:rs -test   ·   find "exact phrase"   ·   find /regex/');
+    return dim(wrapText('Try: find resolveImport · find ext:rs -test · find "exact phrase" · find /regex/', '  '));
   }
   const res = searchRepo(repo, query, { limit: Math.min(Number(limit) || 12, MAX) });
   if (res.error) return bad('  ' + res.error);
-  if (!res.results.length) return dim(`  No match for "${query}" in ${res.indexed} indexed files.`);
+  if (!res.results.length) return dim(wrapText(`No match for "${query}" in ${res.indexed} indexed files.`, '  '));
 
   const w = termWidth();
-  const pathRoom = Math.max(16, Math.min(46, Math.floor(w * 0.42)));
+  // Path, line number and snippet share the terminal. The snippet is the least
+  // identifying part, so it goes first on a narrow terminal; `labelled` owns the
+  // indent, which is why the row cannot be `indent + name + count` glued
+  // together and then be a few cells too wide.
+  const lineRoom = 5;
   const lines = res.results.map((r) => {
-    const snippetRoom = w - pathRoom - 18;
+    const snippetRoom = w - 2 - lineRoom - 2;
     const snip = snippetRoom > 10 ? dim('  ' + fit(r.snippet, snippetRoom, { tail: false })) : '';
-    return '  ' + fit(r.path, pathRoom) + dim(String(r.line).padStart(5)) + '  ' + snip;
+    return labelled('', r.path, dim(String(r.line).padStart(lineRoom)) + snip, { pad: 2 });
   });
   const kind = res.advanced ? 'filtered query' : 'query';
-  const head = dim(`  ${res.total} match${res.total === 1 ? '' : 'es'} (${kind}) across ${res.indexed} indexed files`);
+  const head = dim(fit(`  ${res.total} match${res.total === 1 ? '' : 'es'} (${kind}) across ${res.indexed} indexed files`, Math.max(1, w - 2)));
   return [head, ...lines, hintBar(['show <path> to read one', 'deps <path> to trace it'])].join('\n');
 }
 
@@ -218,8 +200,15 @@ export async function show(repo, { target = '', from = 0, count = 0 } = {}) {
   const file = found.file;
   const text = await readRepoFile(repo, file.path);
   const lines = text.split('\n');
-  const start = Math.max(1, Number(from) || 1);
-  const room = count > 0 ? Math.min(Number(count), 400) : Math.min(lines.length, 40);
+  // `null` here means the argument was present but not a usable line number
+  // (`show f 1.5`), which the command layer turns into a message rather than a
+  // silent fallback. A string means a caller passed a bad value, so say so
+  // instead of coercing it into a nonsensical range.
+  if (from === null || count === null) {
+    return bad(wrapText('Line numbers must be whole numbers.', '  ')) + dim(fit('  Try: `show ' + file.name + ' 40 20`', Math.max(1, termWidth() - 2)));
+  }
+  const start = Math.max(1, from || 1);
+  const room = count > 0 ? Math.min(count, 400) : Math.min(lines.length, 40);
   const end = Math.min(lines.length, start + room - 1);
 
   const gutter = String(end).length;
@@ -240,11 +229,21 @@ export async function show(repo, { target = '', from = 0, count = 0 } = {}) {
 
 // Render a resolver miss the same way everywhere: the reason, then the
 // candidates. A "did you mean" is only useful if it is actionable.
+//
+// The reason is word-wrapped, because a miss on a long path or an unfamiliar
+// filename produces a long sentence, and the commands that surface this
+// (symbols, blast, graph, blame) do not each remember to wrap it.
 export function targetError(found) {
-  const lines = [bad('  ' + found.error)];
+  // The room is the terminal minus the 2-space lead. The `Math.max(8, …)` that
+  // used to be here was itself the bug on an 8-column terminal: a floor above the
+  // available width guarantees an overflow, which is the one thing this function
+  // exists to prevent. `wrapText` already clamps to a single cell.
+  const w = termWidth();
+  const room = Math.max(1, w - 6);
+  const lines = [bad('  ' + wrapText(found.error, '    ', room))];
   if (found.candidates) {
-    for (const c of found.candidates) lines.push('    ' + cyan(c));
-    lines.push(dim('    show <one of these>'));
+    for (const c of found.candidates) lines.push('    ' + cyan(fit(c, Math.max(1, w - 4))));
+    lines.push(dim(fit('    show <one of these>', Math.max(1, w - 2))));
   }
   return lines.join('\n');
 }
@@ -271,11 +270,11 @@ export function deps(repo, { target = '', limit = 15 } = {}) {
     { label: 'dependents', value: `${f.fanIn} file${f.fanIn === 1 ? '' : 's'} import this` },
     { label: 'imports', value: `${f.fanOut} file${f.fanOut === 1 ? '' : 's'} pulled in` },
   ])];
-  if (f.inCycle) head.push(bad('  ' + GLYPHS.warn + ' part of a circular import — refactoring here ripples'));
+  if (f.inCycle) head.push(bad(fit('  ' + GLYPHS.warn + ' part of a circular import — refactoring here ripples', Math.max(1, w - 2))));
 
   const list = (title, items) => {
-    if (!items.length) return dim(`  ${title}: none`);
-    return [dim(`  ${title}:`), ...items.map((x) => '    ' + cyan(fit(x, w - 6)))].join('\n');
+    if (!items.length) return dim(fit(`  ${title}: none`, Math.max(1, w - 2)));
+    return [dim(fit(`  ${title}:`, Math.max(1, w - 2))), ...items.map((x) => '    ' + cyan(fit(x, Math.max(1, w - 4))))].join('\n');
   };
   return [...head, list('imports', imports), list('imported by', importers)].join('\n');
 }
@@ -320,13 +319,14 @@ function renderProse(md) {
 // prompt and an agent asking the MCP server are being told the same thing about
 // the same repository.
 export function tour(repo) {
-  if (!repo.tour.length) return dim('  No tour stops found — is this a code repository?');
+  if (!repo.tour.length) return dim(wrapText('No tour stops found — is this a code repository?', '  '));
   const lines = repo.tour.map((stop, i) => {
-    const n = dim(String(i + 1).padStart(2) + '.');
-    const head = n + ' ' + cyan(fit(stop.path, Math.max(20, Math.floor(termWidth() * 0.45))));
+    // The number is the marker and the path is the value, so the tour stops use
+    // the same helper as every other ranked list and cannot outgrow the terminal.
+    const head = labelled(dim(String(i + 1).padStart(2) + '. '), stop.path, '', { pad: 2 });
     return [head, dim(wrapText(stop.why, '    '))].join('\n');
   });
-  return [bold('  reading order'), ...lines, hintBar(['show <path> to read one'])].join('\n');
+  return [dim(fit('  reading order', Math.max(4, termWidth() - 2))), ...lines, hintBar(['show <path> to read one'])].join('\n');
 }
 
 // ---------------------------------------------------------------- health ---
@@ -335,6 +335,7 @@ export function tour(repo) {
 // breakdown follows because a letter with no reasons is not actionable.
 export function health(repo) {
   const h = repo.health;
+  const w = termWidth();
   const rows = [
     { label: 'grade', value: gradeColor(h.grade) + dim(`   score ${h.score}/100`) },
     { label: 'debt', value: `${h.totals.crit} critical · ${h.totals.high} high findings` },
@@ -350,24 +351,23 @@ export function health(repo) {
     .slice(0, 8);
   const out = [panel('health', rows)];
   if (risky.length) {
-    out.push(dim('  riskiest files:'));
+    out.push(dim(fit('  riskiest files:', Math.max(4, termWidth() - 2))));
     for (const f of risky) {
       // Risk is an integer 0–100; printing "58.00" would imply a precision the
-      // number does not have.
+      // number does not have. The suffix is dropped on a narrow terminal rather
+      // than allowed to push the path off the edge.
       const risk = Number(f.risk);
-      out.push('    ' + warn(GLYPHS.warn + ' ') + cyan(fit(f.path, Math.max(20, termWidth() - 40)))
-        + dim(`  risk ${risk}${f.blast !== undefined ? `  blast ${f.blast}` : ''}`));
+      const tail = dim(`  risk ${risk}${f.blast !== undefined ? `  blast ${f.blast}` : ''}`);
+      out.push(labelled(warn(GLYPHS.warn + ' '), cyan(f.path), tail, { pad: 4 }));
     }
   }
   if (h.breakdown?.length) {
     // The breakdown is the score itemized — each entry is what a factor cost.
     // Showing the label without the points would explain the grade without
     // showing the arithmetic, which is the part that makes it actionable.
-    out.push(dim('  what moved the score:'));
+    out.push(dim(fit('  what moved the score:', Math.max(4, termWidth() - 2))));
     for (const b of h.breakdown) {
-      const pts = bad(String(b.points));
-      const room = Math.max(12, termWidth() - 10);
-      out.push('    ' + dim('· ') + fit(b.label, room) + '  ' + pts);
+      out.push(labelled(dim('· '), b.label, bad(String(b.points)), { pad: 4 }));
     }
   }
   return out.join('\n');
@@ -379,13 +379,15 @@ export function health(repo) {
 // "which file is load-bearing" only has an answer as an ordering.
 export function hubs(repo, { limit = 12 } = {}) {
   const list = repo.facts.hubs.slice(0, Math.min(Number(limit) || 12, MAX));
-  if (!list.length) return dim('  No hubs — nothing here is imported by two or more files.');
+  if (!list.length) return dim(wrapText('No hubs — nothing here is imported by two or more files.', '  '));
   const w = termWidth();
   const top = list[0].fanIn || 1;
-  const barRoom = Math.max(0, Math.min(24, w - 46));
-  return [bold('  most depended-on files'), ...list.map((h) => {
+  // The bar is decoration and is the tail, so it is the first thing dropped on a
+  // narrow terminal. The in/out counts are the reason the file is on the list.
+  const barRoom = Math.max(0, Math.min(24, w - 30));
+  return [dim(fit('  most depended-on files', Math.max(4, w - 2))), ...list.map((h) => {
     const bar = barRoom > 4 ? dim('  ' + '█'.repeat(Math.max(1, Math.round((h.fanIn / top) * barRoom)))) : '';
-    return '  ' + cyan(fit(h.path, Math.max(20, w - 12 - barRoom))) + dim(`  ${h.fanIn} in / ${h.fanOut} out`) + bar;
+    return labelled('', h.path, dim(`  ${h.fanIn} in / ${h.fanOut} out`) + bar, { pad: 2 });
   })].join('\n');
 }
 
@@ -395,13 +397,15 @@ export function hubs(repo, { limit = 12 } = {}) {
 // layer 0 is what runs, and each step down is something it can reach.
 export function layers(repo, { limit = 12 } = {}) {
   const ls = repo.layers.layers;
-  if (!ls.length) return dim('  No layers — no import chain starts anywhere we recognize.');
-  const out = [bold('  import depth')];
+  const w = termWidth();
+  if (!ls.length) return dim(wrapText('No layers — no import chain starts anywhere we recognize.'));
+  const out = [dim(fit('  import depth', Math.max(4, termWidth() - 2)))];
   ls.slice(0, Math.min(Number(limit) || 12, 40)).forEach((files, i) => {
-    const shown = files.slice(0, 3).join(', ');
+    // The "+N more" note is the tail, so a terminal that cannot hold the path
+    // *and* the note drops the note rather than overflowing. Same rule as every
+    // other labelled row, which is why it goes through the same helper.
     const more = files.length > 3 ? dim(`  +${files.length - 3} more`) : '';
-    const room = Math.max(12, termWidth() - String(i).length - 14 - (more ? String(more.length + 2) : 0));
-    out.push(dim(`  layer ${i} (${files.length}) `) + cyan(fit(shown, room)) + more);
+    out.push(labelled(dim(`  layer ${i} (${files.length}) `), cyan(files.slice(0, 3).join(', ')), more));
   });
   if (repo.layers.unreachable.length) {
     out.push(dim(wrapText(`${repo.layers.unreachable.length} files are not reachable from any entry point`)));
@@ -414,14 +418,14 @@ export function layers(repo, { limit = 12 } = {}) {
 // The architecture, in prose. These are the observations `detectPatterns`
 // makes, in the order a senior dev would mention them.
 export function patterns(repo) {
-  if (!repo.patterns.length) return dim('  No patterns stood out.');
-  const out = [bold('  what this codebase looks like')];
+  if (!repo.patterns.length) return dim(wrapText('No patterns stood out.', '  '));
+  const out = [dim(fit('  what this codebase looks like', Math.max(4, termWidth() - 2)))];
   for (const p of repo.patterns) {
     const mark = p.tone === 'good' ? ok(GLYPHS.good) : p.tone === 'warn' ? bad(GLYPHS.warn) : warn('·');
-    out.push('  ' + mark + ' ' + bold(p.title));
+    out.push('  ' + mark + ' ' + dim(fit(p.title, Math.max(4, termWidth() - 4))));
     out.push(dim(wrapText(p.detail, '    ')));
     if (p.paths?.length) {
-      out.push(dim('    ' + fit(p.paths.slice(0, 4).join('  '), Math.max(10, termWidth() - 4))));
+      out.push(dim('    ' + fit(p.paths.slice(0, 4).join('  '), Math.max(4, termWidth() - 4))));
     }
   }
   return out.join('\n');
@@ -439,28 +443,43 @@ export function stats(repo, { limit = 10 } = {}) {
   const cx = [...repo.scan.files].filter((f) => f.complexity > 0).sort((a, b) => b.complexity - a.complexity).slice(0, 5);
 
   const totalLoc = repo.languages.reduce((s2, l) => s2 + l.loc, 0);
+  // One label column for every ranked list, sized from the terminal rather than
+  // hardcoded at 34. The old fixed padding meant a 20-column terminal got 45
+  // columns of output — the number was right and the layout was still wrong.
+  const w = termWidth();
+  const labels = [
+    ...repo.languages.slice(0, 8).map((l) => l.label),
+    ...folders.map((d) => d.path),
+    ...top.map((f) => f.path),
+    ...cx.map((f) => f.path),
+  ];
+  const labelRoom = Math.max(4, Math.min(34, Math.max(0, ...labels.map((s) => s.length)) + 1, Math.floor(w * 0.45)));
+  // The number keeps at least 4 cells and the label gets the rest, so the row is
+  // `indent + label + number` and never exceeds the terminal at any width.
+  const numRoom = Math.max(4, Math.min(7, w - labelRoom - 5));
+  const statRow = (s, n) => labelled('', s, dim(String(n).padStart(numRoom)), { pad: 4 });
+
   const out = [panel('stats', [
     { label: 'files', value: `${s.filesParsed} parsed of ${s.filesTotal} seen` },
-    { label: 'lines', value: `${totalLoc} code` + (s.truncated ? warn(`  (partial scan)`) : '') },
+    { label: 'lines', value: `${totalLoc} code` + (s.truncated ? warn('  (partial scan)') : '') },
     { label: 'imports', value: `${s.edgeCount} resolved` + (s.imports?.total ? dim(`  ${s.imports.confidence}% placed`) : '') },
     { label: 'tests', value: `${repo.facts.testCoverage.ratio}% of non-test files are covered by a test import` },
   ])];
 
-  out.push(bold('  languages'));
-  for (const l of repo.languages.slice(0, 8)) {
-    out.push('    ' + cyan(l.label.padEnd(14)) + dim(String(l.loc).padStart(7)));
-  }
+  out.push(dim(fit('  languages', Math.max(4, w - 2))));
+  for (const l of repo.languages.slice(0, 8)) out.push(statRow(l.label, l.loc));
+
   if (folders.length) {
-    out.push(bold('  biggest folders (loc)'));
-    for (const d of folders) out.push('    ' + cyan(fit(d.path, 34).padEnd(34)) + dim(String(d.loc).padStart(7)));
+    out.push(dim(fit('  biggest folders (loc)', Math.max(4, termWidth() - 2))));
+    for (const d of folders) out.push(statRow(d.path, d.loc));
   }
   if (top.length) {
-    out.push(bold('  biggest files (loc)'));
-    for (const f of top) out.push('    ' + cyan(fit(f.path, 34).padEnd(34)) + dim(String(f.loc).padStart(7)));
+    out.push(dim(fit('  biggest files (loc)', Math.max(4, termWidth() - 2))));
+    for (const f of top) out.push(statRow(f.path, f.loc));
   }
   if (cx.length) {
-    out.push(bold('  most complex'));
-    for (const f of cx) out.push('    ' + cyan(fit(f.path, 34).padEnd(34)) + dim(String(f.complexity).padStart(7)));
+    out.push(dim(fit('  most complex', Math.max(4, w - 2))));
+    for (const f of cx) out.push(statRow(f.path, f.complexity));
   }
   return out.join('\n');
 }
@@ -469,7 +488,8 @@ export function stats(repo, { limit = 10 } = {}) {
 
 export function security(repo, { limit = 12 } = {}) {
   const sec = repo.security;
-  if (!sec.total) return ok('  No findings from the built-in rules.');
+  const w = termWidth();
+  if (!sec.total) return ok(wrapText('No findings from the built-in rules.', '  '));
   const order = ['critical', 'high', 'medium', 'low', 'info'];
   const counts = order.filter((k) => sec.counts[k]).map((k) => `${sec.counts[k]} ${k}`).join(' · ');
   const out = [panel('security', [
@@ -477,8 +497,8 @@ export function security(repo, { limit = 12 } = {}) {
     { label: 'findings', value: counts },
   ])];
   for (const f of sec.files.slice(0, Math.min(Number(limit) || 12, MAX))) {
-    out.push('    ' + (f.worst === 'critical' || f.worst === 'high' ? bad : warn)(GLYPHS.warn + ' ')
-      + cyan(fit(f.path, Math.max(20, termWidth() - 34))) + dim(`  ${f.count} · worst ${f.worst}`));
+    const mark = (f.worst === 'critical' || f.worst === 'high' ? bad : warn)(GLYPHS.warn + ' ');
+    out.push(labelled(mark, cyan(f.path), dim(`  ${f.count} · worst ${f.worst}`), { pad: 4 }));
   }
   out.push(dim(wrapText('Pattern-based heuristics only — not a substitute for a real audit.')));
   return out.join('\n');
@@ -486,14 +506,23 @@ export function security(repo, { limit = 12 } = {}) {
 
 // ----------------------------------------------------------------- stack ---
 
-// The dependency picture the site shows, from the same `analyzeStack`.
+// The dependency picture the site shows, from the same `analyzeStack`. Columns
+// are computed from the widest *actual* value rather than fixed padding, so a
+// long scoped package name shrinks the columns instead of pushing the row off
+// the right edge.
 export function stack(repo, { limit = 20 } = {}) {
   const st = repo.stack;
-  if (!st.items.length) return dim(wrapText('No recognized dependencies (no package manifest found?).'));
-  const out = [bold('  stack') + dim(`  ${st.pm.join(', ') || 'no package manager'}`)];
-  for (const it of st.items.slice(0, Math.min(Number(limit) || 20, MAX))) {
-    const v = it.version ? dim(' ' + it.version) : '';
-    out.push('    ' + cyan(it.name.padEnd(28)) + dim(String(it.category).padEnd(12)) + v + (it.dev ? dim(' dev') : ''));
+  const w = termWidth();
+  if (!st.items.length) return dim(wrapText('No recognized dependencies (no package manifest found?).', '  '));
+  const items = st.items.slice(0, Math.min(Number(limit) || 20, MAX));
+
+  const out = [dim(fit('  stack  ' + (st.pm.join(', ') || 'no package manager'), Math.max(1, w - 2)))];
+  for (const it of items) {
+    // Same shape as every other row: the name is the value, the category and
+    // version are the tail, and the tail is what a narrow terminal drops. The
+    // old version computed its own column budget and was three cells wide.
+    const tail = dim(it.category) + (it.version ? ' ' + it.version : '') + (it.dev ? ' dev' : '');
+    out.push(labelled('', it.name, tail, { pad: 4 }));
   }
   return out.join('\n');
 }
@@ -502,11 +531,12 @@ export function stack(repo, { limit = 20 } = {}) {
 
 export function entry(repo) {
   if (!repo.facts.entries.length) {
-    return dim('  No entry points recognized. tour falls back to the most depended-on files.');
+    return dim(wrapText('No entry points recognized. tour falls back to the most depended-on files.'));
   }
-  return [bold('  entry points'), ...repo.facts.entries.map((p) => {
+  const w = termWidth();
+  return [dim(fit('  entry points', Math.max(4, termWidth() - 2))), ...repo.facts.entries.map((p) => {
     const out = repo.facts.fanOut[p] || 0;
-    return '    ' + ok(GLYPHS.entry + ' ') + cyan(fit(p, Math.max(20, termWidth() - 24))) + dim(`  reaches ${out} files`);
+    return labelled(ok(GLYPHS.entry + ' '), cyan(p), dim(`  reaches ${out} files`), { pad: 4 });
   })].join('\n');
 }
 
@@ -517,19 +547,31 @@ export function entry(repo) {
 // audit actually acts on.
 export function externals(repo) {
   const ext = repo.scan.externals || [];
-  if (!ext.length) return dim('  No external imports found.');
+  if (!ext.length) return dim(wrapText('No external imports found.'));
+  const w = termWidth();
   const sorted = [...ext].sort((a, b) => (b.usedBy?.length || 0) - (a.usedBy?.length || 0));
-  const out = [bold('  external packages')];
-  for (const x of sorted.slice(0, 30)) {
-    out.push('    ' + cyan(String(x.name).padEnd(28)) + dim(`${x.usedBy?.length || 0} files`));
+  const shown = sorted.slice(0, 30);
+  // Two columns when they fit, one per line when they do not. A scoped package
+  // name is long enough on its own to push a fixed-width column off a narrow
+  // terminal, so the column width follows the data.
+  const nameRoom = Math.max(8, Math.min(28, Math.max(...shown.map((x) => String(x.name).length))));
+  const out = [dim(fit('  external packages', Math.max(4, w - 2)))];
+  if (w < nameRoom + 16) {
+    for (const x of shown) {
+      out.push(labelled('', `${x.name} · ${x.usedBy?.length || 0} files`, '', { pad: 4 }));
+    }
+  } else {
+    for (const x of shown) {
+      out.push(labelled('', x.name, dim(`${x.usedBy?.length || 0} files`), { pad: 4 }));
+    }
   }
   const drift = repo.facts.depsDrift;
   if (drift?.undeclaredImported?.length) {
-    out.push(bold('  imported but not declared'));
+    out.push(dim(fit('  imported but not declared', Math.max(4, termWidth() - 2))));
     out.push(wrapText(drift.undeclaredImported.join(', '), '    ').split('\n').map(warn).join('\n'));
   }
   if (drift?.unusedDeclared?.length) {
-    out.push(bold('  declared but never imported'));
+    out.push(dim(fit('  declared but never imported', Math.max(4, termWidth() - 2))));
     out.push(dim(wrapText(drift.unusedDeclared.join(', '), '    ')));
   }
   return out.join('\n');
@@ -540,10 +582,69 @@ export function externals(repo) {
 // Which binary is answering. When the terminal and the website disagree, this
 // is the first thing to ask.
 export function about(repo, version = '') {
-  return panel('onboarder', [
+  const rows = [
     { label: 'version', value: version },
     { label: 'repo', value: repo.root },
     { label: 'indexed', value: `${repo.searchIndex?.totalDocs ?? 0} files for find` },
-    { label: 'scanned', value: repo.scan.scannedAt },
-  ]);
+    { label: 'scanned', value: `${repo.scan.scannedAt}` },
+  ];
+  if (repo.gitUrl) rows.push({ label: 'from', value: repo.gitUrl });
+  if (repo.cloneDir) rows.push({ label: 'clone', value: 'a temp clone — removed when you leave' });
+  return panel('onboarder', rows);
+}
+
+// `github` — the terminal's answer to the site's "From the remote" section:
+// what GitHub says about this repository, as opposed to what reading the code
+// says about it. The distinction is the point. Stars and issues are about the
+// project's standing; `health` and `risks` are about the code in front of you,
+// and neither can tell you the other.
+//
+// The result is passed in rather than fetched here, because every function in
+// this file is pure and testable with no network. `ctx.github()` does the asking.
+export function github(repo, result) {
+  if (!result) {
+    return dim(wrapText('Not a GitHub repository, so there is nothing to ask GitHub about.', '  '));
+  }
+  if (!result.ok) {
+    return [bad(fit('  ' + result.reason, Math.max(1, termWidth() - 2))), dim(wrapText(githubHintText(repo), '  '))].join('\n');
+  }
+
+  const f = result.facts;
+  const rows = [
+    row('repo', result.repoPath),
+    row('stars', String(f.stars)),
+    row('forks', String(f.forks)),
+    row('watching', String(f.watching)),
+    row('open issues', String(f.issues)),
+  ];
+  if (f.license) rows.push(row('license', f.license));
+  if (f.branch) rows.push(row('branch', f.branch));
+  if (f.created) rows.push(row('created', shortDate(f.created)));
+  if (f.pushed) rows.push(row('last push', shortDate(f.pushed)));
+  if (f.archived) rows.push(row('note', 'this repository is archived'));
+
+  const out = [panel(result.repoPath, rows)];
+  if (f.description) out.push(dim(wrapText(f.description)));
+  if (f.topics.length) out.push(dim(fit('  topics   ' + f.topics.join(' '), Math.max(1, termWidth() - 2))));
+  if (f.homepage) out.push(dim(fit('  site     ' + f.homepage, Math.max(1, termWidth() - 2))));
+  // Double quotes rather than an escaped apostrophe: the previous spelling of
+  // this line was a `\\'` inside a single-quoted string, which is a syntax error
+  // waiting for the next person to touch the file.
+  out.push(dim(wrapText("These are GitHub's numbers, not this repo's. `health` and `risks` are about the code.", '  ')));
+  return out.join('\n');
+}
+
+// Returned as plain text and wrapped by the caller: a hint line is exactly the
+// kind of prose that overflows, because it is written once and never measured.
+function githubHintText(repo) {
+  if (repo.gitUrl) return 'It is a clone, so the URL is known — the ask itself failed.';
+  return 'No origin remote here, so there is no URL to ask about.';
+}
+
+// `2024-01-05T…` → `Jan 2024`. A day is noise next to a five-year-old project, and
+// a full timestamp is four columns wider than the label it sits beside.
+function shortDate(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short' });
 }

package/cli/explorer/wrap.js

@@ -0,0 +1,49 @@
+// Word-wrap plain text to the terminal, preserving the indent on continuation
+// lines.
+//
+// This lives in its own module because two callers need it: the views, which
+// wrap the engine's long prose, and the command table, which fits its help
+// screen. Both must agree on the same edge behavior, or the same string comes
+// out two different widths depending on who printed it.
+//
+// Applied *before* painting, so the wrap never has to understand ANSI: the
+// styled string is built from already-wrapped plain text.
+//
+// `room` is clamped to at least one cell. Without that floor, a terminal
+// narrower than the indent drives `room` to zero or below, the hard-split loop
+// slices a word to the empty string and re-reads the same word forever, and the
+// session hangs instead of printing. A tool that reads code should degrade on a
+// tiny terminal, never wedge on one.
+
+import { termWidth } from '../ui.js';
+
+export function wrapText(text, indent = '  ', room = termWidth() - indent.length) {
+  const cell = Math.max(1, Math.floor(room));
+  const out = [];
+  for (const para of String(text).split('\n')) {
+    if (!para.trim()) {
+      out.push('');
+      continue;
+    }
+    let line = '';
+    for (const word of para.split(/\s+/)) {
+      if (!line) {
+        line = word;
+      } else if (line.length + 1 + word.length <= cell) {
+        line += ' ' + word;
+      } else {
+        out.push(indent + line);
+        line = word;
+      }
+      // A single word longer than the room is hard-split rather than allowed to
+      // overflow — a long import specifier is exactly the case that shows up.
+      // `cell >= 1` guarantees each pass consumes a character and terminates.
+      while (line.length > cell) {
+        out.push(indent + line.slice(0, cell));
+        line = line.slice(cell);
+      }
+    }
+    out.push(indent + line);
+  }
+  return out.join('\n');
+}