jfs-components 0.1.30 → 0.1.33

package/scripts/extract-figma-modes.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * Extract explicit variable modes per layer from a Figma file.
+ *
+ * Figma MCP already gives agents the component structure, props, and variants.
+ * The one thing it does NOT expose is which variable modes are explicitly set
+ * on each layer — that is all this script outputs.
+ *
+ * Resolution is collection-key based, exclusively:
+ *   - In consumer files, every subscribed collection id in explicitVariableModes
+ *     embeds the library collection key: "VariableCollectionId:<40-hex key>/<localId>".
+ *     The key never changes across publishes.
+ *   - The packaged variables JSON (src/design-tokens/*-variables-full.json)
+ *     carries the same key on each collection, so key -> collection -> modeId
+ *     -> mode name is exact. Mode ids are looked up only *within* the matched
+ *     collection — never globally, since mode ids can collide across
+ *     collections in complex projects.
+ *
+ * REST API only. No Figma Plugin API anywhere, so consumers with view-only /
+ * Dev seats can run this — any token with file read access works. One
+ * GET /v1/files/:key call per extraction.
+ *
+ * Usage:
+ *   export FIGMA_ACCESS_TOKEN=figd_...
+ *   npx jfs-extract-modes "https://www.figma.com/design/<fileKey>/...?node-id=1-10636"
+ *   npx jfs-extract-modes <fileKey> <nodeId> [--out modes.json]
+ *
+ * One-time maintenance (library maintainers, when the variables JSON export
+ * lacks collection keys): patch keys into the JSON from the master library
+ * file via REST variables/local:
+ *   npx jfs-extract-modes --add-keys <master-library-fileKey-or-url>
+ *
+ * Output schema (only what Figma MCP doesn't provide):
+ *   {
+ *     "file": "D2C Test File",
+ *     "root": "CC / Unsub",
+ *     "modes": [
+ *       { "layer": "AppBar", "nodeId": "1:10638", "path": "CC / Unsub > AppBar",
+ *         "modes": { "Context2": "AppBar" } }
+ *     ]
+ *   }
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const API_BASE = "https://api.figma.com/v1";
+const TOKENS_DIR = path.join(__dirname, "..", "src", "design-tokens");
+const COLLECTION_KEY_PATTERN = /^VariableCollectionId:([0-9a-f]{40})\//;
+
+function usage(exitCode) {
+  console.error(
+    `Usage:
+  FIGMA_ACCESS_TOKEN=... jfs-extract-modes <figma-url> [--out modes.json]
+  FIGMA_ACCESS_TOKEN=... jfs-extract-modes <fileKey> <nodeId> [--out modes.json]
+  FIGMA_ACCESS_TOKEN=... jfs-extract-modes --add-keys <master-library-fileKey-or-url>`,
+  );
+  process.exit(exitCode);
+}
+
+function fileKeyFromUrlOrKey(value) {
+  if (/^https?:\/\//.test(value)) {
+    const match = new URL(value).pathname.match(/\/(?:design|file)\/([^/]+)/);
+    if (!match) {
+      console.error("Could not parse fileKey from URL.");
+      process.exit(1);
+    }
+    return match[1];
+  }
+  return value;
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const out = { fileKey: null, nodeId: null, outPath: null, addKeysFile: null };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--out") {
+      out.outPath = args[++i];
+    } else if (arg === "--add-keys") {
+      out.addKeysFile = fileKeyFromUrlOrKey(args[++i] ?? "");
+    } else if (arg === "--help" || arg === "-h") {
+      usage(0);
+    } else if (/^https?:\/\//.test(arg)) {
+      const url = new URL(arg);
+      out.fileKey = fileKeyFromUrlOrKey(arg);
+      const nodeParam = url.searchParams.get("node-id");
+      if (nodeParam) out.nodeId = nodeParam.replace(/-/g, ":");
+    } else if (!out.fileKey) {
+      out.fileKey = arg;
+    } else if (!out.nodeId) {
+      out.nodeId = arg.replace(/-/g, ":");
+    } else {
+      usage(1);
+    }
+  }
+
+  if (out.addKeysFile) return out;
+  if (!out.fileKey || !out.nodeId) usage(1);
+  return out;
+}
+
+function getToken() {
+  const token = process.env.FIGMA_ACCESS_TOKEN || process.env.FIGMA_TOKEN;
+  if (!token) {
+    console.error("Set FIGMA_ACCESS_TOKEN (needs file read access only).");
+    process.exit(1);
+  }
+  return token;
+}
+
+async function figmaGet(urlPath, token) {
+  const response = await fetch(`${API_BASE}${urlPath}`, {
+    headers: { "X-Figma-Token": token },
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      `Figma API ${response.status} for ${urlPath}: ${body.err || body.message || "request failed"}`,
+    );
+  }
+  return body;
+}
+
+function listVariablesJsonFiles() {
+  let files;
+  try {
+    files = fs
+      .readdirSync(TOKENS_DIR)
+      .filter((name) => name.endsWith("-variables-full.json"))
+      .map((name) => path.join(TOKENS_DIR, name));
+  } catch {
+    files = [];
+  }
+  if (files.length === 0) {
+    console.error(`No *-variables-full.json found in ${TOKENS_DIR}.`);
+    process.exit(1);
+  }
+  return files;
+}
+
+/**
+ * collection key -> { name, modes: Map<modeId, modeName> }
+ * Exits with instructions if any collection is missing its key — key-based
+ * resolution is the only supported path.
+ */
+function buildKeyIndex() {
+  const byKey = new Map();
+  const missingKeys = [];
+  const files = listVariablesJsonFiles();
+
+  for (const file of files) {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    for (const collection of data.collections ?? []) {
+      if (typeof collection.key !== "string" || collection.key.length === 0) {
+        missingKeys.push(`${collection.name} (${path.basename(file)})`);
+        continue;
+      }
+      const modes = new Map();
+      for (const mode of collection.modes ?? []) {
+        modes.set(mode.modeId, mode.name);
+      }
+      byKey.set(collection.key, { name: collection.name, modes });
+    }
+  }
+
+  if (byKey.size === 0) {
+    console.error(
+      "The variables JSON has no collection keys, so modes cannot be resolved.\n" +
+        "Run this once against the master variables library file to patch them in:\n" +
+        "  jfs-extract-modes --add-keys <master-library-fileKey-or-url>",
+    );
+    process.exit(1);
+  }
+  if (missingKeys.length > 0) {
+    console.error(
+      `Warning: ${missingKeys.length} collection(s) have no key and were skipped:\n  ` +
+        missingKeys.slice(0, 10).join("\n  "),
+    );
+  }
+
+  console.error(
+    `Indexed ${byKey.size} collection(s) by key from ${files.length} variables JSON file(s).`,
+  );
+  return byKey;
+}
+
+function findNodePath(node, targetId, trail = []) {
+  const next = [...trail, node];
+  if (node.id === targetId) return next;
+  for (const child of node.children ?? []) {
+    const found = findNodePath(child, targetId, next);
+    if (found) return found;
+  }
+  return null;
+}
+
+function extractModes(fileResponse, nodeId, byKey) {
+  const pathToRoot = findNodePath(fileResponse.document, nodeId);
+  if (!pathToRoot) {
+    throw new Error(`Node "${nodeId}" not found in file.`);
+  }
+
+  const root = pathToRoot[pathToRoot.length - 1];
+  const layers = [];
+  const unresolved = [];
+
+  function resolveNodeModes(node) {
+    const modes = {};
+    for (const [collectionId, modeId] of Object.entries(
+      node.explicitVariableModes ?? {},
+    )) {
+      const keyMatch = String(collectionId).match(COLLECTION_KEY_PATTERN);
+      if (!keyMatch) {
+        // Local (non-subscribed) collection in the consumer file: not part of
+        // the published library, nothing to resolve against.
+        unresolved.push({
+          layer: node.name,
+          collectionId,
+          modeId,
+          reason: "local collection (no library key in id)",
+        });
+        continue;
+      }
+      const collection = byKey.get(keyMatch[1]);
+      if (!collection) {
+        unresolved.push({
+          layer: node.name,
+          collectionId,
+          modeId,
+          reason: "key not in variables JSON (library out of date?)",
+        });
+        continue;
+      }
+      const modeName = collection.modes.get(modeId);
+      if (!modeName) {
+        unresolved.push({
+          layer: node.name,
+          collectionId,
+          modeId,
+          reason: `mode not in collection "${collection.name}" (re-export variables JSON?)`,
+        });
+        continue;
+      }
+      modes[collection.name] = modeName;
+    }
+    return modes;
+  }
+
+  // Modes set on ancestors above the requested node (inherited by everything below)
+  const inherited = {};
+  for (const ancestor of pathToRoot.slice(0, -1)) {
+    Object.assign(inherited, resolveNodeModes(ancestor));
+  }
+
+  function walk(node, trail) {
+    const modes = resolveNodeModes(node);
+    if (Object.keys(modes).length > 0) {
+      layers.push({
+        layer: node.name,
+        nodeId: node.id,
+        path: trail.join(" > "),
+        modes,
+      });
+    }
+    for (const child of node.children ?? []) {
+      walk(child, [...trail, child.name]);
+    }
+  }
+
+  walk(root, [root.name]);
+
+  const result = {
+    file: fileResponse.name ?? null,
+    root: root.name,
+    note: "explicit variable modes per layer; children inherit ancestor modes unless overridden",
+    modes: layers,
+  };
+  if (Object.keys(inherited).length > 0) result.inheritedFromAncestors = inherited;
+  if (unresolved.length > 0) result.unresolved = unresolved;
+  return result;
+}
+
+/**
+ * One-time maintenance: fetch collection keys from the master library file
+ * (REST variables/local returns `key` for every collection) and write them
+ * into the packaged variables JSON, matching by local collection id.
+ */
+async function addKeys(masterFileKey, token) {
+  const response = await figmaGet(
+    `/files/${masterFileKey}/variables/local`,
+    token,
+  );
+  const remote = Object.values(response.meta?.variableCollections ?? {});
+  const keyById = new Map(
+    remote
+      .filter((collection) => collection.key)
+      .map((collection) => [collection.id, collection.key]),
+  );
+  console.error(
+    `Fetched ${keyById.size} collection key(s) from ${masterFileKey}.`,
+  );
+
+  for (const file of listVariablesJsonFiles()) {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    let patched = 0;
+    let missing = 0;
+    for (const collection of data.collections ?? []) {
+      const key = keyById.get(collection.id);
+      if (key) {
+        collection.key = key;
+        patched += 1;
+      } else if (!collection.key) {
+        missing += 1;
+      }
+    }
+    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+    console.error(
+      `${path.basename(file)}: patched ${patched} key(s)` +
+        (missing ? `, ${missing} collection(s) still without key` : ""),
+    );
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const token = getToken();
+
+  if (args.addKeysFile) {
+    await addKeys(args.addKeysFile, token);
+    return;
+  }
+
+  const byKey = buildKeyIndex();
+  const fileResponse = await figmaGet(
+    `/files/${args.fileKey}?ids=${encodeURIComponent(args.nodeId)}`,
+    token,
+  );
+  const result = extractModes(fileResponse, args.nodeId, byKey);
+
+  const json = JSON.stringify(result, null, 2);
+  if (args.outPath) {
+    fs.writeFileSync(path.resolve(args.outPath), `${json}\n`);
+    console.error(`Wrote ${args.outPath}`);
+  }
+  process.stdout.write(`${json}\n`);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message || error);
+    process.exit(1);
+  });
+}
+
+module.exports = { buildKeyIndex, extractModes };