@nodii/dev 0.6.7 → 0.6.9

package/README.md

@@ -59,7 +59,7 @@ nodii-dev login [--no-browser] [--scope KEYS]
 nodii-dev logout
 nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
-nodii-dev doctor [--json]          # preflight: everything a lane needs, read-only
+nodii-dev doctor [--figma-file KEY] [--json]   # preflight: everything a lane needs, read-only
 
 nodii-dev api list [--tag TAG] [--json]
 nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
@@ -137,6 +137,7 @@ only the lists that differ from Dev's current guideline, and `--dry-run`
 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 check FILE_KEY
 nodii-dev figma log-write CHANGE_SET --tool TOOL --nodes NODE[,NODE]
@@ -145,10 +146,23 @@ nodii-dev figma apply CHANGE_SET --figma-version VERSION
 nodii-dev figma published 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
+nodii-dev figma changeset show CHANGE_SET          # items, variants, round, decision, comment
 nodii-dev figma release FILE_KEY
 
 ```
 
+`figma file add` registers a Figma file in Dev so it can be locked; a lane
+can't lock a file Dev doesn't know (`DESIGN_FILE_NOT_FOUND`). Dev first
+reads the file from Figma with its own token. The name must be the file's
+name in Figma: when it isn't, Dev refuses with `DESIGN_FILE_NAME_MISMATCH`
+and the CLI prints the real name to run it again with. Dev also refuses a
+key Figma doesn't know, or a file its Figma account can't see
+(`FIGMA_FILE_NOT_FOUND`, `FIGMA_FILE_NOT_READABLE`: share the file with
+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.
+
 `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
@@ -156,7 +170,42 @@ nodii-dev figma release FILE_KEY
 aren't its holder or an operator (`WITHDRAW_NOT_ALLOWED`), or an item is
 already decided (`CHANGE_SET_HAS_DECISIONS`: ask the reviewer to request
 changes instead). The CLI prints each refusal in plain words and keeps the
-code.
+code. Withdrawing an undecided re-submit returns the set to `applying`.
+
+`figma changeset show` lists a Figma change set's current items (the latest
+round of each): each one's decision, its comment (a rejection always has one), its
+round, the previous round's decision and comment when it was re-submitted,
+and its variants. It reads Dev's `getDesignChangeSet`; `--json` also gives the
+replaced rows (`previousRounds`) and the write log. Guideline change sets are
+`design changeset show`.
+
+`figma resubmit` is round 2 inside the same change set (Dev's
+`resubmitDesignChangeSet`). When every item is decided and some were
+rejected, the set is `applying`: rework the rejected items in Figma (the lock
+check allows writes in `applying`, and refuses them only while a submit is
+`in_review`), then re-submit them. The payload names every rejected item, by
+`itemId` or `figmaNodeId`, with its new variants, exported at 2x as for
+`figma submit`:
+
+```json
+{
+  "figmaVersion": "VERSION",
+  "items": [
+    { "figmaNodeId": "36:531", "variants": [{ "nodeId": "36:532", "afterPngBase64": "..." }] }
+  ]
+}
+```
+
+A variant without a PNG is rendered from Figma, and a variant keeps the
+"before" image from its earlier round. Each item goes back to review with its
+round + 1; approved items keep their decisions; the set goes `in_review`.
+`figma apply` runs once, when every item is approved. Dev refuses when you
+aren't the holder (`CHANGE_SET_HOLDER_REQUIRED`), the set isn't `applying`
+(`INVALID_CHANGE_SET_STATE`), nothing is rejected
+(`CHANGE_SET_HAS_NO_REJECTIONS`), a rejected item is missing (`REJECTED_ITEMS_MISSING`:
+the CLI lists each one with its comment), or the payload names an item that
+isn't rejected (`CHANGE_ITEM_NOT_REJECTED`); images go through the same
+style check as a submit (`CHANGE_SET_IMAGE_STYLE`).
 
 ```bash
 nodii-dev hook claude-figma-pre       # reads Claude Code hook JSON on stdin
@@ -333,6 +382,7 @@ exits 0 only when every check is `OK`. `--json` returns the same checks as
 | `machine` | The machine this agent is assigned to and its coordinator. No machine means `lane start` would fail with `MACHINE_REQUIRED`. |
 | `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`. |
 
 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
@@ -426,7 +476,9 @@ surfaces, service edges, lanes, swaps, ideas, terminology, and the AD era: `rule
 `archive` (`archive resolve --ref pre:D1366`), and `harness methodology`. `api list` is the authoritative discovery view;
 `api OPERATION_ID` makes every operation callable even without an alias.
 
-`figma check` exits `0` when allowed and `3` when denied. The pre-hook permits
+`figma check` exits `0` when allowed and `3` when denied. A held lock is
+denied only while its change set is `in_review` (`change-set-not-editable`),
+and `figma log-write` follows the same rule (`CHANGE_SET_NOT_EDITABLE`). The pre-hook permits
 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

package/dist/cli.js

@@ -26,6 +26,7 @@ import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSugge
 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 { docsCommand, rulebookCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import {
@@ -55,7 +56,8 @@ const HELP = `nodii-dev ${VERSION}
 Usage: nodii-dev <command> [options] [--json]
 
   login | logout | whoami | config show
-  doctor [--json]                       # preflight: sign-in, agent, permissions, machine, repo, lane slots
+  doctor [--figma-file KEY] [--json]    # preflight: sign-in, agent, permissions, machine, repo, lane slots
+                                        # and, given a key (or NODII_DEV_FIGMA_FILE), that Figma file's registration
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
   issues transition ISSUE --to STATUS [--reason TEXT] [--dev-check REF]
@@ -68,7 +70,12 @@ Usage: nodii-dev <command> [options] [--json]
   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 withdraw CHANGE_SET             # holder takes back a submit: in_review -> editing
+  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
+  figma changeset show CHANGE_SET       # items, variants, round, decision and comment (with the previous round's)
+  figma file add FILE_KEY --name TEXT --kind design-system|surfaces|prototype [--module M]
+                                        # register a Figma file in Dev so it can be locked
   hook claude-figma-pre|claude-figma-post|print-settings
   setup [--yes|--check]                 # dry-run by default
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run]
@@ -288,6 +295,38 @@ export async function figmaWithdraw(id, { request = devRequest } = {}) {
   }
 }
 
+// Dev's refusals of registerDesignFile, said in terms of what to do next.
+const REGISTER_REFUSALS = {
+  DESIGN_FILE_NAME_MISMATCH: (key, details, message) =>
+    details?.figmaName ? `Figma names ${key} "${details.figmaName}"; run it again with --name "${details.figmaName}".` : message,
+  FIGMA_FILE_NOT_FOUND: (key) => `Figma has no file ${key} that Dev's Figma account can see; check the key, or share the file with that account.`,
+  FIGMA_FILE_NOT_READABLE: (key) => `Dev's Figma account can't read ${key}; share the file with that account.`,
+};
+
+export async function figmaFileAdd(value, flags, { request = devRequest } = {}) {
+  if (!value) throw new CliError("USAGE", "figma file add FILE_KEY --name TEXT --kind KIND [--module M]", 2);
+  const key = figmaFileKey(value);
+  if (flags.module === true) throw new CliError("USAGE", "--module needs a value", 2);
+  const body = { key, name: requireFlag(flags, "name"), kind: requireFlag(flags, "kind"), ...(flags.module ? { module: flags.module } : {}) };
+  try {
+    return await request("POST", "/api/v1/design/files", body);
+  } catch (error) {
+    const say = REGISTER_REFUSALS[error?.code];
+    if (!say) throw error;
+    throw new CliError(error.code, say(key, error.details, error.message), error.exitCode ?? 1, error.details);
+  }
+}
+
+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);
@@ -338,7 +377,8 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "setup") return emitCommand(await setupCommand(f));
   if (command === "doctor") {
     if (action) throw new CliError("USAGE", `doctor takes no arguments, got: ${[action, ...rest].join(" ")}`, 2);
-    const result = await doctorCommand();
+    if (f["figma-file"] === true) throw new CliError("USAGE", "--figma-file needs a file key or figma.com link", 2);
+    const result = await doctorCommand(f["figma-file"] ? { figmaFile: f["figma-file"] } : {});
     emit(result.payload, json, result.human);
     if (result.exitCode) process.exitCode = result.exitCode;
     return;
@@ -544,14 +584,12 @@ export async function main(argv = process.argv.slice(2)) {
   }
   if (command === "figma") {
     if (action === "lock")
-      return emit(
-        await devRequest(
-          "POST",
-          `/api/v1/design/files/${encode(rest[0])}/lock`,
-          { changeSetTitle: requireFlag(f, "title") },
-        ),
-        json,
-      );
+      return emit(await figmaLock(rest[0], requireFlag(f, "title")), 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) =>
+        `${p.data.fileKey} is registered in Dev: ${p.data.name} (${p.data.kind}${p.data.module ? `, ${p.data.module}` : ""}).`);
+    }
     if (action === "check") {
       const c = await readConfig();
       const result = await devRequest(
@@ -595,7 +633,14 @@ export async function main(argv = process.argv.slice(2)) {
       );
     }
     if (action === "withdraw")
-      return emit(await figmaWithdraw(rest[0]), json, `Withdrew ${rest[0]}; it is back in editing.`);
+      return emit(await figmaWithdraw(rest[0]), json, (p) => `Withdrew ${rest[0]}; it is back in ${p.data?.state ?? "editing"}.`);
+    if (action === "resubmit")
+      return emit(await figmaResubmit(rest[0], rest[1]), json, (p) =>
+        [`Re-submitted ${rest[0]}; it is ${p.data.state}.`, figmaChangeSetText(p.data)].join("\n"));
+    if (action === "changeset") {
+      if (rest[0] !== "show" || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma changeset show CHANGE_SET", 2);
+      return emit(await figmaChangeSetShow(rest[1]), json, (p) => figmaChangeSetText(p.data));
+    }
     if (action === "release")
       return emit(
         await devRequest(

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.7";
+export const VERSION = "0.6.9";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");