@dikolab/kbdb 0.6.3 → 0.6.4

package/dist/src/shared/cli/functions/learn-markdown-document.function.d.ts

@@ -0,0 +1,22 @@
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Attempts to ingest `content` as a multi-section markdown
+ * document, splitting on ATX headings and grouping the resulting
+ * sections under one shared document via `client.groupSections()`.
+ *
+ * Returns `undefined` when splitting does not apply -- fewer than
+ * two sections, or none carry a heading title -- signalling that
+ * the caller should fall back to single-section ingestion.
+ *
+ * @param client - learn client used to add and group sections
+ * @param options - parsed CLI options (tags, replace, description)
+ * @param path - source file path, or `'-'` for stdin
+ * @param content - raw markdown document text
+ * @param sourcePath - absolute file path for supersession, or
+ *   `undefined` for stdin input
+ * @returns one `LearnResult` per section, or `undefined` when the
+ *   document does not warrant splitting
+ */
+export declare function learnMarkdownDocument(client: LearnClient, options: CliOptions, path: string, content: string, sourcePath?: string): Promise<LearnResult[] | undefined>;

package/dist/src/shared/cli/functions/learn-target-content.function.d.ts

@@ -0,0 +1,24 @@
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Ingests one already-read target (a file's content, or stdin) as
+ * either a single section or, for eligible markdown input, a set
+ * of sections grouped under one document.
+ *
+ * Markdown splitting is attempted when `path` is `'-'` (stdin) or
+ * ends with `.md`, and `options.title` was not set explicitly --
+ * an explicit title always maps to a single section. When splitting
+ * does not apply, `content` is ingested as-is via `addSection()`.
+ *
+ * @param client - learn client to delegate ingestion to
+ * @param options - parsed CLI options for this invocation
+ * @param path - source file path, or `'-'` for stdin
+ * @param content - raw text content already read from `path`
+ * @param sourcePath - absolute file path for supersession, or
+ *   `undefined` for stdin input
+ * @param level - hierarchical level for the single-section
+ *   fallback; ignored when markdown splitting applies
+ * @returns one `LearnResult` per ingested section
+ */
+export declare function learnTargetContent(client: LearnClient, options: CliOptions, path: string, content: string, sourcePath?: string, level?: number): Promise<LearnResult[]>;

package/dist/src/shared/cli/functions/map-add-section-result.function.d.ts

@@ -0,0 +1,12 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Maps an `AddSectionResult` returned by the worker daemon to the
+ * `LearnResult` record consumed by the `learn` CLI command.
+ *
+ * @param result - raw result from `client.addSection()`
+ * @param path - source file path, or `'-'` for stdin
+ * @param size - UTF-8 character count of the ingested content
+ * @param sectionType - semantic type used for ingestion
+ */
+export declare function mapAddSectionResult(result: AddSectionResult, path: string, size: number, sectionType: string): LearnResult;

package/dist/src/shared/cli/functions/run-agent-list.function.d.ts

@@ -28,18 +28,22 @@ export interface AgentListClient {
     listDocumentsByType(docType: string): Promise<DocumentSummary[]>;
 }
 /**
- * Lists all agents stored in the knowledge base.
+ * Lists agents stored in the knowledge base.
  *
  * Retrieves all documents with `doc_type: 'agent'` and returns a
- * summary list. The `skillCount` for each agent is
- * `Math.max(0, sections.length - 1)` because the first section
- * always holds the agent's metadata JSON rather than a skill
- * reference.
+ * JSON envelope of matching agent names. When `options.args` is
+ * non-empty, the positional arguments are joined with a space
+ * and used as a case-insensitive substring filter against each
+ * agent's name. An empty query returns every agent. Filtering by
+ * description is not available here because it would require an
+ * extra `readSections` call per agent; use the MCP `agent-list`
+ * tool for description filtering.
  *
  * @param client - agent list client to delegate retrieval to
- * @param _options - parsed CLI options (unused; reserved for future
- *   filtering flags)
- * @returns a `CommandResult` with serialised agent summary list
+ * @param options - parsed CLI options; positional `args` build
+ *   the filter query
+ * @returns a `CommandResult` with a JSON envelope
+ *   (`{ items, total, offset }`) of matching agent names
  */
-export declare function runAgentList(client: AgentListClient, _options: CliOptions): Promise<CommandResult>;
+export declare function runAgentList(client: AgentListClient, options: CliOptions): Promise<CommandResult>;
 export {};

package/dist/src/shared/cli/functions/run-learn.function.d.ts

@@ -1,62 +1,9 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { LearnResult } from '../typings/learn-result.model.ts';
-/** Enriched add-section result returned by the daemon. */
-interface AddSectionResult {
-    /** List of knowledge-base identifiers assigned. */
-    readonly items: string[];
-    /** Number of items in the result set. */
-    readonly total: number;
-    /** Offset into the result set (always 0 for learn). */
-    readonly offset: number;
-    /**
-     * Kbid of the section superseded via `--replace`,
-     * or `null` / `undefined` when none.
-     */
-    readonly superseded?: string | null;
-    /**
-     * Advisory warning strings (e.g. `"heading_missing"`).
-     * May be absent from older daemon versions.
-     */
-    readonly warnings?: string[];
-    /**
-     * Near-duplicate sections with similarity >= 0.85.
-     * May be absent from older daemon versions.
-     */
-    readonly near_duplicates?: {
-        readonly kbid: string;
-        readonly similarity: number;
-    }[];
-}
-/**
- * Minimal client interface required by `runLearn`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface LearnClient {
-    /**
-     * Ingests a content section into the knowledge base.
-     *
-     * @param params - section metadata and raw text content
-     * @returns enriched result containing the new kbid plus
-     *   optional supersession, warnings, and near-duplicate info
-     */
-    addSection(params: {
-        sectionType: string;
-        content: string;
-        title?: string;
-        description?: string;
-        docid?: string;
-        tags?: string[];
-        replace?: boolean;
-        sourcePath?: string;
-        level?: number;
-    }): Promise<AddSectionResult>;
-}
-/** Injectable I/O for testing without real stdin. */
-export interface LearnIO {
-    readStdin: () => Promise<string>;
-}
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { LearnIO } from '../typings/learn-io.interface.ts';
+export type { LearnClient } from '../typings/learn-client.interface.ts';
+export type { LearnIO } from '../typings/learn-io.interface.ts';
 /**
  * Ingests one or more files or directories listed in `options.args`
  * into the knowledge base via the provided client.
@@ -72,11 +19,15 @@ export interface LearnIO {
  * directory to derive a level from, so it is sent unset unless
  * `options.level` is explicit.
  *
+ * `.md` files and stdin input are split into multiple sections on
+ * ATX headings and grouped under one document when the content has
+ * 2+ headings and `options.title` is not set explicitly -- see
+ * `learnTargetContent()` for the exact rule.
+ *
  * @param client - learn client to delegate ingestion to
  * @param options - parsed CLI options whose `args` list targets to
  *   ingest
  * @param io - injectable I/O (defaults to reading process.stdin)
- * @returns one `LearnResult` per file successfully ingested
+ * @returns one `LearnResult` per section successfully ingested
  */
 export declare function runLearn(client: LearnClient, options: CliOptions, io?: LearnIO): Promise<LearnResult[]>;
-export {};

package/dist/src/shared/cli/functions/run-skill-list.function.d.ts

@@ -29,15 +29,19 @@ export interface SkillListClient {
     listByType(sectionType: string): Promise<SkillRecord[]>;
 }
 /**
- * Lists all skill definitions stored in the knowledge base.
+ * Lists skill definitions stored in the knowledge base.
  *
- * Calls `client.listByType('skill')` and maps each record to a
- * summary that includes the argument count parsed from the JSON
- * content. Parse errors default the argument count to `0`.
+ * Calls `client.listByType('skill')` and returns a JSON envelope
+ * of matching skill names. When `options.args` is non-empty, the
+ * positional arguments are joined with a space and used as a
+ * case-insensitive substring filter against each skill's name
+ * and description. An empty query returns every skill.
  *
  * @param client - client used to list skill sections
- * @param _options - parsed CLI options (unused; reserved for future flags)
- * @returns a `CommandResult` containing a JSON array of skill summaries
+ * @param options - parsed CLI options; positional `args` build
+ *   the filter query
+ * @returns a `CommandResult` with a JSON envelope
+ *   (`{ items, total, offset }`) of matching skill names
  */
-export declare function runSkillList(client: SkillListClient, _options: CliOptions): Promise<CommandResult>;
+export declare function runSkillList(client: SkillListClient, options: CliOptions): Promise<CommandResult>;
 export {};

package/dist/src/shared/cli/functions/split-markdown-sections.function.d.ts

@@ -0,0 +1,12 @@
+import type { MarkdownSection } from '../typings/markdown-section.interface.ts';
+/**
+ * Splits markdown content into sections on ATX heading
+ * boundaries (`# Title` through `###### Title`). Headings inside
+ * fenced code blocks are treated as plain text. A document with
+ * no headings is returned as one titleless section.
+ *
+ * @param content - raw markdown document text
+ * @returns sections in document order, with trailing whitespace
+ *   trimmed from each section's body
+ */
+export declare function splitMarkdownSections(content: string): MarkdownSection[];

package/dist/src/shared/cli/typings/learn-client.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
 /**
  * Minimal client interface required by `runLearn`.
  *
@@ -9,8 +10,8 @@ export interface LearnClient {
      * Ingests a content section into the knowledge base.
      *
      * @param params - section metadata and raw text content
-     * @returns enriched result containing the new kbid plus
-     *   optional supersession, warnings, and near-duplicate info
+     * @returns result containing the new kbid plus optional
+     *   supersession, warnings, and near-duplicate info
      */
     addSection(params: {
         sectionType: string;
@@ -25,32 +26,17 @@ export interface LearnClient {
          * via source key when `replace` is `true`.
          */
         sourcePath?: string;
-    }): Promise<LearnAddSectionResult>;
-}
-/** Enriched add-section result returned by the daemon. */
-export interface LearnAddSectionResult {
-    /** List of knowledge-base identifiers assigned. */
-    readonly items: string[];
-    /** Number of items in the result set. */
-    readonly total: number;
-    /** Offset into the result set (always 0 for learn). */
-    readonly offset: number;
-    /**
-     * Kbid of the section superseded via `--replace`,
-     * or `null` / `undefined` when none.
-     */
-    readonly superseded?: string | null;
+        /** Hierarchical level (1-6) assigned to the section. */
+        level?: number;
+    }): Promise<AddSectionResult>;
     /**
-     * Advisory warning strings (e.g. `"heading_missing"`).
-     * May be absent from older daemon versions.
-     */
-    readonly warnings?: string[];
-    /**
-     * Near-duplicate sections with similarity >= 0.85.
-     * May be absent from older daemon versions.
+     * Groups a set of sections under a named document, creating the
+     * shared `DocumentManifest` for a markdown file split on
+     * headings.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @returns the assigned document identifier
      */
-    readonly near_duplicates?: {
-        readonly kbid: string;
-        readonly similarity: number;
-    }[];
+    groupSections(title: string, kbids: string[]): Promise<string>;
 }

package/dist/src/shared/cli/typings/markdown-section.interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A single section of a markdown document produced by splitting
+ * on ATX heading boundaries (`# Title` through `###### Title`).
+ */
+export interface MarkdownSection {
+    /**
+     * Heading text for this section, trimmed of surrounding
+     * whitespace. Omitted for content that precedes the first
+     * heading in the document.
+     */
+    title?: string;
+    /**
+     * ATX heading depth (1-6), derived from the number of `#`
+     * characters. Omitted when `title` is omitted.
+     */
+    level?: number;
+    /**
+     * Body text belonging to this section -- everything between
+     * this section's heading (exclusive) and the next heading
+     * (exclusive), with trailing whitespace trimmed.
+     */
+    content: string;
+}

package/dist/src/shared/mcp/functions/handle-agent-list.function.d.ts

@@ -1,27 +1,17 @@
 import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-/** Shape of a content item in an MCP tool call response. */
-interface ToolContent {
-    /** Content type identifier, typically `'text'`. */
-    readonly type: string;
-    /** The text payload. */
-    readonly text: string;
-}
-/** Result returned by the agent-list tool handler. */
-interface ToolCallResult {
-    /** One or more content items describing the result. */
-    readonly content: ToolContent[];
-    /** Set to `true` when the tool encountered an error. */
-    readonly isError?: boolean;
-}
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
- * Handles the `agent:list` MCP tool call.
+ * Handles the `agent-list` MCP tool call.
  *
- * Retrieves all documents with `doc_type: 'agent'` and returns a
- * numbered, human-readable list of each agent's name and
- * description.
+ * Retrieves all documents with `doc_type: 'agent'`. When
+ * `args.query` is a non-empty string, results are filtered by a
+ * case-insensitive substring match against each agent's name or
+ * description before being returned.
  *
  * @param client - the worker client used to execute operations
- * @returns content items with the formatted agent list
+ * @param args - tool arguments; a string `query` filters results
+ *   by name or description
+ * @returns content items with a JSON envelope
+ *   (`{ items, total, offset }`) of matching agent names
  */
-export declare function handleAgentList(client: McpWorkerClient): Promise<ToolCallResult>;
-export {};
+export declare function handleAgentList(client: McpWorkerClient, args?: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/handle-tool-call.function.d.ts

@@ -1,18 +1,5 @@
 import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-/** Shape of a content item in an MCP tool call response. */
-interface ToolContent {
-    /** Content type identifier, typically 'text'. */
-    readonly type: string;
-    /** The text payload. */
-    readonly text: string;
-}
-/** Result returned by a tool call handler. */
-interface ToolCallResult {
-    /** One or more content items describing the result. */
-    readonly content: ToolContent[];
-    /** Set to `true` when the tool encountered an error. */
-    readonly isError?: boolean;
-}
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
  * Dispatches an MCP tool call to the appropriate knowledge-base
  * operation and returns the result formatted as MCP content.
@@ -23,4 +10,3 @@ interface ToolCallResult {
  * @returns content items with optional isError flag
  */
 export declare function handleToolCall(client: McpWorkerClient, name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
-export {};

package/dist/src/shared/mcp/functions/handle-tool-skill-list.function.d.ts

@@ -3,9 +3,19 @@ import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
 /**
  * Handles the `skill-list` MCP tool call.
  *
- * Lists all skills stored in the knowledge base, including the
- * argument count extracted from each skill's JSON content.
+ * Lists skills stored in the knowledge base as a JSON envelope
+ * of matching skill names. When `args.query` is a non-empty
+ * string, results are filtered by a case-insensitive substring
+ * match against each skill's name or description.
+ *
+ * This handler is not currently wired into `handleToolCall`'s
+ * dispatch (see `handle-tool-call.function.ts`'s inline
+ * `handleSkillList`), but is kept behaviourally in sync with it.
  *
  * @param client - the worker client used to execute operations
+ * @param args - tool arguments; a string `query` filters results
+ *   by name or description
+ * @returns content items with a JSON envelope
+ *   (`{ items, total, offset }`) of matching skill names
  */
-export declare function handleToolSkillList(client: McpWorkerClient): Promise<ToolCallResult>;
+export declare function handleToolSkillList(client: McpWorkerClient, args?: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/query-filter/functions/matches-query.function.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tests whether any of the given fields contains `query` as a
+ * case-insensitive substring.
+ *
+ * Used to filter list results (skills, agents) against a
+ * free-text query built from CLI positional arguments or an MCP
+ * tool's `query` parameter. An empty `query` always matches,
+ * which lets callers filter unconditionally without a separate
+ * "no filter" branch. `null` and `undefined` fields never match
+ * a non-empty query.
+ *
+ * @param query - the substring to search for; matches
+ *   everything when empty
+ * @param fields - candidate field values to search, in order
+ * @returns `true` when `query` is empty or found in any field
+ */
+export declare function matchesQuery(query: string, ...fields: readonly (string | null | undefined)[]): boolean;

package/dist/src/shared/version/constants/version.constant.d.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export declare const VERSION = "0.6.3";
+export declare const VERSION = "0.6.4";

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "@dikolab/kbdb",
-   "version": "0.6.3",
+   "version": "0.6.4",
    "description": "CLI tool and MCP server for a file-based knowledge base database -- index documents, search with ranked results, and recall context for AI agents",
    "publishConfig": {
       "access": "public"