@fragments-sdk/cli 0.2.2

package/src/commands/baseline.ts

@@ -0,0 +1,221 @@
+/**
+ * fragments baseline - Manage visual regression baselines
+ */
+
+import { readdir, rm, mkdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import pc from 'picocolors';
+import { BRAND, type Theme } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { runScreenshotCommand } from '../screenshot.js';
+import { StorageManager } from '../service/index.js';
+
+/**
+ * Options for baseline command
+ */
+export interface BaselineOptions {
+  /** Path to config file */
+  config?: string;
+  /** Specific variant to update */
+  variant?: string;
+  /** Update/delete all baselines */
+  all?: boolean;
+  /** Theme for baseline (light/dark) */
+  theme?: Theme;
+  /** Dev server port */
+  port?: number | string;
+}
+
+/**
+ * Result of baseline command
+ */
+export interface BaselineResult {
+  success: boolean;
+  action: 'update' | 'list' | 'delete';
+  count?: number;
+}
+
+/**
+ * Run the baseline command
+ */
+export async function baseline(
+  action: string,
+  component: string | undefined,
+  options: BaselineOptions = {}
+): Promise<BaselineResult> {
+  const { config: configPath, variant, all = false, theme = 'light', port = 6006 } = options;
+
+  const { config, configDir } = await loadConfig(configPath);
+
+  // Initialize storage manager
+  const storage = new StorageManager({
+    projectRoot: configDir,
+    viewport: config.screenshots?.viewport,
+  });
+  await storage.initialize();
+
+  console.log(pc.cyan(`\n${BRAND.name} Baseline Manager\n`));
+
+  const baseUrl = `http://localhost:${port}`;
+
+  switch (action) {
+    case 'update':
+      return updateBaseline(component, options, config, configDir, baseUrl);
+
+    case 'list':
+      return listBaselines(configDir);
+
+    case 'delete':
+      return deleteBaseline(component, options, configDir);
+
+    default:
+      console.log(pc.red(`Unknown action: ${action}`));
+      console.log(pc.dim('Available actions: update, list, delete\n'));
+      process.exit(1);
+  }
+}
+
+/**
+ * Update baselines
+ */
+async function updateBaseline(
+  component: string | undefined,
+  options: BaselineOptions,
+  config: any,
+  configDir: string,
+  baseUrl: string
+): Promise<BaselineResult> {
+  const { variant, all = false, theme = 'light' as const } = options;
+
+  if (!component && !all) {
+    // Interactive mode - prompt for component selection
+    const { select } = await import('@inquirer/prompts');
+
+    // Fetch available components
+    const contextResp = await fetch(`${baseUrl}/fragments/context?format=json`);
+    if (!contextResp.ok) {
+      throw new Error('Failed to fetch fragments. Make sure dev server is running.');
+    }
+
+    const contextData = JSON.parse(await contextResp.text());
+    const segments = contextData.components || [];
+
+    if (segments.length === 0) {
+      console.log(pc.yellow('No components found.\n'));
+      return { success: true, action: 'update', count: 0 };
+    }
+
+    component = await select({
+      message: 'Select component to update:',
+      choices: segments.map((s: { name: string }) => ({
+        name: s.name,
+        value: s.name,
+      })),
+    });
+  }
+
+  if (all) {
+    // Update all baselines
+    console.log(pc.dim('Updating all baselines...\n'));
+
+    await runScreenshotCommand(config, configDir, {
+      theme,
+    });
+
+    console.log(pc.green('\n✓ All baselines updated\n'));
+  } else if (component) {
+    // Update specific component
+    console.log(pc.dim(`Updating baselines for ${component}...\n`));
+
+    await runScreenshotCommand(config, configDir, {
+      component,
+      variant,
+      theme,
+    });
+
+    console.log(pc.green(`\n✓ Baselines updated for ${component}\n`));
+  }
+
+  // Show file paths
+  const baselinesDir = join(configDir, BRAND.dataDir, 'baselines');
+  console.log(pc.dim(`Baselines directory: ${relative(process.cwd(), baselinesDir)}\n`));
+
+  return { success: true, action: 'update' };
+}
+
+/**
+ * List all baselines
+ */
+async function listBaselines(configDir: string): Promise<BaselineResult> {
+  const baselinesDir = join(configDir, BRAND.dataDir, 'baselines');
+
+  try {
+    const files = await readdir(baselinesDir, { recursive: true });
+    const pngFiles = (files as string[]).filter((f) => f.endsWith('.png'));
+
+    if (pngFiles.length === 0) {
+      console.log(pc.yellow('No baselines found.\n'));
+      console.log(pc.dim(`Run ${pc.cyan(`${BRAND.cliCommand} screenshot`)} to capture baselines.\n`));
+      return { success: true, action: 'list', count: 0 };
+    }
+
+    console.log(pc.bold('Baselines:\n'));
+    for (const file of pngFiles) {
+      console.log(`  ${file}`);
+    }
+    console.log();
+    console.log(pc.dim(`Total: ${pngFiles.length} baseline(s)\n`));
+
+    return { success: true, action: 'list', count: pngFiles.length };
+  } catch {
+    console.log(pc.yellow('No baselines directory found.\n'));
+    console.log(pc.dim(`Run ${pc.cyan(`${BRAND.cliCommand} screenshot`)} to capture baselines.\n`));
+    return { success: true, action: 'list', count: 0 };
+  }
+}
+
+/**
+ * Delete baselines
+ */
+async function deleteBaseline(
+  component: string | undefined,
+  options: BaselineOptions,
+  configDir: string
+): Promise<BaselineResult> {
+  const { all = false } = options;
+  const baselinesDir = join(configDir, BRAND.dataDir, 'baselines');
+
+  if (all) {
+    // Delete all baselines
+    const { confirm } = await import('@inquirer/prompts');
+
+    const confirmed = await confirm({
+      message: 'Delete ALL baselines? This cannot be undone.',
+      default: false,
+    });
+
+    if (!confirmed) {
+      console.log(pc.dim('\nNo changes made.\n'));
+      return { success: true, action: 'delete', count: 0 };
+    }
+
+    await rm(baselinesDir, { recursive: true, force: true });
+    console.log(pc.green('\n✓ All baselines deleted\n'));
+    return { success: true, action: 'delete' };
+  } else if (component) {
+    // Delete specific component baselines
+    const componentDir = join(baselinesDir, component);
+
+    try {
+      await rm(componentDir, { recursive: true, force: true });
+      console.log(pc.green(`✓ Baselines deleted for ${component}\n`));
+      return { success: true, action: 'delete' };
+    } catch {
+      console.log(pc.yellow(`No baselines found for ${component}.\n`));
+      return { success: true, action: 'delete', count: 0 };
+    }
+  } else {
+    console.log(pc.yellow('Specify a component name or use --all flag.\n'));
+    return { success: false, action: 'delete' };
+  }
+}

package/src/commands/build.ts

@@ -0,0 +1,144 @@
+/**
+ * fragments build - Build compiled fragments.json and .fragments/ directory
+ */
+
+import pc from 'picocolors';
+import { BRAND } from '../core/index.js';
+import { loadConfig } from '../core/node.js';
+import { buildSegments, buildFragmentsDir } from '../build.js';
+import { scan } from './scan.js';
+
+/**
+ * Options for build command
+ */
+export interface BuildOptions {
+  /** Path to config file */
+  config?: string;
+  /** Output file path */
+  output?: string;
+  /** Also generate .fragments/registry.json and context.md */
+  registry?: boolean;
+  /** Only generate .fragments/ directory (skip fragments.json) */
+  registryOnly?: boolean;
+  /** Build from source code (zero-config, no fragment files needed) */
+  fromSource?: boolean;
+  /** Skip usage analysis when building from source */
+  skipUsage?: boolean;
+  /** Skip Storybook parsing when building from source */
+  skipStorybook?: boolean;
+  /** Verbose output */
+  verbose?: boolean;
+}
+
+/**
+ * Result of build command
+ */
+export interface BuildResult {
+  success: boolean;
+  segmentCount?: number;
+  outputPath?: string;
+  componentCount?: number;
+  registryPath?: string;
+  contextPath?: string;
+  errors: Array<{
+    file: string;
+    error: string;
+  }>;
+}
+
+/**
+ * Run the build command
+ */
+export async function build(options: BuildOptions = {}): Promise<BuildResult> {
+  // If building from source, use the scan pipeline
+  if (options.fromSource) {
+    console.log(pc.cyan(`\n${BRAND.name} Build (from source)\n`));
+    console.log(pc.dim('Using zero-config source extraction pipeline\n'));
+
+    const scanResult = await scan({
+      config: options.config,
+      output: options.output,
+      skipUsage: options.skipUsage,
+      skipStorybook: options.skipStorybook,
+      verbose: options.verbose,
+    });
+
+    return {
+      success: scanResult.success,
+      segmentCount: scanResult.componentCount,
+      outputPath: scanResult.outputPath,
+      errors: scanResult.errors.map((e) => ({ file: e.component, error: e.error })),
+    };
+  }
+
+  const { config, configDir } = await loadConfig(options.config);
+
+  if (options.output) {
+    config.outFile = options.output;
+  }
+
+  console.log(pc.cyan(`\n${BRAND.name} Build\n`));
+
+  const errors: Array<{ file: string; error: string }> = [];
+  let segmentCount: number | undefined;
+  let outputPath: string | undefined;
+  let componentCount: number | undefined;
+  let registryPath: string | undefined;
+  let contextPath: string | undefined;
+
+  // Build fragments.json unless --registry-only
+  if (!options.registryOnly) {
+    console.log(pc.dim('Compiling fragments...\n'));
+
+    const result = await buildSegments(config, configDir);
+
+    if (result.errors.length > 0) {
+      console.log(pc.yellow('Build completed with errors:\n'));
+      for (const error of result.errors) {
+        console.log(`  ${pc.red('✗')} ${error.file}: ${error.error}`);
+        errors.push(error);
+      }
+      console.log();
+    }
+
+    segmentCount = result.segmentCount;
+    outputPath = result.outputPath;
+
+    console.log(pc.green(`✓ Built ${result.segmentCount} fragment(s)`));
+    console.log(pc.dim(`  Output: ${result.outputPath}\n`));
+  }
+
+  // Build .fragments/ directory if --registry or --registry-only
+  if (options.registry || options.registryOnly) {
+    console.log(pc.dim('Generating registry and context...\n'));
+
+    const fragmentsResult = await buildFragmentsDir(config, configDir);
+
+    if (fragmentsResult.errors.length > 0) {
+      console.log(pc.yellow('Registry build completed with errors:\n'));
+      for (const error of fragmentsResult.errors) {
+        console.log(`  ${pc.red('✗')} ${error.file}: ${error.error}`);
+        errors.push(error);
+      }
+      console.log();
+    }
+
+    componentCount = fragmentsResult.componentCount;
+    registryPath = fragmentsResult.registryPath;
+    contextPath = fragmentsResult.contextPath;
+
+    console.log(pc.green(`✓ Generated registry with ${fragmentsResult.componentCount} component(s)`));
+    console.log(pc.dim(`  Registry: ${fragmentsResult.registryPath}`));
+    console.log(pc.dim(`  Context:  ${fragmentsResult.contextPath}\n`));
+  }
+
+  return {
+    success: errors.length === 0,
+    segmentCount,
+    outputPath,
+    componentCount,
+    registryPath,
+    contextPath,
+    errors,
+  };
+}

package/src/commands/compare.ts

@@ -0,0 +1,337 @@
+/**
+ * fragments compare - Compare component renders against Figma designs
+ */
+
+import pc from 'picocolors';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { BRAND } from '../core/index.js';
+
+/**
+ * Options for compare command
+ */
+export interface CompareOptions {
+  /** Path to config file */
+  config?: string;
+  /** Compare specific variant */
+  variant?: string;
+  /** Figma frame URL (uses segment figma link if not provided) */
+  figma?: string;
+  /** Diff threshold percentage */
+  threshold?: number;
+  /** Compare all components with Figma links */
+  all?: boolean;
+  /** Save diff images to directory */
+  output?: string;
+  /** Dev server port */
+  port?: number | string;
+}
+
+/**
+ * Compare result from server
+ */
+interface CompareResult {
+  match?: boolean;
+  diffPercentage?: number;
+  threshold?: number;
+  figmaUrl?: string;
+  rendered?: string;
+  figma?: string;
+  diff?: string;
+  changedRegions?: Array<{ x: number; y: number; width: number; height: number }>;
+  error?: string;
+  suggestion?: string;
+}
+
+/**
+ * Result of compare command
+ */
+export interface CompareCommandResult {
+  success: boolean;
+  passed: number;
+  failed: number;
+  skipped: number;
+}
+
+/**
+ * Run the compare command
+ */
+export async function compare(
+  component: string | undefined,
+  options: CompareOptions = {}
+): Promise<CompareCommandResult> {
+  const {
+    variant,
+    figma: figmaUrl,
+    threshold = 1.0,
+    all = false,
+    output,
+    port = 6006,
+  } = options;
+
+  // Check for Figma access token
+  if (!process.env.FIGMA_ACCESS_TOKEN) {
+    console.error(pc.red('\nFIGMA_ACCESS_TOKEN environment variable required.'));
+    console.log(pc.dim('Generate at: https://www.figma.com/developers/api#access-tokens'));
+    console.log(pc.dim('  export FIGMA_ACCESS_TOKEN=figd_xxx'));
+    process.exit(1);
+  }
+
+  const baseUrl = `http://localhost:${port}`;
+
+  console.log(pc.cyan(`\n${BRAND.name} Design Verification\n`));
+
+  if (all) {
+    // Compare all components with Figma links
+    return compareAll(baseUrl, threshold, output);
+  }
+
+  // Compare single or selected components
+  let componentsToCompare: string[] = [];
+
+  if (component) {
+    componentsToCompare = [component];
+  } else {
+    // No component specified - show interactive selection
+    componentsToCompare = await selectComponents(baseUrl);
+  }
+
+  if (componentsToCompare.length === 0) {
+    console.log(pc.dim('\nNo components selected.'));
+    return { success: true, passed: 0, failed: 0, skipped: 0 };
+  }
+
+  // Compare selected components
+  if (componentsToCompare.length === 1) {
+    console.log(pc.dim(`Comparing ${componentsToCompare[0]} to Figma design...\n`));
+  } else {
+    console.log(pc.dim(`Comparing ${componentsToCompare.length} components to Figma designs...\n`));
+  }
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const comp of componentsToCompare) {
+    const response = await fetch(`${baseUrl}/segments/compare`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        component: comp,
+        variant,
+        figmaUrl,
+        threshold,
+        figmaToken: process.env.FIGMA_ACCESS_TOKEN,
+      }),
+    });
+
+    const result = await response.json() as CompareResult;
+
+    if (result.error) {
+      failed++;
+      console.log(`${pc.red('✗')} ${pc.bold(comp)} - ${result.error}`);
+      continue;
+    }
+
+    if (result.match) {
+      passed++;
+      console.log(`${pc.green('✓')} ${pc.bold(comp)} ${pc.dim(`${result.diffPercentage}%`)}`);
+    } else {
+      failed++;
+      console.log(`${pc.red('✗')} ${pc.bold(comp)} ${pc.yellow(`${result.diffPercentage}%`)} ${pc.dim(`(threshold: ${threshold}%)`)}`);
+    }
+
+    // Save images if output dir specified
+    if (output && result.rendered && result.figma && result.diff) {
+      await saveImages(output, comp, result);
+    }
+  }
+
+  // Summary for multiple components
+  if (componentsToCompare.length > 1) {
+    console.log();
+    console.log(pc.dim('───────────────────────────────────────'));
+    console.log(`\n${pc.green(`${passed} passed`)}, ${pc.red(`${failed} failed`)}\n`);
+  } else {
+    console.log();
+  }
+
+  if (output && componentsToCompare.length > 0) {
+    console.log(pc.dim(`Images saved to: ${output}/\n`));
+  }
+
+  return {
+    success: failed === 0,
+    passed,
+    failed,
+    skipped: 0,
+  };
+}
+
+/**
+ * Compare all components with Figma links
+ */
+async function compareAll(
+  baseUrl: string,
+  threshold: number,
+  output?: string
+): Promise<CompareCommandResult> {
+  console.log(pc.dim('Comparing all components with Figma links...\n'));
+
+  // Fetch the context to get all segments
+  const contextResp = await fetch(`${baseUrl}/segments/context?format=json`);
+  if (!contextResp.ok) {
+    throw new Error('Failed to fetch segments. Make sure dev server is running.');
+  }
+
+  const contextText = await contextResp.text();
+  let segments: Array<{ name: string; figma?: string }> = [];
+  try {
+    const contextData = JSON.parse(contextText);
+    segments = contextData.components || [];
+  } catch {
+    segments = [];
+  }
+
+  if (segments.length === 0) {
+    console.log(pc.yellow('No components found with Figma links.'));
+    console.log(pc.dim('Add figma field to your segment definitions:'));
+    console.log(pc.dim('  meta: { figma: "https://figma.com/file/..." }'));
+    return { success: true, passed: 0, failed: 0, skipped: 0 };
+  }
+
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+
+  for (const seg of segments) {
+    // Skip components without figma links
+    if (!seg.figma) {
+      skipped++;
+      console.log(`${pc.dim('⏭️')}  ${pc.dim(seg.name)} ${pc.dim('(no figma link)')}`);
+      continue;
+    }
+
+    try {
+      const response = await fetch(`${baseUrl}/segments/compare`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          component: seg.name,
+          threshold,
+          figmaToken: process.env.FIGMA_ACCESS_TOKEN,
+        }),
+      });
+
+      const result = await response.json() as CompareResult;
+
+      if (result.error) {
+        failed++;
+        console.log(`${pc.red('✗')} ${pc.bold(seg.name)} - ${result.error}`);
+      } else if (result.match) {
+        passed++;
+        console.log(`${pc.green('✓')} ${pc.bold(seg.name)} ${pc.dim(`${result.diffPercentage}%`)}`);
+      } else {
+        failed++;
+        console.log(`${pc.red('✗')} ${pc.bold(seg.name)} ${pc.yellow(`${result.diffPercentage}%`)} ${pc.dim(`(threshold: ${threshold}%)`)}`);
+      }
+
+      // Save images if output dir specified
+      if (output && result.rendered && result.figma && result.diff) {
+        await saveImages(output, seg.name, result);
+      }
+    } catch (error) {
+      failed++;
+      console.log(`${pc.red('✗')} ${pc.bold(seg.name)} - ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  console.log();
+  console.log(pc.dim('───────────────────────────────────────'));
+  console.log(`\n${pc.green(`${passed} passed`)}, ${pc.red(`${failed} failed`)}, ${pc.dim(`${skipped} skipped`)}\n`);
+
+  if (output) {
+    console.log(pc.dim(`Images saved to: ${output}/\n`));
+  }
+
+  return {
+    success: failed === 0,
+    passed,
+    failed,
+    skipped,
+  };
+}
+
+/**
+ * Show interactive selection for components with Figma links
+ */
+async function selectComponents(baseUrl: string): Promise<string[]> {
+  console.log(pc.dim('Fetching components with Figma links...\n'));
+
+  const contextResp = await fetch(`${baseUrl}/segments/context?format=json`);
+  if (!contextResp.ok) {
+    throw new Error('Failed to fetch segments. Make sure dev server is running.');
+  }
+
+  const contextText = await contextResp.text();
+  let segments: Array<{ name: string; figma?: string }> = [];
+  try {
+    const contextData = JSON.parse(contextText);
+    segments = (contextData.components || []).filter((s: { figma?: string }) => s.figma);
+  } catch {
+    segments = [];
+  }
+
+  if (segments.length === 0) {
+    console.log(pc.yellow('No components found with Figma links.'));
+    console.log(pc.dim('Add figma field to your segment definitions:'));
+    console.log(pc.dim('  meta: { figma: "https://figma.com/file/..." }'));
+    return [];
+  }
+
+  const { checkbox } = await import('@inquirer/prompts');
+
+  try {
+    const choices = segments.map((seg) => ({
+      name: seg.name,
+      value: seg.name,
+      checked: true,
+    }));
+
+    return await checkbox({
+      message: 'Select components to compare:',
+      choices,
+      pageSize: 15,
+    });
+  } catch {
+    // User cancelled (Ctrl+C)
+    console.log(pc.dim('\nNo changes made.'));
+    return [];
+  }
+}
+
+/**
+ * Save comparison images to output directory
+ */
+async function saveImages(
+  outputDir: string,
+  component: string,
+  result: CompareResult
+): Promise<void> {
+  const dir = resolve(process.cwd(), outputDir);
+  await mkdir(dir, { recursive: true });
+
+  const saveImage = async (data: string, filename: string) => {
+    const base64 = data.replace('data:image/png;base64,', '');
+    await writeFile(join(dir, filename), Buffer.from(base64, 'base64'));
+  };
+
+  if (result.rendered) {
+    await saveImage(result.rendered, `${component}-rendered.png`);
+  }
+  if (result.figma) {
+    await saveImage(result.figma, `${component}-figma.png`);
+  }
+  if (result.diff) {
+    await saveImage(result.diff, `${component}-diff.png`);
+  }
+}