@sxl-studio/bridge 1.7.1 → 1.7.3

package/dist/codeconnect-template.js

@@ -0,0 +1,280 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { buildCodeConnectSuggestions, } from "./codeconnect-suggestions.js";
+function clampIndex(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.floor(value));
+}
+function escapeStringLiteral(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/'/g, "\\'")
+        .replace(/\r/g, "\\r")
+        .replace(/\n/g, "\\n");
+}
+function escapeTemplateLiteral(value, preserveExpressions = false) {
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/`/g, "\\`")
+        .replace(/\$\{/g, preserveExpressions ? "${" : "\\${");
+    return escaped;
+}
+function pascalCase(value) {
+    const parts = value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^a-zA-Z0-9]+/g)
+        .filter(Boolean);
+    if (parts.length === 0)
+        return "Component";
+    return parts.map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join("");
+}
+function camelCase(value) {
+    const pascal = pascalCase(value);
+    return `${pascal.slice(0, 1).toLowerCase()}${pascal.slice(1)}` || "value";
+}
+function safeIdentifier(value, used) {
+    const base = camelCase(value).replace(/^[^a-zA-Z_$]+/, "") || "value";
+    let next = base;
+    let index = 2;
+    while (used.has(next)) {
+        next = `${base}${index}`;
+        index += 1;
+    }
+    used.add(next);
+    return next;
+}
+function safeTemplateId(value) {
+    const id = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+    return id || "code-connect-template";
+}
+function fileNameFor(value) {
+    const base = pascalCase(value);
+    return `${base}.figma.ts`;
+}
+function selectSuggestion(args) {
+    const suggestions = buildCodeConnectSuggestions({
+        targets: args.targets,
+        componentNames: args.componentNames,
+        rootDir: args.rootDir,
+        repositoryUrl: args.repositoryUrl,
+        gitlabUrl: args.gitlabUrl,
+        documentationUrl: args.documentationUrl,
+        documentationDocsQuerySuffix: args.documentationDocsQuerySuffix,
+        documentationStoryPathTemplate: args.documentationStoryPathTemplate,
+        frameworks: args.frameworks,
+        maxSuggestionsPerTarget: args.maxSuggestionsPerTarget,
+        maxFiles: args.maxFiles,
+        maxFileBytes: args.maxFileBytes,
+        includeLowConfidence: args.includeLowConfidence,
+    });
+    const target = suggestions.targets[clampIndex(args.targetIndex, 0)];
+    const suggestion = target?.suggestions[clampIndex(args.suggestionIndex, 0)];
+    if (!target || !suggestion)
+        return null;
+    return { target, suggestion };
+}
+function firstFile(binding) {
+    return binding.files?.find((file) => file.componentName || file.filePath || file.importPath) ?? binding.files?.[0];
+}
+function componentNameFor(binding) {
+    return firstFile(binding)?.componentName?.trim() || pascalCase(binding.displayName);
+}
+function importPathFor(binding) {
+    return binding.importPath?.trim() || firstFile(binding)?.importPath?.trim() || null;
+}
+function sourceFilePathFor(binding) {
+    return firstFile(binding)?.filePath?.trim() || null;
+}
+function snippetFor(binding, componentName, includeAttrs, attrs) {
+    if (!includeAttrs) {
+        return binding.snippetTemplate?.trim() || firstFile(binding)?.snippetTemplate?.trim() || `<${componentName} />`;
+    }
+    if (attrs.length === 0)
+        return `<${componentName} />`;
+    return `<${componentName} ${attrs.join(" ")} />`;
+}
+function propertyKind(property) {
+    return property.kind.trim().toUpperCase();
+}
+function accessorFor(property, variableName) {
+    const name = escapeStringLiteral(property.name);
+    const kind = propertyKind(property);
+    if (kind === "TEXT")
+        return `const ${variableName} = instance.getString('${name}')`;
+    if (kind === "BOOLEAN")
+        return `const ${variableName} = instance.getBoolean('${name}')`;
+    if (kind === "VARIANT") {
+        const options = Array.isArray(property.options) ? property.options : [];
+        const mapLines = options.length > 0
+            ? options.map((option) => `  '${escapeStringLiteral(option)}': '${escapeStringLiteral(option)}',`).join("\n")
+            : `  '${escapeStringLiteral(String(property.defaultValue ?? "Default"))}': '${escapeStringLiteral(String(property.defaultValue ?? "Default"))}',`;
+        return `const ${variableName} = instance.getEnum('${name}', {\n${mapLines}\n})`;
+    }
+    if (kind === "INSTANCE_SWAP")
+        return `const ${variableName} = instance.getInstanceSwap('${name}')`;
+    if (kind === "SLOT")
+        return `const ${variableName} = instance.getSlot('${name}')`;
+    return `const ${variableName} = instance.getString('${name}')`;
+}
+function propertyAttr(property, variableName) {
+    const propName = camelCase(property.name);
+    const kind = propertyKind(property);
+    if (kind === "TEXT" || kind === "VARIANT")
+        return `${propName}={\${${variableName}}}`;
+    if (kind === "BOOLEAN")
+        return `${propName}={\${${variableName}}}`;
+    return null;
+}
+function buildPropertyBlock(binding, includeAccessors, includeMetadata, includeAttrs) {
+    const properties = binding.storybook?.componentApi?.properties ?? [];
+    if (!includeAccessors || properties.length === 0) {
+        return { lines: [], metadataLines: [], attrs: [], names: [] };
+    }
+    const used = new Set();
+    const lines = [];
+    const metadataLines = [];
+    const attrs = [];
+    const names = [];
+    for (const property of properties) {
+        if (!property.name.trim())
+            continue;
+        const variableName = safeIdentifier(property.name, used);
+        names.push(variableName);
+        lines.push(accessorFor(property, variableName));
+        if (includeMetadata)
+            metadataLines.push(`      ${variableName},`);
+        const attr = includeAttrs ? propertyAttr(property, variableName) : null;
+        if (attr)
+            attrs.push(attr);
+    }
+    return { lines, metadataLines, attrs, names };
+}
+function outputPathFor(args, binding, rootDir, componentName) {
+    if (args.outputPath?.trim())
+        return path.resolve(args.outputPath);
+    const fileName = args.fileName?.trim() || fileNameFor(componentName);
+    if (args.outputDir?.trim())
+        return path.resolve(rootDir, args.outputDir, fileName);
+    const sourceFile = sourceFilePathFor(binding);
+    const sourceDir = sourceFile ? path.dirname(sourceFile) : ".";
+    return path.resolve(rootDir, sourceDir, fileName);
+}
+function assertInsideRoot(outputPath, rootDir, allowOutsideRoot) {
+    if (allowOutsideRoot)
+        return;
+    const relative = path.relative(rootDir, outputPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("outputPath must stay inside rootDir unless allowOutsideRoot=true");
+    }
+}
+function templateContent(args, binding) {
+    const componentName = componentNameFor(binding);
+    const importPath = importPathFor(binding);
+    const sourceFilePath = sourceFilePathFor(binding);
+    const includeAccessors = args.includePropertyAccessors !== false;
+    const includeMetadata = args.includePropertyMetadata !== false;
+    const includeAttrs = args.includePropertyAttrs === true;
+    const props = buildPropertyBlock(binding, includeAccessors, includeMetadata, includeAttrs);
+    const snippet = snippetFor(binding, componentName, includeAttrs, props.attrs);
+    const lines = [];
+    if (args.figmaUrl?.trim())
+        lines.push(`// url=${args.figmaUrl.trim()}`);
+    else if (args.nodeId?.trim())
+        lines.push(`// node-id=${args.nodeId.trim()}`);
+    if (sourceFilePath)
+        lines.push(`// source=${sourceFilePath}`);
+    lines.push(`// component=${componentName}`);
+    lines.push("import figma from 'figma'");
+    lines.push("");
+    lines.push("const instance = figma.selectedInstance");
+    if (props.lines.length > 0) {
+        lines.push("");
+        lines.push(...props.lines);
+    }
+    lines.push("");
+    lines.push("export default {");
+    lines.push(`  id: '${safeTemplateId(binding.displayName || componentName)}',`);
+    lines.push(`  example: figma.code\`${escapeTemplateLiteral(snippet, includeAttrs)}\`,`);
+    if (importPath) {
+        lines.push(`  imports: ['import { ${componentName} } from "${escapeStringLiteral(importPath)}"'],`);
+    }
+    if (includeMetadata && props.metadataLines.length > 0) {
+        lines.push("  metadata: {");
+        lines.push("    nestable: true,");
+        lines.push("    props: {");
+        lines.push(...props.metadataLines);
+        lines.push("    },");
+        lines.push("  },");
+    }
+    lines.push("}");
+    lines.push("");
+    return {
+        content: lines.join("\n"),
+        componentName,
+        importPath,
+        sourceFilePath,
+        propertyAccessors: props.names,
+    };
+}
+export function generateCodeConnectTemplate(args) {
+    const rootDir = path.resolve(args.rootDir ?? process.env.SXL_CODECONNECT_ROOT ?? process.cwd());
+    const selected = args.binding ? null : selectSuggestion(args);
+    const binding = (args.binding ?? selected?.suggestion.binding);
+    if (!binding) {
+        throw new Error("No Code Connect binding available. Provide binding or componentNames/targets with a matching local source file.");
+    }
+    const generated = templateContent(args, binding);
+    const outputPath = outputPathFor(args, binding, rootDir, generated.componentName);
+    assertInsideRoot(outputPath, rootDir, args.allowOutsideRoot);
+    const writeRequested = args.writeFile === true;
+    const existed = existsSync(outputPath);
+    if (writeRequested) {
+        if (existed && args.overwrite !== true) {
+            throw new Error(`Template already exists at ${outputPath}. Set overwrite=true to replace it.`);
+        }
+        mkdirSync(path.dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, generated.content, "utf8");
+    }
+    const warnings = [];
+    if (generated.propertyAccessors.length > 0 && args.includePropertyAttrs !== true) {
+        warnings.push("Figma component API properties were emitted as accessors/metadata only. Set includePropertyAttrs=true only after verifying matching code component prop names.");
+    }
+    if (!generated.importPath) {
+        warnings.push("No importPath was available; imports[] was omitted from the generated template.");
+    }
+    return {
+        ok: true,
+        source: "bridge-code-connect-template",
+        dryRun: !writeRequested,
+        generatedAt: new Date().toISOString(),
+        target: selected?.target ?? null,
+        binding,
+        template: {
+            fileName: path.basename(outputPath),
+            outputPath,
+            content: generated.content,
+            bytes: Buffer.byteLength(generated.content, "utf8"),
+            componentName: generated.componentName,
+            importPath: generated.importPath,
+            sourceFilePath: generated.sourceFilePath,
+            propertyAccessors: generated.propertyAccessors,
+        },
+        write: {
+            requested: writeRequested,
+            written: writeRequested,
+            overwritten: writeRequested && existed,
+        },
+        warnings,
+        nextStep: writeRequested
+            ? "Review the generated .figma.ts template, adjust prop mappings if needed, then publish/apply Code Connect through your normal repository workflow."
+            : "Review template.content and call generate_code_connect_template with writeFile=true to create the .figma.ts file.",
+    };
+}
+//# sourceMappingURL=codeconnect-template.js.map

package/dist/codeconnect-template.js.map

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

package/dist/command-queue.d.ts

@@ -4,7 +4,7 @@
  * Serial execution: one command at a time.
  * Each command has a timeout. Results are resolved via promises.
  */
-import type { CommandResult, CommandStatus } from "./types.js";
+import type { CommandQueueSnapshot, CommandResult, CommandStatus, CommandTelemetryEvent, CommandTelemetrySummary } from "./types.js";
 /** Per-command client timeouts. Keep long to avoid client-side aborts on heavy files. */
 export declare const BRIDGE_COMMAND_TIMEOUT_MS: Readonly<Record<string, number>>;
 type CommandSender = (command: {
@@ -15,15 +15,37 @@ type CommandSender = (command: {
 export declare class CommandQueue {
     private queue;
     private current;
+    private immediate;
     private sendCommand;
-    private timeoutHandle;
+    private timeoutHandles;
+    private events;
     setSender(sender: CommandSender): void;
     get queueLength(): number;
     get currentCommand(): string | null;
+    getSnapshot(now?: number): CommandQueueSnapshot;
+    getEventsSnapshot(filters?: {
+        limit?: number;
+        commandId?: string | null;
+    }): CommandTelemetryEvent[];
+    getTelemetrySummary(now?: number): CommandTelemetrySummary;
     execute(commandType: string, payload?: Record<string, unknown>): Promise<CommandResult>;
+    /**
+     * Out-of-band command dispatch for control-plane operations.
+     *
+     * Long Figma operations are intentionally serialized, but cancellation must be able
+     * to reach the plugin while another command is running. The plugin main handler can
+     * process this command concurrently during generator yields and flip its cancellation
+     * flag; queuing it behind the running command makes cancellation ineffective.
+     */
+    private executeImmediate;
+    private scheduleTimeout;
     resolveCommand(commandId: string, status: CommandStatus, result?: unknown, error?: string, events?: unknown[], durationMs?: number): void;
     cancelAll(): void;
     private processNext;
+    recordPluginEvent(raw: unknown): void;
     private clearTimeout;
+    private clearAllTimeouts;
+    private recordCommandEvent;
+    private recordTelemetryEvent;
 }
 export {};