framer-dalton 0.0.1 → 0.0.2

package/dist/cli.js

@@ -6,7 +6,7 @@ import path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 
-/* @framer/ai CLI v0.0.1 */
+/* @framer/ai CLI v0.0.2 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getConfigDir() {
@@ -73,7 +73,7 @@ function getConfigPath() {
 __name(getConfigPath, "getConfigPath");
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path.dirname(__filename$1);
-var VERSION = "0.0.1" ;
+var VERSION = "0.0.2" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19987;
 async function getRelayServerVersion(port = RELAY_PORT) {
   try {
@@ -160,6 +160,709 @@ async function ensureRelayServer(options = {}) {
 }
 __name(ensureRelayServer, "ensureRelayServer");
 
+// src/skill-docs.ts
+var skillDocs = `## CLI Usage
+
+Use \`npx framer-dalton@latest\` for the first command in a session to ensure you're using the latest version. Subsequent commands can omit \`@latest\`:
+
+\`\`\`bash
+npx framer-dalton@latest session new "<projectUrl>" "<apiKey>"  # First command: use @latest
+npx framer-dalton docs Collection                                # Subsequent: @latest optional
+\`\`\`
+
+### Required Workflow
+
+Every task follows these steps:
+
+#### 1. Connect (once per session)
+
+Ask for the Project URL, then create a session:
+
+\`\`\`bash
+npx framer-dalton@latest session new "<projectUrl>"           # Uses cached API key
+npx framer-dalton@latest session new "<projectUrl>" "<apiKey>" # First time: needs API key
+\`\`\`
+
+#### 2. Look up the API (before EVERY code execution)
+
+**You MUST run \`npx framer-dalton docs\` before writing any code.** Do not guess method names or signatures.
+
+\`\`\`bash
+npx framer-dalton docs Collection           # What methods exist?
+npx framer-dalton docs Collection.getItems  # What are the parameters and return type?
+\`\`\`
+
+#### 3. Execute code
+
+Only after checking docs:
+
+\`\`\`bash
+npx framer-dalton -s 1 -e "state.items = await collection.getItems(); console.log(state.items.length)"
+\`\`\`
+
+#### 4. Store results in \`state\`
+
+Always save results you'll need again. Don't repeat API calls.
+
+---
+
+**Do not skip step 2.** The examples below are patterns only - always verify current signatures with \`npx framer-dalton docs\`.
+
+### Communication style
+
+Be concise. Don't narrate implementation details like field IDs, escaping, or internal steps. Just do the work and report what was accomplished in user-facing terms.
+
+---
+
+### Session Management
+
+Each session maintains a persistent connection to a Framer project. Use sessions to:
+
+- Keep state separate between different tasks
+- Persist data across multiple execute calls
+- Reuse the \`framer\` API instance without reconnecting
+
+Get a new session ID:
+
+\`\`\`bash
+npx framer-dalton@latest session new "https://framer.com/projects/Website--abc123" "framer_api_xxx"
+# outputs: 1
+\`\`\`
+
+**Always use your own session** - pass \`-s <id>\` to all commands. Using the same session preserves your \`state\` between calls.
+
+List active sessions:
+
+\`\`\`bash
+npx framer-dalton session list
+\`\`\`
+
+### Execute Code
+
+\`\`\`bash
+npx framer-dalton -s <sessionId> -e "<code>"
+\`\`\`
+
+Default timeout is 30 seconds. Increase with \`--timeout <ms>\`.
+
+**Escaping:** For code with HTML, quotes, or special characters, use a heredoc (see below). For simple strings, use \`$'...'\` syntax.
+
+**Examples:**
+
+\`\`\`bash
+# Fetch collections and store in state (always store results you'll reuse)
+npx framer-dalton -s 1 -e "state.collections = await framer.getCollections(); console.log(state.collections.map(c => c.name))"
+
+# Use stored data in subsequent calls
+npx framer-dalton -s 1 -e "state.team = state.collections.find(c => c.name === 'Team')"
+npx framer-dalton -s 1 -e "state.teamItems = await state.team.getItems(); console.log(state.teamItems.length)"
+\`\`\`
+
+**Multiline code with heredoc (recommended for complex strings):**
+
+For code containing HTML, quotes, or special characters, use a heredoc to avoid escaping issues:
+
+\`\`\`bash
+npx framer-dalton -s 1 <<'EOF'
+const translations = {
+  "node-id": "<h2>Ship's Treasures</h2>",
+  "other-id": "<p>Text with "quotes" and <tags></p>"
+};
+await framer.setLocalizationData({ valuesBySource: translations });
+EOF
+\`\`\`
+
+The \`<<'EOF'\` syntax (with quotes around EOF) prevents shell interpolation.
+
+**Alternative: pipe from file:**
+
+\`\`\`bash
+cat script.js | npx framer-dalton -s 1
+\`\`\`
+
+**Simple inline code:**
+
+\`\`\`bash
+npx framer-dalton -s 1 -e $'
+const collections = await framer.getCollections();
+for (const c of collections) {
+  const items = await c.getItems();
+  console.log(c.name, items.length);
+}
+'
+\`\`\`
+
+### API Documentation
+
+\`\`\`bash
+npx framer-dalton docs                      # List all classes and methods
+npx framer-dalton docs Collection           # Show all methods for Collection
+npx framer-dalton docs Collection.addItems  # Show method with parameter types inlined
+npx framer-dalton docs framer.screenshot    # Show method signature and types
+npx framer-dalton docs ScreenshotOptions    # Look up a specific type definition
+\`\`\`
+
+When looking up a method, all referenced types are automatically expanded inline.
+
+---
+
+## Context Variables
+
+- \`framer\` - Connected Framer Server API instance
+- \`state\` - Object persisted between calls within your session
+- \`console\` - For output (\`console.log\`, \`console.error\`)
+- \`require\` - Sandboxed Node.js modules: fs, path, url, crypto, buffer, util, os
+- Standard globals: \`fetch\`, \`Buffer\`, \`URL\`, \`crypto\`, \`setTimeout\`
+
+**Note:** \`fs\` operations are sandboxed to cwd, /tmp, and os.tmpdir().
+
+### Use \`state\` to Avoid Repeated Calls
+
+**Always store results in \`state\` when you'll need them again.** API calls are slow - don't repeat them.
+
+\`\`\`bash
+# First call: fetch and store
+npx framer-dalton -s 1 -e "state.collections = await framer.getCollections()"
+
+# Later calls: reuse from state
+npx framer-dalton -s 1 -e "const team = state.collections.find(c => c.name === 'Team')"
+npx framer-dalton -s 1 -e "state.teamItems = await state.collections.find(c => c.name === 'Team').getItems()"
+\`\`\`
+
+Store anything you'll reference again: collections, items, nodes, fields.
+
+---
+
+## API Examples
+
+**STOP: These are patterns only. Before using any method below, run \`npx framer-dalton docs <ClassName>\` to verify the current signature.**
+
+---
+
+## Working with Collections (CMS)
+
+Collections are Framer's CMS. Each collection has fields (columns) and items (rows).
+
+### Reading Collections
+
+\`\`\`js
+// Get all collections
+const collections = await framer.getCollections();
+console.log(collections.map((c) => ({ name: c.name, id: c.id })));
+
+// Get a specific collection by ID
+const collection = await framer.getCollection("collection-id");
+
+// Get fields (columns) - returns array of { id, type, name }
+const fields = await collection.getFields();
+console.log(fields);
+// [{ id: "BnNuS2i3o", type: "string", name: "Title" }, ...]
+
+// Get items (rows)
+const items = await collection.getItems();
+console.log(items);
+// [{ id: "XTM8FSHGs", slug: "post-1", draft: false, fieldData: {...} }, ...]
+\`\`\`
+
+### Field Types
+
+\`boolean\`, \`color\`, \`number\`, \`string\`, \`formattedText\` (HTML), \`image\`, \`file\`, \`link\`, \`date\`, \`enum\`, \`collectionReference\`, \`multiCollectionReference\`, \`array\` (galleries)
+
+### Updating Collection Items
+
+\`\`\`js
+// Add or update items (if id matches existing item, it updates)
+await collection.addItems([
+  {
+    id: "new-item-1",
+    slug: "hello-world",
+    fieldData: { titleFieldId: "Hello World" },
+  },
+]);
+
+// Remove items
+await collection.removeItems(["item-id-1", "item-id-2"]);
+
+// Reorder items
+const ids = items.map((i) => i.id).reverse();
+await collection.setItemOrder(ids);
+\`\`\`
+
+### Working with CollectionItem
+
+\`\`\`js
+const items = await collection.getItems();
+const item = items[0];
+
+// Update item attributes
+await item.setAttributes({ slug: "new-slug" });
+
+// Navigate to item in Framer UI
+await item.navigateTo();
+
+// Remove item
+await item.remove();
+\`\`\`
+
+### Managed Collections
+
+Managed collections are fully controlled by code - users can't edit them directly. Use for syncing external data sources.
+
+\`\`\`js
+// Create a managed collection
+const managed = await framer.createManagedCollection({ name: "My Sync" });
+
+// Set fields
+await managed.setFields([
+  { id: "title", name: "Title", type: "string" },
+  { id: "content", name: "Content", type: "formattedText" },
+  { id: "published", name: "Published", type: "date" },
+]);
+
+// Add items
+await managed.addItems([
+  {
+    id: "1",
+    slug: "first-post",
+    fieldData: { title: "Hello", content: "<p>World</p>" },
+  },
+]);
+
+// Store sync metadata
+await managed.setPluginData("lastSync", new Date().toISOString());
+const lastSync = await managed.getPluginData("lastSync");
+\`\`\`
+
+---
+
+## Working with Nodes
+
+Nodes are layers on the canvas: frames, text, images, components, etc.
+
+### Getting Nodes
+
+\`\`\`js
+// Get current selection
+const selection = await framer.getSelection();
+
+// Get canvas root
+const root = await framer.getCanvasRoot();
+
+// Get node by ID
+const node = await framer.getNode("node-id");
+
+// Get children of a node
+const children = await framer.getChildren(node.id);
+
+// Get parent
+const parent = await framer.getParent(node.id);
+
+// Find nodes by type
+const frameNodes = await framer.getNodesWithType("FrameNode");
+const textNodes = await framer.getNodesWithType("TextNode");
+
+// Find nodes with specific attribute set
+const nodesWithBg = await framer.getNodesWithAttributeSet("backgroundColor");
+const nodesWithImage = await framer.getNodesWithAttributeSet("backgroundImage");
+\`\`\`
+
+### Creating Nodes
+
+\`\`\`js
+// Create a frame
+const frame = await framer.createFrameNode({
+  name: "My Frame",
+  width: 200,
+  height: 100,
+  backgroundColor: "rgba(255, 0, 0, 1)",
+});
+
+// Create text (creates TextNode, then use setText)
+const textNode = await framer.createTextNode({ name: "My Text" });
+await textNode.setText("Hello World");
+
+// Add to specific parent
+const child = await framer.createFrameNode({ name: "Child" }, parentNode.id);
+\`\`\`
+
+### Modifying Nodes
+
+\`\`\`js
+// Update attributes
+await node.setAttributes({
+  name: "New Name",
+  width: 300,
+  height: 200,
+  backgroundColor: "rgba(0, 0, 255, 0.5)",
+  visible: true,
+  locked: false,
+});
+
+// Move to different parent
+await framer.setParent(node.id, newParentId);
+
+// Clone a node
+const clone = await node.clone();
+
+// Remove nodes
+await framer.removeNodes([node.id]);
+\`\`\`
+
+### Working with Text
+
+\`\`\`js
+// Get text content
+const text = await framer.getText(); // from selection
+const nodeText = await textNode.getText();
+
+// Set text
+await framer.setText("New text"); // on selection
+await textNode.setText("Hello World");
+\`\`\`
+
+---
+
+## Working with Images
+
+\`\`\`js
+// Add image to canvas
+await framer.addImage({
+  image: "https://example.com/image.png",
+  name: "My Image",
+  altText: "Description",
+});
+
+// Set image on selected node
+await framer.setImage({
+  image: "https://example.com/image.png",
+  altText: "Description",
+});
+
+// Upload image without adding to canvas (for later use)
+const imageAsset = await framer.uploadImage({
+  image: "https://example.com/image.png",
+  name: "My Image",
+  altText: "Alt text",
+});
+
+// Use uploaded image when creating a frame
+await framer.createFrameNode({ backgroundImage: imageAsset });
+
+// Get image from selection
+const image = await framer.getImage();
+console.log(image?.url);
+
+// Add SVG (must be < 10kb)
+await framer.addSVG({
+  svg: '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><circle cx="10" cy="10" r="8"/></svg>',
+  name: "circle.svg",
+});
+\`\`\`
+
+---
+
+## Working with Styles
+
+### Color Styles
+
+\`\`\`js
+// List all color styles
+const colorStyles = await framer.getColorStyles();
+
+// Get specific style
+const style = await framer.getColorStyle("style-id");
+
+// Create color style (supports light/dark themes)
+const newStyle = await framer.createColorStyle({
+  name: "Brand/Primary", // Use / for folders
+  light: "rgba(242, 59, 57, 1)",
+  dark: "rgba(180, 40, 40, 1)",
+});
+
+// Update style
+await style.setAttributes({ light: "rgba(0, 100, 200, 1)" });
+
+// Remove style
+await style.remove();
+\`\`\`
+
+### Text Styles
+
+\`\`\`js
+// List all text styles
+const textStyles = await framer.getTextStyles();
+
+// Create text style
+const heading = await framer.createTextStyle({
+  name: "Typography/Heading 1",
+  tag: "h1",
+  fontSize: "48px",
+  lineHeight: "1.2em",
+  fontWeight: 700,
+});
+
+// With breakpoints for responsive typography
+const responsive = await framer.createTextStyle({
+  fontSize: "24px",
+  minWidth: 1280,
+  breakpoints: [
+    { minWidth: 1024, fontSize: "20px" },
+    { minWidth: 768, fontSize: "18px" },
+    { minWidth: 320, fontSize: "16px" },
+  ],
+});
+
+// Update text style
+await heading.setAttributes({ fontSize: "52px" });
+\`\`\`
+
+### Fonts
+
+\`\`\`js
+// Get available fonts
+const fonts = await framer.getFonts();
+
+// Get specific font
+const font = await framer.getFont("Inter", { weight: 400 });
+const boldFont = await framer.getFont("Inter", { weight: 700 });
+
+// Use font in text style
+await framer.createTextStyle({
+  name: "Body",
+  font,
+  boldFont,
+});
+\`\`\`
+
+---
+
+## Working with Code Files
+
+\`\`\`js
+// List code files
+const codeFiles = await framer.getCodeFiles();
+
+// Get specific code file
+const file = await framer.getCodeFile("file-id");
+
+// Create code file
+const newFile = await framer.createCodeFile({
+  name: "MyComponent.tsx",
+  content: \`export function MyComponent() { return <div>Hello</div> }\`,
+});
+
+// Type check code
+const errors = await framer.typecheckCode(\`const x: string = 123\`);
+\`\`\`
+
+---
+
+## Component Instances
+
+\`\`\`js
+// Insert a component by URL
+await framer.addComponentInstance({
+  url: "https://framer.com/m/Button-5TDo.js",
+  attributes: {
+    width: "200px",
+    height: "50px",
+    controls: { label: "Click me", variant: "primary" },
+  },
+});
+
+// Insert as detached layers (editable)
+await framer.addDetachedComponentLayers({
+  url: "https://framer.com/m/Card-abc.js",
+  attributes: { title: "My Card" },
+});
+\`\`\`
+
+---
+
+## Storing Data
+
+Store metadata on nodes or globally in the project.
+
+\`\`\`js
+// Store global project data
+await framer.setPluginData("myKey", "myValue");
+const value = await framer.getPluginData("myKey");
+
+// Store data on a node
+await node.setPluginData("processed", "true");
+const nodeData = await node.getPluginData("processed");
+
+// List all keys
+const keys = await framer.getPluginDataKeys();
+const nodeKeys = await node.getPluginDataKeys();
+
+// Delete data (set to null)
+await framer.setPluginData("myKey", null);
+\`\`\`
+
+---
+
+## Localization
+
+\`\`\`js
+// Get all locales
+const locales = await framer.getLocales();
+const defaultLocale = await framer.getDefaultLocale();
+
+// Get localization groups (pages, CMS items with translations)
+const groups = await framer.getLocalizationGroups();
+
+// Update translations
+const french = locales.find((l) => l.code === "fr");
+await framer.setLocalizationData({
+  valuesBySource: {
+    [sourceId]: {
+      [french.id]: { action: "set", value: "Bonjour" },
+    },
+  },
+});
+\`\`\`
+
+---
+
+## Common Patterns
+
+### Iterate over all nodes in project
+
+\`\`\`js
+const root = await framer.getCanvasRoot();
+for await (const node of root.walk()) {
+  console.log(node.name);
+}
+\`\`\`
+
+### Sync external data to collection
+
+\`\`\`js
+const collection = await framer.getManagedCollection();
+const existingIds = new Set(await collection.getItemIds());
+
+const externalData = await fetch("https://api.example.com/posts").then((r) =>
+  r.json(),
+);
+
+const items = externalData.map((post) => ({
+  id: post.id,
+  slug: post.slug,
+  fieldData: { title: post.title, content: post.body },
+}));
+
+await collection.addItems(items);
+
+// Remove items no longer in external source
+const newIds = new Set(items.map((i) => i.id));
+const toRemove = [...existingIds].filter((id) => !newIds.has(id));
+if (toRemove.length) await collection.removeItems(toRemove);
+
+await collection.setPluginData("lastSync", new Date().toISOString());
+\`\`\`
+
+### Batch update all images' alt text
+
+\`\`\`js
+const nodes = await framer.getNodesWithAttributeSet("backgroundImage");
+for (const node of nodes) {
+  if (!node.backgroundImage) continue;
+  await node.setAttributes({
+    backgroundImage: node.backgroundImage.cloneWithAttributes({
+      altText: "Updated description",
+    }),
+  });
+}
+\`\`\`
+
+---
+
+## Screenshots and SVG Export
+
+Server API exclusive methods for capturing visual output from nodes.
+
+\`\`\`js
+// Take a screenshot of a node (returns Buffer + mimeType)
+const result = await framer.screenshot(node.id);
+console.log(result.mimeType); // "image/png"
+await require("fs").promises.writeFile("/tmp/screenshot.png", result.data);
+
+// With options
+const jpg = await framer.screenshot(node.id, {
+  format: "jpeg", // "png" (default) or "jpeg"
+  quality: 90, // JPEG quality 0-100 (default 100)
+  scale: 2, // Pixel density: 0.5, 1, 1.5, 2, 3, or 4 (default 1)
+  clip: { x: 0, y: 0, width: 100, height: 100 }, // Clip region in CSS pixels
+});
+
+// Export as SVG string
+const svgString = await framer.exportSVG(node.id);
+await require("fs").promises.writeFile("/tmp/export.svg", svgString);
+\`\`\`
+
+---
+
+## Publishing and Deployments
+
+Server API exclusive methods for publishing and managing deployments.
+
+\`\`\`js
+// Publish the project (creates a new deployment)
+const result = await framer.publish();
+console.log(result.deployment.id); // Deployment ID
+console.log(result.hostnames); // Array of hostnames
+
+// Get all deployments
+const deployments = await framer.getDeployments();
+for (const d of deployments) {
+  console.log(d.id, d.createdAt);
+}
+
+// Deploy a specific deployment to domains
+const hostnames = await framer.deploy(deploymentId, ["example.com"]);
+
+// Get current publish info (production and staging URLs)
+const info = await framer.getPublishInfo();
+console.log(info.production?.url); // Production URL
+console.log(info.staging?.url); // Staging URL
+\`\`\`
+
+---
+
+## Change Tracking
+
+Server API exclusive methods for tracking project changes.
+
+\`\`\`js
+// Get changed paths since last publish
+const changes = await framer.getChangedPaths();
+console.log(changes.added); // New paths
+console.log(changes.modified); // Modified paths
+console.log(changes.removed); // Removed paths
+
+// Get contributors to changes (returns user IDs)
+const contributors = await framer.getChangeContributors();
+\`\`\`
+
+---
+
+## Capabilities
+
+What you can do with the Framer CLI:
+
+- **CMS**: Create, read, update, delete collections and items. Sync external databases.
+- **Canvas**: Create and modify frames, text, images, SVGs. Build layouts programmatically.
+- **Styles**: Manage color and text styles. Sync design systems.
+- **Components**: Insert component instances with configured properties.
+- **Code**: Create and manage code component files.
+- **Assets**: Upload and manage images and files.
+- **Localization**: Manage translations programmatically.
+- **Data**: Store metadata on nodes and projects for plugin state.
+- **Screenshots**: Capture node screenshots as PNG/JPEG. Export nodes as SVG.
+- **Publishing**: Publish projects, manage deployments, track changes.
+`;
+
 // src/types-data.ts
 var methods = [
   {
@@ -6299,6 +7002,9 @@ function getReferencedTypes(text, seen = /* @__PURE__ */ new Set()) {
   return result;
 }
 __name(getReferencedTypes, "getReferencedTypes");
+program.command("skill").description("Output complete skill documentation for Claude").action(() => {
+  print(skillDocs);
+});
 program.command("docs [queries...]").description(
   "Look up API documentation. Use: docs, docs ClassName, docs Class.method, or docs TypeName"
 ).action((queries) => {

package/dist/start-relay-server.js

@@ -9,7 +9,7 @@ import { createRequire } from 'module';
 import * as vm from 'vm';
 import { connect } from 'framer-api';
 
-/* @framer/ai relay server v0.0.1 */
+/* @framer/ai relay server v0.0.2 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getLogPath() {
@@ -46,7 +46,7 @@ function log(message) {
 __name(log, "log");
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.1" ;
+var VERSION = "0.0.2" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19987;
 
 // src/connection-errors.ts

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "bin": {
-    "framer": "./dist/cli.js"
+    "framer-dalton": "./dist/cli.js"
   },
   "main": "./dist/cli.js",
   "types": "./dist/cli.d.ts",