zam-core 0.11.1 → 0.12.0

package/dist/cli/commands/mcp.js

@@ -8352,7 +8352,7 @@ async function prepareRecallChain(db, opts) {
       } else {
         spawnLocalRunner(endpoint.url, endpoint.model, endpoint.runner);
         while (Date.now() < deadline) {
-          await new Promise((resolve7) => setTimeout(resolve7, 1e3));
+          await new Promise((resolve8) => setTimeout(resolve8, 1e3));
           if (await isLlmOnline(endpoint.url)) {
             online = true;
             break;
@@ -8645,7 +8645,7 @@ async function startLocalRunner(url, model, locale, hint) {
   let attempts = 0;
   const dotsPerLine = 30;
   while (true) {
-    await new Promise((resolve7) => setTimeout(resolve7, 500));
+    await new Promise((resolve8) => setTimeout(resolve8, 500));
     if (await isLlmOnline(url)) {
       if (attempts > 0) process.stdout.write("\n");
       return true;
@@ -8734,8 +8734,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
   const dotsPerLine = 30;
   while (true) {
     let timeoutId;
-    const timeoutPromise = new Promise((resolve7) => {
-      timeoutId = setTimeout(() => resolve7("timeout"), timeoutMs);
+    const timeoutPromise = new Promise((resolve8) => {
+      timeoutId = setTimeout(() => resolve8("timeout"), timeoutMs);
     });
     const dotsInterval = setInterval(() => {
       process.stdout.write(".");
@@ -8989,10 +8989,272 @@ var init_client = __esm({
   }
 });
 
+// src/cli/okf/bundle.ts
+var bundle_exports = {};
+__export(bundle_exports, {
+  OKF_VERSION: () => OKF_VERSION,
+  RESERVED_FILES: () => RESERVED_FILES,
+  appendLog: () => appendLog,
+  buildCatalog: () => buildCatalog,
+  isReservedFile: () => isReservedFile,
+  parseFrontmatter: () => parseFrontmatter,
+  renderIndex: () => renderIndex,
+  toCatalogEntry: () => toCatalogEntry,
+  validateArticle: () => validateArticle
+});
+function isReservedFile(file) {
+  return RESERVED_FILES.includes(file);
+}
+function unquote(raw) {
+  const v = raw.trim();
+  if (v.length >= 2 && (v.startsWith('"') && v.endsWith('"') || v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+function parseFrontmatter(markdown) {
+  const lines = markdown.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    throw new Error("frontmatter: file must start with a --- fence");
+  }
+  const fields = {};
+  let listKey = null;
+  let i = 1;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "---") break;
+    if (line.trim() === "") continue;
+    const listItem = /^\s+-\s+(.+)$/.exec(line);
+    if (listItem) {
+      if (!listKey) {
+        throw new Error(`frontmatter line ${i + 1}: list item without a key`);
+      }
+      fields[listKey].push(unquote(listItem[1]));
+      continue;
+    }
+    const pair = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+    if (!pair) {
+      throw new Error(
+        `frontmatter line ${i + 1}: expected "key: value" or "- item"`
+      );
+    }
+    const key = pair[1];
+    const rest = pair[2].trim();
+    if (rest === "") {
+      fields[key] = [];
+      listKey = key;
+    } else {
+      fields[key] = unquote(rest);
+      listKey = null;
+    }
+  }
+  if (i >= lines.length) {
+    throw new Error("frontmatter: missing closing --- fence");
+  }
+  return { fields, body: lines.slice(i + 1).join("\n") };
+}
+function scalar(fields, key) {
+  const v = fields[key];
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : void 0;
+}
+function validateArticle(file, markdown) {
+  const problems = [];
+  if (isReservedFile(file)) {
+    return { ok: false, problems: [`${file}: reserved OKF file name`] };
+  }
+  if (!FILE_NAME_RE.test(file)) {
+    problems.push(`${file}: file name must be kebab-case and end in .md`);
+  }
+  let parsed = null;
+  try {
+    parsed = parseFrontmatter(markdown);
+  } catch (err) {
+    problems.push(
+      `${file}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed) {
+    if (!scalar(parsed.fields, "type")) {
+      problems.push(`${file}: frontmatter field "type" is required`);
+    }
+    if (!scalar(parsed.fields, "description")) {
+      problems.push(`${file}: frontmatter field "description" is required`);
+    }
+    if (parsed.body.trim() === "") {
+      problems.push(`${file}: article body is empty`);
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+function toCatalogEntry(file, markdown) {
+  const { fields } = parseFrontmatter(markdown);
+  const tags = Array.isArray(fields.tags) ? fields.tags : [];
+  return {
+    file,
+    type: scalar(fields, "type") ?? "",
+    title: scalar(fields, "title") ?? file.replace(/\.md$/, ""),
+    description: scalar(fields, "description") ?? "",
+    tags,
+    resource: scalar(fields, "resource"),
+    timestamp: scalar(fields, "timestamp")
+  };
+}
+function buildCatalog(articles) {
+  return articles.map(({ file, markdown }) => toCatalogEntry(file, markdown)).sort((a, b) => a.file.localeCompare(b.file));
+}
+function renderIndex(catalog, okfVersion = OKF_VERSION) {
+  const types = [...new Set(catalog.map((e) => e.type))].sort();
+  const sections = types.map((type) => {
+    const rows = catalog.filter((e) => e.type === type).map((e) => `- [${e.title}](${e.file}) \u2014 ${e.description}`).join("\n");
+    return `## ${type}
+
+${rows}`;
+  });
+  return [
+    "---",
+    `okf_version: "${okfVersion}"`,
+    "---",
+    "",
+    "# ZAM Knowledge Base",
+    "",
+    "Living reference knowledge for this repository in",
+    "[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog).",
+    "Current truth only \u2014 the *why* behind it lives in [../adr/](../adr/)",
+    "(ADR 2026-07-17). Do not edit by hand: write through the",
+    "`zam_okf_upsert` MCP tool.",
+    "",
+    sections.join("\n\n"),
+    ""
+  ].join("\n");
+}
+function appendLog(existing, date, line) {
+  const header = `## ${date}`;
+  const entry = `- ${line}`;
+  const trimmed = existing.trim();
+  if (trimmed === "") {
+    return `# Log
+
+${header}
+
+${entry}
+`;
+  }
+  const lines = trimmed.split("\n");
+  const firstHeaderIdx = lines.findIndex((l) => l.startsWith("## "));
+  if (firstHeaderIdx !== -1 && lines[firstHeaderIdx].trim() === header) {
+    lines.splice(firstHeaderIdx + 2, 0, entry);
+    return `${lines.join("\n")}
+`;
+  }
+  const insertAt = firstHeaderIdx === -1 ? lines.length : firstHeaderIdx;
+  lines.splice(insertAt, 0, header, "", entry, "");
+  return `${lines.join("\n")}
+`;
+}
+var OKF_VERSION, RESERVED_FILES, FILE_NAME_RE;
+var init_bundle = __esm({
+  "src/cli/okf/bundle.ts"() {
+    "use strict";
+    OKF_VERSION = "0.1";
+    RESERVED_FILES = ["index.md", "log.md"];
+    FILE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+  }
+});
+
+// src/cli/okf/io.ts
+var io_exports = {};
+__export(io_exports, {
+  DEFAULT_BUNDLE_DIR: () => DEFAULT_BUNDLE_DIR,
+  loadBundle: () => loadBundle,
+  resolveArticlePath: () => resolveArticlePath,
+  upsertArticle: () => upsertArticle
+});
+import { mkdirSync as mkdirSync16, readdirSync as readdirSync3, readFileSync as readFileSync18, writeFileSync as writeFileSync13 } from "fs";
+import { join as join24, resolve as resolve7 } from "path";
+function resolveArticlePath(dir, file) {
+  if (file.includes("/") || file.includes("\\") || file.includes("..")) {
+    throw new Error(`invalid article file name: ${file}`);
+  }
+  if (isReservedFile(file)) {
+    throw new Error(`refusing to address reserved file: ${file}`);
+  }
+  return join24(resolve7(dir), file);
+}
+function loadBundle(dir) {
+  const root = resolve7(dir);
+  let entries;
+  try {
+    entries = readdirSync3(root).filter(
+      (name) => name.endsWith(".md") && !isReservedFile(name)
+    );
+  } catch {
+    throw new Error(`OKF bundle directory not found: ${root}`);
+  }
+  const articles = entries.sort().map((file) => ({
+    file,
+    markdown: readFileSync18(join24(root, file), "utf8")
+  }));
+  const problems = articles.flatMap(
+    ({ file, markdown }) => validateArticle(file, markdown).problems
+  );
+  const catalog = problems.length === 0 ? buildCatalog(articles) : safeCatalog(articles);
+  return { dir: root, articles, catalog, problems };
+}
+function safeCatalog(articles) {
+  const entries = [];
+  for (const { file, markdown } of articles) {
+    try {
+      entries.push(toCatalogEntry(file, markdown));
+    } catch {
+    }
+  }
+  return entries.sort((a, b) => a.file.localeCompare(b.file));
+}
+function upsertArticle(dir, file, markdown, today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)) {
+  const target = resolveArticlePath(dir, file);
+  const validation = validateArticle(file, markdown);
+  if (!validation.ok) return { validation };
+  const root = resolve7(dir);
+  mkdirSync16(root, { recursive: true });
+  let created = true;
+  try {
+    readFileSync18(target, "utf8");
+    created = false;
+  } catch {
+  }
+  writeFileSync13(target, markdown, "utf8");
+  const bundle = loadBundle(root);
+  writeFileSync13(join24(root, "index.md"), renderIndex(bundle.catalog), "utf8");
+  let log = "";
+  try {
+    log = readFileSync18(join24(root, "log.md"), "utf8");
+  } catch {
+  }
+  const entry = bundle.catalog.find((e) => e.file === file);
+  writeFileSync13(
+    join24(root, "log.md"),
+    appendLog(
+      log,
+      today,
+      `**${created ? "Creation" : "Update"}** \u2014 [${entry?.title ?? file}](${file})`
+    ),
+    "utf8"
+  );
+  return { validation, entry, created };
+}
+var DEFAULT_BUNDLE_DIR;
+var init_io = __esm({
+  "src/cli/okf/io.ts"() {
+    "use strict";
+    init_bundle();
+    DEFAULT_BUNDLE_DIR = "docs/okf";
+  }
+});
+
 // src/cli/commands/mcp.ts
 init_kernel();
-import { existsSync as existsSync21, readFileSync as readFileSync18 } from "fs";
-import { dirname as dirname11, join as join24 } from "path";
+import { existsSync as existsSync21, readFileSync as readFileSync19 } from "fs";
+import { dirname as dirname11, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import {
   RESOURCE_MIME_TYPE,
@@ -11636,7 +11898,7 @@ async function readWebLink(url) {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "User-Agent": "ZAM-Content-Studio/0.11.1"
+          "User-Agent": "ZAM-Content-Studio/0.12.0"
         }
       });
       if (res.status >= 300 && res.status < 400) {
@@ -28964,25 +29226,25 @@ async function observeUiSnapshotViaLLM(db, input) {
   const imageUrls = [];
   const isVideo = /\.(mp4|mov|m4v|avi|mkv|webm)$/i.test(input.imagePath);
   if (isVideo) {
-    const { mkdirSync: mkdirSync16, readdirSync: readdirSync3, rmSync: rmSync4 } = await import("fs");
+    const { mkdirSync: mkdirSync17, readdirSync: readdirSync4, rmSync: rmSync4 } = await import("fs");
     const { execSync: execSync5 } = await import("child_process");
     const tempDir = join20(
       tmpdir2(),
       `zam-frames-${randomBytes(4).toString("hex")}`
     );
-    mkdirSync16(tempDir, { recursive: true });
+    mkdirSync17(tempDir, { recursive: true });
     try {
       execSync5(
         `ffmpeg -i "${input.imagePath}" -vf "fps=1/3,scale=1280:-1" -vsync vfr "${tempDir}/frame_%03d.png"`,
         { stdio: "ignore" }
       );
-      let files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+      let files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
       if (files.length === 0) {
         execSync5(
           `ffmpeg -i "${input.imagePath}" -vframes 1 "${tempDir}/frame_001.png"`,
           { stdio: "ignore" }
         );
-        files = readdirSync3(tempDir).filter((f) => f.endsWith(".png")).sort();
+        files = readdirSync4(tempDir).filter((f) => f.endsWith(".png")).sort();
       }
       const maxFrames = cfg.maxFrames ?? 100;
       let sampledFiles = files;
@@ -30801,7 +31063,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
   const defaultExt = platform === "win32" ? ".mkv" : ".mov";
   const outputPath = opts.output ?? join22(tmpdir3(), `zam-recording-${sessionId}${defaultExt}`);
-  const { existsSync: existsSync22, writeFileSync: writeFileSync13, openSync, closeSync } = await import("fs");
+  const { existsSync: existsSync22, writeFileSync: writeFileSync14, openSync, closeSync } = await import("fs");
   if (existsSync22(statePath)) {
     jsonOut({
       sessionId,
@@ -30856,7 +31118,7 @@ bridgeCommand.command("start-recording").description("Start screen recording in
   }
   child.unref();
   if (child.pid) {
-    writeFileSync13(
+    writeFileSync14(
       statePath,
       JSON.stringify({
         pid: child.pid,
@@ -30893,7 +31155,7 @@ bridgeCommand.command("stop-recording").description(
   }
   const sessionId = opts.session;
   const statePath = join22(tmpdir3(), `zam-recording-${sessionId}.json`);
-  const { existsSync: existsSync22, readFileSync: readFileSync19, rmSync: rmSync4 } = await import("fs");
+  const { existsSync: existsSync22, readFileSync: readFileSync20, rmSync: rmSync4 } = await import("fs");
   if (!existsSync22(statePath)) {
     jsonOut({
       sessionId,
@@ -30902,7 +31164,7 @@ bridgeCommand.command("stop-recording").description(
     });
     return;
   }
-  const state = JSON.parse(readFileSync19(statePath, "utf8"));
+  const state = JSON.parse(readFileSync20(statePath, "utf8"));
   const { pid, outputPath } = state;
   try {
     process.kill(pid, "SIGINT");
@@ -30918,7 +31180,7 @@ bridgeCommand.command("stop-recording").description(
   };
   let attempts = 0;
   while (isProcessRunning(pid) && attempts < 20) {
-    await new Promise((resolve7) => setTimeout(resolve7, 250));
+    await new Promise((resolve8) => setTimeout(resolve8, 250));
     attempts++;
   }
   if (isProcessRunning(pid)) {
@@ -33556,11 +33818,11 @@ async function publishUiIntent(app, input = {}, opts = {}) {
 
 // src/cli/commands/mcp.ts
 var __dirname = dirname11(fileURLToPath6(import.meta.url));
-var pkgPath = join24(__dirname, "..", "..", "package.json");
+var pkgPath = join25(__dirname, "..", "..", "package.json");
 if (!existsSync21(pkgPath)) {
-  pkgPath = join24(__dirname, "..", "..", "..", "package.json");
+  pkgPath = join25(__dirname, "..", "..", "..", "package.json");
 }
-var pkg = JSON.parse(readFileSync18(pkgPath, "utf-8"));
+var pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
 var STUDIO_RESOURCE_URI = "ui://zam/studio";
 var RECALL_RESOURCE_URI = "ui://zam/recall";
 var GRAPH_RESOURCE_URI = "ui://zam/graph";
@@ -33587,13 +33849,13 @@ var STUDIO_BRIDGE_ALLOWED_COMMANDS = /* @__PURE__ */ new Set([
 function loadPanelHtml(fileName, placeholderTitle) {
   const candidates = [
     // dist/cli/commands/mcp.js → dist/ui/
-    join24(__dirname, "..", "..", "ui", fileName),
+    join25(__dirname, "..", "..", "ui", fileName),
     // src/cli/commands/mcp.ts via tsx → <repo>/dist/ui/
-    join24(__dirname, "..", "..", "..", "dist", "ui", fileName)
+    join25(__dirname, "..", "..", "..", "dist", "ui", fileName)
   ];
   for (const candidate of candidates) {
     if (existsSync21(candidate)) {
-      return readFileSync18(candidate, "utf-8");
+      return readFileSync19(candidate, "utf-8");
     }
   }
   return `<!doctype html>
@@ -34358,6 +34620,87 @@ function createMcpServer(db) {
       }
     )
   );
+  const okfBundleDirSchema = z.string().optional().describe("Bundle directory (default docs/okf under the server cwd)");
+  server.registerTool(
+    "zam_okf_catalog",
+    {
+      description: "List the OKF knowledge-base articles (type, title, description, tags, resource URL) plus conformance problems, if any",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    wrapHandler(async (params) => {
+      const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, loadBundle: loadBundle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+      const bundle = loadBundle2(params.bundle_dir ?? DEFAULT_BUNDLE_DIR2);
+      return {
+        dir: bundle.dir,
+        articles: bundle.catalog,
+        problems: bundle.problems
+      };
+    })
+  );
+  server.registerTool(
+    "zam_okf_read",
+    {
+      description: "Read one OKF knowledge-base article: raw markdown plus parsed frontmatter",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema,
+        file: z.string().describe("Article file name, e.g. fsrs-scheduling.md")
+      },
+      annotations: {
+        ...commonAnnotations,
+        readOnlyHint: true
+      }
+    },
+    wrapHandler(async (params) => {
+      const { readFileSync: readFileSync20 } = await import("fs");
+      const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, resolveArticlePath: resolveArticlePath2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+      const { parseFrontmatter: parseFrontmatter2 } = await Promise.resolve().then(() => (init_bundle(), bundle_exports));
+      const path = resolveArticlePath2(
+        params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+        params.file
+      );
+      const markdown = readFileSync20(path, "utf8");
+      const { fields } = parseFrontmatter2(markdown);
+      return { file: params.file, frontmatter: fields, markdown };
+    })
+  );
+  server.registerTool(
+    "zam_okf_upsert",
+    {
+      description: "Create or update an OKF knowledge-base article through the validated write path: checks the frontmatter contract, regenerates index.md, and appends the log.md entry. Never edit bundle files directly.",
+      inputSchema: {
+        bundle_dir: okfBundleDirSchema,
+        file: z.string().describe(
+          "Kebab-case article file name ending in .md (permanent ID)"
+        ),
+        markdown: z.string().describe(
+          "Full article: --- frontmatter (type, title, description, tags, resource, timestamp) then the body"
+        )
+      },
+      annotations: {
+        ...commonAnnotations
+      }
+    },
+    wrapHandler(
+      async (params) => {
+        const { DEFAULT_BUNDLE_DIR: DEFAULT_BUNDLE_DIR2, upsertArticle: upsertArticle2 } = await Promise.resolve().then(() => (init_io(), io_exports));
+        const result = upsertArticle2(
+          params.bundle_dir ?? DEFAULT_BUNDLE_DIR2,
+          params.file,
+          params.markdown
+        );
+        if (!result.validation.ok) {
+          return { ok: false, problems: result.validation.problems };
+        }
+        return { ok: true, created: result.created, entry: result.entry };
+      }
+    )
+  );
   return server;
 }
 async function runMcpServer() {