@muloka/figma-console-mcp 0.1.0

package/dist/cloudflare/browser-manager.js

@@ -0,0 +1,157 @@
+/**
+ * Browser Manager
+ * Manages Puppeteer browser instance lifecycle for Cloudflare Browser Rendering API
+ */
+import puppeteer from '@cloudflare/puppeteer';
+import { createChildLogger } from './core/logger.js';
+const logger = createChildLogger({ component: 'browser-manager' });
+/**
+ * Browser Manager
+ * Handles browser instance creation, page management, and navigation
+ */
+export class BrowserManager {
+    constructor(env, config) {
+        this.browser = null;
+        this.page = null;
+        this.env = env;
+        this.config = config;
+    }
+    /**
+     * Launch browser instance
+     */
+    async launch() {
+        if (this.browser) {
+            logger.info('Browser already running, reusing instance');
+            return this.browser;
+        }
+        logger.info('Launching browser with Cloudflare Browser Rendering API');
+        try {
+            this.browser = await puppeteer.launch(this.env.BROWSER, {
+                keep_alive: 600000, // Keep alive for 10 minutes
+            });
+            logger.info('Browser launched successfully');
+            return this.browser;
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to launch browser');
+            throw new Error(`Browser launch failed: ${error}`);
+        }
+    }
+    /**
+     * Get or create a page instance
+     */
+    async getPage() {
+        if (!this.browser) {
+            await this.launch();
+        }
+        if (this.page && !this.page.isClosed()) {
+            return this.page;
+        }
+        logger.info('Creating new browser page');
+        this.page = await this.browser.newPage();
+        // Set viewport size
+        await this.page.setViewport({
+            width: 1920,
+            height: 1080,
+            deviceScaleFactor: 1,
+        });
+        logger.info('Browser page created');
+        return this.page;
+    }
+    /**
+     * Navigate to Figma URL
+     */
+    async navigateToFigma(figmaUrl) {
+        const page = await this.getPage();
+        // Default to Figma homepage if no URL provided
+        const url = figmaUrl || 'https://www.figma.com';
+        logger.info({ url }, 'Navigating to Figma');
+        try {
+            await page.goto(url, {
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info({ url }, 'Navigation successful');
+            return { page, action: 'navigated', url };
+        }
+        catch (error) {
+            logger.error({ error, url }, 'Navigation failed');
+            throw new Error(`Failed to navigate to ${url}: ${error}`);
+        }
+    }
+    /**
+     * Reload current page
+     */
+    async reload(hardReload = false) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page to reload');
+        }
+        logger.info({ hardReload }, 'Reloading page');
+        try {
+            await this.page.reload({
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info('Page reloaded successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Page reload failed');
+            throw new Error(`Page reload failed: ${error}`);
+        }
+    }
+    /**
+     * Execute JavaScript in page context
+     */
+    async evaluate(fn) {
+        const page = await this.getPage();
+        return page.evaluate(fn);
+    }
+    // Screenshot functionality removed - use Figma REST API's getImages() instead
+    // See: figma_take_screenshot and figma_get_component_image tools
+    /**
+     * Check if browser is running
+     */
+    isRunning() {
+        return this.browser !== null && this.browser.isConnected();
+    }
+    /**
+     * Close browser instance
+     */
+    async close() {
+        if (!this.browser) {
+            return;
+        }
+        logger.info('Closing browser');
+        try {
+            await this.browser.close();
+            this.browser = null;
+            this.page = null;
+            logger.info('Browser closed successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to close browser');
+            throw error;
+        }
+    }
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl() {
+        if (!this.page || this.page.isClosed()) {
+            return null;
+        }
+        return this.page.url();
+    }
+    /**
+     * Wait for navigation
+     */
+    async waitForNavigation(timeout = 30000) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page');
+        }
+        await this.page.waitForNavigation({
+            waitUntil: 'networkidle2',
+            timeout,
+        });
+    }
+}

package/dist/cloudflare/core/accessibility-tools.js

@@ -0,0 +1,361 @@
+/**
+ * Code-side accessibility scanning via axe-core + JSDOM.
+ *
+ * Delegates all rule logic to axe-core (Deque) — the MCP never owns
+ * a rule database. JSDOM provides a lightweight DOM for structural checks
+ * (~50 rules: ARIA, semantics, alt text, form labels, headings, landmarks).
+ *
+ * Visual rules (color contrast, focus-visible) are NOT available via JSDOM —
+ * those are handled by the design-side figma_lint_design tool.
+ */
+import { z } from "zod";
+import { logger } from "./logger.js";
+// Lazy-load axe-core and jsdom to keep them optional
+let axeCore = null;
+let JSDOM = null;
+let depsLoaded = false;
+let depsError = null;
+async function loadDeps() {
+    if (depsLoaded)
+        return;
+    try {
+        axeCore = await import("axe-core");
+        // axe-core's default export structure
+        if (axeCore.default)
+            axeCore = axeCore.default;
+        const jsdomModule = await import("jsdom");
+        JSDOM = jsdomModule.JSDOM;
+        depsLoaded = true;
+    }
+    catch (e) {
+        depsError = `axe-core or jsdom not installed. Run: npm install axe-core jsdom\n${e.message}`;
+        throw new Error(depsError);
+    }
+}
+/**
+ * Run axe-core against an HTML string using JSDOM.
+ *
+ * JSDOM limitations: no computed styles, no layout, no visual rendering.
+ * This means ~50-60 structural rules work, but visual rules
+ * (color-contrast, focus-visible, etc.) will report as "incomplete".
+ */
+async function scanHtmlWithAxe(html, options = {}) {
+    await loadDeps();
+    // Wrap HTML fragment in a full document if needed
+    const fullHtml = html.includes("<html") || html.includes("<!DOCTYPE")
+        ? html
+        : `<!DOCTYPE html><html lang="en"><head><title>Scan</title></head><body>${html}</body></html>`;
+    const dom = new JSDOM(fullHtml, {
+        runScripts: "dangerously",
+        pretendToBeVisual: true,
+        url: "http://localhost",
+    });
+    const { document, window } = dom.window;
+    // Inject axe-core into the JSDOM window
+    const axeSource = axeCore.source;
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent = axeSource;
+    document.head.appendChild(scriptEl);
+    // Configure axe run options
+    const runOptions = {};
+    if (options.tags && options.tags.length > 0) {
+        runOptions.runOnly = { type: "tag", values: options.tags };
+    }
+    // Disable rules that require visual rendering (always fail/incomplete in JSDOM)
+    if (options.disableVisualRules !== false) {
+        runOptions.rules = {
+            "color-contrast": { enabled: false },
+            "color-contrast-enhanced": { enabled: false },
+            "link-in-text-block": { enabled: false },
+        };
+    }
+    // Determine scan context
+    const context = options.context || document;
+    try {
+        const results = await window.axe.run(context, runOptions);
+        // Clean up
+        dom.window.close();
+        return results;
+    }
+    catch (err) {
+        dom.window.close();
+        throw new Error(`axe-core scan failed: ${err.message}`);
+    }
+}
+/**
+ * Extract a CodeSpec.accessibility object from HTML + axe-core results.
+ * This bridges Phase 3 (code scanning) → Phase 4 (parity comparison).
+ *
+ * Parses the HTML to extract semantic element, ARIA attributes, and states.
+ * Uses axe-core results to infer what the code supports.
+ */
+export function axeResultsToCodeSpec(html, axeResults) {
+    const spec = {};
+    // Parse HTML to extract attributes (lightweight regex-based, no DOM needed)
+    const htmlLower = html.toLowerCase();
+    // Semantic element: find the root/first meaningful element
+    const rootElementMatch = html.match(/<(button|a|input|select|textarea|details|dialog|nav|main|form|label|fieldset)\b/i);
+    if (rootElementMatch) {
+        spec.semanticElement = rootElementMatch[1].toLowerCase();
+    }
+    else {
+        const firstElementMatch = html.match(/<(\w+)[\s>]/);
+        if (firstElementMatch && !["div", "span", "html", "head", "body", "script", "style", "!doctype"].includes(firstElementMatch[1].toLowerCase())) {
+            spec.semanticElement = firstElementMatch[1].toLowerCase();
+        }
+        else {
+            spec.semanticElement = "div";
+        }
+    }
+    // ARIA role
+    const roleMatch = html.match(/role=["']([^"']+)["']/i);
+    if (roleMatch) {
+        spec.role = roleMatch[1];
+    }
+    // ARIA label
+    const ariaLabelMatch = html.match(/aria-label=["']([^"']+)["']/i);
+    if (ariaLabelMatch) {
+        spec.ariaLabel = ariaLabelMatch[1];
+    }
+    // Focus visible: check for :focus-visible or :focus in inline styles/class names,
+    // or infer from element type (native interactive elements have default focus)
+    const nativeFocusElements = ["button", "a", "input", "select", "textarea"];
+    const hasFocusCSS = /focus-visible|:focus\b|outline.*focus|ring.*focus|focus.*ring/i.test(html);
+    spec.focusVisible = hasFocusCSS || nativeFocusElements.includes(spec.semanticElement || "");
+    // Disabled support: only assert true when we find positive evidence.
+    // Absence of disabled/aria-disabled in a single HTML snapshot does NOT mean
+    // the component lacks disabled support — it may be in a non-disabled state.
+    if (/\bdisabled\b|aria-disabled/i.test(htmlLower)) {
+        spec.supportsDisabled = true;
+    }
+    // (leave undefined when not found — absence ≠ lack of support)
+    // Error support: same principle — only assert true on positive evidence.
+    // A default-state HTML snippet won't have aria-invalid; that doesn't mean
+    // the component can't enter an error state.
+    if (/aria-invalid|aria-errormessage|aria-describedby.*error/i.test(htmlLower)) {
+        spec.supportsError = true;
+    }
+    // (leave undefined when not found — scan a different state to confirm)
+    // Required: check for required or aria-required attributes
+    if (/aria-required=["']true["']|required(?!=)/i.test(html)) {
+        spec.ariaRequired = true;
+    }
+    else if (/aria-required=["']false["']/i.test(html)) {
+        spec.ariaRequired = false;
+    }
+    // Keyboard interactions: infer from element type
+    const keyboardInteractions = [];
+    if (spec.semanticElement === "button" || spec.role === "button") {
+        keyboardInteractions.push("Enter", "Space");
+    }
+    else if (spec.semanticElement === "a" || spec.role === "link") {
+        keyboardInteractions.push("Enter");
+    }
+    else if (spec.semanticElement === "input" || spec.semanticElement === "textarea") {
+        keyboardInteractions.push("Tab (focus)", "Type (input)");
+    }
+    else if (spec.semanticElement === "select" || spec.role === "listbox") {
+        keyboardInteractions.push("Arrow keys", "Enter", "Space");
+    }
+    else if (spec.role === "checkbox" || spec.role === "switch") {
+        keyboardInteractions.push("Space");
+    }
+    else if (spec.role === "tab") {
+        keyboardInteractions.push("Arrow keys");
+    }
+    // Check HTML for custom keyboard handlers
+    if (/onkeydown|onkeyup|onkeypress|@keydown|@keyup|v-on:keydown/i.test(html)) {
+        if (!keyboardInteractions.includes("Custom key handler")) {
+            keyboardInteractions.push("Custom key handler");
+        }
+    }
+    if (keyboardInteractions.length > 0) {
+        spec.keyboardInteractions = keyboardInteractions;
+    }
+    // Use axe-core results to refine: if certain violations exist, it tells us what's missing
+    if (axeResults?.violations) {
+        for (const v of axeResults.violations) {
+            // If button-name violation exists, the button has no accessible name
+            if (v.id === "button-name") {
+                spec.ariaLabel = undefined; // Explicitly missing
+            }
+            // If label violation exists, input lacks a label
+            if (v.id === "label") {
+                spec.ariaLabel = undefined;
+            }
+        }
+    }
+    return spec;
+}
+/**
+ * Format axe-core results into our standard lint-like output structure.
+ */
+function formatAxeResults(axeResults) {
+    const categories = [];
+    const severityMap = {
+        critical: "critical",
+        serious: "critical",
+        moderate: "warning",
+        minor: "info",
+    };
+    // Group violations
+    for (const violation of axeResults.violations || []) {
+        const severity = severityMap[violation.impact] || "warning";
+        const nodes = violation.nodes.map((node) => ({
+            html: node.html?.substring(0, 200),
+            target: node.target,
+            failureSummary: node.failureSummary?.substring(0, 300),
+        }));
+        categories.push({
+            rule: violation.id,
+            severity,
+            count: violation.nodes.length,
+            description: violation.help,
+            wcagTags: violation.tags.filter((t) => t.startsWith("wcag") || t.startsWith("best-practice")),
+            helpUrl: violation.helpUrl,
+            nodes: nodes.slice(0, 10), // Cap at 10 per rule
+        });
+    }
+    // Sort: critical first, then by count
+    categories.sort((a, b) => {
+        const sevOrder = { critical: 0, warning: 1, info: 2 };
+        if (sevOrder[a.severity] !== sevOrder[b.severity]) {
+            return sevOrder[a.severity] - sevOrder[b.severity];
+        }
+        return b.count - a.count;
+    });
+    // Summary
+    const summary = { critical: 0, warning: 0, info: 0, total: 0 };
+    for (const cat of categories) {
+        summary[cat.severity] += cat.count;
+        summary.total += cat.count;
+    }
+    return {
+        engine: "axe-core",
+        version: axeResults.testEngine?.version || "unknown",
+        mode: "jsdom-structural",
+        note: "JSDOM mode: structural/semantic checks only. Visual rules (color contrast, focus visibility) are disabled — use figma_lint_design for visual accessibility checks.",
+        categories,
+        summary,
+        passes: axeResults.passes?.length || 0,
+        incomplete: axeResults.incomplete?.length || 0,
+        inapplicable: axeResults.inapplicable?.length || 0,
+    };
+}
+/**
+ * Heuristic WCAG 1.4.12 (Text Spacing) / 1.4.4 (Resize Text) signal for CODE.
+ *
+ * This is where text-spacing override support actually belongs: 1.4.12 is about whether
+ * content survives a USER overriding line/letter/word/paragraph spacing — it cannot be
+ * proven from a design's spacing value, only from the code. axe-core can't evaluate it
+ * (it needs layout), but the common, checkable risk indicator is fixed-px typography:
+ * line-height/font-size locked in px don't respond to spacing overrides or text-only zoom,
+ * whereas unitless line-height and rem/em sizing do. Surfaces fixed-px usage as an advisory
+ * (info) finding so teams verify reflow — without red-flagging sub-1.5 line heights, which
+ * are not failures.
+ */
+function scanTextSpacingSupport(html) {
+    // Collect CSS from <style> blocks and inline style="" attributes
+    let css = "";
+    const styleBlocks = html.match(/<style[^>]*>([\s\S]*?)<\/style>/gi) || [];
+    for (const block of styleBlocks)
+        css += block.replace(/<\/?style[^>]*>/gi, "") + "\n";
+    const inlineStyles = html.match(/style=["']([^"']*)["']/gi) || [];
+    for (const s of inlineStyles)
+        css += s.replace(/^style=["']|["']$/gi, "") + ";\n";
+    if (!css.trim())
+        return null;
+    // line-height: <n>px  → won't grow when a user overrides text spacing (1.4.12 risk)
+    const pxLineHeights = css.match(/line-height\s*:\s*[\d.]+px/gi) || [];
+    // font-size: <n>px → won't scale on text-only zoom / 200% resize (1.4.4 risk)
+    const pxFontSizes = css.match(/font-size\s*:\s*[\d.]+px/gi) || [];
+    if (pxLineHeights.length === 0 && pxFontSizes.length === 0)
+        return null;
+    const samples = [
+        ...pxLineHeights.slice(0, 5).map((m) => m.trim()),
+        ...pxFontSizes.slice(0, 5).map((m) => m.trim()),
+    ];
+    return {
+        rule: "text-spacing-support",
+        severity: "info",
+        count: pxLineHeights.length + pxFontSizes.length,
+        description: `Typography uses fixed px units (${pxLineHeights.length} px line-height, ${pxFontSizes.length} px font-size). ` +
+            "This is where WCAG 1.4.12 (Text Spacing) and 1.4.4 (Resize Text) are actually verified — not on the design side. " +
+            "Prefer unitless line-height (e.g. line-height: 1.4) and rem/em font sizes so user spacing overrides and text-only zoom do not clip or overlap content. " +
+            "Advisory only: a sub-1.5 line height is NOT a failure — confirm content still reflows when the 1.4.12 text-spacing overrides are applied.",
+        wcagTags: ["wcag22aa", "wcag1412", "wcag144"],
+        helpUrl: "https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html",
+        samples,
+    };
+}
+export function registerAccessibilityTools(server) {
+    server.tool("figma_scan_code_accessibility", "Scan HTML code for accessibility violations using axe-core (Deque). " +
+        "Runs structural/semantic checks via JSDOM: ARIA attributes, roles, labels, alt text, " +
+        "form labels, heading order, landmarks, semantic HTML, tabindex, duplicate IDs, lang attribute, and ~50 more rules. " +
+        "Visual checks (color contrast, focus visibility) are disabled in this mode — use figma_lint_design for visual a11y on the design side. " +
+        "Also surfaces a WCAG 1.4.12 (Text Spacing) / 1.4.4 (Resize Text) advisory when typography is locked to fixed px units — the code side is where text-spacing override support is actually verified (a sub-1.5 line height in a design is not itself a failure). " +
+        "Together, these two tools provide full-spectrum accessibility coverage across design and code. " +
+        "Pass component HTML directly or use with figma_check_design_parity for design-to-code a11y comparison. " +
+        "No Figma connection required — this is a standalone code analysis tool.", {
+        html: z.string().describe("HTML string to scan. Can be a full document or a component fragment (will be wrapped in a valid document)."),
+        tags: z.array(z.string()).optional().describe("WCAG tag filter. Examples: ['wcag2a'], ['wcag2aa'], ['wcag21aa'], ['wcag22aa'], ['best-practice']. " +
+            "Defaults to all structural rules if omitted."),
+        context: z.string().optional().describe("CSS selector to scope the scan to a specific element (e.g., '#my-component', '.card'). Scans entire document if omitted."),
+        includePassingRules: z.boolean().optional().describe("If true, includes count of passing and incomplete rules in the response (default: false)."),
+        mapToCodeSpec: z.boolean().optional().describe("If true, includes a codeSpec.accessibility object auto-extracted from the HTML + scan results. " +
+            "Pass this directly into figma_check_design_parity's codeSpec.accessibility field for automated design-to-code a11y parity checking."),
+    }, async ({ html, tags, context, includePassingRules, mapToCodeSpec }) => {
+        try {
+            const axeResults = await scanHtmlWithAxe(html, {
+                tags: tags || undefined,
+                context: context || undefined,
+            });
+            const formatted = formatAxeResults(axeResults);
+            // Supplementary WCAG 1.4.12 / 1.4.4 advisory — axe can't see layout/overrides,
+            // and this (not the design side) is where text-spacing support is verifiable.
+            const textSpacing = scanTextSpacingSupport(html);
+            if (textSpacing) {
+                formatted.categories.push(textSpacing);
+                formatted.summary.info += textSpacing.count;
+                formatted.summary.total += textSpacing.count;
+            }
+            // Optionally strip pass/incomplete counts to save tokens
+            if (!includePassingRules) {
+                delete formatted.passes;
+                delete formatted.incomplete;
+                delete formatted.inapplicable;
+            }
+            // Auto-generate CodeSpec.accessibility from HTML + results
+            if (mapToCodeSpec) {
+                formatted.codeSpecAccessibility = axeResultsToCodeSpec(html, axeResults);
+                formatted.codeSpecAccessibility._usage = "Pass this object as codeSpec.accessibility in figma_check_design_parity for automated a11y parity checking.";
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(formatted, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const isDepsError = error.message?.includes("not installed");
+            logger.error({ error }, "Failed to scan code accessibility");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                            hint: isDepsError
+                                ? "Install dependencies: npm install axe-core jsdom"
+                                : "Check that the HTML is valid. For visual accessibility checks, use figma_lint_design instead.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}