@saasontools/strauss-kb 0.1.18 → 0.1.19

package/dist/cli-main.js

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

package/dist/index.cjs

@@ -123,6 +123,7 @@ __export(index_exports, {
   listPins: () => listPins,
   loadQmd: () => loadQmd,
   matchToDiff: () => matchToDiff,
+  matchesTags: () => matchesTags,
   mergedContextBudgets: () => mergedContextBudgets,
   neighbours: () => neighbours,
   pack: () => pack,
@@ -2733,6 +2734,13 @@ function typeRank(record) {
   return index2 === -1 ? TYPE_PRIORITY.length : index2;
 }
 
+// src/kb-tags.ts
+function matchesTags(record, filter) {
+  if (!filter.tags?.length && !filter.excludeTags?.length) return true;
+  const carried = new Set(record.frontmatter.tags ?? []);
+  return (filter.tags ?? []).every((tag) => carried.has(tag)) && !(filter.excludeTags ?? []).some((tag) => carried.has(tag));
+}
+
 // src/catalog.ts
 var EMPTY_STANDINGS = {
   current: 0,
@@ -2743,7 +2751,7 @@ var EMPTY_STANDINGS = {
 };
 function catalog(bundle, options = {}) {
   const wanted = options.type ? bundle.filter((record) => record.frontmatter.type === options.type) : bundle;
-  const entries = adjudicate(wanted, bundle, options.now ?? /* @__PURE__ */ new Date()).map((hit) => ({
+  const entries = adjudicate(wanted, bundle, options.now ?? /* @__PURE__ */ new Date()).filter((hit) => matchesTags(hit.record, options)).map((hit) => ({
     conceptId: hit.record.conceptId,
     type: hit.record.frontmatter.type,
     title: hit.record.frontmatter.title ?? null,
@@ -3016,13 +3024,16 @@ var KbStore = class {
     return this.parse(conceptId2, raw);
   }
   /**
-   * Every record in the bundle, optionally narrowed to one type.
+   * Every record in the bundle, optionally narrowed to one type and to the
+   * records carrying every tag in `filter.tags`. Selection only — `excludeTags`
+   * is not taken here, because `query`, `catalog` and `load` read through this
+   * and must adjudicate over the whole base.
    *
    * A file that fails to parse is skipped and logged rather than thrown: one
    * malformed record — hand-edited, or written by a producer we don't know —
    * must not make the whole bundle unreadable.
    */
-  async list(bundlePath2, type) {
+  async list(bundlePath2, type, filter = {}) {
     const root = this.root(bundlePath2);
     let names;
     try {
@@ -3036,7 +3047,9 @@ var KbStore = class {
       DEFAULT_IO_CONCURRENCY,
       async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await (0, import_promises6.readFile)((0, import_node_path7.join)(root, name), "utf8"))
     );
-    return records.filter((record) => record !== null);
+    return records.filter(
+      (record) => record !== null && matchesTags(record, filter)
+    );
   }
   /**
    * Moves a record's status, preserving everything else.
@@ -3176,9 +3189,10 @@ ${answer}
       /* @__PURE__ */ new Date(),
       await this.detectDrift(narrowed, options.repoRoot)
     );
-    if (options.includeNonCurrent) return adjudicated;
-    const present = new Set(adjudicated.map((hit) => hit.record.conceptId));
-    return adjudicated.filter(
+    const kept = adjudicated.filter((hit) => matchesTags(hit.record, options));
+    if (options.includeNonCurrent) return kept;
+    const present = new Set(kept.map((hit) => hit.record.conceptId));
+    return kept.filter(
       (hit) => hit.standing !== "superseded" || !hit.heads.some((head) => present.has(head.conceptId))
     );
   }
@@ -3281,14 +3295,17 @@ ${answer}
       /* @__PURE__ */ new Date(),
       await this.detectDrift(wanted, options.repoRoot)
     );
-    const records = adjudicated.filter((hit) => hit.standing !== "superseded");
-    const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(stub);
+    const kept = adjudicated.filter(
+      (hit) => matchesTags(hit.record, { excludeTags: options.excludeTags })
+    );
+    const records = kept.filter((hit) => hit.standing !== "superseded");
+    const superseded = kept.filter((hit) => hit.standing === "superseded").map(stub);
     const approxTokens2 = records.reduce((total, hit) => total + estimateTokens(hit.record), 0) + superseded.reduce((total, entry) => total + estimateStubTokens(entry), 0);
     const bundleDigestValue = bundleDigest(records, superseded);
     if (!options.all && approxTokens2 > budgetTokens) {
       return {
         loaded: false,
-        recordCount: wanted.length,
+        recordCount: kept.length,
         approxTokens: approxTokens2,
         budgetTokens,
         message: refusalMessage({
@@ -3301,7 +3318,7 @@ ${answer}
     }
     return {
       loaded: true,
-      recordCount: wanted.length,
+      recordCount: kept.length,
       tokensLoaded: approxTokens2,
       budgetTokens: options.all ? null : budgetTokens,
       records,
@@ -3788,14 +3805,17 @@ function asBudgets(value) {
   if (value === null || typeof value !== "object") return {};
   const table2 = value;
   const pick = (key2, min) => {
-    const raw = table2[key2];
-    return typeof raw === "number" && Number.isInteger(raw) && raw >= min ? raw : void 0;
+    const raw2 = table2[key2];
+    return typeof raw2 === "number" && Number.isInteger(raw2) && raw2 >= min ? raw2 : void 0;
   };
   const budgetTokens = pick("budgetTokens", 1);
   const fullUnderTokens = pick("fullUnderTokens", 0);
+  const raw = table2["excludeTags"];
+  const excludeTags = Array.isArray(raw) ? raw.filter((tag) => typeof tag === "string" && tag !== "") : void 0;
   return {
     ...budgetTokens ? { budgetTokens } : {},
-    ...fullUnderTokens !== void 0 ? { fullUnderTokens } : {}
+    ...fullUnderTokens !== void 0 ? { fullUnderTokens } : {},
+    ...excludeTags ? { excludeTags } : {}
   };
 }
 function contextProfileBudgets(manifest, profile) {
@@ -4111,7 +4131,7 @@ function preamble() {
     "tokens."
   ].join("\n");
 }
-async function renderBase(store, path, absolutePath, fullUnderTokens, pinMode, budgetTokens) {
+async function renderBase(store, path, absolutePath, fullUnderTokens, pinMode, budgetTokens, excludeTags) {
   const bundle = await store.list(absolutePath);
   if (bundle.length === 0) {
     return {
@@ -4125,7 +4145,8 @@ async function renderBase(store, path, absolutePath, fullUnderTokens, pinMode, b
   let degradedFrom;
   if (fullCap > 0) {
     const full = await store.load(absolutePath, {
-      budgetTokens: fullCap
+      budgetTokens: fullCap,
+      excludeTags
     });
     if (!full.loaded && pinMode === "full") {
       degradedFrom = { approxTokens: full.approxTokens };
@@ -4155,7 +4176,9 @@ async function renderBase(store, path, absolutePath, fullUnderTokens, pinMode, b
       };
     }
   }
-  const adjudicated = adjudicate(bundle, bundle);
+  const adjudicated = adjudicate(bundle, bundle).filter(
+    (hit) => matchesTags(hit.record, { excludeTags })
+  );
   const lines = adjudicated.filter((hit) => hit.standing !== "superseded").map((hit) => renderIndexLine(hit.record));
   const superseded = adjudicated.filter((hit) => hit.standing === "superseded").map(
     (hit) => `- \`${hit.record.conceptId}\` \u2192 superseded by ${hit.heads.map((head) => `\`${head.conceptId}\``).join(", ") || "(missing replacement)"}`
@@ -4176,6 +4199,7 @@ async function buildContext(store, workspaceDir, options = {}) {
   const fromManifest = mergedContextBudgets(merged, options.profile);
   budgetTokens = options.budgetTokens ?? fromManifest.budgetTokens ?? builtin.budgetTokens ?? DEFAULT_CONTEXT_BUDGET;
   fullUnderTokens = options.fullUnderTokens ?? fromManifest.fullUnderTokens ?? builtin.fullUnderTokens ?? 0;
+  const excludeTags = options.excludeTags ?? fromManifest.excludeTags ?? builtin.excludeTags ?? [];
   const pins = merged.pins.filter(
     (pin) => !pin.profiles?.length || !options.profile || pin.profiles.includes(options.profile)
   );
@@ -4196,7 +4220,8 @@ async function buildContext(store, workspaceDir, options = {}) {
         pin.absolutePath,
         fullUnderTokens,
         pin.mode,
-        budgetTokens
+        budgetTokens,
+        excludeTags
       ),
       frozen: pin.frozen === true
     }))
@@ -4857,6 +4882,9 @@ var import_zod9 = require("zod");
 var import_zod8 = require("zod");
 var bundlePath = import_zod8.z.string().min(1).describe("Absolute path to the knowledge base directory.");
 var conceptId = import_zod8.z.string().min(1).describe("e.g. decision.cursor-v2");
+var TAGS = import_zod8.z.array(import_zod8.z.string().min(1)).optional().describe(
+  "Keep only records carrying every one of these frontmatter tags. Matched exactly."
+);
 var REPO_ROOT = import_zod8.z.string().min(1).optional().describe(
   "Where the anchored source lives, for the drift check. Defaults to the working directory."
 );
@@ -4878,6 +4906,41 @@ function argvFlag(argv, name) {
   }
   return value;
 }
+function argvFlags(argv, name) {
+  const values = [];
+  for (const [at2, arg] of argv.entries()) {
+    if (arg.startsWith(`${name}=`)) {
+      const value = arg.slice(name.length + 1);
+      if (!value) throw new KbMissingFlagValueError(name);
+      values.push(value);
+    } else if (arg === name) {
+      const value = argv[at2 + 1];
+      if (value === void 0 || value.startsWith("--")) {
+        throw new KbMissingFlagValueError(name);
+      }
+      values.push(value);
+    }
+  }
+  return values;
+}
+function argvWithout(argv, ...names) {
+  const kept = [];
+  for (let at2 = 0; at2 < argv.length; at2 += 1) {
+    const arg = argv[at2];
+    if (names.some((name) => arg.startsWith(`${name}=`))) continue;
+    if (names.includes(arg)) {
+      at2 += 1;
+      continue;
+    }
+    kept.push(arg);
+  }
+  return kept;
+}
+function argvPositional(argv, ...names) {
+  return argvWithout(argv.slice(1), ...names).find(
+    (arg) => !arg.startsWith("--")
+  );
+}
 
 // src/commands/anchor-resolve.ts
 function resolverSummary(results) {
@@ -5194,25 +5257,39 @@ var import_zod12 = require("zod");
 var catalogCommand = define({
   name: "catalog",
   tool: "kb_catalog",
-  usage: "catalog [type]",
+  usage: "catalog [type] [--tag T]...",
   description: "Lists every record as one line \u2014 concept id, type, title, standing, and a stale flag \u2014 at roughly thirty tokens each. Pick this over kb_load once kb_load refuses: kb_catalog never refuses. Superseded records show only their replacement; fetch bodies with kb_load, kb_pack, kb_query, or kb_trace.",
   input: import_zod12.z.object({
     bundlePath,
-    type: import_zod12.z.enum(KB_RECORD_TYPES).optional()
-  }),
-  fromArgv: (argv, path) => ({
-    bundlePath: path,
-    ...argv[1] && !argv[1].startsWith("--") ? { type: argv[1] } : {}
+    type: import_zod12.z.enum(KB_RECORD_TYPES).optional(),
+    tags: TAGS
   }),
-  run: async ({ store }, { bundlePath: path, type }) => render(
-    await store.catalog(path, { ...type ? { type } : {} }),
+  fromArgv: (argv, path) => {
+    const tags = argvFlags(argv, "--tag");
+    const type = argvPositional(argv, "--tag");
+    return {
+      bundlePath: path,
+      ...type ? { type } : {},
+      ...tags.length ? { tags } : {}
+    };
+  },
+  run: async ({ store }, { bundlePath: path, type, tags }) => render(
+    await store.catalog(path, {
+      ...type ? { type } : {},
+      ...tags ? { tags } : {}
+    }),
     path,
-    type
+    type,
+    tags
   )
 });
-function render(result, bundle, type) {
+function render(result, bundle, type, tags) {
+  const narrowed = [
+    ...type ? [type] : [],
+    ...tags?.length ? [`tags: ${tags.join(", ")}`] : []
+  ].join(" \xB7 ");
   const lines = [
-    `# KB Catalog${type ? ` \u2014 ${type}` : ""}`,
+    `# KB Catalog${narrowed ? ` \u2014 ${narrowed}` : ""}`,
     `bundle: ${bundle}`,
     `${count(result.recordCount, "record")}: ${standingCounts(result)}`
   ];
@@ -5224,7 +5301,7 @@ function render(result, bundle, type) {
   lines.push("");
   if (!result.entries.length) {
     lines.push(
-      type ? `(no records of type ${type})` : "(no records \u2014 this base is empty)"
+      narrowed ? `(no records matching ${narrowed})` : "(no records \u2014 this base is empty)"
     );
   } else {
     for (const entry of result.entries) lines.push(renderCatalogLine(entry));
@@ -5257,7 +5334,7 @@ var import_zod13 = require("zod");
 var contextCommand = define({
   name: "context",
   tool: "kb_context",
-  usage: "context [--profile NAME] [--budget N] [--full-under N] [--format json] [--event NAME]",
+  usage: "context [--profile NAME] [--budget N] [--full-under N] [--exclude-tag T]... [--format json] [--event NAME]",
   description: "Index block of pinned bases (ids, titles, standing) for injection at context birth. Takes no bundlePath \u2014 reads the workspace pin manifests. Empty when nothing is pinned; refuses over budget rather than truncating. Budget precedence: flags, then the manifest `context[profile]` over `context.default`, then the built-in profile, then package defaults.",
   input: import_zod13.z.object({
     budgetTokens: import_zod13.z.number().int().positive().optional().describe(
@@ -5269,6 +5346,9 @@ var contextCommand = define({
     profile: import_zod13.z.string().optional().describe(
       "Named budget set: built-ins are session-start (full-under 1500), compact and turn (budget 2500); the manifests' `context` tables override per repo. Unknown names fall through to defaults rather than failing."
     ),
+    excludeTags: import_zod13.z.array(import_zod13.z.string().min(1)).optional().describe(
+      "Frontmatter tags whose records stay out of the block. The base stays pinned and stays readable by tool; resolved like the budgets."
+    ),
     format: import_zod13.z.enum(["markdown", "json"]).optional().describe(
       "CLI envelope for hook protocols that require strict JSON on stdout. MCP callers omit this \u2014 the block itself is identical."
     ),
@@ -5282,19 +5362,22 @@ var contextCommand = define({
     const profile = argvFlag(argv, "--profile");
     const format = argvFlag(argv, "--format");
     const event = argvFlag(argv, "--event");
+    const excludeTags = argvFlags(argv, "--exclude-tag");
     return {
       ...budget ? { budgetTokens: Number(budget) } : {},
       ...fullUnder ? { fullUnderTokens: Number(fullUnder) } : {},
       ...profile ? { profile } : {},
+      ...excludeTags.length ? { excludeTags } : {},
       ...format ? { format } : {},
       ...event ? { event } : {}
     };
   },
-  run: async ({ store }, { budgetTokens, fullUnderTokens, profile, format, event }) => {
+  run: async ({ store }, { budgetTokens, fullUnderTokens, profile, excludeTags, format, event }) => {
     const result = await buildContext(store, process.cwd(), {
       ...budgetTokens ? { budgetTokens } : {},
       ...fullUnderTokens ? { fullUnderTokens } : {},
       ...profile ? { profile } : {},
+      ...excludeTags ? { excludeTags } : {},
       // Degradations — a full pin that could not fit, a refused block — go
       // to stderr as well as into the block itself: stderr is diagnostics on
       // both surfaces (hooks discard it, MCP logs it), so an operator can
@@ -6095,17 +6178,31 @@ var import_zod17 = require("zod");
 var listCommand = define({
   name: "list",
   tool: "kb_list",
-  usage: "list [type]",
-  description: "Every record, optionally one type. For enumerating; use kb_query for a question.",
-  input: import_zod17.z.object({ bundlePath, type: import_zod17.z.enum(KB_RECORD_TYPES).optional() }),
-  fromArgv: (argv, path) => ({ bundlePath: path, type: argv[1] }),
-  run: async ({ store }, { bundlePath: path, type }) => (await store.list(path, type)).map((record) => ({
-    conceptId: record.conceptId,
-    title: record.frontmatter.title ?? null,
-    description: record.frontmatter.description ?? null,
-    status: record.frontmatter.strauss_status,
-    anchors: record.frontmatter.strauss_anchors ?? []
-  }))
+  usage: "list [type] [--tag T]...",
+  description: "Every record, optionally one type or tag. For enumerating; use kb_query for a question.",
+  input: import_zod17.z.object({
+    bundlePath,
+    type: import_zod17.z.enum(KB_RECORD_TYPES).optional(),
+    tags: TAGS
+  }),
+  fromArgv: (argv, path) => {
+    const tags = argvFlags(argv, "--tag");
+    const type = argvPositional(argv, "--tag");
+    return {
+      bundlePath: path,
+      ...type ? { type } : {},
+      ...tags.length ? { tags } : {}
+    };
+  },
+  run: async ({ store }, { bundlePath: path, type, tags }) => (await store.list(path, type, { ...tags ? { tags } : {} })).map(
+    (record) => ({
+      conceptId: record.conceptId,
+      title: record.frontmatter.title ?? null,
+      description: record.frontmatter.description ?? null,
+      status: record.frontmatter.strauss_status,
+      anchors: record.frontmatter.strauss_anchors ?? []
+    })
+  )
 });
 
 // src/commands/load.ts
@@ -6356,31 +6453,33 @@ var import_zod24 = require("zod");
 var queryCommand = define({
   name: "query",
   tool: "kb_query",
-  usage: "query <text...> [--repo-root PATH]",
+  usage: "query <text...> [--tag T]... [--repo-root PATH]",
   description: "Search; every hit carries its standing. Flagged, never filtered: a superseded hit returns with its replacement, a rejected one is marked. Prefer kb_load when the base fits its budget \u2014 a full read beats search. Results are volatile: place them at the tail, not the cached prefix. Never read record files directly.",
   input: import_zod24.z.object({
     bundlePath,
     text: import_zod24.z.string().optional(),
     type: import_zod24.z.enum(KB_RECORD_TYPES).optional(),
     includeNonCurrent: import_zod24.z.boolean().optional(),
+    tags: TAGS,
     repoRoot: REPO_ROOT
   }),
-  // `--repo-root` is a flag, so its value must not fall into the search text.
+  // Both are flags, so neither's value may fall into the search text.
   fromArgv: (argv, path) => {
     const repoRoot = argvFlag(argv, "--repo-root");
-    const words = argv.slice(1);
-    const flag = words.indexOf("--repo-root");
-    if (flag !== -1) words.splice(flag, 2);
+    const tags = argvFlags(argv, "--tag");
+    const words = argvWithout(argv.slice(1), "--repo-root", "--tag");
     return {
       bundlePath: path,
       text: words.join(" ").trim(),
       includeNonCurrent: true,
+      ...tags.length ? { tags } : {},
       ...repoRoot !== void 0 ? { repoRoot } : {}
     };
   },
-  run: async ({ store }, { bundlePath: path, text, type, includeNonCurrent, repoRoot }) => (await store.query(path, text ?? "", {
+  run: async ({ store }, { bundlePath: path, text, type, includeNonCurrent, tags, repoRoot }) => (await store.query(path, text ?? "", {
     ...type ? { type } : {},
     includeNonCurrent: includeNonCurrent === true,
+    ...tags ? { tags } : {},
     ...repoRoot !== void 0 ? { repoRoot } : {}
   })).map((hit) => ({
     conceptId: hit.record.conceptId,
@@ -6795,7 +6894,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.18" : "0.0.0-dev";
+var VERSION = true ? "0.1.19" : "0.0.0-dev";
 
 // src/mcp.ts
 function createKbMcpServer() {
@@ -7039,6 +7138,7 @@ function usage() {
   listPins,
   loadQmd,
   matchToDiff,
+  matchesTags,
   mergedContextBudgets,
   neighbours,
   pack,