@dikolab/kbdb 0.3.2 → 0.4.1

package/src/shared/cli/functions/collect-files.function.ts

@@ -1,55 +0,0 @@
-import { readdirSync, statSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
-import { SUPPORTED_EXTENSIONS } from '../constants/defaults.constant.ts';
-
-/**
- * Resolves a single target path to a flat list of supported files.
- *
- * When `target` is a file, returns it wrapped in an array if its
- * extension is in `SUPPORTED_EXTENSIONS` and it is not a dotfile;
- * otherwise returns `[]`. When `target` is a directory, recursively
- * collects all matching files, skipping dot-entries at every level.
- * Returns `[]` for non-existent or inaccessible paths.
- *
- * @param target - file or directory path to resolve
- * @returns flat array of absolute or relative paths to supported files
- */
-export function collectFiles(target: string): string[] {
-   try {
-      const stat = statSync(target);
-      if (stat.isFile()) {
-         return isSupportedFile(target) ? [target] : [];
-      }
-      if (stat.isDirectory()) {
-         return scanDirectory(target);
-      }
-   } catch {
-      // Non-existent or inaccessible path -- skip
-   }
-   return [];
-}
-
-function scanDirectory(dir: string): string[] {
-   const files: string[] = [];
-   for (const entry of readdirSync(dir)) {
-      if (entry.startsWith('.')) continue;
-      const full = join(dir, entry);
-      try {
-         const stat = statSync(full);
-         if (stat.isDirectory()) {
-            files.push(...scanDirectory(full));
-         } else if (isSupportedFile(full)) {
-            files.push(full);
-         }
-      } catch {
-         // Skip inaccessible entries
-      }
-   }
-   return files;
-}
-
-function isSupportedFile(path: string): boolean {
-   if (basename(path).startsWith('.')) return false;
-   const ext = extname(path).toLowerCase();
-   return (SUPPORTED_EXTENSIONS as readonly string[]).includes(ext);
-}

package/src/shared/cli/functions/compute-section-kbid.function.ts

@@ -1,49 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/** RFC 4648 base32 alphabet (upper-case, no padding). */
-const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
-
-function base32Encode(bytes: Uint8Array): string {
-   let result = '';
-   let bits = 0;
-   let value = 0;
-   for (const byte of bytes) {
-      value = (value << 8) | byte;
-      bits += 8;
-      while (bits >= 5) {
-         result += BASE32_ALPHABET[(value >>> (bits - 5)) & 0x1f];
-         bits -= 5;
-      }
-   }
-   if (bits > 0) {
-      result += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
-   }
-   return result.toLowerCase();
-}
-
-/**
- * Computes a 26-character kbid for a section using the same algorithm
- * as the Rust engine's `hash_section`.
- *
- * Algorithm:
- * 1. Build input: `"section <mime> <byteLen>\0<content>"`
- * 2. SHA-256 hash the input
- * 3. Take the first 16 bytes
- * 4. Base32 encode (RFC 4648, no padding), lowercased → 26 chars
- *
- * @param mimeType - MIME type string (e.g. `"text/markdown"`)
- * @param content - UTF-8 section content string
- * @returns 26-character lowercase base32 kbid
- */
-export function computeSectionKbid(
-   mimeType: string,
-   content: string,
-): string {
-   const contentBytes = Buffer.from(content, 'utf-8');
-   const header = `section ${mimeType} ${contentBytes.length.toString()}\0`;
-   const headerBytes = Buffer.from(header, 'utf-8');
-   const input = Buffer.concat([headerBytes, contentBytes]);
-   const hash = createHash('sha256').update(input).digest();
-   const truncated = new Uint8Array(hash.buffer, 0, 16);
-   return base32Encode(truncated);
-}

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,
-   );
-}