figma-cache-toolchain 1.4.3 → 1.4.4

package/figma-cache/figma-cache.js

@@ -4,10 +4,49 @@ const fs = require("fs");
 const path = require("path");
 const { createRequire } = require("module");
 const { URL } = require("url");
+const { handleFlowCommand } = require("./js/flow-cli");
+const { validateMcpRawEvidence, validateIndex } = require("./js/validate-cli");
+const { buildBudgetReport } = require("./js/budget-cli");
+const { createIndexStore } = require("./js/index-store");
+const { copyCursorBootstrap } = require("./js/cursor-bootstrap-cli");
+const { createEntryFilesService } = require("./js/entry-files");
+const { backfillFromIterations } = require("./js/backfill-cli");
+const { createUpsertService } = require("./js/upsert-core");
+const { createProjectConfigService } = require("./js/project-config");
 
 const ROOT = process.cwd();
 const NORMALIZATION_VERSION = 1;
 const SCHEMA_VERSION = 2;
+const DEFAULT_COMPLETENESS = Object.freeze([
+  "layout",
+  "text",
+  "tokens",
+  "interactions",
+  "states",
+  "accessibility",
+]);
+const COMPLETENESS_ALL_DIMENSIONS = Object.freeze([
+  "layout",
+  "text",
+  "tokens",
+  "interactions",
+  "states",
+  "accessibility",
+  "flow",
+  "assets",
+]);
+const COMPLETENESS_TOOL_REQUIREMENTS = Object.freeze({
+  layout: Object.freeze([
+    Object.freeze(["get_metadata", "get_design_context"]),
+  ]),
+  text: Object.freeze([Object.freeze(["get_design_context"])]),
+  tokens: Object.freeze([Object.freeze(["get_variable_defs"])]),
+  interactions: Object.freeze([Object.freeze(["get_design_context"])]),
+  states: Object.freeze([Object.freeze(["get_design_context"])]),
+  accessibility: Object.freeze([Object.freeze(["get_design_context"])]),
+  flow: Object.freeze([Object.freeze(["get_design_context"])]),
+  assets: Object.freeze([Object.freeze(["get_design_context"])]),
+});
 
 function parsePositiveInt(input, fallback) {
   const n = Number(input);
@@ -40,15 +79,15 @@ const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
 const DEFAULT_FLOW_ID = process.env.FIGMA_DEFAULT_FLOW || "";
 const DEFAULT_STALE_DAYS = parsePositiveInt(
   process.env.FIGMA_CACHE_STALE_DAYS,
-  14
+  14,
 );
 
 const CACHE_DIR = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
-/** 与 `figma-cache/figma-cache.js` 同级的 `cursor-bootstrap/`（随 npm 包分发） */
+/** 涓?`figma-cache/figma-cache.js` 鍚岀骇鐨?`cursor-bootstrap/`锛堥殢 npm 鍖呭垎鍙戯級 */
 const CURSOR_BOOTSTRAP_DIR = path.join(__dirname, "..", "cursor-bootstrap");
 const ITERATIONS_DIR = resolveMaybeAbsolutePath(ITERATIONS_DIR_INPUT);
 
-/** 当前安装包在 package.json 中的 name（用于写入 AGENT-SETUP-PROMPT.md） */
+/** 褰撳墠瀹夎鍖呭湪 package.json 涓殑 name锛堢敤浜庡啓鍏?AGENT-SETUP-PROMPT.md锛?*/
 function readSelfNpmPackageName() {
   try {
     const pkgPath = path.join(__dirname, "..", "package.json");
@@ -64,89 +103,45 @@ const INDEX_PATH = path.isAbsolute(INDEX_FILE_NAME)
   : path.join(CACHE_DIR, INDEX_FILE_NAME);
 const CACHE_BASE_FOR_STORAGE = toProjectRelativeOrAbsolute(CACHE_DIR);
 
-/** @type {object | null} null = not loaded yet; after load always an object (possibly empty) */
-let memoProjectConfig = null;
-/** @type {string | null} */
-let memoProjectConfigPath = null;
-
-/**
- * Load optional project-level config from (first match):
- * 1) FIGMA_CACHE_PROJECT_CONFIG (absolute or relative to ROOT)
- * 2) figma-cache.config.js
- * 3) .figmacacherc.js
- * Core stays agnostic: only reads `hooks` and other neutral keys.
- */
-function loadProjectConfig() {
-  if (memoProjectConfig) {
-    return memoProjectConfig;
-  }
-  const candidates = [];
-  if (process.env.FIGMA_CACHE_PROJECT_CONFIG) {
-    candidates.push(resolveMaybeAbsolutePath(process.env.FIGMA_CACHE_PROJECT_CONFIG));
-  }
-  candidates.push(path.join(ROOT, "figma-cache.config.js"));
-  candidates.push(path.join(ROOT, ".figmacacherc.js"));
-
-  const requireFromRoot = createRequire(path.join(ROOT, "package.json"));
-
-  for (const absPath of candidates) {
-    if (!fs.existsSync(absPath)) {
-      continue;
-    }
-    try {
-      const mod = requireFromRoot(absPath);
-      const cfg = mod && mod.default ? mod.default : mod;
-      memoProjectConfig = cfg && typeof cfg === "object" ? cfg : {};
-      memoProjectConfigPath = absPath;
-      return memoProjectConfig;
-    } catch (err) {
-      console.error(`[figma-cache] project config failed (${absPath}): ${err.message}`);
-    }
-  }
-
-  memoProjectConfig = {};
-  memoProjectConfigPath = null;
-  return memoProjectConfig;
-}
-
-/**
- * After generic entry files exist, run optional hooks.postEnsure from project config.
- * Never throws; never changes process exit code of the caller.
- * @param {string} cacheKey
- * @param {object} item index item
- */
-function runPostEnsureHook(cacheKey, item) {
-  if (!item || !item.paths) {
-    return;
-  }
-  const cfg = loadProjectConfig();
-  const hooks = cfg && cfg.hooks;
-  if (!hooks || typeof hooks.postEnsure !== "function") {
-    return;
-  }
-  const ctx = {
-    cacheKey,
-    fileKey: item.fileKey,
-    nodeId: item.nodeId == null ? null : item.nodeId,
-    scope: item.scope,
-    url: item.url == null ? "" : String(item.url),
-    source: item.source == null ? "" : String(item.source),
-    syncedAt: item.syncedAt == null ? "" : String(item.syncedAt),
-    completeness: Array.isArray(item.completeness) ? item.completeness : [],
-    paths: {
-      raw: item.paths.raw,
-      spec: item.paths.spec,
-      meta: item.paths.meta,
-      stateMap: item.paths.stateMap,
-    },
-    root: ROOT,
-  };
-  try {
-    hooks.postEnsure(ctx);
-  } catch (err) {
-    console.error(`[figma-cache] hooks.postEnsure: ${err.message}`);
-  }
-}
+const indexStore = createIndexStore({
+  fs,
+  CACHE_DIR,
+  INDEX_PATH,
+  SCHEMA_VERSION,
+  NORMALIZATION_VERSION,
+});
+const {
+  ensureCacheDir,
+  buildEmptyIndex,
+  normalizeIndexShape,
+  readIndex,
+  writeIndex,
+  getItem,
+} = indexStore;
+
+const projectConfigService = createProjectConfigService({
+  fs,
+  path,
+  ROOT,
+  createRequire,
+  resolveMaybeAbsolutePath,
+  normalizeSlash,
+});
+const { loadProjectConfig, runPostEnsureHook, getProjectConfigPath } =
+  projectConfigService;
+
+const upsertService = createUpsertService({
+  URL,
+  NORMALIZATION_VERSION,
+  CACHE_BASE_FOR_STORAGE,
+  DEFAULT_COMPLETENESS,
+  normalizeCompletenessList,
+  normalizeIndexShape,
+  readIndex,
+  getItem,
+  writeIndex,
+});
+const { normalizeFigmaUrl, previewUpsertByUrl, upsertByUrl } = upsertService;
 
 function resolveFlowIdFromArgs(rest) {
   const flowArg = rest.find((x) => x.startsWith("--flow="));
@@ -159,479 +154,47 @@ function resolveFlowIdFromArgs(rest) {
   return "";
 }
 
-function ensureCacheDir() {
-  if (!fs.existsSync(CACHE_DIR)) {
-    fs.mkdirSync(CACHE_DIR, { recursive: true });
-  }
-}
-
-function readIndex() {
-  ensureCacheDir();
-  if (!fs.existsSync(INDEX_PATH)) {
-    return buildEmptyIndex();
-  }
-  const raw = fs.readFileSync(INDEX_PATH, "utf8");
-  return normalizeIndexShape(JSON.parse(raw));
-}
-
-function buildEmptyIndex() {
-  return {
-    schemaVersion: SCHEMA_VERSION,
-    version: 1,
-    normalizationVersion: NORMALIZATION_VERSION,
-    updatedAt: null,
-    flows: {},
-    items: {},
-  };
-}
-
-function normalizeIndexShape(index) {
-  if (!index || typeof index !== "object") {
-    return buildEmptyIndex();
-  }
-  if (!index.schemaVersion) {
-    index.schemaVersion = SCHEMA_VERSION;
-  }
-  if (!index.flows || typeof index.flows !== "object") {
-    index.flows = {};
-  }
-  if (!index.items || typeof index.items !== "object") {
-    index.items = {};
-  }
-  if (!index.version) {
-    index.version = 1;
-  }
-  if (!index.normalizationVersion) {
-    index.normalizationVersion = NORMALIZATION_VERSION;
-  }
-  return index;
-}
-
-function writeIndex(index) {
-  const normalized = normalizeIndexShape(index);
-  normalized.version = 1;
-  normalized.schemaVersion = SCHEMA_VERSION;
-  normalized.normalizationVersion = NORMALIZATION_VERSION;
-  normalized.updatedAt = new Date().toISOString();
-  fs.writeFileSync(INDEX_PATH, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
-}
-
-function sanitizeNodeId(nodeId) {
-  return String(nodeId).replace(/:/g, "-");
-}
-
-function normalizeNodeIdValue(nodeId) {
-  const raw = String(nodeId).trim();
-  const dashPattern = /^(\d+)-(\d+)$/;
-  if (dashPattern.test(raw)) {
-    return raw.replace(dashPattern, "$1:$2");
-  }
-  return raw;
-}
-
-function normalizeFigmaUrl(inputUrl) {
-  let parsed;
-  try {
-    parsed = new URL(inputUrl);
-  } catch (error) {
-    throw new Error(`非法 URL: ${inputUrl}`);
-  }
-
-  const hostOk = /(^|\.)figma\.com$/i.test(parsed.hostname);
-  if (!hostOk) {
-    throw new Error(`非 Figma 域名: ${parsed.hostname}`);
-  }
-
-  const parts = parsed.pathname.split("/").filter(Boolean);
-  const routeType = parts[0];
-  const fileKey = parts[1];
-  if (!["file", "design"].includes(routeType) || !fileKey) {
-    throw new Error(`无法从路径提取 fileKey: ${parsed.pathname}`);
-  }
-
-  const nodeIdRaw = parsed.searchParams.get("node-id");
-  const nodeId = nodeIdRaw ? normalizeNodeIdValue(decodeURIComponent(nodeIdRaw)) : null;
-  const isNodeScope = !!nodeId;
-  const scope = isNodeScope ? "node" : "file";
-  const cacheKey = isNodeScope ? `${fileKey}#${nodeId}` : `${fileKey}#__FILE__`;
-
-  return {
-    fileKey,
-    nodeId,
-    scope,
-    cacheKey,
-    normalizedUrl: isNodeScope
-      ? `https://www.figma.com/file/${fileKey}/?node-id=${encodeURIComponent(nodeId)}`
-      : `https://www.figma.com/file/${fileKey}/`,
-    originalUrl: inputUrl,
-    normalizationVersion: NORMALIZATION_VERSION,
-  };
-}
-
-function buildPaths(normalized) {
-  if (normalized.scope === "file") {
-    return {
-      meta: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/meta.json`,
-      spec: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/spec.md`,
-      stateMap: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/state-map.md`,
-      raw: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/raw.json`,
-    };
-  }
-
-  const safeNode = sanitizeNodeId(normalized.nodeId);
-  return {
-    meta: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/meta.json`,
-    spec: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/spec.md`,
-    stateMap: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/state-map.md`,
-    raw: `${CACHE_BASE_FOR_STORAGE}/files/${normalized.fileKey}/nodes/${safeNode}/raw.json`,
-  };
-}
-
-function getItem(index, cacheKey) {
-  const normalized = normalizeIndexShape(index);
-  return normalized.items && normalized.items[cacheKey] ? normalized.items[cacheKey] : null;
-}
-
-function upsertByUrl(inputUrl, extra) {
-  const normalized = normalizeFigmaUrl(inputUrl);
-  const index = normalizeIndexShape(readIndex());
-  const oldItem = getItem(index, normalized.cacheKey);
-  const mergedUrls = Array.from(
-    new Set([...(oldItem ? oldItem.originalUrls || [] : []), normalized.originalUrl])
-  );
-  const now = new Date().toISOString();
-
-  const item = {
-    fileKey: normalized.fileKey,
-    nodeId: normalized.nodeId,
-    scope: normalized.scope,
-    url: normalized.normalizedUrl,
-    originalUrls: mergedUrls,
-    normalizationVersion: NORMALIZATION_VERSION,
-    paths: oldItem && oldItem.paths ? oldItem.paths : buildPaths(normalized),
-    syncedAt: now,
-    completeness: Array.isArray(extra.completeness)
-      ? extra.completeness
-      : oldItem && Array.isArray(oldItem.completeness)
-      ? oldItem.completeness
-      : [],
-    source: extra.source || (oldItem && oldItem.source) || "manual",
-  };
-
-  index.items = index.items || {};
-  index.items[normalized.cacheKey] = item;
-  writeIndex(index);
-  return { normalized, item };
-}
-
-function ensureFileWithDefault(relativePath, fallbackContent) {
-  const absPath = resolveMaybeAbsolutePath(relativePath);
-  const dir = path.dirname(absPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  if (!fs.existsSync(absPath)) {
-    fs.writeFileSync(absPath, fallbackContent, "utf8");
-  }
-}
-
-function ensureEntryFiles(item) {
-  ensureFileWithDefault(
-    item.paths.meta,
-    `${JSON.stringify(
-      {
-        fileKey: item.fileKey,
-        nodeId: item.nodeId,
-        scope: item.scope,
-        source: item.source,
-        syncedAt: item.syncedAt,
-      },
-      null,
-      2
-    )}\n`
-  );
-  ensureFileWithDefault(
-    item.paths.spec,
-    `# Figma Spec\n\n- fileKey: ${item.fileKey}\n- scope: ${item.scope}\n- nodeId: ${item.nodeId || "N/A"}\n- source: ${item.source}\n- syncedAt: ${item.syncedAt}\n`
-  );
-  ensureFileWithDefault(
-    item.paths.stateMap,
-    `# State Map\n\n- TODO: 补充状态与交互映射。\n`
-  );
-  ensureFileWithDefault(item.paths.raw, "{}\n");
-}
-
-/**
- * Writes generic cache skeleton files, then invokes optional lifecycle hook.
- * @param {string} cacheKey
- * @param {object} item
- */
-function ensureEntryFilesAndHook(cacheKey, item) {
-  ensureEntryFiles(item);
-  runPostEnsureHook(cacheKey, item);
-}
-
-function validateIndex(index) {
-  const errors = [];
-  const normalized = normalizeIndexShape(index);
-  const keys = Object.keys(normalized.items || {});
-  keys.forEach((cacheKey) => {
-    const item = normalized.items[cacheKey];
-    const required = [
-      "fileKey",
-      "scope",
-      "url",
-      "originalUrls",
-      "normalizationVersion",
-      "paths",
-      "syncedAt",
-      "completeness",
-    ];
-    required.forEach((field) => {
-      if (item[field] === undefined || item[field] === null) {
-        errors.push(`${cacheKey}: 缺少字段 ${field}`);
-      }
-    });
-    if (item.scope === "node" && !item.nodeId) {
-      errors.push(`${cacheKey}: node 作用域必须包含 nodeId`);
-    }
-  });
-
-  const flowKeys = Object.keys(normalized.flows || {});
-  flowKeys.forEach((flowId) => {
-    const flow = normalized.flows[flowId];
-    if (!flow || typeof flow !== "object") {
-      errors.push(`flow ${flowId}: 非法结构`);
-      return;
-    }
-    if (!flow.id || flow.id !== flowId) {
-      errors.push(`flow ${flowId}: id 字段缺失或不一致`);
-    }
-    if (!Array.isArray(flow.nodes)) {
-      errors.push(`flow ${flowId}: nodes 必须是数组`);
-    }
-    if (!Array.isArray(flow.edges)) {
-      errors.push(`flow ${flowId}: edges 必须是数组`);
-    }
-    if (Array.isArray(flow.edges)) {
-      flow.edges.forEach((edge, idx) => {
-        if (!edge || typeof edge !== "object") {
-          errors.push(`flow ${flowId}: edge[${idx}] 非法`);
-          return;
-        }
-        if (!edge.from || !edge.to) {
-          errors.push(`flow ${flowId}: edge[${idx}] 缺少 from/to`);
-        }
-        if (!edge.type) {
-          errors.push(`flow ${flowId}: edge[${idx}] 缺少 type`);
-        }
-        if (edge.from && !normalized.items[edge.from]) {
-          errors.push(`flow ${flowId}: edge[${idx}] from 不存在于 items: ${edge.from}`);
-        }
-        if (edge.to && !normalized.items[edge.to]) {
-          errors.push(`flow ${flowId}: edge[${idx}] to 不存在于 items: ${edge.to}`);
-        }
-      });
-    }
-    if (Array.isArray(flow.nodes)) {
-      flow.nodes.forEach((cacheKey) => {
-        if (!normalized.items[cacheKey]) {
-          errors.push(`flow ${flowId}: nodes 引用不存在于 items: ${cacheKey}`);
-        }
-      });
-    }
-  });
-
-  return errors;
-}
-
-/** @param {boolean} force 为 true 时覆盖已存在文件 */
-function copyCursorBootstrap(force) {
-  const pairs = [
-    { from: path.join("rules", "01-figma-cache-core.mdc"), to: path.join(".cursor", "rules", "01-figma-cache-core.mdc") },
-    { from: path.join("rules", "02-figma-stack-adapter.mdc"), to: path.join(".cursor", "rules", "02-figma-stack-adapter.mdc") },
-    { from: path.join("rules", "figma-local-cache-first.mdc"), to: path.join(".cursor", "rules", "figma-local-cache-first.mdc") },
-    {
-      from: path.join("skills", "figma-mcp-local-cache", "SKILL.md"),
-      to: path.join(".cursor", "skills", "figma-mcp-local-cache", "SKILL.md"),
-    },
-    { from: "figma-cache.config.example.js", to: "figma-cache.config.example.js" },
-  ];
-  if (!fs.existsSync(CURSOR_BOOTSTRAP_DIR)) {
-    console.error(
-      `[figma-cache] cursor-bootstrap not found at ${normalizeSlash(CURSOR_BOOTSTRAP_DIR)} (broken package install?)`
-    );
-    process.exit(1);
-  }
-  let copied = 0;
-  let skipped = 0;
-  pairs.forEach(({ from: relFrom, to: relTo }) => {
-    const absFrom = path.join(CURSOR_BOOTSTRAP_DIR, relFrom);
-    const absTo = path.join(ROOT, relTo);
-    if (!fs.existsSync(absFrom)) {
-      console.error(`[figma-cache] missing template file: ${normalizeSlash(absFrom)}`);
-      process.exit(1);
-    }
-    fs.mkdirSync(path.dirname(absTo), { recursive: true });
-    if (fs.existsSync(absTo) && !force) {
-      skipped += 1;
-      return;
-    }
-    fs.copyFileSync(absFrom, absTo);
-    copied += 1;
-  });
-
-  const agentSrc = path.join(CURSOR_BOOTSTRAP_DIR, "AGENT-SETUP-PROMPT.md");
-  const agentDest = path.join(ROOT, "AGENT-SETUP-PROMPT.md");
-  if (!fs.existsSync(agentSrc)) {
-    console.error(`[figma-cache] missing ${normalizeSlash(agentSrc)}`);
-    process.exit(1);
-  }
-  let agentBody = fs.readFileSync(agentSrc, "utf8");
-  const npmPkg = readSelfNpmPackageName();
-  agentBody = agentBody.replace(/\{\{NPM_PACKAGE_NAME\}\}/g, npmPkg);
-  fs.writeFileSync(agentDest, agentBody, "utf8");
-
-  const colleagueSrc = path.join(__dirname, "colleague-guide-zh.md");
-  const colleagueDest = path.join(CACHE_DIR, "colleague-guide-zh.md");
-  if (!fs.existsSync(colleagueSrc)) {
-    console.error(`[figma-cache] missing ${normalizeSlash(colleagueSrc)} (broken package install?)`);
-    process.exit(1);
-  }
-  const colleagueSameFile = path.resolve(colleagueSrc) === path.resolve(colleagueDest);
-  if (!colleagueSameFile) {
-    fs.mkdirSync(CACHE_DIR, { recursive: true });
-    fs.copyFileSync(colleagueSrc, colleagueDest);
-  }
-
-  console.log(
-    JSON.stringify(
-      {
-        ok: true,
-        root: normalizeSlash(ROOT),
-        copied,
-        skipped,
-        force: !!force,
-        hint: skipped
-          ? "Some template files were skipped (already exist). Re-run with --force to overwrite."
-          : "Done.",
-        agentPromptFile: normalizeSlash(agentDest),
-        colleagueGuideFile: normalizeSlash(colleagueDest),
-        colleagueGuideSynced: !colleagueSameFile,
-        colleagueGuideNote: colleagueSameFile
-          ? "colleague-guide-zh.md already at package path (toolchain dev tree); no copy."
-          : "colleague-guide-zh.md refreshed under FIGMA_CACHE_DIR (default figma-cache/).",
-        agentPromptNote:
-          "AGENT-SETUP-PROMPT.md is refreshed every run. Next: @ it in Cursor; after Agent finishes, run npm run figma:cache:init (or npx figma-cache init if scripts are missing).",
-        npmPackageName: npmPkg,
-      },
-      null,
-      2
-    )
-  );
-  console.log(
-    "\n" +
-      "================================================================\n" +
-      "下一步（请按顺序）：\n" +
-      "1) 在 Cursor 对话中输入 @AGENT-SETUP-PROMPT.md，并说明「按该文档执行」\n" +
-      "   （每次 cursor init 都会刷新该文件；无需再整篇粘贴。）\n" +
-      "2) 待 Agent 完成后，在项目根初始化本地缓存索引：\n" +
-      "   npm run figma:cache:init\n" +
-      "   若尚未补全 npm scripts，请改用：npx figma-cache init\n" +
-      "================================================================\n"
-  );
-}
-
-function collectMarkdownFiles(dir) {
-  if (!fs.existsSync(dir)) {
+function normalizeCompletenessList(input) {
+  if (!Array.isArray(input)) {
     return [];
   }
+  const seen = new Set();
   const output = [];
-  const list = fs.readdirSync(dir, { withFileTypes: true });
-  list.forEach((entry) => {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      output.push(...collectMarkdownFiles(fullPath));
+  input.forEach((entry) => {
+    const value = String(entry || "").trim();
+    if (!value || seen.has(value)) {
       return;
     }
-    if (entry.isFile() && entry.name.endsWith(".md")) {
-      output.push(fullPath);
-    }
+    seen.add(value);
+    output.push(value);
   });
   return output;
 }
 
-function extractFigmaUrls(content) {
-  const pattern = /https:\/\/www\.figma\.com\/(?:file|design)\/[^\s)\]]+/g;
-  return content.match(pattern) || [];
-}
-
-function backfillFromIterations() {
-  const files = collectMarkdownFiles(ITERATIONS_DIR);
-  let hit = 0;
-  files.forEach((filePath) => {
-    const content = fs.readFileSync(filePath, "utf8");
-    const urls = extractFigmaUrls(content);
-    urls.forEach((url) => {
-      try {
-        upsertByUrl(url, { source: "backfill" });
-        hit += 1;
-      } catch (error) {
-        // 忽略无法解析的 URL
-      }
-    });
-  });
-  console.log(`Backfill done. scanned files=${files.length}, urls=${hit}`);
-}
-
-function slugifyFlowId(name) {
-  const raw = String(name || "")
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return raw || `flow-${Date.now()}`;
-}
+const entryFilesService = createEntryFilesService({
+  fs,
+  path,
+  resolveMaybeAbsolutePath,
+  normalizeCompletenessList,
+  completenessAllDimensions: COMPLETENESS_ALL_DIMENSIONS,
+  runPostEnsureHook,
+});
+const { ensureEntryFilesAndHook } = entryFilesService;
 
-function ensureFlow(index, flowId, meta) {
-  const normalized = normalizeIndexShape(index);
-  normalized.flows = normalized.flows || {};
-  if (!normalized.flows[flowId]) {
-    normalized.flows[flowId] = {
-      id: flowId,
-      title: meta && meta.title ? meta.title : flowId,
-      description: meta && meta.description ? meta.description : "",
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString(),
-      nodes: [],
-      edges: [],
-      assumptions: [],
-      openQuestions: [],
+function parseCompletenessFromArgs(args) {
+  const completenessArg = args.find((x) => x.startsWith("--completeness="));
+  if (!completenessArg) {
+    return {
+      completeness: [...DEFAULT_COMPLETENESS],
+      fromCliArg: false,
     };
   }
-  return normalized.flows[flowId];
-}
-
-function upsertFlowNode(index, flowId, cacheKey) {
-  const flow = ensureFlow(index, flowId, {});
-  if (!flow.nodes.includes(cacheKey)) {
-    flow.nodes.push(cacheKey);
-  }
-  flow.updatedAt = new Date().toISOString();
-}
-
-function addFlowEdge(index, flowId, fromKey, toKey, type, note) {
-  const flow = ensureFlow(index, flowId, {});
-  const edge = {
-    id: `${fromKey}->${toKey}:${type}:${Date.now()}`,
-    from: fromKey,
-    to: toKey,
-    type,
-    note: note || "",
-    createdAt: new Date().toISOString(),
+  return {
+    completeness: normalizeCompletenessList(
+      completenessArg.split("=").slice(1).join("=").split(","),
+    ),
+    fromCliArg: true,
   };
-  flow.edges.push(edge);
-  flow.updatedAt = new Date().toISOString();
 }
 
 /** @returns {string} */
@@ -685,137 +248,112 @@ function safeFileSize(absPath) {
   }
 }
 
-function parsePositiveIntOr(input, fallback) {
-  const n = Number(input);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
-}
-
-function buildBudgetReport(options) {
-  const index = normalizeIndexShape(readIndex());
-  const items = index.items || {};
-  const keys = Object.keys(items);
-  const filteredKeys = keys.filter((cacheKey) => {
-    if (options.cacheKey && cacheKey !== options.cacheKey) {
-      return false;
-    }
-    if (options.mcpOnly) {
-      const item = items[cacheKey];
-      return item && item.source === "figma-mcp";
+function runUpsertLikeCommand(commandName, args, shouldEnsureFiles) {
+  const url = args[0];
+  const sourceArg = args.find((x) => x.startsWith("--source="));
+  const source = sourceArg ? sourceArg.split("=")[1] : "manual";
+  const allowSkeletonWithFigmaMcp = args.includes(
+    "--allow-skeleton-with-figma-mcp",
+  );
+  const { completeness } = parseCompletenessFromArgs(args);
+
+  const preview = previewUpsertByUrl(url, { source, completeness });
+  if (source === "figma-mcp") {
+    const mcpErrors = validateMcpRawEvidence(
+      preview.normalized.cacheKey,
+      preview.item,
+      completeness,
+      { allowSkeletonWithFigmaMcp },
+      {
+        fs,
+        path,
+        resolveMaybeAbsolutePath,
+        safeReadJson,
+        normalizeSlash,
+        normalizeCompletenessList,
+        completenessToolRequirements: COMPLETENESS_TOOL_REQUIREMENTS,
+      },
+    );
+    if (mcpErrors.length) {
+      console.error(
+        `${commandName} failed: source=figma-mcp but MCP raw evidence is incomplete`,
+      );
+      mcpErrors.forEach((err) => console.error(`- ${err}`));
+      process.exit(2);
     }
-    return true;
-  });
-
-  const entries = filteredKeys.map((cacheKey) => {
-    const item = items[cacheKey];
-    const metaAbs = resolveMaybeAbsolutePath(item.paths.meta);
-    const nodeDir = path.dirname(metaAbs);
-    const mcpRawDir = path.join(nodeDir, "mcp-raw");
-    const manifestAbs = path.join(mcpRawDir, "mcp-raw-manifest.json");
-    const manifest = safeReadJson(manifestAbs);
-    const filesMap = manifest && manifest.files && typeof manifest.files === "object" ? manifest.files : {};
-    const fileEntries = Object.entries(filesMap);
-    const mcpRawBytes = fileEntries.reduce((acc, [, fileName]) => {
-      const abs = path.join(mcpRawDir, String(fileName));
-      return acc + safeFileSize(abs);
-    }, 0);
-    const mcpRawFilesCount = fileEntries.length;
-    const toolCalls = manifest && manifest.toolCalls && typeof manifest.toolCalls === "object" ? manifest.toolCalls : {};
-    const toolCallCount = Object.values(toolCalls).reduce((acc, v) => {
-      const count = v && typeof v === "object" ? Number(v.count) : 0;
-      return acc + (Number.isFinite(count) ? count : 0);
-    }, 0);
-    const designContextFile =
-      filesMap && Object.prototype.hasOwnProperty.call(filesMap, "get_design_context")
-        ? String(filesMap.get_design_context)
-        : "";
-    const designContextChars = designContextFile
-      ? safeFileSize(path.join(mcpRawDir, designContextFile))
-      : 0;
+  }
 
-    return {
-      cacheKey,
-      source: item.source || "manual",
-      completeness: Array.isArray(item.completeness) ? item.completeness : [],
-      hasMcpRawManifest: !!manifest,
-      mcpRawFilesCount,
-      mcpRawBytes,
-      tokenProxyBytes: designContextChars,
-      tokenProxyChars: designContextChars,
-      toolCallCount,
-      toolCalls,
-    };
-  });
+  const result = upsertByUrl(url, { source, completeness });
+  if (shouldEnsureFiles) {
+    ensureEntryFilesAndHook(result.normalized.cacheKey, result.item);
+    console.log(
+      JSON.stringify(
+        {
+          cacheKey: result.normalized.cacheKey,
+          ensured: true,
+          paths: result.item.paths,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
 
-  entries.sort((a, b) => b.mcpRawBytes - a.mcpRawBytes);
-  const limit = parsePositiveIntOr(options.limit, entries.length);
-  const limitedEntries = entries.slice(0, limit);
-  const totals = limitedEntries.reduce(
-    (acc, e) => {
-      acc.nodes += 1;
-      acc.nodesWithMcpRaw += e.hasMcpRawManifest ? 1 : 0;
-      acc.mcpRawBytes += e.mcpRawBytes;
-      acc.tokenProxyBytes += e.tokenProxyBytes;
-      acc.toolCallCount += e.toolCallCount;
-      return acc;
-    },
-    {
-      nodes: 0,
-      nodesWithMcpRaw: 0,
-      mcpRawBytes: 0,
-      tokenProxyBytes: 0,
-      toolCallCount: 0,
-    }
+  console.log(
+    JSON.stringify(
+      {
+        cacheKey: result.normalized.cacheKey,
+        scope: result.item.scope,
+        syncedAt: result.item.syncedAt,
+      },
+      null,
+      2,
+    ),
   );
-
-  totals.tokenProxyChars = totals.tokenProxyBytes;
-
-  return {
-    generatedAt: new Date().toISOString(),
-    filters: {
-      cacheKey: options.cacheKey || null,
-      mcpOnly: !!options.mcpOnly,
-      limit,
-    },
-    totals,
-    entries: limitedEntries,
-  };
 }
-
 function run() {
   const [, , cmd, ...args] = process.argv;
   if (!cmd) {
     const ex = inferCliExample();
+    const defaultCompletenessText = DEFAULT_COMPLETENESS.join(",");
     console.log("Usage:");
-    console.log(`  (invoke examples: ${ex} | node bin/figma-cache.js | node figma-cache/figma-cache.js)`);
+    console.log(
+      `  (invoke examples: ${ex} | node bin/figma-cache.js | node figma-cache/figma-cache.js)`,
+    );
     console.log(`  ${ex} normalize <figmaUrl>`);
     console.log(`  ${ex} get <figmaUrl>`);
-    console.log(`  ${ex} upsert <figmaUrl> [--source=manual] [--completeness=a,b]`);
+    console.log(
+      `  ${ex} upsert <figmaUrl> [--source=manual] [--completeness=a,b] [--allow-skeleton-with-figma-mcp]  (default completeness=${defaultCompletenessText})`,
+    );
     console.log(`  ${ex} validate`);
     console.log(`  ${ex} stale [--days=14]`);
     console.log(`  ${ex} backfill`);
-    console.log(`  ${ex} budget [--mcp-only] [--cacheKey=<fileKey#nodeId>] [--limit=50]`);
     console.log(
-      `  ${ex} ensure <figmaUrl> [--source=manual] [--completeness=a,b] [--allow-skeleton-with-figma-mcp]`
+      `  ${ex} budget [--mcp-only] [--cacheKey=<fileKey#nodeId>] [--limit=50]`,
+    );
+    console.log(
+      `  ${ex} ensure <figmaUrl> [--source=manual] [--completeness=a,b] [--allow-skeleton-with-figma-mcp]  (default completeness=${defaultCompletenessText})`,
     );
     console.log(`  ${ex} init`);
     console.log(`  ${ex} config`);
     console.log(
-      "  (optional) figma-cache.config.js | .figmacacherc.js | FIGMA_CACHE_PROJECT_CONFIG — hooks.postEnsure after ensure"
+      "  (optional) figma-cache.config.js | .figmacacherc.js | FIGMA_CACHE_PROJECT_CONFIG 鈥?hooks.postEnsure after ensure",
     );
     console.log(`  ${ex} flow init --id=<flowId> [--title=...]`);
     console.log(
-      `${ex} flow add-node --flow=<flowId> <figmaUrl> [--ensure] [--source=manual] [--completeness=a,b]`
+      `${ex} flow add-node --flow=<flowId> <figmaUrl> [--ensure] [--source=manual] [--completeness=a,b]`,
     );
     console.log(
-      `${ex} flow link --flow=<flowId> <fromUrl> <toUrl> --type=next_step [--note=...]`
+      `${ex} flow link --flow=<flowId> <fromUrl> <toUrl> --type=next_step [--note=...]`,
     );
     console.log(
-      `${ex} flow chain --flow=<flowId> <url1> <url2> ... [--type=next_step|related]`
+      `${ex} flow chain --flow=<flowId> <url1> <url2> ... [--type=next_step|related]`,
     );
     console.log(`  ${ex} flow show --flow=<flowId>`);
     console.log(`  ${ex} flow mermaid --flow=<flowId>`);
     console.log(
-      `${ex} cursor init [--force]  # copy .cursor templates + figma-cache.config.example.js + refresh AGENT-SETUP-PROMPT.md + sync colleague-guide-zh.md into FIGMA_CACHE_DIR`
+      `${ex} cursor init [--force]  # copy .cursor templates + ensure figma-cache.config.js (+ cleanup safe legacy example) + refresh AGENT-SETUP-PROMPT.md + sync colleague-guide-zh.md into FIGMA_CACHE_DIR`,
     );
     process.exit(1);
   }
@@ -827,7 +365,16 @@ function run() {
       process.exit(1);
     }
     const force = args.includes("--force");
-    copyCursorBootstrap(force);
+    copyCursorBootstrap(force, {
+      fs,
+      path,
+      ROOT,
+      CACHE_DIR,
+      CURSOR_BOOTSTRAP_DIR,
+      normalizeSlash,
+      readSelfNpmPackageName,
+      packageDir: __dirname,
+    });
     return;
   }
 
@@ -851,78 +398,33 @@ function run() {
           item: item || null,
         },
         null,
-        2
-      )
+        2,
+      ),
     );
     return;
   }
 
   if (cmd === "upsert") {
-    const url = args[0];
-    const sourceArg = args.find((x) => x.startsWith("--source="));
-    const completenessArg = args.find((x) => x.startsWith("--completeness="));
-    const source = sourceArg ? sourceArg.split("=")[1] : "manual";
-    const completeness = completenessArg
-      ? completenessArg
-          .split("=")[1]
-          .split(",")
-          .map((x) => x.trim())
-          .filter(Boolean)
-      : [];
-    const result = upsertByUrl(url, { source, completeness });
-    console.log(
-      JSON.stringify(
-        { cacheKey: result.normalized.cacheKey, scope: result.item.scope, syncedAt: result.item.syncedAt },
-        null,
-        2
-      )
-    );
+    runUpsertLikeCommand("upsert", args, false);
     return;
   }
 
   if (cmd === "ensure") {
-    const url = args[0];
-    const sourceArg = args.find((x) => x.startsWith("--source="));
-    const completenessArg = args.find((x) => x.startsWith("--completeness="));
-    const allowSkeletonWithFigmaMcp = args.includes("--allow-skeleton-with-figma-mcp");
-    const source = sourceArg ? sourceArg.split("=")[1] : "manual";
-    const completeness = completenessArg
-      ? completenessArg
-          .split("=")[1]
-          .split(",")
-          .map((x) => x.trim())
-          .filter(Boolean)
-      : [];
-    if (source === "figma-mcp" && !allowSkeletonWithFigmaMcp) {
-      console.error(
-        [
-          "ensure 检测到 --source=figma-mcp，但当前 CLI 不会主动发起 MCP 请求。",
-          "为避免“假成功”，已阻止本次写入。",
-          "请先由 Agent/Figma MCP 拉取并写入 mcp-raw，再执行 upsert/ensure；",
-          "若你只想生成本地骨架，请显式追加 --allow-skeleton-with-figma-mcp。",
-        ].join("\n")
-      );
-      process.exit(2);
-    }
-    const result = upsertByUrl(url, { source, completeness });
-    ensureEntryFilesAndHook(result.normalized.cacheKey, result.item);
-    console.log(
-      JSON.stringify(
-        {
-          cacheKey: result.normalized.cacheKey,
-          ensured: true,
-          paths: result.item.paths,
-        },
-        null,
-        2
-      )
-    );
+    runUpsertLikeCommand("ensure", args, true);
     return;
   }
-
   if (cmd === "validate") {
     const index = readIndex();
-    const errors = validateIndex(index);
+    const errors = validateIndex(index, {
+      fs,
+      path,
+      normalizeIndexShape,
+      normalizeCompletenessList,
+      resolveMaybeAbsolutePath,
+      safeReadJson,
+      normalizeSlash,
+      completenessToolRequirements: COMPLETENESS_TOOL_REQUIREMENTS,
+    });
     if (!errors.length) {
       console.log("Validation passed.");
       return;
@@ -940,7 +442,14 @@ function run() {
   }
 
   if (cmd === "backfill") {
-    backfillFromIterations();
+    backfillFromIterations(
+      { iterationsDir: ITERATIONS_DIR },
+      {
+        fs,
+        path,
+        upsertByUrl,
+      },
+    );
     return;
   }
 
@@ -948,9 +457,21 @@ function run() {
     const mcpOnly = args.includes("--mcp-only");
     const cacheKeyArg = args.find((x) => x.startsWith("--cacheKey="));
     const limitArg = args.find((x) => x.startsWith("--limit="));
-    const cacheKey = cacheKeyArg ? cacheKeyArg.split("=").slice(1).join("=") : "";
+    const cacheKey = cacheKeyArg
+      ? cacheKeyArg.split("=").slice(1).join("=")
+      : "";
     const limit = limitArg ? limitArg.split("=")[1] : "";
-    const report = buildBudgetReport({ mcpOnly, cacheKey, limit });
+    const report = buildBudgetReport(
+      { mcpOnly, cacheKey, limit },
+      {
+        path,
+        normalizeIndexShape,
+        readIndex,
+        resolveMaybeAbsolutePath,
+        safeReadJson,
+        safeFileSize,
+      },
+    );
     console.log(JSON.stringify(report, null, 2));
     return;
   }
@@ -967,17 +488,16 @@ function run() {
           iterationsDir: normalizeSlash(ITERATIONS_DIR),
           staleDays: DEFAULT_STALE_DAYS,
           defaultFlowId: DEFAULT_FLOW_ID || null,
+          defaultCompleteness: [...DEFAULT_COMPLETENESS],
           normalizationVersion: NORMALIZATION_VERSION,
-          projectConfigPath: memoProjectConfigPath
-            ? normalizeSlash(memoProjectConfigPath)
-            : null,
+          projectConfigPath: getProjectConfigPath(),
           hooks: {
             postEnsure: !!(hooks && typeof hooks.postEnsure === "function"),
           },
         },
         null,
-        2
-      )
+        2,
+      ),
     );
     return;
   }
@@ -993,8 +513,8 @@ function run() {
             indexPath: normalizeSlash(INDEX_PATH),
           },
           null,
-          2
-        )
+          2,
+        ),
       );
       return;
     }
@@ -1006,176 +526,25 @@ function run() {
           indexPath: normalizeSlash(INDEX_PATH),
         },
         null,
-        2
-      )
+        2,
+      ),
     );
     return;
   }
 
   if (cmd === "flow") {
-    const sub = args[0];
-    const rest = args.slice(1);
-    if (!sub) {
-      console.error("Missing flow subcommand");
-      process.exit(1);
-    }
-
-    if (sub === "init") {
-      const idArg = rest.find((x) => x.startsWith("--id="));
-      const titleArg = rest.find((x) => x.startsWith("--title="));
-      const descArg = rest.find((x) => x.startsWith("--description="));
-      const flowId = idArg ? idArg.split("=")[1] : slugifyFlowId("flow");
-      const title = titleArg ? titleArg.split("=").slice(1).join("=") : flowId;
-      const description = descArg ? descArg.split("=").slice(1).join("=") : "";
-      const index = normalizeIndexShape(readIndex());
-      ensureFlow(index, flowId, { title, description });
-      writeIndex(index);
-      console.log(JSON.stringify({ flowId, created: true }, null, 2));
-      return;
-    }
-
-    if (sub === "add-node") {
-      const flowId = resolveFlowIdFromArgs(rest);
-      if (!flowId) {
-        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
-        process.exit(1);
-      }
-      const url = rest.find((x) => !x.startsWith("--"));
-      const ensureArg = rest.includes("--ensure");
-      const sourceArg = rest.find((x) => x.startsWith("--source="));
-      const completenessArg = rest.find((x) => x.startsWith("--completeness="));
-      const source = sourceArg ? sourceArg.split("=")[1] : "manual";
-      const completeness = completenessArg
-        ? completenessArg
-            .split("=")[1]
-            .split(",")
-            .map((x) => x.trim())
-            .filter(Boolean)
-        : [];
-      const index = normalizeIndexShape(readIndex());
-      const normalized = normalizeFigmaUrl(url);
-      if (!ensureArg && !getItem(index, normalized.cacheKey)) {
-        console.error(
-          `Missing cache item for ${normalized.cacheKey}. Run figma:cache:ensure first, or pass --ensure.`
-        );
-        process.exit(2);
-      }
-      if (ensureArg) {
-        upsertByUrl(url, { source, completeness });
-        const refreshed = normalizeIndexShape(readIndex());
-        const item = getItem(refreshed, normalized.cacheKey);
-        if (item) {
-          ensureEntryFilesAndHook(normalized.cacheKey, item);
-        }
-        Object.assign(index, refreshed);
-      }
-      upsertFlowNode(index, flowId, normalized.cacheKey);
-      writeIndex(index);
-      console.log(
-        JSON.stringify(
-          { flowId, cacheKey: normalized.cacheKey, added: true, ensured: ensureArg },
-          null,
-          2
-        )
-      );
-      return;
-    }
-
-    if (sub === "link") {
-      const flowId = resolveFlowIdFromArgs(rest);
-      const typeArg = rest.find((x) => x.startsWith("--type="));
-      const noteArg = rest.find((x) => x.startsWith("--note="));
-      const urls = rest.filter((x) => !x.startsWith("--"));
-      if (!flowId) {
-        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
-        process.exit(1);
-      }
-      if (urls.length < 2) {
-        console.error("Missing <fromUrl> <toUrl>");
-        process.exit(1);
-      }
-      const type = typeArg ? typeArg.split("=")[1] : "related";
-      const note = noteArg ? noteArg.split("=").slice(1).join("=") : "";
-      const from = normalizeFigmaUrl(urls[0]).cacheKey;
-      const to = normalizeFigmaUrl(urls[1]).cacheKey;
-      const index = normalizeIndexShape(readIndex());
-      if (!getItem(index, from) || !getItem(index, to)) {
-        console.error("Missing cache item for from/to. Cache urls first with ensure/upsert.");
-        process.exit(2);
-      }
-      upsertFlowNode(index, flowId, from);
-      upsertFlowNode(index, flowId, to);
-      addFlowEdge(index, flowId, from, to, type, note);
-      writeIndex(index);
-      console.log(JSON.stringify({ flowId, from, to, type, linked: true }, null, 2));
-      return;
-    }
-
-    if (sub === "chain") {
-      const flowId = resolveFlowIdFromArgs(rest);
-      const typeArg = rest.find((x) => x.startsWith("--type="));
-      const type = typeArg ? typeArg.split("=")[1] : "related";
-      const urls = rest.filter((x) => !x.startsWith("--"));
-      if (!flowId) {
-        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
-        process.exit(1);
-      }
-      if (urls.length < 2) {
-        console.error("Need at least 2 urls");
-        process.exit(1);
-      }
-      const index = normalizeIndexShape(readIndex());
-      const keys = urls.map((u) => normalizeFigmaUrl(u).cacheKey);
-      keys.forEach((k) => {
-        if (!getItem(index, k)) {
-          console.error(`Missing cache item for ${k}. Ensure each url is cached first.`);
-          process.exit(2);
-        }
-      });
-      keys.forEach((k) => upsertFlowNode(index, flowId, k));
-      for (let i = 0; i < keys.length - 1; i += 1) {
-        addFlowEdge(index, flowId, keys[i], keys[i + 1], type, "");
-      }
-      writeIndex(index);
-      console.log(JSON.stringify({ flowId, chained: keys.length - 1, type }, null, 2));
-      return;
-    }
-
-    if (sub === "show") {
-      const flowId = resolveFlowIdFromArgs(rest);
-      if (!flowId) {
-        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
-        process.exit(1);
-      }
-      const index = normalizeIndexShape(readIndex());
-      const flow = index.flows[flowId];
-      console.log(JSON.stringify({ flowId, flow: flow || null }, null, 2));
-      return;
-    }
-
-    if (sub === "mermaid") {
-      const flowId = resolveFlowIdFromArgs(rest);
-      if (!flowId) {
-        console.error("Missing --flow=<flowId> or env FIGMA_DEFAULT_FLOW");
-        process.exit(1);
-      }
-      const index = normalizeIndexShape(readIndex());
-      const flow = index.flows[flowId];
-      if (!flow) {
-        console.error(`Unknown flow: ${flowId}`);
-        process.exit(1);
-      }
-      const lines = ["flowchart LR"];
-      (flow.edges || []).forEach((edge) => {
-        const label = edge.type || "edge";
-        lines.push(`  ${edge.from} -->|${label}| ${edge.to}`);
-      });
-      console.log(lines.join("\n"));
-      return;
-    }
-
-    console.error(`Unknown flow subcommand: ${sub}`);
-    process.exit(1);
+    handleFlowCommand(args, {
+      resolveFlowIdFromArgs,
+      parseCompletenessFromArgs,
+      normalizeIndexShape,
+      readIndex,
+      writeIndex,
+      normalizeFigmaUrl,
+      getItem,
+      upsertByUrl,
+      ensureEntryFilesAndHook,
+    });
+    return;
   }
 
   console.error(`Unknown command: ${cmd}`);