@nodii/dev 0.6.17 → 0.6.21

package/README.md

@@ -12,9 +12,30 @@ Linux only (the launcher is a POSIX shell script).
 nodii-dev login                      # opens the approval page in your browser
 nodii-dev login --no-browser         # prints the link and code instead
 nodii-dev login --scope devops.issues.read,devops.issues.write   # narrower grant
+nodii-dev login --force              # replace the machine's sign-in (never from a lane)
 nodii-dev agent register --name my-agent
 ```
 
+A machine has **one sign-in**. The refresh credential is kept in the keychain
+under the OAuth client, not beside a config file, so every config path on the
+machine (`NODII_DEV_CONFIG_PATH`) shares it. `login` checks it first: when the
+shared access token is live or the refresh credential refreshes, it prints
+"You're already signed in as PERSON on this machine." and exits 0 without a
+device flow, from any config path, an empty or new one included (it writes
+the routing there, without an agent). A sign-in nodii-auth no longer accepts
+(`invalid_grant`), or a refresh it refuses outright, is named, then replaced
+by a device flow. If nodii-auth cannot be reached, or the keychain cannot be
+read, `login` stops: that says nothing about the sign-in. A different
+`--scope` replaces the one sign-in, so with a valid one it needs `--force`.
+`login --force` starts a device flow whatever the machine holds and names the
+person it replaces. A lane's config (`lane-*.json`) never starts a device
+flow (`--force`, or `login` over a dead sign-in: the coordinator signs in) and
+refuses `logout`; both end the one sign-in for every lane.
+`agent register` on a fresh, empty config path takes the machine's sign-in the
+same way (the OAuth client and hosts from the machine's newest config, the
+person and installation from the token; `NODII_DEV_*` variables override),
+so a new lane needs no login and no hand-seeded config.
+
 `nodii-dev` talks only to Dev, through the platform edge
 (`https://platform.nucleus-cloud.in/devops/*`), signed in as the platform
 tenant's nodii-dev OAuth app (D1368). There is no other host and no other way
@@ -62,7 +83,7 @@ Dev failures print Dev's error code to stderr and exit non-zero.
 ## Commands
 
 ```text
-nodii-dev login [--no-browser] [--scope KEYS]
+nodii-dev login [--no-browser] [--scope KEYS] [--force]
 nodii-dev logout
 nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
@@ -82,7 +103,8 @@ nodii-dev issues list [--service ID] [--project KEY] [--status STATUS]
 nodii-dev issues show ISSUE
 nodii-dev issues create --service ID --title TEXT [--body TEXT|--body-file FILE]
                         [--kind KIND] [--priority PRIORITY] [--project KEY]
-nodii-dev issues update ISSUE [the same mutable fields]
+nodii-dev issues update ISSUE [the same mutable fields] [--comment TEXT|--comment-file FILE]
+nodii-dev issues comment ISSUE --body TEXT|--body-file FILE   # commentOnIssue, on the issue's activity feed
 nodii-dev issues claim ISSUE [--ttl MINUTES]
 nodii-dev issues release ISSUE [--note TEXT]
 nodii-dev issues transition ISSUE --to todo|in_progress|in_review|blocked|done|wont_do
@@ -280,7 +302,9 @@ nodii-dev hook print-settings         # prints managed-settings JSON; writes not
 
 nodii-dev lane start KEY --title TEXT --kind dev_fix|new_build|docs_change|uat_fix|prod_fix
                      --side backend|frontend|both [--repo REPO] [--issue ISSUE]
-nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP
+nodii-dev lane step KEY --side backend|frontend --start|--done|--block STEP [--reason TEXT]
+                    # --reason is kept as a lane note; on a step already blocked,
+                    # --block --reason records the new reason (Dev issue 125 moves it onto the step)
 nodii-dev lane evidence KEY --pr|--commit|--figma|--deploy|--dev-check REF
 nodii-dev lane heartbeat KEY [--note TEXT]
 nodii-dev lane review KEY
@@ -402,6 +426,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

@@ -15,11 +15,9 @@ import {
   writeConfig,
 } from "./core.js";
 import {
-  DEFAULT_AUTH_URL,
-  DEFAULT_CLIENT_ID,
-  DEFAULT_EDGE_URL,
-  PLATFORM_TENANT,
-  deviceLogin,
+  adoptMachineSignIn,
+  login as signIn,
+  refuseFromLane,
   revokeOAuth,
 } from "./oauth.js";
 import { heartbeatCurrentLane, postHook, postHookFailure, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
@@ -43,12 +41,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";
@@ -78,11 +77,14 @@ const HELP = `nodii-dev ${VERSION}
 
 Usage: nodii-dev <command> [options] [--json]
 
-  login | logout | whoami | config show
+  login [--force] | logout | whoami | config show
+                                        # login says so when the machine is already signed in; --force
+                                        # replaces that one sign-in (never from a lane)
   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 comment ISSUE --body TEXT      # or --body-file FILE; issues update --comment TEXT|--comment-file FILE adds one too
   issues transition ISSUE --to STATUS [--reason TEXT] [--dev-check REF]
                                         # blocked and wont_do need --reason; done needs --dev-check
   inbox list|show
@@ -96,7 +98,7 @@ 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 ...]
@@ -107,8 +109,12 @@ Usage: nodii-dev <command> [options] [--json]
   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]
@@ -129,7 +135,8 @@ Usage: nodii-dev <command> [options] [--json]
   rules cap TOKENS                      # operator: set the core token cap (default 3000)
 
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
-  lane step <key> --side SIDE --start|--done|--block <step>
+  lane step <key> --side SIDE --start|--done|--block <step> [--reason TEXT]
+                                        # --block --reason on a blocked step records its new reason
   lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
   lane heartbeat|review|land|verify|prioritize|deprioritize|stop <key>
   lane non-issue <key> --reason TEXT --evidence TEXT --reroute KEY[,KEY]|none
@@ -194,18 +201,22 @@ async function login(flags, json) {
         "nodii-dev talks only to Dev, through the platform edge, signed in as the platform tenant's OAuth app. Run `nodii-dev login`.",
       2,
     );
-  const previous = await readConfig(false);
-  const result = await deviceLogin({
-    clientId: flags["client-id"] ?? process.env.NODII_DEV_OAUTH_CLIENT_ID ?? previous?.clientId ?? DEFAULT_CLIENT_ID,
-    authUrl: flags["auth-url"] ?? process.env.NODII_DEV_AUTH_URL ?? DEFAULT_AUTH_URL,
-    edgeUrl: flags["edge-url"] ?? process.env.NODII_DEV_EDGE_URL ?? DEFAULT_EDGE_URL,
-    tenantHint: flags["tenant-hint"] ?? process.env.NODII_DEV_PLATFORM_TENANT_ID ?? PLATFORM_TENANT,
+  const result = await signIn({
+    force: flags.force === true,
+    previous: await readConfig(false),
+    clientId: flags["client-id"] ?? process.env.NODII_DEV_OAUTH_CLIENT_ID,
+    authUrl: flags["auth-url"] ?? process.env.NODII_DEV_AUTH_URL,
+    edgeUrl: flags["edge-url"] ?? process.env.NODII_DEV_EDGE_URL,
+    tenantHint: flags["tenant-hint"] ?? process.env.NODII_DEV_PLATFORM_TENANT_ID,
     noBrowser: Boolean(flags["no-browser"]),
     scope: flags.scope,
     output: json ? console.error : console.log,
-    previous,
   });
-  return emit({ loggedIn: true, provider: "oauth", credentialStorage: result.storage, agentId: result.agentId }, json,
+  if (result.alreadySignedIn)
+    return emit({ loggedIn: true, alreadySignedIn: true, provider: "oauth", person: result.person, agentId: result.agentId }, json,
+      `You're already signed in${result.person ? ` as ${result.person}` : ""} on this machine.${result.agentId ? "" : " Run `nodii-dev agent register --name NAME` next."}`);
+  return emit({ loggedIn: true, alreadySignedIn: false, provider: "oauth", person: result.person, credentialStorage: result.storage, agentId: result.agentId,
+    ...(result.replaced !== undefined ? { replaced: result.replaced } : {}), ...(result.replacedDeadSignIn ? { replacedDeadSignIn: result.replacedDeadSignIn } : {}) }, json,
     result.agentId
       ? `OAuth login complete; refresh credential stored in ${result.storage}. Kept agent registration ${result.agentId}.`
       : `OAuth login complete; refresh credential stored in ${result.storage}. Run \`nodii-dev agent register --name NAME\` next.`);
@@ -232,6 +243,18 @@ async function issues(action, args, f, json) {
   if (action === "show")
     return emit(await devRequest("GET", `/api/v1/issues/${encode(ref)}`), json);
   const config = await readConfig();
+  // commentOnIssue. `issues update --comment` sent no field PATCH accepts (HTTP 400): a comment is its own route.
+  const commentBody = async (name) => {
+    const body = await bodyFlag(f, name);
+    if (typeof body !== "string" || !body.trim())
+      throw new CliError("USAGE", `issues ${action} ISSUE --${name} TEXT (or --${name}-file FILE)`, 2);
+    if (body.length > COMMENT_MAX) throw new CliError("USAGE", `The comment is ${body.length} characters; Dev keeps at most ${COMMENT_MAX}.`, 2);
+    return body;
+  };
+  const comment = (key, body) => devRequest("POST", `/api/v1/issues/${encode(key)}/comment`, { body, onBehalfOf: config.person });
+  if (action === "comment") return emit(await comment(ref, await commentBody("body")), json, `${ref}: comment added.`);
+  // Read and checked before anything is sent, so a bad comment changes nothing.
+  const note = ["create", "update"].includes(action) && (f.comment !== undefined || f["comment-file"] !== undefined) ? await commentBody("comment") : undefined;
   if (action === "create" || action === "update") {
     const bodyMd = await bodyFlag(f);
     const payload = {
@@ -252,11 +275,23 @@ async function issues(action, args, f, json) {
         ].filter(([, v]) => v !== undefined),
       ),
     };
+    // An update with nothing to PATCH but a comment is only the comment.
+    if (action === "update" && note !== undefined && Object.keys(payload).every((k) => k === "onBehalfOf"))
+      return emit(await comment(ref, note), json, `${ref}: comment added.`);
     const result = await devRequest(
       action === "create" ? "POST" : "PATCH",
       action === "create" ? "/api/v1/issues" : `/api/v1/issues/${encode(ref)}`,
       payload,
     );
+    // After the write, so a refused create or update leaves no comment behind.
+    if (note !== undefined) {
+      const key = result.data?.key ?? ref;
+      try {
+        await comment(key, note);
+      } catch (error) {
+        throw new CliError("COMMENT_FAILED", `${key} was ${action}d, but the comment was not posted (${error?.code ?? "error"}: ${error?.message ?? error}). Post it with \`nodii-dev issues comment ${key} --body TEXT\`.`, 1, { issue: result.data ?? null });
+      }
+    }
     return emit(
       result,
       json,
@@ -291,6 +326,8 @@ async function issues(action, args, f, json) {
   throw new CliError("USAGE", `Unknown issues action: ${action}`, 2);
 }
 
+// commentOnIssue's body limit.
+const COMMENT_MAX = 10_000;
 const ISSUE_STATUSES = ["todo", "in_progress", "in_review", "blocked", "done", "wont_do"];
 // A blocked reason names who or what clears it: "cleared by", "unblocks", "waiting on", "until".
 const CLEARED_BY = /\b(clear(s|ed)?|unblock(s|ed)?|wait(s|ing)? (on|for)|until)\b/i;
@@ -386,9 +423,19 @@ export async function main(argv = process.argv.slice(2)) {
   }
   if (command === "login") return login(f, json);
   if (command === "logout") {
+    refuseFromLane("logout");
     const c = await readConfig(false);
     if (c) {
-      try { await revokeOAuth(c); } finally { await deleteCredentials(); }
+      try {
+        await revokeOAuth(c);
+      } catch (error) {
+        // A keychain that cannot be read still holds the credential: keep the
+        // config, so logout can revoke it once the keychain is unlocked.
+        if (error?.code === "KEYCHAIN_UNAVAILABLE") throw error;
+        await deleteCredentials();
+        throw error;
+      }
+      await deleteCredentials();
     } else await deleteCredentials();
     return emit({ loggedOut: true }, json, "Logged out.");
   }
@@ -428,7 +475,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) {
@@ -480,13 +527,15 @@ export async function main(argv = process.argv.slice(2)) {
   if (command === "agent") {
     if (["lane-limit", "grant", "revoke"].includes(action))
       return emitCommand(await agentWorkflowCommand(action, rest, f));
-    const c = await readConfig();
+    // A fresh, empty config path takes the machine's sign-in (Dev issue 110).
+    const name = action === "register" ? requireFlag(f, "name") : undefined;
+    const c = action === "register" ? (await readConfig(false)) ?? (await adoptMachineSignIn()) : await readConfig();
     if (action === "register") {
       // POST /api/v1/agents is the registration route the edge exposes; Dev
       // binds the agent to the OAuth person, app and installation itself.
       const result = await devRequest("POST", "/api/v1/agents", {
         sessionId: f.session ?? crypto.randomUUID(),
-        name: requireFlag(f, "name"),
+        name,
       });
       await writeConfig({ ...c, agentId: result.data.id });
       // Dev ignores a self-claimed service: staff bind agents to services
@@ -646,7 +695,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 +735,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.17";
+export const VERSION = "0.6.21";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -33,7 +33,13 @@ export const isOAuthConfig = (config) =>
 export async function readConfig(required = true) {
   let config;
   try {
-    config = JSON.parse(await readFile(configPath(), "utf8"));
+    const text = await readFile(configPath(), "utf8");
+    // An empty file is a config path made ready for a new agent, not a login.
+    if (!text.trim()) {
+      if (!required) return null;
+      throw new Error("empty");
+    }
+    config = JSON.parse(text);
   } catch (error) {
     if (!required && error?.code === "ENOENT") return null;
     throw new CliError("NOT_LOGGED_IN", "Run `nodii-dev login` first.", 2);
@@ -113,7 +119,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 +130,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 +149,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 +165,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 +184,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 +199,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", "force"]);
 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 };
 }
 

package/dist/doctor.js

@@ -48,7 +48,7 @@ export function grantReason(grant = {}) {
   return "unspecified";
 }
 
-async function readConfigFile(path) {
+export async function readConfigFile(path) {
   let raw;
   try {
     raw = await readFile(path, "utf8");
@@ -56,6 +56,8 @@ async function readConfigFile(path) {
     if (error?.code === "ENOENT") return null;
     return { unreadable: error?.code ?? String(error) };
   }
+  // An empty file is a path made ready for a new agent (`agent register` adopts the machine's sign-in).
+  if (!raw.trim()) return null;
   try { return JSON.parse(raw); } catch { return {}; }
 }
 
@@ -106,8 +108,9 @@ export async function doctorCommand(deps = {}) {
     try {
       await (deps.loadRefreshToken ?? loadRefreshToken)(config.clientId);
       stored = true;
-    } catch {
-      checks.push(missing("signed_in", "no stored sign-in credential for this app in the keychain", loginFix));
+    } catch (error) {
+      if (error?.code === "KEYCHAIN_UNAVAILABLE") checks.push(missing("signed_in", "the keychain could not be read (locked or access denied)", "unlock the login keychain, then rerun"));
+      else checks.push(missing("signed_in", "no stored sign-in credential for this app in the keychain", loginFix));
     }
     if (stored) {
       try {