@muloka/figma-console-mcp 0.1.0

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

@@ -0,0 +1,294 @@
+/**
+ * tokens.config.json schema, loader, and autodiscovery for the figma-console-mcp
+ * token sync engine.
+ *
+ * Both figma_export_tokens and figma_import_tokens read this single config so
+ * follow-up calls in a project are zero-arg. Autodiscovery walks up from the
+ * current working directory looking for `tokens.config.json` at each level
+ * — same convention as `tsconfig.json`, `package.json`, `.eslintrc`, etc.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+/**
+ * Schema for a single output target in `tokens.config.json`. Each entry
+ * produces one or more files when figma_export_tokens runs.
+ */
+const OutputTargetSchema = z.object({
+    format: z.enum([
+        "dtcg",
+        "tokens-studio",
+        "css-vars",
+        "tailwind-v4",
+        "tailwind-v3",
+        "scss",
+        "less",
+        "ts-module",
+        "json-flat",
+        "json-nested",
+        "style-dictionary-v3",
+    ]),
+    /** Optional filename override. Default is derived from format + scope. */
+    filename: z.string().optional(),
+    /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+    prefix: z.string().optional(),
+    /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+    splitByMode: z.boolean().optional(),
+    /** Emit one file per token set / Figma collection. */
+    splitByCollection: z.boolean().optional(),
+    /**
+     * If true, alias references are resolved to literal values in the output.
+     * If false, aliases are preserved (default for JSON formats, forced true
+     * for CSS/SCSS/Tailwind/etc. since they can't natively express aliases).
+     */
+    resolveAliases: z.boolean().optional(),
+    /**
+     * DTCG dialect for dtcg/json outputs. 'legacy' (default): hex-string
+     * colors and bare-number dimensions, maximum compatibility (Style
+     * Dictionary v4, Tokens Studio). '2025': DTCG 2025.10 object colors
+     * ({ colorSpace, components, alpha?, hex }) and dimensions
+     * ({ value, unit }) for Style Dictionary v5+ and other 2025.10-aware
+     * tooling. Ignored by css/scss/tailwind/ts formatters, which render
+     * final code.
+     */
+    dtcgDialect: z.enum(["legacy", "2025"]).optional(),
+    /** Per-target transform options. Override the global defaults. */
+    transforms: z
+        .object({
+        colorFormat: z.enum(["hex", "hex8", "rgba", "oklch", "hsl"]).optional(),
+        sizeUnit: z.enum(["px", "rem", "pt", "dp"]).optional(),
+        remBase: z.number().positive().optional(),
+    })
+        .optional(),
+});
+/**
+ * Full schema for `tokens.config.json`. Every field is optional so the
+ * minimum-viable config is `{ "figmaFile": "..." }` — the rest gets sensible
+ * defaults.
+ */
+export const TokensConfigSchema = z
+    .object({
+    /** Optional JSON Schema URL for editor autocompletion. */
+    $schema: z.string().optional(),
+    /**
+     * Figma file URL or fileKey. When omitted, tools fall back to the
+     * currently-connected Desktop Bridge plugin's file (Local Mode) or the
+     * file context bound by figma_pair_plugin (Cloud Mode).
+     */
+    figmaFile: z.string().optional(),
+    /** Where the canonical (committed) token sources live. */
+    source: z
+        .object({
+        /** Directory holding the canonical token files. */
+        dir: z.string(),
+        /** Glob pattern within dir. Default: "*.tokens.json" */
+        pattern: z.string().optional(),
+        /**
+         * Canonical format for source files. DTCG is the recommended default;
+         * Tokens Studio is supported for users who already have a `$themes.json`
+         * setup (e.g. Altitude).
+         */
+        canonical: z.enum(["dtcg", "tokens-studio"]).default("dtcg"),
+    })
+        .default({ dir: "src/styles/tokens", canonical: "dtcg" }),
+    /** Where build outputs (CSS, Tailwind, etc.) get written. */
+    generated: z
+        .object({
+        dir: z.string().default("src/styles/generated"),
+        formats: z.array(OutputTargetSchema).default([]),
+    })
+        .optional(),
+    /** Mode name mappings (Figma mode name → output mode name). */
+    modes: z
+        .object({
+        /** e.g. { "Light": "light", "Dark": "dark" } */
+        map: z.record(z.string()).optional(),
+        /** Default mode if a token has no explicit mode (e.g. "Light"). */
+        default: z.string().optional(),
+    })
+        .optional(),
+    /** Default conflict-resolution strategy when not specified per-call. */
+    conflictResolution: z
+        .enum(["ask", "figma-wins", "code-wins", "skip"])
+        .default("ask"),
+    /** Behavior for tokens that exist on one side but not the other. */
+    sync: z
+        .object({
+        onMissingInCode: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+        onMissingInFigma: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * Walk up from `startDir` looking for `tokens.config.json`. Returns the first
+ * match, or `null` if none found by the filesystem root.
+ */
+export function findTokensConfig(startDir) {
+    let dir = resolve(startDir);
+    // Hard cap on directory traversal so a misconfigured startDir can't loop
+    // forever (defense against symlinks/weird filesystems).
+    const maxDepth = 32;
+    for (let i = 0; i < maxDepth; i++) {
+        const candidate = join(dir, "tokens.config.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            // Hit filesystem root, no config found.
+            return null;
+        }
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Load and validate `tokens.config.json`. If `explicitPath` is provided, uses
+ * that; otherwise autodiscovers by walking up from `cwd` (default
+ * `process.cwd()`).
+ *
+ * Returns `null` if no config is found AND no explicit path was given. Throws
+ * if an explicit path doesn't exist, or if the discovered file fails schema
+ * validation.
+ */
+export function loadTokensConfig(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const configPath = opts.explicitPath
+        ? resolve(opts.explicitPath)
+        : findTokensConfig(cwd);
+    if (!configPath)
+        return null;
+    if (!existsSync(configPath)) {
+        throw new Error(`[figma-console-mcp] tokens.config.json not found at ${configPath}`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = TokensConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  • ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} failed validation:\n${issues}`);
+    }
+    return {
+        config: result.data,
+        configPath,
+        projectRoot: dirname(configPath),
+    };
+}
+/**
+ * Default config used when none is found. Drives the "no-config detected"
+ * response shape from figma_export_tokens — the AI uses this to propose a
+ * scaffold to the user.
+ */
+export const DEFAULT_TOKENS_CONFIG = {
+    source: { dir: "src/styles/tokens", canonical: "dtcg" },
+    generated: {
+        dir: "src/styles/generated",
+        formats: [
+            { format: "css-vars", splitByMode: true },
+        ],
+    },
+    conflictResolution: "ask",
+};
+/**
+ * Build a `suggestedScaffold` payload returned when a tool is called and no
+ * `tokens.config.json` exists. The AI presents this scaffold to the user,
+ * writes the files via its native edit/write tools, then calls the original
+ * tool again.
+ */
+export function buildSuggestedScaffold(opts) {
+    const config = {
+        $schema: "https://figma-console-mcp.southleft.com/schemas/tokens.config.v1.json",
+        source: { dir: "src/styles/tokens", canonical: "dtcg" },
+        generated: {
+            dir: "src/styles/generated",
+            formats: pickStartingFormats(opts.detectedFramework),
+        },
+        conflictResolution: "ask",
+    };
+    const stylesheetImport = pickStylesheetImport(opts.detectedFramework);
+    return {
+        configContent: JSON.stringify(config, null, 2),
+        directories: [config.source.dir, config.generated?.dir ?? "src/styles/generated"],
+        stylesheetImport,
+        nextSteps: [
+            "1. Write `tokens.config.json` at the project root using `configContent`.",
+            `2. Create the directories: ${config.source.dir} and ${config.generated?.dir}.`,
+            `3. Add this line to your main stylesheet:\n     ${stylesheetImport}`,
+            "4. Run `figma_export_tokens` again — it'll pick up the new config and populate the source dir.",
+        ].join("\n"),
+    };
+}
+function pickStartingFormats(framework) {
+    // Always emit DTCG as the canonical committed source; layer the
+    // framework-appropriate runtime format on top.
+    const base = [];
+    switch (framework) {
+        case "tailwind-v4":
+            base.push({ format: "tailwind-v4", splitByMode: true });
+            break;
+        case "tailwind-v3":
+            base.push({ format: "tailwind-v3" });
+            break;
+        case "scss":
+            base.push({ format: "scss", splitByMode: true });
+            break;
+        case "ts":
+            base.push({ format: "ts-module" });
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+        case "css":
+        default:
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+    }
+    return base;
+}
+function pickStylesheetImport(framework) {
+    switch (framework) {
+        case "tailwind-v4":
+            return "@import './styles/generated/tailwind.theme.css';";
+        case "scss":
+            return "@use './styles/generated/tokens.scss' as *;";
+        case "ts":
+        case "css":
+        default:
+            return "@import './styles/generated/tokens.css';";
+    }
+}
+/**
+ * Pick the export formats from a loaded config that map to a given runtime
+ * format. Used by figma_export_tokens to decide which generated files to
+ * write. Returns the list verbatim if the caller passed an explicit format.
+ */
+export function resolveOutputTargets(config, explicitFormat) {
+    if (explicitFormat) {
+        // Caller specified a format directly; ignore config's generated list.
+        return [{ format: explicitFormat }];
+    }
+    if (!config?.generated?.formats?.length) {
+        // No formats configured. Default to DTCG only — produces the canonical
+        // source files but no derived runtime outputs.
+        return [{ format: "dtcg" }];
+    }
+    return config.generated.formats;
+}
+/**
+ * Resolve the conflict-resolution strategy. Per-call argument wins over config
+ * default, which wins over the global default ("ask").
+ */
+export function resolveConflictStrategy(config, perCall) {
+    return perCall ?? config?.conflictResolution ?? "ask";
+}

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

@@ -0,0 +1,232 @@
+/**
+ * DTCG dialect helpers — legacy vs 2025.10 value encodings.
+ *
+ * The token pipeline historically speaks the "legacy" DTCG dialect: colors
+ * as hex strings ("#4085F2"), FLOAT dimensions as bare numbers. The DTCG
+ * 2025.10 spec (https://tr.designtokens.org/format/) switched to object
+ * forms:
+ *
+ *   color     = { colorSpace: "srgb", components: [r, g, b], alpha?, hex? }
+ *   dimension = { value: number, unit: "px" | "rem" }
+ *   duration  = { value: number, unit: "ms" | "s" }   (we already emit this)
+ *
+ * Export stays legacy by default (downstream consumers depend on it) and
+ * opts into 2025 via the `dtcgDialect` option. Import accepts BOTH dialects
+ * unconditionally. This module centralizes:
+ *
+ *   - 2025 encoding helpers used by the dtcg/json formatters at render time
+ *   - dialect-agnostic canonicalization used by the import diff so a 2025
+ *     color object compares equal to the same color's legacy hex string
+ *     (both are quantized to 1/255 per channel, tolerating the 8-bit
+ *     precision loss inherent to hex)
+ *   - stripping of the transient `rawColor` field the converter carries on
+ *     COLOR TokenValues (full-precision floats for 2025 components) so it
+ *     never leaks into serialized output
+ */
+export function clamp01(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+function byteHex(f) {
+    return Math.round(clamp01(f) * 255)
+        .toString(16)
+        .padStart(2, "0");
+}
+/**
+ * Canonicalize any color-like literal to a lowercase 8-digit hex string
+ * (`#rrggbbaa`), or return null when the literal isn't recognizably a color.
+ *
+ * Accepts:
+ *   - hex strings: #rgb, #rrggbb, #rrggbbaa
+ *   - 2025.10 color objects with srgb (or unspecified) colorSpace +
+ *     3 numeric components (+ optional alpha)
+ *   - color objects with a hex fallback field (any colorSpace) + optional alpha
+ *
+ * Both the components form and the hex form quantize to 1 / 255 per channel,
+ * so a full-precision components array compares equal to the hex string the
+ * legacy pipeline derived from the same Figma floats.
+ */
+export function colorLiteralToCanonicalHex(literal) {
+    if (typeof literal === "string") {
+        const m = literal
+            .trim()
+            .match(/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+        if (!m)
+            return null;
+        let digits = m[1].toLowerCase();
+        if (digits.length === 3) {
+            digits = digits
+                .split("")
+                .map((c) => c + c)
+                .join("");
+        }
+        if (digits.length === 6)
+            digits += "ff";
+        return `#${digits}`;
+    }
+    if (literal && typeof literal === "object" && !Array.isArray(literal)) {
+        const o = literal;
+        const colorSpace = typeof o.colorSpace === "string" ? o.colorSpace : undefined;
+        const comps = o.components;
+        if ((colorSpace === undefined || colorSpace === "srgb") &&
+            Array.isArray(comps) &&
+            comps.length === 3 &&
+            comps.every((c) => typeof c === "number")) {
+            const [r, g, b] = comps;
+            const a = typeof o.alpha === "number" ? o.alpha : 1;
+            return `#${byteHex(r)}${byteHex(g)}${byteHex(b)}${byteHex(a)}`;
+        }
+        if (typeof o.hex === "string") {
+            const base = colorLiteralToCanonicalHex(o.hex);
+            if (!base)
+                return null;
+            if (typeof o.alpha === "number") {
+                return base.slice(0, 7) + byteHex(o.alpha);
+            }
+            return base;
+        }
+    }
+    return null;
+}
+/**
+ * Parse a hex color string to raw rgba floats (0–1). Returns null on
+ * anything that isn't a valid 3/6/8-digit hex string.
+ */
+export function hexToRawRgba(hex) {
+    const canonical = colorLiteralToCanonicalHex(hex);
+    if (!canonical)
+        return null;
+    const d = canonical.slice(1);
+    return {
+        r: parseInt(d.slice(0, 2), 16) / 255,
+        g: parseInt(d.slice(2, 4), 16) / 255,
+        b: parseInt(d.slice(4, 6), 16) / 255,
+        a: parseInt(d.slice(6, 8), 16) / 255,
+    };
+}
+/**
+ * Encode a color TokenValue in the DTCG 2025.10 object form.
+ *
+ * Prefers the converter's transient `rawColor` floats (full precision — NOT
+ * round-tripped through 8-bit hex); falls back to parsing a hex-string
+ * literal. Literals already in object form pass through verbatim. Returns
+ * null when the value can't be encoded (caller keeps the legacy rendering).
+ *
+ * `alpha` is emitted only when < 1; `hex` is always included as the interop
+ * courtesy field (#RRGGBB, alpha carried separately).
+ */
+export function colorValueTo2025(value) {
+    const lit = value.literal;
+    if (lit && typeof lit === "object" && !Array.isArray(lit)) {
+        // Already object-form (e.g. a re-exported 2025 document) — pass through.
+        const o = lit;
+        if ("colorSpace" in o || "components" in o || "hex" in o)
+            return o;
+        return null;
+    }
+    let floats = value.rawColor ?? null;
+    if (!floats && typeof lit === "string") {
+        floats = hexToRawRgba(lit);
+    }
+    if (!floats)
+        return null;
+    const { r, g, b, a } = floats;
+    return {
+        colorSpace: "srgb",
+        components: [r, g, b],
+        ...(a < 1 ? { alpha: a } : {}),
+        hex: `#${byteHex(r)}${byteHex(g)}${byteHex(b)}`.toUpperCase(),
+    };
+}
+/**
+ * Encode a dimension literal in the DTCG 2025.10 object form. The converter
+ * emits Figma FLOAT dimensions as bare unitless numbers conventionally
+ * interpreted as px (the same convention the css/json formatters use), so
+ * only bare finite numbers are converted; everything else (unit strings,
+ * pre-encoded objects) keeps its current rendering.
+ */
+export function dimensionLiteralTo2025(literal) {
+    if (typeof literal === "number" && Number.isFinite(literal)) {
+        return { value: literal, unit: "px" };
+    }
+    return null;
+}
+/**
+ * Normalize a TokenValue to a dialect-agnostic comparable form for diffing:
+ *
+ *   - the transient `rawColor` field is dropped (Figma-side values carry it;
+ *     parsed code-side values never do)
+ *   - color-like literals (hex strings OR 2025 color objects) normalize to a
+ *     lowercase 8-digit hex string, quantized to 1/255 per channel
+ *   - `{ value, unit }` objects with px/ms normalize to the bare number
+ *     ("s" converts to ms first), so `{value: 16, unit: "px"}` equals 16 and
+ *     `{value: 0.3, unit: "s"}` equals `{value: 300, unit: "ms"}`
+ *   - "16px"-style strings normalize to the bare number
+ *
+ * Conservative by design: anything not confidently recognized is returned
+ * unchanged (minus rawColor), falling back to the existing deep comparison.
+ */
+export function canonicalizeTokenValueForComparison(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return v;
+    const obj = v;
+    if (!("literal" in obj) && !("reference" in obj))
+        return v;
+    const { rawColor: _rawColor, ...rest } = obj;
+    if (rest.literal !== undefined) {
+        const hex = colorLiteralToCanonicalHex(rest.literal);
+        if (hex !== null)
+            return { ...rest, literal: hex };
+        const num = numericLiteralToCanonical(rest.literal);
+        if (num !== null)
+            return { ...rest, literal: num };
+    }
+    return rest;
+}
+/**
+ * Normalize dimension/duration-shaped literals to a bare comparable number:
+ *   - `{ value: n, unit: "px" | "ms" }` → n
+ *   - `{ value: n, unit: "s" }` → n * 1000 (canonical ms)
+ *   - `"16px"` strings → 16
+ * Returns null for everything else (including rem/em/% and objects with
+ * extra fields — those keep structural comparison).
+ */
+function numericLiteralToCanonical(literal) {
+    if (typeof literal === "string") {
+        const m = literal.trim().match(/^(-?(?:\d+\.?\d*|\.\d+))px$/i);
+        return m ? Number(m[1]) : null;
+    }
+    if (literal &&
+        typeof literal === "object" &&
+        !Array.isArray(literal) &&
+        Object.keys(literal).length === 2) {
+        const o = literal;
+        if (typeof o.value === "number" && typeof o.unit === "string") {
+            if (o.unit === "px" || o.unit === "ms")
+                return o.value;
+            if (o.unit === "s")
+                return o.value * 1000;
+        }
+    }
+    return null;
+}
+/**
+ * Return a copy of a mode-keyed TokenValue map with the transient `rawColor`
+ * field removed from every entry. Used wherever values get serialized
+ * (lastSyncedValue snapshots, diff-plan samples) so the transient field never
+ * appears in output — keeping legacy output byte-identical.
+ */
+export function stripRawColorFromValues(values) {
+    const out = {};
+    for (const [k, v] of Object.entries(values)) {
+        if (v && typeof v === "object" && "rawColor" in v) {
+            const { rawColor: _rawColor, ...rest } = v;
+            out[k] = rest;
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}