framer-dalton 0.0.12 → 0.0.14

package/dist/cli.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.12 */
+/* @framer/ai CLI v0.0.14 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function openUrl(url) {
@@ -134,11 +134,10 @@ function extractProjectId(input) {
   if (/^[a-zA-Z0-9]+$/.test(input)) {
     return input;
   }
-  const match = input.match(/\/projects\/[^/]+--([a-zA-Z0-9]+)/);
-  if (match) {
-    return match[1];
-  }
-  const slugMatch = input.match(/^(?:.+--)?([a-zA-Z0-9]+)(?:-[a-zA-Z0-9]+)?$/);
+  const candidate = input.match(/\/projects\/([^/?#]+)/)?.[1] ?? input;
+  const slugMatch = candidate.match(
+    /^(?:.+--)?([a-zA-Z0-9]+)(?:-[a-zA-Z0-9]+)?$/
+  );
   if (slugMatch) {
     return slugMatch[1];
   }
@@ -181,6 +180,19 @@ function clearApiKey(projectId) {
 }
 __name(clearApiKey, "clearApiKey");
 
+// src/debug.ts
+var enabled = false;
+function setDebugEnabled(value) {
+  enabled = value;
+}
+__name(setDebugEnabled, "setDebugEnabled");
+function debug(tag, message) {
+  if (!enabled) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  console.error(`[debug ${timestamp}] ${tag}: ${message}`);
+}
+__name(debug, "debug");
+
 // src/utils.ts
 function formatError(error) {
   if (error instanceof Error) {
@@ -313,20 +325,32 @@ __name(parseCode, "parseCode");
 async function acquireKeyFromBrowser(projectId) {
   const state = crypto.randomBytes(16).toString("hex");
   return new Promise((resolve, reject) => {
-    let pendingResult = null;
+    let settled = false;
+    let pendingApiKey = null;
+    function settle(fn) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn();
+    }
+    __name(settle, "settle");
     const server = http.createServer((req, res) => {
       const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+      debug("auth", `request: ${url.pathname}`);
       if (url.pathname === "/done") {
         const theme2 = parseTheme(url.searchParams.get("theme"));
         res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(successHtml(theme2));
-        if (pendingResult) {
-          const { apiKey: apiKey2 } = pendingResult;
-          pendingResult = null;
-          cleanup();
-          print("\u2713 Agent authorized");
-          resolve(apiKey2);
-        }
+        res.end(successHtml(theme2), () => {
+          if (pendingApiKey) {
+            const apiKey2 = pendingApiKey;
+            pendingApiKey = null;
+            settle(() => {
+              debug("auth", "received API key via /done, resolving");
+              print("\u2713 Agent authorized");
+              resolve(apiKey2);
+            });
+          }
+        });
         return;
       }
       if (url.pathname === "/error") {
@@ -346,9 +370,9 @@ async function acquireKeyFromBrowser(projectId) {
       const code = parseCode(url.searchParams.get("code")) ?? legacyCode;
       if (code !== null) {
         res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(codeHtml(code, theme));
-        cleanup();
-        reject(new Error(codeMessages[code]));
+        res.end(codeHtml(code, theme), () => {
+          settle(() => reject(new Error(codeMessages[code])));
+        });
         return;
       }
       const apiKey = url.searchParams.get("apiKey");
@@ -358,7 +382,8 @@ async function acquireKeyFromBrowser(projectId) {
         res.end();
         return;
       }
-      pendingResult = { apiKey, theme };
+      debug("auth", "received valid callback, redirecting to /done");
+      pendingApiKey = apiKey;
       res.writeHead(302, { Location: `/done?theme=${theme}` });
       res.end();
     });
@@ -366,9 +391,11 @@ async function acquireKeyFromBrowser(projectId) {
     const pollTimer = setInterval(() => {
       const apiKey = getApiKey(projectId);
       if (apiKey) {
-        cleanup();
-        print("\u2713 API key detected from config");
-        resolve(apiKey);
+        settle(() => {
+          debug("auth", "API key detected from config file poll");
+          print("\u2713 API key detected from config");
+          resolve(apiKey);
+        });
       }
     }, POLL_INTERVAL_MS);
     const HINT_MS = 55e3;
@@ -385,40 +412,52 @@ async function acquireKeyFromBrowser(projectId) {
       print("Waiting for authorization in browser...");
     }, HINT_MS);
     const timer = setTimeout(() => {
-      cleanup();
-      reject(
-        new Error(
-          "Browser authorization timed out. Use `framer project auth <projectUrlOrId> <apiKey>` instead."
+      settle(
+        () => reject(
+          new Error(
+            "Browser authorization timed out. Use `framer project auth <projectUrlOrId> <apiKey>` instead."
+          )
         )
       );
     }, TIMEOUT_MS);
+    let cleaned = false;
     function cleanup() {
+      if (cleaned) return;
+      cleaned = true;
+      debug("auth", "cleanup: clearing timers and closing server");
       clearTimeout(timer);
       clearTimeout(hintTimer);
       clearInterval(pollTimer);
       server.close();
+      server.closeAllConnections();
     }
     __name(cleanup, "cleanup");
-    server.listen(0, "127.0.0.1", async () => {
+    server.keepAliveTimeout = 0;
+    server.unref();
+    debug("auth", "starting callback server...");
+    server.listen(0, "127.0.0.1", () => {
       const addr = server.address();
       if (!addr || typeof addr === "string") {
-        cleanup();
-        reject(new Error("Failed to start callback server."));
+        settle(() => reject(new Error("Failed to start callback server.")));
         return;
       }
+      debug("auth", `callback server listening on port ${addr.port}`);
       const callbackUrl = `http://127.0.0.1:${addr.port}/callback`;
       const deeplink = new URL("https://framer.com/projects/server-api/auth");
       deeplink.searchParams.set("callback", callbackUrl);
       deeplink.searchParams.set("state", state);
       deeplink.searchParams.set("projectId", projectId);
       const deeplinkStr = deeplink.toString();
-      const opened = await openUrl(deeplinkStr);
-      if (opened) {
-        print("Waiting for authorization in browser...");
-      } else {
-        printError("Could not open browser. Open this URL manually:");
-        printError(deeplinkStr);
-      }
+      debug("auth", "opening browser for deeplink...");
+      openUrl(deeplinkStr).then((opened) => {
+        if (opened) {
+          debug("auth", "browser opened successfully");
+          print("Waiting for authorization in browser...");
+        } else {
+          printError("Could not open browser. Open this URL manually:");
+          printError(deeplinkStr);
+        }
+      });
     });
   });
 }
@@ -6612,6 +6651,18 @@ var types = {
         description: "",
         optional: false
       },
+      {
+        name: "[getCurrentUserMessageType]",
+        type: "() => Promise<User>",
+        description: "",
+        optional: false
+      },
+      {
+        name: "[getProjectInfoMessageType]",
+        type: "() => Promise<ProjectInfo>",
+        description: "",
+        optional: false
+      },
       {
         name: "[getHTMLForNodeMessageType]",
         type: "(nodeId: NodeId) => Promise<string | null>",
@@ -14927,9 +14978,16 @@ ${typeDef}`);
   return { lines, errors };
 }
 __name(renderDocs, "renderDocs");
+
+// src/version.ts
+var VERSION = (
+  // typeof is used to ensure this can be used just via tsx or node etc. without build
+  "0.0.14" 
+);
+
+// src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path4.dirname(__filename$1);
-var VERSION = "0.0.12" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 var client = createTRPCClient({
   links: [
@@ -14967,11 +15025,15 @@ function compareVersions(v1, v2) {
 __name(compareVersions, "compareVersions");
 async function ensureRelayServerRunning(options = {}) {
   const { logger, restartOnVersionMismatch = true } = options;
+  debug("relay", `checking server version (client=${VERSION})...`);
   const serverVersion = await getRelayServerVersion();
+  debug("relay", `server version=${serverVersion ?? "not running"}`);
   if (serverVersion === VERSION) {
+    debug("relay", "version matches, no action needed");
     return;
   }
   if (serverVersion !== null && compareVersions(serverVersion, VERSION) > 0) {
+    debug("relay", "server version is newer, keeping it");
     return;
   }
   if (serverVersion !== null) {
@@ -14979,11 +15041,13 @@ async function ensureRelayServerRunning(options = {}) {
       logger?.log(
         `Relay server version mismatch (server: ${serverVersion}, client: ${VERSION}), restarting...`
       );
+      debug("relay", "shutting down old server...");
       try {
         await client.shutdown.mutate();
         await sleep(500);
       } catch {
       }
+      debug("relay", "old server shut down");
     } else {
       return;
     }
@@ -14992,6 +15056,7 @@ async function ensureRelayServerRunning(options = {}) {
   }
   const isRunningFromSource = __filename$1.endsWith(".ts");
   const scriptPath = isRunningFromSource ? path4.resolve(__dirname$1, "./start-relay-server.ts") : path4.resolve(__dirname$1, "./start-relay-server.js");
+  debug("relay", `spawning server process: ${scriptPath}`);
   const serverProcess = spawn(
     isRunningFromSource ? "tsx" : process.execPath,
     [scriptPath],
@@ -15002,9 +15067,13 @@ async function ensureRelayServerRunning(options = {}) {
     }
   );
   serverProcess.unref();
-  for (let i = 0; i < 10; i++) {
+  for (let attempt = 0; attempt < 10; attempt++) {
     await sleep(500);
     const newVersion = await getRelayServerVersion();
+    debug(
+      "relay",
+      `readiness poll ${attempt + 1}/10: version=${newVersion ?? "not ready"}`
+    );
     if (newVersion) {
       logger?.log("Relay server started successfully");
       return;
@@ -15138,7 +15207,12 @@ __name(installSkills, "installSkills");
 
 // src/cli.ts
 var program = new Command();
-program.name("framer").version(VERSION).description("Framer Server API CLI");
+program.name("framer").version(VERSION).description("Framer Server API CLI").option("--debug", "Enable debug logging").hook("preAction", (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.debug) {
+    setDebugEnabled(true);
+  }
+});
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -15163,11 +15237,13 @@ function printSetupSummary(results) {
 }
 __name(printSetupSummary, "printSetupSummary");
 async function getAgentSystemPrompt(sessionId) {
+  debug("exec", "getAgentSystemPrompt: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return await framer.getAgentSystemPrompt();",
     cwd: process.cwd()
   });
+  debug("exec", "getAgentSystemPrompt: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15179,11 +15255,13 @@ async function getAgentSystemPrompt(sessionId) {
 }
 __name(getAgentSystemPrompt, "getAgentSystemPrompt");
 async function getAgentContext(sessionId) {
+  debug("exec", "getAgentContext: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return await framer.getAgentContext({ pagePath: '/' });",
     cwd: process.cwd()
   });
+  debug("exec", "getAgentContext: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15196,16 +15274,19 @@ async function getAgentContext(sessionId) {
 __name(getAgentContext, "getAgentContext");
 async function refreshSkillsFromSession(sessionId, projectId) {
   try {
+    debug("skills", "fetching agent system prompt + context...");
     const [canvasPrompt, agentContext] = await Promise.all([
       getAgentSystemPrompt(sessionId),
       getAgentContext(sessionId)
     ]);
+    debug("skills", "installing skills...");
     installSkills({
       type: "project",
       canvasPrompt,
       projectId,
       agentContext
     });
+    debug("skills", "skills installed");
   } catch (err) {
     printError(
       `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`
@@ -15217,11 +15298,15 @@ __name(refreshSkillsFromSession, "refreshSkillsFromSession");
 async function resolveSessionCredentials(projectUrlOrId) {
   try {
     const projectId = extractProjectId(projectUrlOrId);
+    debug("credentials", `projectId=${projectId}`);
     const cachedApiKey = getApiKey(projectId);
     if (cachedApiKey) {
+      debug("credentials", "using cached API key");
       return { projectId, apiKey: cachedApiKey };
     }
+    debug("credentials", "no cached key, starting browser auth flow...");
     const newApiKey = await acquireKeyFromBrowser(projectId);
+    debug("credentials", "browser auth complete, saving project");
     saveProject({ projectId, apiKey: newApiKey });
     return { projectId, apiKey: newApiKey };
   } catch (err) {
@@ -15231,11 +15316,13 @@ async function resolveSessionCredentials(projectUrlOrId) {
 }
 __name(resolveSessionCredentials, "resolveSessionCredentials");
 async function getProjectName(sessionId) {
+  debug("exec", "getProjectName: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return (await framer.getProjectInfo()).name;",
     cwd: process.cwd()
   });
+  debug("exec", "getProjectName: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15248,7 +15335,9 @@ async function getProjectName(sessionId) {
 __name(getProjectName, "getProjectName");
 async function ensureRelayForCli() {
   try {
+    debug("relay", "ensuring relay server is running...");
     await ensureRelayServerRunning({ logger: { log: print } });
+    debug("relay", "relay server ready");
   } catch (err) {
     printError(`Failed to check relay status: ${formatError(err)}`);
     process.exit(1);
@@ -15305,27 +15394,39 @@ program.option("-s, --session <id>", "Session ID (required for code execution)")
 });
 var session = program.command("session").description("Manage sessions");
 session.command("new <projectUrlOrId>").description("Create a new session and print the session ID").action(async (projectUrlOrId) => {
+  debug("session.new", `starting for ${projectUrlOrId}`);
+  debug("session.new", "resolving credentials + ensuring relay...");
   const [credentials] = await Promise.all([
     resolveSessionCredentials(projectUrlOrId),
     ensureRelayForCli()
   ]);
+  debug(
+    "session.new",
+    `credentials resolved for project=${credentials.projectId}`
+  );
   try {
+    debug("session.new", "calling createSession on relay...");
     const result = await client.createSession.mutate({
       projectId: credentials.projectId,
       apiKey: credentials.apiKey
     });
     const sessionId = result.id;
+    debug("session.new", `session created id=${sessionId}`);
+    debug("session.new", "fetching project name + refreshing skills...");
     const [projectName] = await Promise.all([
       getProjectName(sessionId),
       refreshSkillsFromSession(sessionId, credentials.projectId)
     ]);
+    debug("session.new", `project name="${projectName}", skills refreshed`);
     saveProject({
       projectId: credentials.projectId,
       apiKey: credentials.apiKey,
       name: projectName,
       lastUsedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
+    debug("session.new", "project saved, printing session id");
     print(sessionId);
+    debug("session.new", "done \u2014 process should exit now");
   } catch (err) {
     const message = formatError(err);
     printError(`Failed to create session: ${message}`);

package/dist/start-relay-server.js

@@ -13,7 +13,7 @@ import { createRequire } from 'module';
 import * as vm from 'vm';
 import { connect } from 'framer-api';
 
-/* @framer/ai relay server v0.0.12 */
+/* @framer/ai relay server v0.0.14 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
 var __typeError = (msg) => {
@@ -89,9 +89,16 @@ function log(message) {
 `);
 }
 __name(log, "log");
+
+// src/version.ts
+var VERSION = (
+  // typeof is used to ensure this can be used just via tsx or node etc. without build
+  "0.0.14" 
+);
+
+// src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.12" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -527,7 +534,9 @@ var ConnectionPool = class {
       }
       return entry.connection;
     }
-    const connection = await connect(projectId, apiKey);
+    const connection = await connect(projectId, apiKey, {
+      clientId: `dalton/${VERSION}`
+    });
     this.pool.set(projectId, {
       connection,
       sessions: /* @__PURE__ */ new Set([session]),
@@ -796,6 +805,7 @@ var appRouter = t.router({
           error: "Failed to get connection for session"
         };
       }
+      const start = performance.now();
       const result = await executeWithReconnect(
         session,
         framer,
@@ -804,8 +814,11 @@ var appRouter = t.router({
         () => sessionManager.reconnect(session),
         execId
       );
+      const elapsed = (performance.now() - start).toFixed(0);
       if (result.error) {
-        log(`exec.error ${tag} error="${result.error}"`);
+        log(`exec.error ${tag} ${elapsed}ms error="${result.error}"`);
+      } else {
+        log(`exec.done ${tag} ${elapsed}ms`);
       }
       return result;
     } catch (_) {

package/docs/skills/framer-canvas-editing-project.md

@@ -1,7 +1,7 @@
 ---
 name: {{SKILL_NAME}}
 description: "Project-scoped Framer canvas editing skill for project {{PROJECT_ID}}. Very important: never load this skill without having already read the `framer` skill and without having already run `session new`, which will dynamically update this skill."
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 ## Project Scope
@@ -49,6 +49,12 @@ framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-read-page.js
 framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-apply-changes.js
 ```
 
+## Critical for UX: Streaming
+
+When you generate a DSL file to apply, keep it short. Each file must only cover ONE logical section (header, footer, hero, card, etc.). Once you generate ONE section, apply it and continue with the next section.
+
+This ensures progress is streamed to the user in small, visible increments.
+
 ## Live Agent System Prompt
 
 This is the static canvas-editing prompt returned by `framer.getAgentSystemPrompt()`. It is the sole documentation for:

package/docs/skills/framer.md

@@ -3,7 +3,7 @@ name: framer
 description: >
   Use when the user wants to design, edit, or publish a website or web page — creating layouts, editing sections, updating text or images, managing CMS collections and content, syncing external data, creating or modifying code components, managing color and text styles, handling localization, or publishing deployments. Trigger when the user mentions Framer, references their website or web pages, asks to edit designs, update site content, or work with any Framer project — even if they don't explicitly say 'Framer'. 
   **Mandatory precondition**: run `npx framer-dalton@latest setup` and let it complete **BEFORE** loading this skill.
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 If you didn't run this command before loading the skill, run it now:
@@ -28,6 +28,10 @@ What you can do with the Framer CLI:
 
 ## CLI Usage
 
+### Permissions
+
+The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx framer-dalton` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
+
 ### Required Workflow
 
 Every task follows these steps:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "type": "module",
   "bin": {
     "framer-dalton": "./dist/cli.js"
@@ -25,7 +25,7 @@
     "@trpc/client": "^11.9.0",
     "@trpc/server": "^11.9.0",
     "commander": "^12.1.0",
-    "framer-api": "https://pkg.pr.new/framer/FramerStudio/framer-api@0711174.tgz",
+    "framer-api": "^0.1.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {