figma-cache-toolchain 1.4.3 → 1.4.5

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

@@ -0,0 +1,227 @@
+/* eslint-disable no-console */
+
+function slugifyFlowId(name) {
+  const raw = String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return raw || `flow-${Date.now()}`;
+}
+
+function ensureFlow(index, flowId, meta, normalizeIndexShape) {
+  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: [],
+    };
+  }
+  return normalized.flows[flowId];
+}
+
+function upsertFlowNode(index, flowId, cacheKey, normalizeIndexShape) {
+  const flow = ensureFlow(index, flowId, {}, normalizeIndexShape);
+  if (!flow.nodes.includes(cacheKey)) {
+    flow.nodes.push(cacheKey);
+  }
+  flow.updatedAt = new Date().toISOString();
+}
+
+function addFlowEdge(index, flowId, fromKey, toKey, type, note, normalizeIndexShape) {
+  const flow = ensureFlow(index, flowId, {}, normalizeIndexShape);
+  const edge = {
+    id: `${fromKey}->${toKey}:${type}:${Date.now()}`,
+    from: fromKey,
+    to: toKey,
+    type,
+    note: note || "",
+    createdAt: new Date().toISOString(),
+  };
+  flow.edges.push(edge);
+  flow.updatedAt = new Date().toISOString();
+}
+
+function handleFlowCommand(args, deps) {
+  const {
+    resolveFlowIdFromArgs,
+    parseCompletenessFromArgs,
+    normalizeIndexShape,
+    readIndex,
+    writeIndex,
+    normalizeFigmaUrl,
+    getItem,
+    upsertByUrl,
+    ensureEntryFilesAndHook,
+  } = deps;
+
+  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 }, normalizeIndexShape);
+    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 source = sourceArg ? sourceArg.split("=")[1] : "manual";
+    const { completeness } = parseCompletenessFromArgs(rest);
+    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, normalizeIndexShape);
+    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, normalizeIndexShape);
+    upsertFlowNode(index, flowId, to, normalizeIndexShape);
+    addFlowEdge(index, flowId, from, to, type, note, normalizeIndexShape);
+    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, normalizeIndexShape));
+    for (let i = 0; i < keys.length - 1; i += 1) {
+      addFlowEdge(index, flowId, keys[i], keys[i + 1], type, "", normalizeIndexShape);
+    }
+    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);
+}
+
+module.exports = {
+  handleFlowCommand,
+};

package/figma-cache/js/index-store.js

@@ -0,0 +1,86 @@
+/* eslint-disable no-console */
+
+function createIndexStore(options) {
+  const {
+    fs,
+    CACHE_DIR,
+    INDEX_PATH,
+    SCHEMA_VERSION,
+    NORMALIZATION_VERSION,
+  } = options;
+
+  function ensureCacheDir() {
+    if (!fs.existsSync(CACHE_DIR)) {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+  }
+
+  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 readIndex() {
+    ensureCacheDir();
+    if (!fs.existsSync(INDEX_PATH)) {
+      return buildEmptyIndex();
+    }
+    const raw = fs.readFileSync(INDEX_PATH, "utf8");
+    return normalizeIndexShape(JSON.parse(raw));
+  }
+
+  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 getItem(index, cacheKey) {
+    const normalized = normalizeIndexShape(index);
+    return normalized.items && normalized.items[cacheKey] ? normalized.items[cacheKey] : null;
+  }
+
+  return {
+    ensureCacheDir,
+    buildEmptyIndex,
+    normalizeIndexShape,
+    readIndex,
+    writeIndex,
+    getItem,
+  };
+}
+
+module.exports = {
+  createIndexStore,
+};

package/figma-cache/js/project-config.js

@@ -0,0 +1,97 @@
+/* eslint-disable no-console */
+
+function createProjectConfigService(deps) {
+  const {
+    fs,
+    path,
+    ROOT,
+    createRequire,
+    resolveMaybeAbsolutePath,
+    normalizeSlash,
+  } = deps;
+
+  /** @type {object | null} null = not loaded yet; after load always an object (possibly empty) */
+  let memoProjectConfig = null;
+  /** @type {string | null} */
+  let memoProjectConfigPath = null;
+
+  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;
+  }
+
+  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}`);
+    }
+  }
+
+  function getProjectConfigPath() {
+    return memoProjectConfigPath ? normalizeSlash(memoProjectConfigPath) : null;
+  }
+
+  return {
+    loadProjectConfig,
+    runPostEnsureHook,
+    getProjectConfigPath,
+  };
+}
+
+module.exports = {
+  createProjectConfigService,
+};

package/figma-cache/js/upsert-core.js

@@ -0,0 +1,156 @@
+/* eslint-disable no-console */
+
+function createUpsertService(deps) {
+  const {
+    URL,
+    NORMALIZATION_VERSION,
+    CACHE_BASE_FOR_STORAGE,
+    DEFAULT_COMPLETENESS,
+    normalizeCompletenessList,
+    normalizeIndexShape,
+    readIndex,
+    getItem,
+    writeIndex,
+  } = deps;
+
+  function resolveCompleteness(extra, oldItem) {
+    const normalizedExtra = normalizeCompletenessList(extra && extra.completeness);
+    if (
+      extra &&
+      Object.prototype.hasOwnProperty.call(extra, "completeness") &&
+      normalizedExtra.length
+    ) {
+      return normalizedExtra;
+    }
+    if (
+      extra &&
+      Object.prototype.hasOwnProperty.call(extra, "completeness") &&
+      Array.isArray(extra.completeness)
+    ) {
+      return [];
+    }
+    if (oldItem && Array.isArray(oldItem.completeness) && oldItem.completeness.length) {
+      return normalizeCompletenessList(oldItem.completeness);
+    }
+    return [...DEFAULT_COMPLETENESS];
+  }
+
+  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 {
+      throw new Error(`Invalid URL: ${inputUrl}`);
+    }
+
+    const hostOk = /(^|\.)figma\.com$/i.test(parsed.hostname);
+    if (!hostOk) {
+      throw new Error(`Non-Figma domain: ${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(`Cannot extract fileKey from path: ${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 buildUpsertItem(normalized, oldItem, extra, syncedAt) {
+    const mergedUrls = Array.from(
+      new Set([...(oldItem ? oldItem.originalUrls || [] : []), normalized.originalUrl])
+    );
+    return {
+      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,
+      completeness: resolveCompleteness(extra, oldItem),
+      source: (extra && extra.source) || (oldItem && oldItem.source) || "manual",
+    };
+  }
+
+  function previewUpsertByUrl(inputUrl, extra) {
+    const normalized = normalizeFigmaUrl(inputUrl);
+    const index = normalizeIndexShape(readIndex());
+    const oldItem = getItem(index, normalized.cacheKey);
+    const item = buildUpsertItem(normalized, oldItem, extra, new Date().toISOString());
+    return { normalized, item };
+  }
+
+  function upsertByUrl(inputUrl, extra) {
+    const normalized = normalizeFigmaUrl(inputUrl);
+    const index = normalizeIndexShape(readIndex());
+    const oldItem = getItem(index, normalized.cacheKey);
+    const item = buildUpsertItem(normalized, oldItem, extra, new Date().toISOString());
+
+    index.items = index.items || {};
+    index.items[normalized.cacheKey] = item;
+    writeIndex(index);
+    return { normalized, item };
+  }
+
+  return {
+    normalizeFigmaUrl,
+    previewUpsertByUrl,
+    upsertByUrl,
+  };
+}
+
+module.exports = {
+  createUpsertService,
+};