@nodii/dev 0.6.11 → 0.6.13

package/README.md

@@ -145,12 +145,14 @@ prints them without creating anything.
 
 ```bash
 nodii-dev figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
-nodii-dev figma lock FILE_KEY --title TEXT
+nodii-dev figma lock FILE_KEY --title TEXT [--scope KIND:ID ...]
+nodii-dev figma scope add CHANGE_SET --scope KIND:ID [--scope ...]
+nodii-dev figma publish-plan FILE_KEY
 nodii-dev figma check FILE_KEY
 nodii-dev figma log-write CHANGE_SET --tool TOOL --nodes NODE[,NODE]
 nodii-dev figma submit CHANGE_SET --file SUBMISSION.json
 nodii-dev figma apply CHANGE_SET --figma-version VERSION
-nodii-dev figma published CHANGE_SET --figma-version VERSION
+nodii-dev figma published FILE_KEY|CHANGE_SET --figma-version VERSION
 nodii-dev figma abandon CHANGE_SET
 nodii-dev figma withdraw CHANGE_SET    # take back a submit before anything is decided
 nodii-dev figma resubmit CHANGE_SET PAYLOAD.json   # round 2: re-submit every rejected item
@@ -170,6 +172,52 @@ that account). Registering a key Dev already has returns the stored row
 unchanged. A figma.com file link works in place of the key. `figma lock` on
 an unregistered file prints the `figma file add` command to run.
 
+**Scoped locks (DEC-0032).** A change set locks scopes inside a file, not
+the whole file, so lanes can change one file in parallel. Give `figma lock`
+one `--scope` per scope:
+
+| `--scope` | Claims |
+| --- | --- |
+| `component:NODE_ID` | a component set or standalone component, at its top-level node (a variant id is taken as its set) |
+| `page:NODE_ID` | a whole Figma page: new screens, specimens, docs pages |
+| `foundations` | the file's variables, text styles and effect styles; one holder at a time |
+| `create:PAGE_ID:NAME` | a new component, made on that page |
+
+A node id from a figma.com link (`12-34`) is read as Figma's `12:34`. Two
+sets conflict only when their scopes overlap: the same node, a page that holds
+a claimed component (or the reverse), or foundations already held. Dev
+refuses an overlap with `SCOPE_CONFLICT`; the CLI prints Dev's message, then
+the set holding the overlapping scope. `figma lock` without `--scope` locks the
+whole file, as older CLIs do, and that conflicts with every other set.
+`figma scope add` widens a set you hold, with the same check; nothing is ever
+widened silently.
+
+Every write must fall inside the set's scopes (MW1-57.7). The post-hook
+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`
+with the same code until it's fixed. You can widen the scope with
+`figma scope add` if it's free (styles and variables need
+`--scope foundations`), or revert the node exactly to how it was at the set's
+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, 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 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
 `withdrawDesignChangeSet`). Dev refuses when the change set doesn't exist
@@ -442,6 +490,7 @@ exits 0 only when every check is `OK`. `--json` returns the same checks as
 | `repo` | Whether the repository in this directory is the agent's home repository or granted to it. Repositories are compared by short name (`nodii-clis`, not `owner/nodii-clis`), as Dev compares them. Dev does not let an OAuth agent read its own grants yet (requested in Dev), so a repository other than the home one is `CANNOT CHECK`. |
 | `lane_limit` | The agent's active lanes against its lane limit. A full limit is `OK` when a lane on this branch holds the slot. |
 | `figma_file` | Only with `--figma-file KEY` (a key or figma.com link), or `NODII_DEV_FIGMA_FILE`: whether Dev has the brief's Figma file registered. `MISSING` names the `figma file add` command, since `figma lock` would fail with `DESIGN_FILE_NOT_FOUND`. |
+| `figma_scopes` | With `figma_file`, when the file is registered: the change set this agent holds in the file and its lock scopes (or the whole file), or that it holds none (DEC-0032). |
 
 Doctor may refresh the access token, as any command does. The permission table
 is kept by hand from Dev's route policy until Dev's OpenAPI names each
@@ -542,5 +591,6 @@ and `figma log-write` follows the same rule (`CHANGE_SET_NOT_EDITABLE`). The pre
 non-Figma tools and allowlisted Figma reads, but defaults to denying every
 Figma write if the file key is absent, Dev cannot be reached, or the lock
 is denied. It exits `2`, which makes Claude Code block the call. The post-hook
-best-effort logs the write and never blocks. Per D1433, Codex remains read-only
+best-effort logs the write and never blocks; it exits `2` only for
+`WRITE_OUT_OF_SCOPE`, after the write is logged, so the agent sees it. Per D1433, Codex remains read-only
 for Figma; this package does not write to Figma itself.

package/dist/cli.js

@@ -22,11 +22,30 @@ import {
   deviceLogin,
   revokeOAuth,
 } from "./oauth.js";
-import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
+import { heartbeatCurrentLane, postHook, postHookFailure, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
 import { doctorCommand } from "./doctor.js";
-import { figmaChangeSetShow, figmaChangeSetText, figmaFileKey, figmaResubmit, notRegisteredHint } from "./figma.js";
+import {
+  figmaChangeSetShow,
+  figmaChangeSetText,
+  figmaFileKey,
+  figmaFilePublished,
+  figmaFilePublishedText,
+  figmaLock,
+  figmaLockCheck,
+  figmaLockText,
+  figmaLogWrite,
+  figmaPublishPlan,
+  figmaPublishPlanText,
+  figmaResubmit,
+  figmaScopeAdd,
+  figmaSubmit,
+  isChangeSetId,
+  scopeText,
+  scopesFrom,
+} from "./figma.js";
+export { figmaLock } from "./figma.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import {
@@ -69,7 +88,13 @@ Usage: nodii-dev <command> [options] [--json]
   design guideline list [--drafted] [--all] | show ENTRY
   design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]
   design changeset list [--entry KEY] [--state STATE] | show ID
-  figma lock|check|log-write|submit|apply|published|abandon|release
+  figma lock FILE_KEY --title TEXT [--scope KIND:ID ...]
+                                        # scopes: component:NODE page:NODE foundations create:PAGE:NAME;
+                                        # no --scope locks the whole file (DEC-0032)
+  figma scope add CHANGE_SET --scope KIND:ID [--scope ...]   # widen a held set's scopes
+  figma publish-plan FILE_KEY           # what to publish, and what to leave unchecked in Figma's dialog
+  figma published FILE_KEY|CHANGE_SET --figma-version V   # a file key marks every awaiting set published
+  figma check|log-write|submit|apply|abandon|release
   figma withdraw CHANGE_SET             # holder takes back a submit: in_review -> editing (or a re-submit -> applying)
   figma resubmit CHANGE_SET PAYLOAD.json
                                         # holder re-submits every rejected item: applying -> in_review, round + 1
@@ -321,16 +346,6 @@ export async function figmaFileAdd(value, flags, { request = devRequest } = {})
   }
 }
 
-export async function figmaLock(value, title, { request = devRequest } = {}) {
-  const key = figmaFileKey(value);
-  try {
-    return await request("POST", `/api/v1/design/files/${encode(key)}/lock`, { changeSetTitle: title });
-  } catch (error) {
-    if (error?.code !== "DESIGN_FILE_NOT_FOUND") throw error;
-    throw new CliError(error.code, notRegisteredHint(key), error.exitCode ?? 1, error.details);
-  }
-}
-
 export async function main(argv = process.argv.slice(2)) {
   if (argv.length === 1 && ["--version", "-v"].includes(argv[0]))
     return console.log(VERSION);
@@ -589,7 +604,24 @@ export async function main(argv = process.argv.slice(2)) {
   }
   if (command === "figma") {
     if (action === "lock")
-      return emit(await figmaLock(rest[0], requireFlag(f, "title")), json);
+      return emit(await figmaLock(rest[0], requireFlag(f, "title"), { scopes: scopesFrom(f) }), json, (p) => figmaLockText(p.data));
+    if (action === "scope") {
+      if (rest[0] !== "add" || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma scope add CHANGE_SET --scope KIND:ID [--scope ...]", 2);
+      return emit(await figmaScopeAdd(rest[1], scopesFrom(f)), json, (p) =>
+        `${rest[1]} holds ${p.data?.scopes?.length ?? "its"} scope(s)${p.data?.scopes?.length ? `: ${p.data.scopes.map(scopeText).join(", ")}` : ""}`);
+    }
+    if (action === "publish-plan") {
+      if (!rest[0] || rest.length > 1) throw new CliError("USAGE", "figma publish-plan FILE_KEY", 2);
+      return emit(await figmaPublishPlan(rest[0]), json, (p) => figmaPublishPlanText(p.data));
+    }
+    // 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) => 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);
+    }
     if (action === "file") {
       if (rest[0] !== "add") throw new CliError("USAGE", "figma file add FILE_KEY --name TEXT --kind KIND [--module M]", 2);
       return emit(await figmaFileAdd(rest[1], f), json, (p) =>
@@ -597,10 +629,7 @@ export async function main(argv = process.argv.slice(2)) {
     }
     if (action === "check") {
       const c = await readConfig();
-      const result = await devRequest(
-        "GET",
-        `/api/v1/design/files/${encode(rest[0])}/lock/check?agentId=${encode(c.agentId)}`,
-      );
+      const result = await figmaLockCheck(figmaFileKey(rest[0]), c.agentId);
       emit(
         result,
         json,
@@ -611,18 +640,8 @@ export async function main(argv = process.argv.slice(2)) {
       return;
     }
     if (action === "log-write")
-      return emit(
-        await devRequest(
-          "POST",
-          `/api/v1/design/change-sets/${encode(rest[0])}/writes`,
-          {
-            tool: requireFlag(f, "tool"),
-            nodeIds: requireFlag(f, "nodes").split(",").filter(Boolean),
-          },
-        ),
-        json,
-      );
-    if (["submit", "apply", "published", "abandon"].includes(action)) {
+      return emit(await figmaLogWrite(rest[0], requireFlag(f, "tool"), requireFlag(f, "nodes").split(",").filter(Boolean)), json);
+    if (["apply", "published", "abandon"].includes(action)) {
       const payload = f.file
         ? JSON.parse(await readFile(f.file, "utf8"))
         : action === "abandon"
@@ -650,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,
@@ -690,9 +709,9 @@ export async function main(argv = process.argv.slice(2)) {
       try {
         return emit(await postHook(payload), json, "logged");
       } catch (error) {
-        console.error(
-          `nodii-dev post hook: ${error.code ?? "ERROR"}: ${error.message}`,
-        );
+        const outcome = postHookFailure(error);
+        console.error(outcome.message);
+        if (outcome.exitCode) process.exitCode = outcome.exitCode;
         return;
       }
     }

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.11";
+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") {