@dikolab/kbdb 0.2.2 → 0.3.1

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

@@ -4,6 +4,30 @@ import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { LearnResult } from '../typings/learn-result.model.ts';
 import { SUPPORTED_EXTENSIONS } from '../constants/defaults.constant.ts';
 
+/** Enriched add-section result returned by the daemon. */
+interface AddSectionResult {
+   /** Knowledge-base identifier assigned to the new section. */
+   readonly kbid: string;
+   /**
+    * 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`.
  *
@@ -14,9 +38,9 @@ export interface LearnClient {
    /**
     * Ingests a content section into the knowledge base.
     *
-    * @param params - section type label and raw text content
-    * @returns result object containing the knowledge-base identifier
-    *   assigned to the section
+    * @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;
@@ -24,7 +48,14 @@ export interface LearnClient {
       title?: string;
       description?: string;
       docid?: string;
-   }): Promise<{ kbid: string }>;
+      tags?: string[];
+      replace?: boolean;
+      /**
+       * Absolute path to the source file. Required for supersession
+       * via source key when `replace` is `true`.
+       */
+      sourcePath?: string;
+   }): Promise<AddSectionResult>;
 }
 
 /** Injectable I/O for testing without real stdin. */
@@ -67,13 +98,10 @@ export async function runLearn(
             title: options.title,
             description: options.description,
             docid: options.docid,
+            tags: options.tags,
+            replace: options.replace,
          });
-         results.push({
-            kbid: result.kbid,
-            path: '-',
-            size: content.length,
-            skipped: false,
-         });
+         results.push(mapAddSectionResult(result, '-', content.length));
          continue;
       }
 
@@ -84,20 +112,44 @@ export async function runLearn(
             sectionType: 'text',
             content,
             title: options.title,
+            description: options.description,
             docid: options.docid,
+            tags: options.tags,
+            replace: options.replace,
+            sourcePath: file,
          });
-         results.push({
-            kbid: result.kbid,
-            path: file,
-            size: content.length,
-            skipped: false,
-         });
+         results.push(
+            mapAddSectionResult(result, file, content.length),
+         );
       }
    }
 
    return results;
 }
 
+/**
+ * Maps an `AddSectionResult` to a `LearnResult` record.
+ *
+ * @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
+ */
+function mapAddSectionResult(
+   result: AddSectionResult,
+   path: string,
+   size: number,
+): LearnResult {
+   return {
+      kbid: result.kbid,
+      path,
+      size,
+      skipped: false,
+      superseded: result.superseded ?? null,
+      warnings: result.warnings ?? [],
+      near_duplicates: result.near_duplicates ?? [],
+   };
+}
+
 function readProcessStdin(): Promise<string> {
    return new Promise<string>((resolve) => {
       const chunks: Buffer[] = [];

package/src/shared/cli/functions/run-recall.function.ts

@@ -0,0 +1,66 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
+
+/** Maximum allowed expansion depth for recall operations. */
+const MAX_RECALL_DEPTH = 3;
+
+/**
+ * Minimal client interface required by `runRecall`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface RecallClient {
+   /**
+    * Retrieves full content and context for one or more sections
+    * by their knowledge-base identifiers.
+    *
+    * @param params - section identifier(s) and optional expansion
+    *   depth (0--3)
+    * @returns a single `RecallResult` when `kbid` is supplied, or
+    *   a `RecallResult[]` when `kbids` is supplied
+    */
+   recall(params: {
+      kbid?: string;
+      kbids?: string[];
+      depth?: number;
+   }): Promise<RecallResult | RecallResult[]>;
+}
+
+/**
+ * Retrieves full content and progressive context for one or more
+ * sections by kbid via the provided client.
+ *
+ * Returns an error result when no kbids are provided in
+ * `options.args`. For a single kbid, calls `client.recall` with the
+ * `kbid` parameter and returns the single `RecallResult`. For
+ * multiple kbids, calls `client.recall` with the `kbids` array.
+ *
+ * The `depth` option is read from `options.depth`, defaulting to 0
+ * and clamped to the range 0--3.
+ *
+ * @param client - recall client to delegate to
+ * @param options - parsed CLI options supplying kbids in `args` and
+ *   expansion depth in `depth`
+ * @returns the `RecallResult` or `RecallResult[]` from the client,
+ *   or an error object when no kbids are provided
+ */
+export async function runRecall(
+   client: RecallClient,
+   options: CliOptions,
+): Promise<RecallResult | RecallResult[] | { error: string }> {
+   if (options.args.length === 0) {
+      return { error: 'no kbid provided' };
+   }
+
+   const depth = Math.min(
+      MAX_RECALL_DEPTH,
+      Math.max(0, options.depth ?? 0),
+   );
+
+   if (options.args.length === 1) {
+      return client.recall({ kbid: options.args[0], depth });
+   }
+
+   return client.recall({ kbids: options.args, depth });
+}

package/src/shared/cli/functions/run-search.function.ts

@@ -1,6 +1,58 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
 
+/** A single raw search result item returned by the daemon. */
+interface RawSearchItem {
+   /** Knowledge-base identifier of the matched section. */
+   readonly kbid: string;
+   /** Section heading, or null when untitled. */
+   readonly heading: string | null;
+   /** MIME type of the section content. */
+   readonly type: string;
+   /** Document IDs this section belongs to. */
+   readonly docids: readonly string[];
+   /** Relevance score from the ranking engine. */
+   readonly score: number;
+   /** KWIC excerpt centered on the highest-scoring matched term. */
+   readonly snippet: string;
+   /** Query terms that matched within this section. */
+   readonly matched_terms: readonly string[];
+   /**
+    * Fields that contained at least one match.
+    * May be absent from older daemon versions.
+    */
+   readonly matched_fields?: readonly string[];
+   /**
+    * Normalised confidence score (0.0-1.0) relative to the top result.
+    * May be absent from older daemon versions.
+    */
+   readonly confidence?: number;
+   /**
+    * ISO 8601 creation timestamp of the section.
+    * May be absent from older daemon versions.
+    */
+   readonly created_at?: string;
+}
+
+/** Raw paginated search response from the daemon. */
+interface RawSearchResponse {
+   /** Result items for the current page. */
+   readonly items: readonly RawSearchItem[];
+   /** Total number of matches across all pages. */
+   readonly total: number;
+   /** Number of results skipped. */
+   readonly offset: number;
+   /** Maximum results per page. */
+   readonly limit: number;
+   /** Whether more results exist beyond this page. */
+   readonly has_more: boolean;
+   /**
+    * When `true`, the engine relaxed the query to produce results.
+    * May be absent from older daemon versions.
+    */
+   readonly relaxed?: boolean;
+}
+
 /**
  * Minimal client interface required by `runSearch`.
  *
@@ -18,21 +70,8 @@ export interface SearchClient {
       mode?: string;
       limit?: number;
       offset?: number;
-   }): Promise<{
-      readonly items: readonly {
-         readonly kbid: string;
-         readonly heading: string | null;
-         readonly type: string;
-         readonly docids: readonly string[];
-         readonly score: number;
-         readonly snippet: string;
-         readonly matched_terms: readonly string[];
-      }[];
-      readonly total: number;
-      readonly offset: number;
-      readonly limit: number;
-      readonly has_more: boolean;
-   }>;
+      algo?: string;
+   }): Promise<RawSearchResponse>;
 }
 
 /**
@@ -59,6 +98,7 @@ export async function runSearch(
          offset: 0,
          limit: options.limit,
          has_more: false,
+         relaxed: false,
       };
    }
 
@@ -67,6 +107,7 @@ export async function runSearch(
       mode: options.mode,
       limit: options.limit,
       offset: options.offset,
+      algo: options.algo,
    });
 
    return {
@@ -76,13 +117,17 @@ export async function runSearch(
          type: r.type,
          docids: r.docids,
          score: r.score,
+         confidence: r.confidence ?? 0,
          snippet: r.snippet,
          matched_terms: r.matched_terms,
+         matched_fields: r.matched_fields ?? [],
+         created_at: r.created_at ?? '',
          preview: '',
       })),
       total: results.total,
       offset: results.offset,
       limit: results.limit,
       has_more: results.has_more,
+      relaxed: results.relaxed ?? false,
    };
 }

package/src/shared/cli/functions/version-gate.function.ts

@@ -0,0 +1,44 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
+
+/**
+ * Checks the database version and returns a `CommandResult` error
+ * when the version is incompatible, or `null` when it is compatible.
+ *
+ * - `'needs_migration'`: prompts the user to run `kbdb --migrate`
+ * - `'too_new'`: informs the user to upgrade kbdb
+ * - `'compatible'`: returns `null` (no gate triggered)
+ *
+ * @param client - disconnectable client with version-check capability
+ * @param dbDir - absolute path to the `.kbdb` database root
+ * @returns error `CommandResult` when blocked, or `null` when clear
+ */
+export async function versionGate(
+   client: DisconnectableClient,
+   dbDir: string,
+): Promise<CommandResult | null> {
+   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;
+}

package/src/shared/cli/functions/wrap-command.function.ts

@@ -0,0 +1,34 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+import { errorToMessage } from './error-to-message.function.ts';
+
+/**
+ * Wraps an async command handler in a standard try/catch envelope.
+ *
+ * On success, serialises the result with `JSON.stringify` and
+ * returns `exitCode: 0`. On failure, returns an error message
+ * prefixed with `<label> failed:` and `exitCode: 1`.
+ *
+ * @param label - command name used in the error prefix
+ * @param handler - async function that produces the command result
+ * @param exitCodeSelector - optional function to derive `exitCode`
+ *   from the successful result; defaults to always returning 0
+ * @returns a `CommandResult` with output or error
+ */
+export async function wrapCommand<T>(
+   label: string,
+   handler: () => Promise<T>,
+   exitCodeSelector?: (result: T) => number,
+): Promise<CommandResult> {
+   try {
+      const result = await handler();
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: exitCodeSelector ? exitCodeSelector(result) : 0,
+      };
+   } catch (err) {
+      return {
+         error: `${label} failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}

package/src/shared/cli/index.ts

@@ -1,6 +1,8 @@
 export { parseArgs } from './functions/parse-args.function.ts';
 export { formatOutput } from './functions/format-output.function.ts';
 export { runSearch } from './functions/run-search.function.ts';
+export { runRecall } from './functions/run-recall.function.ts';
+export { runExport } from './functions/run-export.function.ts';
 export { runLearn } from './functions/run-learn.function.ts';
 export { runUnlearn } from './functions/run-unlearn.function.ts';
 export { runContent } from './functions/run-content.function.ts';
@@ -28,6 +30,8 @@ export type {
    PagedSearchDisplay,
 } from './typings/search-display.model.ts';
 export type { SearchClient } from './functions/run-search.function.ts';
+export type { RecallClient } from './functions/run-recall.function.ts';
+export type { ExportClient } from './functions/run-export.function.ts';
 export type { LearnClient } from './functions/run-learn.function.ts';
 export type {
    UnlearnClient,

package/src/shared/cli/typings/agent-create-client.interface.ts

@@ -0,0 +1,47 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+
+/**
+ * Minimal client interface required by `runAgentCreate`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentCreateClient {
+   /**
+    * Ingests a content section into the knowledge base.
+    *
+    * @param params - section type label, raw content, and optional
+    *   metadata
+    * @returns result object containing the assigned knowledge-base
+    *   identifier
+    */
+   addSection(params: {
+      readonly sectionType: string;
+      readonly content: string;
+      readonly title?: string;
+      readonly description?: string;
+   }): Promise<AddSectionResult>;
+
+   /**
+    * 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
+    */
+   groupSections(
+      title: string,
+      kbids: string[],
+      docType?: string,
+   ): Promise<string>;
+
+   /**
+    * Retrieves one or more sections by their identifiers.
+    *
+    * @param kbids - list of knowledge-base identifiers to fetch
+    * @returns sections found; missing kbids are omitted from the result
+    */
+   readSections(kbids: string[]): Promise<{ kbid: string }[]>;
+}

package/src/shared/cli/typings/agent-get-client.interface.ts

@@ -0,0 +1,39 @@
+/** A document section reference as returned by `retrieveDocument`. */
+export interface AgentDocumentSection {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Zero-based position of the section within the document. */
+   readonly position: number;
+}
+
+/** A section record as returned by `readSections`. */
+export interface AgentSectionRecord {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Raw text content stored in the section. */
+   readonly content: string;
+}
+
+/**
+ * Minimal client interface required by `runAgentGet`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentGetClient {
+   /**
+    * Retrieves a full document record including its ordered sections.
+    *
+    * @param docid - identifier of the document to retrieve
+    * @returns the document record
+    */
+   retrieveDocument(docid: string): Promise<unknown>;
+
+   /**
+    * Retrieves one or more sections by their identifiers.
+    *
+    * @param kbids - list of knowledge-base identifiers to fetch
+    * @returns sections found; missing kbids are omitted from the result
+    */
+   readSections(kbids: string[]): Promise<AgentSectionRecord[]>;
+}

package/src/shared/cli/typings/check-client.interface.ts

@@ -0,0 +1,66 @@
+/** Raw daemon response from `integrityCheck`. */
+export interface RawIntegrityCheckResult {
+   /** `true` when all checks passed and no errors were found. */
+   readonly ok: boolean;
+   /** All integrity errors found; empty when `ok` is `true`. */
+   readonly errors: IntegrityError[];
+   /** Total number of sections examined. */
+   readonly sections_checked: number;
+   /** Total number of documents examined. */
+   readonly documents_checked: number;
+   /** Total number of marker references checked. */
+   readonly references_checked: number;
+   /** Time taken to complete the check, in milliseconds. */
+   readonly elapsed_ms: number;
+   /**
+    * Encoded divergent-content map.
+    *
+    * Format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
+    *
+    * Each semicolon-separated segment is a source key followed by
+    * a colon and a comma-separated list of kbids. Absent when no
+    * divergent content exists.
+    */
+   readonly divergent_content?: string;
+}
+
+/** A single integrity error found during a database check. */
+export interface IntegrityError {
+   /**
+    * The category of integrity violation detected.
+    *
+    * - `'checksum_mismatch'` -- stored content does not match its hash
+    * - `'orphan_section'` -- section not referenced by any document
+    * - `'orphan_document'` -- document references no existing sections
+    * - `'broken_reference'` -- a marker references a non-existent entity
+    * - `'type_mismatch'` -- stored MIME type conflicts with content
+    * - `'circular_reference'` -- marker chain contains a cycle
+    */
+   readonly type:
+      | 'checksum_mismatch'
+      | 'orphan_section'
+      | 'orphan_document'
+      | 'broken_reference'
+      | 'type_mismatch'
+      | 'circular_reference';
+   /** Identifier of the entity (kbid or docid) that has the issue. */
+   readonly entity: string;
+   /** Human-readable description of the specific problem. */
+   readonly detail: string;
+}
+
+/**
+ * Minimal client interface required by `runCheck`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface CheckClient {
+   /**
+    * Runs an integrity check on the knowledge-base database.
+    *
+    * @returns a report of all issues found; `ok` is `true` when
+    *   no errors were detected
+    */
+   integrityCheck(): Promise<RawIntegrityCheckResult>;
+}

package/src/shared/cli/typings/cli-deps.interface.ts

@@ -0,0 +1,54 @@
+import type { CliOptions } from './cli-options.interface.ts';
+import type { InitResult } from '../functions/run-init.function.ts';
+import type { DisconnectableClient } from './disconnectable-client.interface.ts';
+
+/**
+ * Injectable dependencies for the CLI orchestrator.
+ *
+ * Every external side-effect is injected so the function
+ * is fully testable without touching process globals,
+ * filesystem, or network.
+ */
+export interface CliDeps {
+   /** Returns `true` when stdin is an interactive terminal. */
+   isStdinTty: () => boolean;
+
+   /**
+    * Prompts the user with the given question and resolves with
+    * their trimmed response.
+    *
+    * @param question - text to display before the input prompt
+    */
+   promptUser: (question: string) => Promise<string>;
+
+   /**
+    * Creates a worker client connected to the given database path.
+    *
+    * @param opts - connection options including the context path
+    */
+   createWorkerClient: (opts: {
+      contextPath: string;
+   }) => Promise<DisconnectableClient>;
+
+   /**
+    * Finds the `.kbdb` directory starting from the given base path.
+    *
+    * @param basePath - starting directory; defaults to `process.cwd()`
+    * @returns absolute path to `.kbdb` or `null` when not found
+    */
+   findDb: (basePath?: string) => string | null;
+
+   /**
+    * Initialises a new `.kbdb` database directory.
+    *
+    * @param options - parsed CLI options
+    */
+   runInit: (options: CliOptions) => InitResult;
+
+   /**
+    * Starts the MCP server using the given database path.
+    *
+    * @param contextPath - absolute path to the `.kbdb` directory
+    */
+   startMcpServer?: (contextPath: string) => Promise<void>;
+}

package/src/shared/cli/typings/cli-options.interface.ts

@@ -29,6 +29,8 @@ export interface CliOptions {
    format: OutputFormat;
    /** Search mode passed to the worker daemon. Defaults to `'sections'`. */
    mode: SearchMode;
+   /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
+   algo?: string;
    /** Maximum number of results to return. Defaults to 20. */
    limit: number;
    /** Number of results to skip for pagination. */
@@ -52,6 +54,19 @@ export interface CliOptions {
    body?: string;
    /** Comma-separated skill kbids for agent create. */
    skills?: string[];
+   /**
+    * Recall expansion depth (0-3). Clamped to 3.
+    * Defaults to 0.
+    */
+   depth?: number;
+   /** Comma-separated tags for scoping (learn, recall). */
+   tags?: string[];
+   /**
+    * When `true`, enables supersession by source key (learn).
+    * Re-learning edited content replaces the original section
+    * instead of creating a sibling.
+    */
+   replace?: boolean;
    /** Positional arguments following the sub-command. */
    args: string[];
 }

package/src/shared/cli/typings/disconnectable-client.interface.ts

@@ -0,0 +1,29 @@
+import type { VersionStatus } from '../../worker-client/typings/version-status.model.ts';
+import type { MigrateResult } from '../../worker-client/typings/migrate-result.model.ts';
+import type { DispatchClient } from './dispatch-client.type.ts';
+
+/**
+ * Extension of `DispatchClient` with lifecycle methods needed by
+ * the CLI orchestrator.
+ *
+ * Adds version checking, migration, and disconnect so the orchestrator
+ * can manage a worker-client connection across all CLI commands.
+ */
+export interface DisconnectableClient extends DispatchClient {
+   /**
+    * Checks the database version against the worker engine.
+    *
+    * @param targetPath - absolute path to the `.kbdb` database root
+    */
+   checkVersion(targetPath: string): Promise<VersionStatus>;
+
+   /**
+    * Runs all pending database migrations.
+    *
+    * @param targetPath - absolute path to the `.kbdb` database root
+    */
+   migrateDatabase(targetPath: string): Promise<MigrateResult>;
+
+   /** Disconnects from the worker daemon and releases resources. */
+   disconnect(): void;
+}