@kb-labs/shared-cli-ui 1.0.0

package/README.md

@@ -0,0 +1,342 @@
+# @kb-labs/shared-cli-ui
+
+> **Shared CLI UI utilities for KB Labs projects - colors, formatting, progress indicators.** Provides command suggestions, validation, multi-CLI support, formatting utilities, and consistent UX components for CLI applications.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-20.0.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/shared-cli-ui** provides shared CLI UI utilities for KB Labs ecosystem. It includes command suggestions, validation, multi-CLI support, formatting utilities, colors, progress indicators, and consistent UX components for all CLI applications.
+
+### What Problem Does This Solve?
+
+- **CLI UX Consistency**: CLI tools need consistent UI - cli-ui provides shared components
+- **Command Discovery**: Need to discover and suggest commands - cli-ui provides discovery utilities
+- **Formatting**: Need consistent output formatting - cli-ui provides formatting utilities
+- **Multi-CLI Support**: Need to manage multiple CLI packages - cli-ui provides multi-CLI manager
+
+### Why Does This Package Exist?
+
+- **Unified CLI UX**: All KB Labs CLI tools use the same UI components
+- **Code Reuse**: Avoid duplicating CLI UI code
+- **Consistency**: Ensure consistent user experience across CLI tools
+- **Developer Experience**: Easy-to-use utilities for CLI development
+
+### What Makes This Package Unique?
+
+- **Comprehensive Utilities**: Wide range of CLI UI utilities
+- **Multi-CLI Support**: Manage suggestions across multiple CLI packages
+- **Command Discovery**: Automatic command discovery from manifests
+- **Formatting**: Rich formatting utilities (tables, boxes, colors)
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pnpm add @kb-labs/shared-cli-ui
+```
+
+### Basic Usage
+
+```typescript
+import { box, table, keyValue } from '@kb-labs/shared-cli-ui';
+
+const output = box('Title', ['Line 1', 'Line 2']);
+const tableOutput = table([['A', 'B'], ['1', '2']], ['Col1', 'Col2']);
+const kvOutput = keyValue({ key: 'value' });
+```
+
+## ✨ Features
+
+- **Command Suggestions**: Generate contextual suggestions for CLI commands
+- **Command Validation**: Check if commands are available before suggesting them
+- **Multi-CLI Support**: Manage suggestions across multiple CLI packages
+- **Manifest Parsing**: Extract command information from CLI manifests
+- **Consistent UX**: Shared UI components and styling
+
+## Command Suggestions
+
+### Basic Usage
+
+```typescript
+import { 
+  createCommandRegistry, 
+  generateDevlinkSuggestions 
+} from '@kb-labs/shared-cli-ui';
+
+// Create a registry of available commands
+const registry = createCommandRegistry([
+  'devlink:apply',
+  'devlink:clean',
+  'devlink:plan'
+]);
+
+// Generate suggestions based on warnings
+const suggestions = generateDevlinkSuggestions(
+  new Set(['LOCK_MISMATCH']),
+  { undo: { available: true } },
+  registry
+);
+```
+
+### Multi-CLI Integration
+
+```typescript
+import { MultiCLISuggestions } from '@kb-labs/shared-cli-ui';
+
+// Create a multi-CLI manager
+const manager = new MultiCLISuggestions();
+
+// Register your CLI package
+manager.registerPackage({
+  name: 'my-cli',
+  group: 'my-cli',
+  commands: myCommands,
+  priority: 80
+});
+
+// Generate suggestions from all registered packages
+const suggestions = manager.generateAllSuggestions({
+  warningCodes: new Set(['MY_WARNING']),
+  undo: { available: true }
+});
+```
+
+## Integration Guide
+
+### 1. Create CLI Suggestions Module
+
+Create a `cli-suggestions.ts` file in your CLI package:
+
+```typescript
+import { 
+  MultiCLISuggestions, 
+  type CommandSuggestion 
+} from '@kb-labs/shared-cli-ui';
+import { commands } from './cli.manifest.js';
+
+export function generateMyCLISuggestions(
+  warningCodes: Set<string>,
+  context: any
+): CommandSuggestion[] {
+  const suggestions: CommandSuggestion[] = [];
+
+  if (warningCodes.has('MY_WARNING')) {
+    suggestions.push({
+      id: 'MY_COMMAND',
+      command: 'kb my-cli command',
+      args: [],
+      description: 'Execute my command',
+      impact: 'safe',
+      when: 'MY_WARNING',
+      available: true
+    });
+  }
+
+  return suggestions;
+}
+
+export function createMyCLISuggestions(): MultiCLISuggestions {
+  const manager = new MultiCLISuggestions();
+  
+  manager.registerPackage({
+    name: 'my-cli',
+    group: 'my-cli',
+    commands,
+    priority: 80
+  });
+
+  return manager;
+}
+```
+
+### 2. Register with Main CLI
+
+In your main CLI (e.g., devlink), register the package:
+
+```typescript
+import { MultiCLISuggestions } from '@kb-labs/shared-cli-ui';
+import { createMyCLISuggestions } from '@kb-labs/my-cli/cli-suggestions';
+
+const multiCLI = new MultiCLISuggestions();
+
+// Register all CLI packages
+multiCLI.registerPackage(devlinkPackage);
+multiCLI.registerPackage(myCLIPackage);
+
+// Generate suggestions
+const suggestions = multiCLI.generateAllSuggestions(context);
+```
+
+### 3. Command Priority
+
+Set priority for your CLI package:
+- **100**: Core tools (devlink)
+- **80**: Important tools (mind)
+- **70**: Utility tools (tox)
+- **50**: Optional tools (ai-review)
+
+## API Reference
+
+### CommandSuggestion
+
+```typescript
+interface CommandSuggestion {
+  id: string;
+  command: string;
+  args: string[];
+  description: string;
+  impact: 'safe' | 'disruptive';
+  when: string;
+  available?: boolean;
+}
+```
+
+### MultiCLISuggestions
+
+```typescript
+class MultiCLISuggestions {
+  registerPackage(pkg: CLIPackage): void;
+  generateAllSuggestions(context: MultiCLIContext): CommandSuggestion[];
+  generateGroupSuggestions(group: string, context: MultiCLIContext): CommandSuggestion[];
+  getAvailableCommands(group: string): string[];
+}
+```
+
+### Command Registry
+
+```typescript
+function createCommandRegistry(commands: string[]): CommandRegistry;
+function isCommandAvailable(command: string, registry: CommandRegistry): boolean;
+function validateSuggestions(suggestions: CommandSuggestion[], registry: CommandRegistry): CommandSuggestion[];
+```
+
+## Artifacts Display
+
+The artifacts display system provides consistent, beautiful display of generated files and artifacts across all CLI commands.
+
+### Features
+
+- **Consistent Formatting**: Unified display format across all CLI packages
+- **Multiple Display Modes**: Compact, detailed, and grouped views
+- **Smart Sorting**: By time (newest first) by default, with type and custom options
+- **Size & Time Info**: Human-readable file sizes and relative timestamps
+- **Path Normalization**: Shows relative paths for better readability
+- **Federal Sorting**: All CLI packages automatically get time-based sorting
+
+### Usage
+
+```typescript
+import { 
+  displayArtifacts,
+  displayArtifactsCompact,
+  displaySingleArtifact,
+  type ArtifactInfo 
+} from '@kb-labs/shared-cli-ui';
+
+// Define artifacts
+const artifacts: ArtifactInfo[] = [
+  {
+    name: 'Plan',
+    path: '/path/to/.kb/devlink/last-plan.json',
+    size: 1024,
+    modified: new Date(),
+    description: 'Last generated plan'
+  },
+  {
+    name: 'Lock',
+    path: '/path/to/.kb/devlink/lock.json',
+    size: 2048,
+    modified: new Date(Date.now() - 3600000),
+    description: 'Dependency lock file'
+  }
+];
+
+// Display in compact format (for status-like displays)
+const compactDisplay = displayArtifactsCompact(artifacts, { 
+  maxItems: 5,
+  showSize: true 
+});
+
+// Display with full details
+const fullDisplay = displayArtifacts(artifacts, {
+  showSize: true,
+  showTime: true,
+  showDescription: true,
+  maxItems: 10,
+  title: 'Generated Files',
+  groupBy: 'type'
+});
+
+// Display single artifact
+const singleDisplay = displaySingleArtifact(artifacts[0], 'Latest Artifact');
+```
+
+### Display Options
+
+```typescript
+interface ArtifactDisplayOptions {
+  showSize?: boolean;        // Show file sizes (default: true)
+  showTime?: boolean;        // Show modification times (default: true)
+  showDescription?: boolean; // Show descriptions (default: false)
+  maxItems?: number;         // Maximum items to show (default: 10)
+  title?: string;            // Section title (default: 'Generated Artifacts')
+  groupBy?: 'none' | 'type' | 'time'; // Grouping strategy (default: 'none')
+}
+```
+
+### Integration in CLI Commands
+
+```typescript
+import { displayArtifactsCompact } from '@kb-labs/shared-cli-ui';
+import { discoverArtifacts } from './my-artifact-discovery';
+
+export const run: CommandModule['run'] = async (ctx, _argv, flags) => {
+  // ... your command logic ...
+  
+  // Show artifacts after operation
+  const artifacts = await discoverArtifacts(process.cwd());
+  const artifactsInfo = displayArtifactsCompact(artifacts, { maxItems: 5 });
+  
+  const output = box('My Command', [
+    ...summary,
+    ...artifactsInfo
+  ]);
+  
+  ctx.presenter.write(output);
+};
+```
+
+## 📦 API Reference
+
+### Main Exports
+
+#### Formatting Functions
+
+- `box(title, content)`: Create boxed section
+- `table(rows, headers?)`: Format table
+- `keyValue(pairs, options?)`: Format key-value pairs
+- `indent(lines, level?)`: Add indentation
+- `section(header, content)`: Create section
+
+#### Command Utilities
+
+- `createCommandRegistry(commands)`: Create command registry
+- `MultiCLISuggestions`: Multi-CLI manager class
+- `displayArtifacts(artifacts, options?)`: Display artifacts
+- `displayArtifactsCompact(artifacts, options?)`: Compact artifact display
+
+### Types & Interfaces
+
+See detailed API documentation in code comments.
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## 📄 License
+
+MIT © KB Labs