@sxl-studio/bridge 1.7.2 → 1.7.3

package/dist/figma-rest-diagnostics.js

@@ -0,0 +1,314 @@
+import { figmaRestGet, fileKeyFromArgs, FigmaRestError, } from "./figma-rest.js";
+export const FIGMA_REST_DIAGNOSTIC_CHECK_IDS = [
+    "whoami",
+    "fileMetadata",
+    "fileNodes",
+    "fileImages",
+    "fileImageFills",
+    "fileComponents",
+    "fileComponentSets",
+    "fileStyles",
+    "teamComponents",
+    "teamComponentSets",
+    "teamStyles",
+    "variablesLocal",
+    "variablesPublished",
+];
+const DEFAULT_API_BASE_URL = "https://api.figma.com";
+const DEFAULT_TOKEN_ENVS = ["FIGMA_TOKEN", "FIGMA_ACCESS_TOKEN", "FIGMA_REST_TOKEN"];
+const FIGMA_REST_DIAGNOSTIC_SOURCES = [
+    "https://developers.figma.com/docs/rest-api/scopes/",
+    "https://developers.figma.com/docs/rest-api/file-endpoints/",
+    "https://developers.figma.com/docs/rest-api/component-endpoints/",
+    "https://developers.figma.com/docs/rest-api/variables-endpoints/",
+    "https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/",
+];
+const CHECKS = [
+    {
+        id: "whoami",
+        endpoint: () => "/v1/me",
+        requiredScopes: ["current_user:read"],
+        requirements: ["Valid Figma REST token."],
+        skipMessage: "No extra input required.",
+    },
+    {
+        id: "fileMetadata",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/meta` : null,
+        requiredScopes: ["file_metadata:read"],
+        requirements: ["View access to the file."],
+        skipMessage: "Provide fileKey or url to check file metadata access.",
+    },
+    {
+        id: "fileNodes",
+        endpoint: ({ fileKey, nodeIds }) => fileKey && nodeIds.length > 0 ? `/v1/files/${fileKey}/nodes` : null,
+        query: ({ nodeIds }) => ({ ids: nodeIds.join(","), depth: 1 }),
+        requiredScopes: ["file_content:read"],
+        requirements: ["View access to the file.", "At least one node id."],
+        skipMessage: "Provide fileKey/url and nodeIds to check node access.",
+    },
+    {
+        id: "fileImages",
+        endpoint: ({ fileKey, nodeIds }) => fileKey && nodeIds.length > 0 ? `/v1/images/${fileKey}` : null,
+        query: ({ nodeIds }) => ({ ids: nodeIds.join(","), format: "png" }),
+        requiredScopes: ["file_content:read"],
+        requirements: ["View access to the file.", "At least one renderable node id."],
+        skipMessage: "Provide fileKey/url and nodeIds to check image rendering.",
+    },
+    {
+        id: "fileImageFills",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/images` : null,
+        requiredScopes: ["file_content:read"],
+        requirements: ["View access to the file."],
+        skipMessage: "Provide fileKey or url to check image fill access.",
+    },
+    {
+        id: "fileComponents",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/components` : null,
+        requiredScopes: ["library_content:read"],
+        requirements: ["View access to a published library file."],
+        skipMessage: "Provide fileKey or url to check file library components.",
+    },
+    {
+        id: "fileComponentSets",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/component_sets` : null,
+        requiredScopes: ["library_content:read"],
+        requirements: ["View access to a published library file."],
+        skipMessage: "Provide fileKey or url to check file library component sets.",
+    },
+    {
+        id: "fileStyles",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/styles` : null,
+        requiredScopes: ["library_content:read"],
+        requirements: ["View access to a published library file."],
+        skipMessage: "Provide fileKey or url to check file library styles.",
+    },
+    {
+        id: "teamComponents",
+        endpoint: ({ teamId }) => teamId ? `/v1/teams/${teamId}/components` : null,
+        query: () => ({ page_size: 1 }),
+        requiredScopes: ["team_library_content:read"],
+        requirements: ["Access to the team library."],
+        skipMessage: "Provide teamId to check team library components.",
+    },
+    {
+        id: "teamComponentSets",
+        endpoint: ({ teamId }) => teamId ? `/v1/teams/${teamId}/component_sets` : null,
+        query: () => ({ page_size: 1 }),
+        requiredScopes: ["team_library_content:read"],
+        requirements: ["Access to the team library."],
+        skipMessage: "Provide teamId to check team library component sets.",
+    },
+    {
+        id: "teamStyles",
+        endpoint: ({ teamId }) => teamId ? `/v1/teams/${teamId}/styles` : null,
+        query: () => ({ page_size: 1 }),
+        requiredScopes: ["team_library_content:read"],
+        requirements: ["Access to the team library."],
+        skipMessage: "Provide teamId to check team library styles.",
+    },
+    {
+        id: "variablesLocal",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/variables/local` : null,
+        requiredScopes: ["file_variables:read"],
+        requirements: ["Enterprise organization access.", "View access to the design file."],
+        skipMessage: "Provide fileKey or url to check local variables REST access.",
+    },
+    {
+        id: "variablesPublished",
+        endpoint: ({ fileKey }) => fileKey ? `/v1/files/${fileKey}/variables/published` : null,
+        requiredScopes: ["file_variables:read"],
+        requirements: ["Enterprise organization access.", "View access to the design file."],
+        skipMessage: "Provide fileKey or url to check published variables REST access.",
+    },
+];
+function normalizeAuthMode(value) {
+    if (value === "bearer" || value === "x-figma-token")
+        return value;
+    return "x-figma-token";
+}
+function normalizeApiBaseUrl(value) {
+    return (value ?? process.env["FIGMA_API_BASE_URL"] ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+}
+function resolveTokenEnvName(tokenEnv) {
+    if (tokenEnv)
+        return tokenEnv;
+    return DEFAULT_TOKEN_ENVS.find((envName) => Boolean(process.env[envName])) ?? null;
+}
+function hasConfiguredToken(options) {
+    if (options.token)
+        return true;
+    const envName = resolveTokenEnvName(options.tokenEnv);
+    return Boolean(envName && process.env[envName]);
+}
+function defaultChecks(options) {
+    const checks = ["whoami"];
+    const hasFile = Boolean(options.fileKey || options.url);
+    const hasNodes = (options.nodeIds ?? []).length > 0;
+    if (hasFile) {
+        checks.push("fileMetadata", "fileComponents", "fileComponentSets", "fileStyles", "fileImageFills", "variablesLocal", "variablesPublished");
+        if (hasNodes)
+            checks.push("fileNodes", "fileImages");
+    }
+    if (options.teamId) {
+        checks.push("teamComponents", "teamComponentSets", "teamStyles");
+    }
+    return checks;
+}
+function checkDefinition(id) {
+    const definition = CHECKS.find((item) => item.id === id);
+    if (!definition)
+        throw new Error(`Unknown Figma REST diagnostic check: ${id}`);
+    return definition;
+}
+function errorMessage(error) {
+    if (error instanceof Error && error.message.trim())
+        return error.message;
+    return String(error);
+}
+function checkStatusFromError(error) {
+    if (error instanceof FigmaRestError && (error.status === 401 || error.status === 403 || error.status === 404)) {
+        return "warn";
+    }
+    return "fail";
+}
+function isRetryable(error) {
+    return error instanceof FigmaRestError
+        ? error.status === 429 || error.status >= 500
+        : false;
+}
+function buildRecommendations(checks, tokenConfigured) {
+    const recommendations = new Set();
+    if (!tokenConfigured) {
+        recommendations.add("Set FIGMA_TOKEN, FIGMA_ACCESS_TOKEN, or FIGMA_REST_TOKEN in the Bridge process environment.");
+    }
+    for (const check of checks) {
+        if (check.status !== "warn" && check.status !== "fail")
+            continue;
+        if (check.httpStatus === 401) {
+            recommendations.add("Regenerate or reconnect the Figma REST token; the current token is missing, invalid, or expired.");
+        }
+        if (check.httpStatus === 403) {
+            recommendations.add(`Check token scopes for ${check.id}: ${check.requiredScopes.join(", ")}.`);
+            if (check.id === "variablesLocal" || check.id === "variablesPublished") {
+                recommendations.add("Variables REST API requires Enterprise org access and file_variables:read.");
+            }
+        }
+        if (check.httpStatus === 404) {
+            recommendations.add("Verify the fileKey/teamId/nodeIds and that the authenticated user has access.");
+        }
+        if (check.retryable) {
+            recommendations.add("Retry after rate-limit/backoff; this endpoint returned a retryable REST error.");
+        }
+    }
+    return Array.from(recommendations);
+}
+export async function diagnoseFigmaRest(options = {}) {
+    const tokenConfigured = hasConfiguredToken(options);
+    const tokenEnv = resolveTokenEnvName(options.tokenEnv);
+    const authMode = normalizeAuthMode(options.authMode ?? process.env["FIGMA_AUTH_MODE"]);
+    const apiBaseUrl = normalizeApiBaseUrl(options.apiBaseUrl);
+    const nodeIds = options.nodeIds ?? [];
+    const fileKey = options.fileKey || options.url ? fileKeyFromArgs(options) : null;
+    const teamId = options.teamId ?? null;
+    const requested = options.checks?.length ? options.checks : defaultChecks(options);
+    if (!tokenConfigured) {
+        const checks = requested.map((id) => {
+            const definition = checkDefinition(id);
+            return {
+                id,
+                endpoint: null,
+                status: "fail",
+                durationMs: 0,
+                message: "Figma REST token is not configured.",
+                requiredScopes: definition.requiredScopes,
+                requirements: definition.requirements,
+                retryable: false,
+            };
+        });
+        return {
+            ok: false,
+            status: "fail",
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            auth: { tokenConfigured: false, tokenEnv, authMode, apiBaseUrl },
+            inputs: { fileKey, teamId, nodeIds },
+            summary: summarizeChecks(checks),
+            checks,
+            recommendations: buildRecommendations(checks, false),
+            sources: FIGMA_REST_DIAGNOSTIC_SOURCES,
+        };
+    }
+    const context = { fileKey, teamId, nodeIds };
+    const checks = await Promise.all(requested.map(async (id) => {
+        const definition = checkDefinition(id);
+        const endpoint = definition.endpoint(context);
+        if (!endpoint) {
+            return {
+                id,
+                endpoint,
+                status: "skip",
+                durationMs: 0,
+                message: definition.skipMessage,
+                requiredScopes: definition.requiredScopes,
+                requirements: definition.requirements,
+                retryable: false,
+            };
+        }
+        const startedAt = Date.now();
+        try {
+            await figmaRestGet(endpoint, {
+                ...options,
+                authMode,
+                apiBaseUrl,
+                query: definition.query?.({ nodeIds }),
+            });
+            return {
+                id,
+                endpoint,
+                status: "pass",
+                durationMs: Date.now() - startedAt,
+                message: "Endpoint reachable with the configured Figma REST token.",
+                requiredScopes: definition.requiredScopes,
+                requirements: definition.requirements,
+                retryable: false,
+            };
+        }
+        catch (error) {
+            return {
+                id,
+                endpoint,
+                status: checkStatusFromError(error),
+                durationMs: Date.now() - startedAt,
+                httpStatus: error instanceof FigmaRestError ? error.status : undefined,
+                message: errorMessage(error),
+                requiredScopes: definition.requiredScopes,
+                requirements: definition.requirements,
+                retryable: isRetryable(error),
+            };
+        }
+    }));
+    const summary = summarizeChecks(checks);
+    const status = summary.fail > 0 ? "fail" : summary.warn > 0 || summary.skip > 0 ? "warn" : "pass";
+    return {
+        ok: status !== "fail",
+        status,
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        auth: { tokenConfigured: true, tokenEnv, authMode, apiBaseUrl },
+        inputs: { fileKey, teamId, nodeIds },
+        summary,
+        checks,
+        recommendations: buildRecommendations(checks, true),
+        sources: FIGMA_REST_DIAGNOSTIC_SOURCES,
+    };
+}
+function summarizeChecks(checks) {
+    return {
+        requested: checks.length,
+        pass: checks.filter((check) => check.status === "pass").length,
+        warn: checks.filter((check) => check.status === "warn").length,
+        fail: checks.filter((check) => check.status === "fail").length,
+        skip: checks.filter((check) => check.status === "skip").length,
+    };
+}
+//# sourceMappingURL=figma-rest-diagnostics.js.map

package/dist/figma-rest-diagnostics.js.map

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

package/dist/figma-rest.d.ts

@@ -0,0 +1,27 @@
+export type FigmaRestAuthMode = "bearer" | "x-figma-token";
+export type FigmaRestClientOptions = {
+    apiBaseUrl?: string;
+    authMode?: FigmaRestAuthMode;
+    token?: string;
+    tokenEnv?: string;
+    fetchImpl?: typeof fetch;
+};
+export type FigmaRestRequestOptions = FigmaRestClientOptions & {
+    query?: Record<string, string | number | boolean | undefined | null>;
+};
+export declare class FigmaRestError extends Error {
+    status: number;
+    endpoint: string;
+    body: unknown;
+    constructor(args: {
+        status: number;
+        endpoint: string;
+        message: string;
+        body: unknown;
+    });
+}
+export declare function figmaRestGet<T = unknown>(endpoint: string, options?: FigmaRestRequestOptions): Promise<T>;
+export declare function fileKeyFromArgs(args: {
+    fileKey?: string;
+    url?: string;
+}): string;

package/dist/figma-rest.js

@@ -0,0 +1,116 @@
+import { parseFigmaUrl } from "./tools/figma-url.js";
+export class FigmaRestError extends Error {
+    status;
+    endpoint;
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = "FigmaRestError";
+        this.status = args.status;
+        this.endpoint = args.endpoint;
+        this.body = args.body;
+    }
+}
+const DEFAULT_API_BASE_URL = "https://api.figma.com";
+const DEFAULT_TOKEN_ENV_NAMES = ["FIGMA_TOKEN", "FIGMA_ACCESS_TOKEN", "FIGMA_REST_TOKEN"];
+function readEnvToken(tokenEnv) {
+    if (tokenEnv) {
+        return process.env[tokenEnv];
+    }
+    for (const envName of DEFAULT_TOKEN_ENV_NAMES) {
+        const value = process.env[envName];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function normalizeAuthMode(value) {
+    if (value === "bearer" || value === "x-figma-token")
+        return value;
+    return "x-figma-token";
+}
+function normalizeBaseUrl(value) {
+    const raw = value ?? process.env["FIGMA_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`Invalid Figma REST API base URL: ${raw}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`Invalid Figma REST API base URL protocol: ${url.protocol}`);
+    }
+    return url.toString().replace(/\/+$/, "");
+}
+function authHeaders(token, authMode) {
+    if (authMode === "bearer") {
+        return { Authorization: `Bearer ${token}` };
+    }
+    return { "X-Figma-Token": token };
+}
+function appendQuery(url, query) {
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+}
+function messageFromBody(body, fallback) {
+    if (typeof body === "string" && body.trim())
+        return body;
+    if (body && typeof body === "object") {
+        const record = body;
+        for (const key of ["message", "err", "error"]) {
+            if (typeof record[key] === "string" && record[key])
+                return record[key];
+        }
+    }
+    return fallback;
+}
+async function parseResponseBody(response) {
+    const text = await response.text();
+    if (!text.trim())
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export async function figmaRestGet(endpoint, options = {}) {
+    const token = options.token ?? readEnvToken(options.tokenEnv);
+    if (!token) {
+        throw new Error(`Figma REST token is not configured. Set ${DEFAULT_TOKEN_ENV_NAMES.join(" or ")}.`);
+    }
+    const baseUrl = normalizeBaseUrl(options.apiBaseUrl);
+    const url = new URL(endpoint.startsWith("/") ? endpoint : `/${endpoint}`, baseUrl);
+    appendQuery(url, options.query);
+    const authMode = normalizeAuthMode(options.authMode ?? process.env["FIGMA_AUTH_MODE"]);
+    const response = await (options.fetchImpl ?? fetch)(url, {
+        method: "GET",
+        headers: {
+            Accept: "application/json",
+            ...authHeaders(token, authMode),
+        },
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw new FigmaRestError({
+            status: response.status,
+            endpoint,
+            message: messageFromBody(body, `Figma REST ${endpoint} returned HTTP ${response.status}`),
+            body,
+        });
+    }
+    return body;
+}
+export function fileKeyFromArgs(args) {
+    if (args.fileKey)
+        return args.fileKey;
+    if (!args.url)
+        throw new Error("fileKey or url is required");
+    return parseFigmaUrl(args.url).fileKey;
+}
+//# sourceMappingURL=figma-rest.js.map

package/dist/figma-rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-rest.js","sourceRoot":"","sources":["../src/figma-rest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAgBrD,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,MAAM,CAAS;IACf,QAAQ,CAAS;IACjB,IAAI,CAAU;IAEd,YAAY,IAA0E;QACpF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF;AAED,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AACrD,MAAM,uBAAuB,GAAG,CAAC,aAAa,EAAE,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;AAE1F,SAAS,YAAY,CAAC,QAAiB;IACrC,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAyB;IAClD,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,eAAe;QAAE,OAAO,KAAK,CAAC;IAClE,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAyB;IACjD,MAAM,GAAG,GAAG,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,oBAAoB,CAAC;IAC/E,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,6CAA6C,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,QAA2B;IAC7D,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,WAAW,CAAC,GAAQ,EAAE,KAAuC;IACpE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QACpE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,IAAa,EAAE,QAAgB;IACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAA+B,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;YAC9C,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC;gBAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,QAAkB;IACjD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,UAAmC,EAAE;IAErC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,2CAA2C,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;IACnF,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC,GAAG,EAAE;QACvD,MAAM,EAAE,KAAK;QACb,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;YAC1B,GAAG,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;SAChC;KACF,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,cAAc,CAAC;YACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ;YACR,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,cAAc,QAAQ,kBAAkB,QAAQ,CAAC,MAAM,EAAE,CAAC;YACzF,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAwC;IACtE,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC;IACtC,IAAI,CAAC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC7D,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;AACzC,CAAC"}

package/dist/http-api.d.ts

@@ -7,8 +7,19 @@
  * Endpoints:
  *   GET  /api/status      — server + plugin session snapshot
  *   GET  /api/session     — detailed session info
+ *   GET  /api/queue       — current / queued / immediate command snapshot
+ *   GET  /api/events?limit=N&commandId=... — command lifecycle/progress events
  *   GET  /api/tools       — authoritative catalogue of MCP tools
- *   GET  /api/log?limit=N — audit trail of recent commands (ring buffer)
+ *   GET  /api/capabilities — machine-readable capability matrix
+ *   GET  /api/contract-audit — release contract audit for Bridge surface
+ *   GET  /api/figma-mcp-parity — official Figma MCP ↔ Bridge/SXL parity map
+ *   GET  /api/figma-mcp-skills-parity — official Figma MCP skills ↔ Bridge/SXL recipes/resources map
+ *   GET  /api/figma-rest-diagnostics — Figma REST token/scope/preflight diagnostics
+ *   GET  /api/performance-profile?auditLimit=N — tool budgets, large-data/dry-run policy, recent timings
+ *   GET  /api/runtime-summary — compact runtime readiness summary for agents
+ *   GET  /api/operator-runbook — start-here workflow chooser for agents/operators
+ *   GET  /api/ultimate-readiness — requirement-by-requirement Ultimate Bridge readiness audit
+ *   GET  /api/log?limit=N&source=memory|disk — audit trail of recent commands
  *   POST /api/command     — execute a plugin command (with optional Idempotency-Key)
  *   POST /api/disconnect  — close the current plugin socket
  *   GET|POST|DELETE /api/workspace-blob — disk workspace cache (Git Local Storage; no plugin WS required)
@@ -18,5 +29,6 @@
  *   When BRIDGE_AUTH_TOKEN is set, all /api/* and /mcp requests require
  *   `Authorization: Bearer <token>`.
  */
+import { type Server } from "node:http";
 import type { BridgeWSServer } from "./ws-server.js";
-export declare function startHttpApi(bridgePort: number, wsServer: BridgeWSServer): Promise<void>;
+export declare function startHttpApi(bridgePort: number, wsServer: BridgeWSServer): Promise<Server>;