@sxl-studio/bridge 1.7.2 → 1.8.0

package/dist/tools/data.js

@@ -2,55 +2,867 @@
  * MCP tools for Data / Mapping operations.
  */
 import { z } from "zod";
+import { prepareUploadAssets, uploadAssetReports, } from "../asset-upload.js";
+import { buildCodeConnectSuggestions } from "../codeconnect-suggestions.js";
+import { buildEnabledLibrarySearchResult } from "../enabled-library-search.js";
+import { callPluginCommand, callPluginWriteCommand, err, executePluginCommand, executePluginWriteCommand, ok, } from "./shared.js";
+import { destructiveConfirmationArgs, withDestructiveConfirmation } from "./destructive-confirmation.js";
+import { largeDataResponseArgs, normalizeLargeDataResult } from "./large-data.js";
+const datasetZod = z.object({ id: z.string() }).passthrough();
+const assetZod = z.object({ id: z.string() }).passthrough();
+const mappingZod = z.object({ id: z.string() }).passthrough();
+const dryRunZod = z.boolean().optional().describe("Preview the operation without modifying plugin state.");
+const applyScopeZod = z.enum(["selection", "page", "document"]);
+const databaseAssetPayloadZod = z.union([
+    assetZod,
+    z.object({
+        asset: assetZod,
+        content: z.string().optional(),
+        data: z.string().optional(),
+    }).passthrough(),
+]);
+const databasePayloadZod = z.object({
+    kind: z.string().optional(),
+    version: z.number().optional(),
+    exportedAt: z.string().optional(),
+    datasets: z.array(datasetZod).optional(),
+    assets: z.array(databaseAssetPayloadZod).optional(),
+    mappings: z.array(mappingZod).optional(),
+}).passthrough();
+const imageScaleModeZod = z.enum(["FILL", "FIT", "CROP", "TILE"]);
+const codeConnectFrameworkZod = z.enum(["react", "angular", "html", "swift", "kotlin", "vue3", "compose"]);
+const enabledLibraryAssetKindZod = z.enum(["component", "style", "variable", "variableCollection"]);
+const variableResolvedTypeZod = z.enum(["BOOLEAN", "COLOR", "FLOAT", "STRING"]);
+const codeConnectTargetZod = z.object({
+    nodeId: z.string().optional(),
+    nodeName: z.string().describe("Figma node/component name to match against local code files."),
+    nodeType: z.string().optional(),
+});
+const uploadAssetZod = z.object({
+    url: z.string().url().optional().describe("HTTP(S) image URL. Supported: PNG, JPG/JPEG, GIF, WebP."),
+    dataBase64: z.string().optional().describe("Optional base64 image body or data:image/*;base64,... URI."),
+    contentType: z.string().optional().describe("Optional MIME type override, e.g. image/png."),
+    name: z.string().optional(),
+    nodeId: z.string().optional().describe("Existing node to receive this image as fill. If omitted Bridge creates a rectangle."),
+    parentId: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    width: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    cornerRadius: z.number().min(0).optional(),
+    scaleMode: imageScaleModeZod.optional(),
+}).refine((value) => Boolean(value.url || value.dataBase64), {
+    message: "Each asset requires url or dataBase64.",
+});
+function dryRunPreview(action, id, extra = {}) {
+    return ok({
+        ok: true,
+        dryRun: true,
+        action,
+        id,
+        willCallPlugin: false,
+        ...extra,
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readArrayResult(result, key) {
+    if (!isRecord(result))
+        return [];
+    const value = result[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isRecord);
+}
+function readSingleResult(result, key) {
+    if (!isRecord(result))
+        return null;
+    const value = result[key];
+    return isRecord(value) ? value : null;
+}
+function readIdValue(item) {
+    return typeof item.id === "string" && item.id.length > 0 ? item.id : null;
+}
+function filterByIds(items, ids) {
+    if (!Array.isArray(ids) || ids.length === 0)
+        return items;
+    const wanted = new Set(ids);
+    return items.filter((item) => {
+        const id = readIdValue(item);
+        return id ? wanted.has(id) : false;
+    });
+}
+function idSet(items) {
+    return new Set(items.map(readIdValue).filter((id) => Boolean(id)));
+}
+function isExistingId(id, existing) {
+    return typeof id === "string" && existing.has(id);
+}
+function normalizeDatabaseAssetEntry(entry, warnings, index) {
+    if (!isRecord(entry)) {
+        warnings.push(`assets[${index}] ignored: entry must be an object`);
+        return null;
+    }
+    if (isRecord(entry.asset)) {
+        const id = readIdValue(entry.asset);
+        if (!id) {
+            warnings.push(`assets[${index}] ignored: asset.id is required`);
+            return null;
+        }
+        const content = typeof entry.content === "string"
+            ? entry.content
+            : typeof entry.data === "string"
+                ? entry.data
+                : undefined;
+        return { asset: entry.asset, content };
+    }
+    const id = readIdValue(entry);
+    if (!id) {
+        warnings.push(`assets[${index}] ignored: id is required`);
+        return null;
+    }
+    const content = typeof entry.data === "string" ? entry.data : undefined;
+    return { asset: entry, content };
+}
+function normalizeDatabasePayload(payload) {
+    const warnings = [];
+    if (!isRecord(payload)) {
+        return { datasets: [], assets: [], mappings: [], warnings: ["payload must be an object"] };
+    }
+    const datasets = Array.isArray(payload.datasets)
+        ? payload.datasets.filter((dataset, index) => {
+            const valid = isRecord(dataset) && Boolean(readIdValue(dataset));
+            if (!valid)
+                warnings.push(`datasets[${index}] ignored: id is required`);
+            return valid;
+        })
+        : [];
+    const assets = Array.isArray(payload.assets)
+        ? payload.assets
+            .map((asset, index) => normalizeDatabaseAssetEntry(asset, warnings, index))
+            .filter((asset) => Boolean(asset))
+        : [];
+    const mappings = Array.isArray(payload.mappings)
+        ? payload.mappings.filter((mapping, index) => {
+            const valid = isRecord(mapping) && Boolean(readIdValue(mapping));
+            if (!valid)
+                warnings.push(`mappings[${index}] ignored: id is required`);
+            return valid;
+        })
+        : [];
+    return { datasets, assets, mappings, warnings };
+}
+function databaseCounts(payload) {
+    return {
+        datasets: payload.datasets.length,
+        assets: payload.assets.length,
+        assetContents: payload.assets.filter((asset) => typeof asset.content === "string").length,
+        mappings: payload.mappings.length,
+    };
+}
+function readCountResult(result) {
+    if (!isRecord(result))
+        return null;
+    return typeof result.count === "number" && Number.isFinite(result.count) ? result.count : null;
+}
+function mappingFields(mapping) {
+    if (!mapping || !Array.isArray(mapping.fields))
+        return [];
+    return mapping.fields.filter(isRecord);
+}
+function mappingTargetLayerNames(mapping) {
+    return [...new Set(mappingFields(mapping)
+            .map((field) => field.layerName)
+            .filter((name) => typeof name === "string" && name.length > 0))];
+}
+function mappingDatasetIds(mapping) {
+    if (!mapping)
+        return [];
+    const ids = new Set();
+    if (typeof mapping.datasetId === "string" && mapping.datasetId.length > 0)
+        ids.add(mapping.datasetId);
+    for (const field of mappingFields(mapping)) {
+        if (typeof field.datasetId === "string" && field.datasetId.length > 0)
+            ids.add(field.datasetId);
+    }
+    return [...ids];
+}
+function rowCountFromDataset(dataset) {
+    if (!dataset)
+        return null;
+    if (Array.isArray(dataset.data))
+        return dataset.data.length;
+    if (dataset.data !== undefined && dataset.data !== null)
+        return 1;
+    if (typeof dataset.lines === "number" && Number.isFinite(dataset.lines))
+        return dataset.lines;
+    return null;
+}
+function resolveRequestedRowCount(datasetRows, requested) {
+    if (typeof requested === "number" && Number.isFinite(requested)) {
+        return datasetRows === null ? Math.max(0, Math.floor(requested)) : Math.min(datasetRows, Math.max(0, Math.floor(requested)));
+    }
+    return datasetRows;
+}
+function summarizeMapping(mapping) {
+    if (!mapping)
+        return null;
+    return {
+        id: typeof mapping.id === "string" ? mapping.id : null,
+        name: typeof mapping.name === "string" ? mapping.name : null,
+        fieldCount: mappingFields(mapping).length,
+        datasetIds: mappingDatasetIds(mapping),
+        targetLayerNames: mappingTargetLayerNames(mapping),
+    };
+}
+async function getMappingById(queue, mappingId) {
+    const result = await executePluginCommand(queue, "get_mapping", { mappingId });
+    return readSingleResult(result, "mapping");
+}
+function readTargetNodeIds(args) {
+    const direct = Array.isArray(args.targetNodeIds)
+        ? args.targetNodeIds.filter((id) => typeof id === "string" && id.length > 0)
+        : [];
+    const legacy = Array.isArray(args.targetNodes)
+        ? args.targetNodes
+            .map((node) => isRecord(node) ? node.id : undefined)
+            .filter((id) => typeof id === "string" && id.length > 0)
+        : [];
+    return [...new Set([...direct, ...legacy])];
+}
+async function countApplyTargetsSafely(queue, scope, targetNodeIds = []) {
+    try {
+        const result = await executePluginCommand(queue, "count_apply_targets", {
+            scope,
+            ...(targetNodeIds.length > 0 ? { targetNodeIds } : {}),
+        });
+        return { count: readCountResult(result) };
+    }
+    catch (error) {
+        return { count: null, warning: `count_apply_targets failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function datasetSummariesForMapping(queue, mapping) {
+    const warnings = [];
+    const datasets = [];
+    for (const datasetId of mappingDatasetIds(mapping)) {
+        try {
+            const dataset = readSingleResult(await executePluginCommand(queue, "get_dataset", { datasetId }), "dataset");
+            datasets.push({
+                id: datasetId,
+                exists: Boolean(dataset),
+                name: dataset && typeof dataset.name === "string" ? dataset.name : null,
+                rowCount: rowCountFromDataset(dataset),
+            });
+        }
+        catch (error) {
+            warnings.push(`Dataset ${datasetId} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+            datasets.push({ id: datasetId, exists: false, rowCount: null });
+        }
+    }
+    return { datasets, warnings };
+}
+async function readExistingDatabaseIds(queue) {
+    const [datasetsResult, assetsResult, mappingsResult] = await Promise.all([
+        executePluginCommand(queue, "list_datasets"),
+        executePluginCommand(queue, "list_assets"),
+        executePluginCommand(queue, "list_mappings"),
+    ]);
+    return {
+        datasets: idSet(readArrayResult(datasetsResult, "datasets")),
+        assets: idSet(readArrayResult(assetsResult, "assets")),
+        mappings: idSet(readArrayResult(mappingsResult, "mappings")),
+    };
+}
+function findConflicts(payload, existing) {
+    const datasets = payload.datasets.map(readIdValue).filter((id) => isExistingId(id, existing.datasets));
+    const assets = payload.assets
+        .map((entry) => readIdValue(entry.asset))
+        .filter((id) => isExistingId(id, existing.assets));
+    const mappings = payload.mappings.map(readIdValue).filter((id) => isExistingId(id, existing.mappings));
+    return {
+        datasets,
+        assets,
+        mappings,
+        total: datasets.length + assets.length + mappings.length,
+    };
+}
+async function exportDatabasePayload(queue, args) {
+    const includeDatasets = args.includeDatasets !== false;
+    const includeAssets = args.includeAssets !== false;
+    const includeMappings = args.includeMappings !== false;
+    const includeAssetContent = args.includeAssetContent === true;
+    const datasetIds = Array.isArray(args.datasetIds) ? args.datasetIds.filter((id) => typeof id === "string") : undefined;
+    const assetIds = Array.isArray(args.assetIds) ? args.assetIds.filter((id) => typeof id === "string") : undefined;
+    const mappingIds = Array.isArray(args.mappingIds) ? args.mappingIds.filter((id) => typeof id === "string") : undefined;
+    const warnings = [];
+    let datasets = [];
+    if (includeDatasets) {
+        const listResult = await executePluginCommand(queue, "list_datasets");
+        const listed = filterByIds(readArrayResult(listResult, "datasets"), datasetIds);
+        datasets = await Promise.all(listed.map(async (dataset) => {
+            const id = readIdValue(dataset);
+            if (!id)
+                return dataset;
+            try {
+                return readSingleResult(await executePluginCommand(queue, "get_dataset", { datasetId: id }), "dataset") ?? dataset;
+            }
+            catch (error) {
+                warnings.push(`Dataset ${id} could not be hydrated: ${error instanceof Error ? error.message : String(error)}`);
+                return dataset;
+            }
+        }));
+    }
+    let assets = [];
+    if (includeAssets) {
+        const listResult = await executePluginCommand(queue, "list_assets");
+        const listed = filterByIds(readArrayResult(listResult, "assets"), assetIds);
+        assets = await Promise.all(listed.map(async (asset) => {
+            const id = readIdValue(asset);
+            if (!id)
+                return { asset };
+            try {
+                const result = await executePluginCommand(queue, "get_asset", { assetId: id, includeContent: includeAssetContent });
+                const hydratedAsset = readSingleResult(result, "asset") ?? asset;
+                const content = includeAssetContent && isRecord(result) && typeof result.content === "string"
+                    ? result.content
+                    : typeof hydratedAsset.data === "string"
+                        ? hydratedAsset.data
+                        : undefined;
+                return { asset: hydratedAsset, ...(includeAssetContent && content ? { content } : {}) };
+            }
+            catch (error) {
+                warnings.push(`Asset ${id} could not be hydrated: ${error instanceof Error ? error.message : String(error)}`);
+                return { asset };
+            }
+        }));
+    }
+    let mappings = [];
+    if (includeMappings) {
+        const listResult = await executePluginCommand(queue, "list_mappings");
+        const listed = filterByIds(readArrayResult(listResult, "mappings"), mappingIds);
+        mappings = await Promise.all(listed.map(async (mapping) => {
+            const id = readIdValue(mapping);
+            if (!id)
+                return mapping;
+            try {
+                return readSingleResult(await executePluginCommand(queue, "get_mapping", { mappingId: id }), "mapping") ?? mapping;
+            }
+            catch (error) {
+                warnings.push(`Mapping ${id} could not be hydrated: ${error instanceof Error ? error.message : String(error)}`);
+                return mapping;
+            }
+        }));
+    }
+    const normalized = normalizeDatabasePayload({ datasets, assets, mappings });
+    return {
+        ok: true,
+        kind: "sxl-database-payload",
+        version: 1,
+        exportedAt: new Date().toISOString(),
+        counts: databaseCounts(normalized),
+        datasets: normalized.datasets,
+        assets: normalized.assets,
+        mappings: normalized.mappings,
+        warnings: [...warnings, ...normalized.warnings],
+    };
+}
 export function registerDataTools(server, queue) {
-    server.tool("apply_mapping", "Apply a data mapping to target nodes in Figma. Maps dataset fields to Figma layers.", {
+    server.tool("list_datasets", "List SXL database datasets in the plugin workspace. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { ...largeDataResponseArgs }, async (args) => callPluginCommand(queue, "list_datasets", args, { largeData: true }));
+    server.tool("get_dataset", "Get one SXL dataset by id. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { datasetId: z.string(), ...largeDataResponseArgs }, async ({ datasetId, ...controls }) => callPluginCommand(queue, "get_dataset", { datasetId, ...controls }, { largeData: true }));
+    server.tool("save_dataset", "Create or update one SXL dataset. Set dryRun=true to preview without writing.", { dataset: datasetZod, dryRun: dryRunZod }, async ({ dataset, dryRun }) => dryRun
+        ? dryRunPreview("save_dataset", dataset.id)
+        : callPluginWriteCommand(queue, "save_dataset", { dataset }, {
+            okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED",
+        }));
+    server.tool("delete_dataset", "Delete one SXL dataset by id. Set dryRun=true to preview without deleting.", { datasetId: z.string(), dryRun: dryRunZod, ...destructiveConfirmationArgs }, async ({ datasetId, dryRun, confirmDestructive, destructiveReason }) => dryRun
+        ? dryRunPreview("delete_dataset", datasetId, { destructive: true })
+        : callPluginWriteCommand(queue, "delete_dataset", withDestructiveConfirmation({ datasetId }, { confirmDestructive, destructiveReason }), { okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED" }));
+    server.tool("list_assets", "List SXL database local assets in the plugin workspace. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { ...largeDataResponseArgs }, async (args) => callPluginCommand(queue, "list_assets", args, { largeData: true }));
+    server.tool("get_asset", "Get one SXL asset by id. Set includeContent=true to include stored base64 content. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { assetId: z.string(), includeContent: z.boolean().optional(), ...largeDataResponseArgs }, async ({ assetId, includeContent, ...controls }) => callPluginCommand(queue, "get_asset", { assetId, includeContent, ...controls }, { largeData: true }));
+    server.tool("save_asset", "Create or update one SXL asset. Optional data is base64 content. Set dryRun=true to preview without writing.", { asset: assetZod, data: z.string().optional(), dryRun: dryRunZod }, async ({ asset, data, dryRun }) => dryRun
+        ? dryRunPreview("save_asset", asset.id, { hasData: typeof data === "string" })
+        : callPluginWriteCommand(queue, "save_asset", { asset, data }, {
+            okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED",
+        }));
+    server.tool("delete_asset", "Delete one SXL asset by id. Set dryRun=true to preview without deleting.", { assetId: z.string(), dryRun: dryRunZod, ...destructiveConfirmationArgs }, async ({ assetId, dryRun, confirmDestructive, destructiveReason }) => dryRun
+        ? dryRunPreview("delete_asset", assetId, { destructive: true })
+        : callPluginWriteCommand(queue, "delete_asset", withDestructiveConfirmation({ assetId }, { confirmDestructive, destructiveReason }), { okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED" }));
+    server.tool("list_mappings", "List SXL database mappings in the plugin workspace. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { ...largeDataResponseArgs }, async (args) => callPluginCommand(queue, "list_mappings", args, { largeData: true }));
+    server.tool("get_mapping", "Get one SXL mapping by id. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", { mappingId: z.string(), ...largeDataResponseArgs }, async ({ mappingId, ...controls }) => callPluginCommand(queue, "get_mapping", { mappingId, ...controls }, { largeData: true }));
+    server.tool("save_mapping", "Create or update one SXL mapping. Set dryRun=true to preview without writing.", { mapping: mappingZod, dryRun: dryRunZod }, async ({ mapping, dryRun }) => dryRun
+        ? dryRunPreview("save_mapping", mapping.id)
+        : callPluginWriteCommand(queue, "save_mapping", { mapping }, {
+            okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED",
+        }));
+    server.tool("delete_mapping", "Delete one SXL mapping by id. Set dryRun=true to preview without deleting.", { mappingId: z.string(), dryRun: dryRunZod, ...destructiveConfirmationArgs }, async ({ mappingId, dryRun, confirmDestructive, destructiveReason }) => dryRun
+        ? dryRunPreview("delete_mapping", mappingId, { destructive: true })
+        : callPluginWriteCommand(queue, "delete_mapping", withDestructiveConfirmation({ mappingId }, { confirmDestructive, destructiveReason }), { okFalseErrorCode: "SXL_DATABASE_WRITE_FAILED" }));
+    server.tool("export_database_payload", "Export a portable SXL database payload (datasets, local assets, mappings) through existing plugin CRUD commands. Asset content is excluded by default; set includeAssetContent=true for backups that need embedded image data.", {
+        includeDatasets: z.boolean().optional(),
+        includeAssets: z.boolean().optional(),
+        includeMappings: z.boolean().optional(),
+        includeAssetContent: z.boolean().optional().describe("Include stored base64/data URL asset content. Default false to keep MCP responses small."),
+        datasetIds: z.array(z.string()).optional(),
+        assetIds: z.array(z.string()).optional(),
+        mappingIds: z.array(z.string()).optional(),
+        ...largeDataResponseArgs,
+    }, async (args) => {
+        try {
+            const payload = await exportDatabasePayload(queue, args);
+            return ok(normalizeLargeDataResult("export_database_payload", args, payload));
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error), {
+                code: "EXPORT_DATABASE_PAYLOAD_ERROR",
+                retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+            });
+        }
+    });
+    server.tool("import_database_payload", "Import a portable SXL database payload by upserting datasets, local assets, and mappings through existing plugin CRUD commands. Defaults to dryRun=true. Existing IDs require confirmDestructive=true when writing.", {
+        payload: databasePayloadZod,
+        dryRun: dryRunZod,
+        confirmDestructive: destructiveConfirmationArgs.confirmDestructive,
+        destructiveReason: destructiveConfirmationArgs.destructiveReason,
+        ...largeDataResponseArgs,
+    }, async ({ payload, dryRun, confirmDestructive, destructiveReason, ...controls }) => {
+        try {
+            const normalized = normalizeDatabasePayload(payload);
+            const existing = await readExistingDatabaseIds(queue);
+            const conflicts = findConflicts(normalized, existing);
+            const effectiveDryRun = dryRun !== false;
+            const preview = {
+                ok: true,
+                dryRun: effectiveDryRun,
+                action: "import_database_payload",
+                counts: databaseCounts(normalized),
+                conflicts,
+                warnings: normalized.warnings,
+                willCallPlugin: !effectiveDryRun,
+            };
+            if (effectiveDryRun) {
+                return ok(normalizeLargeDataResult("import_database_payload", controls, preview));
+            }
+            if (conflicts.total > 0 && confirmDestructive !== true) {
+                return err("import_database_payload would overwrite existing datasets/assets/mappings. Re-run with confirmDestructive=true and destructiveReason.", {
+                    code: "DATABASE_IMPORT_CONFIRMATION_REQUIRED",
+                    retryable: false,
+                    conflicts,
+                });
+            }
+            if (conflicts.total > 0 && (typeof destructiveReason !== "string" || destructiveReason.trim().length === 0)) {
+                return err("destructiveReason is required when import_database_payload overwrites existing IDs.", {
+                    code: "DATABASE_IMPORT_REASON_REQUIRED",
+                    retryable: false,
+                    conflicts,
+                });
+            }
+            const results = [];
+            for (const dataset of normalized.datasets) {
+                const id = readIdValue(dataset);
+                await executePluginWriteCommand(queue, "save_dataset", { dataset });
+                results.push({ type: "dataset", id, status: "saved" });
+            }
+            for (const entry of normalized.assets) {
+                const id = readIdValue(entry.asset);
+                await executePluginWriteCommand(queue, "save_asset", { asset: entry.asset, data: entry.content });
+                results.push({ type: "asset", id, status: "saved", hasContent: typeof entry.content === "string" });
+            }
+            for (const mapping of normalized.mappings) {
+                const id = readIdValue(mapping);
+                await executePluginWriteCommand(queue, "save_mapping", { mapping });
+                results.push({ type: "mapping", id, status: "saved" });
+            }
+            return ok(normalizeLargeDataResult("import_database_payload", controls, {
+                ...preview,
+                ok: true,
+                dryRun: false,
+                applied: true,
+                results,
+            }));
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error), {
+                code: "IMPORT_DATABASE_PAYLOAD_ERROR",
+                retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+            });
+        }
+    });
+    server.tool("apply_mapping", "Apply a data mapping to explicit targetNodeIds or the current Figma selection. Use dryRun=true first to inspect mapping fields, dataset ids, and target count without writing.", {
         mappingId: z.string().describe("ID of the mapping to apply"),
-        targetNodes: z.array(z.unknown()).optional().describe("Optional target nodes array"),
-    }, async ({ mappingId, targetNodes }) => {
-        const result = await queue.execute("apply_mapping", { mappingId, targetNodes: targetNodes ?? [] });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        targetNodeIds: z.array(z.string()).optional().describe("Optional explicit scene node ids to use as selection roots for this apply."),
+        targetNodes: z.array(z.unknown()).optional().describe("Legacy target node objects with id fields. Prefer targetNodeIds."),
+        dryRun: dryRunZod,
+    }, async ({ mappingId, targetNodeIds, targetNodes, dryRun }) => {
+        const resolvedTargetNodeIds = readTargetNodeIds({ targetNodeIds, targetNodes });
+        if (dryRun) {
+            try {
+                const mapping = await getMappingById(queue, mappingId);
+                const targetCount = await countApplyTargetsSafely(queue, "selection", resolvedTargetNodeIds);
+                const datasets = await datasetSummariesForMapping(queue, mapping);
+                const warnings = [
+                    ...datasets.warnings,
+                    ...(targetCount.warning ? [targetCount.warning] : []),
+                    ...(Array.isArray(targetNodes) && targetNodes.length > 0
+                        ? ["targetNodes is supported as a legacy id carrier; prefer targetNodeIds for new clients."]
+                        : []),
+                ];
+                return ok({
+                    ok: Boolean(mapping),
+                    dryRun: true,
+                    action: "apply_mapping",
+                    mappingId,
+                    mappingExists: Boolean(mapping),
+                    mapping: summarizeMapping(mapping),
+                    scope: "selection",
+                    targetMode: resolvedTargetNodeIds.length > 0 ? "explicit-targets" : "current-selection",
+                    selectionTargetCount: targetCount.count,
+                    targetNodeIds: resolvedTargetNodeIds,
+                    providedTargetNodes: resolvedTargetNodeIds.length,
+                    datasets: datasets.datasets,
+                    warnings,
+                    willCallPlugin: false,
+                });
+            }
+            catch (error) {
+                return err(error instanceof Error ? error.message : String(error), {
+                    code: "APPLY_MAPPING_PREVIEW_ERROR",
+                    retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+                });
+            }
+        }
+        return callPluginWriteCommand(queue, "apply_mapping", {
+            mappingId,
+            ...(resolvedTargetNodeIds.length > 0 ? { targetNodeIds: resolvedTargetNodeIds } : {}),
+            ...(targetNodes ? { targetNodes } : {}),
+        }, { okFalseErrorCode: "SXL_DATA_WRITE_FAILED" });
     });
-    server.tool("apply_all_mappings", "Apply all mappings within a scope (selection, page, or document).", { scope: z.string().optional().describe("Scope: selection, page, or document") }, async ({ scope }) => {
-        const result = await queue.execute("apply_all_mappings", scope ? { scope } : {});
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    server.tool("apply_all_mappings", "Apply all mappings within a scope (selection, page, or document). Use dryRun=true first to count mappings and matching targets without writing.", {
+        scope: applyScopeZod.optional().describe("Scope: selection, page, or document. Default: selection."),
+        targetNodeIds: z.array(z.string()).optional().describe("Optional explicit scene node ids; when provided Bridge applies/counts these as selection roots."),
+        targetNodes: z.array(z.unknown()).optional().describe("Legacy target node objects with id fields. Prefer targetNodeIds."),
+        dryRun: dryRunZod,
+    }, async ({ scope, targetNodeIds, targetNodes, dryRun }) => {
+        const effectiveScope = scope ?? "selection";
+        const resolvedTargetNodeIds = readTargetNodeIds({ targetNodeIds, targetNodes });
+        if (dryRun) {
+            try {
+                const mappingsResult = await executePluginCommand(queue, "list_mappings");
+                const mappings = readArrayResult(mappingsResult, "mappings");
+                const targetCount = await countApplyTargetsSafely(queue, effectiveScope, resolvedTargetNodeIds);
+                return ok({
+                    ok: true,
+                    dryRun: true,
+                    action: "apply_all_mappings",
+                    scope: effectiveScope,
+                    targetMode: resolvedTargetNodeIds.length > 0 ? "explicit-targets" : "scope",
+                    targetNodeIds: resolvedTargetNodeIds,
+                    mappingCount: mappings.length,
+                    mappings: mappings.map((mapping) => summarizeMapping(mapping)),
+                    targetCount: targetCount.count,
+                    warnings: targetCount.warning ? [targetCount.warning] : [],
+                    willCallPlugin: false,
+                });
+            }
+            catch (error) {
+                return err(error instanceof Error ? error.message : String(error), {
+                    code: "APPLY_ALL_MAPPINGS_PREVIEW_ERROR",
+                    retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+                });
+            }
+        }
+        return callPluginWriteCommand(queue, "apply_all_mappings", {
+            scope: effectiveScope,
+            ...(resolvedTargetNodeIds.length > 0 ? { targetNodeIds: resolvedTargetNodeIds } : {}),
+            ...(targetNodes ? { targetNodes } : {}),
+        }, { okFalseErrorCode: "SXL_DATA_WRITE_FAILED" });
     });
-    server.tool("count_apply_targets", "Count how many nodes match a mapping scope.", { scope: z.string().describe("Scope: selection, page, or document") }, async ({ scope }) => {
-        const result = await queue.execute("count_apply_targets", { scope });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    server.tool("count_apply_targets", "Count how many nodes match a mapping scope.", {
+        scope: applyScopeZod.describe("Scope: selection, page, or document"),
+        targetNodeIds: z.array(z.string()).optional().describe("Optional explicit scene node ids to count as selection roots."),
+        targetNodes: z.array(z.unknown()).optional().describe("Legacy target node objects with id fields. Prefer targetNodeIds."),
+    }, async ({ scope, targetNodeIds, targetNodes }) => {
+        const resolvedTargetNodeIds = readTargetNodeIds({ targetNodeIds, targetNodes });
+        return callPluginCommand(queue, "count_apply_targets", {
+            scope,
+            ...(resolvedTargetNodeIds.length > 0 ? { targetNodeIds: resolvedTargetNodeIds } : {}),
+            ...(targetNodes ? { targetNodes } : {}),
+        });
     });
-    server.tool("generate_instances", "Generate component instances from mapping data.", {
+    server.tool("generate_instances", "Generate component instances from mapping data into explicit targetNodeIds or the current Figma selection. Use dryRun=true first to estimate rows and validate mapping/dataset references without writing.", {
         mappingId: z.string().describe("Mapping ID to generate from"),
         rowCount: z.number().nullable().optional().describe("Number of rows to generate (null for all)"),
-    }, async ({ mappingId, rowCount }) => {
-        const result = await queue.execute("generate_instances", {
+        targetNodeIds: z.array(z.string()).optional().describe("Optional explicit scene node ids to use as the template/container source."),
+        targetNodes: z.array(z.unknown()).optional().describe("Legacy target node objects with id fields. Prefer targetNodeIds."),
+        dryRun: dryRunZod,
+    }, async ({ mappingId, rowCount, targetNodeIds, targetNodes, dryRun }) => {
+        const resolvedTargetNodeIds = readTargetNodeIds({ targetNodeIds, targetNodes });
+        if (dryRun) {
+            try {
+                const mapping = await getMappingById(queue, mappingId);
+                const datasets = await datasetSummariesForMapping(queue, mapping);
+                const primaryRows = datasets.datasets.find((dataset) => typeof dataset.rowCount === "number")?.rowCount;
+                const warnings = [
+                    ...datasets.warnings,
+                    ...(Array.isArray(targetNodes) && targetNodes.length > 0
+                        ? ["targetNodes is supported as a legacy id carrier; prefer targetNodeIds for new clients."]
+                        : []),
+                    ...(resolvedTargetNodeIds.length === 0
+                        ? ["No targetNodeIds provided; committed generate_instances will use the current Figma selection as the template/container source."]
+                        : []),
+                ];
+                return ok({
+                    ok: Boolean(mapping),
+                    dryRun: true,
+                    action: "generate_instances",
+                    mappingId,
+                    mappingExists: Boolean(mapping),
+                    mapping: summarizeMapping(mapping),
+                    scope: "selection",
+                    targetMode: resolvedTargetNodeIds.length > 0 ? "explicit-targets" : "current-selection",
+                    targetNodeIds: resolvedTargetNodeIds,
+                    providedTargetNodes: resolvedTargetNodeIds.length,
+                    requestedRowCount: rowCount ?? null,
+                    estimatedRows: resolveRequestedRowCount(primaryRows ?? null, rowCount ?? null),
+                    datasets: datasets.datasets,
+                    warnings,
+                    willCallPlugin: false,
+                });
+            }
+            catch (error) {
+                return err(error instanceof Error ? error.message : String(error), {
+                    code: "GENERATE_INSTANCES_PREVIEW_ERROR",
+                    retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+                });
+            }
+        }
+        return callPluginWriteCommand(queue, "generate_instances", {
             mappingId,
             rowCount: rowCount ?? null,
             scope: "selection",
-        });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            ...(resolvedTargetNodeIds.length > 0 ? { targetNodeIds: resolvedTargetNodeIds } : {}),
+            ...(targetNodes ? { targetNodes } : {}),
+        }, { okFalseErrorCode: "SXL_DATA_WRITE_FAILED" });
     });
     server.tool("apply_image", "Apply an image from URL to the current selection.", {
         url: z.string().describe("Image URL"),
         name: z.string().describe("Image name"),
-    }, async ({ url, name }) => {
-        const result = await queue.execute("apply_image", { url, name });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }, async ({ url, name }) => callPluginWriteCommand(queue, "apply_image", { url, name }, {
+        okFalseErrorCode: "SXL_CANVAS_WRITE_FAILED",
+    }));
+    server.tool("upload_assets", "Bridge asset uploader for Figma Design: fetch/validate PNG, JPG/JPEG, GIF, or WebP assets up to 10MB each and apply them as image fills. If nodeId is supplied the asset fills that node; otherwise Bridge creates image rectangles. Use dryRun=true first.", {
+        assets: z.array(uploadAssetZod).min(1).max(10),
+        dryRun: dryRunZod,
+        fetchInDryRun: z.boolean().optional().describe("If true, dryRun also fetches assets to verify MIME/size."),
+        maxBytes: z.number().int().positive().max(10 * 1024 * 1024).optional().describe("Per-asset byte limit. Default/max: 10MB."),
+        parentId: z.string().optional(),
+        targetNodeId: z.string().optional().describe("Default nodeId for assets that omit nodeId."),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        width: z.number().positive().optional(),
+        height: z.number().positive().optional(),
+        gap: z.number().min(0).optional(),
+        scaleMode: imageScaleModeZod.optional(),
+    }, async (args) => {
+        try {
+            const prepared = await prepareUploadAssets(args);
+            if (prepared.dryRun) {
+                return ok({
+                    ok: true,
+                    dryRun: true,
+                    count: prepared.count,
+                    maxBytes: prepared.maxBytes,
+                    assets: uploadAssetReports(prepared),
+                });
+            }
+            const results = [];
+            for (const asset of prepared.assets) {
+                if (!asset.payload) {
+                    results.push({ ...asset.report, status: "failed", error: "Missing prepared plugin payload" });
+                    continue;
+                }
+                try {
+                    const pluginResult = await executePluginCommand(queue, "set_image_fill", asset.payload);
+                    if (isRecord(pluginResult) && pluginResult.ok === false) {
+                        results.push({
+                            ...asset.report,
+                            status: "failed",
+                            error: typeof pluginResult.error === "string"
+                                ? pluginResult.error
+                                : typeof pluginResult.message === "string"
+                                    ? pluginResult.message
+                                    : "set_image_fill returned ok:false",
+                            result: pluginResult,
+                        });
+                        continue;
+                    }
+                    results.push({ ...asset.report, status: "completed", result: pluginResult });
+                }
+                catch (error) {
+                    results.push({
+                        ...asset.report,
+                        status: "failed",
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            const failures = results.filter((result) => result.status !== "completed");
+            return ok({
+                ok: failures.length === 0,
+                dryRun: false,
+                count: prepared.count,
+                completed: results.length - failures.length,
+                failed: failures.length,
+                assets: results,
+            });
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error), {
+                code: "UPLOAD_ASSETS_ERROR",
+                retryable: false,
+            });
+        }
+    });
+    server.tool("get_code_connect_suggestions", "Bridge-local Code Connect suggestion engine. Scans a local codebase for likely component files, ranks candidate CodeConnectBinding payloads by selected Figma node/component names, and returns reviewable bindings for codeconnect_save_binding. If targets/componentNames are omitted Bridge reads the current Figma selection via get_selection_summary.", {
+        targets: z.array(codeConnectTargetZod).optional(),
+        componentNames: z.array(z.string()).optional(),
+        rootDir: z.string().optional().describe("Local codebase root to scan. Defaults to SXL_CODECONNECT_ROOT or the Bridge process cwd."),
+        repositoryUrl: z.string().optional().describe("Repository web URL copied into suggested binding.gitlabUrl."),
+        gitlabUrl: z.string().optional().describe("Explicit CodeConnectBinding.gitlabUrl override."),
+        documentationUrl: z.string().optional(),
+        documentationDocsQuerySuffix: z.string().optional(),
+        documentationStoryPathTemplate: z.string().optional(),
+        frameworks: z.array(codeConnectFrameworkZod).optional(),
+        maxSuggestionsPerTarget: z.number().int().positive().max(20).optional(),
+        maxFiles: z.number().int().positive().max(10_000).optional(),
+        maxFileBytes: z.number().int().positive().max(1024 * 1024).optional(),
+        includeLowConfidence: z.boolean().optional(),
+        ...largeDataResponseArgs,
+    }, async (args) => {
+        let hasDirectTargets = false;
+        try {
+            let selectionSummary;
+            hasDirectTargets =
+                (Array.isArray(args.targets) && args.targets.length > 0) ||
+                    (Array.isArray(args.componentNames) && args.componentNames.length > 0);
+            if (!hasDirectTargets) {
+                selectionSummary = await executePluginCommand(queue, "get_selection_summary");
+            }
+            const result = buildCodeConnectSuggestions(args, selectionSummary);
+            if (result.targets.length === 0) {
+                return err("No Code Connect targets found. Provide targets/componentNames or select component nodes in Figma with Remote Connect active.", {
+                    code: "CODECONNECT_SUGGESTIONS_NO_TARGETS",
+                    retryable: true,
+                });
+            }
+            return ok(normalizeLargeDataResult("get_code_connect_suggestions", args, result));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const retryable = !hasDirectTargets && /No plugin connected|Session disconnected/i.test(message);
+            return err(message, {
+                code: "CODECONNECT_SUGGESTIONS_ERROR",
+                retryable,
+            });
+        }
+    });
+    server.tool("inspect_enabled_libraries", "Read enabled team-library descriptors for the current Figma file through the plugin teamLibrary API. Returns enabled variable collections and, when available in the Figma runtime, component/style descriptors. This cannot enable libraries or enumerate arbitrary organization/community libraries.", {
+        query: z.string().optional().describe("Optional case-insensitive filter by library/name."),
+        limitPerKind: z.number().int().positive().max(5_000).optional(),
+        includeVariableCollections: z.boolean().optional(),
+        includeStyles: z.boolean().optional(),
+        includeComponents: z.boolean().optional(),
+        ...largeDataResponseArgs,
+    }, async (args) => callPluginCommand(queue, "inspect_enabled_libraries", args, { largeData: true }));
+    server.tool("list_enabled_library_variables", "Read variables from enabled team-library variable collections. Provide collectionKey, collectionKeys, collectionName, libraryName, or includeAllCollections=true. Large responses are summarized automatically for MCP unless bridgeResponseMode='full'.", {
+        collectionKey: z.string().optional(),
+        collectionKeys: z.array(z.string()).optional(),
+        collectionName: z.string().optional(),
+        libraryName: z.string().optional(),
+        includeAllCollections: z.boolean().optional(),
+        resolvedTypes: z.array(variableResolvedTypeZod).optional(),
+        query: z.string().optional(),
+        limit: z.number().int().positive().max(10_000).optional(),
+        ...largeDataResponseArgs,
+    }, async (args) => callPluginCommand(queue, "list_enabled_library_variables", args, { largeData: true }));
+    server.tool("search_enabled_library_assets", "Bridge orchestration search over libraries already enabled for the current Figma file. Searches component/style/variable collection descriptors plus enabled library variables with bounded scans. This cannot enable libraries or discover arbitrary organization/community libraries.", {
+        query: z.string().min(1),
+        kinds: z.array(enabledLibraryAssetKindZod).optional(),
+        libraryName: z.string().optional(),
+        collectionKey: z.string().optional(),
+        collectionName: z.string().optional(),
+        resolvedTypes: z.array(variableResolvedTypeZod).optional(),
+        maxMatches: z.number().int().positive().max(500).optional(),
+        maxVariables: z.number().int().positive().max(10_000).optional(),
+        includeVariables: z.boolean().optional().describe("Default true. Set false for a cheaper descriptor-only search."),
+        ...largeDataResponseArgs,
+    }, async (args) => {
+        try {
+            const kinds = Array.isArray(args.kinds) && args.kinds.length > 0
+                ? args.kinds
+                : ["component", "style", "variable", "variableCollection"];
+            const includeVariables = args.includeVariables !== false && kinds.includes("variable");
+            const inspectResult = await executePluginCommand(queue, "inspect_enabled_libraries", {
+                query: args.query,
+                limitPerKind: args.maxMatches ?? 100,
+                includeComponents: kinds.includes("component"),
+                includeStyles: kinds.includes("style"),
+                includeVariableCollections: true,
+            });
+            let variableResult;
+            const warnings = [];
+            if (includeVariables) {
+                try {
+                    variableResult = await executePluginCommand(queue, "list_enabled_library_variables", {
+                        query: args.query,
+                        collectionKey: args.collectionKey,
+                        collectionName: args.collectionName,
+                        libraryName: args.libraryName,
+                        includeAllCollections: !args.collectionKey && !args.collectionName && !args.libraryName,
+                        resolvedTypes: args.resolvedTypes,
+                        limit: args.maxVariables ?? 1_000,
+                    });
+                }
+                catch (error) {
+                    warnings.push(`Variable scan failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            const result = buildEnabledLibrarySearchResult({
+                args: {
+                    query: args.query,
+                    kinds,
+                    libraryName: args.libraryName,
+                    collectionKey: args.collectionKey,
+                    collectionName: args.collectionName,
+                    maxMatches: args.maxMatches,
+                },
+                inspectResult,
+                variableResult,
+                warnings,
+            });
+            return ok(normalizeLargeDataResult("search_enabled_library_assets", args, result));
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error), {
+                code: "SEARCH_ENABLED_LIBRARY_ASSETS_ERROR",
+                retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+            });
+        }
     });
     server.tool("set_node_text", "Set text content on a text layer in the currently selected nodes (or a specific node by ID). If layerName is provided, finds text nodes with that name inside the selection. Otherwise sets text on all text nodes in selection.", {
         text: z.string().describe("Text content to set"),
         layerName: z.string().optional().describe("Name of the text layer to target (e.g. 'label', 'title'). Omit to set all text nodes."),
         nodeId: z.string().optional().describe("Specific Figma node ID. Omit to use current selection."),
-    }, async ({ text, layerName, nodeId }) => {
-        const result = await queue.execute("set_node_text", { text, layerName, nodeId });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    });
+    }, async ({ text, layerName, nodeId }) => callPluginWriteCommand(queue, "set_node_text", { text, layerName, nodeId }, {
+        okFalseErrorCode: "SXL_CANVAS_WRITE_FAILED",
+    }));
     server.tool("set_node_property", "Set a component property on a selected instance or component. For instances, sets instance property. For components, sets default value.", {
         propertyName: z.string().describe("Property name (e.g. 'label', 'isIcon', 'size')"),
         propertyValue: z.union([z.string(), z.boolean(), z.number()]).describe("Property value"),
         nodeId: z.string().optional().describe("Specific Figma node ID. Omit to use current selection."),
-    }, async ({ propertyName, propertyValue, nodeId }) => {
-        const result = await queue.execute("set_node_property", { propertyName, propertyValue, nodeId });
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    });
+    }, async ({ propertyName, propertyValue, nodeId }) => callPluginWriteCommand(queue, "set_node_property", { propertyName, propertyValue, nodeId }, {
+        okFalseErrorCode: "SXL_CANVAS_WRITE_FAILED",
+    }));
 }
 //# sourceMappingURL=data.js.map