@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/src/__tests__/loader-json-mode.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, afterEach, vi, beforeEach } from 'vitest';
+import { setJsonMode, isJsonMode, useLoader, Loader } from '../loader';
+
+// Restore json mode after each test
+afterEach(() => {
+  setJsonMode(false);
+});
+
+describe('setJsonMode / isJsonMode', () => {
+  it('defaults to false', () => {
+    expect(isJsonMode()).toBe(false);
+  });
+
+  it('setJsonMode(true) flips the flag', () => {
+    setJsonMode(true);
+    expect(isJsonMode()).toBe(true);
+  });
+
+  it('setJsonMode(false) resets the flag', () => {
+    setJsonMode(true);
+    setJsonMode(false);
+    expect(isJsonMode()).toBe(false);
+  });
+});
+
+describe('useLoader picks up global json mode', () => {
+  it('creates a Loader with jsonMode=false by default', () => {
+    const loader = useLoader('test');
+    // start() should normally start the interval — but we can verify it doesn't
+    // write anything if we capture stdout
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.start();
+    // Fake enough time for the interval to fire
+    vi.useFakeTimers();
+    vi.advanceTimersByTime(500);
+    vi.useRealTimers();
+    loader.stop();
+    write.mockRestore();
+    // No assertion needed — just verify it doesn't throw
+  });
+
+  it('when setJsonMode(true), useLoader returns a no-op loader', () => {
+    setJsonMode(true);
+    const loader = useLoader('loading...');
+
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.start();
+    loader.succeed('done');
+    loader.fail('error');
+    expect(write).not.toHaveBeenCalled();
+    write.mockRestore();
+  });
+
+  it('explicit jsonMode option overrides global flag', () => {
+    setJsonMode(true);
+    // Explicit false should override the global true
+    const loader = useLoader('test', { jsonMode: false });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.succeed('done');
+    // succeed() writes when jsonMode=false
+    expect(write).toHaveBeenCalled();
+    write.mockRestore();
+  });
+});
+
+describe('Loader in json mode suppresses all output', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('start() does not write to stdout', () => {
+    const loader = new Loader({ text: 'loading...', jsonMode: true });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.start();
+    vi.advanceTimersByTime(1000);
+    expect(write).not.toHaveBeenCalled();
+    write.mockRestore();
+  });
+
+  it('succeed() does not write to stdout', () => {
+    const loader = new Loader({ text: 'loading...', jsonMode: true });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.start();
+    loader.succeed('completed');
+    expect(write).not.toHaveBeenCalled();
+    write.mockRestore();
+  });
+
+  it('fail() does not write to stdout', () => {
+    const loader = new Loader({ text: 'loading...', jsonMode: true });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.start();
+    loader.fail('failed');
+    expect(write).not.toHaveBeenCalled();
+    write.mockRestore();
+  });
+});
+
+describe('Loader in normal mode writes to stdout', () => {
+  it('succeed() writes success symbol to stdout', () => {
+    const loader = new Loader({ text: 'loading...', jsonMode: false });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.succeed('done');
+    expect(write).toHaveBeenCalledWith(expect.stringContaining('done'));
+    write.mockRestore();
+  });
+
+  it('fail() writes error symbol to stdout', () => {
+    const loader = new Loader({ text: 'loading...', jsonMode: false });
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    loader.fail('oops');
+    expect(write).toHaveBeenCalledWith(expect.stringContaining('oops'));
+    write.mockRestore();
+  });
+});

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

@@ -0,0 +1,266 @@
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+import { safeColors } from './colors';
+import { formatSize, formatRelativeTime, safeKeyValue } from './format';
+
+export interface ArtifactInfo {
+  name: string;
+  path: string;
+  size?: number;
+  modified?: Date;
+  description: string;
+}
+
+export interface ArtifactDisplayOptions {
+  showSize?: boolean;
+  showTime?: boolean;
+  showDescription?: boolean;
+  maxItems?: number;
+  title?: string;
+  groupBy?: 'none' | 'type' | 'time';
+}
+
+/**
+ * Display artifacts information in CLI
+ */
+export function displayArtifacts(
+  artifacts: ArtifactInfo[],
+  options: ArtifactDisplayOptions = {},
+): string[] {
+  const {
+    showSize = true,
+    showTime = true,
+    showDescription = false,
+    maxItems = 10,
+    title = 'Generated Artifacts',
+    groupBy = 'none'
+  } = options;
+
+  if (artifacts.length === 0) {
+    return [];
+  }
+
+  // Sort and limit artifacts
+  let sortedArtifacts = artifacts;
+  
+  if (groupBy === 'time') {
+    sortedArtifacts = [...artifacts].sort(
+      (a, b) => (b.modified?.getTime() ?? 0) - (a.modified?.getTime() ?? 0),
+    );
+  } else if (groupBy === 'type') {
+    sortedArtifacts = [...artifacts].sort((a, b) => a.name.localeCompare(b.name));
+  } else {
+    sortedArtifacts = [...artifacts].sort(
+      (a, b) => (b.modified?.getTime() ?? 0) - (a.modified?.getTime() ?? 0),
+    );
+  }
+
+  sortedArtifacts = sortedArtifacts.slice(0, maxItems);
+
+  const lines: string[] = [];
+
+  if (title) {
+    lines.push(safeColors.bold(title));
+  }
+
+  if (groupBy === 'type') {
+    const grouped = sortedArtifacts.reduce((acc, artifact) => {
+      const type = artifact.name.split(' ')[0] || 'Other';
+      if (!acc[type]) {acc[type] = [];}
+      acc[type]!.push(artifact);
+      return acc;
+    }, {} as Record<string, ArtifactInfo[]>);
+
+    Object.entries(grouped).forEach(([type, items], index) => {
+      if (index > 0 || title) {
+        lines.push('');
+      }
+      lines.push(...safeKeyValue({ [type]: '' }, { pad: false }));
+      items.forEach((artifact, artifactIndex) => {
+        if (artifactIndex > 0) {
+          lines.push('');
+        }
+        lines.push(...formatArtifactLines(artifact, {
+          showSize,
+          showTime,
+          showDescription,
+          indent: 2,
+        }));
+      });
+    });
+    return lines;
+  }
+
+  sortedArtifacts.forEach((artifact, index) => {
+    if (index > 0) {
+      lines.push('');
+    }
+    lines.push(...formatArtifactLines(artifact, {
+      showSize,
+      showTime,
+      showDescription,
+      indent: 0,
+    }));
+  });
+
+  return lines;
+}
+
+/**
+ * Format a single artifact line
+ */
+function formatArtifactLines(
+  artifact: ArtifactInfo,
+  options: {
+    showSize: boolean;
+    showTime: boolean;
+    showDescription: boolean;
+    indent: number;
+  },
+): string[] {
+  const { showSize, showTime, showDescription, indent } = options;
+  const relativePath = path.relative(process.cwd(), artifact.path);
+  const lines: string[] = [];
+  lines.push(
+    ...safeKeyValue({ [artifact.name]: relativePath }, { pad: false, indent }),
+  );
+  if (showSize && artifact.size) {
+    lines.push(
+      ...safeKeyValue({ Size: formatSize(artifact.size) }, { pad: false, indent: indent + 2 }),
+    );
+  }
+
+  if (showTime && artifact.modified) {
+    lines.push(
+      ...safeKeyValue({ Updated: formatRelativeTime(artifact.modified) }, { pad: false, indent: indent + 2 }),
+    );
+  }
+
+  if (showDescription && artifact.description) {
+    lines.push(
+      ...safeKeyValue({ Note: artifact.description }, { pad: false, indent: indent + 2 }),
+    );
+  }
+
+  return lines;
+}
+
+/**
+ * Display a single artifact with full details
+ */
+export function displaySingleArtifact(artifact: ArtifactInfo, title?: string): string[] {
+  const relativePath = path.relative(process.cwd(), artifact.path);
+  const lines: string[] = [];
+  
+  if (title) {
+    lines.push('');
+    lines.push(safeColors.bold(title));
+  }
+  
+  lines.push(`  ${safeColors.bold(artifact.name)}: ${safeColors.info(relativePath)}`);
+  
+  if (artifact.size) {
+    lines.push(`    Size: ${formatSize(artifact.size)}`);
+  }
+  
+  if (artifact.modified) {
+    lines.push(`    Modified: ${formatRelativeTime(artifact.modified)}`);
+  }
+  
+  if (artifact.description) {
+    lines.push(`    Description: ${artifact.description}`);
+  }
+  
+  return lines;
+}
+
+/**
+ * Display artifacts in a compact format (for status-like displays)
+ */
+export function displayArtifactsCompact(
+  artifacts: ArtifactInfo[],
+  options: {
+    maxItems?: number;
+    showSize?: boolean;
+    sortByTime?: boolean;
+    showTime?: boolean;
+    title?: string;
+  } = {},
+): string[] {
+  const {
+    maxItems = 5,
+    showSize = true,
+    sortByTime = true,
+    showTime = true,
+    title = 'Artifacts',
+  } = options;
+  
+  if (artifacts.length === 0) {
+    return [];
+  }
+
+  const sortedArtifacts = (sortByTime
+    ? [...artifacts].sort((a, b) => (b.modified?.getTime() ?? 0) - (a.modified?.getTime() ?? 0))
+    : artifacts.slice()
+  ).slice(0, maxItems);
+
+  const lines: string[] = [];
+  lines.push(safeColors.bold(title));
+
+  sortedArtifacts.forEach((artifact, index) => {
+    if (index > 0) {
+      lines.push('');
+    }
+    lines.push(
+      ...formatArtifactLines(artifact, {
+        showSize,
+        showTime,
+        showDescription: false,
+        indent: 0,
+      }),
+    );
+  });
+
+  return lines;
+}
+
+/**
+ * Discover artifacts in a directory based on patterns
+ * 
+ * @param baseDir - Base directory to search for artifacts
+ * @param patterns - Array of artifact patterns to search for
+ * @returns Array of discovered artifacts
+ * 
+ * @example
+ * ```typescript
+ * const artifacts = await discoverArtifacts('.kb/mind', [
+ *   { name: 'Index', pattern: 'index.json', description: 'Main index' },
+ *   { name: 'API Index', pattern: 'api-index.json', description: 'API index' },
+ * ]);
+ * ```
+ */
+export async function discoverArtifacts(
+  baseDir: string,
+  patterns: Array<{ name: string; pattern: string; description?: string }>
+): Promise<ArtifactInfo[]> {
+  const artifacts: ArtifactInfo[] = [];
+
+  for (const artifact of patterns) {
+    const artifactPath = path.join(baseDir, artifact.pattern);
+    try {
+      await fsp.access(artifactPath);
+      const stats = await fsp.stat(artifactPath);
+      artifacts.push({
+        name: artifact.name,
+        path: artifactPath,
+        size: stats.size,
+        modified: stats.mtime,
+        description: artifact.description || ''
+      });
+    } catch {
+      // Skip if file doesn't exist
+    }
+  }
+
+  return artifacts;
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Automatic CLI discovery and registration
+ */
+
+import { MultiCLISuggestions, type CLIPackage } from './multi-cli-suggestions';
+import { extractCommandIds } from './manifest-parser';
+
+export interface CLIDiscoveryOptions {
+  /**
+   * Root directory to search for CLI packages
+   */
+  rootDir?: string;
+  
+  /**
+   * Whether to include dev dependencies
+   */
+  includeDev?: boolean;
+  
+  /**
+   * Custom package patterns to search for
+   */
+  patterns?: string[];
+}
+
+/**
+ * Discover CLI packages in a workspace
+ */
+export async function discoverCLIPackages(
+  options: CLIDiscoveryOptions = {}
+): Promise<CLIPackage[]> {
+  const packages: CLIPackage[] = [];
+  const rootDir = options.rootDir || process.cwd();
+  
+  // Common patterns for CLI packages
+  const patterns = options.patterns || [
+    '**/cli.manifest.ts',
+    '**/cli.manifest.js',
+    '**/src/cli.manifest.ts',
+    '**/src/cli.manifest.js'
+  ];
+
+  try {
+    const { glob } = await import('glob');
+    
+    for (const pattern of patterns) {
+      const files = await glob(pattern, { cwd: rootDir });
+      
+      for (const file of files) {
+        try {
+          const manifestPath = `${rootDir}/${file}`;
+          const manifest = await import(manifestPath);
+          
+          if (manifest.commands && Array.isArray(manifest.commands)) {
+            // Extract package info from path
+            const pathParts = file.split('/');
+            const packageName = pathParts[pathParts.length - 3] || 'unknown';
+            const group = packageName.replace(/-cli$/, '').replace(/^kb-labs-/, '');
+            
+            // Determine priority based on package type
+            let priority = 50;
+            if (group === 'devlink') {priority = 100;}
+            else if (group === 'mind') {priority = 80;}
+            else if (group === 'tox') {priority = 70;}
+            else if (group === 'profiles') {priority = 60;}
+            else if (group === 'ai-review') {priority = 50;}
+            
+            packages.push({
+              name: packageName,
+              group,
+              commands: manifest.commands,
+              priority
+            });
+          }
+        } catch (error) {
+          // Skip invalid manifests
+          console.warn(`Failed to load manifest: ${file}`, error);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn('Failed to discover CLI packages:', error);
+  }
+
+  return packages;
+}
+
+/**
+ * Create a multi-CLI suggestions instance with auto-discovery
+ */
+export async function createAutoDiscoveredCLISuggestions(
+  options: CLIDiscoveryOptions = {}
+): Promise<MultiCLISuggestions> {
+  const manager = new MultiCLISuggestions();
+  const packages = await discoverCLIPackages(options);
+  
+  for (const pkg of packages) {
+    manager.registerPackage(pkg);
+  }
+  
+  return manager;
+}
+
+/**
+ * Get command registry for a specific workspace
+ */
+export async function getWorkspaceCommandRegistry(
+  rootDir: string = process.cwd()
+): Promise<{ registry: any; packages: CLIPackage[] }> {
+  const packages = await discoverCLIPackages({ rootDir });
+  const allCommands: string[] = [];
+  
+  for (const pkg of packages) {
+    allCommands.push(...extractCommandIds(pkg.commands));
+  }
+  
+  const { createCommandRegistry } = await import('./command-suggestions');
+  const registry = createCommandRegistry(allCommands);
+  
+  return { registry, packages };
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Minimalist color utilities for CLI output
+ * Uses strategic color application - only for status, not decoration
+ */
+
+const CSI = '\x1b[';
+const RESET = '\x1b[0m';
+
+const createColor =
+  (...codes: Array<number | string>) =>
+  (text: string): string =>
+    `${CSI}${codes.join(';')}m${text}${RESET}`;
+
+const accentBlue = '38;5;39';
+const accentViolet = '38;5;99';
+const accentTeal = '38;5;51';
+const accentIndigo = '38;5;63';
+const neutral = 37;
+const neutralMuted = 90;
+
+export const colors = {
+  // Semantic colors
+  success: createColor(32),
+  error: createColor(31),
+  warning: createColor(33),
+  info: createColor(36),
+
+  // Accent palette (reused across CLI)
+  primary: createColor(accentBlue),
+  accent: createColor(accentViolet),
+  highlight: createColor(accentTeal),
+  secondary: createColor(accentIndigo),
+  emphasis: createColor('38;5;117'),
+  muted: createColor(neutralMuted),
+  foreground: createColor(neutral),
+
+  // Formatting helpers
+  dim: createColor(2),
+  bold: createColor(1),
+  underline: createColor(4),
+  inverse: createColor(7),
+};
+
+// Base symbols without emojis
+const symbolCharacters = {
+  success: 'OK',
+  error: 'ERR',
+  warning: 'WARN',
+  info: 'ℹ',
+  bullet: '•',
+  clock: 'TIME',
+  folder: 'DIR',
+  package: '›',
+  pointer: '›',
+  section: '│',
+};
+
+export const symbols = {
+  success: colors.success(symbolCharacters.success),
+  error: colors.error(symbolCharacters.error),
+  warning: colors.warning(symbolCharacters.warning),
+  info: colors.info(symbolCharacters.info),
+  bullet: colors.muted(symbolCharacters.bullet),
+  clock: colors.info(symbolCharacters.clock),
+  folder: colors.primary(symbolCharacters.folder),
+  package: colors.accent(symbolCharacters.package),
+  pointer: colors.primary(symbolCharacters.pointer),
+  section: colors.primary(symbolCharacters.section),
+};
+
+// Check if colors are supported
+const isTruthyEnv = (value: string | undefined): boolean => {
+  if (!value) {return false;}
+  const normalized = value.trim().toLowerCase();
+  return normalized !== '' && normalized !== '0' && normalized !== 'false' && normalized !== 'off';
+};
+
+export const supportsColor = (() => {
+  if (typeof process === 'undefined') {return false;}
+
+  const forceColor = process.env.FORCE_COLOR;
+  if (isTruthyEnv(process.env.NO_COLOR)) {
+    return false;
+  }
+  if (isTruthyEnv(forceColor)) {
+    return true;
+  }
+
+  if (!process.stdout) {return false;}
+
+  if (process.stdout.isTTY === false) {
+    return false;
+  }
+
+  return true;
+})();
+
+// Color functions that respect NO_COLOR
+const passthrough =
+  (fn: (text: string) => string) =>
+  (text: string): string =>
+    supportsColor ? fn(text) : text;
+
+export const safeColors = {
+  success: passthrough(colors.success),
+  error: passthrough(colors.error),
+  warning: passthrough(colors.warning),
+  info: passthrough(colors.info),
+  accent: passthrough(colors.accent),
+  primary: passthrough(colors.primary),
+  highlight: passthrough(colors.highlight),
+  secondary: passthrough(colors.secondary),
+  emphasis: passthrough(colors.emphasis),
+  foreground: passthrough(colors.foreground),
+  muted: passthrough(colors.muted),
+  dim: passthrough(colors.dim),
+  bold: passthrough(colors.bold),
+  underline: passthrough(colors.underline),
+  inverse: passthrough(colors.inverse),
+};
+
+export const safeSymbols = {
+  success: supportsColor ? symbols.success : '✓',
+  error: supportsColor ? symbols.error : '✗',
+  warning: supportsColor ? symbols.warning : '⚠',
+  info: supportsColor ? symbols.info : '→',
+  bullet: supportsColor ? symbols.bullet : '•',
+  clock: supportsColor ? symbols.clock : 'time',
+  folder: supportsColor ? symbols.folder : 'dir',
+  package: supportsColor ? symbols.package : '›',
+  pointer: supportsColor ? symbols.pointer : '>',
+  section: supportsColor ? symbols.section : '|',
+  // Box-drawing characters for modern side border
+  separator: '─',      // Horizontal line
+  border: '│',         // Vertical line
+  topLeft: '┌',        // Top-left corner
+  topRight: '┐',       // Top-right corner
+  bottomLeft: '└',     // Bottom-left corner
+  bottomRight: '┘',    // Bottom-right corner
+  leftT: '├',          // Left T-junction
+  rightT: '┤',         // Right T-junction
+};