@atezer/figma-mcp-bridge 1.9.3 → 1.9.5

package/dist/local-plugin-only.js

@@ -19,6 +19,10 @@ import { PluginBridgeConnector } from "./core/plugin-bridge-connector.js";
 import { parseFigmaUrl } from "./core/figma-url.js";
 import { truncateRestResponse, truncatePluginResponse } from "./core/response-guard.js";
 import { analyzeCodeForWarnings } from "./core/code-warnings.js";
+import { discoveryCounter } from "./core/discovery-counter.js";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { resolveDevice, DEVICE_PRESETS } from "./core/device-presets.js";
 import { closeAuditLog } from "./core/audit-log.js";
 import { FMCP_VERSION } from "./core/version.js";
@@ -34,6 +38,103 @@ const logger = createChildLogger({ component: "plugin-only-mcp" });
  */
 const LEGACY_DEFAULTS = process.env.FMCP_LEGACY_DEFAULTS === "1";
 /** Resolve fileKey from figmaUrl (parse) or explicit fileKey. Returns undefined if neither yields a key. */
+/**
+ * v1.9.5: Screenshot dosya kayıt konumu.
+ * ~/.fmcp/screenshots/ altında timestamp-nodeId.ext formatı.
+ */
+const SCREENSHOT_DIR = join(homedir(), ".fmcp", "screenshots");
+function ensureScreenshotDir() {
+    try {
+        mkdirSync(SCREENSHOT_DIR, { recursive: true });
+    }
+    catch { /* ignore EEXIST */ }
+    return SCREENSHOT_DIR;
+}
+/**
+ * v1.9.5: Base64 image payload'u disk'e yaz, filePath döndür.
+ * Base64 decode edilir, dosyaya binary olarak yazılır.
+ */
+function saveBase64ToFile(base64, format, nodeIdHint) {
+    ensureScreenshotDir();
+    const ts = Date.now();
+    const safeNodeId = (nodeIdHint ?? "node").replace(/[^a-zA-Z0-9_-]/g, "_");
+    const ext = format.toLowerCase() === "png" ? "png" : "jpg";
+    const fileName = `${ts}-${safeNodeId}.${ext}`;
+    const filePath = join(SCREENSHOT_DIR, fileName);
+    const buffer = Buffer.from(base64, "base64");
+    writeFileSync(filePath, buffer);
+    return { filePath, fileSize: buffer.length };
+}
+/**
+ * v1.9.5: Screenshot result'ı returnMode'a göre post-process.
+ * - file: base64'u disk'e yaz, image.base64 yerine filePath döndür
+ * - regions: regions[].image.base64'u tek tek disk'e yaz, regions[].filePath döndür
+ * - summary: plugin zaten metadata döndürdü, dokunma
+ * - base64: eski davranış, dokunma (ama _warning ekle)
+ */
+async function postProcessScreenshotResult(result, returnMode, format, nodeId) {
+    if (!result || typeof result !== "object" || !result.success)
+        return result;
+    if (returnMode === "file") {
+        // Plugin single-image response: { success, image: { base64, format, width, height } }
+        if (result.image && typeof result.image === "object" && typeof result.image.base64 === "string") {
+            try {
+                const { filePath, fileSize } = saveBase64ToFile(result.image.base64, format, nodeId);
+                const { base64, ...imageMetaRest } = result.image;
+                return {
+                    success: true,
+                    filePath,
+                    fileSize,
+                    dimensions: { width: result.image.width, height: result.image.height },
+                    format: result.image.format ?? format,
+                    nodeId: nodeId ?? null,
+                    imageMeta: imageMetaRest,
+                    hint: "v1.9.5 file mode: Screenshot diske yazildi. Claude Desktop 'open <filePath>' ile acabilir. Base64 context'te YOK (~30K token tasarrufu). Onceki davranis icin returnMode: 'base64'.",
+                };
+            }
+            catch (err) {
+                return { ...result, _warning: `File save failed: ${err instanceof Error ? err.message : String(err)}. Falling back to base64 mode.` };
+            }
+        }
+    }
+    if (returnMode === "regions" && Array.isArray(result.regions)) {
+        const processedRegions = result.regions.map((region, idx) => {
+            if (region.image && typeof region.image.base64 === "string") {
+                try {
+                    const regionNodeId = region.nodeId ?? `${nodeId}-region-${idx}`;
+                    const { filePath, fileSize } = saveBase64ToFile(region.image.base64, format, regionNodeId);
+                    const { base64, ...imageMetaRest } = region.image;
+                    return {
+                        name: region.name,
+                        nodeId: region.nodeId,
+                        filePath,
+                        fileSize,
+                        dimensions: { width: region.image.width, height: region.image.height },
+                        imageMeta: imageMetaRest,
+                    };
+                }
+                catch (err) {
+                    return { ...region, _warning: `File save failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            }
+            return region;
+        });
+        return {
+            ...result,
+            regions: processedRegions,
+            hint: "v1.9.5 regions mode: Her region ayri dosyada. Ilgili olanlari 'open <filePath>' ile ac. Tumune bakmana gerek yok. Base64 context'te YOK.",
+        };
+    }
+    if (returnMode === "base64") {
+        // Legacy — add warning
+        return {
+            ...result,
+            _warning: "BASE64_MODE: Context'e ~30K token eklendi. Bir sonraki call'da 'file' veya 'regions' tercih et.",
+        };
+    }
+    // summary mode — plugin already returned metadata-only, no post-processing needed
+    return result;
+}
 function resolveFileKey(figmaUrl, explicitFileKey) {
     if (explicitFileKey && explicitFileKey.trim())
         return explicitFileKey.trim();
@@ -406,23 +507,37 @@ export async function main() {
         }
         const clampedTimeout = Math.max(3000, Math.min(timeout ?? 15000, 30000));
         invalidateCache();
+        // v1.9.5: Discovery budget tracking — code pattern analysis (read-only vs mutation)
+        const budget = discoveryCounter.track("figma_execute", code);
         // v1.8.1: Structured warnings with SEVERE vs ADVISORY severity
         const codeWarnings = analyzeCodeForWarnings(code);
         const severeWarnings = codeWarnings.filter((w) => w.severity === "SEVERE");
         const advisoryWarnings = codeWarnings.filter((w) => w.severity === "ADVISORY");
-        // SEVERE warnings go to a prominent field that Claude cannot ignore
+        // SEVERE warnings go to a prominent field that Claude cannot ignore.
+        // v1.9.4: action text elevated to BLOCKING — Claude must retry, cannot proceed.
         const dsViolations = severeWarnings.length > 0
             ? {
+                _DESIGN_SYSTEM_VIOLATIONS_BLOCKING: true, // v1.9.4: top-level flag Claude Desktop cannot scroll past
                 _designSystemViolations: {
                     count: severeWarnings.length,
-                    message: "⚠️ DESIGN SYSTEM DISIPLIN IHLALI TESPIT EDILDI — kodu duzelt ve tekrar calistir. Bu ekran kabul edilmez.",
+                    severity: "BLOCKING",
+                    message: "❌ DESIGN SYSTEM DISIPLIN IHLALI — BLOCKING. Bu kod KABUL EDILMEZ. Execute sonucu gecersizdir.",
                     violations: severeWarnings.map((w) => ({ category: w.category, message: w.message })),
-                    action: "Her ihlal icin uygun DS token binding veya component instance kullan. Detay: figma-canvas-ops SKILL Kural 10.",
+                    action: "❌ BLOCKING: Bu kodu simdi duzelt ve tekrar calistir. Skip edemezsin. Her SOLID fill icin setBoundVariableForPaint zorunlu; her padding/itemSpacing/cornerRadius icin setBoundVariable zorunlu; her TEXT icin setTextStyleIdAsync zorunlu. Detay: figma-canvas-ops SKILL Kural 10, fmcp-screen-recipes SKILL Adim 9.",
+                    retry_required: true,
                 },
             }
             : {};
-        const warningsField = advisoryWarnings.length > 0
-            ? { _warnings: advisoryWarnings.map((w) => w.message) }
+        // v1.9.5: Discovery budget warnings merge with advisory warnings
+        const combinedWarnings = [
+            ...advisoryWarnings.map((w) => w.message),
+            ...(budget.warnings ?? []),
+        ];
+        const warningsField = combinedWarnings.length > 0
+            ? { _warnings: combinedWarnings }
+            : {};
+        const budgetBlockingField = budget._DISCOVERY_BUDGET_EXCEEDED_BLOCKING
+            ? { _DISCOVERY_BUDGET_EXCEEDED_BLOCKING: true }
             : {};
         const startTime = Date.now();
         try {
@@ -441,6 +556,7 @@ export async function main() {
                 catch { /* safe fallback */ }
                 return {
                     content: [{ type: "text", text: JSON.stringify({
+                                ...budgetBlockingField, // v1.9.5: discovery BLOCKING flag at top
                                 ...dsViolations, // v1.8.1: SEVERE warnings FIRST, before anything else
                                 ...result,
                                 errorCategory: category,
@@ -455,13 +571,14 @@ export async function main() {
             try {
                 enriched = typeof result === "object" && result !== null
                     ? {
+                        ...budgetBlockingField, // v1.9.5: discovery BLOCKING flag at top
                         ...dsViolations, // v1.8.1: SEVERE warnings at top level
                         ...result,
                         _metrics: { durationMs, timeoutMs: clampedTimeout },
                         ...warningsField,
                     }
-                    : severeWarnings.length > 0 || advisoryWarnings.length > 0
-                        ? { ...dsViolations, result, ...warningsField }
+                    : severeWarnings.length > 0 || advisoryWarnings.length > 0 || combinedWarnings.length > 0
+                        ? { ...budgetBlockingField, ...dsViolations, result, ...warningsField }
                         : result;
             }
             catch {
@@ -561,6 +678,8 @@ export async function main() {
             "across 3 dimensions: instance coverage (library usage), token binding coverage (bound variables), " +
             "and auto-layout coverage. Use this AFTER creating a screen to verify DS compliance. " +
             "If score < minScore, Claude should delete the screen and rebuild it using DS components + token bindings. " +
+            "v1.9.4: `breakdown` now always includes `coverage` (granular fills/paddings/radius/itemSpacing/textStyle bind ratios) + `overflow` (root auto-layout overflow). " +
+            "For hardcoded samples + primitive fallback list, use figma_scan_ds_compliance instead. " +
             "Read-only — never mutates the file.",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma file URL for routing."),
@@ -575,10 +694,47 @@ export async function main() {
         const result = await conn.validateScreen({ nodeId, expectedDs, minScore });
         return toolResult(result, "figma_validate_screen");
     }));
-    // ---- figma_capture_screenshot ----
-    // v1.8.0: Default JPG@1x (~80% smaller base64 vs PNG@2x). Override via params.
+    // ---- figma_scan_ds_compliance (v1.9.4) ----
+    // Full DS compliance audit — superset of figma_validate_screen with hardcoded samples,
+    // primitive fallback list, and overflow detection. Call this as the FINAL GATE before
+    // considering a screen complete. Threshold default is 85 (stricter than validate's 80)
+    // because detailed mode flags granular binding gaps that brief mode smooths over.
+    server.registerTool("figma_scan_ds_compliance", {
+        description: "v1.9.4: FINAL GATE — Full DS compliance scan for a completed screen. " +
+            "Returns the same score + breakdown as figma_validate_screen PLUS: " +
+            "(1) `coverage` = granular bind percentages (fills/paddings/radius/itemSpacing/textStyle/textColor/strokes), " +
+            "(2) `samples.hardcodedHex` = up to 8 nodes with hardcoded SOLID colors, " +
+            "(3) `samples.hardcodedFontSize` = up to 8 text nodes with hardcoded fontSize (no textStyleId), " +
+            "(4) `samples.primitiveFrames` = up to 8 frames that should have been DS component instances, " +
+            "(5) `overflow` = root auto-layout overflow analysis (frameSize vs contentSize). " +
+            "If `passed: false`, Claude MUST fix listed violations before presenting the screen as complete. " +
+            "Threshold 85 default (stricter than validate_screen's 80) because this flags granular gaps. " +
+            "Read-only — never mutates the file.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            nodeId: z.string().describe("Node ID of the completed screen to audit"),
+            threshold: z.number().min(0).max(100).optional().default(85).describe("Pass threshold (0-100). Default 85. Below this, screen is non-compliant and must be fixed."),
+            expectedDs: z.string().optional().describe("Expected DS library name (e.g. '❖ SUI')"),
+        },
+        annotations: { readOnlyHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, threshold, expectedDs, }) => {
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const result = await conn.scanDsCompliance({ nodeId, threshold, expectedDs });
+        return toolResult(result, "figma_scan_ds_compliance");
+    }));
+    // ---- figma_capture_screenshot (v1.9.5: method selection) ----
+    // v1.8.0: Default JPG@1x (~80% smaller base64 vs PNG@2x).
+    // v1.9.5: returnMode param — Claude bağlama göre file/summary/regions/base64 seçer.
+    //         Default "file": screenshot ~/.fmcp/screenshots/ altına yazılır, filePath döner,
+    //         base64 context'e girmez (30K → 0.3K token tasarrufu).
     server.registerTool("figma_capture_screenshot", {
-        description: "Capture screenshot of a node or current view from the plugin. No REST API. Defaults to JPG@1x (q70) for context safety. Use scale/format/jpegQuality to override.",
+        description: "v1.9.5: 4 returnMode ile screenshot. Default 'file' (dosyaya yazar, base64 context'te YOK). " +
+            "'summary' screenshot çekmeden metadata özeti (planlama için), " +
+            "'regions' büyük ekranları children/slices olarak parçalar, " +
+            "'base64' eski davranış (opt-in, ~30K token maliyetli). " +
+            "Context-aware fallback: >%80 context kullanımında base64/file → summary'ye otomatik düşer. " +
+            "Karar ağacı: planlama→summary, teslimat→file, scroll'lu ekran→regions, son çare→base64.",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma or FigJam file URL for routing."),
             fileKey: z.string().optional().describe("Target a specific connected file."),
@@ -586,23 +742,51 @@ export async function main() {
             format: z.enum(["PNG", "JPG"]).optional().default(LEGACY_DEFAULTS ? "PNG" : "JPG"),
             scale: z.number().optional().default(LEGACY_DEFAULTS ? 2 : 1),
             jpegQuality: z.number().min(30).max(100).optional().default(70).describe("JPEG quality 30-100. Ignored when format=PNG."),
+            returnMode: z
+                .enum(["file", "base64", "summary", "regions"])
+                .optional()
+                .default("file")
+                .describe("v1.9.5 method: 'file' (default, disk + filePath), 'base64' (legacy, context'e dahil), " +
+                "'summary' (metadata-only, screenshotsuz), 'regions' (parçalı — children veya slices)."),
+            regionStrategy: z
+                .enum(["children", "slices"])
+                .optional()
+                .default("children")
+                .describe("returnMode='regions' için: 'children' = node'un top-level child'ları ayrı ayrı, 'slices' = dikey slice'lar."),
+            maxRegions: z.number().min(1).max(20).optional().default(8).describe("returnMode='regions' için: maks region sayısı."),
+            sliceHeight: z.number().min(200).max(2000).optional().default(600).describe("regionStrategy='slices' için slice yüksekliği (px)."),
+            requestedSlices: z.array(z.number()).optional().describe("regionStrategy='slices' için spesifik slice index'leri (örn: [0,2] → sadece 1. ve 3. slice)."),
         },
         annotations: { readOnlyHint: true },
-    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, format, scale, jpegQuality }) => {
+    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, format, scale, jpegQuality, returnMode, regionStrategy, maxRegions, sliceHeight, requestedSlices, }) => {
+        // v1.9.5: Track discovery budget
+        const budget = discoveryCounter.track("figma_capture_screenshot");
         const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
-        const result = await conn.captureScreenshot(nodeId ?? null, { format, scale, jpegQuality });
-        // v1.9.6 Fix M1 — skipGuard: true → truncatePluginResponse'u bypass et.
-        // Gerekçe: screenshot response {success, image: {base64, ...}} şeklinde.
-        // pruneNodeTree screenshot payload'una (node tree değil) uymadığı için
-        // final fallback truncateResponse({maxStringLength: 200}) devreye girip
-        // base64 string'i 200 karaktere kırpıyordu → Claude Desktop `{}` empty
-        // object görüyordu (FP-1-R-v2 Known Limitation #8 root cause).
-        // skipGuard: true ile payload olduğu gibi JSON.stringify edilir, base64
-        // intact kalır. Claude image render etmez (text content block) ama
-        // base64 string'i görür, kullanabilir, böylece empty object problemi
-        // çözülür. Image content block upgrade'i (MCP image type) Part 5
-        // sonraki adımı — safeToolHandler generic refactor'u gerektirir.
-        return toolResult(result, "figma_capture_screenshot", { skipGuard: true });
+        const result = await conn.captureScreenshot(nodeId ?? null, {
+            format,
+            scale,
+            jpegQuality,
+            returnMode,
+            regionStrategy,
+            maxRegions,
+            sliceHeight,
+            requestedSlices,
+        });
+        // v1.9.5 post-processing: base64 payload'ları file'a yaz (mode='file' veya 'regions')
+        const processed = await postProcessScreenshotResult(result, returnMode, format, nodeId);
+        // Budget warning injection
+        const budgetFields = {};
+        if (budget.warnings && budget.warnings.length > 0) {
+            budgetFields._warnings = [...(processed._warnings ?? []), ...budget.warnings];
+        }
+        if (budget._DISCOVERY_BUDGET_EXCEEDED_BLOCKING) {
+            budgetFields._DISCOVERY_BUDGET_EXCEEDED_BLOCKING = true;
+        }
+        const enriched = typeof processed === "object" && processed !== null
+            ? { ...processed, ...budgetFields }
+            : processed;
+        // skipGuard: true — base64 intact kalır (legacy mode için gerekli)
+        return toolResult(enriched, "figma_capture_screenshot", { skipGuard: true });
     }));
     // ---- figma_set_instance_properties ----
     server.registerTool("figma_set_instance_properties", {