agent-kb 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,1022 @@
+#!/usr/bin/env node
+import {
+  KbError,
+  featureDisabled,
+  hasBlockingFindings,
+  load,
+  openKb
+} from "../chunk-I77A4URT.js";
+
+// src/cli/index.ts
+import * as fs2 from "fs";
+import * as os2 from "os";
+import { pathToFileURL } from "url";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+
+// src/content/agent-kb-skill.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var AGENT_KB_SKILL = `---
+name: using-agent-kb
+description: Use when interacting with a project's agent-kb knowledge base \u2014 reading entities, writing changes, searching, or maintaining graph integrity.
+---
+
+# Using agent-kb
+
+Agent KB is a local, versioned knowledge graph of typed entities and relations, edited via change sets. All writes go through a propose \u2192 accept flow; reads and searches are lock-free.
+
+## Step 1 \u2014 Discover the schema first
+
+Always call this before reading or writing. It returns every entity type (with field names, types, required/optional, enum values, and ref targets), all relations, and available context recipes.
+
+- CLI: \`agent-kb schema describe\`
+- MCP: \`kb_describe_schema\`
+
+## Step 2 \u2014 Read and search
+
+### Retrieve and query
+
+| Goal | CLI | MCP |
+|---|---|---|
+| Get one entity by ID | \`agent-kb get <id> [--links]\` | \`kb_get_entity\` |
+| Query entities by type | \`agent-kb find <type> [--where JSON]\` | \`kb_find_entities\` |
+| Traverse the graph | \`agent-kb related <id>\` | \`kb_related\` |
+| Trace dependency tree | \`agent-kb trace <id>\` | \`kb_trace\` |
+| Assemble context pack | \`agent-kb context <id> [--recipe <name>]\` | \`kb_get_context_pack\` |
+
+### Search
+
+\`agent-kb search <text> [--mode fts|semantic|hybrid]\` / MCP: \`kb_search\`
+
+- **fts** (default) \u2014 full-text keyword search; always available.
+- **semantic** \u2014 vector similarity; requires vectors enabled.
+- **hybrid** \u2014 RRF fusion of fts + semantic; requires vectors enabled.
+
+Before using semantic or hybrid: call \`kb_status\` and check \`vector_enabled\`. If \`false\`, those modes return \`FEATURE_DISABLED\`.
+
+## Step 3 \u2014 Write workflow (change sets)
+
+All writes are atomic and go through a three-step change set flow:
+
+1. **Propose** \u2014 \`agent-kb propose <file.json>\` / MCP: \`kb_propose_change_set\`
+2. **Validate** (optional) \u2014 \`agent-kb validate <id>\` / MCP: \`kb_validate_change_set\`
+3. **Accept** \u2014 \`agent-kb accept <id>\` / MCP: \`kb_accept_change_set\`
+
+To reject: \`agent-kb reject <id> --reason <text>\` / MCP: \`kb_reject_change_set\`
+
+To discover existing change-set IDs:
+- CLI: \`agent-kb changesets\`
+- MCP: \`kb_list_change_sets\`
+
+## Integrity and recovery
+
+- **Verify** \u2014 \`agent-kb verify\` / MCP: \`kb_verify\` \u2014 check referential consistency and dangling links.
+- **Reindex** \u2014 \`agent-kb reindex\` / MCP: \`kb_reindex\` \u2014 rebuild the derived index (FTS + vectors when enabled). Use after \`VECTOR_INDEX_FAILED\` / \`VECTOR_DIM_MISMATCH\` or to backfill vectors after enabling them.
+`.trim();
+function parseSkillScope(raw) {
+  const resolved = raw === true ? "project" : String(raw);
+  if (resolved === "project" || resolved === "global") {
+    return { ok: true, scope: resolved };
+  }
+  return {
+    ok: false,
+    message: `invalid scope '${String(raw)}': must be 'global' or 'project'`
+  };
+}
+function installSkill(scope, root, home = os.homedir()) {
+  const base = scope === "global" ? home : root;
+  const dir = path.join(base, ".claude", "skills", "agent-kb");
+  fs.mkdirSync(dir, { recursive: true });
+  const skillPath = path.join(dir, "SKILL.md");
+  fs.writeFileSync(skillPath, AGENT_KB_SKILL, "utf8");
+  return { path: skillPath };
+}
+
+// src/cli/exit-codes.ts
+function exitCodeFor(env) {
+  if (env.ok) {
+    return 0;
+  }
+  switch (env.error.code) {
+    case "LOCK_TIMEOUT":
+      return 3;
+    case "IO_ERROR":
+    case "PARSE_ERROR":
+    case "INTERNAL":
+      return 4;
+    default:
+      return 1;
+  }
+}
+
+// src/cli/mcp-command.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/mcp/tools.ts
+import { z } from "zod";
+function txt(text) {
+  return { type: "text", text };
+}
+function parseErr(err) {
+  return { content: [txt(`VALIDATION_ERROR: ${err.message}`)], isError: true };
+}
+function envelopeToResult(env) {
+  if (env.ok) {
+    return {
+      content: [txt(JSON.stringify(env.data))],
+      structuredContent: env.data
+    };
+  }
+  return {
+    content: [txt(`${env.error.code}: ${env.error.message}`)],
+    isError: true,
+    structuredContent: { error: { code: env.error.code, message: env.error.message } }
+  };
+}
+var DESCRIBE_HINT = "call kb_describe_schema for the entity's fields, enum values, and ref targets";
+var fieldsSchema = z.record(z.string(), z.unknown()).describe(`Field values keyed by field name; types are entity-specific \u2014 ${DESCRIBE_HINT}.`);
+var setSchema = z.record(z.string(), z.unknown()).describe(
+  `Fields to set, keyed by field name; a value is a scalar or a {add,remove} list mutation \u2014 ${DESCRIBE_HINT}.`
+);
+var createOpSchema = z.object({
+  op: z.literal("create"),
+  entity: z.string().describe("Entity type name to create (see kb_describe_schema.entities)."),
+  handle: z.string().describe("Temporary @handle naming the new entity so later ops can reference it."),
+  fields: fieldsSchema
+}).strict();
+var updateOpSchema = z.object({
+  op: z.literal("update"),
+  id: z.string().describe("EntityId of the entity to update."),
+  base_rev: z.number().describe("Revision the update is based on (optimistic-concurrency guard)."),
+  set: setSchema
+}).strict();
+var deleteOpSchema = z.object({
+  op: z.literal("delete"),
+  id: z.string().describe("EntityId of the entity to delete."),
+  base_rev: z.number().describe("Revision the delete is based on (optimistic-concurrency guard).")
+}).strict();
+var linkOpSchema = z.object({
+  op: z.literal("link"),
+  from: z.string().describe("Source: an EntityId or an @handle defined in this change set."),
+  relation: z.string().describe("Relation name (see kb_describe_schema.relations)."),
+  to: z.string().describe("Target: an EntityId or an @handle defined in this change set."),
+  base_rev: z.number().optional().describe("Optional base revision for concurrency.")
+}).strict();
+var unlinkOpSchema = z.object({
+  op: z.literal("unlink"),
+  from: z.string().describe("Source EntityId."),
+  relation: z.string().describe("Relation name."),
+  to: z.string().describe("Target EntityId.")
+}).strict();
+var mcpOpSchema = z.discriminatedUnion("op", [
+  createOpSchema,
+  updateOpSchema,
+  deleteOpSchema,
+  linkOpSchema,
+  unlinkOpSchema
+]).describe(
+  "A change operation; `op` selects the variant \u2014 create (entity+handle+fields), update (id+base_rev+set), delete (id+base_rev), link (from+relation+to), unlink (from+relation+to)."
+);
+var whereValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.unknown()),
+  z.looseObject({
+    eq: z.unknown().optional(),
+    ne: z.unknown().optional(),
+    gt: z.unknown().optional(),
+    gte: z.unknown().optional(),
+    lt: z.unknown().optional(),
+    lte: z.unknown().optional(),
+    in: z.unknown().optional(),
+    contains: z.unknown().optional()
+  })
+]);
+var whereSchema = z.record(z.string(), whereValueSchema).describe(
+  "Filter map keyed by field name. Each value is a scalar (equality), an array (IN \u2014 matches any), or an operator object with keys eq/ne/gt/gte/lt/lte/in/contains. Fields must exist on the entity (see kb_describe_schema)."
+);
+function buildTools(engine) {
+  const getEntitySchema = z.object({
+    id: z.string().describe("EntityId to retrieve."),
+    include: z.array(z.literal("links")).optional().describe("Set to ['links'] to also return the entity's inbound + outbound links.")
+  });
+  const getEntityTool = {
+    name: "kb_get_entity",
+    description: "Retrieve a single entity by ID, optionally including its outbound and inbound links.",
+    inputShape: getEntitySchema.shape,
+    handler: (input) => {
+      const r = getEntitySchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { id, include } = r.data;
+      return envelopeToResult(engine.get({ id, ...include !== void 0 ? { include } : {} }));
+    }
+  };
+  const findEntitiesSchema = z.object({
+    entity: z.string().describe("Entity type name to query (see kb_describe_schema.entities)."),
+    where: whereSchema.optional(),
+    order_by: z.string().optional().describe("Field name to sort by."),
+    order: z.enum(["asc", "desc"]).optional().describe("Sort direction (default asc)."),
+    limit: z.number().optional().describe("Maximum rows to return."),
+    offset: z.number().optional().describe("Rows to skip, for pagination.")
+  });
+  const findEntitiesTool = {
+    name: "kb_find_entities",
+    description: "Query entities of a given type with optional filtering, sorting, and pagination.",
+    inputShape: findEntitiesSchema.shape,
+    handler: (input) => {
+      const r = findEntitiesSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { entity, where, order_by, order, limit, offset } = r.data;
+      return envelopeToResult(
+        engine.find({
+          entity,
+          ...where !== void 0 ? { where } : {},
+          ...order_by !== void 0 ? { order_by } : {},
+          ...order !== void 0 ? { order } : {},
+          ...limit !== void 0 ? { limit } : {},
+          ...offset !== void 0 ? { offset } : {}
+        })
+      );
+    }
+  };
+  const relatedSchema = z.object({
+    id: z.string().describe("EntityId to traverse from."),
+    depth: z.number().optional().describe("Maximum traversal hops (default 1)."),
+    relations: z.array(z.string()).optional().describe("Restrict traversal to these relation names (default: all)."),
+    direction: z.enum(["out", "in", "both"]).optional().describe("Edge direction to follow: out, in, or both (default both).")
+  });
+  const relatedTool = {
+    name: "kb_related",
+    description: "Traverse the knowledge graph from an entity and return related nodes and edges.",
+    inputShape: relatedSchema.shape,
+    handler: (input) => {
+      const r = relatedSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { id, depth, relations, direction } = r.data;
+      return envelopeToResult(
+        engine.related({
+          id,
+          ...depth !== void 0 ? { depth } : {},
+          ...relations !== void 0 ? { relations } : {},
+          ...direction !== void 0 ? { direction } : {}
+        })
+      );
+    }
+  };
+  const traceSchema = z.object({
+    id: z.string().describe("Root EntityId to trace from.")
+  });
+  const traceTool = {
+    name: "kb_trace",
+    description: "Produce a nested trace tree from a root entity following configured trace paths.",
+    inputShape: traceSchema.shape,
+    handler: (input) => {
+      const r = traceSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      return envelopeToResult(engine.trace({ id: r.data.id }));
+    }
+  };
+  const searchSchema = z.object({
+    text: z.string().describe("Query text to search for."),
+    types: z.array(z.string()).optional().describe("Restrict results to these entity type names (default: all types)."),
+    mode: z.enum(["fts", "semantic", "hybrid"]).optional().describe(
+      "Search mode: fts (keyword, default), semantic or hybrid (both require vector_enabled)."
+    ),
+    limit: z.number().optional().describe("Maximum hits to return.")
+  });
+  const searchTool = {
+    name: "kb_search",
+    description: "Search entities using one of three modes: fts (keyword full-text search), semantic (meaning/vector similarity \u2014 requires vectors enabled), or hybrid (RRF fusion of fts and semantic \u2014 also requires vectors enabled). The semantic and hybrid modes return a FEATURE_DISABLED error when vectors are not enabled. Check kb_status.vector_enabled before using semantic or hybrid. Results are ranked by relevance with optional type filter.",
+    inputShape: searchSchema.shape,
+    handler: (input) => {
+      const r = searchSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { text, types, mode, limit } = r.data;
+      return envelopeToResult(
+        engine.search({
+          text,
+          ...types !== void 0 ? { types } : {},
+          ...mode !== void 0 ? { mode } : {},
+          ...limit !== void 0 ? { limit } : {}
+        })
+      );
+    }
+  };
+  const contextPackSchema = z.object({
+    id: z.string().describe("EntityId to build the context pack for."),
+    recipe: z.string().optional().describe("Named context recipe (see kb_describe_schema.recipes)."),
+    max_depth: z.number().optional().describe("Maximum traversal depth for the recipe.")
+  });
+  const contextPackTool = {
+    name: "kb_get_context_pack",
+    description: "Assemble a context pack for an entity using a named recipe and optional max traversal depth.",
+    inputShape: contextPackSchema.shape,
+    handler: (input) => {
+      const r = contextPackSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { id, recipe, max_depth } = r.data;
+      return envelopeToResult(
+        engine.context({
+          id,
+          ...recipe !== void 0 ? { recipe } : {},
+          ...max_depth !== void 0 ? { maxDepth: max_depth } : {}
+        })
+      );
+    }
+  };
+  const proposeSchema = z.object({
+    by: z.string().describe("Actor proposing the change set (agent or user id)."),
+    reason: z.string().describe("Human-readable reason for the change set."),
+    ops: z.array(mcpOpSchema).describe("Ordered operations applied atomically on acceptance.")
+  });
+  const proposeTool = {
+    name: "kb_propose_change_set",
+    description: "Submit a new change set (list of ops) for validation and optional acceptance.",
+    inputShape: proposeSchema.shape,
+    handler: (input) => {
+      const r = proposeSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { by, reason, ops } = r.data;
+      return envelopeToResult(engine.propose({ changeSet: { by, reason, ops } }));
+    }
+  };
+  const validateSchema = z.object({
+    changeset_id: z.string().optional().describe("Id of a stored change set to validate."),
+    changeset: z.looseObject({
+      by: z.string().optional().describe("Actor who authored the change set."),
+      reason: z.string().optional().describe("Reason for the change set."),
+      ops: z.array(z.record(z.string(), z.unknown())).optional().describe("Operations to validate; see kb_propose_change_set for the op structure.")
+    }).optional().describe(
+      `A change set to validate inline (typically the full stored object, incl. id/status); its ops mirror kb_propose_change_set \u2014 ${DESCRIBE_HINT}. Prefer changeset_id for a stored set. Kept permissive (unknown keys preserved) so a possibly-invalid change set is REPORTED as violations rather than rejected here.`
+    )
+  });
+  const validateTool = {
+    name: "kb_validate_change_set",
+    description: "Validate a change set by ID (from storage) or by providing the change-set object inline.",
+    inputShape: validateSchema.shape,
+    handler: (input) => {
+      const r = validateSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { changeset_id, changeset } = r.data;
+      return envelopeToResult(
+        engine.validate({
+          ...changeset_id !== void 0 ? { id: changeset_id } : {},
+          ...changeset !== void 0 ? { changeSet: changeset } : {}
+        })
+      );
+    }
+  };
+  const acceptSchema = z.object({
+    changeset_id: z.string().describe("Id of the proposed change set to accept."),
+    by: z.string().optional().describe("Actor accepting the change set.")
+  });
+  const acceptTool = {
+    name: "kb_accept_change_set",
+    description: "Accept a proposed change set, applying its ops to the knowledge base.",
+    inputShape: acceptSchema.shape,
+    handler: (input) => {
+      const r = acceptSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { changeset_id, by } = r.data;
+      return envelopeToResult(
+        engine.accept({ id: changeset_id, ...by !== void 0 ? { by } : {} })
+      );
+    }
+  };
+  const rejectSchema = z.object({
+    changeset_id: z.string().describe("Id of the proposed change set to reject."),
+    reason: z.string().describe("Mandatory reason for rejecting the change set."),
+    by: z.string().optional().describe("Actor rejecting the change set.")
+  });
+  const rejectTool = {
+    name: "kb_reject_change_set",
+    description: "Reject a proposed change set with a mandatory reason.",
+    inputShape: rejectSchema.shape,
+    handler: (input) => {
+      const r = rejectSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { changeset_id, reason, by } = r.data;
+      return envelopeToResult(
+        engine.reject({ id: changeset_id, reason, ...by !== void 0 ? { by } : {} })
+      );
+    }
+  };
+  const recordAgentRunSchema = z.object({
+    by: z.string().describe("Actor recording the run (agent or user id)."),
+    reason: z.string().optional().describe('Reason for the change set (defaults to "record agent run").'),
+    fields: z.record(z.string(), z.unknown()).describe(`Fields for the AgentRun entity, keyed by field name \u2014 ${DESCRIBE_HINT}.`)
+  });
+  const recordAgentRunTool = {
+    name: "kb_record_agent_run",
+    description: "Sugar: propose a change set that creates a single AgentRun entity with the given fields. The engine re-validates the AgentRun type against the current schema.",
+    inputShape: recordAgentRunSchema.shape,
+    handler: (input) => {
+      const r = recordAgentRunSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { by, reason, fields } = r.data;
+      const changeSet = {
+        by,
+        reason: reason ?? "record agent run",
+        ops: [
+          {
+            op: "create",
+            entity: "AgentRun",
+            handle: "@agent-run",
+            fields
+          }
+        ]
+      };
+      return envelopeToResult(engine.propose({ changeSet }));
+    }
+  };
+  const statusTool = {
+    name: "kb_status",
+    description: "Report KB health: entity counts by type, number of pending change sets, index_healthy (FTS/derived index fingerprint match), and vector_enabled (whether semantic search is available). Check vector_enabled before using semantic or hybrid search modes in kb_search.",
+    inputShape: {},
+    handler: (_input) => {
+      return envelopeToResult(engine.status());
+    }
+  };
+  const reindexTool = {
+    name: "kb_reindex",
+    description: "Rebuild the derived index (FTS + vectors when enabled). Use this to recover after VECTOR_INDEX_FAILED / VECTOR_DIM_MISMATCH or to backfill vectors after enabling them. Returns the new canonical fingerprint on success.",
+    inputShape: {},
+    handler: (_input) => {
+      return envelopeToResult(engine.reindex());
+    }
+  };
+  const listChangeSetsSchema = z.object({
+    status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional().describe("Filter by change-set status (default: all).")
+  });
+  const listChangeSetsTool = {
+    name: "kb_list_change_sets",
+    description: "List change sets, optionally filtered by status (proposed/accepted/rejected/superseded). Use this to discover change-set ids for accept/reject and to see what is pending.",
+    inputShape: listChangeSetsSchema.shape,
+    handler: (input) => {
+      const r = listChangeSetsSchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { status } = r.data;
+      return envelopeToResult(engine.listChangeSets(status !== void 0 ? { status } : {}));
+    }
+  };
+  const verifySchema = z.object({
+    events: z.boolean().optional().describe("Set true to also verify the event log.")
+  });
+  const verifyTool = {
+    name: "kb_verify",
+    description: "Check knowledge-base integrity (referential consistency, dangling links, etc.); set events: true to also verify the event log. Returns a report of findings.",
+    inputShape: verifySchema.shape,
+    handler: (input) => {
+      const r = verifySchema.safeParse(input);
+      if (!r.success) return parseErr(r.error);
+      const { events } = r.data;
+      return envelopeToResult(engine.verify(events ? { events: true } : {}));
+    }
+  };
+  const describeSchemaSchema = z.object({});
+  const describeSchemaTool = {
+    name: "kb_describe_schema",
+    description: "Return the knowledge-base schema \u2014 entity types with their fields (name/type/required), relations, and context recipes. Call this FIRST to learn what entity types and fields you can create and query.",
+    inputShape: describeSchemaSchema.shape,
+    handler: (_input) => {
+      return envelopeToResult(engine.describeSchema());
+    }
+  };
+  return [
+    getEntityTool,
+    findEntitiesTool,
+    relatedTool,
+    traceTool,
+    searchTool,
+    contextPackTool,
+    proposeTool,
+    validateTool,
+    acceptTool,
+    rejectTool,
+    recordAgentRunTool,
+    statusTool,
+    reindexTool,
+    listChangeSetsTool,
+    verifyTool,
+    describeSchemaTool
+  ];
+}
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+var MCP_INSTRUCTIONS = `
+Agent KB is a local knowledge graph of typed entities and relations, edited via change sets.
+
+Getting started:
+1. Call kb_describe_schema FIRST to learn the available entity types, their fields, and relations.
+
+Write workflow:
+- kb_propose_change_set \u2192 (optional) kb_validate_change_set \u2192 kb_accept_change_set
+- Discover existing change set IDs with kb_list_change_sets.
+
+Search:
+- kb_search supports modes: fts (full-text), semantic, and hybrid.
+- Check kb_status.vector_enabled before using semantic or hybrid modes \u2014 if false, those modes return FEATURE_DISABLED.
+
+Recovery:
+- After VECTOR_INDEX_FAILED or VECTOR_DIM_MISMATCH errors, call kb_reindex to rebuild the index.
+- For data integrity issues, call kb_verify.
+`.trim();
+function createMcpServer(opts) {
+  if (!opts.mcpEnabled) {
+    throw featureDisabled("MCP server is disabled (set mcp.enabled = true in config)");
+  }
+  const server = new McpServer(
+    { name: "agent-kb", version: "0.1.0" },
+    { instructions: MCP_INSTRUCTIONS }
+  );
+  const tools = buildTools(opts.engine);
+  for (const tool of tools) {
+    server.registerTool(
+      tool.name,
+      { description: tool.description, inputSchema: tool.inputShape },
+      // The SDK validates args against inputSchema before calling this handler;
+      // we also parse defensively inside tool.handler. Wrap in async to satisfy
+      // the SDK's Promise-returning callback expectation.
+      async (args) => tool.handler(args)
+    );
+  }
+  return server;
+}
+
+// src/cli/mcp-command.ts
+function isMcpInvocation(argv) {
+  const args = argv.slice(2);
+  let i = 0;
+  while (i < args.length) {
+    const tok = args[i];
+    if (tok === void 0) break;
+    if (tok === "--json" || tok === "--verbose") {
+      i += 1;
+      continue;
+    }
+    if (tok === "--root") {
+      i += 2;
+      continue;
+    }
+    if (tok.startsWith("--root=")) {
+      i += 1;
+      continue;
+    }
+    return tok === "mcp";
+  }
+  return false;
+}
+function parseMcpArgs(argv, cwd) {
+  const args = argv.slice(2);
+  let root;
+  let json = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const tok = args[i];
+    if (tok === void 0) continue;
+    if (tok === "--json") {
+      json = true;
+    } else if (tok === "--root") {
+      const val = args[i + 1];
+      if (val !== void 0) {
+        root = val;
+        i += 1;
+      }
+    } else if (tok.startsWith("--root=")) {
+      root = tok.slice("--root=".length);
+    }
+  }
+  return { root: root ?? cwd, json };
+}
+async function connectStdio(server, deps) {
+  const createTransport = deps?.createTransport ?? (() => new StdioServerTransport());
+  const stdin = deps?.stdin ?? process.stdin;
+  const signals = deps?.signals ?? process;
+  const transport = createTransport();
+  let closing = false;
+  const closeTransport = () => {
+    if (closing) return;
+    closing = true;
+    void transport.close();
+  };
+  const closed = new Promise((resolve) => {
+    transport.onclose = resolve;
+  });
+  const onStdinDone = () => closeTransport();
+  const onSignal = () => closeTransport();
+  stdin.once("end", onStdinDone);
+  stdin.once("error", onStdinDone);
+  stdin.once("close", onStdinDone);
+  signals.once("SIGINT", onSignal);
+  signals.once("SIGTERM", onSignal);
+  try {
+    await server.connect(transport);
+    await closed;
+  } finally {
+    stdin.removeListener("end", onStdinDone);
+    stdin.removeListener("error", onStdinDone);
+    stdin.removeListener("close", onStdinDone);
+    signals.removeListener("SIGINT", onSignal);
+    signals.removeListener("SIGTERM", onSignal);
+  }
+}
+var defaultConnect = (server) => connectStdio(server);
+async function runMcp(argv, deps) {
+  const out = deps?.out ?? process.stdout;
+  const err = deps?.err ?? process.stderr;
+  const openKbFn = deps?.openKb ?? openKb;
+  const loadConfigFn = deps?.loadConfig ?? load;
+  const createServerFn = deps?.createServer ?? createMcpServer;
+  const connectFn = deps?.connect ?? defaultConnect;
+  const cwd = deps?.cwd ?? process.cwd();
+  const { root, json } = parseMcpArgs(argv, cwd);
+  let engine;
+  try {
+    engine = openKbFn({ root });
+    const config = loadConfigFn(root);
+    const server = createServerFn({ engine, mcpEnabled: config.mcp.enabled });
+    await connectFn(server);
+    return 0;
+  } catch (e) {
+    const code = e instanceof KbError ? e.code : "INTERNAL";
+    const message = e instanceof Error ? e.message : String(e);
+    const env = { ok: false, error: { code, message } };
+    if (json) {
+      out.write(JSON.stringify(env) + "\n");
+    } else {
+      err.write(`[${code}] ${message}
+`);
+    }
+    return exitCodeFor(env);
+  } finally {
+    try {
+      engine?.close();
+    } catch {
+    }
+  }
+}
+
+// src/cli/index.ts
+function intArg(v) {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0)
+    throw new InvalidArgumentError("expected a non-negative integer");
+  return n;
+}
+function runCli(argv, deps) {
+  const out = deps?.out ?? process.stdout;
+  const err = deps?.err ?? process.stderr;
+  const openKbFn = deps?.openKb ?? openKb;
+  const cwd = deps?.cwd ?? process.cwd();
+  const homedirFn = deps?.homedir ?? os2.homedir;
+  let exitCode = 0;
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: (s) => out.write(s),
+    writeErr: (s) => err.write(s)
+  });
+  program.name("agent-kb").description("Agent KB knowledge base CLI").version("0.1.0").option("--json", "output as JSON (machine-readable)").option("--verbose", "enable verbose logging").option("--root <dir>", "project root directory");
+  function globalOpts() {
+    return program.opts();
+  }
+  function dispatch(call, exitFor = exitCodeFor) {
+    const opts = globalOpts();
+    const root = opts.root ?? cwd;
+    let env;
+    let engine;
+    try {
+      engine = openKbFn({ root });
+      env = call(engine);
+    } catch (e) {
+      const code = e instanceof KbError ? e.code : "INTERNAL";
+      const message = e instanceof Error ? e.message : String(e);
+      env = { ok: false, error: { code, message } };
+    } finally {
+      try {
+        engine?.close?.();
+      } catch {
+      }
+    }
+    render(env, opts.json ?? false, out, err);
+    return exitFor(env);
+  }
+  function render(env, json, outStream, errStream) {
+    if (json) {
+      outStream.write(JSON.stringify(env) + "\n");
+      return;
+    }
+    if (env.ok) {
+      outStream.write(JSON.stringify(env.data, null, 2) + "\n");
+    } else {
+      errStream.write(`[${env.error.code}] ${env.error.message}
+`);
+    }
+  }
+  program.command("init").description("Initialise a new Agent KB in this project").option("--force", "overwrite existing .agent-kb/").option(
+    "--skill [scope]",
+    "also install the agent-kb Claude skill ('global' or 'project', default 'project')"
+  ).action((opts) => {
+    const root = globalOpts().root ?? cwd;
+    if (opts.skill !== void 0) {
+      const parsed = parseSkillScope(opts.skill);
+      if (!parsed.ok) {
+        const errEnv = {
+          ok: false,
+          error: { code: "VALIDATION_ERROR", message: parsed.message }
+        };
+        render(errEnv, globalOpts().json ?? false, out, err);
+        exitCode = exitCodeFor(errEnv);
+        return;
+      }
+      exitCode = dispatch((engine) => {
+        const initEnv = engine.init(opts.force ? { force: true } : {});
+        if (!initEnv.ok) return initEnv;
+        const { path: skillPath } = installSkill(parsed.scope, root, homedirFn());
+        const initData = initEnv.data;
+        return { ok: true, data: { ...initData, skill: skillPath } };
+      });
+    } else {
+      exitCode = dispatch((engine) => engine.init(opts.force ? { force: true } : {}));
+    }
+  });
+  program.command("status").description("Show KB status").action(() => {
+    exitCode = dispatch((engine) => engine.status());
+  });
+  program.command("reindex").description("Rebuild the index from canonical files").action(() => {
+    exitCode = dispatch((engine) => engine.reindex());
+  });
+  const schemaCmd = program.command("schema").description("Schema management");
+  schemaCmd.command("apply <file>").description("Validate + install a schema file and reindex; --dry-run validates only").option("--dry-run", "validate the schema file without writing or reindexing").action((file, opts) => {
+    exitCode = dispatch(
+      (engine) => engine.applySchema({ file, ...opts.dryRun === true ? { dryRun: true } : {} }),
+      (env) => {
+        if (env.ok) {
+          const r = env.data;
+          if (r.applied === false && Array.isArray(r.violations) && r.violations.length > 0) {
+            return 1;
+          }
+        }
+        return exitCodeFor(env);
+      }
+    );
+  });
+  schemaCmd.command("describe").description("Show the knowledge-base schema: entity types, their fields, and relations").action(() => {
+    exitCode = dispatch((engine) => engine.describeSchema());
+  });
+  program.command("migrate").description("Run pending migrations").option("--allow-data-loss", "allow destructive migration steps").action((opts) => {
+    exitCode = dispatch(
+      (engine) => engine.migrate(opts.allowDataLoss ? { allowDataLoss: true } : {})
+    );
+  });
+  program.command("get <id>").description("Get an entity by ID").option("--links", "include linked entity IDs").action((id, opts) => {
+    exitCode = dispatch((engine) => engine.get(opts.links ? { id, include: ["links"] } : { id }));
+  });
+  program.command("find <type>").description("Find entities by type with optional filters").option("--where <json>", "filter clause as JSON").addOption(new Option("--limit <n>", "max results").argParser(intArg)).addOption(new Option("--offset <n>", "skip N results").argParser(intArg)).option("--order-by <field>", "field to sort by").option("--desc", "sort descending (default: asc)").action(
+    (type, opts) => {
+      exitCode = dispatch((engine) => {
+        let parsedWhere;
+        if (opts.where !== void 0) {
+          try {
+            parsedWhere = JSON.parse(opts.where);
+          } catch {
+            const errEnv = {
+              ok: false,
+              error: { code: "VALIDATION_ERROR", message: `invalid --where JSON: ${opts.where}` }
+            };
+            return errEnv;
+          }
+        }
+        return engine.find({
+          entity: type,
+          ...parsedWhere !== void 0 ? { where: parsedWhere } : {},
+          // Only send order/order_by when --order-by is explicitly provided
+          ...opts.orderBy !== void 0 ? { order_by: opts.orderBy, order: opts.desc ? "desc" : "asc" } : {},
+          ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+          ...opts.offset !== void 0 ? { offset: opts.offset } : {}
+        });
+      });
+    }
+  );
+  program.command("related <id>").description("Get related entities").addOption(new Option("--depth <n>", "traversal depth").argParser(intArg)).option("--relations <list>", "comma-separated relation names").addOption(new Option("--dir <dir>", "direction: out|in|both").choices(["out", "in", "both"])).action(
+    (id, opts) => {
+      exitCode = dispatch(
+        (engine) => engine.related({
+          id,
+          ...opts.depth !== void 0 ? { depth: opts.depth } : {},
+          ...opts.relations !== void 0 ? { relations: opts.relations.split(",") } : {},
+          ...opts.dir !== void 0 ? { direction: opts.dir } : {}
+        })
+      );
+    }
+  );
+  program.command("trace <id>").description("Trace the dependency tree from an entity").action((id) => {
+    exitCode = dispatch((engine) => engine.trace({ id }));
+  });
+  program.command("search <text>").description("Full-text or semantic search").option("--types <list>", "comma-separated entity types to restrict search").addOption(
+    new Option("--mode <mode>", "search mode: fts|semantic|hybrid").choices([
+      "fts",
+      "semantic",
+      "hybrid"
+    ])
+  ).addOption(new Option("--limit <n>", "max results").argParser(intArg)).action(
+    (text, opts) => {
+      exitCode = dispatch(
+        (engine) => engine.search({
+          text,
+          ...opts.types !== void 0 ? { types: opts.types.split(",") } : {},
+          ...opts.mode !== void 0 ? { mode: opts.mode } : {},
+          ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+        })
+      );
+    }
+  );
+  program.command("context <id>").description("Assemble a context pack for an entity").option("--recipe <name>", "context recipe name").addOption(new Option("--max-depth <n>", "max traversal depth").argParser(intArg)).action((id, opts) => {
+    exitCode = dispatch(
+      (engine) => engine.context({
+        id,
+        ...opts.recipe !== void 0 ? { recipe: opts.recipe } : {},
+        ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
+      })
+    );
+  });
+  program.command("why <id>").description("Explain why an entity is relevant to a root context").requiredOption("--in-context <root>", "root entity ID for context").option("--recipe <name>", "context recipe name").action((id, opts) => {
+    exitCode = dispatch(
+      (engine) => engine.why({
+        id,
+        root: opts.inContext,
+        ...opts.recipe !== void 0 ? { recipe: opts.recipe } : {}
+      })
+    );
+  });
+  program.command("propose <file>").description("Propose a change set from a JSON file").action((file) => {
+    exitCode = dispatch((engine) => {
+      let changeSet;
+      try {
+        const raw = fs2.readFileSync(file, "utf8");
+        changeSet = JSON.parse(raw);
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const errEnv = {
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `cannot read/parse changeset file: ${message}`
+          }
+        };
+        return errEnv;
+      }
+      return engine.propose({ changeSet });
+    });
+  });
+  program.command("validate <idOrFile>").description("Validate a change set (by ID or JSON file path)").action((idOrFile) => {
+    exitCode = dispatch((engine) => {
+      if (fs2.existsSync(idOrFile)) {
+        let changeSet;
+        try {
+          const raw = fs2.readFileSync(idOrFile, "utf8");
+          changeSet = JSON.parse(raw);
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          const errEnv = {
+            ok: false,
+            error: {
+              code: "VALIDATION_ERROR",
+              message: `cannot read/parse changeset file: ${message}`
+            }
+          };
+          return errEnv;
+        }
+        return engine.validate({ changeSet });
+      }
+      return engine.validate({ id: idOrFile });
+    });
+  });
+  program.command("accept <id>").description("Accept a proposed change set").option("--by <actor>", "actor accepting the change set").action((id, opts) => {
+    exitCode = dispatch(
+      (engine) => engine.accept({
+        id,
+        ...opts.by !== void 0 ? { by: opts.by } : {}
+      })
+    );
+  });
+  program.command("reject <id>").description("Reject a proposed change set").requiredOption("--reason <text>", "rejection reason").option("--by <actor>", "actor rejecting the change set").action((id, opts) => {
+    exitCode = dispatch(
+      (engine) => engine.reject({
+        id,
+        reason: opts.reason,
+        ...opts.by !== void 0 ? { by: opts.by } : {}
+      })
+    );
+  });
+  program.command("changesets").description("List change sets").addOption(
+    new Option("--status <s>", "filter by status").choices([
+      "proposed",
+      "accepted",
+      "rejected",
+      "superseded"
+    ])
+  ).action((opts) => {
+    exitCode = dispatch(
+      (engine) => engine.listChangeSets(opts.status !== void 0 ? { status: opts.status } : {})
+    );
+  });
+  const docsCmd = program.command("docs").description("Documentation generation");
+  docsCmd.command("generate").description("Generate docs from the KB").action(() => {
+    exitCode = dispatch((engine) => engine.generateDocs());
+  });
+  program.command("scan").description("Scan source code for KB entities").option("--propose", "create a proposed change set from scan findings").action((opts) => {
+    exitCode = dispatch((engine) => engine.scan(opts.propose ? { propose: true } : {}));
+  });
+  program.command("verify").description("Verify KB integrity").option("--events", "include event log verification").action((opts) => {
+    exitCode = dispatch(
+      (engine) => engine.verify(opts.events ? { events: true } : {}),
+      (env) => env.ok && hasBlockingFindings(env.data) ? 1 : exitCodeFor(env)
+    );
+  });
+  const snapshotCmd = program.command("snapshot").description("Snapshot management");
+  snapshotCmd.command("create").description("Create a KB snapshot").option("--name <n>", "snapshot name").action((opts) => {
+    exitCode = dispatch(
+      (engine) => engine.snapshot(opts.name !== void 0 ? { name: opts.name } : {})
+    );
+  });
+  program.command("export").description("Export the KB").addOption(
+    new Option("--format <fmt>", "export format: json or graph").choices(["json", "graph"]).makeOptionMandatory()
+  ).action((opts) => {
+    exitCode = dispatch((engine) => engine.export({ format: opts.format }));
+  });
+  const skillCmd = program.command("skill").description("Skill management");
+  skillCmd.command("install [scope]").description(
+    "Install the agent-kb Claude skill (scope: 'global' or 'project', default 'project')"
+  ).action((scope) => {
+    const root = globalOpts().root ?? cwd;
+    const parsed = parseSkillScope(scope ?? "project");
+    if (!parsed.ok) {
+      const env = {
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: parsed.message }
+      };
+      render(env, globalOpts().json ?? false, out, err);
+      exitCode = exitCodeFor(env);
+      return;
+    }
+    try {
+      const { path: skillPath } = installSkill(parsed.scope, root, homedirFn());
+      const env = { ok: true, data: { skill: skillPath } };
+      render(env, globalOpts().json ?? false, out, err);
+      exitCode = exitCodeFor(env);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      const env = {
+        ok: false,
+        error: { code: "IO_ERROR", message }
+      };
+      render(env, globalOpts().json ?? false, out, err);
+      exitCode = exitCodeFor(env);
+    }
+  });
+  program.command("mcp").description("Run the MCP server over stdio (requires mcp.enabled in config)").action(() => {
+    err.write(
+      "[INTERNAL] `agent-kb mcp` must be launched via the entry point (npx agent-kb mcp)\n"
+    );
+    exitCode = 4;
+  });
+  try {
+    program.parse(argv, { from: "node" });
+  } catch (e) {
+    if (e instanceof CommanderError) {
+      return e.exitCode === 0 ? 0 : 2;
+    }
+    return 4;
+  }
+  return exitCode;
+}
+async function main(argv, deps) {
+  if (isMcpInvocation(argv)) {
+    return runMcp(argv, deps);
+  }
+  return runCli(argv, deps);
+}
+function isEntryPoint() {
+  const argv1 = process.argv[1];
+  if (argv1 === void 0) return false;
+  let resolved = argv1;
+  try {
+    resolved = fs2.realpathSync(argv1);
+  } catch {
+  }
+  return import.meta.url === pathToFileURL(resolved).href;
+}
+if (isEntryPoint()) {
+  void main(process.argv).then(
+    (code) => process.exit(code),
+    () => process.exit(4)
+  );
+}
+export {
+  main,
+  runCli
+};