@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.

🎯 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

pnpm add @kb-labs/shared-cli-ui

Basic Usage

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

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

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:

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:

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

interface CommandSuggestion {
  id: string;
  command: string;
  args: string[];
  description: string;
  impact: 'safe' | 'disruptive';
  when: string;
  available?: boolean;
}

MultiCLISuggestions

class MultiCLISuggestions {
  registerPackage(pkg: CLIPackage): void;
  generateAllSuggestions(context: MultiCLIContext): CommandSuggestion[];
  generateGroupSuggestions(group: string, context: MultiCLIContext): CommandSuggestion[];
  getAvailableCommands(group: string): string[];
}

Command Registry

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

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

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

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 for development guidelines.

📄 License

MIT © KB Labs