@sxl-studio/bridge 1.7.2 → 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: {
@@ -18,9 +18,16 @@ export declare class CommandQueue {
     private immediate;
     private sendCommand;
     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.
@@ -35,7 +42,10 @@ export declare class CommandQueue {
     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 {};

package/dist/command-queue.js

@@ -5,6 +5,7 @@
  * Each command has a timeout. Results are resolved via promises.
  */
 import { randomUUID } from "node:crypto";
+import { guardDestructiveCommand } from "./command-safety.js";
 /** Per-command client timeouts. Keep long to avoid client-side aborts on heavy files. */
 export const BRIDGE_COMMAND_TIMEOUT_MS = {
     export_variables: 3_600_000,
@@ -16,6 +17,21 @@ export const BRIDGE_COMMAND_TIMEOUT_MS = {
     apply_all_mappings: 3_600_000,
     export_composition_json: 3_600_000,
     get_token_file_content: 3_600_000,
+    list_datasets: 3_600_000,
+    get_dataset: 3_600_000,
+    save_dataset: 3_600_000,
+    delete_dataset: 3_600_000,
+    list_assets: 3_600_000,
+    get_asset: 3_600_000,
+    save_asset: 3_600_000,
+    delete_asset: 3_600_000,
+    list_mappings: 3_600_000,
+    get_mapping: 3_600_000,
+    save_mapping: 3_600_000,
+    delete_mapping: 3_600_000,
+    inspect_enabled_libraries: 3_600_000,
+    list_enabled_library_variables: 3_600_000,
+    search_enabled_library_assets: 3_600_000,
     save_token_file: 3_600_000,
     duplicate_subtree: 3_600_000,
     apply_documentation_payload: 3_600_000,
@@ -41,6 +57,10 @@ export const BRIDGE_COMMAND_TIMEOUT_MS = {
     flatten_nodes: 3_600_000,
     get_local_styles: 3_600_000,
     list_components: 3_600_000,
+    get_metadata: 3_600_000,
+    get_design_context: 3_600_000,
+    get_context_for_code_connect: 3_600_000,
+    generate_code_connect_template: 3_600_000,
     find_nodes: 3_600_000,
     get_page_structure: 3_600_000,
     get_variables: 3_600_000,
@@ -55,6 +75,12 @@ export const BRIDGE_COMMAND_TIMEOUT_MS = {
     find_style_coverage_misses: 3_600_000,
     find_unused_variables: 3_600_000,
     find_unused_styles: 3_600_000,
+    analyze_component_usage: 3_600_000,
+    find_component_usages: 3_600_000,
+    analyze_component_prop_usage: 3_600_000,
+    find_component_prop_usages: 3_600_000,
+    get_selection_variable_defs: 3_600_000,
+    update_screen: 3_600_000,
     /** Variables orchestration (Bridge platform Phase B) */
     import_variable_spec: 3_600_000,
     analyze_variable_order: 3_600_000,
@@ -63,6 +89,7 @@ export const BRIDGE_COMMAND_TIMEOUT_MS = {
     apply_coverage_suggestions: 3_600_000,
 };
 const DEFAULT_TIMEOUT = 3_600_000;
+const EVENT_BUFFER_SIZE = 1_000;
 const IMMEDIATE_COMMAND_TYPES = new Set([
     "cancel_composition_generation",
 ]);
@@ -72,6 +99,7 @@ export class CommandQueue {
     immediate = new Map();
     sendCommand = null;
     timeoutHandles = new Map();
+    events = [];
     setSender(sender) {
         this.sendCommand = sender;
     }
@@ -81,11 +109,60 @@ export class CommandQueue {
     get currentCommand() {
         return this.current?.commandType ?? null;
     }
+    getSnapshot(now = Date.now()) {
+        return {
+            current: this.current ? snapshotCommand(this.current, now) : null,
+            queued: this.queue.map((command) => snapshotCommand(command, now)),
+            immediate: Array.from(this.immediate.values()).map((command) => snapshotCommand(command, now)),
+        };
+    }
+    getEventsSnapshot(filters = {}) {
+        const limit = Math.max(1, Math.min(filters.limit ?? 100, EVENT_BUFFER_SIZE));
+        let source = this.events;
+        if (filters.commandId) {
+            source = source.filter((event) => event.commandId === filters.commandId);
+        }
+        return source.slice(-limit).reverse();
+    }
+    getTelemetrySummary(now = Date.now()) {
+        const failures = this.events.filter((event) => event.status === "failed" || event.status === "timeout");
+        const lastEvent = this.events.at(-1);
+        const lastFailure = failures.at(-1);
+        return {
+            eventsBuffered: this.events.length,
+            bridgeEventsBuffered: this.events.filter((event) => event.source === "bridge").length,
+            pluginEventsBuffered: this.events.filter((event) => event.source === "plugin").length,
+            failuresBuffered: failures.filter((event) => event.status === "failed").length,
+            timeoutsBuffered: failures.filter((event) => event.status === "timeout").length,
+            lastEventAt: lastEvent?.at ?? null,
+            lastEventAgeMs: lastEvent ? Math.max(0, now - lastEvent.at) : null,
+            lastFailureAt: lastFailure?.at ?? null,
+            lastFailureAgeMs: lastFailure ? Math.max(0, now - lastFailure.at) : null,
+            lastFailureCommandType: lastFailure?.commandType ?? null,
+            lastFailureMessage: lastFailure?.message ?? null,
+        };
+    }
     async execute(commandType, payload = {}) {
+        const commandId = randomUUID();
+        const safety = guardDestructiveCommand(commandType, payload);
+        if (!safety.ok) {
+            this.recordTelemetryEvent({
+                source: "bridge",
+                phase: "failed",
+                commandId,
+                commandType,
+                status: "failed",
+                durationMs: 0,
+                message: safety.error,
+                payloadKeys: Object.keys(payload ?? {}),
+                detailKeys: ["safety"],
+            });
+            return { commandId, status: "failed", error: safety.error };
+        }
+        payload = safety.payload;
         if (IMMEDIATE_COMMAND_TYPES.has(commandType)) {
             return this.executeImmediate(commandType, payload);
         }
-        const commandId = randomUUID();
         const timeout = BRIDGE_COMMAND_TIMEOUT_MS[commandType] ?? DEFAULT_TIMEOUT;
         return new Promise((resolve) => {
             const command = {
@@ -97,6 +174,7 @@ export class CommandQueue {
                 resolve,
             };
             this.queue.push(command);
+            this.recordCommandEvent(command, "queued");
             this.processNext();
             this.scheduleTimeout(command, timeout);
         });
@@ -111,6 +189,22 @@ export class CommandQueue {
      */
     async executeImmediate(commandType, payload) {
         const commandId = randomUUID();
+        const safety = guardDestructiveCommand(commandType, payload);
+        if (!safety.ok) {
+            this.recordTelemetryEvent({
+                source: "bridge",
+                phase: "failed",
+                commandId,
+                commandType,
+                status: "failed",
+                durationMs: 0,
+                message: safety.error,
+                payloadKeys: Object.keys(payload ?? {}),
+                detailKeys: ["safety"],
+            });
+            return { commandId, status: "failed", error: safety.error };
+        }
+        payload = safety.payload;
         const timeout = BRIDGE_COMMAND_TIMEOUT_MS[commandType] ?? DEFAULT_TIMEOUT;
         return new Promise((resolve) => {
             const command = {
@@ -122,9 +216,11 @@ export class CommandQueue {
                 startedAt: Date.now(),
                 resolve,
             };
+            this.recordCommandEvent(command, "started");
             if (!this.sendCommand) {
                 command.status = "failed";
                 command.completedAt = Date.now();
+                this.recordCommandEvent(command, "failed", { message: "No plugin connected" });
                 resolve({ commandId, status: "failed", error: "No plugin connected" });
                 return;
             }
@@ -136,6 +232,7 @@ export class CommandQueue {
             if (!sent) {
                 command.status = "failed";
                 command.completedAt = Date.now();
+                this.recordCommandEvent(command, "failed", { message: "Failed to send to plugin" });
                 resolve({ commandId, status: "failed", error: "Failed to send to plugin" });
                 return;
             }
@@ -149,6 +246,7 @@ export class CommandQueue {
                 command.status = "timeout";
                 command.completedAt = Date.now();
                 command.error = `Command "${command.commandType}" timed out after ${timeout}ms`;
+                this.recordCommandEvent(command, "timeout", { message: command.error });
                 command.resolve?.({
                     commandId: command.commandId,
                     status: "timeout",
@@ -176,6 +274,7 @@ export class CommandQueue {
         target.error = error;
         target.events = events;
         target.durationMs = durationMs;
+        this.recordCommandEvent(target, status, { message: error, detailKeys: eventDetailKeys(events) });
         target.resolve?.({
             commandId,
             status,
@@ -197,6 +296,8 @@ export class CommandQueue {
         for (const cmd of this.queue) {
             if (cmd.status === "pending") {
                 cmd.status = "cancelled";
+                cmd.completedAt = Date.now();
+                this.recordCommandEvent(cmd, "cancelled", { message: "Session disconnected" });
                 cmd.resolve?.({ commandId: cmd.commandId, status: "cancelled", error: "Session disconnected" });
             }
         }
@@ -204,12 +305,16 @@ export class CommandQueue {
         for (const cmd of this.immediate.values()) {
             if (cmd.status === "pending" || cmd.status === "running") {
                 cmd.status = "cancelled";
+                cmd.completedAt = Date.now();
+                this.recordCommandEvent(cmd, "cancelled", { message: "Session disconnected" });
                 cmd.resolve?.({ commandId: cmd.commandId, status: "cancelled", error: "Session disconnected" });
             }
         }
         this.immediate.clear();
         if (this.current && this.current.status === "running") {
             this.current.status = "cancelled";
+            this.current.completedAt = Date.now();
+            this.recordCommandEvent(this.current, "cancelled", { message: "Session disconnected" });
             this.current.resolve?.({ commandId: this.current.commandId, status: "cancelled", error: "Session disconnected" });
             this.current = null;
         }
@@ -229,6 +334,8 @@ export class CommandQueue {
         }
         if (!this.sendCommand) {
             next.status = "failed";
+            next.completedAt = Date.now();
+            this.recordCommandEvent(next, "failed", { message: "No plugin connected" });
             next.resolve?.({ commandId: next.commandId, status: "failed", error: "No plugin connected" });
             this.processNext();
             return;
@@ -240,6 +347,8 @@ export class CommandQueue {
         });
         if (!sent) {
             next.status = "failed";
+            next.completedAt = Date.now();
+            this.recordCommandEvent(next, "failed", { message: "Failed to send to plugin" });
             next.resolve?.({ commandId: next.commandId, status: "failed", error: "Failed to send to plugin" });
             this.processNext();
             return;
@@ -247,6 +356,40 @@ export class CommandQueue {
         next.status = "running";
         next.startedAt = Date.now();
         this.current = next;
+        this.recordCommandEvent(next, "started");
+    }
+    recordPluginEvent(raw) {
+        if (!raw || typeof raw !== "object") {
+            this.recordTelemetryEvent({
+                source: "plugin",
+                phase: "plugin-event",
+                commandId: null,
+                commandType: null,
+                status: null,
+                durationMs: null,
+                message: typeof raw === "string" ? raw : null,
+                payloadKeys: [],
+                detailKeys: [],
+            });
+            return;
+        }
+        const envelope = raw;
+        const event = isRecord(envelope.event) ? envelope.event : envelope;
+        this.recordTelemetryEvent({
+            source: "plugin",
+            phase: typeof event.phase === "string"
+                ? event.phase
+                : typeof event.type === "string"
+                    ? event.type
+                    : "plugin-event",
+            commandId: typeof event.commandId === "string" ? event.commandId : null,
+            commandType: typeof event.commandType === "string" ? event.commandType : null,
+            status: isCommandStatus(event.status) ? event.status : null,
+            durationMs: typeof event.durationMs === "number" ? event.durationMs : null,
+            message: typeof event.message === "string" ? event.message : null,
+            payloadKeys: [],
+            detailKeys: Object.keys(event).filter((key) => !["commandId", "commandType", "phase", "type", "status", "durationMs", "message"].includes(key)),
+        });
     }
     clearTimeout(commandId) {
         const handle = this.timeoutHandles.get(commandId);
@@ -261,5 +404,61 @@ export class CommandQueue {
         }
         this.timeoutHandles.clear();
     }
+    recordCommandEvent(command, phase, extras = {}) {
+        this.recordTelemetryEvent({
+            source: "bridge",
+            phase,
+            commandId: command.commandId,
+            commandType: command.commandType,
+            status: command.status,
+            durationMs: command.durationMs ?? (command.startedAt && command.completedAt ? command.completedAt - command.startedAt : null),
+            message: extras.message ?? command.error ?? null,
+            payloadKeys: Object.keys(command.payload ?? {}),
+            detailKeys: extras.detailKeys ?? [],
+        });
+    }
+    recordTelemetryEvent(event) {
+        this.events.push({
+            eventId: randomUUID(),
+            at: Date.now(),
+            ...event,
+        });
+        if (this.events.length > EVENT_BUFFER_SIZE) {
+            this.events.splice(0, this.events.length - EVENT_BUFFER_SIZE);
+        }
+    }
+}
+function snapshotCommand(command, now) {
+    return {
+        commandId: command.commandId,
+        commandType: command.commandType,
+        status: command.status,
+        createdAt: command.createdAt,
+        startedAt: command.startedAt ?? null,
+        completedAt: command.completedAt ?? null,
+        ageMs: Math.max(0, now - command.createdAt),
+        runningMs: command.startedAt ? Math.max(0, now - command.startedAt) : null,
+        payloadKeys: Object.keys(command.payload ?? {}),
+    };
+}
+function eventDetailKeys(events) {
+    if (!events || events.length === 0)
+        return [];
+    return events.flatMap((event, index) => {
+        if (!event || typeof event !== "object")
+            return [`events[${index}]`];
+        return Object.keys(event).map((key) => `events[${index}].${key}`);
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCommandStatus(value) {
+    return (value === "pending" ||
+        value === "running" ||
+        value === "completed" ||
+        value === "failed" ||
+        value === "timeout" ||
+        value === "cancelled");
 }
 //# sourceMappingURL=command-queue.js.map