@dikolab/kbdb 0.3.2 → 0.4.0

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

@@ -1,219 +0,0 @@
-/**
- * Help text strings keyed by top-level command name.
- *
- * Used by `generateHelp` to display per-command documentation
- * when the user runs `kbdb <command> --help`.
- */
-export const LEAF_HELP: Readonly<Record<string, string>> = {
-   learn:
-      `kbdb learn - Import content from files or stdin\n` +
-      `\n` +
-      `Usage: kbdb learn [options] <path | ->...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <path | ->          File path, directory,` +
-      ` or - for stdin\n` +
-      `\n` +
-      `Options:\n` +
-      `   --title <title>     Section title\n` +
-      `   --description <d>   Section description\n` +
-      `   --docid <docid>     Document ID to group` +
-      ` under\n` +
-      `   --tags <t,...>      Comma-separated tags\n` +
-      `   --replace           Supersede existing section` +
-      ` by source key\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, path, size, skipped,\n` +
-      `                   superseded, warnings,` +
-      ` near_duplicates }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb learn README.md\n` +
-      `   kbdb learn ./docs/\n` +
-      `   kbdb learn --tags auth,api --replace doc.md\n` +
-      `   cat notes.txt | kbdb learn -\n`,
-
-   unlearn:
-      `kbdb unlearn - Remove sections by kbid\n` +
-      `\n` +
-      `Usage: kbdb unlearn [options] <kbid>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <kbid>              26-character knowledge` +
-      ` base identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, removed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb unlearn abcdef1234567890abcdef1234\n` +
-      `   kbdb unlearn id1 id2 id3\n`,
-
-   search:
-      `kbdb search - Query the knowledge base\n` +
-      `\n` +
-      `Usage: kbdb search [options] <query>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <query>             One or more query terms\n` +
-      `\n` +
-      `Options:\n` +
-      `   --mode <mode>       Result granularity` +
-      ` (sections|documents|stats)\n` +
-      `   --limit <n>         Max results (default: 20)\n` +
-      `   --format <fmt>      Output format` +
-      ` (json|text|mcp)\n` +
-      `   --content, -c       Hydrate results with` +
-      ` section content\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON array of { kbid, score, preview,` +
-      ` matches }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb search "machine learning"\n` +
-      `   kbdb search --limit 5 --format text query\n` +
-      `   kbdb search --mode documents --content term\n`,
-
-   recall:
-      `kbdb recall - Retrieve section context by kbid\n` +
-      `\n` +
-      `Usage: kbdb recall [options] <kbid>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <kbid>              26-character knowledge` +
-      ` base identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --depth <n>, -d     Expansion depth (0-3,` +
-      ` default: 0)\n` +
-      `   --tags <t,...>      Filter by tags\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON RecallResult or RecallResult[]\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb recall abcdef1234567890abcdef1234\n` +
-      `   kbdb recall kbid1 --depth 2\n`,
-
-   content:
-      `kbdb content - Compose rendered content from ids\n` +
-      `\n` +
-      `Usage: kbdb content [options] <id>...\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <id>                kbid or docid identifier\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { type, data, total }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb content abcdef1234567890abcdef1234\n` +
-      `   kbdb content id1 id2\n`,
-
-   check:
-      `kbdb check - Verify knowledge base integrity\n` +
-      `\n` +
-      `Usage: kbdb check [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { ok, errors }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb check\n` +
-      `   kbdb check --db /path/to/project\n`,
-
-   gc:
-      `kbdb gc - Garbage collect unreferenced sections\n` +
-      `\n` +
-      `Usage: kbdb gc [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { removed_sections, removed_bytes }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb gc\n` +
-      `   kbdb gc --db /path/to/project\n`,
-
-   rebuild:
-      `kbdb rebuild - Reconstruct all index files\n` +
-      `\n` +
-      `Usage: kbdb rebuild [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { sections_reindexed, terms_indexed }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb rebuild\n` +
-      `   kbdb rebuild --db /path/to/project\n`,
-
-   status:
-      `kbdb status - Show database status\n` +
-      `\n` +
-      `Usage: kbdb status [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON database status object\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb status\n` +
-      `   kbdb status --db /path/to/project\n`,
-
-   export:
-      `kbdb export - Snapshot database for backup\n` +
-      `\n` +
-      `Usage: kbdb export [options] [<path>]\n` +
-      `\n` +
-      `Arguments:\n` +
-      `   <path>              Output directory path\n` +
-      `                       (default: ./kbdb-export/)\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Output:\n` +
-      `   JSON { path, sections_exported,` +
-      ` documents_exported }\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb export\n` +
-      `   kbdb export ./my-backup\n` +
-      `   kbdb export --db /path/to/project\n`,
-
-   mcp:
-      `kbdb mcp - Start MCP server mode (stdio)\n` +
-      `\n` +
-      `Usage: kbdb mcp [options]\n` +
-      `\n` +
-      `Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `\n` +
-      `Environment:\n` +
-      `   KBDB_DIR            Fallback database path\n` +
-      `\n` +
-      `Examples:\n` +
-      `   kbdb mcp --db /path/to/project\n` +
-      `   KBDB_DIR=/path/to/project kbdb mcp\n`,
-};

package/src/shared/cli/constants/memory-protocol-body.constant.ts

@@ -1,39 +0,0 @@
-/**
- * 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.
- */
-export 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.';

package/src/shared/cli/constants/query-guidance-body.constant.ts

@@ -1,37 +0,0 @@
-/**
- * Body text for the `query-guidance` default skill.
- *
- * Teaches AI agents how to effectively search the knowledge base
- * using lexical BM25F queries.
- */
-export 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.';

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);
-}