figmatk 0.0.6

package/commands/insert-image.mjs

@@ -0,0 +1,90 @@
+/**
+ * insert-image — Apply an image fill override to a slide instance.
+ *
+ * Usage: node cli.mjs insert-image <file.deck> -o <output.deck> --slide <id|name> --key <overrideKey> --image <path.png> [--thumb <thumb.png>]
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid, parseId } from '../lib/node-helpers.mjs';
+import { imageOv } from '../lib/image-helpers.mjs';
+import { readFileSync, copyFileSync, existsSync, mkdirSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+import { getImageDimensions, generateThumbnail } from '../lib/image-utils.mjs';
+
+function sha1Hex(buf) {
+  return createHash('sha1').update(buf).digest('hex');
+}
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRef = flags.slide;
+  const keyStr = flags.key;
+  const imagePath = flags.image;
+  const thumbPath = flags.thumb || null;
+
+  if (!file || !outPath || !slideRef || !keyStr || !imagePath) {
+    console.error('Usage: insert-image <file.deck> -o <out.deck> --slide <id|name> --key <key> --image <path.png> [--thumb <thumb.png>]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  // Find slide
+  const slide = findSlide(deck, slideRef);
+  if (!slide) { console.error(`Slide not found: ${slideRef}`); process.exit(1); }
+
+  const inst = deck.getSlideInstance(nid(slide));
+  if (!inst) { console.error(`No instance on slide ${nid(slide)}`); process.exit(1); }
+
+  const imgBuf = readFileSync(resolve(imagePath));
+  const imgHash = sha1Hex(imgBuf);
+  const { width, height } = await getImageDimensions(resolve(imagePath));
+
+  let thumbHash;
+  if (thumbPath) {
+    const tBuf = readFileSync(resolve(thumbPath));
+    thumbHash = sha1Hex(tBuf);
+    copyToImages(deck, thumbHash, resolve(thumbPath));
+  } else {
+    const tmpThumb = `/tmp/figmatk_thumb_${Date.now()}.png`;
+    await generateThumbnail(resolve(imagePath), tmpThumb);
+    thumbHash = sha1Hex(readFileSync(tmpThumb));
+    copyToImages(deck, thumbHash, tmpThumb);
+  }
+
+  // Copy full image to images dir
+  copyToImages(deck, imgHash, resolve(imagePath));
+
+  // Build and apply override
+  const key = parseId(keyStr);
+  const override = imageOv(key, imgHash, thumbHash, width, height);
+
+  if (!inst.symbolData) inst.symbolData = {};
+  if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+  inst.symbolData.symbolOverrides.push(override);
+
+  console.log(`Image: ${imgHash} (${width}×${height})`);
+  console.log(`Thumb: ${thumbHash}`);
+  console.log(`Applied to slide "${slide.name || nid(slide)}" key ${keyStr}`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function copyToImages(deck, hash, srcPath) {
+  if (!deck.imagesDir) {
+    deck.imagesDir = `/tmp/figmatk_images_${Date.now()}`;
+    mkdirSync(deck.imagesDir, { recursive: true });
+  }
+  const dest = join(deck.imagesDir, hash);
+  if (!existsSync(dest)) {
+    copyFileSync(srcPath, dest);
+  }
+}
+
+function findSlide(deck, ref) {
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+  return deck.getActiveSlides().find(s => s.name === ref);
+}

package/commands/inspect.mjs

@@ -0,0 +1,91 @@
+/**
+ * inspect — Show document structure (node hierarchy tree).
+ *
+ * Usage: node cli.mjs inspect <file.deck|file.fig> [--depth N] [--type TYPE] [--json]
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid } from '../lib/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) { console.error('Usage: inspect <file.deck|file.fig>'); process.exit(1); }
+
+  const maxDepth = flags.depth ? parseInt(flags.depth) : Infinity;
+  const filterType = flags.type || null;
+  const jsonOut = flags.json != null;
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  // Find root nodes (no parentIndex or parent not in nodeMap)
+  const roots = deck.message.nodeChanges.filter(n => {
+    if (!n.parentIndex?.guid) return true;
+    const pid = `${n.parentIndex.guid.sessionID}:${n.parentIndex.guid.localID}`;
+    return !deck.nodeMap.has(pid);
+  });
+
+  if (jsonOut) {
+    const collect = [];
+    for (const root of roots) {
+      collectJson(deck, nid(root), 0, maxDepth, filterType, collect);
+    }
+    console.log(JSON.stringify(collect, null, 2));
+    return;
+  }
+
+  // Summary
+  const slides = deck.getSlides();
+  const active = deck.getActiveSlides();
+  console.log(`Nodes: ${deck.message.nodeChanges.length}  Slides: ${active.length} active / ${slides.length} total  Blobs: ${deck.message.blobs?.length || 0}`);
+  if (deck.deckMeta) console.log(`Deck name: ${deck.deckMeta.file_name || '(unknown)'}`);
+  console.log('');
+
+  for (const root of roots) {
+    printTree(deck, nid(root), 0, maxDepth, filterType);
+  }
+}
+
+function printTree(deck, id, depth, maxDepth, filterType) {
+  if (depth > maxDepth) return;
+  const node = deck.getNode(id);
+  if (!node) return;
+
+  const type = node.type || '?';
+  const show = !filterType || type === filterType;
+
+  if (show) {
+    const indent = '  '.repeat(depth);
+    const name = node.name ? `"${node.name}"` : '';
+    const removed = node.phase === 'REMOVED' ? ' [REMOVED]' : '';
+    const sym = node.symbolData?.symbolID
+      ? ` sym=${node.symbolData.symbolID.sessionID}:${node.symbolData.symbolID.localID}`
+      : '';
+    const ovCount = node.symbolData?.symbolOverrides?.length;
+    const ovs = ovCount ? ` overrides=${ovCount}` : '';
+    console.log(`${indent}${type} ${name} (${id})${removed}${sym}${ovs}`);
+  }
+
+  for (const child of deck.getChildren(id)) {
+    printTree(deck, nid(child), depth + 1, maxDepth, filterType);
+  }
+}
+
+function collectJson(deck, id, depth, maxDepth, filterType, out) {
+  if (depth > maxDepth) return;
+  const node = deck.getNode(id);
+  if (!node) return;
+  const type = node.type || '?';
+  if (!filterType || type === filterType) {
+    out.push({
+      id, type, name: node.name || null,
+      phase: node.phase || null,
+      symbolID: node.symbolData?.symbolID ? nid({ guid: node.symbolData.symbolID }) : null,
+      overrides: node.symbolData?.symbolOverrides?.length || 0,
+      depth,
+    });
+  }
+  for (const child of deck.getChildren(id)) {
+    collectJson(deck, nid(child), depth + 1, maxDepth, filterType, out);
+  }
+}

package/commands/list-overrides.mjs

@@ -0,0 +1,66 @@
+/**
+ * list-overrides — List all editable override keys per symbol.
+ *
+ * Usage: node cli.mjs list-overrides <file.deck> [--symbol NAME|ID]
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid } from '../lib/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  if (!file) { console.error('Usage: list-overrides <file.deck>'); process.exit(1); }
+
+  const filterSym = flags.symbol || null;
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  const symbols = deck.getSymbols();
+
+  for (const sym of symbols) {
+    const symId = nid(sym);
+    const symName = sym.name || '(unnamed)';
+
+    // Filter
+    if (filterSym && symName !== filterSym && symId !== filterSym) continue;
+
+    console.log(`\nSYMBOL "${symName}" (${symId})`);
+    console.log('─'.repeat(60));
+
+    // Walk children and find nodes with overrideKey
+    walkForOverrides(deck, symId, 1);
+  }
+}
+
+function walkForOverrides(deck, parentId, depth) {
+  const children = deck.getChildren(parentId);
+  for (const child of children) {
+    const id = nid(child);
+    const ok = child.overrideKey;
+
+    if (ok) {
+      const indent = '  '.repeat(depth);
+      const keyStr = `${ok.sessionID}:${ok.localID}`;
+      const type = child.type || '?';
+      const name = child.name || '';
+
+      let detail = '';
+      if (type === 'TEXT' && child.textData?.characters) {
+        const text = child.textData.characters;
+        const preview = text.length > 50 ? text.substring(0, 47) + '...' : text;
+        detail = ` → ${JSON.stringify(preview)}`;
+      } else if (type === 'ROUNDED_RECTANGLE' || type === 'RECTANGLE') {
+        const hasFill = child.fillPaints?.some(p => p.type === 'IMAGE');
+        detail = hasFill ? ' [IMAGE PLACEHOLDER]' : '';
+      } else if (type === 'INSTANCE') {
+        const sid = child.symbolData?.symbolID;
+        detail = sid ? ` sym=${sid.sessionID}:${sid.localID}` : '';
+      }
+
+      console.log(`${indent}${keyStr}  ${type} "${name}"${detail}`);
+    }
+
+    walkForOverrides(deck, id, depth + 1);
+  }
+}

package/commands/list-text.mjs

@@ -0,0 +1,60 @@
+/**
+ * list-text — List all text content in the deck.
+ *
+ * Usage: node cli.mjs list-text <file.deck>
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid } from '../lib/node-helpers.mjs';
+import { hashToHex } from '../lib/image-helpers.mjs';
+
+export async function run(args) {
+  const file = args[0];
+  if (!file) { console.error('Usage: list-text <file.deck>'); process.exit(1); }
+
+  const deck = file.endsWith('.fig')
+    ? FigDeck.fromFigFile(file)
+    : await FigDeck.fromDeckFile(file);
+
+  // Direct text nodes
+  console.log('=== Direct text nodes ===\n');
+  for (const node of deck.message.nodeChanges) {
+    if (node.type === 'TEXT' && node.textData?.characters) {
+      const text = node.textData.characters;
+      const preview = text.length > 80 ? text.substring(0, 77) + '...' : text;
+      console.log(`[${nid(node)}] "${node.name || ''}" → ${JSON.stringify(preview)}`);
+    }
+  }
+
+  // Override text per slide
+  console.log('\n=== Override text (per slide instance) ===\n');
+  const slides = deck.getActiveSlides();
+
+  for (const slide of slides) {
+    const inst = deck.getSlideInstance(nid(slide));
+    if (!inst) continue;
+
+    const symId = inst.symbolData?.symbolID;
+    const symStr = symId ? `${symId.sessionID}:${symId.localID}` : '?';
+    console.log(`SLIDE "${slide.name || nid(slide)}" → INSTANCE (${nid(inst)}) sym=${symStr}`);
+
+    const overrides = inst.symbolData?.symbolOverrides || [];
+    for (const ov of overrides) {
+      const path = (ov.guidPath?.guids || [])
+        .map(g => `${g.sessionID}:${g.localID}`).join(' → ');
+
+      if (ov.textData?.characters) {
+        const text = ov.textData.characters;
+        const preview = text.length > 80 ? text.substring(0, 77) + '...' : text;
+        console.log(`  ${path}  TEXT: ${JSON.stringify(preview)}`);
+      }
+      if (ov.fillPaints?.length) {
+        const paint = ov.fillPaints[0];
+        if (paint.type === 'IMAGE' && paint.image?.hash) {
+          const hex = hashToHex(paint.image.hash);
+          console.log(`  ${path}  IMAGE: ${hex} (${paint.originalImageWidth}×${paint.originalImageHeight})`);
+        }
+      }
+    }
+    console.log('');
+  }
+}

package/commands/remove-slide.mjs

@@ -0,0 +1,47 @@
+/**
+ * remove-slide — Mark slides as REMOVED.
+ *
+ * Usage: node cli.mjs remove-slide <file.deck> -o <output.deck> --slide <id|name> [--slide ...]
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid, removeNode } from '../lib/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRefs = Array.isArray(flags.slide) ? flags.slide : (flags.slide ? [flags.slide] : []);
+
+  if (!file || !outPath || slideRefs.length === 0) {
+    console.error('Usage: remove-slide <file.deck> -o <out.deck> --slide <id|name> [--slide ...]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  let removed = 0;
+  for (const ref of slideRefs) {
+    const slide = findSlide(deck, ref);
+    if (!slide) { console.error(`Slide not found: ${ref}`); continue; }
+
+    removeNode(slide);
+    console.log(`  REMOVED slide "${slide.name || ''}" (${nid(slide)})`);
+
+    // Also remove child instances
+    for (const child of deck.getChildren(nid(slide))) {
+      removeNode(child);
+      console.log(`    REMOVED child ${child.type} (${nid(child)})`);
+    }
+    removed++;
+  }
+
+  console.log(`\nRemoved ${removed} slide(s)`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function findSlide(deck, ref) {
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+  return deck.getActiveSlides().find(s => s.name === ref);
+}

package/commands/roundtrip.mjs

@@ -0,0 +1,37 @@
+/**
+ * roundtrip — Decode and re-encode a deck with zero changes (pipeline validation).
+ *
+ * Usage: node cli.mjs roundtrip <file.deck> -o <output.deck>
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+
+  if (!file || !outPath) {
+    console.error('Usage: roundtrip <file.deck> -o <output.deck>');
+    process.exit(1);
+  }
+
+  console.log(`Reading: ${file}`);
+  const deck = await FigDeck.fromDeckFile(file);
+
+  const slides = deck.getSlides();
+  const active = deck.getActiveSlides();
+  const instances = deck.getInstances();
+  const symbols = deck.getSymbols();
+
+  console.log(`  Nodes: ${deck.message.nodeChanges.length}`);
+  console.log(`  Slides: ${active.length} active / ${slides.length} total`);
+  console.log(`  Instances: ${instances.length}`);
+  console.log(`  Symbols: ${symbols.length}`);
+  console.log(`  Blobs: ${deck.message.blobs?.length || 0}`);
+  console.log(`  Chunks: ${deck.rawFiles.length}`);
+  if (deck.deckMeta) console.log(`  Deck name: ${deck.deckMeta.file_name || '(unknown)'}`);
+
+  console.log(`\nEncoding...`);
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+  console.log(`\nRoundtrip complete. Open in Figma to verify.`);
+}

package/commands/update-text.mjs

@@ -0,0 +1,79 @@
+/**
+ * update-text — Apply text overrides to an instance on a slide.
+ *
+ * Usage: node cli.mjs update-text <file.deck> -o <output.deck> --slide <id|name> --set key=value [--set key=value ...]
+ */
+import { FigDeck } from '../lib/fig-deck.mjs';
+import { nid, parseId } from '../lib/node-helpers.mjs';
+
+export async function run(args, flags) {
+  const file = args[0];
+  const outPath = flags.o || flags.output;
+  const slideRef = flags.slide;
+  const sets = Array.isArray(flags.set) ? flags.set : (flags.set ? [flags.set] : []);
+
+  if (!file || !outPath || !slideRef || sets.length === 0) {
+    console.error('Usage: update-text <file.deck> -o <out.deck> --slide <id|name> --set key=value [--set ...]');
+    process.exit(1);
+  }
+
+  const deck = await FigDeck.fromDeckFile(file);
+
+  // Find slide by ID or name
+  const slide = findSlide(deck, slideRef);
+  if (!slide) { console.error(`Slide not found: ${slideRef}`); process.exit(1); }
+
+  const inst = deck.getSlideInstance(nid(slide));
+  if (!inst) { console.error(`No instance found on slide ${nid(slide)}`); process.exit(1); }
+
+  // Ensure symbolOverrides exists
+  if (!inst.symbolData) inst.symbolData = {};
+  if (!inst.symbolData.symbolOverrides) inst.symbolData.symbolOverrides = [];
+
+  let updated = 0;
+  for (const pair of sets) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx < 0) { console.error(`Invalid --set format: ${pair}`); continue; }
+    const keyStr = pair.substring(0, eqIdx);
+    let value = pair.substring(eqIdx + 1);
+
+    // Empty string → space (prevents Figma crash)
+    if (value === '') value = ' ';
+
+    const key = parseId(keyStr);
+    const overrides = inst.symbolData.symbolOverrides;
+
+    // Find existing override for this key
+    const existing = overrides.find(o =>
+      o.guidPath?.guids?.length === 1 &&
+      o.guidPath.guids[0].sessionID === key.sessionID &&
+      o.guidPath.guids[0].localID === key.localID &&
+      o.textData
+    );
+
+    if (existing) {
+      existing.textData.characters = value;
+    } else {
+      overrides.push({
+        guidPath: { guids: [key] },
+        textData: { characters: value },
+      });
+    }
+    updated++;
+    console.log(`  ${keyStr} → ${JSON.stringify(value.substring(0, 60))}`);
+  }
+
+  console.log(`Updated ${updated} text override(s) on slide "${slide.name || nid(slide)}"`);
+
+  const bytes = await deck.saveDeck(outPath);
+  console.log(`Saved: ${outPath} (${bytes} bytes)`);
+}
+
+function findSlide(deck, ref) {
+  // Try as ID first
+  const byId = deck.getNode(ref);
+  if (byId?.type === 'SLIDE') return byId;
+
+  // Try as name
+  return deck.getActiveSlides().find(s => s.name === ref);
+}