@msareen/knowledge-hub-builder 0.1.7 → 0.2.0

package/scripts/cli.ts

@@ -3,16 +3,47 @@
 // so nothing that resolves a hub may be imported at module scope.
 import { version, findHub, markerIn, MARKER } from "./lib/paths";
 
-const COMMANDS: Record<string, { load: () => Promise<unknown>; help: string }> = {
-  init: { load: () => import("./init"), help: "khb init [dir]                  create a hub here (or in dir)" },
-  upgrade: { load: () => import("./init"), help: "khb upgrade                     refresh this hub's contract docs" },
-  "new-bundle": { load: () => import("./new-bundle"), help: 'khb new-bundle <name> ["scope"]  scaffold a bundle + register it' },
-  ingest: { load: () => import("./ingest/index"), help: "khb ingest <bundle> [--force]   acquire + extract declared sources → raw/ (name required once the hub has a bundle other than 'default')" },
-  lint: { load: () => import("./lint"), help: "khb lint                        validate the hub against skills/lint/SKILL.md" },
-  visualize: { load: () => import("./visualize"), help: "khb visualize [--port N] [--no-open]  serve the live bundle graph in your browser; aliases: vis, viz" },
-  export: { load: () => import("./export"), help: "khb export <bundle> [dest]      standalone copy of one bundle" },
+const COMMANDS: Record<string, { load: () => Promise<unknown>; usage: string; desc: string }> = {
+  init: { load: () => import("./init"), usage: 'khb init [dir] [--name N] [--description "…"]', desc: "create a hub here (or in dir)" },
+  upgrade: { load: () => import("./init"), usage: "khb upgrade", desc: "refresh this hub's contract docs" },
+  "new-bundle": { load: () => import("./new-bundle"), usage: 'khb new-bundle <name> ["scope"]', desc: "scaffold a bundle + register it" },
+  ingest: {
+    load: () => import("./ingest/index"),
+    usage: "khb ingest [bundle] [--force] [--skip-ocr] [--skip-audio]",
+    desc: "acquire + extract declared sources → raw/",
+  },
+  lint: { load: () => import("./lint"), usage: "khb lint", desc: "validate the hub against skills/lint/SKILL.md" },
+  visualize: {
+    load: () => import("./visualize"),
+    usage: "khb visualize [--port N] [--no-open]",
+    desc: "serve the live bundle graph in your browser; aliases: vis, viz",
+  },
+  export: { load: () => import("./export"), usage: "khb export <bundle> [dest]", desc: "standalone copy of one bundle" },
+  list: { load: () => import("./hubs"), usage: "khb list [--json]", desc: "every hub on this machine" },
+  go: {
+    load: () => import("./hubs"),
+    usage: "khb go [name|N] [--path] [--no-agent] [--agent X]",
+    desc: "open a hub with your agent (bare 'khb' picks one)",
+  },
+  agent: {
+    load: () => import("./hubs"),
+    usage: 'khb agent [name|none] [--command X] [--args "…"]',
+    desc: "which agent 'khb go' launches",
+  },
+  update: {
+    load: () => import("./hubs"),
+    usage: "khb update [new-path] [--path|-p] [--schema|-s] [--from <old>] [--dry-run]",
+    desc: "repair a moved hub's paths, and/or backfill sources.yaml",
+  },
+  forget: { load: () => import("./hubs"), usage: "khb forget <name|path>", desc: "drop a hub from the list (folder untouched)" },
 };
 
+/**
+ * Commands that work *outside* a hub, against ~/.khb/hubs-config.json. They must not
+ * resolve or upgrade a hub — their whole job is running before you are in one.
+ */
+const REGISTRY_COMMANDS = new Set(["list", "go", "agent", "forget", "update"]);
+
 // Short forms that just resolve to a canonical command above — kept out of COMMANDS
 // itself so help text lists each command once. `-v` is taken by --version, so
 // `visualize` gets word-shaped aliases instead of a letter one.
@@ -34,15 +65,56 @@ if (hubAt >= 0) {
 }
 
 const cmd0 = argv.shift();
-const cmd = cmd0 && ALIASES[cmd0] ? ALIASES[cmd0] : cmd0;
+// Bare `khb` is the way in from a cold terminal: pick a hub and open it. Help stays one
+// word away, and is what you get when no hub has ever been registered.
+const cmd = !cmd0 ? "go" : (ALIASES[cmd0] ?? cmd0);
+
+if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+  // Descriptions align to the longest usage — but only among those that fit. One long
+  // entry should not push every other description off an 80-column terminal: past the
+  // cap, that entry gets its own line for the usage and an indented line for the
+  // description, instead of dragging the whole column wide.
+  const CAP = 60;
+  const usages = Object.values(COMMANDS).map((c) => c.usage.length);
+  const width = Math.max(...usages.filter((n) => n <= CAP));
+  const printSection = (title: string, names: string[]) => {
+    console.log(title);
+    for (const name of names) {
+      const c = COMMANDS[name];
+      if (c.usage.length > width) {
+        console.log(`  ${c.usage}`);
+        console.log(`  ${" ".repeat(width)}   ${c.desc}`);
+      } else {
+        console.log(`  ${c.usage.padEnd(width)}   ${c.desc}`);
+      }
+    }
+  };
 
-if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
-  console.log(`khb ${version()} — Knowledge Hub Builder\n`);
+  console.log(`khb ${version()} — Knowledge Hub Builder`);
+  console.log();
   console.log(`khb is the supporting tool: it handles deterministic extraction, file plumbing,`);
   console.log(`validation, and export. Your AI agent — Claude, Codex, Gemini, or another`);
-  console.log(`compatible agent — follows the workflow skills and orchestrates the knowledge work.\n`);
-  for (const c of Object.values(COMMANDS)) console.log("  " + c.help);
-  console.log(`\nGlobal:  --hub <dir>   operate on that hub instead of searching upward from cwd`);
+  console.log(`compatible agent — follows the workflow skills and orchestrates the knowledge work.`);
+  console.log();
+
+  printSection(
+    "In a hub:",
+    Object.keys(COMMANDS).filter((name) => !REGISTRY_COMMANDS.has(name)),
+  );
+  console.log();
+  printSection(
+    "Anywhere on this machine (no hub needed) — config and maintenance:",
+    Object.keys(COMMANDS).filter((name) => REGISTRY_COMMANDS.has(name)),
+  );
+  console.log();
+
+  console.log(`Global:  --hub <dir>              operate on that hub instead of searching upward from cwd`);
+  console.log(`         help | --help | -h       this help          --version | -v   version`);
+  console.log(`Env:     KHB_HUB                  same as --hub`);
+  console.log(`         KHB_HOME                 where the hub list lives (default ~/.khb)`);
+  console.log(`         KHB_NO_AUTO_UPGRADE      don't refresh a hub's contract docs on version drift`);
+  console.log(`Exit:    0 on success, 1 on a usage error or a failure. An unknown option is an error;`);
+  console.log(`         a source khb cannot extract is not — it becomes a pending row in log.md.`);
   console.log(`Docs:    https://github.com/msareen/knowledge-hub-builder`);
   process.exit(0);
 }
@@ -63,11 +135,31 @@ if (!entry) {
 // stamped at an older version than the installed khb is stating an older contract than
 // the one the CLI now implements. Rather than let the two disagree, refresh the hub in
 // place before running the command — `khb upgrade` touches nothing the user wrote.
-// `init` has no hub yet, `upgrade` does this itself, and $KHB_NO_AUTO_UPGRADE opts out.
-if (cmd !== "init" && cmd !== "upgrade" && !process.env.KHB_NO_AUTO_UPGRADE) {
+// `init` has no hub yet, `upgrade` does this itself, the registry commands run outside
+// any hub, and $KHB_NO_AUTO_UPGRADE opts out.
+if (cmd !== "init" && cmd !== "upgrade" && !REGISTRY_COMMANDS.has(cmd)) {
   const hub = findHub();
   if (hub) {
-    const { hubVersion, upgradeHub } = await import("./lib/upgrade");
+    // Any command run in a hub is proof the hub exists and is in use — record it, so the
+    // machine registry fills itself in without a migration or a `khb register` to recall.
+    const { registerHub, touchHub } = await import("./lib/registry");
+    registerHub(hub);
+    touchHub(hub);
+
+    // …and proof of where it is. The hub records its own location in its marker, so a move
+    // is noticed by the hub itself rather than inferred from a registry that may have been
+    // deleted or never have seen this machine. Must run before the drift check below:
+    // that restamps the marker, and would overwrite the old location before anyone read it.
+    const { recordLocation } = await import("./lib/upgrade");
+    const { moved } = recordLocation(hub);
+    if (moved) {
+      console.error(`khb: this hub was at ${moved} and is now at ${hub}.`);
+      console.error(`khb:   absolute paths recorded inside it still name the old location.`);
+      console.error(`khb:   repair them:  khb update --path           (--dry-run to preview)`);
+    }
+  }
+  if (hub && !process.env.KHB_NO_AUTO_UPGRADE) {
+    const { hubVersion, upgradeHub, updateHint } = await import("./lib/upgrade");
     // A marker under a pre-rename name is drift too, even at a matching version.
     if (hubVersion(hub) !== version() || markerIn(hub) !== MARKER) {
       const { from, to, pruned, renamed } = upgradeHub(hub);
@@ -77,6 +169,8 @@ if (cmd !== "init" && cmd !== "upgrade" && !process.env.KHB_NO_AUTO_UPGRADE) {
       );
       if (renamed) console.error(`khb:   renamed ${renamed} -> khb.json`);
       if (pruned.length) console.error(`khb:   removed (no longer part of the contract): ${pruned.join(", ")}`);
+      const hint = updateHint(hub);
+      if (hint) console.error(hint);
     }
   }
 }

package/scripts/export.ts

@@ -4,8 +4,13 @@
 import { cpSync, writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
 import { HUB, bundleDir, join } from "./lib/util";
 import { detail, totalElapsed } from "./lib/log";
+import { rejectUnknownFlags } from "./lib/args";
 
-const [name, destArg] = process.argv.slice(2);
+const argv = process.argv.slice(2);
+// Before reading positionals: an unrecognized flag would otherwise become the destination,
+// and `khb export mybundle --force` would export into a folder named `--force`.
+rejectUnknownFlags(argv, "khb export <bundle> [dest]");
+const [name, destArg] = argv;
 if (!name) { console.error("Usage: khb export <bundle> [dest]"); process.exit(1); }
 
 const src = bundleDir(name);