@mp3wizard/figma-console-mcp 1.25.1 → 1.27.2

package/dist/core/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/core/identity.ts"],"names":[],"mappings":"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"}

package/dist/core/tokens/alias-resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+import type { Token, TokenDocument, TokenValue } from "./types.js";
+/**
+ * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
+ * objects. Used as the index for resolveAliases().
+ */
+export declare function buildTokenIndex(doc: TokenDocument): Map<string, Token>;
+/**
+ * Resolve a single alias reference. Returns the eventual literal value, or
+ * throws if the reference is unresolvable or cyclic.
+ */
+export declare function resolveReference(reference: string, mode: string, index: Map<string, Token>, seen?: Set<string>): TokenValue;
+/**
+ * Validate every alias in the document. Returns a list of error messages —
+ * empty array means all aliases resolve cleanly.
+ */
+export declare function validateAliases(doc: TokenDocument): string[];
+/**
+ * Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
+ * syntax with curly braces.
+ */
+export declare function formatDtcgReference(referencePath: string[]): string;
+/**
+ * Parse a DTCG alias string back into a path array. Returns null if the
+ * string isn't an alias reference.
+ */
+export declare function parseDtcgReference(s: string): string[] | null;
+//# sourceMappingURL=alias-resolver.d.ts.map

package/dist/core/tokens/alias-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias-resolver.d.ts","sourceRoot":"","sources":["../../../src/core/tokens/alias-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAStE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EACzB,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAC5B,UAAU,CAsCZ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CAqB5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAI7D"}

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

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+/**
+ * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
+ * objects. Used as the index for resolveAliases().
+ */
+export function buildTokenIndex(doc) {
+    const index = new Map();
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            const key = token.path.join(".");
+            index.set(key, token);
+        }
+    }
+    return index;
+}
+/**
+ * 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;
+}
+/**
+ * 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":"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"}

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

@@ -0,0 +1,352 @@
+/**
+ * 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>;
+    /** 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;
+    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;
+    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>;
+            /** 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;
+            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;
+            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;
+            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;
+            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;
+            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;
+            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,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;;;;;YAxD/D,0EAA0E;;YAE1E,qEAAqE;;YAErE,uEAAuE;;YAEvE,sDAAsD;;YAEtD;;;;eAIG;;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"}