@fragments-sdk/cli 0.2.2

package/src/service/storage.ts

@@ -0,0 +1,401 @@
+import { mkdir, readFile, writeFile, stat, readdir, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  BRAND,
+  DEFAULTS,
+  type Screenshot,
+  type BaselineInfo,
+  type Manifest,
+  type Viewport,
+  type Theme,
+} from '../core/index.js';
+import { ServiceError, buildScreenshotPath, computeHash } from './utils.js';
+
+/**
+ * Storage manager configuration
+ */
+export interface StorageConfig {
+  /** Root directory for project (default: process.cwd()) */
+  projectRoot?: string;
+
+  /** Default viewport */
+  viewport?: Viewport;
+
+  /** Default diff threshold */
+  threshold?: number;
+
+  /** Capture delay */
+  captureDelay?: number;
+}
+
+/**
+ * Manages baseline screenshot storage and manifest.
+ */
+export class StorageManager {
+  private readonly projectRoot: string;
+  private readonly dataDir: string;
+  private readonly screenshotsDir: string;
+  private readonly manifestPath: string;
+  private readonly config: Required<Omit<StorageConfig, 'projectRoot'>>;
+
+  private manifest: Manifest | null = null;
+
+  constructor(config: StorageConfig = {}) {
+    this.projectRoot = config.projectRoot ?? process.cwd();
+    this.dataDir = join(this.projectRoot, BRAND.dataDir);
+    this.screenshotsDir = join(this.dataDir, BRAND.screenshotsDir);
+    this.manifestPath = join(this.dataDir, BRAND.manifestFile);
+
+    this.config = {
+      viewport: config.viewport ?? DEFAULTS.viewport,
+      threshold: config.threshold ?? DEFAULTS.diffThreshold,
+      captureDelay: config.captureDelay ?? DEFAULTS.captureDelayMs,
+    };
+  }
+
+  /**
+   * Get the data directory path
+   */
+  get dataDirPath(): string {
+    return this.dataDir;
+  }
+
+  /**
+   * Get the screenshots directory path
+   */
+  get screenshotsDirPath(): string {
+    return this.screenshotsDir;
+  }
+
+  /**
+   * Initialize the storage directory structure
+   */
+  async initialize(): Promise<void> {
+    // Create directories
+    await mkdir(this.screenshotsDir, { recursive: true });
+    await mkdir(join(this.dataDir, BRAND.cacheDir), { recursive: true });
+    await mkdir(join(this.dataDir, BRAND.diffDir), { recursive: true });
+
+    // Load or create manifest
+    if (existsSync(this.manifestPath)) {
+      await this.loadManifest();
+    } else {
+      this.manifest = this.createEmptyManifest();
+      await this.saveManifest();
+    }
+  }
+
+  /**
+   * Save a screenshot as a baseline
+   */
+  async saveBaseline(screenshot: Screenshot): Promise<BaselineInfo> {
+    await this.ensureInitialized();
+
+    const { component, variant, theme } = screenshot.metadata;
+    const relativePath = buildScreenshotPath(component, variant, theme);
+    const absolutePath = join(this.screenshotsDir, relativePath);
+
+    // Ensure directory exists
+    await mkdir(dirname(absolutePath), { recursive: true });
+
+    // Write the image
+    await writeFile(absolutePath, screenshot.data);
+
+    // Get file size
+    const stats = await stat(absolutePath);
+
+    // Create baseline info
+    const baselineInfo: BaselineInfo = {
+      component,
+      variant,
+      theme,
+      path: relativePath,
+      hash: screenshot.hash,
+      viewport: screenshot.viewport,
+      capturedAt: screenshot.capturedAt.toISOString(),
+      fileSize: stats.size,
+    };
+
+    // Update manifest
+    this.updateManifestBaseline(baselineInfo);
+    await this.saveManifest();
+
+    return baselineInfo;
+  }
+
+  /**
+   * Load a baseline screenshot
+   */
+  async loadBaseline(
+    component: string,
+    variant: string,
+    theme: Theme = DEFAULTS.theme
+  ): Promise<Screenshot | null> {
+    await this.ensureInitialized();
+
+    const info = this.getBaselineInfo(component, variant, theme);
+    if (!info) {
+      return null;
+    }
+
+    const absolutePath = join(this.screenshotsDir, info.path);
+
+    if (!existsSync(absolutePath)) {
+      return null;
+    }
+
+    const data = await readFile(absolutePath);
+
+    return {
+      data,
+      hash: info.hash,
+      viewport: info.viewport,
+      capturedAt: new Date(info.capturedAt),
+      metadata: {
+        component: info.component,
+        variant: info.variant,
+        theme: info.theme,
+        renderTimeMs: 0, // Not available for loaded baselines
+        captureTimeMs: 0,
+      },
+    };
+  }
+
+  /**
+   * Get baseline info from manifest
+   */
+  getBaselineInfo(
+    component: string,
+    variant: string,
+    theme: Theme = DEFAULTS.theme
+  ): BaselineInfo | null {
+    if (!this.manifest) {
+      return null;
+    }
+
+    const key = this.buildBaselineKey(component, variant, theme);
+    const componentBaselines = this.manifest.baselines[component];
+
+    if (!componentBaselines) {
+      return null;
+    }
+
+    return componentBaselines[key] ?? null;
+  }
+
+  /**
+   * Check if a baseline exists
+   */
+  hasBaseline(
+    component: string,
+    variant: string,
+    theme: Theme = DEFAULTS.theme
+  ): boolean {
+    return this.getBaselineInfo(component, variant, theme) !== null;
+  }
+
+  /**
+   * List all baselines
+   */
+  listBaselines(): BaselineInfo[] {
+    if (!this.manifest) {
+      return [];
+    }
+
+    const baselines: BaselineInfo[] = [];
+
+    for (const componentBaselines of Object.values(this.manifest.baselines)) {
+      for (const baseline of Object.values(componentBaselines)) {
+        baselines.push(baseline);
+      }
+    }
+
+    return baselines;
+  }
+
+  /**
+   * List baselines for a specific component
+   */
+  listComponentBaselines(component: string): BaselineInfo[] {
+    if (!this.manifest) {
+      return [];
+    }
+
+    const componentBaselines = this.manifest.baselines[component];
+    if (!componentBaselines) {
+      return [];
+    }
+
+    return Object.values(componentBaselines);
+  }
+
+  /**
+   * Delete a baseline
+   */
+  async deleteBaseline(
+    component: string,
+    variant: string,
+    theme: Theme = DEFAULTS.theme
+  ): Promise<boolean> {
+    await this.ensureInitialized();
+
+    const info = this.getBaselineInfo(component, variant, theme);
+    if (!info) {
+      return false;
+    }
+
+    // Delete the file
+    const absolutePath = join(this.screenshotsDir, info.path);
+    if (existsSync(absolutePath)) {
+      await rm(absolutePath);
+    }
+
+    // Remove from manifest
+    const key = this.buildBaselineKey(component, variant, theme);
+    if (this.manifest?.baselines[component]) {
+      delete this.manifest.baselines[component][key];
+
+      // Clean up empty component entry
+      if (Object.keys(this.manifest.baselines[component]).length === 0) {
+        delete this.manifest.baselines[component];
+      }
+    }
+
+    await this.saveManifest();
+    return true;
+  }
+
+  /**
+   * Save a diff image
+   */
+  async saveDiff(
+    component: string,
+    variant: string,
+    theme: Theme,
+    diffImage: Buffer
+  ): Promise<string> {
+    const relativePath = buildScreenshotPath(component, variant, theme).replace(
+      '.png',
+      '-diff.png'
+    );
+    const absolutePath = join(this.dataDir, BRAND.diffDir, relativePath);
+
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, diffImage);
+
+    return absolutePath;
+  }
+
+  /**
+   * Get the manifest
+   */
+  getManifest(): Manifest | null {
+    return this.manifest;
+  }
+
+  /**
+   * Reload manifest from disk
+   */
+  async reloadManifest(): Promise<void> {
+    await this.loadManifest();
+  }
+
+  /**
+   * Build a unique key for baseline lookup
+   */
+  private buildBaselineKey(
+    component: string,
+    variant: string,
+    theme: Theme
+  ): string {
+    return `${variant}:${theme}`;
+  }
+
+  /**
+   * Update manifest with a baseline
+   */
+  private updateManifestBaseline(info: BaselineInfo): void {
+    if (!this.manifest) {
+      this.manifest = this.createEmptyManifest();
+    }
+
+    if (!this.manifest.baselines[info.component]) {
+      this.manifest.baselines[info.component] = {};
+    }
+
+    const key = this.buildBaselineKey(info.component, info.variant, info.theme);
+    this.manifest.baselines[info.component][key] = info;
+    this.manifest.generatedAt = new Date().toISOString();
+  }
+
+  /**
+   * Create an empty manifest
+   */
+  private createEmptyManifest(): Manifest {
+    return {
+      version: '1.0.0',
+      generatedAt: new Date().toISOString(),
+      config: {
+        defaultViewport: this.config.viewport,
+        defaultThreshold: this.config.threshold,
+        captureDelay: this.config.captureDelay,
+      },
+      baselines: {},
+    };
+  }
+
+  /**
+   * Load manifest from disk
+   */
+  private async loadManifest(): Promise<void> {
+    try {
+      const content = await readFile(this.manifestPath, 'utf-8');
+      this.manifest = JSON.parse(content) as Manifest;
+    } catch {
+      this.manifest = this.createEmptyManifest();
+    }
+  }
+
+  /**
+   * Save manifest to disk
+   */
+  private async saveManifest(): Promise<void> {
+    if (!this.manifest) {
+      return;
+    }
+
+    await mkdir(dirname(this.manifestPath), { recursive: true });
+    await writeFile(
+      this.manifestPath,
+      JSON.stringify(this.manifest, null, 2),
+      'utf-8'
+    );
+  }
+
+  /**
+   * Ensure storage is initialized
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (!this.manifest) {
+      await this.initialize();
+    }
+  }
+}
+
+/**
+ * Error class for storage errors
+ */
+export class StorageError extends ServiceError {
+  constructor(message: string, code: string, suggestion?: string) {
+    super(message, code, suggestion);
+    this.name = `${BRAND.name}StorageError`;
+  }
+}
+
+/**
+ * Create a storage manager
+ */
+export function createStorageManager(config?: StorageConfig): StorageManager {
+  return new StorageManager(config);
+}

package/src/service/token-fixes.ts

@@ -0,0 +1,281 @@
+/**
+ * Token Fix Suggestions
+ *
+ * Generates AI-friendly fix suggestions when hardcoded values
+ * should be replaced with design tokens.
+ */
+
+import type {
+  DesignToken,
+  EnhancedStyleDiffItem,
+  TokenFix,
+  TokenUsageSummary,
+} from "../core/index.js";
+import { TokenRegistryManager } from "./token-registry.js";
+
+/**
+ * Context for AI agents to understand and fix token issues
+ */
+export interface TokenFixContext {
+  /** Component name */
+  componentName: string;
+
+  /** Summary of token usage */
+  summary: TokenUsageSummary;
+
+  /** Detailed fix suggestions for each hardcoded property */
+  fixes: TokenFixDetail[];
+
+  /** Markdown-formatted context for AI agents */
+  markdown: string;
+
+  /** JSON-formatted context for programmatic use */
+  json: {
+    component: string;
+    compliancePercent: number;
+    totalProperties: number;
+    hardcodedCount: number;
+    fixes: Array<{
+      property: string;
+      currentValue: string;
+      suggestedToken: string;
+      tokenValue: string;
+      codeFix: string;
+      reason: string;
+    }>;
+  };
+}
+
+/**
+ * Detailed fix for a single property
+ */
+export interface TokenFixDetail {
+  /** CSS property name (e.g., "backgroundColor") */
+  property: string;
+
+  /** CSS property name in kebab-case (e.g., "background-color") */
+  cssProperty: string;
+
+  /** Current hardcoded value */
+  currentValue: string;
+
+  /** Token that should be used */
+  suggestedToken: DesignToken;
+
+  /** The code fix to apply */
+  codeFix: string;
+
+  /** Confidence score 0-1 */
+  confidence: number;
+
+  /** Human-readable explanation */
+  reason: string;
+}
+
+/**
+ * Generate token fixes for a set of style diffs
+ */
+export function generateTokenFixes(
+  componentName: string,
+  styleDiffs: Array<{
+    property: string;
+    figma: string;
+    rendered: string;
+    match: boolean;
+  }>,
+  registry: TokenRegistryManager,
+  theme = "default"
+): TokenFixContext {
+  // Calculate usage summary
+  const summary = registry.calculateUsageSummary(styleDiffs, theme);
+
+  // Generate detailed fixes
+  const fixes: TokenFixDetail[] = [];
+
+  for (const hardcoded of summary.hardcodedProperties) {
+    if (!hardcoded.suggestedFix) continue;
+
+    const token = registry.getToken(hardcoded.suggestedFix.tokenName);
+    if (!token) continue;
+
+    const cssProperty = toCssProperty(hardcoded.property);
+
+    fixes.push({
+      property: hardcoded.property,
+      cssProperty,
+      currentValue: hardcoded.rendered,
+      suggestedToken: token,
+      codeFix: hardcoded.suggestedFix.codeFix,
+      confidence: hardcoded.suggestedFix.confidence,
+      reason: hardcoded.suggestedFix.reason,
+    });
+  }
+
+  // Generate markdown context for AI
+  const markdown = generateMarkdownContext(componentName, summary, fixes);
+
+  // Generate JSON context
+  const json = {
+    component: componentName,
+    compliancePercent: summary.compliancePercent,
+    totalProperties: summary.totalProperties,
+    hardcodedCount: summary.hardcoded,
+    fixes: fixes.map((f) => ({
+      property: f.property,
+      currentValue: f.currentValue,
+      suggestedToken: f.suggestedToken.name,
+      tokenValue: f.suggestedToken.resolvedValue,
+      codeFix: f.codeFix,
+      reason: f.reason,
+    })),
+  };
+
+  return {
+    componentName,
+    summary,
+    fixes,
+    markdown,
+    json,
+  };
+}
+
+/**
+ * Generate markdown context for AI agents
+ */
+function generateMarkdownContext(
+  componentName: string,
+  summary: TokenUsageSummary,
+  fixes: TokenFixDetail[]
+): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`## Design Token Analysis: ${componentName}`);
+  lines.push("");
+
+  // Summary
+  lines.push(`### Compliance: ${summary.compliancePercent}%`);
+  lines.push("");
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total Properties | ${summary.totalProperties} |`);
+  lines.push(`| Using Tokens | ${summary.usingTokens} |`);
+  lines.push(`| Hardcoded | ${summary.hardcoded} |`);
+  lines.push(`| Implicit Matches | ${summary.implicitMatches} |`);
+  lines.push("");
+
+  if (fixes.length === 0) {
+    lines.push("✅ **All styles are using design tokens correctly.**");
+    return lines.join("\n");
+  }
+
+  // Issues
+  lines.push(`### Issues Found: ${fixes.length} hardcoded value(s)`);
+  lines.push("");
+
+  for (let i = 0; i < fixes.length; i++) {
+    const fix = fixes[i];
+    lines.push(`#### ${i + 1}. \`${fix.cssProperty}\``);
+    lines.push("");
+    lines.push(`- **Current Value**: \`${fix.currentValue}\``);
+    lines.push(`- **Suggested Token**: \`${fix.suggestedToken.name}\` (${fix.suggestedToken.resolvedValue})`);
+    lines.push(`- **Confidence**: ${Math.round(fix.confidence * 100)}%`);
+    lines.push("");
+    lines.push("**Fix:**");
+    lines.push("```css");
+    lines.push(`/* Before */ ${fix.cssProperty}: ${fix.currentValue};`);
+    lines.push(`/* After  */ ${fix.codeFix}`);
+    lines.push("```");
+    lines.push("");
+    lines.push(`> ${fix.reason}`);
+    lines.push("");
+  }
+
+  // Why use tokens
+  lines.push("### Why Use Design Tokens?");
+  lines.push("");
+  lines.push("1. **Consistency**: Ensures visual consistency across the application");
+  lines.push("2. **Maintainability**: Change a token value once, update everywhere");
+  lines.push("3. **Theming**: Enables dark mode and other theme variations");
+  lines.push("4. **Design System Compliance**: Keeps code aligned with design specifications");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate AI context for a single component's token issues
+ *
+ * This format is optimized for AI agents to understand and fix
+ */
+export function generateAIFixContext(
+  componentName: string,
+  hardcodedItems: EnhancedStyleDiffItem[],
+  registry: TokenRegistryManager
+): string {
+  if (hardcodedItems.length === 0) {
+    return `Component "${componentName}" is fully compliant with design tokens.`;
+  }
+
+  const lines: string[] = [];
+
+  lines.push(`# Design Token Fix Required: ${componentName}`);
+  lines.push("");
+  lines.push(`Found ${hardcodedItems.length} hardcoded CSS value(s) that should use design tokens.`);
+  lines.push("");
+
+  for (const item of hardcodedItems) {
+    if (!item.suggestedFix) continue;
+
+    const token = registry.getToken(item.suggestedFix.tokenName);
+    const cssProperty = toCssProperty(item.property);
+
+    lines.push(`## Issue: Hardcoded \`${cssProperty}\``);
+    lines.push("");
+    lines.push("| | |");
+    lines.push("|---|---|");
+    lines.push(`| **Property** | \`${cssProperty}\` |`);
+    lines.push(`| **Current Value** | \`${item.rendered}\` |`);
+    lines.push(`| **Expected Token** | \`${item.suggestedFix.tokenName}\` |`);
+    lines.push(`| **Token Value** | \`${token?.resolvedValue || item.suggestedFix.tokenValue}\` |`);
+    lines.push("");
+    lines.push("**Suggested Fix:**");
+    lines.push("```css");
+    lines.push(`/* Replace hardcoded value */`);
+    lines.push(`${cssProperty}: var(${item.suggestedFix.tokenName});`);
+    lines.push("```");
+    lines.push("");
+
+    if (token) {
+      lines.push("**Token Details:**");
+      lines.push(`- Category: ${token.category}`);
+      lines.push(`- Level: ${token.level === 1 ? "Base" : token.level === 2 ? "Semantic" : "Component"}`);
+      lines.push(`- Theme: ${token.theme}`);
+      if (token.description) {
+        lines.push(`- Description: ${token.description}`);
+      }
+      lines.push("");
+    }
+
+    lines.push("---");
+    lines.push("");
+  }
+
+  lines.push("## Why This Matters");
+  lines.push("");
+  lines.push("Using design tokens instead of hardcoded values:");
+  lines.push("- Ensures the component matches the Figma design");
+  lines.push("- Enables automatic theme switching (light/dark mode)");
+  lines.push("- Maintains consistency across the design system");
+  lines.push("- Makes future design updates easier");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Convert camelCase to kebab-case
+ */
+function toCssProperty(prop: string): string {
+  return prop.replace(/([A-Z])/g, "-$1").toLowerCase();
+}