@muloka/figma-console-mcp 0.5.0 → 0.5.2

package/dist/cloudflare/core/diagnose-tool.js

@@ -1,100 +0,0 @@
-/**
- * figma_diagnose — a designer-readable health check for figma-console-mcp.
- *
- * This is the one tool to point a confused user at. It self-identifies the
- * server, reports the transport / plugin / token state in plain language,
- * and explicitly disclaims any token or OAuth error a user might be seeing
- * in chat (those typically come from a different MCP). The response is
- * structured so an LLM is likely to surface the `report` field verbatim.
- */
-import { z } from "zod";
-import { MCP_NAME, withIdentity } from "./identity.js";
-function buildReport(opts) {
-    const lines = [];
-    lines.push(`# ${MCP_NAME} diagnostic`);
-    lines.push("");
-    lines.push(`Server version: ${opts.getServerVersion()}`);
-    lines.push(`Mode: ${opts.mode === "local" ? "Local (stdio + WebSocket plugin bridge)" : "Cloud (Cloudflare Workers)"}`);
-    lines.push("");
-    const plugin = opts.getPluginState?.();
-    lines.push("## Plugin connection");
-    if (!plugin) {
-        lines.push("- No WebSocket server (cloud mode runs without a local plugin bridge unless paired).");
-    }
-    else if (plugin.connected) {
-        const portInfo = plugin.portFallbackFrom && plugin.port && plugin.port !== plugin.portFallbackFrom
-            ? `port ${plugin.port} (fallback from ${plugin.portFallbackFrom})`
-            : plugin.port
-                ? `port ${plugin.port}`
-                : "connected";
-        lines.push(`- ✅ Desktop Bridge plugin connected on ${portInfo}.`);
-        if (plugin.fileName) {
-            lines.push(`- Active file: **${plugin.fileName}**${plugin.currentPage ? ` (page: ${plugin.currentPage})` : ""}.`);
-        }
-        if (plugin.editorType && plugin.editorType !== "figma") {
-            lines.push(`- Editor type: ${plugin.editorType}.`);
-        }
-        if (plugin.pluginUpdateAvailable) {
-            const bundledVersion = opts.getBundledPluginVersion?.() ?? opts.getServerVersion();
-            lines.push(`- ⚠️ **Plugin update available**: the imported plugin${plugin.pluginVersion ? ` (v${plugin.pluginVersion})` : " (version unknown — very old)"} differs from the plugin files this server ships (v${bundledVersion}). Figma caches plugin files, so re-import it: Figma Desktop → Plugins → Development → Import plugin from manifest → select manifest.json. Until then, recently added or fixed plugin features may silently misbehave.`);
-        }
-    }
-    else {
-        lines.push(`- ⚠️ Desktop Bridge plugin not connected${plugin.port ? ` (server is listening on port ${plugin.port})` : ""}.`);
-        lines.push("- To fix: open the Figma Desktop Bridge plugin in Figma Desktop. If it was already running, close and reopen it once.");
-    }
-    lines.push("");
-    const token = opts.getTokenState?.();
-    lines.push("## REST API token");
-    if (!token) {
-        lines.push("- Token state not available in this mode.");
-    }
-    else if (token.hasToken) {
-        lines.push(`- ✅ Figma access token detected (source: ${token.source ?? "unknown"}). REST-based tools should work.`);
-    }
-    else {
-        lines.push("- ⚠️ No Figma access token detected. Plugin-based tools still work; REST-only tools (file data, version history, image rendering) will return an auth error.");
-        if (opts.mode === "local") {
-            lines.push("- To enable REST tools: set FIGMA_ACCESS_TOKEN in your MCP client config. Generate a token at https://www.figma.com/developers/api#access-tokens.");
-        }
-        else {
-            lines.push("- To enable REST tools: authenticate via your MCP client's OAuth flow or pass a Figma personal access token (figd_...) as a Bearer token.");
-        }
-    }
-    lines.push("");
-    lines.push("## If you're seeing token / OAuth errors in chat");
-    lines.push(`If you see messages like "API token has expired" or "Bearer token has expired" and the response above does NOT show a token problem, the error is most likely coming from a **different MCP server**, not from ${MCP_NAME}.`);
-    lines.push("");
-    lines.push("Common cause: Figma's native MCP (often listed as just `Figma` in your MCP client) is also installed and its OAuth session expired. Check your MCP client's server list. Errors from those servers are not produced by figma-console-mcp.");
-    lines.push("");
-    return lines.join("\n");
-}
-export function registerDiagnoseTool(server, options) {
-    server.tool("figma_diagnose", `Designer-readable health check for ${MCP_NAME}. Use this when something seems wrong — it self-identifies the server, reports plugin connection / file / token status in plain language, and disambiguates errors that may be coming from a different Figma-related MCP server. Recommended as the first step when a user reports a "token expired" or "plugin disconnected" issue.`, {
-        verbose: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Include the raw structured state alongside the human-readable report."),
-    }, async ({ verbose }) => {
-        const report = buildReport(options);
-        const details = verbose
-            ? {
-                plugin: options.getPluginState?.() ?? null,
-                token: options.getTokenState?.() ?? null,
-            }
-            : undefined;
-        const payload = withIdentity({
-            report,
-            ...(details ? { details } : {}),
-        });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify(payload),
-                },
-            ],
-        };
-    });
-}

package/dist/cloudflare/core/diff/changelog-formatter.js

@@ -1,275 +0,0 @@
-/**
- * Pure-function markdown formatter for version diff results.
- *
- * Takes a diff payload (the structured response from figma_diff_versions)
- * plus optional author/label metadata for the from/to versions, and produces
- * a release-notes-style markdown string.
- *
- * Mode-aware:
- *   summary  — header + a single line of counts
- *   standard — header + page section + per-component counts
- *   detailed — header + page section + per-component property/binding details
- *
- * Pure: no I/O, no side effects. Trivially testable.
- */
-export function formatChangelogMarkdown(input, mode = "standard") {
-    const lines = [];
-    // Header
-    const title = input.file_name ? `${input.file_name} — Change Log` : "Figma File Change Log";
-    lines.push(`# ${title}`);
-    lines.push("");
-    lines.push(`**From:** ${formatVersionRef(input.from_meta, input.from_version_id, false)}`);
-    lines.push(`**To:** ${formatVersionRef(input.to_meta, input.to_version_id, true)}`);
-    const span = computeSpanDays(input.from_meta?.created_at, input.to_meta?.created_at);
-    if (span !== null) {
-        lines.push(`**Span:** ${span} day${span === 1 ? "" : "s"}`);
-    }
-    lines.push("");
-    // Summary mode: one-line punch line
-    if (mode === "summary") {
-        lines.push(formatSummaryLine(input));
-        lines.push("");
-        appendNotes(lines, input.notes);
-        return lines.join("\n").trimEnd() + "\n";
-    }
-    // Page Structure section (always for standard/detailed)
-    appendPageStructureSection(lines, input.page_structure);
-    // Components section
-    if (input.scoped_nodes && input.scoped_nodes.length > 0) {
-        appendComponentsSection(lines, input.scoped_nodes, mode);
-    }
-    else {
-        lines.push("## Components");
-        lines.push("");
-        lines.push("_No components were scoped for this changelog. Pass `component_ids` to include per-component changes._");
-        lines.push("");
-    }
-    appendNotes(lines, input.notes);
-    return lines.join("\n").trimEnd() + "\n";
-}
-// ============================================================================
-// Section formatters
-// ============================================================================
-function appendPageStructureSection(lines, page) {
-    const total = page.summary.added + page.summary.removed + page.summary.renamed;
-    lines.push("## Page Structure");
-    lines.push("");
-    if (total === 0) {
-        lines.push("_No page-level changes._");
-        lines.push("");
-        return;
-    }
-    if (page.pages_added.length > 0) {
-        lines.push(`**Added (${page.pages_added.length}):**`);
-        for (const p of page.pages_added)
-            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
-        lines.push("");
-    }
-    if (page.pages_removed.length > 0) {
-        lines.push(`**Removed (${page.pages_removed.length}):**`);
-        for (const p of page.pages_removed)
-            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
-        lines.push("");
-    }
-    if (page.pages_renamed.length > 0) {
-        lines.push(`**Renamed (${page.pages_renamed.length}):**`);
-        for (const r of page.pages_renamed) {
-            lines.push(`- \`${r.id}\`: ${escapeMd(r.old_name)} → ${escapeMd(r.new_name)}`);
-        }
-        lines.push("");
-    }
-}
-function appendComponentsSection(lines, scoped, mode) {
-    lines.push("## Components");
-    lines.push("");
-    const withChanges = scoped.filter((n) => n.change_count > 0);
-    const unchanged = scoped.filter((n) => n.change_count === 0 && n.notes.length === 0);
-    const notFound = scoped.filter((n) => n.notes.some((note) => note.toLowerCase().includes("not found")));
-    if (withChanges.length === 0 && unchanged.length === 0 && notFound.length === 0) {
-        lines.push("_No scoped components had changes._");
-        lines.push("");
-        return;
-    }
-    for (const n of withChanges) {
-        appendComponentBlock(lines, n, mode);
-    }
-    if (unchanged.length > 0) {
-        lines.push(`**No changes:** ${unchanged.map((n) => `\`${n.node_name || n.node_id}\``).join(", ")}`);
-        lines.push("");
-    }
-    if (notFound.length > 0) {
-        lines.push(`**Not found in either version:** ${notFound.map((n) => `\`${n.node_id || "(empty)"}\``).join(", ")}`);
-        lines.push("");
-    }
-}
-function appendComponentBlock(lines, n, mode) {
-    const heading = n.node_name ? `${n.node_name}` : "(unnamed)";
-    lines.push(`### ${escapeMd(heading)} — \`${n.node_id}\``);
-    lines.push(`**${n.change_count} change${n.change_count === 1 ? "" : "s"}**`);
-    // Each subsequent sub-section adds its own single-blank-line separator so
-    // we don't end up with two consecutive blank lines when one of these
-    // sub-sections is empty. (Earlier versions unconditionally pushed a blank
-    // after the change count then again before each sub-section, producing
-    // double-blanks in the common case.)
-    const bullets = [];
-    if (n.name_changed) {
-        bullets.push(`- Renamed: \`${escapeMd(n.name_changed.from)}\` → \`${escapeMd(n.name_changed.to)}\``);
-    }
-    if (n.description_changed) {
-        const fromLen = n.description_changed.from.length;
-        const toLen = n.description_changed.to.length;
-        bullets.push(`- Description changed (${fromLen} → ${toLen} chars)`);
-    }
-    if (n.children_added.length > 0) {
-        const inline = n.children_added.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
-        bullets.push(`- Children added (${n.children_added.length}): ${inline}`);
-    }
-    if (n.children_removed.length > 0) {
-        const inline = n.children_removed.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
-        bullets.push(`- Children removed (${n.children_removed.length}): ${inline}`);
-    }
-    if (bullets.length > 0) {
-        lines.push("");
-        lines.push(...bullets);
-    }
-    if (n.component_properties && hasAnyPropChanges(n.component_properties.summary)) {
-        const s = n.component_properties.summary;
-        const parts = [];
-        if (s.added > 0)
-            parts.push(`${s.added} added`);
-        if (s.removed > 0)
-            parts.push(`${s.removed} removed`);
-        if (s.type_changed > 0)
-            parts.push(`${s.type_changed} type changed`);
-        if (s.default_changed > 0)
-            parts.push(`${s.default_changed} default changed`);
-        lines.push("");
-        lines.push(`**Component properties:** ${parts.join(", ")}`);
-        if (mode === "detailed") {
-            for (const p of n.component_properties.added) {
-                lines.push(`- ➕ \`${escapeMd(p.name)}\` (${p.type}, default: \`${stringifyValue(p.default_value)}\`)`);
-            }
-            for (const p of n.component_properties.removed) {
-                lines.push(`- ➖ \`${escapeMd(p.name)}\` (${p.type})`);
-            }
-            for (const t of n.component_properties.type_changed) {
-                lines.push(`- 🔄 \`${escapeMd(t.name)}\`: ${t.from_type} → ${t.to_type}`);
-            }
-            for (const d of n.component_properties.default_changed) {
-                lines.push(`- ⚙️ \`${escapeMd(d.name)}\`: \`${stringifyValue(d.from_default)}\` → \`${stringifyValue(d.to_default)}\``);
-            }
-        }
-    }
-    if (n.binding_changes.length > 0) {
-        lines.push("");
-        lines.push(`**Variable bindings (${n.binding_changes.length}):**`);
-        if (mode === "detailed") {
-            for (const b of n.binding_changes) {
-                const arrow = b.change_kind === "added"
-                    ? `→ \`${b.to_variable_id}\``
-                    : b.change_kind === "removed"
-                        ? `(removed, was \`${b.from_variable_id}\`)`
-                        : `\`${b.from_variable_id}\` → \`${b.to_variable_id}\``;
-                lines.push(`- ${escapeMd(b.node_name || b.node_id)} — \`${b.property}\` ${arrow}`);
-            }
-        }
-        else {
-            // standard mode: group by change_kind, give counts
-            const counts = { added: 0, removed: 0, rebound: 0 };
-            for (const b of n.binding_changes)
-                counts[b.change_kind]++;
-            const parts = [];
-            if (counts.added > 0)
-                parts.push(`${counts.added} added`);
-            if (counts.removed > 0)
-                parts.push(`${counts.removed} removed`);
-            if (counts.rebound > 0)
-                parts.push(`${counts.rebound} rebound`);
-            lines.push(`_${parts.join(", ")}._`);
-        }
-    }
-    lines.push("");
-}
-function appendNotes(lines, notes) {
-    if (!notes || notes.length === 0)
-        return;
-    lines.push("## Notes");
-    lines.push("");
-    for (const n of notes)
-        lines.push(`- ${n}`);
-    lines.push("");
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-function formatVersionRef(meta, versionId, isTo) {
-    if (meta?.is_head || versionId === "current") {
-        const date = meta?.created_at ? formatDate(meta.created_at) : "current state";
-        const user = meta?.user_handle ? ` by ${meta.user_handle}` : "";
-        return `Current state (last modified ${date}${user})`;
-    }
-    if (!meta) {
-        return `\`${versionId}\` _(metadata not available)_`;
-    }
-    const label = meta.label && meta.label.trim() !== "" ? `"${meta.label}"` : "_(unlabeled)_";
-    const date = meta.created_at ? formatDate(meta.created_at) : "";
-    const user = meta.user_handle ? `by ${meta.user_handle}` : "";
-    const parts = [label, date, user].filter(Boolean).join(" — ");
-    return `${parts} \`${versionId}\``;
-}
-function formatSummaryLine(input) {
-    const p = input.page_structure.summary;
-    const componentCount = input.scoped_nodes?.filter((n) => n.change_count > 0).length ?? 0;
-    const totalComponentChanges = input.scoped_nodes?.reduce((acc, n) => acc + n.change_count, 0) ?? 0;
-    const parts = [];
-    if (p.added > 0)
-        parts.push(`${p.added} page${p.added === 1 ? "" : "s"} added`);
-    if (p.removed > 0)
-        parts.push(`${p.removed} page${p.removed === 1 ? "" : "s"} removed`);
-    if (p.renamed > 0)
-        parts.push(`${p.renamed} page${p.renamed === 1 ? "" : "s"} renamed`);
-    if (componentCount > 0) {
-        parts.push(`${componentCount} component${componentCount === 1 ? "" : "s"} with ${totalComponentChanges} change${totalComponentChanges === 1 ? "" : "s"}`);
-    }
-    if (parts.length === 0)
-        return "_No structural changes detected._";
-    return parts.join("; ") + ".";
-}
-function computeSpanDays(fromIso, toIso) {
-    if (!fromIso || !toIso)
-        return null;
-    const from = new Date(fromIso).getTime();
-    const to = new Date(toIso).getTime();
-    if (isNaN(from) || isNaN(to))
-        return null;
-    return Math.max(0, Math.round((to - from) / (1000 * 60 * 60 * 24)));
-}
-function formatDate(iso) {
-    // ISO 8601 is fine as-is for release notes; trim time if it's midnight UTC for cleaner output
-    const d = new Date(iso);
-    if (isNaN(d.getTime()))
-        return iso;
-    return d.toISOString().slice(0, 10);
-}
-function escapeMd(s) {
-    // Escape characters that would break markdown. Keep light — release notes
-    // should be readable, not over-escaped.
-    return s.replace(/([\\`*_{}\[\]<>])/g, "\\$1");
-}
-function stringifyValue(v) {
-    if (v === undefined)
-        return "?"; // standard mode strips defaults; render placeholder
-    if (v === null)
-        return "null";
-    if (typeof v === "string")
-        return v;
-    try {
-        return JSON.stringify(v);
-    }
-    catch {
-        return String(v);
-    }
-}
-function hasAnyPropChanges(s) {
-    return s.added > 0 || s.removed > 0 || s.type_changed > 0 || s.default_changed > 0;
-}