faux-studio 0.3.12 → 0.4.0

package/README.md

@@ -67,6 +67,27 @@ faux-studio runs locally and bridges your AI client to Figma Desktop:
 - Setup guide: [faux.design/docs/setup](https://faux.design/docs/setup)
 - Issues: [github.com/uxfreak/faux-studio/issues](https://github.com/uxfreak/faux-studio/issues)
 
+## Publishing a New Version
+
+To publish a new version to npm:
+
+1. Bump the version in `package.json`:
+   ```bash
+   npm version patch   # 0.4.0 → 0.4.1
+   npm version minor   # 0.4.0 → 0.5.0
+   npm version major   # 0.4.0 → 1.0.0
+   ```
+   This updates `package.json` and creates a git commit + tag automatically.
+
+2. Push the commit and tag:
+   ```bash
+   git push && git push --tags
+   ```
+
+3. The [publish workflow](.github/workflows/publish.yml) will build and publish to npm automatically on any `v*` tag push.
+
+> **Note:** Ensure the `NPM_TOKEN` secret is configured in the repo's GitHub Settings → Secrets and variables → Actions.
+
 ## License
 
 MIT

package/dist/index.js

@@ -10451,7 +10451,7 @@ function error(message) {
 // src/auth.ts
 var FAUX_DIR = join(homedir(), ".faux");
 var CREDENTIALS_PATH = join(FAUX_DIR, "credentials.json");
-var AUTH_BASE = "https://auth.faux.design";
+var AUTH_BASE = process.env.FAUX_AUTH_URL || "https://auth.faux.design";
 var POLL_INTERVAL_MS = 2e3;
 var POLL_TIMEOUT_MS = 5 * 60 * 1e3;
 var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
@@ -10630,7 +10630,7 @@ import { join as join2 } from "path";
 import { homedir as homedir2 } from "os";
 var FAUX_DIR2 = join2(homedir2(), ".faux");
 var CACHE_PATH = join2(FAUX_DIR2, "tool-cache.json");
-var API_BASE = "https://mcp.faux.design";
+var API_BASE = process.env.FAUX_API_URL || "https://api.faux.design";
 async function loadCachedTools() {
   try {
     const raw = await readFile2(CACHE_PATH, "utf-8");
@@ -10756,10 +10756,12 @@ var CdpClient = class {
   pending = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
   figmaContextId = null;
+  _targetWsUrl = null;
   // -------------------------------------------------------------------------
   // Connection
   // -------------------------------------------------------------------------
   async connect(wsUrl) {
+    this._targetWsUrl = wsUrl;
     return new Promise((resolve, reject) => {
       const ws = new wrapper_default(wsUrl);
       const timeout = setTimeout(() => {
@@ -10865,7 +10867,7 @@ var CdpClient = class {
     this.on("Runtime.executionContextCreated", handler);
     try {
       await this.send("Runtime.enable");
-      await new Promise((r) => setTimeout(r, 500));
+      await new Promise((r) => setTimeout(r, 150));
     } finally {
       this.off("Runtime.executionContextCreated", handler);
     }
@@ -10928,6 +10930,15 @@ ${script}
 })()`);
   }
   // -------------------------------------------------------------------------
+  // Reconnection
+  // -------------------------------------------------------------------------
+  /** Close current connection and reconnect to a different CDP target. */
+  async reconnectToTarget(wsUrl) {
+    this.close();
+    await this.connect(wsUrl);
+    await this.discoverFigmaContext();
+  }
+  // -------------------------------------------------------------------------
   // State
   // -------------------------------------------------------------------------
   get connected() {
@@ -10936,6 +10947,10 @@ ${script}
   get hasContext() {
     return this.figmaContextId !== null;
   }
+  /** The WebSocket URL this client is currently connected to. */
+  get targetWsUrl() {
+    return this._targetWsUrl;
+  }
   resetContext() {
     this.figmaContextId = null;
   }
@@ -10946,6 +10961,7 @@ ${script}
     this.ws?.close();
     this.ws = null;
     this.figmaContextId = null;
+    this._targetWsUrl = null;
   }
 };
 
@@ -11057,10 +11073,20 @@ async function listTargets(port) {
   if (!res.ok) throw new Error(`Failed to list CDP targets (HTTP ${res.status})`);
   return await res.json();
 }
-var FIGMA_DESIGN_URL_RE = /figma\.com\/(file|design)\//;
+var FIGMA_DESIGN_URL_RE = /figma\.com\/(file|design)\/([a-zA-Z0-9]+)/;
 function findFigmaDesignTarget(targets) {
   return targets.find((t) => t.type === "page" && FIGMA_DESIGN_URL_RE.test(t.url)) || targets.find((t) => t.type === "page") || null;
 }
+function findShellTarget(targets) {
+  return targets.find((t) => t.type === "page" && t.url?.includes("shell.html")) || null;
+}
+function listDesignTargets(targets) {
+  return targets.filter((t) => t.type === "page" && FIGMA_DESIGN_URL_RE.test(t.url)).map((t) => {
+    const fileKey = t.url.match(FIGMA_DESIGN_URL_RE)[2];
+    const fileName = t.title.replace(/\s[–—-]\s*Figma\s*$/u, "").trim();
+    return { ...t, fileKey, fileName };
+  });
+}
 async function probeCdpPorts() {
   for (const port of KNOWN_CDP_PORTS) {
     const { alive, isFigma } = await isCdpAlive(port);
@@ -11438,6 +11464,229 @@ var PluginWsServer = class {
   }
 };
 
+// src/file-tracker.ts
+var FileChangedError = class extends Error {
+  previousFileName;
+  currentFileName;
+  currentFileKey;
+  allFiles;
+  constructor(previousFileName, currentFileName, currentFileKey, allFiles) {
+    super(`Active Figma file changed from "${previousFileName}" to "${currentFileName}".`);
+    this.name = "FileChangedError";
+    this.previousFileName = previousFileName;
+    this.currentFileName = currentFileName;
+    this.currentFileKey = currentFileKey;
+    this.allFiles = allFiles;
+  }
+};
+var FileUnknownError = class extends Error {
+  allFiles;
+  constructor(allFiles) {
+    super("Cannot detect which Figma file is active. Please confirm the target file.");
+    this.name = "FileUnknownError";
+    this.allFiles = allFiles;
+  }
+};
+var LAST_KNOWN_STALE_MS = 5 * 6e4;
+var SHELL_DETECT_TIMEOUT_MS = 500;
+var CdpFileTracker = class {
+  cdpPort;
+  shellWsUrl = null;
+  _activeFileKey = null;
+  _lastKnownFileKey = null;
+  _lastKnownFileName = null;
+  _lastAcknowledgedAt = 0;
+  _files = /* @__PURE__ */ new Map();
+  _lastDetectTime = 0;
+  _cachedResult = null;
+  constructor(cdpPort) {
+    this.cdpPort = cdpPort;
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Detect the currently active file. Uses cached result if fresh.
+   * @param cacheTtlMs How long to trust cached results (0 = always re-detect).
+   */
+  async detectActiveFile(cacheTtlMs = 2e3) {
+    if (this._cachedResult && cacheTtlMs > 0 && Date.now() - this._lastDetectTime < cacheTtlMs) {
+      return this._cachedResult;
+    }
+    const result = await this.detect();
+    this._cachedResult = result;
+    this._lastDetectTime = Date.now();
+    if (result.activeFile) {
+      this._activeFileKey = result.activeFile.fileKey;
+    }
+    return result;
+  }
+  /** List all open design files from /json/list. */
+  async listOpenFiles() {
+    try {
+      const targets = await listTargets(this.cdpPort);
+      return this.parseDesignTargets(targets);
+    } catch {
+      return Array.from(this._files.values());
+    }
+  }
+  /** Get cached file info by fileKey. */
+  getFileTarget(fileKey) {
+    return this._files.get(fileKey) || null;
+  }
+  /** Whether the detected active file differs from the last acknowledged file. */
+  hasFileChanged() {
+    return this._activeFileKey !== null && this._lastKnownFileKey !== null && this._activeFileKey !== this._lastKnownFileKey;
+  }
+  /**
+   * Acknowledge the current active file as the intended target.
+   * Call AFTER successful execution (AR-3).
+   */
+  acknowledgeActiveFile() {
+    if (this._activeFileKey) {
+      this._lastKnownFileKey = this._activeFileKey;
+      this._lastKnownFileName = this._files.get(this._activeFileKey)?.fileName ?? null;
+      this._lastAcknowledgedAt = Date.now();
+    }
+  }
+  get activeFileKey() {
+    return this._activeFileKey;
+  }
+  get lastKnownFileKey() {
+    return this._lastKnownFileKey;
+  }
+  get lastKnownFileName() {
+    return this._lastKnownFileName;
+  }
+  get activeFileName() {
+    return this._activeFileKey ? this._files.get(this._activeFileKey)?.fileName ?? null : null;
+  }
+  // -------------------------------------------------------------------------
+  // Private: Core Detection
+  // -------------------------------------------------------------------------
+  async detect() {
+    let targets;
+    try {
+      targets = await listTargets(this.cdpPort);
+      if (!Array.isArray(targets)) targets = [];
+    } catch {
+      return this.fallbackToLastKnown([]);
+    }
+    const designFiles = this.parseDesignTargets(targets);
+    this._files.clear();
+    for (const f of designFiles) {
+      this._files.set(f.fileKey, f);
+    }
+    if (designFiles.length === 0) {
+      return { activeFile: null, allFiles: [], method: "none", confidence: "none" };
+    }
+    if (designFiles.length === 1) {
+      this._activeFileKey = designFiles[0].fileKey;
+      return { activeFile: designFiles[0], allFiles: designFiles, method: "single-file", confidence: "high" };
+    }
+    const shellTabName = await this.detectViaShellTabBar(targets);
+    if (shellTabName) {
+      const matched = this.matchTabNameToFile(shellTabName, designFiles);
+      if (matched) {
+        this._activeFileKey = matched.fileKey;
+        log(`File tracker: active file "${matched.fileName}" (${matched.fileKey}) via shell tab bar`);
+        return { activeFile: matched, allFiles: designFiles, method: "shell-tab-bar", confidence: "high" };
+      }
+    }
+    return this.fallbackToLastKnown(designFiles);
+  }
+  // -------------------------------------------------------------------------
+  // Private: Shell.html Tab Bar Detection (PRIMARY)
+  // -------------------------------------------------------------------------
+  /**
+   * Read the active tab name from Figma's shell.html tab bar.
+   * Security: uses a fixed literal expression — never interpolate user input (SR-1).
+   */
+  async detectViaShellTabBar(targets) {
+    if (!this.shellWsUrl) {
+      const shell = findShellTarget(targets);
+      if (!shell?.webSocketDebuggerUrl) return null;
+      if (!shell.webSocketDebuggerUrl.startsWith("ws://127.0.0.1:")) return null;
+      this.shellWsUrl = shell.webSocketDebuggerUrl;
+    }
+    const client = new CdpClient();
+    try {
+      const connectPromise = client.connect(this.shellWsUrl);
+      const timeoutPromise = new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("shell detect timeout")), SHELL_DETECT_TIMEOUT_MS)
+      );
+      await Promise.race([connectPromise, timeoutPromise]);
+      const result = await client.send("Runtime.evaluate", {
+        expression: `document.querySelector('[role="tab"][aria-selected="true"]')?.getAttribute('aria-label')`,
+        returnByValue: true
+      });
+      const raw = result?.result?.value;
+      return this.parseTabNameFromCdpResult(raw);
+    } catch {
+      this.shellWsUrl = null;
+      return null;
+    } finally {
+      client.close();
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private: Fallback — Last Known
+  // -------------------------------------------------------------------------
+  fallbackToLastKnown(designFiles) {
+    if (this._lastKnownFileKey && !this.isLastKnownStale()) {
+      const existing = designFiles.find((f) => f.fileKey === this._lastKnownFileKey);
+      if (existing) {
+        this._activeFileKey = existing.fileKey;
+        log(`File tracker: using last-known file "${existing.fileName}" (low confidence)`);
+        return { activeFile: existing, allFiles: designFiles, method: "last-known", confidence: "low" };
+      }
+    }
+    log("File tracker: cannot detect active file \u2014 shell detection failed and last-known is stale or missing");
+    return { activeFile: null, allFiles: designFiles, method: "none", confidence: "none" };
+  }
+  /** True if the last acknowledged execution was more than 5 minutes ago. */
+  isLastKnownStale() {
+    if (this._lastAcknowledgedAt === 0) return false;
+    return Date.now() - this._lastAcknowledgedAt > LAST_KNOWN_STALE_MS;
+  }
+  // -------------------------------------------------------------------------
+  // Private: Matching & Validation
+  // -------------------------------------------------------------------------
+  /**
+   * Match a tab name from shell.html against design file targets.
+   * Returns null if ambiguous (multiple files with same name) — AR-9.
+   */
+  matchTabNameToFile(tabName, designFiles) {
+    const matches = designFiles.filter((f) => f.fileName === tabName);
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      warn(`File tracker: ${matches.length} files named "${tabName}" \u2014 cannot disambiguate`);
+      return null;
+    }
+    return null;
+  }
+  /**
+   * Validate and clean the CDP result from shell.html evaluation (SR-3).
+   * Rejects non-string, empty, oversized, or control-character values.
+   */
+  parseTabNameFromCdpResult(raw) {
+    if (typeof raw !== "string") return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || trimmed.length > 512) return null;
+    if (/[\x00-\x1f\x7f]/.test(trimmed)) return null;
+    return trimmed;
+  }
+  /** Parse design targets from /json/list into FigmaFileInfo[]. */
+  parseDesignTargets(targets) {
+    return listDesignTargets(targets).map((t) => ({
+      fileKey: t.fileKey,
+      fileName: t.fileName,
+      targetId: t.id,
+      wsUrl: t.webSocketDebuggerUrl
+    }));
+  }
+};
+
 // node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -25585,7 +25834,7 @@ function createMcpServer(deps) {
       },
       {
         name: "setup_figma",
-        description: "Ensure Figma Desktop is running and the plugin is connected. Call this before any design work. Launches Figma if needed, waits for the plugin to connect, and provides setup guidance. Idempotent \u2014 safe to call multiple times. Returns connection status and active file info.",
+        description: "Ensure Figma Desktop is running and connected. Call this before any design work. Launches Figma if needed, detects open files and the active tab, and provides setup guidance. Returns connection status, active file, and list of all open design files. Idempotent \u2014 safe to call multiple times.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -25675,7 +25924,10 @@ function createMcpServer(deps) {
         macro: typeof params._intent_macro === "string" ? params._intent_macro : void 0
       };
       const script = await deps.generateScript(name, params);
-      const result = await deps.executeScript(script, intents);
+      const annotation = TOOL_ANNOTATIONS[name];
+      const isReadOnly = annotation?.readOnlyHint === true;
+      const cacheTtlMs = isReadOnly ? 2e3 : 0;
+      const result = await deps.executeScript(script, intents, { cacheTtlMs });
       const imageData = extractImageData(result);
       if (imageData) {
         const content = [
@@ -25691,6 +25943,37 @@ function createMcpServer(deps) {
         content: [{ type: "text", text }]
       };
     } catch (err) {
+      if (err instanceof FileChangedError) {
+        const annotation = TOOL_ANNOTATIONS[name];
+        const isReadOnly = annotation?.readOnlyHint === true;
+        const payload = JSON.stringify({
+          status: "confirmation_required",
+          reason: "ACTIVE_FILE_CHANGED",
+          previousFile: err.previousFileName,
+          currentFile: err.currentFileName,
+          currentFileKey: err.currentFileKey,
+          message: `The active Figma file changed from "${err.previousFileName}" to "${err.currentFileName}". Please confirm which file you want to work on.`,
+          availableFiles: err.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+        }, null, 2);
+        if (isReadOnly) {
+          return { content: [{ type: "text", text: payload }] };
+        }
+        return { content: [{ type: "text", text: payload }], isError: true };
+      }
+      if (err instanceof FileUnknownError) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "confirmation_required",
+              reason: "ACTIVE_FILE_UNKNOWN",
+              message: "Cannot detect which Figma file is active. Please confirm the target file.",
+              availableFiles: err.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+            }, null, 2)
+          }],
+          isError: true
+        };
+      }
       const message = err instanceof Error ? err.message : String(err);
       const isAuthError = message.includes("auth") || message.includes("401") || message.includes("AUTH_EXPIRED");
       return {
@@ -25740,6 +26023,7 @@ async function startServer(server2) {
 // src/index.ts
 var auth;
 var cdpClient = null;
+var fileTracker = null;
 var pluginServer = new PluginWsServer();
 var forceTransport = process.env.FAUX_TRANSPORT;
 async function tryConnectCdp() {
@@ -25747,20 +26031,23 @@ async function tryConnectCdp() {
     if (cdpClient?.connected && cdpClient.hasContext) return cdpClient;
     cdpClient?.close();
     cdpClient = null;
-    const { targets } = await ensureFigma();
-    const target = findFigmaDesignTarget(targets);
+    const connection = await ensureFigma();
+    const target = findFigmaDesignTarget(connection.targets);
     if (!target) return null;
     const client = new CdpClient();
     await client.connect(target.webSocketDebuggerUrl);
     await client.discoverFigmaContext();
     log(`CDP connected: ${target.title}`);
     cdpClient = client;
+    if (!fileTracker) {
+      fileTracker = new CdpFileTracker(connection.port);
+    }
     return client;
   } catch {
     return null;
   }
 }
-async function executeScript(script, intents) {
+async function executeScript(script, intents, opts) {
   if (forceTransport !== "cdp" && pluginServer.hasConnections) {
     log(`Executing via plugin (file: ${pluginServer.activeFileId || "active"})`);
     return pluginServer.executeScript(script, void 0, intents);
@@ -25768,12 +26055,34 @@ async function executeScript(script, intents) {
   if (forceTransport !== "plugin") {
     const client = await tryConnectCdp();
     if (client) {
+      if (fileTracker) {
+        const detection = await fileTracker.detectActiveFile(opts?.cacheTtlMs);
+        if (!detection.activeFile && detection.allFiles.length > 1) {
+          throw new FileUnknownError(detection.allFiles);
+        }
+        if (fileTracker.hasFileChanged()) {
+          throw new FileChangedError(
+            fileTracker.lastKnownFileName,
+            fileTracker.activeFileName,
+            fileTracker.activeFileKey,
+            detection.allFiles
+          );
+        }
+        if (detection.activeFile && client.targetWsUrl !== detection.activeFile.wsUrl) {
+          log(`Switching CDP target to "${detection.activeFile.fileName}" (${detection.activeFile.fileKey})`);
+          await client.reconnectToTarget(detection.activeFile.wsUrl);
+        }
+      }
       log("Executing via CDP");
       try {
-        return await client.executeScript(script);
+        const result = await client.executeScript(script);
+        fileTracker?.acknowledgeActiveFile();
+        return result;
       } catch (err) {
         if (err instanceof ContextDestroyedError) {
-          return await recoverCdp(client, script);
+          const result = await recoverCdp(client, script);
+          fileTracker?.acknowledgeActiveFile();
+          return result;
         }
         throw err;
       }
@@ -25841,6 +26150,16 @@ async function setupFigma(params) {
     return pluginReadyResult();
   }
   if (forceTransport !== "plugin" && cdpClient?.connected && cdpClient.hasContext) {
+    if (fileTracker) {
+      const detection = await fileTracker.detectActiveFile();
+      return {
+        status: "ready",
+        transport: "cdp",
+        message: `Connected via CDP. Active file: "${detection.activeFile?.fileName ?? "unknown"}". ${detection.allFiles.length} file(s) open. Ready to design.`,
+        activeFile: detection.activeFile?.fileName,
+        openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+      };
+    }
     return {
       status: "ready",
       transport: "cdp",
@@ -25860,11 +26179,17 @@ async function setupFigma(params) {
           await client.discoverFigmaContext();
           cdpClient = client;
           log(`CDP connected: ${target.title}`);
+          if (!fileTracker) {
+            fileTracker = new CdpFileTracker(existing.port);
+          }
+          const detection = await fileTracker.detectActiveFile();
+          fileTracker.acknowledgeActiveFile();
           return {
             status: "ready",
             transport: "cdp",
-            message: `Connected via CDP. Active file: ${target.title}. Ready to design.`,
-            activeFile: target.title,
+            message: `Connected via CDP. Active file: "${detection.activeFile?.fileName ?? target.title}". ${detection.allFiles.length} file(s) open. Ready to design.`,
+            activeFile: detection.activeFile?.fileName ?? target.title,
+            openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName })),
             port: existing.port
           };
         } catch {
@@ -26000,10 +26325,31 @@ async function main() {
 function shutdown() {
   pluginServer.close();
   cdpClient?.close();
+  fileTracker = null;
   process.exit(0);
 }
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
+var ORPHAN_CHECK_MS = 5e3;
+var originalPpid = process.ppid;
+function isParentAlive() {
+  try {
+    process.kill(originalPpid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+process.stdin.on("end", () => {
+  log("stdin closed \u2014 parent process gone, shutting down");
+  shutdown();
+});
+setInterval(() => {
+  if (!isParentAlive()) {
+    log(`Parent process (PID ${originalPpid}) gone \u2014 shutting down`);
+    shutdown();
+  }
+}, ORPHAN_CHECK_MS).unref();
 main().catch((err) => {
   error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faux-studio",
-  "version": "0.3.12",
+  "version": "0.4.0",
   "description": "AI-powered Figma design via MCP — connect any AI client to Figma Desktop",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "build:staging": "tsup --env.FAUX_API_URL https://staging-api.faux.design --env.FAUX_AUTH_URL https://staging-auth.faux.design",
     "build:plugin": "cd plugin && npm run build",
     "build:all": "npm run build && npm run build:plugin",
     "dev": "tsup --watch",