@akesson/figma-explorer 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,198 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-28
+
+### Added
+
+- **Cached files are checked against Figma before they're served.** Designers
+  edit files while you work, and until now a cached file was served as-is
+  until the next `cache prefetch` — days out of date with no warning. Every
+  command that reads cached file data now compares the file's Figma `version`
+  (a ~1 KB `/meta` request) at most once every 5 minutes per file, and
+  refetches a changed file before answering; stderr says
+  `cache: N files changed on Figma (…) — refetching…`. Cross-file `find` and
+  `ls` at `--depth 2`+ check all the files they read. If the check or the
+  refetch fails, the cached copy is served with a note rather than an error.
+  `--cache-only` makes no requests and notes data past the 5-minute window.
+  The first run after upgrading refetches each file once, since older caches
+  don't record a version.
+
+- **Comments are kept current too.** A new comment doesn't change a file's
+  Figma `version`, so the check above never saw it, and `comments` kept
+  serving whatever the last `cache prefetch` fetched. `comments` and
+  `node-info` (when its output includes comments) now re-fetch a file's
+  comments if they haven't been checked in the last 5 minutes. If that fails,
+  the cached comments are served with a note on stderr, and the next attempt
+  waits for the next 5-minute window. `find` and `ls` still read the cached
+  comments as-is, since they span every file.
+
+- **Local variables are refreshed with the file.** On accounts with the
+  Variables REST API (Enterprise), the cached variables were only re-fetched
+  by `cache prefetch`, so after a designer's change `node-info` could pair
+  the new design with old variable values. A file that already has cached
+  variables now re-fetches them whenever the file itself is refetched. If
+  that fails, the old values are kept and `node-info` says on stderr that they
+  may be out of date. Files that never had variables (every file on other
+  plans) make no extra request.
+
+- **New and deleted files show up without a prefetch.** The version check
+  only covers files already in the cache, so a file a designer added to a
+  folder never appeared in `ls` or `find` until the next `cache prefetch`, and
+  a deleted one kept showing. `ls` (root or a folder) and `find` without
+  `--in` now check each configured folder's file list at most once every 5
+  minutes (one request per folder). New files are fetched, files gone from
+  Figma are dropped, and renamed or moved files get their new name or folder.
+  stderr reports what changed. Only folders that already have cached files
+  get new files fetched automatically, so the first `ls` on an empty cache
+  doesn't quietly turn into a full prefetch. `--cache-only` skips the check.
+
+- **`node-info file:N` now shows each named style's value.** Every entry in
+  the file summary's `styles` list carries a `value`: a FILL style's hex (or
+  its paint list for gradients and stacked paints), a TEXT style's font
+  family, weight, size, line height and letter spacing, an EFFECT style's
+  shadow list. Figma returns no values for styles, so each is read off the
+  first visible node applying it, offline from the full-file sidecar; a style
+  no visible node uses has no `value`. Library copies are flagged
+  `remote: true`, since one can share a name with a local style yet differ.
+  `node-info file:N --only styles` gives just this table.
+
+### Removed
+
+- **`tokens` is gone.** Its output wasn't usable as design tokens: outside
+  `--scope file` it named colors after the layers they were found on
+  (`--color-rectangle-13`, `--color-vector`), and it read only fill and text
+  styles, so effect styles (shadows, focus rings) never appeared even with
+  `--only shadows`. Use instead:
+  - a file's named styles and their values → `node-info file:N --only styles`
+    (above), which covers effect styles too;
+  - the colors, type and effects a frame uses → `node-info file:N:x:y`, which
+    lists them with the named style each one comes from.
+- **`context` is gone.** It bundled a tree, a screenshot, `tokens` output and
+  `assets` into one directory. Run the parts directly: `node-info` for the
+  structure, `screenshot --out` for the image, `assets --out-dir` for icons
+  and images.
+
+### Fixed
+
+- **macOS binaries are now codesigned and notarized.** Downloading a release
+  tarball from GitHub in a browser previously produced "cannot be opened
+  because the developer cannot be verified" on first run. Binaries are now
+  signed with a Developer ID certificate under the hardened runtime and
+  notarized with Apple. Homebrew, npm, and the shell installer were never
+  affected (none of them set the quarantine attribute).
+- **Region comments keep their region.** A comment pinned to a region of a
+  frame (rather than a point) lost its region size and pin corner, because
+  the generated client matched it to the point shape first. Cached comments
+  correct themselves on their next refresh.
+- **`file:N` ids are assigned in the same order on every machine.** A fresh
+  `cache prefetch` numbered files in filesystem order, so `file:1` could name
+  different files on different machines. Files are now numbered by folder,
+  then name. Ids already assigned don't change.
+
+## [0.2.3] - 2026-09-23
+
+### Fixed
+
+- **`cache prefetch` now backfills a missing `.full.json.gz` sidecar.** A file
+  first cached by opening it via URL (`ls <url>`, `node-info <url>`, …) has a
+  payload but no full sidecar, and prefetch used to count it as up to date
+  forever — so `node-info --cache-only` never worked offline for it. Prefetch
+  now refetches an unchanged file whose full sidecar is missing or stamped
+  with another schema version (unless `--no-full`).
+- **Root `ls` no longer lists folders with no cached files.** A folder dropped
+  from `FIGMA_PROJECTS_IDS` keeps its `proj:N` id (synthetic ids are stable),
+  and root `ls` rendered it as an empty project named by its raw folder id
+  (e.g. `proj:3 "571382610"`). Such folders are now omitted; `ls proj:N` still
+  works, and `cache prefetch --folder-ids <id>` brings a folder back with its
+  real name.
+- **`cache prefetch`, root `ls` refresh and `ls proj:N` refresh no longer 403
+  with a Figma token created after 2026-08-03.** Figma renamed projects to
+  folders; new personal access tokens carry `folders:read` instead of
+  `projects:read`, and the deprecated `GET /v1/projects/{id}/files` rejects
+  them (`Invalid scope … requires the file_read or files:read or projects:read
+  scope`). Listings now use `GET /v2/folders/{id}/files`. Folder ids are the
+  old project ids, so `FIGMA_PROJECTS_IDS`, `proj:N` and existing cache metas
+  are unchanged; `--project-ids` gained a `--folder-ids` alias. A 403 from v2
+  falls back to v1 once (pre-rename tokens are documented to keep working
+  there) and prints a hint to regenerate the token. `figma-api` was
+  regenerated from the 2026-08-11 upstream spec, which adds `folders_api`;
+  `figma-get` gained `folder-files`, `folder-folders`, `folder-meta` and
+  `team-folders`, and marks `project-files` / `team-projects` deprecated.
+
+### Changed
+
+- **`node-info` output is ~4–5× smaller with nothing implementation-relevant
+  dropped.** Measured on a 475-node screen: 634 KB → 141 KB YAML. What changed
+  in the curated view (`--raw` is untouched):
+  - Hidden (`visible: false`) children are pruned and listed on the parent as
+    `hidden_children: [{id, name, type}]` — they were 65% of the output and,
+    worse, their descendants were indistinguishable from visible nodes.
+    `--include-hidden` restores them; a hidden target is always rendered, and
+    so is a hidden layer inside a COMPONENT definition whose visibility is
+    wired to a BOOLEAN property (its `property_refs` are the wiring an
+    implementer needs). A comment anchored to a pruned node is tagged
+    `anchor_rendered: false`.
+  - Defaults are elided: `constraints: LEFT/TOP`, `layout.wrap: NO_WRAP`,
+    axis `sizing: AUTO` / `align: MIN`, text alignment LEFT/TOP,
+    `line_height_unit: PIXELS`.
+  - `bounds` is parent-relative on descendants; flow children of an
+    auto-layout parent carry only `width`/`height`. A CANVAS has no box, so
+    a page's children are relative to the canvas origin (Figma's absolute
+    coordinates). `size` appears only when it differs from the bounding box
+    (rotation).
+  - Colors are `hex` only; the float channels are gone from fills, strokes,
+    gradient stops and effects.
+  - Text style drops `font_post_script_name`, `line_height_percent`,
+    `line_height_percent_font_size` (all restate other fields).
+  - `layout_child.sizing` is one `"H/V"` string; padding is one number when
+    uniform, else `[top, right, bottom, left]`.
+  - `component.component_properties` is split into `variants` and
+    `properties` with plain scalar values and Figma's `#n:m` name suffixes
+    stripped (kept when stripping would collide). An INSTANCE_SWAP prop keeps
+    its allowed swap targets as `preferred`. `property_refs` is emitted on
+    the target and inside component definitions only.
+  - Geometry leaves below the target (VECTOR, BOOLEAN_OPERATION, STAR, LINE,
+    REGULAR_POLYGON) drop only the layout block that cannot apply to them —
+    `constraints` when they are flow children of an auto-layout parent,
+    `layout_child` when the parent has no auto-layout — so a FILL-width
+    divider LINE keeps its sizing; fills and strokes stay so icon color
+    tokens remain visible.
+  - Bound variables are referenced by short handles (`v1`, `v2`, … in
+    first-seen order). The top-level `variables` block is keyed by handle and
+    always carries the raw `id`, plus name/values when the Variables sidecar
+    is available. The 60-character `VariableID:` strings no longer repeat
+    per use.
+  - Node-level `bound_variables` no longer repeats `fills[i]`/`strokes[i]`
+    entries that the paint itself already carries as `bound_variable` (half
+    of the map on a real screen). Entries the paints don't mirror are kept.
+  - Floats are rounded to 3 decimals (`14.40007495880127` → `14.4`): Figma
+    stores f32 and the REST API prints it as f64. The top-level `variables`
+    block gets the same treatment.
+  - `--no-variables` once again omits the `variables` block entirely; when a
+    sidecar is present but some handles point at library-owned variables, a
+    `variables_note` says how many could not be resolved locally.
+- **YAML output uses flow style for leaf containers** (`bounds: {width: 24,
+  height: 24}`, `padding: [0, 12, 0, 12]`, one record per row in lists)
+  instead of `serde_yaml`'s all-block rendering, via the new `yaml_out`
+  printer. Still standard YAML; a `node-info` view goes from 4,564 to 2,464
+  lines and 31.3k to 27.8k tokens. Non-ASCII keys are no longer escaped
+  (`💠 Before Icon`, not `\u{1f4a0} Before Icon`) and integral floats print
+  as `12`, not `12.0`. Multi-line text renders as a `|-` literal block.
+  Quoting is conservative enough for YAML 1.1 parsers (PyYAML, Psych):
+  `687:45` and `10:5` are quoted (base 60 would read them as integers),
+  `1,000` and `2026-9-5` too, large floats print as `1.5e+20`, a leading
+  `:`/`?` is quoted inside `{}`/`[]`, and U+2028/U+2029, NEL, DEL and the C1
+  range are `\uXXXX`-escaped rather than written raw (libyaml refuses the
+  whole document otherwise — Shift+Enter in a Figma text layer produces
+  U+2028). Applies to every command's YAML output.
+- **`--json` is compact**, not pretty-printed. Pretty JSON was the most
+  token-expensive rendering of all (37% more than the YAML default on the
+  same view); `jq` does not care.
+- `scripts/node_info_lossless.py` — checks a curated view against `--raw` for
+  the same target (node set, hidden listing, bounds reconstruction, paints,
+  layout, text, component props, variable handles).
+
 ## [0.2.2] - 2026-08-22
 
 ### Fixed

package/README.md

@@ -5,14 +5,12 @@ A command-line tool for navigating, inspecting, and exporting from Figma files v
 ## What it does
 
 - **`ls`** / **`find`** — navigate projects, files, and node trees by name or visible text without copy-pasting node ids. `find` speaks web-search syntax: `"exact phrases"`, uppercase `OR`, `-exclusion`.
-- **`node-info`** — single-target view with layout, fills, strokes, effects, text, bound variables, comments, and a ready-made figma.com `url:`. Designed to be pasted into an agent prompt.
+- **`node-info`** — single-target view with layout, fills, strokes, effects, text, bound variables, comments, and a ready-made figma.com `url:`. Hidden subtrees are pruned (listed as `hidden_children`), defaults elided, and variables referenced by short handles, so a full screen is a few dozen KB rather than hundreds. Designed to be pasted into an agent prompt. On a file (`node-info file:N --only styles`) it lists the file's named styles with their values — fill hex, text font, shadow effects.
 - **`comments`** — list a file's comment threads (replies inline, newest first), threads under a node, or a single thread; filter with `--unresolved` / `--since` / `--grep`.
 - **`mark`** — curated keyword→node bookmarks (`mark add key file:N:x:y --alias …`); `find` and `library search` surface matching marks ahead of their own hits, and `mark:key` resolves anywhere an id is accepted.
 - **`library search`** — fuzzy search across a team's published component library (components, component sets, styles).
 - **`screenshot`** — export a node as PNG / JPG / SVG / PDF.
-- **`tokens`** — extract design tokens (colors, fonts, sizes, spacing).
-- **`assets`** — bulk-export every icon/image below a node.
-- **`context`** — aggregate: tree + screenshot + tokens + assets for a node.
+- **`assets`** — bulk-export every icon (SVG) and image (PNG) below a node, with a manifest.
 - **`cache prefetch`** / **`cache status`** — pre-warm a local cache so subsequent commands are offline-fast, and report what it holds (per-file age, sidecars, catalog) without touching the network.
 
 All commands share a tagged-id grammar — `proj:N`, `file:N`, `file:N:x:y`, or a full `figma.com` URL — so you never paste raw node identifiers by hand.
@@ -57,9 +55,11 @@ Get a personal access token at https://www.figma.com/developers/api#access-token
 export FIGMA_TOKEN=figd_...
 ```
 
+Give the token the **File content** (`file_content:read`) and **File metadata** (`file_metadata:read`) read scopes. The metadata scope powers the cheap freshness check (`/v1/files/{key}/meta`); without it, checks fall back to a slower depth-limited file request.
+
 Optional environment variables:
 
-- `FIGMA_PROJECTS_IDS` — comma-separated project ids; needed by `cache prefetch`.
+- `FIGMA_PROJECTS_IDS` — comma-separated Figma folder ids (Figma renamed "projects" to "folders" in August 2026; the numeric ids are unchanged, so existing values keep working); needed by `cache prefetch`.
 - `FIGMA_TEAM_ID` — needed by `library search` and for the catalog warm in `cache prefetch`.
 - `FIGMA_EXPLORER_CACHE_DIR` — override the cache location (default: OS cache dir).
 
@@ -90,8 +90,8 @@ figma-explorer node-info file:2:1094:66591
 # Search the team component library
 figma-explorer library search "icon arrow"
 
-# Export everything below a node as PNGs
-figma-explorer assets file:2:1094:66591 ./out/
+# Export every icon and image below a node
+figma-explorer assets file:2:1094:66591 --out-dir ./out/
 
 # Pre-warm the cache so subsequent reads are offline
 figma-explorer cache prefetch
@@ -99,12 +99,14 @@ figma-explorer cache prefetch
 
 ## Output
 
-YAML by default (terse, agent-friendly). Pass `--json` for full pretty JSON suitable for `jq` pipelines.
+YAML by default (terse, agent-friendly: block style for the tree, flow style `{k: v}` for leaf maps and short lists). Pass `--json` for compact JSON suitable for `jq` pipelines.
 
 ## Cache
 
 A local rkyv cache lives at `$FIGMA_EXPLORER_CACHE_DIR` or the OS cache dir. It is **per-machine** — rkyv archives are not endianness-portable, so don't sync the cache directory across architectures. `cache clear` removes everything; `cache prefetch` warms it from `FIGMA_PROJECTS_IDS`.
 
+Designers edit files live, so cached data is checked against Figma before it is served: at most once every 5 minutes per file, a ~1 KB `GET /v1/files/{key}/meta` compares Figma's `version` with the cached one, and a changed file is refetched (payload and `node-info` sidecar together) before the command answers. If the check or refetch fails, the cached copy is served with a note on stderr. `--cache-only` never checks; it notes data older than the window instead.
+
 ## License
 
 MIT. See `LICENSE-MIT`.

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@akesson/figma-explorer",
-      "version": "0.2.2"
+      "version": "0.3.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.2.2"
+  "version": "0.3.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/akesson/figma-explorer/releases/download/v0.2.2"
+    "https://github.com/akesson/figma-explorer/releases/download/v0.3.0"
   ],
   "bin": {
     "figma-explorer": "run-figma-explorer.js"
@@ -8,7 +8,7 @@
   "dependencies": {
     "detect-libc": "^2.1.2"
   },
-  "description": "High-level CLI on top of the Figma REST API: name-based navigation, asset extraction, design tokens, and bundled context export.",
+  "description": "High-level CLI on top of the Figma REST API: name-based navigation, implementation-ready node views, comments, screenshots, and asset export.",
   "devDependencies": {
     "prettier": "^3.8.3"
   },
@@ -26,7 +26,7 @@
     "figma",
     "cli",
     "design",
-    "design-tokens"
+    "design-to-code"
   ],
   "license": "MIT",
   "name": "@akesson/figma-explorer",
@@ -95,7 +95,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.2.2",
+  "version": "0.3.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"