@fragments-sdk/cli 0.2.2

package/src/diff.ts

@@ -0,0 +1,323 @@
+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,
+  DiffEngine,
+  formatMs,
+  type CaptureOptions,
+  type DiffResult,
+} from './service/index.js';
+
+/**
+ * Options for the diff command
+ */
+export interface DiffCommandOptions {
+  /** Specific component to diff */
+  component?: string;
+
+  /** Specific variant to diff */
+  variant?: string;
+
+  /** Theme to compare */
+  theme?: Theme;
+
+  /** CI mode - exit 1 on differences */
+  ci?: boolean;
+
+  /** Diff threshold percentage */
+  threshold?: number;
+
+  /** Open diff images */
+  open?: boolean;
+}
+
+/**
+ * Single diff result with metadata
+ */
+export interface VariantDiffResult {
+  component: string;
+  variant: string;
+  theme: Theme;
+  result: DiffResult;
+  diffImagePath?: string;
+}
+
+/**
+ * Result of the diff command
+ */
+export interface DiffCommandResult {
+  success: boolean;
+  total: number;
+  passed: number;
+  failed: number;
+  missing: number;
+  results: VariantDiffResult[];
+  totalTimeMs: number;
+}
+
+/**
+ * Execute the diff command
+ */
+export async function runDiffCommand(
+  config: SegmentsConfig,
+  configDir: string,
+  options: DiffCommandOptions = {}
+): Promise<DiffCommandResult> {
+  const startTime = Date.now();
+  const results: VariantDiffResult[] = [];
+
+  // Initialize storage
+  const storage = new StorageManager({
+    projectRoot: configDir,
+    viewport: config.screenshots?.viewport,
+  });
+  await storage.initialize();
+
+  // Initialize diff engine
+  const threshold = options.threshold ?? config.screenshots?.threshold ?? DEFAULTS.diffThreshold;
+  const diffEngine = new DiffEngine(threshold);
+
+  // Discover segments
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+
+  if (segmentFiles.length === 0) {
+    console.log(pc.yellow('No segment files found.'));
+    return {
+      success: true,
+      total: 0,
+      passed: 0,
+      failed: 0,
+      missing: 0,
+      results: [],
+      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 {
+      // Skip failed loads
+    }
+  }
+
+  // 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,
+      total: 0,
+      passed: 0,
+      failed: 0,
+      missing: 0,
+      results: [],
+      totalTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Build list of variants to diff
+  const variantsToDiff: Array<{
+    component: string;
+    variant: string;
+  }> = [];
+
+  for (const { segment } of filteredSegments) {
+    const variants = options.variant
+      ? segment.variants.filter((v) => v.name === options.variant)
+      : segment.variants;
+
+    for (const variant of variants) {
+      variantsToDiff.push({
+        component: segment.meta.name,
+        variant: variant.name,
+      });
+    }
+  }
+
+  if (variantsToDiff.length === 0) {
+    console.log(pc.yellow('No variants to compare.'));
+    return {
+      success: true,
+      total: 0,
+      passed: 0,
+      failed: 0,
+      missing: 0,
+      results: [],
+      totalTimeMs: Date.now() - startTime,
+    };
+  }
+
+  // Determine theme
+  const theme: Theme = options.theme ?? DEFAULTS.theme;
+  const viewport = config.screenshots?.viewport ?? DEFAULTS.viewport;
+
+  console.log(pc.cyan(`\n${BRAND.name} Diff\n`));
+  console.log(pc.dim(`Comparing against baselines (theme: ${theme}, threshold: ${threshold}%):\n`));
+
+  // Initialize browser pool
+  const pool = new BrowserPool({
+    viewport,
+  });
+
+  // Create capture engine
+  const viewerPort = DEFAULTS.port;
+  const baseUrl = `http://localhost:${viewerPort}`;
+  const captureEngine = new CaptureEngine(pool, baseUrl);
+
+  let passed = 0;
+  let failed = 0;
+  let missing = 0;
+
+  const captureOptions: CaptureOptions = {
+    theme,
+    viewport,
+    delay: config.screenshots?.delay ?? DEFAULTS.captureDelayMs,
+  };
+
+  try {
+    // Warm up the pool
+    await pool.warmup();
+
+    // Compare each variant
+    for (const { component, variant } of variantsToDiff) {
+      // Load baseline
+      const baseline = await storage.loadBaseline(component, variant, theme);
+
+      if (!baseline) {
+        console.log(
+          `  ${pc.yellow('?')} ${component}/${variant} ${pc.dim('(no baseline)')}`
+        );
+        missing++;
+        continue;
+      }
+
+      try {
+        // Capture current
+        const current = await captureEngine.captureVariant(
+          component,
+          variant,
+          captureOptions
+        );
+
+        // Quick hash check
+        if (diffEngine.areIdentical(current, baseline)) {
+          console.log(`  ${pc.green('✓')} ${component}/${variant} ${pc.dim('0.0%')}`);
+          results.push({
+            component,
+            variant,
+            theme,
+            result: {
+              matches: true,
+              diffPercentage: 0,
+              diffPixelCount: 0,
+              totalPixels: current.viewport.width * current.viewport.height,
+              changedRegions: [],
+              diffTimeMs: 0,
+            },
+          });
+          passed++;
+          continue;
+        }
+
+        // Full diff
+        const diffResult = diffEngine.compare(current, baseline, { threshold });
+
+        if (diffResult.matches) {
+          console.log(
+            `  ${pc.green('✓')} ${component}/${variant} ${pc.dim(`${diffResult.diffPercentage}%`)}`
+          );
+          passed++;
+        } else {
+          // Save diff image
+          let diffImagePath: string | undefined;
+          if (diffResult.diffImage) {
+            diffImagePath = await storage.saveDiff(
+              component,
+              variant,
+              theme,
+              diffResult.diffImage
+            );
+          }
+
+          console.log(
+            `  ${pc.red('✗')} ${component}/${variant} ${pc.yellow(`${diffResult.diffPercentage}%`)}` +
+              (diffImagePath ? pc.dim(` → ${diffImagePath}`) : '')
+          );
+          failed++;
+
+          results.push({
+            component,
+            variant,
+            theme,
+            result: diffResult,
+            diffImagePath,
+          });
+          continue;
+        }
+
+        results.push({
+          component,
+          variant,
+          theme,
+          result: diffResult,
+        });
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.log(`  ${pc.red('!')} ${component}/${variant} ${pc.dim(errorMsg)}`);
+        failed++;
+      }
+    }
+  } finally {
+    // Shutdown browser pool
+    await pool.shutdown();
+  }
+
+  const totalTimeMs = Date.now() - startTime;
+  const total = passed + failed + missing;
+
+  // Print summary
+  console.log();
+  if (failed === 0 && missing === 0) {
+    console.log(pc.green(`✓ All ${passed} variant(s) match baselines`));
+  } else if (failed > 0) {
+    console.log(pc.red(`✗ ${failed} variant(s) differ from baselines`));
+  }
+
+  if (missing > 0) {
+    console.log(pc.yellow(`  ${missing} variant(s) have no baseline (run \`${BRAND.cliCommand} screenshot\`)`));
+  }
+
+  console.log(pc.dim(`  Completed in ${formatMs(totalTimeMs)}\n`));
+
+  // In CI mode, exit with error if any failed
+  const success = failed === 0;
+
+  return {
+    success,
+    total,
+    passed,
+    failed,
+    missing,
+    results,
+    totalTimeMs,
+  };
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// Re-export from core/node (Node.js-only APIs)
+export {
+  loadConfig,
+  findConfigFile,
+  discoverSegmentFiles,
+  discoverComponentFiles,
+  extractComponentName,
+} from "./core/node.js";
+export type { DiscoveredFile } from "./core/node.js";
+
+// Validators
+export { validateSchema, validateCoverage, validateAll } from "./validators.js";
+export type {
+  ValidationResult,
+  ValidationError,
+  ValidationWarning,
+} from "./validators.js";
+
+// Build
+export { buildSegments } from "./build.js";
+export type { BuildResult } from "./build.js";
+
+// Screenshot
+export { runScreenshotCommand } from "./screenshot.js";
+export type {
+  ScreenshotCommandOptions,
+  ScreenshotResult,
+} from "./screenshot.js";
+
+// Diff
+export { runDiffCommand } from "./diff.js";
+export type {
+  DiffCommandOptions,
+  DiffCommandResult,
+  VariantDiffResult,
+} from "./diff.js";
+
+// Analyze
+export { runAnalyzeCommand } from "./analyze.js";
+export type { AnalyzeOptions, AnalyzeResult } from "./analyze.js";
+
+// Static Viewer
+export { generateStaticViewer, generateViewerFromJson } from "./static-viewer.js";

package/src/mcp/__tests__/projectFields.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import { projectFields } from "../utils.js";
+
+describe("projectFields", () => {
+  describe("basic field extraction", () => {
+    it("returns full object when no fields specified", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      expect(projectFields(obj, [])).toEqual(obj);
+    });
+
+    it("extracts single top-level field", () => {
+      const obj = { name: "Button", category: "actions", status: "stable" };
+      const result = projectFields(obj, ["name"]);
+      expect(result).toEqual({ name: "Button" });
+    });
+
+    it("extracts multiple top-level fields", () => {
+      const obj = { name: "Button", category: "actions", status: "stable" };
+      const result = projectFields(obj, ["name", "category"]);
+      expect(result).toEqual({ name: "Button", category: "actions" });
+    });
+
+    it("ignores non-existent fields", () => {
+      const obj = { name: "Button" };
+      const result = projectFields(obj, ["name", "nonexistent"]);
+      expect(result).toEqual({ name: "Button" });
+    });
+  });
+
+  describe("nested field extraction", () => {
+    it("extracts nested field with dot notation", () => {
+      const obj = {
+        meta: { name: "Button", category: "actions" },
+        usage: { when: ["action needed"], whenNot: ["static text"] },
+      };
+      const result = projectFields(obj, ["meta.name"]);
+      expect(result).toEqual({ meta: { name: "Button" } });
+    });
+
+    it("extracts multiple nested fields from same parent", () => {
+      const obj = {
+        meta: { name: "Button", category: "actions", status: "stable" },
+      };
+      const result = projectFields(obj, ["meta.name", "meta.category"]);
+      expect(result).toEqual({ meta: { name: "Button", category: "actions" } });
+    });
+
+    it("extracts deeply nested fields", () => {
+      const obj = {
+        config: {
+          theme: {
+            colors: { primary: "blue", secondary: "gray" },
+          },
+        },
+      };
+      const result = projectFields(obj, ["config.theme.colors.primary"]);
+      expect(result).toEqual({
+        config: { theme: { colors: { primary: "blue" } } },
+      });
+    });
+
+    it("extracts fields from different branches", () => {
+      const obj = {
+        meta: { name: "Button" },
+        usage: { when: ["action needed"] },
+        props: { variant: { type: "enum" } },
+      };
+      const result = projectFields(obj, ["meta.name", "usage.when"]);
+      expect(result).toEqual({
+        meta: { name: "Button" },
+        usage: { when: ["action needed"] },
+      });
+    });
+  });
+
+  describe("mixed top-level and nested", () => {
+    it("handles mix of top-level and nested fields", () => {
+      const obj = {
+        name: "Button",
+        meta: { category: "actions" },
+        variants: [{ name: "Primary" }],
+      };
+      const result = projectFields(obj, ["name", "meta.category"]);
+      expect(result).toEqual({
+        name: "Button",
+        meta: { category: "actions" },
+      });
+    });
+
+    it("extracts entire nested object when parent is specified", () => {
+      const obj = {
+        meta: { name: "Button", category: "actions" },
+        usage: { when: ["x"], whenNot: ["y"] },
+      };
+      const result = projectFields(obj, ["meta"]);
+      expect(result).toEqual({
+        meta: { name: "Button", category: "actions" },
+      });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles null values in path (creates empty parent)", () => {
+      const obj = { meta: null };
+      const result = projectFields(obj as Record<string, unknown>, ["meta.name"]);
+      // When parent is null, we still create the path structure but value is undefined
+      expect(result).toEqual({ meta: {} });
+    });
+
+    it("handles undefined values in path (creates empty parent)", () => {
+      const obj = { meta: undefined };
+      const result = projectFields(obj as Record<string, unknown>, ["meta.name"]);
+      // When parent is undefined, we still create the path structure but value is undefined
+      expect(result).toEqual({ meta: {} });
+    });
+
+    it("handles arrays as values", () => {
+      const obj = {
+        usage: { when: ["use case 1", "use case 2"] },
+      };
+      const result = projectFields(obj, ["usage.when"]);
+      expect(result).toEqual({ usage: { when: ["use case 1", "use case 2"] } });
+    });
+
+    it("handles empty object", () => {
+      const result = projectFields({}, ["name"]);
+      expect(result).toEqual({});
+    });
+  });
+});

package/src/mcp/bin.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { startMcpServer } from './server.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+let projectRoot = process.cwd();
+let viewerUrl: string | undefined;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  if (arg === '--project-root' || arg === '-p') {
+    projectRoot = args[++i] ?? projectRoot;
+  } else if (arg === '--viewer-url' || arg === '-u') {
+    viewerUrl = args[++i];
+  } else if (arg === '--help' || arg === '-h') {
+    console.log(`
+Usage: fragments-mcp [options]
+
+Options:
+  -p, --project-root <path>  Project root directory (default: cwd)
+  -u, --viewer-url <url>     Viewer URL (default: http://localhost:6006)
+  -h, --help                 Show this help message
+`);
+    process.exit(0);
+  }
+}
+
+// Start server
+startMcpServer({
+  projectRoot,
+  viewerUrl,
+}).catch((error) => {
+  console.error('Failed to start MCP server:', error);
+  process.exit(1);
+});

package/src/mcp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fragments-sdk/mcp
+ *
+ * MCP server for AI agent integration with Fragments.
+ * Exposes tools for listing, querying, and verifying component fragments.
+ */
+
+export { createMcpServer, startMcpServer, type McpServerConfig } from './server.js';