@mp3wizard/figma-console-mcp 1.22.6 → 1.25.1

package/dist/cloudflare/core/diff/diff-engine.js

@@ -0,0 +1,334 @@
+/**
+ * Diff engine — pure functions for comparing Figma file/node snapshots
+ * across two versions.
+ *
+ * Scope (v1):
+ *   - Page-structure diff (added/removed/renamed pages) from depth=1 file fetches
+ *   - Per-node diff for scoped fetches: name, description, children added/removed,
+ *     componentPropertyDefinitions changes (for COMPONENT_SET), boundVariables changes
+ *
+ * NOT in scope (deferred):
+ *   - Variable VALUE history (Figma REST does not expose this; planned forward
+ *     ledger will fill the gap going forward, never retroactively)
+ *   - Style-content diffs (only style add/remove via reachable styles map)
+ *   - Inside-fills/strokes binding diffs (top-level boundVariables only for v1)
+ */
+/**
+ * Compare two file documents (from /v1/files/:key?version=X with depth=1 or higher).
+ * Both arguments should be the `document` field of a Figma file response.
+ */
+export function diffPageStructure(fromDoc, toDoc) {
+    const fromPages = extractPages(fromDoc);
+    const toPages = extractPages(toDoc);
+    const fromById = new Map(fromPages.map((p) => [p.id, p]));
+    const toById = new Map(toPages.map((p) => [p.id, p]));
+    const added = [];
+    const removed = [];
+    const renamed = [];
+    for (const p of toPages) {
+        if (!fromById.has(p.id)) {
+            added.push(p);
+        }
+        else {
+            const old = fromById.get(p.id);
+            if (old.name !== p.name) {
+                renamed.push({ id: p.id, old_name: old.name, new_name: p.name });
+            }
+        }
+    }
+    for (const p of fromPages) {
+        if (!toById.has(p.id))
+            removed.push(p);
+    }
+    return {
+        pages_added: added,
+        pages_removed: removed,
+        pages_renamed: renamed,
+        summary: {
+            added: added.length,
+            removed: removed.length,
+            renamed: renamed.length,
+        },
+    };
+}
+function extractPages(doc) {
+    const children = doc?.children;
+    if (!Array.isArray(children))
+        return [];
+    return children
+        .filter((c) => c && typeof c.id === "string" && typeof c.name === "string")
+        .map((c) => ({ id: c.id, name: c.name }));
+}
+/**
+ * Diff a COMPONENT_SET's componentPropertyDefinitions map.
+ * Each definition is keyed by `propName#nodeId` in Figma's response.
+ */
+export function diffComponentPropertyDefinitions(fromDefs, toDefs) {
+    const from = fromDefs ?? {};
+    const to = toDefs ?? {};
+    const added = [];
+    const removed = [];
+    const typeChanged = [];
+    const defaultChanged = [];
+    for (const key of Object.keys(to)) {
+        const toDef = to[key];
+        if (!(key in from)) {
+            added.push({ name: key, type: toDef.type, default_value: toDef.defaultValue });
+        }
+        else {
+            const fromDef = from[key];
+            if (fromDef.type !== toDef.type) {
+                typeChanged.push({ name: key, from_type: fromDef.type, to_type: toDef.type });
+            }
+            if (!deepEqual(fromDef.defaultValue, toDef.defaultValue)) {
+                defaultChanged.push({
+                    name: key,
+                    from_default: fromDef.defaultValue,
+                    to_default: toDef.defaultValue,
+                });
+            }
+        }
+    }
+    for (const key of Object.keys(from)) {
+        if (!(key in to)) {
+            const fromDef = from[key];
+            removed.push({ name: key, type: fromDef.type, default_value: fromDef.defaultValue });
+        }
+    }
+    return {
+        added,
+        removed,
+        type_changed: typeChanged,
+        default_changed: defaultChanged,
+        summary: {
+            added: added.length,
+            removed: removed.length,
+            type_changed: typeChanged.length,
+            default_changed: defaultChanged.length,
+        },
+    };
+}
+/**
+ * Walk both node trees in parallel (matched by node id), comparing top-level
+ * boundVariables. Inside-fills/strokes binding diffs are explicitly NOT included
+ * in v1 — they add complexity for marginal additional value over node-level deltas.
+ */
+export function collectBindingChanges(fromNode, toNode) {
+    const changes = [];
+    walkBoth(fromNode, toNode, (a, b) => {
+        const aBindings = extractTopLevelBindings(a);
+        const bBindings = extractTopLevelBindings(b);
+        const allKeys = new Set([...Object.keys(aBindings), ...Object.keys(bBindings)]);
+        for (const key of allKeys) {
+            const fromId = aBindings[key] ?? null;
+            const toId = bBindings[key] ?? null;
+            if (fromId === toId)
+                continue;
+            let kind;
+            if (fromId === null)
+                kind = "added";
+            else if (toId === null)
+                kind = "removed";
+            else
+                kind = "rebound";
+            changes.push({
+                node_id: (b ?? a).id,
+                node_name: (b ?? a).name ?? "",
+                property: key,
+                from_variable_id: fromId,
+                to_variable_id: toId,
+                change_kind: kind,
+            });
+        }
+    });
+    return changes;
+}
+function extractTopLevelBindings(node) {
+    const out = {};
+    const bv = node?.boundVariables;
+    if (!bv || typeof bv !== "object")
+        return out;
+    for (const [prop, ref] of Object.entries(bv)) {
+        if (ref && typeof ref === "object") {
+            // Single VARIABLE_ALIAS reference
+            if (ref.type === "VARIABLE_ALIAS" && typeof ref.id === "string") {
+                out[prop] = ref.id;
+                continue;
+            }
+            // Array of refs (e.g., fills binding can be an array — surface first match for v1)
+            if (Array.isArray(ref)) {
+                const first = ref.find((r) => r && r.type === "VARIABLE_ALIAS" && typeof r.id === "string");
+                if (first)
+                    out[`${prop}[0]`] = first.id;
+            }
+        }
+    }
+    return out;
+}
+function walkBoth(fromNode, toNode, visit) {
+    if (!fromNode && !toNode)
+        return;
+    visit(fromNode, toNode);
+    const fromChildren = Array.isArray(fromNode?.children) ? fromNode.children : [];
+    const toChildren = Array.isArray(toNode?.children) ? toNode.children : [];
+    const byIdFrom = new Map();
+    for (const c of fromChildren)
+        if (c?.id)
+            byIdFrom.set(c.id, c);
+    const byIdTo = new Map();
+    for (const c of toChildren)
+        if (c?.id)
+            byIdTo.set(c.id, c);
+    const allIds = new Set([...byIdFrom.keys(), ...byIdTo.keys()]);
+    for (const id of allIds) {
+        walkBoth(byIdFrom.get(id), byIdTo.get(id), visit);
+    }
+}
+/**
+ * Diff a single node (typically a COMPONENT_SET) at depth=2. Either side may be
+ * null/undefined to represent "newly added" or "removed entirely."
+ */
+export function diffNode(fromNode, toNode, mode = "standard") {
+    const id = (toNode ?? fromNode)?.id ?? "";
+    const name = (toNode ?? fromNode)?.name ?? "";
+    const type = (toNode ?? fromNode)?.type ?? "";
+    const out = {
+        node_id: id,
+        node_name: name,
+        node_type: type,
+        name_changed: null,
+        description_changed: null,
+        children_added: [],
+        children_removed: [],
+        component_properties: null,
+        binding_changes: [],
+        change_count: 0,
+        notes: [],
+    };
+    if (!fromNode && toNode) {
+        out.notes.push("Node was added in the target version (no prior state to compare).");
+        out.change_count = 1;
+        return out;
+    }
+    if (fromNode && !toNode) {
+        out.notes.push("Node was removed in the target version (no later state to compare).");
+        out.change_count = 1;
+        return out;
+    }
+    if (!fromNode && !toNode) {
+        out.notes.push("Node not found in either version.");
+        return out;
+    }
+    if (fromNode.name !== toNode.name) {
+        out.name_changed = { from: fromNode.name, to: toNode.name };
+    }
+    if ((fromNode.description ?? "") !== (toNode.description ?? "")) {
+        out.description_changed = {
+            from: fromNode.description ?? "",
+            to: toNode.description ?? "",
+        };
+    }
+    const fromChildIds = new Set((fromNode.children ?? []).filter((c) => c?.id).map((c) => c.id));
+    const toChildIds = new Set((toNode.children ?? []).filter((c) => c?.id).map((c) => c.id));
+    for (const c of toNode.children ?? []) {
+        if (c?.id && !fromChildIds.has(c.id)) {
+            out.children_added.push({ id: c.id, name: c.name ?? "", type: c.type ?? "" });
+        }
+    }
+    for (const c of fromNode.children ?? []) {
+        if (c?.id && !toChildIds.has(c.id)) {
+            out.children_removed.push({ id: c.id, name: c.name ?? "", type: c.type ?? "" });
+        }
+    }
+    if (fromNode.type === "COMPONENT_SET" || toNode.type === "COMPONENT_SET") {
+        const propDiff = diffComponentPropertyDefinitions(fromNode.componentPropertyDefinitions, toNode.componentPropertyDefinitions);
+        const hasAny = propDiff.summary.added > 0 ||
+            propDiff.summary.removed > 0 ||
+            propDiff.summary.type_changed > 0 ||
+            propDiff.summary.default_changed > 0;
+        if (hasAny)
+            out.component_properties = propDiff;
+    }
+    out.binding_changes = collectBindingChanges(fromNode, toNode);
+    out.change_count =
+        (out.name_changed ? 1 : 0) +
+            (out.description_changed ? 1 : 0) +
+            out.children_added.length +
+            out.children_removed.length +
+            (out.component_properties
+                ? out.component_properties.summary.added +
+                    out.component_properties.summary.removed +
+                    out.component_properties.summary.type_changed +
+                    out.component_properties.summary.default_changed
+                : 0) +
+            out.binding_changes.length;
+    if (mode === "summary") {
+        // Strip detail arrays, keep counts only
+        out.children_added = [];
+        out.children_removed = [];
+        if (out.component_properties) {
+            out.component_properties = {
+                added: [],
+                removed: [],
+                type_changed: [],
+                default_changed: [],
+                summary: out.component_properties.summary,
+            };
+        }
+        out.binding_changes = [];
+    }
+    else if (mode === "standard") {
+        // Keep the lightweight summaries (children_added, children_removed,
+        // component_properties.summary). Strip the heavy detail arrays.
+        if (out.component_properties) {
+            out.component_properties = {
+                added: out.component_properties.added.map((p) => ({ ...p, default_value: undefined })),
+                removed: out.component_properties.removed.map((p) => ({
+                    ...p,
+                    default_value: undefined,
+                })),
+                type_changed: out.component_properties.type_changed,
+                default_changed: out.component_properties.default_changed.map((d) => ({
+                    name: d.name,
+                    from_default: undefined,
+                    to_default: undefined,
+                })),
+                summary: out.component_properties.summary,
+            };
+        }
+        // Bindings: keep as-is, they're already compact.
+    }
+    // mode === "detailed" → keep everything
+    return out;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!deepEqual(a[i], b[i]))
+                return false;
+        return true;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys)
+        if (!deepEqual(a[k], b[k]))
+            return false;
+    return true;
+}

package/dist/cloudflare/core/diff/property-compare.js

@@ -0,0 +1,36 @@
+/**
+ * Property comparison primitives.
+ *
+ * Pure helper functions used by both the design-code parity tools and
+ * the version diff engine. Moved here from src/core/design-code-tools.ts
+ * so multiple consumers can share without circular dependencies.
+ */
+/** Convert Figma RGBA (0-1 floats) to hex string */
+export function figmaRGBAToHex(color) {
+    const r = Math.round(color.r * 255);
+    const g = Math.round(color.g * 255);
+    const b = Math.round(color.b * 255);
+    const hex = `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
+    if (color.a !== undefined && color.a < 1) {
+        const a = Math.round(color.a * 255);
+        return `${hex}${a.toString(16).padStart(2, "0")}`;
+    }
+    return hex;
+}
+/** Normalize a color string for comparison (uppercase hex without alpha if fully opaque) */
+export function normalizeColor(color) {
+    let c = color.trim().toUpperCase();
+    // Strip alpha if fully opaque (FF)
+    if (c.length === 9 && c.endsWith("FF")) {
+        c = c.slice(0, 7);
+    }
+    // Expand shorthand (#RGB -> #RRGGBB)
+    if (/^#[0-9A-F]{3}$/.test(c)) {
+        c = `#${c[1]}${c[1]}${c[2]}${c[2]}${c[3]}${c[3]}`;
+    }
+    return c;
+}
+/** Compare numeric values with a tolerance */
+export function numericClose(a, b, tolerance = 1) {
+    return Math.abs(a - b) <= tolerance;
+}

package/dist/cloudflare/core/diff/version-cache.js

@@ -0,0 +1,74 @@
+/**
+ * In-memory LRU cache for Figma file snapshots at past versions.
+ *
+ * Past versions are immutable, so a cached snapshot for `${fileKey}:${versionId}`
+ * never goes stale. The cache is process-scoped (no persistence) and bounded by
+ * a max-entries cap rather than a byte budget — keeps the implementation simple
+ * and avoids assumptions about JSON serialization size.
+ *
+ * HEAD ("current") is intentionally NOT cached because it changes on every save.
+ * Callers should pass `null` as the versionId for HEAD requests; the cache
+ * methods short-circuit on null.
+ *
+ * Usage:
+ *   const cache = new VersionSnapshotCache();
+ *   const key = cache.makeKey(fileKey, versionId, depth, nodeIds);
+ *   let snapshot = cache.get(key);
+ *   if (!snapshot) {
+ *     snapshot = await api.getFile(fileKey, { version: versionId, depth });
+ *     cache.set(key, snapshot);
+ *   }
+ */
+export class VersionSnapshotCache {
+    constructor(options = {}) {
+        // Map preserves insertion order — first key is the LRU.
+        this.store = new Map();
+        this.maxEntries = options.maxEntries ?? 50;
+    }
+    /**
+     * Build a stable cache key from the request parameters.
+     * Returns null for HEAD requests (versionId is null/undefined/empty).
+     */
+    makeKey(fileKey, versionId, depth, nodeIds) {
+        if (!versionId)
+            return null;
+        const idsHash = nodeIds && nodeIds.length > 0
+            ? [...nodeIds].sort().join(",")
+            : "";
+        const depthPart = depth === undefined ? "full" : String(depth);
+        return `${fileKey}:${versionId}:${depthPart}:${idsHash}`;
+    }
+    get(key) {
+        if (key === null)
+            return undefined;
+        if (!this.store.has(key))
+            return undefined;
+        // Refresh recency: delete + re-insert moves the key to the end.
+        const value = this.store.get(key);
+        this.store.delete(key);
+        this.store.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (key === null)
+            return;
+        if (this.store.has(key))
+            this.store.delete(key);
+        this.store.set(key, value);
+        while (this.store.size > this.maxEntries) {
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.store.delete(oldestKey);
+        }
+    }
+    has(key) {
+        return key !== null && this.store.has(key);
+    }
+    get size() {
+        return this.store.size;
+    }
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/cloudflare/core/figma-api.js

@@ -308,6 +308,25 @@ export class FigmaAPI {
             method: 'DELETE',
         });
     }
+    /**
+     * GET /v1/files/:file_key/versions
+     * List a file's version history. Cursor-style pagination via before/after
+     * (cursors are version IDs). Response includes pagination.prev_page and
+     * pagination.next_page as full URLs — Figma recommends following those
+     * directly rather than reconstructing cursors. Requires the
+     * `file_versions:read` OAuth scope (or PAT "Versions" Read permission).
+     */
+    async getFileVersions(fileKey, options) {
+        const params = new URLSearchParams();
+        if (options?.page_size !== undefined)
+            params.set('page_size', String(options.page_size));
+        if (options?.before)
+            params.set('before', options.before);
+        if (options?.after)
+            params.set('after', options.after);
+        const query = params.toString() ? `?${params.toString()}` : '';
+        return this.request(`/files/${fileKey}/versions${query}`);
+    }
     /**
      * Helper: Get all design tokens (variables) with formatted output
      * Both local and published can fail gracefully (e.g., 403 without Enterprise plan)