@fragments-sdk/cli 0.2.2

package/src/bin.ts

@@ -0,0 +1,916 @@
+#!/usr/bin/env node
+/**
+ * fragments CLI - Design system documentation and compliance tool
+ *
+ * This file registers all commands with Commander. Command implementations
+ * are in the commands/ directory.
+ */
+
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { BRAND } from './core/index.js';
+import { loadConfig } from './core/node.js';
+
+// Import command implementations
+import { validate } from './commands/validate.js';
+import { build } from './commands/build.js';
+import { context } from './commands/context.js';
+import { list } from './commands/list.js';
+import { reset } from './commands/reset.js';
+import { dev } from './commands/dev.js';
+import { compare } from './commands/compare.js';
+import { verify } from './commands/verify.js';
+import { audit } from './commands/audit.js';
+import { a11y } from './commands/a11y.js';
+import { storygen } from './commands/storygen.js';
+import { metrics } from './commands/metrics.js';
+import { baseline } from './commands/baseline.js';
+import { add } from './commands/add.js';
+import { linkFigma, linkStorybook } from './commands/link/index.js';
+import { enhance } from './commands/enhance.js';
+import { scan } from './commands/scan.js';
+
+// Import existing commands that were already extracted
+import { runScreenshotCommand } from './screenshot.js';
+import { runDiffCommand } from './diff.js';
+import { runAnalyzeCommand } from './analyze.js';
+
+const program = new Command();
+
+program
+  .name(BRAND.cliCommand)
+  .description(`${BRAND.name} - Design system documentation and compliance tool`)
+  .version('0.1.0');
+
+// ============================================================================
+// VALIDATE COMMAND
+// ============================================================================
+program
+  .command('validate')
+  .description('Validate fragment files')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--schema', 'Validate fragment schema only')
+  .option('--coverage', 'Validate coverage only')
+  .action(async (options) => {
+    try {
+      const result = await validate(options);
+      if (!result.valid) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// BUILD COMMAND
+// ============================================================================
+program
+  .command('build')
+  .description(`Build compiled ${BRAND.outFile} and ${BRAND.dataDir}/ directory`)
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--registry', `Also generate ${BRAND.dataDir}/${BRAND.registryFile} and ${BRAND.contextFile}`)
+  .option('--registry-only', `Only generate ${BRAND.dataDir}/ directory (skip ${BRAND.outFile})`)
+  .option('--from-source', 'Build from source code (zero-config, no fragment files needed)')
+  .option('--skip-usage', 'Skip usage analysis when building from source')
+  .option('--skip-storybook', 'Skip Storybook parsing when building from source')
+  .option('-v, --verbose', 'Verbose output')
+  .action(async (options) => {
+    try {
+      const result = await build({
+        config: options.config,
+        output: options.output,
+        registry: options.registry,
+        registryOnly: options.registryOnly,
+        fromSource: options.fromSource,
+        skipUsage: options.skipUsage,
+        skipStorybook: options.skipStorybook,
+        verbose: options.verbose,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// CONTEXT COMMAND
+// ============================================================================
+program
+  .command('context')
+  .description('Generate AI-ready context for your design system')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-i, --input <path>', `Path to ${BRAND.outFile} (builds if not provided)`)
+  .option('-f, --format <format>', 'Output format (markdown/json)', 'markdown')
+  .option('--compact', 'Minimal output for token efficiency')
+  .option('--code', 'Include code examples')
+  .option('--relations', 'Include component relationships')
+  .option('--tokens', 'Only output token estimate')
+  .action(async (options) => {
+    try {
+      const result = await context({
+        config: options.config,
+        input: options.input,
+        format: options.format,
+        compact: options.compact,
+        includeCode: options.code,
+        includeRelations: options.relations,
+        tokensOnly: options.tokens,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// AI COMMAND (for Claude Desktop integration)
+// ============================================================================
+program
+  .command('ai')
+  .description('Generate context optimized for AI assistants (Claude Desktop)')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--live', 'Connect to running dev server for live data')
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (options) => {
+    try {
+      // If live mode, fetch from dev server
+      if (options.live) {
+        const baseUrl = `http://localhost:${options.port}`;
+        const response = await fetch(`${baseUrl}/${BRAND.nameLower}/context?format=markdown`);
+        if (!response.ok) {
+          throw new Error('Failed to fetch context. Make sure dev server is running.');
+        }
+        const contextContent = await response.text();
+        console.log(contextContent);
+      } else {
+        // Build and generate context
+        const result = await context({
+          config: options.config,
+          format: 'markdown',
+          compact: false,
+          includeCode: true,
+          includeRelations: true,
+        });
+        if (!result.success) {
+          process.exit(1);
+        }
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// LIST COMMAND
+// ============================================================================
+program
+  .command('list')
+  .description('List all discovered fragment files')
+  .option('-c, --config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      await list(options);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// RESET COMMAND
+// ============================================================================
+program
+  .command('reset')
+  .description('Reset to initial state (delete all generated files)')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .option('--dry-run', 'Show what would be deleted without deleting')
+  .action(async (options) => {
+    try {
+      await reset(options);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// LINK COMMAND (parent for subcommands)
+// ============================================================================
+const linkCommand = program
+  .command('link')
+  .description('Link external resources (Figma designs, Storybook stories) to fragments');
+
+// Link Figma subcommand
+linkCommand
+  .command('figma')
+  .argument('[figma-url]', 'Figma file URL to link components from')
+  .description('Interactive wizard to link Figma components to code')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--auto', 'Auto-link matching components without prompts')
+  .option('--dry-run', 'Show matches without updating files')
+  .option('--no-variants', 'Skip linking individual variants to their Figma frames')
+  .action(async (figmaUrl, options) => {
+    try {
+      await linkFigma(figmaUrl, {
+        config: options.config,
+        auto: options.auto,
+        dryRun: options.dryRun,
+        variants: options.variants,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// Link Storybook subcommand
+linkCommand
+  .command('storybook')
+  .description('Bootstrap fragments from existing Storybook stories')
+  .option('-c, --config <path>', 'Path to .storybook/main.* config')
+  .option('-o, --out <dir>', 'Output directory for fragment files')
+  .option('--yes', 'Skip confirmation prompts')
+  .option('--dry-run', 'Preview what would be generated without writing files')
+  .option('--include <glob>', 'Only process stories matching glob')
+  .option('--exclude <glob>', 'Skip stories matching glob')
+  .action(async (options) => {
+    try {
+      await linkStorybook({
+        config: options.config,
+        out: options.out,
+        yes: options.yes,
+        dryRun: options.dryRun,
+        include: options.include,
+        exclude: options.exclude,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// DEV COMMAND
+// ============================================================================
+program
+  .command('dev')
+  .description('Start the development server with live component rendering')
+  .option('-p, --port <port>', 'Port to run on', '6006')
+  .option('--no-open', 'Do not open browser')
+  .option('--skip-setup', 'Skip auto-setup (Storybook import, build, Figma link)')
+  .option('--skip-storybook', 'Skip auto-importing from Storybook')
+  .option('--skip-figma', 'Skip Figma link check')
+  .option('--skip-build', `Skip auto-building ${BRAND.outFile}`)
+  .action(async (options) => {
+    try {
+      await dev({
+        port: options.port,
+        open: options.open,
+        skipSetup: options.skipSetup,
+        skipStorybook: options.skipStorybook,
+        skipFigma: options.skipFigma,
+        skipBuild: options.skipBuild,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      if (error instanceof Error && error.stack) {
+        console.error(pc.dim(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// SCREENSHOT COMMAND
+// ============================================================================
+program
+  .command('screenshot')
+  .description('Capture screenshots of component variants')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--component <name>', 'Capture specific component only')
+  .option('--variant <name>', 'Capture specific variant only')
+  .option('--theme <theme>', 'Theme to capture (light/dark)', 'light')
+  .option('--update', 'Update existing baselines')
+  .option('--width <pixels>', 'Viewport width', parseInt)
+  .option('--height <pixels>', 'Viewport height', parseInt)
+  .option('--ci', 'CI mode - no interactive prompts')
+  .action(async (options) => {
+    try {
+      const { config, configDir } = await loadConfig(options.config);
+      const result = await runScreenshotCommand(config, configDir, {
+        component: options.component,
+        variant: options.variant,
+        theme: options.theme,
+        update: options.update,
+        ci: options.ci,
+        width: options.width,
+        height: options.height,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// DIFF COMMAND
+// ============================================================================
+program
+  .command('diff')
+  .argument('[component]', 'Component name to diff (optional)')
+  .description('Compare current renders against baselines')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--variant <name>', 'Compare specific variant only')
+  .option('--theme <theme>', 'Theme to compare (light/dark)', 'light')
+  .option('--threshold <percent>', 'Diff threshold percentage', parseFloat)
+  .option('--ci', 'CI mode - exit 1 on differences')
+  .option('--open', 'Open diff images')
+  .action(async (component, options) => {
+    try {
+      const { config, configDir } = await loadConfig(options.config);
+      const result = await runDiffCommand(config, configDir, {
+        component,
+        variant: options.variant,
+        theme: options.theme,
+        threshold: options.threshold,
+        ci: options.ci,
+        open: options.open,
+      });
+      if (!result.success && options.ci) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// COMPARE COMMAND
+// ============================================================================
+program
+  .command('compare')
+  .argument('[component]', 'Component name to compare')
+  .description('Compare component renders against Figma designs')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--variant <name>', 'Compare specific variant')
+  .option('--figma <url>', 'Figma frame URL (uses fragment figma link if not provided)')
+  .option('--threshold <percent>', 'Diff threshold percentage', parseFloat, 1.0)
+  .option('--all', 'Compare all components with Figma links')
+  .option('--output <dir>', 'Save diff images to directory')
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (component, options) => {
+    try {
+      const result = await compare(component, {
+        config: options.config,
+        variant: options.variant,
+        figma: options.figma,
+        threshold: options.threshold,
+        all: options.all,
+        output: options.output,
+        port: options.port,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      console.log(pc.dim(`\nMake sure the dev server is running: ${BRAND.cliCommand} dev`));
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// ANALYZE COMMAND
+// ============================================================================
+program
+  .command('analyze')
+  .description('Analyze design system and generate report')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-f, --format <format>', 'Output format (html/json/console)', 'html')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--open', 'Open report in browser after generation')
+  .option('--ci', 'CI mode - exit with code based on score')
+  .option('--min-score <score>', 'Minimum score to pass in CI mode', parseFloat)
+  .action(async (options) => {
+    try {
+      const { config, configDir } = await loadConfig(options.config);
+      const result = await runAnalyzeCommand(config, configDir, {
+        format: options.format,
+        output: options.output,
+        open: options.open,
+        ci: options.ci,
+        minScore: options.minScore,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// VERIFY COMMAND
+// ============================================================================
+program
+  .command('verify')
+  .argument('[component]', 'Component name to verify (optional, verifies all if omitted)')
+  .description('Verify component compliance for CI pipelines')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--ci', 'CI mode - output JSON and exit non-zero on failure')
+  .option('--min-compliance <percent>', 'Minimum compliance percentage (default: 80)', parseFloat, 80)
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (component, options) => {
+    try {
+      const summary = await verify(component, {
+        config: options.config,
+        ci: options.ci,
+        minCompliance: options.minCompliance,
+        port: options.port,
+      });
+      if (!summary.passed && options.ci) {
+        process.exit(1);
+      }
+    } catch (error) {
+      if (options.ci) {
+        console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'Verification failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// AUDIT COMMAND
+// ============================================================================
+program
+  .command('audit')
+  .description('Scan all fragments and show compliance metrics across the design system')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--json', 'Output machine-readable JSON format')
+  .option('--sort <field>', 'Sort by field: compliance, name, hardcoded (default: compliance)', 'compliance')
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (options) => {
+    try {
+      await audit({
+        config: options.config,
+        json: options.json,
+        sort: options.sort,
+        port: options.port,
+      });
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'Audit failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// A11Y COMMAND
+// ============================================================================
+program
+  .command('a11y')
+  .description('Run accessibility checks on all component variants')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--json', 'Output results as JSON')
+  .option('--ci', 'CI mode (exit code 1 if any critical/serious violations)')
+  .option('--component <name>', 'Check specific component only')
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (options) => {
+    try {
+      await a11y({
+        config: options.config,
+        json: options.json,
+        ci: options.ci,
+        component: options.component,
+        port: options.port,
+      });
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'A11y check failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// ENHANCE COMMAND
+// ============================================================================
+program
+  .command('enhance')
+  .description('AI-powered documentation generation from codebase analysis')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--component <name>', 'Enhance specific component (or "all")')
+  .option('--yes', 'Skip confirmation prompts')
+  .option('--dry-run', 'Only analyze, do not modify files')
+  .option('--format <format>', 'Output format: interactive, json, quiet, context', 'interactive')
+  .option('--provider <provider>', 'AI provider: anthropic, openai (auto-detected from API key)')
+  .option('--api-key <key>', 'API key (or use ANTHROPIC_API_KEY/OPENAI_API_KEY env)')
+  .option('--model <model>', 'AI model to use (default: claude-sonnet-4 for anthropic, gpt-4o for openai)')
+  .option('--root <dir>', 'Root directory to scan', process.cwd())
+  .option('--context-only', 'Output context for IDE AI (Cursor, Copilot) without calling API')
+  .action(async (options) => {
+    try {
+      await enhance({
+        config: options.config,
+        component: options.component,
+        yes: options.yes,
+        dryRun: options.dryRun,
+        format: options.format,
+        provider: options.provider,
+        apiKey: options.apiKey,
+        model: options.model,
+        root: options.root,
+        contextOnly: options.contextOnly,
+      });
+    } catch (error) {
+      if (options.format === 'json') {
+        console.log(JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Enhance failed' }));
+      } else {
+        console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// SCAN COMMAND
+// ============================================================================
+program
+  .command('scan')
+  .description(`Zero-config ${BRAND.outFile} generation from source code`)
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-o, --output <path>', 'Output file path', BRAND.outFile)
+  .option('--patterns <patterns...>', 'Component file patterns to scan')
+  .option('--barrel <files...>', 'Barrel export files to parse')
+  .option('--usage-dir <dir>', 'Directory to scan for usage patterns')
+  .option('--skip-usage', 'Skip usage pattern analysis')
+  .option('--skip-storybook', 'Skip Storybook story parsing')
+  .option('-v, --verbose', 'Verbose output')
+  .action(async (options) => {
+    try {
+      const result = await scan({
+        config: options.config,
+        output: options.output,
+        componentPatterns: options.patterns,
+        barrelFiles: options.barrel,
+        usageDir: options.usageDir,
+        skipUsage: options.skipUsage,
+        skipStorybook: options.skipStorybook,
+        verbose: options.verbose,
+      });
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// STORYGEN COMMAND
+// ============================================================================
+program
+  .command('storygen')
+  .description('Generate Storybook stories from fragment definitions')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('-o, --output <dir>', 'Output directory', '.storybook/generated')
+  .option('--watch', 'Watch for segment changes and regenerate')
+  .option('--format <format>', 'Story format (csf3)', 'csf3')
+  .action(async (options) => {
+    try {
+      await storygen({
+        config: options.config,
+        output: options.output,
+        watch: options.watch,
+        format: options.format,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// METRICS COMMAND
+// ============================================================================
+program
+  .command('metrics')
+  .argument('[component]', 'Component name (optional, shows system-wide if omitted)')
+  .description('View compliance trends over time')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--days <number>', 'Number of days to look back', parseInt, 30)
+  .option('--json', 'Output JSON format')
+  .action(async (component, options) => {
+    try {
+      await metrics(component, {
+        config: options.config,
+        days: options.days,
+        json: options.json,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// BASELINE COMMAND
+// ============================================================================
+program
+  .command('baseline')
+  .description('Manage visual regression baselines')
+  .argument('<action>', 'Action to perform: update, list, delete')
+  .argument('[component]', 'Component name (optional for update/delete)')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--variant <name>', 'Specific variant to update')
+  .option('--all', 'Update/delete all baselines')
+  .option('--theme <theme>', 'Theme for baseline (light/dark)', 'light')
+  .option('-p, --port <port>', 'Dev server port', '6006')
+  .action(async (action, component, options) => {
+    try {
+      await baseline(action, component, {
+        config: options.config,
+        variant: options.variant,
+        all: options.all,
+        theme: options.theme as 'light' | 'dark' | undefined,
+        port: options.port,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      if (action === 'update') {
+        console.log(pc.dim(`\nMake sure the dev server is running: ${BRAND.cliCommand} dev`));
+      }
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// VIEW COMMAND
+// ============================================================================
+program
+  .command('view')
+  .description(`Generate a static HTML viewer for ${BRAND.outFile}`)
+  .option('-i, --input <path>', `Path to ${BRAND.outFile}`, BRAND.outFile)
+  .option('-o, --output <path>', 'Output HTML file path', BRAND.viewerHtmlFile)
+  .option('--open', 'Open in browser after generation')
+  .action(async (options) => {
+    try {
+      const { generateViewerFromJson } = await import('./static-viewer.js');
+      const fs = await import('node:fs/promises');
+      const path = await import('node:path');
+
+      const inputPath = path.resolve(process.cwd(), options.input);
+      const outputPath = path.resolve(process.cwd(), options.output);
+
+      console.log(pc.cyan(`\n${BRAND.name} Viewer Generator\n`));
+
+      try {
+        await fs.access(inputPath);
+      } catch {
+        console.log(pc.red(`Error: ${options.input} not found.`));
+        console.log(pc.dim(`\nRun ${pc.cyan(`${BRAND.cliCommand} build`)} first to generate ${BRAND.outFile}\n`));
+        process.exit(1);
+      }
+
+      console.log(pc.dim(`Reading: ${options.input}`));
+      const html = await generateViewerFromJson(inputPath);
+
+      await fs.writeFile(outputPath, html);
+      console.log(pc.green(`\n✓ Generated: ${options.output}\n`));
+
+      if (options.open) {
+        const { exec } = await import('node:child_process');
+        const openCmd = process.platform === 'darwin' ? 'open' :
+                        process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${openCmd} "${outputPath}"`);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// ADD COMMAND
+// ============================================================================
+program
+  .command('add')
+  .argument('[name]', 'Component name (e.g., "Button", "TextField")')
+  .description('Scaffold a new component with fragment file')
+  .option('-c, --category <category>', 'Component category')
+  .option('-d, --dir <directory>', 'Output directory')
+  .option('-t, --template <template>', 'Template to use (action, form-input, layout, display)')
+  .option('--no-component', 'Only generate fragment file, skip component stub')
+  .action(async (name, options) => {
+    try {
+      await add(name, {
+        category: options.category,
+        dir: options.dir,
+        template: options.template,
+        component: options.component,
+      });
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// INIT COMMAND
+// ============================================================================
+program
+  .command('init')
+  .description('Initialize fragments in a project (interactive by default)')
+  .option('--force', 'Overwrite existing config')
+  .option('-y, --yes', 'Non-interactive mode - auto-detect and use defaults')
+  .action(async (options) => {
+    try {
+      const { init } = await import('./commands/init.js');
+      const result = await init({
+        projectRoot: process.cwd(),
+        force: options.force,
+        yes: options.yes,
+      });
+
+      if (!result.success) {
+        console.error(pc.red('\nInit failed with errors:'));
+        for (const error of result.errors) {
+          console.error(pc.red(`  - ${error}`));
+        }
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// TOKENS COMMAND
+// ============================================================================
+program
+  .command('tokens')
+  .description('Discover and list design tokens from CSS/SCSS files')
+  .option('-c, --config <path>', 'Path to config file')
+  .option('--json', 'Output as JSON')
+  .option('--categories', 'Group tokens by category')
+  .option('--theme <theme>', 'Filter by theme name')
+  .option('--category <category>', 'Filter by category (color, spacing, typography, etc.)')
+  .option('--verbose', 'Show all tokens (no truncation)')
+  .action(async (options) => {
+    try {
+      const { tokens } = await import('./commands/tokens.js');
+      const result = await tokens({
+        config: options.config,
+        json: options.json,
+        categories: options.categories,
+        theme: options.theme,
+        category: options.category,
+        verbose: options.verbose,
+      });
+
+      if (!result.success) {
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// GENERATE COMMAND
+// ============================================================================
+program
+  .command('generate')
+  .description('Generate fragment files from component source code')
+  .argument('[component]', 'Specific component name to generate (optional)')
+  .option('--force', 'Overwrite existing fragment files')
+  .option('--pattern <glob>', 'Pattern for component files', 'src/components/**/*.tsx')
+  .action(async (component, options) => {
+    try {
+      const { generate } = await import('./commands/generate.js');
+      const result = await generate({
+        projectRoot: process.cwd(),
+        component,
+        force: options.force,
+        componentPattern: options.pattern,
+      });
+
+      if (!result.success) {
+        console.error(pc.red('\nGenerate completed with errors'));
+        process.exit(1);
+      }
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// TEST COMMAND
+// ============================================================================
+program
+  .command('test')
+  .description('Run interaction tests for fragments with play functions')
+  .option('-c, --config <path>', 'Path to config file')
+  // Discovery options
+  .option('--component <name>', 'Filter by component name')
+  .option('--tags <tags>', 'Filter by tags (comma-separated)')
+  .option('--grep <pattern>', 'Filter by variant name pattern')
+  .option('--exclude <pattern>', 'Exclude tests matching pattern')
+  // Execution options
+  .option('--parallel <count>', 'Number of parallel browser contexts', parseInt, 4)
+  .option('--timeout <ms>', 'Timeout per test in milliseconds', parseInt, 30000)
+  .option('--retries <count>', 'Number of retries for failed tests', parseInt, 0)
+  .option('--bail', 'Stop on first failure')
+  .option('--browser <name>', 'Browser to use (chromium, firefox, webkit)', 'chromium')
+  .option('--headed', 'Run in headed mode (show browser)')
+  // Feature flags
+  .option('--a11y', 'Run accessibility checks with axe-core')
+  .option('--visual', 'Capture screenshots for visual regression')
+  .option('--update-snapshots', 'Update visual snapshots')
+  .option('--watch', 'Watch mode - re-run on file changes')
+  // Output options
+  .option('--reporters <names>', 'Reporters to use (console, junit, json)', 'console')
+  .option('-o, --output <dir>', 'Output directory for results', './test-results')
+  // Server options
+  .option('--server-url <url>', 'URL of running dev server (skips starting server)')
+  .option('-p, --port <port>', 'Port for dev server', parseInt, 6006)
+  // CI mode
+  .option('--ci', 'CI mode - non-interactive, exit with code 1 on failure')
+  // List only
+  .option('--list', 'List available tests without running them')
+  .action(async (options) => {
+    try {
+      const { config, configDir } = await loadConfig(options.config);
+
+      // Import test module
+      const { runTestCommand, listTests } = await import('./test/index.js');
+
+      // List mode
+      if (options.list) {
+        await listTests(config, configDir, {
+          component: options.component,
+          tags: options.tags,
+          grep: options.grep,
+          exclude: options.exclude,
+        });
+        return;
+      }
+
+      // Run tests
+      const exitCode = await runTestCommand(config, configDir, {
+        component: options.component,
+        tags: options.tags,
+        grep: options.grep,
+        exclude: options.exclude,
+        parallel: options.parallel,
+        timeout: options.timeout,
+        retries: options.retries,
+        bail: options.bail,
+        browser: options.browser as 'chromium' | 'firefox' | 'webkit',
+        headless: !options.headed,
+        a11y: options.a11y,
+        visual: options.visual,
+        updateSnapshots: options.updateSnapshots,
+        watch: options.watch,
+        reporters: options.reporters,
+        output: options.output,
+        serverUrl: options.serverUrl,
+        port: options.port,
+        ci: options.ci,
+      });
+
+      process.exit(exitCode);
+    } catch (error) {
+      console.error(pc.red('Error:'), error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+// Parse command line arguments
+program.parse();