figma-cache-toolchain 1.4.3 → 1.4.5

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

@@ -0,0 +1,50 @@
+/* eslint-disable no-console */
+
+function collectMarkdownFiles(dir, deps) {
+  if (!deps.fs.existsSync(dir)) {
+    return [];
+  }
+
+  const output = [];
+  const list = deps.fs.readdirSync(dir, { withFileTypes: true });
+  list.forEach((entry) => {
+    const fullPath = deps.path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      output.push(...collectMarkdownFiles(fullPath, deps));
+      return;
+    }
+    if (entry.isFile() && entry.name.endsWith(".md")) {
+      output.push(fullPath);
+    }
+  });
+  return output;
+}
+
+function extractFigmaUrls(content) {
+  const pattern = /https:\/\/www\.figma\.com\/(?:file|design)\/[^\s)\]]+/g;
+  return content.match(pattern) || [];
+}
+
+function backfillFromIterations(options, deps) {
+  const files = collectMarkdownFiles(options.iterationsDir, deps);
+  let hit = 0;
+
+  files.forEach((filePath) => {
+    const content = deps.fs.readFileSync(filePath, "utf8");
+    const urls = extractFigmaUrls(content);
+    urls.forEach((url) => {
+      try {
+        deps.upsertByUrl(url, { source: "backfill", completeness: [] });
+        hit += 1;
+      } catch {
+        // 忽略无法解析的 URL
+      }
+    });
+  });
+
+  console.log(`Backfill done. scanned files=${files.length}, urls=${hit}`);
+}
+
+module.exports = {
+  backfillFromIterations,
+};

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

@@ -0,0 +1,108 @@
+/* eslint-disable no-console */
+
+function parsePositiveIntOr(input, fallback) {
+  const n = Number(input);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+
+function buildBudgetReport(options, deps) {
+  const index = deps.normalizeIndexShape(deps.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";
+    }
+    return true;
+  });
+
+  const entries = filteredKeys.map((cacheKey) => {
+    const item = items[cacheKey];
+    const metaAbs = deps.resolveMaybeAbsolutePath(item.paths.meta);
+    const nodeDir = deps.path.dirname(metaAbs);
+    const mcpRawDir = deps.path.join(nodeDir, "mcp-raw");
+    const manifestAbs = deps.path.join(mcpRawDir, "mcp-raw-manifest.json");
+    const manifest = deps.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 = deps.path.join(mcpRawDir, String(fileName));
+      return acc + deps.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
+      ? deps.safeFileSize(deps.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,
+    };
+  });
+
+  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,
+    }
+  );
+
+  totals.tokenProxyChars = totals.tokenProxyBytes;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    filters: {
+      cacheKey: options.cacheKey || null,
+      mcpOnly: !!options.mcpOnly,
+      limit,
+    },
+    totals,
+    entries: limitedEntries,
+  };
+}
+
+module.exports = {
+  buildBudgetReport,
+};

package/figma-cache/js/cursor-bootstrap-cli.js

@@ -0,0 +1,178 @@
+/* eslint-disable no-console */
+
+function readUtf8IfExists(fs, absPath) {
+  if (!fs.existsSync(absPath)) {
+    return "";
+  }
+  return fs.readFileSync(absPath, "utf8");
+}
+
+function copyCursorBootstrap(force, deps) {
+  const {
+    fs,
+    path,
+    ROOT,
+    CACHE_DIR,
+    CURSOR_BOOTSTRAP_DIR,
+    normalizeSlash,
+    readSelfNpmPackageName,
+    packageDir,
+  } = deps;
+
+  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"),
+    },
+  ];
+
+  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 configTemplatePath = path.join(CURSOR_BOOTSTRAP_DIR, "figma-cache.config.example.js");
+  const projectConfigPath = path.join(ROOT, "figma-cache.config.js");
+  const legacyExamplePath = path.join(ROOT, "figma-cache.config.example.js");
+
+  if (!fs.existsSync(configTemplatePath)) {
+    console.error(`[figma-cache] missing template file: ${normalizeSlash(configTemplatePath)}`);
+    process.exit(1);
+  }
+
+  const hadProjectConfig = fs.existsSync(projectConfigPath);
+  const hadLegacyExample = fs.existsSync(legacyExamplePath);
+  const configTemplateBody = fs.readFileSync(configTemplatePath, "utf8");
+
+  let configAction = "skipped";
+  let configSource = "existing";
+  if (hadProjectConfig && !force) {
+    configAction = "skipped";
+    configSource = "existing";
+  } else if (!hadProjectConfig && hadLegacyExample && !force) {
+    fs.copyFileSync(legacyExamplePath, projectConfigPath);
+    configAction = "created";
+    configSource = "legacy-example";
+  } else {
+    fs.writeFileSync(projectConfigPath, configTemplateBody, "utf8");
+    configAction = hadProjectConfig ? "overwritten" : "created";
+    configSource = "template";
+  }
+
+  let legacyExampleStatus = "not-found";
+  if (fs.existsSync(legacyExamplePath)) {
+    const legacyBody = readUtf8IfExists(fs, legacyExamplePath);
+    const projectBody = readUtf8IfExists(fs, projectConfigPath);
+    const sameAsTemplate = legacyBody === configTemplateBody;
+    const sameAsProject = projectBody && legacyBody === projectBody;
+    if (sameAsTemplate || sameAsProject) {
+      fs.unlinkSync(legacyExamplePath);
+      legacyExampleStatus = "deleted";
+    } else {
+      legacyExampleStatus = "kept-customized";
+    }
+  }
+
+  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(packageDir, "docs", "colleague-guide-zh.md");
+  const colleagueDest = path.join(CACHE_DIR, "docs", "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(path.dirname(colleagueDest), { 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.",
+        configFile: normalizeSlash(projectConfigPath),
+        configAction,
+        configSource,
+        legacyExampleFile: normalizeSlash(legacyExamplePath),
+        legacyExampleStatus,
+        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/docs (default figma-cache/docs/).",
+        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"
+  );
+}
+
+module.exports = {
+  copyCursorBootstrap,
+};
+

package/figma-cache/js/entry-files.js

@@ -0,0 +1,149 @@
+/* eslint-disable no-console */
+
+function createEntryFilesService(deps) {
+  const {
+    fs,
+    path,
+    resolveMaybeAbsolutePath,
+    normalizeCompletenessList,
+    completenessAllDimensions,
+    runPostEnsureHook,
+  } = deps;
+
+  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 buildCoverageSummary(completeness) {
+    const covered = normalizeCompletenessList(completeness);
+    const missing = completenessAllDimensions.filter((dim) => !covered.includes(dim));
+    return {
+      covered,
+      missing,
+      evidence: {
+        layout: covered.includes("layout") ? ["spec.md#layout"] : [],
+        text: covered.includes("text") ? ["spec.md#text"] : [],
+        tokens: covered.includes("tokens") ? ["spec.md#tokens"] : [],
+        interactions: covered.includes("interactions") ? ["state-map.md#interactions"] : [],
+        states: covered.includes("states") ? ["state-map.md#states"] : [],
+        accessibility: covered.includes("accessibility")
+          ? ["state-map.md#accessibility"]
+          : [],
+      },
+    };
+  }
+
+  function buildDefaultSpecContent(item) {
+    const completeness = normalizeCompletenessList(item.completeness);
+    return (
+      `# 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` +
+      `- completeness: ${completeness.join(", ") || "N/A"}\n\n` +
+      `## Layout（结构）\n\n` +
+      `- TODO: 补充布局结构与关键尺寸。\n\n` +
+      `## Text（文案）\n\n` +
+      `- TODO: 补充关键文案与语义。\n\n` +
+      `## Tokens（变量 / 样式）\n\n` +
+      `- TODO: 补充颜色、字体、间距等 token 映射。\n\n` +
+      `## Interactions（交互）\n\n` +
+      `- TODO: 补充触发条件、状态流转、键盘行为。\n\n` +
+      `## States（状态）\n\n` +
+      `- TODO: 补充 default / hover / active / focus / disabled 等状态定义。\n\n` +
+      `## Accessibility（可访问性）\n\n` +
+      `- TODO: 补充 ARIA、焦点顺序、读屏文案和对比度要求。\n`
+    );
+  }
+
+  function buildDefaultStateMapContent(item) {
+    return (
+      `# State Map\n\n` +
+      `- cacheKey: ${item.fileKey}#${item.nodeId || "__FILE__"}\n` +
+      `- completeness: ${normalizeCompletenessList(item.completeness).join(", ") || "N/A"}\n\n` +
+      `## Interactions\n\n` +
+      `| Trigger | From | To | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| TODO | default | TODO | 补充点击/键盘/失焦行为 |\n\n` +
+      `## States\n\n` +
+      `| State | Visual | Data | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| default | TODO | TODO | 初始态 |\n` +
+      `| hover | TODO | TODO | 悬停态 |\n` +
+      `| active | TODO | TODO | 激活态 |\n` +
+      `| focus | TODO | TODO | 焦点态 |\n` +
+      `| disabled | TODO | TODO | 禁用态 |\n\n` +
+      `## Accessibility\n\n` +
+      `- TODO: 补充 role / aria-* / tab 顺序 / 键盘行为。\n`
+    );
+  }
+
+  function buildDefaultRawContent(item) {
+    const completeness = normalizeCompletenessList(item.completeness);
+    return `${JSON.stringify(
+      {
+        source: item.source,
+        fileKey: item.fileKey,
+        nodeId: item.nodeId,
+        scope: item.scope,
+        syncedAt: item.syncedAt,
+        completeness,
+        coverageSummary: buildCoverageSummary(completeness),
+        interactions: {
+          notes: "TODO: 补充点击、键盘、失焦、外部点击等交互规则。",
+        },
+        states: {
+          notes: "TODO: 补充状态矩阵（default/hover/active/focus/disabled）。",
+        },
+        accessibility: {
+          notes: "TODO: 补充 ARIA、焦点管理、读屏文本、无障碍要求。",
+        },
+      },
+      null,
+      2
+    )}\n`;
+  }
+
+  function ensureEntryFiles(item) {
+    ensureFileWithDefault(
+      item.paths.meta,
+      `${JSON.stringify(
+        {
+          fileKey: item.fileKey,
+          nodeId: item.nodeId,
+          scope: item.scope,
+          source: item.source,
+          syncedAt: item.syncedAt,
+          completeness: normalizeCompletenessList(item.completeness),
+        },
+        null,
+        2
+      )}\n`
+    );
+    ensureFileWithDefault(item.paths.spec, buildDefaultSpecContent(item));
+    ensureFileWithDefault(item.paths.stateMap, buildDefaultStateMapContent(item));
+    ensureFileWithDefault(item.paths.raw, buildDefaultRawContent(item));
+  }
+
+  function ensureEntryFilesAndHook(cacheKey, item) {
+    ensureEntryFiles(item);
+    runPostEnsureHook(cacheKey, item);
+  }
+
+  return {
+    ensureEntryFilesAndHook,
+  };
+}
+
+module.exports = {
+  createEntryFilesService,
+};