@dikolab/kbdb 0.3.0 → 0.3.1

package/src/shared/cli/functions/generate-group-help.function.ts

@@ -0,0 +1,41 @@
+/** One-line description for each group command. */
+const GROUP_DESCRIPTIONS: Readonly<Record<string, string>> = {
+   db: 'Database management',
+   skill: 'Skill management',
+   agent: 'Agent management',
+};
+
+/**
+ * Generates the level-2 help text for a group command.
+ *
+ * Lists all subcommands with their descriptions and
+ * includes a footer pointing to per-subcommand help.
+ *
+ * @param group - the group command name (e.g. `'db'`, `'skill'`)
+ * @param subs - ordered list of `[name, description]` pairs
+ * @returns formatted help string for the group command
+ */
+export function generateGroupHelp(
+   group: string,
+   subs: readonly (readonly [string, string])[],
+): string {
+   const subLines = subs
+      .map(([name, desc]) => `   ${name.padEnd(20)}${desc}`)
+      .join('\n');
+   const desc = GROUP_DESCRIPTIONS[group] ?? group;
+   return (
+      `kbdb ${group} - ${desc}\n` +
+      `\n` +
+      `Usage: kbdb ${group} <subcommand> [options]\n` +
+      `\n` +
+      `Subcommands:\n` +
+      `${subLines}\n` +
+      `\n` +
+      `Global Options:\n` +
+      `   --db <path>         Path to .kbdb directory\n` +
+      `   -h, --help          Show this help message\n` +
+      `\n` +
+      `Run "kbdb ${group} <subcommand> --help"` +
+      ` for details.\n`
+   );
+}

package/src/shared/cli/functions/handle-data-command.function.ts

@@ -0,0 +1,67 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
+import { errorToMessage } from './error-to-message.function.ts';
+import { versionGate } from './version-gate.function.ts';
+import { dispatchCommand } from './dispatch-command.function.ts';
+
+/**
+ * Handles data commands (search, learn, recall, etc.) by finding or
+ * creating the database, running the version gate, and dispatching to
+ * the appropriate command handler.
+ *
+ * When the database is not found in non-TTY mode, returns an error.
+ * In TTY mode, prompts the user to create a new database.
+ *
+ * @param options - parsed CLI options with command and args
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` from the dispatched command
+ */
+export async function handleDataCommand(
+   options: CliOptions,
+   deps: CliDeps,
+): Promise<CommandResult> {
+   let dbDir = deps.findDb(options.dbPath);
+
+   if (!dbDir) {
+      const basePath = options.dbPath ?? process.cwd();
+      if (!deps.isStdinTty()) {
+         return {
+            error:
+               `error: no .kbdb database found at ${basePath}` +
+               ' -- run `kbdb --init` to create one',
+            exitCode: 1,
+         };
+      }
+      const answer = await deps.promptUser(
+         `No .kbdb database found. Create one in ${basePath}? [y/N] `,
+      );
+      if (answer.toLowerCase() !== 'y') {
+         return { error: 'aborted: no database created', exitCode: 1 };
+      }
+      const initResult = deps.runInit(options);
+      if (!initResult.ok) {
+         return {
+            error: `error: ${initResult.errorMessage ?? 'init failed'}`,
+            exitCode: 1,
+         };
+      }
+      dbDir = initResult.targetPath;
+   }
+
+   let client: DisconnectableClient;
+   try {
+      client = await deps.createWorkerClient({ contextPath: dbDir });
+   } catch (err) {
+      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
+   }
+
+   try {
+      const gateResult = await versionGate(client, dbDir);
+      if (gateResult) return gateResult;
+      return await dispatchCommand(client, options);
+   } finally {
+      client.disconnect();
+   }
+}

package/src/shared/cli/functions/handle-mcp.function.ts

@@ -0,0 +1,56 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
+import { errorToMessage } from './error-to-message.function.ts';
+import { versionGate } from './version-gate.function.ts';
+
+/**
+ * Handles the `mcp` command sub-flow.
+ *
+ * Resolves the database directory, creates a worker client, runs
+ * the version gate, and starts the MCP server. Disconnects the
+ * worker client when finished.
+ *
+ * @param options - parsed CLI options (uses `dbPath` and env fallback)
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` with `exitCode: 0` on success
+ */
+export async function handleMcp(
+   options: CliOptions,
+   deps: CliDeps,
+): Promise<CommandResult> {
+   const rawDbPath = options.dbPath ?? process.env['KBDB_DIR'];
+   if (!rawDbPath) {
+      return {
+         error: 'error: --db or KBDB_DIR required in MCP mode',
+         exitCode: 1,
+      };
+   }
+   const dbDir = deps.findDb(rawDbPath);
+   if (!dbDir) {
+      return {
+         error: `error: no .kbdb database found at ${rawDbPath}`,
+         exitCode: 1,
+      };
+   }
+   let client: DisconnectableClient;
+   try {
+      client = await deps.createWorkerClient({ contextPath: dbDir });
+   } catch (err) {
+      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
+   }
+   try {
+      const gateResult = await versionGate(client, dbDir);
+      if (gateResult) return gateResult;
+      if (deps.startMcpServer) await deps.startMcpServer(dbDir);
+      return { exitCode: 0 };
+   } catch (err) {
+      return {
+         error: `error: mcp failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   } finally {
+      client.disconnect();
+   }
+}

package/src/shared/cli/functions/handle-migrate.function.ts

@@ -0,0 +1,64 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
+import { errorToMessage } from './error-to-message.function.ts';
+
+/**
+ * Handles the `migrate` / `db-migrate` command sub-flow.
+ *
+ * Resolves the database directory, creates a worker client,
+ * checks the version, and runs migrations when needed. Disconnects
+ * the worker client when finished.
+ *
+ * @param options - parsed CLI options (uses `dbPath`)
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` with migration output or an error
+ */
+export async function handleMigrate(
+   options: CliOptions,
+   deps: CliDeps,
+): Promise<CommandResult> {
+   const dbDir = deps.findDb(options.dbPath);
+   if (!dbDir) {
+      return {
+         error: `error: no .kbdb database found at ${options.dbPath ?? process.cwd()}`,
+         exitCode: 1,
+      };
+   }
+   let client: DisconnectableClient;
+   try {
+      client = await deps.createWorkerClient({ contextPath: dbDir });
+   } catch (err) {
+      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
+   }
+   try {
+      const versionStatus = await client.checkVersion(dbDir);
+      if (versionStatus.status === 'too_new') {
+         return {
+            error:
+               `error: database version` +
+               ` ${versionStatus.currentVersion.toString()}` +
+               ` is newer than kbdb version` +
+               ` ${versionStatus.requiredVersion.toString()}` +
+               ` -- upgrade kbdb`,
+            exitCode: 1,
+         };
+      }
+      if (versionStatus.status === 'needs_migration') {
+         const migrateResult = await client.migrateDatabase(dbDir);
+         return {
+            output: JSON.stringify(migrateResult, null, 2),
+            exitCode: 0,
+         };
+      }
+      return { output: 'already up to date', exitCode: 0 };
+   } catch (err) {
+      return {
+         error: `error: migrate failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   } finally {
+      client.disconnect();
+   }
+}

package/src/shared/cli/functions/hydrate-search-previews.function.ts

@@ -0,0 +1,29 @@
+import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
+import type { ContentClient } from './run-content.function.ts';
+
+/**
+ * Hydrates each result's `preview` field with the actual section
+ * content fetched from the client.
+ *
+ * Failures for individual results are caught and suppressed so that
+ * one unavailable section does not prevent other previews from
+ * being returned.
+ *
+ * @param client - content client used to fetch section text
+ * @param paged - mutable search display records to hydrate
+ */
+export async function hydrateSearchPreviews(
+   client: ContentClient,
+   paged: PagedSearchDisplay,
+): Promise<void> {
+   await Promise.all(
+      paged.items.map(async (result) => {
+         try {
+            const contentResult = await client.content([result.kbid]);
+            result.preview = contentResult.data;
+         } catch {
+            // Leave preview as empty string on failure.
+         }
+      }),
+   );
+}

package/src/shared/cli/functions/parse-args.function.ts

@@ -94,6 +94,9 @@ export function parseArgs(argv: string[]): CliOptions {
                parseInt(argv[++i] ?? '', 10) || 0,
             );
             break;
+         case '--algo':
+            options.algo = argv[++i];
+            break;
          case '--title':
             options.title = argv[++i];
             break;

package/src/shared/cli/functions/resolve-skill-names.function.ts

@@ -0,0 +1,43 @@
+import type {
+   AgentGetClient,
+   AgentDocumentSection,
+   AgentSectionRecord,
+} from '../typings/agent-get-client.interface.ts';
+
+/**
+ * Resolves skill names by reading each skill section's JSON content.
+ *
+ * Returns `null` for any reference whose section no longer exists
+ * (dangling reference) or whose content cannot be parsed.
+ *
+ * @param client - client used to fetch section records
+ * @param skillRefs - ordered section references to resolve
+ * @returns list of resolved skill entries with name and position
+ */
+export async function resolveSkillNames(
+   client: AgentGetClient,
+   skillRefs: AgentDocumentSection[],
+): Promise<{ kbid: string; name: string | null; position: number }[]> {
+   if (skillRefs.length === 0) return [];
+   const kbids = skillRefs.map((r) => r.kbid);
+   const sections: AgentSectionRecord[] =
+      await client.readSections(kbids);
+   const sectionMap = new Map(sections.map((s) => [s.kbid, s]));
+   return skillRefs.map((ref) => {
+      const sec = sectionMap.get(ref.kbid);
+      if (!sec) {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+      try {
+         const parsed = JSON.parse(sec.content) as Record<
+            string,
+            unknown
+         >;
+         const name =
+            typeof parsed['name'] === 'string' ? parsed['name'] : null;
+         return { kbid: ref.kbid, name, position: ref.position };
+      } catch {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+   });
+}

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

@@ -70,6 +70,7 @@ export interface SearchClient {
       mode?: string;
       limit?: number;
       offset?: number;
+      algo?: string;
    }): Promise<RawSearchResponse>;
 }
 
@@ -106,6 +107,7 @@ export async function runSearch(
       mode: options.mode,
       limit: options.limit,
       offset: options.offset,
+      algo: options.algo,
    });
 
    return {

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/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. */

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;
+}