@muloka/figma-console-mcp 0.1.0

package/dist/core/tokens/alias-resolver.js

@@ -0,0 +1,206 @@
+/**
+ * Alias reference resolution and validation.
+ *
+ * DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
+ * They can chain (an alias can reference another alias), but cycles are an
+ * error.
+ *
+ * This module:
+ *   - Resolves an alias to its eventual literal value (for formatters that
+ *     can't natively express references — CSS, SCSS, Tailwind).
+ *   - Validates that every alias points to an existing token.
+ *   - Detects cycles.
+ */
+/**
+ * Slugify a set/collection name into the key used for the top-level set
+ * group in DTCG output AND the set-qualifier prefix in alias references
+ * (`{<set-slug>.<path.to.token>}`). Must stay in sync with the DTCG
+ * formatter's group keys so emitted references resolve inside the file.
+ */
+export function slugifySetName(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Build a lookup map for alias resolution. Every token is indexed under its
+ * set-qualified key (`<set-slug>.<dot.path>` — the same shape the converter
+ * emits in references), and additionally under its bare dot-path
+ * (`color.primary`) when that bare path is unambiguous across sets.
+ *
+ * When two collections both contain the same bare path (e.g. two collections
+ * each defining `color/primary`), the bare key is NOT indexed — resolving a
+ * bare reference to "whichever set was indexed last" is exactly the
+ * cross-collection misresolution bug this guards against. Callers that pass
+ * a `warnings` array get one warning per ambiguous bare path.
+ */
+export function buildTokenIndex(doc, warnings) {
+    const index = new Map();
+    for (const [key, entry] of buildTokenLookup(doc, warnings)) {
+        index.set(key, entry.token);
+    }
+    return index;
+}
+/**
+ * Set-aware variant of buildTokenIndex — identical key scheme and ambiguity
+ * rules (set-qualified keys always; bare-path fallback only when unambiguous
+ * across sets), but each entry carries the owning set's name alongside the
+ * token. buildTokenIndex delegates to this so the two can never drift.
+ */
+export function buildTokenLookup(doc, warnings) {
+    const index = new Map();
+    // barePath → owning entries, used to detect cross-set ambiguity.
+    const bareOwners = new Map();
+    for (const set of doc.sets) {
+        const setKey = slugifySetName(set.name);
+        for (const token of set.tokens) {
+            const bare = token.path.join(".");
+            index.set(`${setKey}.${bare}`, { setName: set.name, token });
+            const owners = bareOwners.get(bare) ?? [];
+            owners.push({ setName: set.name, token });
+            bareOwners.set(bare, owners);
+        }
+    }
+    // Bare-path fallback: only when a path exists in exactly one set, and only
+    // when it doesn't shadow a set-qualified key that's already indexed.
+    for (const [bare, owners] of bareOwners) {
+        if (owners.length === 1) {
+            if (!index.has(bare))
+                index.set(bare, owners[0]);
+        }
+        else if (warnings) {
+            warnings.push(`Token path "${bare}" exists in multiple collections (${owners
+                .map((o) => `"${o.setName}"`)
+                .join(", ")}) — bare alias references to it are ambiguous and will not resolve. Use a set-qualified reference like {${slugifySetName(owners[0].setName)}.${bare}}.`);
+        }
+    }
+    return index;
+}
+/**
+ * Resolve a reference to the path segments of its TARGET token — for
+ * formatters that name-ify aliases (CSS `var(--...)`, SCSS `$...`,
+ * Tokens Studio / SD v3 `{...}` refs). Set-qualified references
+ * (`{set-slug.path.to.token}`) resolve to the target token's own path
+ * (WITHOUT the set qualifier), matching how those formatters name the
+ * target's declaration. Falls back to the raw reference path when the
+ * target isn't in the index (e.g. hand-written bare refs to tokens that
+ * weren't exported).
+ */
+export function referenceTargetPath(reference, index) {
+    const bare = reference.replace(/^\{|\}$/g, "");
+    const target = index.get(bare);
+    if (target)
+        return target.path;
+    return bare.split(".");
+}
+/**
+ * Resolve a single alias reference. Returns the eventual literal value, or
+ * throws if the reference is unresolvable or cyclic.
+ */
+export function resolveReference(reference, mode, index, seen = new Set()) {
+    // Strip the curly braces if present: "{color.primary}" → "color.primary"
+    const path = reference.replace(/^\{|\}$/g, "");
+    if (seen.has(path)) {
+        throw new Error(`[figma-console-mcp] Alias cycle detected: ${[...seen, path].join(" → ")}`);
+    }
+    seen.add(path);
+    const target = index.get(path);
+    if (!target) {
+        throw new Error(`[figma-console-mcp] Unresolvable alias reference: {${path}}`);
+    }
+    // Find the value for the requested mode; fall back to the only mode if
+    // there's just one (alias's target may be single-mode while the source
+    // is multi-mode, or vice versa).
+    const value = target.values[mode] ??
+        (Object.keys(target.values).length === 1
+            ? Object.values(target.values)[0]
+            : undefined);
+    if (!value) {
+        throw new Error(`[figma-console-mcp] Alias {${path}} has no value for mode "${mode}"`);
+    }
+    // Chain: if the target's value is itself an alias, recurse.
+    if (value.reference) {
+        return resolveReference(value.reference, mode, index, seen);
+    }
+    return value;
+}
+/**
+ * Resolve an alias chain to its final literal value, walking through
+ * intermediate alias hops. Returns the final TokenValue (with `literal` set
+ * if resolution succeeded) or `null` if the chain ends at a cross-library
+ * reference / unresolvable target / cycle.
+ *
+ * Used by formatters that can't natively express alias references in their
+ * output (Tailwind v3, TypeScript modules, plain JSON) — those need literal
+ * values at export time.
+ *
+ * Safer counterpart of `resolveReference` because it swallows errors
+ * (unresolvable / cycle) into `null` rather than throwing; formatters can
+ * then emit a comment or skip the token instead of failing the whole export.
+ */
+export function resolveAliasChain(value, mode, index) {
+    if (!value.reference)
+        return value;
+    // Cross-library aliases are not resolvable — formatters should skip with a comment.
+    const bare = value.reference.replace(/^\{|\}$/g, "");
+    if (bare.startsWith("__library:") || bare === "unknown")
+        return null;
+    try {
+        const resolved = resolveReference(value.reference, mode, index);
+        // resolveReference throws on cycles / unresolvable, so a returned value
+        // is either a literal or another reference. If still a reference,
+        // recurse (defensive — resolveReference already chases chains, but the
+        // top-level call may return a value with `reference` if mode-fallback
+        // routes through an aliased entry).
+        if (resolved.reference) {
+            return resolveAliasChain(resolved, mode, index);
+        }
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate every alias in the document. Returns a list of error messages —
+ * empty array means all aliases resolve cleanly.
+ */
+export function validateAliases(doc) {
+    const index = buildTokenIndex(doc);
+    const errors = [];
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            for (const [mode, value] of Object.entries(token.values)) {
+                if (value.reference) {
+                    try {
+                        resolveReference(value.reference, mode, index);
+                    }
+                    catch (err) {
+                        errors.push(`${token.path.join(".")} (mode "${mode}"): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
+ * syntax with curly braces.
+ */
+export function formatDtcgReference(referencePath) {
+    return `{${referencePath.join(".")}}`;
+}
+/**
+ * Parse a DTCG alias string back into a path array. Returns null if the
+ * string isn't an alias reference.
+ */
+export function parseDtcgReference(s) {
+    const match = s.match(/^\{([^}]+)\}$/);
+    if (!match)
+        return null;
+    return match[1].split(".");
+}
+//# sourceMappingURL=alias-resolver.js.map

package/dist/core/tokens/alias-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-resolver.js","sourceRoot":"","sources":["../../../src/core/tokens/alias-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI;SACR,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAkB,EAClB,QAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC3D,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAkB,EAClB,QAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAClD,iEAAiE;IACjE,MAAM,UAAU,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEzD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClC,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC7D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,qEAAqE;IACrE,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QACxC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC;aAAM,IAAI,QAAQ,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CACX,eAAe,IAAI,qCAAqC,MAAM;iBAC3D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC;iBAC5B,IAAI,CAAC,IAAI,CAAC,2GAA2G,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CACtK,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,KAAyB;IAEzB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,IAAY,EACZ,KAAyB,EACzB,OAAoB,IAAI,GAAG,EAAE;IAE7B,yEAAyE;IACzE,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE/C,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,6CAA6C,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAC3E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEf,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,sDAAsD,IAAI,GAAG,CAC9D,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,uEAAuE;IACvE,iCAAiC;IACjC,MAAM,KAAK,GACT,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACnB,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;YACtC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEjB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,4BAA4B,IAAI,GAAG,CACtE,CAAC;IACJ,CAAC;IAED,4DAA4D;IAC5D,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,IAAY,EACZ,KAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAEnC,oFAAoF;IACpF,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAErE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAChE,wEAAwE;QACxE,kEAAkE;QAClE,uEAAuE;QACvE,sEAAsE;QACtE,oCAAoC;QACpC,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,iBAAiB,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAkB;IAChD,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;YAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzD,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oBACpB,IAAI,CAAC;wBACH,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;oBACjD,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACb,MAAM,CAAC,IAAI,CACT,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,OACpC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAuB;IACzD,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAS;IAC1C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/core/tokens/config.d.ts

@@ -0,0 +1,380 @@
+/**
+ * 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 { z } from "zod";
+import type { ConflictResolution, ExportFormat } from "./types.js";
+/**
+ * Schema for a single output target in `tokens.config.json`. Each entry
+ * produces one or more files when figma_export_tokens runs.
+ */
+declare const OutputTargetSchema: z.ZodObject<{
+    format: z.ZodEnum<["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.ZodOptional<z.ZodString>;
+    /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+    prefix: z.ZodOptional<z.ZodString>;
+    /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+    splitByMode: z.ZodOptional<z.ZodBoolean>;
+    /** Emit one file per token set / Figma collection. */
+    splitByCollection: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * 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.ZodOptional<z.ZodBoolean>;
+    /**
+     * 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.ZodOptional<z.ZodEnum<["legacy", "2025"]>>;
+    /** Per-target transform options. Override the global defaults. */
+    transforms: z.ZodOptional<z.ZodObject<{
+        colorFormat: z.ZodOptional<z.ZodEnum<["hex", "hex8", "rgba", "oklch", "hsl"]>>;
+        sizeUnit: z.ZodOptional<z.ZodEnum<["px", "rem", "pt", "dp"]>>;
+        remBase: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    }, {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+    resolveAliases?: boolean | undefined;
+    filename?: string | undefined;
+    prefix?: string | undefined;
+    splitByMode?: boolean | undefined;
+    splitByCollection?: boolean | undefined;
+    dtcgDialect?: "legacy" | "2025" | undefined;
+    transforms?: {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    } | undefined;
+}, {
+    format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+    resolveAliases?: boolean | undefined;
+    filename?: string | undefined;
+    prefix?: string | undefined;
+    splitByMode?: boolean | undefined;
+    splitByCollection?: boolean | undefined;
+    dtcgDialect?: "legacy" | "2025" | undefined;
+    transforms?: {
+        colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+        sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+        remBase?: number | undefined;
+    } | undefined;
+}>;
+export type OutputTarget = z.infer<typeof OutputTargetSchema>;
+/**
+ * Full schema for `tokens.config.json`. Every field is optional so the
+ * minimum-viable config is `{ "figmaFile": "..." }` — the rest gets sensible
+ * defaults.
+ */
+export declare const TokensConfigSchema: z.ZodObject<{
+    /** Optional JSON Schema URL for editor autocompletion. */
+    $schema: z.ZodOptional<z.ZodString>;
+    /**
+     * 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.ZodOptional<z.ZodString>;
+    /** Where the canonical (committed) token sources live. */
+    source: z.ZodDefault<z.ZodObject<{
+        /** Directory holding the canonical token files. */
+        dir: z.ZodString;
+        /** Glob pattern within dir. Default: "*.tokens.json" */
+        pattern: z.ZodOptional<z.ZodString>;
+        /**
+         * 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.ZodDefault<z.ZodEnum<["dtcg", "tokens-studio"]>>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        canonical: "dtcg" | "tokens-studio";
+        pattern?: string | undefined;
+    }, {
+        dir: string;
+        pattern?: string | undefined;
+        canonical?: "dtcg" | "tokens-studio" | undefined;
+    }>>;
+    /** Where build outputs (CSS, Tailwind, etc.) get written. */
+    generated: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        formats: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            format: z.ZodEnum<["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.ZodOptional<z.ZodString>;
+            /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+            prefix: z.ZodOptional<z.ZodString>;
+            /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+            splitByMode: z.ZodOptional<z.ZodBoolean>;
+            /** Emit one file per token set / Figma collection. */
+            splitByCollection: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * 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.ZodOptional<z.ZodBoolean>;
+            /**
+             * 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.ZodOptional<z.ZodEnum<["legacy", "2025"]>>;
+            /** Per-target transform options. Override the global defaults. */
+            transforms: z.ZodOptional<z.ZodObject<{
+                colorFormat: z.ZodOptional<z.ZodEnum<["hex", "hex8", "rgba", "oklch", "hsl"]>>;
+                sizeUnit: z.ZodOptional<z.ZodEnum<["px", "rem", "pt", "dp"]>>;
+                remBase: z.ZodOptional<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            }, {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }, {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        formats: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[];
+    }, {
+        dir?: string | undefined;
+        formats?: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[] | undefined;
+    }>>;
+    /** Mode name mappings (Figma mode name → output mode name). */
+    modes: z.ZodOptional<z.ZodObject<{
+        /** e.g. { "Light": "light", "Dark": "dark" } */
+        map: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Default mode if a token has no explicit mode (e.g. "Light"). */
+        default: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    }, {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    }>>;
+    /** Default conflict-resolution strategy when not specified per-call. */
+    conflictResolution: z.ZodDefault<z.ZodEnum<["ask", "figma-wins", "code-wins", "skip"]>>;
+    /** Behavior for tokens that exist on one side but not the other. */
+    sync: z.ZodOptional<z.ZodObject<{
+        onMissingInCode: z.ZodDefault<z.ZodEnum<["preserve", "delete", "warn"]>>;
+        onMissingInFigma: z.ZodDefault<z.ZodEnum<["preserve", "delete", "warn"]>>;
+    }, "strip", z.ZodTypeAny, {
+        onMissingInCode: "warn" | "delete" | "preserve";
+        onMissingInFigma: "warn" | "delete" | "preserve";
+    }, {
+        onMissingInCode?: "warn" | "delete" | "preserve" | undefined;
+        onMissingInFigma?: "warn" | "delete" | "preserve" | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    source: {
+        dir: string;
+        canonical: "dtcg" | "tokens-studio";
+        pattern?: string | undefined;
+    };
+    conflictResolution: "ask" | "figma-wins" | "code-wins" | "skip";
+    sync?: {
+        onMissingInCode: "warn" | "delete" | "preserve";
+        onMissingInFigma: "warn" | "delete" | "preserve";
+    } | undefined;
+    modes?: {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    figmaFile?: string | undefined;
+    generated?: {
+        dir: string;
+        formats: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[];
+    } | undefined;
+}, {
+    sync?: {
+        onMissingInCode?: "warn" | "delete" | "preserve" | undefined;
+        onMissingInFigma?: "warn" | "delete" | "preserve" | undefined;
+    } | undefined;
+    source?: {
+        dir: string;
+        pattern?: string | undefined;
+        canonical?: "dtcg" | "tokens-studio" | undefined;
+    } | undefined;
+    modes?: {
+        map?: Record<string, string> | undefined;
+        default?: string | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    figmaFile?: string | undefined;
+    generated?: {
+        dir?: string | undefined;
+        formats?: {
+            format: "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+            resolveAliases?: boolean | undefined;
+            filename?: string | undefined;
+            prefix?: string | undefined;
+            splitByMode?: boolean | undefined;
+            splitByCollection?: boolean | undefined;
+            dtcgDialect?: "legacy" | "2025" | undefined;
+            transforms?: {
+                colorFormat?: "hex" | "hex8" | "rgba" | "oklch" | "hsl" | undefined;
+                sizeUnit?: "px" | "rem" | "pt" | "dp" | undefined;
+                remBase?: number | undefined;
+            } | undefined;
+        }[] | undefined;
+    } | undefined;
+    conflictResolution?: "ask" | "figma-wins" | "code-wins" | "skip" | undefined;
+}>;
+export type TokensConfig = z.infer<typeof TokensConfigSchema>;
+/**
+ * Result of running `loadTokensConfig`. Includes the resolved config plus
+ * provenance info — where the file was found and the absolute project root.
+ */
+export interface LoadedTokensConfig {
+    config: TokensConfig;
+    /** Absolute path to the discovered `tokens.config.json`. */
+    configPath: string;
+    /** Directory containing the config file — used as the project root. */
+    projectRoot: string;
+}
+/**
+ * Walk up from `startDir` looking for `tokens.config.json`. Returns the first
+ * match, or `null` if none found by the filesystem root.
+ */
+export declare function findTokensConfig(startDir: string): string | 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 declare function loadTokensConfig(opts?: {
+    cwd?: string;
+    explicitPath?: string;
+}): LoadedTokensConfig | null;
+/**
+ * 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 declare const DEFAULT_TOKENS_CONFIG: TokensConfig;
+/**
+ * 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 declare function buildSuggestedScaffold(opts: {
+    projectRoot: string;
+    detectedFramework?: "tailwind-v4" | "tailwind-v3" | "css" | "scss" | "ts";
+}): {
+    configContent: string;
+    directories: string[];
+    stylesheetImport: string;
+    nextSteps: string;
+};
+/**
+ * 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 declare function resolveOutputTargets(config: TokensConfig | null, explicitFormat: ExportFormat | undefined): OutputTarget[];
+/**
+ * Resolve the conflict-resolution strategy. Per-call argument wins over config
+ * default, which wins over the global default ("ask").
+ */
+export declare function resolveConflictStrategy(config: TokensConfig | null, perCall: ConflictResolution | undefined): ConflictResolution;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/core/tokens/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/tokens/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,QAAA,MAAM,kBAAkB;;IActB,0EAA0E;;IAE1E,qEAAqE;;IAErE,uEAAuE;;IAEvE,sDAAsD;;IAEtD;;;;OAIG;;IAEH;;;;;;;;OAQG;;IAEH,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQlE,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;IAE3B,0DAA0D;;IAE1D;;;;OAIG;;IAEH,0DAA0D;;QAGtD,mDAAmD;;QAEnD,wDAAwD;;QAExD;;;;WAIG;;;;;;;;;;;IAIP,6DAA6D;;;;;YAlE/D,0EAA0E;;YAE1E,qEAAqE;;YAErE,uEAAuE;;YAEvE,sDAAsD;;YAEtD;;;;eAIG;;YAEH;;;;;;;;eAQG;;YAEH,kEAAkE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiDhE,+DAA+D;;QAG3D,gDAAgD;;QAEhD,mEAAmE;;;;;;;;;IAIvE,wEAAwE;;IAIxE,oEAAoE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7D,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,kBAAkB,GAAG,IAAI,CAwCjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,YASnC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,aAAa,GAAG,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;CAC3E,GAAG;IACF,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,CAyBA;AA6CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,cAAc,EAAE,YAAY,GAAG,SAAS,GACvC,YAAY,EAAE,CAWhB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,OAAO,EAAE,kBAAkB,GAAG,SAAS,GACtC,kBAAkB,CAEpB"}