@sxl-studio/bridge 1.5.1 → 1.6.0

package/dist/tools/variables-orchestration.js

@@ -0,0 +1,116 @@
+/**
+ * Variables orchestration — Bridge platform Phase B tools.
+ *
+ * "Thick" commands that wrap multi-step Figma Variables refactors:
+ *   - `import_variable_spec`        — declarative bulk create / update with aliases.
+ *   - `analyze_variable_order`      — read-only diff to recommend a new order.
+ *   - `dedupe_variables`            — find / merge duplicates (dry-run by default).
+ *   - `rebind_variable_aliases`     — bulk rewrite alias chains across modes.
+ *   - `apply_coverage_suggestions`  — convert audit_variable_coverage suggestions
+ *                                     into safe `setBoundVariableFor*` writes.
+ *
+ * Token economy:
+ *   - dry-run (default for dedupe / apply_coverage_suggestions / spec preview)
+ *     returns the exact plan WITHOUT touching the canvas. Agents inspect the
+ *     summary, surface it to the user, then re-call with `apply: true` /
+ *     `dryRun: false` to commit.
+ */
+import { z } from "zod";
+import { callPluginCommand } from "./shared.js";
+const variableValueLiteralZod = z.union([
+    z.number(),
+    z.string(),
+    z.boolean(),
+    z.object({
+        r: z.number(),
+        g: z.number(),
+        b: z.number(),
+        a: z.number().optional(),
+    }),
+]);
+const aliasRefZod = z.union([
+    z.object({ variableId: z.string() }),
+    z.object({ variableName: z.string() }),
+]);
+const variableValueZod = z.union([
+    z.object({ value: variableValueLiteralZod }),
+    z.object({ alias: aliasRefZod }),
+    z.object({
+        rawAlias: z.union([
+            z.object({ type: z.literal("VARIABLE_ALIAS"), id: z.string() }),
+            z.object({ aliasOf: z.string() }),
+        ]),
+    }),
+]);
+const modeZod = z.object({
+    key: z.string().describe("Stable mode key referenced from variable values"),
+    name: z.string().optional().describe("Display name (required when creating a new mode)"),
+});
+const variableTypeZod = z.enum(["COLOR", "FLOAT", "STRING", "BOOLEAN"]);
+const variableEntryZod = z.object({
+    name: z.string(),
+    type: variableTypeZod,
+    valuesByMode: z.record(variableValueZod).optional(),
+    scopes: z.array(z.string()).optional(),
+    codeSyntax: z.record(z.string()).optional(),
+    description: z.string().optional(),
+});
+const collectionSpecZod = z
+    .object({
+    collectionId: z.string().optional(),
+    collectionName: z.string().optional(),
+    modes: z.array(modeZod).optional(),
+    variables: z.array(variableEntryZod).optional(),
+})
+    .refine((c) => Boolean(c.collectionId ?? c.collectionName), {
+    message: "Collection requires collectionId or collectionName",
+});
+const variableSpecZod = z.object({
+    collections: z.array(collectionSpecZod).min(1),
+    resolveAliases: z.boolean().optional(),
+    dryRun: z.boolean().optional(),
+});
+const reorderStrategyZod = z.union([
+    z.object({ type: z.literal("alphabetical") }),
+    z.object({ type: z.literal("byPath"), separator: z.string().optional() }),
+    z.object({ type: z.literal("explicit"), order: z.array(z.string()).min(1) }),
+]);
+const dedupeStrategyZod = z.enum(["byName", "byDefaultModeValue"]);
+export function registerVariablesOrchestrationTools(server, queue) {
+    server.tool("import_variable_spec", "Idempotent bulk-create / update of Variables from a single declarative spec. Creates collections + modes + variables, applies per-mode literal values, then resolves aliases in a second pass so cross-collection references work. Errors are collected per-item without aborting the run. Pass `dryRun: true` for a preview (returns the diff and skips Figma writes). CANVAS WRITE in apply mode — blocked in Dev Mode.", {
+        spec: variableSpecZod.describe("Top-level spec. `collections[]` is required; each collection identifies itself by `collectionId` (existing) or `collectionName` (resolves existing or creates new). Variable values support `{ value }` literals (hex strings auto-coerce for COLOR), `{ alias: { variableId | variableName } }`, or `{ rawAlias }` passthrough."),
+    }, async ({ spec }) => callPluginCommand(queue, "import_variable_spec", { spec }));
+    server.tool("analyze_variable_order", "READ-ONLY: produce a recommended order of variables inside a collection. Returns `moves[]` describing every position that would change. Strategies: `alphabetical`, `byPath` (with optional separator), `explicit` (caller-supplied list). Figma Plugin API does not expose a stable `move` primitive, so this command stays diff-only — use it to drive a manual reorder in the Variables panel.", {
+        collectionId: z.string().describe("Variable collection id (VariableCollectionId:...)"),
+        strategy: reorderStrategyZod,
+    }, async (args) => callPluginCommand(queue, "analyze_variable_order", args));
+    server.tool("dedupe_variables", "Find (and optionally merge) duplicate Variables. Strategies: `byName` (same name across collections) or `byDefaultModeValue` (same default-mode literal value within the same resolvedType). Default is dry-run — returns groups + suggested survivor + would-be rebindings. With `apply: true` the survivor inherits incoming aliases (via `rebind_variable_aliases`) and duplicates are removed. CANVAS WRITE only in apply mode.", {
+        strategy: dedupeStrategyZod.default("byName"),
+        apply: z.boolean().optional().describe("When true, perform the merge. Default: false (dry-run)."),
+        collectionId: z
+            .string()
+            .optional()
+            .describe("Restrict the scan to a single collection. Default: scan all local variables."),
+    }, async (args) => callPluginCommand(queue, "dedupe_variables", args));
+    server.tool("rebind_variable_aliases", "Bulk rewrite alias targets inside Variable collections. Each `{ fromVariableId, toVariableId }` pair redirects every `valuesByMode` entry that aliases the source so it points at the target. Read-only nodes / bindings are NOT touched (use `apply_coverage_suggestions` for that). Pass `dryRun: true` to count rewrites without writing.", {
+        mappings: z
+            .array(z.object({
+            fromVariableId: z.string(),
+            toVariableId: z.string(),
+        }))
+            .min(1),
+        dryRun: z.boolean().optional().describe("When true, count rewrites without applying. Default: false."),
+    }, async (args) => callPluginCommand(queue, "rebind_variable_aliases", args));
+    server.tool("apply_coverage_suggestions", "Apply the `suggestion` entries from `audit_variable_coverage` / `find_variable_coverage_misses`. Translates property paths like `fills[0].color`, `effects[2].color`, `cornerRadius` etc. into Figma `setBoundVariableForPaint` / `setBoundVariableForEffect` / `setBoundVariable` writes. Default mode is dry-run — agent receives a `preview[]` it can show the user. Set `dryRun: false` to commit. CANVAS WRITE only when `dryRun: false`.", {
+        suggestions: z
+            .array(z.object({
+            nodeId: z.string(),
+            property: z.string().describe("Property path as returned by find_variable_coverage_misses"),
+            variableId: z.string(),
+            variableName: z.string().optional(),
+        }))
+            .min(1),
+        dryRun: z.boolean().optional().describe("Default: true. Pass false to actually wire bindings."),
+    }, async (args) => callPluginCommand(queue, "apply_coverage_suggestions", args));
+}
+//# sourceMappingURL=variables-orchestration.js.map

package/dist/tools/variables-orchestration.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sxl-studio/bridge",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "MCP/HTTP bridge server for SXL Studio Figma plugin — enables remote control from IDE",
   "type": "module",
   "main": "dist/index.js",