codebase-onboarder 0.5.0 → 0.6.0

package/cli/explorer/app.js

@@ -19,12 +19,14 @@ 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 { openRepo, openRepoOrClone, isGitUrl, remoteUrlFor, closeRemote } from './session.js';
+import { fetchRepoFacts } from './github.js';
+import { CLEAR, EXIT, commandNames, completer, helpText, lookup, shellEscape, tokenize } from './commands.js';
+import { overview, github as githubView } 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';
+import { expandHome } from '../../server/paths.js';
 
 const VERSION = JSON.parse(
   fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
@@ -52,10 +54,16 @@ export async function runExplore({ target = '.', flags = {}, out = console.log,
 
   let repo;
   try {
-    repo = await openRepo(target, { onProgress: progressReporter(out) });
+    // The launch argument accepts a URL for the same reason `cd` does: someone
+    // who has never seen this repo should be able to name it and read it. A
+    // silent ten-second clone looks like a hang, so the URL case says what it
+    // is doing before it starts.
+    if (isGitUrl(target)) out(dim(`  cloning ${target}…`));
+    repo = await openRepoOrClone(target, { onProgress: progressReporter(out) });
   } catch (e) {
     err('  ' + bad((e.message || String(e))));
     err(dim('    Point it at a folder: onboarder explore /path/to/repo'));
+    err(dim('    …or a git URL:      onboarder explore https://github.com/org/repo'));
     return 1;
   }
 
@@ -112,6 +120,7 @@ function session({ repo, flags, out, err, version }) {
     help: (topic) => helpText(ctx, topic),
     rescan: () => reload(ctx, ctx.repo.root),
     loadRepo: (where) => reload(ctx, where),
+    github: () => askGithub(ctx),
     web: () => startWeb(ctx),
   };
 
@@ -121,14 +130,36 @@ function session({ repo, flags, out, err, version }) {
     prompt: promptFor(repo),
     terminal: true,
     historySize: 200,
+    // The completer closes over the *current* repo rather than the one captured
+    // here, so after a `cd` it completes paths in the new repository. Reading
+    // `ctx.repo` at completion time is the whole trick.
+    completer: (line) => completer(ctx.repo)(line),
   });
 
   let queue = Promise.resolve();
   let closed = false;
   let interrupts = 0;
+  let onResize = null;
 
+  // One poisoned promise must not end the session. `handleLine` catches its own
+  // errors, but anything thrown outside it — a prompt write to a closed stream,
+  // an error in a command's argument handling — would otherwise reject this
+  // chain and silently swallow every command typed afterwards. The session would
+  // look alive and do nothing, which is the worst failure mode a REPL has.
   rl.on('line', (line) => {
-    queue = queue.then(() => handleLine(ctx, line, rl, out, err));
+    queue = queue
+      .then(() => handleLine(ctx, line, rl, out, err))
+      .catch((e) => {
+        err('  ' + bad((e?.message || String(e))));
+        if (!closed) {
+          try {
+            rl.setPrompt(promptFor(ctx.repo));
+            rl.prompt();
+          } catch {
+            // The stream is gone; the close handler finishes the session.
+          }
+        }
+      });
   });
 
   // Ctrl-D on an empty line is the universal "I'm done". On a line with text,
@@ -140,7 +171,9 @@ function session({ repo, flags, out, err, version }) {
   // its input is followed immediately by `exit`. The exit waits on the queue.
   rl.on('close', () => {
     closed = true;
-    process.stdout.off('resize', onResize);
+    // The listener is removed on every exit path, including the interval one
+    // below, so a session that ends by any route leaves stdout as it found it.
+    if (onResize) process.stdout.off('resize', onResize);
   });
 
   // Ctrl-C twice leaves. Once clears the line, which is what readline already
@@ -158,7 +191,7 @@ function session({ repo, flags, out, err, version }) {
   });
 
   // A resize redraws rather than leaving the prompt stranded mid-wrap.
-  const onResize = () => {
+  onResize = () => {
     if (!closed) rl.write(null, { ctrl: true, name: 'l' });
   };
   process.stdout.on('resize', onResize);
@@ -174,6 +207,11 @@ function session({ repo, flags, out, err, version }) {
       queue.then(() => {
         out('');
         out(dim('  bye.'));
+        // A clone this session made is a temp directory, and the session is the
+        // only thing that knows about it. Removing it last — after the last
+        // command has finished reading files out of it — is the only ordering
+        // that cannot pull the ground out from under a command still running.
+        closeRemote(ctx.repo).catch(() => {});
         resolve(0);
       });
     }, 20);
@@ -191,6 +229,18 @@ async function handleLine(ctx, line, rl, out, err) {
     return;
   }
   const [name, ...args] = words;
+
+  // `!cmd` runs a shell command from inside the session and prints its output.
+  // It is the only way out to a shell, which is the point: the set of things
+  // that can happen here stays small enough to remember.
+  if (name.startsWith('!') && name.length > 1) {
+    const result = await shellEscape(line.replace(/^!\s*/, ''), ctx.repo.root);
+    if (result) out(result);
+    rl.setPrompt(promptFor(ctx.repo));
+    rl.prompt();
+    return;
+  }
+
   const cmd = lookup(name);
 
   if (!cmd) {
@@ -227,12 +277,51 @@ async function handleLine(ctx, line, rl, out, err) {
 // 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: () => {} });
+  if (!target) {
+    return '  cd needs a folder or a URL — `cd ../other-repo`, `cd https://github.com/org/repo`.';
+  }
+
+  // `rescan` re-reads the folder the session is already in. Re-cloning the URL
+  // to get the same bytes back would be slow and would change the temp
+  // directory out from under the session, so a target that resolves to the
+  // current root takes the local path even when the repo remembers a URL.
+  const reloadingCurrent = !isGitUrl(target) && path.resolve(expandHome(target)) === path.resolve(ctx.repo.root);
+  const previous = ctx.repo;
+  const next = reloadingCurrent
+    ? await openRepo(previous.root)
+    : await openRepoOrClone(target, { onProgress: () => {} });
+
+  // A reload of the current folder produces a repo that has never heard of the
+  // URL it was cloned from: `openRepo` reads a directory, and a directory does
+  // not know where it came from. Carrying the three fields across is what keeps
+  // `rescan` from silently demoting a clone to a nameless temp folder — the
+  // prompt, `about` and `github` all read them.
+  if (reloadingCurrent) {
+    next.gitUrl = previous.gitUrl;
+    next.cloneDir = previous.cloneDir;
+    next.tempId = previous.tempId;
+    if (previous.name !== next.name && !previous.cloneDir) next.name = previous.name;
+  }
+
+  // The old clone is only dropped once the new one has loaded. Doing it the
+  // other way round means a typo in a URL leaves you with nothing loaded *and*
+  // the repo you were reading deleted from under you.
+  if (!reloadingCurrent) await closeRemote(previous);
   ctx.repo = next;
   return '\n' + overview(next);
 }
 
+// Ask GitHub about the loaded repo and print the answer. Network failures are
+// the expected case, not the exception — this is a command someone types on a
+// plane — so every one of them comes back as a line of text.
+async function askGithub(ctx) {
+  const url = await remoteUrlFor(ctx.repo);
+  if (!url) {
+    return githubView(ctx.repo, { ok: false, reason: 'This folder has no GitHub remote — there is nothing to ask about.' });
+  }
+  return githubView(ctx.repo, await fetchRepoFacts(url));
+}
+
 // 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
@@ -244,12 +333,19 @@ async function startWeb(ctx) {
   const recorded = readPidFile(file);
 
   if (recorded && pidIsAlive(recorded)) {
-    return ['  ' + ok('Already running.') + dim(`  PID ${recorded.pid}`), '    ' + cyan(urls.local)].join('\n');
+    return ['  ' + ok('Already running.') + dim(`  PID ${recorded}`), '    ' + cyan(urls.local)].join('\n');
   }
 
   const { runStartBackground } = await import('../commands.js');
   const code = await runStartBackground({
-    flags: { ...ctx.flags, json: true },
+    // `nonInteractive` is not optional here. With no config on disk,
+    // `runStartBackground` hands off to `runSetup`, which opens its own readline
+    // on the same stdin this session is already reading — the wizard and the
+    // explorer would then compete for keystrokes, and the explorer could process
+    // a wizard answer as a command. Inside a session the server either starts
+    // from the config that exists or reports that there is none; the person can
+    // run `onboarder setup` deliberately if they want the wizard.
+    flags: { ...ctx.flags, json: true, nonInteractive: true },
     out: () => {},
     err: () => {},
   });

package/cli/explorer/commands.js

@@ -11,6 +11,14 @@
 // handled once, in the tokenizer, and every command sees the same shape.
 
 import * as V from './views.js';
+import * as A from './advanced.js';
+import { lineNumber } from './session.js';
+import { bold, cyan, dim, ok, fit, termWidth } from '../ui.js';
+import { wrapText } from './wrap.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
 
 export const EXIT = Symbol('exit');
 export const CLEAR = Symbol('clear');
@@ -18,8 +26,10 @@ export const CLEAR = Symbol('clear');
 export const COMMANDS = [
   {
     name: 'help', aliases: ['?'], group: 'basics',
-    usage: 'help', summary: 'This list.',
-    run: (ctx) => ctx.help(),
+    usage: 'help [command]', summary: 'This list, or everything about one command.',
+    // The topic is forwarded. `help find` used to ignore its argument and print
+    // the whole list, which reads as the command not working.
+    run: (ctx, args) => ctx.help(args.join(' ')),
   },
   {
     name: 'map', aliases: ['overview', 'home'], group: 'basics',
@@ -42,10 +52,12 @@ export const COMMANDS = [
     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.
+      // `tree . 3` would be pedantry in a tool built to be forgiving. `.` is the
+      // root, so it must not be taken as a folder name either.
       const onlyDepth = args.length === 1 && /^\d+$/.test(args[0]);
+      const sub = onlyDepth ? '' : (args[0] || '');
       return V.tree(ctx.repo, {
-        sub: onlyDepth ? '' : (args[0] || ''),
+        sub: sub === '.' ? '' : sub,
         depth: onlyDepth ? Number(args[0]) : (Number(args[1]) || 2),
       });
     },
@@ -58,10 +70,14 @@ export const COMMANDS = [
   {
     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 }),
+    run: (ctx, args) => V.show(ctx.repo, {
+      target: args[0] || '',
+      from: lineNumber(args[1], 0),
+      count: lineNumber(args[2], 0),
+    }),
   },
   {
-    name: 'deps', aliases: ['connections', 'graph'], group: 'navigate',
+    name: 'deps', aliases: ['connections'], group: 'navigate',
     usage: 'deps <file>', summary: 'What a file imports, and what imports it.',
     run: (ctx, args) => V.deps(ctx.repo, { target: args.join(' ') }),
   },
@@ -110,6 +126,75 @@ export const COMMANDS = [
     usage: 'externals', summary: 'External packages, plus dependency drift.',
     run: (ctx) => V.externals(ctx.repo),
   },
+  {
+    name: 'graph', aliases: ['tree-graph'], group: 'navigate',
+    usage: 'graph <file> [depth]', summary: 'The dependency tree around a file, as arrows.',
+    run: (ctx, args) => A.graph(ctx.repo, { target: args[0] || '', depth: Number(args[1]) || 2 }),
+  },
+  {
+    name: 'blast', aliases: ['impact', 'radius'], group: 'navigate',
+    usage: 'blast <file>', summary: 'What breaks if this file breaks, transitively.',
+    run: (ctx, args) => A.blast(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'symbols', aliases: ['outline', 'functions'], group: 'navigate',
+    usage: 'symbols <file>', summary: 'Functions, classes and exports in a file.',
+    run: (ctx, args) => A.symbols(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'docs', aliases: ['document'], group: 'analyze',
+    usage: 'docs [file|folder] | docs --write', summary: 'Prose docs for a file, or write ONBOARDER.md.',
+    run: async (ctx, args) => {
+      // `--write` is the one command here that touches the filesystem. It is
+      // opt-in, explicit, and prints where it wrote — a map tool should never
+      // leave a file behind just because someone asked what the docs say.
+      if (args[0] === '--write') {
+        const abs = await A.writeDocs(ctx.repo, args[1] || 'ONBOARDER.md');
+        return '  ' + ok('Wrote ') + cyan(abs);
+      }
+      return A.docs(ctx.repo, { target: args.filter((a) => a !== '--write').join(' ') });
+    },
+  },
+  {
+    name: 'log', aliases: ['history', 'commits'], group: 'git',
+    usage: 'log [count]', summary: 'Recent commits, and who wrote them.',
+    run: (ctx, args) => A.log(ctx.repo, { limit: Number(args[0]) || 15 }),
+  },
+  {
+    name: 'hotspots', aliases: ['churn'], group: 'git',
+    usage: 'hotspots [count]', summary: 'Files that are both complex and frequently changed.',
+    run: (ctx, args) => A.hotspots(ctx.repo, { limit: Number(args[0]) || 12 }),
+  },
+  {
+    name: 'blame', aliases: ['authors'], group: 'git',
+    usage: 'blame <file>', summary: 'Who wrote each line of a file.',
+    run: (ctx, args) => A.blame(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'coupling', aliases: ['matrix', 'heatmap'], group: 'analyze',
+    usage: 'coupling', summary: 'Folder-to-folder import traffic, as a heat grid.',
+    run: (ctx) => A.coupling(ctx.repo),
+  },
+  {
+    name: 'clusters', aliases: ['communities', 'modules'], group: 'analyze',
+    usage: 'clusters', summary: 'Groups of files that import each other more than the rest.',
+    run: (ctx) => A.clusters(ctx.repo),
+  },
+  {
+    name: 'diagram', aliases: ['mermaid'], group: 'analyze',
+    usage: 'diagram [file]', summary: 'Mermaid source for the repo, or one file.',
+    run: (ctx, args) => A.diagram(ctx.repo, { target: args.join(' ') }),
+  },
+  {
+    name: 'layers-diagram', aliases: [], group: 'analyze',
+    usage: 'layers-diagram', summary: 'Mermaid source for the layer stack.',
+    run: (ctx) => A.layerDiagram(ctx.repo),
+  },
+  {
+    name: 'risks', aliases: ['problems', 'smells'], group: 'analyze',
+    usage: 'risks', summary: 'Cycles, orphans, dead exports, drift — in one list.',
+    run: (ctx) => A.risks(ctx.repo),
+  },
   {
     name: 'about', aliases: ['version'], group: 'session',
     usage: 'about', summary: 'Version, repo path, and what is indexed.',
@@ -120,9 +205,14 @@ export const COMMANDS = [
     usage: 'rescan', summary: 'Re-read the repo from disk.',
     run: (ctx) => ctx.rescan(),
   },
+  {
+    name: 'github', aliases: ['remote', 'repo'], group: 'session',
+    usage: 'github', summary: "What GitHub says about this repo — stars, issues, license.",
+    run: (ctx) => ctx.github(),
+  },
   {
     name: 'cd', aliases: ['open-repo', 'use'], group: 'session',
-    usage: 'cd <folder>', summary: 'Load a different repository.',
+    usage: 'cd <folder|url>', summary: 'Load another repository, or clone one by URL.',
     run: (ctx, args) => ctx.loadRepo(args.join(' ')),
   },
   {
@@ -161,27 +251,41 @@ export function commandNames() {
 }
 
 // `help <command>` answers about one command; bare `help` lists them, grouped so
-// the shape of the tool is visible rather than alphabetical.
+// the shape of the tool is visible rather than alphabetical. Every row is
+// fitted, because a long summary on a narrow terminal used to wrap into the
+// next row and make the list unreadable.
 export function helpText(ctx, topic = '') {
+  const w = termWidth();
   if (topic) {
     const cmd = lookup(topic);
-    if (!cmd) return `  No command called "${topic}". Try \`help\`.`;
+    if (!cmd) return fit(`  No command called "${topic}". Try \`help\`.`, Math.max(10, w - 2));
     const also = cmd.aliases.length ? `  (also: ${cmd.aliases.join(', ')})` : '';
-    return ['  ' + cmd.usage + also, '    ' + cmd.summary].join('\n');
+    return [
+      fit('  ' + cmd.usage + also, Math.max(10, w - 2)),
+      wrapText(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));
+  // Two cells of indent, two of gap, and the summary gets whatever is left. The
+  // usage column shrinks with the terminal rather than pushing the text off it.
+  const longest = Math.max(...COMMANDS.map((c) => c.usage.length));
+  const usageRoom = Math.max(8, Math.min(longest, Math.floor(w * 0.4)));
   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(fit('  ' + group.toUpperCase(), Math.max(10, w - 2)));
+    for (const c of list) {
+      const left = '    ' + fit(c.usage, usageRoom);
+      const room = w - left.length - 2;
+      out.push(room > 8 ? left + '  ' + fit(c.summary, room, { tail: false }) : left);
+    }
   }
   out.push('');
-  out.push('  ' + (ctx?.repo ? ctx.repo.name : 'onboarder') + ' · Ctrl-D or `exit` to leave · Ctrl-C twice to quit');
+  out.push(fit('  ' + (ctx?.repo ? ctx.repo.name : 'onboarder')
+    + ' · Ctrl-D or `exit` to leave · Ctrl-C twice to quit', Math.max(10, w - 2)));
   return out.join('\n');
 }
 
@@ -195,3 +299,71 @@ export function tokenize(line) {
   while ((m = re.exec(String(line || '')))) out.push(m[1] ?? m[2] ?? m[3]);
   return out;
 }
+
+// Tab completion, because a REPL where you retype `shared/analyzer/graph.js` one
+// letter at a time is not a REPL, it is a punishment.
+//
+// Two contexts, chosen by what is already typed. Before the first space, the line
+// is a command name, so it completes against the command table — including
+// aliases, because a person who types `ls` wants `tree` to finish. After a space,
+// it is an argument, so it completes against real file paths in the loaded repo,
+// which is the thing that is tedious to type and impossible to remember.
+//
+// `shellEscape` is the other half of a good REPL: `!git status` runs a shell
+// command and hands the output back, so nobody has to leave the session to run
+// one thing. It is deliberately the *only* way out to a shell, so the set of
+// things that can happen in a session stays legible.
+function completer(repo) {
+  return function complete(line) {
+    const trailingSpace = /\s$/.test(line);
+    const parts = line.split(/\s+/);
+    // Completing a command (no space yet, or trailing space after one word).
+    if (parts.length <= 1 || (parts.length === 2 && trailingSpace)) {
+      const hits = [...BY_NAME.keys()].filter((n) => n.startsWith(parts[0] || '')).sort();
+      return [hits.length ? hits : parts, parts[0] || ''];
+    }
+    // Completing a path argument against the loaded repo. Matches at any depth,
+    // not just from the root: `show rend` should find `src/render.js`, which is
+    // the case the resolver's forgiving path lookup already handles — the
+    // completer has to agree with it or Tab contradicts what the command does.
+    const frag = parts[parts.length - 1] || '';
+    const slash = frag.lastIndexOf('/');
+    const dir = slash === -1 ? '' : frag.slice(0, slash + 1);
+    const base = slash === -1 ? frag : frag.slice(slash + 1);
+    const seen = new Set();
+    const hits = [];
+    for (const f of repo.scan.allFiles || repo.scan.files) {
+      if (dir && !f.startsWith(dir)) continue;
+      // With no directory typed, match the *last* segment so `rend` finds
+      // `src/render.js`; with one typed, match the segment being completed.
+      const name = dir ? f.slice(dir.length) : f.slice(f.lastIndexOf('/') + 1);
+      if (!name.startsWith(base)) continue;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      hits.push(name);
+      if (hits.length >= 200) break;
+    }
+    return [hits.length ? hits : [frag], frag];
+  };
+}
+
+// Run a shell command and capture its output. A non-zero exit is not a crash —
+// `grep` that finds nothing is a normal answer — so the code is reported, not
+// thrown. There is no `shell: true`: the whole line is the argument vector, so
+// nothing in a filename can be interpreted as a second command.
+async function shellEscape(line, cwd) {
+  const parts = tokenize(line);
+  if (!parts.length) return null;
+  try {
+    const { stdout, stderr } = await run(parts[0], parts.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
+    const out = String(stdout || '').trimEnd();
+    const err = String(stderr || '').trimEnd();
+    return [out, err].filter(Boolean).join('\n') || dim('  (no output)');
+  } catch (e) {
+    const code = e.code ?? e.status;
+    const err = String(e.stderr || '').trimEnd() || String(e.message || '').trimEnd();
+    return dim('  exit ' + (code ?? '?') + (err ? '\n  ' + err : ''));
+  }
+}
+
+export { completer, shellEscape };

package/cli/explorer/github.js

@@ -0,0 +1,75 @@
+// Asking GitHub what it knows about a repository — the terminal half of the
+// feature the web app calls "From the remote".
+//
+// The `fetch` lives here rather than in `shared/analyzer/github.js` because it
+// can only happen in one runtime at a time, and because this side can do
+// something the browser cannot: send a token. `GITHUB_TOKEN` (or `GH_TOKEN`, the
+// name the `gh` CLI uses) turns GitHub's 60-requests-an-hour guest allowance
+// into 5,000. The browser has nowhere to keep a secret, which is precisely why
+// this is better in a terminal than on the web.
+//
+// A failed lookup is never fatal. `github` on a repo with no remote, a private
+// one, or a machine with no network is a normal thing to type, so every path
+// returns the honest reason instead of throwing.
+
+import { githubRepoPath, remoteError, remoteFacts } from '../../shared/analyzer/github.js';
+
+const API = 'https://api.github.com/repos/';
+const TIMEOUT_MS = 8000;
+
+// The token is read per call rather than at import: a session that exports one
+// mid-flight should not need to be restarted to pick it up.
+function token() {
+  const t = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  return typeof t === 'string' && t.trim() ? t.trim() : '';
+}
+
+/**
+ * Look up a GitHub repository's public facts.
+ *
+ * `fetchImpl` is a parameter so this is testable without a network, and so the
+ * caller can pass an already-aborted-aware fetch if it has one.
+ *
+ * Returns `{ ok: true, facts, repoPath }` or `{ ok: false, reason }`. Never
+ * throws — the reason is the return value, because every failure here is
+ * something to print, not something to crash a session over.
+ */
+export async function fetchRepoFacts(url, { fetchImpl = globalThis.fetch } = {}) {
+  const repoPath = githubRepoPath(url);
+  if (!repoPath) {
+    return { ok: false, reason: 'That is not a GitHub URL, so there are no remote facts to ask for.' };
+  }
+  if (typeof fetchImpl !== 'function') {
+    return { ok: false, reason: 'This runtime has no fetch, so GitHub cannot be asked.' };
+  }
+
+  const headers = { accept: 'application/vnd.github+json', 'user-agent': 'onboarder' };
+  const auth = token();
+  if (auth) headers.authorization = 'Bearer ' + auth;
+
+  let res;
+  try {
+    res = await fetchImpl(API + repoPath, {
+      headers,
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (err) {
+    // A timeout and a refused connection are the same thing to the person who
+    // typed the command: it did not come back. The message is kept because
+    // "GitHub could not be reached" and "the certificate is not trusted" are
+    // very different problems on very different machines.
+    const detail = /timeout|abort/i.test(err?.message || '') ? ' (it took too long)' : '';
+    return { ok: false, reason: 'Could not reach GitHub' + detail + ' — ' + (err?.message || err) };
+  }
+
+  if (!res.ok) return { ok: false, reason: remoteError(res.status) };
+
+  let facts;
+  try {
+    facts = remoteFacts(await res.json());
+  } catch {
+    return { ok: false, reason: 'GitHub sent something that is not JSON.' };
+  }
+  if (!facts) return { ok: false, reason: 'GitHub sent no repository facts.' };
+  return { ok: true, facts, repoPath };
+}