@servicetitan/hammer-token 2.5.2 → 3.0.1

package/src/utils/figma/figma-api.js

@@ -0,0 +1,1069 @@
+#!/usr/bin/env node
+
+/**
+ * Figma API Utilities
+ *
+ * Functions for making requests to the Figma API and managing collections, modes, and variables.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { getAccessToken } = require("./auth");
+
+// Debug logging helper
+const DEBUG_LOG_PATH = path.join(__dirname, "../../../../.cursor/debug.log");
+function debugLog(location, message, data, hypothesisId) {
+  try {
+    const logEntry =
+      JSON.stringify({
+        location,
+        message,
+        data,
+        timestamp: Date.now(),
+        sessionId: "debug-session",
+        runId: "run1",
+        hypothesisId,
+      }) + "\n";
+    fs.appendFileSync(DEBUG_LOG_PATH, logEntry);
+  } catch (_e) {
+    // Silently fail if logging fails
+  }
+}
+
+// Configuration
+const FIGMA_API_BASE = "https://api.figma.com/v1";
+
+// Rate limit tracking
+const rateLimitInfo = {
+  remaining: null,
+  resetAt: null,
+};
+
+/**
+ * Sleep for specified milliseconds
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise} Promise that resolves after the delay
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Make a request to the Figma API with retry logic
+ * @param {Object} config - Configuration object
+ * @param {string} endpoint - API endpoint
+ * @param {Object} options - Request options
+ * @param {number} retries - Number of retry attempts
+ * @returns {Promise<any>} API response data
+ */
+async function figmaRequest(config, endpoint, options = {}, retries = 3) {
+  // Get access token (OAuth2)
+  const accessToken = await getAccessToken(config);
+
+  const url = `${FIGMA_API_BASE}/files/${config.fileKey}${endpoint}`;
+
+  // OAuth2 uses Bearer token
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    ...options.headers,
+  };
+
+  for (let attempt = 0; attempt < retries; attempt++) {
+    try {
+      // Build request config, ensuring body is preserved
+      const requestConfig = {
+        method: options.method || "GET",
+        headers,
+      };
+
+      // Only include body for POST/PUT/PATCH requests
+      if (
+        options.body &&
+        (options.method === "POST" ||
+          options.method === "PUT" ||
+          options.method === "PATCH")
+      ) {
+        requestConfig.body = options.body;
+      }
+
+      // Include any other options (but don't override method, headers, or body)
+      for (const [key, value] of Object.entries(options)) {
+        if (key !== "method" && key !== "headers" && key !== "body") {
+          requestConfig[key] = value;
+        }
+      }
+
+      // Debug logging for POST /variables body parse failures only
+      if (
+        endpoint === "/variables" &&
+        requestConfig.method === "POST" &&
+        options.body
+      ) {
+        try {
+          if (typeof options.body === "string") {
+            JSON.parse(options.body);
+          }
+        } catch (e) {
+          debugLog(
+            "figma-api.js:figmaRequest",
+            "POST /variables body parse error",
+            {
+              error: e.message,
+              bodyPreview:
+                typeof options.body === "string"
+                  ? options.body.substring(0, 500)
+                  : String(options.body).substring(0, 500),
+            },
+            "B3",
+          );
+        }
+      }
+
+      const response = await fetch(url, requestConfig);
+
+      // Update rate limit info from headers
+      const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
+      const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+      if (rateLimitRemaining !== null) {
+        rateLimitInfo.remaining = parseInt(rateLimitRemaining, 10);
+      }
+      if (rateLimitReset !== null) {
+        rateLimitInfo.resetAt = parseInt(rateLimitReset, 10) * 1000; // Convert to ms
+      }
+
+      // Handle rate limiting (429)
+      if (response.status === 429) {
+        const retryAfter = response.headers.get("Retry-After");
+        let waitTime;
+
+        if (retryAfter) {
+          waitTime = parseInt(retryAfter, 10) * 1000;
+        } else if (rateLimitInfo.resetAt) {
+          waitTime = Math.max(0, rateLimitInfo.resetAt - Date.now());
+        } else {
+          waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff with jitter
+        }
+
+        if (attempt < retries - 1) {
+          console.warn(
+            `   ⚠️  Rate limited. Waiting ${Math.ceil(waitTime / 1000)}s before retry...`,
+          );
+          await sleep(waitTime);
+          continue;
+        }
+      }
+
+      // Check rate limit before making request (preventive)
+      if (rateLimitInfo.remaining === 0 && rateLimitInfo.resetAt) {
+        const waitTime = Math.max(0, rateLimitInfo.resetAt - Date.now());
+        if (waitTime > 0) {
+          console.warn(
+            `   ⚠️  Rate limit reached. Waiting ${Math.ceil(waitTime / 1000)}s...`,
+          );
+          await sleep(waitTime);
+        }
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        debugLog(
+          "figma-api.js:figmaRequest",
+          "API error response",
+          {
+            status: response.status,
+            statusText: response.statusText,
+            errorText: errorText?.substring(0, 200),
+            url,
+            fileKey: config.fileKey,
+            fileKeyLength: config.fileKey?.length,
+          },
+          "C",
+        );
+
+        let errorMessage = `Figma API error (${response.status}): ${errorText || response.statusText}`;
+
+        // Provide helpful error messages
+        if (response.status === 401) {
+          errorMessage =
+            "Authentication failed. Please check your OAuth2 credentials (FIGMA_CLIENT_ID, FIGMA_CLIENT_SECRET, FIGMA_REFRESH_TOKEN).";
+        } else if (response.status === 403) {
+          // Try to parse error for more details
+          let details = "";
+          try {
+            const errorJson = JSON.parse(errorText);
+            if (errorJson.err) {
+              details = ` (${errorJson.err})`;
+            } else if (errorJson.message) {
+              details = ` (${errorJson.message})`;
+            }
+          } catch {
+            if (errorText && errorText.length < 200) {
+              details = ` (${errorText})`;
+            }
+          }
+
+          errorMessage =
+            `Access forbidden (403). Please check file permissions and token access.${details}\n\n` +
+            `This usually means:\n` +
+            `  1. Your OAuth2 token doesn't have permission to access this file\n` +
+            `  2. The file is in a team/org that requires organization-level access\n` +
+            `  3. The token was created by a different account\n` +
+            `  4. The token doesn't have the required scopes\n\n` +
+            `To fix:\n` +
+            `  - Verify you can open the file in Figma: https://www.figma.com/design/${config.fileKey}/...\n` +
+            `  - Verify your OAuth2 app has the required scopes\n` +
+            `  - Check that the refresh token hasn't expired (re-authenticate if needed)\n`;
+        } else if (response.status === 404) {
+          // Try to parse error for more details
+          let details = "";
+          try {
+            const errorJson = JSON.parse(errorText);
+            if (errorJson.err) {
+              details = ` (${errorJson.err})`;
+            }
+          } catch {
+            // Not JSON, use raw text
+            if (errorText) {
+              details = ` (${errorText})`;
+            }
+          }
+          debugLog(
+            "figma-api.js:figmaRequest",
+            "404 error details",
+            {
+              fileKey: config.fileKey,
+              fileKeyLength: config.fileKey?.length,
+              details,
+              errorText: errorText?.substring(0, 200),
+              url,
+              errorMessageBefore: errorMessage,
+            },
+            "D",
+          );
+          errorMessage = `File not found. Please check the file key: ${config.fileKey}${details}`;
+        }
+
+        // In debug mode, show full error
+        if (process.env.DEBUG) {
+          console.error(`Full API response:`, {
+            status: response.status,
+            statusText: response.statusText,
+            body: errorText,
+            url: url,
+          });
+        }
+
+        throw new Error(errorMessage);
+      }
+
+      return response.json();
+    } catch (error) {
+      debugLog(
+        "figma-api.js:figmaRequest",
+        "figmaRequest catch block",
+        {
+          attempt,
+          retries,
+          errorMessage: error.message,
+          errorMessageLength: error.message?.length,
+          fileKey: config.fileKey,
+          isLastAttempt: attempt === retries - 1,
+        },
+        "E",
+      );
+
+      // If it's the last attempt or not a network error, throw
+      if (
+        attempt === retries - 1 ||
+        (error.message && !error.message.includes("fetch"))
+      ) {
+        throw error;
+      }
+
+      // Wait before retrying network errors
+      await sleep(Math.pow(2, attempt) * 1000);
+    }
+  }
+}
+
+/**
+ * Verify file access before attempting to sync
+ * @param {Object} config - Configuration object
+ * @returns {Promise<boolean>} True if access is granted
+ */
+async function verifyFileAccess(config) {
+  try {
+    // Try to get file metadata - this will fail if we don't have access.
+    // Use ?depth=1 to avoid "Request too large" on large files (Figma requires depth > 0; depth=1 returns only Pages).
+    const fileData = await figmaRequest(config, "?depth=1");
+
+    if (process.env.DEBUG) {
+      console.log(`   File name: ${fileData.name || "Unknown"}`);
+      console.log(`   File key: ${config.fileKey}`);
+    }
+
+    return true;
+  } catch (error) {
+    if (error.message.includes("404") || error.message.includes("Not found")) {
+      // Check if it's an authentication issue vs access issue
+      const isAuthError =
+        error.message.includes("401") ||
+        error.message.includes("Authentication");
+
+      if (isAuthError) {
+        throw new Error(
+          `Authentication failed for file ${config.fileKey}.\n\n` +
+            `Please verify:\n` +
+            `  1. Your OAuth2 credentials are correct (FIGMA_CLIENT_ID, FIGMA_CLIENT_SECRET, FIGMA_REFRESH_TOKEN)\n` +
+            `  2. The refresh token hasn't expired (re-authenticate if needed)\n` +
+            `  3. Your OAuth2 app has the required scopes`,
+        );
+      }
+
+      throw new Error(
+        `Cannot access file ${config.fileKey}.\n\n` +
+          `This file appears to be in a team or organization. Please verify:\n` +
+          `  1. Your OAuth2 app was created by an account that has access to this file\n` +
+          `  2. You are a member of the team/organization that owns this file\n` +
+          `  3. Your OAuth2 app has organization-level access if the file is in an organization\n` +
+          `  4. For Enterprise organizations, API access may be restricted - contact your admin\n\n` +
+          `To fix:\n` +
+          `  - Log into Figma and verify you can open this file: https://www.figma.com/design/${config.fileKey}/...\n` +
+          `  - Verify your OAuth2 app has the required scopes\n` +
+          `  - Re-authenticate to get a new refresh token if needed`,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get or create an extended variable collection
+ * @param {Object} config - Configuration object
+ * @param {string} parentCollectionId - ID of the parent collection to extend
+ * @param {string} extendedCollectionName - Name for the extended collection
+ * @returns {Promise<Object>} Extended collection object
+ */
+async function getOrCreateExtendedCollection(
+  config,
+  parentCollectionId,
+  extendedCollectionName,
+) {
+  // Get all local variables
+  const variablesData = await figmaRequest(config, "/variables/local");
+  const collections = variablesData.meta?.variableCollections
+    ? Object.values(variablesData.meta.variableCollections)
+    : [];
+
+  // Find existing extended collection
+  const existingCollection = collections.find(
+    (coll) =>
+      coll.name === extendedCollectionName &&
+      coll.parentVariableCollectionId === parentCollectionId,
+  );
+
+  if (existingCollection) {
+    return existingCollection;
+  }
+
+  // Create new extended collection
+  const tempCollectionId = "temp_extended_collection_" + Date.now();
+  const response = await figmaRequest(config, "/variables", {
+    method: "POST",
+    body: JSON.stringify({
+      variableCollections: [
+        {
+          action: "CREATE",
+          id: tempCollectionId,
+          name: extendedCollectionName,
+          parentVariableCollectionId: parentCollectionId,
+          isExtension: true,
+        },
+      ],
+    }),
+  });
+
+  const realCollectionId = response.meta?.tempIdToRealId?.[tempCollectionId];
+  if (!realCollectionId) {
+    throw new Error("Failed to create extended collection: no ID returned");
+  }
+
+  // Fetch the newly created collection to get full details
+  const updatedVariablesData = await figmaRequest(config, "/variables/local");
+  const updatedCollections = updatedVariablesData.meta?.variableCollections
+    ? Object.values(updatedVariablesData.meta.variableCollections)
+    : [];
+  const newCollection = updatedCollections.find(
+    (coll) => coll.id === realCollectionId,
+  );
+
+  if (!newCollection) {
+    throw new Error(
+      `Failed to retrieve newly created extended collection with ID: ${realCollectionId}`,
+    );
+  }
+
+  return newCollection;
+}
+
+/**
+ * Get or create variable collection
+ * @param {Object} config - Configuration object
+ * @returns {Promise<Object>} Collection object
+ */
+async function getOrCreateCollection(config) {
+  // Get all local variables
+  // This will fail with 404 if file doesn't exist or token doesn't have access
+  try {
+    const variablesData = await figmaRequest(config, "/variables/local");
+
+    // variableCollections is a dictionary (object) keyed by collection ID, convert to array
+    const collections = variablesData.meta?.variableCollections
+      ? Object.values(variablesData.meta.variableCollections)
+      : [];
+
+    // Find existing collection
+    const existingCollection = collections.find(
+      (coll) => coll.name === config.collectionName,
+    );
+
+    if (existingCollection) {
+      return existingCollection;
+    }
+
+    // Create new collection using the bulk operations endpoint
+    const tempCollectionId = "temp_collection_" + Date.now();
+    const response = await figmaRequest(config, "/variables", {
+      method: "POST",
+      body: JSON.stringify({
+        variableCollections: [
+          {
+            action: "CREATE",
+            id: tempCollectionId,
+            name: config.collectionName,
+          },
+        ],
+      }),
+    });
+
+    // Get the real collection ID from the response
+    const realCollectionId = response.meta?.tempIdToRealId?.[tempCollectionId];
+    if (!realCollectionId) {
+      throw new Error("Failed to create collection: no ID returned");
+    }
+
+    // Fetch the newly created collection to get full details
+    const updatedVariablesData = await figmaRequest(config, "/variables/local");
+    const updatedCollections = updatedVariablesData.meta?.variableCollections
+      ? Object.values(updatedVariablesData.meta.variableCollections)
+      : [];
+    const newCollection = updatedCollections.find(
+      (coll) => coll.id === realCollectionId,
+    );
+
+    if (!newCollection) {
+      throw new Error(
+        `Failed to retrieve newly created collection with ID: ${realCollectionId}`,
+      );
+    }
+
+    return newCollection;
+  } catch (error) {
+    debugLog(
+      "figma-api.js:getOrCreateCollection",
+      "getOrCreateCollection error",
+      { errorMessage: error.message, fileKey: config.fileKey },
+      "F6",
+    );
+    throw error;
+  }
+}
+
+/**
+ * Get or create variable modes (Light/Dark)
+ * @param {Object} config - Configuration object
+ * @param {string} collectionId - Collection ID
+ * @returns {Promise<Object>} Object with light and dark mode objects
+ */
+async function getOrCreateModes(config, collectionId) {
+  // Get collection details to see existing modes
+  const variablesData = await figmaRequest(config, "/variables/local");
+
+  // variableCollections is a dictionary (object) keyed by collection ID
+  const collections = variablesData.meta?.variableCollections || {};
+  const collection = collections[collectionId];
+
+  const modes = collection?.modes || [];
+  const lightMode = modes.find((m) => m.name === config.lightModeName);
+  const darkMode = modes.find((m) => m.name === config.darkModeName);
+
+  const createdModes = {};
+
+  // Handle Light mode: if it doesn't exist, check if there's a default mode to rename
+  if (!lightMode) {
+    // Check if there's a default mode (usually "Mode 1" or similar default name)
+    // When Figma creates a collection, it automatically creates a default mode
+    const defaultMode = modes.find(
+      (m) =>
+        m.name === "Mode 1" ||
+        m.name === "Default" ||
+        (modes.length === 1 && m.name !== config.darkModeName),
+    );
+
+    if (defaultMode && defaultMode.modeId) {
+      // Rename the default mode to "Light" instead of creating a new one
+      await figmaRequest(config, "/variables", {
+        method: "POST",
+        body: JSON.stringify({
+          variableModes: [
+            {
+              action: "UPDATE",
+              id: defaultMode.modeId,
+              name: config.lightModeName,
+              variableCollectionId: collectionId,
+            },
+          ],
+        }),
+      });
+
+      // Fetch the updated collection to get the renamed mode
+      const updatedVariablesData = await figmaRequest(
+        config,
+        "/variables/local",
+      );
+      const updatedCollections =
+        updatedVariablesData.meta?.variableCollections || {};
+      const updatedCollection = updatedCollections[collectionId];
+      const renamedLightMode = updatedCollection?.modes?.find(
+        (m) => m.modeId === defaultMode.modeId,
+      );
+
+      if (!renamedLightMode) {
+        throw new Error(
+          `Failed to retrieve renamed light mode with ID: ${defaultMode.modeId}`,
+        );
+      }
+
+      // Map modeId to id for backward compatibility with existing code
+      createdModes.light = {
+        ...renamedLightMode,
+        id: renamedLightMode.id || renamedLightMode.modeId,
+      };
+    } else {
+      // No default mode found, create a new Light mode
+      const tempModeId = "temp_light_mode_" + Date.now();
+      const response = await figmaRequest(config, "/variables", {
+        method: "POST",
+        body: JSON.stringify({
+          variableModes: [
+            {
+              action: "CREATE",
+              id: tempModeId,
+              name: config.lightModeName,
+              variableCollectionId: collectionId,
+            },
+          ],
+        }),
+      });
+
+      const realModeId = response.meta?.tempIdToRealId?.[tempModeId];
+      if (!realModeId) {
+        throw new Error("Failed to create light mode: no ID returned");
+      }
+
+      // Fetch the updated collection to get the new mode
+      const updatedVariablesData = await figmaRequest(
+        config,
+        "/variables/local",
+      );
+      const updatedCollections =
+        updatedVariablesData.meta?.variableCollections || {};
+      const updatedCollection = updatedCollections[collectionId];
+      const newLightMode = updatedCollection?.modes?.find(
+        (m) => m.modeId === realModeId,
+      );
+
+      if (!newLightMode) {
+        throw new Error(
+          `Failed to retrieve newly created light mode with ID: ${realModeId}`,
+        );
+      }
+
+      // Map modeId to id for backward compatibility with existing code
+      createdModes.light = {
+        ...newLightMode,
+        id: newLightMode.id || newLightMode.modeId,
+      };
+    }
+  } else {
+    // Map modeId to id for backward compatibility with existing code
+    createdModes.light = { ...lightMode, id: lightMode.id || lightMode.modeId };
+  }
+
+  // Create Dark mode if it doesn't exist
+  if (!darkMode) {
+    const tempModeId = "temp_dark_mode_" + Date.now();
+    const response = await figmaRequest(config, "/variables", {
+      method: "POST",
+      body: JSON.stringify({
+        variableModes: [
+          {
+            action: "CREATE",
+            id: tempModeId,
+            name: config.darkModeName,
+            variableCollectionId: collectionId,
+          },
+        ],
+      }),
+    });
+
+    const realModeId = response.meta?.tempIdToRealId?.[tempModeId];
+    if (!realModeId) {
+      throw new Error("Failed to create dark mode: no ID returned");
+    }
+
+    // Fetch the updated collection to get the new mode
+    const updatedVariablesData = await figmaRequest(config, "/variables/local");
+    const updatedCollections =
+      updatedVariablesData.meta?.variableCollections || {};
+    const updatedCollection = updatedCollections[collectionId];
+    const newDarkMode = updatedCollection?.modes?.find(
+      (m) => m.modeId === realModeId,
+    );
+
+    if (!newDarkMode) {
+      throw new Error(
+        `Failed to retrieve newly created dark mode with ID: ${realModeId}`,
+      );
+    }
+
+    // Map modeId to id for backward compatibility with existing code
+    createdModes.dark = {
+      ...newDarkMode,
+      id: newDarkMode.id || newDarkMode.modeId,
+    };
+  } else {
+    // Map modeId to id for backward compatibility with existing code
+    createdModes.dark = { ...darkMode, id: darkMode.id || darkMode.modeId };
+  }
+
+  // Clean up any unwanted modes (e.g., default "mode 1" created by Figma)
+  // Fetch the collection again to get all current modes
+  const finalVariablesData = await figmaRequest(config, "/variables/local");
+  const finalCollections = finalVariablesData.meta?.variableCollections || {};
+  const finalCollection = finalCollections[collectionId];
+  const allModes = finalCollection?.modes || [];
+
+  // Find modes that aren't Light or Dark
+  const unwantedModes = allModes.filter(
+    (m) => m.name !== config.lightModeName && m.name !== config.darkModeName,
+  );
+
+  // Delete unwanted modes (only if they have valid modeIds)
+  // Note: mode.id might be a node ID (like "5:0") which is not valid for variable mode operations
+  // We must use mode.modeId for variable mode operations
+  if (unwantedModes.length > 0) {
+    const modeDeletions = unwantedModes
+      .map((mode) => {
+        const modeId = mode.modeId; // Only use modeId, not mode.id (which might be a node ID)
+        // Skip if modeId is missing or invalid
+        // Note: Figma mode IDs are typically in "X:Y" format (e.g., "19:0"), which is valid for deletion
+        if (!modeId) {
+          return null;
+        }
+        return { action: "DELETE", id: modeId };
+      })
+      .filter((deletion) => deletion !== null);
+
+    if (modeDeletions.length > 0) {
+      try {
+        await figmaRequest(config, "/variables", {
+          method: "POST",
+          body: JSON.stringify({
+            variableModes: modeDeletions,
+          }),
+        });
+
+        console.log(
+          `   🗑️  Removed ${modeDeletions.length} unwanted mode(s): ${unwantedModes.map((m) => m.name).join(", ")}`,
+        );
+      } catch (error) {
+        // Log but don't fail the entire sync if mode deletion fails
+        console.warn(
+          `   ⚠️  Failed to remove unwanted modes: ${error.message}`,
+        );
+        if (process.env.DEBUG) {
+          console.warn(
+            `   Unwanted modes: ${JSON.stringify(unwantedModes, null, 2)}`,
+          );
+        }
+      }
+    } else {
+      console.warn(
+        `   ⚠️  Found ${unwantedModes.length} unwanted mode(s) but none have valid IDs to delete`,
+      );
+    }
+  }
+
+  return createdModes;
+}
+
+/**
+ * Create or update a variable (DEPRECATED - use buildBulkVariableRequest instead)
+ * @param {Object} config - Configuration object
+ * @param {string} collectionId - Collection ID
+ * @param {Object} modes - Modes object
+ * @param {string} variableName - Variable name
+ * @param {string} variableType - Variable type
+ * @param {any} lightValue - Light mode value
+ * @param {any} darkValue - Dark mode value
+ * @param {Map} resolvedTokens - Resolved tokens map
+ * @param {Array} existingVariables - Existing variables array
+ * @returns {Promise<Object>} Result object with action and variable
+ */
+async function createOrUpdateVariable(
+  config,
+  collectionId,
+  modes,
+  variableName,
+  variableType,
+  lightValue,
+  darkValue,
+  resolvedTokens,
+  existingVariables,
+) {
+  // This function is deprecated but kept for backward compatibility
+  // It uses functions from other modules that need to be imported
+  const {
+    isReference,
+    extractReferencePath,
+    resolveReferencePath,
+  } = require("./token-resolution");
+  const { convertTokenValueToFigma } = require("./token-conversion");
+
+  // Check if this should be an alias (for semantic/component tokens)
+  const isLightReference = isReference(lightValue);
+  const isDarkReference = isReference(darkValue);
+
+  let lightAliasId = null;
+  let darkAliasId = null;
+
+  // Resolve alias targets (only for non-primitive tokens)
+  const tokenData = resolvedTokens.get(variableName);
+  const isPrimitive = tokenData?.isPrimitive ?? false;
+
+  if (!isPrimitive && isLightReference) {
+    const refPath = extractReferencePath(lightValue);
+    const targetPath = resolveReferencePath(refPath, resolvedTokens);
+    // Use the local getVariableIdByName function
+    const variable = existingVariables.find(
+      (v) => v.name === targetPath || v.key === targetPath,
+    );
+    lightAliasId = variable?.id || null;
+  }
+
+  if (!isPrimitive && isDarkReference) {
+    const refPath = extractReferencePath(darkValue);
+    const targetPath = resolveReferencePath(refPath, resolvedTokens);
+    // Use the local getVariableIdByName function
+    const variable = existingVariables.find(
+      (v) => v.name === targetPath || v.key === targetPath,
+    );
+    darkAliasId = variable?.id || null;
+  }
+
+  // Get existing variable
+  const existing = existingVariables.find(
+    (v) => v.name === variableName || v.key === variableName,
+  );
+
+  // Convert values for comparison/creation
+  let lightFigmaValue;
+  let darkFigmaValue;
+
+  const tokenScopes = tokenData?.token?.$extensions?.["com.figma.scopes"] ?? [];
+
+  if (lightAliasId) {
+    lightFigmaValue = { type: "VARIABLE_ALIAS", id: lightAliasId };
+  } else {
+    const converted = convertTokenValueToFigma(variableType, lightValue, {
+      variableName,
+      scopes: tokenScopes,
+    });
+    if (converted === null) {
+      throw new Error(`Could not convert light value for ${variableName}`);
+    }
+    lightFigmaValue = converted;
+  }
+
+  if (darkAliasId) {
+    darkFigmaValue = { type: "VARIABLE_ALIAS", id: darkAliasId };
+  } else {
+    const converted = convertTokenValueToFigma(variableType, darkValue, {
+      variableName,
+      scopes: tokenScopes,
+    });
+    if (converted === null) {
+      throw new Error(`Could not convert dark value for ${variableName}`);
+    }
+    darkFigmaValue = converted;
+  }
+
+  if (existing) {
+    // Check if values are the same (by actual value; normalizes Figma vs our color shape and alias key order)
+    const existingValues = existing.valuesByMode || {};
+    const existingLight = existingValues[modes.light.id];
+    const existingDark = existingValues[modes.dark.id];
+
+    const lightSame = valuesEqual(existingLight, lightFigmaValue);
+    const darkSame = valuesEqual(existingDark, darkFigmaValue);
+
+    if (lightSame && darkSame) {
+      return { action: "skipped", variable: existing };
+    }
+
+    // Update variable
+    await figmaRequest(config, `/variables/${existing.id}`, {
+      method: "PUT",
+      body: JSON.stringify({
+        name: variableName,
+        valuesByMode: {
+          [modes.light.id]: lightFigmaValue,
+          [modes.dark.id]: darkFigmaValue,
+        },
+      }),
+    });
+
+    return { action: "updated", variable: existing };
+  } else {
+    // Create new variable
+    const response = await figmaRequest(config, "/variables", {
+      method: "POST",
+      body: JSON.stringify({
+        name: variableName,
+        variableCollectionId: collectionId,
+        resolvedType: (() => {
+          switch (variableType) {
+            case "color":
+              return "COLOR";
+            case "dimension":
+            case "duration":
+            case "number":
+              return "FLOAT";
+            case "string":
+              return "STRING";
+            default:
+              return "STRING";
+          }
+        })(),
+        valuesByMode: {
+          [modes.light.id]: lightFigmaValue,
+          [modes.dark.id]: darkFigmaValue,
+        },
+      }),
+    });
+
+    const newVariable = response.meta.variable;
+    // Add to cache for future alias resolution
+    existingVariables.push(newVariable);
+
+    return { action: "created", variable: newVariable };
+  }
+}
+
+/**
+ * Normalize a color value to { r, g, b, a } for comparison.
+ * Accepts our format { r, g, b, a } or Figma's format { components, alpha, hex }.
+ * @param {any} val - Color object
+ * @returns {{ r: number, g: number, b: number, a: number } | null} Normalized RGBA or null if not a color
+ */
+function normalizeColorForCompare(val) {
+  if (!val || typeof val !== "object") return null;
+  // Our format: { r, g, b, a }
+  if (val.r !== undefined && val.g !== undefined && val.b !== undefined) {
+    return {
+      r: Number(val.r),
+      g: Number(val.g),
+      b: Number(val.b),
+      a: Number(val.a ?? 1),
+    };
+  }
+  // Figma format: { components: [r,g,b], alpha, hex }
+  if (Array.isArray(val.components) && val.components.length >= 3) {
+    return {
+      r: Number(val.components[0]),
+      g: Number(val.components[1]),
+      b: Number(val.components[2]),
+      a: Number(val.alpha ?? 1),
+    };
+  }
+  return null;
+}
+
+/**
+ * Compare two Figma variable values by actual value, not object structure.
+ * Colors: normalizes both (our { r,g,b,a } or Figma's { components, alpha, hex }) and compares r,g,b,a with tolerance.
+ * Aliases: compares type and id so key order does not matter.
+ * @param {any} val1 - First value (e.g. from Figma API)
+ * @param {any} val2 - Second value (e.g. our computed value)
+ * @returns {boolean} True if values are equal
+ */
+function valuesEqual(val1, val2) {
+  if (typeof val1 !== typeof val2) return false;
+
+  if (typeof val1 === "object" && val1 !== null && val2 !== null) {
+    const norm1 = normalizeColorForCompare(val1);
+    const norm2 = normalizeColorForCompare(val2);
+    if (norm1 !== null && norm2 !== null) {
+      return (
+        Math.abs(norm1.r - norm2.r) < 0.001 &&
+        Math.abs(norm1.g - norm2.g) < 0.001 &&
+        Math.abs(norm1.b - norm2.b) < 0.001 &&
+        Math.abs(norm1.a - norm2.a) < 0.001
+      );
+    }
+    // VARIABLE_ALIAS: compare by type and id only (ignore key order)
+    if (
+      val1.type === "VARIABLE_ALIAS" &&
+      val2.type === "VARIABLE_ALIAS" &&
+      val1.id !== undefined &&
+      val2.id !== undefined
+    ) {
+      return String(val1.id) === String(val2.id);
+    }
+    // Other objects (e.g. dimensions): structural comparison
+    return JSON.stringify(val1) === JSON.stringify(val2);
+  }
+
+  // Numbers: compare with tolerance so float precision (e.g. 0.6 vs 0.6000000238418579) doesn't force updates
+  // Figma FLOAT can differ by ~2e-8; use 1e-6 so opacity/dimension values match
+  const numericTolerance = 1e-6;
+  if (typeof val1 === "number" && typeof val2 === "number") {
+    return Math.abs(val1 - val2) < numericTolerance;
+  }
+
+  // Figma may return FLOAT as string (e.g. "0.6") while we send number — treat as equal if numeric
+  const num1 = typeof val1 === "number" ? val1 : parseFloat(val1);
+  const num2 = typeof val2 === "number" ? val2 : parseFloat(val2);
+  if (!Number.isNaN(num1) && !Number.isNaN(num2)) {
+    return Math.abs(num1 - num2) < numericTolerance;
+  }
+
+  return val1 === val2;
+}
+
+/**
+ * Get variable ID by name from existing variables cache
+ * Optimized: Use Map for O(1) lookup instead of array search
+ * @param {string} variableName - Variable name to find
+ * @param {Array} existingVariables - Array of existing variables
+ * @returns {string|null} Variable ID or null if not found
+ */
+function getVariableIdByName(variableName, existingVariables) {
+  // Optimize: Create a Map for O(1) lookups if we have many variables
+  // For small arrays, linear search is fine, but for large arrays, Map is better
+  if (existingVariables.length > 100) {
+    // Create a Map for efficient lookups
+    const variableMap = new Map();
+    for (const v of existingVariables) {
+      if (v.name) variableMap.set(v.name, v.id);
+      if (v.key && v.key !== v.name) variableMap.set(v.key, v.id);
+    }
+    return variableMap.get(variableName) || null;
+  }
+
+  // For smaller arrays, use linear search (simpler and faster for small N)
+  const variable = existingVariables.find(
+    (v) => v.name === variableName || v.key === variableName,
+  );
+  return variable?.id || null;
+}
+
+/**
+ * Determine the variable name for a token path by checking token data and existing variables
+ * @param {string} targetPath - Token path (e.g., "color/neutral/0")
+ * @param {Map} resolvedTokensForRefs - Map of resolved tokens for reference resolution
+ * @param {Array} existingVariables - Array of existing Figma variables
+ * @param {Map} tempIdMap - Temporary ID map for tracking created variables
+ * @param {Function} isComponentToken - Function to check if a token is a component token
+ * @returns {string} Variable name with correct prefix (primitive/, semantic/, or component/)
+ */
+function determineVariableName(
+  targetPath,
+  resolvedTokensForRefs,
+  existingVariables,
+  tempIdMap,
+  isComponentToken,
+) {
+  // First, check if token exists in resolvedTokensForRefs
+  const targetTokenData = resolvedTokensForRefs.get(targetPath);
+  if (targetTokenData) {
+    if (targetTokenData.isPrimitive) {
+      return `primitive/${targetPath}`;
+    }
+    if (isComponentToken && isComponentToken(targetTokenData.sourceFilePath)) {
+      return `component/${targetPath}`;
+    }
+    return `semantic/${targetPath}`;
+  }
+
+  // Token not in registry - check existing variables to determine type
+  // Check in order: primitive, component, semantic (most common fallback)
+  const primitiveVarName = `primitive/${targetPath}`;
+  const componentVarName = `component/${targetPath}`;
+  const semanticVarName = `semantic/${targetPath}`;
+  const primitiveId = getVariableIdByName(primitiveVarName, existingVariables);
+  const componentId = getVariableIdByName(componentVarName, existingVariables);
+  const primitiveInTemp = tempIdMap.has(primitiveVarName);
+  const componentInTemp = tempIdMap.has(componentVarName);
+  if (primitiveId || primitiveInTemp) {
+    return primitiveVarName;
+  }
+  if (componentId || componentInTemp) {
+    return componentVarName;
+  }
+  // Default to semantic if not found (backward compatibility)
+  return semanticVarName;
+}
+
+/**
+ * Compare two token values to see if they differ
+ * @param {any} value1 - First value
+ * @param {any} value2 - Second value
+ * @returns {boolean} True if values are different
+ */
+function tokenValuesDiffer(value1, value2) {
+  if (value1 === value2) return false;
+  if (value1 == null || value2 == null) return true;
+
+  // Deep comparison for objects
+  if (typeof value1 === "object" && typeof value2 === "object") {
+    const keys1 = Object.keys(value1).sort();
+    const keys2 = Object.keys(value2).sort();
+    if (keys1.length !== keys2.length) return true;
+
+    for (const key of keys1) {
+      if (!keys2.includes(key)) return true;
+      if (tokenValuesDiffer(value1[key], value2[key])) return true;
+    }
+    return false;
+  }
+
+  return true;
+}
+
+module.exports = {
+  figmaRequest,
+  verifyFileAccess,
+  getOrCreateCollection,
+  getOrCreateExtendedCollection,
+  getOrCreateModes,
+  createOrUpdateVariable,
+  valuesEqual,
+  getVariableIdByName,
+  determineVariableName,
+  tokenValuesDiffer,
+  debugLog,
+  sleep,
+};