framer-dalton 0.0.23 → 0.0.24

package/dist/cli.js

@@ -7,10 +7,11 @@ import http from 'http';
 import { spawn, execFile } from 'child_process';
 import { z } from 'zod';
 import os from 'os';
+import { ErrorCode, FramerAPIError } from 'framer-api';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.23 */
+/* @framer/ai CLI v0.0.24 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -328,7 +329,7 @@ __name(markTelemetryNoticeShown, "markTelemetryNoticeShown");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.23" 
+  "0.0.24" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -418,8 +419,27 @@ function trackError(payload) {
   });
 }
 __name(trackError, "trackError");
-
-// src/utils.ts
+function rehydrateFramerAPIError(error) {
+  if (!(error instanceof Error)) return null;
+  const framerApi = error.data?.framerApi;
+  if (!framerApi || typeof framerApi.code !== "string") return null;
+  const code = ErrorCode[framerApi.code] ?? ErrorCode.INTERNAL;
+  const options = framerApi.ref ? { ref: framerApi.ref } : void 0;
+  return new FramerAPIError(error.message, code, options);
+}
+__name(rehydrateFramerAPIError, "rehydrateFramerAPIError");
+function errorWithRef(message, ref) {
+  const err = new Error(message);
+  if (ref) err.ref = ref;
+  return err;
+}
+__name(errorWithRef, "errorWithRef");
+function getErrorRef(error) {
+  if (!(error instanceof Error)) return void 0;
+  const ref = error.ref;
+  return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+}
+__name(getErrorRef, "getErrorRef");
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -427,6 +447,14 @@ function formatError(error) {
   return String(error);
 }
 __name(formatError, "formatError");
+function formatErrorForUser(error) {
+  if (!(error instanceof Error)) return String(error);
+  const rehydrated = rehydrateFramerAPIError(error);
+  if (rehydrated) return rehydrated.toString();
+  const ref = getErrorRef(error);
+  return ref ? `${error.message} [ref: ${ref}]` : error.message;
+}
+__name(formatErrorForUser, "formatErrorForUser");
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -518,7 +546,7 @@ function successHtml(theme, message) {
   return htmlPage({
     title: "Framer \u2014 Agent Approved",
     heading: "Agent Approved",
-    message: message ?? "Your local agent now has edit access to the project. You can close this tab and continue with the local agent.",
+    message: message ?? "Your external agent now has edit access to the project. You can close this tab and continue with the external agent.",
     theme
   });
 }
@@ -767,7 +795,7 @@ async function acquireAuthWithNewProject() {
     expectProjectId: true,
     successMessage: "Project created and agent authorized",
     authType: "new_project",
-    browserSuccessMessage: "A new project has been created and your local agent is authorized to edit it. You can close this tab."
+    browserSuccessMessage: "A new project has been created and your external agent is authorized to edit it. You can close this tab."
   });
 }
 __name(acquireAuthWithNewProject, "acquireAuthWithNewProject");
@@ -784,7 +812,7 @@ async function acquireAuthWithRemixProject(sourceProjectUrlOrId) {
     expectProjectId: true,
     successMessage: "Project remixed and agent authorized",
     authType: "remix",
-    browserSuccessMessage: "The project has been remixed and your local agent is authorized to edit it. You can close this tab.",
+    browserSuccessMessage: "The project has been remixed and your external agent is authorized to edit it. You can close this tab.",
     projectOrigin
   });
 }
@@ -797,6 +825,48 @@ function isAuthError(errorMessage) {
 }
 __name(isAuthError, "isAuthError");
 
+// src/closest-match.ts
+function levenshteinDistance(source, target) {
+  const sourceLength = source.length;
+  const targetLength = target.length;
+  const matrix = Array.from(
+    { length: sourceLength + 1 },
+    () => Array.from({ length: targetLength + 1 }).fill(0)
+  );
+  for (let row = 0; row <= sourceLength; row++) matrix[row][0] = row;
+  for (let col = 0; col <= targetLength; col++) matrix[0][col] = col;
+  for (let row = 1; row <= sourceLength; row++) {
+    for (let col = 1; col <= targetLength; col++) {
+      const cost = source[row - 1] === target[col - 1] ? 0 : 1;
+      matrix[row][col] = Math.min(
+        matrix[row - 1][col] + 1,
+        matrix[row][col - 1] + 1,
+        matrix[row - 1][col - 1] + cost
+      );
+    }
+  }
+  return matrix[sourceLength][targetLength];
+}
+__name(levenshteinDistance, "levenshteinDistance");
+function findClosestMatch(query, candidates) {
+  const queryLower = query.toLowerCase();
+  let bestMatch;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const distance = levenshteinDistance(queryLower, candidate.toLowerCase());
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestMatch = candidate;
+    }
+  }
+  const maxDistance = Math.max(2, Math.floor(query.length / 3));
+  if (bestDistance <= maxDistance) {
+    return bestMatch;
+  }
+  return void 0;
+}
+__name(findClosestMatch, "findClosestMatch");
+
 // src/types-data.ts
 var types = {
   addcomponentinstanceoptions: {
@@ -975,7 +1045,7 @@ var types = {
       {
         name: "imageUrls",
         type: "readonly string[]",
-        description: "Attach images to this agent turn by URL.\n\nURLs can be external or existing Framer asset URLs. They will be ingested into the\nproject's assets if needed, then sent to the model as image parts.\n\nTip: if you have a local file (or bytes), upload it first (e.g. `framer.uploadImage(...)`) and\npass the returned asset URL here.",
+        description: "Attach images to this agent turn by URL.\n\nURLs can be external or existing Framer asset URLs. They will be ingested into the\nproject's assets if needed, then made available to the agent as trusted attachment URLs.\n\nTip: if you have a local file (or bytes), upload it first (e.g. `framer.uploadImage(...)`) and\npass the returned asset URL here.",
         optional: true
       }
     ]
@@ -7704,6 +7774,12 @@ var types = {
         type: "number",
         description: "",
         optional: true
+      },
+      {
+        name: "captureTrainingData",
+        type: "boolean",
+        description: "When true, capture per-step (system, tools, messages) \u2192 response training rows for SFT.",
+        optional: true
       }
     ]
   },
@@ -7724,6 +7800,18 @@ var types = {
         type: "string",
         description: "",
         optional: false
+      },
+      {
+        name: "trainingDataFilename",
+        type: "string",
+        description: "Training-data filename, present when `captureTrainingData` was set.",
+        optional: true
+      },
+      {
+        name: "trainingDataJsonl",
+        type: "string",
+        description: "JSONL string with one training row per inner-agent step, present when `captureTrainingData` was set.",
+        optional: true
       }
     ]
   },
@@ -15896,6 +15984,26 @@ function getType(name2) {
 __name(getType, "getType");
 
 // src/docs.ts
+function getAllKnownNames() {
+  const bareNames = [
+    ...Object.values(classes).map((classInfo) => classInfo.name),
+    ...Object.values(types).map((typeInfo) => typeInfo.name)
+  ];
+  const framerMethods = methodsByCategory.framer ?? [];
+  for (const method of framerMethods) {
+    bareNames.push(method.name);
+  }
+  const methodNames = [];
+  for (const [category, methods] of Object.entries(methodsByCategory)) {
+    const categoryInfo = classes[category];
+    const displayCategory = categoryInfo?.name ?? category;
+    for (const method of methods) {
+      methodNames.push(`${displayCategory}.${method.name}`);
+    }
+  }
+  return { bareNames, methodNames };
+}
+__name(getAllKnownNames, "getAllKnownNames");
 function formatDocComment(text, indent = "") {
   const lines = text.split("\n");
   if (lines.length === 1) {
@@ -15985,8 +16093,11 @@ function renderDocs(queries) {
     if (query.includes(".")) {
       const method = getMethod(query);
       if (!method) {
+        const { methodNames } = getAllKnownNames();
+        const suggestion = findClosestMatch(query, methodNames);
+        const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
         errors.push(
-          `Method '${query}' not found. Use 'framer docs' to list all.`
+          `Method '${query}' not found.${hint} Use 'framer docs' to list all.`
         );
         return { lines, errors };
       }
@@ -16031,7 +16142,12 @@ ${typeDef}`);
 ${typeDef}`);
           }
         } else {
-          errors.push(`'${query}' not found. Use 'framer docs' to list all.`);
+          const { bareNames } = getAllKnownNames();
+          const suggestion = findClosestMatch(query, bareNames);
+          const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+          errors.push(
+            `'${query}' not found.${hint} Use 'framer docs' to list all.`
+          );
           return { lines, errors };
         }
       }
@@ -16209,6 +16325,16 @@ async function ensureRelayServerRunning(options = {}) {
   throw new Error("Failed to start relay server after 5 seconds");
 }
 __name(ensureRelayServerRunning, "ensureRelayServerRunning");
+
+// src/skill-discovery-wait.ts
+var CLAUDE_CODE_SKILL_DISCOVERY_WAIT_MS = 4e3;
+async function waitForClaudeCodeSkillDiscovery() {
+  if (process.env.CLAUDECODE === void 0) return;
+  await new Promise(
+    (resolve) => setTimeout(resolve, CLAUDE_CODE_SKILL_DISCOVERY_WAIT_MS)
+  );
+}
+__name(waitForClaudeCodeSkillDiscovery, "waitForClaudeCodeSkillDiscovery");
 var FRAMER_TEMPORARY_DIR = path7.join(os.tmpdir(), "framer");
 function ensureTemporaryDir() {
   fs7.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
@@ -16360,6 +16486,10 @@ program.name(PROGRAM_NAME).version(VERSION).description("Framer Server API CLI")
     setDebugEnabled(true);
   }
 });
+function throwRelayError(result) {
+  throw errorWithRef(result.error ?? "Relay error", result.errorRef);
+}
+__name(throwRelayError, "throwRelayError");
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -16402,9 +16532,7 @@ async function getAgentSystemPrompt(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getAgentSystemPrompt: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const prompt = result.output.at(-1);
   if (typeof prompt !== "string") {
     throw new Error("Did not receive agent prompt output.");
@@ -16420,9 +16548,7 @@ async function getAgentContext(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getAgentContext: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const context = result.output.at(-1);
   if (typeof context !== "string") {
     throw new Error("Did not receive agent context output.");
@@ -16446,8 +16572,9 @@ async function refreshSkillsFromSession(sessionId, projectId) {
     });
     debug("skills", "skills installed");
   } catch (err) {
-    throw new Error(
-      `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`
+    throw errorWithRef(
+      `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`,
+      getErrorRef(err)
     );
   }
 }
@@ -16473,7 +16600,7 @@ async function resolveSessionCredentials(projectUrlOrId) {
       projectId,
       errorMessage: message
     });
-    printError(`Failed to resolve credentials: ${message}`);
+    printError(`Failed to resolve credentials: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16487,9 +16614,7 @@ async function getProjectName(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getProjectName: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const projectName = result.output.at(-1);
   if (typeof projectName !== "string") {
     throw new Error("Did not receive project name output.");
@@ -16511,7 +16636,7 @@ async function ensureRelayForCli(context) {
       userId: context?.userId,
       errorMessage: message
     });
-    printError(`Failed to check relay status: ${message}`);
+    printError(`Failed to check relay status: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16529,12 +16654,14 @@ async function execAndPrint(sessionId, code) {
       print(line);
     }
     if (result.error) {
-      printError(`Error: ${result.error}`);
+      printError(
+        `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef))}`
+      );
       await waitForTrackingToFinish();
       process.exit(1);
     }
   } catch (err) {
-    printError(`Execution failed: ${formatError(err)}`);
+    printError(`Execution failed: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16551,7 +16678,7 @@ program.command("exec").description("Execute code in a session").requiredOption(
     try {
       code = fs7.readFileSync(filePath, "utf-8");
     } catch (err) {
-      printError(`Failed to read file: ${formatError(err)}`);
+      printError(`Failed to read file: ${formatErrorForUser(err)}`);
       await waitForTrackingToFinish();
       process.exit(1);
     }
@@ -16640,6 +16767,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         refreshSkillsFromSession(sessionId, projectId)
       ]);
       debug("session.new", `project name="${projectName}", skills refreshed`);
+      await waitForClaudeCodeSkillDiscovery();
       saveProject({
         projectId,
         apiKey: credentials.apiKey,
@@ -16656,7 +16784,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         cleanupStaleSkills(activeProjectIds);
       } catch (error) {
         printWarning(
-          `Failed to clean up stale skills: ${formatError(error)}`
+          `Failed to clean up stale skills: ${formatErrorForUser(error)}`
         );
       }
       const activeSessionIds = activeSessions.map(
@@ -16666,7 +16794,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         cleanupStaleSessionCodeFiles(activeSessionIds);
       } catch (error) {
         printWarning(
-          `Failed to clean up stale session code files: ${formatError(error)}`
+          `Failed to clean up stale session code files: ${formatErrorForUser(error)}`
         );
       }
       debug(
@@ -16685,7 +16813,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         userId,
         errorMessage: message
       });
-      printError(`Failed to create session: ${message}`);
+      printError(`Failed to create session: ${formatErrorForUser(err)}`);
       if (isAuthError(message)) {
         clearApiKey(projectId);
         printError("The stored API key was invalid and has been removed.");
@@ -16719,7 +16847,7 @@ session.command("list").description("List all active sessions").action(async ()
       })
     );
   } catch (err) {
-    printError(`Failed to list sessions: ${formatError(err)}`);
+    printError(`Failed to list sessions: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16759,7 +16887,7 @@ async function saveAuthResult(verb, authFn) {
     saveProject({ projectId, apiKey: result.apiKey, userId: result.userId });
     print(`Project ${projectId} saved`);
   } catch (error) {
-    printError(`Failed to ${verb} project: ${formatError(error)}`);
+    printError(`Failed to ${verb} project: ${formatErrorForUser(error)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16782,7 +16910,7 @@ session.command("destroy <sessionId>").description("Destroy a session").action(a
     await client.destroySession.mutate({ sessionId });
     print(`Session ${sessionId} destroyed`);
   } catch (err) {
-    printError(`Failed to destroy session: ${formatError(err)}`);
+    printError(`Failed to destroy session: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16810,10 +16938,11 @@ program.command("setup").description(
 ).action(async () => {
   try {
     const results = installSkills();
+    await waitForClaudeCodeSkillDiscovery();
     printSetupSummary(results);
     printTelemetryNotice();
   } catch (err) {
-    printError(`Setup failed: ${formatError(err)}`);
+    printError(`Setup failed: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }

package/dist/start-relay-server.js

@@ -8,12 +8,12 @@ import crypto, { randomUUID, timingSafeEqual } from 'crypto';
 import http from 'http';
 import { createHTTPHandler } from '@trpc/server/adapters/standalone';
 import { initTRPC, TRPCError } from '@trpc/server';
+import { connect, FramerAPIError } from 'framer-api';
 import { z } from 'zod';
-import { connect } from 'framer-api';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.23 */
+/* @framer/ai relay server v0.0.24 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -159,7 +159,7 @@ __name(debug, "debug");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.23" 
+  "0.0.24" 
 );
 
 // src/relay-client.ts
@@ -391,6 +391,19 @@ var ScopedFS = class {
   }
   constants = fs4.constants;
 };
+function getErrorRef(error) {
+  if (!(error instanceof Error)) return void 0;
+  const ref = error.ref;
+  return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+}
+__name(getErrorRef, "getErrorRef");
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+__name(formatError, "formatError");
 
 // src/execute.ts
 var EXECUTION_TIMEOUT = 10 * 60 * 1e3;
@@ -530,9 +543,11 @@ async function execute(session, code, options = {}) {
     if (isConnectionError(errorMessage)) {
       session.connection.markDisconnected();
     }
+    const errorRef = getErrorRef(err);
     return {
       output,
-      error: errorMessage
+      error: errorMessage,
+      ...errorRef ? { errorRef } : {}
     };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
@@ -546,10 +561,13 @@ async function executeWithReconnect(session, code, options, execId) {
     );
     try {
       await session.connection.reconnect();
-    } catch {
+    } catch (err) {
+      const inner = err instanceof Error ? err.message : String(err);
+      const errorRef = getErrorRef(err);
       return {
         output: [],
-        error: "Failed to get connection for session"
+        error: `Failed to get connection for session: ${inner}`,
+        ...errorRef ? { errorRef } : {}
       };
     }
   }
@@ -562,13 +580,16 @@ async function executeWithReconnect(session, code, options, execId) {
   );
   try {
     await session.connection.reconnect();
-  } catch {
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    const errorRef = getErrorRef(err);
     log(
-      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="reconnect failed"`
+      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${inner}"`
     );
     return {
       output: [],
-      error: "Connection lost and failed to reconnect"
+      error: `Connection lost and failed to reconnect: ${inner}`,
+      ...errorRef ? { errorRef } : {}
     };
   }
   log(
@@ -1156,7 +1177,17 @@ var SessionManager = class {
 var sessionManager = new SessionManager();
 
 // src/router.ts
-var t = initTRPC.create();
+var t = initTRPC.create({
+  errorFormatter({ shape, error }) {
+    const cause = error.cause;
+    if (cause instanceof FramerAPIError) {
+      const framerApi = { code: cause.code };
+      if (cause.ref !== void 0) framerApi.ref = cause.ref;
+      return { ...shape, data: { ...shape.data, framerApi } };
+    }
+    return shape;
+  }
+});
 var nextExecId = 0;
 var appRouter = t.router({
   version: t.procedure.query(() => {
@@ -1192,7 +1223,7 @@ var appRouter = t.router({
       });
       return { id: session.id };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = formatError(err);
       trackError({
         errorType: "session_create_error",
         projectId: input.projectId,
@@ -1201,7 +1232,8 @@ var appRouter = t.router({
       });
       throw new TRPCError({
         code: isAuthError(message) ? "UNAUTHORIZED" : "INTERNAL_SERVER_ERROR",
-        message
+        message,
+        cause: err
       });
     }
   }),

package/docs/skills/framer.md

@@ -198,12 +198,25 @@ Prompting may take a while to complete, so set the command timeout to 10 minutes
 
 ## Execute Code
 
-Use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
+Prefer writing code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`:
 
 ```bash
 npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
+For short snippets, `exec` also accepts `-e <code>` or code piped on stdin.
+
+## Shell Quoting
+
+In Windows PowerShell, if an argument contains nested quotes, use a single-quoted here-string and pass the variable. Do not backslash-escape quotes.
+
+```powershell
+$value = @'
+[{"key":"value","filter":["text","$rect"]}]
+'@
+npx framer-dalton <command> --option $value
+```
+
 ## API Documentation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -20,14 +20,14 @@
     "generate-types": "tsx scripts/generate-types.ts"
   },
   "dependencies": {
-    "@trpc/client": "^11.9.0",
-    "@trpc/server": "^11.9.0",
+    "@trpc/client": "^11.17.0",
+    "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "^0.1.9",
+    "framer-api": "0.1.10",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.13",
+    "@biomejs/biome": "^2.4.13",
     "@framerjs/framer-events": "0.0.175",
     "@types/node": "24.10.9",
     "tsup": "^8.0.2",