@grida/refig 0.0.2 → 0.0.3

package/README.md

@@ -194,8 +194,9 @@ pnpm add -g @grida/refig
 Or run without installing:
 
 ```sh
-npx @grida/refig <input> --node <node-id> --out <path>
-pnpm dlx @grida/refig <input> --node <node-id> --out <path>
+# Instant usage (writes to OS temp dir; output path printed)
+npx @grida/refig <input> --node <node-id> --format png
+pnpm dlx @grida/refig <input> --export-all
 ```
 
 ### Usage
@@ -211,44 +212,50 @@ Using a directory avoids passing the document and images separately.
 
 ```sh
 # Single node (default)
-refig <input> --node <node-id> --out <path> [options]
+# - Without --out: writes to OS temp dir (requires --format)
+# - With --out: format inferred from file extension unless --format is provided
+refig <input> --node <node-id> --format <fmt> [options]
+refig <input> --node <node-id> --out <path> [--format <fmt>] [options]
 
 # With images directory (REST JSON only; IMAGE fills rendered from local files)
-refig <input> --images <dir> --node <node-id> --out <path>
+refig <input> --images <dir> --node <node-id> --format <fmt> [options]
+refig <input> --images <dir> --node <node-id> --out <path> [--format <fmt>] [options]
 
 # Directory input: document.json + images/ under one folder
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 
 # Export all nodes that have exportSettings (REST JSON or .fig)
-refig <input> --export-all --out <output-dir>
+refig <input> --export-all [--out <output-dir>]
 ```
 
 ### Examples
 
 ```sh
-# Render a node from a .fig file
-refig ./design.fig --node "1:23" --out ./out.png
-
-# Render from REST API JSON
-refig ./figma-response.json --node "1:23" --out ./out.svg
+# Instant usage: omit --out to write to OS temp directory (output path printed)
+refig ./design.fig --node "1:23" --format png
+refig ./figma-response.json --node "1:23" --format svg
 
 # Directory with document.json (and optionally images/): one path instead of response + --images
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 # (my-figma-export/document.json, my-figma-export/images/)
 
 # Explicit images directory (when not using a project directory)
-refig ./figma-response.json --images ./downloaded-images --node "1:23" --out ./out.png
+refig ./figma-response.json --images ./downloaded-images --node "1:23" --format png
 
 # Export all: render every node that has export settings (see below)
-refig ./figma-response.json --export-all --out ./exports
-refig ./design.fig --export-all --out ./exports
+refig ./figma-response.json --export-all
+refig ./design.fig --export-all
 
 # Scale 2x, custom dimensions
-refig ./design.fig --node "1:23" --out ./out.png --width 512 --height 512 --scale 2
+refig ./design.fig --node "1:23" --format png --width 512 --height 512 --scale 2
+
+# Deterministic output: provide --out (useful for CI or saving into a known path)
+refig ./design.fig --node "1:23" --out ./out.png
+refig ./figma-response.json --export-all --out ./exports
 
 # No-install (run without installing)
-npx @grida/refig ./design.fig --node "1:23" --out ./out.png
-pnpm dlx @grida/refig ./design.fig --node "1:23" --out ./out.png
+npx @grida/refig ./design.fig --node "1:23" --format png
+pnpm dlx @grida/refig ./design.fig --export-all
 ```
 
 ### Quick test via `figma_archive.py` (REST API → `document.json` + `images/`)
@@ -275,10 +282,10 @@ This writes:
 
 ```sh
 # Single node
-refig ./my-figma-export --node "1:23" --out ./out.png
+refig ./my-figma-export --node "1:23" --format png
 
 # Or export everything with Figma export presets
-refig ./my-figma-export --export-all --out ./exports
+refig ./my-figma-export --export-all
 ```
 
 ### Export all (`--export-all`)
@@ -291,17 +298,17 @@ With **`--export-all`**, refig walks the document and renders every node that ha
 
 ### Flags
 
-| Flag             | Required | Default                         | Description                                                                                   |
-| ---------------- | -------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
-| `<input>`        | yes      |                                 | Path to `.fig`, JSON file, or directory containing `document.json` (and optionally `images/`) |
-| `--images <dir>` | no       |                                 | Directory of image assets for REST document (ignored if `<input>` is a dir with `images/`)    |
-| `--node <id>`    | yes\*    |                                 | Figma node ID to render (\*omit when using `--export-all`)                                    |
-| `--out <path>`   | yes      |                                 | Output file path (single node) or output directory (`--export-all`)                           |
-| `--export-all`   | no       |                                 | Export every node with exportSettings (REST JSON or .fig); `--out` is a directory             |
-| `--format <fmt>` | no       | inferred from `--out` extension | `png`, `jpeg`, `webp`, `pdf`, `svg` (single-node only)                                        |
-| `--width <px>`   | no       | `1024`                          | Viewport width (single-node only)                                                             |
-| `--height <px>`  | no       | `1024`                          | Viewport height (single-node only)                                                            |
-| `--scale <n>`    | no       | `1`                             | Raster scale factor (single-node only)                                                        |
+| Flag             | Required | Default                         | Description                                                                                                                                                                          |
+| ---------------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `<input>`        | yes      |                                 | Path to `.fig`, JSON file, or directory containing `document.json` (and optionally `images/`)                                                                                        |
+| `--images <dir>` | no       |                                 | Directory of image assets for REST document (ignored if `<input>` is a dir with `images/`)                                                                                           |
+| `--node <id>`    | yes\*    |                                 | Figma node ID to render (\*omit when using `--export-all`)                                                                                                                           |
+| `--out <path>`   | no       | OS temp dir when omitted        | Output file path (single node) or output directory (`--export-all`). When omitted, writes to the OS temp directory (valid with `--export-all` or with both `--format` and `--node`). |
+| `--export-all`   | no       |                                 | Export every node with exportSettings (REST JSON or .fig); `--out` is a directory                                                                                                    |
+| `--format <fmt>` | no       | inferred from `--out` extension | `png`, `jpeg`, `webp`, `pdf`, `svg` (single-node only; required when `--out` is omitted)                                                                                             |
+| `--width <px>`   | no       | `1024`                          | Viewport width (single-node only)                                                                                                                                                    |
+| `--height <px>`  | no       | `1024`                          | Viewport height (single-node only)                                                                                                                                                   |
+| `--scale <n>`    | no       | `1`                             | Raster scale factor (single-node only)                                                                                                                                               |
 
 ## Architecture
 
@@ -332,9 +339,9 @@ REST JSON ───┘
 **CLI** — You can pass images in two ways:
 
 - **`--images <dir>`** — Explicit images directory. Files are keyed by filename without extension (e.g. `a1b2c3d4.png` → ref `a1b2c3d4`). Use when the document is a separate file:  
-  `refig ./figma-response.json --images ./downloaded-images --node "1:23" --out ./out.png`
+  `refig ./figma-response.json --images ./downloaded-images --node "1:23" --format png`
 - **Directory input** — Pass a single directory that contains **`document.json`** (REST response) and optionally **`images/`**. No need to pass `--images` separately:  
-  `refig ./my-figma-export --node "1:23" --out ./out.png`  
+  `refig ./my-figma-export --node "1:23" --format png`  
   (expects `my-figma-export/document.json` and, if present, `my-figma-export/images/`.)
 
 For **`.fig`** input, images are embedded in the file; no extra images directory is needed. For **REST** input, use `--images` or a project directory with `images/` to render IMAGE fills correctly.
@@ -372,7 +379,7 @@ From the package root:
 
 1. Install dependencies and build: `pnpm install && pnpm build`
 2. Link the package so the `refig` CLI is available: `pnpm link --global`
-3. Run the `refig` command from anywhere to test (e.g. `refig ./fixture.json --node "1:1" --out ./out.png`)
+3. Run the `refig` command from anywhere to test (e.g. `refig ./fixture.json --node "1:1" --format png`)
 
 To unlink: `pnpm unlink --global`.
 

package/dist/cli.mjs

@@ -15,9 +15,11 @@ import {
   mkdirSync,
   writeFileSync,
   existsSync,
-  statSync
+  statSync,
+  mkdtempSync
 } from "fs";
 import path from "path";
+import { tmpdir } from "os";
 import { program } from "commander";
 var FORMAT_SET = /* @__PURE__ */ new Set(["png", "jpeg", "webp", "pdf", "svg"]);
 var DOCUMENT_JSON = "document.json";
@@ -175,9 +177,9 @@ async function main() {
   ).argument(
     "<input>",
     "Path to .fig, JSON file (REST API response), or directory containing document.json (and optionally images/)"
-  ).requiredOption(
+  ).option(
     "--out <path>",
-    "Output file path (single node) or output directory (--export-all)"
+    "Output file path (single node) or output directory (--export-all); when omitted, uses OS temp directory (valid with --export-all or with both --format and --node)"
   ).option(
     "--images <dir>",
     "Directory of image files for REST API document (optional; not used if <input> is a dir with images/)"
@@ -199,9 +201,6 @@ async function main() {
       const exportAll = options.exportAll === true;
       const nodeId = String(options.node ?? "").trim();
       const explicitImagesDir = typeof options.images === "string" ? options.images : void 0;
-      if (!outPath) {
-        program.error("--out is required");
-      }
       const { documentPath, imagesDir, isRestJson } = resolveInput(
         input.trim(),
         explicitImagesDir
@@ -210,17 +209,20 @@ async function main() {
         if (nodeId) {
           program.error("--node must not be used with --export-all");
         }
-        const outDir = path.resolve(outPath);
-        if (existsSync(outDir)) {
-          const stat = statSync(outDir);
-          if (!stat.isDirectory()) {
-            program.error(
-              "--out must be a directory when using --export-all"
-            );
+        const outDir = outPath ? (() => {
+          const resolved = path.resolve(outPath);
+          if (existsSync(resolved)) {
+            const stat = statSync(resolved);
+            if (!stat.isDirectory()) {
+              program.error(
+                "--out must be a directory when using --export-all"
+              );
+            }
+          } else {
+            mkdirSync(resolved, { recursive: true });
           }
-        } else {
-          mkdirSync(outDir, { recursive: true });
-        }
+          return resolved;
+        })() : mkdtempSync(path.join(tmpdir(), "refig-export-"));
         await runExportAll(
           documentPath,
           outDir,
@@ -235,8 +237,28 @@ async function main() {
       const width = Number(options.width ?? 1024);
       const height = Number(options.height ?? 1024);
       const scale = Number(options.scale ?? 1);
-      await runSingleNode(documentPath, nodeId, path.resolve(outPath), {
-        format: typeof options.format === "string" ? options.format : void 0,
+      const formatOption = typeof options.format === "string" ? options.format : void 0;
+      let singleOutPath;
+      if (outPath) {
+        singleOutPath = path.resolve(outPath);
+      } else {
+        if (!formatOption) {
+          program.error(
+            "When --out is omitted, both --node and --format are required"
+          );
+        }
+        const format = formatOption.toLowerCase();
+        if (!FORMAT_SET.has(format)) {
+          program.error(`Unsupported --format "${format}"`);
+        }
+        const ext = EXT_BY_FORMAT[format] ?? "png";
+        singleOutPath = path.join(
+          tmpdir(),
+          `refig-${sanitizeForFilename(nodeId)}.${ext}`
+        );
+      }
+      await runSingleNode(documentPath, nodeId, singleOutPath, {
+        format: formatOption,
         width,
         height,
         scale,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grida/refig",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "description": "Headless Figma renderer — render .fig and REST API JSON to PNG/JPEG/WebP/PDF/SVG",
   "keywords": [