@msareen/knowledge-hub-builder 0.1.4 → 0.1.5

package/AGENTS.md

@@ -135,7 +135,7 @@ From outside, pass `--hub <dir>` or set `$KHB_HUB`.
 | Command | Purpose |
 |---|---|
 | `khb lint` | validate structure against `skills/lint/SKILL.md` |
-| `khb upgrade` | refresh this hub's package-owned contract docs |
+| `khb upgrade` | refresh this hub's package-owned contract docs — runs by itself whenever `khb.json`'s stamped version differs from the installed khb, so these docs always match the CLI |
 | `khb visualize` | regenerate `visualizer/graph.html` |
 | `khb new-bundle <name>` | scaffold + register a bundle |
 | `khb ingest <bundle>` | acquire + extract every source in `sources.yaml` → `raw/`; maintains `log.md`. Name the bundle — with none it lists the hub's bundles and stops, unless there is nothing to choose between (no bundles, or only `default`), where it uses `default` |

package/README.md

@@ -208,6 +208,12 @@ files under `skills/` when developing KHB.
 changing `bundles/` or `outer.index.md`. `khb export` includes the same compatibility
 layout in a standalone bundle export.
 
+The refresh is also automatic: every command that works on a hub first compares the `khb`
+version stamped in `khb.json` against the installed package, and upgrades the hub in place
+if they differ, printing one line to stderr. So updating the package is enough — the hub's
+contract docs can never be a version behind the CLI acting on them. Set
+`KHB_NO_AUTO_UPGRADE=1` to suppress the check and leave the hub as it is.
+
 ## Commands
 
 Commands can be run directly or requested through the matching agent skill.
@@ -215,7 +221,7 @@ Commands can be run directly or requested through the matching agent skill.
 | Command | Purpose |
 |---|---|
 | `khb init [dir]` | Create a hub |
-| `khb upgrade` | Refresh package-owned contracts and skills |
+| `khb upgrade` | Refresh package-owned contracts and skills (also runs automatically on version drift) |
 | `khb new-bundle <name> ["scope"]` | Create and register a bundle |
 | `khb ingest [bundle] [--force]` | Acquire and extract declared sources |
 | `khb lint` | Validate routing, bundle structure, and OKF metadata |
@@ -229,14 +235,15 @@ Additional ingest flags:
 
 Run against a hub outside the current directory with `--hub <dir>` or `$KHB_HUB`.
 
-To update the installed package and then refresh a hub:
+To update the installed package:
 
 ```bash
 bun update -g @msareen/knowledge-hub-builder
-cd ~/my-knowledge
-khb upgrade
 ```
 
+Each hub refreshes itself the next time you run any command in it. `khb upgrade` does the
+same thing on demand, with a fuller report.
+
 ## Hub Layout
 
 ```text

package/SPEC.md

@@ -92,6 +92,14 @@ agent is opened on the hub folder and must find its rules there, without knowing
 `khb` is installed. They are package-owned: `khb upgrade` overwrites them in place and
 leaves `bundles/` and `outer.index.md` alone.
 
+Copies drift, so the copy is kept honest by the CLI rather than by the user's memory.
+`khb.json` stamps the version that wrote the hub's copies; before running any command that
+touches a hub, `khb` compares that stamp to the installed package version and, if they
+differ, performs the upgrade in place and says so on stderr. Only `init` (no hub yet) and
+`upgrade` (which is the operation) skip the check, and `KHB_NO_AUTO_UPGRADE=1` disables it.
+The invariant it buys: **a hub's contract docs always state the same version as the `khb`
+acting on them** — an agent can never read a protocol the CLI no longer implements.
+
 ### 2b. The package — `@msareen/knowledge-hub-builder`, installed once
 
 > **None of the following is in your hub.** This section describes the *installed tool*,
@@ -105,7 +113,7 @@ leaves `bundles/` and `outer.index.md` alone.
 @msareen/knowledge-hub-builder/     # installed once, globally — NOT part of a hub
 ├── package.json               # bin: khb → scripts/cli.ts
 ├── scripts/
-│   ├── cli.ts                 # subcommand dispatch; owns the global --hub flag
+│   ├── cli.ts                 # subcommand dispatch; --hub flag; the version drift check
 │   ├── init.ts                # khb init / khb upgrade
 │   ├── new-bundle.ts          # scaffold from .bundle_template, register in outer.index.md
 │   ├── export.ts              # bundle + common patterns → standalone shareable folder
@@ -116,6 +124,7 @@ leaves `bundles/` and `outer.index.md` alone.
 │       ├── extract.ts         # every local extractor + the content-hash cache
 │       ├── ledger.ts          # log.md read/write
 │       ├── paths.ts           # package-side paths — importing it never needs a hub
+│       ├── upgrade.ts         # the refresh itself: `khb upgrade` and the drift check
 │       └── util.ts            # hub resolution + shared helpers
 ├── .bundle_template/          # copied by `khb new-bundle`
 ├── templates/hub/             # copied by `khb init`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msareen/knowledge-hub-builder",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Knowledge Hub Builder — a bundle-of-bundles knowledge base you build with an agent",
   "keywords": ["knowledge-base", "okf", "agent", "wiki", "bundles", "claude", "codex", "rag"],
   "license": "MIT",

package/scripts/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 // khb — the CLI. Subcommands are loaded lazily: `init` must run before a hub exists,
 // so nothing that resolves a hub may be imported at module scope.
-import { version } from "./lib/paths";
+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)" },
@@ -59,6 +59,28 @@ if (!entry) {
   process.exit(1);
 }
 
+// Version drift: a hub carries package-owned copies of the agent contract, and a hub
+// 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) {
+  const hub = findHub();
+  if (hub) {
+    const { hubVersion, upgradeHub } = 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);
+      // stderr, so a command's own output stays pipeable.
+      console.error(
+        `khb: hub was built by ${from ?? "an unknown version"}, khb is ${to} — refreshed its contract docs.`,
+      );
+      if (renamed) console.error(`khb:   renamed ${renamed} -> khb.json`);
+      if (pruned.length) console.error(`khb:   removed (no longer part of the contract): ${pruned.join(", ")}`);
+    }
+  }
+}
+
 // Subcommand modules parse process.argv.slice(2) themselves — reshape it so they see
 // their own arguments and not the subcommand name.
 process.argv = [process.argv[0], process.argv[1], ...argv];

package/scripts/init.ts

@@ -5,63 +5,23 @@
 // copied INTO the hub — an agent opened on the hub folder must be able to read them
 // without knowing where khb is installed. Those copies are package-owned: `upgrade`
 // overwrites them.
-import { cpSync, mkdirSync, writeFileSync, existsSync, statSync, rmSync } from "node:fs";
-import { join, resolve, basename, dirname } from "node:path";
-import { PKG, HUB_TEMPLATE, MANAGED, RETIRED, MARKER, markerIn, version } from "./lib/paths";
+//
+// 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";
 
 const upgrading = process.env.KHB_SUBCOMMAND === "upgrade";
 const [dirArg] = process.argv.slice(2);
 
-/** Copy every package-owned contract file into the hub, replacing what is there. */
-function syncManaged(hub: string): string[] {
-  const done: string[] = [];
-  for (const f of MANAGED) {
-    const src = join(PKG, f);
-    if (!existsSync(src)) continue;
-    const dest = join(hub, f);
-    mkdirSync(dirname(dest), { recursive: true });
-    cpSync(src, dest, { recursive: true, force: true });
-    done.push(statSync(src).isDirectory() ? `${f}/` : f);
-  }
-  return done;
-}
-
-/** Drop package-owned files that later versions stopped shipping. */
-function pruneRetired(hub: string): string[] {
-  const gone: string[] = [];
-  for (const f of RETIRED) {
-    const p = join(hub, f);
-    if (!existsSync(p)) continue;
-    rmSync(p, { recursive: true, force: true });
-    gone.push(f);
-  }
-  return gone;
-}
-
-function stamp(hub: string, created?: string) {
-  writeFileSync(
-    join(hub, MARKER),
-    JSON.stringify(
-      { khb: version(), created: created ?? new Date().toISOString(), upgraded: new Date().toISOString() },
-      null,
-      2,
-    ) + "\n",
-  );
-}
-
 if (upgrading) {
   const { HUB } = await import("./lib/util"); // resolves the hub, or exits with guidance
-  // The hub may still carry a marker name from an older version; stamp() writes MARKER,
-  // so drop the old file rather than leaving the hub with two.
-  const found = markerIn(HUB)!;
-  const before = JSON.parse(await Bun.file(join(HUB, found)).text());
-  if (found !== MARKER) rmSync(join(HUB, found));
-  const synced = syncManaged(HUB);
-  const pruned = pruneRetired(HUB);
-  stamp(HUB, before.created);
-  console.log(`Upgraded ${HUB}: ${before.khb ?? before.bkr ?? "?"} -> ${version()}`);
+  const { from, to, synced, pruned, renamed } = upgradeHub(HUB);
+  console.log(`Upgraded ${HUB}: ${from ?? "?"} -> ${to}`);
   console.log(`  refreshed: ${synced.join(", ")}`);
-  if (found !== MARKER) console.log(`  renamed: ${found} -> ${MARKER}`);
+  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`);
 } else {

package/scripts/lib/paths.ts

@@ -1,7 +1,7 @@
 // Package-side paths. Importing this must never require a hub to exist — `khb init`
 // runs before there is one. Hub-side paths live in util.ts.
 import { fileURLToPath } from "node:url";
-import { join } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { readFileSync, existsSync } from "node:fs";
 
 /** Root of the installed @msareen/knowledge-hub-builder package (NOT the user's hub). */
@@ -29,6 +29,26 @@ export const LEGACY_MARKERS = ["bkr.json"];
 export const markerIn = (dir: string): string | undefined =>
   [MARKER, ...LEGACY_MARKERS].find((m) => existsSync(join(dir, m)));
 
+/**
+ * The hub this invocation acts on, or undefined if there is none. Precedence:
+ * $KHB_HUB (set from --hub by cli.ts) > nearest ancestor of cwd holding a marker.
+ * Soft by design — util.ts turns "none" into an error with guidance, while the version
+ * drift check in cli.ts must stay silent for commands that run outside a hub.
+ */
+export function findHub(): string | undefined {
+  const explicit = process.env.KHB_HUB;
+  if (explicit) {
+    const dir = resolve(explicit);
+    return markerIn(dir) ? dir : undefined;
+  }
+  for (let dir = process.cwd(); ; ) {
+    if (markerIn(dir)) return dir;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
 /**
  * Package-owned files copied into every hub by `khb init` and refreshed by
  * `khb upgrade`. These are the agent contract — the hub needs its own copies so an

package/scripts/lib/upgrade.ts

@@ -0,0 +1,93 @@
+// The upgrade mechanism: refresh a hub's package-owned contract docs to match the
+// installed khb. Lives here rather than in init.ts because two callers need it — the
+// explicit `khb upgrade`, and the drift check cli.ts runs before every hub command.
+//
+// Nothing here may import util.ts: the drift check runs before a hub is resolved, and
+// util.ts resolves one or exits.
+import { cpSync, mkdirSync, writeFileSync, readFileSync, existsSync, statSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { PKG, MANAGED, RETIRED, MARKER, markerIn, version } from "./paths";
+
+export type UpgradeResult = {
+  /** Version recorded in the hub's marker before the upgrade, if it recorded one. */
+  from?: string;
+  to: string;
+  synced: string[];
+  pruned: string[];
+  /** Set when a legacy marker name was renamed to khb.json. */
+  renamed?: string;
+};
+
+/** Read the khb version a hub was last stamped with. Undefined if it records none. */
+export function hubVersion(hub: string): string | undefined {
+  const found = markerIn(hub);
+  if (!found) return undefined;
+  try {
+    const marker = JSON.parse(readFileSync(join(hub, found), "utf8"));
+    return marker.khb ?? marker.bkr; // bkr: the pre-rename field name
+  } catch {
+    return undefined; // unreadable marker — treat as drifted, upgrade will restamp it
+  }
+}
+
+/** Copy every package-owned contract file into the hub, replacing what is there. */
+export function syncManaged(hub: string): string[] {
+  const done: string[] = [];
+  for (const f of MANAGED) {
+    const src = join(PKG, f);
+    if (!existsSync(src)) continue;
+    const dest = join(hub, f);
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true, force: true });
+    done.push(statSync(src).isDirectory() ? `${f}/` : f);
+  }
+  return done;
+}
+
+/** Drop package-owned files that later versions stopped shipping. */
+function pruneRetired(hub: string): string[] {
+  const gone: string[] = [];
+  for (const f of RETIRED) {
+    const p = join(hub, f);
+    if (!existsSync(p)) continue;
+    rmSync(p, { recursive: true, force: true });
+    gone.push(f);
+  }
+  return gone;
+}
+
+/** Write khb.json with the installed version, preserving the hub's creation date. */
+export function stamp(hub: string, created?: string) {
+  writeFileSync(
+    join(hub, MARKER),
+    JSON.stringify(
+      { khb: version(), created: created ?? new Date().toISOString(), upgraded: new Date().toISOString() },
+      null,
+      2,
+    ) + "\n",
+  );
+}
+
+/**
+ * Bring `hub`'s package-owned files up to the installed version. Touches only what the
+ * package owns: bundles/, outer.index.md and anything else the user wrote are untouched.
+ */
+export function upgradeHub(hub: string): UpgradeResult {
+  // The hub may still carry a marker name from an older version; stamp() writes MARKER,
+  // so drop the old file rather than leaving the hub with two.
+  const found = markerIn(hub)!;
+  let created: string | undefined;
+  let from: string | undefined;
+  try {
+    const before = JSON.parse(readFileSync(join(hub, found), "utf8"));
+    created = before.created;
+    from = before.khb ?? before.bkr;
+  } catch {
+    /* unreadable marker: rewritten below with today's date */
+  }
+  if (found !== MARKER) rmSync(join(hub, found));
+  const synced = syncManaged(hub);
+  const pruned = pruneRetired(hub);
+  stamp(hub, created);
+  return { from, to: version(), synced, pruned, renamed: found === MARKER ? undefined : found };
+}

package/scripts/lib/util.ts

@@ -1,7 +1,7 @@
 import { readdirSync, readFileSync, existsSync, statSync, mkdirSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { join, basename, dirname, resolve } from "node:path";
-import { MARKER, markerIn } from "./paths";
+import { join, basename, resolve } from "node:path";
+import { MARKER, markerIn, findHub } from "./paths";
 
 /**
  * Find the hub root — the folder holding khb.json, outer.index.md and bundles/.
@@ -10,20 +10,12 @@ import { MARKER, markerIn } from "./paths";
  * ancestor of cwd containing the marker.
  */
 function resolveHub(): string {
+  const found = findHub();
+  if (found) return found;
   const explicit = process.env.KHB_HUB;
   if (explicit) {
-    const dir = resolve(explicit);
-    if (!markerIn(dir)) {
-      console.error(`Not a KHB hub (no ${MARKER}): ${dir}`);
-      process.exit(1);
-    }
-    return dir;
-  }
-  for (let dir = process.cwd(); ; ) {
-    if (markerIn(dir)) return dir;
-    const up = dirname(dir);
-    if (up === dir) break;
-    dir = up;
+    console.error(`Not a KHB hub (no ${MARKER}): ${resolve(explicit)}`);
+    process.exit(1);
   }
   console.error(`No KHB hub found in ${process.cwd()} or any parent directory.`);
   console.error(`Create one:   khb init <dir>`);