@viloforge/vfkb 0.2.1 → 0.2.2

package/README.md

@@ -97,6 +97,24 @@ these are good tools solving a *different* problem:
 
 ## Install
 
+### From npm
+
+```bash
+npm install -g @viloforge/vfkb
+
+vfkb --version     # prints the installed version
+vfkb init          # wire a repo: .vfkb/ brain + harness hooks
+vfkb-mcp           # the MCP server (stdio)
+```
+
+Published as [`@viloforge/vfkb`](https://www.npmjs.com/package/@viloforge/vfkb) with
+[provenance attestation](https://docs.npmjs.com/generating-provenance-statements) (SLSA v1,
+built on GitHub Actions from this repo). The install path is delivery-proven, not assumed:
+every release's [publish workflow](.github/workflows/publish.yml) ends in a canary job on a
+fresh runner — no checkout, no cache — that installs the just-published version from the real
+registry and content-asserts the CLI, `init` scaffolding, an add/list round-trip, and an MCP
+initialize handshake ([v0.2.1 canary run](https://github.com/vilosource/vfkb/actions/runs/29197631539)).
+
 ### From source
 
 ```bash

package/dist/bundles/vfkb-mcp.mjs

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -10593,7 +10597,6 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
 var ZodBranded = class extends ZodType {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -11098,7 +11101,7 @@ function $constructor(name, initializer3, params) {
   Object.defineProperty(_, "name", { value: name });
   return _;
 }
-var $brand = Symbol("zod_brand");
+var $brand = /* @__PURE__ */ Symbol("zod_brand");
 var $ZodAsyncError = class extends Error {
   constructor() {
     super(`Encountered Promise during synchronous parse. Use .parseAsync() instead.`);
@@ -15527,6 +15530,7 @@ var error5 = () => {
         return `Clau inv\xE0lida a ${issue2.origin}`;
       case "invalid_union":
         return "Entrada inv\xE0lida";
+      // Could also be "Tipus d'unió invàlid" but "Entrada invàlida" is more general
       case "invalid_element":
         return `Element inv\xE0lid a ${issue2.origin}`;
       default:
@@ -20840,8 +20844,8 @@ function yo_default() {
 
 // node_modules/zod/v4/core/registries.js
 var _a2;
-var $output = Symbol("ZodOutput");
-var $input = Symbol("ZodInput");
+var $output = /* @__PURE__ */ Symbol("ZodOutput");
+var $input = /* @__PURE__ */ Symbol("ZodInput");
 var $ZodRegistry = class {
   constructor() {
     this._map = /* @__PURE__ */ new WeakMap();
@@ -21878,7 +21882,7 @@ function _stringbool(Classes, _params) {
     type: "pipe",
     in: stringSchema,
     out: booleanSchema,
-    transform: (input, payload) => {
+    transform: ((input, payload) => {
       let data = input;
       if (params.case !== "sensitive")
         data = data.toLowerCase();
@@ -21897,14 +21901,14 @@ function _stringbool(Classes, _params) {
         });
         return {};
       }
-    },
-    reverseTransform: (input, _payload) => {
+    }),
+    reverseTransform: ((input, _payload) => {
       if (input === true) {
         return truthyArray[0] || "true";
       } else {
         return falsyArray[0] || "false";
       }
-    },
+    }),
     error: params.error
   });
   return codec2;
@@ -22933,10 +22937,10 @@ var ZodMiniType = /* @__PURE__ */ $constructor("ZodMiniType", (inst, def) => {
   inst.with = inst.check;
   inst.clone = (_def, params) => clone(inst, _def, params);
   inst.brand = () => inst;
-  inst.register = (reg, meta3) => {
+  inst.register = ((reg, meta3) => {
     reg.add(inst, meta3);
     return inst;
-  };
+  });
   inst.apply = (fn) => fn(inst);
 });
 var ZodMiniObject = /* @__PURE__ */ $constructor("ZodMiniObject", (inst, def) => {
@@ -26843,11 +26847,13 @@ function assertCompleteRequestPrompt(request) {
   if (request.params.ref.type !== "ref/prompt") {
     throw new TypeError(`Expected CompleteRequestPrompt, but got ${request.params.ref.type}`);
   }
+  void request;
 }
 function assertCompleteRequestResourceTemplate(request) {
   if (request.params.ref.type !== "ref/resource") {
     throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request.params.ref.type}`);
   }
+  void request;
 }
 var CompleteResultSchema = ResultSchema.extend({
   completion: looseObject({
@@ -27000,7 +27006,7 @@ function isTerminal(status) {
 }
 
 // node_modules/zod-to-json-schema/dist/esm/Options.js
-var ignoreOverride = Symbol("Let zodToJsonSchema decide on which parser to use");
+var ignoreOverride = /* @__PURE__ */ Symbol("Let zodToJsonSchema decide on which parser to use");
 var defaultOptions = {
   name: void 0,
   $refStrategy: "root",
@@ -29976,7 +29982,7 @@ var Server = class extends Protocol {
 };
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
-var COMPLETABLE_SYMBOL = Symbol.for("mcp.completable");
+var COMPLETABLE_SYMBOL = /* @__PURE__ */ Symbol.for("mcp.completable");
 function isCompletable(schema) {
   return !!schema && typeof schema === "object" && COMPLETABLE_SYMBOL in schema;
 }
@@ -31934,7 +31940,7 @@ function queryExplained(opts = {}) {
 }
 
 // src/version.ts
-var ENGINE_VERSION = true ? "0.2.1" : ownPackageVersion();
+var ENGINE_VERSION = true ? "0.2.2" : ownPackageVersion();
 
 // src/mcp-server.ts
 var SEARCH_DEFAULT_LIMIT = 25;
@@ -31970,8 +31976,24 @@ function renderNoMatch(d, q) {
     }
   }
 }
-function tags(csv) {
-  return csv ? csv.split(",").map((t) => t.trim()).filter(Boolean) : void 0;
+function tags(csv, label = "tags") {
+  if (csv === void 0) return void 0;
+  const s = csv.trim();
+  if (!s) return void 0;
+  if (s.startsWith("[")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(s);
+    } catch {
+      throw new Error(`${label} received JSON-array-shaped input that does not parse: ${s} \u2014 pass a comma-separated string like "a,b"`);
+    }
+    if (!Array.isArray(parsed)) throw new Error(`${label} received JSON that is not an array: ${s}`);
+    if (!parsed.every((t) => typeof t === "string")) {
+      throw new Error(`${label} JSON array must contain only strings: ${s}`);
+    }
+    return parsed.map((t) => t.trim()).filter(Boolean);
+  }
+  return s.split(",").map((t) => t.trim()).filter(Boolean);
 }
 function envRole() {
   const p = ROLE2.safeParse(process.env.VFKB_ROLE);
@@ -32062,7 +32084,7 @@ server.registerTool(
       type: ENTRY_TYPE,
       text: external_exports.string(),
       why: external_exports.string().optional().describe('rationale; stored structurally AND folded into the text as a "Why: \u2026" line (esp. for decisions)'),
-      tags: external_exports.string().optional().describe("comma-separated"),
+      tags: external_exports.string().optional().describe('comma-separated (a tag itself cannot start with "[")'),
       path: external_exports.string().optional().describe(
         'link target (path or URL) for type=link \u2014 folded into the text as "<text> \u2192 <path>" (link entries have no structural target field); rejected for other types'
       ),
@@ -32084,7 +32106,7 @@ server.registerTool(
       role: envRole() ?? a.role ?? "executor",
       why: a.why,
       tags: tags(a.tags),
-      contradicts: tags(a.contradicts),
+      contradicts: tags(a.contradicts, "contradicts"),
       status: a.status,
       constitutional: a.constitutional
     });
@@ -32099,11 +32121,14 @@ server.registerTool(
       old_id: external_exports.string(),
       text: external_exports.string(),
       why: external_exports.string().optional().describe('rationale for the new decision; stored structurally AND folded into its text as a "Why: \u2026" line'),
+      // Issue #127: without this in the schema the SDK strips a model-supplied
+      // `tags` silently and every successor lands untagged.
+      tags: external_exports.string().optional().describe('comma-separated; tags for the NEW decision (a tag itself cannot start with "[")'),
       role: ROLE2.optional()
     }
   },
   async (a) => {
-    const e = supersede(a.old_id, a.text, { role: envRole() ?? a.role ?? "architect", why: a.why });
+    const e = supersede(a.old_id, a.text, { role: envRole() ?? a.role ?? "architect", why: a.why, tags: tags(a.tags) });
     return text(`superseded ${a.old_id} -> ${line(e)}`);
   }
 );

package/dist/bundles/vfkb.mjs

@@ -786,7 +786,7 @@ function $constructor(name, initializer3, params) {
   Object.defineProperty(_, "name", { value: name });
   return _;
 }
-var $brand = Symbol("zod_brand");
+var $brand = /* @__PURE__ */ Symbol("zod_brand");
 var $ZodAsyncError = class extends Error {
   constructor() {
     super(`Encountered Promise during synchronous parse. Use .parseAsync() instead.`);
@@ -5215,6 +5215,7 @@ var error5 = () => {
         return `Clau inv\xE0lida a ${issue2.origin}`;
       case "invalid_union":
         return "Entrada inv\xE0lida";
+      // Could also be "Tipus d'unió invàlid" but "Entrada invàlida" is more general
       case "invalid_element":
         return `Element inv\xE0lid a ${issue2.origin}`;
       default:
@@ -10528,8 +10529,8 @@ function yo_default() {
 
 // node_modules/zod/v4/core/registries.js
 var _a2;
-var $output = Symbol("ZodOutput");
-var $input = Symbol("ZodInput");
+var $output = /* @__PURE__ */ Symbol("ZodOutput");
+var $input = /* @__PURE__ */ Symbol("ZodInput");
 var $ZodRegistry = class {
   constructor() {
     this._map = /* @__PURE__ */ new WeakMap();
@@ -11566,7 +11567,7 @@ function _stringbool(Classes, _params) {
     type: "pipe",
     in: stringSchema,
     out: booleanSchema,
-    transform: (input, payload) => {
+    transform: ((input, payload) => {
       let data = input;
       if (params.case !== "sensitive")
         data = data.toLowerCase();
@@ -11585,14 +11586,14 @@ function _stringbool(Classes, _params) {
         });
         return {};
       }
-    },
-    reverseTransform: (input, _payload) => {
+    }),
+    reverseTransform: ((input, _payload) => {
       if (input === true) {
         return truthyArray[0] || "true";
       } else {
         return falsyArray[0] || "false";
       }
-    },
+    }),
     error: params.error
   });
   return codec2;
@@ -16345,8 +16346,8 @@ import { dirname as dirname3, join as join9 } from "node:path";
 
 // src/version.ts
 var SCHEMA_VERSION = 1;
-var ENGINE_VERSION = true ? "0.2.1" : ownPackageVersion();
-var ENGINE_COMMIT = true ? "38bbdb9" : "dev";
+var ENGINE_VERSION = true ? "0.2.2" : ownPackageVersion();
+var ENGINE_COMMIT = true ? "046120c" : "dev";
 
 // src/manifest.ts
 function manifestPath(brainDir2) {
@@ -17067,9 +17068,13 @@ import { readFileSync as readFileSync11 } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname as dirname5, join as join13 } from "node:path";
 function packageVersion() {
-  const here = dirname5(fileURLToPath(import.meta.url));
-  const pkg = JSON.parse(readFileSync11(join13(here, "..", "package.json"), "utf8"));
-  return pkg.version || "0.0.0";
+  try {
+    const here = dirname5(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync11(join13(here, "..", "package.json"), "utf8"));
+    return pkg.version || ENGINE_VERSION;
+  } catch {
+    return ENGINE_VERSION;
+  }
 }
 function readStdin() {
   return new Promise((resolve3) => {

package/dist/bundles.test.js

@@ -174,4 +174,16 @@ describe('FR-2 portable single-file engine bundles (ADR-0030)', () => {
         const entries = readFileSync(join(brain, 'entries.jsonl'), 'utf8');
         expect(entries).toContain('bundle-portability-smoke');
     }, 30000);
+    // The bundle layout has no ../package.json (that resolves to dist/package.json),
+    // so a --version that insists on the manifest crashes every bundle deployment —
+    // observed 2026-07-12 vendoring into the Claude Code plugin. The bundle's
+    // ENGINE_VERSION is define-injected from the same manifest at build time, so
+    // falling back to it keeps ADR-0057's "never hardcoded" intent.
+    it('vfkb.mjs --version answers from a non-repo cwd (no ../package.json to read)', async () => {
+        const cwd = mkdtempSync(join(tmpdir(), 'vfkb-consumer-'));
+        const r = await run('node', [bundles.cli, '--version'], { cwd });
+        expect(r.code, `--version crashed:\n${r.stderr}`).toBe(0);
+        const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
+        expect(r.stdout.trim()).toBe(pkg.version);
+    }, 30000);
 });

package/dist/cli.js

@@ -26,10 +26,20 @@ import { dirname, join } from 'node:path';
 // hardcoded (ADR-0057 step 1). Resolved relative to this module file so it works
 // from dist/cli.js inside an `npm i -g` install: bin -> dist/cli.js, package.json
 // is one level up from dist/, in both the tsc dev build and the packed tarball.
+// The single-file bundles sit in dist/bundles/ where ../package.json does NOT
+// exist — an unguarded read crashed --version in every bundle deployment
+// (observed 2026-07-12 vendoring into the plugin). A bundle's ENGINE_VERSION is
+// define-injected from this same manifest at build time, so falling back to it
+// is the manifest's version by another route, not a hardcoded literal.
 function packageVersion() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
-    return pkg.version || '0.0.0';
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version || ENGINE_VERSION;
+    }
+    catch {
+        return ENGINE_VERSION;
+    }
 }
 function readStdin() {
     return new Promise((resolve) => {

package/dist/mcp-server.js

@@ -58,8 +58,35 @@ function renderNoMatch(d, q) {
         }
     }
 }
-function tags(csv) {
-    return csv ? csv.split(',').map((t) => t.trim()).filter(Boolean) : undefined;
+// Issue #127: some harnesses serialize array-valued params to strings, so the
+// JSON text of an array can arrive here (`'["a","b"]'`). A naive CSV split
+// stores a mangled fragment per element, and a silent fallback is only ever
+// discovered by a later reviewer — so JSON-array-shaped input is parsed
+// honestly, and garbage errors loudly back to the agent instead of degrading.
+function tags(csv, label = 'tags') {
+    if (csv === undefined)
+        return undefined;
+    const s = csv.trim();
+    if (!s)
+        return undefined;
+    if (s.startsWith('[')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(s);
+        }
+        catch {
+            throw new Error(`${label} received JSON-array-shaped input that does not parse: ${s} — pass a comma-separated string like "a,b"`);
+        }
+        if (!Array.isArray(parsed))
+            throw new Error(`${label} received JSON that is not an array: ${s}`);
+        // String()-coercing a non-string element would store mangled values like
+        // '[object Object]' silently — the exact class this parser exists to stop.
+        if (!parsed.every((t) => typeof t === 'string')) {
+            throw new Error(`${label} JSON array must contain only strings: ${s}`);
+        }
+        return parsed.map((t) => t.trim()).filter(Boolean);
+    }
+    return s.split(',').map((t) => t.trim()).filter(Boolean);
 }
 // In the fleet, who wrote an entry must be stamped by the HARNESS, not self-reported
 // by the model (VERIFIED = observed, not asserted — applied to provenance). When the
@@ -143,7 +170,7 @@ server.registerTool('kb_add', {
         type: ENTRY_TYPE,
         text: z.string(),
         why: z.string().optional().describe('rationale; stored structurally AND folded into the text as a "Why: …" line (esp. for decisions)'),
-        tags: z.string().optional().describe('comma-separated'),
+        tags: z.string().optional().describe('comma-separated (a tag itself cannot start with "[")'),
         path: z
             .string()
             .optional()
@@ -168,7 +195,7 @@ server.registerTool('kb_add', {
         role: envRole() ?? a.role ?? 'executor',
         why: a.why,
         tags: tags(a.tags),
-        contradicts: tags(a.contradicts),
+        contradicts: tags(a.contradicts, 'contradicts'),
         status: a.status,
         constitutional: a.constitutional,
     });
@@ -183,10 +210,13 @@ server.registerTool('kb_supersede', {
             .string()
             .optional()
             .describe('rationale for the new decision; stored structurally AND folded into its text as a "Why: …" line'),
+        // Issue #127: without this in the schema the SDK strips a model-supplied
+        // `tags` silently and every successor lands untagged.
+        tags: z.string().optional().describe('comma-separated; tags for the NEW decision (a tag itself cannot start with "[")'),
         role: ROLE.optional(),
     },
 }, async (a) => {
-    const e = supersede(a.old_id, a.text, { role: envRole() ?? a.role ?? 'architect', why: a.why });
+    const e = supersede(a.old_id, a.text, { role: envRole() ?? a.role ?? 'architect', why: a.why, tags: tags(a.tags) });
     return text(`superseded ${a.old_id} -> ${line(e)}`);
 });
 server.registerTool('kb_transition', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viloforge/vfkb",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "ViloForge KnowledgeBase (vfkb) — per-project knowledge substrate for the ViloForge software factory. Greenfield TypeScript.",
   "type": "module",
   "main": "dist/engine.js",
@@ -39,10 +39,10 @@
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.9",
-    "@types/node": "^25.9.1",
-    "esbuild": "^0.21.5",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "@types/node": "^26.1.1",
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",