@nodii/dev 0.6.6 → 0.6.8

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]
@@ -144,8 +145,32 @@ 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 abandon CHANGE_SET
+nodii-dev figma withdraw CHANGE_SET    # take back a submit before anything is decided
 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
+(`CHANGE_SET_NOT_FOUND`), isn't in review (`CHANGE_SET_NOT_IN_REVIEW`), you
+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.
+
+```bash
 nodii-dev hook claude-figma-pre       # reads Claude Code hook JSON on stdin
 nodii-dev hook claude-figma-post      # reads Claude Code hook JSON on stdin
 nodii-dev hook print-settings         # prints managed-settings JSON; writes nothing
@@ -320,6 +345,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

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 { figmaFileKey, 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,6 +70,9 @@ 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 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]
@@ -268,6 +273,57 @@ export function transitionBody(f) {
   return { to, ...(note ? { note } : {}) };
 }
 
+// Dev's refusals of withdrawDesignChangeSet, said in terms of what to do next.
+const WITHDRAW_REFUSALS = {
+  CHANGE_SET_NOT_FOUND: (id) => `No change set ${id} in Dev.`,
+  CHANGE_SET_NOT_IN_REVIEW: (id) => `${id} is not in review; only a submitted (in_review) change set can be withdrawn.`,
+  WITHDRAW_NOT_ALLOWED: (id) => `You don't hold ${id}; only its holder (or an operator) can withdraw it.`,
+  CHANGE_SET_HAS_DECISIONS: (id) => `${id} already has a decided item, so it can't be withdrawn; ask the reviewer to request changes instead.`,
+};
+
+export async function figmaWithdraw(id, { request = devRequest } = {}) {
+  if (!id) throw new CliError("USAGE", "figma withdraw CHANGE_SET", 2);
+  try {
+    return await request("POST", `/api/v1/design/change-sets/${encode(id)}/withdraw`, {});
+  } catch (error) {
+    const say = WITHDRAW_REFUSALS[error?.code];
+    if (!say) throw error;
+    throw new CliError(error.code, say(id), error.exitCode ?? 1, error.details);
+  }
+}
+
+// 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);
@@ -318,7 +374,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;
@@ -524,14 +581,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(
@@ -574,6 +629,8 @@ export async function main(argv = process.argv.slice(2)) {
         json,
       );
     }
+    if (action === "withdraw")
+      return emit(await figmaWithdraw(rest[0]), json, `Withdrew ${rest[0]}; it is back in editing.`);
     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.6";
+export const VERSION = "0.6.8";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");