@kb-labs/shared 1.1.0

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

@@ -0,0 +1,310 @@
+import { box, keyValue, safeKeyValue, hasAnsi } from './format';
+import { formatTiming } from './command-output';
+import { safeColors, safeSymbols } from './colors';
+import {
+  displayArtifacts,
+  type ArtifactInfo,
+  type ArtifactDisplayOptions,
+} from './artifacts-display';
+import { TimingTracker } from './timing-tracker';
+
+// Optional analytics types - using interface to avoid type resolution errors
+// when @kb-labs/analytics-sdk-node is not installed
+interface AnalyticsRunScope {
+  (options: { runId?: string; actor?: unknown; ctx?: Record<string, unknown> }, fn: (emit: AnalyticsEmit) => Promise<unknown>): Promise<unknown>;
+}
+
+interface AnalyticsEmit {
+  (event: Partial<{ type: string; payload: Record<string, unknown> }>): Promise<unknown>;
+}
+
+export interface CommandPresenter {
+  info(message: string): void;
+  warn?(message: string): void;
+  error(message: string): void;
+  write(payload: string): void;
+  json(payload: unknown): void;
+}
+
+export interface CommandContext {
+  cwd: string;
+  presenter: CommandPresenter;
+}
+
+export interface CommandExecutionResult {
+  summary: Record<string, string | number>;
+  artifacts?: ArtifactInfo[];
+  artifactsOptions?: ArtifactDisplayOptions;
+  timing?: number | Record<string, number>;
+  diagnostics?: string[];
+  warnings?: string[];
+  errors?: string[];
+  data?: Record<string, unknown>;
+}
+
+export interface AnalyticsConfig {
+  actor: string;
+  started: string;
+  finished: string;
+  getPayload?: (flags: Record<string, unknown>, result?: CommandExecutionResult) => Record<string, unknown>;
+}
+
+export interface CommandRunnerOptions {
+  title: string;
+  analytics?: AnalyticsConfig;
+  execute: (ctx: CommandContext, flags: Record<string, unknown>, tracker: TimingTracker) => Promise<CommandExecutionResult>;
+}
+
+export function createCommandRunner(options: CommandRunnerOptions) {
+  return async (ctx: CommandContext, argv: string[], flags: Record<string, unknown>): Promise<number> => {
+    const tracker = new TimingTracker();
+    const jsonMode = flags.json === true;
+    const quietMode = flags.quiet === true;
+    const start = Date.now();
+
+    let runScope: AnalyticsRunScope | null = null;
+    if (options.analytics !== undefined) {
+      try {
+        // Dynamic import with type assertion to avoid TypeScript errors
+        // @kb-labs/analytics-sdk-node is an optional dependency
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore - optional dependency, types may not be available
+        const analyticsModule = await import('@kb-labs/analytics-sdk-node') as {
+          runScope?: AnalyticsRunScope;
+        };
+        if (analyticsModule.runScope) {
+          runScope = analyticsModule.runScope;
+        }
+      } catch {
+        // Analytics SDK not available, continue without it
+        runScope = null;
+      }
+    }
+
+    const execute = async (): Promise<number> => {
+      tracker.checkpoint('start');
+      try {
+        const result = await options.execute(ctx, flags, tracker);
+        tracker.checkpoint('complete');
+        formatSuccessOutput(ctx, options.title, result, tracker.total(), {
+          jsonMode,
+          quietMode,
+        });
+        return 0;
+      } catch (error) {
+        tracker.checkpoint('error');
+        const message = error instanceof Error ? error.message : String(error);
+        formatErrorOutput(ctx, message, tracker.total(), {
+          jsonMode,
+          quietMode,
+        });
+        return 1;
+      }
+    };
+
+    if (!runScope || !options.analytics) {
+      return execute();
+    }
+
+    const totalStart = Date.now();
+    const result = await runScope(
+      {
+        actor: options.analytics.actor as never,
+        ctx: { workspace: ctx.cwd },
+      },
+      async (emit: AnalyticsEmit) => {
+        await emit({
+          type: options.analytics!.started,
+          payload: options.analytics!.getPayload?.(flags) ?? {},
+        });
+
+        let exitCode = 0;
+        try {
+          exitCode = await execute();
+          await emit({
+            type: options.analytics!.finished,
+            payload: {
+              ...(options.analytics!.getPayload?.(flags) ?? {}),
+              durationMs: Date.now() - totalStart,
+              result: exitCode === 0 ? 'success' : 'error',
+            },
+          });
+        } catch (error) {
+          await emit({
+            type: options.analytics!.finished,
+            payload: {
+              ...(options.analytics!.getPayload?.(flags) ?? {}),
+              durationMs: Date.now() - totalStart,
+              result: 'error',
+              error: error instanceof Error ? error.message : String(error),
+            },
+          });
+          throw error;
+        }
+
+        return exitCode;
+      },
+    );
+
+    return result as number;
+  };
+}
+
+interface OutputFlags {
+  jsonMode: boolean;
+  quietMode: boolean;
+}
+
+function formatSuccessOutput(
+  ctx: CommandContext,
+  title: string,
+  result: CommandExecutionResult,
+  durationMs: number,
+  flags: OutputFlags,
+): void {
+  if (flags.jsonMode) {
+    const payload: Record<string, unknown> = {
+      ok: true,
+      summary: result.summary,
+      timing: result.timing ?? durationMs,
+      diagnostics: result.diagnostics,
+      warnings: result.warnings,
+      errors: result.errors,
+    };
+    if (result.artifacts) {
+      payload.artifacts = result.artifacts;
+    }
+    if (result.data) {
+      Object.assign(payload, result.data);
+    }
+    ctx.presenter.json(payload);
+    return;
+  }
+
+  if (flags.quietMode) {
+    return;
+  }
+
+  const statusEntry = extractStatusEntry(result.summary);
+  const summaryForDisplay: Record<string, string | number> = statusEntry
+    ? { ...result.summary }
+    : result.summary;
+
+  if (statusEntry) {
+    delete summaryForDisplay[statusEntry.key];
+  }
+
+  const lines: string[] = [];
+  const summaryLines = keyValue(summaryForDisplay);
+  if (summaryLines.length > 0) {
+    lines.push(...summaryLines);
+  }
+
+  if (result.artifacts && result.artifacts.length > 0) {
+    if (lines.length > 0) {
+      lines.push('');
+    }
+    lines.push(...displayArtifacts(result.artifacts, result.artifactsOptions));
+  }
+
+  const timing = result.timing ?? durationMs;
+  if (typeof timing !== 'number') {
+    const entries = Object.entries(timing);
+    if (entries.length > 0) {
+      if (lines.length > 0) {
+        lines.push('');
+      }
+      lines.push(safeColors.bold('Timing'));
+      for (const [label, value] of entries) {
+        lines.push(...safeKeyValue({ [label]: formatTiming(value) }, { indent: 2, pad: false }));
+      }
+    }
+  }
+
+  if (result.diagnostics && result.diagnostics.length > 0) {
+    if (lines.length > 0) {
+      lines.push('');
+    }
+    lines.push(safeColors.bold('Diagnostics'));
+    result.diagnostics.forEach((item) => lines.push(safeColors.muted(`- ${item}`)));
+  }
+
+  if (result.warnings && result.warnings.length > 0) {
+    if (lines.length > 0) {
+      lines.push('');
+    }
+    lines.push(safeColors.bold('Warnings'));
+    result.warnings.forEach((item) => lines.push(safeColors.muted(`- ${item}`)));
+  }
+
+  if (result.errors && result.errors.length > 0) {
+    if (lines.length > 0) {
+      lines.push('');
+    }
+    lines.push(safeColors.bold('Errors'));
+    result.errors.forEach((item) => lines.push(safeColors.muted(`- ${item}`)));
+  }
+
+  if (lines.length > 0) {
+    lines.push('');
+  }
+  lines.push(formatStatusLine(statusEntry?.value, durationMs));
+
+  ctx.presenter.write(box(title, lines));
+}
+
+function formatErrorOutput(
+  ctx: CommandContext,
+  errorMessage: string,
+  durationMs: number,
+  flags: OutputFlags,
+): void {
+  if (flags.jsonMode) {
+    ctx.presenter.json({
+      ok: false,
+      error: errorMessage,
+      timing: durationMs,
+    });
+    return;
+  }
+
+  if (flags.quietMode) {
+    return;
+  }
+
+  ctx.presenter.error(errorMessage);
+}
+
+interface StatusEntry {
+  key: string;
+  value: string;
+}
+
+function extractStatusEntry(summary: Record<string, string | number>): StatusEntry | null {
+  for (const [key, value] of Object.entries(summary)) {
+    if (typeof value === 'string' && key.toLowerCase().includes('status')) {
+      return { key, value };
+    }
+  }
+  return null;
+}
+
+function formatStatusLine(statusValue: string | undefined, durationMs: number): string {
+  const rawStatus = statusValue ?? 'Done';
+  const normalized = rawStatus.toLowerCase();
+
+  let symbol = safeSymbols.success;
+  let colorize = safeColors.success;
+
+  if (normalized.includes('error') || normalized.includes('fail')) {
+    symbol = safeSymbols.error;
+    colorize = safeColors.error;
+  } else if (normalized.includes('partial') || normalized.includes('warn')) {
+    symbol = safeSymbols.warning;
+    colorize = safeColors.warning;
+  }
+
+  const statusText = hasAnsi(rawStatus) ? rawStatus : colorize(rawStatus);
+  return `${symbol} ${statusText} · ${safeColors.muted(formatTiming(durationMs))}`;
+}
+

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

@@ -0,0 +1,204 @@
+/**
+ * Command suggestions and validation utilities
+ */
+
+export interface CommandSuggestion {
+  id: string;
+  command: string;
+  args: string[];
+  description: string;
+  impact: 'safe' | 'disruptive';
+  when: string;
+  available?: boolean;
+}
+
+export interface CommandRegistry {
+  commands: Set<string>;
+  groups: Map<string, Set<string>>;
+}
+
+/**
+ * Create a command registry from available commands
+ */
+export function createCommandRegistry(commands: string[]): CommandRegistry {
+  const commandSet = new Set(commands);
+  const groups = new Map<string, Set<string>>();
+  
+  // Group commands by prefix (e.g., "devlink:apply" -> group "devlink")
+  for (const cmd of commands) {
+    const [group, ...rest] = cmd.split(':');
+    if (group && rest.length > 0) {
+      if (!groups.has(group)) {
+        groups.set(group, new Set());
+      }
+      groups.get(group)!.add(rest.join(':'));
+    }
+  }
+  
+  return {
+    commands: commandSet,
+    groups
+  };
+}
+
+/**
+ * Check if a command is available in the registry
+ */
+export function isCommandAvailable(
+  command: string, 
+  registry: CommandRegistry
+): boolean {
+  // Handle full command strings like "kb devlink apply"
+  if (command.startsWith('kb ')) {
+    const parts = command.split(' ');
+    if (parts.length >= 3 && parts[1] && parts[2]) {
+      const group = parts[1];
+      const subcommand = parts[2];
+      const fullCommand = `${group}:${subcommand}`;
+      return registry.commands.has(fullCommand);
+    }
+  }
+  
+  // Handle direct command names like "devlink:apply"
+  return registry.commands.has(command);
+}
+
+/**
+ * Validate suggestions against available commands
+ */
+export function validateSuggestions(
+  suggestions: CommandSuggestion[],
+  registry: CommandRegistry
+): CommandSuggestion[] {
+  return suggestions.map(suggestion => ({
+    ...suggestion,
+    available: isCommandAvailable(suggestion.command, registry)
+  })).filter(suggestion => suggestion.available);
+}
+
+/**
+ * Generate common devlink suggestions
+ */
+export function generateDevlinkSuggestions(
+  warningCodes: Set<string>,
+  context: { undo?: { available: boolean } },
+  registry: CommandRegistry
+): CommandSuggestion[] {
+  const suggestions: CommandSuggestion[] = [];
+
+  // LOCK_MISMATCH -> apply
+  if (warningCodes.has('LOCK_MISMATCH')) {
+    suggestions.push({
+      id: 'SYNC_LOCK',
+      command: 'kb devlink apply',
+      args: ['--yes'],
+      description: 'Apply changes to sync manifests',
+      impact: 'safe',
+      when: 'LOCK_MISMATCH'
+    });
+  }
+
+  // BACKUP_MISSING -> freeze
+  if (warningCodes.has('BACKUP_MISSING')) {
+    suggestions.push({
+      id: 'CREATE_BACKUP',
+      command: 'kb devlink freeze',
+      args: ['--replace'],
+      description: 'Create a fresh backup',
+      impact: 'safe',
+      when: 'BACKUP_MISSING'
+    });
+  }
+
+  // STALE_LOCK -> freeze
+  if (warningCodes.has('STALE_LOCK')) {
+    suggestions.push({
+      id: 'REFRESH_LOCK',
+      command: 'kb devlink freeze',
+      args: ['--pin=caret'],
+      description: 'Refresh lock file',
+      impact: 'safe',
+      when: 'STALE_LOCK'
+    });
+  }
+
+  // STALE_YALC_ARTIFACTS -> clean
+  if (warningCodes.has('STALE_YALC_ARTIFACTS')) {
+    suggestions.push({
+      id: 'CLEAN_YALC',
+      command: 'kb devlink clean',
+      args: [],
+      description: 'Remove yalc artifacts',
+      impact: 'safe',
+      when: 'STALE_YALC_ARTIFACTS'
+    });
+  }
+
+  // PROTOCOL_CONFLICTS -> clean --hard
+  if (warningCodes.has('PROTOCOL_CONFLICTS')) {
+    suggestions.push({
+      id: 'FIX_PROTOCOLS',
+      command: 'kb devlink clean',
+      args: ['--hard'],
+      description: 'Reset all protocols and reapply',
+      impact: 'disruptive',
+      when: 'PROTOCOL_CONFLICTS'
+    });
+  }
+
+  // Undo suggestion
+  if (context.undo?.available) {
+    suggestions.push({
+      id: 'UNDO_LAST',
+      command: 'kb devlink undo',
+      args: [],
+      description: 'Revert last operation',
+      impact: 'safe',
+      when: 'BACKUP_AVAILABLE'
+    });
+  }
+
+  // Validate and return only available suggestions
+  return validateSuggestions(suggestions, registry);
+}
+
+
+/**
+ * Generate quick actions for common scenarios
+ */
+export function generateQuickActions(
+  hasWarnings: boolean,
+  registry: CommandRegistry,
+  group: string = 'devlink'
+): CommandSuggestion[] {
+  if (!hasWarnings) {return [];}
+
+  const quickActions: CommandSuggestion[] = [
+    {
+      id: 'QUICK_CLEAN',
+      command: `kb ${group} clean`,
+      args: [],
+      description: 'Clean artifacts',
+      impact: 'safe',
+      when: 'QUICK_ACTIONS'
+    },
+    {
+      id: 'QUICK_PLAN',
+      command: `kb ${group} plan`,
+      args: [],
+      description: 'Create plan',
+      impact: 'safe',
+      when: 'QUICK_ACTIONS'
+    },
+    {
+      id: 'QUICK_APPLY',
+      command: `kb ${group} apply`,
+      args: [],
+      description: 'Apply changes',
+      impact: 'safe',
+      when: 'QUICK_ACTIONS'
+    }
+  ];
+
+  return validateSuggestions(quickActions, registry);
+}

package/packages/shared-cli-ui/src/debug/components/output.ts

@@ -0,0 +1,141 @@
+import { box } from '../../format';
+import { formatDebugEntryAI, formatDebugEntriesAI, shouldUseAIFormat } from '../formatters/ai';
+import {
+  formatDebugEntryHuman,
+  formatDebugEntriesHuman,
+  type HumanFormatterOptions,
+} from '../formatters/human';
+import { formatTimelineWithSummary } from '../formatters/timeline';
+import type { DebugDetailLevel, DebugEntry, DebugFormat } from '../types';
+
+export interface DebugOutputOptions extends HumanFormatterOptions {
+  format?: DebugFormat;
+  detailLevel?: DebugDetailLevel;
+  useTimeline?: boolean;
+}
+
+export function formatDebugOutput(entry: DebugEntry, options: DebugOutputOptions = {}): string {
+  if (shouldUseAIFormat(options.format)) {
+    return formatDebugEntryAI(entry);
+  }
+
+  return formatDebugEntryHuman(entry, options);
+}
+
+export function formatDebugOutputs(entries: DebugEntry[], options: DebugOutputOptions = {}): string {
+  if (shouldUseAIFormat(options.format)) {
+    return formatDebugEntriesAI(entries);
+  }
+
+  if (options.useTimeline) {
+    return formatTimelineWithSummary(entries);
+  }
+
+  return formatDebugEntriesHuman(entries, options);
+}
+
+export class DebugSection {
+  private readonly entries: DebugEntry[] = [];
+  private readonly title: string;
+  private readonly options: DebugOutputOptions;
+
+  constructor(title: string, options: DebugOutputOptions = {}) {
+    this.title = title;
+    this.options = options;
+  }
+
+  add(entry: DebugEntry): void {
+    this.entries.push(entry);
+  }
+
+  addAll(entries: DebugEntry[]): void {
+    this.entries.push(...entries);
+  }
+
+  clear(): void {
+    this.entries.length = 0;
+  }
+
+  format(): string {
+    if (this.entries.length === 0) {
+      return '';
+    }
+
+    const content = formatDebugOutputs(this.entries, this.options);
+    if (!content) {
+      return '';
+    }
+
+    if (shouldUseAIFormat(this.options.format)) {
+      return content;
+    }
+
+    return box(this.title, content.split('\n'));
+  }
+
+  get count(): number {
+    return this.entries.length;
+  }
+}
+
+export class DebugOutput {
+  private readonly sections = new Map<string, DebugSection>();
+  private readonly globalEntries: DebugEntry[] = [];
+  private readonly options: DebugOutputOptions;
+
+  constructor(options: DebugOutputOptions = {}) {
+    this.options = options;
+  }
+
+  add(entry: DebugEntry): void {
+    this.globalEntries.push(entry);
+  }
+
+  addToSection(sectionName: string, entry: DebugEntry): void {
+    if (!this.sections.has(sectionName)) {
+      this.sections.set(sectionName, new DebugSection(sectionName, this.options));
+    }
+    this.sections.get(sectionName)!.add(entry);
+  }
+
+  getSection(sectionName: string): DebugSection {
+    if (!this.sections.has(sectionName)) {
+      this.sections.set(sectionName, new DebugSection(sectionName, this.options));
+    }
+    return this.sections.get(sectionName)!;
+  }
+
+  format(): string {
+    const parts: string[] = [];
+
+    if (this.globalEntries.length > 0) {
+      const formatted = formatDebugOutputs(this.globalEntries, this.options);
+      if (formatted) {
+        parts.push(formatted);
+      }
+    }
+
+    for (const [, section] of this.sections) {
+      const formatted = section.format();
+      if (formatted) {
+        parts.push(formatted);
+      }
+    }
+
+    return parts.join('\n\n');
+  }
+
+  clear(): void {
+    this.globalEntries.length = 0;
+    this.sections.clear();
+  }
+
+  get totalCount(): number {
+    let count = this.globalEntries.length;
+    for (const section of this.sections.values()) {
+      count += section.count;
+    }
+    return count;
+  }
+}
+