okf-catalog 0.1.0

package/dist/fs/walk.js

@@ -0,0 +1,168 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readSync, realpathSync, } from "node:fs";
+import { join, sep } from "node:path";
+import { byCodeUnit } from "../bundle/paths.js";
+const errorCode = (error) => error.code ?? error.name ?? "error";
+/**
+ * Reads a bundle folder into memory. Regular files only: a symbolic link is refused where it stands, a pipe,
+ * socket or device is refused as a special file, an oversize file is refused from its size without being read,
+ * and an entry that cannot be listed, inspected or read is refused with the system's error code while the rest
+ * of the bundle is still reported. Dot-leading entries are returned as hidden paths and never opened, so a
+ * checkout's `.git` never enters the walk. Files are opened without following links and without blocking, and
+ * read through the descriptor that was checked. Every directory entry counts toward the file cap, so a folder of
+ * links or hidden files cannot grow without bound. The root is resolved once; a folder whose real path leaves it
+ * is refused. Residual: a folder replaced by a link between its check and its listing is listed once, because
+ * Node cannot list a directory through a descriptor; whoever can swap folders during the walk already owns the
+ * bundle.
+ */
+export function walkBundle(root, caps) {
+    let realRoot;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        throw new Error(`the bundle folder ${root} does not exist or cannot be read`);
+    }
+    const result = { files: [], hidden: [], hiddenFolders: [], refusals: [] };
+    const refuse = (path, rule, detail) => {
+        result.refusals.push({ path, rule, detail });
+    };
+    let total = 0;
+    let entries = 0;
+    const pending = [""];
+    while (pending.length > 0) {
+        const relDir = pending.pop();
+        const absDir = relDir === "" ? realRoot : join(realRoot, relDir);
+        if (relDir !== "") {
+            // Checked when it was listed as an entry; checked again here, right before it is read, to narrow the
+            // window in which a folder swapped for a link could be followed.
+            let real;
+            try {
+                real = realpathSync(absDir);
+            }
+            catch (error) {
+                refuse(relDir, "unreadable", `${errorCode(error)}: the folder could not be resolved`);
+                continue;
+            }
+            if (real !== absDir) {
+                refuse(relDir, "path-escape", "the folder changed under the walk");
+                continue;
+            }
+        }
+        let listed;
+        try {
+            listed = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (relDir === "")
+                throw new Error(`the bundle folder ${root} cannot be listed (${errorCode(error)})`);
+            refuse(relDir, "unreadable", `${errorCode(error)}: the folder could not be listed`);
+            continue;
+        }
+        listed.sort((a, b) => byCodeUnit(a.name, b.name));
+        for (const entry of listed) {
+            entries += 1;
+            if (entries > caps.files) {
+                result.fatal = {
+                    path: "",
+                    rule: "too-many-files",
+                    detail: `more than ${caps.files} entries (files, folders, links and hidden entries all count)`,
+                };
+                return result;
+            }
+            const rel = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+            if (entry.name.startsWith(".")) {
+                result.hidden.push(rel);
+                if (entry.isDirectory())
+                    result.hiddenFolders.push(rel);
+                continue;
+            }
+            const abs = join(absDir, entry.name);
+            let stat;
+            try {
+                stat = lstatSync(abs);
+            }
+            catch (error) {
+                refuse(rel, "unreadable", `${errorCode(error)}: the entry could not be inspected`);
+                continue;
+            }
+            if (stat.isSymbolicLink()) {
+                refuse(rel, "symlink", "symbolic links are not followed");
+                continue;
+            }
+            if (stat.isDirectory()) {
+                let real;
+                try {
+                    real = realpathSync(abs);
+                }
+                catch (error) {
+                    refuse(rel, "unreadable", `${errorCode(error)}: the folder could not be resolved`);
+                    continue;
+                }
+                if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+                    refuse(rel, "path-escape", "the folder's real path leaves the bundle");
+                    continue;
+                }
+                pending.push(rel);
+                continue;
+            }
+            if (!stat.isFile()) {
+                refuse(rel, "special-file", "not a regular file (a pipe, socket or device)");
+                continue;
+            }
+            if (stat.size > caps.fileBytes) {
+                refuse(rel, "oversize", `${stat.size} bytes exceeds the cap of ${caps.fileBytes}`);
+                continue;
+            }
+            let bytes;
+            try {
+                bytes = readRegularFile(abs, caps.fileBytes);
+            }
+            catch (error) {
+                refuse(rel, "unreadable", `${errorCode(error)}: the file could not be read`);
+                continue;
+            }
+            if (bytes === undefined) {
+                refuse(rel, "special-file", "the entry changed under the walk and is not a regular file");
+                continue;
+            }
+            if (bytes.length > caps.fileBytes) {
+                refuse(rel, "oversize", `more than ${caps.fileBytes} bytes`);
+                continue;
+            }
+            result.files.push({ path: rel, bytes });
+            total += bytes.length;
+            if (total > caps.treeBytes) {
+                result.fatal = {
+                    path: "",
+                    rule: "tree-too-large",
+                    detail: `more than ${caps.treeBytes} bytes`,
+                };
+                return result;
+            }
+        }
+    }
+    result.files.sort((a, b) => byCodeUnit(a.path, b.path));
+    return result;
+}
+/** Opens without following a link and without blocking, checks the descriptor, and reads at most `cap + 1` bytes. */
+function readRegularFile(abs, cap) {
+    const fd = openSync(abs, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            return undefined;
+        const buffer = Buffer.alloc(Math.min(stat.size, cap + 1));
+        let offset = 0;
+        while (offset < buffer.length) {
+            const n = readSync(fd, buffer, offset, buffer.length - offset, offset);
+            if (n === 0)
+                break;
+            offset += n;
+        }
+        return buffer.subarray(0, offset);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/fs/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../src/fs/walk.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  closeSync,\n  constants,\n  type Dirent,\n  fstatSync,\n  lstatSync,\n  openSync,\n  readdirSync,\n  readSync,\n  realpathSync,\n} from \"node:fs\";\nimport { join, sep } from \"node:path\";\nimport type { BundleFile, Caps, Refusal } from \"../bundle/model.js\";\nimport { byCodeUnit } from \"../bundle/paths.js\";\n\nexport interface WalkResult {\n  files: BundleFile[];\n  /** Dot-leading entries, as paths, never descended into or read. */\n  hidden: string[];\n  /** The hidden entries that are folders; a manifest entry beneath one counts as present. */\n  hiddenFolders: string[];\n  refusals: Refusal[];\n  fatal?: Refusal;\n}\n\nconst errorCode = (error: unknown): string =>\n  (error as NodeJS.ErrnoException).code ?? (error as Error).name ?? \"error\";\n\n/**\n * Reads a bundle folder into memory. Regular files only: a symbolic link is refused where it stands, a pipe,\n * socket or device is refused as a special file, an oversize file is refused from its size without being read,\n * and an entry that cannot be listed, inspected or read is refused with the system's error code while the rest\n * of the bundle is still reported. Dot-leading entries are returned as hidden paths and never opened, so a\n * checkout's `.git` never enters the walk. Files are opened without following links and without blocking, and\n * read through the descriptor that was checked. Every directory entry counts toward the file cap, so a folder of\n * links or hidden files cannot grow without bound. The root is resolved once; a folder whose real path leaves it\n * is refused. Residual: a folder replaced by a link between its check and its listing is listed once, because\n * Node cannot list a directory through a descriptor; whoever can swap folders during the walk already owns the\n * bundle.\n */\nexport function walkBundle(root: string, caps: Caps): WalkResult {\n  let realRoot: string;\n  try {\n    realRoot = realpathSync(root);\n  } catch {\n    throw new Error(`the bundle folder ${root} does not exist or cannot be read`);\n  }\n  const result: WalkResult = { files: [], hidden: [], hiddenFolders: [], refusals: [] };\n  const refuse = (path: string, rule: Refusal[\"rule\"], detail: string): void => {\n    result.refusals.push({ path, rule, detail });\n  };\n  let total = 0;\n  let entries = 0;\n  const pending: string[] = [\"\"];\n  while (pending.length > 0) {\n    const relDir = pending.pop() as string;\n    const absDir = relDir === \"\" ? realRoot : join(realRoot, relDir);\n    if (relDir !== \"\") {\n      // Checked when it was listed as an entry; checked again here, right before it is read, to narrow the\n      // window in which a folder swapped for a link could be followed.\n      let real: string;\n      try {\n        real = realpathSync(absDir);\n      } catch (error) {\n        refuse(relDir, \"unreadable\", `${errorCode(error)}: the folder could not be resolved`);\n        continue;\n      }\n      if (real !== absDir) {\n        refuse(relDir, \"path-escape\", \"the folder changed under the walk\");\n        continue;\n      }\n    }\n    let listed: Dirent[];\n    try {\n      listed = readdirSync(absDir, { withFileTypes: true });\n    } catch (error) {\n      if (relDir === \"\")\n        throw new Error(`the bundle folder ${root} cannot be listed (${errorCode(error)})`);\n      refuse(relDir, \"unreadable\", `${errorCode(error)}: the folder could not be listed`);\n      continue;\n    }\n    listed.sort((a: Dirent, b: Dirent) => byCodeUnit(a.name, b.name));\n    for (const entry of listed) {\n      entries += 1;\n      if (entries > caps.files) {\n        result.fatal = {\n          path: \"\",\n          rule: \"too-many-files\",\n          detail: `more than ${caps.files} entries (files, folders, links and hidden entries all count)`,\n        };\n        return result;\n      }\n      const rel = relDir === \"\" ? entry.name : `${relDir}/${entry.name}`;\n      if (entry.name.startsWith(\".\")) {\n        result.hidden.push(rel);\n        if (entry.isDirectory()) result.hiddenFolders.push(rel);\n        continue;\n      }\n      const abs = join(absDir, entry.name);\n      let stat: ReturnType<typeof lstatSync>;\n      try {\n        stat = lstatSync(abs);\n      } catch (error) {\n        refuse(rel, \"unreadable\", `${errorCode(error)}: the entry could not be inspected`);\n        continue;\n      }\n      if (stat.isSymbolicLink()) {\n        refuse(rel, \"symlink\", \"symbolic links are not followed\");\n        continue;\n      }\n      if (stat.isDirectory()) {\n        let real: string;\n        try {\n          real = realpathSync(abs);\n        } catch (error) {\n          refuse(rel, \"unreadable\", `${errorCode(error)}: the folder could not be resolved`);\n          continue;\n        }\n        if (real !== realRoot && !real.startsWith(realRoot + sep)) {\n          refuse(rel, \"path-escape\", \"the folder's real path leaves the bundle\");\n          continue;\n        }\n        pending.push(rel);\n        continue;\n      }\n      if (!stat.isFile()) {\n        refuse(rel, \"special-file\", \"not a regular file (a pipe, socket or device)\");\n        continue;\n      }\n      if (stat.size > caps.fileBytes) {\n        refuse(rel, \"oversize\", `${stat.size} bytes exceeds the cap of ${caps.fileBytes}`);\n        continue;\n      }\n      let bytes: Uint8Array | undefined;\n      try {\n        bytes = readRegularFile(abs, caps.fileBytes);\n      } catch (error) {\n        refuse(rel, \"unreadable\", `${errorCode(error)}: the file could not be read`);\n        continue;\n      }\n      if (bytes === undefined) {\n        refuse(rel, \"special-file\", \"the entry changed under the walk and is not a regular file\");\n        continue;\n      }\n      if (bytes.length > caps.fileBytes) {\n        refuse(rel, \"oversize\", `more than ${caps.fileBytes} bytes`);\n        continue;\n      }\n      result.files.push({ path: rel, bytes });\n      total += bytes.length;\n      if (total > caps.treeBytes) {\n        result.fatal = {\n          path: \"\",\n          rule: \"tree-too-large\",\n          detail: `more than ${caps.treeBytes} bytes`,\n        };\n        return result;\n      }\n    }\n  }\n  result.files.sort((a, b) => byCodeUnit(a.path, b.path));\n  return result;\n}\n\n/** Opens without following a link and without blocking, checks the descriptor, and reads at most `cap + 1` bytes. */\nfunction readRegularFile(abs: string, cap: number): Uint8Array | undefined {\n  const fd = openSync(abs, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);\n  try {\n    const stat = fstatSync(fd);\n    if (!stat.isFile()) return undefined;\n    const buffer = Buffer.alloc(Math.min(stat.size, cap + 1));\n    let offset = 0;\n    while (offset < buffer.length) {\n      const n = readSync(fd, buffer, offset, buffer.length - offset, offset);\n      if (n === 0) break;\n      offset += n;\n    }\n    return buffer.subarray(0, offset);\n  } finally {\n    closeSync(fd);\n  }\n}\n"]}

package/dist/log.js

@@ -0,0 +1,65 @@
+import { escapeControls } from "./catalog/text.js";
+const ORDER = { error: 0, warn: 1, info: 2, debug: 3 };
+const COUNTS = [
+    "documents",
+    "notIndexed",
+    "collisions",
+    "encodedFolders",
+    "admitted",
+    "refused",
+    "degraded",
+    "ms",
+];
+/**
+ * The closed allowlist of fields per event. Nothing outside it is written, so no question, path argument, title,
+ * body or snippet can reach the log through any event.
+ */
+const ALLOWED = {
+    "serve.start": ["company", "source", "lock", "dev", "node", "configRule", "note"],
+    "serve.refusing": ["problem", "detail"],
+    "serve.shutdown": ["reason"],
+    "engine.reset": ["detail"],
+    "load.done": COUNTS,
+    "load.fatal": ["rule", "path", "detail"],
+    "refresh.done": COUNTS,
+    "refresh.fatal": ["rule", "path", "detail"],
+    "refresh.failed": ["error", "detail"],
+    "load.served-previous": ["commit", "refused"],
+    "poller.tick": ["outcome", "ms", "error", "detail"],
+    "source.recloned": ["reason"],
+    "tool.call": ["tool", "ms", "hits", "engineQueries", "rowsFetched", "error"],
+    "transport.error": ["error"],
+    console: ["method", "text"],
+};
+/** The most characters a free-text field keeps; one error message cannot flood the log. */
+export const LOG_VALUE_CAP = 2_000;
+const clipValue = (value) => value.length <= LOG_VALUE_CAP ? value : `${value.slice(0, LOG_VALUE_CAP)}…`;
+/** JSON lines on a stream, one object per line: `time`, `level`, `event`, then the event's allowed fields, control characters escaped. */
+export function createLog(stream, level, clock = () => new Date()) {
+    const threshold = ORDER[level];
+    const write = (at, event, fields = {}) => {
+        if (ORDER[at] > threshold)
+            return;
+        const record = { time: clock().toISOString(), level: at, event };
+        const allowed = ALLOWED[event] ?? [];
+        for (const key of allowed) {
+            const value = fields[key];
+            if (value === undefined)
+                continue;
+            record[key] =
+                typeof value === "string"
+                    ? escapeControls(clipValue(value))
+                    : Array.isArray(value)
+                        ? value.map((v) => escapeControls(clipValue(String(v))))
+                        : value;
+        }
+        stream.write(`${JSON.stringify(record)}\n`);
+    };
+    return {
+        error: (event, fields) => write("error", event, fields),
+        warn: (event, fields) => write("warn", event, fields),
+        info: (event, fields) => write("info", event, fields),
+        debug: (event, fields) => write("debug", event, fields),
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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","sourcesContent":["import { escapeControls } from \"./catalog/text.js\";\n\nexport type Level = \"error\" | \"warn\" | \"info\" | \"debug\";\nconst ORDER: Record<Level, number> = { error: 0, warn: 1, info: 2, debug: 3 };\n\nconst COUNTS = [\n  \"documents\",\n  \"notIndexed\",\n  \"collisions\",\n  \"encodedFolders\",\n  \"admitted\",\n  \"refused\",\n  \"degraded\",\n  \"ms\",\n] as const;\n\n/**\n * The closed allowlist of fields per event. Nothing outside it is written, so no question, path argument, title,\n * body or snippet can reach the log through any event.\n */\nconst ALLOWED: Record<string, readonly string[]> = {\n  \"serve.start\": [\"company\", \"source\", \"lock\", \"dev\", \"node\", \"configRule\", \"note\"],\n  \"serve.refusing\": [\"problem\", \"detail\"],\n  \"serve.shutdown\": [\"reason\"],\n  \"engine.reset\": [\"detail\"],\n  \"load.done\": COUNTS,\n  \"load.fatal\": [\"rule\", \"path\", \"detail\"],\n  \"refresh.done\": COUNTS,\n  \"refresh.fatal\": [\"rule\", \"path\", \"detail\"],\n  \"refresh.failed\": [\"error\", \"detail\"],\n  \"load.served-previous\": [\"commit\", \"refused\"],\n  \"poller.tick\": [\"outcome\", \"ms\", \"error\", \"detail\"],\n  \"source.recloned\": [\"reason\"],\n  \"tool.call\": [\"tool\", \"ms\", \"hits\", \"engineQueries\", \"rowsFetched\", \"error\"],\n  \"transport.error\": [\"error\"],\n  console: [\"method\", \"text\"],\n};\n\nexport type Fields = Record<string, string | number | boolean | readonly string[] | undefined>;\n\n/** The most characters a free-text field keeps; one error message cannot flood the log. */\nexport const LOG_VALUE_CAP = 2_000;\nconst clipValue = (value: string): string =>\n  value.length <= LOG_VALUE_CAP ? value : `${value.slice(0, LOG_VALUE_CAP)}…`;\n\nexport interface Log {\n  error(event: string, fields?: Fields): void;\n  warn(event: string, fields?: Fields): void;\n  info(event: string, fields?: Fields): void;\n  debug(event: string, fields?: Fields): void;\n}\n\n/** JSON lines on a stream, one object per line: `time`, `level`, `event`, then the event's allowed fields, control characters escaped. */\nexport function createLog(\n  stream: { write(text: string): void },\n  level: Level,\n  clock: () => Date = () => new Date(),\n): Log {\n  const threshold = ORDER[level];\n  const write = (at: Level, event: string, fields: Fields = {}): void => {\n    if (ORDER[at] > threshold) return;\n    const record: Record<string, unknown> = { time: clock().toISOString(), level: at, event };\n    const allowed = ALLOWED[event] ?? [];\n    for (const key of allowed) {\n      const value = fields[key];\n      if (value === undefined) continue;\n      record[key] =\n        typeof value === \"string\"\n          ? escapeControls(clipValue(value))\n          : Array.isArray(value)\n            ? value.map((v) => escapeControls(clipValue(String(v))))\n            : value;\n    }\n    stream.write(`${JSON.stringify(record)}\\n`);\n  };\n  return {\n    error: (event, fields) => write(\"error\", event, fields),\n    warn: (event, fields) => write(\"warn\", event, fields),\n    info: (event, fields) => write(\"info\", event, fields),\n    debug: (event, fields) => write(\"debug\", event, fields),\n  };\n}\n"]}

package/dist/mcp/server.js

@@ -0,0 +1,30 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { DATA_SENTENCE } from "../catalog/text.js";
+import { registerTools } from "./tools.js";
+/** What the client is told at `initialize`: how to use the catalog, and the rules the tool results repeat. */
+export const INSTRUCTIONS = [
+    "This server serves one company's knowledge bundle (Open Knowledge Format).",
+    "Start with `catalog` to see what exists, search with keywords through `search`, then read a page whole with `get_page`.",
+    "Cite every answer with the page's path, its trust tier, its verifier and its recheck date as the result states them; say so when a page is overdue or deprecated, and follow a replacement.",
+    "When no page answers, say that there is none. Never claim a page says what it does not.",
+    DATA_SENTENCE,
+].join(" ");
+/** Builds one server per connection. The runtime lives outside, so a probe connection costs nothing. */
+export function createServerFactory(runtime, options, clock, log, version = "0.0.0") {
+    return () => {
+        const server = new McpServer({ name: "okf-catalog", version }, { instructions: INSTRUCTIONS });
+        registerTools(server, runtime, options, clock, log);
+        // The first load starts when a client sends `notifications/initialized` (the 2025-era handshake). A
+        // current-protocol client adopts the discovery result and sends neither `initialize` nor the notification;
+        // over stdio its first request that is not a probe starts the load (see `stdio.ts`), and any tool call does
+        // through `lease()`. A probe connection never gets this far.
+        const inner = server.server;
+        const previous = inner.oninitialized;
+        inner.oninitialized = () => {
+            previous?.();
+            runtime.start?.();
+        };
+        return server;
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,8GAA8G;AAC9G,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,4EAA4E;IAC5E,yHAAyH;IACzH,6LAA6L;IAC7L,yFAAyF;IACzF,aAAa;CACd,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,wGAAwG;AACxG,MAAM,UAAU,mBAAmB,CACjC,OAAgB,EAChB,OAAoB,EACpB,KAAiB,EACjB,GAAS,EACT,OAAO,GAAG,OAAO;IAEjB,OAAO,GAAG,EAAE;QACV,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC;QAC/F,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACpD,oGAAoG;QACpG,2GAA2G;QAC3G,4GAA4G;QAC5G,6DAA6D;QAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAwC,CAAC;QAC9D,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAa,CAAC;QACrC,KAAK,CAAC,aAAa,GAAG,GAAG,EAAE;YACzB,QAAQ,EAAE,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QACpB,CAAC,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { McpServer } from \"@modelcontextprotocol/server\";\nimport type { Runtime, ToolOptions } from \"../catalog/runtime.js\";\nimport { DATA_SENTENCE } from \"../catalog/text.js\";\nimport type { Log } from \"../log.js\";\nimport { registerTools } from \"./tools.js\";\n\n/** What the client is told at `initialize`: how to use the catalog, and the rules the tool results repeat. */\nexport const INSTRUCTIONS = [\n  \"This server serves one company's knowledge bundle (Open Knowledge Format).\",\n  \"Start with `catalog` to see what exists, search with keywords through `search`, then read a page whole with `get_page`.\",\n  \"Cite every answer with the page's path, its trust tier, its verifier and its recheck date as the result states them; say so when a page is overdue or deprecated, and follow a replacement.\",\n  \"When no page answers, say that there is none. Never claim a page says what it does not.\",\n  DATA_SENTENCE,\n].join(\" \");\n\n/** Builds one server per connection. The runtime lives outside, so a probe connection costs nothing. */\nexport function createServerFactory(\n  runtime: Runtime,\n  options: ToolOptions,\n  clock: () => Date,\n  log?: Log,\n  version = \"0.0.0\",\n): () => McpServer {\n  return () => {\n    const server = new McpServer({ name: \"okf-catalog\", version }, { instructions: INSTRUCTIONS });\n    registerTools(server, runtime, options, clock, log);\n    // The first load starts when a client sends `notifications/initialized` (the 2025-era handshake). A\n    // current-protocol client adopts the discovery result and sends neither `initialize` nor the notification;\n    // over stdio its first request that is not a probe starts the load (see `stdio.ts`), and any tool call does\n    // through `lease()`. A probe connection never gets this far.\n    const inner = server.server as { oninitialized?: () => void };\n    const previous = inner.oninitialized;\n    inner.oninitialized = () => {\n      previous?.();\n      runtime.start?.();\n    };\n    return server;\n  };\n}\n"]}

package/dist/mcp/stdio.js

@@ -0,0 +1,45 @@
+import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
+/** Requests that must cost the server nothing: the probe, the handshake and liveness. Everything else is work. */
+const PROBES = new Set(["server/discover", "initialize", "ping"]);
+/**
+ * Calls `onWork` the first time a message arrives that means the client wants the bundle: the 2025-era
+ * `notifications/initialized`, or any request that is not a probe (a current-protocol client adopts the
+ * discovery result and sends neither `initialize` nor the notification, so its `tools/list` is the first sign).
+ * The SDK assigns the transport's `onmessage` when it connects; an accessor wraps whatever it assigns.
+ */
+function watchForWork(transport, onWork) {
+    let inner;
+    let started = false;
+    Object.defineProperty(transport, "onmessage", {
+        configurable: true,
+        enumerable: true,
+        get: () => inner,
+        set: (listener) => {
+            inner =
+                listener === undefined
+                    ? undefined
+                    : (message, extra) => {
+                        if (!started) {
+                            const m = message;
+                            const isWork = typeof m.method === "string" &&
+                                (m.method === "notifications/initialized" ||
+                                    (m.id !== undefined && !PROBES.has(m.method)));
+                            if (isWork) {
+                                started = true;
+                                onWork();
+                            }
+                        }
+                        listener(message, extra);
+                    };
+        },
+    });
+}
+/** Serves the factory over the given streams. The transport writes to `stdout` and nothing else does. */
+export function serveOverStdio(factory, streams, onerror, onWork) {
+    const transport = new StdioServerTransport(streams.stdin, streams.stdout);
+    if (onWork !== undefined)
+        watchForWork(transport, onWork);
+    const handle = serveStdio(factory, { transport, onerror });
+    return { close: () => handle.close() };
+}
+//# sourceMappingURL=stdio.js.map

package/dist/mcp/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/mcp/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAMtF,kHAAkH;AAClH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;AAIlE;;;;;GAKG;AACH,SAAS,YAAY,CAAC,SAA+B,EAAE,MAAkB;IACvE,IAAI,KAA2B,CAAC;IAChC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE;QAC5C,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;QAChB,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;QAChB,GAAG,EAAE,CAAC,QAA8B,EAAE,EAAE;YACtC,KAAK;gBACH,QAAQ,KAAK,SAAS;oBACpB,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;wBACjB,IAAI,CAAC,OAAO,EAAE,CAAC;4BACb,MAAM,CAAC,GAAG,OAA6C,CAAC;4BACxD,MAAM,MAAM,GACV,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;gCAC5B,CAAC,CAAC,CAAC,MAAM,KAAK,2BAA2B;oCACvC,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;4BACnD,IAAI,MAAM,EAAE,CAAC;gCACX,OAAO,GAAG,IAAI,CAAC;gCACf,MAAM,EAAE,CAAC;4BACX,CAAC;wBACH,CAAC;wBACD,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;oBAC3B,CAAC,CAAC;QACV,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,cAAc,CAC5B,OAAwB,EACxB,OAA8C,EAC9C,OAA+B,EAC/B,MAAmB;IAEnB,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1E,IAAI,MAAM,KAAK,SAAS;QAAE,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;AACzC,CAAC","sourcesContent":["import type { Readable, Writable } from \"node:stream\";\nimport type { McpServer } from \"@modelcontextprotocol/server\";\nimport { StdioServerTransport, serveStdio } from \"@modelcontextprotocol/server/stdio\";\n\nexport interface StdioHandle {\n  close(): Promise<void>;\n}\n\n/** Requests that must cost the server nothing: the probe, the handshake and liveness. Everything else is work. */\nconst PROBES = new Set([\"server/discover\", \"initialize\", \"ping\"]);\n\ntype Listener = (message: unknown, extra?: unknown) => void;\n\n/**\n * Calls `onWork` the first time a message arrives that means the client wants the bundle: the 2025-era\n * `notifications/initialized`, or any request that is not a probe (a current-protocol client adopts the\n * discovery result and sends neither `initialize` nor the notification, so its `tools/list` is the first sign).\n * The SDK assigns the transport's `onmessage` when it connects; an accessor wraps whatever it assigns.\n */\nfunction watchForWork(transport: StdioServerTransport, onWork: () => void): void {\n  let inner: Listener | undefined;\n  let started = false;\n  Object.defineProperty(transport, \"onmessage\", {\n    configurable: true,\n    enumerable: true,\n    get: () => inner,\n    set: (listener: Listener | undefined) => {\n      inner =\n        listener === undefined\n          ? undefined\n          : (message, extra) => {\n              if (!started) {\n                const m = message as { method?: unknown; id?: unknown };\n                const isWork =\n                  typeof m.method === \"string\" &&\n                  (m.method === \"notifications/initialized\" ||\n                    (m.id !== undefined && !PROBES.has(m.method)));\n                if (isWork) {\n                  started = true;\n                  onWork();\n                }\n              }\n              listener(message, extra);\n            };\n    },\n  });\n}\n\n/** Serves the factory over the given streams. The transport writes to `stdout` and nothing else does. */\nexport function serveOverStdio(\n  factory: () => McpServer,\n  streams: { stdin: Readable; stdout: Writable },\n  onerror: (error: Error) => void,\n  onWork?: () => void,\n): StdioHandle {\n  const transport = new StdioServerTransport(streams.stdin, streams.stdout);\n  if (onWork !== undefined) watchForWork(transport, onWork);\n  const handle = serveStdio(factory, { transport, onerror });\n  return { close: () => handle.close() };\n}\n"]}

package/dist/mcp/tools.js

@@ -0,0 +1,249 @@
+import { z } from "zod/v4";
+import { byCodeUnit } from "../bundle/paths.js";
+import { listTypes } from "../catalog/model.js";
+import { nearestPaths } from "../catalog/nearest.js";
+import { CatalogOutputSchema, PageOutputSchema, projectCatalog, projectPage, projectReserved, projectSearch, projectStatus, refusingText, SearchOutputSchema, StatusOutputSchema, statusSummary, } from "../catalog/outputs.js";
+import { DATA_SENTENCE, safe } from "../catalog/text.js";
+import { search } from "../search/search.js";
+const FOLDER_LIST_CAP = 50;
+const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+const ok = (text, structured) => ({
+    content: [{ type: "text", text }],
+    structuredContent: structured,
+});
+/** A blank optional string means absent. */
+const blank = (value) => value === undefined || value.trim().length === 0 ? undefined : value.trim();
+/** A folder as the search filter normalises it: no leading or trailing slashes; the empty string is the root. */
+const normaliseFolder = (value) => value.trim().replace(/^\/+|\/+$/g, "");
+/** A page path as the model may write it: one leading `/` or `./` stripped (OKF bundle-absolute links). */
+const normalisePath = (value) => value.trim().replace(/^(\.\/|\/)/, "");
+function folderList(catalog) {
+    const names = [...catalog.folders.keys()]
+        .sort(byCodeUnit)
+        .map((f) => (f === "" ? "(root)" : safe(f)));
+    const shown = names.slice(0, FOLDER_LIST_CAP).join(", ");
+    return names.length > FOLDER_LIST_CAP ? `${shown} … (${names.length} folders)` : shown;
+}
+function refused(generation) {
+    const fatal = generation.report.fatal;
+    if (fatal === undefined)
+        return undefined;
+    return fail(`the bundle was refused and nothing is served: ${safe(fatal.rule)}${fatal.path ? ` (${safe(fatal.path)})` : ""}: ${safe(fatal.detail)}`);
+}
+function reservedAt(catalog, path) {
+    const slash = path.lastIndexOf("/");
+    const folder = slash === -1 ? "" : path.slice(0, slash);
+    const name = slash === -1 ? path : path.slice(slash + 1);
+    const entry = catalog.folders.get(folder);
+    if (entry === undefined)
+        return undefined;
+    if (name === "index.md" && entry.index !== undefined)
+        return { file: entry.index, source: entry.indexSource };
+    if (name === "log.md" && entry.log !== undefined)
+        return { file: entry.log, source: "file" };
+    return undefined;
+}
+function servedPaths(catalog) {
+    const paths = [...catalog.pages.keys()];
+    for (const [folder, entry] of catalog.folders) {
+        const prefix = folder === "" ? "" : `${folder}/`;
+        if (entry.index !== undefined)
+            paths.push(`${prefix}index.md`);
+        if (entry.log !== undefined)
+            paths.push(`${prefix}log.md`);
+    }
+    return paths;
+}
+function pageText(output) {
+    const tail = output.truncated && output.nextOffset !== undefined
+        ? `\n[truncated at the result budget; continue with offset ${output.nextOffset}]`
+        : "";
+    return `${output.citation}\n${output.notice}\n${output.body}${tail}`;
+}
+const describeType = (text) => `${text} ${DATA_SENTENCE}`;
+/** The one sentence every tool answers with while the server cannot serve: the fix, never a path the model has no business with. */
+const refusingSentence = (refusing) => `the server is refusing every request until its configuration is fixed: ${refusingText(refusing)}`;
+/**
+ * The four tools. Every handler runs under a lease on the current generation, answers in both channels, and
+ * turns anything it cannot repair into a fixed sentence; the detail goes to the log, never to the model.
+ */
+export function registerTools(server, runtime, options, clock, log) {
+    const guarded = (tool, fn) => async (args) => {
+        const started = performance.now();
+        const refusing = runtime.status().refusing;
+        if (refusing !== undefined)
+            return fail(refusingSentence(refusing));
+        try {
+            const { logFields, ...result } = await runtime.lease(async (generation, engine) => fn(args, generation, engine));
+            const hits = result.structuredContent?.hits?.length;
+            log?.info("tool.call", {
+                tool,
+                ms: Math.round(performance.now() - started),
+                ...(hits === undefined ? {} : { hits }),
+                ...(logFields ?? {}),
+                ...(result.isError === true ? { error: "answered-with-error" } : {}),
+            });
+            return result;
+        }
+        catch (error) {
+            log?.error("tool.call", {
+                tool,
+                ms: Math.round(performance.now() - started),
+                error: error.message,
+            });
+            // The call that started the first load is the one that sees it fail: answer with the fix, as later calls do.
+            const refusingNow = runtime.status().refusing;
+            if (refusingNow !== undefined)
+                return fail(refusingSentence(refusingNow));
+            return fail("the server hit a defect answering this call; its log has the detail");
+        }
+    };
+    server.registerTool("search", {
+        title: "Search the knowledge bundle",
+        description: describeType("Finds pages by keywords. Write one concept per word; common words are dropped, and when no page holds every word the match is relaxed and the result says so. Each hit carries its path, type, status, trust tier, recheck date, source count, resource and a quoted snippet."),
+        inputSchema: z.object({
+            question: z
+                .string()
+                .min(1)
+                .max(200)
+                .describe("Keywords, or a short question; one concept per word."),
+            type: z
+                .string()
+                .max(200)
+                .optional()
+                .describe("Only pages of this type (case does not matter)."),
+            topic: z
+                .string()
+                .max(1024)
+                .optional()
+                .describe("Only pages under this folder of the bundle."),
+            include_stale: z
+                .boolean()
+                .optional()
+                .describe("Include pages past their recheck date; they are flagged as overdue."),
+            limit: z.number().int().min(1).max(25).optional().describe("How many hits, 1 to 25."),
+        }),
+        outputSchema: SearchOutputSchema,
+        annotations: { readOnlyHint: true },
+    }, guarded("search", async (args, generation, engine) => {
+        const stop = refused(generation);
+        if (stop !== undefined)
+            return stop;
+        const wantedType = blank(args.type);
+        let type;
+        if (wantedType !== undefined) {
+            const types = listTypes(generation.catalog);
+            type = types.find((t) => t.toLowerCase() === wantedType.toLowerCase());
+            if (type === undefined) {
+                return fail(`no page has the type ${JSON.stringify(safe(wantedType))}; the types in use are: ${types.map(safe).join(", ") || "(none)"}`);
+            }
+        }
+        const wantedTopic = blank(args.topic);
+        let topic;
+        if (wantedTopic !== undefined) {
+            topic = normaliseFolder(wantedTopic);
+            if (topic.length > 0 && !generation.catalog.folders.has(topic)) {
+                return fail(`there is no folder ${JSON.stringify(safe(topic))}; the folders are: ${folderList(generation.catalog)}`);
+            }
+            if (topic.length === 0)
+                topic = undefined;
+        }
+        const now = clock();
+        const response = await search(generation.catalog, engine, {
+            question: args.question,
+            ...(type === undefined ? {} : { type }),
+            ...(topic === undefined ? {} : { topic }),
+            includeStale: args.include_stale ?? false,
+            limit: args.limit ?? options.limitDefault,
+        }, now);
+        if (response.reason === "no-content-terms") {
+            return fail("every word of the question is a common word the index ignores; ask with keywords, the distinctive words a page would use");
+        }
+        const output = projectSearch(response, generation.catalog, now, { dev: options.dev });
+        return {
+            ...ok([output.summary, ...output.hits.map((h) => h.citation)].join("\n"), output),
+            logFields: { engineQueries: response.engineQueries, rowsFetched: response.rowsFetched },
+        };
+    }));
+    server.registerTool("get_page", {
+        title: "Read a page",
+        description: describeType("Returns one page whole, with its provenance header first: path, type, status, trust tier, verifier, recheck date and deprecation. Reserved files (index.md, log.md) are served too. A long page is cut at the result budget and says where to continue."),
+        inputSchema: z.object({
+            path: z
+                .string()
+                .min(1)
+                .max(1024)
+                .describe("The page's path in the bundle, as a search result or a catalog lists it."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Continue a long page from this character offset."),
+        }),
+        outputSchema: PageOutputSchema,
+        annotations: { readOnlyHint: true },
+    }, guarded("get_page", (args, generation) => {
+        const stop = refused(generation);
+        if (stop !== undefined)
+            return stop;
+        const path = normalisePath(args.path);
+        const offset = args.offset ?? 0;
+        const page = generation.catalog.pages.get(path);
+        if (page !== undefined) {
+            const output = projectPage(page, clock(), offset, options.resultBudget);
+            return ok(pageText(output), output);
+        }
+        const reserved = reservedAt(generation.catalog, path);
+        if (reserved !== undefined) {
+            const output = projectReserved(reserved.file, reserved.source, offset, options.resultBudget);
+            return ok(pageText(output), output);
+        }
+        const nearest = nearestPaths(servedPaths(generation.catalog), path);
+        return fail(`no page at ${JSON.stringify(safe(path))}; the nearest served paths are: ${nearest.map(safe).join(", ") || "(none)"}`);
+    }));
+    server.registerTool("catalog", {
+        title: "List a folder of the bundle",
+        description: describeType("Returns a folder's index: its pages with their titles and descriptions, and the folder's index text as the company wrote it or as the server generated it. Start here, at the root, to see what exists."),
+        inputSchema: z.object({
+            folder: z
+                .string()
+                .max(1024)
+                .optional()
+                .describe("A folder of the bundle; omit for the root."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Continue a long index from this character offset."),
+        }),
+        outputSchema: CatalogOutputSchema,
+        annotations: { readOnlyHint: true },
+    }, guarded("catalog", (args, generation) => {
+        const stop = refused(generation);
+        if (stop !== undefined)
+            return stop;
+        const folder = normaliseFolder(args.folder ?? "");
+        const output = projectCatalog(generation.catalog, folder, args.offset ?? 0, options.resultBudget);
+        if (output === undefined) {
+            return fail(`there is no folder ${JSON.stringify(safe(folder))}; the folders are: ${folderList(generation.catalog)}`);
+        }
+        const tail = output.truncated && output.nextOffset !== undefined
+            ? `\n[truncated at the result budget; continue with offset ${output.nextOffset}]`
+            : "";
+        const head = `catalog of ${folder === "" ? "the bundle root" : safe(folder)} (${output.source} index, ${output.entries.length} pages)`;
+        return ok(`${head}\n${output.notice}\n${output.text}${tail}`, output);
+    }));
+    server.registerTool("status", {
+        title: "Report the bundle's state",
+        description: describeType("Reports what was loaded: counts of pages admitted, refused and degraded, the lists the report carries, the integrity mode, the engine's counts and the lock. Nothing in it is page text."),
+        inputSchema: z.object({}),
+        outputSchema: StatusOutputSchema,
+        annotations: { readOnlyHint: true },
+    }, guarded("status", (_args, generation) => {
+        const output = projectStatus(generation, runtime.status(), options, clock());
+        return ok(statusSummary(output), output);
+    }));
+}
+//# sourceMappingURL=tools.js.map