figma-local 1.5.0 → 1.7.0

package/package.json

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

package/plugin/manifest.json

@@ -5,6 +5,7 @@
   "main": "code.js",
   "ui": "ui.html",
   "capabilities": [],
+  "permissions": ["teamlibrary"],
   "enableProposedApi": false,
   "editorType": ["figma", "figjam"],
   "networkAccess": {

package/src/index.js

@@ -8537,6 +8537,7 @@ program
   .option('--tokens', 'Show only the design tokens (colors, spacing, etc.) used in the frame')
   .option('--selection', 'Read whatever is currently selected in Figma')
   .option('--link <url>', 'Read a specific node from a Figma selection link (e.g. copied via "Copy link to selection")')
+  .option('--page', 'Read the entire current page — all frames with full structure, tokens, and specs')
   .option('--stage <n>', 'Run a specific stage: 1 (list frames), 2 (structure), 3 (tokens)')
   .addHelpText('after', `
 Examples:
@@ -8545,6 +8546,7 @@ Examples:
   fig read "Login Screen" --tokens  Show only the design tokens used by Login Screen
   fig read --selection              Read the node you currently have selected in Figma
   fig read --link "https://..."     Read a node from a Figma selection link
+  fig read --page                   Read the entire page with all frames, structure, and tokens
   fig read --json                   Output raw JSON (useful for piping to other tools)
 `)
   .action(async (frameName, options) => {
@@ -8620,6 +8622,136 @@ Examples:
         return;
       }
 
+      // --page: read the entire current page with all frames
+      if (options.page) {
+        spinner.text = 'Reading entire page...';
+        const pageCode = `(function() {
+          const page = figma.currentPage;
+          function walk(n, depth) {
+            if (depth > 20) return { type: n.type, name: n.name };
+            var obj = { type: n.type, name: n.name, id: n.id };
+            if (n.width) obj.w = Math.round(n.width);
+            if (n.height) obj.h = Math.round(n.height);
+            if (n.x !== undefined) obj.x = Math.round(n.x);
+            if (n.y !== undefined) obj.y = Math.round(n.y);
+            if (n.type === 'TEXT') obj.text = n.characters;
+            if (n.fills && n.fills.length) {
+              obj.fills = n.fills.map(function(f) {
+                if (f.type === 'SOLID') return { type: 'SOLID', r: Math.round(f.color.r*255), g: Math.round(f.color.g*255), b: Math.round(f.color.b*255), a: f.opacity !== undefined ? f.opacity : 1 };
+                return { type: f.type };
+              });
+            }
+            if (n.strokes && n.strokes.length) {
+              obj.strokes = n.strokes.map(function(s) {
+                if (s.type === 'SOLID') return { type: 'SOLID', r: Math.round(s.color.r*255), g: Math.round(s.color.g*255), b: Math.round(s.color.b*255) };
+                return { type: s.type };
+              });
+              if (n.strokeWeight) obj.strokeWeight = n.strokeWeight;
+            }
+            if (n.cornerRadius) obj.radius = n.cornerRadius;
+            if (n.opacity !== undefined && n.opacity < 1) obj.opacity = n.opacity;
+            if (n.layoutMode) {
+              obj.layout = { mode: n.layoutMode };
+              if (n.itemSpacing) obj.layout.gap = n.itemSpacing;
+              if (n.paddingTop || n.paddingRight || n.paddingBottom || n.paddingLeft) {
+                obj.layout.padding = { top: n.paddingTop || 0, right: n.paddingRight || 0, bottom: n.paddingBottom || 0, left: n.paddingLeft || 0 };
+              }
+              if (n.primaryAxisAlignItems) obj.layout.mainAlign = n.primaryAxisAlignItems;
+              if (n.counterAxisAlignItems) obj.layout.crossAlign = n.counterAxisAlignItems;
+            }
+            if (n.type === 'TEXT') {
+              obj.typography = {};
+              try { obj.typography.family = n.fontName.family; } catch(e) {}
+              try { obj.typography.style = n.fontName.style; } catch(e) {}
+              try { obj.typography.size = n.fontSize; } catch(e) {}
+              try { obj.typography.weight = n.fontWeight; } catch(e) {}
+              try {
+                if (n.lineHeight && n.lineHeight.value) obj.typography.lineHeight = n.lineHeight.unit === 'PERCENT' ? n.lineHeight.value + '%' : n.lineHeight.value;
+              } catch(e) {}
+              try { if (n.letterSpacing && n.letterSpacing.value) obj.typography.letterSpacing = n.letterSpacing.value; } catch(e) {}
+            }
+            if (n.effects && n.effects.length) {
+              obj.effects = n.effects.map(function(e) {
+                var eff = { type: e.type };
+                if (e.radius) eff.radius = e.radius;
+                if (e.offset) eff.offset = { x: e.offset.x, y: e.offset.y };
+                if (e.color) eff.color = { r: Math.round(e.color.r*255), g: Math.round(e.color.g*255), b: Math.round(e.color.b*255), a: e.color.a };
+                return eff;
+              });
+            }
+            // Variable bindings
+            try {
+              var vars = {};
+              var bindings = n.boundVariables;
+              if (bindings) {
+                Object.keys(bindings).forEach(function(prop) {
+                  try {
+                    var binding = bindings[prop];
+                    if (Array.isArray(binding)) binding = binding[0];
+                    if (binding && binding.id) {
+                      var v = figma.variables.getVariableById(binding.id);
+                      if (v) {
+                        var info = { name: v.name };
+                        try {
+                          var collection = figma.variables.getVariableCollectionById(v.variableCollectionId);
+                          if (collection && collection.modes && collection.modes.length > 0) {
+                            info.values = {};
+                            collection.modes.forEach(function(mode) {
+                              try {
+                                var mVal = v.valuesByMode[mode.modeId];
+                                if (mVal && mVal.type === 'VARIABLE_ALIAS') {
+                                  try {
+                                    var aliased = figma.variables.getVariableById(mVal.id);
+                                    info.values[mode.name] = aliased ? aliased.name : 'alias';
+                                  } catch(e3) { info.values[mode.name] = 'alias'; }
+                                } else {
+                                  info.values[mode.name] = mVal;
+                                }
+                              } catch(e4) {}
+                            });
+                          }
+                        } catch(e5) {}
+                        vars[prop] = info;
+                      }
+                    }
+                  } catch(e) {}
+                });
+              }
+              if (Object.keys(vars).length > 0) obj.variables = vars;
+            } catch(e) {}
+            // Component info
+            if (n.type === 'COMPONENT') obj.isComponent = true;
+            if (n.type === 'INSTANCE') {
+              obj.isInstance = true;
+              try { obj.componentName = n.mainComponent ? n.mainComponent.name : undefined; } catch(e) {}
+            }
+            if (n.children) obj.children = n.children.map(function(c) { return walk(c, depth + 1); });
+            return obj;
+          }
+          var frames = [];
+          for (var i = 0; i < page.children.length; i++) {
+            frames.push(walk(page.children[i], 0));
+          }
+          return { page: page.name, frameCount: frames.length, frames: frames };
+        })()`;
+        const result = await daemonExec('eval', { code: pageCode });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Read page "${result.page}" — ${result.frameCount} top-level frames`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          // Pretty print each frame
+          for (const frame of result.frames) {
+            console.log(chalk.cyan(`\n━━━ ${frame.name} [${frame.type}] ${frame.w || ''}x${frame.h || ''} ━━━`));
+            console.log(formatSelectionResult({ node: frame }));
+          }
+        }
+        return;
+      }
+
       // Stage 1: metadata — always run, cheapest call
       spinner.text = 'Scanning canvas...';
       const metadata = await daemonExec('eval', { code: STAGE1_METADATA });
@@ -10441,4 +10573,228 @@ program
     }
   });
 
+// ============ LIBRARY — access team library components & variables ============
+
+program
+  .command('library <action>')
+  .description('Access team library components and variables from other Figma files')
+  .option('--key <key>', 'Component key for importing')
+  .option('--name <name>', 'Filter by name (partial match)')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Actions:
+  collections    List all available library variable collections
+  variables      List variables from a library collection (use --name to filter)
+  components     List available library components (use --name to filter)
+  import         Import a component by key (use --key)
+
+Examples:
+  fig library collections                    List all library variable collections
+  fig library variables                      List all library variables
+  fig library variables --name "color"       List variables matching "color"
+  fig library components                     List available library components
+  fig library components --name "button"     Find button components
+  fig library import --key "abc123..."       Import a component by its key
+  fig library import --key "abc123..." --name "MyButton"  Import and rename
+`)
+  .action(async (action, options) => {
+    checkConnection();
+    const spinner = ora('Accessing library...').start();
+
+    try {
+      if (action === 'collections') {
+        spinner.text = 'Fetching library variable collections...';
+        const code = `(async function() {
+          try {
+            var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            return cols.map(function(c) {
+              return { name: c.name, key: c.key, libraryName: c.libraryName };
+            });
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library collections. Make sure teamlibrary permission is enabled.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Found ${result.length} library variable collection${result.length !== 1 ? 's' : ''}`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log(chalk.yellow('No library variable collections found. Make sure you have libraries enabled in this file.'));
+          }
+          for (const col of result) {
+            console.log(`  ${chalk.cyan(col.name)} ${chalk.gray('from')} ${chalk.white(col.libraryName)}`);
+            console.log(`    ${chalk.gray('key:')} ${col.key}`);
+          }
+        }
+      } else if (action === 'variables') {
+        spinner.text = 'Fetching library variables...';
+        const nameFilter = options.name ? options.name.toLowerCase() : '';
+        const code = `(async function() {
+          try {
+            var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            var allVars = [];
+            for (var i = 0; i < cols.length; i++) {
+              try {
+                var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(cols[i].key);
+                for (var j = 0; j < vars.length; j++) {
+                  allVars.push({
+                    name: vars[j].name,
+                    key: vars[j].key,
+                    resolvedType: vars[j].resolvedType,
+                    collection: cols[i].name,
+                    library: cols[i].libraryName
+                  });
+                }
+              } catch(e2) {}
+            }
+            ${nameFilter ? `allVars = allVars.filter(function(v) { return v.name.toLowerCase().indexOf('${nameFilter}') !== -1; });` : ''}
+            return allVars;
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library variables.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Found ${result.length} library variable${result.length !== 1 ? 's' : ''}`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.length === 0) {
+            console.log(chalk.yellow('No variables found.' + (nameFilter ? ` Try a different search term.` : '')));
+          }
+          let currentCollection = '';
+          for (const v of result) {
+            const collLabel = `${v.collection} (${v.library})`;
+            if (collLabel !== currentCollection) {
+              currentCollection = collLabel;
+              console.log(chalk.cyan(`\n  ${collLabel}`));
+            }
+            console.log(`    ${chalk.white(v.name)} ${chalk.gray(`[${v.resolvedType}]`)} ${chalk.gray('key:')} ${v.key}`);
+          }
+        }
+      } else if (action === 'components') {
+        spinner.text = 'Fetching library components...';
+        const nameFilter = options.name ? options.name.toLowerCase() : '';
+        const code = `(async function() {
+          try {
+            var collections = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+            var libraryNames = collections.map(function(c) { return c.libraryName; });
+          } catch(e) { var libraryNames = []; }
+          try {
+            // Get components from the assets panel search
+            var components = [];
+            // Try to find components by listing component sets and instances on the current page
+            function findComponents(node) {
+              if (node.type === 'INSTANCE' && node.mainComponent) {
+                try {
+                  var mc = node.mainComponent;
+                  var parent = mc.parent;
+                  components.push({
+                    name: mc.name,
+                    key: mc.key,
+                    componentSetName: parent && parent.type === 'COMPONENT_SET' ? parent.name : null,
+                    description: mc.description || '',
+                    remote: mc.remote
+                  });
+                } catch(e) {}
+              }
+              if ('children' in node) {
+                for (var i = 0; i < node.children.length; i++) {
+                  findComponents(node.children[i]);
+                }
+              }
+            }
+            findComponents(figma.currentPage);
+            // Deduplicate by key
+            var seen = {};
+            var unique = [];
+            for (var i = 0; i < components.length; i++) {
+              if (!seen[components[i].key]) {
+                seen[components[i].key] = true;
+                unique.push(components[i]);
+              }
+            }
+            ${nameFilter ? `unique = unique.filter(function(c) { return c.name.toLowerCase().indexOf('${nameFilter}') !== -1 || (c.componentSetName && c.componentSetName.toLowerCase().indexOf('${nameFilter}') !== -1); });` : ''}
+            return { components: unique, note: unique.length === 0 ? 'No library components found on this page. Drag some components from the Assets panel first, or use fig library import --key <key> if you have the component key.' : null };
+          } catch(e) {
+            return { error: e.message || 'Failed to fetch library components.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        const comps = result.components || [];
+        spinner.succeed(`Found ${comps.length} component${comps.length !== 1 ? 's' : ''} on this page`);
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          if (result.note) {
+            console.log(chalk.yellow(`  ${result.note}`));
+          }
+          for (const c of comps) {
+            const setLabel = c.componentSetName ? chalk.gray(` (set: ${c.componentSetName})`) : '';
+            const remoteLabel = c.remote ? chalk.blue(' [library]') : chalk.gray(' [local]');
+            console.log(`  ${chalk.white(c.name)}${setLabel}${remoteLabel}`);
+            console.log(`    ${chalk.gray('key:')} ${c.key}`);
+            if (c.description) console.log(`    ${chalk.gray('desc:')} ${c.description}`);
+          }
+        }
+      } else if (action === 'import') {
+        if (!options.key) {
+          spinner.fail('--key is required. Get the key from: fig library components, or fig library variables');
+          process.exit(1);
+        }
+        spinner.text = `Importing component ${options.key}...`;
+        const importName = options.name || '';
+        const code = `(async function() {
+          try {
+            var component = await figma.importComponentByKeyAsync('${options.key}');
+            if (!component) return { error: 'Component not found for key: ${options.key}' };
+            // Create an instance
+            var instance = component.createInstance();
+            // Place it in the center of the viewport
+            var vp = figma.viewport.center;
+            instance.x = Math.round(vp.x);
+            instance.y = Math.round(vp.y);
+            ${importName ? `instance.name = '${importName}';` : ''}
+            figma.currentPage.selection = [instance];
+            return {
+              name: instance.name,
+              id: instance.id,
+              componentName: component.name,
+              w: Math.round(instance.width),
+              h: Math.round(instance.height)
+            };
+          } catch(e) {
+            return { error: e.message || 'Failed to import component. Check the key is valid.' };
+          }
+        })()`;
+        const result = await daemonExec('eval', { code });
+        if (result.error) {
+          spinner.fail(result.error);
+          process.exit(1);
+        }
+        spinner.succeed(`Imported "${result.componentName}" as ${result.name} (${result.w}x${result.h})`);
+        console.log(`  ${chalk.gray('id:')} ${result.id}`);
+        console.log(chalk.gray('  Component is now selected on the canvas.'));
+      } else {
+        spinner.fail(`Unknown action: ${action}. Use: collections, variables, components, import`);
+        process.exit(1);
+      }
+    } catch (e) {
+      spinner.fail(`Library access failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();