@dikolab/kbdb 0.3.2 → 0.4.0

package/src/shared/cli/functions/generate-help.function.ts

@@ -1,654 +0,0 @@
-import { VERSION } from '../../version/index.ts';
-
-/**
- * The set of all recognised top-level command names,
- * including group commands (`db`, `skill`, `agent`).
- */
-const KNOWN_COMMANDS = new Set([
-   'learn',
-   'unlearn',
-   'search',
-   'recall',
-   'content',
-   'check',
-   'gc',
-   'rebuild',
-   'status',
-   'export',
-   'mcp',
-   'db',
-   'skill',
-   'agent',
-]);
-
-/** Subcommands available under each group command. */
-const GROUP_SUBCOMMANDS: Readonly<
-   Record<string, readonly (readonly [string, string])[]>
-> = {
-   db: [
-      ['init', 'Initialise a new .kbdb directory'],
-      ['migrate', 'Migrate database to current format'],
-   ],
-   skill: [
-      ['learn', 'Create a new skill definition'],
-      ['list', 'List all skills'],
-      ['get', 'Retrieve a skill by name or kbid'],
-      ['delete', 'Remove a skill'],
-   ],
-   agent: [
-      ['create', 'Create an agent with skill refs'],
-      ['list', 'List all agents'],
-      ['get', 'Retrieve an agent by docid'],
-      ['delete', 'Remove an agent'],
-   ],
-};
-
-/**
- * Returns `true` when `cmd` is a recognised command name.
- *
- * Accepts both simple top-level names (`'learn'`, `'db'`)
- * and the hyphenated compound form produced by `parseArgs`
- * when a group + subcommand precedes `--help`
- * (e.g. `'db-init'`, `'skill-learn'`).
- */
-export function isKnownCommand(cmd: string): boolean {
-   if (KNOWN_COMMANDS.has(cmd)) {
-      return true;
-   }
-   // Check hyphenated compound form: 'db-init', 'skill-learn'
-   const dashIdx = cmd.indexOf('-');
-   if (dashIdx < 0) {
-      return false;
-   }
-   const group = cmd.slice(0, dashIdx);
-   return group in GROUP_SUBCOMMANDS;
-}
-
-/**
- * Generates contextual help text for the `kbdb` CLI.
- *
- * Three levels of detail are produced depending on
- * how many command tokens are supplied:
- *
- * - No arguments: global help listing all commands.
- * - `command` only: command-level help. When `command`
- *   is a hyphenated compound (`'db-init'`), it is split
- *   into group + subcommand automatically.  Group
- *   commands show a subcommand listing; leaf commands
- *   show detailed help; unknown commands show an error
- *   prefix followed by global help.
- * - `command` + `subcommand`: detailed help for that
- *   specific subcommand (falls back to group help when
- *   the subcommand is not recognised).
- *
- * @param command - optional top-level command token,
- *   or a hyphenated compound such as `'db-init'`
- * @param subcommand - optional subcommand token
- */
-export function generateHelp(
-   command?: string,
-   subcommand?: string,
-): string {
-   if (!command) {
-      return generateGlobalHelp();
-   }
-   // Handle compound form produced by parseArgs:
-   // 'db-init' -> group='db', sub='init'
-   if (!subcommand && command.includes('-')) {
-      const dashIdx = command.indexOf('-');
-      const group = command.slice(0, dashIdx);
-      const sub = command.slice(dashIdx + 1);
-      if (group in GROUP_SUBCOMMANDS) {
-         return generateSubcommandHelp(group, sub);
-      }
-   }
-   if (subcommand) {
-      return generateSubcommandHelp(command, subcommand);
-   }
-   return generateCommandHelp(command);
-}
-
-// ---------------------------------------------------------------------------
-// Level 1: Global help
-// ---------------------------------------------------------------------------
-
-function generateGlobalHelp(): string {
-   return (
-      `kbdb v${VERSION} - File-based knowledge base` +
-      ` database for AI agents\n` +
-      `\n` +
-      `Usage: kbdb [options]\n` +
-      `       kbdb <command> [options] ...[parameters]\n` +
-      `       kbdb <command> <subcommand> [options]` +
-      ` ...[params]\n` +
-      `\n` +
-      `Knowledge Base:\n` +
-      `   learn               Import content from` +
-      ` files/stdin\n` +
-      `   unlearn             Remove sections by kbid\n` +
-      `   search              Query the knowledge base\n` +
-      `   recall              Retrieve section context` +
-      ` by kbid\n` +
-      `   content             Compose rendered content` +
-      ` from ids\n` +
-      `\n` +
-      `Database:\n` +
-      `   db init             Initialise a new .kbdb` +
-      ` directory\n` +
-      `   db migrate          Migrate database to current` +
-      ` format\n` +
-      `\n` +
-      `Maintenance:\n` +
-      `   check               Verify knowledge base` +
-      ` integrity\n` +
-      `   gc                  Garbage collect unreferenced\n` +
-      `                       sections\n` +
-      `   rebuild             Reconstruct all index` +
-      ` files\n` +
-      `   status              Show database status\n` +
-      `   export              Snapshot database for` +
-      ` backup\n` +
-      `\n` +
-      `Skills:\n` +
-      `   skill learn         Create a new skill` +
-      ` definition\n` +
-      `   skill list          List all skills\n` +
-      `   skill get           Retrieve a skill by name` +
-      ` or kbid\n` +
-      `   skill delete        Remove a skill\n` +
-      `\n` +
-      `Agents:\n` +
-      `   agent create        Create an agent with skill` +
-      ` refs\n` +
-      `   agent list          List all agents\n` +
-      `   agent get           Retrieve an agent by docid\n` +
-      `   agent delete        Remove an agent\n` +
-      `\n` +
-      `Server:\n` +
-      `   mcp                 Start MCP server mode` +
-      ` (stdio)\n` +
-      `\n` +
-      `Global Options:\n` +
-      `   -h, --help          Show this help message\n` +
-      `   -v, --version       Show version information\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `   --format <fmt>      Output format` +
-      ` (json|text|mcp)\n` +
-      `\n` +
-      `Run "kbdb <command> --help" for detailed` +
-      ` information.\n`
-   );
-}
-
-// ---------------------------------------------------------------------------
-// Level 2: Command help
-// ---------------------------------------------------------------------------
-
-function generateCommandHelp(command: string): string {
-   if (command in GROUP_SUBCOMMANDS) {
-      return generateGroupHelp(command);
-   }
-   const leaf = LEAF_HELP[command];
-   if (leaf) {
-      return leaf;
-   }
-   return `Unknown command: ${command}\n\n` + generateGlobalHelp();
-}
-
-function generateGroupHelp(group: string): string {
-   const subs = GROUP_SUBCOMMANDS[group] ?? [];
-   const subLines = subs
-      .map(([name, desc]) => `   ${name.padEnd(20)}${desc}`)
-      .join('\n');
-   const desc = GROUP_DESCRIPTIONS[group] ?? group;
-   return (
-      `kbdb ${group} - ${desc}\n` +
-      `\n` +
-      `Usage: kbdb ${group} <subcommand> [options]\n` +
-      `\n` +
-      `Subcommands:\n` +
-      `${subLines}\n` +
-      `\n` +
-      `Global Options:\n` +
-      `   --db <path>         Path to .kbdb directory\n` +
-      `   -h, --help          Show this help message\n` +
-      `\n` +
-      `Run "kbdb ${group} <subcommand> --help"` +
-      ` for details.\n`
-   );
-}
-
-/** One-line description for each group command. */
-const GROUP_DESCRIPTIONS: Readonly<Record<string, string>> = {
-   db: 'Database management',
-   skill: 'Skill management',
-   agent: 'Agent management',
-};
-
-// ---------------------------------------------------------------------------
-// Leaf command help texts
-// ---------------------------------------------------------------------------
-
-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`,
-};
-
-// ---------------------------------------------------------------------------
-// Level 3: Subcommand help
-// ---------------------------------------------------------------------------
-
-/**
- * Detailed help texts keyed by `"group-subcommand"`.
- * Falls back to group help when the key is absent.
- */
-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`,
-};
-
-function generateSubcommandHelp(
-   command: string,
-   subcommand: string,
-): string {
-   const key = `${command}-${subcommand}`;
-   const text = SUBCOMMAND_HELP[key];
-   if (text) {
-      return text;
-   }
-   // Fall back to group help when subcommand is unknown
-   return generateCommandHelp(command);
-}