@nodii/dev 0.6.11 → 0.6.13

package/dist/doctor.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { devRequest, encode, isOAuthConfig, query, setAuthProvider } from "./core.js";
 import { OAuthAuthProvider, decodeClaims, loadRefreshToken } from "./oauth.js";
 import { inferGitContext, repoName } from "./lanes.js";
-import { figmaFileKey, notRegisteredHint } from "./figma.js";
+import { figmaFileKey, figmaLockCheck, holdsSet, notRegisteredHint, scopeText } from "./figma.js";
 
 /**
  * What a lane's commands need, in Dev's route policy (staffRuleFor in Dev's
@@ -237,6 +237,19 @@ export async function doctorCommand(deps = {}) {
         const file = (await request("GET", `/api/v1/design/files/${encode(fileKey)}`)).data;
         checks.push(ok("figma_file", `${fileKey} is registered: ${file.name} (${file.kind}${file.module ? `, ${file.module}` : ""})`,
           { fileKey, registered: true }));
+        // The lock scopes this agent holds in the file (DEC-0032).
+        if (config.agentId) {
+          try {
+            const held = (await figmaLockCheck(fileKey, config.agentId, request)).data;
+            const mine = holdsSet(held);
+            const scopes = mine ? (held.scopes ?? []) : [];
+            checks.push(ok("figma_scopes", mine
+              ? `${held.changeSetId} (${held.state}) holds ${scopes.length ? scopes.map(scopeText).join(", ") : "the whole file"}`
+              : `holds no scopes in ${fileKey}`, { fileKey, changeSetId: mine ? held.changeSetId : null, scopes }));
+          } catch (error) {
+            checks.push(cannot("figma_scopes", `checkDesignFileLock failed (${devReason(error)})`, { fileKey }));
+          }
+        }
       } catch (error) {
         if (error?.code === "DESIGN_FILE_NOT_FOUND")
           checks.push(missing("figma_file", `${fileKey} is NOT registered: run figma file add; figma lock fails with DESIGN_FILE_NOT_FOUND`,

package/dist/figma.js

@@ -68,7 +68,7 @@ export async function figmaResubmit(id, file, { request = devRequest, read = (f)
     return await request("POST", `/api/v1/design/change-sets/${encode(id)}/resubmit`, body);
   } catch (error) {
     const say = RESUBMIT_REFUSALS[error?.code];
-    if (!say) throw error;
+    if (!say) throw scopeRefusal(error, id) ?? error;
     throw new CliError(error.code, say(id, error.details, error.message), error.exitCode ?? 1, error.details);
   }
 }
@@ -104,3 +104,211 @@ export function figmaChangeSetText(cs) {
   if (cs.previousRounds?.length) lines.push(`${cs.previousRounds.length} earlier-round item(s) replaced by a re-submit; --json lists them.`);
   return lines.join("\n");
 }
+
+// Scoped design locks (DEC-0032, MW1-57.6 to 57.9). A scope is written
+// kind:id on the command line: component:NODE, page:NODE, foundations, or
+// create:PAGE:NAME. A node id from a figma.com link (12-34) is Figma's 12:34.
+const nodeId = (text) => (/^\d+-\d+$/.test(text) ? text.replace("-", ":") : text);
+const SCOPE_USAGE = "--scope component:NODE_ID | page:NODE_ID | foundations | create:PAGE_ID:NAME";
+
+export function parseScope(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  const bad = () => new CliError("USAGE", `bad scope ${JSON.stringify(text)}: use ${SCOPE_USAGE}`, 2);
+  if (text === "foundations") return { kind: "foundations" };
+  const create = text.match(/^create:(\d+[:-]\d+):(.*)$/);
+  if (create && create[2].trim() && create[2].trim().length <= 200)
+    return { kind: "create", pageId: nodeId(create[1]), name: create[2].trim() };
+  // Dev takes a scope at a top-level node: a plain id, never an instance's (I1:2;3:4).
+  const node = text.match(/^(component|page):(\d+[:-]\d+)$/);
+  if (!node) throw bad();
+  return { kind: node[1], nodeId: nodeId(node[2]) };
+}
+
+/** Every --scope flag as a scope; none at all is a whole-file lock (MW1-57.9). */
+export function scopesFrom(flags) {
+  const given = flags.scope === undefined ? [] : [flags.scope].flat();
+  return given.map((value) => {
+    if (value === true) throw new CliError("USAGE", `--scope needs a value: ${SCOPE_USAGE}`, 2);
+    return parseScope(value);
+  });
+}
+
+export const scopeText = (s) =>
+  !s ? "?"
+    : s.kind === "foundations" ? "foundations"
+    : s.kind === "file" ? "whole file"
+    : s.kind === "create" ? `create:${s.pageId}:${s.name}`
+    : `${s.kind}:${s.nodeId}`;
+
+const conflictText = (message, details) => {
+  const held = details?.heldBy;
+  if (!held) return message;
+  return [
+    message,
+    `${scopeText(details.requested)} overlaps ${scopeText(held.scope)}, held by ${held.changeSetId}${held.title ? ` "${held.title}"` : ""}.`,
+    `Claim a scope that doesn't overlap, or wait until ${held.changeSetId} reaches awaiting_publish (scopes release there).`,
+  ].join("\n");
+};
+
+/** 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") {
+  const ids = details?.nodeIds ?? [];
+  if (details?.reason === "unknown-ids" || (ids.length && ids.every((x) => x === "unknown")))
+    return [
+      message,
+      `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) || /^S:/.test(x));
+  return [
+    message,
+    ...(ids.length ? [`Out of scope: ${ids.join(", ")}`] : []),
+    ...(foundations.length
+      ? [`Styles and variables (${foundations.join(", ")}) need the foundations scope: nodii-dev figma scope add ${id} --scope foundations`]
+      : []),
+    `Widen with nodii-dev figma scope add ${id} --scope component:NODE_ID|page:NODE_ID if the scope is free, or revert the node exactly to how it was at the set's base version, then submit again.`,
+  ].join("\n");
+}
+
+// Keep Dev's code and message; add what to do next.
+function scopeRefusal(error, id) {
+  if (error?.code === "SCOPE_CONFLICT")
+    return new CliError(error.code, conflictText(error.message, error.details), error.exitCode ?? 1, error.details);
+  if (error?.code === "WRITE_OUT_OF_SCOPE")
+    return new CliError(error.code, outOfScopeText(error.message, error.details, id), error.exitCode ?? 1, error.details);
+  return null;
+}
+
+/** A change-set route whose scope refusals say what to do next. */
+const changeSetCall = (id, request) => async (method, path, body) => {
+  try {
+    return await request(method, path, body);
+  } catch (error) {
+    throw scopeRefusal(error, id) ?? error;
+  }
+};
+
+/** A file route that names the `figma file add` command for an unregistered file. */
+const fileCall = (key, request) => async (method, path, body) => {
+  try {
+    return await request(method, path, body);
+  } catch (error) {
+    if (error?.code === "DESIGN_FILE_NOT_FOUND")
+      throw new CliError(error.code, notRegisteredHint(key), error.exitCode ?? 1, error.details);
+    throw scopeRefusal(error) ?? error;
+  }
+};
+
+/** May this agent write to the file? Its own set, state and scopes (checkDesignFileLock). */
+export const figmaLockCheck = (fileKey, agentId, request = devRequest) =>
+  request("GET", `/api/v1/design/files/${encode(fileKey)}/lock/check?agentId=${encode(agentId)}`);
+
+/** Whether a lock check answers for this agent's own set (it holds one), not another agent's. */
+export const holdsSet = (check) => Boolean(check?.changeSetId) && (check.allowed || check.reason === "change-set-not-editable");
+
+const isWholeFile = (scopes) => !scopes?.length || scopes.some((s) => s.kind === "file");
+
+export async function figmaLock(value, title, { scopes = [], request = devRequest } = {}) {
+  const key = figmaFileKey(value);
+  const result = await fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/lock`, {
+    changeSetTitle: title,
+    ...(scopes.length ? { scopes } : {}),
+  });
+  // A Dev that doesn't know scopes ignores them and locks the whole file,
+  // which blocks every other lane: say so loudly instead of exiting 0.
+  if (scopes.length && isWholeFile(result?.data?.scopes))
+    throw new CliError(
+      "SCOPES_NOT_APPLIED",
+      `Dev locked the whole of ${key} as ${result?.data?.id ?? "a change set"}, not the scopes asked for (this Dev predates scoped locks). It blocks every other change set on the file: run nodii-dev figma abandon ${result?.data?.id ?? "CHANGE_SET"}.`,
+      1,
+      result?.data,
+    );
+  return result;
+}
+
+export const figmaLockText = (cs) =>
+  [
+    `${cs.id}  ${cs.state ?? "editing"}  ${cs.title}`,
+    isWholeFile(cs.scopes)
+      ? `Locked the whole of ${cs.fileKey}: this conflicts with every other change set on the file. Claim scopes instead with ${SCOPE_USAGE}.`
+      : `Holds ${cs.scopes.length} scope(s) in ${cs.fileKey}: ${cs.scopes.map(scopeText).join(", ")}`,
+  ].join("\n");
+
+export async function figmaScopeAdd(id, scopes, { request = devRequest } = {}) {
+  if (!id || !scopes.length) throw new CliError("USAGE", `figma scope add CHANGE_SET ${SCOPE_USAGE} [--scope ...]`, 2);
+  return changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/scopes`, { scopes });
+}
+
+export const figmaSubmit = (id, payload, { request = devRequest } = {}) =>
+  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/submit`, payload);
+
+export const figmaLogWrite = (id, tool, nodeIds, { request = devRequest } = {}) =>
+  changeSetCall(id, request)("POST", `/api/v1/design/change-sets/${encode(id)}/writes`, { tool, nodeIds });
+
+/** 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);
+  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.
+// 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 ?? (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) {
+  const publish = plan.publish ?? [];
+  const leave = plan.leaveUnchecked ?? [];
+  return [
+    `Publish plan for ${plan.fileKey}${plan.sinceVersion ? ` (changes since version ${plan.sinceVersion})` : ""}`,
+    `publish (${publish.length}): sets awaiting publish`,
+    ...(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`]
+      : []),
+  ].join("\n");
+}

package/dist/hooks.js

@@ -1,4 +1,5 @@
 import { CliError, devRequest } from "./core.js";
+import { FOUNDATIONS_ID, figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -58,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];
 }
@@ -88,10 +119,7 @@ export async function preHook(payload, request = devRequest) {
   const { agentId } = await config();
   let response;
   try {
-    response = await request(
-      "GET",
-      `/api/v1/design/files/${encodeURIComponent(fileKey)}/lock/check?agentId=${encodeURIComponent(agentId)}`,
-    );
+    response = await figmaLockCheck(fileKey, agentId, request);
   } catch (error) {
     throw new CliError(
       "FIGMA_CHECK_FAILED",
@@ -111,32 +139,44 @@ export async function preHook(payload, request = devRequest) {
   return { allowed: true, fileKey, changeSetId: response.data.changeSetId };
 }
 
-export async function postHook(payload, request = devRequest) {
+export async function postHook(payload, request = devRequest, config = async () => (await import("./core.js")).readConfig()) {
   const name = payload.tool_name ?? "";
   if (!isFigmaTool(name) || isReadTool(name))
     return { logged: false, ignored: true };
   const fileKey = extractFileKey(payload.tool_input);
   if (!fileKey) return { logged: false, reason: "no file key" };
-  const { agentId } = await (await import("./core.js")).readConfig();
-  const checked = await request(
-    "GET",
-    `/api/v1/design/files/${encodeURIComponent(fileKey)}/lock/check?agentId=${encodeURIComponent(agentId)}`,
-  );
+  const { agentId } = await config();
+  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");
-  await request(
-    "POST",
-    `/api/v1/design/change-sets/${encodeURIComponent(checked.data.changeSetId)}/writes`,
-    { tool: name, nodeIds },
-  );
+  try {
+    await request(
+      "POST",
+      `/api/v1/design/change-sets/${encodeURIComponent(checked.data.changeSetId)}/writes`,
+      { tool: name, nodeIds },
+    );
+  } catch (error) {
+    // Name the set in the fix even when Dev's details leave it out.
+    if (error?.code === "WRITE_OUT_OF_SCOPE")
+      throw new CliError(error.code, error.message, error.exitCode ?? 1, { ...error.details, changeSetId: error.details?.changeSetId ?? checked.data.changeSetId });
+    throw error;
+  }
   return { logged: true, changeSetId: checked.data.changeSetId, nodeIds };
 }
 
+// What the post-hook says when logging a write fails. A write logged outside
+// the set's scopes (MW1-57.7) exits 2, so Claude Code shows the agent why its
+// submit will be refused; any other failure stays a note that blocks nothing.
+export function postHookFailure(error) {
+  if (error?.code === "WRITE_OUT_OF_SCOPE")
+    return { exitCode: 2, message: `nodii-dev post hook: WRITE_OUT_OF_SCOPE: ${outOfScopeText(error.message, error.details)}` };
+  return { exitCode: 0, message: `nodii-dev post hook: ${error?.code ?? "ERROR"}: ${error?.message ?? String(error)}` };
+}
+
 export const settingsSnippet = () => ({
   hooks: {
     PreToolUse: [

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.11",
+  "version": "0.6.13",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {