@nodii/dev 0.6.16 → 0.6.20

package/README.md

@@ -181,12 +181,15 @@ one `--scope` per scope:
 | --- | --- |
 | `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 |
+| `section:NODE_ID` | a Figma section and every node inside it (its own size and name too) |
 | `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
+a claimed component or section (or the reverse), a section that holds a
+claimed component or section (or the reverse), or foundations already held.
+Sibling sections don't conflict. 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.
@@ -399,6 +402,29 @@ version. A set never submitted needs `--file`: the body `figma submit --file`
 would send. A cold run can outlast the edge's gateway; the CLI then says
 `DEV_TIMEOUT` and to run it again (Dev keeps the mains it read for 5 minutes).
 
+### Large sets: submit as a Dev job
+
+`figma submit`, `figma resubmit` and `design check --change-set` send
+`Prefer: respond-async`. Dev answers 202 with a job, and the CLI polls it
+(`getDesignSubmitJob`) with backoff, printing progress on stderr, until it
+ends. The output and exit code are the synchronous call's: a succeeded job
+prints Dev's 200 body and warnings, a failed one its error and findings. A
+large set's gate outlasts the edge's 30 s timeout, so this is the default.
+
+- `a submit is already running: JOB`: Dev already runs a submit (or a dry run)
+  for this set (409 `SUBMIT_IN_PROGRESS` / `CONFORMANCE_IN_PROGRESS`). The CLI
+  polls that job instead of sending again, then exits 1 with the 409's code
+  and that job's outcome (`--json`: `details.result` or `details.error`):
+  this command's body was not sent, so read the set and run it again if it
+  still needs to go.
+- `SUBMIT_JOB_LOST`: Dev restarted while the job ran. Run the same command again.
+- `SUBMIT_JOB_UNREACHABLE`: polling lost the edge; the job runs on in Dev.
+  Read the set with `figma changeset show` before sending it again.
+- `--sync` sends the old single request. If it (or a submit's 202) meets the
+  edge's 502 or 504, the CLI reads the set and says whether the submit landed;
+  it never resends. `SUBMIT_UNCONFIRMED` means it hasn't yet: check with
+  `figma changeset show` before submitting again.
+
 When `figma submit`, `figma resubmit` or the dry run hits
 `DS_CONFORMANCE_FAILED`, the CLI prints each finding and Dev's warnings. A
 submit Dev accepts prints its warnings too. On a stale version it also prints

package/dist/cli.js

@@ -43,12 +43,13 @@ import {
   figmaScopeSet,
   figmaScopeSetText,
   figmaSubmit,
+  submitMode,
   isChangeSetId,
   scopeText,
   scopesFrom,
   conformanceLines,
 } from "./figma.js";
-export { figmaLock } from "./figma.js";
+export { figmaLock, submitMode } from "./figma.js";
 import { docsCommand, rulebookCommand, rulesCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import { designCheck, designCheckText, designRoles, designRolesText } from "./design.js";
@@ -96,19 +97,23 @@ Usage: nodii-dev <command> [options] [--json]
   design check FILE_KEY|LINK [--nodes A,B] [--roles R,S] [--library]
                                         # the DS conformance check Dev's submit runs, before you submit;
                                         # reads Figma with FIGMA_PAT; exit 1 = DS_CONFORMANCE_FAILED or an error (--json: data.passed)
-  design check --change-set CS [--file SUBMIT.json] [--figma-version V]
+  design check --change-set CS [--file SUBMIT.json] [--figma-version V] [--sync]
                                         # Dev's dry run of the submit gate on a set, with the image guard;
                                         # a stale version is a warning that prints when to retry
   figma lock FILE_KEY --title TEXT [--scope KIND:ID ...]
-                                        # scopes: component:NODE page:NODE foundations create:PAGE:NAME;
+                                        # scopes: component:NODE page:NODE section: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 scope set CHANGE_SET --scope KIND:ID [--scope ...]   # narrow to exactly these; the rest frees
   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 submit CHANGE_SET --file SUBMIT.json [--sync]
+                                        # submit, resubmit and design check --change-set run as a job in Dev
+                                        # and poll it (a large set outlasts the edge's timeout); --sync waits
+                                        # on one request instead. A 502/504 is checked against the set, never resent
   figma withdraw CHANGE_SET             # holder takes back a submit: in_review -> editing (or a re-submit -> applying)
-  figma resubmit CHANGE_SET PAYLOAD.json
+  figma resubmit CHANGE_SET PAYLOAD.json [--sync]
                                         # 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]
@@ -428,7 +433,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "design" && action === "roles") return emit(await designRoles(rest), json, designRolesText);
   if (command === "design" && action === "check") {
     if ((!rest[0] && f["change-set"] === undefined) || rest.length > 1)
-      throw new CliError("USAGE", "design check FILE_KEY|LINK [--nodes A,B] [--roles R,S] [--library] | design check --change-set CS [--file SUBMIT.json] [--figma-version V]", 2);
+      throw new CliError("USAGE", "design check FILE_KEY|LINK [--nodes A,B] [--roles R,S] [--library] | design check --change-set CS [--file SUBMIT.json] [--figma-version V] [--sync]", 2);
     const result = await designCheck(rest[0], f);
     emit(result.payload, json, result.human ?? designCheckText);
     if (result.exitCode) {
@@ -646,7 +651,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (action === "submit") {
       const payload = f.file ? JSON.parse(await readFile(f.file, "utf8")) : { figmaVersion: requireFlag(f, "figma-version") };
       // A 200 carries top-level warnings (STALE_FIGMA_VERSION): print them.
-      return emit(await figmaSubmit(rest[0], payload), json, (p) =>
+      return emit(await figmaSubmit(rest[0], payload, { sync: submitMode(f) }), json, (p) =>
         [JSON.stringify(p.data, null, 2), ...conformanceLines({ warnings: p.warnings })].join("\n"));
     }
     if (action === "file") {
@@ -686,7 +691,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (action === "withdraw")
       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) =>
+      return emit(await figmaResubmit(rest[0], rest[1], { sync: submitMode(f) }), json, (p) =>
         [`Re-submitted ${rest[0]}; it is ${p.data.state}.`, figmaChangeSetText(p.data), ...conformanceLines({ warnings: p.warnings })].join("\n"));
     if (action === "changeset") {
       if (rest[0] !== "show" || !rest[1] || rest.length > 2) throw new CliError("USAGE", "figma changeset show CHANGE_SET", 2);

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.16";
+export const VERSION = "0.6.20";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -113,7 +113,7 @@ const staleCode = (raw) => {
   }
 };
 
-async function devFetch(method, path, bodyText, contentType, accept) {
+async function devFetch(method, path, bodyText, contentType, accept, extra = {}) {
   const config = await readConfig();
   const auth = await authProvider();
   const url = requestUrl(config, path);
@@ -124,7 +124,7 @@ async function devFetch(method, path, bodyText, contentType, accept) {
   let refreshed = false;
   let adopted = false;
   for (;;) {
-    const headers = { accept };
+    const headers = { accept, ...extra };
     if (bodyText !== undefined) headers["content-type"] = contentType;
     Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
     let response;
@@ -143,8 +143,9 @@ async function devFetch(method, path, bodyText, contentType, accept) {
   }
 }
 
-export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
-  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json");
+/** A JSON call that keeps the status: `{ status, payload }`. Errors throw as devRawRequest's do. */
+export async function devExchange(method, path, bodyText, { contentType = "application/json", headers = {} } = {}) {
+  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json", headers);
   let payload;
   try {
     payload = raw ? JSON.parse(raw) : {};
@@ -158,7 +159,11 @@ export async function devRawRequest(method, path, bodyText, contentType = "appli
       1,
       payload.details,
     );
-  return payload;
+  return { status: response.status, payload };
+}
+
+export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
+  return (await devExchange(method, path, bodyText, { contentType })).payload;
 }
 
 /** A Dev route that answers with text (e.g. a document body as text/markdown). Errors are Dev's JSON. */
@@ -173,6 +178,10 @@ export async function devTextRequest(method, path) {
 export const devRequest = (method, path, body) =>
   devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body));
 
+/** A JSON call sent with `Prefer: respond-async` (RFC 7240): `{ status, payload }`, 202 when Dev took it as a job. */
+export const devAsyncRequest = async (method, path, body) =>
+  devExchange(method, path, body === undefined ? undefined : JSON.stringify(body), { headers: { prefer: "respond-async" } });
+
 /** Proves the stored OAuth login works: a token refresh, then the agent read once registered. */
 export async function checkLogin() {
   const config = await readConfig();
@@ -184,7 +193,7 @@ export async function checkLogin() {
 export const encode = (value) => encodeURIComponent(value);
 // Switches never take the next token as their value, so
 // `docs upload --wait rulebook/` keeps rulebook/ as a path.
-const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library"]);
+const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted", "library", "async", "sync"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];

package/dist/design.js

@@ -8,7 +8,7 @@
 // library main.
 import { readFile } from "node:fs/promises";
 import { CliError, devRequest } from "./core.js";
-import { conformanceLines, figmaConformance, figmaFileKey } from "./figma.js";
+import { conformanceLines, figmaConformance, figmaFileKey, submitMode } from "./figma.js";
 import { checkConformance, neededMains, VERSION as CHECK_VERSION } from "./vendor/ds-conformance.mjs";
 
 const FIGMA_API = "https://api.figma.com/v1";
@@ -159,7 +159,7 @@ export async function lastPublish(figmaGet, fileKey) {
 /**
  * The main of each instance, keyed by the instance's componentId (this file's
  * id for it), resolved as Dev's gate resolves it (Dev issue 92, conformance
- * 1.0.3), so both give one verdict:
+ * 1.0.4), so both give one verdict:
  * - a local component (remote: false) is read from this file;
  * - a remote one is found in the DS file's published listing, else by Figma's
  *   lookup of its key, and is read only from a library Dev has registered
@@ -273,8 +273,10 @@ const nodeId = (x) => (/^\d+-\d+$/.test(x) ? x.replace("-", ":") : x);
  * finding fails; stale overrides (a value equal to the main's) are listed but
  * never fail (DEC-0035).
  */
-export async function designCheck(target, flags = {}, { request = devRequest, env = process.env, figmaGet, read } = {}) {
-  if (flags["change-set"] !== undefined) return designCheckChangeSet(target, flags, { request, ...(read ? { read } : {}) });
+export async function designCheck(target, flags = {}, { request = devRequest, send, progress, env = process.env, figmaGet, read } = {}) {
+  submitMode(flags);
+  if (flags["change-set"] !== undefined)
+    return designCheckChangeSet(target, flags, { request, ...(send ? { send } : {}), ...(progress ? { progress } : {}), ...(read ? { read } : {}) });
   // A --nodes that names nothing must not widen to every page.
   if (flags.nodes !== undefined && ([flags.nodes].flat().includes(true) || !list(flags.nodes).length))
     throw new CliError("USAGE", "--nodes needs node ids, e.g. --nodes 12:34,12:56", 2);
@@ -345,6 +347,8 @@ export async function designCheck(target, flags = {}, { request = devRequest, en
     // Same value through a different variable: the file is behind a library
     // republish. Accept the update in Figma (MW6-17); never a failure.
     libraryUpdatePending: result.libraryUpdatePending ?? [],
+    // What the app-UI gate leaves out (email), with its node count (Dev issue 116).
+    outOfScope: result.outOfScope ?? [], outOfScopeNodes: result.outOfScopeNodes ?? 0,
     warnings,
   };
   return { payload: { data }, exitCode: data.passed ? 0 : 1 };
@@ -367,8 +371,9 @@ export function designCheckText({ data }) {
  * plus the submit-time guards against the set's items: IMAGE_NOT_TRUECOLOR
  * refuses; STALE_FIGMA_VERSION is a warning. Changes no state.
  */
-export async function designCheckChangeSet(target, flags, { request = devRequest, read = (f) => readFile(f, "utf8") } = {}) {
+export async function designCheckChangeSet(target, flags, { request = devRequest, send, progress, read = (f) => readFile(f, "utf8") } = {}) {
   const id = flags["change-set"];
+  const sync = submitMode(flags);
   if (id === true || !id) throw new CliError("USAGE", "--change-set needs a change set id, e.g. --change-set CS-123", 2);
   if (target !== undefined) throw new CliError("USAGE", "design check --change-set CS takes no file: Dev checks the set's own items", 2);
   if (flags["figma-version"] === true) throw new CliError("USAGE", "--figma-version needs a version id", 2);
@@ -387,17 +392,18 @@ export async function designCheckChangeSet(target, flags, { request = devRequest
   if (flags["figma-version"]) body = { ...body, figmaVersion: String(flags["figma-version"]) };
   let p;
   try {
-    p = await figmaConformance(id, body, { request });
+    p = await figmaConformance(id, body, { request, sync, ...(send ? { send } : {}), ...(progress ? { progress } : {}) });
   } catch (error) {
     // A cold run reads every root and main from Figma and can outlast the
     // edge's gateway (504, an HTML page). Dev keeps the mains it read for 5
     // minutes, so the same run again usually answers.
-    if (error?.code !== "HTTP_504") throw error;
-    throw new CliError("DEV_TIMEOUT", `Dev's dry run of ${id} ran past the edge's gateway timeout while reading Figma; run it again (Dev keeps the library mains it read for 5 minutes)`, 1);
+    if (error?.code !== "HTTP_504" && error?.code !== "HTTP_502") throw error;
+    throw new CliError("DEV_TIMEOUT", `Dev's dry run of ${id} ran past the edge's gateway timeout while reading Figma; run it again${sync ? " without --sync, so Dev runs it as a job" : ""} (Dev keeps the library mains it read for 5 minutes)`, 1);
   }
   const r = p.data ?? {};
   const data = { changeSetId: id, checkVersion: r.version, passed: Boolean(r.passed), checked: r.checked, findings: r.findings ?? [],
-    staleOverrides: r.staleOverrides ?? [], libraryUpdatePending: r.libraryUpdatePending ?? [], warnings: r.warnings ?? [], staleVersion: r.staleVersion ?? null };
+    staleOverrides: r.staleOverrides ?? [], libraryUpdatePending: r.libraryUpdatePending ?? [],
+    outOfScope: r.outOfScope ?? [], outOfScopeNodes: r.outOfScopeNodes ?? 0, warnings: r.warnings ?? [], staleVersion: r.staleVersion ?? null };
   return { payload: { data }, exitCode: data.passed ? 0 : 1, human: designCheckChangeSetText };
 }