@servicetitan/hammer-token 2.5.0 → 3.0.0

package/src/utils/figma/__tests__/token-resolution.test.js

@@ -0,0 +1,231 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildReferenceChain,
+  getDefaultDescription,
+  getTokenDescription,
+} from "../token-resolution.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal token registry Map.
+ * Each entry: { token: { $value }, resolvedLight }
+ */
+const makeRegistry = (entries) => {
+  const map = new Map();
+  for (const [path, data] of entries) {
+    map.set(path, data);
+  }
+  return map;
+};
+
+// ---------------------------------------------------------------------------
+// buildReferenceChain
+// ---------------------------------------------------------------------------
+
+describe("buildReferenceChain", () => {
+  it("returns null for non-reference strings", () => {
+    expect(buildReferenceChain("#ffffff", new Map())).toBeNull();
+  });
+
+  it("returns path when token not in registry", () => {
+    const result = buildReferenceChain("{color.primary}", new Map());
+    expect(result).toBe("color/primary");
+  });
+
+  it("follows a single-hop reference to a terminal hex value", () => {
+    const registry = makeRegistry([
+      [
+        "color/primary",
+        { token: { $value: "#0066cc" }, resolvedLight: "#0066cc" },
+      ],
+    ]);
+    const result = buildReferenceChain("{color.primary}", registry);
+    expect(result).toBe("color/primary → #0066cc");
+  });
+
+  it("follows a multi-hop reference chain", () => {
+    const registry = makeRegistry([
+      [
+        "semantic/color/primary",
+        { token: { $value: "{color.primary}" }, resolvedLight: null },
+      ],
+      [
+        "color/primary",
+        { token: { $value: "#0066cc" }, resolvedLight: "#0066cc" },
+      ],
+    ]);
+    const result = buildReferenceChain("{semantic.color.primary}", registry);
+    expect(result).toBe("semantic/color/primary → color/primary → #0066cc");
+  });
+
+  it("handles dimension terminal with rem unit", () => {
+    const registry = makeRegistry([
+      [
+        "size/2",
+        {
+          token: { $value: { value: 0.5, unit: "rem" } },
+          resolvedLight: { value: 0.5, unit: "rem" },
+        },
+      ],
+    ]);
+    const result = buildReferenceChain("{size.2}", registry);
+    expect(result).toBe("size/2 → 0.5rem (8px)");
+  });
+
+  it("handles dimension terminal with px unit", () => {
+    const registry = makeRegistry([
+      [
+        "size/0",
+        {
+          token: { $value: { value: 0, unit: "rem" } },
+          resolvedLight: { value: 0, unit: "rem" },
+        },
+      ],
+    ]);
+    const result = buildReferenceChain("{size.0}", registry);
+    expect(result).toBe("size/0 → 0rem");
+  });
+
+  it("handles composite color terminal with hex resolution", () => {
+    const registry = makeRegistry([
+      [
+        "shadow/color/default",
+        {
+          token: { $value: { color: "{color.neutral.900}", alpha: 0.08 } },
+          resolvedLight: null,
+        },
+      ],
+      [
+        "color/neutral/900",
+        { token: { $value: "#1a1a1a" }, resolvedLight: "#1a1a1a" },
+      ],
+    ]);
+    const result = buildReferenceChain("{shadow.color.default}", registry);
+    expect(result).toBe(
+      "shadow/color/default → color/neutral/900 at 8% opacity → #1A1A1A at 8% opacity",
+    );
+  });
+
+  it("handles composite color terminal without resolving base hex", () => {
+    const registry = makeRegistry([
+      [
+        "shadow/color/default",
+        {
+          token: { $value: { color: "{color.neutral.900}", alpha: 0.08 } },
+          resolvedLight: null,
+        },
+      ],
+      // color/neutral/900 not in registry
+    ]);
+    const result = buildReferenceChain("{shadow.color.default}", registry);
+    expect(result).toBe(
+      "shadow/color/default → color/neutral/900 at 8% opacity",
+    );
+  });
+
+  it("stops at cycle and returns path without infinite recursion", () => {
+    const registry = makeRegistry([
+      ["a/b", { token: { $value: "{a.b}" }, resolvedLight: null }],
+    ]);
+    // Should not throw or infinite-loop; cycle terminates at the repeated path
+    const result = buildReferenceChain("{a.b}", registry);
+    expect(result).toBe("a/b → a/b");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getDefaultDescription
+// ---------------------------------------------------------------------------
+
+describe("getDefaultDescription", () => {
+  it("returns empty string when token has no $value", () => {
+    expect(getDefaultDescription({}, new Map())).toBe("");
+  });
+
+  it("returns empty string for non-reference literal values", () => {
+    expect(getDefaultDescription({ $value: "#ffffff" }, new Map())).toBe("");
+  });
+
+  it("returns chain for reference value", () => {
+    const registry = makeRegistry([
+      [
+        "color/primary",
+        { token: { $value: "#0066cc" }, resolvedLight: "#0066cc" },
+      ],
+    ]);
+    const token = { $value: "{color.primary}" };
+    expect(getDefaultDescription(token, registry)).toBe(
+      "color/primary → #0066cc",
+    );
+  });
+
+  it("returns composite color description for composite value with reference", () => {
+    const registry = makeRegistry([
+      [
+        "color/neutral/900",
+        { token: { $value: "#1a1a1a" }, resolvedLight: "#1a1a1a" },
+      ],
+    ]);
+    const token = { $value: { color: "{color.neutral.900}", alpha: 0.08 } };
+    expect(getDefaultDescription(token, registry)).toBe(
+      "color/neutral/900 at 8% opacity → #1A1A1A at 8% opacity",
+    );
+  });
+
+  it("returns composite color without hex when base not in registry", () => {
+    const token = { $value: { color: "{color.neutral.900}", alpha: 0.5 } };
+    expect(getDefaultDescription(token, new Map())).toBe(
+      "color/neutral/900 at 50% opacity",
+    );
+  });
+
+  it("returns empty string for composite color with no color ref", () => {
+    const token = { $value: { color: "#ffffff", alpha: 0.5 } };
+    expect(getDefaultDescription(token, new Map())).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getTokenDescription
+// ---------------------------------------------------------------------------
+
+describe("getTokenDescription", () => {
+  it("returns only explicit $description when no chain available", () => {
+    const token = { $description: "My description", $value: "#ffffff" };
+    expect(getTokenDescription(token, new Map())).toBe("My description");
+  });
+
+  it("returns chain when no $description and value is a reference", () => {
+    const registry = makeRegistry([
+      [
+        "color/primary",
+        { token: { $value: "#0066cc" }, resolvedLight: "#0066cc" },
+      ],
+    ]);
+    const token = { $value: "{color.primary}" };
+    expect(getTokenDescription(token, registry)).toBe(
+      "color/primary → #0066cc",
+    );
+  });
+
+  it("combines $description and chain with newline when both exist", () => {
+    const registry = makeRegistry([
+      [
+        "color/primary",
+        { token: { $value: "#0066cc" }, resolvedLight: "#0066cc" },
+      ],
+    ]);
+    const token = { $description: "Primary color", $value: "{color.primary}" };
+    expect(getTokenDescription(token, registry)).toBe(
+      "Primary color\ncolor/primary → #0066cc",
+    );
+  });
+
+  it("returns empty string when no $description and no chain", () => {
+    const token = { $value: "#ffffff" };
+    expect(getTokenDescription(token, new Map())).toBe("");
+  });
+});

package/src/utils/figma/auth.js

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+
+/**
+ * Figma Authentication Module
+ *
+ * Handles loading configuration and OAuth2 refresh token authentication for Figma API access.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const {
+  FIGMA_PROD_FILE_KEY,
+  COLLECTION_NAME,
+  LIGHT_MODE_NAME,
+  DARK_MODE_NAME,
+} = require("./constants");
+const { ConfigurationError } = require("./errors");
+const { validateFileKey } = require("./utils");
+
+// .env.local file path (repo root)
+const ENV_FILE = path.join(__dirname, "../../../../../.env.local");
+
+/**
+ * Load environment variables from .env.local file if it exists
+ */
+function loadEnvFile() {
+  if (fs.existsSync(ENV_FILE)) {
+    try {
+      const envContent = fs.readFileSync(ENV_FILE, "utf8");
+      const lines = envContent.split("\n");
+
+      for (const line of lines) {
+        // Skip comments and empty lines
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+          continue;
+        }
+
+        // Parse KEY=VALUE format
+        const match = trimmed.match(/^([^=]+)=(.*)$/);
+        if (match) {
+          const key = match[1].trim();
+          const value = match[2].trim().replace(/^["']|["']$/g, ""); // Remove quotes
+          // Only set if not already in process.env (env vars take precedence)
+          if (!process.env[key]) {
+            process.env[key] = value;
+          }
+        }
+      }
+    } catch (error) {
+      // Silently fail if .env.local file can't be read
+      if (process.env.DEBUG) {
+        console.warn(
+          `Warning: Could not read .env.local file: ${error.message}`,
+        );
+      }
+    }
+  }
+}
+
+// Load .env.local file on module load
+loadEnvFile();
+
+// Default configuration (uses production file key)
+const DEFAULT_CONFIG = {
+  fileKey: FIGMA_PROD_FILE_KEY,
+  collectionName: COLLECTION_NAME,
+  lightModeName: LIGHT_MODE_NAME,
+  darkModeName: DARK_MODE_NAME,
+};
+
+// OAuth2 token cache (in-memory)
+let tokenCache = {
+  accessToken: null,
+  expiresAt: null,
+  refreshToken: null,
+};
+
+// Figma OAuth2 endpoints
+const FIGMA_OAUTH_BASE = "https://api.figma.com/v1";
+const TOKEN_EXPIRY_BUFFER_MS = 60000; // Refresh 1 minute before expiry
+
+/**
+ * Validate configuration
+ * @param {Object} config - Configuration object to validate
+ * @throws {ConfigurationError} If configuration is invalid
+ */
+function validateConfig(config) {
+  const errors = [];
+
+  if (!config.fileKey) {
+    errors.push(
+      "FIGMA_FILE_KEY is required (set via env var, config file, or --file-key flag)",
+    );
+  } else {
+    try {
+      validateFileKey(config.fileKey);
+    } catch (error) {
+      errors.push(`Invalid file key: ${error.message}`);
+    }
+  }
+
+  if (!isOAuth2Configured(config)) {
+    errors.push(
+      "OAuth2 credentials are required. Set FIGMA_CLIENT_ID, FIGMA_CLIENT_SECRET, and FIGMA_REFRESH_TOKEN",
+    );
+  }
+
+  if (errors.length > 0) {
+    throw new ConfigurationError("Configuration validation failed", { errors });
+  }
+}
+
+/**
+ * Load configuration from environment variables
+ * @param {string} [overrideFileKey] - Optional fileKey to override the default or env var
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipValidation=false] - Skip validation (for testing)
+ * @returns {Object} Configuration object with fileKey, collectionName, mode names, and OAuth2 credentials
+ */
+function loadConfig(overrideFileKey = null, options = {}) {
+  const { skipValidation = false } = options;
+  const config = { ...DEFAULT_CONFIG };
+
+  // Load from environment variables
+  if (process.env.FIGMA_CLIENT_ID) {
+    config.clientId = process.env.FIGMA_CLIENT_ID;
+  }
+  if (process.env.FIGMA_CLIENT_SECRET) {
+    config.clientSecret = process.env.FIGMA_CLIENT_SECRET;
+  }
+  if (process.env.FIGMA_REFRESH_TOKEN) {
+    config.refreshToken = process.env.FIGMA_REFRESH_TOKEN;
+  }
+  if (process.env.FIGMA_FILE_KEY) {
+    config.fileKey = process.env.FIGMA_FILE_KEY;
+  }
+
+  // Override fileKey if provided as parameter (takes precedence)
+  if (overrideFileKey) {
+    config.fileKey = overrideFileKey;
+  }
+
+  // Validate configuration unless explicitly skipped
+  if (!skipValidation) {
+    validateConfig(config);
+  }
+
+  return config;
+}
+
+/**
+ * Check if OAuth2 credentials are configured
+ * @param {Object} config - Configuration object
+ * @returns {boolean} True if OAuth2 is configured
+ */
+function isOAuth2Configured(config) {
+  return !!(config.clientId && config.clientSecret && config.refreshToken);
+}
+
+/**
+ * Check if a cached access token is still valid
+ * @returns {boolean} True if token is valid and not expired
+ */
+function isTokenValid() {
+  if (!tokenCache.accessToken || !tokenCache.expiresAt) {
+    return false;
+  }
+
+  // Check if token expires within the buffer time
+  const now = Date.now();
+  return tokenCache.expiresAt > now + TOKEN_EXPIRY_BUFFER_MS;
+}
+
+/**
+ * Refresh OAuth2 access token using refresh token
+ * @param {Object} config - Configuration object with OAuth2 credentials
+ * @returns {Promise<string>} New access token
+ * @throws {Error} If refresh fails
+ */
+async function refreshAccessToken(config) {
+  const { clientId, clientSecret, refreshToken } = config;
+
+  if (!clientId || !clientSecret || !refreshToken) {
+    throw new Error(
+      "OAuth2 credentials not configured. Required environment variables:\n" +
+        "  - FIGMA_CLIENT_ID\n" +
+        "  - FIGMA_CLIENT_SECRET\n" +
+        "  - FIGMA_REFRESH_TOKEN",
+    );
+  }
+
+  try {
+    // Figma requires HTTP Basic Authentication with Base64 encoded client_id:client_secret
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString(
+      "base64",
+    );
+
+    // Figma requires form-encoded body for refresh token endpoint
+    const formData = new URLSearchParams({
+      refresh_token: refreshToken,
+    });
+
+    const response = await fetch(`${FIGMA_OAUTH_BASE}/oauth/refresh`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${credentials}`,
+      },
+      body: formData.toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorMessage = `Token refresh failed (${response.status}): ${errorText || response.statusText}`;
+
+      // Parse error details if available
+      try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.error) {
+          errorMessage = `Token refresh failed: ${errorJson.error}`;
+          if (errorJson.error_description) {
+            errorMessage += ` - ${errorJson.error_description}`;
+          }
+        }
+      } catch {
+        // Not JSON, use raw text
+        if (errorText && errorText.length < 200) {
+          errorMessage += ` (${errorText})`;
+        }
+      }
+
+      // Handle specific error cases
+      if (response.status === 401 || errorMessage.includes("invalid_grant")) {
+        throw new Error(
+          "Authentication Failed - Please Re-Login\n\n" +
+            "The refresh token has expired or been revoked. You need to:\n" +
+            "  1. Re-authenticate with Figma OAuth2\n" +
+            "  2. Obtain a new refresh token\n" +
+            "  3. Update FIGMA_REFRESH_TOKEN in your configuration",
+        );
+      }
+
+      throw new Error(errorMessage);
+    }
+
+    const data = await response.json();
+
+    if (!data.access_token) {
+      throw new Error("Token refresh response missing access_token");
+    }
+
+    // Update token cache
+    tokenCache.accessToken = data.access_token;
+
+    // Figma access tokens typically expire in 1 hour (3600 seconds)
+    // Use expires_in if provided, otherwise default to 1 hour
+    const expiresIn = data.expires_in || 3600;
+    tokenCache.expiresAt = Date.now() + expiresIn * 1000;
+
+    // Handle token rotation - Figma may return a new refresh token
+    if (data.refresh_token && data.refresh_token !== refreshToken) {
+      tokenCache.refreshToken = data.refresh_token;
+
+      // Log warning about token rotation
+      console.warn("\n⚠️  WARNING: Refresh Token has rotated!");
+      console.warn("   A new refresh token was returned by Figma.");
+      console.warn(
+        "   Please update your configuration with the new refresh token:\n",
+      );
+      console.warn(`   New Refresh Token: ${data.refresh_token}\n`);
+      console.warn("   Update the following:");
+      console.warn("     - FIGMA_REFRESH_TOKEN environment variable");
+      console.warn("     - GitHub secret (if running in CI)\n");
+
+      // In CI, also log to stdout for easy capture
+      if (process.env.CI || process.env.GITHUB_ACTIONS) {
+        console.log("::warning::Refresh token rotated - update your secrets");
+        console.log(`FIGMA_REFRESH_TOKEN=${data.refresh_token}`);
+      }
+    } else {
+      // Keep the existing refresh token
+      tokenCache.refreshToken = refreshToken;
+    }
+
+    return data.access_token;
+  } catch (error) {
+    // Re-throw with more context if it's not already a formatted error
+    if (error.message && !error.message.includes("Authentication Failed")) {
+      throw new Error(`Failed to refresh access token: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get a valid access token using OAuth2 refresh token
+ * @param {Object} config - Configuration object
+ * @returns {Promise<string>} Access token
+ * @throws {Error} If OAuth2 is not configured or refresh fails
+ */
+async function getAccessToken(config) {
+  if (!isOAuth2Configured(config)) {
+    throw new Error(
+      "OAuth2 credentials not configured.\n\n" +
+        "Please provide OAuth2 credentials as environment variables:\n" +
+        "  - FIGMA_CLIENT_ID\n" +
+        "  - FIGMA_CLIENT_SECRET\n" +
+        "  - FIGMA_REFRESH_TOKEN\n\n" +
+        "Get OAuth2 credentials from: https://www.figma.com/developers/apps",
+    );
+  }
+
+  // Check if we have a valid cached token
+  if (isTokenValid()) {
+    return tokenCache.accessToken;
+  }
+
+  // Refresh the token
+  return await refreshAccessToken(config);
+}
+
+/**
+ * Get authentication method being used
+ * @param {Object} config - Configuration object
+ * @returns {Promise<string>} Authentication method (always 'OAuth2' if configured)
+ */
+async function getAuthMethod(config) {
+  if (isOAuth2Configured(config)) {
+    return "OAuth2";
+  }
+  return "None";
+}
+
+/**
+ * Clear the token cache (useful for testing or forced refresh)
+ */
+function clearTokenCache() {
+  tokenCache = {
+    accessToken: null,
+    expiresAt: null,
+    refreshToken: null,
+  };
+}
+
+module.exports = {
+  loadConfig,
+  validateConfig,
+  getAccessToken,
+  getAuthMethod,
+  refreshAccessToken,
+  clearTokenCache,
+  isOAuth2Configured,
+  DEFAULT_CONFIG,
+};

package/src/utils/figma/constants.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * Figma Constants
+ *
+ * File-specific constants for Figma integration.
+ */
+
+// Figma file key - specific to the target file
+const FIGMA_PROD_FILE_KEY = "YiDC0EjGiMSxgXU61X6Qpx";
+
+// Variable collection configuration
+const COLLECTION_NAME = "Anvil2 Theme";
+const LIGHT_MODE_NAME = "Light";
+const DARK_MODE_NAME = "Dark";
+
+module.exports = {
+  FIGMA_PROD_FILE_KEY,
+  COLLECTION_NAME,
+  LIGHT_MODE_NAME,
+  DARK_MODE_NAME,
+};

package/src/utils/figma/errors.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Custom Error Classes for Figma Sync
+ *
+ * Provides structured error handling with error codes and details.
+ */
+
+/**
+ * Base error class for all Figma sync errors
+ */
+class FigmaSyncError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = "FigmaSyncError";
+    this.code = code;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Authentication-related errors
+ */
+class AuthenticationError extends FigmaSyncError {
+  constructor(message, details = {}) {
+    super(message, "AUTH_ERROR", details);
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * File access-related errors
+ */
+class FileAccessError extends FigmaSyncError {
+  constructor(message, details = {}) {
+    super(message, "FILE_ACCESS_ERROR", details);
+    this.name = "FileAccessError";
+  }
+}
+
+/**
+ * Configuration validation errors
+ */
+class ConfigurationError extends FigmaSyncError {
+  constructor(message, details = {}) {
+    super(message, "CONFIG_ERROR", details);
+    this.name = "ConfigurationError";
+  }
+}
+
+/**
+ * Token validation errors
+ */
+class TokenValidationError extends FigmaSyncError {
+  constructor(message, details = {}) {
+    super(message, "TOKEN_VALIDATION_ERROR", details);
+    this.name = "TokenValidationError";
+  }
+}
+
+/**
+ * API request errors
+ */
+class ApiError extends FigmaSyncError {
+  constructor(message, statusCode, details = {}) {
+    super(message, "API_ERROR", { ...details, statusCode });
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+  }
+}
+
+module.exports = {
+  FigmaSyncError,
+  AuthenticationError,
+  FileAccessError,
+  ConfigurationError,
+  TokenValidationError,
+  ApiError,
+};