@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,223 +0,0 @@
-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';
-
-/** Enriched add-section result returned by the daemon. */
-interface AddSectionResult {
-   /** Knowledge-base identifier assigned to the new section. */
-   readonly kbid: string;
-   /**
-    * Kbid of the section superseded via `--replace`,
-    * or `null` / `undefined` when none.
-    */
-   readonly superseded?: string | null;
-   /**
-    * Advisory warning strings (e.g. `"heading_missing"`).
-    * May be absent from older daemon versions.
-    */
-   readonly warnings?: string[];
-   /**
-    * Near-duplicate sections with similarity >= 0.85.
-    * May be absent from older daemon versions.
-    */
-   readonly near_duplicates?: {
-      readonly kbid: string;
-      readonly similarity: number;
-   }[];
-}
-
-/**
- * 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 metadata and raw text content
-    * @returns enriched result containing the new kbid plus
-    *   optional supersession, warnings, and near-duplicate info
-    */
-   addSection(params: {
-      sectionType: string;
-      content: string;
-      title?: string;
-      description?: string;
-      docid?: string;
-      tags?: string[];
-      replace?: boolean;
-      /**
-       * Absolute path to the source file. Required for supersession
-       * via source key when `replace` is `true`.
-       */
-      sourcePath?: string;
-   }): Promise<AddSectionResult>;
-}
-
-/** 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,
-            tags: options.tags,
-            replace: options.replace,
-         });
-         results.push(mapAddSectionResult(result, '-', content.length));
-         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,
-            description: options.description,
-            docid: options.docid,
-            tags: options.tags,
-            replace: options.replace,
-            sourcePath: file,
-         });
-         results.push(
-            mapAddSectionResult(result, file, content.length),
-         );
-      }
-   }
-
-   return results;
-}
-
-/**
- * Maps an `AddSectionResult` to a `LearnResult` record.
- *
- * @param result - raw result from `client.addSection()`
- * @param path - source file path or `'-'` for stdin
- * @param size - UTF-8 character count of the ingested content
- */
-function mapAddSectionResult(
-   result: AddSectionResult,
-   path: string,
-   size: number,
-): LearnResult {
-   return {
-      kbid: result.kbid,
-      path,
-      size,
-      skipped: false,
-      superseded: result.superseded ?? null,
-      warnings: result.warnings ?? [],
-      near_duplicates: result.near_duplicates ?? [],
-   };
-}
-
-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

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

@@ -1,47 +0,0 @@
-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-recall.function.ts

@@ -1,66 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
-
-/** Maximum allowed expansion depth for recall operations. */
-const MAX_RECALL_DEPTH = 3;
-
-/**
- * Minimal client interface required by `runRecall`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface RecallClient {
-   /**
-    * Retrieves full content and context for one or more sections
-    * by their knowledge-base identifiers.
-    *
-    * @param params - section identifier(s) and optional expansion
-    *   depth (0--3)
-    * @returns a single `RecallResult` when `kbid` is supplied, or
-    *   a `RecallResult[]` when `kbids` is supplied
-    */
-   recall(params: {
-      kbid?: string;
-      kbids?: string[];
-      depth?: number;
-   }): Promise<RecallResult | RecallResult[]>;
-}
-
-/**
- * Retrieves full content and progressive context for one or more
- * sections by kbid via the provided client.
- *
- * Returns an error result when no kbids are provided in
- * `options.args`. For a single kbid, calls `client.recall` with the
- * `kbid` parameter and returns the single `RecallResult`. For
- * multiple kbids, calls `client.recall` with the `kbids` array.
- *
- * The `depth` option is read from `options.depth`, defaulting to 0
- * and clamped to the range 0--3.
- *
- * @param client - recall client to delegate to
- * @param options - parsed CLI options supplying kbids in `args` and
- *   expansion depth in `depth`
- * @returns the `RecallResult` or `RecallResult[]` from the client,
- *   or an error object when no kbids are provided
- */
-export async function runRecall(
-   client: RecallClient,
-   options: CliOptions,
-): Promise<RecallResult | RecallResult[] | { error: string }> {
-   if (options.args.length === 0) {
-      return { error: 'no kbid provided' };
-   }
-
-   const depth = Math.min(
-      MAX_RECALL_DEPTH,
-      Math.max(0, options.depth ?? 0),
-   );
-
-   if (options.args.length === 1) {
-      return client.recall({ kbid: options.args[0], depth });
-   }
-
-   return client.recall({ kbids: options.args, depth });
-}

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

@@ -1,133 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-
-/** A single raw search result item returned by the daemon. */
-interface RawSearchItem {
-   /** Knowledge-base identifier of the matched section. */
-   readonly kbid: string;
-   /** Section heading, or null when untitled. */
-   readonly heading: string | null;
-   /** MIME type of the section content. */
-   readonly type: string;
-   /** Document IDs this section belongs to. */
-   readonly docids: readonly string[];
-   /** Relevance score from the ranking engine. */
-   readonly score: number;
-   /** KWIC excerpt centered on the highest-scoring matched term. */
-   readonly snippet: string;
-   /** Query terms that matched within this section. */
-   readonly matched_terms: readonly string[];
-   /**
-    * Fields that contained at least one match.
-    * May be absent from older daemon versions.
-    */
-   readonly matched_fields?: readonly string[];
-   /**
-    * Normalised confidence score (0.0-1.0) relative to the top result.
-    * May be absent from older daemon versions.
-    */
-   readonly confidence?: number;
-   /**
-    * ISO 8601 creation timestamp of the section.
-    * May be absent from older daemon versions.
-    */
-   readonly created_at?: string;
-}
-
-/** Raw paginated search response from the daemon. */
-interface RawSearchResponse {
-   /** Result items for the current page. */
-   readonly items: readonly RawSearchItem[];
-   /** Total number of matches across all pages. */
-   readonly total: number;
-   /** Number of results skipped. */
-   readonly offset: number;
-   /** Maximum results per page. */
-   readonly limit: number;
-   /** Whether more results exist beyond this page. */
-   readonly has_more: boolean;
-   /**
-    * When `true`, the engine relaxed the query to produce results.
-    * May be absent from older daemon versions.
-    */
-   readonly relaxed?: boolean;
-}
-
-/**
- * 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 paginated results.
-    *
-    * @param params - query, mode, limit, and offset
-    */
-   search(params: {
-      query: string;
-      mode?: string;
-      limit?: number;
-      offset?: number;
-      algo?: string;
-   }): Promise<RawSearchResponse>;
-}
-
-/**
- * Executes a search query via the provided client and maps the
- * daemon results to the `PagedSearchDisplay` format used by the
- * CLI.
- *
- * Returns an empty paged result 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<PagedSearchDisplay> {
-   const query = options.args.join(' ').trim();
-   if (!query) {
-      return {
-         items: [],
-         total: 0,
-         offset: 0,
-         limit: options.limit,
-         has_more: false,
-         relaxed: false,
-      };
-   }
-
-   const results = await client.search({
-      query,
-      mode: options.mode,
-      limit: options.limit,
-      offset: options.offset,
-      algo: options.algo,
-   });
-
-   return {
-      items: results.items.map((r) => ({
-         kbid: r.kbid,
-         heading: r.heading,
-         type: r.type,
-         docids: r.docids,
-         score: r.score,
-         confidence: r.confidence ?? 0,
-         snippet: r.snippet,
-         matched_terms: r.matched_terms,
-         matched_fields: r.matched_fields ?? [],
-         created_at: r.created_at ?? '',
-         preview: '',
-      })),
-      total: results.total,
-      offset: results.offset,
-      limit: results.limit,
-      has_more: results.has_more,
-      relaxed: results.relaxed ?? false,
-   };
-}

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

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

@@ -1,90 +0,0 @@
-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,
-   };
-}