@nodii/dev 0.6.12 → 0.6.13

package/README.md

@@ -193,7 +193,11 @@ whole file, as older CLIs do, and that conflicts with every other set.
 widened silently.
 
 Every write must fall inside the set's scopes (MW1-57.7). The post-hook
-logs each write's node ids as before. When Dev answers `WRITE_OUT_OF_SCOPE`,
+logs each write's node ids, in colon form. It also logs the variable,
+collection and style ids (`VariableID:…`, `VariableCollectionId:…`, `S:…`)
+that a write returns, including those in a `use_figma` script's JSON
+result, so Dev can tell a foundations write. Dev checks containment at
+`submit`, `resubmit` and `apply`. When Dev answers `WRITE_OUT_OF_SCOPE`,
 the hook exits `2`, so Claude Code shows the agent why: a write that
 returned no node ids (return them from the script, then run `figma log-write`),
 or ids outside the scopes. Dev refuses `figma submit` and `figma resubmit`
@@ -205,11 +209,14 @@ base version.
 Scopes release when a set reaches `awaiting_publish`. One library publish
 then covers every set awaiting publish. Before you publish in Figma,
 `figma publish-plan FILE_KEY` lists the components changed since the last
-publish in two groups. **publish** belongs to sets awaiting publish. **leave
+publish in two groups, and warns about any component that sets from both
+groups changed. **publish** belongs to sets awaiting publish. **leave
 unchecked** belongs to sets still editing or in review: untick those in
 Figma's publish dialog. Then `figma published FILE_KEY --figma-version VERSION`
-marks every awaiting set published, and Dev flags any published component
-from an unfinished set. `figma published CS-123 ...` keeps the per-set route.
+marks every set applied before that version as published (pass the
+library publish's version id). Dev holds back a set whose component an
+unfinished set now holds, and flags any published component from an
+unfinished set. `figma published CS-123 ...` keeps the per-set route.
 
 `figma withdraw` moves a change set you hold from `in_review` back to
 `editing`, as long as no item has been decided (Dev's

package/dist/cli.js

@@ -31,6 +31,7 @@ import {
   figmaChangeSetText,
   figmaFileKey,
   figmaFilePublished,
+  figmaFilePublishedText,
   figmaLock,
   figmaLockCheck,
   figmaLockText,
@@ -616,9 +617,7 @@ export async function main(argv = process.argv.slice(2)) {
     // One publish covers every set awaiting publish on the file (MW1-57.8); a
     // change set id keeps the per-set route.
     if (action === "published" && rest[0] && !isChangeSetId(rest[0]))
-      return emit(await figmaFilePublished(rest[0], f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") }), json, (p) =>
-        `Published ${p.data.published?.length ?? 0} change set(s): ${(p.data.published ?? []).join(", ") || "none awaiting publish"}` +
-        (p.data.flagged?.length ? `\nFLAGGED: published components from unfinished sets: ${JSON.stringify(p.data.flagged)}` : ""));
+      return emit(await figmaFilePublished(rest[0], f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") }), json, (p) => figmaFilePublishedText(p.data));
     if (action === "submit") {
       const payload = f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") };
       return emit(await figmaSubmit(rest[0], payload), json);
@@ -670,7 +669,7 @@ export async function main(argv = process.argv.slice(2)) {
       return emit(
         await devRequest(
           "POST",
-          `/api/v1/design/files/${encode(rest[0])}/lock/release`,
+          `/api/v1/design/files/${encode(figmaFileKey(rest[0]))}/lock/release`,
           {},
         ),
         json,

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.12";
+export const VERSION = "0.6.13";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -105,20 +105,42 @@ export function requestUrl(config, path) {
   return `${config.edgeUrl.replace(/\/$/, "")}/devops${path}`;
 }
 
+const staleCode = (raw) => {
+  try {
+    return JSON.parse(raw)?.code === "token_stale";
+  } catch {
+    return false;
+  }
+};
+
 async function devFetch(method, path, bodyText, contentType, accept) {
   const config = await readConfig();
   const auth = await authProvider();
-  const headers = { accept };
-  if (bodyText !== undefined) headers["content-type"] = contentType;
-  Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
   const url = requestUrl(config, path);
-  let response;
-  try {
-    response = await fetch(url, { method, headers, body: bodyText });
-  } catch (error) {
-    throw new CliError("DEV_UNREACHABLE", `Cannot reach Dev at ${new URL(url).origin}: ${error.message}`);
+  // The edge refuses a token minted before the principal's claims epoch with
+  // 401 token_stale (refresh and retry once). The request never reached Dev,
+  // so it is sent again: with a token another process cached since, or with
+  // one refresh. A token_stale after that refresh is surfaced.
+  let refreshed = false;
+  let adopted = false;
+  for (;;) {
+    const headers = { accept };
+    if (bodyText !== undefined) headers["content-type"] = contentType;
+    Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
+    let response;
+    try {
+      response = await fetch(url, { method, headers, body: bodyText });
+    } catch (error) {
+      throw new CliError("DEV_UNREACHABLE", `Cannot reach Dev at ${new URL(url).origin}: ${error.message}`);
+    }
+    const raw = await response.text();
+    if (response.status !== 401 || typeof auth.refreshStale !== "function" || !staleCode(raw)) return { response, raw };
+    if (refreshed) return { response, raw };
+    // A cached token that is stale too is not adopted twice: the next one is refreshed.
+    const used = String(headers.authorization ?? "").replace(/^Bearer /, "");
+    if ((await auth.refreshStale(used, { force: adopted })) === "refreshed") refreshed = true;
+    else adopted = true;
   }
-  return { response, raw: await response.text() };
 }
 
 export async function devRawRequest(method, path, bodyText, contentType = "application/json") {

package/dist/figma.js

@@ -150,7 +150,8 @@ const conflictText = (message, details) => {
   ].join("\n");
 };
 
-const FOUNDATIONS_ID = /^(?:S:|VariableID:|VariableCollectionId:)/;
+/** A variable, variable collection or style id: a write to one is a foundations write. */
+export const FOUNDATIONS_ID = /^(?:VariableID:\d+:\d+|VariableCollectionId:\d+:\d+|S:[0-9a-f]+(?:,\d+:\d+)?)$/;
 
 /** Dev's WRITE_OUT_OF_SCOPE, with what to do about it (MW1-57.7). */
 export function outOfScopeText(message, details, id = details?.changeSetId ?? "CHANGE_SET") {
@@ -161,7 +162,7 @@ export function outOfScopeText(message, details, id = details?.changeSetId ?? "C
       `The write returned no node ids, so Dev can't check it against ${id}'s scopes.`,
       `Return the ids you wrote from the script, then run: nodii-dev figma log-write ${id} --tool TOOL --nodes ID,ID`,
     ].join("\n");
-  const foundations = ids.filter((x) => FOUNDATIONS_ID.test(x));
+  const foundations = ids.filter((x) => FOUNDATIONS_ID.test(x) || /^S:/.test(x));
   return [
     message,
     ...(ids.length ? [`Out of scope: ${ids.join(", ")}`] : []),
@@ -250,18 +251,45 @@ export const figmaLogWrite = (id, tool, nodeIds, { request = devRequest } = {})
 /** One publish for the file: every awaiting_publish set on it (MW1-57.8). */
 export async function figmaFilePublished(value, payload, { request = devRequest } = {}) {
   const key = figmaFileKey(value);
-  return fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/published`, payload);
+  try {
+    return await fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/published`, payload);
+  } catch (error) {
+    if (error?.code !== "FIGMA_VERSION_NOT_FOUND") throw error;
+    throw new CliError(error.code, `${error.message}\nPass the id of the library publish's version, from the file's version history in Figma.`, error.exitCode ?? 1, error.details);
+  }
+}
+
+const idOf = (x) => (typeof x === "string" ? x : (x?.changeSetId ?? x?.id ?? JSON.stringify(x)));
+const list = (ids) => (ids?.length ? ids.map(idOf).join(", ") : "none");
+
+/** What a file-level publish did: published, held back for the next publish, and anything Dev flags. */
+export function figmaFilePublishedText(result) {
+  return [
+    `Published ${result.published?.length ?? 0} change set(s): ${list(result.published)}`,
+    ...(result.heldBack?.length
+      ? [`Held back for the next publish (an unfinished set now holds their component, and this publish didn't include it): ${list(result.heldBack)}`]
+      : []),
+    ...(result.versionTime === "unverified" ? ["Dev couldn't verify when that Figma version was made."] : []),
+    ...(result.flagged?.length
+      ? [`FLAGGED: this publish includes components from unfinished sets: ${result.flagged.map((f) => (typeof f === "string" ? f : `${f.nodeId ?? "?"}${f.name ? ` ${f.name}` : ""} (${f.changeSetId ?? "?"})`)).join(", ")}`]
+      : []),
+  ].join("\n");
 }
 
 // A change set id (CS-123) takes the per-set route; a file key or link takes the file's.
-export const isChangeSetId = (value) => typeof value === "string" && /^CS-\d+$/i.test(value);
+// Anything else starting CS- is a mistyped id, never a file.
+export function isChangeSetId(value) {
+  if (typeof value !== "string" || !/^CS-/i.test(value)) return false;
+  if (!/^CS-\d+$/i.test(value)) throw new CliError("USAGE", `${value} is not a change set id (CS-123) or a Figma file key`, 2);
+  return true;
+}
 
 export async function figmaPublishPlan(value, { request = devRequest } = {}) {
   const key = figmaFileKey(value);
   return fileCall(key, request)("GET", `/api/v1/design/files/${encode(key)}/publish-plan`);
 }
 
-const planLine = (x) => `  ${x.nodeId ?? scopeText(x)}  ${x.name ?? ""}  (${x.changeSetId} ${x.state}${x.title ? `: ${x.title}` : ""})`;
+const planLine = (x) => `  ${x.nodeId ?? (x.kind ? scopeText(x) : "(no node)")}  ${x.name ?? ""}  (${x.changeSetId} ${x.state}${x.title ? `: ${x.title}` : ""})`;
 
 /** The publish plan as two groups: what to publish, and what to leave unchecked in Figma's publish dialog. */
 export function figmaPublishPlanText(plan) {
@@ -273,6 +301,12 @@ export function figmaPublishPlanText(plan) {
     ...(publish.length ? publish.map(planLine) : ["  nothing awaiting publish"]),
     `leave unchecked (${leave.length}): sets still editing or in review`,
     ...(leave.length ? leave.map(planLine) : ["  none"]),
+    ...(plan.collisions?.length
+      ? [
+          `WARNING: ${plan.collisions.length} component(s) changed by both a set to publish and an unfinished set; Figma can't publish half of one:`,
+          ...plan.collisions.map((c) => `  ${c.nodeId}  ${c.name ?? ""}  publish ${list([c.publish].flat())}; leave unchecked ${list([c.leaveUnchecked].flat())}`),
+        ]
+      : []),
     ...(publish.length
       ? [`After publishing in Figma: nodii-dev figma published ${plan.fileKey} --figma-version VERSION`]
       : []),

package/dist/hooks.js

@@ -1,5 +1,5 @@
 import { CliError, devRequest } from "./core.js";
-import { figmaLockCheck, outOfScopeText } from "./figma.js";
+import { FOUNDATIONS_ID, figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -59,17 +59,47 @@ export function extractFileKey(input) {
   return null;
 }
 
-export function extractNodeIds(value, out = new Set()) {
+// Figma ids, in the colon form Dev stores: 12-34 (a link's form) is 12:34,
+// I12-34;56-78 is I12:34;56:78. Variables, collections and styles carry
+// their own ids (VariableID:1:2, VariableCollectionId:1:2, S:<hash>,1:2);
+// a write to one is a foundations write (MW1-57.7).
+const FOUNDATIONS_IN_TEXT = new RegExp(`(?<![\\w:])${FOUNDATIONS_ID.source.replace(/^\^|\$$/g, "")}`, "g");
+// id, ids, nodeId(s), node_ids, createdNodeIds, mutatedNodeIds, variableIds, styleId, ...
+const ID_KEY = /^(?:ids?|\w*node_?ids?|(?:variable|style|collection)_?ids?)$/i;
+const FIGMA_NODE_ID = /^I?\d+[:-]\d+(?:;\d+[:-]\d+)*$/;
+// A tool's input may name a node by any id its server uses; a result is held to Figma's shapes.
+const INPUT_ID = /^(?:\d+[:;-]\d+|[A-Za-z0-9_-]{8,})$/;
+const colonForm = (id) =>
+  /^I?\d+-\d+(?:;\d+-\d+)*$/.test(id) ? id.replace(/(\d+)-(\d+)/g, "$1:$2") : id;
+
+/**
+ * The node ids in hook data: values under id-like keys, and any variable,
+ * collection or style id. With `text`, a JSON string (a tool's text result)
+ * is read as JSON, and other text is searched for variable and style ids;
+ * a tool's input (its script) is never searched as text.
+ */
+export function extractNodeIds(value, out = new Set(), { text = false } = {}) {
+  if (typeof value === "string") {
+    if (!text) return [...out];
+    const trimmed = value.trim();
+    if (/^[[{]/.test(trimmed)) {
+      try {
+        return extractNodeIds(JSON.parse(trimmed), out, { text });
+      } catch {}
+    }
+    for (const id of value.match(FOUNDATIONS_IN_TEXT) ?? []) out.add(id);
+    return [...out];
+  }
   if (!value || typeof value !== "object") return [...out];
   for (const [key, item] of Object.entries(value)) {
-    if (/^(node_?ids?|id)$/i.test(key))
-      for (const v of Array.isArray(item) ? item : [item])
-        if (
-          typeof v === "string" &&
-          /^(?:\d+[:;-]\d+|[A-Za-z0-9_-]{8,})$/.test(v)
-        )
-          out.add(v);
-    if (typeof item === "object") extractNodeIds(item, out);
+    const keyed = ID_KEY.test(key);
+    for (const v of Array.isArray(item) ? item : [item]) {
+      if (typeof v !== "string") continue;
+      if (FOUNDATIONS_ID.test(v)) out.add(v);
+      else if (keyed && (FIGMA_NODE_ID.test(v) || (!text && INPUT_ID.test(v)))) out.add(colonForm(v));
+      else if (text) extractNodeIds(v, out, { text });
+    }
+    if (typeof item === "object") extractNodeIds(item, out, { text });
   }
   return [...out];
 }
@@ -119,10 +149,9 @@ export async function postHook(payload, request = devRequest, config = async ()
   const checked = await figmaLockCheck(fileKey, agentId, request);
   if (!checked.data?.allowed || !checked.data.changeSetId)
     return { logged: false, reason: checked.data?.reason ?? "lock denied" };
-  const nodeIds = extractNodeIds({
-    input: payload.tool_input,
-    response: payload.tool_response,
-  });
+  const found = new Set();
+  extractNodeIds(payload.tool_input, found);
+  const nodeIds = extractNodeIds(payload.tool_response, found, { text: true });
   if (!nodeIds.length) nodeIds.push("unknown");
   try {
     await request(

package/dist/oauth.js

@@ -525,6 +525,27 @@ export class OAuthAuthProvider {
     })().finally(() => { this.#refreshPromise = undefined; });
     return this.#refreshPromise;
   }
+  /**
+   * The edge refused `stale` as minted before the principal's claims epoch
+   * (401 token_stale). Get a token past it: one another process cached since
+   * (resolves "cache"), or else a refresh under the lock, re-checking the
+   * cache once the lock is held so concurrent processes rotate only once
+   * (resolves "refreshed"). `force` skips the cache.
+   */
+  async refreshStale(stale, { force = false } = {}) {
+    if (this.#accessToken === stale) {
+      this.#accessToken = undefined;
+      this.#expiresAt = 0;
+    }
+    const config = await readConfig();
+    const fresh = (cached) => !force && cached?.token !== stale && this.#usable(cached);
+    if (fresh(await this.loadAccess(config.clientId))) return "cache";
+    return this.lock(async ({ held } = {}) => {
+      if (fresh(await this.loadAccess(config.clientId))) return "cache";
+      await this.#refresh(config, held ?? (async () => true));
+      return "refreshed";
+    }, { clientId: config.clientId }).finally(() => this.#release());
+  }
   async #attempt(config, refresh, deadline, held) {
     const floor = Math.min(MIN_ATTEMPT_MS, this.timeoutMs);
     let result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {