figma-local 1.1.0 → 1.3.0

package/README.md

@@ -51,6 +51,12 @@ npm install -g figma-local
 
 Gives you `fig` and `fig-start` globally on your PATH.
 
+**Update to latest:**
+
+```bash
+npm update -g figma-local
+```
+
 ### curl (one-line)
 
 ```bash
@@ -74,7 +80,7 @@ npx figma-local read
 
 ```bash
 git clone https://github.com/thepreakerebi/figma-local.git
-cd figma-cli
+cd figma-local
 npm install && npm install -g .
 ```
 
@@ -93,32 +99,66 @@ npm install && npm install -g .
 
 ## Setup (one time only)
 
-### 1. Import the Figma plugin
+### Step 1 — Install the CLI
 
-1. Open **Figma Desktop**
-2. Hamburger menu → **Plugins → Development → Import plugin from manifest...**
-3. Navigate to the `plugin/` folder in this repo (or `$(npm root -g)/figma-local/plugin/`)
-4. Select `manifest.json` → click **Open**
-5. Right-click **Figma Local** in the plugin list → **Add to toolbar**
+Pick one of the install methods above (npm recommended):
+
+```bash
+npm install -g figma-local
+```
 
-### 2. Connect
+Verify it worked:
 
 ```bash
-fig-start --safe
+fig --help
 ```
 
-This starts the daemon, waits for you to click Figma Local in Figma, then launches Claude Code.
+### Step 2 — Import the Figma plugin into Figma Desktop
+
+The plugin lets figma-local talk to Figma. You only need to do this once per Figma account.
+
+1. Open **Figma Desktop** (not the browser — the desktop app)
+2. Open any design file
+3. Click the **hamburger menu** (☰) in the top-left corner
+4. Go to **Plugins → Development → Import plugin from manifest...**
+5. In the file picker, navigate to the plugin folder:
+   - If you installed via **npm**: run `echo "$(npm root -g)/figma-local/plugin"` in your terminal to get the path, then navigate there
+   - If you cloned the **repo**: go to `figma-local/plugin/` in the cloned folder
+6. Select `manifest.json` → click **Open**
+7. You should see **"Figma Local"** appear in your plugin list
+8. *(Optional but recommended)* Right-click **Figma Local** in the plugin list → **Add to toolbar** for one-click access
+
+### Step 3 — Connect and verify
+
+1. In Figma, start the plugin: **Plugins → Development → Figma Local** (or click it in your toolbar)
+2. You should see a small widget that says **"Figma Local"** with a connecting status
+3. In your terminal, run:
+
+```bash
+fig connect --safe
+```
+
+4. The plugin widget should show a **green dot** and say **"Connected"**
+5. Try reading your canvas:
+
+```bash
+fig read
+```
+
+If you see a list of frames, you're all set!
 
 ---
 
 ## Every session after that
 
-```
-1. Open Figma → click Figma Local in the toolbar
-2. In terminal: fig-start --safe
+```bash
+# 1. Open Figma Desktop and your design file
+# 2. Click "Figma Local" in the toolbar (or Plugins → Development → Figma Local)
+# 3. In your terminal:
+fig-start --safe
 ```
 
-Claude Code reads `CLAUDE.md` and knows every command automatically.
+This connects to Figma and launches Claude Code. Claude reads `CLAUDE.md` and knows every `fig` command automatically.
 
 ---
 
@@ -249,13 +289,34 @@ fig prompt "Login" \
 
 Generates ~45 tokens of structured text instead of attaching a Figma frame (300–500+ hidden tokens). **91–97% smaller input, more consistent AI output.**
 
+### Screenshots
+
+```bash
+fig screenshot                           # Screenshot current selection
+fig screenshot --node "123:456"          # Screenshot a specific node
+fig screenshot --link "https://..."      # Screenshot from a Figma link
+fig screenshot -o design.png -s 2        # Save to file at 2x scale
+fig screenshot -f svg -o icon.svg        # Export as SVG
+```
+
 ### Verify & compare
 
 ```bash
-fig verify                         # Screenshot of selection for AI review
-fig verify --compare "https://..."  # Diff prototype vs Figma design → correction prompts
+fig verify                                          # Screenshot of selection for AI review
+fig verify --link "https://..."                     # Verify from a Figma link
+fig verify --node "123:456"                         # Verify a specific node
+fig verify --compare "https://..."                  # Diff prototype vs Figma design → correction prompts
+
+# Visual comparison between any two sources
+fig compare --a selection --b "123:456"              # Compare selection vs a node
+fig compare --a design.png --b "123:456"             # Compare a screenshot file vs a Figma node
+fig compare --a design.png --b coded.png             # Compare two screenshot files
+fig compare --a-link "https://..." --b-link "https://..."  # Compare two Figma links
+fig compare --a "123:456" --b "789:012"              # Compare two nodes by ID
 ```
 
+Sources for `--a` and `--b` can be: `selection`, a node ID (`123:456`), or a file path (`screenshot.png`). Use `--a-link` / `--b-link` for Figma selection URLs.
+
 ### Export
 
 ```bash
@@ -392,7 +453,7 @@ Issues and PRs welcome. For major changes, open an issue first to discuss.
 
 ```bash
 git clone https://github.com/thepreakerebi/figma-local.git
-cd figma-cli
+cd figma-local
 npm install
 node src/index.js --help
 npm test

package/bin/fig-start

@@ -123,11 +123,14 @@ for arg in "$@"; do
 done
 
 if [ "$1" = "--setup" ]; then
-    printf "${BOLD}Enter the path to your figma-cli repo:${NC} "
+    printf "${BOLD}Enter the absolute path to your figma-local folder:${NC} "
     read -r repo_path < /dev/tty
     repo_path="${repo_path/#\~/$HOME}"
-    if [ ! -f "$repo_path/src/index.js" ]; then
-        echo -e "${RED}Not a valid figma-cli repo:${NC} $repo_path"
+    if [[ "$repo_path" != /* ]]; then
+        repo_path="$(cd "$repo_path" 2>/dev/null && pwd)"
+    fi
+    if [ -z "$repo_path" ] || [ ! -f "$repo_path/src/index.js" ]; then
+        echo -e "${RED}Not a valid figma-local folder.${NC} Expected src/index.js inside it."
         exit 1
     fi
     save_repo_path "$repo_path"
@@ -139,21 +142,34 @@ fi
 REPO_PATH=$(get_repo_path)
 
 if [ -z "$REPO_PATH" ] || [ ! -d "$REPO_PATH" ]; then
-    # Try to find it relative to this script
+    # Try to find it relative to this script (works for both git clone and npm -g installs)
     SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
     if [ -f "$SCRIPT_DIR/src/index.js" ]; then
         REPO_PATH="$SCRIPT_DIR"
         save_repo_path "$REPO_PATH"
     else
-        echo -e "${YELLOW}figma-cli repo not configured.${NC}"
-        printf "${BOLD}Enter the path to your figma-cli repo:${NC} "
-        read -r REPO_PATH < /dev/tty
-        REPO_PATH="${REPO_PATH/#\~/$HOME}"
-        if [ ! -f "$REPO_PATH/src/index.js" ]; then
-            echo -e "${RED}Not a valid figma-cli repo:${NC} $REPO_PATH"
-            exit 1
+        # Try npm global install location
+        NPM_GLOBAL="$(npm root -g 2>/dev/null)/figma-local"
+        if [ -f "$NPM_GLOBAL/src/index.js" ]; then
+            REPO_PATH="$NPM_GLOBAL"
+            save_repo_path "$REPO_PATH"
+        else
+            echo -e "${YELLOW}figma-local repo not configured.${NC}"
+            echo -e "${DIM}If you installed via npm, run: fig-start --setup${NC}"
+            printf "${BOLD}Enter the absolute path to your figma-local folder:${NC} "
+            read -r REPO_PATH < /dev/tty
+            REPO_PATH="${REPO_PATH/#\~/$HOME}"
+            # Convert relative paths to absolute
+            if [[ "$REPO_PATH" != /* ]]; then
+                REPO_PATH="$(cd "$REPO_PATH" 2>/dev/null && pwd)"
+            fi
+            if [ -z "$REPO_PATH" ] || [ ! -f "$REPO_PATH/src/index.js" ]; then
+                echo -e "${RED}Not a valid figma-local folder.${NC} Expected src/index.js inside it."
+                echo -e "${DIM}Tip: use the full path, e.g. /Users/yourname/figma-local${NC}"
+                exit 1
+            fi
+            save_repo_path "$REPO_PATH"
         fi
-        save_repo_path "$REPO_PATH"
     fi
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-local",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Control Figma Desktop with Claude Code. Smart read, write, and AI-prompt export. No API key required.",
   "author": "elvke",
   "license": "MIT",

package/src/index.js

@@ -5205,18 +5205,30 @@ const exp = program
 
 exp
   .command('screenshot')
-  .description('Take a screenshot of selected node or current page')
+  .description('Take a screenshot of selected node, specific node, or from a Figma link')
   .option('-o, --output <file>', 'Output file', 'screenshot.png')
   .option('-s, --scale <number>', 'Export scale (1-4)', '2')
   .option('-f, --format <format>', 'Format: png, jpg, svg, pdf', 'png')
+  .option('--node <id>', 'Screenshot a specific node by ID')
+  .option('--link <url>', 'Screenshot a node from a Figma selection link')
   .action((options) => {
     checkConnection();
     const format = options.format.toUpperCase();
     const scale = parseFloat(options.scale);
+    let nodeResolver;
+    if (options.link) {
+      const nodeId = parseNodeIdFromLink(options.link);
+      if (!nodeId) { console.error(chalk.red('✗'), 'Could not parse node ID from link'); process.exit(1); }
+      nodeResolver = `node = await figma.getNodeByIdAsync('${nodeId}');`;
+    } else if (options.node) {
+      nodeResolver = `node = await figma.getNodeByIdAsync('${options.node}');`;
+    } else {
+      nodeResolver = `const sel = figma.currentPage.selection; node = sel.length > 0 ? sel[0] : figma.currentPage;`;
+    }
     const code = `(async () => {
-const sel = figma.currentPage.selection;
-const node = sel.length > 0 ? sel[0] : figma.currentPage;
-if (!node) return { error: 'No page or selection' };
+let node;
+${nodeResolver}
+if (!node) return { error: 'No node found' };
 if (!('exportAsync' in node)) return { error: 'Node cannot be exported' };
 const bytes = await node.exportAsync({ format: '${format}', constraint: { type: 'SCALE', value: ${scale} } });
 return {
@@ -5333,14 +5345,25 @@ program
   .option('--save [path]', 'Save as PNG file (default: /tmp/figma-verify-{id}.png)')
   .option('--compare <url>', 'Compare against a prototype/preview URL and generate correction prompts')
   .option('--compare-save <path>', 'Save prototype screenshot to this path when using --compare')
+  .option('--link <url>', 'Verify a node from a Figma selection link')
+  .option('--node <id>', 'Verify a specific node by ID')
   .action(async (nodeId, options) => {
     checkConnection();
     const scale = parseFloat(options.scale);
     const maxDim = parseInt(options.max);
 
+    // Resolve node: --link > --node > positional nodeId > selection
+    let resolvedNodeId = nodeId;
+    if (options.link) {
+      resolvedNodeId = parseNodeIdFromLink(options.link);
+      if (!resolvedNodeId) { console.error(chalk.red('✗'), 'Could not parse node ID from link'); process.exit(1); }
+    } else if (options.node) {
+      resolvedNodeId = options.node;
+    }
+
     const code = `(async () => {
       let node;
-      ${nodeId ? `node = await figma.getNodeByIdAsync('${nodeId}');` : `
+      ${resolvedNodeId ? `node = await figma.getNodeByIdAsync('${resolvedNodeId}');` : `
       const sel = figma.currentPage.selection;
       node = sel.length > 0 ? sel[0] : null;
       `}
@@ -5441,6 +5464,137 @@ program
     }
   });
 
+// ============ COMPARE (Visual Comparison) ============
+
+function exportNodeScreenshot(nodeResolver, scale, maxDim) {
+  const code = `(async () => {
+    let node;
+    ${nodeResolver}
+    if (!node) return { error: 'No node found' };
+    if (!('exportAsync' in node)) return { error: 'Node cannot be exported' };
+    const nodeWidth = node.width || 100;
+    const nodeHeight = node.height || 100;
+    let finalScale = ${scale};
+    const maxNodeDim = Math.max(nodeWidth, nodeHeight);
+    if (maxNodeDim * finalScale > ${maxDim}) finalScale = ${maxDim} / maxNodeDim;
+    if (maxNodeDim * finalScale > 7500) finalScale = 7500 / maxNodeDim;
+    const bytes = await node.exportAsync({ format: 'PNG', constraint: { type: 'SCALE', value: finalScale } });
+    return {
+      name: node.name,
+      id: node.id,
+      type: node.type,
+      width: Math.round(nodeWidth * finalScale),
+      height: Math.round(nodeHeight * finalScale),
+      originalWidth: Math.round(nodeWidth),
+      originalHeight: Math.round(nodeHeight),
+      bytes: Array.from(bytes)
+    };
+  })()`;
+  return figmaEvalSync(code);
+}
+
+program
+  .command('compare')
+  .description('Compare two things visually: screenshots, Figma nodes, or a mix. Outputs both images for AI analysis.')
+  .option('--a <source>', 'First source: file path, node ID, or "selection"', 'selection')
+  .option('--b <source>', 'Second source: file path, node ID, or Figma link')
+  .option('--a-link <url>', 'First source from a Figma selection link')
+  .option('--b-link <url>', 'Second source from a Figma selection link')
+  .option('-s, --scale <number>', 'Export scale for Figma nodes', '1')
+  .option('--max <pixels>', 'Max dimension for exports', '2000')
+  .option('--save-dir <dir>', 'Directory to save comparison images', '/tmp')
+  .addHelpText('after', `
+Examples:
+  fig compare --a selection --b "123:456"          Compare selection vs a node
+  fig compare --a design.png --b "123:456"         Compare a screenshot file vs a Figma node
+  fig compare --a design.png --b coded.png         Compare two screenshot files
+  fig compare --a-link "https://..." --b-link "https://..."   Compare two Figma links
+  fig compare --a selection --b-link "https://..."  Compare selection vs a Figma link
+  fig compare --a "123:456" --b "789:012"          Compare two nodes by ID
+`)
+  .action((options) => {
+    checkConnection();
+    const scale = parseFloat(options.scale);
+    const maxDim = parseInt(options.max);
+    const saveDir = options.saveDir;
+    const timestamp = Date.now();
+
+    function resolveSource(source, linkOpt, label) {
+      // If it's a --link option
+      if (linkOpt) {
+        const nodeId = parseNodeIdFromLink(linkOpt);
+        if (!nodeId) { console.error(chalk.red('✗'), `Could not parse node ID from ${label} link`); process.exit(1); }
+        const result = exportNodeScreenshot(`node = await figma.getNodeByIdAsync('${nodeId}');`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      // File path (existing screenshot)
+      if (source && existsSync(source)) {
+        return { type: 'file', name: source.split('/').pop(), path: source };
+      }
+
+      // "selection"
+      if (source === 'selection') {
+        const result = exportNodeScreenshot(`const sel = figma.currentPage.selection; node = sel.length > 0 ? sel[0] : null;`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      // Node ID (contains ":")
+      if (source && source.includes(':')) {
+        const result = exportNodeScreenshot(`node = await figma.getNodeByIdAsync('${source}');`, scale, maxDim);
+        if (result.error) { console.error(chalk.red('✗'), `${label}: ${result.error}`); process.exit(1); }
+        const filePath = `${saveDir}/figma-compare-${label}-${timestamp}.png`;
+        writeFileSync(filePath, Buffer.from(result.bytes));
+        return { type: 'figma-node', name: result.name, id: result.id, nodeType: result.type, width: result.width, height: result.height, originalWidth: result.originalWidth, originalHeight: result.originalHeight, path: filePath };
+      }
+
+      console.error(chalk.red('✗'), `${label}: "${source}" is not a valid file path, node ID, or "selection"`);
+      process.exit(1);
+    }
+
+    const sourceA = resolveSource(options.a, options.aLink, 'a');
+    const sourceB = resolveSource(options.b, options.bLink, 'b');
+
+    console.log(chalk.bold('\n## Visual Comparison\n'));
+    console.log(chalk.cyan('Source A:'), sourceA.name, sourceA.type === 'figma-node' ? `(${sourceA.nodeType} ${sourceA.id}, ${sourceA.originalWidth}x${sourceA.originalHeight})` : '(file)');
+    console.log(chalk.cyan('Source B:'), sourceB.name, sourceB.type === 'figma-node' ? `(${sourceB.nodeType} ${sourceB.id}, ${sourceB.originalWidth}x${sourceB.originalHeight})` : '(file)');
+    console.log('');
+    console.log(chalk.green('Image A:'), sourceA.path);
+    console.log(chalk.green('Image B:'), sourceB.path);
+    console.log('');
+
+    // Output structured data for AI agents
+    console.log(JSON.stringify({
+      mode: 'visual-comparison',
+      sourceA: { ...sourceA, bytes: undefined },
+      sourceB: { ...sourceB, bytes: undefined },
+      instructions: [
+        `1. Open and examine Image A: ${sourceA.path}`,
+        `2. Open and examine Image B: ${sourceB.path}`,
+        '3. Compare them visually for differences in:',
+        '   - Layout and spacing (padding, margins, gaps)',
+        '   - Colors (backgrounds, text, borders)',
+        '   - Typography (font size, weight, line-height)',
+        '   - Border radius and shadows',
+        '   - Missing or extra elements',
+        '   - Alignment and positioning',
+        '4. Output a structured gap report with specific differences',
+        '5. For each difference, provide the exact values from both sources',
+      ],
+      gapReportTemplate: {
+        matches: '(list elements that match between A and B)',
+        differences: '(table: element | property | value_in_A | value_in_B | severity)',
+        summary: '(brief overall assessment: how closely do they match)',
+      }
+    }, null, 2));
+  });
+
 // ============ EVAL ============
 
 program