@fragments-sdk/cli 0.2.2

package/src/commands/link/figma.ts

@@ -0,0 +1,645 @@
+/**
+ * fragments link figma - Link Figma components to segments
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import pc from 'picocolors';
+import { BRAND } from '../../core/index.js';
+import { loadConfig, discoverSegmentFiles } from '../../core/node.js';
+import { FigmaClient } from '../../service/index.js';
+
+/**
+ * Options for link figma command
+ */
+export interface LinkFigmaOptions {
+  /** Path to config file */
+  config?: string;
+  /** Auto-link matching components without prompts */
+  auto?: boolean;
+  /** Show matches without updating files */
+  dryRun?: boolean;
+  /** Link individual variants to their Figma frames */
+  variants?: boolean;
+}
+
+/**
+ * Result of link figma command
+ */
+export interface LinkFigmaResult {
+  success: boolean;
+  updated: number;
+  variantUpdates: number;
+}
+
+/**
+ * Segment variant info
+ */
+interface SegmentVariantInfo {
+  name: string;
+  hasFigma: boolean;
+}
+
+/**
+ * Segment info
+ */
+interface SegmentInfo {
+  name: string;
+  filePath: string;
+  relativePath: string;
+  hasFigma: boolean;
+  variants: SegmentVariantInfo[];
+}
+
+/**
+ * Match result
+ */
+interface Match {
+  segment: SegmentInfo;
+  figmaComponent: {
+    name: string;
+    description: string;
+    key: string;
+    file_key: string;
+    node_id: string;
+  };
+  score: number;
+  alreadyLinked?: boolean;
+}
+
+/**
+ * Run the link figma command
+ */
+export async function linkFigma(
+  figmaUrl: string | undefined,
+  options: LinkFigmaOptions = {}
+): Promise<LinkFigmaResult> {
+  const { config: configPath, auto = false, dryRun = false, variants = true } = 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);
+  }
+
+  console.log(pc.cyan(`\n${BRAND.name} Link Wizard\n`));
+
+  // Load config to check for figmaFile
+  const { config, configDir } = await loadConfig(configPath);
+
+  // Get Figma URL: CLI arg > config > interactive prompt
+  let fileUrl = figmaUrl || config.figmaFile;
+
+  if (!fileUrl) {
+    const { input } = await import('@inquirer/prompts');
+
+    console.log(pc.dim('Tip: Add `figmaFile` to fragments.config.ts to skip this prompt\n'));
+
+    try {
+      fileUrl = await input({
+        message: 'Enter Figma file URL:',
+        validate: (value) => {
+          if (!value.trim()) return 'URL is required';
+          if (!value.includes('figma.com')) return 'Please enter a valid Figma URL';
+          return true;
+        },
+      });
+    } catch {
+      // User cancelled (Ctrl+C)
+      console.log(pc.dim('\nNo changes made.'));
+      process.exit(0);
+    }
+  } else if (config.figmaFile && !figmaUrl) {
+    console.log(pc.dim(`Using Figma file from config: ${config.figmaFile}\n`));
+  }
+
+  // Import FigmaClient
+  const figmaClient = new FigmaClient({ accessToken: process.env.FIGMA_ACCESS_TOKEN });
+
+  // Parse the URL to get file key
+  console.log(pc.dim('Parsing Figma URL...'));
+  const { fileKey } = figmaClient.parseFileUrl(fileUrl);
+
+  // Fetch components from Figma
+  console.log(pc.dim('Fetching components from Figma...'));
+  const figmaData = await figmaClient.getFileComponents(fileKey);
+
+  // Use component sets (main components) preferentially
+  const allFigmaComponents = figmaData.componentSets.length > 0
+    ? figmaData.componentSets
+    : figmaData.components;
+
+  if (allFigmaComponents.length === 0) {
+    console.log(pc.yellow('\nNo components found in Figma file.'));
+    console.log(pc.dim('Make sure the file contains published components.'));
+    process.exit(0);
+  }
+
+  const componentType = figmaData.componentSets.length > 0 ? 'component set' : 'component';
+  console.log(pc.green(`✓ Found ${allFigmaComponents.length} Figma ${componentType}(s) in "${figmaData.fileName}"`));
+  if (figmaData.components.length > 0 && figmaData.componentSets.length > 0) {
+    console.log(pc.dim(`  (${figmaData.components.length} individual components also available)\n`));
+  } else {
+    console.log();
+  }
+
+  // Discover local segments
+  const segmentFiles = await discoverSegmentFiles(config, configDir);
+
+  if (segmentFiles.length === 0) {
+    console.log(pc.yellow('No segment files found in codebase.'));
+    console.log(pc.dim(`Looking for: ${config.include.join(', ')}`));
+    process.exit(0);
+  }
+
+  console.log(pc.dim(`Found ${segmentFiles.length} segment file(s)\n`));
+
+  // Load segments to get names
+  const segments: SegmentInfo[] = [];
+  for (const file of segmentFiles) {
+    try {
+      const content = await readFile(file.absolutePath, 'utf-8');
+      // Extract name from meta.name in the file
+      const nameMatch = content.match(/name:\s*['"]([^'"]+)['"]/);
+      // Check if figma is already set in meta
+      const hasFigma = /meta:\s*\{[^}]*figma:\s*['"]https?:/.test(content);
+
+      // Extract variant names and their figma status
+      const segmentVariants = extractVariants(content, nameMatch?.[1]);
+
+      if (nameMatch) {
+        segments.push({
+          name: nameMatch[1],
+          filePath: file.absolutePath,
+          relativePath: file.relativePath,
+          hasFigma,
+          variants: segmentVariants,
+        });
+      }
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  // Find matches
+  const matches: Match[] = [];
+  const unmatchedSegments: SegmentInfo[] = [];
+
+  for (const segment of segments) {
+    // Find best matching Figma component
+    let bestMatch: typeof allFigmaComponents[0] | null = null;
+    let bestScore = 0;
+
+    for (const figmaComp of allFigmaComponents) {
+      const score = calculateMatchScore(segment.name, figmaComp.name);
+
+      if (score > bestScore) {
+        bestMatch = figmaComp;
+        bestScore = score;
+
+        // Perfect match, no need to continue
+        if (score === 100) break;
+      }
+    }
+
+    // Accept matches with 65%+ score
+    if (bestMatch && bestScore >= 65) {
+      const alreadyLinked = segment.hasFigma;
+      if (alreadyLinked && !auto) {
+        console.log(pc.dim(`⏭️  ${segment.name} (already linked)`));
+      }
+      matches.push({ segment, figmaComponent: bestMatch, score: bestScore, alreadyLinked });
+    } else {
+      unmatchedSegments.push(segment);
+    }
+  }
+
+  if (unmatchedSegments.length > 0) {
+    console.log(pc.dim('Unmatched segments:'));
+    for (const seg of unmatchedSegments) {
+      console.log(`  ${pc.dim('•')} ${seg.name}`);
+    }
+    console.log();
+  }
+
+  // Split matches into new and already-linked
+  const newMatches = matches.filter((m) => !m.alreadyLinked);
+  const alreadyLinkedMatches = matches.filter((m) => m.alreadyLinked);
+
+  if (matches.length === 0) {
+    console.log(pc.yellow('\nNo automatic matches found.'));
+    console.log(pc.dim('You can manually add figma URLs to your segment definitions.'));
+    process.exit(0);
+  }
+
+  // Dry run - just show what would be done
+  if (dryRun) {
+    if (newMatches.length > 0) {
+      console.log(pc.bold('\nMatched Components:\n'));
+      for (const match of newMatches) {
+        const scoreColor = match.score === 100 ? pc.green : pc.yellow;
+        console.log(
+          `  ${pc.green('✓')} ${pc.bold(match.segment.name)} → ${match.figmaComponent.name} ${scoreColor(`(${Math.round(match.score)}%)`)}`
+        );
+      }
+    }
+    console.log(pc.yellow('\n[Dry run - no files were updated]'));
+    return { success: true, updated: 0, variantUpdates: 0 };
+  }
+
+  // Interactive selection or auto mode (only for new components)
+  let selectedMatches: Match[] = newMatches;
+
+  if (newMatches.length > 0) {
+    if (auto) {
+      // Auto mode - show matches and proceed
+      console.log(pc.bold('\nMatched Components:\n'));
+      for (const match of newMatches) {
+        const scoreColor = match.score === 100 ? pc.green : pc.yellow;
+        console.log(
+          `  ${pc.green('✓')} ${pc.bold(match.segment.name)} → ${match.figmaComponent.name} ${scoreColor(`(${Math.round(match.score)}%)`)}`
+        );
+      }
+    } else {
+      // Interactive selection with checkbox
+      const { checkbox } = await import('@inquirer/prompts');
+
+      console.log(pc.bold('\nMatched Components:\n'));
+      console.log(pc.dim('Use ↑/↓ to navigate, Space to toggle, Enter to confirm\n'));
+
+      const choices = newMatches.map((match) => {
+        const scoreColor = match.score === 100 ? pc.green : pc.yellow;
+        return {
+          name: `${pc.bold(match.segment.name)} → ${match.figmaComponent.name} ${scoreColor(`(${Math.round(match.score)}%)`)}`,
+          value: match,
+          checked: true,
+        };
+      });
+
+      try {
+        selectedMatches = await checkbox({
+          message: 'Select components to link:',
+          choices,
+          pageSize: 20,
+        });
+      } catch {
+        // User cancelled (Ctrl+C)
+        console.log(pc.dim('\nNo changes made.'));
+        return { success: true, updated: 0, variantUpdates: 0 };
+      }
+    }
+  }
+
+  // Include already-linked matches for variant linking
+  const allSelectedMatches = [...selectedMatches, ...alreadyLinkedMatches];
+
+  // Update segment files (only for new matches, not already-linked)
+  let updated = 0;
+  for (const match of selectedMatches) {
+    if (match.alreadyLinked) continue;
+
+    try {
+      let content = await readFile(match.segment.filePath, 'utf-8');
+      const figmaUrlToInsert = figmaClient.buildNodeUrl(
+        match.figmaComponent.file_key,
+        match.figmaComponent.node_id,
+        figmaData.fileName
+      );
+
+      // Check if figma field already exists in meta
+      if (/meta:\s*\{[^}]*figma:/.test(content)) {
+        // Replace existing figma URL
+        content = content.replace(
+          /(meta:\s*\{[^}]*figma:\s*['"])([^'"]*)['"]/,
+          `$1${figmaUrlToInsert}'`
+        );
+      } else {
+        // Add figma field after category in meta
+        content = content.replace(
+          /(meta:\s*\{[^}]*category:\s*['"][^'"]*['"],?)/,
+          `$1\n    figma: '${figmaUrlToInsert}',`
+        );
+      }
+
+      await writeFile(match.segment.filePath, content);
+      updated++;
+      console.log(`  ${pc.green('✓')} Updated ${match.segment.relativePath}`);
+    } catch (error) {
+      console.log(`  ${pc.red('✗')} Failed to update ${match.segment.relativePath}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  }
+
+  if (updated > 0) {
+    console.log(pc.green(`\n✓ Updated ${updated} segment file(s)\n`));
+  }
+
+  // Variant linking
+  let variantUpdates = 0;
+  if (variants && figmaData.componentSets.length > 0) {
+    variantUpdates = await linkVariants(
+      allSelectedMatches,
+      figmaData,
+      figmaClient,
+      fileKey
+    );
+  }
+
+  // Next steps
+  console.log(pc.dim('───────────────────────────────────────'));
+  console.log(pc.bold('\nNext steps:'));
+  console.log(`  1. Run ${pc.cyan(`${BRAND.cliCommand} compare --all`)} to verify designs`);
+  console.log(`  2. Add figmaProps mappings for prop-level linking`);
+  console.log();
+
+  return { success: true, updated, variantUpdates };
+}
+
+/**
+ * Extract variants from segment file content
+ */
+function extractVariants(content: string, componentName?: string): SegmentVariantInfo[] {
+  const variants: SegmentVariantInfo[] = [];
+
+  // Find variants: [ ... ] section
+  const variantsArrayMatch = content.match(/variants:\s*\[/);
+  if (variantsArrayMatch && variantsArrayMatch.index !== undefined) {
+    const variantsStart = variantsArrayMatch.index + variantsArrayMatch[0].length;
+    // Find matching closing bracket
+    let bracketCount = 1;
+    let variantsEnd = variantsStart;
+    while (bracketCount > 0 && variantsEnd < content.length) {
+      if (content[variantsEnd] === '[') bracketCount++;
+      if (content[variantsEnd] === ']') bracketCount--;
+      variantsEnd++;
+    }
+    const variantsSection = content.slice(variantsStart, variantsEnd - 1);
+
+    // Find all variant objects within the variants array
+    const variantNameRegex = /\{\s*\n?\s*name:\s*['"]([^'"]+)['"]/g;
+    let variantMatch;
+    while ((variantMatch = variantNameRegex.exec(variantsSection)) !== null) {
+      const variantName = variantMatch[1];
+      // Skip if this matches the component name
+      if (componentName && variantName === componentName) continue;
+
+      // Find the extent of this variant object
+      const objectStart = variantMatch.index;
+      let braceCount = 1;
+      let objectEnd = objectStart + 1;
+      while (braceCount > 0 && objectEnd < variantsSection.length) {
+        if (variantsSection[objectEnd] === '{') braceCount++;
+        if (variantsSection[objectEnd] === '}') braceCount--;
+        objectEnd++;
+      }
+      const objectContent = variantsSection.slice(objectStart, objectEnd);
+
+      // Check if this variant has a figma URL
+      const variantHasFigma = /figma:\s*['"]https?:/.test(objectContent);
+
+      variants.push({
+        name: variantName,
+        hasFigma: variantHasFigma,
+      });
+    }
+  }
+
+  return variants;
+}
+
+/**
+ * Calculate match score between two names
+ */
+function calculateMatchScore(segmentName: string, figmaName: string): number {
+  const normalizeForMatch = (s: string) =>
+    s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  const normalizedSegment = normalizeForMatch(segmentName);
+  const normalizedFigma = normalizeForMatch(figmaName);
+
+  // Exact match after normalization
+  if (normalizedSegment === normalizedFigma) {
+    return 100;
+  }
+
+  // Check if segment name appears at the START of figma name
+  if (normalizedFigma.startsWith(normalizedSegment)) {
+    const coverage = normalizedSegment.length / normalizedFigma.length;
+    return Math.max(85, coverage * 100);
+  }
+
+  // Check if figma name appears at the START of segment name
+  if (normalizedSegment.startsWith(normalizedFigma)) {
+    const coverage = normalizedFigma.length / normalizedSegment.length;
+    return Math.max(80, coverage * 100);
+  }
+
+  // Word-based matching
+  const getWords = (s: string): string[] => {
+    return s
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      .replace(/[^a-zA-Z0-9]+/g, ' ')
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 0);
+  };
+
+  const segmentWords = getWords(segmentName);
+  const figmaWords = getWords(figmaName);
+
+  // Check if all segment words appear in figma words
+  const allSegmentWordsInFigma = segmentWords.every((sw) =>
+    figmaWords.some((fw) => fw === sw || fw.startsWith(sw) || sw.startsWith(fw))
+  );
+
+  if (allSegmentWordsInFigma && segmentWords.length > 0) {
+    const wordOverlap = segmentWords.length / Math.max(segmentWords.length, figmaWords.length);
+    return Math.max(75, wordOverlap * 95);
+  }
+
+  // Partial containment
+  if (normalizedFigma.includes(normalizedSegment)) {
+    return 70;
+  }
+  if (normalizedSegment.includes(normalizedFigma)) {
+    return 65;
+  }
+
+  return 0;
+}
+
+/**
+ * Link variants to Figma frames
+ */
+async function linkVariants(
+  matches: Match[],
+  figmaData: any,
+  figmaClient: FigmaClient,
+  fileKey: string
+): Promise<number> {
+  console.log(pc.bold('\nLinking variants...\n'));
+
+  // Fetch variants for matched component sets
+  const matchedComponentSets = matches
+    .map((m) => m.figmaComponent)
+    .filter((c) => figmaData.componentSets.some((cs: any) => cs.key === c.key));
+
+  if (matchedComponentSets.length === 0) {
+    return 0;
+  }
+
+  console.log(pc.dim('Fetching Figma variants...'));
+  const componentSetVariants = await figmaClient.getComponentSetVariants(fileKey, matchedComponentSets);
+
+  let variantUpdates = 0;
+  const { select } = await import('@inquirer/prompts');
+
+  const normalizeForMatch = (s: string) =>
+    s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+  const escapeRegExp = (s: string) =>
+    s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  for (const match of matches) {
+    const csWithVariants = componentSetVariants.find(
+      (cs) => cs.componentSet.key === match.figmaComponent.key
+    );
+
+    if (!csWithVariants || csWithVariants.variants.length === 0) {
+      continue;
+    }
+
+    // Match segment variants to Figma variants
+    const segmentVariants = match.segment.variants.filter((v) => !v.hasFigma);
+    if (segmentVariants.length === 0) {
+      console.log(pc.dim(`  ⏭️  ${match.segment.name}: all variants already linked`));
+      continue;
+    }
+
+    console.log(pc.dim(`  ${match.segment.name}: ${csWithVariants.variants.length} Figma variants`));
+
+    for (const segmentVariant of segmentVariants) {
+      // Find matching Figma variants by score
+      const variantMatches: Array<{
+        figmaVariant: typeof csWithVariants.variants[0];
+        score: number;
+      }> = [];
+
+      for (const fv of csWithVariants.variants) {
+        // Check if any property value matches the segment variant name
+        const normalizedSegment = normalizeForMatch(segmentVariant.name);
+
+        for (const value of fv.values) {
+          const normalizedValue = normalizeForMatch(value);
+
+          if (normalizedSegment === normalizedValue) {
+            variantMatches.push({ figmaVariant: fv, score: 100 });
+            break;
+          } else if (normalizedValue.includes(normalizedSegment)) {
+            variantMatches.push({ figmaVariant: fv, score: 85 });
+          } else if (normalizedSegment.includes(normalizedValue)) {
+            variantMatches.push({ figmaVariant: fv, score: 75 });
+          }
+        }
+      }
+
+      // Sort by score
+      variantMatches.sort((a, b) => b.score - a.score);
+
+      // If perfect match, use it automatically
+      if (variantMatches.length > 0 && variantMatches[0].score === 100) {
+        const bestMatch = variantMatches[0];
+        const variantUrl = figmaClient.buildNodeUrl(
+          match.figmaComponent.file_key,
+          bestMatch.figmaVariant.node_id,
+          figmaData.fileName
+        );
+
+        try {
+          let content = await readFile(match.segment.filePath, 'utf-8');
+
+          // Add figma URL after the variant's name field
+          const namePattern = new RegExp(
+            `(name:\\s*['"]${escapeRegExp(segmentVariant.name)}['"],?)`,
+            'g'
+          );
+
+          let replaced = false;
+          content = content.replace(namePattern, (matchedStr) => {
+            if (replaced) return matchedStr;
+            replaced = true;
+            return `${matchedStr}\n      figma: '${variantUrl}',`;
+          });
+
+          await writeFile(match.segment.filePath, content);
+          variantUpdates++;
+          console.log(
+            `    ${pc.green('✓')} ${segmentVariant.name} → ${bestMatch.figmaVariant.name}`
+          );
+        } catch (error) {
+          console.log(
+            `    ${pc.red('✗')} ${segmentVariant.name}: ${error instanceof Error ? error.message : 'Unknown error'}`
+          );
+        }
+      } else if (variantMatches.length > 0) {
+        // Multiple possible matches - ask user
+        const choices = [
+          ...variantMatches.slice(0, 4).map((m) => ({
+            name: `${m.figmaVariant.name} (${m.score}%)`,
+            value: m.figmaVariant,
+          })),
+          { name: 'Skip this variant', value: null },
+        ];
+
+        try {
+          const selectedVariant = await select({
+            message: `  Match for "${segmentVariant.name}":`,
+            choices,
+          });
+
+          if (selectedVariant) {
+            const variantUrl = figmaClient.buildNodeUrl(
+              match.figmaComponent.file_key,
+              selectedVariant.node_id,
+              figmaData.fileName
+            );
+
+            let content = await readFile(match.segment.filePath, 'utf-8');
+            const namePattern = new RegExp(
+              `(name:\\s*['"]${escapeRegExp(segmentVariant.name)}['"],?)`,
+              'g'
+            );
+
+            let replaced = false;
+            content = content.replace(namePattern, (matchedStr) => {
+              if (replaced) return matchedStr;
+              replaced = true;
+              return `${matchedStr}\n      figma: '${variantUrl}',`;
+            });
+
+            await writeFile(match.segment.filePath, content);
+            variantUpdates++;
+            console.log(
+              `    ${pc.green('✓')} ${segmentVariant.name} → ${selectedVariant.name}`
+            );
+          } else {
+            console.log(`    ${pc.dim('⏭️')} ${segmentVariant.name} (skipped)`);
+          }
+        } catch {
+          console.log(`    ${pc.dim('⏭️')} ${segmentVariant.name} (cancelled)`);
+        }
+      } else {
+        console.log(`    ${pc.yellow('?')} ${segmentVariant.name}: no matching Figma variant`);
+      }
+    }
+  }
+
+  if (variantUpdates > 0) {
+    console.log(pc.green(`\n✓ Linked ${variantUpdates} variant(s)\n`));
+  } else {
+    console.log(pc.dim('\nNo variant updates made.\n'));
+  }
+
+  return variantUpdates;
+}

package/src/commands/link/index.ts

@@ -0,0 +1,10 @@
+/**
+ * fragments link - Link external resources to segments
+ *
+ * This module provides subcommands for:
+ * - figma: Link Figma components to segments
+ * - storybook: Bootstrap segments from Storybook stories
+ */
+
+export { linkFigma, type LinkFigmaOptions, type LinkFigmaResult } from './figma.js';
+export { linkStorybook, type LinkStorybookOptions, type LinkStorybookResult } from './storybook.js';