@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,58 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+
+/** Removal result returned by `UnlearnClient.removeSection`. */
+interface RemoveSectionResult {
+   /** `true` when the section was found and successfully removed. */
+   readonly removed: boolean;
+   /** Time taken to perform the removal, in milliseconds. */
+   readonly elapsed_ms: number;
+}
+
+/**
+ * Minimal client interface required by `runUnlearn`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface UnlearnClient {
+   /**
+    * Removes a section from the knowledge base.
+    *
+    * @param kbid - identifier of the section to remove
+    * @returns removal result with `removed` flag and elapsed time
+    */
+   removeSection(kbid: string): Promise<RemoveSectionResult>;
+}
+
+/** Result record produced for each kbid processed by the unlearn command. */
+export interface UnlearnResult {
+   /** Knowledge-base identifier that was targeted for removal. */
+   kbid: string;
+   /** `true` when the section was found and successfully removed. */
+   removed: boolean;
+}
+
+/**
+ * Removes the knowledge-base sections identified by `options.args`
+ * via the provided client.
+ *
+ * Each kbid in `options.args` is processed independently. If a kbid
+ * does not exist in the knowledge base, `removed` is set to `false`
+ * rather than throwing.
+ *
+ * @param client - unlearn client to delegate removal to
+ * @param options - parsed CLI options whose `args` list the kbids to
+ *   remove
+ * @returns one `UnlearnResult` per kbid processed
+ */
+export async function runUnlearn(
+   client: UnlearnClient,
+   options: CliOptions,
+): Promise<UnlearnResult[]> {
+   const results: UnlearnResult[] = [];
+   for (const kbid of options.args) {
+      const result = await client.removeSection(kbid);
+      results.push({ kbid, removed: result.removed });
+   }
+   return results;
+}

package/src/shared/cli/index.ts

@@ -0,0 +1,48 @@
+export { parseArgs } from './functions/parse-args.function.ts';
+export { formatOutput } from './functions/format-output.function.ts';
+export { runSearch } from './functions/run-search.function.ts';
+export { runLearn } from './functions/run-learn.function.ts';
+export { runUnlearn } from './functions/run-unlearn.function.ts';
+export { runContent } from './functions/run-content.function.ts';
+export { runCheck } from './functions/run-check.function.ts';
+export { runGc } from './functions/run-gc.function.ts';
+export { runRebuild } from './functions/run-rebuild.function.ts';
+export { ensureDb } from './functions/ensure-db.function.ts';
+export { findDb } from './functions/find-db.function.ts';
+export { runInit } from './functions/run-init.function.ts';
+export { runMigrate } from './functions/run-migrate.function.ts';
+export { errorToMessage } from './functions/error-to-message.function.ts';
+export { isStdinTty } from './functions/is-stdin-tty.function.ts';
+export { promptUser } from './functions/prompt-user.function.ts';
+export { dispatchCommand } from './functions/dispatch-command.function.ts';
+export { runCli } from './functions/run-cli.function.ts';
+export { HELP_TEXT } from './constants/help-text.constant.ts';
+export type {
+   CliOptions,
+   OutputFormat,
+   SearchMode,
+} from './typings/cli-options.interface.ts';
+export type { LearnResult } from './typings/learn-result.model.ts';
+export type { SearchDisplay } from './typings/search-display.model.ts';
+export type { SearchClient } from './functions/run-search.function.ts';
+export type { LearnClient } from './functions/run-learn.function.ts';
+export type {
+   UnlearnClient,
+   UnlearnResult,
+} from './functions/run-unlearn.function.ts';
+export type { ContentClient } from './functions/run-content.function.ts';
+export type { CheckClient } from './functions/run-check.function.ts';
+export type { GcClient } from './functions/run-gc.function.ts';
+export type { RebuildClient } from './functions/run-rebuild.function.ts';
+export type { InitResult } from './functions/run-init.function.ts';
+export type {
+   MigrateClient,
+   MigrateCommandResult,
+} from './functions/run-migrate.function.ts';
+export type { CommandResult } from './typings/command-result.model.ts';
+export type { PromptIO } from './functions/prompt-user.function.ts';
+export type { DispatchClient } from './functions/dispatch-command.function.ts';
+export type {
+   CliDeps,
+   DisconnectableClient,
+} from './functions/run-cli.function.ts';

package/src/shared/cli/typings/cli-options.interface.ts

@@ -0,0 +1,55 @@
+/**
+ * Supported output formats for CLI results.
+ *
+ * - `'json'` -- machine-readable JSON array
+ * - `'text'` -- human-readable numbered list
+ * - `'mcp'` -- JSON envelope for MCP protocol consumers
+ */
+export type OutputFormat = 'json' | 'text' | 'mcp';
+
+/**
+ * Controls which entity type is returned by a search query.
+ *
+ * - `'sections'` -- individual content sections (default)
+ * - `'documents'` -- document-level groupings
+ * - `'stats'` -- index statistics
+ */
+export type SearchMode = 'sections' | 'documents' | 'stats';
+
+/** Parsed representation of all CLI arguments for a single invocation. */
+export interface CliOptions {
+   /** The sub-command to execute (e.g. `'search'`, `'learn'`). */
+   command: string;
+   /**
+    * Path to the knowledge-base root directory.
+    * Defaults to the current working directory when omitted.
+    */
+   dbPath?: string;
+   /** Output format for results. Defaults to `'json'`. */
+   format: OutputFormat;
+   /** Search mode passed to the worker daemon. Defaults to `'sections'`. */
+   mode: SearchMode;
+   /** Maximum number of results to return. Defaults to 20. */
+   limit: number;
+   /** Section title for learn command. */
+   title?: string;
+   /** Section description for learn command. */
+   description?: string;
+   /** Document ID for learn command. */
+   docid?: string;
+   /**
+    * When `true`, hydrates each search result's `preview` field
+    * with the section's actual content via `client.content()`.
+    */
+   content?: boolean;
+   /** Skill or agent name for skill/agent commands. */
+   name?: string;
+   /** Agent persona content or file path. */
+   persona?: string;
+   /** Skill body content or file path. */
+   body?: string;
+   /** Comma-separated skill kbids for agent create. */
+   skills?: string[];
+   /** Positional arguments following the sub-command. */
+   args: string[];
+}

package/src/shared/cli/typings/command-result.model.ts

@@ -0,0 +1,15 @@
+/**
+ * Result of dispatching a CLI command.
+ *
+ * Encapsulates output, error text, and exit code so the
+ * caller can decide how to present them (console, MCP, etc.)
+ * without the dispatch function touching process globals.
+ */
+export interface CommandResult {
+   /** Text to write to stdout (if any). */
+   output?: string;
+   /** Error message to write to stderr (if any). */
+   error?: string;
+   /** Process exit code. `0` means success. */
+   exitCode: number;
+}

package/src/shared/cli/typings/learn-result.model.ts

@@ -0,0 +1,11 @@
+/** Result record produced for each file processed by the learn command. */
+export interface LearnResult {
+   /** Knowledge-base identifier assigned to the ingested section. */
+   kbid: string;
+   /** Absolute path to the source file that was ingested. */
+   path: string;
+   /** Size of the file content in bytes (UTF-8 character count). */
+   size: number;
+   /** `true` when the file was skipped without being ingested. */
+   skipped: boolean;
+}

package/src/shared/cli/typings/search-display.model.ts

@@ -0,0 +1,17 @@
+/** A single search result formatted for display to the user. */
+export interface SearchDisplay {
+   /** Knowledge-base identifier of the matched section. */
+   kbid: string;
+   /** Relevance score assigned by the ranking engine. */
+   score: number;
+   /**
+    * Short excerpt from the section content.
+    * Empty string when no preview text is available.
+    */
+   preview: string;
+   /** Terms that matched within this section and their frequencies. */
+   readonly matches: readonly {
+      readonly term: string;
+      readonly frequency: number;
+   }[];
+}

package/src/shared/dir-resolver/functions/resolve-base-dir.function.ts

@@ -0,0 +1,25 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { BaseDir } from '../typings/base-dir.interface.ts';
+
+export function resolveScriptDir(
+   entryUrl: string,
+   entryDirname?: string,
+): string {
+   if (entryDirname) return entryDirname;
+   if (entryUrl.startsWith('file:'))
+      return dirname(fileURLToPath(entryUrl));
+   return dirname(entryUrl);
+}
+
+export function resolveBaseDir(
+   entryUrl: string,
+   entryDirname?: string,
+): BaseDir {
+   const scriptDir =
+      typeof __dirname !== 'undefined'
+         ? __dirname
+         : resolveScriptDir(entryUrl, entryDirname);
+   return { scriptDir, cwd: process.cwd() };
+}

package/src/shared/dir-resolver/functions/resolve-wasm-dir.function.ts

@@ -0,0 +1,5 @@
+import { join } from 'node:path';
+
+export function resolveWasmDir(scriptDir: string): string {
+   return join(scriptDir, 'wasm');
+}

package/src/shared/dir-resolver/functions/resolve-worker-script.function.ts

@@ -0,0 +1,13 @@
+import { join } from 'node:path';
+
+import type { Runtime } from '../../runtime/typings/runtime.ts';
+
+export function resolveWorkerScript(
+   scriptDir: string,
+   runtime: Runtime,
+): string {
+   if (runtime === 'deno') {
+      return join(scriptDir, 'worker.ts');
+   }
+   return join(scriptDir, 'kbdb-worker.cjs');
+}

package/src/shared/dir-resolver/index.ts

@@ -0,0 +1,7 @@
+export {
+   resolveBaseDir,
+   resolveScriptDir,
+} from './functions/resolve-base-dir.function.ts';
+export { resolveWorkerScript } from './functions/resolve-worker-script.function.ts';
+export { resolveWasmDir } from './functions/resolve-wasm-dir.function.ts';
+export type { BaseDir } from './typings/base-dir.interface.ts';

package/src/shared/dir-resolver/typings/base-dir.interface.ts

@@ -0,0 +1,4 @@
+export interface BaseDir {
+   readonly scriptDir: string;
+   readonly cwd: string;
+}

package/src/shared/hash/functions/compute-sha256.ts

@@ -0,0 +1,17 @@
+/**
+ * Computes the SHA-256 hash of a UTF-8 string.
+ *
+ * Uses the Web Crypto API (`crypto.subtle`), which is available
+ * in both Deno and Node.js >= 20 without additional imports.
+ *
+ * @param input - the string to hash
+ * @returns lowercase hex-encoded SHA-256 digest (64 characters)
+ */
+export async function computeSha256(input: string): Promise<string> {
+   const data = new TextEncoder().encode(input);
+   const hash = await crypto.subtle.digest('SHA-256', data);
+   const bytes = new Uint8Array(hash);
+   return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+}

package/src/shared/hash/index.ts

@@ -0,0 +1 @@
+export { computeSha256 } from './functions/compute-sha256.ts';