@figtools/cli 0.1.0 → 0.2.1

package/README.es.md

@@ -72,10 +72,14 @@ Omite el mensaje `Resolving N URL(s)...` en stderr — útil si estás capturand
 | `--format` | `json`, `markdown` | `json` | Formato de salida |
 | `--output` | ruta de archivo o carpeta | stdout (json) / `.` (markdown) | Dónde escribir el resultado |
 | `--quiet` | — | `false` | Omite el mensaje de progreso en stderr |
+| `--help`, `-h` | — | — | Imprime información de uso y termina |
+| `--version`, `-v` | — | — | Imprime la versión del CLI y termina |
 
 ## Troubleshooting
 
 - **`Error: unsupported extension "<ext>"`**: con `--format markdown`, `--output` siempre se trata como una carpeta. Con `--format json`, solo se acepta una ruta terminada en `.json` o sin extensión (tratada como carpeta); cualquier otra extensión falla explícitamente.
+- **`--format` argument 'xml' is invalid. Allowed choices are json, markdown.`**: un valor de `--format` no soportado se rechaza explícitamente en vez de caer en `json` en silencio.
+- **`error: unknown option '--foo'`**: una flag no reconocida se rechaza explícitamente en vez de ser ignorada en silencio.
 - **El proceso termina con código `1` pero imprimió resultados**: significa que al menos una de las URLs falló — revisa el bloque `URLs with errors:` al final de stderr para ver el código (`FigmaScraperErrorCode`) y mensaje de cada una. Ver la tabla de errores en el [README de `@figtools/core`](../core/README.es.md#errores-posibles).
 - **`figtools login` no avanza**: la ventana de Chromium espera indefinidamente a que termines el login manual; confirma que llegaste a `https://www.figma.com/files/...` antes de cerrar la ventana.
 

package/README.md

@@ -72,10 +72,14 @@ Omits the `Resolving N URL(s)...` message on stderr — useful if you're capturi
 | `--format` | `json`, `markdown` | `json` | Output format |
 | `--output` | file or folder path | stdout (json) / `.` (markdown) | Where to write the result |
 | `--quiet` | — | `false` | Omits the progress message on stderr |
+| `--help`, `-h` | — | — | Prints usage information and exits |
+| `--version`, `-v` | — | — | Prints the CLI's version and exits |
 
 ## Troubleshooting
 
 - **`Error: unsupported extension "<ext>"`**: with `--format markdown`, `--output` is always treated as a folder. With `--format json`, only a path ending in `.json` or with no extension (treated as a folder) is accepted; any other extension fails explicitly.
+- **`--format` argument 'xml' is invalid. Allowed choices are json, markdown.**: an unsupported `--format` value is rejected explicitly instead of silently falling back to `json`.
+- **`error: unknown option '--foo'`**: an unrecognized flag is rejected explicitly instead of being silently ignored.
 - **The process exits with code `1` but printed results**: at least one of the URLs failed — check the `URLs with errors:` block at the end of stderr for each one's code (`FigmaScraperErrorCode`) and message. See the error table in the [`@figtools/core` README](../core#possible-errors).
 - **`figtools login` doesn't progress**: the Chromium window waits indefinitely for you to finish the manual login; confirm you reached `https://www.figma.com/files/...` before closing the window.
 

package/dist/cli.d.ts

@@ -7,15 +7,22 @@ export interface ParsedArgs {
     command?: "login";
 }
 type ParseArgsError = {
-    code: "VALIDATION_NO_URLS" | "VALIDATION_UNSUPPORTED_EXTENSION";
+    code: "VALIDATION_NO_URLS" | "VALIDATION_UNSUPPORTED_EXTENSION" | "COMMANDER_ERROR";
     message: string;
 };
+type ParseArgsInfo = {
+    code: "HELP_DISPLAYED" | "VERSION_DISPLAYED";
+    output: string;
+};
 export type ParseArgsResult = {
     ok: true;
     value: ParsedArgs;
 } | {
     ok: false;
     error: ParseArgsError;
+} | {
+    ok: false;
+    info: ParseArgsInfo;
 };
 export type OutputTarget = {
     kind: "stdout";

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAYA,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,CAAC;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,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,CAAC;AAEzC,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;AAEzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA+BzD;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":"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"}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 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 { mkdir, writeFile } from "node:fs/promises";
 async function resolveAll(core, urls) {
@@ -54,8 +55,28 @@ function slugifyWithCollisions(names) {
 function isFigmaPage(result) {
     return "nodes" in result;
 }
+function formatPaint(paint) {
+    const { r, g, b, a } = paint.color;
+    const color = `rgba(${r}, ${g}, ${b}, ${a})`;
+    return paint.styleName ? `${paint.styleName} (${color})` : color;
+}
+function metadataLines(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 (typography) {
+        for (const [key, value] of Object.entries(typography))if (null != value) lines.push(`typography.${key}: ${value}`);
+    }
+    return lines;
+}
 function leafContent(node) {
-    return `# ${node.name}\n\ntype: ${node.type}\n`;
+    return `# ${node.name}\n\n${metadataLines(node).join("\n")}\n`;
 }
 function containerContent(name, children, childSlugs) {
     const links = children.map((child, i)=>{
@@ -97,28 +118,89 @@ async function writeAsMarkdownTree(fileKey, result, options) {
     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]);
 }
-function parseArgs(argv) {
-    if ("login" === argv[0]) return {
-        ok: true,
-        value: {
+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."}');
+function createProgram() {
+    let output = "";
+    let parsed;
+    const program = new Command().name("figtools").description(package_namespaceObject.h_).version(package_namespaceObject.rE, "-v, --version").exitOverride().configureOutput({
+        writeOut: (str)=>{
+            output += str;
+        },
+        writeErr: (str)=>{
+            output += str;
+        }
+    });
+    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)=>{
+        parsed = {
+            urls,
+            format: opts.format,
+            outputPath: opts.output,
+            quiet: opts.quiet
+        };
+    });
+    resolveCommand.exitOverride();
+    const loginCommand = program.command("login").description("Force a new interactive login, discarding any saved session").action(()=>{
+        parsed = {
             command: "login",
             urls: [],
             format: "json",
             quiet: false
-        }
+        };
+    });
+    loginCommand.exitOverride();
+    return {
+        program,
+        getParsed: ()=>parsed,
+        getOutput: ()=>output
     };
-    let format = "json";
-    let outputPath;
-    let quiet = false;
-    const urls = [];
-    for(let i = 0; i < argv.length; i++){
-        const arg = argv[i];
-        if ("--format" === arg) format = argv[++i];
-        else if ("--output" === arg) outputPath = argv[++i];
-        else if ("--quiet" === arg) quiet = true;
-        else if (!arg.startsWith("--")) urls.push(arg);
+}
+function parseFormat(value) {
+    if ("json" !== value && "markdown" !== value) throw new InvalidArgumentError("Allowed choices are json, markdown.");
+    return value;
+}
+function parseArgs(argv) {
+    const { program, getParsed, getOutput } = createProgram();
+    try {
+        program.parse(argv, {
+            from: "user"
+        });
+    } catch (err) {
+        if (err instanceof CommanderError) {
+            if ("commander.helpDisplayed" === err.code) return {
+                ok: false,
+                info: {
+                    code: "HELP_DISPLAYED",
+                    output: getOutput()
+                }
+            };
+            if ("commander.version" === err.code) return {
+                ok: false,
+                info: {
+                    code: "VERSION_DISPLAYED",
+                    output: getOutput()
+                }
+            };
+            if ("commander.missingArgument" === err.code) return {
+                ok: false,
+                error: {
+                    code: "VALIDATION_NO_URLS",
+                    message: "At least one Figma URL is required"
+                }
+            };
+            return {
+                ok: false,
+                error: {
+                    code: "COMMANDER_ERROR",
+                    message: getOutput() || err.message
+                }
+            };
+        }
+        throw err;
     }
-    if (0 === urls.length) return {
+    const value = getParsed();
+    if (!value) return {
         ok: false,
         error: {
             code: "VALIDATION_NO_URLS",
@@ -127,12 +209,7 @@ function parseArgs(argv) {
     };
     return {
         ok: true,
-        value: {
-            urls,
-            format,
-            outputPath,
-            quiet
-        }
+        value
     };
 }
 function decideOutputTarget(outputPath, format) {
@@ -166,6 +243,10 @@ function extractFileKey(url) {
 }
 async function main(argv) {
     const parsed = parseArgs(argv);
+    if (!parsed.ok && "info" in parsed) {
+        process.stdout.write(parsed.info.output);
+        process.exit(0);
+    }
     if (!parsed.ok) {
         process.stderr.write(`Error: ${parsed.error.message}\n`);
         process.exit(1);

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,EAAwB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAoCD,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,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figtools/cli",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -34,6 +34,7 @@
     "access": "public"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "playwright": "^1.61.1",
     "@figtools/core": "0.1.0"
   },