run402 4.93.2 → 4.95.0

package/lib/login.mjs

@@ -0,0 +1,207 @@
+/**
+ * `run402 login [--device] [--no-open]` — sign a person in. See sign-in.mjs.
+ */
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, positionalArgs } from "./argparse.mjs";
+import {
+  saveControlPlaneSession,
+  controlPlaneSessionFromTokenResponse,
+  clearRetiredSessionCaches,
+} from "../core-dist/control-plane-session.js";
+import { clearApprovals } from "../core-dist/write-approvals.js";
+import { openBrowser, pkce, sessionView, startLoopbackServer } from "./sign-in.mjs";
+
+const HELP = `run402 login — sign in as a person (your sign-in session)
+
+Usage:
+  run402 login [--no-open]            browser passkey sign-in (full session)
+  run402 login --device [--no-open]   device code for a terminal with no browser (read-only)
+
+A person signs in; an agent's wallet is a separate identity ('run402 status').
+'run402 login' opens the browser, where you sign in with your passkey, and
+catches the redirect on a 127.0.0.1 port. The session it caches can write,
+and step-up works on it. 'run402 login --device' prints a code you approve in
+the console from any device; that session can only read (every write answers
+SESSION_READ_ONLY).
+
+Provisioning, deploying, and writing secrets without a wallet also need a
+write approval: 'run402 approve --action <capability> (--org <org_id> |
+--project <project_id>)'. From a terminal the CLI opens it for you.
+
+Options:
+  --device   Use the device-code flow (RFC 8628) instead of the browser redirect.
+  --no-open  Do not open the browser; print the URL only.
+
+Notes:
+  - The session is cached at the base config dir, shared across named wallets.
+  - JSON to stdout; the URL and code to open go to stderr.
+  - 'run402 whoami' shows the session's grade; 'run402 logout' ends it.
+`;
+
+const CLIENT_NAME = "run402 CLI";
+
+/** Cache a freshly minted session; a new session invalidates every approval bound to the old one. */
+function cacheSession(tokenResponse) {
+  const cached = controlPlaneSessionFromTokenResponse(tokenResponse);
+  clearApprovals();
+  clearRetiredSessionCaches();
+  saveControlPlaneSession(cached);
+  return cached;
+}
+
+/** Best-effort: surface org memberships (auto-redeemed invites land here). Never fails the login. */
+async function attachMemberships(view, token) {
+  try {
+    const who = await getSdk().session.whoami({ token });
+    const memberships = Array.isArray(who?.memberships) ? who.memberships : [];
+    view.memberships = memberships;
+    if (memberships.length) {
+      process.stderr.write(
+        `Member of ${memberships.length} org(s):\n` +
+          memberships.map((m) => `  - ${m.display_name || m.org_id || "unknown"} (${m.role}, ${m.status})`).join("\n") +
+          "\n",
+      );
+    }
+  } catch {
+    /* best-effort — the session is valid regardless of the whoami result */
+  }
+}
+
+async function loopbackLogin({ noOpen }) {
+  const sdk = getSdk();
+  const { codeVerifier, codeChallenge, state, nonce } = pkce();
+  const { ready, codePromise, close } = startLoopbackServer({ expectedState: state, timeoutMs: 300_000 });
+
+  let port;
+  try {
+    port = await ready;
+  } catch (err) {
+    close();
+    return fail({ code: "LOOPBACK_FAILED", message: `Could not start the loopback server: ${err.message}` });
+  }
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  const authorizeUrl = sdk.session.buildCliAuthorizeUrl({ redirectUri, codeChallenge, state, nonce });
+
+  process.stderr.write(`\nTo sign in, open:\n  ${authorizeUrl}\n\n`);
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(authorizeUrl);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  let code;
+  try {
+    code = await codePromise;
+  } catch (err) {
+    close();
+    return fail({ code: "LOGIN_FAILED", message: err.message, hint: "Run 'run402 login' to try again." });
+  }
+
+  let session;
+  try {
+    session = await sdk.session.exchangeCliToken({ code, codeVerifier, redirectUri, state });
+  } catch (err) {
+    close();
+    return reportSdkError(err);
+  }
+  // The loopback server has done its job. Tear it down (destroying any
+  // keep-alive socket) so Node's event loop drains and the CLI exits instead
+  // of hanging until Ctrl+C.
+  close();
+
+  const cached = cacheSession(session);
+  process.stderr.write(`\nSigned in (grade: ${cached.grade}).\n`);
+  const view = sessionView(cached);
+  await attachMemberships(view, session.control_plane_session_token);
+  console.log(JSON.stringify(view));
+}
+
+async function deviceLogin({ noOpen }) {
+  const sdk = getSdk();
+  let start;
+  try {
+    start = await sdk.session.deviceStart();
+  } catch (err) {
+    return reportSdkError(err);
+  }
+
+  // Human-in-the-loop prompt → stderr, so stdout stays clean for the final JSON.
+  const target = start.verification_uri_complete || start.verification_uri;
+  process.stderr.write(
+    `\nTo authorize the ${CLIENT_NAME}, open:\n  ${start.verification_uri}\n` +
+      `and enter the code:  ${start.user_code}\n\n`,
+  );
+  if (!noOpen && process.stderr.isTTY) {
+    openBrowser(target);
+    process.stderr.write("(opening your browser…)\n\n");
+  }
+  process.stderr.write("Waiting for approval…\n");
+
+  // Poll loop — honor the server interval, back off on slow_down, and stop at
+  // the device-code deadline. if/else (not switch) so the sync scanner doesn't
+  // mistake the poll states for CLI subcommands.
+  let intervalMs = Math.max(1, Number(start.interval) || 5) * 1000;
+  const deadline = Date.now() + Math.max(1, Number(start.expires_in) || 600) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    let result;
+    try {
+      result = await sdk.session.devicePoll(start.device_code);
+    } catch (err) {
+      return reportSdkError(err);
+    }
+    if (result.kind === "approved") {
+      const cached = cacheSession(result.session);
+      process.stderr.write(`\nSigned in (grade: ${cached.grade}, read-only).\n`);
+      const view = sessionView(cached);
+      await attachMemberships(view, result.session.control_plane_session_token);
+      console.log(JSON.stringify(view));
+      return;
+    }
+    if (result.kind === "authorization_pending") continue;
+    if (result.kind === "slow_down") {
+      intervalMs += 5000;
+      continue;
+    }
+    if (result.kind === "access_denied") {
+      fail({
+        code: "LOGIN_DENIED",
+        message: "Authorization was denied in the browser.",
+        hint: "Run 'run402 login --device' to try again.",
+      });
+    }
+    if (result.kind === "expired_token") {
+      fail({
+        code: "LOGIN_EXPIRED",
+        message: "The device code expired before approval.",
+        hint: "Run 'run402 login --device' to get a fresh code.",
+      });
+    }
+    fail({ code: "LOGIN_FAILED", message: `Unexpected device poll result: ${result.kind}` });
+  }
+  fail({
+    code: "LOGIN_TIMEOUT",
+    message: "Timed out waiting for browser approval.",
+    hint: "Run 'run402 login --device' to try again.",
+  });
+}
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(args, ["--help", "-h", "--no-open", "--device"]);
+  const extra = positionalArgs(args, []);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for login: ${extra[0]}`, hint: "Use `run402 login [--device] [--no-open]`." });
+  }
+  const noOpen = args.includes("--no-open");
+  if (args.includes("--device")) return deviceLogin({ noOpen });
+  return loopbackLogin({ noOpen });
+}

package/lib/logout.mjs

@@ -0,0 +1,53 @@
+/**
+ * `run402 logout` — end the sign-in session server-side and clear the local
+ * session and write-approval caches. See sign-in.mjs.
+ */
+
+import { fail } from "./sdk-errors.mjs";
+import { getSdk } from "./sdk.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, positionalArgs } from "./argparse.mjs";
+import {
+  loadLiveControlPlaneSession,
+  clearControlPlaneSession,
+  clearRetiredSessionCaches,
+} from "../core-dist/control-plane-session.js";
+import { clearApprovals } from "../core-dist/write-approvals.js";
+
+const HELP = `run402 logout — end your sign-in session
+
+Usage:
+  run402 logout
+
+Revokes the cached sign-in session on the gateway, then deletes it and every
+cached write approval from this machine. The local cache is cleared even when
+the revoke cannot reach the gateway. A wallet is not affected.
+`;
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  assertKnownFlags(args, ["--help", "-h"]);
+  const extra = positionalArgs(args, []);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for logout: ${extra[0]}`, hint: "Use `run402 logout`." });
+  }
+  const session = loadLiveControlPlaneSession();
+  let revoked = false;
+  if (session) {
+    try {
+      await getSdk().session.revoke({ token: session.control_plane_session_token });
+      revoked = true;
+    } catch {
+      // Best-effort: a failed server revoke (expired token, offline) must not
+      // block clearing the local cache. The local token is removed regardless.
+      revoked = false;
+    }
+  }
+  clearControlPlaneSession();
+  clearApprovals();
+  clearRetiredSessionCaches();
+  console.log(JSON.stringify({ revoked, cleared: true }));
+}

package/lib/logs.mjs

@@ -33,11 +33,11 @@ import {
 const HELP = `run402 logs — Fetch function logs by request id
 
 Usage:
-  run402 logs --request-id <id> [<function> | --function <name>] [--project <id>] [options]
-  run402 logs --function <name> [--project <id>] [options]
+  run402 logs --request-id <request_id> [<function> | --function <name>] [--project <project_id>] [options]
+  run402 logs --function <name> [--project <project_id>] [options]
 
 Required (one of):
-  --request-id <id>       A req_... id (the x-run402-request-id response header),
+  --request-id <request_id>       A req_... id (the x-run402-request-id response header),
                           or a fnrun_... / fnatt_... durable-run id. Without
                           --function, every function in the project is scanned.
   --function <name>       Limit to one function. Alone (no --request-id) this
@@ -45,7 +45,7 @@ Required (one of):
                           <function> means the same thing.
 
 Optional:
-  --project <id>          Project id (default: \$RUN402_PROJECT_ID, else the active project)
+  --project <project_id>          Project id (default: \$RUN402_PROJECT_ID, else the active project)
   --tail <n>              Max entries per function BEFORE the origin filter (default 100, max 1000)
   --since <ts>            ISO timestamp or epoch ms; only entries at or after this
   --app                   Only the function's own output (default). Lambda runtime
@@ -77,7 +77,7 @@ Tip: the request id appears in:
   - The 'x-run402-request-id' response header on every function response
   - The 'requestId' field of any R402_SSR_RUNTIME_ERROR envelope
   - The 'request_id' field in deploy / cache invalidate result envelopes
-  - The 'samples' of 'run402 errors' (each sample names a runnable logs command)
+  - The 'samples' of 'run402 errors list' (each sample names a runnable logs command)
 `;
 
 const VALUE_FLAGS = ["--request-id", "--function", "--project", "--tail", "--since"];
@@ -103,7 +103,7 @@ export async function run(sub, args = []) {
     fail({
       code: "BAD_USAGE",
       message: `Unexpected argument: ${positionals[1]}`,
-      hint: "run402 logs [<function>] --request-id <id> [--project <id>]",
+      hint: "run402 logs [<function>] --request-id <request_id> [--project <project_id>]",
       details: { argument: positionals[1] },
     });
   }
@@ -119,7 +119,7 @@ export async function run(sub, args = []) {
   if (!requestId && !fnName) {
     fail({
       code: "BAD_USAGE",
-      message: "Missing --request-id <id> (or --function <name> for a plain tail).",
+      message: "Missing --request-id <request_id> (or --function <name> for a plain tail).",
       hint: "Pass the request id from the 'x-run402-request-id' response header.",
     });
   }
@@ -130,7 +130,7 @@ export async function run(sub, args = []) {
     fail({
       code: "BAD_USAGE",
       message: "Missing project id.",
-      hint: "Pass --project <id>, set RUN402_PROJECT_ID, or 'run402 projects use <id>'.",
+      hint: "Pass --project <project_id>, set RUN402_PROJECT_ID, or 'run402 projects use <project_id>'.",
     });
   }
 

package/lib/messages.mjs

@@ -42,15 +42,15 @@ const ROOM_FLAGS = ["--project", "--org", "--room"];
 const HELP = `run402 messages — room-visible messages between agents
 
 Usage:
-  run402 messages send <body> [--to <names>] [--ack] [--thread <id>]
-  run402 messages list [--unread] [--cursor <mcr_...>] [--thread <id>]
-  run402 messages wait [--addressed-to me] [--thread <id>] [--timeout <s>] [--cursor <mcr_...>]
+  run402 messages send <body> [--to <names>] [--ack] [--thread <thread>]
+  run402 messages list [--unread] [--cursor <mcr_...>] [--thread <thread>]
+  run402 messages wait [--addressed-to me] [--thread <thread>] [--timeout <s>] [--cursor <mcr_...>]
   run402 messages get <message_id>
   run402 messages ack <message_id>
 
 Addressing (all subcommands):
-  --project <id>    That project's DEFAULT room (the room key IS the project id)
-  --org <id> --room <key>   A named org room
+  --project <project_id>    That project's DEFAULT room (the room key IS the project id)
+  --org <org_id> --room <key>   A named org room
   (omit both)       Resolved from RUN402_ROOM, a .run402.json binding, or the
                     wallet profile's selected org
 

package/lib/next-actions.mjs

@@ -35,7 +35,7 @@ export function retryAction(command, why) {
 export function initializeWalletAction() {
   return nextAction("initialize_wallet", {
     command: "run402 init",
-    why: "Create and fund an agent allowance, then retry.",
+    why: "Create and fund a local wallet, then retry.",
   });
 }
 
@@ -56,54 +56,54 @@ export function selectProjectAction() {
 export function setTierAction(tier = "prototype") {
   return nextAction("renew_tier", {
     command: `run402 tier set ${tier}`,
-    why: "Subscribe the account to a tier (free on testnet), then retry.",
+    why: "Set a tier for the organization (prototype is free), then retry.",
   });
 }
 
 export function deployAction() {
   return nextAction("deploy", {
-    command: "run402 deploy apply --manifest app.json",
-    why: "Apply your release manifest to deploy.",
+    command: "run402 deploy --manifest app.json",
+    why: "Deploy your release manifest.",
   });
 }
 
 /**
  * The cold-start deploy when the account holds no tier yet: `run402 up -y`
- * subscribes the prototype tier itself as part of the first deploy, so `init`
+ * sets the prototype tier itself as part of the first deploy, so `init`
  * hands the agent ONE command instead of `tier set` + a separate deploy.
  * `tier set prototype` stays named as the standalone alternative.
  */
 export function upDeployAction() {
   return nextAction("deploy", {
     command: "run402 up -y",
-    why: "Deploy with run402 up -y — it subscribes the prototype tier (free on testnet) as part of the first deploy. Or subscribe separately: run402 tier set prototype.",
+    why: "Deploy with run402 up -y — it sets the prototype tier (free on testnet) as part of the first deploy. Or set it separately: run402 tier set prototype.",
   });
 }
 
 /**
- * `repos create` (and `gitvault init`) on an org with no claimed slug: the
+ * `repos create` (and `gitvault init`) on an org with no slug set: the
  * response's `address: null` had no pointer to WHY, or to the named-addressing
  * feature at all. Owner-only. Wording deliberately
  * omits a price: the first slug per org is free, and renames/re-claims cost
  * $1 — a gateway change lands the fee separately, so this stays true under
  * both the old and new pricing rule.
  */
-export function claimOrgSlugAction() {
-  return nextAction("claim_org_slug", {
-    command: "run402 org slug <slug>",
-    why: "This organization has no claimed slug yet, so its repos have no run402::<slug>/<name> address. Owner-only.",
+export function setOrgSlugAction() {
+  return nextAction("set_org_slug", {
+    command: "run402 orgs slug <slug>",
+    why: "This organization has no slug set yet, so its repos have no run402::<slug>/<name> address. Owner-only.",
   });
 }
 
 /**
  * The org already has a slug, but this project's address-form repo name was
- * not claimed this time (a collision, or the best-effort claim failed for
- * some other reason) — point at the explicit claim verb instead of leaving
+ * not set this time (a collision, or the best-effort set failed for
+ * some other reason) — point at the explicit set verb instead of leaving
  * `address: null` unexplained.
  */
-export function claimRepoNameAction(projectId) {
-  return nextAction("claim_repo_name", {
+export function setRepoNameAction(projectId) {
+  return nextAction("set_repo_name", {
     command: `run402 repos name <name> --project ${projectId}`,
-    why: "The owning organization has a slug, but this project has no claimed address-form name yet.",
+    why: "The owning organization has a slug, but this project has no address-form name set yet.",
   });
 }

package/lib/org-context.mjs

@@ -11,7 +11,7 @@
  * organization named directly outranks one derived from a project named in that
  * same class:
  *
- *   1. flag          --org <org_id>           else --project <id> -> its org
+ *   1. flag          --org <org_id>           else --project <project_id> -> its org
  *   2. environment   RUN402_ORG, else the org else RUN402_PROJECT_ID -> its org
  *                    half of RUN402_ROOM
  *   3. binding       the `org` key of the nearest .run402(.local).json
@@ -57,7 +57,7 @@ export const ROOM_ENV = "RUN402_ROOM";
 export const PROJECT_ENV = "RUN402_PROJECT_ID";
 
 /** Command groups that must stay usable while selection is ambiguous. */
-const CONFLICT_EXEMPT = new Set(["org", "wallets", "doctor"]);
+const CONFLICT_EXEMPT = new Set(["orgs", "wallets", "doctor"]);
 
 /** `org_id` is a UUID at every API boundary (`uuidParam` on every route). */
 const ORG_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
@@ -78,7 +78,7 @@ function assertOrgIdShape(orgId, origin) {
   fail({
     code: "BAD_ORG_ID",
     message: `Invalid organization id ${JSON.stringify(describeRejectedValue(orgId))} (from ${origin}).`,
-    hint: "An org_id is a UUID. Run 'run402 org list' to see the organizations you belong to.",
+    hint: "An org_id is a UUID. Run 'run402 orgs list' to see the organizations you belong to.",
     details: { org_id: describeRejectedValue(orgId), origin },
     next_actions: [listOrgsAction()],
   });
@@ -118,7 +118,7 @@ async function readGitvaultPinnedOrgId(cwd) {
 
 function listOrgsAction() {
   return nextAction("edit_request", {
-    command: "run402 org list",
+    command: "run402 orgs list",
     why: "List the organizations this wallet belongs to.",
   });
 }
@@ -126,7 +126,7 @@ function listOrgsAction() {
 function orgRequiredActions() {
   return [
     nextAction("edit_request", {
-      command: "run402 org use <org_id>",
+      command: "run402 orgs use <org_id>",
       why: "Select a current organization for this wallet profile.",
     }),
     listOrgsAction(),
@@ -266,7 +266,7 @@ export async function resolveOrg(input = {}, opts = {}) {
   // --- Class 4: profile state ----------------------------------------------
   const selected = trimmed(coreGetActiveOrgId());
   if (selected) {
-    return { orgId: assertOrgIdShape(selected, "org use"), source: "profile", sourceDetail: "org use" };
+    return { orgId: assertOrgIdShape(selected, "orgs use"), source: "profile", sourceDetail: "orgs use" };
   }
   const activeProject = trimmed(getActiveProjectId());
   if (activeProject) {
@@ -278,7 +278,7 @@ export async function resolveOrg(input = {}, opts = {}) {
   fail({
     code: "ORG_REQUIRED",
     message: "No organization specified and no current organization set.",
-    hint: `Pass --org <org_id>, set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 org use <org_id>`,
+    hint: `Pass --org <org_id>, set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 orgs use <org_id>`,
     next_actions: orgRequiredActions(),
   });
   return null; // unreachable — fail() exits
@@ -301,17 +301,17 @@ export async function resolveOrgId(a, opts = {}) {
  * Every Org-Scoped Command").
  *
  * `<org_id>` is optional sugar on every verb that acts on an organization —
- * `org get`, `org member add`, `billing link-wallet`, … A leading positional
+ * `orgs get`, `orgs members add`, `billing link-wallet`, … A leading positional
  * that IS an org id (a UUID) addresses that org; anything else is the verb's
  * own next positional (a wallet, an email, a principal) and the org comes from
  * the shared chain: `--org`, then `RUN402_ORG`, then the `.run402.json`
- * binding, then `org use`. So inside a bound checkout the two-agent case reads
- * `run402 org member add 0xB… --role developer` with nothing else to know.
+ * binding, then `orgs use`. So inside a bound checkout the two-agent case reads
+ * `run402 orgs members add 0xB… --role developer` with nothing else to know.
  *
  * Naming the org twice with different values (positional AND `--org`) is
  * `AMBIGUOUS_ORG`, never a silent pick — the same refusal the env-vs-binding
  * pair gets. A non-org first positional with no chain answer fails
- * `ORG_REQUIRED` and NAMES the rejected value, so `org get foo` says why `foo`
+ * `ORG_REQUIRED` and NAMES the rejected value, so `orgs get foo` says why `foo`
  * did not count rather than reporting a bare "no organization".
  *
  * Returns the org id with provenance plus the REMAINING positionals; bound
@@ -350,7 +350,7 @@ export async function takeOrgPositional(a, valueFlags = [], opts = {}) {
     message: typeof first === "string"
       ? `No organization specified and no current organization set (${JSON.stringify(first)} is not an org_id — an org_id is a UUID).`
       : "No organization specified and no current organization set.",
-    hint: `Pass --org <org_id> (or a leading <org_id> positional), set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 org use <org_id>`,
+    hint: `Pass --org <org_id> (or a leading <org_id> positional), set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 orgs use <org_id>`,
     ...(typeof first === "string" ? { details: { rejected_positional: first } } : {}),
     next_actions: orgRequiredActions(),
   });
@@ -388,7 +388,7 @@ export function getSelectedOrgId() {
 }
 
 /** Record the profile's selected organization. */
-export function setSelectedOrgId(orgId, origin = "org use") {
+export function setSelectedOrgId(orgId, origin = "orgs use") {
   coreSetActiveOrgId(assertOrgIdShape(orgId, origin));
 }