@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/src/command-discovery.ts

@@ -0,0 +1,72 @@
+/**
+ * Command discovery utilities for CLI systems
+ */
+
+export interface CommandInfo {
+  id: string;
+  group: string;
+  name: string;
+  description: string;
+  available: boolean;
+}
+
+/**
+ * Discover available commands from CLI manifest or registry
+ * This is a generic interface that can be implemented by different CLI systems
+ */
+export interface CommandDiscovery {
+  /**
+   * Get all available commands
+   */
+  getAvailableCommands(): Promise<string[]>;
+  
+  /**
+   * Get command info by ID
+   */
+  getCommandInfo(commandId: string): Promise<CommandInfo | null>;
+  
+  /**
+   * Check if a command is available
+   */
+  isCommandAvailable(commandId: string): Promise<boolean>;
+}
+
+/**
+ * Simple command discovery that works with a predefined list
+ * Can be extended to work with actual CLI registries
+ */
+export class StaticCommandDiscovery implements CommandDiscovery {
+  constructor(private commands: string[]) {}
+
+  async getAvailableCommands(): Promise<string[]> {
+    return [...this.commands];
+  }
+
+  async getCommandInfo(commandId: string): Promise<CommandInfo | null> {
+    if (!this.commands.includes(commandId)) {
+      return null;
+    }
+
+    const [group, name] = commandId.split(':');
+    return {
+      id: commandId,
+      group: group || 'unknown',
+      name: name || commandId,
+      description: `Execute ${commandId}`,
+      available: true
+    };
+  }
+
+  async isCommandAvailable(commandId: string): Promise<boolean> {
+    return this.commands.includes(commandId);
+  }
+}
+
+
+
+/**
+ * Create a command discovery instance from a command list
+ */
+export function createCommandDiscovery(commands: string[]): CommandDiscovery {
+  return new StaticCommandDiscovery(commands);
+}

package/packages/shared-cli-ui/src/command-output.ts

@@ -0,0 +1,153 @@
+/**
+ * Command output formatting utilities
+ * Provides consistent formatting for CLI command results
+ */
+
+import { box, keyValue } from './format';
+import { safeColors } from './colors';
+
+export interface CommandResult {
+  title: string;
+  summary: Record<string, string | number>;
+  timing?: number | Record<string, number>;
+  diagnostics?: string[];
+  warnings?: string[];
+  errors?: string[];
+  suggestions?: string[];
+}
+
+/**
+ * Format timing in milliseconds to human-readable string
+ */
+export function formatTiming(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  } else if (ms < 60000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  } else {
+    const minutes = Math.floor(ms / 60000);
+    const seconds = ((ms % 60000) / 1000).toFixed(1);
+    return `${minutes}m ${seconds}s`;
+  }
+}
+
+/**
+ * Format timing breakdown as array of strings
+ */
+export function formatTimingBreakdown(timings: Record<string, number>): string[] {
+  const lines: string[] = [];
+  
+  // Sort timings by value (descending) for better readability
+  const sortedEntries = Object.entries(timings)
+    .filter(([key]) => key !== 'total')
+    .sort(([, a], [, b]) => b - a);
+  
+  for (const [name, ms] of sortedEntries) {
+    const formattedName = name.charAt(0).toUpperCase() + name.slice(1);
+    lines.push(`${formattedName}: ${formatTiming(ms)}`);
+  }
+  
+  // Always show total at the end
+  if (timings.total !== undefined) {
+    lines.push(`Total: ${formatTiming(timings.total)}`);
+  }
+  
+  return lines;
+}
+
+/**
+ * Format complete command output with box, summary, timing, and additional info
+ */
+export function formatCommandOutput(result: CommandResult): string {
+  const sections: string[] = [];
+  
+  // Add summary section
+  const summaryLines = keyValue(result.summary);
+  sections.push(...summaryLines);
+  
+  // Add timing section
+  if (result.timing !== undefined) {
+    sections.push('');
+    
+    if (typeof result.timing === 'number') {
+      sections.push(`Time: ${formatTiming(result.timing)}`);
+    } else {
+      const timingLines = formatTimingBreakdown(result.timing);
+      sections.push(...timingLines);
+    }
+  }
+  
+  // Add warnings section
+  if (result.warnings && result.warnings.length > 0) {
+    sections.push('');
+    sections.push(safeColors.warning('Warnings:'));
+    result.warnings.forEach(warning => 
+      sections.push(`  ${safeColors.dim('•')} ${warning}`)
+    );
+  }
+  
+  // Add errors section
+  if (result.errors && result.errors.length > 0) {
+    sections.push('');
+    sections.push(safeColors.error('Errors:'));
+    result.errors.forEach(error => 
+      sections.push(`  ${safeColors.dim('•')} ${error}`)
+    );
+  }
+  
+  // Add diagnostics section
+  if (result.diagnostics && result.diagnostics.length > 0) {
+    sections.push('');
+    sections.push(safeColors.info('Diagnostics:'));
+    result.diagnostics.forEach(diagnostic => 
+      sections.push(`  ${safeColors.dim('•')} ${diagnostic}`)
+    );
+  }
+  
+  // Add suggestions section
+  if (result.suggestions && result.suggestions.length > 0) {
+    sections.push('');
+    sections.push(safeColors.info('Suggestions:'));
+    result.suggestions.forEach(suggestion => 
+      sections.push(`  ${safeColors.dim('•')} ${suggestion}`)
+    );
+  }
+  
+  return box(result.title, sections);
+}
+
+/**
+ * Create a simple command result with just title, summary, and timing
+ */
+export function createSimpleResult(
+  title: string, 
+  summary: Record<string, string | number>, 
+  timing?: number
+): CommandResult {
+  return {
+    title,
+    summary,
+    timing,
+  };
+}
+
+/**
+ * Create a detailed command result with all optional fields
+ */
+export function createDetailedResult(
+  title: string,
+  summary: Record<string, string | number>,
+  options: {
+    timing?: number | Record<string, number>;
+    diagnostics?: string[];
+    warnings?: string[];
+    errors?: string[];
+    suggestions?: string[];
+  } = {}
+): CommandResult {
+  return {
+    title,
+    summary,
+    ...options,
+  };
+}

package/packages/shared-cli-ui/src/command-result.ts

@@ -0,0 +1,267 @@
+/**
+ * Command result formatting utilities
+ * Provides high and low-level APIs for formatting command output
+ */
+
+import {
+  sideBorderBox,
+  metricsList,
+  bulletList,
+  type SectionContent,
+} from './modern-format';
+
+/**
+ * Command output with human and machine-readable formats
+ * Extends CommandResult contract from command-kit
+ */
+export interface CommandOutput {
+  /** Whether command executed successfully - required by CommandResult contract */
+  ok: boolean;
+  /** Execution status */
+  status?: 'success' | 'error' | 'warning' | 'info' | 'failed' | 'cancelled' | 'skipped';
+  /** Human-readable output (side border format) */
+  human: string;
+  /** Machine-readable output (JSON) */
+  json: object;
+  /** Agent-specific output (optional, for --agent flag) */
+  agent?: object;
+}
+
+/**
+ * Parameters for formatting command results
+ */
+export interface CommandResultParams {
+  title: string;
+  summary?: Record<string, string | number>;
+  details?: Array<{ section: string; items: string[] }>;
+  warnings?: string[];
+  errors?: string[];
+  timing?: number;
+  status: 'success' | 'error' | 'warning' | 'info';
+  /** Custom JSON data (optional) */
+  jsonData?: object;
+}
+
+/**
+ * Low-level: Format command result with full control
+ *
+ * @example
+ * ```typescript
+ * const output = formatCommandResult({
+ *   title: 'System Diagnostics',
+ *   summary: { 'Total Checks': 4, 'OK': 3 },
+ *   details: [
+ *     { section: 'Environment', items: ['Node 20.11.0'] }
+ *   ],
+ *   warnings: ['Cache is old'],
+ *   timing: 150,
+ *   status: 'success',
+ * });
+ *
+ * console.log(output.human);  // Pretty CLI output
+ * console.log(output.json);   // JSON for --json flag
+ * ```
+ */
+export function formatCommandResult(params: CommandResultParams): CommandOutput {
+  const {
+    title,
+    summary,
+    details = [],
+    warnings = [],
+    errors = [],
+    timing,
+    status,
+    jsonData,
+  } = params;
+
+  // Build sections for human output
+  const sections: SectionContent[] = [];
+
+  // Summary section
+  if (summary && Object.keys(summary).length > 0) {
+    sections.push({
+      header: 'Summary',
+      items: metricsList(summary),
+    });
+  }
+
+  // Details sections
+  for (const detail of details) {
+    sections.push({
+      header: detail.section,
+      items: detail.items,
+    });
+  }
+
+  // Warnings section
+  if (warnings.length > 0) {
+    sections.push({
+      header: '⚠ Warnings',
+      items: bulletList(warnings),
+    });
+  }
+
+  // Errors section
+  if (errors.length > 0) {
+    sections.push({
+      header: '✗ Errors',
+      items: bulletList(errors),
+    });
+  }
+
+  // Generate human-readable output
+  const human = sideBorderBox({
+    title,
+    sections,
+    status,
+    timing,
+  });
+
+  // Generate JSON output
+  const json: any = {
+    ok: status === 'success',
+    status,
+    ...(summary && { summary }),
+    ...(details.length > 0 && {
+      details: details.reduce((acc, d) => {
+        acc[d.section] = d.items;
+        return acc;
+      }, {} as Record<string, string[]>),
+    }),
+    ...(warnings.length > 0 && { warnings }),
+    ...(errors.length > 0 && { errors }),
+    ...(timing !== undefined && { timingMs: timing }),
+    ...(jsonData && { data: jsonData }),
+  };
+
+  return {
+    ok: status === 'success',
+    status,
+    human,
+    json
+  };
+}
+
+/**
+ * High-level: Quick success result
+ *
+ * @example
+ * ```typescript
+ * return successResult('Version Info', {
+ *   summary: { 'CLI Version': '0.1.0' },
+ *   timing: 5,
+ * });
+ * ```
+ */
+export function successResult(
+  title: string,
+  data?: {
+    summary?: Record<string, string | number>;
+    details?: Array<{ section: string; items: string[] }>;
+    timing?: number;
+    json?: object;
+  }
+): CommandOutput {
+  return formatCommandResult({
+    title,
+    summary: data?.summary,
+    details: data?.details,
+    timing: data?.timing,
+    status: 'success',
+    jsonData: data?.json,
+  });
+}
+
+/**
+ * High-level: Quick error result
+ *
+ * @example
+ * ```typescript
+ * return errorResult('Command Failed', new Error('Something went wrong'), {
+ *   timing: 100,
+ *   suggestions: ['Try running with --debug flag'],
+ * });
+ * ```
+ */
+export function errorResult(
+  title: string,
+  error: Error | string,
+  options?: {
+    timing?: number;
+    suggestions?: string[];
+  }
+): CommandOutput {
+  const errorMessage = error instanceof Error ? error.message : error;
+  const errorStack = error instanceof Error ? error.stack : undefined;
+
+  return formatCommandResult({
+    title,
+    errors: [errorMessage],
+    details: options?.suggestions
+      ? [{ section: 'Suggestions', items: bulletList(options.suggestions) }]
+      : [],
+    timing: options?.timing,
+    status: 'error',
+    jsonData: {
+      error: errorMessage,
+      ...(errorStack && { stack: errorStack }),
+    },
+  });
+}
+
+/**
+ * High-level: Quick warning result
+ *
+ * @example
+ * ```typescript
+ * return warningResult('Configuration Updated', ['Deprecated option used'], {
+ *   summary: { 'Files Updated': 3 },
+ *   timing: 50,
+ * });
+ * ```
+ */
+export function warningResult(
+  title: string,
+  warnings: string[],
+  options?: {
+    summary?: Record<string, string | number>;
+    timing?: number;
+  }
+): CommandOutput {
+  return formatCommandResult({
+    title,
+    warnings,
+    summary: options?.summary,
+    timing: options?.timing,
+    status: 'warning',
+  });
+}
+
+/**
+ * High-level: Info result
+ *
+ * @example
+ * ```typescript
+ * return infoResult('Help Information', {
+ *   details: [
+ *     { section: 'Usage', items: ['kb command --flag'] }
+ *   ],
+ * });
+ * ```
+ */
+export function infoResult(
+  title: string,
+  data?: {
+    summary?: Record<string, string | number>;
+    details?: Array<{ section: string; items: string[] }>;
+    timing?: number;
+  }
+): CommandOutput {
+  return formatCommandResult({
+    title,
+    summary: data?.summary,
+    details: data?.details,
+    timing: data?.timing,
+    status: 'info',
+  });
+}