figma-cache-toolchain 2.0.4 → 2.0.7

package/scripts/import-mcp-raw-evidence.cjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Import MCP raw evidence files into figma-cache node directory and generate a manifest.
+ *
+ * This is the toolchain-friendly way to implement: "call MCP once -> cache evidence".
+ *
+ * Usage:
+ *   node scripts/import-mcp-raw-evidence.cjs \
+ *     --cacheKey=<fileKey#nodeId> \
+ *     --design-context=<path/to/get_design_context.txt> \
+ *     --metadata=<path/to/get_metadata.txt> \
+ *     --variable-defs=<path/to/get_variable_defs.json>
+ *
+ * Notes:
+ * - Writes to: figma-cache/files/<fileKey>/nodes/<safeNodeId>/mcp-raw/
+ * - Generates: mcp-raw-manifest.json with sha256 + byte sizes
+ */
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+function sha256Utf8(text) {
+  return crypto.createHash("sha256").update(String(text || ""), "utf8").digest("hex");
+}
+
+function sizeUtf8(text) {
+  return Buffer.byteLength(String(text || ""), "utf8");
+}
+
+function readUtf8(absPath) {
+  return fs.readFileSync(absPath, "utf8");
+}
+
+function resolveAbs(p) {
+  const v = String(p || "").trim();
+  if (!v) return "";
+  return path.isAbsolute(v) ? v : path.join(process.cwd(), v);
+}
+
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+function parseArgs(argv) {
+  const out = {
+    cacheKey: "",
+    designContext: "",
+    metadata: "",
+    variableDefs: "",
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--cacheKey=")) out.cacheKey = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--design-context="))
+      out.designContext = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--metadata=")) out.metadata = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--variable-defs="))
+      out.variableDefs = arg.split("=").slice(1).join("=").trim();
+  });
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.cacheKey || !args.designContext || !args.metadata || !args.variableDefs) {
+    console.error(
+      "Usage: node scripts/import-mcp-raw-evidence.cjs --cacheKey=<fileKey#nodeId> --design-context=<txt> --metadata=<txt> --variable-defs=<json>"
+    );
+    process.exit(2);
+  }
+
+  const cacheKey = String(args.cacheKey).trim();
+  const [fileKey, nodeIdRaw] = cacheKey.split("#");
+  const nodeId = normalizeNodeId(nodeIdRaw);
+  if (!fileKey || !nodeId) {
+    console.error(`[import-mcp-raw-evidence] invalid cacheKey: ${cacheKey}`);
+    process.exit(2);
+  }
+
+  const safeNodeDir = nodeId.replace(/:/g, "-");
+  const mcpRawDir = path.join(
+    process.cwd(),
+    "figma-cache",
+    "files",
+    fileKey,
+    "nodes",
+    safeNodeDir,
+    "mcp-raw"
+  );
+  fs.mkdirSync(mcpRawDir, { recursive: true });
+
+  const srcDesign = resolveAbs(args.designContext);
+  const srcMeta = resolveAbs(args.metadata);
+  const srcVars = resolveAbs(args.variableDefs);
+  if (!fs.existsSync(srcDesign) || !fs.existsSync(srcMeta) || !fs.existsSync(srcVars)) {
+    console.error("[import-mcp-raw-evidence] missing input file(s)");
+    process.exit(2);
+  }
+
+  const files = {
+    get_design_context: "mcp-raw-get-design-context.txt",
+    get_metadata: "mcp-raw-get-metadata.txt",
+    get_variable_defs: "mcp-raw-get-variable-defs.json",
+  };
+
+  const contents = {
+    get_design_context: readUtf8(srcDesign),
+    get_metadata: readUtf8(srcMeta),
+    get_variable_defs: readUtf8(srcVars),
+  };
+
+  fs.writeFileSync(path.join(mcpRawDir, files.get_design_context), contents.get_design_context, "utf8");
+  fs.writeFileSync(path.join(mcpRawDir, files.get_metadata), contents.get_metadata, "utf8");
+  fs.writeFileSync(path.join(mcpRawDir, files.get_variable_defs), contents.get_variable_defs, "utf8");
+
+  const manifest = {
+    mcpServer: "plugin-figma-figma",
+    fileKey,
+    nodeId,
+    files,
+    fileHashes: Object.fromEntries(Object.entries(contents).map(([k, v]) => [k, sha256Utf8(v)])),
+    fileSizes: Object.fromEntries(Object.entries(contents).map(([k, v]) => [k, sizeUtf8(v)])),
+  };
+
+  fs.writeFileSync(
+    path.join(mcpRawDir, "mcp-raw-manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8"
+  );
+
+  console.log(
+    `[import-mcp-raw-evidence] ok -> ${path.join(mcpRawDir, "mcp-raw-manifest.json")}`
+  );
+}
+
+main();
+

package/scripts/merge-figma-geometry-metrics.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Merge figma-geometry-metrics.json into raw.json as layoutMetrics[].
+ *
+ * Geometry file shape:
+ * {
+ *   "version": 1,
+ *   "source": "figma_plugin_absoluteBoundingBox",
+ *   "metrics": [ { "id": "...", "kind": "spacer_between_nodes_y", "fromNodeId": "...", "toNodeId": "...", "spacerPx": 26, ... } ]
+ * }
+ *
+ * Usage:
+ *   node scripts/merge-figma-geometry-metrics.cjs --raw=<raw.json> --geometry=<figma-geometry-metrics.json>
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { mergeLayoutMetricsFromGeometry } = require("../figma-cache/js/raw-derivatives");
+
+function safeReadJson(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(absPath, value) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function parseArgs(argv) {
+  const out = { raw: "", geometry: "" };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--raw=")) out.raw = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--geometry=")) out.geometry = arg.split("=").slice(1).join("=").trim();
+  });
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const rawAbs = path.isAbsolute(args.raw) ? args.raw : path.join(process.cwd(), args.raw);
+  const geoAbs = path.isAbsolute(args.geometry) ? args.geometry : path.join(process.cwd(), args.geometry);
+  if (!args.raw || !args.geometry) {
+    console.error(
+      "Usage: node scripts/merge-figma-geometry-metrics.cjs --raw=<raw.json> --geometry=<figma-geometry-metrics.json>"
+    );
+    process.exit(2);
+  }
+  if (!fs.existsSync(rawAbs)) {
+    console.error(`[merge-figma-geometry-metrics] raw not found: ${rawAbs}`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(geoAbs)) {
+    console.error(`[merge-figma-geometry-metrics] geometry not found: ${geoAbs}`);
+    process.exit(2);
+  }
+
+  const raw = safeReadJson(rawAbs);
+  const geo = safeReadJson(geoAbs);
+  if (!raw || typeof raw !== "object") {
+    console.error(`[merge-figma-geometry-metrics] invalid raw: ${rawAbs}`);
+    process.exit(2);
+  }
+  if (!geo || typeof geo !== "object" || !Array.isArray(geo.metrics)) {
+    console.error(`[merge-figma-geometry-metrics] invalid geometry (need .metrics[]): ${geoAbs}`);
+    process.exit(2);
+  }
+
+  mergeLayoutMetricsFromGeometry(raw, geo);
+  writeJson(rawAbs, raw);
+  console.log(
+    `[merge-figma-geometry-metrics] ok merged=${geo.metrics.length} -> ${rawAbs}`
+  );
+}
+
+main();

package/scripts/ui-1to1-audit.js

@@ -11,11 +11,28 @@ const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
 const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
 const DEFAULT_CONTRACT_PATH = "figma-cache/adapters/ui-adapter.contract.json";
-const DEFAULT_REPORT_PATH = "figma-cache/reports/ui-1to1-report.json";
+const DEFAULT_REPORT_PATH = "figma-cache/reports/runtime/ui-1to1-report.json";
 const DEFAULT_MIN_SCORE = 85;
 const DEFAULT_RECIPES_DIR = "figma-cache/adapters/recipes";
 const FAIL_EXIT_CODE = 2;
 
+function parseBoolEnv(value, fallback) {
+  if (value == null) return fallback;
+  const v = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(v)) return true;
+  if (["0", "false", "no", "off"].includes(v)) return false;
+  return fallback;
+}
+
+function filterRemoteFigmaAssetRefs(input) {
+  const text = String(input || "");
+  // Mask Figma MCP asset URLs (often require auth; non-deterministic in runtime).
+  // This keeps audits stable when teams choose to not ship remote figma assets.
+  return text
+    .replace(/https:\/\/www\.figma\.com\/api\/mcp\/asset\/[a-z0-9-]+/gi, "__FIGMA_MCP_ASSET__")
+    .replace(/\bimg[A-Za-z0-9_]*\s*=\s*['"]https:\/\/www\.figma\.com\/api\/mcp\/asset\/[a-z0-9-]+['"]/gi, "img__=__FIGMA_MCP_ASSET__");
+}
+
 function normalizeSlash(input) {
   return String(input || "").replace(/\\/g, "/");
 }
@@ -51,6 +68,7 @@ function parseArgs(argv) {
     reportPath: DEFAULT_REPORT_PATH,
     minScore: DEFAULT_MIN_SCORE,
     recipesDir: DEFAULT_RECIPES_DIR,
+    filterRemoteFigmaAssets: parseBoolEnv(process.env.FIGMA_UI_FILTER_REMOTE_FIGMA_ASSETS, true),
     unknownArgs: [],
   };
 
@@ -80,6 +98,10 @@ function parseArgs(argv) {
       options.recipesDir = arg.split("=").slice(1).join("=").trim() || DEFAULT_RECIPES_DIR;
       return;
     }
+    if (arg === "--no-filter-remote-figma-assets") {
+      options.filterRemoteFigmaAssets = false;
+      return;
+    }
     options.unknownArgs.push(arg);
   });
 
@@ -170,7 +192,7 @@ function detectMatchedRecipes(recipes, contextText, statesInCache) {
 }
 
 function scoreItem(params) {
-  const { cacheKey, item, contract, targetCode, recipes } = params;
+  const { cacheKey, item, contract, targetCode, recipes, options } = params;
   const blocking = [];
   const warnings = [];
   const diffs = [];
@@ -261,9 +283,13 @@ function scoreItem(params) {
   }
 
   const hasTodo = normalizedFacts.hasPlaceholder;
+  const effectiveTargetCode =
+    options && options.filterRemoteFigmaAssets
+      ? filterRemoteFigmaAssetRefs(targetCode)
+      : String(targetCode || "");
   const matchedRecipes = detectMatchedRecipes(
     recipes,
-    `${specText}\n${stateMapText}\n${JSON.stringify(rawJson || {})}\n${targetCode}`,
+    `${specText}\n${stateMapText}\n${JSON.stringify(rawJson || {})}\n${effectiveTargetCode}`,
     statesInCache
   );
   if (!matchedRecipes.length) {
@@ -283,11 +309,11 @@ function scoreItem(params) {
     : textFacts.length;
   const tokenCodeHits = hasTargetCode
     ? tokenFacts.filter((fact) =>
-        targetCode.toUpperCase().includes(String(normalizeHexColor(fact.value || "")).toUpperCase())
+        effectiveTargetCode.toUpperCase().includes(String(normalizeHexColor(fact.value || "")).toUpperCase())
       ).length
     : tokenFacts.length;
   const stateCodeHits = hasTargetCode
-    ? statesInCache.filter((state) => targetCode.toLowerCase().includes(state)).length
+    ? statesInCache.filter((state) => effectiveTargetCode.toLowerCase().includes(state)).length
     : statesInCache.length;
 
   const layoutScore = entryReady ? 100 : 20;
@@ -361,6 +387,7 @@ function run() {
       contract,
       targetCode,
       recipes,
+      options,
     })
   );
 
@@ -409,6 +436,7 @@ function run() {
       contractPath: normalizeSlash(contractPath),
       reportPath: normalizeSlash(reportPath),
       recipesDir: normalizeSlash(recipesDir),
+      filterRemoteFigmaAssets: options.filterRemoteFigmaAssets,
     },
     blocking,
     warnings,

package/scripts/ui-auto-acceptance.js

@@ -105,13 +105,13 @@ function buildReportPaths(options) {
   const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
   return {
     preflight: resolveMaybeAbsolutePath(
-      options.preflightReport || path.join(cacheDir, "reports", "ui-preflight-report.json")
+      options.preflightReport || path.join(cacheDir, "reports", "runtime", "ui-preflight-report.json")
     ),
     audit: resolveMaybeAbsolutePath(
-      options.auditReport || path.join(cacheDir, "reports", "ui-1to1-report.json")
+      options.auditReport || path.join(cacheDir, "reports", "runtime", "ui-1to1-report.json")
     ),
     summary: resolveMaybeAbsolutePath(
-      options.summaryReport || path.join(cacheDir, "reports", "ui-quality-summary.json")
+      options.summaryReport || path.join(cacheDir, "reports", "runtime", "ui-quality-summary.json")
     ),
   };
 }

package/scripts/ui-preflight.js

@@ -10,7 +10,7 @@ const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
 const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
 const DEFAULT_CONTRACT_PATH = "figma-cache/adapters/ui-adapter.contract.json";
-const DEFAULT_REPORT_PATH = "figma-cache/reports/ui-preflight-report.json";
+const DEFAULT_REPORT_PATH = "figma-cache/reports/runtime/ui-preflight-report.json";
 const BLOCKING_EXIT_CODE = 2;
 
 function normalizeSlash(input) {

package/scripts/ui-report-aggregate.js

@@ -8,7 +8,7 @@ const { getUiProfileConfig } = require("./ui-profile");
 
 const ROOT = process.cwd();
 const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
-const DEFAULT_OUTPUT_PATH = "figma-cache/reports/ui-quality-summary.json";
+const DEFAULT_OUTPUT_PATH = "figma-cache/reports/runtime/ui-quality-summary.json";
 
 function resolveMaybeAbsolutePath(input) {
   if (!input) {
@@ -62,10 +62,10 @@ function run() {
   const options = parseArgs(process.argv.slice(2));
   const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
   const preflightPath = resolveMaybeAbsolutePath(
-    options.preflightReport || path.join(cacheDir, "reports", "ui-preflight-report.json")
+    options.preflightReport || path.join(cacheDir, "reports", "runtime", "ui-preflight-report.json")
   );
   const auditPath = resolveMaybeAbsolutePath(
-    options.auditReport || path.join(cacheDir, "reports", "ui-1to1-report.json")
+    options.auditReport || path.join(cacheDir, "reports", "runtime", "ui-1to1-report.json")
   );
   const outputPath = resolveMaybeAbsolutePath(options.output);
   const profileConfig = getUiProfileConfig();