@mp3wizard/figma-console-mcp 1.32.3 → 1.34.1

package/dist/cloudflare/core/port-discovery.js

@@ -18,6 +18,11 @@
  *     3. Age ceiling — startedAt older than 4 hours with no heartbeat (pre-v1.12 compat)
  *   Zombie processes are terminated with SIGTERM to free their ports.
  *
+ *   Cleanup exists in two flavors: synchronous (startup path, before the stdio
+ *   transport serves requests — blocking is acceptable there) and async
+ *   (periodic reaper — must never block the event loop, or in-flight MCP tool
+ *   calls freeze while lsof/ps/curl run).
+ *
  * Data flow:
  *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
  *   Server heartbeat → refreshes lastSeen every 30s
@@ -26,8 +31,11 @@
  */
 import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { tmpdir } from 'os';
+import { tmpdir, devNull } from 'os';
+import { execFile, execFileSync } from 'child_process';
+import { promisify } from 'util';
 import { createChildLogger } from './logger.js';
+const execFileAsync = promisify(execFile);
 const logger = createChildLogger({ component: 'port-discovery' });
 /** Default preferred WebSocket port */
 export const DEFAULT_WS_PORT = 9223;
@@ -170,10 +178,102 @@ export function isStaleInstance(data) {
     const startedAge = now - new Date(data.startedAt).getTime();
     return startedAge > MAX_PORT_FILE_AGE_MS;
 }
+/**
+ * Extra staleness margin required before a live-but-stale instance becomes
+ * kill-eligible: it must have missed at least 2 further heartbeats PAST the
+ * stale threshold. After a laptop sleeps, every instance's lastSeen is old
+ * simultaneously — this margin gives freshly-woken siblings time to refresh
+ * their advertisement files before any reaper considers killing them.
+ */
+export const KILL_ELIGIBLE_EXTRA_STALE_MS = 2 * HEARTBEAT_INTERVAL_MS;
+/**
+ * Whether a stale instance has been stale long enough to be kill-eligible.
+ * Pre-v1.12 files (no lastSeen) already use the conservative 4-hour age
+ * ceiling, so plain staleness is sufficient there.
+ */
+function isKillEligible(data) {
+    if (!data.lastSeen)
+        return isStaleInstance(data);
+    const lastSeenAge = Date.now() - new Date(data.lastSeen).getTime();
+    return lastSeenAge > HEARTBEAT_STALE_MS + KILL_ELIGIBLE_EXTRA_STALE_MS;
+}
+/**
+ * Ports reaching the probes come from JSON port files in a world-writable
+ * temp dir, so treat them as untrusted input. A garbage port means a garbage
+ * file — verdict is inconclusive (do NOT kill), same as any other ambiguity.
+ */
+function isValidProbePort(port) {
+    return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+/** curl arguments for the /health liveness probe against a sibling's port.
+ * `devNull` (not a literal /dev/null) — Windows ships curl.exe, and a bad
+ * output path there makes curl exit non-zero, which reads as "nothing
+ * responding" and would let the reaper kill a healthy sibling. */
+function healthProbeArgs(port) {
+    return ['-s', '-o', devNull, '-m', '1', `http://127.0.0.1:${port}/health`];
+}
+/**
+ * Liveness probe against a sibling server's HTTP `/health` endpoint (the
+ * WebSocket server serves it on the same port). Synchronous via curl —
+ * startup-path only; the periodic reaper uses probeServerHealthAsync.
+ * execFileSync (no shell) so the untrusted port can never be interpreted
+ * as shell syntax.
+ *
+ * @returns true  — server responded (alive, do NOT kill)
+ *          false — probe ran and failed (nothing responding on the port)
+ *          null  — inconclusive (curl missing / probe ambiguous — do NOT kill)
+ */
+function probeServerHealth(port) {
+    if (!isValidProbePort(port))
+        return null;
+    try {
+        execFileSync('curl', healthProbeArgs(port), {
+            timeout: 3000,
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch (error) {
+        // curl binary not found (no shell, so ENOENT instead of exit 127/9009) — inconclusive
+        if (error?.code === 'ENOENT')
+            return null;
+        // execFileSync-level timeout (killed by signal, no exit status) — inconclusive
+        if (error?.signal)
+            return null;
+        // curl ran and exited non-zero (connection refused, curl -m timeout, …)
+        if (typeof error?.status === 'number')
+            return false;
+        return null; // unknown failure — err on the side of NOT killing
+    }
+}
+/**
+ * Async variant of probeServerHealth for the periodic reaper — identical
+ * verdict semantics, but never blocks the event loop (execFile, no shell).
+ */
+async function probeServerHealthAsync(port) {
+    if (!isValidProbePort(port))
+        return null;
+    try {
+        await execFileAsync('curl', healthProbeArgs(port), { timeout: 3000 });
+        return true;
+    }
+    catch (error) {
+        // curl binary not found (no shell, so ENOENT instead of exit 127) — inconclusive
+        if (error?.code === 'ENOENT')
+            return null;
+        // execFile-level timeout (process killed by signal) — inconclusive
+        if (error?.killed || error?.signal)
+            return null;
+        // curl ran and exited non-zero (connection refused, curl -m timeout, …)
+        if (typeof error?.code === 'number')
+            return false;
+        return null; // unknown failure — err on the side of NOT killing
+    }
+}
 /**
  * Block the current thread for `ms` milliseconds (synchronous).
  * Used between SIGTERM and SIGKILL so terminateProcess can stay synchronous
- * (its callers — cleanup functions — are synchronous and use execSync).
+ * (its callers — the startup-path cleanup functions — are synchronous).
  */
 function sleepSyncMs(ms) {
     if (ms <= 0)
@@ -187,6 +287,35 @@ function sleepSyncMs(ms) {
         while (Date.now() < end) { /* best-effort spin fallback */ }
     }
 }
+/**
+ * Non-blocking sleep for the async reaper path. The timer is unref'd so an
+ * in-flight reaper wait never keeps the process alive on its own.
+ */
+function sleepMs(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    });
+}
+/**
+ * Parse `ps -o etime=` output into milliseconds.
+ * `etime` (formatted elapsed time) is portable across macOS and Linux;
+ * `etimes` (seconds) is Linux-only — macOS ps rejects it. Format is
+ * [[DD-]HH:]MM:SS, e.g. "05:51", "55:27", "01:13:31", "09-14:15:41".
+ */
+function parseEtimeMs(out) {
+    const m = out.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+    if (!m)
+        return null;
+    const days = parseInt(m[1] || '0', 10);
+    const hours = parseInt(m[2] || '0', 10);
+    const mins = parseInt(m[3], 10);
+    const secs = parseInt(m[4], 10);
+    return ((((days * 24 + hours) * 60 + mins) * 60) + secs) * 1000;
+}
 /**
  * Elapsed time since a process started, in milliseconds. Returns null if it
  * cannot be determined (process gone, or `ps` unavailable/unparseable).
@@ -196,21 +325,25 @@ function getProcessAgeMs(pid) {
         return null;
     try {
         const { execSync } = require('child_process');
-        // `etime` (formatted elapsed time) is portable across macOS and Linux;
-        // `etimes` (seconds) is Linux-only — macOS ps rejects it. Format is
-        // [[DD-]HH:]MM:SS, e.g. "05:51", "55:27", "01:13:31", "09-14:15:41".
         const out = execSync(`ps -p ${pid} -o etime= 2>/dev/null`, {
             encoding: 'utf-8',
             timeout: 2000,
-        }).trim();
-        const m = out.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
-        if (!m)
-            return null;
-        const days = parseInt(m[1] || '0', 10);
-        const hours = parseInt(m[2] || '0', 10);
-        const mins = parseInt(m[3], 10);
-        const secs = parseInt(m[4], 10);
-        return ((((days * 24 + hours) * 60 + mins) * 60) + secs) * 1000;
+        });
+        return parseEtimeMs(out);
+    }
+    catch {
+        return null;
+    }
+}
+/** Async variant of getProcessAgeMs for the periodic reaper. */
+async function getProcessAgeMsAsync(pid) {
+    if (process.platform === 'win32')
+        return null;
+    try {
+        const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'etime='], {
+            timeout: 2000,
+        });
+        return parseEtimeMs(stdout);
     }
     catch {
         return null;
@@ -251,6 +384,37 @@ function terminateProcess(pid, graceMs = TERMINATE_GRACE_MS) {
     sleepSyncMs(Math.min(graceMs, 200));
     return !isProcessAlive(pid);
 }
+/**
+ * Async variant of terminateProcess for the periodic reaper — identical
+ * SIGTERM→SIGKILL escalation, but the grace waits yield the event loop
+ * instead of blocking it.
+ *
+ * @returns true if the process is confirmed gone afterwards, false if it survived.
+ */
+async function terminateProcessAsync(pid, graceMs = TERMINATE_GRACE_MS) {
+    // SIGTERM first — give the process a chance to shut down gracefully.
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return true; // already gone — nothing to terminate
+    }
+    // Windows: SIGTERM maps to TerminateProcess (immediate, uncatchable).
+    if (process.platform === 'win32')
+        return !isProcessAlive(pid);
+    // POSIX: let the graceful handler run, then force-kill if it ignored SIGTERM.
+    await sleepMs(graceMs);
+    if (!isProcessAlive(pid))
+        return true;
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        return true; // exited between the check and the kill
+    }
+    await sleepMs(Math.min(graceMs, 200));
+    return !isProcessAlive(pid);
+}
 /**
  * Read and validate a port advertisement file.
  * Returns null if the file doesn't exist, is invalid, or the owning process is dead.
@@ -317,14 +481,96 @@ export function cleanupStalePortFiles() {
                         logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file (dead process)');
                     }
                     else if (data.pid !== process.pid && isStaleInstance(data)) {
-                        // Live PID but stale — zombie process, terminate it to free the port
-                        logger.info({ port: data.port, pid: data.pid, startedAt: data.startedAt, lastSeen: data.lastSeen }, 'Detected zombie MCP process — sending SIGTERM to free port');
-                        terminateProcess(data.pid);
-                        try {
-                            unlinkSync(filePath);
+                        // Live PID but stale heartbeat. Staleness alone is NOT proof of
+                        // death — after the machine sleeps longer than HEARTBEAT_STALE_MS,
+                        // ALL instances look stale at once and whichever reaper ticks first
+                        // would kill healthy siblings. Verify actual deadness before
+                        // terminating: extra staleness margin + failed liveness probe.
+                        if (!isKillEligible(data)) {
+                            logger.debug({ port: data.port, pid: data.pid, lastSeen: data.lastSeen }, 'Stale instance within kill-eligibility margin — skipping');
+                        }
+                        else {
+                            const health = probeServerHealth(data.port);
+                            if (health !== false) {
+                                logger.debug({ port: data.port, pid: data.pid, probe: health === true ? 'responding' : 'inconclusive' }, 'Stale-looking instance not confirmed dead by liveness probe — skipping kill');
+                            }
+                            else {
+                                logger.info({ port: data.port, pid: data.pid, startedAt: data.startedAt, lastSeen: data.lastSeen }, 'Detected zombie MCP process (stale heartbeat, health probe failed) — sending SIGTERM to free port');
+                                terminateProcess(data.pid);
+                                try {
+                                    unlinkSync(filePath);
+                                }
+                                catch { /* best-effort */ }
+                                cleaned++;
+                            }
                         }
-                        catch { /* best-effort */ }
+                    }
+                }
+                catch {
+                    // Corrupt file — remove it
+                    try {
+                        unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    catch {
+        // Can't read /tmp — unusual but not fatal
+    }
+    return cleaned;
+}
+/**
+ * Async variant of cleanupStalePortFiles for the periodic reaper.
+ *
+ * Same detection layers and kill-safety gates as the sync version (dead PID →
+ * delete file; live-but-stale → kill-eligibility margin + failed liveness
+ * probe before terminating; corrupt → delete file), but the probe and the
+ * SIGTERM→SIGKILL grace waits are non-blocking so a slow pass never stalls
+ * the stdio MCP transport.
+ */
+export async function cleanupStalePortFilesAsync() {
+    let cleaned = 0;
+    try {
+        const files = readdirSync(PORT_FILE_DIR);
+        for (const file of files) {
+            if (file.startsWith(PORT_FILE_PREFIX) && file.endsWith('.json')) {
+                const filePath = join(PORT_FILE_DIR, file);
+                try {
+                    const raw = readFileSync(filePath, 'utf-8');
+                    const data = JSON.parse(raw);
+                    if (!isProcessAlive(data.pid)) {
+                        // Dead PID — just clean up the file
+                        unlinkSync(filePath);
                         cleaned++;
+                        logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file (dead process)');
+                    }
+                    else if (data.pid !== process.pid && isStaleInstance(data)) {
+                        // Live PID but stale heartbeat. Staleness alone is NOT proof of
+                        // death — after the machine sleeps longer than HEARTBEAT_STALE_MS,
+                        // ALL instances look stale at once and whichever reaper ticks first
+                        // would kill healthy siblings. Verify actual deadness before
+                        // terminating: extra staleness margin + failed liveness probe.
+                        if (!isKillEligible(data)) {
+                            logger.debug({ port: data.port, pid: data.pid, lastSeen: data.lastSeen }, 'Stale instance within kill-eligibility margin — skipping');
+                        }
+                        else {
+                            const health = await probeServerHealthAsync(data.port);
+                            if (health !== false) {
+                                logger.debug({ port: data.port, pid: data.pid, probe: health === true ? 'responding' : 'inconclusive' }, 'Stale-looking instance not confirmed dead by liveness probe — skipping kill');
+                            }
+                            else {
+                                logger.info({ port: data.port, pid: data.pid, startedAt: data.startedAt, lastSeen: data.lastSeen }, 'Detected zombie MCP process (stale heartbeat, health probe failed) — sending SIGTERM to free port');
+                                await terminateProcessAsync(data.pid);
+                                try {
+                                    unlinkSync(filePath);
+                                }
+                                catch { /* best-effort */ }
+                                cleaned++;
+                            }
+                        }
                     }
                 }
                 catch {
@@ -389,7 +635,7 @@ export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT, option
                         encoding: 'utf-8',
                         timeout: 2000,
                     }).trim();
-                    if (cmdline.includes('figma-console-mcp') || cmdline.includes('figma_console_mcp') || cmdline.includes('local.js')) {
+                    if (isMcpServerCommand(cmdline)) {
                         // Don't reap a sibling that is still starting up (bound a port but
                         // hasn't advertised yet). Real orphans are far older than this.
                         const ageMs = getProcessAgeMs(pid);
@@ -429,6 +675,110 @@ export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT, option
     }
     return cleaned;
 }
+/** Whether a process command line identifies a figma-console-mcp server. */
+function isMcpServerCommand(cmdline) {
+    return cmdline.includes('figma-console-mcp') || cmdline.includes('figma_console_mcp') || cmdline.includes('local.js');
+}
+/**
+ * List PIDs listening on ports in the range via a single batched lsof call.
+ * Returns a map of pid → first listening port seen (for logging). The sync
+ * startup path runs lsof once per port; batching matters here because the
+ * periodic reaper must not hold the event loop across 10 sequential calls.
+ */
+async function listListeningPidsAsync(ports) {
+    const pidToPort = new Map();
+    const low = ports[0];
+    const high = ports[ports.length - 1];
+    let stdout = '';
+    try {
+        ({ stdout } = await execFileAsync('lsof', ['-nP', `-iTCP:${low}-${high}`, '-sTCP:LISTEN', '-Fpn'], { timeout: 5000 }));
+    }
+    catch (error) {
+        // lsof exits 1 when nothing matches; any partial output is still usable
+        stdout = typeof error?.stdout === 'string' ? error.stdout : '';
+    }
+    // -F output: `p<pid>` starts a process group, `n<host:port>` lines follow
+    let currentPid = null;
+    for (const line of stdout.split('\n')) {
+        if (line.startsWith('p')) {
+            const pid = parseInt(line.slice(1), 10);
+            currentPid = Number.isFinite(pid) ? pid : null;
+        }
+        else if (line.startsWith('n') && currentPid !== null) {
+            const m = line.match(/:(\d+)(?:\s|$)/);
+            if (!m)
+                continue;
+            const port = parseInt(m[1], 10);
+            if (ports.includes(port) && !pidToPort.has(currentPid)) {
+                pidToPort.set(currentPid, port);
+            }
+        }
+    }
+    return pidToPort;
+}
+/**
+ * Async variant of cleanupOrphanedProcesses for the periodic reaper.
+ *
+ * Same safety guards as the sync version (known-PID skip, MCP command-line
+ * check, ORPHAN_MIN_AGE_MS age guard, confirmed-kill counting), but all child
+ * processes run via async execFile and the lsof scan is a single batched call
+ * over the port range — a slow tick no longer freezes in-flight tool calls on
+ * the stdio transport.
+ */
+export async function cleanupOrphanedProcessesAsync(preferredPort = DEFAULT_WS_PORT, options = {}) {
+    // Only supported on macOS/Linux (lsof)
+    if (process.platform === 'win32')
+        return 0;
+    const minAgeMs = options.minAgeMs ?? ORPHAN_MIN_AGE_MS;
+    let cleaned = 0;
+    const myPid = process.pid;
+    const ports = getPortRange(preferredPort);
+    // Collect PIDs that have valid port files (known-good servers)
+    const knownPids = new Set();
+    for (const port of ports) {
+        const data = readPortFile(port);
+        if (data)
+            knownPids.add(data.pid);
+    }
+    knownPids.add(myPid); // Never kill ourselves
+    const pidToPort = await listListeningPidsAsync(ports);
+    for (const [pid, port] of pidToPort) {
+        if (knownPids.has(pid))
+            continue; // Skip known-good servers
+        // Verify this is actually a figma-console-mcp process before killing
+        try {
+            const { stdout } = await execFileAsync('ps', ['-p', String(pid), '-o', 'command='], {
+                timeout: 2000,
+            });
+            const cmdline = stdout.trim();
+            if (isMcpServerCommand(cmdline)) {
+                // Don't reap a sibling that is still starting up (bound a port but
+                // hasn't advertised yet). Real orphans are far older than this.
+                const ageMs = await getProcessAgeMsAsync(pid);
+                if (minAgeMs > 0 && ageMs !== null && ageMs < minAgeMs) {
+                    continue;
+                }
+                logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                // Only count confirmed kills, matching the sync path.
+                if (await terminateProcessAsync(pid)) {
+                    cleaned++;
+                }
+                else {
+                    logger.warn({ port, pid }, 'Failed to terminate orphaned MCP server (survived SIGKILL)');
+                }
+            }
+        }
+        catch {
+            // Can't read process info — skip to be safe
+        }
+    }
+    if (cleaned > 0) {
+        // Give terminated processes a moment to release their ports
+        await sleepMs(500);
+        logger.info({ cleaned }, `Cleaned up ${cleaned} orphaned MCP server process(es)`);
+    }
+    return cleaned;
+}
 /**
  * Last-resort eviction: terminate the oldest MCP server instance to free a port.
  *
@@ -522,11 +872,8 @@ export function evictOldestInstance(preferredPort = DEFAULT_WS_PORT) {
 export function registerPortCleanup(port) {
     const cleanup = () => unadvertisePort(port);
     process.on('exit', cleanup);
-    // Re-register SIGINT/SIGTERM to ensure cleanup runs before the
-    // existing handlers in local.ts main() call process.exit()
-    const originalSigintListeners = process.listeners('SIGINT');
-    const originalSigtermListeners = process.listeners('SIGTERM');
-    // Prepend our cleanup — it runs first, then existing handlers take over
+    // Prepend our cleanup — it runs first before the existing SIGINT/SIGTERM
+    // handlers in local.ts main() call process.exit()
     process.prependListener('SIGINT', cleanup);
     process.prependListener('SIGTERM', cleanup);
 }
@@ -541,22 +888,48 @@ export function registerPortCleanup(port) {
  * every 30s) so they are in the known-PID set and skipped, and the age guard in
  * cleanupOrphanedProcesses protects mid-startup siblings.
  *
+ * The tick runs the fully-async cleanup variants — the sync ones issue
+ * blocking lsof/ps/curl calls (seconds each under load), which would stall
+ * the stdio MCP transport and freeze in-flight tool calls. Only the startup
+ * path (before the transport is serving requests) uses the sync variants.
+ *
  * The interval is unref'd so it never keeps the process alive on its own.
  *
  * @returns a stop function that clears the interval.
  */
 export function startPeriodicReaper(preferredPort = DEFAULT_WS_PORT) {
-    const tick = () => {
+    let running = false;
+    let stopped = false;
+    const tick = async () => {
+        if (running)
+            return; // previous tick still in flight — skip this one
+        running = true;
         try {
-            cleanupStalePortFiles();
-            cleanupOrphanedProcesses(preferredPort);
+            // Refresh our OWN advertisement first so sibling reapers see us fresh.
+            // Post-sleep, every instance's lastSeen is stale simultaneously — the
+            // first reaper to tick must not look like a zombie to the others.
+            // refreshPortAdvertisement is a no-op for files owned by other PIDs,
+            // so scanning the whole range only touches our own file.
+            for (const port of getPortRange(preferredPort)) {
+                refreshPortAdvertisement(port);
+            }
+            await cleanupStalePortFilesAsync();
+            if (stopped)
+                return;
+            await cleanupOrphanedProcessesAsync(preferredPort);
         }
         catch (error) {
             logger.warn({ error }, 'Periodic reaper tick failed');
         }
+        finally {
+            running = false;
+        }
     };
-    const interval = setInterval(tick, REAP_INTERVAL_MS);
+    const interval = setInterval(() => { void tick(); }, REAP_INTERVAL_MS);
     if (typeof interval.unref === 'function')
         interval.unref();
-    return () => clearInterval(interval);
+    return () => {
+        stopped = true;
+        clearInterval(interval);
+    };
 }

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

@@ -12,19 +12,89 @@
  *   - Detects cycles.
  */
 /**
- * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
- * objects. Used as the index for resolveAliases().
+ * 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 buildTokenIndex(doc) {
+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 key = token.path.join(".");
-            index.set(key, token);
+            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.

package/dist/cloudflare/core/tokens/config.js

@@ -42,6 +42,16 @@ const OutputTargetSchema = z.object({
      * for CSS/SCSS/Tailwind/etc. since they can't natively express aliases).
      */
     resolveAliases: z.boolean().optional(),
+    /**
+     * 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.enum(["legacy", "2025"]).optional(),
     /** Per-target transform options. Override the global defaults. */
     transforms: z
         .object({