@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,171 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+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';
+
+/**
+ * Minimal client interface required by `runLearn`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+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
+    */
+   addSection(params: {
+      sectionType: string;
+      content: string;
+      title?: string;
+      description?: string;
+      docid?: string;
+   }): Promise<{ kbid: string }>;
+}
+
+/** Injectable I/O for testing without real stdin. */
+export interface LearnIO {
+   readStdin: () => Promise<string>;
+}
+
+/**
+ * Ingests one or more files or directories listed in `options.args`
+ * into the knowledge base via the provided client.
+ *
+ * Each argument is resolved to a set of supported files. Unsupported
+ * extensions, dotfiles, dot-directories, and non-existent paths are
+ * silently skipped. The `-` argument reads content from stdin
+ * (consumed only once).
+ *
+ * @param client - learn client to delegate ingestion to
+ * @param options - parsed CLI options whose `args` list targets to
+ *   ingest
+ * @param io - injectable I/O (defaults to reading process.stdin)
+ * @returns one `LearnResult` per file successfully ingested
+ */
+export async function runLearn(
+   client: LearnClient,
+   options: CliOptions,
+   io?: LearnIO,
+): Promise<LearnResult[]> {
+   const results: LearnResult[] = [];
+   let stdinConsumed = false;
+   const readStdin = io?.readStdin ?? readProcessStdin;
+
+   for (const target of options.args) {
+      if (target === '-') {
+         if (stdinConsumed) continue;
+         stdinConsumed = true;
+         const content = await readStdin();
+         const result = await client.addSection({
+            sectionType: 'text',
+            content,
+            title: options.title,
+            description: options.description,
+            docid: options.docid,
+         });
+         results.push({
+            kbid: result.kbid,
+            path: '-',
+            size: content.length,
+            skipped: false,
+         });
+         continue;
+      }
+
+      const files = collectFiles(target);
+      for (const file of files) {
+         const content = readFileSync(file, 'utf-8');
+         const result = await client.addSection({
+            sectionType: 'text',
+            content,
+            title: options.title,
+            docid: options.docid,
+         });
+         results.push({
+            kbid: result.kbid,
+            path: file,
+            size: content.length,
+            skipped: false,
+         });
+      }
+   }
+
+   return results;
+}
+
+function readProcessStdin(): Promise<string> {
+   return new Promise<string>((resolve) => {
+      const chunks: Buffer[] = [];
+      process.stdin.on('data', (chunk: Buffer) => {
+         chunks.push(chunk);
+      });
+      process.stdin.on('end', () => {
+         resolve(Buffer.concat(chunks).toString('utf-8'));
+      });
+      process.stdin.resume();
+   });
+}
+
+/**
+ * Resolves a single target path to a flat list of supported files.
+ *
+ * Returns an empty array for non-existent or inaccessible paths.
+ *
+ * @param target - file or directory path to resolve
+ */
+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 [];
+}
+
+/**
+ * Recursively scans a directory and returns all supported files,
+ * excluding dot-entries at every level.
+ *
+ * @param dir - absolute or relative directory path to scan
+ */
+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;
+}
+
+/**
+ * Returns `true` when the file's extension is in
+ * `SUPPORTED_EXTENSIONS`.
+ *
+ * @param path - file path to check
+ */
+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/run-migrate.function.ts

@@ -0,0 +1,85 @@
+import { resolve } from 'node:path';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { MigrateResult } from '../../worker-client/typings/migrate-result.model.ts';
+import type {
+   VersionCompatibility,
+   VersionStatus,
+} from '../../worker-client/typings/version-status.model.ts';
+
+/**
+ * Result returned by `runMigrate` describing the outcome of the
+ * migration attempt.
+ */
+export interface MigrateCommandResult {
+   /**
+    * The compatibility status returned by the version check.
+    * Mirrors `VersionStatus.status`.
+    */
+   readonly status: VersionCompatibility;
+   /** Full version status from the pre-migration check. */
+   readonly versionStatus: VersionStatus;
+   /**
+    * Migration report when `status` is `'needs_migration'`.
+    * `undefined` for `'compatible'` and `'too_new'` outcomes.
+    */
+   readonly migrateResult?: MigrateResult;
+}
+
+/**
+ * Minimal client interface required by `runMigrate`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface MigrateClient {
+   /**
+    * Checks the database format version against the WASM 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>;
+}
+
+/**
+ * Checks the database version and runs pending migrations when needed.
+ *
+ * Resolution order:
+ * - `'compatible'`: returns without running migrations
+ * - `'needs_migration'`: calls `client.migrateDatabase` and returns
+ *   the migration report
+ * - `'too_new'`: returns without running migrations (caller should
+ *   print an error and exit non-zero)
+ *
+ * @param client - migrate client to delegate to
+ * @param options - parsed CLI options supplying the optional `dbPath`
+ * @returns result containing the version status and optional migration
+ *   report
+ */
+export async function runMigrate(
+   client: MigrateClient,
+   options: CliOptions,
+): Promise<MigrateCommandResult> {
+   const targetPath = options.dbPath
+      ? resolve(options.dbPath)
+      : process.cwd();
+
+   const versionStatus = await client.checkVersion(targetPath);
+
+   if (versionStatus.status === 'needs_migration') {
+      const migrateResult = await client.migrateDatabase(targetPath);
+      return {
+         status: 'needs_migration',
+         versionStatus,
+         migrateResult,
+      };
+   }
+
+   return { status: versionStatus.status, versionStatus };
+}

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

@@ -0,0 +1,47 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+
+/**
+ * Index rebuild report returned by the daemon.
+ */
+interface RebuildResult {
+   /** Number of text and code sections that were re-indexed. */
+   readonly sections_reindexed: number;
+   /** Total number of unique terms written to the rebuilt indexes. */
+   readonly terms_indexed: number;
+   /** Time taken to complete the rebuild, in milliseconds. */
+   readonly elapsed_ms: number;
+}
+
+/**
+ * Minimal client interface required by `runRebuild`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface RebuildClient {
+   /**
+    * Reconstructs all index files from section files and document
+    * manifests on disk. Text and code sections are re-tokenized;
+    * image sections are skipped.
+    *
+    * @returns a report of sections and terms re-indexed
+    */
+   rebuildIndexes(): Promise<RebuildResult>;
+}
+
+/**
+ * Rebuilds all database indexes and returns the report.
+ *
+ * Delegates to `client.rebuildIndexes()`. The caller is responsible
+ * for printing the result to stdout.
+ *
+ * @param client - rebuild client to delegate to
+ * @param _options - parsed CLI options (unused; reserved for future flags)
+ * @returns the index rebuild report from the daemon
+ */
+export async function runRebuild(
+   client: RebuildClient,
+   _options: CliOptions,
+): Promise<RebuildResult> {
+   return client.rebuildIndexes();
+}

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

@@ -0,0 +1,62 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { SearchDisplay } from '../typings/search-display.model.ts';
+
+/**
+ * Minimal client interface required by `runSearch`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SearchClient {
+   /**
+    * Searches the knowledge base and returns ranked results.
+    *
+    * @param params - query, mode, and result limit
+    */
+   search(params: {
+      query: string;
+      mode?: string;
+      limit?: number;
+   }): Promise<
+      {
+         kbid: string;
+         score: number;
+         readonly matches: readonly {
+            readonly term: string;
+            readonly frequency: number;
+         }[];
+      }[]
+   >;
+}
+
+/**
+ * Executes a search query via the provided client and maps the raw
+ * daemon results to the `SearchDisplay` format used by the CLI.
+ *
+ * Returns an empty array without calling the client when `options.args`
+ * contains no query terms.
+ *
+ * @param client - search client to delegate to
+ * @param options - parsed CLI options supplying query args and search
+ *   parameters
+ */
+export async function runSearch(
+   client: SearchClient,
+   options: CliOptions,
+): Promise<SearchDisplay[]> {
+   const query = options.args.join(' ').trim();
+   if (!query) return [];
+
+   const results = await client.search({
+      query,
+      mode: options.mode,
+      limit: options.limit,
+   });
+
+   return results.map((r) => ({
+      kbid: r.kbid,
+      score: r.score,
+      preview: '',
+      matches: r.matches,
+   }));
+}

package/src/shared/cli/functions/run-skill-delete.function.ts

@@ -0,0 +1,47 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+
+/**
+ * Minimal client interface required by `runSkillDelete`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SkillDeleteClient {
+   /**
+    * Removes a section from the knowledge base.
+    *
+    * @param kbid - knowledge-base identifier of the section to remove
+    * @returns result indicating whether the section was found and removed
+    */
+   removeSection(kbid: string): Promise<{ removed: boolean }>;
+}
+
+/**
+ * Deletes a skill section from the knowledge base by its kbid.
+ *
+ * The kbid must be supplied as the first positional argument. Returns
+ * an error result if it is missing.
+ *
+ * @param client - client used to remove the skill section
+ * @param options - parsed CLI options; `args[0]` is the kbid
+ * @returns a `CommandResult` with the kbid and removal status
+ */
+export async function runSkillDelete(
+   client: SkillDeleteClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const kbid = options.args[0];
+   if (!kbid) {
+      return { error: 'kbid is required', exitCode: 1 };
+   }
+   const result = await client.removeSection(kbid);
+   return {
+      output: JSON.stringify(
+         { kbid, removed: result.removed },
+         null,
+         2,
+      ),
+      exitCode: 0,
+   };
+}

package/src/shared/cli/functions/run-skill-get.function.ts

@@ -0,0 +1,90 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import { parseSkillContent } from '../../mcp/functions/parse-skill-content.function.ts';
+
+/**
+ * Minimal client interface required by `runSkillGet`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SkillGetClient {
+   /**
+    * Retrieves one or more sections by their knowledge-base IDs.
+    *
+    * @param kbids - list of knowledge-base identifiers to fetch
+    * @returns matching section rows
+    */
+   readSections(
+      kbids: string[],
+   ): Promise<{ kbid: string; content: string }[]>;
+
+   /**
+    * Retrieves all sections stored with the given type name.
+    *
+    * @param sectionType - the type name to filter by
+    * @returns matching section rows
+    */
+   listByType(
+      sectionType: string,
+   ): Promise<
+      { kbid: string; title: string | null; content: string }[]
+   >;
+}
+
+/**
+ * Retrieves a skill definition by name or kbid.
+ *
+ * Accepts the identifier as the first positional argument or as
+ * `options.name`. When the identifier looks like a hex hash
+ * (16 or more hex characters) it is tried as a kbid first; if
+ * no section is found it falls back to a name lookup. When the
+ * identifier is not hex-like it goes directly to name lookup.
+ * For name lookups the most recently stored match (last in the
+ * array) is returned.
+ *
+ * @param client - client used to look up the skill section
+ * @param options - parsed CLI options; first positional arg or `name`
+ *   is used as the identifier
+ * @returns a `CommandResult` containing the serialized
+ *   `SkillDefinition` JSON or an error message
+ */
+export async function runSkillGet(
+   client: SkillGetClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const identifier = options.args[0] ?? options.name;
+   if (!identifier) {
+      return {
+         error: 'skill name or kbid required',
+         exitCode: 1,
+      };
+   }
+   let content: string | undefined;
+   // Try as kbid first when it looks like a hex hash.
+   if (/^[0-9a-f]{16,}$/i.test(identifier)) {
+      const sections = await client.readSections([identifier]);
+      if (sections.length > 0) {
+         content = sections[0]?.content;
+      }
+   }
+   // If not found by kbid, try by name.
+   if (content === undefined) {
+      const records = await client.listByType('skill');
+      const match = records.filter((r) => r.title === identifier).pop();
+      if (match) {
+         content = match.content;
+      }
+   }
+   if (content === undefined) {
+      return {
+         error: `skill not found: ${identifier}`,
+         exitCode: 1,
+      };
+   }
+   const skill = parseSkillContent(content);
+   return {
+      output: JSON.stringify(skill, null, 2),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,70 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import { extractSkillArguments } from '../../mcp/functions/extract-skill-arguments.function.ts';
+import { serializeSkillContent } from '../../mcp/functions/serialize-skill-content.function.ts';
+
+/**
+ * Minimal client interface required by `runSkillLearn`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SkillLearnClient {
+   /**
+    * Stores a skill section in the knowledge base.
+    *
+    * @param params - section type, serialized JSON content,
+    *   and optional title and description
+    * @returns result containing the assigned kbid
+    */
+   addSection(params: {
+      readonly sectionType: string;
+      readonly content: string;
+      readonly title?: string;
+      readonly description?: string;
+   }): Promise<AddSectionResult>;
+}
+
+/**
+ * Creates or updates a skill definition in the knowledge base.
+ *
+ * Validates that `--name` and `--body` are provided, extracts
+ * `{{argName}}` placeholders from the body, serializes the skill
+ * to JSON, and stores it as a `'skill'` section.
+ *
+ * @param client - client used to store the skill section
+ * @param options - parsed CLI options with `name` and `body` fields
+ * @returns a `CommandResult` with the stored section info or an error
+ */
+export async function runSkillLearn(
+   client: SkillLearnClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const name = options.name;
+   if (!name) {
+      return { error: '--name is required', exitCode: 1 };
+   }
+   const body = options.body;
+   if (!body) {
+      return { error: '--body is required', exitCode: 1 };
+   }
+   const args = extractSkillArguments(body);
+   const skill = {
+      name,
+      description: options.description,
+      arguments: args.length > 0 ? args : undefined,
+      body,
+   };
+   const json = serializeSkillContent(skill);
+   const result = await client.addSection({
+      sectionType: 'skill',
+      content: json,
+      title: name,
+      description: options.description,
+   });
+   return {
+      output: JSON.stringify(result, null, 2),
+      exitCode: 0,
+   };
+}

package/src/shared/cli/functions/run-skill-list.function.ts

@@ -0,0 +1,74 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+
+/**
+ * A single row returned by `listByType` for the skill client.
+ */
+interface SkillRecord {
+   /** Knowledge-base identifier for the skill section. */
+   kbid: string;
+   /** Skill name stored as the section title. */
+   title: string | null;
+   /** Optional skill description stored on the section. */
+   description: string | null;
+   /** Serialized `SkillDefinition` JSON stored as section content. */
+   content: string;
+}
+
+/**
+ * Minimal client interface required by `runSkillList`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface SkillListClient {
+   /**
+    * Retrieves all sections stored with the given type name.
+    *
+    * @param sectionType - the type name to filter by
+    * @returns matching section rows
+    */
+   listByType(sectionType: string): Promise<SkillRecord[]>;
+}
+
+/**
+ * Lists all skill definitions stored in the knowledge base.
+ *
+ * Calls `client.listByType('skill')` and maps each record to a
+ * summary that includes the argument count parsed from the JSON
+ * content. Parse errors default the argument count to `0`.
+ *
+ * @param client - client used to list skill sections
+ * @param _options - parsed CLI options (unused; reserved for future flags)
+ * @returns a `CommandResult` containing a JSON array of skill summaries
+ */
+export async function runSkillList(
+   client: SkillListClient,
+   _options: CliOptions,
+): Promise<CommandResult> {
+   const records = await client.listByType('skill');
+   const items = records.map((r) => {
+      let argumentCount = 0;
+      try {
+         const parsed = JSON.parse(r.content) as Record<
+            string,
+            unknown
+         >;
+         if (Array.isArray(parsed['arguments'])) {
+            argumentCount = parsed['arguments'].length;
+         }
+      } catch {
+         // ignore parse errors
+      }
+      return {
+         kbid: r.kbid,
+         name: r.title,
+         description: r.description,
+         argumentCount,
+      };
+   });
+   return {
+      output: JSON.stringify(items, null, 2),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,29 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+
+/**
+ * Minimal client interface required by `runStatus`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface StatusClient {
+   dbStatus(): Promise<unknown>;
+}
+
+/**
+ * Retrieves the database status and returns the summary report.
+ *
+ * Delegates to `client.dbStatus()`. The caller is responsible
+ * for serialising the result and setting the process exit code.
+ *
+ * @param client - status client to delegate to
+ * @param _options - parsed CLI options (unused; reserved for
+ *   future flags)
+ * @returns the status report from the daemon
+ */
+export async function runStatus(
+   client: StatusClient,
+   _options: CliOptions,
+): Promise<unknown> {
+   return client.dbStatus();
+}