figma-cache-toolchain 2.0.5 → 2.0.7

package/figma-cache/js/raw-derivatives.js

@@ -0,0 +1,85 @@
+"use strict";
+
+/**
+ * MCP raw → raw.json 派生字段的纯函数（无 fs），供 entry-files hydrate 与 CLI merge 脚本复用。
+ */
+
+function mergeLayoutMetricsFromGeometry(raw, geometry) {
+  if (!raw || typeof raw !== "object") {
+    return raw;
+  }
+  if (!geometry || typeof geometry !== "object" || !Array.isArray(geometry.metrics)) {
+    return raw;
+  }
+  if (!geometry.metrics.length) {
+    return raw;
+  }
+  const existing = Array.isArray(raw.layoutMetrics) ? raw.layoutMetrics : [];
+  const byId = new Map(
+    existing.map((m) => [String(m && m.id ? m.id : "").trim(), m]).filter(([k]) => k)
+  );
+  geometry.metrics.forEach((m) => {
+    const id = String(m && m.id ? m.id : "").trim();
+    if (!id) return;
+    byId.set(id, m);
+  });
+  raw.layoutMetrics = Array.from(byId.values()).sort((a, b) =>
+    String(a.id).localeCompare(String(b.id))
+  );
+  return raw;
+}
+
+function buildEvidenceSummary(input) {
+  const {
+    designContextText = "",
+    metadataText = "",
+    variableDefs = null,
+    nodeId = "",
+    geometryFilePresent = false,
+    iconMetricsCount = 0,
+    layoutMetricsCount = 0,
+  } = input || {};
+
+  const dc = String(designContextText);
+  const meta = String(metadataText);
+  const designContextBytes = Buffer.byteLength(dc, "utf8");
+  const metadataBytes = Buffer.byteLength(meta, "utf8");
+  const dataNodeIdRefs = (dc.match(/data-node-id="/g) || []).length;
+  const scopeNodeId = String(nodeId || "").trim();
+  const dataNodeIdContainsScope =
+    scopeNodeId && dc.length ? dc.includes(`data-node-id="${scopeNodeId}"`) : null;
+  const designContextImgConstDefinitions = (
+    dc.match(/\bconst\s+img[A-Za-z0-9_]*\s*=\s*"https:\/\/www\.figma\.com\/api\/mcp\/asset\//g) || []
+  ).length;
+  const imgTagOccurrences = (dc.match(/<img\b/gi) || []).length;
+  const figmaAssetUrlOccurrences = (dc.match(/https:\/\/www\.figma\.com\/api\/mcp\/asset\//g) || []).length;
+  const approximateHexColorLiterals = (
+    dc.match(/#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g) || []
+  ).length;
+  const variableDefKeys =
+    variableDefs && typeof variableDefs === "object" && !Array.isArray(variableDefs)
+      ? Object.keys(variableDefs).length
+      : 0;
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    designContextBytes,
+    metadataBytes,
+    dataNodeIdRefs,
+    dataNodeIdContainsScope,
+    designContextImgConstDefinitions,
+    imgTagOccurrences,
+    figmaAssetUrlOccurrences,
+    approximateHexColorLiterals,
+    variableDefKeys,
+    geometryFilePresent,
+    iconMetricsCount,
+    layoutMetricsCount,
+  };
+}
+
+module.exports = {
+  mergeLayoutMetricsFromGeometry,
+  buildEvidenceSummary,
+};

package/figma-cache/js/related-cache-keys.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * Derive peer cacheKeys from index.json flows: undirected edges whose type starts with "related"
+ * (e.g. related_auto, related_confirmed).
+ */
+
+function itemCacheKeyFromItem(item) {
+  if (!item || !item.fileKey) {
+    return "";
+  }
+  if (item.scope === "file" || !item.nodeId) {
+    return `${item.fileKey}#__FILE__`;
+  }
+  return `${item.fileKey}#${item.nodeId}`;
+}
+
+function collectRelatedNeighborMap(index) {
+  const flows = index && typeof index.flows === "object" ? index.flows : {};
+  /** @type {Map<string, Set<string>>} */
+  const neighbors = new Map();
+  function link(a, b) {
+    const x = String(a || "").trim();
+    const y = String(b || "").trim();
+    if (!x || !y || x === y) return;
+    if (!neighbors.has(x)) neighbors.set(x, new Set());
+    if (!neighbors.has(y)) neighbors.set(y, new Set());
+    neighbors.get(x).add(y);
+    neighbors.get(y).add(x);
+  }
+  Object.values(flows).forEach((flow) => {
+    if (!flow || !Array.isArray(flow.edges)) return;
+    flow.edges.forEach((edge) => {
+      if (!edge || !edge.from || !edge.to) return;
+      const t = String(edge.type || "").trim().toLowerCase();
+      if (!t.startsWith("related")) return;
+      link(edge.from, edge.to);
+    });
+  });
+  return neighbors;
+}
+
+function getRelatedCacheKeysFromIndex(cacheKey, index) {
+  const key = String(cacheKey || "").trim();
+  if (!key) return [];
+  const neighbors = collectRelatedNeighborMap(index);
+  const set = neighbors.get(key);
+  if (!set || !set.size) return [];
+  return Array.from(set).sort((a, b) => a.localeCompare(b));
+}
+
+module.exports = {
+  itemCacheKeyFromItem,
+  getRelatedCacheKeysFromIndex,
+  collectRelatedNeighborMap,
+};

package/figma-cache/js/ui-facts-normalizer.js

@@ -67,31 +67,42 @@ function isPlaceholderText(input) {
 function extractSpecFacts(specText) {
   const textFacts = [];
   const tokenFacts = [];
-  const tokenRegex = /-\s*([^:\n]+?)\s*:\s*(#[0-9a-fA-F]{3,8})/g;
-  String(specText || "")
-    .split(/\r?\n/)
-    .forEach((line) => {
-      const t = line.trim();
-      if (!t.startsWith("-")) {
-        return;
-      }
-      let hasToken = false;
-      let match = null;
-      while ((match = tokenRegex.exec(t))) {
-        hasToken = true;
+  /** 同一行内可多次出现 name:#hex，每行重置 lastIndex，避免 /g 状态串行污染 */
+  const tokenPairRe = /-\s*([^:\n]+?)\s*:\s*(#[0-9a-fA-F]{3,8})/g;
+  const lines = String(specText || "").split(/\r?\n/);
+  let inTextSection = false;
+  let inTokenSection = false;
+
+  lines.forEach((rawLine) => {
+    const t = rawLine.trim();
+    if (/^##\s+/i.test(t)) {
+      inTextSection = /(Text|文案)/i.test(t);
+      inTokenSection = /(Tokens|Token|变量|样式)/i.test(t);
+      return;
+    }
+    if (!t.startsWith("-")) {
+      return;
+    }
+    tokenPairRe.lastIndex = 0;
+    let hasTokenPair = false;
+    let match = null;
+    while ((match = tokenPairRe.exec(t)) !== null) {
+      hasTokenPair = true;
+      if (inTokenSection) {
         tokenFacts.push({
           name: String(match[1] || "").trim(),
           value: String(match[2] || "").trim(),
           source: "spec.md",
         });
       }
-      if (!hasToken) {
-        const text = t.replace(/^-+\s*/, "").trim();
-        if (text) {
-          textFacts.push(text);
-        }
+    }
+    if (inTextSection && !hasTokenPair) {
+      const text = t.replace(/^-+\s*/, "").trim();
+      if (text) {
+        textFacts.push(text);
       }
-    });
+    }
+  });
   return {
     textFacts: dedupeStrings(textFacts),
     tokenFacts: dedupeTokens(tokenFacts),

package/figma-cache/js/validate-cli.js

@@ -8,12 +8,77 @@ function isTodoLike(value) {
 function hasTruncatedMarker(value) {
   const text = String(value || "");
   return (
+    /\btruncated\b/i.test(text) ||
     /omitted\s+for\s+brevity/i.test(text) ||
     /省略|截断|已截短|摘要版/i.test(text) ||
+    /证据占位|占位证据|evidence\s+placeholder|used\s+as\s+evidence/i.test(text) ||
+    /omitted\s+here/i.test(text) ||
+    /for\s+brevity\s+in\s+this\s+workspace/i.test(text) ||
+    /\(\s*truncated\s*\)/i.test(text) ||
     /\.\.\.\s*(MCP|get_design_context|response|回包|原始响应)/i.test(text)
   );
 }
 
+function validateDesignContextNotSkeleton(cacheKey, fileAbs, content, errors, deps) {
+  const { normalizeSlash } = deps;
+  const minBytesRaw = Number(process.env.FIGMA_MCP_MIN_DESIGN_CONTEXT_BYTES);
+  const minBytes = Number.isFinite(minBytesRaw) && minBytesRaw >= 0 ? Math.floor(minBytesRaw) : 1500;
+  const bytes = Buffer.byteLength(String(content || ""), "utf8");
+
+  // Hard-fail if it's too small to be a real get_design_context payload.
+  // This catches "placeholder evidence" where only a wrapper/div exists.
+  if (minBytes > 0 && bytes < minBytes) {
+    errors.push(
+      `${cacheKey}: get_design_context 原始文件疑似过小（${bytes}B < ${minBytes}B），禁止省略/占位，必须直存完整回包 ${normalizeSlash(
+        fileAbs
+      )}`
+    );
+    return;
+  }
+
+  // Additional structural sanity checks for common placeholder patterns.
+  const text = String(content || "");
+  const nodeIdMatch = cacheKey.split("#")[1] || "";
+  if (nodeIdMatch && !text.includes(`data-node-id="${nodeIdMatch}"`)) {
+    errors.push(
+      `${cacheKey}: get_design_context 原始文件缺少目标 data-node-id="${nodeIdMatch}"（疑似非对应节点回包或被截断） ${normalizeSlash(
+        fileAbs
+      )}`
+    );
+  }
+
+  const minNodeRefsRaw = Number(process.env.FIGMA_MCP_MIN_DESIGN_CONTEXT_NODE_REFS);
+  const minNodeRefs =
+    Number.isFinite(minNodeRefsRaw) && minNodeRefsRaw >= 0 ? Math.floor(minNodeRefsRaw) : 6;
+  if (minNodeRefs > 0) {
+    const nodeRefs = (text.match(/data-node-id="/g) || []).length;
+    if (nodeRefs < minNodeRefs) {
+      errors.push(
+        `${cacheKey}: get_design_context data-node-id 引用数量过少（${nodeRefs} < ${minNodeRefs}），疑似省略/骨架模式 ${normalizeSlash(
+          fileAbs
+        )}`
+      );
+    }
+  }
+
+  const requireAssetsFlag = String(process.env.FIGMA_MCP_REQUIRE_DESIGN_CONTEXT_ASSETS || "")
+    .trim()
+    .toLowerCase();
+  const requireAssets = requireAssetsFlag ? requireAssetsFlag !== "0" && requireAssetsFlag !== "false" : true;
+  if (requireAssets) {
+    const hasAssetConstants =
+      /\bconst\s+img[A-Za-z0-9_]*\s*=\s*"https:\/\/www\.figma\.com\/api\/mcp\/asset\//.test(text);
+    const hasImgUsage = /<img\b/i.test(text);
+    if (!hasAssetConstants || !hasImgUsage) {
+      errors.push(
+        `${cacheKey}: get_design_context 缺少资产常量或 <img> 使用（疑似被省略/占位）。如节点确实无资产，可设 FIGMA_MCP_REQUIRE_DESIGN_CONTEXT_ASSETS=0 关闭该检查 ${normalizeSlash(
+          fileAbs
+        )}`
+      );
+    }
+  }
+}
+
 function getManifestFilesMap(cacheKey, item, errors, deps) {
   const { resolveMaybeAbsolutePath, safeReadJson, normalizeSlash, path, fs } = deps;
   if (!item || !item.paths || !item.paths.meta) {
@@ -64,6 +129,9 @@ function getManifestFilesMap(cacheKey, item, errors, deps) {
       );
       return;
     }
+    if (toolName === "get_design_context") {
+      validateDesignContextNotSkeleton(cacheKey, fileAbs, content, errors, deps);
+    }
     if (fileHashes && fileSizes) {
       const expectedHash = String(fileHashes[toolName] || "").trim().toLowerCase();
       const expectedSize = Number(fileSizes[toolName]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "figma-cache-toolchain",
-    "version": "2.0.5",
+    "version": "2.0.7",
     "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
     "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
     "keywords": [
@@ -28,6 +28,8 @@
         "figma-cache/js/index-store.js",
         "figma-cache/js/cursor-bootstrap-cli.js",
         "figma-cache/js/entry-files.js",
+        "figma-cache/js/raw-derivatives.js",
+        "figma-cache/js/related-cache-keys.js",
         "figma-cache/js/backfill-cli.js",
         "figma-cache/js/project-config.js",
         "figma-cache/js/contract-check-cli.js",
@@ -39,15 +41,24 @@
         "scripts/ui-report-aggregate.js",
         "scripts/ui-auto-acceptance.js",
         "scripts/cross-project-e2e.js",
+        "scripts/forbidden-markup-check.cjs",
+        "scripts/generate-icon-insets.cjs",
+        "scripts/generate-icon-insets-from-batch.cjs",
+        "scripts/auto-link-related-from-batch.cjs",
+        "scripts/import-mcp-raw-evidence.cjs",
+        "scripts/merge-figma-geometry-metrics.cjs",
+        "scripts/apply-auto-related-suggestions.cjs",
+        "scripts/archive-artifacts-from-batch.cjs",
         "figma-cache/adapters/recipes/*.json",
         "figma-cache/docs/*.md",
-        "figma-cache/docs/ui-1to1-report.schema.json"
+        "figma-cache/docs/ui-1to1-report.schema.json",
+        "figma-cache/docs/raw-json-extensions.schema.json"
     ],
     "publishConfig": {
         "registry": "https://registry.npmjs.org/"
     },
     "scripts": {
-        "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/smoke.js",
+        "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/raw-derivatives.test.js && node tests/related-cache-keys.test.js && node tests/smoke.js",
         "prepack": "npm run cursor:shadow:check && npm run docs:encoding:check && node bin/figma-cache.js validate",
         "figma:cache:normalize": "node bin/figma-cache.js normalize",
         "figma:cache:get": "node bin/figma-cache.js get",
@@ -78,6 +89,8 @@
         "figma:ui:gate": "npm run figma:ui:preflight && npm run figma:ui:audit -- --min-score=85 && npm run figma:cache:validate && npm run cursor:shadow:check && npm test",
         "figma:ui:gate:pr": "npm run figma:ui:preflight && npm run figma:cache:validate",
         "figma:ui:gate:main": "npm run figma:ui:preflight && npm run figma:ui:audit -- --min-score=90 && npm run figma:ui:report:aggregate && npm run figma:cache:validate && npm run cursor:shadow:check && npm test",
+        "figma:cache:merge-geometry": "node scripts/merge-figma-geometry-metrics.cjs",
+        "figma:cache:enrich": "node bin/figma-cache.js enrich",
         "figma:cache:contract:check": "node bin/figma-cache.js contract-check",
         "preflight:shell": "node scripts/preflight-shell.js --warn",
         "preflight:shell:strict": "node scripts/preflight-shell.js --strict"

package/scripts/apply-auto-related-suggestions.cjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Apply auto-link suggestions into figma-cache/index.json flows.
+ *
+ * This is designed to be used after:
+ *   auto-link-related-from-batch.cjs -> auto-related-suggestions.json
+ *
+ * Usage:
+ *   node scripts/apply-auto-related-suggestions.cjs --suggestions=<path> --pairs=<from->to,from->to>
+ *
+ * Options:
+ *   --index=<path>          (default: figma-cache/index.json)
+ *   --flow=<flowId>         (default: suggestions.flowId || "auto-related")
+ *   --type=<edgeType>       (default: related_confirmed)
+ *   --pairs=<csv>           required. Each pair: <fromCacheKey>-><toCacheKey>
+ *   --dry-run               do not write index
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = process.cwd();
+
+function safeReadJson(abs) {
+  try {
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(abs, value) {
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+function normalizeCacheKey(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  const parts = value.split("#");
+  if (parts.length !== 2) return value;
+  return `${parts[0]}#${normalizeNodeId(parts[1])}`;
+}
+
+function parseArgs(argv) {
+  const out = {
+    suggestions: "",
+    index: path.join(ROOT, "figma-cache", "index.json"),
+    flowId: "",
+    type: "related_confirmed",
+    pairs: [],
+    dryRun: false,
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--suggestions=")) out.suggestions = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--index=")) out.index = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--flow=")) out.flowId = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--type=")) out.type = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--pairs=")) {
+      out.pairs = arg
+        .split("=").slice(1).join("=")
+        .split(",")
+        .map((s) => String(s || "").trim())
+        .filter(Boolean);
+    }
+    if (arg === "--dry-run") out.dryRun = true;
+  });
+  return out;
+}
+
+function ensureFlow(index, flowId) {
+  index.flows = index.flows || {};
+  if (!index.flows[flowId]) {
+    index.flows[flowId] = {
+      id: flowId,
+      title: flowId,
+      description: "Manually confirmed auto-link suggestions",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      nodes: [],
+      edges: [],
+      assumptions: [],
+      openQuestions: [],
+    };
+  }
+  return index.flows[flowId];
+}
+
+function addNode(flow, cacheKey) {
+  flow.nodes = flow.nodes || [];
+  if (!flow.nodes.includes(cacheKey)) flow.nodes.push(cacheKey);
+}
+
+function hasEdge(flow, from, to, type) {
+  const edges = Array.isArray(flow.edges) ? flow.edges : [];
+  return edges.some((e) => e && e.from === from && e.to === to && e.type === type);
+}
+
+function addEdge(flow, from, to, type, note) {
+  if (hasEdge(flow, from, to, type)) return false;
+  flow.edges = flow.edges || [];
+  flow.edges.push({
+    id: `${from}->${to}:${type}:${Date.now()}`,
+    from,
+    to,
+    type,
+    note: note || "",
+    createdAt: new Date().toISOString(),
+  });
+  return true;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.suggestions || !args.pairs.length) {
+    console.error(
+      "Usage: node scripts/apply-auto-related-suggestions.cjs --suggestions=<path> --pairs=<from->to,from->to> [--flow=...] [--type=...] [--dry-run]"
+    );
+    process.exit(2);
+  }
+
+  const suggestionsAbs = path.isAbsolute(args.suggestions) ? args.suggestions : path.join(ROOT, args.suggestions);
+  const indexAbs = path.isAbsolute(args.index) ? args.index : path.join(ROOT, args.index);
+  const s = safeReadJson(suggestionsAbs);
+  const index = safeReadJson(indexAbs);
+  if (!s || typeof s !== "object") {
+    console.error(`[apply-auto-related-suggestions] invalid suggestions json: ${suggestionsAbs}`);
+    process.exit(2);
+  }
+  if (!index || typeof index !== "object") {
+    console.error(`[apply-auto-related-suggestions] invalid index json: ${indexAbs}`);
+    process.exit(2);
+  }
+
+  const flowId = String(args.flowId || s.flowId || "auto-related").trim();
+  const flow = ensureFlow(index, flowId);
+
+  const allowedPairs = new Set(
+    (Array.isArray(s.suggestions) ? s.suggestions : []).map((x) => `${x.from}->${x.to}`)
+  );
+
+  let applied = 0;
+  args.pairs.forEach((pairRaw) => {
+    const pair = String(pairRaw || "").trim();
+    const m = pair.split("->");
+    if (m.length !== 2) return;
+    const from = normalizeCacheKey(m[0]);
+    const to = normalizeCacheKey(m[1]);
+    if (!from || !to) return;
+
+    // Safety: only apply pairs that are actually in the suggestions list.
+    if (!allowedPairs.has(`${from}->${to}`)) {
+      console.error(`[apply-auto-related-suggestions] skipped (not suggested): ${from}->${to}`);
+      return;
+    }
+
+    addNode(flow, from);
+    addNode(flow, to);
+    if (addEdge(flow, from, to, args.type, "confirmed from suggestions")) applied += 1;
+  });
+
+  flow.updatedAt = new Date().toISOString();
+  index.updatedAt = new Date().toISOString();
+
+  if (!args.dryRun) writeJson(indexAbs, index);
+  console.log(
+    `[apply-auto-related-suggestions] ok applied=${applied} flow=${flowId} dryRun=${args.dryRun ? "1" : "0"}`
+  );
+}
+
+main();
+

package/scripts/archive-artifacts-from-batch.cjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Archive per-case figma-cache evidence into a dedicated artifacts root
+ * (defaults to <projectRoot>/figma-cache/artifacts/by-target/), to avoid
+ * polluting source directories.
+ *
+ * Layout (default):
+ *   <outRoot>/<targetRelDir>/figma-cache/<cacheKeySanitized>/
+ *     - meta.json
+ *     - raw.json
+ *     - spec.md
+ *     - state-map.md
+ *     - mcp-raw/...
+ *
+ * And also copies shared runtime reports into:
+ *   <outRoot>/<targetRelDir>/reports/runtime/
+ *
+ * Usage:
+ *   node scripts/archive-artifacts-from-batch.cjs --batch=./figma-e2e-batch.json
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = process.cwd();
+
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+function cacheKeyFromItem(item) {
+  const fileKey = String(item && item.fileKey ? item.fileKey : "").trim();
+  const nodeId = String(item && item.nodeId ? item.nodeId : "").trim();
+  if (!fileKey || !nodeId) return "";
+  return `${fileKey}#${normalizeNodeId(nodeId)}`;
+}
+
+function resolveTargetAbs(rawTarget) {
+  const trimmed = String(rawTarget || "").trim();
+  if (!trimmed) return "";
+  return path.isAbsolute(trimmed) ? path.normalize(trimmed) : path.join(ROOT, trimmed);
+}
+
+function sanitizeForPath(input) {
+  return String(input || "")
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/g, "_")
+    .replace(/\s+/g, "_");
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyFileIfExists(src, dst) {
+  if (!fs.existsSync(src)) return false;
+  ensureDir(path.dirname(dst));
+  fs.copyFileSync(src, dst);
+  return true;
+}
+
+function copyDirIfExists(srcDir, dstDir) {
+  if (!fs.existsSync(srcDir)) return false;
+  ensureDir(dstDir);
+  fs.cpSync(srcDir, dstDir, { recursive: true });
+  return true;
+}
+
+function parseArgs(argv) {
+  const out = {
+    batch: path.join(ROOT, "figma-e2e-batch.json"),
+    cacheRoot: path.join(ROOT, "figma-cache"),
+    reportsRuntime: path.join(ROOT, "figma-cache", "reports", "runtime"),
+    outRoot:
+      process.env.FIGMA_UI_ARTIFACTS_ROOT ||
+      path.join(ROOT, "figma-cache", "artifacts", "by-target"),
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--batch=")) out.batch = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--cache-root=")) out.cacheRoot = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--out-root=")) out.outRoot = arg.split("=").slice(1).join("=").trim();
+  });
+  return out;
+}
+
+function nodeDirFromCacheKey(cacheRootAbs, cacheKey) {
+  const [fileKey, nodeId] = String(cacheKey).split("#");
+  const safeNodeDir = String(nodeId || "").replace(/:/g, "-");
+  return path.join(cacheRootAbs, "files", fileKey, "nodes", safeNodeDir);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const batchAbs = path.isAbsolute(args.batch) ? args.batch : path.join(ROOT, args.batch);
+  const cacheRootAbs = path.isAbsolute(args.cacheRoot) ? args.cacheRoot : path.join(ROOT, args.cacheRoot);
+  const reportsRuntimeAbs = path.isAbsolute(args.reportsRuntime) ? args.reportsRuntime : path.join(ROOT, args.reportsRuntime);
+
+  if (!fs.existsSync(batchAbs)) {
+    console.error(`[archive-artifacts-from-batch] batch not found: ${batchAbs}`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(cacheRootAbs)) {
+    console.error(`[archive-artifacts-from-batch] cache root not found: ${cacheRootAbs}`);
+    process.exit(2);
+  }
+
+  const payload = JSON.parse(fs.readFileSync(batchAbs, "utf8"));
+  if (!Array.isArray(payload) || payload.length === 0) {
+    console.error("[archive-artifacts-from-batch] batch must be a non-empty array");
+    process.exit(2);
+  }
+
+  let copiedCases = 0;
+  payload.forEach((item, idx) => {
+    const cacheKey = String(item && (item.cacheKey || cacheKeyFromItem(item)) || "").trim();
+    const targetAbs = resolveTargetAbs(item && item.target);
+    if (!cacheKey) {
+      console.error(`[archive-artifacts-from-batch] case[${idx}] missing cacheKey or (fileKey+nodeId)`);
+      process.exit(2);
+    }
+    if (!targetAbs) {
+      console.error(`[archive-artifacts-from-batch] case[${idx}] missing target`);
+      process.exit(2);
+    }
+
+    const outRootAbs = path.isAbsolute(args.outRoot) ? args.outRoot : path.join(ROOT, args.outRoot);
+    const targetRelDir = sanitizeForPath(
+      path.relative(ROOT, path.dirname(targetAbs)).replace(/\\/g, "/")
+    );
+    const artifactsRoot = path.join(outRootAbs, targetRelDir);
+    const caseDir = path.join(artifactsRoot, "figma-cache", sanitizeForPath(cacheKey));
+
+    const nodeDir = nodeDirFromCacheKey(cacheRootAbs, cacheKey);
+    if (!fs.existsSync(nodeDir)) {
+      console.error(`[archive-artifacts-from-batch] node dir not found for ${cacheKey}: ${nodeDir}`);
+      process.exit(2);
+    }
+
+    copyFileIfExists(path.join(nodeDir, "meta.json"), path.join(caseDir, "meta.json"));
+    copyFileIfExists(path.join(nodeDir, "raw.json"), path.join(caseDir, "raw.json"));
+    copyFileIfExists(path.join(nodeDir, "spec.md"), path.join(caseDir, "spec.md"));
+    copyFileIfExists(path.join(nodeDir, "state-map.md"), path.join(caseDir, "state-map.md"));
+    copyDirIfExists(path.join(nodeDir, "mcp-raw"), path.join(caseDir, "mcp-raw"));
+
+    // Shared runtime reports snapshot
+    if (fs.existsSync(reportsRuntimeAbs)) {
+      copyDirIfExists(reportsRuntimeAbs, path.join(artifactsRoot, "reports", "runtime"));
+    }
+
+    copiedCases += 1;
+  });
+
+  console.log(`[archive-artifacts-from-batch] ok (${copiedCases} cases)`);
+}
+
+main();
+