@muloka/figma-console-mcp 0.1.0

package/dist/core/tokens-tools.d.ts

@@ -0,0 +1,285 @@
+/**
+ * MCP tool registrar for figma_export_tokens and figma_import_tokens.
+ *
+ * Current scope (v1.27.0):
+ *   - figma_export_tokens: working for DTCG JSON (canonical) and CSS
+ *     custom properties output. Other formats (Tailwind v4, SCSS, TS
+ *     module, Tokens Studio, Style Dictionary v3) are scaffolded and
+ *     return TokenFormatNotImplementedError with a helpful message
+ *     directing users to DTCG.
+ *   - figma_import_tokens: working for DTCG JSON input with full
+ *     diff-aware merge and a complete apply phase:
+ *       • toUpdate — value updates batched via the plugin bridge,
+ *         including alias-target updates ({ type: "VARIABLE_ALIAS", id })
+ *         when the reference resolves to an existing or just-created
+ *         variable.
+ *       • toCreate — missing collections (created with the token file's
+ *         full mode list) and missing variables in one batched script;
+ *         literal values first, alias values in a second pass so
+ *         within-batch alias targets exist. TIMING/EASING cannot be
+ *         created via the Plugin API and are skipped with a warning.
+ *       • toDelete — STRICTLY gated behind strategy: "replace". Merge
+ *         (default) preserves Figma-only variables and only reports them.
+ *
+ * Both tools auto-discover `tokens.config.json` at the project root and use
+ * its source/generated/modes/conflictResolution settings as defaults. They
+ * stay zero-arg in normal use.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type TokenDocument } from "./tokens/index.js";
+export interface RegisterTokensToolsOptions {
+    /**
+     * True when registering in Cloud Mode (Cloudflare Workers). In Cloud Mode
+     * the MCP server has no local filesystem access, so the tools surface a
+     * clear "inline payload required" error instead of letting an fs ENOENT
+     * bubble up cryptically. Export still works with explicit content return;
+     * import still works with inline payload/files. tokens.config.json
+     * autodiscovery, outputPath disk writes, and config-source file reads
+     * are all Local Mode only.
+     */
+    isRemoteMode?: boolean;
+}
+export declare function registerExportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+export declare function registerImportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+/**
+ * Convenience: register both tools at once.
+ */
+export declare function registerTokensTools(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+/**
+ * Compute a diff plan between Figma's current state (left) and the code's
+ * proposed state (right). Returns a structured diff plan; value-update
+ * mutations are applied via the plugin bridge below.
+ *
+ * MATCH PRIORITY (as the tool description promises): Figma variable ID
+ * first, then exact set::path. A code-side token whose path has no Figma
+ * counterpart but whose $extensions["figma-console-mcp"].variableId matches
+ * a live variable is a RENAME — routed to toRename (name change + any
+ * value/meta changes), and its Figma-side counterpart is EXCLUDED from
+ * toDelete. Without this, a path rename in the code file would create a
+ * duplicate variable under merge, and under replace would permanently
+ * delete the original (detaching all its bindings).
+ *
+ * Exported for test coverage of the dialect-normalized comparison
+ * (round-trip exports in both DTCG dialects must diff as unchanged) and
+ * rename classification.
+ */
+export declare function computeDiffPlan(figmaDoc: TokenDocument, codeDoc: TokenDocument): {
+    toCreate: Array<{
+        path: string;
+        type: string;
+        value: unknown;
+    }>;
+    toUpdate: Array<{
+        path: string;
+        before: unknown;
+        after: unknown;
+        /**
+         * Present when variable metadata (scopes/codeSyntax) changed. Absent for
+         * plain value-only updates (the historical entry shape). `values: false`
+         * tells the apply phase to skip setValueForMode entirely and only write
+         * the metadata.
+         */
+        changes?: {
+            values: boolean;
+            scopes: boolean;
+            codeSyntax: boolean;
+        };
+    }>;
+    toRename: Array<{
+        /** New (code-side) diff key. */
+        path: string;
+        /** Old (Figma-side) diff key the variableId matched. */
+        from: string;
+        variableId: string;
+        /** New Figma variable name — the '/'-joined code-side token path. */
+        newName: string;
+        /** Value/meta changes to apply alongside the rename. */
+        changes: {
+            values: boolean;
+            scopes: boolean;
+            codeSyntax: boolean;
+        };
+    }>;
+    toDelete: Array<{
+        path: string;
+    }>;
+    unchanged: number;
+};
+/**
+ * How an alias reference resolves for the apply phase:
+ *   - { id }      → an existing (or already-created) Figma variable ID
+ *   - { pending } → the target is itself in this import's toCreate batch;
+ *                   the create script resolves it in its second pass via the
+ *                   returned key
+ *   - null        → unresolvable; caller skips with a warning
+ */
+type AliasIdResolution = {
+    id: string;
+} | {
+    pending: string;
+} | null;
+/**
+ * Build a resolver that maps a DTCG alias reference (set-qualified
+ * `{theme.color.primary}`, bare `{color.primary}` when unambiguous, or the
+ * converter's `{__library:VariableID:...}` cross-library form) to a Figma
+ * variable ID.
+ *
+ * Resolution priority for a matched code-side token:
+ *   1. a variable created earlier in THIS apply run (createdIdByKey — the
+ *      resolver closes over the mutable map, so the create phase's results
+ *      are visible to the later update phase)
+ *   2. the live Figma snapshot's variable ID for the same set::path
+ *   3. "pending" when the target is queued in this run's toCreate batch
+ *   4. the token's own $extensions variableId (stale-but-recorded fallback)
+ * References that don't match a code-side token fall back to the live Figma
+ * snapshot lookup. Exported for test coverage.
+ */
+export declare function makeAliasIdResolver(figmaDoc: TokenDocument, codeDoc: TokenDocument, toCreateKeys: Set<string>, createdIdByKey: Map<string, string>): (reference: string) => AliasIdResolution;
+/**
+ * One variable update to push to Figma. mapping is by modeId (Figma's
+ * native identifier), not mode name, because that's what the Plugin API
+ * needs.
+ */
+interface VariableUpdate {
+    variableId: string;
+    variableName: string;
+    resolvedType: "COLOR" | "FLOAT" | "STRING" | "BOOLEAN";
+    valuesByMode: Record<string, unknown>;
+    /**
+     * Rename op: set `variable.name` to this '/'-joined path before any value
+     * writes. Produced by the ID-first rename classification in
+     * computeDiffPlan — never combined with a create/delete of the same
+     * variable.
+     */
+    newName?: string;
+    /** Full replacement scopes array (`variable.scopes = [...]`). */
+    scopes?: string[];
+    /**
+     * Per-platform code syntax ops: `set` maps platform → value
+     * (setVariableCodeSyntax), `remove` lists platforms to clear
+     * (removeVariableCodeSyntax).
+     */
+    codeSyntax?: {
+        set?: Record<string, string>;
+        remove?: string[];
+    };
+}
+/**
+ * Convert a TokenValue back to Figma's native value shape. Required for the
+ * Plugin API's setValueForMode call.
+ *
+ *   - color hex string "#RRGGBB(AA)" → { r, g, b, a } floats in [0, 1].
+ *     Non-hex color strings ("rgb(255,0,0)", "transparent", named colors
+ *     like "salmon") return skip-invalid instead of throwing — a throw here
+ *     would abort the import mid-apply.
+ *   - DTCG 2025.10 color objects → { r, g, b, a }: srgb components map
+ *     directly (clamped to [0, 1]); non-srgb colorSpaces (display-p3,
+ *     oklch, …) fall back to the object's `hex` field when present, else
+ *     skip-invalid; hex-only objects are accepted too
+ *   - FLOAT-typed number → number ("16px"-style strings and DTCG
+ *     { value, unit } objects are parsed to their numeric part; anything
+ *     that still comes out NaN is skipped rather than pushed to Figma)
+ *   - STRING-typed string → string
+ *   - BOOLEAN → boolean
+ *   - Alias references return `skip-alias` so the CALLER resolves them —
+ *     both apply paths pass the reference through their alias-ID resolver
+ *     (just-created variable → live snapshot → pending in batch → recorded
+ *     $extensions ID) and write { type: "VARIABLE_ALIAS", id }. Only when
+ *     the resolver comes up empty does the reference stay skipped, with a
+ *     warning rather than a silent drop.
+ *
+ * Exported for test coverage of the value-conversion edge cases.
+ */
+export declare function tokenValueToFigma(value: {
+    literal?: unknown;
+    reference?: string;
+}, resolvedType: VariableUpdate["resolvedType"]): {
+    kind: "value";
+    value: unknown;
+} | {
+    kind: "skip-alias";
+    reference: string;
+} | {
+    kind: "skip-empty";
+} | {
+    kind: "skip-invalid";
+    reason: string;
+};
+/**
+ * One value to set on a variable at creation time. New-collection variables
+ * carry `modeName` (the script resolves the modeId from the collection it
+ * just created); existing-collection variables carry `modeId` (resolved
+ * server-side from the live snapshot). Alias values come in two flavors:
+ * `alias` (target already exists in Figma) and `alias-pending` (target is
+ * created in this same batch; the script resolves `targetKey` against its
+ * created-ID map in the second pass).
+ */
+type CreateValueEntry = {
+    modeName?: string;
+    modeId?: string;
+} & ({
+    kind: "literal";
+    value: unknown;
+} | {
+    kind: "alias";
+    targetId: string;
+} | {
+    kind: "alias-pending";
+    targetKey: string;
+});
+interface CreateVariableDef {
+    /** Diff key ("SetName::dot.path") — primary key for created-ID mapping. */
+    key: string;
+    /** Figma variable name (slash-joined token path). */
+    name: string;
+    resolvedType: VariableUpdate["resolvedType"];
+    description?: string;
+    values: CreateValueEntry[];
+    /** Non-default scopes to apply at creation (from token $extensions). */
+    scopes?: string[];
+    /** Per-platform code syntax to apply at creation (from token $extensions). */
+    codeSyntax?: Record<string, string>;
+}
+/**
+ * The create-phase plan: which collections to create (with the token file's
+ * full mode list) and which variables to create where. Built entirely
+ * server-side so the plugin script stays a dumb executor.
+ */
+export interface CreatePlan {
+    newCollections: Array<{
+        setName: string;
+        modes: string[];
+        variables: CreateVariableDef[];
+    }>;
+    existingCollections: Array<{
+        collectionId: string;
+        variables: CreateVariableDef[];
+    }>;
+}
+/**
+ * Translate the diff's toCreate entries into a CreatePlan.
+ *
+ *   - Sets with no matching Figma collection (matched by the round-trip
+ *     figmaCollectionId first, then by name) become newCollections carrying
+ *     the set's FULL mode list.
+ *   - Variables missing from an existing collection go to that collection,
+ *     with values pre-resolved to modeIds; values for modes the collection
+ *     doesn't have are skipped with a warning.
+ *   - resolvedType honors $extensions.figmaResolvedType when recorded, else
+ *     falls back to inferFigmaResolvedType. TIMING/EASING variables are
+ *     skipped with a warning — the Figma Plugin API cannot create them.
+ *   - Literal values convert via tokenValueToFigma (both DTCG dialects);
+ *     alias values resolve via the alias-ID resolver (existing target →
+ *     "alias", within-batch target → "alias-pending", unresolvable → skip
+ *     with warning).
+ *
+ * Exported for test coverage.
+ */
+export declare function buildCreatePlan(toCreate: Array<{
+    path: string;
+}>, codeDoc: TokenDocument, figmaPayload: {
+    collections: any[];
+    variables: any[];
+}, resolveAliasId: (reference: string) => AliasIdResolution, warnings: string[]): CreatePlan;
+export {};
+//# sourceMappingURL=tokens-tools.d.ts.map

package/dist/core/tokens-tools.d.ts.map

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