@mp3wizard/figma-console-mcp 1.25.1 → 1.28.2

package/dist/cloudflare/core/tokens/formatters/tokens-studio.js

@@ -0,0 +1,250 @@
+/**
+ * Tokens Studio for Figma JSON formatter.
+ *
+ * Tokens Studio uses a multi-file layout:
+ *
+ *   $themes.json      — array of theme definitions with selectedTokenSets
+ *   $metadata.json    — list of token set names + tokenSetOrder
+ *   primitives.json   — one file per token set
+ *   semantic.json
+ *   theme/light.json
+ *   theme/dark.json
+ *
+ * Each per-set file holds tokens with the Tokens Studio shape:
+ *
+ *   {
+ *     "color": {
+ *       "primary": {
+ *         "value": "#4085F2",
+ *         "type": "color",
+ *         "description": "Primary brand color"
+ *       }
+ *     }
+ *   }
+ *
+ * Tokens Studio uses bare `value` / `type` (no `$` prefix — same as
+ * Style Dictionary v3, which the plugin's format is based on). Aliases
+ * use `{path.to.token}` syntax.
+ *
+ * `$themes.json` carries the Figma collection/mode bindings that make
+ * Tokens Studio's "send to Figma" feature work — preserved here for
+ * round-trip with Tokens Studio plugin users (notably Altitude).
+ *
+ * Output strategy:
+ *   - One file per TokenSet, named after the set (slugified).
+ *   - Multi-mode sets emit one file per (set, mode) pair (Tokens Studio
+ *     convention).
+ *   - `$metadata.json` enumerates the token set names in order.
+ *   - `$themes.json` builds a theme entry per mode with selectedTokenSets
+ *     and the figma-console-mcp metadata stamped onto it.
+ */
+import { FIGMA_MCP_EXTENSION_KEY } from "../types.js";
+export function formatTokensStudio(doc, opts) {
+    const warnings = [];
+    const files = [];
+    // Track which (setName, mode) → filename pairs exist so $metadata + $themes
+    // can reference them.
+    const setNamesByMode = [];
+    // 1. Per-set per-mode token files.
+    for (const set of doc.sets) {
+        for (const mode of set.modes) {
+            const fileSetName = set.modes.length > 1 ? `${slugify(set.name)}/${slugify(mode)}` : slugify(set.name);
+            const filename = `${fileSetName}.json`;
+            setNamesByMode.push({ setName: fileSetName, mode, filename });
+            files.push({
+                path: filename,
+                content: renderSetFile(set, mode, warnings),
+            });
+        }
+    }
+    // 2. $metadata.json — ordered list of token sets.
+    const tokenSetOrder = setNamesByMode.map((e) => e.setName);
+    files.push({
+        path: "$metadata.json",
+        content: JSON.stringify({ tokenSetOrder }, null, 2) + "\n",
+    });
+    // 3. $themes.json — one theme entry per mode, with figma-console-mcp
+    //    metadata so the Tokens Studio plugin's Figma sync features know
+    //    which Figma collection/mode each theme maps to.
+    const themes = buildThemes(doc, setNamesByMode);
+    files.push({
+        path: "$themes.json",
+        content: JSON.stringify(themes, null, 2) + "\n",
+    });
+    return { files, warnings };
+}
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Render a single set's tokens for a specific mode in Tokens Studio's
+ * bare-key JSON format.
+ */
+function renderSetFile(set, mode, warnings) {
+    const tree = {};
+    for (const token of set.tokens) {
+        const value = token.values[mode];
+        if (!value)
+            continue;
+        const tsValue = tsValueFor(value, token, warnings);
+        if (tsValue === undefined)
+            continue;
+        // Walk path creating nested groups.
+        let cursor = tree;
+        for (let i = 0; i < token.path.length - 1; i++) {
+            const segment = token.path[i];
+            if (!cursor[segment] || typeof cursor[segment] !== "object") {
+                cursor[segment] = {};
+            }
+            cursor = cursor[segment];
+        }
+        const leafKey = token.path[token.path.length - 1];
+        const leaf = {
+            value: tsValue,
+            type: tsTypeFor(token),
+        };
+        if (token.description)
+            leaf.description = token.description;
+        cursor[leafKey] = leaf;
+    }
+    return JSON.stringify(sortKeys(tree), null, 2) + "\n";
+}
+/**
+ * Build the $themes.json structure. One theme entry per (set, mode) tuple.
+ * For multi-mode sets, the theme name combines set + mode.
+ */
+function buildThemes(doc, setNamesByMode) {
+    const themes = [];
+    // Group by mode so each mode gets one theme entry pulling in the
+    // appropriate set files.
+    const allModes = new Set();
+    for (const e of setNamesByMode)
+        allModes.add(e.mode);
+    for (const mode of allModes) {
+        const selectedTokenSets = {};
+        for (const e of setNamesByMode) {
+            if (e.mode === mode) {
+                selectedTokenSets[e.setName] = "enabled";
+            }
+            else {
+                // Other-mode sets are disabled in this theme (Tokens Studio
+                // convention: only one mode of each set is "enabled" per theme).
+                selectedTokenSets[e.setName] = "source";
+            }
+        }
+        // Find the Figma collection + mode IDs for this mode (preserved
+        // from the export converter's $extensions metadata).
+        const figmaCollectionId = findCollectionIdForMode(doc, mode);
+        const figmaModeId = findModeId(doc, mode);
+        const theme = {
+            id: `${slugify(mode)}-${Math.random().toString(36).slice(2, 10)}`,
+            name: mode,
+            selectedTokenSets,
+        };
+        // Stash Figma metadata for round-trip with Tokens Studio plugin.
+        if (figmaCollectionId)
+            theme.$figmaCollectionId = figmaCollectionId;
+        if (figmaModeId)
+            theme.$figmaModeId = figmaModeId;
+        // Also stash our own extension namespace for tools that read it.
+        if (figmaCollectionId || figmaModeId) {
+            theme.$extensions = {
+                [FIGMA_MCP_EXTENSION_KEY]: {
+                    ...(figmaCollectionId ? { figmaCollectionId } : {}),
+                    ...(figmaModeId ? { figmaModeId } : {}),
+                },
+            };
+        }
+        themes.push(theme);
+    }
+    return themes;
+}
+function findCollectionIdForMode(doc, _mode) {
+    // The mode-to-collection mapping requires knowing which set the mode
+    // belongs to. For simplicity, return the first collection ID we find;
+    // multi-collection support requires per-set theme entries which the
+    // Tokens Studio plugin does support.
+    for (const set of doc.sets) {
+        if (set.meta?.figmaCollectionId)
+            return set.meta.figmaCollectionId;
+    }
+    return undefined;
+}
+function findModeId(_doc, _mode) {
+    // We don't carry Figma's modeId through the internal model in this
+    // version — it's computed lazily during apply via the
+    // (collectionId, modeName) lookup map. Future enhancement: stash the
+    // modeId in TokenSet.meta during export so it round-trips through
+    // Tokens Studio.
+    return undefined;
+}
+/**
+ * Map DTCG types to Tokens Studio's type names. Tokens Studio uses SD-style
+ * type names with some additions (e.g. "sizing", "borderRadius",
+ * "boxShadow", "typography", "opacity", "fontFamilies", "fontWeights").
+ */
+function tsTypeFor(token) {
+    if (token.type === "color")
+        return "color";
+    if (token.type === "fontFamily")
+        return "fontFamilies";
+    if (token.type === "fontWeight")
+        return "fontWeights";
+    if (token.type === "typography")
+        return "typography";
+    if (token.type === "shadow")
+        return "boxShadow";
+    if (token.type === "duration")
+        return "time";
+    if (token.type === "dimension") {
+        const lower = token.path[0]?.toLowerCase() ?? "";
+        if (lower.includes("border") || lower.includes("radius"))
+            return "borderRadius";
+        if (lower.startsWith("space") || lower.startsWith("spacing"))
+            return "spacing";
+        if (lower.includes("size") || lower.includes("width") || lower.includes("height"))
+            return "sizing";
+        return "sizing";
+    }
+    return token.type;
+}
+function tsValueFor(value, token, warnings) {
+    if (value.reference) {
+        const bare = value.reference.replace(/^\{|\}$/g, "");
+        if (bare.startsWith("__library:") || bare === "unknown") {
+            warnings.push(`Skipped ${token.path.join(".")} in Tokens Studio — cross-library alias unresolved.`);
+            return undefined;
+        }
+        return `{${bare}}`;
+    }
+    if (value.literal === undefined || value.literal === null)
+        return undefined;
+    if (typeof value.literal === "number" && token.type === "dimension") {
+        return `${value.literal}px`;
+    }
+    return value.literal;
+}
+function sortKeys(node) {
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+        return node;
+    }
+    const obj = node;
+    const sorted = {};
+    // $-prefixed keys first (matches Tokens Studio convention), then alphabetical.
+    const keys = Object.keys(obj).sort((a, b) => {
+        const aDollar = a.startsWith("$");
+        const bDollar = b.startsWith("$");
+        if (aDollar && !bDollar)
+            return -1;
+        if (!aDollar && bDollar)
+            return 1;
+        return a.localeCompare(b);
+    });
+    for (const k of keys)
+        sorted[k] = sortKeys(obj[k]);
+    return sorted;
+}

package/dist/cloudflare/core/tokens/formatters/ts-module.js

@@ -0,0 +1,198 @@
+/**
+ * TypeScript module formatter.
+ *
+ * Output shape:
+ *
+ *   // tokens.ts
+ *   export const tokens = {
+ *     color: {
+ *       primary: "#4085F2",
+ *       brand: { primary: "#FF00AA" }
+ *     },
+ *     spacing: {
+ *       md: "16px"
+ *     }
+ *   } as const;
+ *
+ *   export type Tokens = typeof tokens;
+ *
+ * Multi-mode tokens emit as nested objects keyed by mode name:
+ *
+ *   export const tokens = {
+ *     mode: {
+ *       primary: { Light: "#FFFFFF", Dark: "#000000" }
+ *     }
+ *   } as const;
+ *
+ * Aliases get resolved at write time to the literal value (TypeScript
+ * can't natively express references). Cross-library aliases get emitted
+ * as `null` with a "TODO: cross-library alias unresolved" comment so
+ * consumers see the gap.
+ */
+import { buildTokenIndex, resolveAliasChain } from "../alias-resolver.js";
+export function formatTsModule(doc, opts) {
+    const warnings = [];
+    const files = [];
+    const splitByCollection = opts.target.splitByCollection ?? false;
+    // splitByMode doesn't make conceptual sense for a TypeScript module
+    // (the value is held in-memory at runtime, not selected by CSS cascade).
+    // TypeScript modules can't natively express alias references — runtime
+    // code reading tokens.color.X gets a string at runtime, no resolution
+    // logic. Build a document-wide token index so aliases resolve to their
+    // literal target at export time. The index spans every set even when
+    // splitByCollection writes single-set files, because aliases often
+    // cross set boundaries (semantic → primitives).
+    const tokenIndex = buildTokenIndex(doc);
+    if (splitByCollection) {
+        for (const set of doc.sets) {
+            files.push({
+                path: filenameFor(opts, set),
+                content: renderTsFile([set], opts, tokenIndex, warnings),
+            });
+        }
+    }
+    else {
+        files.push({
+            path: filenameFor(opts),
+            content: renderTsFile(doc.sets, opts, tokenIndex, warnings),
+        });
+    }
+    return { files, warnings };
+}
+function filenameFor(opts, set) {
+    if (opts.target.filename)
+        return opts.target.filename;
+    if (set)
+        return `${slugify(set.name)}.tokens.ts`;
+    return "tokens.ts";
+}
+function slugify(s) {
+    return s
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Convert a path segment to a valid JS identifier or quoted-key form.
+ * Numeric leading chars, hyphens, etc. → quoted string key.
+ */
+function jsKey(segment) {
+    if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(segment))
+        return segment;
+    return JSON.stringify(segment);
+}
+function renderTsFile(sets, opts, tokenIndex, warnings) {
+    const prefix = opts.target.prefix ?? "";
+    const lines = [];
+    lines.push("/**");
+    lines.push(" * Generated by figma-console-mcp — do not edit by hand.");
+    lines.push(" * Regenerate with: figma_export_tokens (or your npm tokens:export script)");
+    lines.push(" */");
+    lines.push("");
+    const constName = prefix
+        ? `${prefix.replace(/-+$/, "").replace(/-(\w)/g, (_, c) => c.toUpperCase())}Tokens`
+        : "tokens";
+    // Build the nested object structure by walking each set's tokens.
+    const tree = {};
+    for (const set of sets) {
+        for (const token of set.tokens) {
+            writeTokenIntoTree(tree, token, set, tokenIndex, warnings);
+        }
+    }
+    lines.push(`export const ${constName} = ${renderTree(tree, 0)} as const;`);
+    lines.push("");
+    lines.push(`export type ${constName[0].toUpperCase()}${constName.slice(1)} = typeof ${constName};`);
+    lines.push("");
+    return lines.join("\n");
+}
+function writeTokenIntoTree(tree, token, set, tokenIndex, warnings) {
+    let cursor = tree;
+    for (let i = 0; i < token.path.length - 1; i++) {
+        const segment = token.path[i];
+        let next = cursor[segment];
+        if (!next || isLeaf(next)) {
+            next = {};
+            cursor[segment] = next;
+        }
+        cursor = next;
+    }
+    const leafKey = token.path[token.path.length - 1];
+    const isMulti = set.modes.length > 1;
+    const resolvedValues = {};
+    for (const [modeName, value] of Object.entries(token.values)) {
+        let effective = value;
+        if (value.reference) {
+            effective = resolveAliasChain(value, modeName, tokenIndex);
+            if (!effective) {
+                const bare = value.reference.replace(/^\{|\}$/g, "");
+                const reason = bare.startsWith("__library:") || bare === "unknown"
+                    ? "cross-library alias"
+                    : "alias target not found";
+                warnings.push(`Skipped ${token.path.join(".")} (mode "${modeName}") in TS module — ${reason}: ${value.reference}.`);
+                resolvedValues[modeName] = null;
+                continue;
+            }
+        }
+        if (!effective || effective.literal === undefined || effective.literal === null)
+            continue;
+        resolvedValues[modeName] = formatLiteral(effective.literal, token.type);
+    }
+    cursor[leafKey] = {
+        __leaf: true,
+        values: resolvedValues,
+        type: token.type,
+        isMultiMode: isMulti,
+        description: token.description,
+    };
+}
+function isLeaf(node) {
+    return node.__leaf === true;
+}
+function renderTree(tree, indent) {
+    const ind = "  ".repeat(indent);
+    const innerInd = "  ".repeat(indent + 1);
+    const entries = [];
+    for (const [key, value] of Object.entries(tree)) {
+        const k = jsKey(key);
+        if (isLeaf(value)) {
+            const leaf = value;
+            if (leaf.isMultiMode) {
+                // Emit as { Mode: value } object
+                const modeEntries = [];
+                for (const [m, v] of Object.entries(leaf.values)) {
+                    modeEntries.push(`${jsKey(m)}: ${renderValue(v)}`);
+                }
+                entries.push(`${innerInd}${k}: { ${modeEntries.join(", ")} }`);
+            }
+            else {
+                // Single-mode: emit value directly
+                const onlyValue = Object.values(leaf.values)[0];
+                entries.push(`${innerInd}${k}: ${renderValue(onlyValue)}`);
+            }
+        }
+        else {
+            entries.push(`${innerInd}${k}: ${renderTree(value, indent + 1)}`);
+        }
+    }
+    if (entries.length === 0)
+        return "{}";
+    return `{\n${entries.join(",\n")},\n${ind}}`;
+}
+function renderValue(v) {
+    if (v === null)
+        return "null /* TODO: cross-library alias unresolved */";
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return JSON.stringify(v);
+}
+function formatLiteral(value, type) {
+    if (typeof value === "number") {
+        if (type === "dimension")
+            return `${value}px`;
+        return value;
+    }
+    return value;
+}

package/dist/cloudflare/core/tokens/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public surface of the token sync engine.
+ *
+ * Re-exports the canonical types, the parser/formatter dispatchers, the
+ * config loader, the alias resolver, and the Figma converter. External
+ * callers (tools, tests) should import from here rather than reaching into
+ * subdirectories.
+ */
+export { FIGMA_MCP_EXTENSION_KEY } from "./types.js";
+export { TokensConfigSchema, loadTokensConfig, findTokensConfig, DEFAULT_TOKENS_CONFIG, buildSuggestedScaffold, resolveOutputTargets, resolveConflictStrategy, } from "./config.js";
+export { ExportTokensInputSchema, ImportTokensInputSchema, ExportFormatSchema, ImportFormatSchema, SyncStrategySchema, ConflictResolutionSchema, } from "./schemas.js";
+export { parse, detectFormat, } from "./parsers/index.js";
+export { format, } from "./formatters/index.js";
+export { buildTokenIndex, resolveReference, resolveAliasChain, validateAliases, formatDtcgReference, parseDtcgReference, } from "./alias-resolver.js";
+export { convertFigmaVariablesToDocument, } from "./figma-converter.js";

package/dist/cloudflare/core/tokens/parsers/css-vars.js

@@ -0,0 +1,4 @@
+import { TokenFormatNotImplementedError } from "./stubs.js";
+export function parseCssVars(_input) {
+    throw new TokenFormatNotImplementedError("CSS custom properties", "parser");
+}