@dikolab/kbdb 0.6.3 → 0.6.4

package/dist/cli.mjs

@@ -659,6 +659,120 @@ function computeDirectoryLevel(filePath, basePath) {
   return Math.min(depth + 1, MAX_LEVEL);
 }
 
+// src/shared/cli/functions/learn-markdown-document.function.ts
+import { basename as basename2 } from "node:path";
+
+// src/shared/cli/functions/split-markdown-sections.function.ts
+var HEADING_PATTERN = /^(#{1,6})\s+(.+)$/;
+function splitMarkdownSections(content) {
+  const sections = [];
+  let draft = { lines: [] };
+  let inCodeBlock = false;
+  for (const line of content.split("\n")) {
+    if (line.startsWith("```") || line.startsWith("~~~")) {
+      inCodeBlock = !inCodeBlock;
+      draft.lines.push(line);
+      continue;
+    }
+    const heading = inCodeBlock ? null : HEADING_PATTERN.exec(line);
+    if (heading) {
+      flushSection(draft, sections);
+      draft = {
+        title: heading[2].trim(),
+        level: heading[1].length,
+        lines: []
+      };
+      continue;
+    }
+    draft.lines.push(line);
+  }
+  flushSection(draft, sections);
+  return sections.length > 0 ? sections : [{ content: content.trimEnd() }];
+}
+function flushSection(draft, sections) {
+  const body = draft.lines.join("\n").trimEnd();
+  if (draft.title === void 0 && body.length === 0) return;
+  sections.push(
+    draft.title === void 0 ? { content: body } : { title: draft.title, level: draft.level, content: body }
+  );
+}
+
+// src/shared/cli/functions/map-add-section-result.function.ts
+function mapAddSectionResult(result, path, size, sectionType) {
+  return {
+    kbid: result.items[0] ?? "",
+    indexed_terms_count: 0,
+    type: sectionType,
+    path,
+    size,
+    skipped: false,
+    superseded: result.superseded ?? null,
+    warnings: result.warnings ?? [],
+    near_duplicates: result.near_duplicates ?? []
+  };
+}
+
+// src/shared/cli/functions/learn-markdown-document.function.ts
+async function learnMarkdownDocument(client, options, path, content, sourcePath) {
+  const sections = splitMarkdownSections(content);
+  const titled = sections.filter((s) => s.title !== void 0);
+  if (sections.length < 2 || titled.length === 0) return void 0;
+  const docTitle = titled[0]?.title ?? basename2(path);
+  const kbids = [];
+  const results = [];
+  for (const section of sections) {
+    const added = await client.addSection({
+      sectionType: "text",
+      content: section.content,
+      title: section.title,
+      description: options.description,
+      docid: path,
+      tags: options.tags,
+      replace: options.replace,
+      sourcePath,
+      level: section.level
+    });
+    kbids.push(added.items[0] ?? "");
+    results.push(
+      mapAddSectionResult(
+        added,
+        path,
+        section.content.length,
+        "text"
+      )
+    );
+  }
+  await client.groupSections(docTitle, kbids);
+  return results;
+}
+
+// src/shared/cli/functions/learn-target-content.function.ts
+async function learnTargetContent(client, options, path, content, sourcePath, level) {
+  const markdownEligible = (path === "-" || path.endsWith(".md")) && !options.title;
+  if (markdownEligible) {
+    const split = await learnMarkdownDocument(
+      client,
+      options,
+      path,
+      content,
+      sourcePath
+    );
+    if (split) return split;
+  }
+  const result = await client.addSection({
+    sectionType: "text",
+    content,
+    title: options.title,
+    description: options.description,
+    docid: options.docid,
+    tags: options.tags,
+    replace: options.replace,
+    sourcePath,
+    level
+  });
+  return [mapAddSectionResult(result, path, content.length, "text")];
+}
+
 // src/shared/cli/functions/run-learn.function.ts
 async function runLearn(client, options, io) {
   log(
@@ -673,37 +787,30 @@ async function runLearn(client, options, io) {
       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,
-        tags: options.tags,
-        replace: options.replace,
-        level: options.level
-      });
       results.push(
-        mapAddSectionResult(result, "-", content.length, "text")
+        ...await learnTargetContent(
+          client,
+          options,
+          "-",
+          content,
+          void 0,
+          options.level
+        )
       );
       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,
-        description: options.description,
-        docid: options.docid,
-        tags: options.tags,
-        replace: options.replace,
-        sourcePath: file,
-        level: options.level ?? computeDirectoryLevel(file, target)
-      });
       results.push(
-        mapAddSectionResult(result, file, content.length, "text")
+        ...await learnTargetContent(
+          client,
+          options,
+          file,
+          content,
+          file,
+          options.level ?? computeDirectoryLevel(file, target)
+        )
       );
     }
   }
@@ -713,19 +820,6 @@ async function runLearn(client, options, io) {
   );
   return results;
 }
-function mapAddSectionResult(result, path, size, sectionType) {
-  return {
-    kbid: result.items[0] ?? "",
-    indexed_terms_count: 0,
-    type: sectionType,
-    path,
-    size,
-    skipped: false,
-    superseded: result.superseded ?? null,
-    warnings: result.warnings ?? [],
-    near_duplicates: result.near_duplicates ?? []
-  };
-}
 function readProcessStdin() {
   return new Promise((resolve7) => {
     const chunks = [];
@@ -1113,28 +1207,27 @@ async function runSkillLearn(client, options) {
   };
 }
 
+// src/shared/query-filter/functions/matches-query.function.ts
+function matchesQuery(query, ...fields) {
+  if (!query) return true;
+  const needle = query.toLowerCase();
+  return fields.some(
+    (field) => typeof field === "string" && field.toLowerCase().includes(needle)
+  );
+}
+
 // src/shared/cli/functions/run-skill-list.function.ts
-async function runSkillList(client, _options) {
+async function runSkillList(client, options) {
   log("running skill-list", 0 /* DEBUG */);
   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
-    };
-  });
+  const query = options.args.join(" ").toLowerCase();
+  const filtered = records.filter(
+    (r) => matchesQuery(query, r.title, r.description)
+  );
+  const names = filtered.map((r) => r.title);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
-    output: JSON.stringify(items, null, 2),
+    output: JSON.stringify(data, null, 2),
     exitCode: 0
   };
 }
@@ -1263,16 +1356,15 @@ async function runAgentCreate(client, options) {
 }
 
 // src/shared/cli/functions/run-agent-list.function.ts
-async function runAgentList(client, _options) {
+async function runAgentList(client, options) {
   log("running agent-list", 0 /* DEBUG */);
   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)
-  }));
+  const query = options.args.join(" ").toLowerCase();
+  const filtered = docs.filter((d) => matchesQuery(query, d.title));
+  const names = filtered.map((d) => d.title);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
-    output: JSON.stringify(items, null, 2),
+    output: JSON.stringify(data, null, 2),
     exitCode: 0
   };
 }
@@ -1740,7 +1832,7 @@ async function handleTypedSearch(client, options, type) {
 }
 
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.6.3";
+var VERSION = "0.6.4";
 
 // src/shared/cli/functions/generate-help.function.ts
 var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
@@ -1768,13 +1860,13 @@ var GROUP_SUBCOMMANDS = {
   ],
   skill: [
     ["learn", "Create a new skill definition"],
-    ["list", "List all skills"],
+    ["list", "List skills (filter by keyword)"],
     ["get", "Retrieve a skill by name or kbid"],
     ["delete", "Remove a skill"]
   ],
   agent: [
     ["create", "Create an agent with skill refs"],
-    ["list", "List all agents"],
+    ["list", "List agents (filter by keyword)"],
     ["get", "Retrieve an agent by docid"],
     ["delete", "Remove an agent"]
   ],
@@ -1819,9 +1911,9 @@ Usage: kbdb [options]
        kbdb <command> <subcommand> [options] ...[params]
 
 Knowledge Base:
-   learn               Import content from files/stdin
+   learn               Import content (splits .md on headings)
    unlearn             Remove sections by kbid
-   search              Query the knowledge base
+   search              Query the knowledge base (sibling boost)
    recall              Retrieve section context by kbid
    content             Compose rendered content from ids
 
@@ -1840,13 +1932,13 @@ Maintenance:
 
 Skills:
    skill learn         Create a new skill definition
-   skill list          List all skills
+   skill list          List skills (filter by keyword)
    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 list          List agents (filter by keyword)
    agent get           Retrieve an agent by docid
    agent delete        Remove an agent
 
@@ -1918,9 +2010,17 @@ Options:
    --replace           Supersede existing section by source key
    --db <path>         Path to .kbdb directory
 
+Markdown splitting:
+   .md files are automatically split on ATX
+   headings (# through ######) into independent
+   sections. Each section uses its heading as
+   the title and shares a docid for document
+   grouping. Providing --title imports the file
+   as a single section (skips splitting).
+   Non-.md files are never split.
+
 Output:
-   JSON array of { kbid, path, size, skipped,
-                   superseded, warnings, near_duplicates }
+   { items, total, offset } envelope
 
 Examples:
    kbdb learn README.md
@@ -1959,8 +2059,14 @@ Options:
    --content, -c       Hydrate results with section content
    --db <path>         Path to .kbdb directory
 
+Scoring:
+   Results are ranked by BM25F. Sections from
+   the same document (shared docid) receive a
+   sibling score boost when multiple sections
+   match the query.
+
 Output:
-   JSON array of { kbid, score, preview, matches }
+   { items, total, offset } envelope
 
 Examples:
    kbdb search "machine learning"
@@ -2169,16 +2275,20 @@ Examples:
 `,
   "skill-list": `kbdb skill list - List all skills
 
-Usage: kbdb skill list [options]
+Usage: kbdb skill list [options] [keywords...]
+
+Arguments:
+   [keywords...]       Case-insensitive substring filter on name or description
 
 Options:
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON array of { kbid, name, description, argumentCount }
+   JSON { items, total, offset }
 
 Examples:
    kbdb skill list
+   kbdb skill list summarize
    kbdb skill list --db /path/to/project
 `,
   "skill-get": `kbdb skill get - Retrieve a skill by name or kbid
@@ -2234,16 +2344,20 @@ Examples:
 `,
   "agent-list": `kbdb agent list - List all agents
 
-Usage: kbdb agent list [options]
+Usage: kbdb agent list [options] [keywords...]
+
+Arguments:
+   [keywords...]       Case-insensitive substring filter on agent name
 
 Options:
    --db <path>         Path to .kbdb directory
 
 Output:
-   JSON array of { docid, name, description, skillCount }
+   JSON { items, total, offset }
 
 Examples:
    kbdb agent list
+   kbdb agent list reviewer
    kbdb agent list --db /path/to/project
 `,
   "agent-get": `kbdb agent get - Retrieve an agent by docid
@@ -3503,7 +3617,7 @@ function createToolDefinitions() {
   return [
     {
       name: "search",
-      description: "Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use multiple short keyword queries for best coverage. Use recall to get full content.",
+      description: "Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Sections from the same document receive a sibling score boost when multiple sections match. Use multiple short keyword queries for best coverage. Use recall for full content.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3546,7 +3660,7 @@ function createToolDefinitions() {
     },
     {
       name: "learn",
-      description: "Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use replace when updating existing knowledge. Attach tags for scoping.",
+      description: "Import content into the knowledge base. Markdown content is automatically split on ATX headings into independent sections that share a docid. Providing title imports as a single section (skips splitting). Use replace when updating existing knowledge. Attach tags for scoping.",
       inputSchema: {
         type: "object",
         properties: {
@@ -3560,7 +3674,7 @@ function createToolDefinitions() {
           },
           title: {
             type: "string",
-            description: "Section title. Required for image/* types."
+            description: "Section title. Skips markdown splitting when set. Required for image/* types."
           },
           description: {
             type: "string",
@@ -3568,7 +3682,7 @@ function createToolDefinitions() {
           },
           docid: {
             type: "string",
-            description: "Document ID to group under"
+            description: "Document ID to group sections under. Set automatically when markdown splitting is active."
           },
           tags: {
             type: "array",
@@ -3797,10 +3911,15 @@ function createToolDefinitions() {
     },
     {
       name: "skill-list",
-      description: "List all skills in the knowledge base.",
+      description: "List skill definitions stored in the knowledge base, optionally filtered by a substring query.",
       inputSchema: {
         type: "object",
-        properties: {}
+        properties: {
+          query: {
+            type: "string",
+            description: "Case-insensitive substring filter on skill name or description."
+          }
+        }
       },
       annotations: {
         title: "List Skills",
@@ -3891,10 +4010,15 @@ function createToolDefinitions() {
     },
     {
       name: "agent-list",
-      description: "List all agents in the knowledge base.",
+      description: "List agent documents in the knowledge base, optionally filtered by a substring query.",
       inputSchema: {
         type: "object",
-        properties: {}
+        properties: {
+          query: {
+            type: "string",
+            description: "Case-insensitive substring filter on agent name or description."
+          }
+        }
       },
       annotations: {
         title: "List Agents",
@@ -4142,7 +4266,7 @@ async function readAgentDescription(client, sections) {
     return "";
   }
 }
-async function handleAgentList(client) {
+async function handleAgentList(client, args = {}) {
   const docs = await client.listDocumentsByType("agent");
   const items = await Promise.all(
     docs.map(async (d) => ({
@@ -4150,17 +4274,17 @@ async function handleAgentList(client) {
       description: await readAgentDescription(client, d.sections)
     }))
   );
-  const lines = items.map(
-    (item, index) => `${String(index + 1)}. ${item.name}` + (item.description ? ` -- ${item.description}` : "")
-  );
-  const text = [`${String(items.length)} agents:`, ...lines].join(
-    "\n"
+  const query = typeof args["query"] === "string" ? args["query"].toLowerCase() : "";
+  const filtered = items.filter(
+    (item) => matchesQuery(query, item.name, item.description)
   );
+  const names = filtered.map((item) => item.name);
+  const data = { items: names, total: names.length, offset: 0 };
   return {
     content: [
       {
         type: "text",
-        text
+        text: JSON.stringify(data, null, 2)
       }
     ]
   };
@@ -4462,7 +4586,7 @@ async function handleToolCall(client, name, args) {
       case "skill-learn":
         return await handleSkillLearn(client, args);
       case "skill-list":
-        return await handleSkillList(client);
+        return await handleSkillList(client, args);
       case "skill-get":
         return await handleSkillGet(client, args);
       case "skill-delete":
@@ -4470,7 +4594,7 @@ async function handleToolCall(client, name, args) {
       case "agent-create":
         return await handleAgentCreate(client, args);
       case "agent-list":
-        return await handleAgentList(client);
+        return await handleAgentList(client, args);
       case "agent-get":
         return await handleAgentGet(client, args);
       case "agent-delete":
@@ -4711,17 +4835,17 @@ async function handleSkillLearn(client, args) {
     ]
   };
 }
-async function handleSkillList(client) {
+async function handleSkillList(client, args) {
   const records = await client.listByType("skill");
-  const lines = records.map((r, index) => {
-    const desc = r.description ? ` -- ${r.description}` : "";
-    const label = r.title ?? "(untitled)";
-    return `${String(index + 1)}. ${label} (${r.kbid})${desc}`;
-  });
-  const text = [`${String(records.length)} skills:`, ...lines].join(
-    "\n"
+  const query = typeof args["query"] === "string" ? args["query"].toLowerCase() : "";
+  const filtered = records.filter(
+    (r) => matchesQuery(query, r.title, r.description)
   );
-  return { content: [{ type: "text", text }] };
+  const names = filtered.map((r) => r.title ?? "");
+  const data = { items: names, total: names.length, offset: 0 };
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
 }
 async function handleSkillGet(client, args) {
   const kbid = typeof args["kbid"] === "string" ? args["kbid"] : void 0;