@kb-labs/cli-commands 2.93.0 → 2.96.0

package/dist/{discover-D_Is1Qqq.d.ts → discover-DxmYCrcJ.d.ts}

@@ -1,4 +1,6 @@
-import { ManifestV3, PluginContextV3 } from '@kb-labs/plugin-contracts';
+import { ILogger } from '@kb-labs/core-platform';
+import { Command, CommandGroup } from '@kb-labs/shared-command-kit';
+import { ManifestV3 } from '@kb-labs/plugin-contracts';
 
 /**
  * @kb-labs/cli-commands/registry
@@ -7,10 +9,17 @@ import { ManifestV3, PluginContextV3 } from '@kb-labs/plugin-contracts';
 
 interface CommandManifest {
     manifestVersion: '1.0';
+    /** Canonical routing key — full path segments, e.g. ['clickup', 'task', 'search'] */
+    segments: readonly string[];
+    /** Last segment — e.g. 'search' */
     id: string;
-    aliases?: string[];
+    /** First segment — e.g. 'clickup' */
     group: string;
+    /** Second segment when depth >= 3 — e.g. 'task' */
     subgroup?: string;
+    aliases?: string[];
+    category?: string;
+    /** One-line description shown in group help (under 50 chars, no trailing period). */
     describe: string;
     longDescription?: string;
     requires?: string[];
@@ -18,7 +27,6 @@ interface CommandManifest {
     examples?: string[];
     loader?: () => Promise<CommandModule>;
     package?: string;
-    namespace?: string;
     engine?: {
         node?: string;
         kbCli?: string;
@@ -30,6 +38,8 @@ interface CommandManifest {
     pkgRoot?: string;
     /** Internal flag: true for synthetic "unavailable" manifests that must not be cached. */
     _synthetic?: boolean;
+    /** Archetype from manifest — drives automatic flag injection and --schema generation. */
+    operationType?: 'read' | 'mutate' | 'execute' | 'analyze';
 }
 interface FlagDefinition {
     name: string;
@@ -64,8 +74,9 @@ interface DiscoveryResult {
     /**
      * Scope this result came from. Platform-wide discovery (monorepo workspace,
      * platform node_modules) reports `platform`; discovery from
-     * `<projectRoot>/.kb/plugins/` reports `project`. On collision (same
-     * packageName in both scopes) the platform entry wins — see ADR-0012.
+     * `<projectRoot>/.kb/plugins/` or `<projectRoot>` workspace reports `project`.
+     * On collision (same packageName in both scopes) the project entry wins —
+     * project overrides platform defaults.
      */
     scope: 'platform' | 'project';
     packageName: string;
@@ -95,6 +106,7 @@ interface PackageCacheEntry {
 interface CacheFile {
     version: string;
     cliVersion: string;
+    discoveryVersion?: number;
     timestamp: number;
     ttlMs?: number;
     stateHash?: string;
@@ -120,124 +132,136 @@ type AvailabilityCheck = {
 };
 
 /**
- * Legacy V2 types for backward compatibility
- * These types were removed from cli-contracts but are still needed
- * for the adapter layer in service.ts
+ * @kb-labs/cli-commands/registry/trie-router
+ * Path-based trie router for CLI command resolution.
+ *
+ * Replaces the flat-map InMemoryRegistry + backtracking resolveCommand().
+ * Two trie instances: systemTrie (always first) + pluginTrie (plugins).
+ *
+ * Key guarantees:
+ *  - O(depth) resolution — no backtracking
+ *  - No collisions: same last-segment in different paths are distinct nodes
+ *  - "did you mean?" via Levenshtein ≤ 2 + findDeep shorthand detection
+ *  - Tab completion via complete()
  */
 
-interface CommandRun {
-    (ctx: PluginContextV3, argv: string[], flags: Record<string, unknown>): Promise<number | void>;
-}
-interface Command {
-    name: string;
-    category?: string;
-    describe: string;
-    longDescription?: string;
-    aliases?: string[];
-    flags?: FlagDefinition[];
-    examples?: string[];
-    run: CommandRun;
-}
-interface CommandGroup {
-    name: string;
-    describe?: string;
-    commands: Command[];
-    subgroups?: CommandGroup[];
-}
-interface CommandRegistry {
-    register(cmd: Command): void;
-    registerGroup(group: CommandGroup): void;
-    registerManifest(cmd: RegisteredCommand): void;
-    list(): Command[];
-    listGroups(): CommandGroup[];
-    listManifests(): RegisteredCommand[];
-    markPartial(isPartial: boolean): void;
-    isPartial(): boolean;
-}
-
-interface ProductGroup {
-    name: string;
+type RouteResult = {
+    type: 'system-cmd';
+    cmd: Command;
+    rest: string[];
+} | {
+    type: 'system-group';
+    group: CommandGroup;
+    rest: string[];
+} | {
+    type: 'command';
+    command: RegisteredCommand;
+    rest: string[];
+} | {
+    type: 'group';
+    segments: string[];
     describe?: string;
-    commands: RegisteredCommand[];
-}
-type CommandType = 'system' | 'plugin';
-interface CommandLookupResult {
-    cmd: Command | CommandGroup;
-    type: CommandType;
+    childKeys: string[];
+} | {
+    type: 'ambiguous';
+    input: string[];
+    candidates: string[];
+} | {
+    type: 'not-found';
+    input: string[];
+    suggestions: string[];
+};
+interface RegistryDiagnostics {
+    systemCommandCount: number;
+    systemGroupCount: number;
+    pluginCommandCount: number;
+    partialLoad: boolean;
 }
-declare class InMemoryRegistry implements CommandRegistry {
-    private systemCommands;
-    private pluginByCanonical;
-    private pluginAliases;
-    private byName;
-    private groups;
-    private manifests;
-    private partial;
-    register(cmd: Command): void;
-    registerGroup(group: CommandGroup): void;
-    registerManifest(cmd: RegisteredCommand): void;
-    /**
-     * Check whether any system command already owns the canonical id or its parts.
-     * Returns the colliding key if found, null otherwise.
-     */
-    private _findSystemCollision;
+declare function levenshtein(a: string, b: string): number;
+declare class TrieRouter {
+    private readonly root;
     /**
-     * Register all lookup aliases for a plugin command.
+     * Insert a plugin command into the trie.
      *
-     * Priority (what beats what) is handled in resolveToCanonical at query time.
-     * Here we just build the mapping.
+     * Enforces 1-manifest-1-namespace: the first packageName to register any command
+     * under a top-level group becomes the owner. Subsequent packages with a different
+     * packageName are rejected (collides: true) — the caller is responsible for warning
+     * and marking the command as shadowed.
      *
-     * Aliases registered:
-     *   - canonicalId itself        ("marketplace:plugins:list")
-     *   - bare id                   ("list")         ← low priority, may clash
-     *   - 2-part shorthand          ("marketplace:list", "marketplace list")
-     *   - manifest.aliases[]        (user-defined aliases, except collisions)
+     * Returns { collides: false } on success, or { collides: true, ownerPackage } on conflict.
      */
-    private _registerPluginAliases;
+    insertCommand(segments: readonly string[], cmd: RegisteredCommand): {
+        collides: false;
+    } | {
+        collides: true;
+        ownerPackage: string | undefined;
+    };
+    insertSystemCommand(cmd: Command): void;
+    insertSystemGroup(group: CommandGroup): void;
+    getGroupDescribe(segments: string[]): string | undefined;
+    setGroupDescribe(segments: string[], describe: string): void;
+    resolve(tokens: string[]): RouteResult;
+    complete(tokens: string[]): string[];
     /**
-     * Register synthetic subgroups for help display.
+     * List all leaf plugin commands under a given node path.
      */
-    private _registerSyntheticGroups;
+    listUnder(segments: string[]): RegisteredCommand[];
     /**
-     * Resolve any user input to its canonical plugin ID.
-     *
-     * Returns canonicalId if found in plugin aliases, undefined otherwise.
+     * Get exact command at path.
      */
-    private resolveToCanonical;
-    markPartial(partial: boolean): void;
-    isPartial(): boolean;
-    getManifest(id: string): RegisteredCommand | undefined;
-    listManifests(): RegisteredCommand[];
-    has(name: string): boolean;
+    getAt(segments: string[]): RegisteredCommand | null;
     /**
-     * Get command with type information for secure routing.
-     *
-     * System commands ALWAYS win — checked first before any plugin lookup.
-     * Returns type='system' for system commands (in-process execution).
-     * Returns type='plugin' for plugin commands (subprocess execution).
+     * List top-level system groups and standalone system commands (depth=1 nodes).
      */
-    getWithType(nameOrPath: string | string[]): CommandLookupResult | undefined;
-    get(nameOrPath: string | string[]): Command | CommandGroup | undefined;
-    list(): Command[];
-    listGroups(): CommandGroup[];
-    getGroupsByPrefix(prefix: string): CommandGroup[];
-    getCommandsByGroupPrefix(prefix: string): Command[];
-    listProductGroups(): ProductGroup[];
-    getCommandsByGroup(group: string): RegisteredCommand[];
-    getManifestCommand(idOrAlias: string): RegisteredCommand | undefined;
+    listSystemTopLevel(): Array<{
+        name: string;
+        describe: string;
+        isGroup: boolean;
+    }>;
+    /**
+     * Collect all plugin commands reachable from node.
+     */
+    listAll(): RegisteredCommand[];
+    private _collectCommands;
+    private _notFound;
 }
-declare const registry: InMemoryRegistry;
-declare function findCommand(nameOrPath: string | string[]): Command | CommandGroup | undefined;
+
 /**
- * Find command with type information for secure routing.
- *
- * Use this in bootstrap.ts to determine execution path:
- * - type='system' → execute via cmd.run() in-process
- * - type='plugin' → execute via executePlugin() in plugin-executor
+ * @kb-labs/cli-commands/registry/service
+ * TrieBackedRegistry — path-based CLI command registry (ADR-0015, ADR-0018)
  *
- * System commands ALWAYS take priority over plugin commands.
+ * Replaces InMemoryRegistry + all legacy flat-map methods.
+ * System commands (in-process) always take priority over plugin commands.
+ * Plugin namespace ownership: 1 manifest = 1 namespace (ADR-0018).
  */
-declare function findCommandWithType(nameOrPath: string | string[]): CommandLookupResult | undefined;
+
+declare class TrieBackedRegistry {
+    private readonly systemRouter;
+    private readonly pluginRouter;
+    private partial;
+    private logger;
+    setLogger(logger: ILogger): void;
+    register(cmd: Command): void;
+    registerGroup(group: CommandGroup): void;
+    registerManifest(cmd: RegisteredCommand): void;
+    resolve(tokens: string[]): RouteResult;
+    complete(tokens: string[]): string[];
+    listSystemTopLevel(): Array<{
+        name: string;
+        describe: string;
+        isGroup: boolean;
+    }>;
+    getPluginGroupDescribe(segments: string[]): string | undefined;
+    listCommands(): RegisteredCommand[];
+    listCommandsUnder(segments: string[]): RegisteredCommand[];
+    getCommandAt(segments: string[]): RegisteredCommand | null;
+    markPartial(v: boolean): void;
+    isPartial(): boolean;
+    getDiagnostics(): RegistryDiagnostics;
+}
+declare function createRegistry(): TrieBackedRegistry;
+/** Global registry singleton — populated by bootstrap before any command runs. */
+declare const registry: TrieBackedRegistry;
 
 /**
  * @kb-labs/cli-commands/registry
@@ -263,6 +287,14 @@ declare const __test: {
  * in the same process performs a fresh scan rather than serving stale results.
  */
 declare function resetInProcCache(): void;
+/**
+ * Load kb.config.json with plugins allowlist/blocklist
+ */
+declare function loadConfig(cwd: string): Promise<{
+    allow?: string[];
+    block?: string[];
+    linked?: string[];
+}>;
 /**
  * Main discovery function — discovers command manifests from workspace,
  * current package, and `node_modules`.
@@ -287,4 +319,4 @@ declare function discoverManifests(cwd: string, noCache?: boolean, options?: {
  */
 declare function discoverManifestsByNamespace(cwd: string, namespace: string, noCache?: boolean): Promise<DiscoveryResult[]>;
 
-export { type AvailabilityCheck as A, type CommandGroup as C, type DiscoveryResult as D, type FlagDefinition as F, type GlobalFlags as G, type ProductGroup as P, type RegisteredCommand as R, __test as _, type Command as a, type CacheFile as b, type CommandLookupResult as c, type CommandManifest as d, type CommandModule as e, type CommandType as f, type PackageCacheEntry as g, discoverManifests as h, discoverManifestsByNamespace as i, findCommand as j, findCommandWithType as k, type CommandRegistry as l, resetInProcCache as m, registry as r };
+export { type AvailabilityCheck as A, type CommandManifest as C, type DiscoveryResult as D, type FlagDefinition as F, type GlobalFlags as G, type PackageCacheEntry as P, type RegisteredCommand as R, TrieBackedRegistry as T, __test as _, type CacheFile as a, type CommandModule as b, type RegistryDiagnostics as c, type RouteResult as d, createRegistry as e, discoverManifests as f, discoverManifestsByNamespace as g, TrieRouter as h, loadConfig as i, resetInProcCache as j, levenshtein as l, registry as r };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { C as CommandGroup, P as ProductGroup, a as Command, R as RegisteredCommand } from './discover-D_Is1Qqq.js';
-export { A as AvailabilityCheck, b as CacheFile, c as CommandLookupResult, d as CommandManifest, e as CommandModule, f as CommandType, D as DiscoveryResult, F as FlagDefinition, G as GlobalFlags, g as PackageCacheEntry, h as discoverManifests, i as discoverManifestsByNamespace, j as findCommand, k as findCommandWithType, r as registry } from './discover-D_Is1Qqq.js';
+import { R as RegisteredCommand, T as TrieBackedRegistry, C as CommandManifest } from './discover-DxmYCrcJ.js';
+export { A as AvailabilityCheck, a as CacheFile, b as CommandModule, D as DiscoveryResult, F as FlagDefinition, G as GlobalFlags, P as PackageCacheEntry, c as RegistryDiagnostics, d as RouteResult, e as createRegistry, f as discoverManifests, g as discoverManifestsByNamespace, r as registry } from './discover-DxmYCrcJ.js';
 import { ILogger } from '@kb-labs/core-platform';
 export { TimingTracker } from '@kb-labs/shared-cli-ui';
 import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+export { Command as SystemCommand, CommandGroup as SystemGroup } from '@kb-labs/shared-command-kit';
 import '@kb-labs/plugin-contracts';
 
 interface RegisterBuiltinCommandsInput {
@@ -27,17 +28,19 @@ interface RegisterBuiltinCommandsInput {
 }
 declare function registerBuiltinCommands(input?: RegisterBuiltinCommandsInput): Promise<void>;
 
-declare function renderGroupHelp(group: CommandGroup): string;
+interface GroupHelpOptions {
+    /** Full path of the group (e.g. ['marketplace', 'plugins']) */
+    segments: string[];
+    describe?: string;
+    /** Direct child key names shown in group listing */
+    childKeys: string[];
+    /** Full plugin commands available under this path (for detailed listing) */
+    commands?: RegisteredCommand[];
+}
+declare function renderGroupHelp(opts: GroupHelpOptions): string;
 
-declare function renderGlobalHelp(groups: ProductGroup[], standalone: Command[]): string;
-declare function renderGlobalHelpNew(registry: {
-    listProductGroups(): ProductGroup[];
-    list(): Command[];
-    listGroups?(): CommandGroup[];
-}): string;
-declare function renderPluginsHelp(registry: {
-    list(): Command[];
-}): string;
+declare function renderGlobalHelp(registry: TrieBackedRegistry): string;
+declare function renderPluginsHelp(registry: TrieBackedRegistry): string;
 
 declare function renderProductHelp(groupName: string, commands: RegisteredCommand[]): string;
 
@@ -50,6 +53,12 @@ interface RenderHelpOptions {
 }
 declare function renderHelp(commands: RegisteredCommand[], options: RenderHelpOptions): string | Record<string, unknown>;
 
+/**
+ * Generates a JSON Schema object from a CommandManifest.
+ * Used by the --schema flag interception in bootstrap.
+ */
+declare function generateCommandSchema(manifest: CommandManifest): object;
+
 /**
  * Generate command examples
  * Simple helper to format command examples for CLI commands
@@ -66,6 +75,8 @@ declare const health: _kb_labs_shared_command_kit.Command;
 
 declare const version: _kb_labs_shared_command_kit.Command;
 
+declare function createCompletionCommand(registry: TrieBackedRegistry): _kb_labs_shared_command_kit.Command;
+
 /**
  * logs diagnose — "What went wrong?" Automated error analysis.
  * Agent-first command: single call gives a full diagnostic report.
@@ -104,4 +115,4 @@ declare const logsGet: _kb_labs_shared_command_kit.Command;
  */
 declare const logsStats: _kb_labs_shared_command_kit.Command;
 
-export { type ExampleCase, ProductGroup, RegisteredCommand, generateExamples, health, hello, logsContext, logsDiagnose, logsGet, logsQuery, logsSearch, logsStats, logsSummarize, registerBuiltinCommands, renderGlobalHelp, renderGlobalHelpNew, renderGroupHelp, renderHelp, renderManifestCommandHelp, renderPluginsHelp, renderProductHelp, version };
+export { CommandManifest, type ExampleCase, RegisteredCommand, TrieBackedRegistry, createCompletionCommand, generateCommandSchema, generateExamples, health, hello, logsContext, logsDiagnose, logsGet, logsQuery, logsSearch, logsStats, logsSummarize, registerBuiltinCommands, renderGlobalHelp, renderGroupHelp, renderHelp, renderManifestCommandHelp, renderPluginsHelp, renderProductHelp, version };