@msareen/knowledge-hub-builder 0.1.7 → 0.1.8

package/scripts/ingest/exclude.ts

@@ -0,0 +1,37 @@
+// One rule for `exclude:` entries in sources.yaml, shared by folder and files sources. An
+// entry that starts with a drive letter or `/` is absolute and is checked against the file's
+// absolute path; anything else is relative and checked against the file's path relative to
+// its source root (or, for `files` sources, its basename). Within either case, an entry with
+// no glob metacharacter (* ? [) is a plain prefix — it matches the path itself or anything
+// under it — and an entry with one is a Bun.Glob pattern. Bun.Glob is a global, no import
+// needed.
+import { isAbsolute } from "node:path";
+
+const isGlobPattern = (p: string) => /[*?[]/.test(p);
+const posix = (p: string) => p.replaceAll("\\", "/");
+
+type Matcher = (path: string) => boolean;
+
+function makeMatcher(patterns: string[]): Matcher {
+  const plain: string[] = [];
+  const globs: Bun.Glob[] = [];
+  for (const raw of patterns) {
+    const p = posix(raw).replace(/\/+$/, ""); // trailing slash is cosmetic on a plain entry
+    if (isGlobPattern(p)) globs.push(new Bun.Glob(p));
+    else plain.push(p);
+  }
+  return (path: string) =>
+    plain.some((p) => path === p || path.startsWith(`${p}/`)) || globs.some((g) => g.match(path));
+}
+
+/**
+ * Build an excluder from `sources.yaml`'s `exclude:` list. The returned function takes a
+ * file's absolute path and its path relative to the source (or basename, for `files`
+ * sources) and reports whether either matched an exclude entry of the corresponding kind.
+ */
+export function makeExcluder(patterns: string[] | undefined): (absPath: string, relPath: string) => boolean {
+  if (!patterns?.length) return () => false;
+  const abs = makeMatcher(patterns.filter((p) => isAbsolute(p)).map(posix));
+  const rel = makeMatcher(patterns.filter((p) => !isAbsolute(p)));
+  return (absPath: string, relPath: string) => abs(posix(absPath)) || rel(relPath);
+}

package/scripts/ingest/files.ts

@@ -5,6 +5,7 @@ import { basename } from "../lib/util";
 import type { Entry } from "../lib/ledger";
 import { acquireFile, newCounters, report, type Options } from "./acquire";
 import { detail, item, outcome, pos } from "../lib/log";
+import { makeExcluder } from "./exclude";
 import type { Source } from "./index";
 
 export async function ingestFiles(
@@ -15,9 +16,14 @@ export async function ingestFiles(
   opts: Options,
 ) {
   detail(`${s.paths.length} file(s) declared`);
+  const excluded = makeExcluder(s.exclude);
+  const paths = s.paths.filter((p) => !excluded(p, basename(p)));
+  const skippedCount = s.paths.length - paths.length;
+  if (skippedCount) detail(`${skippedCount} excluded by 'exclude' rule(s), ${paths.length} remain`);
+
   const c = newCounters();
-  for (const [i, p] of s.paths.entries()) {
-    const at = pos(i + 1, s.paths.length);
+  for (const [i, p] of paths.entries()) {
+    const at = pos(i + 1, paths.length);
     if (!existsSync(p)) {
       item(at, p);
       outcome("missing, skipped");

package/scripts/ingest/folder.ts

@@ -6,6 +6,7 @@ import { join } from "../lib/util";
 import type { Entry } from "../lib/ledger";
 import { acquireFile, newCounters, report, type Options } from "./acquire";
 import { detail, pos } from "../lib/log";
+import { makeExcluder } from "./exclude";
 import type { Source } from "./index";
 
 export async function ingestFolder(
@@ -30,14 +31,23 @@ export async function ingestFolder(
   // take a while to enumerate, and knowing the denominator is what makes "[ 3/57]" mean
   // anything to someone deciding whether to wait.
   detail(`scanning ${s.path} …`);
-  const files = walk(s.path);
-  detail(`${files.length} file(s) found`);
+  const all = walk(s.path);
+  detail(`${all.length} file(s) found`);
+
+  // relOf is posix-normalized so an 'exclude' entry like "drafts/" behaves the same whether
+  // the corpus was walked on Windows or POSIX; it's computed once and reused for both the
+  // exclude check and the flattened raw/ filename below.
+  const relOf = (p: string) => p.slice(s.path.length + 1).replaceAll("\\", "/");
+  const excluded = makeExcluder(s.exclude);
+  const files = all.filter((p) => !excluded(p, relOf(p)));
+  const skippedCount = all.length - files.length;
+  if (skippedCount) detail(`${skippedCount} excluded by 'exclude' rule(s), ${files.length} remain`);
 
   const c = newCounters();
   for (const [i, p] of files.entries()) {
     // Flatten the subtree into the filename so two `notes.md` in sibling folders don't
     // collide in raw/, and so the origin stays legible without opening the file.
-    const rel = p.slice(s.path.length + 1).replaceAll(/[\\/]/g, "__");
+    const rel = relOf(p).replaceAll("/", "__");
     await acquireFile(pos(i + 1, files.length), p, rel, rawDir, bundleDir, entries, c, opts);
   }
   report(c);

package/scripts/ingest/index.ts

@@ -21,8 +21,8 @@ import { ingestWeb } from "./web";
 import type { Options } from "./acquire";
 
 export type Source =
-  | { type: "folder"; path: string }
-  | { type: "files"; paths: string[] }
+  | { type: "folder"; path: string; exclude?: string[] }
+  | { type: "files"; paths: string[]; exclude?: string[] }
   | { type: "web"; urls: string[] };
 
 const argv = process.argv.slice(2);
@@ -94,6 +94,14 @@ for (const [i, s] of sources.entries()) {
       process.exit(1);
     }
   }
+  if (
+    (s.type === "folder" || s.type === "files") &&
+    s.exclude !== undefined &&
+    (!Array.isArray(s.exclude) || s.exclude.some((v: unknown) => typeof v !== "string"))
+  ) {
+    console.error(`${bundle}: ${at}.exclude must be a list of strings`);
+    process.exit(1);
+  }
 }
 if (!sources.length) {
   console.log(`${bundle}: no sources configured.`);

package/scripts/init.ts

@@ -8,13 +8,30 @@
 //
 // The mechanism itself lives in lib/upgrade.ts, because cli.ts also runs it on version
 // drift before any hub command.
-import { cpSync, mkdirSync, existsSync } from "node:fs";
-import { join, resolve, basename } from "node:path";
-import { HUB_TEMPLATE, MARKER, markerIn } from "./lib/paths";
-import { upgradeHub, syncManaged, stamp } from "./lib/upgrade";
+import { resolve, basename } from "node:path";
+import { MARKER, markerIn } from "./lib/paths";
+import { upgradeHub, updateHint } from "./lib/upgrade";
 
 const upgrading = process.env.KHB_SUBCOMMAND === "upgrade";
-const [dirArg] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+
+// A hub describes itself in its own marker, and the machine-level registry reads those
+// two fields from there — so the label follows the hub when it is moved or cloned onto
+// another machine, instead of living only in one laptop's shortcut list.
+function takeOpt(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i < 0) return undefined;
+  const v = argv[i + 1];
+  if (v === undefined) {
+    console.error(`${name} needs a value`);
+    process.exit(1);
+  }
+  argv.splice(i, 2);
+  return v;
+}
+const nameOpt = takeOpt("--name");
+const descOpt = takeOpt("--description");
+const [dirArg] = argv;
 
 if (upgrading) {
   const { HUB } = await import("./lib/util"); // resolves the hub, or exits with guidance
@@ -24,6 +41,8 @@ if (upgrading) {
   if (renamed) console.log(`  renamed: ${renamed} -> ${MARKER}`);
   if (pruned.length) console.log(`  removed (no longer part of the contract): ${pruned.join(", ")}`);
   console.log(`Your bundles/ and outer.index.md were not touched. Next: khb lint`);
+  const hint = updateHint(HUB);
+  if (hint) console.log(hint);
 } else {
   const hub = resolve(dirArg ?? process.cwd());
 
@@ -33,14 +52,8 @@ if (upgrading) {
     process.exit(1);
   }
 
-  mkdirSync(join(hub, "bundles"), { recursive: true });
-  cpSync(join(HUB_TEMPLATE, "outer.index.md"), join(hub, "outer.index.md"));
-  // Dotfiles: shipped unprefixed so npm doesn't swallow them, renamed on the way in.
-  // Never clobber — `khb init` may be run inside a folder that is already a git repo.
-  for (const f of ["gitignore", "gitattributes"])
-    if (!existsSync(join(hub, `.${f}`))) cpSync(join(HUB_TEMPLATE, f), join(hub, `.${f}`));
-  const synced = syncManaged(hub);
-  stamp(hub);
+  const { createHub } = await import("./lib/create");
+  const { synced, entry } = createHub(hub, { name: nameOpt, description: descOpt });
 
   console.log(`Hub created: ${hub}`);
   console.log(`  khb.json, outer.index.md, bundles/, .gitignore, .gitattributes`);
@@ -50,4 +63,5 @@ if (upgrading) {
   console.log(`  git init                              # optional, but recommended`);
   console.log(`  khb new-bundle <name> "<scope>"       # your first bundle`);
   console.log(`\nThen open this folder with Claude or Codex — both load AGENTS.md and the workflow skills.`);
+  console.log(`Registered as "${entry.name}" — from any terminal, 'khb' comes back here and starts your agent.`);
 }

package/scripts/lib/args.ts

@@ -1,8 +1,12 @@
 // Tiny argv helpers shared by the scripts that take flags. Each `take*` removes what it
 // consumed from the array, so whatever is left is the positional arguments.
-export function takeFlag(args: string[], name: string): boolean {
-  const i = args.indexOf(name);
-  if (i < 0) return false;
-  args.splice(i, 1);
-  return true;
+export function takeFlag(args: string[], ...names: string[]): boolean {
+  for (const name of names) {
+    const i = args.indexOf(name);
+    if (i >= 0) {
+      args.splice(i, 1);
+      return true;
+    }
+  }
+  return false;
 }

package/scripts/lib/create.ts

@@ -0,0 +1,39 @@
+// Creating a hub, as a function rather than a script.
+//
+// Two callers need it and must not diverge: `khb init`, and the first-run wizard a bare
+// `khb` opens when the machine has no hubs yet. A hub made by the wizard is the same hub
+// down to the byte — the wizard only asks the questions `init` takes as flags.
+import { cpSync, mkdirSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { HUB_TEMPLATE } from "./paths";
+import { syncManaged, stamp } from "./upgrade";
+import { registerHub, type HubEntry } from "./registry";
+
+export type CreatedHub = {
+  hub: string;
+  /** Package-owned contract files copied in, for the caller to report. */
+  synced: string[];
+  entry: HubEntry;
+};
+
+export function createHub(
+  dir: string,
+  opts: { name?: string; description?: string } = {},
+): CreatedHub {
+  const hub = resolve(dir);
+  mkdirSync(join(hub, "bundles"), { recursive: true });
+  cpSync(join(HUB_TEMPLATE, "outer.index.md"), join(hub, "outer.index.md"));
+  // Dotfiles: shipped unprefixed so npm doesn't swallow them, renamed on the way in.
+  // Never clobber — a hub may be created inside a folder that is already a git repo.
+  for (const f of ["gitignore", "gitattributes"])
+    if (!existsSync(join(hub, `.${f}`))) cpSync(join(HUB_TEMPLATE, f), join(hub, `.${f}`));
+  const synced = syncManaged(hub);
+  stamp(hub, undefined, {
+    ...(opts.name ? { name: opts.name } : {}),
+    ...(opts.description ? { description: opts.description } : {}),
+  });
+  // Put it on the machine's shortcut list straight away, so a bare `khb` from any
+  // terminal can find its way back here without the user remembering the path.
+  const entry = registerHub(hub);
+  return { hub, synced, entry };
+}

package/scripts/lib/log.ts

@@ -51,3 +51,43 @@ export function note(msg: string) {
 export function outcome(msg: string) {
   console.log(`         ${msg} (${secs(Date.now() - itemStart)})`);
 }
+
+/**
+ * A running counter for a walk whose units are too fast and too many to deserve a line
+ * each — thousands of files checked in milliseconds, where `item()` per file would bury
+ * the result in its own progress.
+ *
+ * On a terminal it rewrites one line in place, on **stderr**: the transient text never
+ * lands in a redirected log or a pipe, so `khb … > out.txt` still gets clean output. With
+ * no terminal it degrades to a milestone line every `every` units, so a CI log or a
+ * captured run still shows the walk moving rather than appearing hung.
+ *
+ * Always call `done()`, including on the early-exit paths — it is what erases the line.
+ */
+export function ticker(label: string, total?: number, every = 500) {
+  const tty = process.stderr.isTTY;
+  const of = total ? `/${total}` : "";
+  let n = 0;
+  let lastPaint = 0;
+  let width = 0;
+  return {
+    tick(suffix = "") {
+      n++;
+      const text = `  ${label} ${n}${of}${suffix ? ` — ${suffix}` : ""}`;
+      if (tty) {
+        // Repaint at ~12fps, not per unit: the terminal is slower than the walk, and an
+        // unthrottled counter spends more time drawing than working.
+        const now = Date.now();
+        if (now - lastPaint < 80 && n !== total) return;
+        lastPaint = now;
+        width = Math.max(width, text.length);
+        process.stderr.write(`\r${text.padEnd(width)}`);
+      } else if (n % every === 0) {
+        console.log(text);
+      }
+    },
+    done() {
+      if (tty && width) process.stderr.write(`\r${" ".repeat(width)}\r`);
+    },
+  };
+}

package/scripts/lib/registry.ts

@@ -0,0 +1,306 @@
+// The machine-level registry: ~/.khb/hubs-config.json.
+//
+// A hub is self-contained and knows nothing about the machine it sits on — that is the
+// point of the marker file. But a person with hubs in three places has no way to find
+// them from a cold terminal, so khb keeps one small file per *machine* listing where the
+// hubs are and which agent to open them with. It holds no knowledge, only paths: delete
+// it and nothing is lost but the shortcuts.
+//
+// Package-side, like paths.ts — importing this must never require a hub to exist.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, basename } from "node:path";
+import { markerIn } from "./paths";
+
+/** $KHB_HOME overrides the location — tests and portable installs need it moveable. */
+export const KHB_HOME = process.env.KHB_HOME ? resolve(process.env.KHB_HOME) : join(homedir(), ".khb");
+export const CONFIG = join(KHB_HOME, "hubs-config.json");
+
+/** How to start an agent in a hub folder. `args` is appended after the hub is cd'd into. */
+export type AgentSpec = { command: string; args?: string[] };
+
+export type HubEntry = {
+  name: string;
+  description: string;
+  path: string;
+  added: string;
+  lastUsed?: string;
+  /**
+   * The `created` stamp from the hub's own marker. Copied here purely as an identity
+   * fingerprint: after a hub is moved, its registry entry points at nothing, and matching
+   * this against the marker at the new location is how `khb update --path` knows which dead entry
+   * is the same hub rather than a different one that also went missing.
+   */
+  created?: string;
+};
+
+export type Config = {
+  version: 1;
+  /** Key into `agents`. Empty string means "never launch anything, just show the path". */
+  defaultAgent: string;
+  agents: Record<string, AgentSpec>;
+  hubs: HubEntry[];
+};
+
+/**
+ * Shipped defaults. Both are the plain binary name — resolved on PATH at launch time, so
+ * a machine without one installed simply fails at spawn with its own error rather than
+ * khb pretending to know where it lives.
+ */
+const DEFAULT_AGENTS: Record<string, AgentSpec> = {
+  claude: { command: "claude", args: [] },
+  codex: { command: "codex", args: [] },
+};
+
+const blank = (): Config => ({
+  version: 1,
+  defaultAgent: "claude",
+  agents: { ...DEFAULT_AGENTS },
+  hubs: [],
+});
+
+/**
+ * Read the registry, creating it on first run. Never throws on a damaged file: a
+ * corrupted shortcut list must not block `khb lint` in a hub that is perfectly fine, so
+ * unreadable JSON is reported once and treated as empty.
+ */
+export function loadConfig(): Config {
+  if (!existsSync(CONFIG)) {
+    const fresh = blank();
+    saveConfig(fresh);
+    return fresh;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(CONFIG, "utf8")) as Partial<Config>;
+    return {
+      version: 1,
+      defaultAgent: raw.defaultAgent ?? "claude",
+      agents: { ...DEFAULT_AGENTS, ...(raw.agents ?? {}) },
+      hubs: Array.isArray(raw.hubs) ? raw.hubs.filter((h) => h && typeof h.path === "string") : [],
+    };
+  } catch {
+    console.error(`khb: could not read ${CONFIG} — ignoring it. Fix or delete the file.`);
+    return blank();
+  }
+}
+
+export function saveConfig(cfg: Config): void {
+  mkdirSync(KHB_HOME, { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+/**
+ * The one true spelling of a path. `resolve` is not enough on Windows, where the same
+ * folder is reachable as `C:\Users\MANASV~1\…` and `C:\Users\Manasvi Sareen\…` with
+ * different casing again on top — three strings, one directory. Registering it under two
+ * of them would list one hub twice and defeat the move repair, so every path stored in or
+ * compared against the registry goes through here first.
+ *
+ * realpath also follows symlinks, which is the behaviour we want: a hub reached through a
+ * link is the same hub as the hub itself.
+ */
+export function canonical(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    return abs; // path does not exist (a moved-away hub): the resolved form is the best we have
+  }
+}
+
+/** Case-insensitive on Windows, after canonicalizing — see `canonical`. */
+const samePath = (a: string, b: string) => {
+  const [x, y] = [canonical(a), canonical(b)];
+  return process.platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+};
+
+/** Whatever the hub's own marker says about itself. Unreadable marker → nothing known. */
+export function markerFields(hub: string): { name?: string; description?: string; created?: string } {
+  const marker = markerIn(hub);
+  if (!marker) return {};
+  try {
+    const j = JSON.parse(readFileSync(join(hub, marker), "utf8"));
+    const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+    return { name: str(j.name), description: str(j.description), created: str(j.created) };
+  } catch {
+    return {}; // a hub with an unreadable marker still deserves a listing
+  }
+}
+
+/**
+ * A one-line description for a hub. Authored in the hub's own `khb.json` (`description`),
+ * so it travels with the hub and is not a second place to maintain the same sentence;
+ * with none, describe the hub by what is in it. Deliberately does not scrape
+ * `outer.index.md` — its opening line is template boilerplate identical in every hub.
+ */
+export function describeHub(hub: string): string {
+  const own = markerFields(hub).description;
+  if (own) return own;
+  const names = bundleNames(hub);
+  if (!names.length) return "no bundles yet";
+  const shown = names.slice(0, 4).join(", ");
+  return `${names.length} bundle${names.length === 1 ? "" : "s"}: ${shown}${names.length > 4 ? ", …" : ""}`;
+}
+
+export function bundleNames(hub: string): string[] {
+  try {
+    return readdirSync(join(hub, "bundles"), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Unique registry name for a hub: what its marker calls itself, else the folder name,
+ * suffixed if two hubs on this machine want the same one.
+ */
+function uniqueName(cfg: Config, hub: string): string {
+  const base = markerFields(hub).name ?? basename(hub) ?? "hub";
+  if (!cfg.hubs.some((h) => h.name === base)) return base;
+  for (let i = 2; ; i++) if (!cfg.hubs.some((h) => h.name === `${base}-${i}`)) return `${base}-${i}`;
+}
+
+/**
+ * Record a hub in the registry, or refresh what is already recorded. Called whenever khb
+ * resolves a hub, so hubs created before the registry existed register themselves the
+ * first time any command runs in them — no migration step, no `khb register` to remember.
+ * A user-edited name is never overwritten; the description is, since it is derived.
+ */
+export function registerHub(hub: string, opts: { name?: string; description?: string } = {}): HubEntry {
+  const path = canonical(hub);
+  const cfg = loadConfig();
+  const own = markerFields(path);
+  let entry = cfg.hubs.find((h) => samePath(resolve(h.path), path));
+  if (entry) {
+    entry.path = path;
+    // Both fields are derived from the hub, so both re-derive: rename or re-describe a hub
+    // in its own khb.json and the listing follows on the next command run there.
+    if (opts.name ?? own.name) entry.name = opts.name ?? own.name!;
+    entry.description = opts.description ?? describeHub(path);
+    entry.created = own.created;
+  } else {
+    entry = {
+      name: opts.name ?? uniqueName(cfg, path),
+      description: opts.description ?? describeHub(path),
+      path,
+      added: new Date().toISOString(),
+      created: own.created,
+    };
+    cfg.hubs.push(entry);
+  }
+  saveConfig(cfg);
+  return entry;
+}
+
+/** Stamp a hub as most recently used, so the picker can order by recency. */
+export function touchHub(hub: string): void {
+  const path = canonical(hub);
+  const cfg = loadConfig();
+  const entry = cfg.hubs.find((h) => samePath(resolve(h.path), path));
+  if (!entry) return;
+  entry.lastUsed = new Date().toISOString();
+  saveConfig(cfg);
+}
+
+export function forgetHub(nameOrPath: string): HubEntry | undefined {
+  const cfg = loadConfig();
+  const i = cfg.hubs.findIndex(
+    (h) => h.name === nameOrPath || samePath(resolve(h.path), resolve(nameOrPath)),
+  );
+  if (i < 0) return undefined;
+  const [gone] = cfg.hubs.splice(i, 1);
+  saveConfig(cfg);
+  return gone;
+}
+
+/** A registered hub whose folder no longer holds a marker — moved, deleted, or unmounted. */
+export const isAlive = (h: HubEntry): boolean => existsSync(h.path) && !!markerIn(h.path);
+
+/**
+ * Dead entries that are plausibly `hub` under its former name, best evidence first:
+ * an identical `created` stamp is proof (it is minted once, at `khb init`), a matching
+ * registry name is a guess. Returning candidates rather than picking one is deliberate —
+ * `khb update --path` acts on proof and asks when it only has a guess.
+ */
+export function relocationCandidates(hub: string): { certain: HubEntry[]; likely: HubEntry[] } {
+  const path = canonical(hub);
+  const own = markerFields(path);
+  const dead = loadConfig().hubs.filter((h) => !isAlive(h) && !samePath(resolve(h.path), path));
+  const certain = own.created ? dead.filter((h) => h.created === own.created) : [];
+  const likely = dead.filter(
+    (h) => !certain.includes(h) && h.name === (own.name ?? basename(path)),
+  );
+  return { certain, likely };
+}
+
+/**
+ * Point a registry entry at where the hub now lives. If the new location was already
+ * registered separately — a `khb` command was run there before anyone repaired the move —
+ * the two entries are the same hub, so fold the older one's history into the survivor
+ * rather than leaving a duplicate behind.
+ */
+export function relocateHub(oldPath: string, newPath: string): HubEntry {
+  const from = canonical(oldPath);
+  const to = canonical(newPath);
+  const cfg = loadConfig();
+  const stale = cfg.hubs.find((h) => samePath(resolve(h.path), from));
+  const already = cfg.hubs.find((h) => samePath(resolve(h.path), to));
+
+  const survivor = stale ?? already ?? {
+    name: uniqueName(cfg, to),
+    description: describeHub(to),
+    path: to,
+    added: new Date().toISOString(),
+  };
+  if (stale && already && stale !== already) {
+    survivor.added = [stale.added, already.added].filter(Boolean).sort()[0];
+    survivor.lastUsed = [stale.lastUsed, already.lastUsed].filter(Boolean).sort().pop();
+    cfg.hubs.splice(cfg.hubs.indexOf(already), 1);
+  }
+  if (!cfg.hubs.includes(survivor)) cfg.hubs.push(survivor);
+
+  survivor.path = to;
+  const own = markerFields(to);
+  // A name the marker states is the hub's own and survives the move. A name that was only
+  // ever the old folder's would otherwise outlive the folder — re-derive it from the new
+  // location, so the listing does not go on calling a hub after a directory that is gone.
+  if (own.name) survivor.name = own.name;
+  else if (survivor.name === basename(from)) {
+    const taken = cfg.hubs.filter((h) => h !== survivor);
+    survivor.name = uniqueName({ ...cfg, hubs: taken }, to);
+  }
+  survivor.description = describeHub(to);
+  survivor.created = own.created;
+  saveConfig(cfg);
+  return survivor;
+}
+
+/** Registered hubs, live ones first, each group most-recently-used first. */
+export function listHubs(): HubEntry[] {
+  const recency = (h: HubEntry) => Date.parse(h.lastUsed ?? h.added) || 0;
+  return loadConfig().hubs.slice().sort((a, b) => {
+    if (isAlive(a) !== isAlive(b)) return isAlive(a) ? -1 : 1;
+    return recency(b) - recency(a);
+  });
+}
+
+/** Resolve `khb go <what>` — a registry name, a 1-based list position, or a path. */
+export function findHubEntry(what: string): HubEntry | undefined {
+  const hubs = listHubs();
+  const byName = hubs.find((h) => h.name === what);
+  if (byName) return byName;
+  const n = Number(what);
+  if (Number.isInteger(n) && n >= 1 && n <= hubs.length) return hubs[n - 1];
+  return hubs.find((h) => samePath(resolve(h.path), resolve(what)));
+}
+
+export function agentFor(cfg: Config, name?: string): { name: string; spec: AgentSpec } | undefined {
+  const key = name ?? cfg.defaultAgent;
+  if (!key) return undefined;
+  const spec = cfg.agents[key];
+  // An unknown name is still usable as a bare command — someone naming an agent khb has
+  // never heard of should get their agent, not a lecture about the config file.
+  return { name: key, spec: spec ?? { command: key, args: [] } };
+}