@kb-labs/cli-commands 1.0.0

package/README.md

@@ -0,0 +1,253 @@
+# @kb-labs/cli-commands
+
+> **Command implementations for KB Labs CLI.** Contains command implementations and registry system for KB Labs CLI with plugin-based architecture, command discovery, execution, and help generation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18.18.0+-green.svg)](https://nodejs.org/)
+[![pnpm](https://img.shields.io/badge/pnpm-9.0.0+-orange.svg)](https://pnpm.io/)
+
+## 🎯 Vision & Purpose
+
+**@kb-labs/cli-commands** provides command implementations and registry system for KB Labs CLI. It includes plugin-based command architecture, command discovery, execution, help generation, and built-in system commands.
+
+## 🏗️ Architecture
+
+### Core Components
+
+#### Command Registry
+
+- **Purpose**: Discover and register commands
+- **Responsibilities**: Plugin discovery, manifest validation, command registration
+- **Dependencies**: cli-core, plugin-manifest
+
+#### Command Execution
+
+- **Purpose**: Execute commands
+- **Responsibilities**: Command routing, handler execution, error handling
+- **Dependencies**: Registry, cli-core
+
+#### Help Generation
+
+- **Purpose**: Generate help output
+- **Responsibilities**: Global help, group help, manifest help
+- **Dependencies**: Registry
+
+### Design Patterns
+
+- **Registry Pattern**: Command registry
+- **Plugin Pattern**: Plugin-based commands
+- **Strategy Pattern**: Multiple discovery strategies
+- **Command Pattern**: Command execution
+
+### Data Flow
+
+```
+CLI Entry Point
+    │
+    ├──► Discover plugins
+    ├──► Register commands
+    ├──► Parse arguments
+    ├──► Find command
+    ├──► Execute command
+    └──► Return result
+```
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pnpm add @kb-labs/cli-commands
+```
+
+### Basic Usage
+
+```typescript
+import { discoverManifests, registerCommands } from '@kb-labs/cli-commands';
+
+const manifests = await discoverManifests(process.cwd());
+const registry = await registerCommands(manifests);
+```
+
+## ✨ Features
+
+```
+kb-labs-cli/packages/commands/src/
+├── registry/           # Plugin discovery and registration
+│   ├── types.ts       # All interfaces
+│   ├── availability.ts # ESM-safe dependency resolution
+│   ├── discover.ts    # Workspace + node_modules discovery
+│   ├── register.ts    # Manifest validation and shadowing
+│   ├── run.ts         # Command execution
+│   └── __tests__/     # Comprehensive test suite
+├── builtins/          # Built-in commands (legacy)
+└── utils/             # Utilities (logger, path helpers)
+```
+
+### Plugin Manifest v2
+
+Commands ship as part of plugin manifests declared via ManifestV2:
+
+```typescript
+// packages/my-plugin/src/kb/manifest.ts
+import type { ManifestV2 } from '@kb-labs/plugin-manifest';
+
+export const manifest: ManifestV2 = {
+  schema: 'kb.plugin/2',
+  id: '@kb-labs/my-plugin',
+  version: '0.1.0',
+  display: {
+    name: 'My Plugin',
+    description: 'Example plugin command set',
+  },
+  permissions: {
+    fs: { mode: 'read', allow: ['.'] },
+  },
+  cli: {
+    commands: [
+      {
+        id: 'my:command',
+        group: 'my',
+        describe: 'My command description',
+        handler: './commands/command#run',
+        flags: [],
+      },
+    ],
+  },
+};
+```
+
+The CLI registry converts these declarations into internal command manifests during discovery.
+
+### Package.json Configuration
+
+```json
+{
+  "name": "@kb-labs/my-plugin",
+  "exports": {
+    "./kb/manifest": "./dist/kb/manifest.js"
+  },
+  "kb": {
+    "plugin": true,
+    "manifest": "./dist/kb/manifest.js"
+  }
+}
+```
+
+## Global Flags
+
+All commands receive these global flags regardless of their own flag definitions:
+
+- `--json` - JSON output mode
+- `--only-available` - Filter unavailable commands (help only)
+- `--no-cache` - Force discovery refresh
+- `--verbose` - Detailed output
+- `--quiet` - Minimal output
+- `--help` - Show help
+- `--version` - Show version
+
+These flags are guaranteed to be passed through to all commands.
+
+## Exit Codes
+
+- **0** - Success
+- **1** - Command error / invalid module
+- **2** - Command unavailable (missing dependencies)
+
+In `--json` mode with exit code 2:
+```json
+{
+  "ok": false,
+  "available": false,
+  "command": "my:command",
+  "reason": "Missing dependency: @kb-labs/some-dependency",
+  "hint": "Run: kb devlink apply"
+}
+```
+
+## Logging
+
+The CLI respects the `KB_LOG_LEVEL` environment variable:
+
+- `silent` - No output
+- `error` - Error messages only
+- `warn` - Warnings and errors (default)
+- `info` - Informational messages
+- `debug` - Debug information
+
+All diagnostic output goes to `stderr`, leaving `stdout` free for command output.
+
+## Discovery Process
+
+1. **Workspace Discovery**: Scans `pnpm-workspace.yaml` for packages exposing `./kb/manifest` via exports or `kb.manifest`.
+2. **Node Modules Discovery**: Looks through installed packages for ManifestV2 files.
+3. **Explicit Paths**: Follows linked directories and CLI-provided manifest paths.
+4. **Shadowing**: Workspace packages shadow node_modules packages.
+5. **Caching**: Results are cached in memory (and optional adapters) for fast startup.
+
+## Command Execution
+
+Commands execute inside the plugin sandbox:
+
+1. Validate ManifestV2 metadata and permissions.
+2. Check availability and granted permissions.
+3. Execute via `@kb-labs/plugin-adapter-cli` (sandbox runtime).
+4. Record telemetry and return the exit code.
+
+## Diagnostics
+
+Use `kb plugins list` to see all discovered commands with their status:
+
+- Available/unavailable status
+- Source (workspace/node_modules/builtin)
+- Shadowing information
+- Missing dependency reasons and hints
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test
+```
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Adding New Commands
+
+1. Run `kb plugins scaffold my-plugin` to generate a manifest v2 skeleton.
+2. Implement your command handler in `src/commands/<name>.ts`.
+3. Update manifest permissions and metadata as needed.
+4. Build your package and test with `kb plugins list`.
+
+## Migration from Legacy Commands
+
+Legacy command groups are being converted to manifest format:
+
+1. **Built-in Commands**: Converted to manifest format in `builtins/`
+2. **Product Commands**: Moved to their respective packages
+3. **System Commands**: Available as standalone commands
+
+The registry system maintains backward compatibility during the transition.
+
+## 🔧 Configuration
+
+### Configuration Options
+
+No global configuration needed. Commands are discovered automatically.
+
+### Environment Variables
+
+- `KB_LOG_LEVEL`: Logging level (`silent`, `error`, `warn`, `info`, `debug`)
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+KB Public License v1.1 © KB Labs

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+import { ManifestV3 } from '@kb-labs/plugin-contracts';
+import { Logger } from '@kb-labs/cli-core';
+export { TimingTracker } from '@kb-labs/shared-cli-ui';
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * @kb-labs/cli-commands/registry
+ * Type definitions for the plugin system
+ */
+
+interface CommandManifest {
+    manifestVersion: '1.0';
+    id: string;
+    aliases?: string[];
+    group: string;
+    describe: string;
+    longDescription?: string;
+    requires?: string[];
+    flags?: FlagDefinition[];
+    examples?: string[];
+    loader?: () => Promise<CommandModule>;
+    package?: string;
+    namespace?: string;
+    engine?: {
+        node?: string;
+        kbCli?: string;
+        module?: 'esm' | 'cjs';
+    };
+    permissions?: string[];
+    telemetry?: 'opt-in' | 'off';
+    manifestV2?: ManifestV3;
+}
+interface FlagDefinition {
+    name: string;
+    type: "string" | "boolean" | "number" | "array";
+    alias?: string;
+    default?: any;
+    description?: string;
+    describe?: string;
+    choices?: string[];
+    required?: boolean;
+    examples?: string[];
+}
+interface RegisteredCommand {
+    manifest: CommandManifest;
+    v3Manifest?: ManifestV3;
+    available: boolean;
+    unavailableReason?: string;
+    hint?: string;
+    source: 'workspace' | 'node_modules' | 'linked' | 'builtin';
+    shadowed: boolean;
+    pkgRoot?: string;
+    packageName?: string;
+}
+interface CommandModule {
+    run: (ctx: any, argv: string[], flags: Record<string, any>) => Promise<number | void>;
+}
+interface DiscoveryResult {
+    source: 'workspace' | 'node_modules' | 'linked' | 'builtin';
+    packageName: string;
+    manifestPath: string;
+    pkgRoot: string;
+    manifests: CommandManifest[];
+}
+interface GlobalFlags {
+    json?: boolean;
+    onlyAvailable?: boolean;
+    noCache?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+    help?: boolean;
+    version?: boolean;
+    dryRun?: boolean;
+}
+interface PackageCacheEntry {
+    version: string;
+    manifestHash: string;
+    manifestPath: string;
+    pkgJsonMtime: number;
+    manifestMtime: number;
+    cachedAt: number;
+    result: DiscoveryResult;
+}
+interface CacheFile {
+    version: string;
+    cliVersion: string;
+    timestamp: number;
+    ttlMs?: number;
+    stateHash?: string;
+    lockfileHash?: string;
+    configHash?: string;
+    pluginsStateHash?: string;
+    packages: Record<string, PackageCacheEntry>;
+}
+type AvailabilityCheck = {
+    available: true;
+} | {
+    available: false;
+    reason: string;
+    hint?: string;
+};
+
+/**
+ * Legacy V2 types for backward compatibility
+ * These types were removed from cli-contracts but are still needed
+ * for the adapter layer in service.ts
+ */
+
+interface CommandRun {
+    (ctx: any, argv: string[], flags: Record<string, any>): 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[];
+}
+interface CommandRegistry {
+    register(cmd: Command): void;
+    registerGroup(group: CommandGroup): void;
+    registerManifest(cmd: any): void;
+    list(): Command[];
+    listGroups(): CommandGroup[];
+    listManifests(): any[];
+    markPartial(isPartial: boolean): void;
+    isPartial(): boolean;
+}
+
+interface ProductGroup {
+    name: string;
+    describe?: string;
+    commands: RegisteredCommand[];
+}
+type CommandType = 'system' | 'plugin';
+interface CommandLookupResult {
+    cmd: Command | CommandGroup;
+    type: CommandType;
+}
+declare class InMemoryRegistry implements CommandRegistry {
+    private systemCommands;
+    private pluginCommands;
+    private byName;
+    private groups;
+    private manifests;
+    private partial;
+    register(cmd: Command): void;
+    registerGroup(group: CommandGroup): void;
+    registerManifest(cmd: RegisteredCommand): void;
+    markPartial(partial: boolean): void;
+    isPartial(): boolean;
+    getManifest(id: string): RegisteredCommand | undefined;
+    listManifests(): RegisteredCommand[];
+    has(name: string): boolean;
+    /**
+     * Get command with type information for secure routing
+     *
+     * Returns type='system' for commands from registerGroup() - execute in-process
+     * Returns type='plugin' for commands from registerManifest() - execute in subprocess
+     *
+     * This separation prevents malicious plugins from escaping the sandbox.
+     */
+    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;
+}
+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 tryExecuteV3() in subprocess
+ */
+declare function findCommandWithType(nameOrPath: string | string[]): CommandLookupResult | undefined;
+
+interface RegisterBuiltinCommandsInput {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    logger?: Logger;
+}
+declare function registerBuiltinCommands(input?: RegisterBuiltinCommandsInput): Promise<void>;
+
+declare function renderGroupHelp(group: CommandGroup): 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 renderProductHelp(groupName: string, commands: RegisteredCommand[]): string;
+
+declare function renderManifestCommandHelp(registered: RegisteredCommand): string;
+
+interface RenderHelpOptions {
+    json: boolean;
+    onlyAvailable: boolean;
+    version?: string;
+}
+declare function renderHelp(commands: RegisteredCommand[], options: RenderHelpOptions): string | Record<string, unknown>;
+
+/**
+ * Generate command examples
+ * Simple helper to format command examples for CLI commands
+ */
+interface ExampleCase {
+    flags: Record<string, unknown>;
+    description?: string;
+}
+declare function generateExamples(commandName: string, productName: string, cases: ExampleCase[]): string[];
+
+/**
+ * @kb-labs/cli-commands/registry
+ * Command manifest discovery - workspace, node_modules, current package
+ */
+
+/**
+ * Main discovery function
+ * Discovers command manifests from workspace, current package, and node_modules
+ */
+declare function discoverManifests(cwd: string, noCache?: boolean): Promise<DiscoveryResult[]>;
+/**
+ * Lazy load manifests for a specific namespace
+ * Only loads manifests from packages matching the namespace
+ */
+declare function discoverManifestsByNamespace(cwd: string, namespace: string, noCache?: boolean): Promise<DiscoveryResult[]>;
+
+declare const hello: _kb_labs_shared_command_kit.Command;
+
+declare const health: _kb_labs_shared_command_kit.Command;
+
+declare const version: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs diagnose — "What went wrong?" Automated error analysis.
+ * Agent-first command: single call gives a full diagnostic report.
+ */
+declare const logsDiagnose: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs context — Show full timeline for an execution/trace/request.
+ * Agent-first: "What happened in this workflow run?"
+ */
+declare const logsContext: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs summarize — AI-powered log analysis.
+ * Agent-first: ask a natural-language question about logs.
+ */
+declare const logsSummarize: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs query — Query logs with filters and pagination
+ */
+declare const logsQuery: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs search — Full-text search across logs (FTS5)
+ */
+declare const logsSearch: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs get — Get single log by ID with optional related logs
+ */
+declare const logsGet: _kb_labs_shared_command_kit.Command;
+
+/**
+ * logs stats — Show log storage statistics and capabilities
+ */
+declare const logsStats: _kb_labs_shared_command_kit.Command;
+
+export { type AvailabilityCheck, type CacheFile, type CommandLookupResult, type CommandManifest, type CommandModule, type CommandType, type DiscoveryResult, type ExampleCase, type FlagDefinition, type GlobalFlags, type PackageCacheEntry, type ProductGroup, type RegisteredCommand, discoverManifests, discoverManifestsByNamespace, findCommand, findCommandWithType, generateExamples, health, hello, logsContext, logsDiagnose, logsGet, logsQuery, logsSearch, logsStats, logsSummarize, registerBuiltinCommands, registry, renderGlobalHelp, renderGlobalHelpNew, renderGroupHelp, renderHelp, renderManifestCommandHelp, renderPluginsHelp, renderProductHelp, version };