@saasontools/strauss-kb 0.1.15 → 0.1.16

package/dist/cli-main.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   runKbCli
-} from "./chunk-MK7GU4DX.js";
-import "./chunk-KNIUBCZY.js";
+} from "./chunk-RINBOAQZ.js";
+import "./chunk-H5W53NVU.js";
 
 // src/cli-main.ts
 runKbCli(process.argv.slice(2)).catch((error) => {

package/dist/index.cjs

@@ -149,7 +149,6 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/kb-store.ts
-var import_node_crypto2 = require("crypto");
 var import_promises4 = require("fs/promises");
 var import_node_path4 = require("path");
 
@@ -345,6 +344,8 @@ var ErrorTypes = /* @__PURE__ */ ((ErrorTypes2) => {
   ErrorTypes2["KbPackBudgetExceeded"] = "KbPackBudgetExceeded";
   ErrorTypes2["KbRecordNotFound"] = "KbRecordNotFound";
   ErrorTypes2["KbSelfVerification"] = "KbSelfVerification";
+  ErrorTypes2["KbStampBaselineUnreadable"] = "KbStampBaselineUnreadable";
+  ErrorTypes2["KbStampDigestBaselineAmbiguous"] = "KbStampDigestBaselineAmbiguous";
   ErrorTypes2["KbUnknownLinkRel"] = "KbUnknownLinkRel";
   ErrorTypes2["KbWriteConflict"] = "KbWriteConflict";
   return ErrorTypes2;
@@ -499,6 +500,36 @@ var KbInvalidConceptIdError = class extends BaseError {
     });
   }
 };
+var KbStampBaselineError = class extends BaseError {
+  constructor(since) {
+    super({
+      message: `kb: --since ${since} is neither a 64-character digest nor a readable stamp file`,
+      errorType: "KbStampBaselineUnreadable" /* KbStampBaselineUnreadable */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { since }
+    });
+    this.since = since;
+  }
+  since;
+};
+var KbStampDigestBaselineError = class extends BaseError {
+  constructor(since) {
+    super({
+      message: `kb: --since ${since} is a digest, which needs --bundle (one base) \u2014 a file baseline works for many`,
+      errorType: "KbStampDigestBaselineAmbiguous" /* KbStampDigestBaselineAmbiguous */,
+      code: 400,
+      fault: "User" /* User */,
+      retriable: false,
+      reportToUser: true,
+      details: { since }
+    });
+    this.since = since;
+  }
+  since;
+};
 
 // src/kb-index.ts
 var INDEX_FILE = "INDEX.md";
@@ -1068,6 +1099,38 @@ function successors(record, byId) {
   return { records, missing };
 }
 
+// src/kb-stamp.ts
+var import_node_crypto = require("crypto");
+function sha256(contents) {
+  return (0, import_node_crypto.createHash)("sha256").update(contents).digest("hex");
+}
+function bundleStamp(records, superseded) {
+  const entries = [
+    ...records.map((hit) => ({
+      conceptId: hit.record.conceptId,
+      digest: `current:${sha256(
+        stringifyMarkdownWithFrontmatter(
+          hit.record.body,
+          hit.record.frontmatter
+        )
+      )}`
+    })),
+    ...superseded.map((entry) => ({
+      conceptId: entry.conceptId,
+      digest: `superseded:${sha256(JSON.stringify(entry))}`
+    }))
+  ].sort((a, b) => a.conceptId < b.conceptId ? -1 : 1);
+  return {
+    digest: sha256(
+      entries.map((entry) => `${entry.conceptId}:${entry.digest}`).join("\n")
+    ),
+    records: entries
+  };
+}
+function bundleDigest(records, superseded) {
+  return bundleStamp(records, superseded).digest;
+}
+
 // src/anchor-resolver/read.ts
 var import_promises2 = require("fs/promises");
 var import_node_path2 = require("path");
@@ -1159,7 +1222,7 @@ async function readAnchorFiles(files, read, concurrency = DEFAULT_IO_CONCURRENCY
 }
 
 // src/anchor-resolver/resolver.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var PARENT_SCOPE_LINES = 50;
 var CLEAN_STATE = { blockComment: false, template: false };
 function stripLine(line, state) {
@@ -1320,7 +1383,7 @@ function distanceToParent(lines, index, parent) {
   return Number.POSITIVE_INFINITY;
 }
 function hashAnchorText(text) {
-  return `sha256:${(0, import_node_crypto.createHash)("sha256").update(text.replace(/\r\n/g, "\n")).digest("hex")}`;
+  return `sha256:${(0, import_node_crypto2.createHash)("sha256").update(text.replace(/\r\n/g, "\n")).digest("hex")}`;
 }
 function resolveAnchor(source, anchor, resolver = regexResolver) {
   const normalized = source.replace(/\r\n/g, "\n");
@@ -2523,6 +2586,28 @@ ${answer}
       digest: bundleDigestValue
     };
   }
+  /**
+   * `load`'s digest without `load`'s bodies — the same records, adjudicated
+   * the same way, handed back as a stamp. Skips the anchor drift pass, which
+   * reads source files and only ever adds warnings: no warning reaches the
+   * digest, so the value is identical to the one `load` returns.
+   */
+  async stamp(bundlePath2) {
+    const bundle = await this.list(bundlePath2);
+    const adjudicated = adjudicate(bundle, bundle, /* @__PURE__ */ new Date());
+    const current = adjudicated.filter((hit) => hit.standing !== "superseded");
+    const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(stub);
+    const stamped = bundleStamp(current, superseded);
+    const dates = bundle.map((record) => record.frontmatter.generated?.at ?? null).filter((at) => typeof at === "string").sort();
+    return {
+      path: bundlePath2,
+      digest: stamped.digest,
+      recordCount: bundle.length,
+      superseded: superseded.length,
+      newestAt: dates.at(-1) ?? null,
+      records: stamped.records
+    };
+  }
   /** How a position was arrived at, as a timeline. See `trace.ts`. */
   async trace(bundlePath2, seedId, options = {}) {
     return trace(seedId, await this.list(bundlePath2), options);
@@ -2634,7 +2719,7 @@ ${answer}
     const body = changeBody(parsed.body);
     const contents = stringifyMarkdownWithFrontmatter(body, frontmatter);
     const witness = await (0, import_promises4.readFile)(target, "utf8").catch(() => null);
-    if (witness === null || digest(witness) !== digest(before)) {
+    if (witness === null || sha256(witness) !== sha256(before)) {
       throw new KbWriteConflictError(conceptId2);
     }
     await this.publish(target, contents, true, conceptId2);
@@ -2842,25 +2927,6 @@ function normalizeActor(id) {
   if (colon === -1) return id.toLowerCase();
   return id.slice(0, colon + 1).toLowerCase() + id.slice(colon + 1);
 }
-function digest(contents) {
-  return (0, import_node_crypto2.createHash)("sha256").update(contents).digest("hex");
-}
-function bundleDigest(records, superseded) {
-  const entries = [
-    ...records.map(
-      (hit) => `${hit.record.conceptId}:current:${digest(
-        stringifyMarkdownWithFrontmatter(
-          hit.record.body,
-          hit.record.frontmatter
-        )
-      )}`
-    ),
-    ...superseded.map(
-      (entry) => `${entry.conceptId}:superseded:${digest(JSON.stringify(entry))}`
-    )
-  ].sort();
-  return digest(entries.join("\n"));
-}
 
 // src/compose.ts
 var import_zod3 = require("zod");
@@ -4921,17 +4987,115 @@ var schemaCommand = define({
   run: () => Promise.resolve(kbJsonSchemas())
 });
 
-// src/commands/status.ts
+// src/commands/stamp.ts
+var import_promises7 = require("fs/promises");
 var import_zod25 = require("zod");
+var DIGEST = /^[0-9a-f]{64}$/;
+var stampCommand = define({
+  name: "stamp",
+  tool: "kb_stamp",
+  usage: "stamp [--bundle PATH] [--since DIGEST|FILE]",
+  description: "Content stamp of a base \u2014 `load`'s digest, record counts, per-record digests \u2014 without any bodies. Takes no bundlePath to stamp every pinned base. With `since`, reports only the bases that moved, naming the changed ids when the baseline is a prior stamp; silent when nothing changed. Reads, never writes.",
+  input: import_zod25.z.object({
+    bundlePath: import_zod25.z.string().min(1).optional().describe(
+      "Absolute path to one knowledge base. Omit to stamp every pinned base."
+    ),
+    since: import_zod25.z.string().min(1).optional().describe(
+      "Prior digest, or path to a prior `stamp --json`; only moved bases return, with changed ids when the baseline is a file."
+    )
+  }),
+  fromArgv: (argv, path, _stdin, bundleExplicit) => {
+    const since = argvFlag(argv, "--since");
+    return {
+      ...bundleExplicit ? { bundlePath: path } : {},
+      ...since !== void 0 ? { since } : {}
+    };
+  },
+  run: async ({ store }, { bundlePath: bundlePath2, since }) => {
+    const targets = bundlePath2 ? [bundlePath2] : (await readMergedPins(process.cwd())).pins.map(
+      (pin) => pin.absolutePath
+    );
+    if (since !== void 0 && DIGEST.test(since) && targets.length > 1) {
+      throw new KbStampDigestBaselineError(since);
+    }
+    const stamps = await Promise.all(
+      targets.map((target) => store.stamp(target))
+    );
+    if (since === void 0) {
+      return stamps.map((stamp) => ({ ...stamp, changed: null }));
+    }
+    const baseline = await readBaseline(since);
+    const reports = [];
+    for (const stamp of stamps) {
+      const before = baseline.byPath.get(stamp.path);
+      if (baseline.digest !== null) {
+        if (baseline.digest === stamp.digest) continue;
+        reports.push({ ...stamp, changed: null });
+        continue;
+      }
+      if (before && before.digest === stamp.digest) continue;
+      reports.push({ ...stamp, changed: changedIds(before?.records, stamp) });
+    }
+    return reports;
+  },
+  render: (result) => result.map((report) => {
+    const counts = `${report.recordCount} record(s), ${report.superseded} superseded`;
+    const head = `${report.path}  ${report.digest}  ${counts}${report.newestAt ? `  newest ${report.newestAt}` : ""}`;
+    return report.changed?.length ? `${head}
+  changed: ${report.changed.join(", ")}` : head;
+  }).join("\n")
+});
+function changedIds(before, stamp) {
+  const now = new Map(
+    stamp.records.map((record) => [record.conceptId, record.digest])
+  );
+  const ids = /* @__PURE__ */ new Set();
+  for (const [conceptId2, digest] of now) {
+    if (before?.get(conceptId2) !== digest) ids.add(conceptId2);
+  }
+  for (const conceptId2 of before?.keys() ?? []) {
+    if (!now.has(conceptId2)) ids.add(conceptId2);
+  }
+  return [...ids].sort();
+}
+async function readBaseline(since) {
+  if (DIGEST.test(since)) return { digest: since, byPath: /* @__PURE__ */ new Map() };
+  let parsed;
+  try {
+    parsed = JSON.parse(await (0, import_promises7.readFile)(since, "utf8"));
+  } catch {
+    throw new KbStampBaselineError(since);
+  }
+  const entries = Array.isArray(parsed) ? parsed : parsed?.stamps ?? [];
+  const byPath = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (typeof entry?.path !== "string" || typeof entry?.digest !== "string") {
+      continue;
+    }
+    byPath.set(entry.path, {
+      digest: entry.digest,
+      records: new Map(
+        (entry.records ?? []).map((record) => [
+          record.conceptId,
+          record.digest
+        ])
+      )
+    });
+  }
+  return { digest: null, byPath };
+}
+
+// src/commands/status.ts
+var import_zod26 = require("zod");
 var statusCommand = define({
   name: "status",
   tool: "kb_status",
   usage: "status <concept-id> <status>",
   description: "Move a record's status. Compare-and-swap: a concurrent change fails instead of being overwritten.",
-  input: import_zod25.z.object({
+  input: import_zod26.z.object({
     bundlePath,
     conceptId,
-    status: import_zod25.z.enum(KB_RECORD_STATUSES)
+    status: import_zod26.z.enum(KB_RECORD_STATUSES)
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -4946,13 +5110,13 @@ var statusCommand = define({
 });
 
 // src/commands/supersede.ts
-var import_zod26 = require("zod");
+var import_zod27 = require("zod");
 var supersedeCommand = define({
   name: "supersede",
   tool: "kb_supersede",
   usage: "supersede <concept-id> <replacement-id>",
   description: "Mark a record superseded by another, linked in both directions. Use instead of editing a record whose meaning changed.",
-  input: import_zod26.z.object({ bundlePath, conceptId, replacementId: conceptId }),
+  input: import_zod27.z.object({ bundlePath, conceptId, replacementId: conceptId }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
     conceptId: argv[1],
@@ -4966,16 +5130,16 @@ var supersedeCommand = define({
 });
 
 // src/commands/sync-instructions.ts
-var import_zod27 = require("zod");
+var import_zod28 = require("zod");
 var syncInstructionsCommand = define({
   name: "sync-instructions",
   usage: "sync-instructions <file> [--profile NAME] [--budget N] [--full-under N]",
   description: "CLI-only: plant the kb_context block between sentinel comments in AGENTS.md or CLAUDE.md, idempotently.",
-  input: import_zod27.z.object({
-    file: import_zod27.z.string().min(1).describe("The instruction file to edit in place."),
-    budgetTokens: import_zod27.z.number().int().positive().optional(),
-    fullUnderTokens: import_zod27.z.number().int().positive().optional(),
-    profile: import_zod27.z.string().optional()
+  input: import_zod28.z.object({
+    file: import_zod28.z.string().min(1).describe("The instruction file to edit in place."),
+    budgetTokens: import_zod28.z.number().int().positive().optional(),
+    fullUnderTokens: import_zod28.z.number().int().positive().optional(),
+    profile: import_zod28.z.string().optional()
   }),
   fromArgv: (argv) => {
     const budget = argvFlag(argv, "--budget");
@@ -5001,17 +5165,17 @@ var syncInstructionsCommand = define({
 });
 
 // src/commands/trace.ts
-var import_zod28 = require("zod");
+var import_zod29 = require("zod");
 var traceCommand = define({
   name: "trace",
   tool: "kb_trace",
   usage: "trace <concept-id> [edges...]",
   description: 'Timeline of how a position was reached, ordered by write time, following supersession, shared anchors and shared sources. Includes rejected, draft and superseded records \u2014 in a history they are the content. For "why is it like this"; kb_load answers "what holds now".',
-  input: import_zod28.z.object({
+  input: import_zod29.z.object({
     bundlePath,
     conceptId,
-    edges: import_zod28.z.array(import_zod28.z.enum(TRACE_EDGES)).optional(),
-    depth: import_zod28.z.number().int().positive().optional()
+    edges: import_zod29.z.array(import_zod29.z.enum(TRACE_EDGES)).optional(),
+    depth: import_zod29.z.number().int().positive().optional()
   }),
   fromArgv: (argv, path) => ({
     bundlePath: path,
@@ -5033,37 +5197,37 @@ var traceCommand = define({
 });
 
 // src/commands/types.ts
-var import_zod29 = require("zod");
+var import_zod30 = require("zod");
 var typesCommand = define({
   name: "types",
   tool: "kb_types",
   usage: "types",
   description: "The twelve record types with their purpose, body sections, and starting status. Read this before writing rather than guessing headings \u2014 a section the type does not define is rejected.",
-  input: import_zod29.z.object({}),
+  input: import_zod30.z.object({}),
   fromArgv: () => ({}),
   run: () => Promise.resolve(RECORD_TYPES)
 });
 
 // src/commands/unpin.ts
-var import_zod30 = require("zod");
+var import_zod31 = require("zod");
 var unpinCommand = define({
   name: "unpin",
   tool: "kb_unpin",
   usage: "unpin [bundle-path]",
   description: "Remove a base from every manifest layer that holds it. Reports the layers touched.",
-  input: import_zod30.z.object({ bundlePath }),
+  input: import_zod31.z.object({ bundlePath }),
   fromArgv: (argv, path) => ({ bundlePath: argv[1] ?? path }),
   run: (_ctx, { bundlePath: path }) => unpinBase(process.cwd(), path)
 });
 
 // src/commands/validate.ts
-var import_zod31 = require("zod");
+var import_zod32 = require("zod");
 var validateCommand = define({
   name: "validate",
   tool: "kb_validate",
   usage: "validate",
   description: "Check pointers no single record can see: supersession links that disagree between the two records, typed causal links, and assumptions that cite sources. Each finding carries a severity: errors fail the exit code, warnings do not.",
-  input: import_zod31.z.object({ bundlePath }),
+  input: import_zod32.z.object({ bundlePath }),
   fromArgv: (_argv, path) => ({ bundlePath: path }),
   run: async ({ store }, { bundlePath: path }) => validateBundle(await store.list(path)),
   // Warnings never fail the exit code; every other severity does.
@@ -5073,16 +5237,16 @@ var validateCommand = define({
 });
 
 // src/commands/verify.ts
-var import_zod32 = require("zod");
+var import_zod33 = require("zod");
 var verifyCommand = define({
   name: "verify",
   tool: "kb_verify",
   usage: "verify <concept-id> --note <text>",
   description: "Append a verified[] event: who checked, when, and what was found. Append-only. A record's own generator is refused unless the actor is `human:`-prefixed.",
-  input: import_zod32.z.object({
+  input: import_zod33.z.object({
     bundlePath,
     conceptId,
-    note: import_zod32.z.string().refine((s) => s.trim().length > 0, {
+    note: import_zod33.z.string().refine((s) => s.trim().length > 0, {
       message: "note must say what the check found"
     })
   }),
@@ -5102,15 +5266,15 @@ var verifyCommand = define({
 });
 
 // src/commands/write.ts
-var import_zod33 = require("zod");
+var import_zod34 = require("zod");
 var writeCommand = define({
   name: "write",
   tool: "kb_write",
   usage: "write <type> < record.json",
   description: "Write one record. Search first \u2014 a duplicate concept id is rejected, not overwritten; kb_types lists each type's sections. An unsourced claim is an `assumption` with assumption: true, never a vague `fact`. Conflicting records get a `risk`, `open-question`, or superseding `decision`. Prefer a new short record over overloading one. Never delete; supersede.",
-  input: import_zod33.z.object({
+  input: import_zod34.z.object({
     bundlePath,
-    type: import_zod33.z.enum(KB_RECORD_TYPES),
+    type: import_zod34.z.enum(KB_RECORD_TYPES),
     input: composeInputSchema
   }),
   fromArgv: async (argv, path, stdin) => ({
@@ -5134,13 +5298,13 @@ var writeCommand = define({
 });
 
 // src/commands/write-decision.ts
-var import_zod34 = require("zod");
+var import_zod35 = require("zod");
 var writeDecisionCommand = define({
   name: "write-decision",
   tool: "kb_write_decision",
   usage: "write-decision < decision.json",
   description: "Write a decision, with `alternative` (what was rejected and why) and `impact` as fields. Record one when a later reader would otherwise simplify the constraint away; skip when the diff already answers it. `sources` for material read, `anchors` for code, `relatedConceptIds` for records.",
-  input: import_zod34.z.object({ bundlePath, input: decisionInputSchema }),
+  input: import_zod35.z.object({ bundlePath, input: decisionInputSchema }),
   fromArgv: async (_argv, path, stdin) => ({
     bundlePath: path,
     input: JSON.parse(await stdin())
@@ -5180,6 +5344,7 @@ var KB_COMMANDS = [
   listCommand,
   readIndexCommand,
   logCommand,
+  stampCommand,
   validateCommand,
   doctorCommand,
   schemaCommand,
@@ -5199,7 +5364,7 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/version.ts
-var VERSION = true ? "0.1.15" : "0.0.0-dev";
+var VERSION = true ? "0.1.16" : "0.0.0-dev";
 
 // src/mcp.ts
 function createKbMcpServer() {
@@ -5241,7 +5406,11 @@ async function runKbMcpServer() {
 var import_node_path9 = require("path");
 async function runKbCli(argv) {
   const { flags, literal } = takeLiteral(argv);
-  const { bundle, rest: withFlags } = takeBundle(flags);
+  const {
+    bundle,
+    explicit: bundleExplicit,
+    rest: withFlags
+  } = takeBundle(flags);
   const name = withFlags[0] ?? "";
   if (!name || name === "-h" || name === "--help") {
     process.stdout.write(usage());
@@ -5262,7 +5431,7 @@ async function runKbCli(argv) {
     ...json ? withFlags.filter((argument) => argument !== "--json") : withFlags,
     ...literal
   ];
-  const raw = await command.fromArgv(rest, bundle, readStdin);
+  const raw = await command.fromArgv(rest, bundle, readStdin, bundleExplicit);
   const parsed = command.input.safeParse(raw);
   if (!parsed.success) {
     die(
@@ -5284,6 +5453,7 @@ async function runKbCli(argv) {
   if (command.failsWhen?.(result, parsed.data)) process.exitCode = 1;
   if (result === "") return;
   const text = command.render && !json ? command.render(result) : typeof result === "string" ? result : JSON.stringify(result, null, 2);
+  if (text === "") return;
   process.stdout.write(text.endsWith("\n") ? text : `${text}
 `);
 }
@@ -5295,11 +5465,15 @@ function takeLiteral(argv) {
 function takeBundle(argv) {
   const at = argv.indexOf("--bundle");
   if (at === -1) {
-    return { bundle: (0, import_node_path9.join)(process.cwd(), KB_DIR), rest: argv };
+    return { bundle: (0, import_node_path9.join)(process.cwd(), KB_DIR), explicit: false, rest: argv };
   }
   const bundle = argv[at + 1];
   if (!bundle) die("--bundle requires a path");
-  return { bundle, rest: [...argv.slice(0, at), ...argv.slice(at + 2)] };
+  return {
+    bundle,
+    explicit: true,
+    rest: [...argv.slice(0, at), ...argv.slice(at + 2)]
+  };
 }
 function readStdin() {
   return new Promise((resolve6, reject) => {