@nodii/dev 0.6.12 → 0.6.14

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(", ")}`] : []),
@@ -241,6 +242,41 @@ export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
   return changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
 }
 
+/**
+ * Narrows a held set to exactly these scopes (Dev issue 104,
+ * setDesignChangeSetScopes); the rest is released for other sets. Each must
+ * sit inside what the set holds: the whole file holds everything, a page its
+ * components and creates.
+ */
+export async function figmaScopeSet(id, scopes, { request = devRequest } = {}) {
+  if (!id || !scopes.length) throw new CliError("USAGE", `figma scope set CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  try {
+    return await request("PUT", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
+  } catch (error) {
+    if (error?.code === "SCOPE_NOT_NARROWER")
+      throw new CliError(error.code, `${error.message}\nscope set only narrows; to claim more, run nodii-dev figma scope add ${id} --scope ...`, error.exitCode ?? 1, error.details);
+    if (error?.code === "WRITE_OUT_OF_SCOPE")
+      throw new CliError(
+        error.code,
+        [
+          error.message,
+          ...(error.details?.nodeIds?.length ? [`Would fall outside: ${error.details.nodeIds.join(", ")}`] : []),
+          `Keep a scope that holds them (styles and variables need --scope foundations), or revert those nodes to how they were at ${id}'s base version.`,
+        ].join("\n"),
+        error.exitCode ?? 1,
+        error.details,
+      );
+    throw scopeRefusal(error, id) ?? error;
+  }
+}
+
+/** What a narrowing left the set holding, and what it released. */
+export const figmaScopeSetText = (id, data) =>
+  [
+    `${id} holds ${data?.scopes?.length ?? 0} scope(s): ${(data?.scopes ?? []).map(scopeText).join(", ") || "none"}`,
+    ...(data?.released?.length ? [`Released for other sets: ${data.released.map(scopeText).join(", ")}`] : []),
+  ].join("\n");
+
 export const figmaSubmit = (id, payload, { request = devRequest } = {}) =>
   changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
 
@@ -250,18 +286,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 +336,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.14",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {