@ttsalpha/mirra 1.2.0 → 1.3.0

package/README.md

@@ -65,11 +65,13 @@ skips all of it. The command is written with the real path of the Node binary th
 because a version manager puts `node` behind a path that changes with every shell and a
 GUI client never sees it.
 
-Then, by hand:
+It also registers the plugin with Figma Desktop by writing into Figma's own settings,
+which only works while Figma is **closed** — that file is rewritten from memory on quit.
+If Figma is running, or the format turns out to be one Mirra does not recognise, `init` says
+so and falls back to the manual route: Figma Desktop → Plugins → Development → Import plugin
+from manifest… → `~/.mirra/plugin/manifest.json`.
 
-1. Figma Desktop → Plugins → Development → Import plugin from manifest… →
-   `~/.mirra/plugin/manifest.json`
-2. **Restart the clients**, or they will not see the tools
+Either way, **restart the clients**, or they will not see the tools.
 
 And once per working session: open a file in Figma, run the Mirra plugin, leave its panel
 open. Figma has no background plugins, so closing the panel ends the connection.

package/dist/index.js

@@ -32732,6 +32732,13 @@ function claudeCode(node2, entryPoint) {
   };
 }
 
+// src/figma-settings.ts
+import { execFile } from "node:child_process";
+import { readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname2, join as join3, sep as sep2 } from "node:path";
+import { promisify } from "node:util";
+
 // src/install.ts
 import { spawn } from "node:child_process";
 import { access as access2, cp, mkdir, readFile as readFile2, rm } from "node:fs/promises";
@@ -32784,6 +32791,106 @@ function reveal(path) {
   spawn("open", ["-R", path], { stdio: "ignore", detached: true }).unref();
 }
 
+// src/figma-settings.ts
+var FIGMA_SETTINGS = settingsPath();
+function settingsPath() {
+  if (process.platform === "darwin") {
+    return join3(homedir3(), "Library/Application Support/Figma/settings.json");
+  }
+  if (process.platform === "win32") {
+    const local = process.env["LOCALAPPDATA"] ?? join3(homedir3(), "AppData/Local");
+    return join3(local, "Figma/settings.json");
+  }
+  return join3(homedir3(), ".config/Figma/settings.json");
+}
+var PLUGIN_ID = "mirra-figma-bridge";
+async function registerPluginWithFigma(pluginDir) {
+  if (await isFigmaRunning()) {
+    return { status: "skipped", reason: "Figma Desktop is running; quit it first" };
+  }
+  let raw;
+  try {
+    raw = await readFile3(FIGMA_SETTINGS, "utf8");
+  } catch {
+    return { status: "skipped", reason: `no settings file at ${FIGMA_SETTINGS}` };
+  }
+  try {
+    const settings = JSON.parse(raw);
+    const entries = settings["localFileExtensions"];
+    if (!Array.isArray(entries)) {
+      return { status: "skipped", reason: "unfamiliar settings format" };
+    }
+    const next = rebuild(entries, pluginDir);
+    if (!next) return { status: "already" };
+    settings["localFileExtensions"] = next;
+    const temporary = join3(dirname2(FIGMA_SETTINGS), `.mirra-${process.pid}.json`);
+    await writeFile2(temporary, JSON.stringify(settings, null, 2));
+    await rename2(temporary, FIGMA_SETTINGS);
+    return { status: "registered" };
+  } catch (error62) {
+    return { status: "skipped", reason: error62 instanceof Error ? error62.message : String(error62) };
+  }
+}
+function rebuild(entries, pluginDir) {
+  const mine = entries.filter((entry) => isMine(entry, entries));
+  if (isCleanTrio(mine, pluginDir)) return null;
+  const others = entries.filter((entry) => !mine.includes(entry));
+  return [...others, ...entriesFor(pluginDir, nextId(others))];
+}
+function isCleanTrio(mine, pluginDir) {
+  const manifest = mine.find((entry) => entry.fileMetadata.type === "manifest");
+  if (mine.length !== 3 || !manifest || manifest.fileMetadata.type !== "manifest") return false;
+  if (manifest.manifestPath !== join3(pluginDir, "manifest.json")) return false;
+  const { codeFileId, uiFileIds } = manifest.fileMetadata;
+  const paths = new Map(mine.map((entry) => [entry.id, entry.manifestPath]));
+  return paths.get(codeFileId) === join3(pluginDir, "main.js") && uiFileIds.length === 1 && paths.get(uiFileIds[0]) === join3(pluginDir, "ui.html");
+}
+function isMine(entry, all) {
+  if (entry.lastKnownPluginId === PLUGIN_ID) return true;
+  if (entry.manifestPath.startsWith(`${MIRRA_HOME}${sep2}`)) return true;
+  const metadata = entry.fileMetadata;
+  return metadata.type !== "manifest" && !all.some((e) => e.id === metadata.manifestFileId);
+}
+async function isFigmaRunning() {
+  const run = promisify(execFile);
+  try {
+    if (process.platform === "win32") {
+      const { stdout } = await run("tasklist", ["/fi", "imagename eq Figma.exe", "/nh"]);
+      return stdout.includes("Figma.exe");
+    }
+    await run("pgrep", ["-x", "Figma"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextId(entries) {
+  return entries.reduce((highest, entry) => Math.max(highest, entry.id), 0) + 1;
+}
+function entriesFor(pluginDir, first) {
+  const [manifestId, codeId, uiId] = [first, first + 1, first + 2];
+  return [
+    {
+      id: manifestId,
+      manifestPath: join3(pluginDir, "manifest.json"),
+      lastKnownName: "Mirra",
+      lastKnownPluginId: PLUGIN_ID,
+      cachedContainsWidget: false,
+      fileMetadata: { type: "manifest", codeFileId: codeId, uiFileIds: [uiId] }
+    },
+    {
+      id: codeId,
+      manifestPath: join3(pluginDir, "main.js"),
+      fileMetadata: { type: "code", manifestFileId: manifestId }
+    },
+    {
+      id: uiId,
+      manifestPath: join3(pluginDir, "ui.html"),
+      fileMetadata: { type: "ui", manifestFileId: manifestId }
+    }
+  ];
+}
+
 // ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -40821,7 +40928,20 @@ var EMPTY_COMPLETION_RESULT = {
 };
 
 // src/version.ts
-var SERVER_VERSION = "1.2.0";
+var SERVER_VERSION = "1.3.0";
+
+// src/tools/annotations.ts
+var READS = { readOnlyHint: true, openWorldHint: false };
+var ADDS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: false
+};
+var CHANGES = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
 
 // src/errors.ts
 var MirraError = class extends Error {
@@ -40853,7 +40973,12 @@ value keyed by mode name sets one value per mode. Both halves are optional.`;
 function registerDefine(server, bridge) {
   server.registerTool(
     "mirra_define_tokens",
-    { title: "Define Figma variables", description: DESCRIPTION, inputSchema: DefineParams.shape },
+    {
+      annotations: CHANGES,
+      title: "Define Figma variables",
+      description: DESCRIPTION,
+      inputSchema: DefineParams.shape
+    },
     async (params) => {
       try {
         const result = DefineResult.parse(await bridge.request("define", params));
@@ -40879,7 +41004,12 @@ The body is an async function receiving \`figma\`; use it only for what the type
 function registerExec(server, bridge) {
   server.registerTool(
     "mirra_exec",
-    { title: "Run Plugin API code", description: DESCRIPTION2, inputSchema: ExecParams.shape },
+    {
+      annotations: CHANGES,
+      title: "Run Plugin API code",
+      description: DESCRIPTION2,
+      inputSchema: ExecParams.shape
+    },
     async (params) => {
       try {
         const result = ExecResult.parse(await bridge.request("exec", params));
@@ -40892,11 +41022,11 @@ function registerExec(server, bridge) {
 }
 
 // src/tools/export.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, writeFile as writeFile3 } from "node:fs/promises";
 import { resolve as resolve3 } from "node:path";
 
 // src/tools/paths.ts
-import { resolve as resolve2, sep as sep2 } from "node:path";
+import { resolve as resolve2, sep as sep3 } from "node:path";
 function rootDirectory() {
   const configured = process.env["MIRRA_ROOT"];
   return configured ? resolve2(configured) : process.cwd();
@@ -40905,7 +41035,7 @@ function resolveInRoot(path) {
   const root = rootDirectory();
   const full = resolve2(root, path);
   if (!process.env["MIRRA_ROOT"]) return full;
-  if (full !== root && !full.startsWith(root + sep2)) {
+  if (full !== root && !full.startsWith(root + sep3)) {
     throw new MirraError(
       `${path} is outside MIRRA_ROOT`,
       "outside_root",
@@ -40922,6 +41052,7 @@ function registerExport(server, bridge) {
   server.registerTool(
     "mirra_export_assets",
     {
+      annotations: CHANGES,
       title: "Export Figma layers to files",
       description: DESCRIPTION3,
       inputSchema: ExportParams.shape
@@ -40934,7 +41065,7 @@ function registerExport(server, bridge) {
         const written = [];
         for (const asset2 of result.assets) {
           const file2 = resolve3(directory, `${slug(asset2.name)}.${asset2.extension}`);
-          await writeFile2(file2, Buffer.from(asset2.data, "base64"));
+          await writeFile3(file2, Buffer.from(asset2.data, "base64"));
           written.push(file2);
         }
         return text([`wrote ${written.length} file(s):`, ...written]);
@@ -40957,7 +41088,12 @@ tool works on the current page, so start here when the layer you want is elsewhe
 function registerFind(server, bridge) {
   server.registerTool(
     "mirra_find",
-    { title: "Find Figma layers", description: FIND, inputSchema: FindParams.shape },
+    {
+      annotations: READS,
+      title: "Find Figma layers",
+      description: FIND,
+      inputSchema: FindParams.shape
+    },
     async (params) => {
       try {
         const result = FindResult.parse(await bridge.request("find", params));
@@ -40975,7 +41111,13 @@ function registerFind(server, bridge) {
   );
   server.registerTool(
     "mirra_pages",
-    { title: "List or switch Figma pages", description: PAGES, inputSchema: PagesParams.shape },
+    {
+      // Not read-only: it can add a page and change which one is current.
+      annotations: ADDS,
+      title: "List, add or switch Figma pages",
+      description: PAGES,
+      inputSchema: PagesParams.shape
+    },
     async (params) => {
       try {
         const result = PagesResult.parse(await bridge.request("pages", params));
@@ -40990,7 +41132,7 @@ function registerFind(server, bridge) {
 }
 
 // src/tools/assets.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 import { extname } from "node:path";
 var MIME = /* @__PURE__ */ new Map([
   [".png", "image/png"],
@@ -41020,13 +41162,13 @@ function isPath(src) {
   return true;
 }
 async function readSvg(path) {
-  return readFile3(resolveInRoot(path), "utf8");
+  return readFile4(resolveInRoot(path), "utf8");
 }
 async function readImage(path) {
   const file2 = resolveInRoot(path);
   const type = MIME.get(extname(file2).toLowerCase());
   if (!type) throw new Error(`Unsupported image type: ${extname(file2) || file2}`);
-  return `data:${type};base64,${(await readFile3(file2)).toString("base64")}`;
+  return `data:${type};base64,${(await readFile4(file2)).toString("base64")}`;
 }
 
 // src/tools/patch.ts
@@ -41038,6 +41180,7 @@ function registerPatch(server, bridge) {
   server.registerTool(
     "mirra_patch",
     {
+      annotations: CHANGES,
       title: "Patch existing Figma layers",
       description: DESCRIPTION4,
       inputSchema: PatchParams.shape
@@ -41062,6 +41205,7 @@ function registerPing(server, bridge) {
   server.registerTool(
     "mirra_ping",
     {
+      annotations: READS,
       title: "Ping the Figma plugin",
       description: "Check that the Mirra plugin is connected, and report the open file, current page and selection size."
     },
@@ -41097,6 +41241,7 @@ function registerRead(server, bridge) {
   server.registerTool(
     "mirra_read",
     {
+      annotations: READS,
       title: "Read Figma layers as a UI tree",
       description: DESCRIPTION5,
       inputSchema: ReadParams.shape
@@ -41126,6 +41271,7 @@ function registerRender(server, bridge) {
   server.registerTool(
     "mirra_render",
     {
+      annotations: ADDS,
       title: "Render a UI tree into Figma",
       description: DESCRIPTION6,
       inputSchema: RenderParams.shape
@@ -41155,6 +41301,7 @@ function registerScreenshot(server, bridge) {
   server.registerTool(
     "mirra_screenshot",
     {
+      annotations: READS,
       title: "Screenshot a Figma layer",
       description: DESCRIPTION7,
       inputSchema: ScreenshotParams.shape
@@ -41166,7 +41313,7 @@ function registerScreenshot(server, bridge) {
           content: [
             {
               type: "text",
-              text: `${shot.name} (${shot.width}x${shot.height}, ${shot.id})`
+              text: `${shot.name} (${shot.width}x${shot.height}, ${shot.id})` + (shot.scale === 1 ? "" : ` at ${shot.scale.toFixed(2)}x`)
             },
             { type: "image", data: shot.png, mimeType: "image/png" }
           ]
@@ -41185,7 +41332,7 @@ bound to the design system instead of to a hardcoded value.`;
 function registerTokens(server, bridge) {
   server.registerTool(
     "mirra_tokens",
-    { title: "List design tokens", description: DESCRIPTION8 },
+    { annotations: READS, title: "List design tokens", description: DESCRIPTION8 },
     async () => {
       try {
         const result = TokensResult.parse(await bridge.request("tokens"));
@@ -41422,7 +41569,7 @@ var USAGE = `mirra <command>
   doctor   Bind the plugin port and wait for the Figma plugin to connect
 
 Flags:
-  --no-reveal   init: do not open the folder in Finder
+  --no-reveal   init: do not open the folder in Finder on a manual import
   --no-config   init: do not touch any client's configuration
 
 Environment:
@@ -41478,14 +41625,26 @@ async function init() {
     }
     lines.push("", "A client that was already running has to be restarted to see the tools.", "");
   }
-  lines.push(
-    "Then, in Figma Desktop:",
-    "  1. Plugins -> Development -> Import plugin from manifest...",
-    `     and choose ${manifest}`,
-    "  2. Open a file, run Mirra, and leave the panel open",
-    "  3. Ask the agent for mirra_ping; the panel badge should turn green"
-  );
-  if (!process.argv.includes("--no-reveal")) reveal(manifest);
+  const figma = await registerPluginWithFigma(PLUGIN_HOME);
+  const manual = figma.status === "skipped";
+  if (manual) {
+    lines.push(
+      `Could not register the plugin with Figma Desktop: ${figma.reason}`,
+      "Then, in Figma Desktop:",
+      "  1. Plugins -> Development -> Import plugin from manifest...",
+      `     and choose ${manifest}`,
+      "  2. Open a file, run Mirra, and leave the panel open",
+      "  3. Ask the agent for mirra_ping; the panel badge should turn green"
+    );
+  } else {
+    lines.push(
+      figma.status === "registered" ? "Registered the plugin with Figma Desktop." : "Figma Desktop already knows the plugin.",
+      "Then, in Figma Desktop:",
+      "  1. Open a file, run Plugins -> Development -> Mirra, and leave the panel open",
+      "  2. Ask the agent for mirra_ping; the panel badge should turn green"
+    );
+  }
+  if (manual && !process.argv.includes("--no-reveal")) reveal(manifest);
   console.log(lines.join("\n"));
 }
 async function doctor() {

package/dist/plugin/main.js

@@ -950,7 +950,7 @@
   }
 
   // src/version.ts
-  var PLUGIN_VERSION = "1.2.0";
+  var PLUGIN_VERSION = "1.3.0";
 
   // src/ops/ping.ts
   function ping() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsalpha/mirra",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Two-way MCP server for Figma: read a design and render one back through the Figma Plugin API",
   "keywords": [
     "figma",