@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,338 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { SearchDisplay } from '../typings/search-display.model.ts';
+import type { LearnIO } from './run-learn.function.ts';
+import type { SearchClient } from './run-search.function.ts';
+import type { LearnClient } from './run-learn.function.ts';
+import type { UnlearnClient } from './run-unlearn.function.ts';
+import type { ContentClient } from './run-content.function.ts';
+import type { CheckClient } from './run-check.function.ts';
+import type { GcClient } from './run-gc.function.ts';
+import type { RebuildClient } from './run-rebuild.function.ts';
+import type { StatusClient } from './run-status.function.ts';
+import type { DbMigrateClient } from './run-db-migrate.function.ts';
+import type { SkillLearnClient } from './run-skill-learn.function.ts';
+import type { SkillListClient } from './run-skill-list.function.ts';
+import type { SkillGetClient } from './run-skill-get.function.ts';
+import type { SkillDeleteClient } from './run-skill-delete.function.ts';
+import type { AgentCreateClient } from './run-agent-create.function.ts';
+import type { AgentListClient } from './run-agent-list.function.ts';
+import type { AgentGetClient } from './run-agent-get.function.ts';
+import type { AgentDeleteClient } from './run-agent-delete.function.ts';
+import { runSearch } from './run-search.function.ts';
+import { runLearn } from './run-learn.function.ts';
+import { runUnlearn } from './run-unlearn.function.ts';
+import { runContent } from './run-content.function.ts';
+import { runCheck } from './run-check.function.ts';
+import { runGc } from './run-gc.function.ts';
+import { runRebuild } from './run-rebuild.function.ts';
+import { runStatus } from './run-status.function.ts';
+import { runDbInit } from './run-db-init.function.ts';
+import { runInit } from './run-init.function.ts';
+import { runDbMigrate } from './run-db-migrate.function.ts';
+import { runSkillLearn } from './run-skill-learn.function.ts';
+import { runSkillList } from './run-skill-list.function.ts';
+import { runSkillGet } from './run-skill-get.function.ts';
+import { runSkillDelete } from './run-skill-delete.function.ts';
+import { runAgentCreate } from './run-agent-create.function.ts';
+import { runAgentList } from './run-agent-list.function.ts';
+import { runAgentGet } from './run-agent-get.function.ts';
+import { runAgentDelete } from './run-agent-delete.function.ts';
+import { formatOutput } from './format-output.function.ts';
+import { errorToMessage } from './error-to-message.function.ts';
+
+/**
+ * Intersection of all data-command client interfaces.
+ *
+ * Each run* function defines its own minimal interface; this
+ * intersection combines them so `dispatchCommand` can route
+ * to any command handler with full type safety.
+ */
+export type DispatchClient = SearchClient &
+   LearnClient &
+   UnlearnClient &
+   ContentClient &
+   CheckClient &
+   GcClient &
+   RebuildClient &
+   StatusClient &
+   DbMigrateClient &
+   SkillLearnClient &
+   SkillListClient &
+   SkillGetClient &
+   SkillDeleteClient &
+   AgentCreateClient &
+   AgentListClient &
+   AgentGetClient &
+   AgentDeleteClient;
+
+/**
+ * Routes a parsed CLI command to the appropriate handler and
+ * returns a `CommandResult` without touching process globals.
+ *
+ * @param client - worker client covering all data commands
+ * @param options - parsed CLI options with command and args
+ * @param io - optional injectable I/O for learn stdin
+ */
+export async function dispatchCommand(
+   client: DispatchClient,
+   options: CliOptions,
+   io?: LearnIO,
+): Promise<CommandResult> {
+   switch (options.command) {
+      case 'learn':
+         return handleLearn(client, options, io);
+      case 'unlearn':
+         return handleUnlearn(client, options);
+      case 'search':
+         return handleSearch(client, options);
+      case 'content':
+         return handleContent(client, options);
+      case 'check':
+         return handleCheck(client, options);
+      case 'gc':
+         return handleGc(client, options);
+      case 'rebuild':
+         return handleRebuild(client, options);
+      case 'status':
+         return handleStatus(client, options);
+      case 'db-init':
+         return handleDbInit(options);
+      case 'db-migrate':
+         return handleDbMigrate(client, options);
+      case 'skill-learn': {
+         const result = await runSkillLearn(client, options);
+         return result;
+      }
+      case 'skill-list': {
+         const result = await runSkillList(client, options);
+         return result;
+      }
+      case 'skill-get': {
+         const result = await runSkillGet(client, options);
+         return result;
+      }
+      case 'skill-delete': {
+         const result = await runSkillDelete(client, options);
+         return result;
+      }
+      case 'agent-create': {
+         const result = await runAgentCreate(client, options);
+         return result;
+      }
+      case 'agent-list': {
+         const result = await runAgentList(client, options);
+         return result;
+      }
+      case 'agent-get': {
+         const result = await runAgentGet(client, options);
+         return result;
+      }
+      case 'agent-delete': {
+         const result = await runAgentDelete(client, options);
+         return result;
+      }
+      default:
+         return {
+            error: `unknown command: ${options.command}`,
+            exitCode: 1,
+         };
+   }
+}
+
+async function handleLearn(
+   client: DispatchClient,
+   options: CliOptions,
+   io?: LearnIO,
+): Promise<CommandResult> {
+   try {
+      const results = await runLearn(client, options, io);
+      return {
+         output: JSON.stringify(results, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `learn failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleUnlearn(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const results = await runUnlearn(client, options);
+      return {
+         output: JSON.stringify(results, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `unlearn failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleSearch(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const results = await runSearch(client, options);
+      if (options.content) {
+         await hydrateSearchPreviews(client, results);
+      }
+      return {
+         output: formatOutput(results, options.format),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `search failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleContent(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runContent(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `content failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleCheck(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runCheck(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: result.ok ? 0 : 1,
+      };
+   } catch (err) {
+      return {
+         error: `check failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleGc(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runGc(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `gc failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleRebuild(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runRebuild(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `rebuild failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+async function handleStatus(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runStatus(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `status failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+function handleDbInit(options: CliOptions): CommandResult {
+   return runDbInit(options, runInit);
+}
+
+async function handleDbMigrate(
+   client: DispatchClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   try {
+      const result = await runDbMigrate(client, options);
+      return {
+         output: JSON.stringify(result, null, 2),
+         exitCode: 0,
+      };
+   } catch (err) {
+      return {
+         error: `db-migrate failed: ${errorToMessage(err)}`,
+         exitCode: 1,
+      };
+   }
+}
+
+/**
+ * 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 results - mutable search display records to hydrate
+ */
+async function hydrateSearchPreviews(
+   client: ContentClient,
+   results: SearchDisplay[],
+): Promise<void> {
+   await Promise.all(
+      results.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/ensure-db.function.ts

@@ -0,0 +1,21 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Ensures that the `.kbdb` database directory exists at the
+ * resolved base path, creating it recursively if necessary.
+ *
+ * When `dbPath` is provided it is resolved to an absolute path and
+ * used as the base; otherwise `process.cwd()` is used.
+ *
+ * @param dbPath - optional path to the knowledge-base root directory
+ * @returns absolute path to the `.kbdb` directory
+ */
+export function ensureDb(dbPath?: string): string {
+   const base = dbPath ? resolve(dbPath) : process.cwd();
+   const kbdbDir = join(base, '.kbdb');
+   if (!existsSync(kbdbDir)) {
+      mkdirSync(kbdbDir, { recursive: true });
+   }
+   return kbdbDir;
+}

package/src/shared/cli/functions/error-to-message.function.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts an unknown thrown value to a human-readable message.
+ *
+ * @param err - the caught value
+ * @returns the error message string
+ */
+export function errorToMessage(err: unknown): string {
+   return err instanceof Error ? err.message : String(err);
+}

package/src/shared/cli/functions/find-db.function.ts

@@ -0,0 +1,20 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Resolves the absolute path to the `.kbdb` database directory
+ * under the given base path (or the current working directory).
+ *
+ * Unlike `ensureDb`, this function is purely read-only: it never
+ * creates the directory. Returns `null` when the `.kbdb` directory
+ * does not exist.
+ *
+ * @param dbPath - optional path to the knowledge-base root directory
+ * @returns absolute path to the `.kbdb` directory, or `null` when
+ *   it does not exist
+ */
+export function findDb(dbPath?: string): string | null {
+   const base = dbPath ? resolve(dbPath) : process.cwd();
+   const kbdbDir = join(base, '.kbdb');
+   return existsSync(kbdbDir) ? kbdbDir : null;
+}

package/src/shared/cli/functions/format-output.function.ts

@@ -0,0 +1,64 @@
+import type { OutputFormat } from '../typings/cli-options.interface.ts';
+import type { SearchDisplay } from '../typings/search-display.model.ts';
+
+/**
+ * Serialises an array of search results into the requested output
+ * format string.
+ *
+ * - `'json'` -- pretty-printed JSON array
+ * - `'text'` -- numbered human-readable list
+ * - `'mcp'` -- JSON envelope compatible with MCP protocol consumers
+ *
+ * @param results - ranked search results to format
+ * @param format - target output format
+ * @returns formatted string ready for stdout
+ */
+export function formatOutput(
+   results: SearchDisplay[],
+   format: OutputFormat,
+): string {
+   switch (format) {
+      case 'json':
+         return JSON.stringify(results, null, 2);
+      case 'text':
+         return formatText(results);
+      case 'mcp':
+         return formatMcp(results);
+   }
+}
+
+/**
+ * Renders results as a numbered human-readable list.
+ *
+ * @param results - search results to render
+ */
+function formatText(results: SearchDisplay[]): string {
+   if (results.length === 0) return 'No results found.';
+   return results
+      .map(
+         (r, i) =>
+            `${String(i + 1)}. [${r.kbid}] ` +
+            `(score: ${r.score.toFixed(4)})\n` +
+            `   ${r.preview}\n` +
+            `   matches: ${r.matches.map((m) => m.term).join(', ')}`,
+      )
+      .join('\n\n');
+}
+
+/**
+ * Renders results as a JSON envelope for MCP protocol consumers.
+ *
+ * @param results - search results to render
+ */
+function formatMcp(results: SearchDisplay[]): string {
+   return JSON.stringify({
+      type: 'text',
+      text: results
+         .map(
+            (r) =>
+               `[${r.kbid}] score=${r.score.toFixed(4)}` +
+               ` — ${r.preview}`,
+         )
+         .join('\n'),
+   });
+}