@nodii/dev 0.6.3 → 0.6.4

package/README.md

@@ -45,7 +45,9 @@ asks you to run `nodii-dev login`.
 `nodii-dev` is only the Dev control CLI. The local-stack CLI is `./nodii-stack`,
 run from the `nodii-local-stack` checkout (renamed per operator ruling G3-6,
 with no alias under the old name). Typing one of its verbs here, such as
-`nodii-dev doctor`, fails and names the `./nodii-stack` command instead.
+`nodii-dev provenance`, fails and names the `./nodii-stack` command instead.
+`nodii-dev doctor` is this CLI's own preflight (below); `./nodii-stack doctor`
+checks the local stack.
 
 Every command accepts `--json`; without it, output is formatted for humans.
 Dev failures print Dev's error code to stderr and exit non-zero.
@@ -57,6 +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 api list [--tag TAG] [--json]
 nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
@@ -252,10 +255,32 @@ source documents moved, and each file created, updated or removed. It
 removes only files, blocks and hook entries it wrote, and it refuses (writing
 nothing) when one of its files was edited by hand.
 
+## Preflight: `doctor`
+
+Run `nodii-dev doctor` from the lane's worktree, with the lane agent's config,
+before `lane start`. It only reads, and prints one line per check: `OK`,
+`MISSING` (with the command that fixes it) or `CANNOT CHECK` (with why). It
+exits 0 only when every check is `OK`. `--json` returns the same checks as
+`{ data: { ok, configPath, configSource, checks: [{ key, status, message, fix?, ... }] } }`.
+
+| Check | What it reads |
+| --- | --- |
+| `config` | Which config file is in use: `NODII_DEV_CONFIG_PATH` or the default `~/.config/nodii-dev/config.json`, and whether it is an OAuth login. |
+| `signed_in` | The refresh credential in the keychain, and an access token from it. When nodii-auth rejects the sign-in, it says whether the grant **expired**, was **revoked** or was **replaced**, if the server named which (otherwise it says the server did not). A rejected credential is reported, never cleared. |
+| `agent` | The agent on this config (`agentId`), as Dev reads it back. |
+| `permissions` | The sign-in's permissions against what lane commands need (`devops.issues`, `lanes`, `agents` `.read`/`.write`, `devops.machines.manage`, `devops.decisions.read`/`.write`/`.lock` for Figma locks, `devops.rulebook.read`). Each missing key is listed, with whether the installation has not consented to it or no role grants it. |
+| `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. |
+
+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
+operation's permission (requested in Dev).
+
 ## Build lanes and repository setup
 
-`lane start` creates and starts a lane. It infers the repository, branch and
-worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
+`lane start` creates and starts a lane. It infers the repository (by short
+name, as Dev compares it), branch and worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
 required by Dev. Lane keys are passed directly to every lane and Built
 acknowledgement route. `next` reads the lane's generated
 API steps and prints the exact next `lane step` command. Server refusals,

package/dist/cli.js

@@ -25,6 +25,7 @@ import {
 import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
 import { harnessCommand } from "./harness.js";
+import { doctorCommand } from "./doctor.js";
 import { docsCommand, rulebookCommand } from "./upload.js";
 import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import {
@@ -54,6 +55,7 @@ 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
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
   inbox list|show
@@ -101,7 +103,8 @@ Run a command with --help or see the package README for all flags.`;
 
 // Verbs of the local-stack CLI, which shared this name until it became
 // ./nodii-stack (operator G3-6, no alias). Named here only to point there.
-const STACK_VERBS = new Set(["up", "down", "doctor", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
+// `doctor` is not one of them: `nodii-dev doctor` is this CLI's own preflight.
+const STACK_VERBS = new Set(["up", "down", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
 
 async function stdinText() {
   let value = "";
@@ -272,6 +275,13 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const emitCommand = async (result) => emit(result.payload, json, result.human);
   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();
+    emit(result.payload, json, result.human);
+    if (result.exitCode) process.exitCode = result.exitCode;
+    return;
+  }
   if (command === "harness" && ["install", "update"].includes(action)) {
     // `--include-drafts` is a switch: `--include-drafts false` would leave `false` here and turn drafts on.
     if (rest.length) throw new CliError("USAGE", `harness ${action} takes no arguments, got: ${rest.join(" ")}. Write a flag value as --include-drafts=false.`, 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.3";
+export const VERSION = "0.6.4";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/doctor.js

@@ -0,0 +1,235 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { devRequest, encode, isOAuthConfig, query, setAuthProvider } from "./core.js";
+import { OAuthAuthProvider, decodeClaims, loadRefreshToken } from "./oauth.js";
+import { inferGitContext, repoName } from "./lanes.js";
+
+/**
+ * What a lane's commands need, in Dev's route policy (staffRuleFor in Dev's
+ * src/lib/auth/staff-policy.ts): an area's reads need `.read` and its writes
+ * `.write`; every machine route needs `machines.manage`; Figma file locks live
+ * in the decisions area, and releasing one needs `decisions.lock`. Dev's
+ * OpenAPI does not name the permission per operation, so this table is kept
+ * by hand.
+ */
+export const LANE_PERMISSIONS = [
+  { key: "devops.issues.read", for: "issues list|show" },
+  { key: "devops.issues.write", for: "issues create|update|claim|release, api transitionIssue" },
+  { key: "devops.lanes.read", for: "lane show|list, next" },
+  { key: "devops.lanes.write", for: "lane start|step|evidence|heartbeat|review|land|verify" },
+  { key: "devops.agents.read", for: "whoami, reading this agent" },
+  { key: "devops.agents.write", for: "agent register|heartbeat" },
+  { key: "devops.machines.manage", for: "machine show (this agent's machine and coordinator)" },
+  { key: "devops.decisions.read", for: "figma check" },
+  { key: "devops.decisions.write", for: "figma lock|log-write|submit|apply|published|abandon" },
+  { key: "devops.decisions.lock", for: "figma release" },
+  { key: "devops.rulebook.read", for: "rulebook show" },
+];
+
+// Lane statuses that hold one of the agent's lane slots (Dev's ACTIVE set).
+const ACTIVE = new Set(["queued", "building", "built", "review", "on_main"]);
+const LABEL = { ok: "OK", missing: "MISSING", cannot_check: "CANNOT CHECK" };
+
+const ok = (key, message, extra = {}) => ({ key, status: "ok", message, ...extra });
+const missing = (key, message, fix, extra = {}) => ({ key, status: "missing", message, ...(fix ? { fix } : {}), ...extra });
+const cannot = (key, message, extra = {}) => ({ key, status: "cannot_check", message: `cannot check: ${message}`, ...extra });
+const devReason = (error) => [error.code, error.details?.reason].filter(Boolean).join(" ") + (error.message ? `: ${error.message}` : "");
+
+/** expired, revoked, replaced, or unspecified — only what nodii-auth said. */
+export function grantReason(grant = {}) {
+  if (grant.error === "expired_token") return "expired";
+  if (grant.error === "token_revoked") return "revoked";
+  const said = String(grant.description ?? "").toLowerCase();
+  if (/revok/.test(said)) return "revoked";
+  if (/expir/.test(said)) return "expired";
+  if (/reuse|replay|rotat|replac|supersed/.test(said)) return "replaced";
+  return "unspecified";
+}
+
+async function readConfigFile(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    return { unreadable: error?.code ?? String(error) };
+  }
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+/** A provider that never clears a rejected credential: doctor only looks. */
+export function lookingProvider(options = {}) {
+  const provider = new OAuthAuthProvider({ ...options, deleteToken: async () => {}, deleteAccess: async () => {} });
+  setAuthProvider(provider);
+  return provider;
+}
+
+async function allLanes(request, agentId) {
+  const lanes = [];
+  let cursor;
+  do {
+    const page = await request("GET", `/api/v1/lanes${query({ agent: agentId, cursor, limit: 200 })}`);
+    lanes.push(...(page.data ?? []));
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  return lanes;
+}
+
+/**
+ * `nodii-dev doctor`: read-only preflight of everything a lane needs, so a
+ * missing permission, machine or grant shows before the lane starts.
+ */
+export async function doctorCommand(deps = {}) {
+  const env = deps.env ?? process.env;
+  const path = env.NODII_DEV_CONFIG_PATH ?? (deps.defaultConfigPath ?? (() => join(homedir(), ".config/nodii-dev/config.json")))();
+  const configSource = env.NODII_DEV_CONFIG_PATH ? "NODII_DEV_CONFIG_PATH" : "default";
+  const request = deps.request ?? devRequest;
+  const prefix = env.NODII_DEV_CONFIG_PATH ? `NODII_DEV_CONFIG_PATH=${env.NODII_DEV_CONFIG_PATH} ` : "";
+  const loginFix = `${prefix}nodii-dev login`;
+  const checks = [];
+
+  // 1. Config, and which file.
+  const config = await (deps.readConfigFile ?? readConfigFile)(path);
+  const configOk = isOAuthConfig(config);
+  if (config === null) checks.push(missing("config", `no config at ${path} (${configSource})`, loginFix));
+  else if (config.unreadable) checks.push(missing("config", `cannot read ${path} (${config.unreadable})`, `check the file's permissions, or ${loginFix}`));
+  else if (!configOk) checks.push(missing("config", `${path} is not an OAuth login (written before 0.5.0, or not valid JSON)`, loginFix));
+  else checks.push(ok("config", `${path} (${configSource})`));
+
+  // 2. Signed in: a stored credential, and an access token from it.
+  let claims = null;
+  if (!configOk) checks.push(missing("signed_in", "not signed in", loginFix));
+  else {
+    let stored = false;
+    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));
+    }
+    if (stored) {
+      try {
+        const token = await (deps.accessToken ?? (() => lookingProvider().accessToken()))();
+        claims = (deps.decodeClaims ?? decodeClaims)(token);
+        const minutes = Number.isFinite(claims.exp) ? Math.max(0, Math.floor((claims.exp * 1000 - Date.now()) / 60_000)) : null;
+        checks.push(ok("signed_in", `as person ${claims.sub ?? config.person} through installation ${config.installationId ?? "unknown"}${minutes === null ? "" : `; access token valid ${minutes} min`}`,
+          { person: claims.sub ?? config.person, installationId: config.installationId ?? null }));
+      } catch (error) {
+        if (error?.code === "OAUTH_LOGIN_REQUIRED" && error.details?.grant) {
+          const reason = grantReason(error.details.grant);
+          const why = reason === "unspecified"
+            ? `nodii-auth rejected the sign-in (${error.details.grant.error ?? "invalid_grant"}) and did not say whether it expired, was revoked or was replaced`
+            : `nodii-auth rejected the sign-in: ${reason}`;
+          checks.push(missing("signed_in", why, loginFix, { reason }));
+        } else if (error?.code === "OAUTH_LOGIN_REQUIRED") checks.push(missing("signed_in", "no stored sign-in credential for this app in the keychain", loginFix));
+        else if (error?.code === "OAUTH_REFRESH_FAILED") checks.push(missing("signed_in", error.message, loginFix));
+        else checks.push(cannot("signed_in", `${error?.code ?? "ERROR"}: ${error?.message ?? error}`));
+      }
+    }
+  }
+  const signedIn = claims !== null;
+
+  // 3. Agent registered on this config and recognised by Dev.
+  let agent = null;
+  const registerFix = `${prefix}nodii-dev agent register --name NAME`;
+  if (!signedIn) checks.push(cannot("agent", "needs a sign-in"));
+  else if (!config.agentId) checks.push(missing("agent", `no agent registered on ${path}`, registerFix));
+  else {
+    try {
+      agent = (await request("GET", `/api/v1/agents/${encode(config.agentId)}`)).data;
+      if (agent.status === "disconnected") {
+        checks.push(missing("agent", `agent ${agent.name} (${agent.id}) is disconnected`, registerFix));
+        agent = null;
+      } else checks.push(ok("agent", `${agent.name} (${agent.id}), ${agent.status}, role ${agent.role}`, { agentId: agent.id, name: agent.name }));
+    } catch (error) {
+      checks.push(missing("agent", `Dev does not recognise agent ${config.agentId} (${devReason(error)})`, registerFix));
+    }
+  }
+
+  // 4. Permissions: the installation's consent and the person's roles, as the token carries them.
+  if (!signedIn) checks.push(cannot("permissions", "needs a sign-in"));
+  else if (!Array.isArray(claims.permissions)) checks.push(cannot("permissions", "the access token carries no permissions claim"));
+  else {
+    const granted = new Set(claims.permissions);
+    const consented = new Set(Array.isArray(claims.grant_scope) ? claims.grant_scope : claims.permissions);
+    const gaps = LANE_PERMISSIONS.filter((x) => !granted.has(x.key)).map((x) => ({ key: x.key, for: x.for, why: consented.has(x.key) ? "no_role" : "not_consented" }));
+    if (!gaps.length) checks.push(ok("permissions", `all ${LANE_PERMISSIONS.length} permissions a lane needs are granted`, { missing: [] }));
+    else {
+      const text = gaps.map((x) => `${x.key} (${x.why === "not_consented" ? "installation has not consented" : "consented, but no role grants it"}; for ${x.for})`).join(", ");
+      const fixes = [
+        ...(gaps.some((x) => x.why === "not_consented") ? [`re-consent the nodii-dev installation, then ${loginFix}`] : []),
+        ...(gaps.some((x) => x.why === "no_role") ? ["ask a Dev admin for a role that grants the missing keys, then sign in again"] : []),
+      ];
+      checks.push(missing("permissions", `missing ${text}`, fixes.join("; "), { missing: gaps }));
+    }
+  }
+
+  // 5. Machine and its coordinator.
+  if (!agent) checks.push(cannot("machine", "needs a registered agent"));
+  else if (!agent.machineId)
+    checks.push(missing("machine", "this agent is not assigned to a machine; lane start fails with MACHINE_REQUIRED",
+      `ask the machine's coordinator: nodii-dev machine assign <machine> ${agent.id} --home-repo <repo>`));
+  else {
+    try {
+      const machine = (await request("GET", `/api/v1/machines/${encode(agent.machineId)}`)).data;
+      const coordinator = (machine.agents ?? []).find((x) => x.id === machine.coordinatorAgentId);
+      checks.push(ok("machine", `${machine.name} (${machine.id}); coordinator ${machine.coordinatorAgentId ? `${coordinator?.name ?? "agent"} (${machine.coordinatorAgentId})` : "none set"}`,
+        { machineId: machine.id, machineName: machine.name, coordinatorAgentId: machine.coordinatorAgentId ?? null, coordinatorName: coordinator?.name ?? null }));
+    } catch (error) {
+      checks.push(cannot("machine", `assigned to ${agent.machineId}, but getMachine failed (${devReason(error)})`, { machineId: agent.machineId }));
+    }
+  }
+
+  // 6. Home repo or a grant for the repository in this directory, by short name.
+  let context = null;
+  if (!agent) checks.push(cannot("repo", "needs a registered agent"));
+  else {
+    try {
+      context = await (deps.gitContext ?? inferGitContext)();
+    } catch (error) {
+      checks.push(cannot("repo", `${error?.code === "GIT_REQUIRED" ? "not in a git worktree on a branch" : (error?.message ?? error)}; run doctor from the lane's worktree`));
+    }
+    if (context) {
+      const repo = repoName(context.repo);
+      if (agent.homeRepo && repoName(agent.homeRepo) === repo) checks.push(ok("repo", `${repo} is this agent's home repository`, { repo, homeRepo: agent.homeRepo }));
+      else {
+        try {
+          const grants = (await request("GET", `/api/v1/agents/${encode(agent.id)}/repo-grants`)).data ?? [];
+          if (grants.some((x) => !x.revokedAt && repoName(x.repo) === repo)) checks.push(ok("repo", `${repo} is granted to this agent (home ${agent.homeRepo ?? "none"})`, { repo, homeRepo: agent.homeRepo ?? null }));
+          else checks.push(missing("repo", `${repo} is neither the home repository (${agent.homeRepo ?? "none"}) nor granted; lane start fails with REPO_NOT_GRANTED`,
+            `nodii-dev agent grant ${agent.id} ${repo}`, { repo, homeRepo: agent.homeRepo ?? null }));
+        } catch (error) {
+          checks.push(cannot("repo", `${repo} is not the home repository (${agent.homeRepo ?? "none"}), and listAgentRepoGrants failed (${devReason(error)})`, { repo, homeRepo: agent.homeRepo ?? null }));
+        }
+      }
+    }
+  }
+
+  // 7. Lane limit: a free slot, or a lane on this branch already holding one.
+  if (!agent) checks.push(cannot("lane_limit", "needs a registered agent"));
+  else {
+    try {
+      const active = (await allLanes(request, agent.id)).filter((x) => ACTIVE.has(x.status));
+      const limit = agent.laneLimit ?? 1;
+      const here = (x) => x.branch === context.branch && (!Array.isArray(x.repos) || x.repos.map(repoName).includes(repoName(context.repo)));
+      const mine = context && active.find(here);
+      const keys = active.map((x) => x.key).join(", ");
+      const extra = { active: active.length, limit, lanes: active.map((x) => x.key) };
+      if (active.length < limit) checks.push(ok("lane_limit", `${active.length} of ${limit} lane slots in use${keys ? ` (${keys})` : ""}`, extra));
+      else if (mine) checks.push(ok("lane_limit", `${active.length} of ${limit} lane slots in use; ${mine.key} on this branch holds one`, extra));
+      else checks.push(missing("lane_limit", `${active.length} of ${limit} lane slots in use (${keys}); lane start fails with LANE_LIMIT_REACHED`,
+        `land or stop a lane, or ask the coordinator: nodii-dev agent lane-limit ${agent.id} <n>`, extra));
+    } catch (error) {
+      checks.push(cannot("lane_limit", `listLanes failed (${devReason(error)})`));
+    }
+  }
+
+  const ready = checks.every((x) => x.status === "ok");
+  const width = Math.max(...checks.map((x) => x.key.length));
+  const human = (p) => [
+    ...p.data.checks.map((x) => `${LABEL[x.status].padEnd(12)} ${x.key.padEnd(width)}  ${x.message}${x.fix ? ` — fix: ${x.fix}` : ""}`),
+    p.data.ok ? "Ready for a lane." : `Not ready: ${p.data.checks.filter((x) => x.status !== "ok").map((x) => x.key).join(", ")}.`,
+  ].join("\n");
+  return { payload: { data: { ok: ready, configPath: path, configSource, checks } }, human, exitCode: ready ? 0 : 1 };
+}

package/dist/lanes.js

@@ -18,15 +18,21 @@ async function git(...args) {
   }
 }
 
+/**
+ * A repository as Dev names it: the short name. Dev compares a lane's repos
+ * exactly against the agent's home repo and grants, which are short names, so
+ * `owner/name` from the remote was refused as REPO_NOT_GRANTED.
+ */
+export const repoName = (remoteOrPath) => String(remoteOrPath).replace(/\/+$/, "").replace(/\.git$/, "").split(/[/:]/).filter(Boolean).at(-1);
+
 export async function inferGitContext() {
   const worktree = await git("rev-parse", "--show-toplevel");
   const branch = await git("branch", "--show-current");
   let repo;
   try {
-    const remote = await git("remote", "get-url", "origin");
-    repo = remote.replace(/\.git$/, "").replace(/^git@[^:]+:/, "").replace(/^https?:\/\/[^/]+\//, "");
+    repo = repoName(await git("remote", "get-url", "origin"));
   } catch {
-    repo = worktree.split("/").filter(Boolean).at(-1);
+    repo = repoName(worktree);
   }
   return { repo, branch: need(branch, "Detached HEAD: pass --branch."), worktree };
 }

package/dist/oauth.js

@@ -440,7 +440,10 @@ export class OAuthAuthProvider {
         await this.deleteToken(config.clientId);
         await this.deleteAccess(config.clientId);
       }
-      throw new CliError("OAUTH_LOGIN_REQUIRED", `nodii-auth no longer accepts this sign-in (invalid_grant: expired, revoked or replayed)${cleared ? " and the saved credential was cleared" : ""}; run \`nodii-dev login\` again.`, 2);
+      // What the server said, so `doctor` can name expired, revoked or replaced.
+      const said = (key) => (typeof result.body[key] === "string" ? result.body[key] : undefined);
+      const grant = Object.fromEntries([["error", said("error")], ["description", said("error_description")]].filter(([, v]) => v !== undefined));
+      throw new CliError("OAUTH_LOGIN_REQUIRED", `nodii-auth no longer accepts this sign-in (invalid_grant: expired, revoked or replayed)${cleared ? " and the saved credential was cleared" : ""}; run \`nodii-dev login\` again.`, 2, { grant });
     }
     if (kind === "retry")
       throw new CliError("OAUTH_REFRESH_UNAVAILABLE", `Could not refresh the sign-in (${describe(result)}) after ${attempts} attempt${attempts === 1 ? "" : "s"}; the saved credential was kept. Retry the command shortly.`, 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {