@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/figma/sync-main.js

@@ -0,0 +1,692 @@
+#!/usr/bin/env node
+
+/**
+ * Figma Variables Sync Script - Main Entry Point
+ *
+ * Syncs design tokens from hammer-token/src to Figma variables using the Figma REST API.
+ * Handles token parsing, reference resolution, variable creation/updates, and mode management.
+ */
+
+const { loadConfig, getAccessToken, getAuthMethod } = require("./auth");
+const { debugLog, figmaRequest } = require("./figma-api");
+const {
+  detectThemes,
+  loadThemeTokenFiles,
+  parseTokenFile,
+  flattenTokenTree,
+  pathToVariableName,
+} = require("./token-parsing");
+const { resolvePrimitiveReferences } = require("./token-resolution");
+const { syncTheme } = require("./sync-orchestration");
+const {
+  maskToken,
+  validateFileKey,
+  parseCliArgs,
+  formatDuration,
+  printHelp,
+} = require("./utils");
+const {
+  ConfigurationError,
+  AuthenticationError,
+  FileAccessError,
+} = require("./errors");
+const { FIGMA_PROD_FILE_KEY } = require("./constants");
+
+// Configuration
+const FIGMA_API_BASE = "https://api.figma.com/v1";
+
+/**
+ * Main sync function
+ * @param {string} [fileKey] - Optional fileKey to override the default or env var
+ * @param {Object} [options] - Sync options
+ * @param {boolean} [options.dryRun=false] - If true, validate without making changes
+ * @param {boolean} [options.verbose=false] - Enable verbose logging
+ * @returns {Promise<Object>} Sync statistics
+ */
+async function syncToFigma(fileKey = null, options = {}) {
+  const { dryRun = false, verbose = false } = options;
+  const startTime = Date.now();
+  const apiCallCount = 0;
+
+  if (dryRun) {
+    console.log("🔍 DRY RUN MODE - No changes will be made\n");
+  }
+  console.log("🚀 Starting Figma variables sync...\n");
+
+  try {
+    // Validate fileKey if provided
+    if (fileKey) {
+      validateFileKey(fileKey);
+    }
+
+    // Load configuration
+    const config = loadConfig(fileKey);
+    console.log(`📁 Using Figma file: ${config.fileKey}`);
+    console.log(`📦 Collection: ${config.collectionName}`);
+
+    // Get access token (supports both PAT and OAuth2)
+    const authMethod = await getAuthMethod(config);
+    const accessToken = await getAccessToken(config);
+    console.log(`🔑 Auth method: ${authMethod}`);
+    if (verbose) {
+      console.log(`🔑 Token: ${maskToken(accessToken)}\n`);
+    } else {
+      console.log();
+    }
+
+    // Set accessToken for API calls (for backward compatibility)
+    config.accessToken = accessToken;
+
+    // Skip dedicated file verification: GET /files/:key (even with ?depth=1) can return
+    // "Request too large" on very large files. Access is verified by the first real
+    // API call (getOrCreateCollection → GET /variables/local); 403 there is treated as FileAccessError below.
+
+    // Detect themes
+    console.log("🎨 Detecting themes...");
+    const themes = detectThemes();
+    console.log(`   Found themes: ${themes.join(", ")}\n`);
+
+    if (themes.length === 0) {
+      throw new Error("No themes found in src/theme/ directory");
+    }
+
+    // Process core theme first
+    console.log("📂 Processing core theme...");
+    const coreThemeName = themes[0]; // Core should be first
+    if (coreThemeName !== "core") {
+      console.warn(
+        `   ⚠️  Warning: First theme is "${coreThemeName}", expected "core"`,
+      );
+    }
+
+    // Sync core theme (full sync)
+    const coreStats = await syncTheme(
+      config,
+      coreThemeName,
+      null,
+      config.collectionName,
+      { dryRun, verbose },
+    );
+
+    // Load core tokens for comparison with extended themes
+    const coreTokenFiles = loadThemeTokenFiles(coreThemeName);
+    const coreAllTokens = [];
+    for (const filePath of coreTokenFiles) {
+      const tokenData = parseTokenFile(filePath);
+      const flattened = flattenTokenTree(tokenData, [], [], filePath);
+      coreAllTokens.push(...flattened);
+    }
+    const coreTokenRegistry = new Map();
+    for (const tokenData of coreAllTokens) {
+      const variableName = pathToVariableName(tokenData.path);
+      coreTokenRegistry.set(variableName, {
+        ...tokenData,
+        variableName,
+      });
+    }
+    const coreResolvedTokens = resolvePrimitiveReferences(coreTokenRegistry);
+
+    // Process extended themes
+    const extendedThemes = themes.slice(1);
+    const allStats = { ...coreStats };
+    const allErrorMessages = [...(coreStats.errorMessages || [])];
+
+    for (const themeName of extendedThemes) {
+      const extendedCollectionName = themeName; // Use just the theme name for extended collections
+      const themeStats = await syncTheme(
+        config,
+        themeName,
+        coreResolvedTokens,
+        extendedCollectionName,
+        { dryRun, verbose },
+      );
+
+      // Accumulate stats
+      allStats.created += themeStats.created ?? 0;
+      allStats.updated += themeStats.updated ?? 0;
+      allStats.skipped += themeStats.skipped ?? 0;
+      allStats.deleted += themeStats.deleted ?? 0;
+      allStats.errors += themeStats.errors ?? 0;
+
+      // Collect error messages
+      if (themeStats.errorMessages) {
+        allErrorMessages.push(...themeStats.errorMessages);
+      }
+    }
+
+    const duration = Date.now() - startTime;
+
+    // Group errors by type
+    const errorGroups = new Map();
+    for (const error of allErrorMessages) {
+      let errorType = "Other";
+      if (error.includes("Could not find")) {
+        errorType = "Token Not Found";
+      } else if (error.includes("Could not resolve")) {
+        errorType = "Reference Resolution";
+      } else if (error.includes("Could not convert")) {
+        errorType = "Value Conversion";
+      } else if (
+        error.includes("Modes are missing") ||
+        error.includes("Mode IDs are missing")
+      ) {
+        errorType = "Mode Configuration";
+      } else if (
+        error.includes("Existing variable") ||
+        error.includes("has no ID")
+      ) {
+        errorType = "Variable ID Missing";
+      } else if (error.includes("Error parsing")) {
+        errorType = "Parsing Error";
+      } else if (error.includes("Error resolving references")) {
+        errorType = "Reference Resolution";
+      }
+
+      if (!errorGroups.has(errorType)) {
+        errorGroups.set(errorType, []);
+      }
+      errorGroups.get(errorType).push(error);
+    }
+
+    // Final summary
+    console.log("\n");
+    console.log("📊 Sync Summary:");
+    if (dryRun) {
+      console.log("   🔍 DRY RUN - No changes were made");
+    } else {
+      console.log("   ✅ Sync complete!");
+    }
+    console.log(`   ✅ Created: ${allStats.created ?? 0}`);
+    console.log(`   🔄 Updated: ${allStats.updated ?? 0}`);
+    console.log(`   ⏭️  Skipped: ${allStats.skipped ?? 0}`);
+    if ((allStats.deleted ?? 0) > 0) {
+      console.log(`   🗑️  Deleted: ${allStats.deleted}`);
+    }
+    if (allStats.errors > 0) {
+      console.log(`   ❌ Errors: ${allStats.errors}`);
+      console.log("\n   Error Breakdown:");
+      for (const [errorType, errors] of errorGroups.entries()) {
+        console.log(`      ${errorType}: ${errors.length}`);
+        // Always show error details (up to 5 per type) so user can fix; show all when verbose
+        const toShow = verbose ? errors : errors.slice(0, 5);
+        toShow.forEach((err) => {
+          console.log(`         - ${err}`);
+        });
+        if (!verbose && errors.length > 5) {
+          console.log(
+            `         ... and ${errors.length - 5} more (run with --verbose to see all)`,
+          );
+        }
+      }
+    }
+    console.log(`   ⏱️  Duration: ${formatDuration(duration)}`);
+    if (verbose) {
+      console.log(`   📡 API Calls: ${apiCallCount}`);
+    }
+  } catch (error) {
+    debugLog(
+      "sync-main.js:syncToFigma",
+      "Fatal error caught",
+      {
+        errorMessage: error.message,
+        errorMessageLength: error.message?.length,
+        errorStack: error.stack?.substring(0, 500),
+        errorCode: error.code,
+        errorName: error.name,
+      },
+      "I",
+    );
+
+    // Handle custom error types (including 403 from first real API call when we skip file verification)
+    if (error instanceof ConfigurationError) {
+      console.error("\n❌ Configuration Error:", error.message);
+      if (error.details?.errors) {
+        error.details.errors.forEach((err) => {
+          console.error(`   - ${err}`);
+        });
+      }
+    } else if (
+      error instanceof FileAccessError ||
+      error.message.includes("403") ||
+      error.message.includes("forbidden")
+    ) {
+      console.error("\n❌ File Access Error:", error.message);
+    } else if (error instanceof AuthenticationError) {
+      console.error("\n❌ Authentication Error:", error.message);
+    } else {
+      console.error("\n❌ Fatal error:", error.message);
+    }
+    if (
+      error.stack &&
+      (process.env.DEBUG || process.env.NODE_ENV === "development")
+    ) {
+      console.error("\nStack trace:");
+      console.error(error.stack);
+    }
+    console.error("\n💡 Tips:");
+    console.error(
+      "   - Check that OAuth2 credentials are set correctly (FIGMA_CLIENT_ID, FIGMA_CLIENT_SECRET, FIGMA_REFRESH_TOKEN)",
+    );
+    console.error(
+      "   - Verify the refresh token hasn't expired (re-authenticate if needed)",
+    );
+    console.error("   - Verify the file key is correct");
+    console.error("   - Ensure you have access to the Figma file");
+    console.error("   - Verify your OAuth2 app has the required scopes");
+    console.error("   - Run with DEBUG=1 for more details");
+    process.exit(1);
+  }
+}
+
+/**
+ * Test API access and token validity
+ * @param {string} [fileKey] - Optional fileKey to override the default or env var
+ * @param {Object} [options] - Test options
+ * @param {boolean} [options.full=false] - Run full test suite
+ * @param {boolean} [options.verbose=false] - Enable verbose logging
+ */
+async function testFigmaAccess(fileKey = null, options = {}) {
+  const { full: _full = false, verbose = false } = options;
+  console.log("🧪 Testing Figma API access...\n");
+
+  try {
+    // Validate fileKey if provided
+    if (fileKey) {
+      validateFileKey(fileKey);
+    }
+
+    const config = loadConfig(fileKey);
+    console.log(`📁 File key: ${config.fileKey}`);
+
+    // Get access token (OAuth2)
+    const authMethod = await getAuthMethod(config);
+    const accessToken = await getAccessToken(config);
+    console.log(`🔑 Auth method: ${authMethod}`);
+    if (verbose) {
+      console.log(`🔑 Token: ${maskToken(accessToken)}\n`);
+    } else {
+      console.log();
+    }
+
+    // Test 1: Verify token validity
+    console.log("1️⃣  Testing token validity...");
+    try {
+      const response = await fetch(`${FIGMA_API_BASE}/me`, {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+        },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        let errorJson;
+        try {
+          errorJson = JSON.parse(errorText);
+        } catch {
+          // Not JSON, use raw text
+        }
+
+        // Check if it's a scope error (missing current_user:read)
+        const isScopeError =
+          response.status === 403 &&
+          (errorText.includes("current_user:read") ||
+            (errorJson?.err && errorJson.err.includes("current_user:read")));
+
+        if (isScopeError) {
+          console.warn(
+            "   ⚠️  Token validation skipped (missing current_user:read scope)",
+          );
+          console.warn(
+            "\n   💡 The token doesn't have the 'current_user:read' scope required for /me endpoint.",
+          );
+          console.warn(
+            "   This is not critical - the token will still work for file and variables API calls.",
+          );
+          console.warn(
+            "   To fix: Re-authenticate with updated scopes that include 'current_user:read'.\n",
+          );
+          // Don't throw - continue with other tests
+        } else {
+          throw new Error(
+            `Token validation failed (${response.status}): ${errorText}`,
+          );
+        }
+      } else {
+        const userData = await response.json();
+        console.log("   ✅ Token is valid");
+        console.log(
+          `   👤 Account: ${userData.email || userData.handle || "Unknown"}`,
+        );
+        console.log(`   📧 Email: ${userData.email || "Not available"}`);
+        console.log(`   🆔 User ID: ${userData.id || "Not available"}\n`);
+      }
+    } catch (error) {
+      // Only throw if it's not already handled (scope error case)
+      if (!error.message.includes("Token validation skipped")) {
+        console.error("   ❌ Token validation failed:", error.message);
+        console.error("\n   💡 This usually means:");
+        console.error("      - The token is invalid or has been revoked");
+        console.error("      - The token format is incorrect");
+        console.error(
+          "      - The token is missing required scopes (e.g., current_user:read)",
+        );
+        throw error;
+      }
+    }
+
+    // Test 2: Verify file access
+    console.log("2️⃣  Testing file access...");
+    try {
+      const fileData = await figmaRequest(config, "");
+      console.log("   ✅ File access granted");
+      console.log(`   📄 File name: ${fileData.name || "Unknown"}`);
+      console.log(`   🔑 File key: ${config.fileKey}`);
+      console.log(
+        `   📅 Last modified: ${fileData.lastModified || "Unknown"}\n`,
+      );
+    } catch (error) {
+      const is403 =
+        error.message.includes("403") || error.message.includes("forbidden");
+      const is404 =
+        error.message.includes("404") || error.message.includes("not found");
+
+      console.error("   ❌ File access failed:", error.message);
+      console.error("\n   💡 Troubleshooting:");
+
+      if (is403) {
+        console.error("      This is a 403 Forbidden error, which means:");
+        console.error("      - The file exists and the token is valid");
+        console.error(
+          "      - But your OAuth2 app doesn't have API access to this file",
+        );
+        console.error("\n      Possible solutions:");
+        console.error(
+          "      1. Check if the file is in a team/org you're a member of",
+        );
+        console.error(
+          "      2. Verify you can open the file in Figma: https://www.figma.com/design/" +
+            config.fileKey,
+        );
+        console.error(
+          "      3. Verify your OAuth2 app has the required scopes",
+        );
+        console.error("      4. For Enterprise orgs:");
+        console.error(
+          "         - Contact your Figma admin to enable API access",
+        );
+        console.error(
+          "         - Check if your org has API access restrictions",
+        );
+        console.error(
+          "         - You may need organization-level API permissions",
+        );
+        console.error(
+          "      5. Re-authenticate to get a new refresh token if needed",
+        );
+      } else if (is404) {
+        console.error("      This is a 404 Not Found error, which means:");
+        console.error("      - The file key might be incorrect");
+        console.error("      - Or the file doesn't exist");
+        console.error("\n      Verify the file key from the Figma URL");
+      } else {
+        console.error("      - The file key might be incorrect");
+        console.error("      - Your account doesn't have access to this file");
+        console.error(
+          "      - The file is in a team/org you're not a member of",
+        );
+        console.error(
+          "      - For Enterprise orgs, API access may be restricted",
+        );
+      }
+      throw error;
+    }
+
+    // Test 3: Verify variables API access
+    console.log("3️⃣  Testing variables API access...");
+    try {
+      const variablesData = await figmaRequest(config, "/variables/local");
+      const collections = variablesData.meta?.variableCollections
+        ? Object.values(variablesData.meta.variableCollections)
+        : [];
+      const variables = variablesData.meta?.variables
+        ? Object.values(variablesData.meta.variables)
+        : [];
+
+      console.log("   ✅ Variables API access granted");
+      console.log(`   📦 Collections: ${collections.length}`);
+      console.log(`   🔢 Variables: ${variables.length}`);
+
+      if (collections.length > 0) {
+        console.log("\n   Existing collections:");
+        collections.forEach((coll) => {
+          console.log(
+            `      - ${coll.name} (${coll.modes?.length || 0} modes)`,
+          );
+        });
+      }
+      console.log("");
+    } catch (error) {
+      console.error("   ❌ Variables API access failed:", error.message);
+      console.error("\n   💡 This usually means:");
+      console.error("      - The token doesn't have 'Design systems' scopes");
+      console.error("      - Required scopes:");
+      console.error("        • Read variables in accessible files");
+      console.error(
+        "        • Create and modify variables in accessible files",
+      );
+      console.error(
+        "      - For Enterprise orgs, variables API may be restricted",
+      );
+      throw error;
+    }
+
+    // Test 4: Check required scopes (informational)
+    console.log("4️⃣  Scope requirements:");
+    console.log("   Required scopes for this script:");
+    console.log("   ✓ Read variables in accessible files");
+    console.log("   ✓ Create and modify variables in accessible files");
+    console.log(
+      "\n   ℹ️  Note: We cannot verify scopes via API, but the tests above",
+    );
+    console.log("      will fail if scopes are missing.\n");
+
+    console.log("✅ All tests passed! Your setup is ready for syncing.\n");
+    console.log("💡 Run 'pnpm figma:sync' to start syncing tokens.\n");
+  } catch (error) {
+    console.error("\n❌ Test failed:", error.message);
+    if (error.stack && process.env.DEBUG) {
+      console.error("\nStack trace:");
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Validate token files without syncing
+ * @param {string} [fileKey] - Optional fileKey to override the default or env var
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.verbose=false] - Enable verbose logging
+ */
+async function validateTokens(fileKey = null, options = {}) {
+  const { verbose = false } = options;
+  console.log("🔍 Validating token files...\n");
+
+  try {
+    // Validate fileKey if provided
+    if (fileKey) {
+      validateFileKey(fileKey);
+    }
+
+    // Load configuration (skip validation since we're just validating tokens)
+    loadConfig(fileKey, { skipValidation: true });
+
+    // Detect themes
+    console.log("🎨 Detecting themes...");
+    const themes = detectThemes();
+    console.log(`   Found themes: ${themes.join(", ")}\n`);
+
+    if (themes.length === 0) {
+      throw new Error("No themes found in src/theme/ directory");
+    }
+
+    let totalTokens = 0;
+    const errors = [];
+
+    // Validate each theme
+    for (const themeName of themes) {
+      console.log(`📂 Validating theme: ${themeName}`);
+      const tokenFiles = loadThemeTokenFiles(themeName);
+
+      if (tokenFiles.length === 0) {
+        console.log(`   ⚠️  No token files found for theme "${themeName}"\n`);
+        continue;
+      }
+
+      // Parse tokens
+      const allTokens = [];
+      for (const filePath of tokenFiles) {
+        try {
+          const tokenData = parseTokenFile(filePath);
+          const flattened = flattenTokenTree(tokenData, [], [], filePath);
+          allTokens.push(...flattened);
+        } catch (error) {
+          errors.push(`Error parsing ${filePath}: ${error.message}`);
+        }
+      }
+
+      // Build token registry
+      const tokenRegistry = new Map();
+      for (const tokenData of allTokens) {
+        const variableName = pathToVariableName(tokenData.path);
+        tokenRegistry.set(variableName, {
+          ...tokenData,
+          variableName,
+        });
+      }
+
+      // Resolve primitive references
+      try {
+        const resolvedTokens = resolvePrimitiveReferences(tokenRegistry);
+        totalTokens += resolvedTokens.size;
+        console.log(`   ✅ Validated ${resolvedTokens.size} tokens\n`);
+      } catch (error) {
+        errors.push(
+          `Error resolving references in ${themeName}: ${error.message}`,
+        );
+      }
+    }
+
+    // Summary
+    console.log("\n📊 Validation Summary:");
+    console.log(`   ✅ Total tokens: ${totalTokens}`);
+    if (errors.length > 0) {
+      console.log(`   ❌ Errors: ${errors.length}`);
+      errors.forEach((err) => {
+        console.log(`      - ${err}`);
+      });
+      process.exit(1);
+    } else {
+      console.log("   ✅ All tokens validated successfully!\n");
+    }
+  } catch (error) {
+    console.error("\n❌ Validation failed:", error.message);
+    if (error.stack && (process.env.DEBUG || verbose)) {
+      console.error("\nStack trace:");
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  try {
+    const args = process.argv.slice(2);
+
+    // Handle help flag
+    if (args.includes("--help") || args.includes("-h")) {
+      printHelp();
+      process.exit(0);
+    }
+
+    // Parse CLI arguments
+    const options = parseCliArgs(args);
+
+    // Set verbose mode in environment if requested
+    if (options.verbose) {
+      process.env.VERBOSE = "1";
+    }
+
+    // Determine fileKey: explicit fileKey or default (FIGMA_PROD_FILE_KEY)
+    const fileKey = options.fileKey || FIGMA_PROD_FILE_KEY;
+
+    // Execute command
+    if (options.command === "test") {
+      testFigmaAccess(fileKey, {
+        full: options.full,
+        verbose: options.verbose,
+      });
+    } else if (options.command === "test:file") {
+      if (!fileKey) {
+        console.error("❌ Error: fileKey is required for test:file command");
+        console.error(
+          "\nUsage: pnpm figma:test:file <fileKey> [--full] [--verbose]",
+        );
+        process.exit(1);
+      }
+      testFigmaAccess(fileKey, {
+        full: options.full,
+        verbose: options.verbose,
+      });
+    } else if (options.command === "validate") {
+      validateTokens(fileKey, { verbose: options.verbose });
+    } else if (options.command === "file") {
+      // Legacy file command
+      if (!fileKey) {
+        console.error("❌ Error: fileKey is required for 'file' command");
+        console.error("\nUsage:");
+        console.error(
+          "  pnpm figma:sync:file <fileKey>        - Sync to specified file",
+        );
+        console.error(
+          "  pnpm figma:test:file <fileKey>        - Test access to specified file",
+        );
+        process.exit(1);
+      }
+      // Check if there's a subcommand
+      const remainingArgs = args.slice(args.indexOf("file") + 2);
+      if (remainingArgs.includes("test") || remainingArgs.includes("--test")) {
+        testFigmaAccess(fileKey, { verbose: options.verbose });
+      } else {
+        syncToFigma(fileKey, {
+          dryRun: options.dryRun,
+          verbose: options.verbose,
+        });
+      }
+    } else {
+      // Default to sync command
+      syncToFigma(fileKey, {
+        dryRun: options.dryRun,
+        verbose: options.verbose,
+      });
+    }
+  } catch (error) {
+    if (
+      error.message.includes("Missing value") ||
+      error.message.includes("requires")
+    ) {
+      console.error(`❌ Error: ${error.message}`);
+      printHelp();
+    } else {
+      console.error(`❌ Error: ${error.message}`);
+      if (error.stack && process.env.DEBUG) {
+        console.error("\nStack trace:");
+        console.error(error.stack);
+      }
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = { syncToFigma, testFigmaAccess, validateTokens };