@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/cli/functions/handle-data-command.function.ts

@@ -1,67 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { CliDeps } from '../typings/cli-deps.interface.ts';
-import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-import { versionGate } from './version-gate.function.ts';
-import { dispatchCommand } from './dispatch-command.function.ts';
-
-/**
- * Handles data commands (search, learn, recall, etc.) by finding or
- * creating the database, running the version gate, and dispatching to
- * the appropriate command handler.
- *
- * When the database is not found in non-TTY mode, returns an error.
- * In TTY mode, prompts the user to create a new database.
- *
- * @param options - parsed CLI options with command and args
- * @param deps - injectable CLI dependencies
- * @returns a `CommandResult` from the dispatched command
- */
-export async function handleDataCommand(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   let dbDir = deps.findDb(options.dbPath);
-
-   if (!dbDir) {
-      const basePath = options.dbPath ?? process.cwd();
-      if (!deps.isStdinTty()) {
-         return {
-            error:
-               `error: no .kbdb database found at ${basePath}` +
-               ' -- run `kbdb --init` to create one',
-            exitCode: 1,
-         };
-      }
-      const answer = await deps.promptUser(
-         `No .kbdb database found. Create one in ${basePath}? [y/N] `,
-      );
-      if (answer.toLowerCase() !== 'y') {
-         return { error: 'aborted: no database created', exitCode: 1 };
-      }
-      const initResult = deps.runInit(options);
-      if (!initResult.ok) {
-         return {
-            error: `error: ${initResult.errorMessage ?? 'init failed'}`,
-            exitCode: 1,
-         };
-      }
-      dbDir = initResult.targetPath;
-   }
-
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({ contextPath: dbDir });
-   } catch (err) {
-      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
-   }
-
-   try {
-      const gateResult = await versionGate(client, dbDir);
-      if (gateResult) return gateResult;
-      return await dispatchCommand(client, options);
-   } finally {
-      client.disconnect();
-   }
-}

package/src/shared/cli/functions/handle-mcp.function.ts

@@ -1,56 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { CliDeps } from '../typings/cli-deps.interface.ts';
-import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-import { versionGate } from './version-gate.function.ts';
-
-/**
- * Handles the `mcp` command sub-flow.
- *
- * Resolves the database directory, creates a worker client, runs
- * the version gate, and starts the MCP server. Disconnects the
- * worker client when finished.
- *
- * @param options - parsed CLI options (uses `dbPath` and env fallback)
- * @param deps - injectable CLI dependencies
- * @returns a `CommandResult` with `exitCode: 0` on success
- */
-export async function handleMcp(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   const rawDbPath = options.dbPath ?? process.env['KBDB_DIR'];
-   if (!rawDbPath) {
-      return {
-         error: 'error: --db or KBDB_DIR required in MCP mode',
-         exitCode: 1,
-      };
-   }
-   const dbDir = deps.findDb(rawDbPath);
-   if (!dbDir) {
-      return {
-         error: `error: no .kbdb database found at ${rawDbPath}`,
-         exitCode: 1,
-      };
-   }
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({ contextPath: dbDir });
-   } catch (err) {
-      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
-   }
-   try {
-      const gateResult = await versionGate(client, dbDir);
-      if (gateResult) return gateResult;
-      if (deps.startMcpServer) await deps.startMcpServer(dbDir);
-      return { exitCode: 0 };
-   } catch (err) {
-      return {
-         error: `error: mcp failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   } finally {
-      client.disconnect();
-   }
-}

package/src/shared/cli/functions/handle-migrate.function.ts

@@ -1,64 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { CliDeps } from '../typings/cli-deps.interface.ts';
-import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-
-/**
- * Handles the `migrate` / `db-migrate` command sub-flow.
- *
- * Resolves the database directory, creates a worker client,
- * checks the version, and runs migrations when needed. Disconnects
- * the worker client when finished.
- *
- * @param options - parsed CLI options (uses `dbPath`)
- * @param deps - injectable CLI dependencies
- * @returns a `CommandResult` with migration output or an error
- */
-export async function handleMigrate(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   const dbDir = deps.findDb(options.dbPath);
-   if (!dbDir) {
-      return {
-         error: `error: no .kbdb database found at ${options.dbPath ?? process.cwd()}`,
-         exitCode: 1,
-      };
-   }
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({ contextPath: dbDir });
-   } catch (err) {
-      return { error: `error: ${errorToMessage(err)}`, exitCode: 1 };
-   }
-   try {
-      const versionStatus = await client.checkVersion(dbDir);
-      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,
-         };
-      }
-      if (versionStatus.status === 'needs_migration') {
-         const migrateResult = await client.migrateDatabase(dbDir);
-         return {
-            output: JSON.stringify(migrateResult, null, 2),
-            exitCode: 0,
-         };
-      }
-      return { output: 'already up to date', exitCode: 0 };
-   } catch (err) {
-      return {
-         error: `error: migrate failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   } finally {
-      client.disconnect();
-   }
-}

package/src/shared/cli/functions/hydrate-search-previews.function.ts

@@ -1,29 +0,0 @@
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-import type { ContentClient } from './run-content.function.ts';
-
-/**
- * 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 paged - mutable search display records to hydrate
- */
-export 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/install-default-skills.function.ts

@@ -1,296 +0,0 @@
-import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-/**
- * RFC 4648 base32 alphabet (upper-case, no padding).
- * Used to encode the SHA-256-derived kbid bytes.
- */
-const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
-
-/**
- * Encodes a byte array as a lowercase base32 string without padding.
- *
- * Mirrors the `data_encoding::BASE32_NOPAD` encoding used in the
- * Rust engine's `KbId::from_content`.
- *
- * @param bytes - raw bytes to encode
- * @returns lowercase base32-encoded string
- */
-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
- */
-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);
-}
-
-/**
- * Escapes backslashes and double-quotes in a string for TOML inline
- * string values.
- *
- * Mirrors the `escape_toml_str` function in the Rust engine.
- *
- * @param s - string to escape
- * @returns escaped string safe for use inside TOML double-quoted strings
- */
-function escapeToml(s: string): string {
-   return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-}
-
-/**
- * Serializes a skill section record to the `.section` file format.
- *
- * Format:
- * ```
- * kbid = "..."
- * section_type = "text/markdown"
- * type_name = "skill"
- * title = "..."
- * description = "..."
- * size = 0
- * token_count = 0
- * heading_token_count = 0
- * body_token_count = 0
- * code_token_count = 0
- * created_at = 0
- * checksum = "..."
- *
- * ---
- * <json content>
- * ```
- *
- * @param kbid - 26-char content-addressed identifier
- * @param title - skill name used as section title
- * @param description - human-readable description
- * @param content - serialised JSON skill definition
- * @returns file content string
- */
-function serializeSkillSection(
-   kbid: string,
-   title: string,
-   description: string,
-   content: string,
-): string {
-   const size = Buffer.byteLength(content, 'utf-8');
-   const header = [
-      `kbid = "${escapeToml(kbid)}"`,
-      `section_type = "text/markdown"`,
-      `type_name = "skill"`,
-      `title = "${escapeToml(title)}"`,
-      `description = "${escapeToml(description)}"`,
-      `size = ${size.toString()}`,
-      `token_count = 0`,
-      `heading_token_count = 0`,
-      `body_token_count = 0`,
-      `code_token_count = 0`,
-      `created_at = 0`,
-      `checksum = "${escapeToml(kbid)}"`,
-      '',
-   ].join('\n');
-   return `${header}\n---\n${content}`;
-}
-
-/** Descriptor for a skill to install. */
-interface SkillDescriptor {
-   /** Unique skill name (kebab-case). */
-   readonly name: string;
-   /** Human-readable description. */
-   readonly description: string;
-   /** Template body text. */
-   readonly body: string;
-}
-
-/**
- * Installs a single skill section file under `sectionsDir`.
- *
- * Creates the shard subdirectory if it does not exist. Skips
- * writing if the section file already exists, preserving any
- * user modifications.
- *
- * @param sectionsDir - absolute path to `.kbdb/sections`
- * @param skill - skill definition to serialise and store
- */
-function installSkill(
-   sectionsDir: string,
-   skill: SkillDescriptor,
-): void {
-   const content = JSON.stringify({
-      name: skill.name,
-      description: skill.description,
-      arguments: [],
-      body: skill.body,
-   });
-   const kbid = computeSectionKbid('text/markdown', content);
-   const prefix = kbid.slice(0, 2);
-   const shardDir = join(sectionsDir, prefix);
-   const filePath = join(shardDir, `${kbid}.section`);
-
-   if (existsSync(filePath)) {
-      return;
-   }
-
-   mkdirSync(shardDir, { recursive: true });
-
-   const fileContent = serializeSkillSection(
-      kbid,
-      skill.name,
-      skill.description,
-      content,
-   );
-   writeFileSync(filePath, fileContent, 'utf-8');
-}
-
-/**
- * Body text for the `query-guidance` default skill.
- *
- * Teaches AI agents how to effectively search the knowledge base
- * using lexical BM25F queries.
- */
-const QUERY_GUIDANCE_BODY =
-   'This knowledge base uses lexical search (stemmed BM25F), not' +
-   ' semantic/vector search. Follow these guidelines for effective' +
-   ' retrieval:\n\n' +
-   '1. Issue MULTIPLE short keyword queries rather than one long' +
-   ' natural-language question. Each query should target 2-3' +
-   ' specific terms.\n\n' +
-   '2. EXPAND SYNONYMS yourself. "login" will not match "sign-in"' +
-   ' unless both terms appear in the content. Try alternative' +
-   ' phrasings: search for "login", then "sign-in", then' +
-   ' "authentication".\n\n' +
-   '3. USE BOOLEAN AND PHRASE SYNTAX:\n' +
-   '   - Exact phrases: "error handling"\n' +
-   '   - Boolean AND: auth AND token\n' +
-   '   - Boolean OR: cache OR redis\n' +
-   '   - Exclusion: auth -oauth\n\n' +
-   '4. LEAN ON HEADINGS. Headings carry 2x weight in ranking.' +
-   ' Search for terms that are likely in section titles.\n\n' +
-   '5. STEMMING IS AUTOMATIC. "connections" matches "connect",' +
-   ' "running" matches "run". You do not need to try inflected' +
-   ' forms.\n\n' +
-   '6. USE RECALL AFTER SEARCH. After finding relevant sections' +
-   ' with search, use recall with increasing depth (0-3) to' +
-   ' progressively expand context: depth 0 = full content, depth' +
-   ' 1 = parent documents + back-references, depth 2 = siblings' +
-   ' + forward references, depth 3 = referenced sections.\n\n' +
-   '7. CODE IDENTIFIERS ARE SPLIT. camelCase and snake_case names' +
-   ' are decomposed: getUserById becomes searchable as "get",' +
-   ' "user", "by", "id".\n\n' +
-   '8. PAGINATION. Default limit is 20 results. Use offset for' +
-   ' additional pages if total > limit.';
-
-/**
- * Body text for the `memory-protocol` default skill.
- *
- * Teaches AI agents when and what to store in the knowledge base
- * to keep it accurate and useful.
- */
-const MEMORY_PROTOCOL_BODY =
-   'Follow these guidelines to keep the knowledge base accurate' +
-   ' and useful:\n\n' +
-   '1. STORE DURABLE FACTS: decisions, architecture choices,' +
-   ' configuration values, corrections to prior knowledge, API' +
-   ' contracts, and resolved incidents. These are the facts that' +
-   ' matter weeks later.\n\n' +
-   '2. DO NOT STORE: transient conversation context, debugging' +
-   ' output, ephemeral task state, raw log dumps, or information' +
-   ' that changes every session. The brain should contain' +
-   ' knowledge, not activity logs.\n\n' +
-   '3. SEARCH BEFORE STORING. Always search the knowledge base' +
-   ' before adding new content. If a section already covers the' +
-   ' topic, use learn with --replace to update it rather than' +
-   ' creating a duplicate.\n\n' +
-   '4. USE --replace FOR CORRECTIONS. When a fact changes (e.g.,' +
-   ' rate limit updated from 100 to 200 req/min), re-learn the' +
-   ' corrected content with --replace so the old version is' +
-   ' superseded. Without --replace, both the old and new versions' +
-   ' coexist with equal ranking.\n\n' +
-   '5. ATTACH TAGS for scoping. Use tags like project name,' +
-   ' domain, or topic (e.g., --tags auth,api,v2) so queries can' +
-   ' be filtered by scope later.\n\n' +
-   '6. PREFER RECENT RESULTS. When search returns multiple' +
-   ' sections covering the same topic, prefer the one with the' +
-   ' most recent created_at timestamp -- it is more likely to' +
-   ' reflect the current state.\n\n' +
-   '7. USE RECALL AFTER SEARCH. After finding relevant sections,' +
-   ' use recall with increasing depth (0-3) to expand context' +
-   ' progressively before making decisions.\n\n' +
-   '8. INCLUDE HEADINGS. Always provide a descriptive title when' +
-   ' storing content. Headings carry 2x ranking weight -- omitting' +
-   ' them significantly reduces searchability.';
-
-/**
- * Default skills installed on every fresh `kbdb db init`.
- *
- * These provide baseline guidance that improves AI agent
- * effectiveness out of the box. They are regular skill sections
- * and can be deleted by users.
- */
-const DEFAULT_SKILLS: readonly SkillDescriptor[] = [
-   {
-      name: 'query-guidance',
-      description:
-         'How to effectively search this knowledge base.' +
-         ' Read this before issuing search queries.',
-      body: QUERY_GUIDANCE_BODY,
-   },
-   {
-      name: 'memory-protocol',
-      description:
-         'Guidelines for what to store in this knowledge base' +
-         ' and when. Read this before using the learn tool.',
-      body: MEMORY_PROTOCOL_BODY,
-   },
-];
-
-/**
- * Writes the two default skills (`query-guidance` and
- * `memory-protocol`) as section files directly into the `.kbdb`
- * directory scaffold.
- *
- * Called by `runInit` after the directory scaffold is created.
- * Does not require a running worker daemon. Skips any skill whose
- * section file already exists so user modifications are preserved.
- *
- * @param dbDir - absolute path to the `.kbdb` directory
- */
-export function installDefaultSkills(dbDir: string): void {
-   const sectionsDir = join(dbDir, 'sections');
-   for (const skill of DEFAULT_SKILLS) {
-      installSkill(sectionsDir, skill);
-   }
-}

package/src/shared/cli/functions/is-stdin-tty.function.ts

@@ -1,12 +0,0 @@
-/**
- * Returns `true` when stdin is an interactive terminal.
- *
- * @param stdin - readable stream to check (defaults to
- *   `process.stdin`)
- */
-export function isStdinTty(
-   stdin: NodeJS.ReadStream = process.stdin,
-): boolean {
-   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- isTTY is undefined at runtime for non-TTY despite Node types saying boolean
-   return stdin.isTTY ?? false;
-}

package/src/shared/cli/functions/parse-args.function.ts

@@ -1,156 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import {
-   DEFAULT_FORMAT,
-   DEFAULT_LIMIT,
-   DEFAULT_MODE,
-} from '../constants/defaults.constant.ts';
-
-/**
- * Parses a raw argument vector into a structured `CliOptions` object.
- *
- * Recognises `--help` / `-h` and `--version` / `-v` as early-exit
- * flags that set the command and return immediately. All other flags
- * consume the next token as their value. The first non-flag token
- * becomes the command; subsequent non-flag tokens become `args`.
- *
- * Compound commands are supported: when the first positional token is
- * a group name (`db`, `skill`, or `agent`), the next positional token
- * is joined with a hyphen to form the compound command
- * (e.g. `db init` → `'db-init'`).
- *
- * Context-aware `--help`: when `--help` or `-h` appears after a
- * command has been set, the existing command is moved to `args[0]`
- * and the command is set to `'help'`, enabling per-command help.
- *
- * Deprecated flags `--init` and `--migrate` emit a warning to stderr
- * before setting the corresponding command.
- *
- * @param argv - argument strings (typically `process.argv.slice(2)`)
- * @returns fully populated `CliOptions` with defaults applied
- */
-export function parseArgs(argv: string[]): CliOptions {
-   const options: CliOptions = {
-      command: '',
-      format: DEFAULT_FORMAT,
-      mode: DEFAULT_MODE,
-      limit: DEFAULT_LIMIT,
-      args: [],
-   };
-
-   let i = 0;
-   while (i < argv.length) {
-      const arg = argv[i];
-      switch (arg) {
-         case '--help':
-         case '-h':
-            if (options.command) {
-               options.args.unshift(options.command);
-               options.command = 'help';
-            } else {
-               options.command = 'help';
-            }
-            return options;
-         case '--version':
-         case '-v':
-            options.command = 'version';
-            return options;
-         case '--init':
-            // eslint-disable-next-line no-console
-            console.error(
-               'warning: --init is deprecated,' + ' use "kbdb db init"',
-            );
-            options.command = 'init';
-            break;
-         case '--migrate':
-            // eslint-disable-next-line no-console
-            console.error(
-               'warning: --migrate is deprecated,' +
-                  ' use "kbdb db migrate"',
-            );
-            options.command = 'migrate';
-            break;
-         case '--db':
-            options.dbPath = argv[++i];
-            break;
-         case '--format':
-         case '-f':
-            options.format = (argv[++i] ??
-               DEFAULT_FORMAT) as CliOptions['format'];
-            break;
-         case '--mode':
-         case '-m':
-            options.mode = (argv[++i] ??
-               DEFAULT_MODE) as CliOptions['mode'];
-            break;
-         case '--limit':
-         case '-l':
-            options.limit =
-               parseInt(argv[++i] ?? '', 10) || DEFAULT_LIMIT;
-            break;
-         case '--offset':
-         case '-o':
-            options.offset = Math.max(
-               0,
-               parseInt(argv[++i] ?? '', 10) || 0,
-            );
-            break;
-         case '--algo':
-            options.algo = argv[++i];
-            break;
-         case '--title':
-            options.title = argv[++i];
-            break;
-         case '--description':
-            options.description = argv[++i];
-            break;
-         case '--docid':
-            options.docid = argv[++i];
-            break;
-         case '--name':
-            options.name = argv[++i];
-            break;
-         case '--persona':
-            options.persona = argv[++i];
-            break;
-         case '--body':
-            options.body = argv[++i];
-            break;
-         case '--skills':
-            options.skills = (argv[++i] ?? '').split(',');
-            break;
-         case '--tags':
-            options.tags = (argv[++i] ?? '').split(',');
-            break;
-         case '--replace':
-            options.replace = true;
-            break;
-         case '--depth':
-         case '-d':
-            options.depth = Math.min(
-               3,
-               Math.max(0, parseInt(argv[++i] ?? '', 10) || 0),
-            );
-            break;
-         case '--content':
-         case '-c':
-            options.content = true;
-            break;
-         default:
-            if (!options.command) {
-               options.command = arg;
-            } else if (
-               !options.args.length &&
-               (options.command === 'db' ||
-                  options.command === 'skill' ||
-                  options.command === 'agent')
-            ) {
-               options.command = `${options.command}-${arg}`;
-            } else {
-               options.args.push(arg);
-            }
-      }
-      i++;
-   }
-
-   return options;
-}