@hegemonart/get-design-done 1.59.3 → 1.59.4

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 agents, 95 skills, 39 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
-    "version": "1.59.3"
+    "version": "1.59.4"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 specialized agents, 95 skills, 39 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
-      "version": "1.59.3",
+      "version": "1.59.4",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.59.3",
+  "version": "1.59.4",
   "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 specialized agents, 95 skills, 39 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.59.4] - 2026-06-04
+
+Fourth point release of the **v1.59 "Audit Closeout & Honesty Pass"** milestone. Skill-surface + build hygiene.
+
+### Changed
+
+- **`skill-templates/` relocated to `scripts/skill-templates/`** (source-dir move, git history preserved; 36 reference updates). The committed `skills/` build output is unchanged, so the `build:skills:check` drift gate stays meaningful.
+- **`/gdd:help` is now complete and dynamic.** It reads `scripts/lib/manifest/skills.json` and renders every skill, replacing a hardcoded ~41-command subset (of 95). Root SKILL.md Jump Mode now notes it is a curated subset and points to `/gdd:help` for the full manifest-rendered reference.
+
+### Added
+
+- **npm-installed users can now author skills.** `package.json#files[]` ships `scripts/skill-templates/`, `scripts/build-skills.cjs`, and `scripts/generate-skill-frontmatter.cjs` (so `/gdd:new-skill` + rebuild work off an `npm install`), plus the figma plugin source (`figma-plugin/`).
+- **`codegen:schemas:check` drift gate** (EOL-agnostic) wired into CI, closing the one previously un-gated generator (`reference/schemas/generated.d.ts`).
+
+### Fixed
+
+- **Stale "gitignored" README claims** corrected: `skills/` has been a committed build artifact since v1.58.1, not gitignored.
+- Pre-existing stale `source/skills` regex in `hooks/gdd-intel-trigger.js` repointed to `scripts/skill-templates`.
+
+### Note
+
+- The "7 Phase-28.8 baseline regen pending" skips named in the plan were already resolved by earlier phases (no such markers remain), so there was nothing to burn down.
+
+### Breaking changes
+
+None.
+
+5,049/5,049 tests pass.
+
+---
+
 ## [1.59.3] - 2026-06-04
 
 Third point release of the **v1.59 "Audit Closeout & Honesty Pass"** milestone. A routing-coherence pass on agent model/tier declarations.

package/SKILL.md

@@ -199,6 +199,8 @@ Use `[✓]` for complete, `[→]` for current, `[ ]` for pending, `[!]` for gaps
 
 If `$ARGUMENTS` is a stage or command name - invoke it directly, no state check:
 
+> This table lists the common stage and shortcut routes. Every skill in `scripts/lib/manifest/skills.json` is auto-resolvable as `/gdd:<name>`; run `/gdd:help` for the complete, always-current command reference (rendered from the manifest, never a hardcoded subset).
+
 ```
 /gdd:brief     → Skill("get-design-done:gdd-brief")
 /gdd:explore   → Skill("get-design-done:gdd-explore")

package/figma-plugin/README.md

@@ -0,0 +1,61 @@
+# GDD Sync — Figma plugin
+
+`GDD Sync` is the Figma-side half of GDD's design-system extractor (Path C). It reads
+your file's **local Figma variables** from inside Figma and POSTs them as JSON to a
+GDD extract receiver listening on `localhost:5179`.
+
+## Why this exists
+
+GDD's extractor pulls a design system from the Figma REST API into a compact local
+digest. The Variables REST API, however, is **Enterprise-only** — it returns `403` on
+Free/Pro/Org plans. A Figma plugin has full `figma.variables` access on **any** plan, so
+this plugin fills that gap: it reads what the API cannot and ships it to GDD locally.
+
+## Security
+
+The plugin can talk to **localhost only**. `manifest.json` declares
+`networkAccess.allowedDomains` as exactly:
+
+```json
+["http://localhost:5179", "http://127.0.0.1:5179"]
+```
+
+No wildcard, no external host. This is the single hard security boundary of Path C
+(decision D-06): the plugin has no exfiltration surface — it can reach the local GDD
+receiver and nothing else.
+
+## Development
+
+This is a standalone TypeScript package (decision D-05). It is **not** part of the root
+`get-design-done` package.
+
+### Build
+
+```bash
+cd figma-plugin
+npm install
+npm run build   # runs tsc → emits code.js next to code.ts
+```
+
+`code.ts` (sandbox entry) and `src/*.ts` compile under `tsconfig.json` against
+`@figma/plugin-typings` into `code.js`, which `manifest.json` references via `main`.
+
+### Dev-install (Figma desktop)
+
+1. Build (`npm run build`) so `code.js` exists.
+2. In the **Figma desktop app**: **Plugins → Development → Import plugin from manifest…**
+3. Select `figma-plugin/manifest.json`.
+
+### Usage
+
+1. Start a GDD extract run so the receiver is listening on `localhost:5179`.
+2. Open the Figma file whose variables you want to export.
+3. Run **GDD Sync** (Plugins → Development → GDD Sync).
+4. Click **Export to GDD**. The plugin reads the file's local variables and POSTs them
+   to the receiver, which writes them into the extract cache.
+
+## Distribution
+
+Community submission is **deferred** (decision D-07). For v1.31.0 the supported path is
+**dev-install** via the manifest, as documented above. Publishing to the Figma Community
+is a follow-up that will not block the version cut.

package/figma-plugin/code.ts

@@ -0,0 +1,36 @@
+// GDD Sync — Figma plugin sandbox entry (main thread).
+//
+// SCAFFOLD (Plan 31-04): this is the shell only. It opens the single-button UI
+// (ui.html) and wires the message plumbing that routes the "export" action to
+// exportVariables(). The actual variables-read + POST logic lives in
+// ./src/export-variables (a compiling PLACEHOLDER in this plan; Plan 31-05
+// replaces it with the real implementation).
+//
+// Message contract (the seam 31-05 builds on):
+//   ui.html  -- parent.postMessage({ pluginMessage: { type: 'export' } }) -->  code.ts
+//   code.ts  -- figma.ui.onmessage receives { type: 'export' } --> exportVariables()
+//   exportVariables() (31-05) reads figma.variables, builds the payload, and
+//   POSTs it to http://localhost:5179/variables (the GDD receiver, Plan 31-06).
+//
+// Security: the only network destination the manifest permits is localhost:5179
+// (manifest.networkAccess.allowedDomains, D-06). code.ts itself opens no sockets.
+
+import { exportVariables } from './src/export-variables';
+
+// Messages the UI may post to the sandbox. 31-05 may extend this union.
+interface ExportMessage {
+  type: 'export';
+}
+
+type UiMessage = ExportMessage;
+
+figma.showUI(__html__, { width: 280, height: 160 });
+
+figma.ui.onmessage = (msg: UiMessage): void => {
+  if (msg && msg.type === 'export') {
+    // Delegate to the export entry point. 31-05 supplies the real logic;
+    // this scaffold ships a notify-only placeholder so code.ts compiles
+    // standalone in Wave B.1.
+    void exportVariables();
+  }
+};

package/figma-plugin/manifest.json

@@ -0,0 +1,12 @@
+{
+  "name": "GDD Sync",
+  "id": "gdd-sync-figma-variables-export",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "editorType": ["figma"],
+  "networkAccess": {
+    "allowedDomains": ["http://localhost:5179", "http://127.0.0.1:5179"],
+    "reasoning": "GDD Sync POSTs locally-read Figma variables to an ephemeral GDD extract receiver bound to 127.0.0.1:5179 ONLY (Path C, decision D-06). The plugin has NO other network surface: no external host, no wildcard. This is the security boundary that prevents design-data exfiltration."
+  }
+}

package/figma-plugin/package-lock.json

@@ -0,0 +1,35 @@
+{
+  "name": "gdd-figma-sync-plugin",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "gdd-figma-sync-plugin",
+      "devDependencies": {
+        "@figma/plugin-typings": "^1.109.0",
+        "typescript": "^5.7.2"
+      }
+    },
+    "node_modules/@figma/plugin-typings": {
+      "version": "1.127.0",
+      "resolved": "https://registry.npmjs.org/@figma/plugin-typings/-/plugin-typings-1.127.0.tgz",
+      "integrity": "sha512-Y8fjfUCdWN6bUTs1wsd9GFZ3zF4USDVNmmxfUo/4Ia7NmFemSK2nBxOu7BKcusEHCERwiO7N8iOqw5jwvbL80g==",
+      "dev": true,
+      "license": "MIT License"
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}

package/figma-plugin/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "gdd-figma-sync-plugin",
+  "private": true,
+  "description": "GDD Sync — Figma plugin that reads local Figma variables and POSTs them to the GDD extract receiver on localhost:5179 (Path C for non-Enterprise token extraction).",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@figma/plugin-typings": "^1.109.0",
+    "typescript": "^5.7.2"
+  }
+}

package/figma-plugin/src/export-variables.ts

@@ -0,0 +1,144 @@
+// figma-plugin/src/export-variables.ts — Plan 31-05 (Wave B.2)
+//
+// Path C of the three-path token extraction (D-04). The Variables REST API is
+// Enterprise-only (the spike hit a 403); the in-Figma sandbox Variables API
+// (figma.variables.*) works on ANY plan. This module reads the local variable
+// collections + variables from inside Figma, resolves aliases, includes mode
+// metadata, emits ALL local variables (D-13 — no published filter), builds a
+// payload conforming to the receiver's payload-schema.json (31-06), and POSTs it
+// to the ephemeral localhost receiver (D-06: 127.0.0.1:5179 ONLY).
+//
+// Replaces the 31-04 placeholder. Contract preserved: `export async function
+// exportVariables(): Promise<void>` is what code.ts calls on the { type:'export' }
+// message. The PURE builder (buildPayload, re-exported from ./payload-schema) is
+// kept network-free so the offline test drives it against a figma.variables mock.
+//
+// Reading strategy: the async API (getLocalVariableCollectionsAsync /
+// getLocalVariablesAsync / getVariableByIdAsync) is used rather than the
+// deprecated sync variants — the sync methods throw under
+// `"documentAccess":"dynamic-page"` manifests, and async is the documented,
+// future-proof surface. The pure buildPayload stays synchronous so the data
+// gathering (async, Figma-bound) and the shaping (sync, testable) are separated.
+
+import {
+  buildPayload,
+  type GddSyncPayload,
+  type RawCollectionLike,
+  type RawVariableLike,
+  type VariableNameResolver,
+} from './payload-schema';
+
+// Re-export the pure builder + payload type so code.ts / tests have one import
+// site for the plugin-side contract.
+export {
+  buildPayload,
+  isGddSyncPayload,
+  type GddSyncPayload,
+} from './payload-schema';
+
+// D-06: the ONE permitted network destination. Matches the receiver's bind host
+// (127.0.0.1 — receiver.cjs RECEIVER_HOST) and manifest.networkAccess.allowedDomains.
+// Using the explicit loopback IP (not `localhost`) avoids any IPv6 `::1`
+// resolution surprise and matches the receiver's 127.0.0.1 bind exactly.
+export const RECEIVER_URL = 'http://127.0.0.1:5179/variables';
+
+/**
+ * Read local collections + variables from the Figma sandbox and shape them into
+ * a GddSyncPayload via the pure buildPayload. Async because the non-deprecated
+ * Variables API is async. Emits ALL local variables (D-13). Alias targets are
+ * resolved to names (via getVariableByIdAsync) so the digest can render the
+ * alias chain like the spike's `{alias}` form.
+ *
+ * Separated from exportVariables() so the network POST is the only impure part.
+ */
+export async function gatherPayload(): Promise<GddSyncPayload> {
+  // getLocalVariableCollectionsAsync(): VariableCollection[] — { id, name, modes:[{modeId,name}] }
+  const rawCollections = await figma.variables.getLocalVariableCollectionsAsync();
+  // getLocalVariablesAsync(): Variable[] — ALL locals (D-13; no type filter).
+  const rawVariables = await figma.variables.getLocalVariablesAsync();
+
+  const collections: RawCollectionLike[] = rawCollections.map((c) => ({
+    id: c.id,
+    name: c.name,
+    modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
+  }));
+
+  const variables: RawVariableLike[] = rawVariables.map((v) => ({
+    id: v.id,
+    name: v.name,
+    resolvedType: v.resolvedType,
+    variableCollectionId: v.variableCollectionId,
+    // valuesByMode is { [modeId]: VariableValue }; pass through — buildPayload
+    // resolves alias markers + renders the flat tokens[].
+    valuesByMode: v.valuesByMode as RawVariableLike['valuesByMode'],
+  }));
+
+  // Pre-resolve every alias target name once (async), then hand buildPayload a
+  // synchronous resolver. We gather the set of alias target ids first to avoid
+  // N awaits inside the pure builder.
+  const aliasIds = new Set<string>();
+  for (const v of rawVariables) {
+    for (const modeId of Object.keys(v.valuesByMode)) {
+      const value = v.valuesByMode[modeId] as unknown;
+      if (
+        value &&
+        typeof value === 'object' &&
+        (value as { type?: string }).type === 'VARIABLE_ALIAS' &&
+        typeof (value as { id?: string }).id === 'string'
+      ) {
+        aliasIds.add((value as { id: string }).id);
+      }
+    }
+  }
+
+  const nameById = new Map<string, string>();
+  for (const id of aliasIds) {
+    try {
+      const target = await figma.variables.getVariableByIdAsync(id);
+      if (target) nameById.set(id, target.name);
+    } catch {
+      // A missing/unreadable alias target is non-fatal — buildPayload falls back
+      // to `{id}` so the reference is still recorded.
+    }
+  }
+  const resolveName: VariableNameResolver = (id) => nameById.get(id);
+
+  return buildPayload(collections, variables, {
+    fileKey: figma.fileKey,
+    exportedAt: new Date().toISOString(),
+    resolveName,
+  });
+}
+
+/**
+ * The export entry point code.ts calls on the { type:'export' } message. Builds
+ * the payload then POSTs it to the receiver. Network failures + non-2xx
+ * responses are surfaced via figma.notify and NEVER crash the sandbox.
+ */
+export async function exportVariables(): Promise<void> {
+  let payload: GddSyncPayload;
+  try {
+    payload = await gatherPayload();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    figma.notify('GDD Sync: failed to read variables — ' + msg);
+    return;
+  }
+
+  try {
+    const res = await fetch(RECEIVER_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+      figma.notify('GDD Sync: receiver rejected payload (' + res.status + ')');
+    } else {
+      figma.notify('GDD Sync: exported ' + payload.variables.length + ' variables');
+    }
+  } catch {
+    // No receiver listening (the common case when no extract run is active),
+    // or any other network error. Guide the user; do not throw.
+    figma.notify('GDD Sync: no receiver on 127.0.0.1:5179 — start a GDD extract run first');
+  }
+}

package/figma-plugin/src/payload-schema.ts

@@ -0,0 +1,250 @@
+// figma-plugin/src/payload-schema.ts — Plan 31-05 (Wave B.2)
+//
+// Single plugin-side definition of the GDD Sync payload: the TS mirror of
+// scripts/lib/figma-extract/payload-schema.json (31-06), the shared Path C
+// contract (D-04, D-13). code.ts + export-variables.ts import the payload type
+// from here; buildPayload below is the PURE, network-free core the offline test
+// drives against a figma.variables mock.
+//
+// Two consumers, one payload (the make-or-break interop requirement):
+//   1. Receiver (31-06) validates source + collections[] + variables[] against
+//      payload-schema.json before writing variables.json.
+//   2. The digest's normalizePluginPayload (31-02) reads a FLAT tokens[] array
+//      (preferred) or payload.meta.* — it does NOT read top-level variables[].
+//      So the payload ALSO carries tokens[] (colors->hex, aliases->{name}, modes
+//      keyed by mode NAME) so plugin variables surface in DESIGN.md.
+//      additionalProperties:true permits the extra tokens[]. One object, both ends.
+//
+// D-13: ALL local variables are emitted — no published-only filter here; the
+// digest filters.
+
+/** Figma colour: 0..1 floats. `a` optional (RGB vs RGBA). */
+export interface GddRgba {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+/** Alias marker — kept resolvable: target id always, target name when looked up. */
+export interface GddVariableAlias {
+  type: 'VARIABLE_ALIAS';
+  id: string;
+  name?: string;
+}
+
+/** A per-mode value in the receiver-facing variables[] (raw, unrendered). */
+export type GddVariableValue =
+  | number
+  | string
+  | boolean
+  | GddRgba
+  | GddVariableAlias;
+
+// ── Receiver-facing shapes (validated against payload-schema.json) ────────────
+
+export interface GddSyncMode {
+  modeId: string;
+  name: string;
+}
+
+export interface GddSyncCollection {
+  id: string;
+  name: string;
+  modes: GddSyncMode[];
+}
+
+export interface GddSyncVariable {
+  id: string;
+  name: string;
+  /** COLOR | FLOAT | STRING | BOOLEAN (schema enum). */
+  resolvedType: string;
+  collectionId: string;
+  /** Keyed by modeId. Raw value or alias marker (digest renders later). */
+  valuesByMode: Record<string, GddVariableValue>;
+}
+
+// ── Digest-interop shape: the FLAT tokens[] normalizePluginPayload reads ───────
+// Matches digest.cjs extractTokensFromVariables() output so DESIGN.md is
+// identical across paths: { name, type, collection, modes:{ <modeName>: rendered } }
+// where rendered = hex for colours, `{targetName}` for aliases, primitive otherwise.
+
+export interface GddSyncToken {
+  name: string;
+  type: string;
+  /** Collection NAME (not id) — matches digest Path A. */
+  collection?: string;
+  /** Keyed by mode NAME → rendered value. */
+  modes: Record<string, unknown>;
+}
+
+export interface GddSyncPayload {
+  /** Path C marker the digest/receiver key on. Literal — never anything else. */
+  source: 'gdd-plugin';
+  fileKey?: string;
+  exportedAt?: string;
+  collections: GddSyncCollection[];
+  /** ALL local variables, raw values (D-13). */
+  variables: GddSyncVariable[];
+  /** Flat rendered tokens the digest consumes (variables[] is ignored there). */
+  tokens: GddSyncToken[];
+}
+
+// ── Pure value rendering (shared by the flat tokens[] builder) ────────────────
+
+function isRgba(v: unknown): v is GddRgba {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof (v as GddRgba).r === 'number' &&
+    typeof (v as GddRgba).g === 'number' &&
+    typeof (v as GddRgba).b === 'number'
+  );
+}
+
+function isAlias(v: unknown): v is GddVariableAlias {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as GddVariableAlias).type === 'VARIABLE_ALIAS' &&
+    typeof (v as GddVariableAlias).id === 'string'
+  );
+}
+
+/** Render Figma {r,g,b,a?} (0..1) to hex — mirrors digest.cjs rgbToHex. */
+export function rgbToHex({ r, g, b, a }: GddRgba): string {
+  const to = (v: number): string =>
+    Math.round(v * 255)
+      .toString(16)
+      .padStart(2, '0');
+  const hex = `#${to(r)}${to(g)}${to(b)}`;
+  return a !== undefined && a < 1 ? `${hex}${to(a)}` : hex;
+}
+
+/** colour→hex, alias→`{targetName}` (or `{id}`), else primitive passthrough. */
+export function renderTokenValue(raw: GddVariableValue): unknown {
+  if (isRgba(raw)) return rgbToHex(raw);
+  if (isAlias(raw)) return `{${raw.name || raw.id}}`;
+  return raw;
+}
+
+// ── The single pure builder (network-free; the testable core) ─────────────────
+
+/** Minimal collection shape buildPayload needs (mirrors VariableCollection). */
+export interface RawCollectionLike {
+  id: string;
+  name: string;
+  modes: ReadonlyArray<{ modeId: string; name: string }>;
+}
+
+/** Minimal variable shape buildPayload needs (mirrors Variable). */
+export interface RawVariableLike {
+  id: string;
+  name: string;
+  resolvedType: string;
+  variableCollectionId: string;
+  valuesByMode: Record<string, GddVariableValue>;
+}
+
+/** Resolve a variable id → name (Figma's getVariableById(...)?.name). */
+export type VariableNameResolver = (id: string) => string | undefined;
+
+export interface BuildPayloadOptions {
+  fileKey?: string;
+  exportedAt?: string;
+  resolveName?: VariableNameResolver;
+}
+
+/**
+ * Build a GddSyncPayload from raw collections + variables. PURE: no Figma
+ * globals, no network. Emits ALL variables passed in (D-13). Produces BOTH the
+ * receiver-facing variables[] (raw values, alias markers retained with resolved
+ * name) AND the flat rendered tokens[] the digest consumes.
+ */
+export function buildPayload(
+  rawCollections: ReadonlyArray<RawCollectionLike>,
+  rawVariables: ReadonlyArray<RawVariableLike>,
+  opts: BuildPayloadOptions = {}
+): GddSyncPayload {
+  const resolveName: VariableNameResolver = opts.resolveName || (() => undefined);
+
+  const collections: GddSyncCollection[] = rawCollections.map((c) => ({
+    id: c.id,
+    name: c.name,
+    modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
+  }));
+  const collectionById = new Map<string, GddSyncCollection>(
+    collections.map((c) => [c.id, c])
+  );
+
+  const variables: GddSyncVariable[] = [];
+  const tokens: GddSyncToken[] = [];
+
+  for (const v of rawVariables) {
+    // Receiver-facing valuesByMode: raw values, but resolve alias targets to a
+    // name (keep id + type) so it stays auditable. Keyed by modeId (schema).
+    const rawValuesByMode: Record<string, GddVariableValue> = {};
+    for (const modeId of Object.keys(v.valuesByMode)) {
+      const value = v.valuesByMode[modeId];
+      rawValuesByMode[modeId] = isAlias(value)
+        ? { type: 'VARIABLE_ALIAS', id: value.id, name: resolveName(value.id) }
+        : value;
+    }
+
+    variables.push({
+      id: v.id,
+      name: v.name,
+      resolvedType: v.resolvedType,
+      collectionId: v.variableCollectionId,
+      valuesByMode: rawValuesByMode,
+    });
+
+    // Flat token for the digest: rendered values keyed by mode NAME so a
+    // multi-mode (light/dark) variable round-trips.
+    const collection = collectionById.get(v.variableCollectionId);
+    const modesByName: Record<string, unknown> = {};
+    const modeList = collection ? collection.modes : [];
+    if (modeList.length > 0) {
+      for (const mode of modeList) {
+        const raw = rawValuesByMode[mode.modeId];
+        if (raw !== undefined) modesByName[mode.name] = renderTokenValue(raw);
+      }
+    } else {
+      // No collection metadata — fall back to modeId so nothing is dropped.
+      for (const modeId of Object.keys(rawValuesByMode)) {
+        modesByName[modeId] = renderTokenValue(rawValuesByMode[modeId]);
+      }
+    }
+
+    tokens.push({
+      name: v.name,
+      type: v.resolvedType,
+      collection: collection ? collection.name : undefined,
+      modes: modesByName,
+    });
+  }
+
+  const payload: GddSyncPayload = {
+    source: 'gdd-plugin',
+    collections,
+    variables,
+    tokens,
+  };
+  if (opts.fileKey) payload.fileKey = opts.fileKey;
+  if (opts.exportedAt) payload.exportedAt = opts.exportedAt;
+  return payload;
+}
+
+/**
+ * Narrow an unknown to GddSyncPayload: the literal source marker + the two
+ * required arrays. Cheap structural check (the receiver validates fully).
+ */
+export function isGddSyncPayload(x: unknown): x is GddSyncPayload {
+  if (typeof x !== 'object' || x === null) return false;
+  const p = x as Partial<GddSyncPayload>;
+  return (
+    p.source === 'gdd-plugin' &&
+    Array.isArray(p.collections) &&
+    Array.isArray(p.variables)
+  );
+}

package/figma-plugin/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "amd",
+    "moduleResolution": "node",
+    "lib": ["ES2017"],
+    "strict": true,
+    "outFile": "code.js",
+    "noEmitOnError": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "typeRoots": ["./node_modules/@types", "./node_modules/@figma"]
+  },
+  "include": ["code.ts", "src/**/*.ts"]
+}