@saasontools/strauss-kb 0.1.18 → 0.1.19

package/dist/{chunk-ROGVYSMV.js → chunk-ZWSCLHG6.js}

@@ -2,7 +2,7 @@ import {
   KB_COMMANDS,
   KbStore,
   VERSION
-} from "./chunk-GSOTMWZZ.js";
+} from "./chunk-MNQNHYWL.js";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -46,4 +46,4 @@ export {
   createKbMcpServer,
   runKbMcpServer
 };
-//# sourceMappingURL=chunk-ROGVYSMV.js.map
+//# sourceMappingURL=chunk-ZWSCLHG6.js.map

package/dist/cli-main.cjs

@@ -2177,14 +2177,17 @@ function asBudgets(value) {
   if (value === null || typeof value !== "object") return {};
   const table2 = value;
   const pick = (key, min) => {
-    const raw = table2[key];
-    return typeof raw === "number" && Number.isInteger(raw) && raw >= min ? raw : void 0;
+    const raw2 = table2[key];
+    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) {
@@ -2471,6 +2474,9 @@ async function unpinBase(workspaceDir, bundlePath2) {
 var import_zod6 = require("zod");
 var bundlePath = import_zod6.z.string().min(1).describe("Absolute path to the knowledge base directory.");
 var conceptId = import_zod6.z.string().min(1).describe("e.g. decision.cursor-v2");
+var TAGS = import_zod6.z.array(import_zod6.z.string().min(1)).optional().describe(
+  "Keep only records carrying every one of these frontmatter tags. Matched exactly."
+);
 var REPO_ROOT = import_zod6.z.string().min(1).optional().describe(
   "Where the anchored source lives, for the drift check. Defaults to the working directory."
 );
@@ -2492,6 +2498,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) {
@@ -2924,6 +2965,13 @@ function successors(record, byId) {
   return { records, missing: missing2 };
 }
 
+// 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,
@@ -2934,7 +2982,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,
@@ -2974,25 +3022,39 @@ function renderCatalogLine(entry) {
 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_zod10.z.object({
     bundlePath,
-    type: import_zod10.z.enum(KB_RECORD_TYPES).optional()
-  }),
-  fromArgv: (argv, path) => ({
-    bundlePath: path,
-    ...argv[1] && !argv[1].startsWith("--") ? { type: argv[1] } : {}
+    type: import_zod10.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)}`
   ];
@@ -3004,7 +3066,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));
@@ -3091,7 +3153,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 {
@@ -3105,7 +3167,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 };
@@ -3135,7 +3198,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)"}`
@@ -3156,6 +3221,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)
   );
@@ -3176,7 +3242,8 @@ async function buildContext(store, workspaceDir, options = {}) {
         pin.absolutePath,
         fullUnderTokens,
         pin.mode,
-        budgetTokens
+        budgetTokens,
+        excludeTags
       ),
       frozen: pin.frozen === true
     }))
@@ -3297,7 +3364,7 @@ ${CONTEXT_END}` : null;
 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_zod11.z.object({
     budgetTokens: import_zod11.z.number().int().positive().optional().describe(
@@ -3309,6 +3376,9 @@ var contextCommand = define({
     profile: import_zod11.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_zod11.z.array(import_zod11.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_zod11.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."
     ),
@@ -3322,19 +3392,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
@@ -4615,17 +4688,31 @@ var import_zod15 = 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_zod15.z.object({ bundlePath, type: import_zod15.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_zod15.z.object({
+    bundlePath,
+    type: import_zod15.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
@@ -4876,31 +4963,33 @@ var import_zod22 = 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_zod22.z.object({
     bundlePath,
     text: import_zod22.z.string().optional(),
     type: import_zod22.z.enum(KB_RECORD_TYPES).optional(),
     includeNonCurrent: import_zod22.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,
@@ -5899,13 +5988,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 {
@@ -5919,7 +6011,9 @@ var KbStore = class {
       DEFAULT_IO_CONCURRENCY,
       async ({ name, conceptId: conceptId2 }) => this.parse(conceptId2, await (0, import_promises10.readFile)((0, import_node_path11.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.
@@ -6059,9 +6153,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))
     );
   }
@@ -6164,14 +6259,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({
@@ -6184,7 +6282,7 @@ ${answer}
     }
     return {
       loaded: true,
-      recordCount: wanted.length,
+      recordCount: kept.length,
       tokensLoaded: approxTokens2,
       budgetTokens: options.all ? null : budgetTokens,
       records,
@@ -6545,7 +6643,7 @@ function normalizeActor(id) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.1.18" : "0.0.0-dev";
+var VERSION = true ? "0.1.19" : "0.0.0-dev";
 
 // src/cli.ts
 async function runKbCli(argv) {