@nodii/dev 0.6.11 → 0.6.12

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,177 @@ 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");
+};
+
+const FOUNDATIONS_ID = /^(?:S:|VariableID:|VariableCollectionId:)/;
+
+/** 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));
+  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);
+  return fileCall(key, request)("POST", `/api/v1/design/files/${encode(key)}/published`, payload);
+}
+
+// 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);
+
+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}` : ""})`;
+
+/** 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"]),
+    ...(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 { figmaLockCheck, outOfScopeText } from "./figma.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -88,10 +89,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,17 +109,14 @@ 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({
@@ -129,14 +124,30 @@ export async function postHook(payload, request = devRequest) {
     response: payload.tool_response,
   });
   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/package.json

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