@fragments-sdk/cli 0.2.2

package/src/viewer/bin.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { createDevServer } from './server.js';
+import { runCommand } from './cli/index.js';
+
+async function startDevServer(): Promise<void> {
+  const args = process.argv.slice(2);
+  const portArg = args.find((arg) => arg.startsWith('--port='));
+  const port = portArg ? parseInt(portArg.split('=')[1], 10) : 6006;
+  const noOpen = args.includes('--no-open');
+
+  console.log(pc.cyan(`\n${BRAND.name} Dev Server\n`));
+  console.log(pc.dim('Starting development server...\n'));
+
+  try {
+    const server = await createDevServer({
+      port,
+      open: !noOpen,
+    });
+
+    const address = server.httpServer?.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+
+    console.log(pc.green(`✓ Server running at http://localhost:${actualPort}\n`));
+    console.log(pc.dim('Press Ctrl+C to stop\n'));
+  } catch (error) {
+    console.error(pc.red('Failed to start server:'), error);
+    process.exit(1);
+  }
+}
+
+function showHelp(): void {
+  console.log(pc.cyan(`\n${BRAND.name} CLI\n`));
+  console.log(`Usage: ${BRAND.cliCommand} <command> [options]\n`);
+  console.log('Commands:');
+  console.log('  dev              Start the development server (default)');
+  console.log('  scan <dir>       Scan codebase for component usage');
+  console.log('  health           Generate design system health report');
+  console.log('');
+  console.log('Dev Server Options:');
+  console.log('  --port=<port>    Port to run on (default: 6006)');
+  console.log('  --no-open        Don\'t open browser automatically');
+  console.log('');
+  console.log('Scan Options:');
+  console.log('  --format=<fmt>   Output format: table, json (default: table)');
+  console.log('  --component=<n>  Filter to specific component');
+  console.log('  --verbose        Show detailed usage info');
+  console.log('');
+  console.log('Health Options:');
+  console.log('  --format=<fmt>   Output format: table, json, markdown (default: table)');
+  console.log('  --scan=<dir>     Include codebase usage scan');
+  console.log('  --ci             CI mode: exit 1 if score below threshold');
+  console.log('  --threshold=<n>  Minimum score for CI mode (default: 80)');
+  console.log('');
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // Show help
+  if (command === '--help' || command === '-h' || command === 'help') {
+    showHelp();
+    return;
+  }
+
+  // Route to subcommands
+  if (command === 'scan' || command === 'health') {
+    await runCommand(command, args.slice(1));
+    return;
+  }
+
+  // Default: start dev server (handles 'dev' command or no command)
+  if (!command || command === 'dev' || command.startsWith('--')) {
+    await startDevServer();
+    return;
+  }
+
+  // Unknown command
+  console.error(pc.red(`Unknown command: ${command}`));
+  console.log(pc.dim(`Run "${BRAND.cliCommand} --help" for usage information.\n`));
+  process.exit(1);
+}
+
+main();

package/src/viewer/cli/health.ts

@@ -0,0 +1,256 @@
+/**
+ * Health Command
+ * Generates a comprehensive design system health report
+ */
+
+import pc from 'picocolors';
+import fs from 'fs';
+import path from 'path';
+import { BRAND } from '../../core/index.js';
+import { loadConfig } from '../../core/node.js';
+import { scanForUsages } from '../intelligence/usageScanner.js';
+import { generateHealthReport, formatHealthReportAsMarkdown, type HealthReport } from '../intelligence/healthReport.js';
+import {
+  parseArgs,
+  createSpinner,
+  formatScore,
+  printHeader,
+  printKV,
+  printWarning,
+  printSuccess,
+  formatList,
+} from './utils.js';
+
+type OutputFormat = 'table' | 'json' | 'markdown';
+
+interface HealthCommandOptions {
+  format: OutputFormat;
+  scanDir?: string;
+  ci: boolean;
+  threshold: number;
+}
+
+function parseOptions(args: string[]): HealthCommandOptions {
+  const { options } = parseArgs(args);
+
+  return {
+    format: (options.format as OutputFormat) || 'table',
+    scanDir: options.scan as string | undefined,
+    ci: !!options.ci,
+    threshold: options.threshold ? parseInt(options.threshold as string, 10) : 80,
+  };
+}
+
+/**
+ * Load segments from the project
+ */
+async function loadSegments(): Promise<Array<{ path: string; segment: any }>> {
+  const configResult = await loadConfig();
+
+  if (!configResult) {
+    throw new Error('No fragments.config.ts found. Run this command from a Fragments project.');
+  }
+
+  const { config } = configResult;
+
+  // Try to load compiled segments
+  const segmentsPath = path.resolve(process.cwd(), config.outFile || `${BRAND.dataDir}/${BRAND.outFile}`);
+
+  if (fs.existsSync(segmentsPath)) {
+    const data = JSON.parse(fs.readFileSync(segmentsPath, 'utf-8'));
+    return Object.entries(data.segments || {}).map(([name, segment]: [string, any]) => ({
+      path: segment.filePath || name,
+      segment: {
+        meta: segment.meta || { name, description: '', category: '' },
+        usage: segment.usage || { when: [], whenNot: [] },
+        props: segment.props || {},
+        variants: segment.variants || [],
+        relations: segment.relations,
+        contract: segment.contract,
+        _generated: segment._generated,
+        component: () => null, // Placeholder
+      },
+    }));
+  }
+
+  // Fallback: return empty if no compiled segments
+  console.log(pc.yellow(`No compiled segments found. Run \`${BRAND.cliCommand} build\` first for complete analysis.`));
+  return [];
+}
+
+function formatGrade(grade: string): string {
+  switch (grade) {
+    case 'A':
+      return pc.green(pc.bold(grade));
+    case 'B':
+      return pc.cyan(grade);
+    case 'C':
+      return pc.yellow(grade);
+    case 'D':
+      return pc.magenta(grade);
+    case 'F':
+      return pc.red(pc.bold(grade));
+    default:
+      return grade;
+  }
+}
+
+function formatTableOutput(report: HealthReport): void {
+  console.log(pc.cyan(`\n${BRAND.name} Health Report\n`));
+  console.log(pc.dim(`Generated: ${new Date(report.generatedAt).toLocaleString()}\n`));
+
+  // Overall score
+  const scoreColor = report.overallScore >= 80 ? pc.green : report.overallScore >= 60 ? pc.yellow : pc.red;
+  console.log(`  ${pc.bold('Overall Score:')} ${scoreColor(pc.bold(`${report.overallScore}%`))}\n`);
+
+  // Grade summary
+  console.log(pc.bold('  Category Grades:\n'));
+  console.log(`    Usage:         ${formatGrade(report.grades.usage)}  (${report.usage.adoptionRate}% adoption)`);
+  console.log(`    Style Drift:   ${formatGrade(report.grades.drift)}  (${report.styleDrift.averageCompliance}% compliance)`);
+  console.log(`    Documentation: ${formatGrade(report.grades.documentation)}  (${report.documentation.documentationRate}% documented)`);
+  console.log(`    Token Usage:   ${formatGrade(report.grades.tokens)}  (${report.tokens.tokenizationRate}% tokenized)`);
+  console.log('');
+
+  // Usage section
+  printHeader('Usage Statistics');
+  printKV('Total Components', report.usage.totalComponents.toString());
+  printKV('Used Components', report.usage.usedComponents.toString());
+  printKV('Adoption Rate', formatScore(report.usage.adoptionRate));
+
+  if (report.usage.mostUsed.length > 0) {
+    console.log(pc.dim('\n  Most Used:'));
+    for (const item of report.usage.mostUsed.slice(0, 5)) {
+      console.log(`    ${pc.cyan(item.component)}: ${item.count} uses`);
+    }
+  }
+
+  if (report.usage.unusedComponents.length > 0 && report.usage.unusedComponents.length <= 5) {
+    console.log(pc.dim('\n  Unused:'));
+    for (const name of report.usage.unusedComponents) {
+      printWarning(name);
+    }
+  } else if (report.usage.unusedComponents.length > 5) {
+    printWarning(`${report.usage.unusedComponents.length} unused components`);
+  }
+
+  // Style Drift section
+  printHeader('Style Drift Analysis');
+  printKV('Components with Drift', report.styleDrift.componentsWithDrift.toString());
+  printKV('Total Drifts', report.styleDrift.totalDrifts.toString());
+  printKV('Average Compliance', formatScore(report.styleDrift.averageCompliance));
+
+  if (report.styleDrift.bySeverity.high > 0) {
+    console.log('');
+    printWarning(`${report.styleDrift.bySeverity.high} high-severity drift(s) - affects brand identity`);
+  }
+
+  if (report.styleDrift.worstOffenders.length > 0) {
+    console.log(pc.dim('\n  Needs Attention:'));
+    for (const item of report.styleDrift.worstOffenders.slice(0, 3)) {
+      console.log(`    ${pc.red('!')} ${item.component} (${item.variant}): ${item.driftCount} drifts`);
+    }
+  }
+
+  // Documentation section
+  printHeader('Documentation Coverage');
+  printKV('Documented', `${report.documentation.documented} components`);
+  printKV('Coverage', formatScore(report.documentation.documentationRate));
+
+  if (report.documentation.missingDescriptions.length > 0) {
+    printWarning(`${report.documentation.missingDescriptions.length} missing descriptions`);
+  }
+
+  if (report.documentation.missingUsage.length > 0) {
+    printWarning(`${report.documentation.missingUsage.length} missing usage guidelines`);
+  }
+
+  // Token section
+  printHeader('Design Token Usage');
+  printKV('Token Compliance', formatScore(report.tokens.complianceScore));
+  printKV('Tokenized Values', report.tokens.tokenizedValues.toString());
+  printKV('Hardcoded Values', report.tokens.hardcodedValues.toString(), report.tokens.hardcodedValues > 0 ? pc.yellow : undefined);
+
+  // Recommendations
+  if (report.recommendations.length > 0) {
+    printHeader('Recommendations');
+    console.log('');
+    for (const rec of report.recommendations) {
+      console.log(`  ${pc.yellow('→')} ${rec}`);
+    }
+  }
+
+  console.log('');
+}
+
+function formatJsonOutput(report: HealthReport): void {
+  console.log(JSON.stringify(report, null, 2));
+}
+
+function formatMarkdownOutput(report: HealthReport): void {
+  console.log(formatHealthReportAsMarkdown(report));
+}
+
+/**
+ * Run the health command
+ */
+export async function healthCommand(args: string[]): Promise<void> {
+  const options = parseOptions(args);
+
+  const spinner = createSpinner('Analyzing design system health...');
+  spinner.start();
+
+  try {
+    // Load segments
+    spinner.update('Loading segments...');
+    const segments = await loadSegments();
+
+    if (segments.length === 0) {
+      spinner.stop(false, 'No segments found');
+      console.log(pc.yellow(`\nNo components to analyze. Create segment files or run \`${BRAND.cliCommand} build\`.\n`));
+      return;
+    }
+
+    // Run usage scan if directory provided
+    let usageScan;
+    if (options.scanDir) {
+      spinner.update(`Scanning ${options.scanDir} for component usage...`);
+      usageScan = await scanForUsages({ directory: options.scanDir });
+    }
+
+    // Generate report
+    spinner.update('Generating health report...');
+    const report = generateHealthReport({
+      segments,
+      usageScan,
+      // Note: Drift reports would require running the viewer and extracting styles
+      // For CLI, we focus on what can be statically analyzed
+    });
+
+    spinner.stop(true, 'Health analysis complete');
+
+    // Output
+    switch (options.format) {
+      case 'json':
+        formatJsonOutput(report);
+        break;
+      case 'markdown':
+        formatMarkdownOutput(report);
+        break;
+      default:
+        formatTableOutput(report);
+    }
+
+    // CI mode: exit with error if below threshold
+    if (options.ci) {
+      if (report.overallScore < options.threshold) {
+        console.log(pc.red(`\nCI Check Failed: Score ${report.overallScore}% is below threshold ${options.threshold}%\n`));
+        process.exit(1);
+      } else {
+        console.log(pc.green(`\nCI Check Passed: Score ${report.overallScore}% meets threshold ${options.threshold}%\n`));
+      }
+    }
+  } catch (error) {
+    spinner.stop(false, 'Health analysis failed');
+    throw error;
+  }
+}

package/src/viewer/cli/index.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI Command Router
+ * Routes subcommands to their respective handlers
+ */
+
+import pc from 'picocolors';
+import { scanCommand } from './scan.js';
+import { healthCommand } from './health.js';
+
+export type CommandName = 'scan' | 'health';
+
+/**
+ * Run a CLI command with the given arguments
+ */
+export async function runCommand(command: CommandName, args: string[]): Promise<void> {
+  try {
+    switch (command) {
+      case 'scan':
+        await scanCommand(args);
+        break;
+      case 'health':
+        await healthCommand(args);
+        break;
+      default:
+        console.error(pc.red(`Unknown command: ${command}`));
+        process.exit(1);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(pc.red(`\nError: ${message}\n`));
+    process.exit(1);
+  }
+}

package/src/viewer/cli/scan.ts

@@ -0,0 +1,124 @@
+/**
+ * Scan Command
+ * Scans a codebase for component usage
+ */
+
+import pc from 'picocolors';
+import path from 'path';
+import { scanForUsages, type FullScanResult, type UsageScanResult } from '../intelligence/usageScanner.js';
+import { parseArgs, createSpinner, formatTable, formatDuration, printHeader, printKV } from './utils.js';
+
+type OutputFormat = 'table' | 'json';
+
+interface ScanCommandOptions {
+  format: OutputFormat;
+  component?: string;
+  verbose: boolean;
+}
+
+function parseOptions(args: string[]): { directory: string; options: ScanCommandOptions } {
+  const { positional, options } = parseArgs(args);
+
+  return {
+    directory: positional[0] || '.',
+    options: {
+      format: (options.format as OutputFormat) || 'table',
+      component: options.component as string | undefined,
+      verbose: !!options.verbose || !!options.v,
+    },
+  };
+}
+
+function formatTableOutput(result: FullScanResult, options: ScanCommandOptions): void {
+  const { results, summary } = result;
+
+  printHeader('Component Usage Scan');
+  printKV('Directory scanned', path.resolve(result.results[0]?.usages[0]?.file || '.').split(path.sep).slice(0, -1).join(path.sep) || '.');
+  printKV('Files scanned', summary.totalFiles.toString());
+  printKV('Files with usage', summary.filesWithUsage.toString());
+  printKV('Scan time', formatDuration(summary.scanTimeMs));
+  console.log('');
+
+  if (results.length === 0) {
+    console.log(pc.yellow('  No component usages found.\n'));
+    return;
+  }
+
+  // Summary table
+  const headers = ['Component', 'Files', 'Total Uses'];
+  const rows = results.map((r) => [
+    r.component,
+    String(r.usages.length),
+    String(r.totalUsages),
+  ]);
+
+  console.log(formatTable(headers, rows));
+  console.log('');
+
+  // Verbose: show file details
+  if (options.verbose) {
+    console.log(pc.bold('\nDetailed Usage:\n'));
+
+    for (const r of results) {
+      console.log(pc.cyan(`  ${r.component}`));
+      for (const usage of r.usages) {
+        const relativePath = path.relative(process.cwd(), usage.file);
+        const importIcon = usage.importType === 'named' ? '{}' : usage.importType === 'default' ? '=>' : '*';
+        console.log(pc.dim(`    ${importIcon} ${relativePath}:${usage.line} (${usage.usageCount} uses)`));
+      }
+      console.log('');
+    }
+  }
+
+  // Summary footer
+  console.log(pc.dim('─'.repeat(50)));
+  console.log(`  ${pc.bold(String(summary.totalComponents))} components used ${pc.bold(String(summary.totalUsages))} times across ${pc.bold(String(summary.filesWithUsage))} files`);
+  console.log('');
+}
+
+function formatJsonOutput(result: FullScanResult): void {
+  const output = {
+    summary: result.summary,
+    components: result.results.map((r) => ({
+      name: r.component,
+      totalUsages: r.totalUsages,
+      fileCount: r.usages.length,
+      usages: r.usages.map((u) => ({
+        file: path.relative(process.cwd(), u.file),
+        line: u.line,
+        importType: u.importType,
+        usageCount: u.usageCount,
+      })),
+    })),
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * Run the scan command
+ */
+export async function scanCommand(args: string[]): Promise<void> {
+  const { directory, options } = parseOptions(args);
+
+  const spinner = createSpinner(`Scanning ${directory} for component usage...`);
+  spinner.start();
+
+  try {
+    const result = await scanForUsages({
+      directory,
+      components: options.component ? [options.component] : undefined,
+    });
+
+    spinner.stop(true, `Scanned ${result.summary.totalFiles} files in ${formatDuration(result.summary.scanTimeMs)}`);
+
+    if (options.format === 'json') {
+      formatJsonOutput(result);
+    } else {
+      formatTableOutput(result, options);
+    }
+  } catch (error) {
+    spinner.stop(false, 'Scan failed');
+    throw error;
+  }
+}

package/src/viewer/cli/utils.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared CLI Utilities
+ * Common helpers for CLI commands
+ */
+
+import pc from 'picocolors';
+
+/**
+ * Parse command line arguments into options object
+ */
+export function parseArgs(args: string[]): {
+  positional: string[];
+  options: Record<string, string | boolean>;
+} {
+  const positional: string[] = [];
+  const options: Record<string, string | boolean> = {};
+
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const [key, value] = arg.slice(2).split('=');
+      options[key] = value ?? true;
+    } else if (arg.startsWith('-')) {
+      const key = arg.slice(1);
+      options[key] = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { positional, options };
+}
+
+/**
+ * Spinner for async operations
+ */
+export function createSpinner(message: string): {
+  start: () => void;
+  stop: (success?: boolean, finalMessage?: string) => void;
+  update: (message: string) => void;
+} {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let frameIndex = 0;
+  let interval: NodeJS.Timeout | null = null;
+  let currentMessage = message;
+
+  return {
+    start() {
+      process.stdout.write('\n');
+      interval = setInterval(() => {
+        process.stdout.write(`\r${pc.cyan(frames[frameIndex])} ${currentMessage}`);
+        frameIndex = (frameIndex + 1) % frames.length;
+      }, 80);
+    },
+    stop(success = true, finalMessage?: string) {
+      if (interval) {
+        clearInterval(interval);
+        interval = null;
+      }
+      const icon = success ? pc.green('✓') : pc.red('✗');
+      process.stdout.write(`\r${icon} ${finalMessage || currentMessage}\n`);
+    },
+    update(message: string) {
+      currentMessage = message;
+    },
+  };
+}
+
+/**
+ * Format a table for console output
+ */
+export function formatTable(
+  headers: string[],
+  rows: string[][],
+  options: { padding?: number; maxWidth?: number } = {}
+): string {
+  const { padding = 2, maxWidth = 50 } = options;
+
+  // Calculate column widths
+  const widths = headers.map((h, i) => {
+    const columnValues = [h, ...rows.map((r) => r[i] || '')];
+    return Math.min(maxWidth, Math.max(...columnValues.map((v) => v.length)));
+  });
+
+  // Format header
+  const headerLine = headers
+    .map((h, i) => h.padEnd(widths[i] + padding))
+    .join('');
+  const separator = widths.map((w) => '─'.repeat(w + padding)).join('');
+
+  // Format rows
+  const formattedRows = rows.map((row) =>
+    row.map((cell, i) => (cell || '').padEnd(widths[i] + padding)).join('')
+  );
+
+  return [
+    pc.bold(headerLine),
+    pc.dim(separator),
+    ...formattedRows,
+  ].join('\n');
+}
+
+/**
+ * Format bytes as human-readable size
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+/**
+ * Format duration in milliseconds
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+/**
+ * Format a score with color based on thresholds
+ */
+export function formatScore(score: number, thresholds = { good: 80, warn: 50 }): string {
+  const formatted = `${score}%`;
+  if (score >= thresholds.good) return pc.green(formatted);
+  if (score >= thresholds.warn) return pc.yellow(formatted);
+  return pc.red(formatted);
+}
+
+/**
+ * Print a section header
+ */
+export function printHeader(title: string): void {
+  console.log(`\n${pc.bold(pc.cyan(title))}`);
+  console.log(pc.dim('─'.repeat(title.length + 4)));
+}
+
+/**
+ * Print a key-value pair
+ */
+export function printKV(key: string, value: string | number, color?: (s: string) => string): void {
+  const valueStr = String(value);
+  console.log(`  ${pc.dim(key + ':')} ${color ? color(valueStr) : valueStr}`);
+}
+
+/**
+ * Print a warning message
+ */
+export function printWarning(message: string): void {
+  console.log(pc.yellow(`  ⚠ ${message}`));
+}
+
+/**
+ * Print an error message
+ */
+export function printError(message: string): void {
+  console.log(pc.red(`  ✗ ${message}`));
+}
+
+/**
+ * Print a success message
+ */
+export function printSuccess(message: string): void {
+  console.log(pc.green(`  ✓ ${message}`));
+}
+
+/**
+ * Format a list for bullet points
+ */
+export function formatList(items: string[], bullet = '•'): string {
+  return items.map((item) => `  ${pc.dim(bullet)} ${item}`).join('\n');
+}