@akesson/figma-explorer 0.2.3 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-11-07
+
+### Fixed
+
+- **A newly configured folder shows up in `ls` before it's prefetched.** Root
+  `ls` used to list only folders with cached files, so after adding a folder
+  id to `FIGMA_PROJECTS_IDS` it looked as if the config hadn't been read. A
+  configured folder with nothing cached now gets its own row, named and
+  counted from the folder listing `ls` already makes:
+  `proj:3 "Mobile"  (23 files on Figma, none cached — run `figma-explorer cache prefetch`)`.
+  If Figma refuses to list the folder, the row shows the error instead.
+  `ls` still doesn't fetch the files, and `--cache-only` shows the row from
+  the last listing without making requests.
+
+- **`cache prefetch` retries transient failures.** A file whose fetch timed
+  out, hit a 429, or got a 5xx used to fail for the run, so finishing a large
+  folder took several reruns. Each file is now retried up to twice with
+  backoff (honoring `Retry-After`), and each retry is logged with how long
+  the failed attempt took. A 403/404 is not retried.
+
+- **Reruns of `cache prefetch` are fast.** A rerun polled the comments of
+  every unchanged file, one request each — about a minute for 50 files even
+  with nothing to do. Comments checked in the last 5 minutes are now
+  skipped, the same window `comments` uses.
+
+- **`ls` no longer calls retried files "added".** When a folder sync
+  re-fetched files whose earlier fetch had failed, stderr said they were
+  "added to Figma folders". It now says
+  `cache: retrying N files that failed to fetch earlier (…)`.
+
+## [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

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:`. 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.
+- **`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,6 +55,8 @@ 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 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`.
@@ -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
@@ -105,6 +105,8 @@ YAML by default (terse, agent-friendly: block style for the tree, flow style `{k
 
 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.3"
+      "version": "0.3.1"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.2.3"
+  "version": "0.3.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/akesson/figma-explorer/releases/download/v0.2.3"
+    "https://github.com/akesson/figma-explorer/releases/download/v0.3.1"
   ],
   "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.3",
+  "version": "0.3.1",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"