@figtools/cli 0.2.1 → 0.3.1

package/dist/cli.d.ts

@@ -1,8 +1,10 @@
 export type OutputFormat = "json" | "markdown";
+export type ImageFormat = "webp" | "png" | "jpg";
 export interface ParsedArgs {
     urls: string[];
     format: OutputFormat;
     outputPath?: string;
+    imageFormat: ImageFormat;
     quiet: boolean;
     command?: "login";
 }

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,oBAAoB,GAAG,kCAAkC,GAAG,iBAAiB,CAAC;IACpF,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAMF,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AA8DzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAmCzD;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,YAAY,GACnB,YAAY,CAad"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,KAAK,cAAc,GAAG;IACpB,IAAI,EAAE,oBAAoB,GAAG,kCAAkC,GAAG,iBAAiB,CAAC;IACpF,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAMF,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACpC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEvC,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAuEzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAmCzD;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,YAAY,GACnB,YAAY,CAad"}

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
+import { realpathSync } from "node:fs";
 import { extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError, InvalidArgumentError } from "commander";
-import { CookieSessionStore, PlaywrightFigmaGateway, PlaywrightLogin, createFigmaScraperCore } from "@figtools/core";
+import { CookieSessionStore, PlaywrightFigmaNodeSource, PlaywrightLogin, createFigmaScraperCore } from "@figtools/core";
 import { mkdir, writeFile } from "node:fs/promises";
 async function resolveAll(core, urls) {
     const sessionResult = await core.ensureSession();
@@ -55,70 +56,148 @@ function slugifyWithCollisions(names) {
 function isFigmaPage(result) {
     return "nodes" in result;
 }
+function colorToHex({ r, g, b, a }) {
+    const hex = [
+        r,
+        g,
+        b
+    ].map((c)=>Math.round(c).toString(16).padStart(2, "0")).join("").toUpperCase();
+    return a < 1 ? `#${hex} ${Math.round(100 * a)}%` : `#${hex}`;
+}
 function formatPaint(paint) {
-    const { r, g, b, a } = paint.color;
-    const color = `rgba(${r}, ${g}, ${b}, ${a})`;
-    return paint.styleName ? `${paint.styleName} (${color})` : color;
+    const hex = colorToHex(paint.color);
+    return paint.styleName ? `${hex} (${paint.styleName})` : hex;
+}
+function formatEffect(effect) {
+    const color = effect.color ? colorToHex(effect.color) : "";
+    return [
+        effect.type,
+        `x=${effect.x}`,
+        `y=${effect.y}`,
+        `blur=${effect.blur}`,
+        `spread=${effect.spread}`,
+        color
+    ].filter(Boolean).join(" ");
 }
-function metadataLines(node) {
+function formatSize(value, mode) {
+    if ("Fill" === mode) return null !== value ? `Fill (${value}px)` : "Fill";
+    if (null === value) return null;
+    if ("Hug" === mode) return `Hug (${value}px)`;
+    if ("Fixed" === mode) return `Fixed (${value}px)`;
+    return `${value}px`;
+}
+function nodePropertyLines(node) {
     const lines = [
         `type: ${node.type}`
     ];
-    if (null !== node.position.x && null !== node.position.y) lines.push(`position: x=${node.position.x}, y=${node.position.y}`);
-    if (null !== node.size.width && null !== node.size.height) lines.push(`size: width=${node.size.width}, height=${node.size.height}`);
-    const { typography, fills, strokes, ...rest } = node.styles;
-    for (const [key, value] of Object.entries(rest))if (void 0 !== value) lines.push(`${key}: ${value}`);
-    if (fills && fills.length > 0) lines.push(`fills: ${fills.map(formatPaint).join(", ")}`);
-    if (strokes && strokes.length > 0) lines.push(`strokes: ${strokes.map(formatPaint).join(", ")}`);
+    if (!node.visible) lines.push("visible: false");
+    const { flow, widthSizing, heightSizing, fills, strokes, strokeWeight, strokeSide, cornerRadius, effects, opacity, paddingTop, paddingRight, paddingBottom, paddingLeft, itemSpacing, typography } = node.styles;
+    const layoutLines = [];
+    if (flow) layoutLines.push(`Flow: ${flow}`);
+    if (null !== node.position.x && null !== node.position.y) layoutLines.push(`Position: x=${node.position.x} y=${node.position.y}`);
+    const w = formatSize(node.size.width, widthSizing);
+    const h = formatSize(node.size.height, heightSizing);
+    if (null !== w) layoutLines.push(`Width: ${w}`);
+    if (null !== h) layoutLines.push(`Height: ${h}`);
+    if (void 0 !== paddingTop) layoutLines.push(`Padding top: ${paddingTop}px`);
+    if (void 0 !== paddingRight) layoutLines.push(`Padding right: ${paddingRight}px`);
+    if (void 0 !== paddingBottom) layoutLines.push(`Padding bottom: ${paddingBottom}px`);
+    if (void 0 !== paddingLeft) layoutLines.push(`Padding left: ${paddingLeft}px`);
+    if (void 0 !== itemSpacing) layoutLines.push(`Gap: ${itemSpacing}px`);
+    if (void 0 !== opacity) layoutLines.push(`Opacity: ${opacity}%`);
+    if (layoutLines.length > 0) lines.push("", "## Layout", ...layoutLines);
+    if (fills && fills.length > 0) lines.push("", "## Fill", ...fills.map(formatPaint));
+    const borderLines = [];
+    if (void 0 !== strokeWeight || strokes && strokes.length > 0) {
+        const label = strokeSide ? `Border ${strokeSide.toLowerCase()}` : "Border";
+        const parts = [];
+        if (void 0 !== strokeWeight) parts.push(`${strokeWeight}px`);
+        if (strokes && strokes.length > 0) parts.push(strokes.map(formatPaint).join(", "));
+        borderLines.push(`${label}: ${parts.join(" ")}`);
+    }
+    if (void 0 !== cornerRadius) borderLines.push(`Radius: ${cornerRadius}px`);
+    if (effects && effects.length > 0) for (const effect of effects)borderLines.push(formatEffect(effect));
+    if (borderLines.length > 0) lines.push("", "## Border", ...borderLines);
     if (typography) {
-        for (const [key, value] of Object.entries(typography))if (null != value) lines.push(`typography.${key}: ${value}`);
+        const typoLines = [];
+        if (typography.styleName) typoLines.push(`Text style: ${typography.styleName}`);
+        if (typography.fontFamily) typoLines.push(`Font: ${typography.fontFamily}`);
+        if (typography.style) typoLines.push(`Style: ${typography.style}`);
+        if (null !== typography.fontWeight && void 0 !== typography.fontWeight) typoLines.push(`Weight: ${typography.fontWeight}`);
+        if (null !== typography.fontSize && void 0 !== typography.fontSize) typoLines.push(`Size: ${typography.fontSize}px`);
+        if (null !== typography.lineHeightPx && void 0 !== typography.lineHeightPx) typoLines.push(`Line height: ${typography.lineHeightPx}px`);
+        if (void 0 !== typography.letterSpacing) typoLines.push(`Letter spacing: ${typography.letterSpacing}`);
+        if (typography.textAlignHorizontal) typoLines.push(`Align: ${typography.textAlignHorizontal}`);
+        if (typography.textAlignVertical) typoLines.push(`Vertical align: ${typography.textAlignVertical}`);
+        if (typoLines.length > 0) lines.push("", "## Typography", ...typoLines);
     }
+    if (null !== node.characters) lines.push("", "## Content", node.characters);
     return lines;
 }
-function leafContent(node) {
-    return `# ${node.name}\n\n${metadataLines(node).join("\n")}\n`;
+function mediaHead(node, slug, format) {
+    const lines = [];
+    if (null !== node.image) lines.push(`![${node.name}](./${slug}.${format})`);
+    if (null !== node.svgCode) lines.push(`[SVG](./${slug}.svg)`);
+    return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
 }
-function containerContent(name, children, childSlugs) {
-    const links = children.map((child, i)=>{
-        const slug = childSlugs[i];
-        const href = 0 === child.children.length ? `${slug}.md` : `${slug}/index.md`;
-        return `- [${child.name}](${href})`;
-    }).join("\n");
+function nodeContent(node, slug, format) {
+    return `# ${node.name}${mediaHead(node, slug, format)}\n\n${nodePropertyLines(node).join("\n")}\n`;
+}
+function pageContent(name, nodes, childSlugs) {
+    const links = nodes.map((node, i)=>`- [${node.name}](${childSlugs[i]}/index.md)`).join("\n");
     return `# ${name}\n\n${links}\n`;
 }
-async function writeChildNode(node, parentDir, slug) {
-    if (0 === node.children.length) return void await writeFile(join(parentDir, `${slug}.md`), leafContent(node), "utf8");
+function containerContent(node, childSlugs, slug, format) {
+    const meta = nodePropertyLines(node);
+    const links = node.children.map((child, i)=>`- [${child.name}](${childSlugs[i]}/index.md)`).join("\n");
+    return `# ${node.name}${mediaHead(node, slug, format)}\n\n${meta.join("\n")}\n\n## Children\n\n${links}\n`;
+}
+async function writeNodeAssets(node, dir, slug, format) {
+    if (null !== node.image) await writeFile(join(dir, `${slug}.${format}`), node.image);
+    if (null !== node.svgCode) await writeFile(join(dir, `${slug}.svg`), node.svgCode, "utf8");
+}
+async function writeChildNode(node, parentDir, slug, options) {
     const nodeDir = join(parentDir, slug);
     await mkdir(nodeDir, {
         recursive: true
     });
+    const format = options.imageFormat ?? "png";
+    await writeNodeAssets(node, nodeDir, slug, format);
+    if (0 === node.children.length) return void await writeFile(join(nodeDir, "index.md"), nodeContent(node, slug, format), "utf8");
     const childSlugs = slugifyWithCollisions(node.children.map((c)=>c.name));
-    await writeFile(join(nodeDir, "index.md"), containerContent(node.name, node.children, childSlugs), "utf8");
-    for(let i = 0; i < node.children.length; i++)await writeChildNode(node.children[i], nodeDir, childSlugs[i]);
+    await writeFile(join(nodeDir, "index.md"), containerContent(node, childSlugs, slug, format), "utf8");
+    for(let i = 0; i < node.children.length; i++)await writeChildNode(node.children[i], nodeDir, childSlugs[i], options);
 }
 async function writeAsMarkdownTree(fileKey, result, options) {
     const fileKeyDir = join(options.outputDir, fileKey);
     await mkdir(fileKeyDir, {
         recursive: true
     });
+    const format = options.imageFormat ?? "png";
     if (isFigmaPage(result)) {
         const childSlugs = slugifyWithCollisions(result.nodes.map((n)=>n.name));
-        await writeFile(join(fileKeyDir, "index.md"), containerContent(result.name, result.nodes, childSlugs), "utf8");
-        for(let i = 0; i < result.nodes.length; i++)await writeChildNode(result.nodes[i], fileKeyDir, childSlugs[i]);
+        await writeFile(join(fileKeyDir, "index.md"), pageContent(result.name, result.nodes, childSlugs), "utf8");
+        for(let i = 0; i < result.nodes.length; i++)await writeChildNode(result.nodes[i], fileKeyDir, childSlugs[i], options);
         return;
     }
+    const [slug] = slugifyWithCollisions([
+        result.name
+    ]);
     if (0 === result.children.length) {
-        const [slug] = slugifyWithCollisions([
-            result.name
-        ]);
-        await writeFile(join(fileKeyDir, `${slug}.md`), leafContent(result), "utf8");
+        const nodeDir = join(fileKeyDir, slug);
+        await mkdir(nodeDir, {
+            recursive: true
+        });
+        await writeNodeAssets(result, nodeDir, slug, format);
+        await writeFile(join(nodeDir, "index.md"), nodeContent(result, slug, format), "utf8");
         return;
     }
+    await writeNodeAssets(result, fileKeyDir, slug, format);
     const childSlugs = slugifyWithCollisions(result.children.map((c)=>c.name));
-    await writeFile(join(fileKeyDir, "index.md"), containerContent(result.name, result.children, childSlugs), "utf8");
-    for(let i = 0; i < result.children.length; i++)await writeChildNode(result.children[i], fileKeyDir, childSlugs[i]);
+    await writeFile(join(fileKeyDir, "index.md"), containerContent(result, childSlugs, slug, format), "utf8");
+    for(let i = 0; i < result.children.length; i++)await writeChildNode(result.children[i], fileKeyDir, childSlugs[i], options);
 }
-var package_namespaceObject = /*#__PURE__*/ JSON.parse('{"rE":"0.2.1","h_":"Resolves one or more Figma URLs from the command line and writes the result as JSON or as a navigable markdown tree meant to be used as a data source by an LLM."}');
+var package_namespaceObject = /*#__PURE__*/ JSON.parse('{"rE":"0.3.1","h_":"Resolves one or more Figma URLs from the command line and writes the result as JSON or as a navigable markdown tree meant to be used as a data source by an LLM."}');
 function createProgram() {
     let output = "";
     let parsed;
@@ -132,11 +211,12 @@ function createProgram() {
     });
     const resolveCommand = program.command("resolve", {
         isDefault: true
-    }).description("Resolve one or more Figma URLs and write the result").argument("<urls...>", "One or more Figma URLs to resolve").option("--format <format>", "Output format (json or markdown)", parseFormat, "json").option("--output <path>", "File or directory to write the result to").option("--quiet", "Suppress progress messages on stderr", false).action((urls, opts)=>{
+    }).description("Resolve one or more Figma URLs and write the result").argument("<urls...>", "One or more Figma URLs to resolve").option("--format <format>", "Output format (json or markdown)", parseFormat, "json").option("--image-format <format>", "Image format for node previews (webp, png, jpg)", parseImageFormat, "png").option("--output <path>", "File or directory to write the result to").option("--quiet", "Suppress progress messages on stderr", false).action((urls, opts)=>{
         parsed = {
             urls,
             format: opts.format,
             outputPath: opts.output,
+            imageFormat: opts.imageFormat,
             quiet: opts.quiet
         };
     });
@@ -146,6 +226,7 @@ function createProgram() {
             command: "login",
             urls: [],
             format: "json",
+            imageFormat: "png",
             quiet: false
         };
     });
@@ -160,6 +241,10 @@ function parseFormat(value) {
     if ("json" !== value && "markdown" !== value) throw new InvalidArgumentError("Allowed choices are json, markdown.");
     return value;
 }
+function parseImageFormat(value) {
+    if ("webp" !== value && "png" !== value && "jpg" !== value) throw new InvalidArgumentError("Allowed choices are webp, png, jpg.");
+    return value;
+}
 function parseArgs(argv) {
     const { program, getParsed, getOutput } = createProgram();
     try {
@@ -251,11 +336,11 @@ async function main(argv) {
         process.stderr.write(`Error: ${parsed.error.message}\n`);
         process.exit(1);
     }
-    const { command, urls, format, outputPath, quiet } = parsed.value;
+    const { command, urls, format, outputPath, imageFormat, quiet } = parsed.value;
     const core = createFigmaScraperCore({
         sessionStore: new CookieSessionStore(),
         interactiveLogin: new PlaywrightLogin(),
-        gateway: new PlaywrightFigmaGateway()
+        gateway: new PlaywrightFigmaNodeSource()
     });
     if ("login" === command) {
         const result = await core.reauthenticate();
@@ -283,7 +368,8 @@ async function main(argv) {
         if ("markdown" === format) {
             const dir = "directory" === outputTarget.kind ? outputTarget.path : ".";
             await writeAsMarkdownTree(fileKey, result.value, {
-                outputDir: dir
+                outputDir: dir,
+                imageFormat
             });
         } else {
             const writePath = "file" === outputTarget.kind ? outputTarget.path : "directory" === outputTarget.kind ? outputTarget.path : void 0;
@@ -299,5 +385,13 @@ async function main(argv) {
     }
     process.exit(hadFailure ? 1 : 0);
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+function isMainModule() {
+    if (!process.argv[1]) return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    } catch  {
+        return false;
+    }
+}
+if (isMainModule()) main(process.argv.slice(2));
 export { decideOutputTarget, parseArgs };

package/dist/output/markdown-writer.d.ts

@@ -1,6 +1,7 @@
 import type { FigmaScrapeResult } from "@figtools/core";
 export interface MarkdownWriterOptions {
     outputDir: string;
+    imageFormat?: "webp" | "png" | "jpg";
 }
 export declare function writeAsMarkdownTree(fileKey: string, result: FigmaScrapeResult, options: MarkdownWriterOptions): Promise<void>;
 //# sourceMappingURL=markdown-writer.d.ts.map

package/dist/output/markdown-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-writer.d.ts","sourceRoot":"","sources":["../../src/output/markdown-writer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoC,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG1F,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAyED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgCf"}
+{"version":3,"file":"markdown-writer.d.ts","sourceRoot":"","sources":["../../src/output/markdown-writer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiD,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGvG,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;CACtC;AA8KD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figtools/cli",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Resolves one or more Figma URLs from the command line and writes the result as JSON or as a navigable markdown tree meant to be used as a data source by an LLM.",
   "keywords": [
     "figma",
@@ -36,7 +36,7 @@
   "dependencies": {
     "commander": "^15.0.0",
     "playwright": "^1.61.1",
-    "@figtools/core": "0.1.0"
+    "@figtools/core": "0.2.0"
   },
   "devDependencies": {
     "@rslib/core": "^0.23.2",