@dikolab/kbdb 0.3.1 → 0.4.0

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

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

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

@@ -1,29 +0,0 @@
-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();
-}

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

@@ -1,58 +0,0 @@
-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/functions/version-gate.function.ts

@@ -1,44 +0,0 @@
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
-
-/**
- * Checks the database version and returns a `CommandResult` error
- * when the version is incompatible, or `null` when it is compatible.
- *
- * - `'needs_migration'`: prompts the user to run `kbdb --migrate`
- * - `'too_new'`: informs the user to upgrade kbdb
- * - `'compatible'`: returns `null` (no gate triggered)
- *
- * @param client - disconnectable client with version-check capability
- * @param dbDir - absolute path to the `.kbdb` database root
- * @returns error `CommandResult` when blocked, or `null` when clear
- */
-export async function versionGate(
-   client: DisconnectableClient,
-   dbDir: string,
-): Promise<CommandResult | null> {
-   const versionStatus = await client.checkVersion(dbDir);
-
-   if (versionStatus.status === 'needs_migration') {
-      return {
-         error:
-            'error: database needs migration' +
-            ' -- run `kbdb --migrate`',
-         exitCode: 1,
-      };
-   }
-
-   if (versionStatus.status === 'too_new') {
-      return {
-         error:
-            `error: database version` +
-            ` ${versionStatus.currentVersion.toString()}` +
-            ` is newer than kbdb version` +
-            ` ${versionStatus.requiredVersion.toString()}` +
-            ` -- upgrade kbdb`,
-         exitCode: 1,
-      };
-   }
-
-   return null;
-}

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

@@ -1,34 +0,0 @@
-import type { CommandResult } from '../typings/command-result.model.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-
-/**
- * Wraps an async command handler in a standard try/catch envelope.
- *
- * On success, serialises the result with `JSON.stringify` and
- * returns `exitCode: 0`. On failure, returns an error message
- * prefixed with `<label> failed:` and `exitCode: 1`.
- *
- * @param label - command name used in the error prefix
- * @param handler - async function that produces the command result
- * @param exitCodeSelector - optional function to derive `exitCode`
- *   from the successful result; defaults to always returning 0
- * @returns a `CommandResult` with output or error
- */
-export async function wrapCommand<T>(
-   label: string,
-   handler: () => Promise<T>,
-   exitCodeSelector?: (result: T) => number,
-): Promise<CommandResult> {
-   try {
-      const result = await handler();
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: exitCodeSelector ? exitCodeSelector(result) : 0,
-      };
-   } catch (err) {
-      return {
-         error: `${label} failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}

package/src/shared/cli/index.ts

@@ -1,55 +0,0 @@
-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 { runRecall } from './functions/run-recall.function.ts';
-export { runExport } from './functions/run-export.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,
-   PagedSearchDisplay,
-} from './typings/search-display.model.ts';
-export type { SearchClient } from './functions/run-search.function.ts';
-export type { RecallClient } from './functions/run-recall.function.ts';
-export type { ExportClient } from './functions/run-export.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/agent-create-client.interface.ts

@@ -1,47 +0,0 @@
-import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
-
-/**
- * Minimal client interface required by `runAgentCreate`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface AgentCreateClient {
-   /**
-    * Ingests a content section into the knowledge base.
-    *
-    * @param params - section type label, raw content, and optional
-    *   metadata
-    * @returns result object containing the assigned knowledge-base
-    *   identifier
-    */
-   addSection(params: {
-      readonly sectionType: string;
-      readonly content: string;
-      readonly title?: string;
-      readonly description?: string;
-   }): Promise<AddSectionResult>;
-
-   /**
-    * Groups a set of sections under a named document.
-    *
-    * @param title - human-readable document title
-    * @param kbids - identifiers of the sections to group
-    * @param docType - application-level document type tag; omit or
-    *   pass an empty string for untagged documents
-    * @returns the assigned document identifier
-    */
-   groupSections(
-      title: string,
-      kbids: string[],
-      docType?: string,
-   ): Promise<string>;
-
-   /**
-    * Retrieves one or more sections by their identifiers.
-    *
-    * @param kbids - list of knowledge-base identifiers to fetch
-    * @returns sections found; missing kbids are omitted from the result
-    */
-   readSections(kbids: string[]): Promise<{ kbid: string }[]>;
-}

package/src/shared/cli/typings/agent-get-client.interface.ts

@@ -1,39 +0,0 @@
-/** A document section reference as returned by `retrieveDocument`. */
-export interface AgentDocumentSection {
-   /** Knowledge-base identifier of the section. */
-   readonly kbid: string;
-   /** Zero-based position of the section within the document. */
-   readonly position: number;
-}
-
-/** A section record as returned by `readSections`. */
-export interface AgentSectionRecord {
-   /** Knowledge-base identifier of the section. */
-   readonly kbid: string;
-   /** Raw text content stored in the section. */
-   readonly content: string;
-}
-
-/**
- * Minimal client interface required by `runAgentGet`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface AgentGetClient {
-   /**
-    * Retrieves a full document record including its ordered sections.
-    *
-    * @param docid - identifier of the document to retrieve
-    * @returns the document record
-    */
-   retrieveDocument(docid: string): Promise<unknown>;
-
-   /**
-    * Retrieves one or more sections by their identifiers.
-    *
-    * @param kbids - list of knowledge-base identifiers to fetch
-    * @returns sections found; missing kbids are omitted from the result
-    */
-   readSections(kbids: string[]): Promise<AgentSectionRecord[]>;
-}

package/src/shared/cli/typings/check-client.interface.ts

@@ -1,66 +0,0 @@
-/** Raw daemon response from `integrityCheck`. */
-export interface RawIntegrityCheckResult {
-   /** `true` when all checks passed and no errors were found. */
-   readonly ok: boolean;
-   /** All integrity errors found; empty when `ok` is `true`. */
-   readonly errors: IntegrityError[];
-   /** Total number of sections examined. */
-   readonly sections_checked: number;
-   /** Total number of documents examined. */
-   readonly documents_checked: number;
-   /** Total number of marker references checked. */
-   readonly references_checked: number;
-   /** Time taken to complete the check, in milliseconds. */
-   readonly elapsed_ms: number;
-   /**
-    * Encoded divergent-content map.
-    *
-    * Format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
-    *
-    * Each semicolon-separated segment is a source key followed by
-    * a colon and a comma-separated list of kbids. Absent when no
-    * divergent content exists.
-    */
-   readonly divergent_content?: string;
-}
-
-/** A single integrity error found during a database check. */
-export interface IntegrityError {
-   /**
-    * The category of integrity violation detected.
-    *
-    * - `'checksum_mismatch'` -- stored content does not match its hash
-    * - `'orphan_section'` -- section not referenced by any document
-    * - `'orphan_document'` -- document references no existing sections
-    * - `'broken_reference'` -- a marker references a non-existent entity
-    * - `'type_mismatch'` -- stored MIME type conflicts with content
-    * - `'circular_reference'` -- marker chain contains a cycle
-    */
-   readonly type:
-      | 'checksum_mismatch'
-      | 'orphan_section'
-      | 'orphan_document'
-      | 'broken_reference'
-      | 'type_mismatch'
-      | 'circular_reference';
-   /** Identifier of the entity (kbid or docid) that has the issue. */
-   readonly entity: string;
-   /** Human-readable description of the specific problem. */
-   readonly detail: string;
-}
-
-/**
- * Minimal client interface required by `runCheck`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface CheckClient {
-   /**
-    * Runs an integrity check on the knowledge-base database.
-    *
-    * @returns a report of all issues found; `ok` is `true` when
-    *   no errors were detected
-    */
-   integrityCheck(): Promise<RawIntegrityCheckResult>;
-}

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

@@ -1,54 +0,0 @@
-import type { CliOptions } from './cli-options.interface.ts';
-import type { InitResult } from '../functions/run-init.function.ts';
-import type { DisconnectableClient } from './disconnectable-client.interface.ts';
-
-/**
- * Injectable dependencies for the CLI orchestrator.
- *
- * Every external side-effect is injected so the function
- * is fully testable without touching process globals,
- * filesystem, or network.
- */
-export interface CliDeps {
-   /** Returns `true` when stdin is an interactive terminal. */
-   isStdinTty: () => boolean;
-
-   /**
-    * Prompts the user with the given question and resolves with
-    * their trimmed response.
-    *
-    * @param question - text to display before the input prompt
-    */
-   promptUser: (question: string) => Promise<string>;
-
-   /**
-    * Creates a worker client connected to the given database path.
-    *
-    * @param opts - connection options including the context path
-    */
-   createWorkerClient: (opts: {
-      contextPath: string;
-   }) => Promise<DisconnectableClient>;
-
-   /**
-    * Finds the `.kbdb` directory starting from the given base path.
-    *
-    * @param basePath - starting directory; defaults to `process.cwd()`
-    * @returns absolute path to `.kbdb` or `null` when not found
-    */
-   findDb: (basePath?: string) => string | null;
-
-   /**
-    * Initialises a new `.kbdb` database directory.
-    *
-    * @param options - parsed CLI options
-    */
-   runInit: (options: CliOptions) => InitResult;
-
-   /**
-    * Starts the MCP server using the given database path.
-    *
-    * @param contextPath - absolute path to the `.kbdb` directory
-    */
-   startMcpServer?: (contextPath: string) => Promise<void>;
-}

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

@@ -1,72 +0,0 @@
-/**
- * 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;
-   /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
-   algo?: string;
-   /** Maximum number of results to return. Defaults to 20. */
-   limit: number;
-   /** Number of results to skip for pagination. */
-   offset?: 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[];
-   /**
-    * Recall expansion depth (0-3). Clamped to 3.
-    * Defaults to 0.
-    */
-   depth?: number;
-   /** Comma-separated tags for scoping (learn, recall). */
-   tags?: string[];
-   /**
-    * When `true`, enables supersession by source key (learn).
-    * Re-learning edited content replaces the original section
-    * instead of creating a sibling.
-    */
-   replace?: boolean;
-   /** Positional arguments following the sub-command. */
-   args: string[];
-}

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

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