@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/cli/constants/subcommand-help.constant.ts

@@ -1,195 +0,0 @@
-/**
- * Detailed help texts keyed by `"group-subcommand"`.
- *
- * Used by `generateHelp` to display per-subcommand documentation
- * when the user runs `kbdb <group> <subcommand> --help`. Falls
- * back to group-level help when the key is absent.
- */
-export const SUBCOMMAND_HELP: Readonly<Record<string, string>> = {
-   'db-init':
-      `kbdb db init - Initialise a new .kbdb directory\n` +
-      `\n` +
-      `Usage: kbdb db init [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to create .kbdb in\n` +
-      `                       (default: current directory)\n` +
-      `   -h, --help          Show this help message\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { path, created }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb db init\n` +
-      `   kbdb db init --db /path/to/project\n`,
-
-   'db-migrate':
-      `kbdb db migrate - Migrate database to current` +
-      ` format\n` +
-      `\n` +
-      `Usage: kbdb db migrate [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path containing .kbdb\n` +
-      `                       (default: current directory)\n` +
-      `   -h, --help          Show this help message\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON MigrateResult or "already up to date"\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb db migrate\n` +
-      `   kbdb db migrate --db /path/to/project\n`,
-
-   'skill-learn':
-      `kbdb skill learn - Create a new skill definition\n` +
-      `\n` +
-      `Usage: kbdb skill learn [options]` +
-      ` --name <n> --body <file|->\n` +
-      `\n` +
-      `Options:\n` +
-      `   --name <name>       Skill name (required)\n` +
-      `   --description <d>   Skill description\n` +
-      `   --body <file|->     Template body file or` +
-      ` stdin (required)\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { kbid, name, arguments }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb skill learn --name summarize` +
-      ` --body prompt.txt\n` +
-      `   cat body.txt | kbdb skill learn` +
-      ` --name my-skill --body -\n`,
-
-   'skill-list':
-      `kbdb skill list - List all skills\n` +
-      `\n` +
-      `Usage: kbdb skill list [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, name, description,` +
-      ` argumentCount }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb skill list\n` +
-      `   kbdb skill list --db /path/to/project\n`,
-
-   'skill-get':
-      `kbdb skill get - Retrieve a skill by name` +
-      ` or kbid\n` +
-      `\n` +
-      `Usage: kbdb skill get [options] <name-or-kbid>\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <name-or-kbid>      Skill name or 26-char` +
-      ` kbid\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON SkillDefinition object\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb skill get summarize-document\n` +
-      `   kbdb skill get abcdef1234567890abcdef1234\n`,
-
-   'skill-delete':
-      `kbdb skill delete - Remove a skill\n` +
-      `\n` +
-      `Usage: kbdb skill delete [options] <kbid>\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <kbid>              26-character kbid of the` +
-      ` skill to remove\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { kbid, removed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb skill delete abcdef1234567890abcdef1234\n`,
-
-   'agent-create':
-      `kbdb agent create - Create an agent with skill` +
-      ` refs\n` +
-      `\n` +
-      `Usage: kbdb agent create [options] --name <n>` +
-      ` --persona <file|-> --skills <kbid,...>\n` +
-      `\n` +
-      `Options:\n` +
-      `   --name <name>       Agent name (required)\n` +
-      `   --description <d>   Agent description\n` +
-      `   --persona <file|->  Persona file or stdin` +
-      ` (required)\n` +
-      `   --skills <kbid,...> Comma-separated skill` +
-      ` kbids (required)\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { docid, name, skills }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb agent create --name code-reviewer` +
-      ` --persona ./p.txt --skills abc123\n` +
-      `   cat persona.txt | kbdb agent create` +
-      ` --name my-agent --persona - --skills abc123\n`,
-
-   'agent-list':
-      `kbdb agent list - List all agents\n` +
-      `\n` +
-      `Usage: kbdb agent list [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { docid, name, description,` +
-      ` skillCount }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb agent list\n` +
-      `   kbdb agent list --db /path/to/project\n`,
-
-   'agent-get':
-      `kbdb agent get - Retrieve an agent by docid\n` +
-      `\n` +
-      `Usage: kbdb agent get [options] <docid>\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <docid>             Agent document identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON AgentDefinition object with resolved` +
-      ` skills\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb agent get agent-code-reviewer\n`,
-
-   'agent-delete':
-      `kbdb agent delete - Remove an agent\n` +
-      `\n` +
-      `Usage: kbdb agent delete [options] <docid>\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <docid>             Agent document identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { docid, removed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb agent delete agent-code-reviewer\n`,
-};

package/src/shared/cli/functions/collect-files.function.ts

@@ -1,55 +0,0 @@
-import { readdirSync, statSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
-import { SUPPORTED_EXTENSIONS } from '../constants/defaults.constant.ts';
-
-/**
- * Resolves a single target path to a flat list of supported files.
- *
- * When `target` is a file, returns it wrapped in an array if its
- * extension is in `SUPPORTED_EXTENSIONS` and it is not a dotfile;
- * otherwise returns `[]`. When `target` is a directory, recursively
- * collects all matching files, skipping dot-entries at every level.
- * Returns `[]` for non-existent or inaccessible paths.
- *
- * @param target - file or directory path to resolve
- * @returns flat array of absolute or relative paths to supported files
- */
-export 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 [];
-}
-
-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;
-}
-
-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/compute-section-kbid.function.ts

@@ -1,49 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/** RFC 4648 base32 alphabet (upper-case, no padding). */
-const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
-
-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
- */
-export 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);
-}

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

@@ -1,390 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { CommandResult } from '../typings/command-result.model.ts';
-import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
-import type { LearnIO } from './run-learn.function.ts';
-import type { SearchClient } from './run-search.function.ts';
-import type { LearnClient } from './run-learn.function.ts';
-import type { UnlearnClient } from './run-unlearn.function.ts';
-import type { ContentClient } from './run-content.function.ts';
-import type { CheckClient } from './run-check.function.ts';
-import type { GcClient } from './run-gc.function.ts';
-import type { RebuildClient } from './run-rebuild.function.ts';
-import type { StatusClient } from './run-status.function.ts';
-import type { DbMigrateClient } from './run-db-migrate.function.ts';
-import type { SkillLearnClient } from './run-skill-learn.function.ts';
-import type { SkillListClient } from './run-skill-list.function.ts';
-import type { SkillGetClient } from './run-skill-get.function.ts';
-import type { SkillDeleteClient } from './run-skill-delete.function.ts';
-import type { AgentCreateClient } from './run-agent-create.function.ts';
-import type { AgentListClient } from './run-agent-list.function.ts';
-import type { AgentGetClient } from './run-agent-get.function.ts';
-import type { AgentDeleteClient } from './run-agent-delete.function.ts';
-import type { RecallClient } from './run-recall.function.ts';
-import type { ExportClient } from './run-export.function.ts';
-import { runSearch } from './run-search.function.ts';
-import { runLearn } from './run-learn.function.ts';
-import { runUnlearn } from './run-unlearn.function.ts';
-import { runContent } from './run-content.function.ts';
-import { runCheck } from './run-check.function.ts';
-import { runGc } from './run-gc.function.ts';
-import { runRebuild } from './run-rebuild.function.ts';
-import { runStatus } from './run-status.function.ts';
-import { runDbInit } from './run-db-init.function.ts';
-import { runInit } from './run-init.function.ts';
-import { runDbMigrate } from './run-db-migrate.function.ts';
-import { runSkillLearn } from './run-skill-learn.function.ts';
-import { runSkillList } from './run-skill-list.function.ts';
-import { runSkillGet } from './run-skill-get.function.ts';
-import { runSkillDelete } from './run-skill-delete.function.ts';
-import { runAgentCreate } from './run-agent-create.function.ts';
-import { runAgentList } from './run-agent-list.function.ts';
-import { runAgentGet } from './run-agent-get.function.ts';
-import { runAgentDelete } from './run-agent-delete.function.ts';
-import { runRecall } from './run-recall.function.ts';
-import { runExport } from './run-export.function.ts';
-import { formatOutput } from './format-output.function.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-
-/**
- * Intersection of all data-command client interfaces.
- *
- * Each run* function defines its own minimal interface; this
- * intersection combines them so `dispatchCommand` can route
- * to any command handler with full type safety.
- */
-export type DispatchClient = SearchClient &
-   LearnClient &
-   UnlearnClient &
-   ContentClient &
-   CheckClient &
-   GcClient &
-   RebuildClient &
-   StatusClient &
-   DbMigrateClient &
-   SkillLearnClient &
-   SkillListClient &
-   SkillGetClient &
-   SkillDeleteClient &
-   AgentCreateClient &
-   AgentListClient &
-   AgentGetClient &
-   AgentDeleteClient &
-   RecallClient &
-   ExportClient;
-
-/**
- * Routes a parsed CLI command to the appropriate handler and
- * returns a `CommandResult` without touching process globals.
- *
- * @param client - worker client covering all data commands
- * @param options - parsed CLI options with command and args
- * @param io - optional injectable I/O for learn stdin
- */
-export async function dispatchCommand(
-   client: DispatchClient,
-   options: CliOptions,
-   io?: LearnIO,
-): Promise<CommandResult> {
-   switch (options.command) {
-      case 'learn':
-         return handleLearn(client, options, io);
-      case 'unlearn':
-         return handleUnlearn(client, options);
-      case 'search':
-         return handleSearch(client, options);
-      case 'recall':
-         return handleRecall(client, options);
-      case 'content':
-         return handleContent(client, options);
-      case 'check':
-         return handleCheck(client, options);
-      case 'gc':
-         return handleGc(client, options);
-      case 'rebuild':
-         return handleRebuild(client, options);
-      case 'status':
-         return handleStatus(client, options);
-      case 'export':
-         return handleExport(client, options);
-      case 'db-init':
-         return handleDbInit(options);
-      case 'db-migrate':
-         return handleDbMigrate(client, options);
-      case 'skill-learn': {
-         const result = await runSkillLearn(client, options);
-         return result;
-      }
-      case 'skill-list': {
-         const result = await runSkillList(client, options);
-         return result;
-      }
-      case 'skill-get': {
-         const result = await runSkillGet(client, options);
-         return result;
-      }
-      case 'skill-delete': {
-         const result = await runSkillDelete(client, options);
-         return result;
-      }
-      case 'agent-create': {
-         const result = await runAgentCreate(client, options);
-         return result;
-      }
-      case 'agent-list': {
-         const result = await runAgentList(client, options);
-         return result;
-      }
-      case 'agent-get': {
-         const result = await runAgentGet(client, options);
-         return result;
-      }
-      case 'agent-delete': {
-         const result = await runAgentDelete(client, options);
-         return result;
-      }
-      default:
-         return {
-            error: `unknown command: ${options.command}`,
-            exitCode: 1,
-         };
-   }
-}
-
-async function handleLearn(
-   client: DispatchClient,
-   options: CliOptions,
-   io?: LearnIO,
-): Promise<CommandResult> {
-   try {
-      const results = await runLearn(client, options, io);
-      return {
-         output: JSON.stringify(results, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `learn failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleUnlearn(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const results = await runUnlearn(client, options);
-      return {
-         output: JSON.stringify(results, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `unlearn failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleSearch(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const results = await runSearch(client, options);
-      if (options.content) {
-         await hydrateSearchPreviews(client, results);
-      }
-      return {
-         output: formatOutput(results, options.format),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `search failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleRecall(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runRecall(client, options);
-      if ('error' in result) {
-         return {
-            error: `error: ${result.error}`,
-            exitCode: 1,
-         };
-      }
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `recall failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleExport(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runExport(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `export failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleContent(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runContent(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `content failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleCheck(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runCheck(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: result.ok ? 0 : 1,
-      };
-   } catch (err) {
-      return {
-         error: `check failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleGc(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runGc(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `gc failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleRebuild(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runRebuild(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `rebuild failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-async function handleStatus(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runStatus(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `status failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-function handleDbInit(options: CliOptions): CommandResult {
-   return runDbInit(options, runInit);
-}
-
-async function handleDbMigrate(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult> {
-   try {
-      const result = await runDbMigrate(client, options);
-      return {
-         output: JSON.stringify(result, null, 2),
-         exitCode: 0,
-      };
-   } catch (err) {
-      return {
-         error: `db-migrate failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-}
-
-/**
- * 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 results - mutable search display records to hydrate
- */
-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/ensure-db.function.ts

@@ -1,21 +0,0 @@
-import { existsSync, mkdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-/**
- * Ensures that the `.kbdb` database directory exists at the
- * resolved base path, creating it recursively if necessary.
- *
- * When `dbPath` is provided it is resolved to an absolute path and
- * used as the base; otherwise `process.cwd()` is used.
- *
- * @param dbPath - optional path to the knowledge-base root directory
- * @returns absolute path to the `.kbdb` directory
- */
-export function ensureDb(dbPath?: string): string {
-   const base = dbPath ? resolve(dbPath) : process.cwd();
-   const kbdbDir = join(base, '.kbdb');
-   if (!existsSync(kbdbDir)) {
-      mkdirSync(kbdbDir, { recursive: true });
-   }
-   return kbdbDir;
-}