@fragments-sdk/cli 0.2.2

package/src/migrate/types.ts

@@ -0,0 +1,169 @@
+/**
+ * Types for the Storybook migration tool.
+ */
+
+/**
+ * Parsed Storybook story metadata
+ */
+export interface ParsedMeta {
+  /** Full title path (e.g., "Components/Forms/Input") */
+  title: string;
+  /** Component name (inferred from title or component ref) */
+  componentName: string;
+  /** Component import path */
+  componentImport?: string;
+  /** Tags from the story */
+  tags?: string[];
+  /** Description from parameters.docs */
+  description?: string;
+}
+
+/**
+ * Parsed argType definition
+ */
+export interface ParsedArgType {
+  /** Storybook control type */
+  control?: string;
+  /** Options for select/radio controls */
+  options?: string[];
+  /** Prop description */
+  description?: string;
+  /** Default value */
+  defaultValue?: unknown;
+  /** TypeScript type (if available) */
+  type?: string;
+  /** Whether the prop is required */
+  required?: boolean;
+}
+
+/**
+ * Parsed individual story
+ */
+export interface ParsedStory {
+  /** Story name (export name) */
+  name: string;
+  /** Args passed to the component */
+  args: Record<string, unknown>;
+  /** Story description */
+  description?: string;
+  /** Whether story has a custom render function */
+  hasCustomRender?: boolean;
+  /** Raw render code if extractable */
+  renderCode?: string;
+}
+
+/**
+ * Complete parsed story file
+ */
+export interface ParsedStoryFile {
+  /** Original file path */
+  filePath: string;
+  /** Parsed metadata */
+  meta: ParsedMeta;
+  /** Parsed argTypes */
+  argTypes: Record<string, ParsedArgType>;
+  /** Parsed stories */
+  stories: ParsedStory[];
+  /** Parse warnings */
+  warnings: string[];
+  /** Confidence score (0-1) - how reliable the extraction was */
+  confidence: number;
+}
+
+/**
+ * Detected Storybook configuration
+ */
+export interface StorybookConfig {
+  /** Path to .storybook/main.* */
+  configPath: string;
+  /** Story glob patterns from config */
+  storyPatterns: string[];
+  /** Detected framework (react, vue, etc.) */
+  framework?: string;
+  /** Detected builder (vite, webpack) */
+  builder?: string;
+  /** Whether config was successfully parsed */
+  valid: boolean;
+  /** Parse errors if any */
+  errors?: string[];
+}
+
+/**
+ * Conversion result for a single story file
+ */
+export interface ConversionResult {
+  /** Original story file path */
+  sourceFile: string;
+  /** Output segment file path */
+  outputFile: string;
+  /** Generated segment code */
+  code: string;
+  /** Component name */
+  componentName: string;
+  /** Category extracted from title */
+  category: string;
+  /** Number of variants generated */
+  variantCount: number;
+  /** Number of props extracted */
+  propCount: number;
+  /** Confidence score (0-1) - how reliable the extraction was */
+  confidence: number;
+  /** TODOs that need human attention */
+  todos: string[];
+  /** Warnings during conversion */
+  warnings: string[];
+  /** Whether conversion was successful */
+  success: boolean;
+}
+
+/**
+ * Migration report summary
+ */
+export interface MigrationReport {
+  /** When the migration was run */
+  timestamp: Date;
+  /** Source directory */
+  sourceDir: string;
+  /** Output directory */
+  outputDir: string;
+  /** Total story files found */
+  totalStoryFiles: number;
+  /** Successfully converted files */
+  successfulConversions: number;
+  /** Failed conversions */
+  failedConversions: number;
+  /** Total variants generated */
+  totalVariants: number;
+  /** Total TODOs that need attention */
+  totalTodos: number;
+  /** Individual conversion results */
+  results: ConversionResult[];
+  /** Categories discovered */
+  categories: string[];
+  /** Analytics from the converted segments */
+  analytics?: {
+    overallScore: number;
+    coveragePercentage: number;
+    recommendations: string[];
+  };
+}
+
+/**
+ * Migration options
+ */
+export interface MigrateOptions {
+  /** Source directory or file pattern */
+  from: string;
+  /** Output directory (default: same as source) */
+  to?: string;
+  /** Dry run - don't write files */
+  dryRun?: boolean;
+  /** Overwrite existing segment files */
+  overwrite?: boolean;
+  /** Generate HTML report */
+  report?: boolean;
+  /** Report output path */
+  reportPath?: string;
+  /** Verbose output */
+  verbose?: boolean;
+}

package/src/screenshot.ts

@@ -0,0 +1,249 @@
+import pc from 'picocolors';
+import {
+  BRAND,
+  DEFAULTS,
+  type SegmentsConfig,
+  type SegmentDefinition,
+  type Theme,
+} from './core/index.js';
+import { discoverSegmentFiles, loadSegmentFile } from './core/node.js';
+import {
+  BrowserPool,
+  CaptureEngine,
+  StorageManager,
+  formatMs,
+  type CaptureOptions,
+} from './service/index.js';
+
+/**
+ * Options for the screenshot command
+ */
+export interface ScreenshotCommandOptions {
+  /** Specific component to capture */
+  component?: string;
+
+  /** Specific variant to capture */
+  variant?: string;
+
+  /** Theme to capture */
+  theme?: Theme;
+
+  /** Update existing baselines */
+  update?: boolean;
+
+  /** CI mode - no interactive prompts */
+  ci?: boolean;
+
+  /** Viewport width */
+  width?: number;
+
+  /** Viewport height */
+  height?: number;
+}
+
+/**
+ * Result of the screenshot command
+ */
+export interface ScreenshotResult {
+  success: boolean;
+  captured: number;
+  skipped: number;
+  errors: Array<{ component: string; variant: string; error: string }>;
+  totalTimeMs: number;
+}
+
+/**
+ * Execute the screenshot command
+ */
+export async function runScreenshotCommand(
+  config: SegmentsConfig,
+  configDir: string,
+  options: ScreenshotCommandOptions = {}
+): Promise<ScreenshotResult> {
+  const startTime = Date.now();
+  const errors: ScreenshotResult['errors'] = [];
+
+  // Initialize storage
+  const storage = new StorageManager({
+    projectRoot: configDir,
+    viewport: options.width && options.height
+      ? { width: options.width, height: options.height }
+      : config.screenshots?.viewport,
+  });
+  await storage.initialize();
+
+  // Discover segments
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+
+  if (segmentFiles.length === 0) {
+    console.log(pc.yellow('No segment files found.'));
+    return {
+      success: true,
+      captured: 0,
+      skipped: 0,
+      errors: [],
+      totalTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Load all segments
+  const segments: Array<{ path: string; segment: SegmentDefinition }> = [];
+
+  for (const file of segmentFiles) {
+    try {
+      const segment = await loadSegmentFile(file.absolutePath);
+      if (segment) {
+        segments.push({ path: file.relativePath, segment });
+      }
+    } catch (error) {
+      errors.push({
+        component: file.relativePath,
+        variant: '',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // Filter by component if specified
+  const filteredSegments = options.component
+    ? segments.filter((s) => s.segment.meta.name === options.component)
+    : segments;
+
+  if (options.component && filteredSegments.length === 0) {
+    console.log(pc.yellow(`Component "${options.component}" not found.`));
+    return {
+      success: false,
+      captured: 0,
+      skipped: 0,
+      errors: [],
+      totalTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Build list of variants to capture
+  const variantsToCapture: Array<{
+    component: string;
+    variant: string;
+    render: () => unknown;
+  }> = [];
+
+  for (const { segment } of filteredSegments) {
+    const variants = options.variant
+      ? segment.variants.filter((v) => v.name === options.variant)
+      : segment.variants;
+
+    for (const variant of variants) {
+      variantsToCapture.push({
+        component: segment.meta.name,
+        variant: variant.name,
+        render: variant.render,
+      });
+    }
+  }
+
+  if (variantsToCapture.length === 0) {
+    console.log(pc.yellow('No variants to capture.'));
+    return {
+      success: true,
+      captured: 0,
+      skipped: 0,
+      errors: [],
+      totalTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Determine theme
+  const theme: Theme = options.theme ?? DEFAULTS.theme;
+  const viewport = {
+    width: options.width ?? config.screenshots?.viewport?.width ?? DEFAULTS.viewport.width,
+    height: options.height ?? config.screenshots?.viewport?.height ?? DEFAULTS.viewport.height,
+  };
+
+  console.log(pc.cyan(`\n${BRAND.name} Screenshot\n`));
+  console.log(pc.dim(`Capturing variants (theme: ${theme}, viewport: ${viewport.width}x${viewport.height}):\n`));
+
+  // Initialize browser pool
+  const pool = new BrowserPool({
+    viewport,
+  });
+
+  // Create capture engine - use the viewer URL
+  const viewerPort = DEFAULTS.port;
+  const baseUrl = `http://localhost:${viewerPort}`;
+  const captureEngine = new CaptureEngine(pool, baseUrl);
+
+  let captured = 0;
+  let skipped = 0;
+
+  const captureOptions: CaptureOptions = {
+    theme,
+    viewport,
+    delay: config.screenshots?.delay ?? DEFAULTS.captureDelayMs,
+  };
+
+  try {
+    // Warm up the pool
+    console.log(pc.dim('Starting browser...'));
+    await pool.warmup();
+    console.log(pc.dim('Browser ready.\n'));
+
+    // Capture each variant
+    for (const { component, variant } of variantsToCapture) {
+      const hasExisting = storage.hasBaseline(component, variant, theme);
+
+      // Skip if exists and not updating
+      if (hasExisting && !options.update) {
+        console.log(`  ${pc.dim('○')} ${component}/${variant} ${pc.dim('(skipped)')}`);
+        skipped++;
+        continue;
+      }
+
+      try {
+        const screenshot = await captureEngine.captureVariant(
+          component,
+          variant,
+          captureOptions
+        );
+
+        await storage.saveBaseline(screenshot);
+
+        const totalTime = screenshot.metadata.renderTimeMs + screenshot.metadata.captureTimeMs;
+        console.log(
+          `  ${pc.green('✓')} ${component}/${variant} ${pc.dim(formatMs(totalTime))}`
+        );
+        captured++;
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.log(`  ${pc.red('✗')} ${component}/${variant} ${pc.dim(errorMsg)}`);
+        errors.push({ component, variant, error: errorMsg });
+      }
+    }
+  } finally {
+    // Shutdown browser pool
+    await pool.shutdown();
+  }
+
+  const totalTimeMs = Date.now() - startTime;
+
+  // Print summary
+  console.log();
+  if (errors.length === 0) {
+    console.log(pc.green(`✓ Captured ${captured} screenshot(s) in ${formatMs(totalTimeMs)}`));
+  } else {
+    console.log(pc.yellow(`⚠ Captured ${captured} screenshot(s) with ${errors.length} error(s)`));
+  }
+
+  if (skipped > 0) {
+    console.log(pc.dim(`  ${skipped} skipped (use --update to recapture)`));
+  }
+
+  console.log(pc.dim(`  Stored in ${storage.screenshotsDirPath}\n`));
+
+  return {
+    success: errors.length === 0,
+    captured,
+    skipped,
+    errors,
+    totalTimeMs,
+  };
+}