@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/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

package/packages/shared-cli-ui/docs/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# Package Architecture Description: @kb-labs/shared-cli-ui
+
+**Version**: 0.1.0
+**Last Updated**: 2025-11-16
+
+## Executive Summary
+
+**@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.
+
+## 1. Package Overview
+
+### 1.1 Purpose & Scope
+
+**Primary Purpose**: Provide shared CLI UI utilities for consistent user experience.
+
+**Scope Boundaries**:
+- **In Scope**: Formatting, command discovery, suggestions, artifacts display
+- **Out of Scope**: Command execution, file system operations
+
+**Domain**: Shared Utilities / CLI UI
+
+### 1.2 Key Responsibilities
+
+1. **Formatting**: Format CLI output (tables, boxes, colors)
+2. **Command Discovery**: Discover commands from manifests
+3. **Command Suggestions**: Generate context-aware suggestions
+4. **Artifacts Display**: Display generated artifacts
+
+## 2. High-Level Architecture
+
+### 2.1 Architecture Diagram
+
+```
+CLI UI Utilities
+    │
+    ├──► Formatting (tables, boxes, colors)
+    ├──► Command Discovery (manifest parsing)
+    ├──► Command Suggestions (auto-suggestions)
+    ├──► Multi-CLI Support (multi-package manager)
+    ├──► Artifacts Display (artifact rendering)
+    └──► Debug Utilities (debug formatting)
+```
+
+### 2.2 Architectural Style
+
+- **Style**: Utility Library with Manager Pattern
+- **Rationale**: Pure utilities with stateful managers for multi-CLI
+
+## 3. Component Architecture
+
+### 3.1 Component: Formatting Utilities
+
+- **Purpose**: Format CLI output
+- **Responsibilities**: Tables, boxes, colors, indentation
+- **Dependencies**: None (pure functions)
+
+### 3.2 Component: Command Discovery
+
+- **Purpose**: Discover commands from manifests
+- **Responsibilities**: Parse manifests, extract commands
+- **Dependencies**: None
+
+### 3.3 Component: Multi-CLI Manager
+
+- **Purpose**: Manage multiple CLI packages
+- **Responsibilities**: Register packages, generate suggestions
+- **Dependencies**: Command discovery
+
+## 4. Data Flow
+
+```
+createCommandRegistry(commands)
+    │
+    ├──► Build command registry
+    └──► return registry
+
+generateSuggestions(context, registry)
+    │
+    ├──► Analyze context
+    ├──► Match commands
+    └──► return suggestions
+```
+
+## 5. Design Patterns
+
+- **Utility Pattern**: Pure utility functions
+- **Manager Pattern**: Multi-CLI manager
+- **Factory Pattern**: Command runner creation
+
+## 6. Performance Architecture
+
+- **Time Complexity**: O(n) for most operations
+- **Space Complexity**: O(n) for formatting
+- **Bottlenecks**: Large table formatting
+
+## 7. Security Architecture
+
+- **Input Validation**: All inputs validated
+- **No Side Effects**: Pure functions (mostly)
+- **Path Validation**: Path operations validated
+
+---
+
+**Last Updated**: 2025-11-16
+

package/packages/shared-cli-ui/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/shared-cli-ui/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@kb-labs/shared-cli-ui",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Shared CLI UI utilities for KB Labs projects - colors, formatting, progress indicators",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./debug": {
+      "import": "./dist/debug.js",
+      "types": "./dist/debug.d.ts"
+    },
+    "./table": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ],
+      "debug": [
+        "src/debug"
+      ],
+      "debug/*": [
+        "src/debug/*"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "eslint": "^9",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@types/node": "^24.3.3"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/shared-cli-ui/src/__tests__/artifacts-display.spec.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import path from 'node:path';
+
+const TEST_NOW = new Date('2025-01-01T00:06:00Z');
+
+describe('artifacts display formatting', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    vi.setSystemTime(TEST_NOW);
+    process.env.NO_COLOR = '1';
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    delete process.env.NO_COLOR;
+  });
+
+  it('renders detailed artifact list with metadata', async () => {
+    const { displayArtifacts } = await import('../artifacts-display.js');
+    const cwd = process.cwd();
+
+    const apiArtifact = {
+      name: 'API Index',
+      path: path.join(cwd, 'api-index.json'),
+      size: 512,
+      modified: new Date('2025-01-01T00:05:00Z'),
+      description: 'API index',
+    };
+
+    const indexArtifact = {
+      name: 'Index',
+      path: path.join(cwd, 'index.json'),
+      size: 1024,
+      modified: new Date('2025-01-01T00:04:00Z'),
+      description: 'Primary index',
+    };
+
+    const artifacts = [indexArtifact, apiArtifact];
+    const lines = displayArtifacts(artifacts, {
+      title: 'Artifacts',
+      showDescription: true,
+    });
+
+    const expected = [
+      'Artifacts',
+      `${apiArtifact.name}: ${path.relative(cwd, apiArtifact.path)}`,
+      '  Size: 512 B',
+      '  Updated: 1 minute ago',
+      `  Note: ${apiArtifact.description}`,
+      '',
+      `${indexArtifact.name}: ${path.relative(cwd, indexArtifact.path)}`,
+      '  Size: 1.0 KB',
+      '  Updated: 2 minutes ago',
+      `  Note: ${indexArtifact.description}`,
+    ];
+
+    expect(lines).toEqual(expected);
+  });
+
+  it('renders compact artifact summary', async () => {
+    const { displayArtifactsCompact } = await import('../artifacts-display.js');
+    const cwd = process.cwd();
+
+    const artifact = {
+      name: 'Index',
+      path: path.join(cwd, 'index.json'),
+      size: 1024,
+      modified: new Date('2025-01-01T00:05:00Z'),
+      description: '',
+    };
+
+    const lines = displayArtifactsCompact([artifact], {
+      title: 'Artifacts',
+      showTime: true,
+      showSize: true,
+    });
+
+    const expected = [
+      'Artifacts',
+      `${artifact.name}: ${path.relative(cwd, artifact.path)}`,
+      '  Size: 1.0 KB',
+      '  Updated: 1 minute ago',
+    ];
+
+    expect(lines).toEqual(expected);
+  });
+});
+

package/packages/shared-cli-ui/src/__tests__/format.spec.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { formatTimestamp, formatRelativeTime } from '../format';
+
+describe('format helpers', () => {
+  const baseDate = new Date('2025-01-01T00:05:30Z');
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('formats timestamp in ISO mode with offset', () => {
+    expect(formatTimestamp(baseDate, { mode: 'iso', timeZone: 'UTC' })).toBe('2025-01-01T00:05:30.000Z (+00:00)');
+    expect(formatTimestamp(baseDate, { mode: 'iso', timeZone: 'UTC', includeMilliseconds: false })).toBe(
+      '2025-01-01T00:05:30Z (+00:00)',
+    );
+  });
+
+  it('formats timestamp in local mode for a specific timezone', () => {
+    expect(
+      formatTimestamp(baseDate, {
+        mode: 'local',
+        timeZone: 'UTC',
+        includeSeconds: true,
+      }),
+    ).toBe('2025-01-01 00:05:30 (+00:00)');
+
+    expect(
+      formatTimestamp(baseDate, {
+        mode: 'local',
+        timeZone: 'America/Los_Angeles',
+        includeSeconds: true,
+      }),
+    ).toBe('2024-12-31 16:05:30 (-08:00)');
+  });
+
+  it('returns human-friendly relative time', () => {
+    const now = new Date('2025-01-01T00:06:30Z');
+    vi.useFakeTimers();
+    vi.setSystemTime(now);
+
+    expect(formatRelativeTime(baseDate)).toBe('1 minute ago');
+  });
+});
+