@saasontools/strauss-kb 0.1.7 → 0.1.8

package/README.md

@@ -224,6 +224,8 @@ strauss-kb [--bundle PATH] <command> [args]
   index                                    The index, rebuilt if it disagrees with the records.
   log                                      What touched what, and when.
   validate                                 Cross-record checks. Exits 1 when it reports a problem.
+  doctor [--expiring-days N] [--unverified-days N] [--aging-days N] [--strict]
+                                           Health sweep: what expired, went unconfirmed, aged, or was orphaned.
   schema                                   JSON Schema for the format.
   types                                    The twelve types, their sections and initial status.
   pin [bundle-path] [flags]                Pin a base. --mode, --profiles, --frozen; --local/--user pick the layer.
@@ -233,14 +235,20 @@ strauss-kb [--bundle PATH] <command> [args]
   sync-instructions <file>                 Plant the context block between sentinels in an instruction file.
 
   --bundle PATH  defaults to ./.strauss/kb
+  --json         the machine shape, where a command prints a table
+  --             everything after it is text, not flags
   STRAUSS_KB_ACTOR names the writer in the log
 ```
 
 Results go to stdout as JSON — `index` and `pack` are markdown, which is what
-they are. Errors
-go to stderr and exit 1. `validate` is the one command whose exit code is not
-just "did it run": a check that reports a problem succeeded as a command and
-failed as a check, so it exits 1 with its findings on stdout.
+they are, and `doctor` prints a table unless `--json` asks for the object
+behind it. `--json` is refused rather than ignored on the commands that have
+only one form, since a flag that quietly does nothing reads as one that
+worked; `--` ends flag parsing, for the verbs that end in free prose. Errors
+go to stderr and exit 1. `validate` and `doctor --strict` are the commands
+whose exit code is not just "did it run": a check that reports a problem
+succeeded as a command and failed as a check, so it exits 1 with its findings
+on stdout.
 
 ```bash
 strauss-kb --bundle .strauss/kb write fact <<'JSON'
@@ -262,7 +270,8 @@ strauss-kb validate || echo "problems above"
 `strauss-kb-mcp` speaks stdio and takes no API key and no required environment.
 Every CLI verb is a tool: `kb_write`, `kb_write_decision`, `kb_no_decision`,
 `kb_status`, `kb_supersede`, `kb_answer`, `kb_verify`, `kb_load`, `kb_pack`, `kb_query`,
-`kb_trace`, `kb_list`, `kb_index`, `kb_log`, `kb_validate`, `kb_schema`, `kb_types`,
+`kb_trace`, `kb_list`, `kb_index`, `kb_log`, `kb_validate`, `kb_doctor`,
+`kb_schema`, `kb_types`,
 `kb_pin`, `kb_unpin`, `kb_pins`, `kb_context`. Most tools take a `bundlePath`;
 `kb_schema` and `kb_types` describe the format rather than any one base, and
 `kb_pins` and `kb_context` read the workspace pin manifests instead. The one
@@ -401,6 +410,83 @@ fact; a missing replacement is `broken-chain` with no head — the case that nee
 the most care, because returning the stale record unmarked looks exactly like
 success.
 
+## Health
+
+`doctor` sweeps a whole base and reports what has decayed. It is read-only —
+nothing is re-dated, re-verified, superseded, or deleted — because every
+finding is a judgment somebody has to make: whether a claim still holds, which
+question is worth answering, which island to link or drop.
+
+It exists because decay is invisible from inside a single record. A stale
+record reads exactly like a live one, a question nobody answered reads exactly
+like one nobody asked, and a record nothing links to is reachable only by
+someone who already knows it is there. `validate` is the narrower neighbour:
+it asks only whether pointers between records agree.
+
+| Check                  | Reports                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| `expired`              | `stale_after` is in the past — or is not a readable date, which is no better.  |
+| `expiring`             | `stale_after` falls inside the next `--expiring-days` (30).                    |
+| `unverified`           | `verified[]` is empty and the record is over `--unverified-days` (90) old.     |
+| `aging`                | Still `open` or `proposed` after `--aging-days` (90).                          |
+| `orphaned`             | No other record links to it, by body link or supersession.                     |
+| `broken-supersession`  | A chain that does not resolve: no replacement, a missing one, a cycle, a fork. |
+| `superseded-but-cited` | A record that still holds, whose body links to one that does not.              |
+
+The last check's name is for its common case: a rejected target counts too, and
+is the worse half — a superseded record at least names its replacement, while a
+rejected one is a well-formed assertion of what someone decided _not_ to do,
+cited by a record the reader trusts.
+
+```bash
+strauss-kb doctor                       # the table
+strauss-kb doctor --json                # the object behind it
+strauss-kb doctor --strict              # exit 1 if anything has expired
+strauss-kb doctor --unverified-days 30  # a stricter confirmation window
+```
+
+All seven groups are reported even when empty. A check that found nothing and
+a check that never ran look identical in a report that only lists findings,
+which is the whole value of a sweep.
+
+Judgments the checks make, worth knowing before reading a report:
+
+- **Superseded and rejected records sit out the freshness checks.** A replaced
+  record whose date has passed needs no repair, and reporting it would bury the
+  records that do. They stay in the graph checks, where standing is not the
+  question.
+- **A date-only `stale_after` expires at UTC midnight.** `2026-09-01` parses as
+  `2026-09-01T00:00:00Z`, so a record goes stale at the start of its date: a
+  sweep run at exactly that instant still calls it expiring, and one a minute
+  later calls it expired. That is `adjudicate`'s comparison rather than a
+  second one — two readings of the same field disagreeing about the day would
+  be worse than either.
+- **Age is read from `generated.at`, exclusively.** A record carrying no
+  timestamp is not reported as aging or unverified — without a start there is
+  no duration, and inventing one would flag every foreign record as overdue
+  (adjudication still warns `unverified` on it at read time). Exactly N days
+  old is not yet "older than N".
+- **`orphaned` counts incoming links only, and reads supersession one way.** A
+  record that cites five others and is cited by none is precisely the island:
+  reachable if you already know it exists. The replacement references what it
+  replaced, never the reverse — taken symmetrically, a dead record would vouch
+  for its own replacement and an old→new pair nothing else touches would rescue
+  itself. Shared anchors and shared sources are co-location rather than
+  reference, so they do not rescue a record either.
+- **A record citing the one it replaced is not superseded-but-cited.** That
+  link is the history working as designed, and reporting it would put a finding
+  on every correctly performed supersession.
+- **A replacement pointer is checked whatever the status says.** The store
+  writes `strauss_status` and `strauss_superseded_by` in one mutation, so a
+  record left `accepted` while naming a replacement was hand-edited — and
+  adjudication reads it as current no matter what the pointer says, which is
+  what makes it worth naming.
+
+`--strict` gates on expiry alone. The other six report debt a reader decides
+about; an expired record is the base itself saying it would stop standing
+behind something, which is the one finding a pipeline can act on without a
+judgment call.
+
 ## Living in an agent session
 
 Long sessions lose a knowledge base twice over: attention decays, and

package/dist/{chunk-GKCG4P3L.js → chunk-MGPYUZOM.js}

@@ -4,13 +4,14 @@ import {
   KB_DIR,
   KbStore,
   VERSION
-} from "./chunk-GKUQOJEK.js";
+} from "./chunk-YJK7KGHN.js";
 
 // src/cli.ts
 import { join } from "path";
 async function runKbCli(argv) {
-  const { bundle, rest } = takeBundle(argv);
-  const name = rest[0] ?? "";
+  const { flags, literal } = takeLiteral(argv);
+  const { bundle, rest: withFlags } = takeBundle(flags);
+  const name = withFlags[0] ?? "";
   if (!name || name === "-h" || name === "--help") {
     process.stdout.write(usage());
     return;
@@ -22,6 +23,14 @@ async function runKbCli(argv) {
   }
   const command = KB_COMMANDS_BY_NAME.get(name);
   if (!command) die(`unknown command ${name}`);
+  const json = withFlags.includes("--json");
+  if (json && !command.render) {
+    die(`${name} takes no --json: its result is already the machine shape`);
+  }
+  const rest = [
+    ...json ? withFlags.filter((argument) => argument !== "--json") : withFlags,
+    ...literal
+  ];
   const raw = await command.fromArgv(rest, bundle, readStdin);
   const parsed = command.input.safeParse(raw);
   if (!parsed.success) {
@@ -41,13 +50,16 @@ async function runKbCli(argv) {
     },
     parsed.data
   );
-  if (command.failsWhen?.(result)) process.exitCode = 1;
+  if (command.failsWhen?.(result, parsed.data)) process.exitCode = 1;
   if (result === "") return;
-  process.stdout.write(
-    typeof result === "string" ? result.endsWith("\n") ? result : `${result}
-` : `${JSON.stringify(result, null, 2)}
-`
-  );
+  const text = command.render && !json ? command.render(result) : typeof result === "string" ? result : JSON.stringify(result, null, 2);
+  process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+}
+function takeLiteral(argv) {
+  const at = argv.indexOf("--");
+  if (at === -1) return { flags: argv, literal: [] };
+  return { flags: argv.slice(0, at), literal: argv.slice(at + 1) };
 }
 function takeBundle(argv) {
   const at = argv.indexOf("--bundle");
@@ -89,6 +101,8 @@ function usage() {
     ),
     "",
     `  --bundle PATH  defaults to ./${KB_DIR}`,
+    "  --json         the machine shape, where a command prints a table",
+    "  --             everything after it is text, not flags",
     "  --version      the installed package version",
     "  STRAUSS_KB_ACTOR names the writer in the log",
     ""
@@ -98,4 +112,4 @@ function usage() {
 export {
   runKbCli
 };
-//# sourceMappingURL=chunk-GKCG4P3L.js.map
+//# sourceMappingURL=chunk-MGPYUZOM.js.map

package/dist/chunk-MGPYUZOM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["/**\n * strauss-kb — a knowledge base's command line.\n *\n * A dispatcher over `KB_COMMANDS`, which the MCP server also projects. Nothing\n * command-specific lives here beyond turning argv into the object both\n * surfaces pass.\n */\nimport { join } from \"node:path\";\nimport { KB_COMMANDS, KB_COMMANDS_BY_NAME } from \"./commands/index.js\";\nimport { KB_DIR, KbStore } from \"./kb-store.js\";\nimport { VERSION } from \"./version.js\";\n\nexport async function runKbCli(argv: string[]): Promise<void> {\n  const { flags, literal } = takeLiteral(argv);\n  const { bundle, rest: withFlags } = takeBundle(flags);\n  const name = withFlags[0] ?? \"\";\n\n  if (!name || name === \"-h\" || name === \"--help\") {\n    process.stdout.write(usage());\n    return;\n  }\n\n  // The plugin in front of this CLI updates from a marketplace while the CLI\n  // updates from npm, and neither prompts for the other. Answering \"which one\n  // is installed\" is what makes that skew diagnosable instead of mysterious.\n  if (name === \"--version\" || name === \"-v\") {\n    process.stdout.write(`${VERSION}\\n`);\n    return;\n  }\n\n  const command = KB_COMMANDS_BY_NAME.get(name);\n  if (!command) die(`unknown command ${name}`);\n\n  // Output shape, not an argument: stripped before the command sees argv, so a\n  // positional adapter never has to know the flag exists. Refused rather than\n  // ignored where a command has only one form — a flag that silently does\n  // nothing teaches a caller that it worked.\n  const json = withFlags.includes(\"--json\");\n  if (json && !command.render) {\n    die(`${name} takes no --json: its result is already the machine shape`);\n  }\n  const rest = [\n    ...(json\n      ? withFlags.filter((argument) => argument !== \"--json\")\n      : withFlags),\n    ...literal,\n  ];\n\n  const raw = await command.fromArgv(rest, bundle, readStdin);\n  const parsed = command.input.safeParse(raw);\n  if (!parsed.success) {\n    die(\n      `${name}: ${parsed.error.issues\n        .map((issue) => `${issue.path.join(\".\") || \"(root)\"}: ${issue.message}`)\n        .join(\"; \")}`,\n    );\n  }\n\n  const store = new KbStore({\n    warn: (entry) => process.stderr.write(`${JSON.stringify(entry)}\\n`),\n  });\n  const result = await command.run(\n    {\n      store,\n      actor: process.env.STRAUSS_KB_ACTOR ?? \"unknown\",\n      now: () => new Date().toISOString(),\n    },\n    parsed.data,\n  );\n\n  // A check reporting a problem succeeded as a command and failed as a check;\n  // the command says which, rather than the dispatcher knowing their names.\n  if (command.failsWhen?.(result, parsed.data)) process.exitCode = 1;\n  // An empty string is deliberate silence — `context` with nothing pinned\n  // runs from hooks at every session start, and even a bare newline is noise\n  // injected into a fresh context.\n  if (result === \"\") return;\n  const text =\n    command.render && !json\n      ? command.render(result)\n      : typeof result === \"string\"\n        ? result\n        : JSON.stringify(result, null, 2);\n  process.stdout.write(text.endsWith(\"\\n\") ? text : `${text}\\n`);\n}\n\n/**\n * Everything after a bare `--` is text, never flags.\n *\n * Several verbs end in free prose — `no-decision`, `answer`, `query` — and a\n * reason that happens to contain `--json` or `--bundle` would otherwise lose a\n * word to the flag scan, or two. The sentinel is the usual escape, and the\n * token itself is dropped while the order of everything else is kept, so the\n * positional adapters still index the same way.\n */\nfunction takeLiteral(argv: string[]): { flags: string[]; literal: string[] } {\n  const at = argv.indexOf(\"--\");\n  if (at === -1) return { flags: argv, literal: [] };\n  return { flags: argv.slice(0, at), literal: argv.slice(at + 1) };\n}\n\n/**\n * `--bundle` addresses a base directly; without it the command works on the\n * one under the current directory. A base belongs to whatever prompted it, so\n * the default cannot be the only option.\n */\nfunction takeBundle(argv: string[]): { bundle: string; rest: string[] } {\n  const at = argv.indexOf(\"--bundle\");\n  if (at === -1) {\n    return { bundle: join(process.cwd(), KB_DIR), rest: argv };\n  }\n  const bundle = argv[at + 1];\n  if (!bundle) die(\"--bundle requires a path\");\n  return { bundle, rest: [...argv.slice(0, at), ...argv.slice(at + 2)] };\n}\n\nfunction readStdin(): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let text = \"\";\n    process.stdin.setEncoding(\"utf8\");\n    process.stdin.on(\"data\", (chunk) => (text += chunk));\n    process.stdin.on(\"end\", () => resolve(text));\n    process.stdin.on(\"error\", reject);\n  });\n}\n\nfunction die(message: string): never {\n  process.stderr.write(`strauss-kb: error: ${message}\\n`);\n  process.exit(1);\n}\n\n/** First sentence, capped — the full text is what an MCP client shows. */\nfunction summarise(description: string): string {\n  const first = description.split(\"\\n\")[0] ?? \"\";\n  const sentence = first.includes(\". \")\n    ? `${first.slice(0, first.indexOf(\". \"))}.`\n    : first;\n  return sentence.length > 78 ? `${sentence.slice(0, 75)}…` : sentence;\n}\n\nfunction usage(): string {\n  const width = Math.max(...KB_COMMANDS.map((command) => command.usage.length));\n  return [\n    \"strauss-kb — knowledge base commands\",\n    \"\",\n    \"Usage: strauss-kb [--bundle PATH] <command> [args]\",\n    \"\",\n    ...KB_COMMANDS.map(\n      (command) =>\n        `  ${command.usage.padEnd(width)}  ${summarise(command.description)}`,\n    ),\n    \"\",\n    `  --bundle PATH  defaults to ./${KB_DIR}`,\n    \"  --json         the machine shape, where a command prints a table\",\n    \"  --             everything after it is text, not flags\",\n    \"  --version      the installed package version\",\n    \"  STRAUSS_KB_ACTOR names the writer in the log\",\n    \"\",\n  ].join(\"\\n\");\n}\n"],"mappings":"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","names":[]}