@dikolab/kbdb 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,3537 @@
+import {
+  computeSha256,
+  detectRuntime,
+  getArgs,
+  getIpcPath,
+  resolveBaseDir,
+  resolveWorkerScript
+} from "./chunk-QCCN7OZH.mjs";
+
+// src/shared/cli/constants/defaults.constant.ts
+var DEFAULT_LIMIT = 20;
+var DEFAULT_FORMAT = "json";
+var DEFAULT_MODE = "sections";
+var SUPPORTED_EXTENSIONS = [
+  ".md",
+  ".txt",
+  ".rst",
+  ".adoc"
+];
+
+// src/shared/cli/functions/parse-args.function.ts
+function parseArgs(argv) {
+  const options = {
+    command: "",
+    format: DEFAULT_FORMAT,
+    mode: DEFAULT_MODE,
+    limit: DEFAULT_LIMIT,
+    args: []
+  };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        if (options.command) {
+          options.args.unshift(options.command);
+          options.command = "help";
+        } else {
+          options.command = "help";
+        }
+        return options;
+      case "--version":
+      case "-v":
+        options.command = "version";
+        return options;
+      case "--init":
+        console.error(
+          'warning: --init is deprecated, use "kbdb db init"'
+        );
+        options.command = "init";
+        break;
+      case "--migrate":
+        console.error(
+          'warning: --migrate is deprecated, use "kbdb db migrate"'
+        );
+        options.command = "migrate";
+        break;
+      case "--db":
+        options.dbPath = argv[++i];
+        break;
+      case "--format":
+      case "-f":
+        options.format = argv[++i] ?? DEFAULT_FORMAT;
+        break;
+      case "--mode":
+      case "-m":
+        options.mode = argv[++i] ?? DEFAULT_MODE;
+        break;
+      case "--limit":
+      case "-l":
+        options.limit = parseInt(argv[++i] ?? "", 10) || DEFAULT_LIMIT;
+        break;
+      case "--title":
+        options.title = argv[++i];
+        break;
+      case "--description":
+        options.description = argv[++i];
+        break;
+      case "--docid":
+        options.docid = argv[++i];
+        break;
+      case "--name":
+        options.name = argv[++i];
+        break;
+      case "--persona":
+        options.persona = argv[++i];
+        break;
+      case "--body":
+        options.body = argv[++i];
+        break;
+      case "--skills":
+        options.skills = (argv[++i] ?? "").split(",");
+        break;
+      case "--content":
+      case "-c":
+        options.content = true;
+        break;
+      default:
+        if (!options.command) {
+          options.command = arg;
+        } else if (!options.args.length && (options.command === "db" || options.command === "skill" || options.command === "agent")) {
+          options.command = `${options.command}-${arg}`;
+        } else {
+          options.args.push(arg);
+        }
+    }
+    i++;
+  }
+  return options;
+}
+
+// src/shared/cli/functions/format-output.function.ts
+function formatOutput(results, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(results, null, 2);
+    case "text":
+      return formatText(results);
+    case "mcp":
+      return formatMcp(results);
+  }
+}
+function formatText(results) {
+  if (results.length === 0) return "No results found.";
+  return results.map(
+    (r, i) => `${String(i + 1)}. [${r.kbid}] (score: ${r.score.toFixed(4)})
+   ${r.preview}
+   matches: ${r.matches.map((m) => m.term).join(", ")}`
+  ).join("\n\n");
+}
+function formatMcp(results) {
+  return JSON.stringify({
+    type: "text",
+    text: results.map(
+      (r) => `[${r.kbid}] score=${r.score.toFixed(4)} \u2014 ${r.preview}`
+    ).join("\n")
+  });
+}
+
+// src/shared/cli/functions/run-search.function.ts
+async function runSearch(client, options) {
+  const query = options.args.join(" ").trim();
+  if (!query) return [];
+  const results = await client.search({
+    query,
+    mode: options.mode,
+    limit: options.limit
+  });
+  return results.map((r) => ({
+    kbid: r.kbid,
+    score: r.score,
+    preview: "",
+    matches: r.matches
+  }));
+}
+
+// src/shared/cli/functions/run-learn.function.ts
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+async function runLearn(client, options, io) {
+  const results = [];
+  let stdinConsumed = false;
+  const readStdin = io?.readStdin ?? readProcessStdin;
+  for (const target of options.args) {
+    if (target === "-") {
+      if (stdinConsumed) continue;
+      stdinConsumed = true;
+      const content = await readStdin();
+      const result = await client.addSection({
+        sectionType: "text",
+        content,
+        title: options.title,
+        description: options.description,
+        docid: options.docid
+      });
+      results.push({
+        kbid: result.kbid,
+        path: "-",
+        size: content.length,
+        skipped: false
+      });
+      continue;
+    }
+    const files = collectFiles(target);
+    for (const file of files) {
+      const content = readFileSync(file, "utf-8");
+      const result = await client.addSection({
+        sectionType: "text",
+        content,
+        title: options.title,
+        docid: options.docid
+      });
+      results.push({
+        kbid: result.kbid,
+        path: file,
+        size: content.length,
+        skipped: false
+      });
+    }
+  }
+  return results;
+}
+function readProcessStdin() {
+  return new Promise((resolve4) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    process.stdin.on("end", () => {
+      resolve4(Buffer.concat(chunks).toString("utf-8"));
+    });
+    process.stdin.resume();
+  });
+}
+function collectFiles(target) {
+  try {
+    const stat = statSync(target);
+    if (stat.isFile()) {
+      return isSupportedFile(target) ? [target] : [];
+    }
+    if (stat.isDirectory()) {
+      return scanDirectory(target);
+    }
+  } catch {
+  }
+  return [];
+}
+function scanDirectory(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir)) {
+    if (entry.startsWith(".")) continue;
+    const full = join(dir, entry);
+    try {
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        files.push(...scanDirectory(full));
+      } else if (isSupportedFile(full)) {
+        files.push(full);
+      }
+    } catch {
+    }
+  }
+  return files;
+}
+function isSupportedFile(path) {
+  if (basename(path).startsWith(".")) return false;
+  const ext = extname(path).toLowerCase();
+  return SUPPORTED_EXTENSIONS.includes(ext);
+}
+
+// src/shared/cli/functions/run-unlearn.function.ts
+async function runUnlearn(client, options) {
+  const results = [];
+  for (const kbid of options.args) {
+    const result = await client.removeSection(kbid);
+    results.push({ kbid, removed: result.removed });
+  }
+  return results;
+}
+
+// src/shared/cli/functions/run-content.function.ts
+async function runContent(client, options) {
+  return client.content(options.args);
+}
+
+// src/shared/cli/functions/run-check.function.ts
+async function runCheck(client, _options) {
+  return client.integrityCheck();
+}
+
+// src/shared/cli/functions/run-gc.function.ts
+async function runGc(client, _options) {
+  return client.gc();
+}
+
+// src/shared/cli/functions/run-rebuild.function.ts
+async function runRebuild(client, _options) {
+  return client.rebuildIndexes();
+}
+
+// src/shared/cli/functions/find-db.function.ts
+import { existsSync } from "node:fs";
+import { join as join2, resolve } from "node:path";
+function findDb(dbPath) {
+  const base = dbPath ? resolve(dbPath) : process.cwd();
+  const kbdbDir = join2(base, ".kbdb");
+  return existsSync(kbdbDir) ? kbdbDir : null;
+}
+
+// src/shared/cli/functions/run-init.function.ts
+import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
+import { join as join3, resolve as resolve2 } from "node:path";
+var DB_FORMAT_VERSION = 1;
+var CATALOG_TOML = `version = ${DB_FORMAT_VERSION.toString()}
+section_count = 0
+document_count = 0
+created_at = 0
+updated_at = 0
+checksum = ""
+`;
+var WORKER_TOML = "# kbdb worker configuration\n";
+var GITIGNORE = [
+  "# kbdb binary indexes (auto-generated)",
+  "corpus.bin",
+  "inverted.idx",
+  "positional.idx",
+  ""
+].join("\n");
+function createScaffold(dbDir) {
+  mkdirSync(dbDir, { recursive: true });
+  mkdirSync(join3(dbDir, "sections"));
+  mkdirSync(join3(dbDir, "documents"));
+  writeFileSync(join3(dbDir, "catalog.toml"), CATALOG_TOML);
+  writeFileSync(join3(dbDir, "corpus.bin"), "");
+  writeFileSync(join3(dbDir, "inverted.idx"), "");
+  writeFileSync(join3(dbDir, "positional.idx"), "");
+  writeFileSync(join3(dbDir, "worker.toml"), WORKER_TOML);
+  writeFileSync(join3(dbDir, ".gitignore"), GITIGNORE);
+}
+function runInit(options) {
+  const basePath = options.dbPath ? resolve2(options.dbPath) : process.cwd();
+  const dbDir = join3(basePath, ".kbdb");
+  try {
+    if (existsSync2(dbDir)) {
+      return {
+        ok: false,
+        targetPath: dbDir,
+        errorMessage: `database directory already exists: ${dbDir}`
+      };
+    }
+    createScaffold(dbDir);
+    return { ok: true, targetPath: dbDir };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    return { ok: false, targetPath: dbDir, errorMessage };
+  }
+}
+
+// src/shared/cli/functions/error-to-message.function.ts
+function errorToMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/shared/cli/functions/is-stdin-tty.function.ts
+function isStdinTty(stdin = process.stdin) {
+  return stdin.isTTY ?? false;
+}
+
+// src/shared/cli/functions/prompt-user.function.ts
+import { createInterface } from "node:readline";
+async function promptUser(question, io) {
+  const ask = io?.ask ?? askReadline;
+  const answer = await ask(question);
+  return answer.trim();
+}
+function askReadline(question) {
+  return new Promise((resolve4) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve4(answer);
+    });
+  });
+}
+
+// src/shared/cli/functions/run-status.function.ts
+async function runStatus(client, _options) {
+  return client.dbStatus();
+}
+
+// src/shared/cli/functions/run-db-init.function.ts
+function runDbInit(options, runInitFn) {
+  const result = runInitFn(options);
+  if (result.ok) {
+    return {
+      output: JSON.stringify(
+        { path: result.targetPath, created: true },
+        null,
+        2
+      ),
+      exitCode: 0
+    };
+  }
+  return {
+    error: result.errorMessage ?? "init failed",
+    exitCode: 1
+  };
+}
+
+// src/shared/cli/functions/run-db-migrate.function.ts
+async function runDbMigrate(client, options) {
+  const dbPath = options.dbPath ?? process.cwd();
+  return client.migrateDatabase(dbPath);
+}
+
+// src/shared/mcp/functions/extract-skill-arguments.function.ts
+function extractSkillArguments(body) {
+  const seen = /* @__PURE__ */ new Set();
+  const args = [];
+  const re = /\{\{(\w+)\}\}/g;
+  let match;
+  while ((match = re.exec(body)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      args.push({ name, required: true });
+    }
+  }
+  return args;
+}
+
+// src/shared/mcp/functions/serialize-skill-content.function.ts
+function serializeSkillContent(skill) {
+  return JSON.stringify(skill);
+}
+
+// src/shared/cli/functions/run-skill-learn.function.ts
+async function runSkillLearn(client, options) {
+  const name = options.name;
+  if (!name) {
+    return { error: "--name is required", exitCode: 1 };
+  }
+  const body = options.body;
+  if (!body) {
+    return { error: "--body is required", exitCode: 1 };
+  }
+  const args = extractSkillArguments(body);
+  const skill = {
+    name,
+    description: options.description,
+    arguments: args.length > 0 ? args : void 0,
+    body
+  };
+  const json = serializeSkillContent(skill);
+  const result = await client.addSection({
+    sectionType: "skill",
+    content: json,
+    title: name,
+    description: options.description
+  });
+  return {
+    output: JSON.stringify(result, null, 2),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-skill-list.function.ts
+async function runSkillList(client, _options) {
+  const records = await client.listByType("skill");
+  const items = records.map((r) => {
+    let argumentCount = 0;
+    try {
+      const parsed = JSON.parse(r.content);
+      if (Array.isArray(parsed["arguments"])) {
+        argumentCount = parsed["arguments"].length;
+      }
+    } catch {
+    }
+    return {
+      kbid: r.kbid,
+      name: r.title,
+      description: r.description,
+      argumentCount
+    };
+  });
+  return {
+    output: JSON.stringify(items, null, 2),
+    exitCode: 0
+  };
+}
+
+// src/shared/mcp/functions/parse-skill-content.function.ts
+function parseSkillContent(json) {
+  const raw = JSON.parse(json);
+  if (typeof raw["name"] !== "string" || !raw["name"]) {
+    throw new Error("skill name is required");
+  }
+  if (typeof raw["body"] !== "string") {
+    throw new Error("skill body is required");
+  }
+  return {
+    name: raw["name"],
+    description: typeof raw["description"] === "string" ? raw["description"] : void 0,
+    arguments: Array.isArray(raw["arguments"]) ? raw["arguments"] : void 0,
+    body: raw["body"]
+  };
+}
+
+// src/shared/cli/functions/run-skill-get.function.ts
+async function runSkillGet(client, options) {
+  const identifier = options.args[0] ?? options.name;
+  if (!identifier) {
+    return {
+      error: "skill name or kbid required",
+      exitCode: 1
+    };
+  }
+  let content;
+  if (/^[0-9a-f]{16,}$/i.test(identifier)) {
+    const sections = await client.readSections([identifier]);
+    if (sections.length > 0) {
+      content = sections[0]?.content;
+    }
+  }
+  if (content === void 0) {
+    const records = await client.listByType("skill");
+    const match = records.filter((r) => r.title === identifier).pop();
+    if (match) {
+      content = match.content;
+    }
+  }
+  if (content === void 0) {
+    return {
+      error: `skill not found: ${identifier}`,
+      exitCode: 1
+    };
+  }
+  const skill = parseSkillContent(content);
+  return {
+    output: JSON.stringify(skill, null, 2),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-skill-delete.function.ts
+async function runSkillDelete(client, options) {
+  const kbid = options.args[0];
+  if (!kbid) {
+    return { error: "kbid is required", exitCode: 1 };
+  }
+  const result = await client.removeSection(kbid);
+  return {
+    output: JSON.stringify(
+      { kbid, removed: result.removed },
+      null,
+      2
+    ),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-agent-create.function.ts
+async function runAgentCreate(client, options) {
+  const name = options.name;
+  if (!name) {
+    return { error: "--name is required", exitCode: 1 };
+  }
+  const persona = options.persona;
+  if (!persona) {
+    return { error: "--persona is required", exitCode: 1 };
+  }
+  const skills = options.skills ?? [];
+  if (skills.length > 0) {
+    const sections = await client.readSections(skills);
+    const found = new Set(sections.map((s) => s.kbid));
+    const missing = skills.filter((k) => !found.has(k));
+    if (missing.length > 0) {
+      return {
+        error: `skill not found: ${missing.join(", ")}`,
+        exitCode: 1
+      };
+    }
+  }
+  const metadata = JSON.stringify({
+    name,
+    description: options.description ?? "",
+    persona
+  });
+  const metaResult = await client.addSection({
+    sectionType: "text",
+    content: metadata,
+    title: name,
+    description: options.description
+  });
+  const allKbids = [metaResult.kbid, ...skills];
+  const docid = await client.groupSections(name, allKbids, "agent");
+  return {
+    output: JSON.stringify(
+      { docid, name, skillCount: skills.length },
+      null,
+      2
+    ),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-agent-list.function.ts
+async function runAgentList(client, _options) {
+  const docs = await client.listDocumentsByType("agent");
+  const items = docs.map((d) => ({
+    docid: d.docid,
+    name: d.title,
+    skillCount: Math.max(0, d.sections.length - 1)
+  }));
+  return {
+    output: JSON.stringify(items, null, 2),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-agent-get.function.ts
+async function readAgentMeta(client, metaKbid, fallbackName) {
+  const sections = await client.readSections([metaKbid]);
+  const first = sections.at(0);
+  if (!first) {
+    return { name: fallbackName, description: "", persona: "" };
+  }
+  try {
+    const meta = JSON.parse(first.content);
+    return {
+      name: typeof meta["name"] === "string" ? meta["name"] : fallbackName,
+      description: typeof meta["description"] === "string" ? meta["description"] : "",
+      persona: typeof meta["persona"] === "string" ? meta["persona"] : ""
+    };
+  } catch {
+    return { name: fallbackName, description: "", persona: "" };
+  }
+}
+async function resolveSkills(client, skillRefs) {
+  if (skillRefs.length === 0) {
+    return [];
+  }
+  const kbids = skillRefs.map((r) => r.kbid);
+  const sections = await client.readSections(kbids);
+  const sectionMap = new Map(sections.map((s) => [s.kbid, s]));
+  return skillRefs.map((ref) => {
+    const sec = sectionMap.get(ref.kbid);
+    if (!sec) {
+      return { kbid: ref.kbid, name: null, position: ref.position };
+    }
+    try {
+      const parsed = JSON.parse(sec.content);
+      const skillName = typeof parsed["name"] === "string" ? parsed["name"] : null;
+      return {
+        kbid: ref.kbid,
+        name: skillName,
+        position: ref.position
+      };
+    } catch {
+      return { kbid: ref.kbid, name: null, position: ref.position };
+    }
+  });
+}
+async function runAgentGet(client, options) {
+  const docid = options.args[0];
+  if (!docid) {
+    return { error: "docid is required", exitCode: 1 };
+  }
+  const doc = await client.retrieveDocument(docid);
+  const metaKbid = doc.sections[0]?.kbid;
+  const skillRefs = doc.sections.slice(1);
+  const { name, description, persona } = metaKbid ? await readAgentMeta(client, metaKbid, doc.title) : { name: doc.title, description: "", persona: "" };
+  const skills = await resolveSkills(client, skillRefs);
+  return {
+    output: JSON.stringify(
+      { docid, name, description, persona, skills },
+      null,
+      2
+    ),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/run-agent-delete.function.ts
+async function runAgentDelete(client, options) {
+  const docid = options.args[0];
+  if (!docid) {
+    return { error: "docid is required", exitCode: 1 };
+  }
+  await client.removeGrouping(docid);
+  return {
+    output: JSON.stringify({ docid, removed: true }, null, 2),
+    exitCode: 0
+  };
+}
+
+// src/shared/cli/functions/dispatch-command.function.ts
+async function dispatchCommand(client, options, io) {
+  switch (options.command) {
+    case "learn":
+      return handleLearn(client, options, io);
+    case "unlearn":
+      return handleUnlearn(client, options);
+    case "search":
+      return handleSearch(client, options);
+    case "content":
+      return handleContent(client, options);
+    case "check":
+      return handleCheck(client, options);
+    case "gc":
+      return handleGc(client, options);
+    case "rebuild":
+      return handleRebuild(client, options);
+    case "status":
+      return handleStatus(client, options);
+    case "db-init":
+      return handleDbInit(options);
+    case "db-migrate":
+      return handleDbMigrate(client, options);
+    case "skill-learn": {
+      const result = await runSkillLearn(client, options);
+      return result;
+    }
+    case "skill-list": {
+      const result = await runSkillList(client, options);
+      return result;
+    }
+    case "skill-get": {
+      const result = await runSkillGet(client, options);
+      return result;
+    }
+    case "skill-delete": {
+      const result = await runSkillDelete(client, options);
+      return result;
+    }
+    case "agent-create": {
+      const result = await runAgentCreate(client, options);
+      return result;
+    }
+    case "agent-list": {
+      const result = await runAgentList(client, options);
+      return result;
+    }
+    case "agent-get": {
+      const result = await runAgentGet(client, options);
+      return result;
+    }
+    case "agent-delete": {
+      const result = await runAgentDelete(client, options);
+      return result;
+    }
+    default:
+      return {
+        error: `unknown command: ${options.command}`,
+        exitCode: 1
+      };
+  }
+}
+async function handleLearn(client, options, io) {
+  try {
+    const results = await runLearn(client, options, io);
+    return {
+      output: JSON.stringify(results, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `learn failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleUnlearn(client, options) {
+  try {
+    const results = await runUnlearn(client, options);
+    return {
+      output: JSON.stringify(results, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `unlearn failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleSearch(client, options) {
+  try {
+    const results = await runSearch(client, options);
+    if (options.content) {
+      await hydrateSearchPreviews(client, results);
+    }
+    return {
+      output: formatOutput(results, options.format),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `search failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleContent(client, options) {
+  try {
+    const result = await runContent(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `content failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleCheck(client, options) {
+  try {
+    const result = await runCheck(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: result.ok ? 0 : 1
+    };
+  } catch (err) {
+    return {
+      error: `check failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleGc(client, options) {
+  try {
+    const result = await runGc(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `gc failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleRebuild(client, options) {
+  try {
+    const result = await runRebuild(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `rebuild failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function handleStatus(client, options) {
+  try {
+    const result = await runStatus(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `status failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+function handleDbInit(options) {
+  return runDbInit(options, runInit);
+}
+async function handleDbMigrate(client, options) {
+  try {
+    const result = await runDbMigrate(client, options);
+    return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0
+    };
+  } catch (err) {
+    return {
+      error: `db-migrate failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+}
+async function hydrateSearchPreviews(client, results) {
+  await Promise.all(
+    results.map(async (result) => {
+      try {
+        const contentResult = await client.content([result.kbid]);
+        result.preview = contentResult.data;
+      } catch {
+      }
+    })
+  );
+}
+
+// src/shared/version/constants/version.constant.ts
+var VERSION = "0.1.0";
+
+// src/shared/cli/functions/generate-help.function.ts
+var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
+  "learn",
+  "unlearn",
+  "search",
+  "content",
+  "check",
+  "gc",
+  "rebuild",
+  "status",
+  "mcp",
+  "db",
+  "skill",
+  "agent"
+]);
+var GROUP_SUBCOMMANDS = {
+  db: [
+    ["init", "Initialise a new .kbdb directory"],
+    ["migrate", "Migrate database to current format"]
+  ],
+  skill: [
+    ["learn", "Create a new skill definition"],
+    ["list", "List all skills"],
+    ["get", "Retrieve a skill by name or kbid"],
+    ["delete", "Remove a skill"]
+  ],
+  agent: [
+    ["create", "Create an agent with skill refs"],
+    ["list", "List all agents"],
+    ["get", "Retrieve an agent by docid"],
+    ["delete", "Remove an agent"]
+  ]
+};
+function isKnownCommand(cmd) {
+  if (KNOWN_COMMANDS.has(cmd)) {
+    return true;
+  }
+  const dashIdx = cmd.indexOf("-");
+  if (dashIdx < 0) {
+    return false;
+  }
+  const group = cmd.slice(0, dashIdx);
+  return group in GROUP_SUBCOMMANDS;
+}
+function generateHelp(command, subcommand) {
+  if (!command) {
+    return generateGlobalHelp();
+  }
+  if (!subcommand && command.includes("-")) {
+    const dashIdx = command.indexOf("-");
+    const group = command.slice(0, dashIdx);
+    const sub = command.slice(dashIdx + 1);
+    if (group in GROUP_SUBCOMMANDS) {
+      return generateSubcommandHelp(group, sub);
+    }
+  }
+  if (subcommand) {
+    return generateSubcommandHelp(command, subcommand);
+  }
+  return generateCommandHelp(command);
+}
+function generateGlobalHelp() {
+  return `kbdb v${VERSION} - File-based knowledge base database for AI agents
+
+Usage: kbdb [options]
+       kbdb <command> [options] ...[parameters]
+       kbdb <command> <subcommand> [options] ...[params]
+
+Knowledge Base:
+   learn               Import content from files/stdin
+   unlearn             Remove sections by kbid
+   search              Query the knowledge base
+   content             Compose rendered content from ids
+
+Database:
+   db init             Initialise a new .kbdb directory
+   db migrate          Migrate database to current format
+
+Maintenance:
+   check               Verify knowledge base integrity
+   gc                  Garbage collect unreferenced
+                       sections
+   rebuild             Reconstruct all index files
+   status              Show database status
+
+Skills:
+   skill learn         Create a new skill definition
+   skill list          List all skills
+   skill get           Retrieve a skill by name or kbid
+   skill delete        Remove a skill
+
+Agents:
+   agent create        Create an agent with skill refs
+   agent list          List all agents
+   agent get           Retrieve an agent by docid
+   agent delete        Remove an agent
+
+Server:
+   mcp                 Start MCP server mode (stdio)
+
+Global Options:
+   -h, --help          Show this help message
+   -v, --version       Show version information
+   --db <path>         Path to .kbdb directory
+   --format <fmt>      Output format (json|text|mcp)
+
+Run "kbdb <command> --help" for detailed information.
+`;
+}
+function generateCommandHelp(command) {
+  if (command in GROUP_SUBCOMMANDS) {
+    return generateGroupHelp(command);
+  }
+  const leaf = LEAF_HELP[command];
+  if (leaf) {
+    return leaf;
+  }
+  return `Unknown command: ${command}
+
+` + generateGlobalHelp();
+}
+function generateGroupHelp(group) {
+  const subs = GROUP_SUBCOMMANDS[group] ?? [];
+  const subLines = subs.map(([name, desc2]) => `   ${name.padEnd(20)}${desc2}`).join("\n");
+  const desc = GROUP_DESCRIPTIONS[group] ?? group;
+  return `kbdb ${group} - ${desc}
+
+Usage: kbdb ${group} <subcommand> [options]
+
+Subcommands:
+${subLines}
+
+Global Options:
+   --db <path>         Path to .kbdb directory
+   -h, --help          Show this help message
+
+Run "kbdb ${group} <subcommand> --help" for details.
+`;
+}
+var GROUP_DESCRIPTIONS = {
+  db: "Database management",
+  skill: "Skill management",
+  agent: "Agent management"
+};
+var LEAF_HELP = {
+  learn: `kbdb learn - Import content from files or stdin
+
+Usage: kbdb learn [options] <path | ->...
+
+Arguments:
+   <path | ->          File path, directory, or - for stdin
+
+Options:
+   --title <title>     Section title
+   --description <d>   Section description
+   --docid <docid>     Document ID to group under
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON array of { kbid, path, size, skipped }
+
+Examples:
+   kbdb learn README.md
+   kbdb learn ./docs/
+   cat notes.txt | kbdb learn -
+`,
+  unlearn: `kbdb unlearn - Remove sections by kbid
+
+Usage: kbdb unlearn [options] <kbid>...
+
+Arguments:
+   <kbid>              26-character knowledge base identifier
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON array of { kbid, removed }
+
+Examples:
+   kbdb unlearn abcdef1234567890abcdef1234
+   kbdb unlearn id1 id2 id3
+`,
+  search: `kbdb search - Query the knowledge base
+
+Usage: kbdb search [options] <query>...
+
+Arguments:
+   <query>             One or more query terms
+
+Options:
+   --mode <mode>       Result granularity (sections|documents|stats)
+   --limit <n>         Max results (default: 20)
+   --format <fmt>      Output format (json|text|mcp)
+   --content, -c       Hydrate results with section content
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON array of { kbid, score, preview, matches }
+
+Examples:
+   kbdb search "machine learning"
+   kbdb search --limit 5 --format text query
+   kbdb search --mode documents --content term
+`,
+  content: `kbdb content - Compose rendered content from ids
+
+Usage: kbdb content [options] <id>...
+
+Arguments:
+   <id>                kbid or docid identifier
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { type, data, total }
+
+Examples:
+   kbdb content abcdef1234567890abcdef1234
+   kbdb content id1 id2
+`,
+  check: `kbdb check - Verify knowledge base integrity
+
+Usage: kbdb check [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { ok, errors }
+
+Examples:
+   kbdb check
+   kbdb check --db /path/to/project
+`,
+  gc: `kbdb gc - Garbage collect unreferenced sections
+
+Usage: kbdb gc [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { removed_sections, removed_bytes }
+
+Examples:
+   kbdb gc
+   kbdb gc --db /path/to/project
+`,
+  rebuild: `kbdb rebuild - Reconstruct all index files
+
+Usage: kbdb rebuild [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { sections_reindexed, terms_indexed }
+
+Examples:
+   kbdb rebuild
+   kbdb rebuild --db /path/to/project
+`,
+  status: `kbdb status - Show database status
+
+Usage: kbdb status [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON database status object
+
+Examples:
+   kbdb status
+   kbdb status --db /path/to/project
+`,
+  mcp: `kbdb mcp - Start MCP server mode (stdio)
+
+Usage: kbdb mcp [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Environment:
+   KBDB_DIR            Fallback database path
+
+Examples:
+   kbdb mcp --db /path/to/project
+   KBDB_DIR=/path/to/project kbdb mcp
+`
+};
+var SUBCOMMAND_HELP = {
+  "db-init": `kbdb db init - Initialise a new .kbdb directory
+
+Usage: kbdb db init [options]
+
+Options:
+   --db <path>         Path to create .kbdb in
+                       (default: current directory)
+   -h, --help          Show this help message
+
+Output:
+   JSON { path, created }
+
+Examples:
+   kbdb db init
+   kbdb db init --db /path/to/project
+`,
+  "db-migrate": `kbdb db migrate - Migrate database to current format
+
+Usage: kbdb db migrate [options]
+
+Options:
+   --db <path>         Path containing .kbdb
+                       (default: current directory)
+   -h, --help          Show this help message
+
+Output:
+   JSON MigrateResult or "already up to date"
+
+Examples:
+   kbdb db migrate
+   kbdb db migrate --db /path/to/project
+`,
+  "skill-learn": `kbdb skill learn - Create a new skill definition
+
+Usage: kbdb skill learn [options] --name <n> --body <file|->
+
+Options:
+   --name <name>       Skill name (required)
+   --description <d>   Skill description
+   --body <file|->     Template body file or stdin (required)
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { kbid, name, arguments }
+
+Examples:
+   kbdb skill learn --name summarize --body prompt.txt
+   cat body.txt | kbdb skill learn --name my-skill --body -
+`,
+  "skill-list": `kbdb skill list - List all skills
+
+Usage: kbdb skill list [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON array of { kbid, name, description, argumentCount }
+
+Examples:
+   kbdb skill list
+   kbdb skill list --db /path/to/project
+`,
+  "skill-get": `kbdb skill get - Retrieve a skill by name or kbid
+
+Usage: kbdb skill get [options] <name-or-kbid>
+
+Arguments:
+   <name-or-kbid>      Skill name or 26-char kbid
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON SkillDefinition object
+
+Examples:
+   kbdb skill get summarize-document
+   kbdb skill get abcdef1234567890abcdef1234
+`,
+  "skill-delete": `kbdb skill delete - Remove a skill
+
+Usage: kbdb skill delete [options] <kbid>
+
+Arguments:
+   <kbid>              26-character kbid of the skill to remove
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { kbid, removed }
+
+Examples:
+   kbdb skill delete abcdef1234567890abcdef1234
+`,
+  "agent-create": `kbdb agent create - Create an agent with skill refs
+
+Usage: kbdb agent create [options] --name <n> --persona <file|-> --skills <kbid,...>
+
+Options:
+   --name <name>       Agent name (required)
+   --description <d>   Agent description
+   --persona <file|->  Persona file or stdin (required)
+   --skills <kbid,...> Comma-separated skill kbids (required)
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { docid, name, skills }
+
+Examples:
+   kbdb agent create --name code-reviewer --persona ./p.txt --skills abc123
+   cat persona.txt | kbdb agent create --name my-agent --persona - --skills abc123
+`,
+  "agent-list": `kbdb agent list - List all agents
+
+Usage: kbdb agent list [options]
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON array of { docid, name, description, skillCount }
+
+Examples:
+   kbdb agent list
+   kbdb agent list --db /path/to/project
+`,
+  "agent-get": `kbdb agent get - Retrieve an agent by docid
+
+Usage: kbdb agent get [options] <docid>
+
+Arguments:
+   <docid>             Agent document identifier
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON AgentDefinition object with resolved skills
+
+Examples:
+   kbdb agent get agent-code-reviewer
+`,
+  "agent-delete": `kbdb agent delete - Remove an agent
+
+Usage: kbdb agent delete [options] <docid>
+
+Arguments:
+   <docid>             Agent document identifier
+
+Options:
+   --db <path>         Path to .kbdb directory
+
+Output:
+   JSON { docid, removed }
+
+Examples:
+   kbdb agent delete agent-code-reviewer
+`
+};
+function generateSubcommandHelp(command, subcommand) {
+  const key = `${command}-${subcommand}`;
+  const text = SUBCOMMAND_HELP[key];
+  if (text) {
+    return text;
+  }
+  return generateCommandHelp(command);
+}
+
+// src/shared/cli/functions/run-cli.function.ts
+async function runCli(argv, deps2) {
+  const options = parseArgs(argv);
+  if (options.command === "help" || !options.command) {
+    const helpCommand = options.args[0];
+    const helpSubcommand = options.args[1];
+    const helpText = generateHelp(helpCommand, helpSubcommand);
+    if (helpCommand && !isKnownCommand(helpCommand)) {
+      return { output: helpText, exitCode: 1 };
+    }
+    return { output: helpText, exitCode: 0 };
+  }
+  if (options.command === "version") {
+    return { output: VERSION, exitCode: 0 };
+  }
+  if (options.command === "init" || options.command === "db-init") {
+    return handleInit(options, deps2);
+  }
+  if (options.command === "mcp") {
+    return handleMcp(options, deps2);
+  }
+  if (options.command === "migrate" || options.command === "db-migrate") {
+    return handleMigrate(options, deps2);
+  }
+  return handleDataCommand(options, deps2);
+}
+function handleInit(options, deps2) {
+  const result = deps2.runInit(options);
+  if (result.ok) {
+    return {
+      output: result.targetPath,
+      exitCode: 0
+    };
+  }
+  return {
+    error: `error: ${result.errorMessage ?? "init failed"}`,
+    exitCode: 1
+  };
+}
+async function handleMcp(options, deps2) {
+  const rawDbPath = options.dbPath ?? process.env["KBDB_DIR"];
+  if (!rawDbPath) {
+    return {
+      error: "error: --db or KBDB_DIR required in MCP mode",
+      exitCode: 1
+    };
+  }
+  const dbDir = deps2.findDb(rawDbPath);
+  if (!dbDir) {
+    return {
+      error: `error: no .kbdb database found at ${rawDbPath}`,
+      exitCode: 1
+    };
+  }
+  let client;
+  try {
+    client = await deps2.createWorkerClient({
+      contextPath: dbDir
+    });
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+  try {
+    const gateResult = await versionGate(client, dbDir);
+    if (gateResult) return gateResult;
+    if (deps2.startMcpServer) {
+      await deps2.startMcpServer(dbDir);
+    }
+    return { exitCode: 0 };
+  } catch (err) {
+    return {
+      error: `error: mcp failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  } finally {
+    client.disconnect();
+  }
+}
+async function handleMigrate(options, deps2) {
+  const dbDir = deps2.findDb(options.dbPath);
+  if (!dbDir) {
+    const basePath = options.dbPath ?? process.cwd();
+    return {
+      error: `error: no .kbdb database found at ${basePath}`,
+      exitCode: 1
+    };
+  }
+  let client;
+  try {
+    client = await deps2.createWorkerClient({
+      contextPath: dbDir
+    });
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+  try {
+    const versionStatus = await client.checkVersion(dbDir);
+    if (versionStatus.status === "too_new") {
+      return {
+        error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
+        exitCode: 1
+      };
+    }
+    if (versionStatus.status === "needs_migration") {
+      const migrateResult = await client.migrateDatabase(dbDir);
+      return {
+        output: JSON.stringify(migrateResult, null, 2),
+        exitCode: 0
+      };
+    }
+    return { output: "already up to date", exitCode: 0 };
+  } catch (err) {
+    return {
+      error: `error: migrate failed: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  } finally {
+    client.disconnect();
+  }
+}
+async function handleDataCommand(options, deps2) {
+  let dbDir = deps2.findDb(options.dbPath);
+  if (!dbDir) {
+    const basePath = options.dbPath ?? process.cwd();
+    if (!deps2.isStdinTty()) {
+      return {
+        error: `error: no .kbdb database found at ${basePath} -- run \`kbdb --init\` to create one`,
+        exitCode: 1
+      };
+    }
+    const answer = await deps2.promptUser(
+      `No .kbdb database found. Create one in ${basePath}? [y/N] `
+    );
+    if (answer.toLowerCase() !== "y") {
+      return {
+        error: "aborted: no database created",
+        exitCode: 1
+      };
+    }
+    const initResult = deps2.runInit(options);
+    if (!initResult.ok) {
+      return {
+        error: `error: ${initResult.errorMessage ?? "init failed"}`,
+        exitCode: 1
+      };
+    }
+    dbDir = initResult.targetPath;
+  }
+  let client;
+  try {
+    client = await deps2.createWorkerClient({
+      contextPath: dbDir
+    });
+  } catch (err) {
+    return {
+      error: `error: ${errorToMessage(err)}`,
+      exitCode: 1
+    };
+  }
+  try {
+    const gateResult = await versionGate(client, dbDir);
+    if (gateResult) return gateResult;
+    return await dispatchCommand(client, options);
+  } finally {
+    client.disconnect();
+  }
+}
+async function versionGate(client, dbDir) {
+  const versionStatus = await client.checkVersion(dbDir);
+  if (versionStatus.status === "needs_migration") {
+    return {
+      error: "error: database needs migration -- run `kbdb --migrate`",
+      exitCode: 1
+    };
+  }
+  if (versionStatus.status === "too_new") {
+    return {
+      error: `error: database version ${versionStatus.currentVersion.toString()} is newer than kbdb version ${versionStatus.requiredVersion.toString()} -- upgrade kbdb`,
+      exitCode: 1
+    };
+  }
+  return null;
+}
+
+// src/shared/cli/constants/help-text.constant.ts
+var HELP_TEXT = generateHelp();
+
+// src/shared/worker-client/classes/worker-client.class.ts
+import { connect } from "node:net";
+var WorkerClient = class {
+  /**
+   * @param socketPath - absolute path to the daemon's IPC socket
+   *   (or Windows named pipe path)
+   * @param contextId - 16-character context identifier sent as
+   *   `ctx` in every JSON-RPC request
+   */
+  constructor(socketPath, contextId) {
+    this.socketPath = socketPath;
+    this.contextId = contextId;
+  }
+  /** Underlying socket; `null` when not connected. */
+  socket = null;
+  /** Monotonically increasing request ID counter. */
+  nextId = 1;
+  /** Map of outstanding request IDs to their resolve/reject pairs. */
+  pending = /* @__PURE__ */ new Map();
+  /** Partial line buffer for split TCP/IPC frames. */
+  buffer = "";
+  /**
+   * Establishes the IPC connection to the worker daemon.
+   *
+   * @throws {Error} if the connection cannot be established
+   */
+  async connect() {
+    return new Promise((resolve4, reject) => {
+      this.socket = connect(this.socketPath, () => {
+        resolve4();
+      });
+      this.socket.on("error", (err) => {
+        reject(err);
+      });
+      this.socket.on("data", (chunk) => {
+        this.handleData(chunk.toString());
+      });
+    });
+  }
+  /** Destroys the IPC socket and clears the connection state. */
+  disconnect() {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+  /**
+   * Searches the knowledge base.
+   *
+   * @param params - query parameters including the search string
+   * @returns ranked list of matching sections
+   */
+  async search(params) {
+    return this.call("search", params);
+  }
+  /**
+   * Adds a new section to the knowledge base.
+   *
+   * @param params - section content and metadata
+   * @returns the result including the assigned knowledge-base
+   *   identifier and indexing statistics
+   */
+  async addSection(params) {
+    return this.call(
+      "addSection",
+      params
+    );
+  }
+  /**
+   * Replaces an existing section's content and metadata.
+   *
+   * @param kbid - identifier of the section to update
+   * @param params - new content and metadata
+   * @returns the knowledge-base identifier of the updated section
+   */
+  async updateSection(kbid, params) {
+    return this.call("updateSection", {
+      kbid,
+      ...params
+    });
+  }
+  /**
+   * Removes a section from the knowledge base.
+   *
+   * @param kbid - identifier of the section to remove
+   * @returns removal result with `removed` flag and elapsed time
+   */
+  async removeSection(kbid) {
+    return this.call("removeSection", {
+      kbid
+    });
+  }
+  /**
+   * Retrieves multiple sections by their identifiers.
+   *
+   * @param kbids - list of knowledge-base identifiers to fetch
+   * @returns sections in the order their IDs were requested
+   */
+  async readSections(kbids) {
+    return this.call("readSections", {
+      kbids
+    });
+  }
+  /**
+   * Groups a set of sections under a named document.
+   *
+   * @param title - human-readable document title
+   * @param kbids - identifiers of the sections to group
+   * @param docType - application-level document type tag; omit or
+   *   pass an empty string for untagged documents
+   * @returns the assigned document identifier
+   */
+  async groupSections(title, kbids, docType) {
+    const result = await this.call("groupSections", {
+      title,
+      kbids,
+      docType: docType ?? ""
+    });
+    return typeof result === "string" ? result : result.docid;
+  }
+  /**
+   * Removes the document grouping for the given document.
+   *
+   * The sections themselves are not deleted; only the grouping
+   * record is removed.
+   *
+   * @param docid - identifier of the document grouping to remove
+   */
+  async removeGrouping(docid) {
+    await this.call("removeGrouping", { docid });
+  }
+  /**
+   * Retrieves a full document record including its sections.
+   *
+   * @param docid - identifier of the document to retrieve
+   * @returns the document record as returned by the daemon
+   */
+  async retrieveDocument(docid) {
+    return this.call("retrieveDocument", { docid });
+  }
+  /**
+   * Composes a rendered Markdown document from one or more kbid
+   * or docid identifiers.
+   *
+   * @param ids - list of kbid or docid identifiers (may be mixed)
+   * @returns composed Markdown result with character count
+   */
+  async content(ids) {
+    return this.call("content", { ids });
+  }
+  /**
+   * Runs an integrity check on the knowledge-base database.
+   *
+   * @returns a report of all issues found; `ok` is `true` when
+   *   no errors were detected
+   */
+  async integrityCheck() {
+    return this.call(
+      "integrityCheck",
+      {}
+    );
+  }
+  /**
+   * Removes unreferenced sections from the database.
+   *
+   * @returns a report of sections removed and bytes freed
+   */
+  async gc() {
+    return this.call("gc", {});
+  }
+  /**
+   * Reconstructs all index files from section files and document
+   * manifests on disk. Text and code sections are re-tokenized;
+   * image sections are skipped.
+   *
+   * @returns a report of sections and terms re-indexed
+   */
+  async rebuildIndexes() {
+    return this.call("rebuildIndexes", {});
+  }
+  /**
+   * Invalidates the in-memory cache entry for a single section.
+   *
+   * @param kbid - identifier of the section to evict from cache
+   */
+  async invalidate(kbid) {
+    await this.call("invalidate", { kbid });
+  }
+  /** Clears all entries from the daemon's in-memory cache. */
+  async invalidateAll() {
+    await this.call("invalidateAll", {});
+  }
+  /**
+   * Retrieves diagnostic status information from the daemon.
+   *
+   * @returns current initialization state and cache statistics
+   */
+  async status() {
+    return this.call("status", {});
+  }
+  /**
+   * Returns database metadata and status from the daemon,
+   * including document count, section count, index size, and
+   * cache statistics.
+   *
+   * @returns database metadata from the daemon's cached state
+   */
+  async dbStatus() {
+    return this.call("dbStatus", {});
+  }
+  /**
+   * Initialises a new `.kbdb` database directory at the given path
+   * by sending an init request to the worker daemon.
+   *
+   * The daemon creates all required subdirectories and seed files via
+   * the `worker_init_directory` WASM export.
+   *
+   * @param targetPath - absolute path to the directory that will
+   *   contain the new `.kbdb` database
+   * @throws {Error} if the `.kbdb` directory already exists or the
+   *   daemon cannot create the layout
+   */
+  async initDirectory(targetPath) {
+    await this.call("initDirectory", { targetPath });
+  }
+  /**
+   * Runs all pending database migrations for the `.kbdb` directory
+   * at the given path.
+   *
+   * Delegates to the `worker_migrate` WASM export on the daemon.
+   * Each migration step updates `catalog.toml` on success, so
+   * retrying after a partial failure is safe.
+   *
+   * @param targetPath - absolute path to the `.kbdb` database root
+   * @returns migration report with old version, new version, and
+   *   number of migration steps applied
+   */
+  async migrateDatabase(targetPath) {
+    return this.call("migrateDatabase", {
+      targetPath
+    });
+  }
+  /**
+   * Checks the format version of the `.kbdb` database at the given
+   * path against the version required by the current WASM engine.
+   *
+   * This is a read-only operation: it reads `catalog.toml` and
+   * returns the compatibility status without making any changes.
+   *
+   * @param targetPath - absolute path to the `.kbdb` database root
+   * @returns version compatibility report
+   */
+  async checkVersion(targetPath) {
+    return this.call("checkVersion", {
+      targetPath
+    });
+  }
+  /**
+   * Retrieves all sections whose type name matches the given string.
+   *
+   * @param sectionType - the application-level type name to filter by
+   * @returns all section records with a matching type name
+   */
+  async listByType(sectionType) {
+    return this.call("listByType", {
+      sectionType
+    });
+  }
+  /**
+   * Retrieves all documents whose type name matches the given string.
+   *
+   * @param docType - the application-level document type to filter by
+   * @returns all document manifests with a matching type name
+   */
+  async listDocumentsByType(docType) {
+    return this.call("listDocumentsByType", {
+      docType
+    });
+  }
+  /**
+   * Sends a JSON-RPC 2.0 request and awaits the response.
+   *
+   * @param method - the RPC method name
+   * @param params - parameters to include in the request
+   * @throws {Error} if not connected
+   * @throws {Error} when the daemon returns an error response
+   */
+  async call(method, params) {
+    const socket = this.socket;
+    if (!socket) {
+      throw new Error("not connected");
+    }
+    const id = this.nextId++;
+    const request = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params: { ctx: this.contextId, ...params }
+    };
+    return new Promise((resolve4, reject) => {
+      this.pending.set(id, { resolve: resolve4, reject });
+      socket.write(JSON.stringify(request) + "\n");
+    });
+  }
+  /**
+   * Processes incoming data from the socket, splitting on newlines
+   * and dispatching complete JSON-RPC response objects.
+   *
+   * @param data - raw string chunk received from the socket
+   */
+  handleData(data) {
+    this.buffer += data;
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const response = JSON.parse(line);
+        const pending = this.pending.get(response.id);
+        if (pending) {
+          this.pending.delete(response.id);
+          if (response.error) {
+            const err = new Error(response.error.message);
+            err.code = response.error.code;
+            pending.reject(err);
+          } else {
+            pending.resolve(response.result);
+          }
+        }
+      } catch {
+      }
+    }
+  }
+};
+
+// src/shared/worker-client/functions/create-worker-client.function.ts
+import { existsSync as existsSync6, readFileSync as readFileSync3, unlinkSync as unlinkSync2 } from "node:fs";
+import { join as join7 } from "node:path";
+import { tmpdir as tmpdir3 } from "node:os";
+
+// src/shared/worker-client/functions/resolve-db-path.function.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join4, resolve as resolve3 } from "node:path";
+function resolveDbPath(targetDir) {
+  const base = targetDir ? resolve3(targetDir) : process.cwd();
+  const dbPath = join4(base, ".kbdb");
+  if (!existsSync3(dbPath)) {
+    throw new Error(`database not found: ${dbPath}`);
+  }
+  return dbPath;
+}
+
+// src/shared/worker-client/functions/compute-context-id.function.ts
+async function computeContextId(absolutePath) {
+  const hash = await computeSha256(absolutePath);
+  return hash.slice(0, 16);
+}
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+import { existsSync as existsSync4, readFileSync as readFileSync2, unlinkSync } from "node:fs";
+import { join as join5 } from "node:path";
+import { tmpdir } from "node:os";
+
+// src/shared/platform/functions/is-process-alive.function.ts
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+function discoverDaemon(contextId) {
+  const pidPath = join5(tmpdir(), `kbdb-${contextId}.pid`);
+  if (!existsSync4(pidPath)) return null;
+  const pidStr = readFileSync2(pidPath, "utf-8").trim();
+  const pid = parseInt(pidStr, 10);
+  if (isNaN(pid) || !isProcessAlive(pid)) {
+    try {
+      unlinkSync(pidPath);
+    } catch {
+    }
+    return null;
+  }
+  const socketPath = join5(tmpdir(), `kbdb-${contextId}.sock`);
+  const crashPath = join5(tmpdir(), `kbdb-${contextId}.crash`);
+  try {
+    unlinkSync(crashPath);
+  } catch {
+  }
+  return { pid, socketPath };
+}
+
+// src/shared/worker-client/functions/spawn-daemon.function.ts
+import { spawn } from "node:child_process";
+function spawnDaemon(contextPath, runtime2, workerScript2) {
+  if (!workerScript2) {
+    throw new Error(
+      "workerScript must be provided (resolve at entry point)"
+    );
+  }
+  const execPath = runtime2 === "deno" ? "deno" : process.execPath;
+  const args = runtime2 === "deno" ? ["run", "--allow-all", workerScript2, contextPath] : [workerScript2, contextPath];
+  const child = spawn(execPath, args, {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+
+// src/shared/worker-client/functions/wait-for-daemon.function.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var POLL_INTERVAL_MS = 100;
+async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const pidPath = join6(tmpdir2(), `kbdb-${contextId}.pid`);
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync5(pidPath)) return true;
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  return false;
+}
+
+// src/shared/worker-client/functions/create-worker-client.function.ts
+async function createWorkerClient(options) {
+  const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
+  const contextId = await computeContextId(dbPath);
+  const socketPath = getIpcPath(contextId);
+  let daemon = discoverDaemon(contextId);
+  if (!daemon && options?.autoSpawn !== false) {
+    const runtime2 = detectRuntime();
+    spawnDaemon(dbPath, runtime2, options?.workerScript);
+    await waitForDaemon(contextId, options?.connectTimeoutMs);
+    daemon = discoverDaemon(contextId);
+  }
+  if (!daemon) {
+    throw new Error(
+      `kbdb worker daemon did not start: ${readCrashReason(contextId)}`
+    );
+  }
+  const client = new WorkerClient(socketPath, contextId);
+  await client.connect();
+  return client;
+}
+function readCrashReason(contextId) {
+  const crashPath = join7(tmpdir3(), `kbdb-${contextId}.crash`);
+  if (!existsSync6(crashPath)) {
+    return "daemon failed to start (no details available)";
+  }
+  try {
+    const raw = readFileSync3(crashPath, "utf-8");
+    const crash = JSON.parse(raw);
+    unlinkSync2(crashPath);
+    return crash.error ?? "unknown error (crash log empty)";
+  } catch {
+    return "daemon failed to start (crash log unreadable)";
+  }
+}
+
+// src/shared/mcp/classes/mcp-server.class.ts
+import { createInterface as createInterface2 } from "node:readline";
+
+// src/shared/mcp/functions/create-tool-definitions.function.ts
+function createToolDefinitions() {
+  return [
+    {
+      name: "search",
+      description: "Search the knowledge base for relevant sections using natural language queries.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Search query text"
+          },
+          mode: {
+            type: "string",
+            enum: ["sections", "documents", "stats"],
+            description: "Search mode (default: sections)"
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (default: 20)"
+          }
+        },
+        required: ["query"]
+      },
+      annotations: {
+        title: "Search KB",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "learn",
+      description: "Add a text section to the knowledge base.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "Text content to add"
+          },
+          type: {
+            type: "string",
+            description: "MIME type (default: text/markdown). Use image/* for images."
+          },
+          title: {
+            type: "string",
+            description: "Section title. Required for image/* types."
+          },
+          description: {
+            type: "string",
+            description: "Optional section description"
+          },
+          docid: {
+            type: "string",
+            description: "Document ID to group under"
+          }
+        },
+        required: ["content"]
+      },
+      annotations: {
+        title: "Import Content",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "unlearn",
+      description: "Remove a section from the knowledge base by its kb-id.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kbid: {
+            type: "string",
+            description: "Knowledge base ID of the section"
+          }
+        },
+        required: ["kbid"]
+      },
+      annotations: {
+        title: "Remove Section",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "retrieve",
+      description: "Retrieve a section or document by ID. Provide kbid or docid.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kbid: {
+            type: "string",
+            description: "Section kb-id"
+          },
+          docid: {
+            type: "string",
+            description: "Document ID"
+          }
+        }
+      },
+      annotations: {
+        title: "Fetch Content",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "status",
+      description: "Get database metadata including document count, section count, index size, and cache statistics.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "DB Status",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "content",
+      description: "Compose a rendered Markdown document from one or more kbid or docid identifiers.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ids: {
+            type: "array",
+            items: { type: "string" },
+            description: "One or more kbid or docid identifiers (may be mixed)"
+          }
+        },
+        required: ["ids"]
+      },
+      annotations: {
+        title: "Compose Content",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "check",
+      description: "Verify the integrity of the knowledge base. Reports checksum mismatches, orphan sections, broken references, and circular reference chains.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "Integrity Check",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "gc",
+      description: "Remove unreferenced sections from the knowledge base. A section is eligible when no document manifest references it.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "Garbage Collect",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false
+      }
+    },
+    {
+      name: "rebuild",
+      description: "Reconstruct all index files from section files and document manifests on disk. Use this to recover from index corruption.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "Rebuild Indexes",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false
+      }
+    },
+    {
+      name: "skill-learn",
+      description: "Create or update a skill definition. Skills are reusable AI agent capabilities with template placeholders.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Skill name"
+          },
+          description: {
+            type: "string",
+            description: "Skill description"
+          },
+          body: {
+            type: "string",
+            description: "Skill body template. Use {{argName}} for placeholders."
+          }
+        },
+        required: ["name", "body"]
+      },
+      annotations: {
+        title: "Create Skill",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "skill-list",
+      description: "List all skills in the knowledge base.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "List Skills",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "skill-get",
+      description: "Get a skill definition by name or kbid.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Skill name"
+          },
+          kbid: {
+            type: "string",
+            description: "Knowledge base ID"
+          }
+        }
+      },
+      annotations: {
+        title: "Get Skill",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "skill-delete",
+      description: "Delete a skill by its kbid.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kbid: {
+            type: "string",
+            description: "Knowledge base ID"
+          }
+        },
+        required: ["kbid"]
+      },
+      annotations: {
+        title: "Delete Skill",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "agent-create",
+      description: "Create an AI agent with a persona and optional skill references.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Agent name"
+          },
+          description: {
+            type: "string",
+            description: "Agent description"
+          },
+          persona: {
+            type: "string",
+            description: "Agent persona prompt"
+          },
+          skills: {
+            type: "array",
+            items: { type: "string" },
+            description: "Skill kbid references to attach"
+          }
+        },
+        required: ["name", "persona"]
+      },
+      annotations: {
+        title: "Create Agent",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "agent-list",
+      description: "List all agents in the knowledge base.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      annotations: {
+        title: "List Agents",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "agent-get",
+      description: "Get an agent definition by document ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          docid: {
+            type: "string",
+            description: "Document ID of the agent"
+          }
+        },
+        required: ["docid"]
+      },
+      annotations: {
+        title: "Get Agent",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true
+      }
+    },
+    {
+      name: "agent-delete",
+      description: "Delete an agent by its document ID. Skill sections are not removed.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          docid: {
+            type: "string",
+            description: "Document ID of the agent"
+          }
+        },
+        required: ["docid"]
+      },
+      annotations: {
+        title: "Delete Agent",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true
+      }
+    }
+  ];
+}
+
+// src/shared/mcp/functions/create-resource-templates.function.ts
+function createResourceTemplates() {
+  return [
+    {
+      uriTemplate: "kbdb://section/{kb_id}",
+      name: "Section",
+      description: "A knowledge base section by its kb-id.",
+      mimeType: "text/plain"
+    },
+    {
+      uriTemplate: "kbdb://document/{doc_id}",
+      name: "Document",
+      description: "A document with its ordered sections.",
+      mimeType: "application/json"
+    }
+  ];
+}
+
+// src/shared/mcp/functions/handle-agent-create.function.ts
+function asString(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+function asStringArray(value) {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  return [];
+}
+async function handleAgentCreate(client, args) {
+  const name = asString(args["name"], "");
+  const description = asString(args["description"], "");
+  const persona = asString(args["persona"], "");
+  const skills = asStringArray(args["skills"]);
+  if (!name) {
+    return {
+      content: [{ type: "text", text: "name is required" }],
+      isError: true
+    };
+  }
+  if (!persona) {
+    return {
+      content: [{ type: "text", text: "persona is required" }],
+      isError: true
+    };
+  }
+  if (skills.length > 0) {
+    const sections = await client.readSections(skills);
+    const found = new Set(sections.map((s) => s.kbid));
+    const missing = skills.filter((k) => !found.has(k));
+    if (missing.length > 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `skill not found: ${missing.join(", ")}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+  const metadata = JSON.stringify({ name, description, persona });
+  const metaResult = await client.addSection({
+    sectionType: "text",
+    content: metadata,
+    title: name,
+    description
+  });
+  const allKbids = [metaResult.kbid, ...skills];
+  const docid = await client.groupSections(name, allKbids);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          docid,
+          name,
+          skillCount: skills.length
+        })
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-agent-list.function.ts
+async function handleAgentList(client) {
+  const docs = await client.listDocumentsByType("agent");
+  const items = docs.map((d) => ({
+    docid: d.docid,
+    name: d.title,
+    skillCount: Math.max(0, d.sections.length - 1)
+  }));
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(items, null, 2)
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-agent-get.function.ts
+async function readAgentMeta2(client, metaKbid, fallbackName) {
+  const metaSections = await client.readSections([metaKbid]);
+  const first = metaSections.at(0);
+  if (!first) {
+    return { name: fallbackName, description: "", persona: "" };
+  }
+  try {
+    const meta = JSON.parse(first.content);
+    return {
+      name: typeof meta["name"] === "string" ? meta["name"] : fallbackName,
+      description: typeof meta["description"] === "string" ? meta["description"] : "",
+      persona: typeof meta["persona"] === "string" ? meta["persona"] : ""
+    };
+  } catch {
+    return { name: fallbackName, description: "", persona: "" };
+  }
+}
+async function resolveSkillRefs(client, skillRefs) {
+  if (skillRefs.length === 0) {
+    return [];
+  }
+  const skillKbids = skillRefs.map((s) => s.kbid);
+  const skillSections = await client.readSections(skillKbids);
+  const sectionMap = new Map(skillSections.map((s) => [s.kbid, s]));
+  return skillRefs.map((ref) => {
+    const sec = sectionMap.get(ref.kbid);
+    if (!sec) {
+      return { kbid: ref.kbid, name: null, position: ref.position };
+    }
+    try {
+      const parsed = JSON.parse(sec.content);
+      const skillName = typeof parsed["name"] === "string" ? parsed["name"] : null;
+      return {
+        kbid: ref.kbid,
+        name: skillName,
+        position: ref.position
+      };
+    } catch {
+      return { kbid: ref.kbid, name: null, position: ref.position };
+    }
+  });
+}
+async function handleAgentGet(client, args) {
+  const docid = typeof args["docid"] === "string" ? args["docid"] : "";
+  if (!docid) {
+    return {
+      content: [{ type: "text", text: "docid is required" }],
+      isError: true
+    };
+  }
+  const doc = await client.retrieveDocument(docid);
+  const metaKbid = doc.sections[0]?.kbid;
+  const skillRefs = doc.sections.slice(1);
+  const { name, description, persona } = metaKbid ? await readAgentMeta2(client, metaKbid, doc.title) : { name: doc.title, description: "", persona: "" };
+  const skills = await resolveSkillRefs(client, skillRefs);
+  const agent = {
+    docid,
+    name,
+    description,
+    persona,
+    skills
+  };
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(agent, null, 2)
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-agent-delete.function.ts
+async function handleAgentDelete(client, args) {
+  const docid = typeof args["docid"] === "string" ? args["docid"] : "";
+  if (!docid) {
+    return {
+      content: [{ type: "text", text: "docid is required" }],
+      isError: true
+    };
+  }
+  await client.removeGrouping(docid);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ docid, removed: true })
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-tool-call.function.ts
+function asString2(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+function asStringArray2(value) {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  return [];
+}
+async function handleToolCall(client, name, args) {
+  try {
+    switch (name) {
+      case "search":
+        return await handleSearch2(client, args);
+      case "learn":
+        return await handleLearn2(client, args);
+      case "unlearn":
+        return await handleUnlearn2(client, args);
+      case "retrieve":
+        return await handleRetrieve(client, args);
+      case "status":
+        return await handleStatus2(client);
+      case "content":
+        return await handleContent2(client, args);
+      case "check":
+        return await handleCheck2(client);
+      case "gc":
+        return await handleGc2(client);
+      case "rebuild":
+        return await handleRebuild2(client);
+      case "skill-learn":
+        return await handleSkillLearn(client, args);
+      case "skill-list":
+        return await handleSkillList(client);
+      case "skill-get":
+        return await handleSkillGet(client, args);
+      case "skill-delete":
+        return await handleSkillDelete(client, args);
+      case "agent-create":
+        return await handleAgentCreate(client, args);
+      case "agent-list":
+        return await handleAgentList(client);
+      case "agent-get":
+        return await handleAgentGet(client, args);
+      case "agent-delete":
+        return await handleAgentDelete(client, args);
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool: ${name}`
+            }
+          ],
+          isError: true
+        };
+    }
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: err instanceof Error ? err.message : String(err)
+        }
+      ],
+      isError: true
+    };
+  }
+}
+async function handleSearch2(client, args) {
+  const results = await client.search({
+    query: asString2(args["query"], ""),
+    mode: args["mode"],
+    limit: args["limit"]
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(results, null, 2)
+      }
+    ]
+  };
+}
+async function handleLearn2(client, args) {
+  const sectionType = asString2(args["type"], "text/markdown");
+  const title = typeof args["title"] === "string" ? args["title"] : void 0;
+  const description = typeof args["description"] === "string" ? args["description"] : void 0;
+  const docid = typeof args["docid"] === "string" ? args["docid"] : void 0;
+  if (sectionType.startsWith("image/") && !title) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "title is required for image/* types"
+        }
+      ],
+      isError: true
+    };
+  }
+  const result = await client.addSection({
+    sectionType,
+    content: asString2(args["content"], ""),
+    title,
+    description,
+    docid
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result)
+      }
+    ]
+  };
+}
+async function handleUnlearn2(client, args) {
+  const result = await client.removeSection(
+    asString2(args["kbid"], "")
+  );
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result)
+      }
+    ]
+  };
+}
+async function handleRetrieve(client, args) {
+  if (typeof args["kbid"] === "string") {
+    const sections = await client.readSections([args["kbid"]]);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(sections, null, 2)
+        }
+      ]
+    };
+  }
+  if (typeof args["docid"] === "string") {
+    const doc = await client.retrieveDocument(args["docid"]);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(doc, null, 2)
+        }
+      ]
+    };
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: "Provide kbid or docid"
+      }
+    ],
+    isError: true
+  };
+}
+async function handleStatus2(client) {
+  const status = await client.dbStatus();
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(status, null, 2)
+      }
+    ]
+  };
+}
+async function handleContent2(client, args) {
+  const ids = asStringArray2(args["ids"]);
+  const result = await client.content(ids);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result)
+      }
+    ]
+  };
+}
+async function handleCheck2(client) {
+  const report = await client.integrityCheck();
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(report, null, 2)
+      }
+    ]
+  };
+}
+async function handleGc2(client) {
+  const report = await client.gc();
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(report, null, 2)
+      }
+    ]
+  };
+}
+async function handleRebuild2(client) {
+  const report = await client.rebuildIndexes();
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(report, null, 2)
+      }
+    ]
+  };
+}
+async function handleSkillLearn(client, args) {
+  const name = asString2(args["name"], "");
+  if (!name) {
+    return {
+      content: [{ type: "text", text: "name is required" }],
+      isError: true
+    };
+  }
+  const body = asString2(args["body"], "");
+  if (!body) {
+    return {
+      content: [{ type: "text", text: "body is required" }],
+      isError: true
+    };
+  }
+  const description = typeof args["description"] === "string" ? args["description"] : void 0;
+  const skillArgs = extractSkillArguments(body);
+  const skill = {
+    name,
+    description,
+    arguments: skillArgs.length > 0 ? skillArgs : void 0,
+    body
+  };
+  const json = serializeSkillContent(skill);
+  const result = await client.addSection({
+    sectionType: "skill",
+    content: json,
+    title: name,
+    description
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ kbid: result.kbid, name })
+      }
+    ]
+  };
+}
+async function handleSkillList(client) {
+  const records = await client.listByType("skill");
+  const items = records.map((r) => {
+    let argumentCount = 0;
+    try {
+      const parsed = JSON.parse(r.content);
+      if (Array.isArray(parsed["arguments"])) {
+        argumentCount = parsed["arguments"].length;
+      }
+    } catch {
+    }
+    return {
+      kbid: r.kbid,
+      name: r.title,
+      description: r.description,
+      argumentCount
+    };
+  });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(items, null, 2)
+      }
+    ]
+  };
+}
+async function handleSkillGet(client, args) {
+  const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;
+  const name = typeof args["name"] === "string" ? args["name"] : void 0;
+  if (!kbid && !name) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "name or kbid is required"
+        }
+      ],
+      isError: true
+    };
+  }
+  let content;
+  if (kbid) {
+    const sections = await client.readSections([kbid]);
+    if (sections.length > 0) {
+      content = sections[0]?.content;
+    }
+  }
+  if (content === void 0 && name) {
+    const records = await client.listByType("skill");
+    const match = records.filter((r) => r.title === name).pop();
+    if (match) {
+      content = match.content;
+    }
+  }
+  if (content === void 0) {
+    const identifier = kbid ?? name ?? "";
+    return {
+      content: [
+        {
+          type: "text",
+          text: `skill not found: ${identifier}`
+        }
+      ],
+      isError: true
+    };
+  }
+  const skill = parseSkillContent(content);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(skill, null, 2)
+      }
+    ]
+  };
+}
+async function handleSkillDelete(client, args) {
+  const kbid = asString2(args["kbid"], "");
+  if (!kbid) {
+    return {
+      content: [{ type: "text", text: "kbid is required" }],
+      isError: true
+    };
+  }
+  const result = await client.removeSection(kbid);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ kbid, removed: result.removed })
+      }
+    ]
+  };
+}
+
+// src/shared/mcp/functions/handle-resource-read.function.ts
+async function handleResourceRead(client, uri) {
+  const sectionMatch = uri.match(/^kbdb:\/\/section\/(.+)$/);
+  if (sectionMatch) {
+    const sections = await client.readSections([sectionMatch[1]]);
+    const text = sections.length > 0 ? sections[0].content : "";
+    return {
+      contents: [{ uri, mimeType: "text/plain", text }]
+    };
+  }
+  const docMatch = uri.match(/^kbdb:\/\/document\/(.+)$/);
+  if (docMatch) {
+    const doc = await client.retrieveDocument(docMatch[1]);
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(doc, null, 2)
+        }
+      ]
+    };
+  }
+  throw new Error(`Unknown resource URI: ${uri}`);
+}
+
+// src/shared/mcp/functions/create-prompt-definitions.function.ts
+function parseSkillArguments(content) {
+  try {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed["arguments"])) {
+      return void 0;
+    }
+    return parsed["arguments"].map(
+      (arg) => ({
+        name: typeof arg["name"] === "string" ? arg["name"] : "",
+        description: typeof arg["description"] === "string" ? arg["description"] : void 0,
+        required: typeof arg["required"] === "boolean" ? arg["required"] : void 0
+      })
+    );
+  } catch {
+    return void 0;
+  }
+}
+function createPromptDefinitions(skills, agents) {
+  const skillPrompts = skills.filter(
+    (r) => r.title !== null
+  ).map((record) => {
+    const args = parseSkillArguments(record.content);
+    const prompt = {
+      name: record.title,
+      description: record.description ?? void 0,
+      arguments: args
+    };
+    return prompt;
+  });
+  const agentPrompts = agents.map((doc) => ({
+    name: `agent:${doc.title}`,
+    arguments: []
+  }));
+  return [...skillPrompts, ...agentPrompts];
+}
+
+// src/shared/mcp/functions/handle-prompt-get.function.ts
+function parseAgentMeta(content) {
+  try {
+    const parsed = JSON.parse(content);
+    return {
+      persona: typeof parsed["persona"] === "string" ? parsed["persona"] : ""
+    };
+  } catch {
+    return { persona: "" };
+  }
+}
+function buildSkillsText(skillSections) {
+  const lines = [];
+  for (const sec of skillSections) {
+    try {
+      const parsed = JSON.parse(sec.content);
+      const name = typeof parsed["name"] === "string" ? parsed["name"] : null;
+      if (name === null) {
+        continue;
+      }
+      const description = typeof parsed["description"] === "string" ? parsed["description"] : "";
+      lines.push(`- ${name}: ${description}`);
+    } catch {
+    }
+  }
+  if (lines.length === 0) {
+    return null;
+  }
+  return `Available skills:
+${lines.join("\n")}`;
+}
+async function handleAgentPrompt(name, client) {
+  const docid = name.slice(6);
+  const doc = await client.retrieveDocument(docid);
+  const sections = doc.sections;
+  const metaSection = sections.at(0);
+  const skillRefs = sections.slice(1);
+  let persona = "";
+  if (metaSection !== void 0) {
+    const metaSections = await client.readSections([
+      metaSection.kbid
+    ]);
+    const metaContent = metaSections.at(0);
+    if (metaContent !== void 0) {
+      persona = parseAgentMeta(metaContent.content).persona;
+    }
+  }
+  const messages = [
+    {
+      role: "assistant",
+      content: { type: "text", text: persona }
+    }
+  ];
+  if (skillRefs.length === 0) {
+    return messages;
+  }
+  const skillKbids = skillRefs.map((s) => s.kbid);
+  const skillSections = await client.readSections(skillKbids);
+  const skillsText = buildSkillsText(skillSections);
+  if (skillsText !== null) {
+    messages.push({
+      role: "user",
+      content: { type: "text", text: skillsText }
+    });
+  }
+  return messages;
+}
+async function handleSkillPrompt(name, promptArgs, client) {
+  const sections = await client.listByType("skill");
+  let matchContent;
+  for (const sec of sections) {
+    if (sec.title === name) {
+      matchContent = sec.content;
+    }
+  }
+  if (matchContent === void 0) {
+    throw new Error(`Prompt not found: ${name}`);
+  }
+  const parsed = JSON.parse(matchContent);
+  const body = typeof parsed["body"] === "string" ? parsed["body"] : "";
+  const rendered = body.replace(
+    /\{\{(\w+)\}\}/g,
+    (_match, key) => key in promptArgs ? promptArgs[key] ?? _match : _match
+  );
+  return [
+    {
+      role: "user",
+      content: { type: "text", text: rendered }
+    }
+  ];
+}
+async function handlePromptGet(name, promptArgs, client) {
+  if (name.startsWith("agent:")) {
+    return handleAgentPrompt(name, client);
+  }
+  return handleSkillPrompt(name, promptArgs, client);
+}
+
+// src/shared/mcp/functions/handle-completion.function.ts
+async function handleCompletion(ref, argument, client) {
+  if (ref.type !== "ref/prompt") {
+    return { completion: { values: [], hasMore: false, total: 0 } };
+  }
+  const [skills, agents] = await Promise.all([
+    client.listByType("skill"),
+    client.listDocumentsByType("agent")
+  ]);
+  const names = [];
+  for (const skill of skills) {
+    if (skill.title !== null) {
+      names.push(skill.title);
+    }
+  }
+  for (const agent of agents) {
+    names.push(`agent:${agent.title}`);
+  }
+  const prefix = argument.value;
+  function matchesPrefix(candidate) {
+    if (prefix.length === 0) {
+      return true;
+    }
+    if (candidate.startsWith(prefix)) {
+      return true;
+    }
+    const AGENT_PREFIX = "agent:";
+    if (candidate.startsWith(AGENT_PREFIX)) {
+      return candidate.slice(AGENT_PREFIX.length).startsWith(prefix);
+    }
+    return false;
+  }
+  const values = names.filter(matchesPrefix);
+  return {
+    completion: {
+      values,
+      hasMore: false,
+      total: values.length
+    }
+  };
+}
+
+// src/shared/mcp/functions/handle-roots-list.function.ts
+function handleRootsList(contextPath) {
+  return [
+    {
+      uri: `file://${contextPath}`,
+      name: "kbdb database"
+    }
+  ];
+}
+
+// src/shared/mcp/functions/should-emit-log.function.ts
+var LOG_LEVEL_ORDER = [
+  "debug",
+  "info",
+  "notice",
+  "warning",
+  "error",
+  "critical",
+  "alert",
+  "emergency"
+];
+function shouldEmitLog(messageLevel, threshold) {
+  const messageIndex = LOG_LEVEL_ORDER.indexOf(messageLevel);
+  const thresholdIndex = LOG_LEVEL_ORDER.indexOf(threshold);
+  return messageIndex >= thresholdIndex;
+}
+
+// src/shared/mcp/constants/mcp-error-codes.constant.ts
+var PARSE_ERROR = -32700;
+var METHOD_NOT_FOUND = -32601;
+var RESOURCE_NOT_FOUND = -32002;
+
+// src/shared/mcp/classes/mcp-server.class.ts
+var McpServer = class {
+  client;
+  contextPath;
+  initialized = false;
+  hostCapabilities = null;
+  logLevel = null;
+  subscriptions = /* @__PURE__ */ new Set();
+  nextRequestId = 1;
+  pendingRequests = /* @__PURE__ */ new Map();
+  constructor(client, contextPath) {
+    this.client = client;
+    this.contextPath = contextPath ?? "";
+  }
+  async listen() {
+    const rl = createInterface2({
+      input: process.stdin,
+      terminal: false
+    });
+    await new Promise((resolve4) => {
+      rl.on("line", (line) => {
+        void this.dispatchLine(line);
+      });
+      rl.on("close", () => {
+        this.client.disconnect();
+        resolve4();
+      });
+    });
+  }
+  async handleLineForTest(line) {
+    return this.processLine(line);
+  }
+  /**
+   * Sends a JSON-RPC notification (no `id`, no response
+   * expected) to stdout.
+   */
+  notify(method, params) {
+    const notification = {
+      jsonrpc: "2.0",
+      method
+    };
+    if (params !== void 0) {
+      notification["params"] = params;
+    }
+    process.stdout.write(JSON.stringify(notification) + "\n");
+  }
+  /**
+   * Emits a log notification if the message severity meets or
+   * exceeds the configured log level threshold.
+   */
+  log(level, message, logger) {
+    if (this.logLevel === null) return;
+    if (!shouldEmitLog(level, this.logLevel)) return;
+    this.notify("notifications/message", {
+      level,
+      logger: logger ?? "kbdb",
+      data: message
+    });
+  }
+  /**
+   * Sends a JSON-RPC request to the host (server-to-client)
+   * and returns a Promise that resolves with the response
+   * result. Times out after 30 seconds.
+   */
+  sendRequest(method, params) {
+    const id = this.nextRequestId++;
+    const request = { jsonrpc: "2.0", id, method, params };
+    process.stdout.write(JSON.stringify(request) + "\n");
+    return new Promise((resolve4, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`Request ${method} timed out`));
+      }, 3e4);
+      this.pendingRequests.set(id, {
+        resolve: resolve4,
+        reject,
+        timer
+      });
+    });
+  }
+  /**
+   * Requests the host to generate text via the sampling
+   * capability. Throws if the host did not advertise sampling
+   * support during initialization.
+   */
+  async requestSampling(messages, maxTokens) {
+    if (!this.hostCapabilities?.["sampling"]) {
+      throw new Error("Host does not support sampling");
+    }
+    return this.sendRequest("sampling/createMessage", {
+      messages,
+      maxTokens
+    });
+  }
+  async dispatchLine(line) {
+    const response = await this.processLine(line);
+    if (response !== null) {
+      this.send(response);
+    }
+  }
+  async processLine(line) {
+    if (!line.trim()) return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return {
+        jsonrpc: "2.0",
+        id: 0,
+        error: {
+          code: PARSE_ERROR,
+          message: "Parse error"
+        }
+      };
+    }
+    if (parsed["id"] !== void 0 && typeof parsed["method"] !== "string") {
+      const responseId = parsed["id"];
+      const pending = this.pendingRequests.get(responseId);
+      if (pending) {
+        this.pendingRequests.delete(responseId);
+        clearTimeout(pending.timer);
+        if (parsed["error"]) {
+          const err = parsed["error"];
+          pending.reject(
+            new Error(err.message ?? "Request failed")
+          );
+        } else {
+          pending.resolve(parsed["result"]);
+        }
+      }
+      return null;
+    }
+    const request = parsed;
+    if (request.id === void 0) {
+      if (request.method === "notifications/initialized" || request.method === "notifications/cancelled") {
+        if (request.method === "notifications/initialized") {
+          this.initialized = true;
+        }
+      }
+      return null;
+    }
+    const id = request.id;
+    if (!this.initialized && request.method !== "initialize" && request.method !== "ping") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: RESOURCE_NOT_FOUND,
+          message: "Server not initialized"
+        }
+      };
+    }
+    const response = await this.handleRequest(request);
+    return response;
+  }
+  async handleRequest(request) {
+    const id = request.id;
+    switch (request.method) {
+      case "initialize": {
+        const params = request.params ?? {};
+        const caps = params["capabilities"];
+        this.hostCapabilities = caps ? caps : null;
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: "2025-11-25",
+            serverInfo: {
+              name: "kbdb",
+              version: "0.1.0"
+            },
+            capabilities: {
+              tools: {},
+              resources: { subscribe: true },
+              prompts: {},
+              logging: {},
+              completions: {}
+            }
+          }
+        };
+      }
+      case "ping":
+        return { jsonrpc: "2.0", id, result: {} };
+      case "tools/list":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            tools: createToolDefinitions()
+          }
+        };
+      case "resources/list":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: { resources: [] }
+        };
+      case "resources/templates/list":
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            resourceTemplates: createResourceTemplates()
+          }
+        };
+      case "tools/call": {
+        const params = request.params ?? {};
+        const rawName = params["name"];
+        const name = typeof rawName === "string" ? rawName : "";
+        const args = params["arguments"] ?? {};
+        const result = await handleToolCall(
+          this.client,
+          name,
+          args
+        );
+        return { jsonrpc: "2.0", id, result };
+      }
+      case "resources/read": {
+        const params = request.params ?? {};
+        const rawUri = params["uri"];
+        const uri = typeof rawUri === "string" ? rawUri : "";
+        try {
+          const result = await handleResourceRead(
+            this.client,
+            uri
+          );
+          return { jsonrpc: "2.0", id, result };
+        } catch (err) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: RESOURCE_NOT_FOUND,
+              message: err instanceof Error ? err.message : String(err)
+            }
+          };
+        }
+      }
+      case "prompts/list": {
+        const skills = await this.client.listByType("skill");
+        const agents = await this.client.listDocumentsByType("agent");
+        const prompts = createPromptDefinitions(skills, agents);
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: { prompts }
+        };
+      }
+      case "prompts/get": {
+        const params = request.params ?? {};
+        const name = typeof params["name"] === "string" ? params["name"] : "";
+        const promptArgs = params["arguments"] ?? {};
+        try {
+          const messages = await handlePromptGet(
+            name,
+            promptArgs,
+            this.client
+          );
+          return {
+            jsonrpc: "2.0",
+            id,
+            result: { messages }
+          };
+        } catch (err) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: RESOURCE_NOT_FOUND,
+              message: err instanceof Error ? err.message : String(err)
+            }
+          };
+        }
+      }
+      case "completion/complete": {
+        const params = request.params ?? {};
+        const ref = params["ref"];
+        const argument = params["argument"] ?? {
+          name: "",
+          value: ""
+        };
+        const result = await handleCompletion(
+          ref,
+          argument,
+          this.client
+        );
+        return { jsonrpc: "2.0", id, result };
+      }
+      case "roots/list": {
+        const roots = handleRootsList(this.contextPath);
+        return {
+          jsonrpc: "2.0",
+          id,
+          result: { roots }
+        };
+      }
+      case "logging/setLevel": {
+        const params = request.params ?? {};
+        const level = params["level"];
+        this.logLevel = level ?? null;
+        return { jsonrpc: "2.0", id, result: {} };
+      }
+      case "resources/subscribe": {
+        const params = request.params ?? {};
+        const uri = typeof params["uri"] === "string" ? params["uri"] : "";
+        this.subscriptions.add(uri);
+        return { jsonrpc: "2.0", id, result: {} };
+      }
+      case "resources/unsubscribe": {
+        const params = request.params ?? {};
+        const uri = typeof params["uri"] === "string" ? params["uri"] : "";
+        this.subscriptions.delete(uri);
+        return { jsonrpc: "2.0", id, result: {} };
+      }
+      default:
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: METHOD_NOT_FOUND,
+            message: `Method not found: ` + request.method
+          }
+        };
+    }
+  }
+  send(response) {
+    const json = JSON.stringify(response);
+    process.stdout.write(json + "\n");
+  }
+};
+
+// src/shared/mcp/functions/create-mcp-server.function.ts
+function createMcpServer(client) {
+  return new McpServer(client);
+}
+
+// src/cli.ts
+var runtime = detectRuntime();
+var baseDir = resolveBaseDir(import.meta.url, import.meta.dirname);
+var workerScript = resolveWorkerScript(baseDir.scriptDir, runtime);
+var deps = {
+  isStdinTty,
+  promptUser,
+  createWorkerClient: (opts) => createWorkerClient({ ...opts, workerScript }),
+  findDb,
+  runInit,
+  startMcpServer: async (contextPath) => {
+    const client = await createWorkerClient({
+      contextPath,
+      workerScript
+    });
+    try {
+      const server = createMcpServer(client);
+      await server.listen();
+    } finally {
+      client.disconnect();
+    }
+  }
+};
+async function main() {
+  const result = await runCli(getArgs(), deps);
+  if (result.output) {
+    console.log(result.output);
+  }
+  if (result.error) {
+    console.error(result.error);
+  }
+  if (result.exitCode !== 0) {
+    process.exitCode = result.exitCode;
+  }
+}
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`error: ${msg}`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=cli.mjs.map