@dikolab/kbdb 0.3.2 → 0.4.0

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

@@ -1,390 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { PagedSearchDisplay } 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 type { RecallClient } from './run-recall.function.ts';
-import type { ExportClient } from './run-export.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 { runRecall } from './run-recall.function.ts';
-import { runExport } from './run-export.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 &
-   RecallClient &
-   ExportClient;
-
-/**
- * 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 'recall':
-         return handleRecall(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 'export':
-         return handleExport(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 handleRecall(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runRecall(client, options);
-      if ('error' in result) {
-         return {
-            error: `error: ${result.error}`,
-            exitCode: 1,
-         };
-      }
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `recall failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleExport(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runExport(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `export 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,
-   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/ensure-db.function.ts

@@ -1,21 +0,0 @@
-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

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-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-mcp-output.function.ts

@@ -1,41 +0,0 @@
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-
-/**
- * Formats a paged search result as a JSON string compatible
- * with the MCP (Model Context Protocol) `text` content block.
- *
- * @param paged - paginated search results to serialise
- * @returns MCP-compatible JSON string ready for stdout
- */
-export function formatMcpOutput(paged: PagedSearchDisplay): string {
-   const mcpItems = paged.items.map((r) => ({
-      kbid: r.kbid,
-      heading: r.heading,
-      type: r.type,
-      docids: r.docids,
-      snippet: r.snippet,
-      matched_terms: r.matched_terms,
-      matched_fields: r.matched_fields,
-      created_at: r.created_at,
-   }));
-   return JSON.stringify(
-      {
-         type: 'text',
-         text: paged.items
-            .map(
-               (r) =>
-                  `[${r.kbid}] ${r.heading ?? '(untitled)'}` +
-                  ` — ${r.snippet || r.preview}`,
-            )
-            .join('\n'),
-         items: mcpItems,
-         total: paged.total,
-         offset: paged.offset,
-         limit: paged.limit,
-         has_more: paged.has_more,
-         relaxed: paged.relaxed,
-      },
-      null,
-      2,
-   );
-}

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

@@ -1,95 +0,0 @@
-import type { OutputFormat } from '../typings/cli-options.interface.ts';
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-
-/**
- * Serialises a paged search result into the requested output
- * format string.
- *
- * - `'json'` -- pretty-printed JSON envelope
- * - `'text'` -- numbered human-readable list with paging footer
- * - `'mcp'` -- JSON envelope compatible with MCP protocol
- *
- * @param paged - paginated search results to format
- * @param format - target output format
- * @returns formatted string ready for stdout
- */
-export function formatOutput(
-   paged: PagedSearchDisplay,
-   format: OutputFormat,
-): string {
-   switch (format) {
-      case 'json':
-         return JSON.stringify(paged, null, 2);
-      case 'text':
-         return formatText(paged);
-      case 'mcp':
-         return formatMcp(paged);
-   }
-}
-
-function formatText(paged: PagedSearchDisplay): string {
-   if (paged.items.length === 0) return 'No results found.';
-   const start = paged.offset + 1;
-   const end = paged.offset + paged.items.length;
-
-   const lines = paged.items
-      .map((r, i) => {
-         const num = paged.offset + i + 1;
-         const heading = r.heading ?? '(untitled)';
-         const terms = r.matched_terms.join(', ');
-         const fields = r.matched_fields.join(', ');
-         const confidencePct = (r.confidence * 100).toFixed(0);
-         return (
-            `${String(num)}. [${r.kbid}] ${heading}` +
-            ` (score: ${r.score.toFixed(4)},` +
-            ` confidence: ${confidencePct}%)\n` +
-            `   ${r.snippet || r.preview || '(no snippet)'}\n` +
-            `   type: ${r.type}` +
-            `  terms: ${terms}` +
-            (fields ? `  fields: ${fields}` : '')
-         );
-      })
-      .join('\n\n');
-
-   const footer =
-      `\nShowing ${String(start)}-${String(end)}` +
-      ` of ${String(paged.total)} results`;
-   const hint = paged.has_more
-      ? `\nUse --offset ${String(end)} to see more`
-      : '';
-
-   return lines + footer + hint;
-}
-
-function formatMcp(paged: PagedSearchDisplay): string {
-   const mcpItems = paged.items.map((r) => ({
-      kbid: r.kbid,
-      heading: r.heading,
-      type: r.type,
-      docids: r.docids,
-      snippet: r.snippet,
-      matched_terms: r.matched_terms,
-      matched_fields: r.matched_fields,
-      created_at: r.created_at,
-   }));
-   return JSON.stringify(
-      {
-         type: 'text',
-         text: paged.items
-            .map(
-               (r) =>
-                  `[${r.kbid}] ${r.heading ?? '(untitled)'}` +
-                  ` — ${r.snippet || r.preview}`,
-            )
-            .join('\n'),
-         items: mcpItems,
-         total: paged.total,
-         offset: paged.offset,
-         limit: paged.limit,
-         has_more: paged.has_more,
-         relaxed: paged.relaxed,
-      },
-      null,
-      2,
-   );
-}

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

@@ -1,42 +0,0 @@
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-
-/**
- * Formats a paged search result as a numbered human-readable
- * text list with a paging footer and optional "more" hint.
- *
- * @param paged - paginated search results to render
- * @returns formatted string ready for stdout
- */
-export function formatTextOutput(paged: PagedSearchDisplay): string {
-   if (paged.items.length === 0) return 'No results found.';
-   const start = paged.offset + 1;
-   const end = paged.offset + paged.items.length;
-
-   const lines = paged.items
-      .map((r, i) => {
-         const num = paged.offset + i + 1;
-         const heading = r.heading ?? '(untitled)';
-         const terms = r.matched_terms.join(', ');
-         const fields = r.matched_fields.join(', ');
-         const confidencePct = (r.confidence * 100).toFixed(0);
-         return (
-            `${String(num)}. [${r.kbid}] ${heading}` +
-            ` (score: ${r.score.toFixed(4)},` +
-            ` confidence: ${confidencePct}%)\n` +
-            `   ${r.snippet || r.preview || '(no snippet)'}\n` +
-            `   type: ${r.type}` +
-            `  terms: ${terms}` +
-            (fields ? `  fields: ${fields}` : '')
-         );
-      })
-      .join('\n\n');
-
-   const footer =
-      `\nShowing ${String(start)}-${String(end)}` +
-      ` of ${String(paged.total)} results`;
-   const hint = paged.has_more
-      ? `\nUse --offset ${String(end)} to see more`
-      : '';
-
-   return lines + footer + hint;
-}

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

@@ -1,41 +0,0 @@
-/** 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`
-   );
-}