@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/src/manifest-parser.ts

@@ -0,0 +1,151 @@
+/**
+ * CLI manifest parsing utilities
+ */
+
+export interface CommandManifest {
+  manifestVersion: string;
+  id: string;
+  aliases?: string[];
+  group: string;
+  describe: string;
+  longDescription?: string;
+  requires?: string[];
+  flags?: FlagDefinition[];
+  examples?: string[];
+  loader: () => Promise<{ run: any }>;
+}
+
+export interface FlagDefinition {
+  name: string;
+  type: 'string' | 'boolean' | 'number' | 'array';
+  alias?: string;
+  default?: any;
+  description?: string;
+  choices?: string[];
+  required?: boolean;
+}
+
+/**
+ * Extract command IDs from a manifest
+ */
+export function extractCommandIds(manifest: CommandManifest[]): string[] {
+  return manifest.map(cmd => cmd.id);
+}
+
+/**
+ * Extract command groups from a manifest
+ */
+export function extractCommandGroups(manifest: CommandManifest[]): string[] {
+  const groups = new Set<string>();
+  manifest.forEach(cmd => groups.add(cmd.group));
+  return Array.from(groups);
+}
+
+/**
+ * Find commands by group
+ */
+export function findCommandsByGroup(manifest: CommandManifest[], group: string): CommandManifest[] {
+  return manifest.filter(cmd => cmd.group === group);
+}
+
+/**
+ * Find command by ID
+ */
+export function findCommandById(manifest: CommandManifest[], id: string): CommandManifest | undefined {
+  return manifest.find(cmd => cmd.id === id);
+}
+
+/**
+ * Get command info for suggestions
+ */
+export function getCommandInfo(manifest: CommandManifest[], commandId: string): {
+  id: string;
+  group: string;
+  name: string;
+  description: string;
+  available: boolean;
+} | null {
+  const cmd = findCommandById(manifest, commandId);
+  if (!cmd) {
+    return null;
+  }
+
+  const [group, name] = commandId.split(':');
+  return {
+    id: commandId,
+    group: group || 'unknown',
+    name: name || commandId,
+    description: cmd.describe,
+    available: true
+  };
+}
+
+/**
+ * Generate suggestions for a specific group
+ */
+export function generateGroupSuggestions(
+  manifest: CommandManifest[],
+  group: string,
+  _warningCodes: Set<string>,
+  _context: any
+): Array<{
+  id: string;
+  command: string;
+  args: string[];
+  description: string;
+  impact: 'safe' | 'disruptive';
+  when: string;
+  available: boolean;
+}> {
+  const groupCommands = findCommandsByGroup(manifest, group);
+  const suggestions: Array<{
+    id: string;
+    command: string;
+    args: string[];
+    description: string;
+    impact: 'safe' | 'disruptive';
+    when: string;
+    available: boolean;
+  }> = [];
+
+  // Generate common suggestions for each group
+  for (const cmd of groupCommands) {
+    // Basic command suggestion
+    suggestions.push({
+      id: `${cmd.group.toUpperCase()}_${cmd.id.split(':')[1]?.toUpperCase() || 'UNKNOWN'}`,
+      command: `kb ${cmd.group} ${cmd.id.split(':')[1] || ''}`,
+      args: [],
+      description: cmd.describe,
+      impact: 'safe',
+      when: 'GENERAL',
+      available: true
+    });
+
+    // Add specific suggestions based on command type
+    if (cmd.id.includes('init')) {
+      suggestions.push({
+        id: `${cmd.group.toUpperCase()}_INIT_FORCE`,
+        command: `kb ${cmd.group} ${cmd.id.split(':')[1] || ''}`,
+        args: ['--force'],
+        description: `${cmd.describe} (force)`,
+        impact: 'disruptive',
+        when: 'INIT_FAILED',
+        available: true
+      });
+    }
+
+    if (cmd.id.includes('clean') || cmd.id.includes('reset')) {
+      suggestions.push({
+        id: `${cmd.group.toUpperCase()}_CLEAN_HARD`,
+        command: `kb ${cmd.group} ${cmd.id.split(':')[1] || ''}`,
+        args: ['--hard'],
+        description: `${cmd.describe} (hard)`,
+        impact: 'disruptive',
+        when: 'CLEAN_NEEDED',
+        available: true
+      });
+    }
+  }
+
+  return suggestions;
+}

package/packages/shared-cli-ui/src/modern-format.ts

@@ -0,0 +1,271 @@
+/**
+ * Modern CLI formatting utilities with side border design
+ * Provides minimalist, modern UI components for CLI output
+ */
+
+import { safeColors, safeSymbols } from './colors';
+import { stripAnsi, bulletList as baseBulletList } from './format';
+import { formatTiming as baseFormatTiming } from './command-output';
+
+/**
+ * Side border box - modern minimalist design
+ *
+ * @example
+ * ```
+ * ┌── Command Name
+ * │
+ * │ Section Header
+ * │  Key: value
+ * │
+ * └── ✓ Success / 12ms
+ * ```
+ */
+export interface SideBorderBoxOptions {
+  title: string;
+  sections: SectionContent[];
+  footer?: string;
+  status?: 'success' | 'error' | 'warning' | 'info';
+  timing?: number;
+}
+
+export interface SectionContent {
+  header?: string;
+  items: string[];
+}
+
+/**
+ * Create a side-bordered box with modern design
+ */
+export function sideBorderBox(options: SideBorderBoxOptions): string {
+  const { title, sections, footer, status, timing } = options;
+  const lines: string[] = [];
+
+  // Top border with title (using top-left corner)
+  const titleLine = `${safeSymbols.topLeft}${safeSymbols.separator.repeat(2)} ${safeColors.primary(safeColors.bold(title))}`;
+  lines.push(titleLine);
+  lines.push(safeSymbols.border);
+
+  // Sections
+  for (let i = 0; i < sections.length; i++) {
+    const section = sections[i];
+    if (!section) {continue;}
+
+    // Section header (optional)
+    if (section.header) {
+      lines.push(`${safeSymbols.border} ${safeColors.bold(section.header)}`);
+    }
+
+    // Section items
+    for (const item of section.items) {
+      lines.push(`${safeSymbols.border}  ${item}`);
+    }
+
+    // Add spacing between sections (but not after the last one)
+    if (i < sections.length - 1) {
+      lines.push(safeSymbols.border);
+    }
+  }
+
+  // Bottom border with status/timing
+  if (footer || status || timing !== undefined) {
+    lines.push(safeSymbols.border);
+    const footerParts: string[] = [];
+
+    if (footer) {
+      footerParts.push(footer);
+    } else if (status) {
+      const statusSymbol = getStatusSymbol(status);
+      const statusText = getStatusText(status);
+      const statusColor = getStatusColor(status);
+      footerParts.push(statusColor(`${statusSymbol} ${statusText}`));
+    }
+
+    if (timing !== undefined) {
+      footerParts.push(formatTiming(timing));
+    }
+
+    const footerLine = `${safeSymbols.bottomLeft}${safeSymbols.separator.repeat(2)} ${footerParts.join(' / ')}`;
+    lines.push(footerLine);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a section header
+ */
+export function sectionHeader(text: string): string {
+  return safeColors.bold(text);
+}
+
+/**
+ * Format metrics list (key: value pairs with aligned values)
+ */
+export function metricsList(metrics: Record<string, string | number>): string[] {
+  const entries = Object.entries(metrics);
+  if (entries.length === 0) {return [];}
+
+  // Find max key length for alignment
+  const maxKeyLength = Math.max(
+    ...entries.map(([key]) => stripAnsi(key).length)
+  );
+
+  return entries.map(([key, value]) => {
+    const keyLength = stripAnsi(key).length;
+    const padding = ' '.repeat(maxKeyLength - keyLength + 2);
+    const formattedKey = safeColors.bold(key);
+    const formattedValue = safeColors.muted(String(value));
+    return `${formattedKey}:${padding}${formattedValue}`;
+  });
+}
+
+/**
+ * Format a bullet list (re-exported from base utilities)
+ */
+export const bulletList = baseBulletList;
+
+/**
+ * Format timing (re-exported from command-output)
+ */
+export const formatTiming = baseFormatTiming;
+
+/**
+ * Format status line for footer
+ */
+export function statusLine(
+  status: 'success' | 'error' | 'warning' | 'info',
+  timing?: number
+): string {
+  const symbol = getStatusSymbol(status);
+  const text = getStatusText(status);
+  const color = getStatusColor(status);
+
+  const parts = [color(`${symbol} ${text}`)];
+
+  if (timing !== undefined) {
+    parts.push(formatTiming(timing));
+  }
+
+  return parts.join(' / ');
+}
+
+// Helper functions
+
+function getStatusSymbol(status: 'success' | 'error' | 'warning' | 'info'): string {
+  switch (status) {
+    case 'success':
+      return safeSymbols.success;
+    case 'error':
+      return safeSymbols.error;
+    case 'warning':
+      return safeSymbols.warning;
+    case 'info':
+      return safeSymbols.info;
+  }
+}
+
+function getStatusText(status: 'success' | 'error' | 'warning' | 'info'): string {
+  switch (status) {
+    case 'success':
+      return 'Success';
+    case 'error':
+      return 'Failed';
+    case 'warning':
+      return 'Warning';
+    case 'info':
+      return 'Info';
+  }
+}
+
+function getStatusColor(status: 'success' | 'error' | 'warning' | 'info'): (text: string) => string {
+  switch (status) {
+    case 'success':
+      return safeColors.success;
+    case 'error':
+      return safeColors.error;
+    case 'warning':
+      return safeColors.warning;
+    case 'info':
+      return safeColors.info;
+  }
+}
+
+/**
+ * Format command help in modern side-border style
+ *
+ * @example
+ * ```typescript
+ * const help = formatCommandHelp({
+ *   title: 'kb version',
+ *   description: 'Show CLI version',
+ *   longDescription: 'Displays the current version...',
+ *   examples: ['kb version', 'kb version --json'],
+ *   flags: [{name: 'json', description: 'Output in JSON'}]
+ * });
+ * ```
+ */
+export function formatCommandHelp(options: {
+  title: string;
+  description?: string;
+  longDescription?: string;
+  examples?: string[];
+  flags?: Array<{ name: string; alias?: string; description?: string; required?: boolean }>;
+  aliases?: string[];
+}): string {
+  const { title, description, longDescription, examples, flags, aliases } = options;
+  const sections: SectionContent[] = [];
+
+  // Description section
+  if (description) {
+    sections.push({
+      header: 'Description',
+      items: [description],
+    });
+  }
+
+  // Long description
+  if (longDescription) {
+    sections.push({
+      header: 'Details',
+      items: [longDescription],
+    });
+  }
+
+  // Aliases
+  if (aliases && aliases.length > 0) {
+    sections.push({
+      header: 'Aliases',
+      items: aliases.map(a => safeColors.muted(a)),
+    });
+  }
+
+  // Flags
+  if (flags && flags.length > 0) {
+    const flagItems = flags.map(flag => {
+      const label = flag.alias
+        ? `--${flag.name}, -${flag.alias}`
+        : `--${flag.name}`;
+      const required = flag.required ? safeColors.warning(' (required)') : '';
+      const desc = flag.description ? safeColors.muted(` — ${flag.description}`) : '';
+      return `${safeColors.bold(label)}${required}${desc}`;
+    });
+    sections.push({
+      header: 'Flags',
+      items: flagItems,
+    });
+  }
+
+  // Examples
+  if (examples && examples.length > 0) {
+    sections.push({
+      header: 'Examples',
+      items: examples.map(ex => safeColors.muted(`  ${ex}`)),
+    });
+  }
+
+  return sideBorderBox({
+    title,
+    sections,
+    status: 'info',
+  });
+}

package/packages/shared-cli-ui/src/multi-cli-suggestions.ts

@@ -0,0 +1,159 @@
+/**
+ * Multi-CLI suggestions system
+ * Supports multiple CLI packages with their own manifests
+ */
+
+import { 
+  createCommandRegistry, 
+  generateDevlinkSuggestions,
+  type CommandSuggestion,
+  type CommandRegistry 
+} from './command-suggestions';
+import { 
+  extractCommandIds, 
+  generateGroupSuggestions,
+  type CommandManifest 
+} from './manifest-parser';
+
+export interface MultiCLIContext {
+  warningCodes: Set<string>;
+  [key: string]: any;
+}
+
+export interface CLIPackage {
+  name: string;
+  group: string;
+  commands: CommandManifest[];
+  priority: number; // Higher priority = more important suggestions
+}
+
+/**
+ * Multi-CLI suggestions manager
+ */
+export class MultiCLISuggestions {
+  private packages: Map<string, CLIPackage> = new Map();
+  private globalRegistry: CommandRegistry | null = null;
+
+  /**
+   * Register a CLI package
+   */
+  registerPackage(pkg: CLIPackage): void {
+    this.packages.set(pkg.name, pkg);
+    this.globalRegistry = null; // Invalidate cache
+  }
+
+  /**
+   * Get or create global command registry
+   */
+  private getGlobalRegistry(): CommandRegistry {
+    if (this.globalRegistry) {
+      return this.globalRegistry;
+    }
+
+    const allCommands: string[] = [];
+    for (const pkg of this.packages.values()) {
+      allCommands.push(...extractCommandIds(pkg.commands));
+    }
+
+    this.globalRegistry = createCommandRegistry(allCommands);
+    return this.globalRegistry;
+  }
+
+  /**
+   * Generate suggestions for a specific group
+   */
+  generateGroupSuggestions(
+    group: string, 
+    context: MultiCLIContext
+  ): CommandSuggestion[] {
+    const suggestions: CommandSuggestion[] = [];
+    const registry = this.getGlobalRegistry();
+
+    // Find packages for this group
+    const groupPackages = Array.from(this.packages.values())
+      .filter(pkg => pkg.group === group)
+      .sort((a, b) => b.priority - a.priority);
+
+    for (const pkg of groupPackages) {
+      const groupSuggestions = generateGroupSuggestions(
+        pkg.commands, 
+        group, 
+        context.warningCodes, 
+        context
+      );
+
+      // Convert to CommandSuggestion format and validate
+      for (const suggestion of groupSuggestions) {
+        if (registry.commands.has(suggestion.command.replace('kb ', '').replace(' ', ':'))) {
+          suggestions.push({
+            id: suggestion.id,
+            command: suggestion.command,
+            args: suggestion.args,
+            description: suggestion.description,
+            impact: suggestion.impact,
+            when: suggestion.when,
+            available: true
+          });
+        }
+      }
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Generate all suggestions across all packages
+   */
+  generateAllSuggestions(context: MultiCLIContext): CommandSuggestion[] {
+    const suggestions: CommandSuggestion[] = [];
+    const registry = this.getGlobalRegistry();
+
+    // Special handling for devlink (highest priority)
+    if (this.packages.has('devlink')) {
+      const devlinkSuggestions = generateDevlinkSuggestions(
+        context.warningCodes, 
+        { undo: context.undo }, 
+        registry
+      );
+      suggestions.push(...devlinkSuggestions);
+    }
+
+    // Generate suggestions for other groups
+    const groups = new Set<string>();
+    for (const pkg of this.packages.values()) {
+      groups.add(pkg.group);
+    }
+
+    for (const group of groups) {
+      if (group !== 'devlink') { // Skip devlink as it's handled above
+        const groupSuggestions = this.generateGroupSuggestions(group, context);
+        suggestions.push(...groupSuggestions);
+      }
+    }
+
+    return suggestions;
+  }
+
+  /**
+   * Get available commands for a group
+   */
+  getAvailableCommands(group: string): string[] {
+    const groupPackages = Array.from(this.packages.values())
+      .filter(pkg => pkg.group === group);
+    
+    const commands: string[] = [];
+    for (const pkg of groupPackages) {
+      commands.push(...extractCommandIds(pkg.commands));
+    }
+    
+    return commands;
+  }
+
+  /**
+   * Get all registered packages
+   */
+  getPackages(): CLIPackage[] {
+    return Array.from(this.packages.values());
+  }
+}
+

package/packages/shared-cli-ui/src/table.ts

@@ -0,0 +1,134 @@
+/**
+ * Table formatting utilities for CLI output
+ * Handles proper column alignment accounting for emoji/unicode width
+ */
+
+/**
+ * Calculate visual width of a string (accounting for emoji/wide chars and ANSI codes)
+ * Simplified version - emoji count as 2 chars, ANSI codes are stripped
+ */
+function visualWidth(str: string): number {
+  // Remove ANSI escape codes first
+  const ansiRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
+  const cleanStr = str.replace(ansiRegex, '');
+  
+  // Count emoji and wide characters as 2
+  const emojiRegex = /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]|[\u{1F600}-\u{1F64F}]|[\u{1F680}-\u{1F6FF}]|[\u{1F900}-\u{1F9FF}]|[\u{1FA00}-\u{1FA6F}]|[\u{1FA70}-\u{1FAFF}]|[\u{2190}-\u{21FF}]|[\u{2300}-\u{23FF}]|[\u{24C2}-\u{1F251}]|[\u{2B50}-\u{2B55}]|[\u{3030}-\u{303D}]|[\u{3297}-\u{3299}]|[\u{1F000}-\u{1F02F}]|[\u{1F0A0}-\u{1F0FF}]|[\u{1F100}-\u{1F1FF}]|[\u{1F200}-\u{1F2FF}]|[\u{1F300}-\u{1F5FF}]|[\u{1F600}-\u{1F64F}]|[\u{1F680}-\u{1F6FF}]|[\u{1F700}-\u{1F7FF}]|[\u{1F800}-\u{1F8FF}]|[\u{1F900}-\u{1F9FF}]|[\u{1FA00}-\u{1FA6F}]|[\u{1FA70}-\u{1FAFF}]|[\u{23F0}-\u{23FF}]|[\u{25A0}-\u{25FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]|[\u{FE00}-\u{FE0F}]|[\u{1F1E6}-\u{1F1FF}]|[\u{1F3FB}-\u{1F3FF}]|[\u{1F9B0}-\u{1F9B3}]|[\u{20E3}]|[\u{FE0F}]/gu;
+  const emojiMatches = cleanStr.match(emojiRegex);
+  const emojiCount = emojiMatches ? emojiMatches.length : 0;
+  
+  // Basic character count minus emoji count (since emoji are already counted)
+  // Then add emoji count * 2 for visual width
+  return cleanStr.length - emojiCount + emojiCount * 2;
+}
+
+/**
+ * Pad string to visual width (accounting for emoji)
+ */
+function padVisual(str: string, width: number, padChar: string = ' '): string {
+  const vWidth = visualWidth(str);
+  const padding = Math.max(0, width - vWidth);
+  return str + padChar.repeat(padding);
+}
+
+export interface TableColumn {
+  header: string;
+  width?: number; // Auto-calculated if not provided
+  align?: 'left' | 'right' | 'center';
+}
+
+export interface TableOptions {
+  header?: boolean;
+  separator?: string; // Character for separator line (e.g., '─')
+  padding?: number; // Padding between columns
+}
+
+/**
+ * Format data as a table with proper column alignment
+ */
+export function formatTable(
+  columns: TableColumn[],
+  rows: string[][],
+  options: TableOptions = {}
+): string[] {
+  const { header = true, separator = '─', padding = 1 } = options;
+  
+  // Calculate column widths
+  const widths: number[] = columns.map((col, idx) => {
+    if (col.width !== undefined) {
+      return col.width;
+    }
+    
+    // Calculate max width from header and all rows
+    let maxWidth = visualWidth(col.header);
+    for (const row of rows) {
+      if (row[idx]) {
+        maxWidth = Math.max(maxWidth, visualWidth(String(row[idx])));
+      }
+    }
+    return maxWidth;
+  });
+  
+  const lines: string[] = [];
+  
+  // Header
+  if (header) {
+    const headerCells = columns.map((col, idx) => {
+      const cell = col.header;
+      const width = widths[idx]!;
+      return padVisual(cell, width);
+    });
+    lines.push(headerCells.join(' '.repeat(padding)));
+    
+    // Separator
+    if (separator) {
+      const separatorLine = widths.map(w => separator.repeat(w)).join(' '.repeat(padding));
+      lines.push(separatorLine);
+    }
+  }
+  
+  // Rows
+  for (const row of rows) {
+    const cells = columns.map((col, idx) => {
+      const cell = row[idx] !== undefined ? String(row[idx]) : '';
+      const align = col.align || 'left';
+      const width = widths[idx]!;
+      
+      if (align === 'right') {
+        const vWidth = visualWidth(cell);
+        const padding = Math.max(0, width - vWidth);
+        return ' '.repeat(padding) + cell;
+      } else if (align === 'center') {
+        const vWidth = visualWidth(cell);
+        const padding = Math.max(0, width - vWidth);
+        const leftPad = Math.floor(padding / 2);
+        const rightPad = padding - leftPad;
+        return ' '.repeat(leftPad) + cell + ' '.repeat(rightPad);
+      } else {
+        return padVisual(cell, width);
+      }
+    });
+    lines.push(cells.join(' '.repeat(padding)));
+  }
+  
+  return lines;
+}
+
+/**
+ * Format simple key-value pairs as a table
+ */
+export function formatKeyValueTable(
+  data: Record<string, string | number>,
+  options: { keyWidth?: number; valueWidth?: number } = {}
+): string[] {
+  const keys = Object.keys(data);
+  if (keys.length === 0) {return [];}
+  
+  const keyWidth = options.keyWidth || Math.max(...keys.map(k => visualWidth(k)), 0);
+  const valueWidth = options.valueWidth || Math.max(...Object.values(data).map(v => visualWidth(String(v))), 0);
+  
+  return keys.map(key => {
+    const value = String(data[key]);
+    return `${padVisual(key, keyWidth)}  ${padVisual(value, valueWidth)}`;
+  });
+}