raptor-aios 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [0.11.0] - 2026-06-12
+
+### Added
+
+- **Integração Figma/Design — captura determinística + seed + gate (`packages/core/src/design/`).** Um link do Figma em `raptor new --figma <url>` deixa de ser só uma URL na spec: o Raptor CAPTURA o design de forma determinística e SEMEIA `design/` com os artefatos reais (espelhando o modelo do enriquecimento Jira). A captura usa o provider **`figma-rest`** (REST API + Personal Access Token, determinístico e roda em CI), selecionável via `design.provider` no `raptor.yml`.
+  - **Tokens** via `GET /v1/files/:key/variables/local` (com fallback para `/styles` quando o endpoint dá `403` em planos não-Enterprise ou volta vazio), normalizados em `design/tokens.json` (colors/typography/spacing/radii) por uma classificação robusta a nomes inconsistentes do mundo real (o valor decide antes do nome; tipografia decomposta em family/size/weight/lineHeight/letterSpacing — um número nunca vira família).
+  - **Telas** via `GET /v1/files/:key/nodes` (nó linkado) ou `?depth=2` (arquivo inteiro) → `design/screens/<slug>.md`.
+  - **Assets** escopados ao frame: o render do nó (`/v1/images`) + os image fills que a subárvore realmente pinta (`collectImageRefs` sobre `/nodes`, filtrando o `/v1/files/:key/images` que devolve o arquivo inteiro) — baixados com `sha256`, guarda anti-SSRF e `max_bytes`, catalogados em `design/assets-manifest.json`.
+  - **Fontes** (o Figma não serve o binário) resolvidas por precedência repo/brand → Google Fonts → OS (`fc-match`) → `pending`.
+  - **Comandos** `raptor design connect | status | pull | sync | disconnect` (o `sync` re-semeia idempotente — nunca sobrescreve refino — e emite `design.synced`).
+  - **Flip REDISTRIBUIR**: `spec.md.hbs`, os prompts de comando (`specify`/`plan`/`tasks`) e o prompt canônico bifurcam — quando o design foi semeado, instruem o agente a **REFINAR e redistribuir** os artefatos em disco (referenciar por `[screen: X]`/`[asset: Y]`, refinar os `screens/*.md`, verificar os tokens, declarar as libs); sem captura, mantêm a instrução de **ENXERGAR** via Figma MCP. O `spec.md.hbs` lista o que foi semeado (contagem de tokens, telas, assets, libs).
+  - **`gate.design.ready`** cobra a incorporação na promoção da spec (telas/assets referenciados existem e estão em disco; tokens não-vazios).
+  - **Auditoria** enriquecida (`feature.created`/`design.imported` com contagens de tokens/telas/assets; novo evento `design.synced`).
+  - Validado E2E contra o arquivo Check-in real (`figma-rest`/PAT) e endurecido por revisão adversarial multi-dimensão: escopo de assets (1357 imagens espúrias → 0), classificação de tokens (63 → 93 bem distribuídos, 0 famílias falsas), memoização de `/nodes`. Doc: [`docs/design-figma-sync.md`](docs/design-figma-sync.md).
+
 ## [0.10.0] - 2026-06-11
 
 ### Added

package/dist/_core/dist/agents/prompt-builder.js

@@ -33,9 +33,10 @@ const PHASE_MAP = {
             "   e todo id de AC é espelhado no frontmatter `acceptance.ids`.",
             "6. Success Criteria mensuráveis e tecnologia-agnósticos (foco no usuário).",
             "7. Auto-valide contra o 'Review & Acceptance Checklist' do template antes de entregar.",
-            "8. Se a feature tiver design anexado (pasta `design/` presente ou seção `## Design Reference`",
-            "   na spec), use suas ferramentas de design (Figma MCP) para ENXERGAR o design: derive",
-            "   telas, fluxos e critérios das telas reais e crie `design/screens/<nome>.md` por tela.",
+            "8. Se a feature tiver design (pasta `design/` ou seção `## Design Reference`): se já houver",
+            "   artefatos semeados (`design/tokens.json` populado, `design/screens/*.md`), REFINE e",
+            "   redistribua esses artefatos em vez de re-buscar; senão use o Figma MCP para ENXERGAR o",
+            "   design. Derive telas/fluxos/critérios das telas reais e refine (ou crie) `design/screens/<nome>.md`.",
             "",
             "### Feature a especificar:",
             "",
@@ -67,8 +68,9 @@ const PHASE_MAP = {
             "3. Inclua Data Model, Contracts e Research quando aplicável.",
             "4. Gere Complexity Tracking se algum gate for violado.",
             "5. Não invente onde a spec tem `[NEEDS CLARIFICATION]`.",
-            "6. Se a feature tiver design (pasta `design/`), use o Figma MCP para extrair tokens em",
-            "   `design/tokens.json` e declarar as bibliotecas/design-system necessárias no plan.",
+            "6. Se a feature tiver design (pasta `design/`): se `design/tokens.json` já estiver populado,",
+            "   VERIFIQUE/corrija os tokens semeados; senão extraia via Figma MCP. Declare as",
+            "   bibliotecas/design-system necessárias no plan.",
         ].join("\n"),
     },
     tasks: {
@@ -97,9 +99,9 @@ const PHASE_MAP = {
             "3. Inclua critério de aceite técnico por task.",
             "4. Ordene pela dependência natural (build-order).",
             "5. Toda task deve ser completável em ≤4h.",
-            "6. Se a feature tiver design (pasta `design/`), gere tasks que baixem os assets via Figma",
-            "   MCP para `assets/{images,icons,fonts}`, os cataloguem em `design/assets-manifest.json`",
-            "   e os referenciem por caminho concreto (tags `[screen: X]` / `[asset: X]`).",
+            "6. Se a feature tiver design (pasta `design/`): consuma os assets já catalogados em",
+            "   `design/assets-manifest.json` (baixados em `assets/{images,icons,fonts}`) e baixe via",
+            "   Figma MCP só o que faltar; referencie por caminho concreto (tags `[screen: X]` / `[asset: X]`).",
         ].join("\n"),
     },
     implement: {

package/dist/_core/dist/audit/schema.js

@@ -64,6 +64,7 @@ export const auditEventSchema = {
                 "hotfix.reconciled",
                 "jira.issues.created",
                 "design.imported",
+                "design.synced",
                 "branch.created",
                 "branch.switched",
                 "commit.guarded",

package/dist/_core/dist/design/asset-normalize.js

@@ -0,0 +1,37 @@
+import { slugify } from "./slug.js";
+import { assetDirFor, classifyAssetType, extForFormat, extFromUrl } from "./asset-paths.js";
+export function normalizeImagesToAssets(renders, fills, opts = {}) {
+    const out = [];
+    const seen = new Set();
+    const fmt = opts.format ?? "png";
+    const renderType = classifyAssetType(fmt);
+    const renderExt = extForFormat(fmt);
+    const renderDir = assetDirFor(renderType);
+    for (const [nodeId, url] of Object.entries(renders)) {
+        if (!url)
+            continue;
+        const human = opts.names?.[nodeId];
+        let base = slugify(human || `node ${nodeId}`) || slugify(`node ${nodeId}`);
+        let path = `${renderDir}/${base}.${renderExt}`;
+        if (seen.has(path)) {
+            base = `${base}-${slugify(nodeId)}`;
+            path = `${renderDir}/${base}.${renderExt}`;
+        }
+        seen.add(path);
+        out.push({ name: human || base, type: renderType, path, url, figma_node_id: nodeId });
+    }
+    for (const [ref, url] of Object.entries(fills)) {
+        if (!url)
+            continue;
+        let base = slugify(`fill ${ref}`).slice(0, 40) || slugify(`fill ${ref}`);
+        const ext = extFromUrl(url) ?? "png";
+        let path = `assets/images/${base}.${ext}`;
+        if (seen.has(path)) {
+            base = `${base}-${slugify(ref)}`.slice(0, 60);
+            path = `assets/images/${base}.${ext}`;
+        }
+        seen.add(path);
+        out.push({ name: base, type: "image", path, url });
+    }
+    return out;
+}

package/dist/_core/dist/design/asset-paths.js

@@ -0,0 +1,23 @@
+export function classifyAssetType(format) {
+    return format.trim().toLowerCase() === "svg" ? "svg" : "image";
+}
+export function assetDirFor(type) {
+    if (type === "svg" || type === "icon")
+        return "assets/icons";
+    if (type === "font")
+        return "assets/fonts";
+    return "assets/images";
+}
+export function extForFormat(format) {
+    const f = format.trim().toLowerCase();
+    if (!/^[a-z0-9]{2,5}$/.test(f))
+        return "png";
+    return f === "jpeg" ? "jpg" : f;
+}
+export function extFromUrl(url) {
+    const m = url.match(/\.([A-Za-z0-9]{2,5})(?:[?#]|$)/);
+    if (!m)
+        return null;
+    const ext = m[1].toLowerCase();
+    return ext === "jpeg" ? "jpg" : ext;
+}

package/dist/_core/dist/design/downloader.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { normalizePath } from "./slug.js";
+export class DownloadError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "DownloadError";
+    }
+}
+export async function downloadAsset(url, destAbs, opts = {}) {
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    const max = opts.maxBytes && opts.maxBytes > 0 ? opts.maxBytes : 0;
+    assertSafeAssetUrl(url, opts.allowHttp ?? false);
+    let res;
+    try {
+        res = await doFetch(url, opts.headers ? { headers: opts.headers } : {});
+    }
+    catch (err) {
+        throw new DownloadError(`download failed for ${url}: ${err instanceof Error ? err.message : String(err)}`, 0);
+    }
+    if (!res.ok) {
+        throw new DownloadError(`download ${url} → ${res.status} ${res.statusText}`, res.status);
+    }
+    const contentType = res.headers.get("content-type") ?? undefined;
+    const declared = Number(res.headers.get("content-length") ?? "");
+    if (max && Number.isFinite(declared) && declared > max) {
+        throw new DownloadError(`download ${url} exceeds max_bytes (${declared} > ${max})`, res.status);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (max && buf.length > max) {
+        throw new DownloadError(`download ${url} exceeds max_bytes (${buf.length} > ${max})`, res.status);
+    }
+    mkdirSync(dirname(destAbs), { recursive: true });
+    writeFileSync(destAbs, buf);
+    const hash = createHash("sha256").update(buf).digest("hex");
+    return { hash, bytes: buf.length, ...(contentType ? { contentType } : {}) };
+}
+export async function downloadAll(pending, root, opts = {}) {
+    const concurrency = Math.max(1, opts.concurrency ?? 4);
+    const results = new Array(pending.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= pending.length)
+                return;
+            const a = pending[i];
+            if (!a)
+                return;
+            const base = {
+                name: a.name,
+                type: a.type,
+                path: a.path,
+                ...(a.figma_node_id ? { figma_node_id: a.figma_node_id } : {}),
+                ...(a.screen ? { screen: a.screen } : {}),
+            };
+            try {
+                const rel = normalizePath(a.path);
+                const rootAbs = resolve(root);
+                const within = resolve(rootAbs, rel);
+                if (isAbsolute(rel) || (within !== rootAbs && !within.startsWith(rootAbs + sep))) {
+                    throw new DownloadError(`asset path escapes project root: ${a.path}`, 0);
+                }
+                const destAbs = join(root, rel);
+                const { hash } = await downloadAsset(a.url, destAbs, opts);
+                results[i] = { ...base, hash, status: "downloaded" };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (opts.onWarn)
+                    opts.onWarn(`asset "${a.name}" not downloaded: ${msg}`);
+                else
+                    process.stderr.write(`Warning: asset "${a.name}" not downloaded: ${msg}\n`);
+                results[i] = { ...base, status: "pending" };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, worker));
+    return results;
+}
+function assertSafeAssetUrl(url, allowHttp) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new DownloadError(`invalid asset URL: ${url}`, 0);
+    }
+    if (u.protocol !== "https:" && !(allowHttp && u.protocol === "http:")) {
+        throw new DownloadError(`refusing non-https asset URL (${u.protocol}//…)`, 0);
+    }
+    const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (isInternalHost(host)) {
+        throw new DownloadError(`refusing asset URL to internal host: ${host}`, 0);
+    }
+}
+function isInternalHost(host) {
+    if (host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if (host === "metadata.google.internal")
+        return true;
+    if (host.includes(":")) {
+        if (host === "::1" || host === "::")
+            return true;
+        if (host.startsWith("fe80:"))
+            return true;
+        if (/^f[cd][0-9a-f]{2}:/.test(host))
+            return true;
+        if (host.startsWith("::ffff:")) {
+            const rest = host.slice("::ffff:".length);
+            if (rest.includes("."))
+                return isInternalHost(rest);
+            const hx = rest.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+            if (hx) {
+                const hi = parseInt(hx[1], 16);
+                const lo = parseInt(hx[2], 16);
+                return isInternalHost(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+            }
+        }
+        return false;
+    }
+    const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (m) {
+        const a = Number(m[1]);
+        const b = Number(m[2]);
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        return false;
+    }
+    return false;
+}

package/dist/_core/dist/design/fetcher.js

@@ -0,0 +1,203 @@
+import { downloadAll } from "./downloader.js";
+import { resolveFonts } from "./font-resolver.js";
+function warn(opts, message) {
+    if (opts.onWarn)
+        opts.onWarn(message);
+    else
+        process.stderr.write(`Warning: ${message}\n`);
+}
+export async function fetchDesignData(refs, client, opts = {}) {
+    const varMap = {};
+    for (const ref of refs) {
+        try {
+            const m = await client.getVariableDefs(ref.fileKey, ref.nodeId);
+            Object.assign(varMap, m);
+        }
+        catch (err) {
+            warn(opts, `Figma variables read failed for ${ref.url}: ${errMsg(err)}`);
+        }
+    }
+    const libraries = new Set();
+    if (client.getLibraries) {
+        for (const ref of refs) {
+            try {
+                for (const lib of await client.getLibraries(ref.fileKey))
+                    libraries.add(lib);
+            }
+            catch (err) {
+                warn(opts, `Figma libraries read failed for ${ref.url}: ${errMsg(err)}`);
+            }
+        }
+    }
+    const tokens = normalizeVariablesToTokens(varMap, opts.source);
+    const screens = await captureScreens(refs, client, opts);
+    const assets = [];
+    if (opts.root) {
+        assets.push(...(await captureAssets(refs, client, tokens.typography, opts)));
+    }
+    return {
+        tokens,
+        screens,
+        assets,
+        libraries: [...libraries],
+    };
+}
+async function captureScreens(refs, client, opts) {
+    if (!client.captureScreens)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const ref of refs) {
+        try {
+            for (const s of await client.captureScreens(ref.fileKey, ref.nodeId)) {
+                const key = s.nodeId
+                    ? `id:${s.file ?? ""}#${s.nodeId}`
+                    : `nm:${s.file ?? ""}#${s.name}#${s.summary ?? ""}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(s);
+            }
+        }
+        catch (err) {
+            warn(opts, `Figma screens read failed for ${ref.url}: ${errMsg(err)}`);
+        }
+    }
+    return out;
+}
+async function captureAssets(refs, client, typography, opts) {
+    const root = opts.root;
+    const format = opts.assets?.format ?? "svg";
+    const scale = opts.assets?.scale ?? 2;
+    const maxBytes = opts.assets?.maxBytes ?? 5_000_000;
+    const fetchImpl = opts.deps?.fetchImpl;
+    const pending = [];
+    const seenPaths = new Set();
+    if (client.captureAssets) {
+        for (const ref of refs) {
+            try {
+                const found = await client.captureAssets(ref.fileKey, ref.nodeId, { format, scale });
+                for (const p of found) {
+                    if (seenPaths.has(p.path))
+                        continue;
+                    seenPaths.add(p.path);
+                    pending.push(p);
+                }
+            }
+            catch (err) {
+                warn(opts, `Figma asset read failed for ${ref.url}: ${errMsg(err)}`);
+            }
+        }
+    }
+    const out = [];
+    if (pending.length) {
+        const entries = await downloadAll(pending, root, {
+            ...(fetchImpl ? { fetchImpl } : {}),
+            maxBytes,
+            ...(opts.concurrency ? { concurrency: opts.concurrency } : {}),
+            ...(opts.onWarn ? { onWarn: opts.onWarn } : {}),
+        });
+        for (const e of entries) {
+            if (e.status === "downloaded")
+                out.push(e);
+            else
+                warn(opts, `asset "${e.name}" could not be downloaded — left pending (not catalogued)`);
+        }
+    }
+    const fontEntries = await resolveFonts(typography, {
+        root,
+        brandDir: opts.fonts?.brandDir ?? "assets/fonts",
+        google: opts.fonts?.google !== false,
+        os: opts.fonts?.os !== false,
+        maxBytes,
+        deps: {
+            ...(fetchImpl ? { fetchImpl } : {}),
+            ...(opts.deps?.fcMatch ? { fcMatch: opts.deps.fcMatch } : {}),
+            ...(opts.deps?.osFontDirs ? { osFontDirs: opts.deps.osFontDirs } : {}),
+        },
+        ...(opts.onWarn ? { onWarn: opts.onWarn } : {}),
+    });
+    out.push(...fontEntries);
+    return out;
+}
+export function isColorValue(value) {
+    const v = value.trim().toLowerCase();
+    return /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(v) || /^rgba?\(/.test(v);
+}
+export function isNumericValue(value) {
+    return /^-?\d+(\.\d+)?(px|rem|em|pt|%)?$/.test(value.trim());
+}
+export function classifyToken(name, value) {
+    const lname = name.toLowerCase();
+    if (isColorValue(value))
+        return "color";
+    if (value === "true" || value === "false")
+        return "unknown";
+    if (/(radius|radii|corner|rounded)/.test(lname))
+        return "radius";
+    if (/(font|typograph|leading|line-?height|letter-?spacing|\btext\b|\btype\b)/.test(lname)) {
+        return "typography";
+    }
+    if (!isNumericValue(value) && /(colou?r|fill|bg|background|surface|border|stroke|brand|shadow)/.test(lname)) {
+        return "color";
+    }
+    if (/(spac|sizing|gap|pad|margin|inset|\bsize\b|dimension|width|height)/.test(lname)) {
+        return "spacing";
+    }
+    return "unknown";
+}
+function typographyField(name, value) {
+    const ln = name.toLowerCase();
+    if (/weight/.test(ln))
+        return { fontWeight: value };
+    if (/(line-?height|leading)/.test(ln))
+        return { lineHeight: value };
+    if (/(letter-?spacing|tracking)/.test(ln))
+        return { letterSpacing: value };
+    if (/size/.test(ln) || isNumericValue(value))
+        return { fontSize: value };
+    return { fontFamily: value };
+}
+export function normalizeVariablesToTokens(map, source) {
+    const colors = [];
+    const spacing = [];
+    const radii = [];
+    const typography = [];
+    for (const [rawName, rawValue] of Object.entries(map)) {
+        const name = rawName.trim();
+        const value = String(rawValue).trim();
+        if (!name || !value)
+            continue;
+        switch (classifyToken(name, value)) {
+            case "color":
+                colors.push({ name, value });
+                break;
+            case "radius":
+                radii.push({ name, value });
+                break;
+            case "spacing":
+                spacing.push({ name, value });
+                break;
+            case "typography":
+                typography.push({ name, ...typographyField(name, value) });
+                break;
+        }
+    }
+    const tokens = { colors, typography, spacing };
+    if (radii.length)
+        tokens.radii = radii;
+    if (source) {
+        tokens.source = {
+            provider: source.provider,
+            ...(source.fileKey ? { fileKey: source.fileKey } : {}),
+            ...(source.generatedAt ? { generatedAt: source.generatedAt } : {}),
+        };
+    }
+    return tokens;
+}
+export function seededTokensCount(t) {
+    return t.colors.length + t.typography.length + t.spacing.length + (t.radii?.length ?? 0);
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/_core/dist/design/figma-client.js

@@ -0,0 +1,198 @@
+import { connectOAuthMcp, connectStdioMcp, } from "../transport/mcp.js";
+import { FIGMA_REMOTE_DIALECT, detectFigmaDialect, resolveFigmaDialect, } from "./figma-dialects.js";
+import { FigmaOAuthProvider, FIGMA_MCP_URL, openBrowser, startCallbackServer, } from "./figma-oauth.js";
+import { assetDirFor, classifyAssetType, extForFormat, extFromUrl, } from "./asset-paths.js";
+import { normalizeMetadataToScreens, pageIdsFromMetadata } from "./screens.js";
+import { slugify } from "./slug.js";
+export function makeFigmaMcpClient(caller, opts = {}) {
+    const dialect = opts.dialect ?? detectFigmaDialect(caller.toolNames) ?? FIGMA_REMOTE_DIALECT;
+    const resolve = (op) => {
+        const candidates = dialect.toolNames[op];
+        const found = candidates.find((n) => caller.toolNames.includes(n));
+        if (found)
+            return found;
+        const advertised = caller.toolNames.slice(0, 12).join(", ");
+        throw new Error(`No Figma MCP tool for "${op}": dialect "${dialect.name}" expects one of ` +
+            `[${candidates.join(", ")}], but the server advertises [${advertised}` +
+            `${caller.toolNames.length > 12 ? ", …" : ""}]. ` +
+            `Set design.mcp.dialect in raptor.yml to match your server.`);
+    };
+    return {
+        async getVariableDefs(fileKey, nodeId) {
+            const data = await caller.call(resolve("variables"), dialect.args.variables(fileKey, nodeId));
+            return coerceVarMap(data);
+        },
+        async getMetadata(fileKey, nodeId) {
+            return caller.call(resolve("metadata"), dialect.args.metadata(fileKey, nodeId));
+        },
+        async getLibraries(fileKey) {
+            const data = await caller.call(resolve("libraries"), dialect.args.libraries(fileKey));
+            return coerceLibraries(data);
+        },
+        async captureAssets(fileKey, nodeId, assetOpts = {}) {
+            const data = await caller.call(resolve("downloadAssets"), dialect.args.downloadAssets({
+                fileKey,
+                nodeId,
+                ...(assetOpts.format ? { format: assetOpts.format } : {}),
+                ...(assetOpts.scale ? { scale: assetOpts.scale } : {}),
+            }));
+            return coerceDownloadAssets(data, { format: assetOpts.format, nodeId });
+        },
+        async captureScreens(fileKey, nodeId) {
+            const data = await caller.call(resolve("metadata"), dialect.args.metadata(fileKey, nodeId));
+            const screens = normalizeMetadataToScreens(data, fileKey, nodeId);
+            if (screens.length || nodeId)
+                return screens;
+            const out = [];
+            const seen = new Set();
+            for (const pageId of pageIdsFromMetadata(data)) {
+                const pageData = await caller.call(resolve("metadata"), dialect.args.metadata(fileKey, pageId));
+                for (const s of normalizeMetadataToScreens(pageData, fileKey)) {
+                    const key = s.nodeId || slugify(s.name);
+                    if (!key || seen.has(key))
+                        continue;
+                    seen.add(key);
+                    out.push(s);
+                }
+            }
+            return out;
+        },
+        close: () => caller.close(),
+    };
+}
+export async function connectFigmaMcpStdio(cfg) {
+    const caller = await connectStdioMcp(cfg, { label: "Figma MCP" });
+    return makeFigmaMcpClient(caller, cfg.dialect ? { dialect: resolveFigmaDialect(cfg.dialect) } : {});
+}
+export async function connectFigmaMcp(opts = {}) {
+    const callback = await startCallbackServer({ productName: "Figma" });
+    let authUrl;
+    const provider = new FigmaOAuthProvider({
+        redirectUrl: callback.redirectUrl,
+        onAuthorizationUrl: (url) => {
+            authUrl = url;
+            if (opts.onAuthorizationUrl)
+                return opts.onAuthorizationUrl(url);
+            openBrowser(url.toString());
+        },
+    });
+    const caller = await connectOAuthMcp({
+        provider,
+        serverUrl: new URL(opts.serverUrl ?? FIGMA_MCP_URL),
+        callback,
+        onWaiting: () => {
+            if (authUrl)
+                opts.onWaiting?.(authUrl);
+        },
+    });
+    return makeFigmaMcpClient(caller);
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function coerceVarMap(data) {
+    const src = isRecord(data) && isRecord(data["variables"]) ? data["variables"] : data;
+    if (!isRecord(src))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(src)) {
+        if (v == null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[k] = String(v);
+        }
+        else if (isRecord(v) && (typeof v["value"] === "string" || typeof v["value"] === "number")) {
+            out[k] = String(v["value"]);
+        }
+    }
+    return out;
+}
+const URL_KEYS = ["url", "downloadUrl", "download_url", "src", "imageUrl", "image_url"];
+const NAME_KEYS = ["name", "fileName", "filename"];
+const NODE_KEYS = ["nodeId", "node_id"];
+function collectUrlItems(data, depth = 0, out = []) {
+    if (depth > 6 || data == null)
+        return out;
+    if (Array.isArray(data)) {
+        for (const el of data)
+            collectUrlItems(el, depth + 1, out);
+        return out;
+    }
+    if (typeof data !== "object")
+        return out;
+    const rec = data;
+    const urlKey = URL_KEYS.find((k) => typeof rec[k] === "string" && rec[k].startsWith("http"));
+    if (urlKey) {
+        const item = { url: rec[urlKey] };
+        if (typeof rec["format"] === "string")
+            item.format = rec["format"];
+        const nameKey = NAME_KEYS.find((k) => typeof rec[k] === "string");
+        if (nameKey)
+            item.name = rec[nameKey];
+        const nodeKey = NODE_KEYS.find((k) => typeof rec[k] === "string");
+        if (nodeKey)
+            item.nodeId = rec[nodeKey];
+        out.push(item);
+        return out;
+    }
+    for (const v of Object.values(rec)) {
+        if (v && typeof v === "object")
+            collectUrlItems(v, depth + 1, out);
+    }
+    return out;
+}
+export function coerceDownloadAssets(data, opts = {}) {
+    const items = collectUrlItems(data);
+    const out = [];
+    const seenUrls = new Set();
+    const seenPaths = new Set();
+    let i = 0;
+    for (const it of items) {
+        if (seenUrls.has(it.url))
+            continue;
+        seenUrls.add(it.url);
+        const fmt = (it.format ?? opts.format ?? extFromUrl(it.url) ?? "png").toLowerCase();
+        const type = classifyAssetType(fmt);
+        const ext = extFromUrl(it.url) ?? extForFormat(fmt);
+        const rawName = it.name && it.name.trim() ? it.name.trim() : undefined;
+        const nameSlug = rawName ? slugify(rawName) : "";
+        const nodeSlug = it.nodeId ? slugify(it.nodeId) : "";
+        let key = [nameSlug, nodeSlug].filter(Boolean).join("-") || `asset-${i}`;
+        let path = `${assetDirFor(type)}/${key}.${ext}`;
+        while (seenPaths.has(path)) {
+            key = `${key}-${i}`;
+            path = `${assetDirFor(type)}/${key}.${ext}`;
+        }
+        seenPaths.add(path);
+        i++;
+        const attrNode = it.nodeId ?? opts.nodeId;
+        out.push({
+            name: rawName ?? key,
+            type,
+            path,
+            url: it.url,
+            ...(attrNode ? { figma_node_id: attrNode } : {}),
+        });
+    }
+    return out;
+}
+export function coerceLibraries(data) {
+    const arr = Array.isArray(data)
+        ? data
+        : isRecord(data) && Array.isArray(data["libraries"])
+            ? data["libraries"]
+            : isRecord(data) && Array.isArray(data["values"])
+                ? data["values"]
+                : [];
+    const out = [];
+    for (const item of arr) {
+        if (typeof item === "string" && item.trim())
+            out.push(item.trim());
+        else if (isRecord(item)) {
+            const name = item["name"] ?? item["libraryName"] ?? item["key"];
+            if (typeof name === "string" && name.trim())
+                out.push(name.trim());
+        }
+    }
+    return [...new Set(out)];
+}