run402 4.27.0 → 4.28.0

package/lib/command-manifest.mjs

@@ -202,6 +202,8 @@ export const COMMAND_MANIFEST = [
   { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["org", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
+  { path: ["org", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "member", "list"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "member", "add"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
   { path: ["org", "member", "role"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1", "--role", "viewer"] },

package/lib/init.mjs

@@ -627,6 +627,29 @@ export async function run(args = []) {
     }
   }
 
+  // 5b. The org. `init` already materializes it (the tier read above
+  // authenticates, which provisions the wallet's org-of-one), so NOT reporting
+  // it forced every agent that wanted to coordinate to go find it with a second
+  // command and copy a UUID by hand. It is an identifier, not a credential.
+  try {
+    const orgs = await getSdk().orgs.list();
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    summary.orgs = rows.map((o) => ({
+      org_id: o.org_id,
+      display_name: o.display_name ?? null,
+      role: o.role ?? null,
+    }));
+    if (rows.length === 1) {
+      line("Org", `${rows[0].org_id}${rows[0].display_name ? ` (${rows[0].display_name})` : ""}`);
+    } else if (rows.length > 1) {
+      line("Org", `${rows.length} organizations — run402 org list`);
+    }
+  } catch {
+    // Best-effort, exactly like the billing read: a listing failure must never
+    // fail setup.
+    summary.orgs = null;
+  }
+
   // 6. Next step — canonical typed action(s); `next_step` is the back-compat
   // string mirror of the first action's command (one spelling, surface-wide).
   write("");

package/lib/org-context.mjs

@@ -258,6 +258,11 @@ export async function resolveOrgId(a, opts = {}) {
   return resolved ? resolved.orgId : null;
 }
 
+/** Validate an org id supplied by a human, naming the origin. Throws via fail(). */
+export function requireOrgIdShape(orgId, origin = "--org") {
+  return assertOrgIdShape(orgId, origin);
+}
+
 /** The profile's selected organization, without running the chain. */
 export function getSelectedOrgId() {
   return trimmed(coreGetActiveOrgId());

package/lib/org.mjs

@@ -1,6 +1,9 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
+import { nextAction } from "./next-actions.mjs";
 import {
+  requireOrgIdShape,
   resolveOrg,
   orgProvenance,
   getSelectedOrgId,
@@ -31,6 +34,8 @@ Usage:
   run402 org use     <org_id>
   run402 org current
   run402 org clear
+  run402 org bind   [--org <org_id>] [--room <key>]
+  run402 org unbind
   run402 org audit  <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
   run402 org member list <org_id>
   run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
@@ -51,6 +56,8 @@ Subcommands:
   use         Select the current org for this wallet profile
   current     Report the resolved current org and where it came from
   clear       Clear this wallet profile's org selection
+  bind        Write this checkout's org (+room) into .run402.json — commit it
+  unbind      Remove the org/room keys from .run402.json
   payout-wallet  Set or clear the tenant route payout wallet (admin+)
   whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
   member      Manage members (list, add, role, rm) — mutations require owner
@@ -239,6 +246,99 @@ async function clear(args) {
   console.log(JSON.stringify({ org_id: null, selected: false, previous_org_id: previous ?? null }, null, 2));
 }
 
+/**
+ * Slugify a directory name into a legal room key.
+ * Room keys match /^[a-z0-9][a-z0-9._-]{0,63}$/ (the DB CHECK on every
+ * agent-messaging table), so the repo's own name has to be coerced, not trusted.
+ */
+function roomKeyFromDir(dir) {
+  const base = dir.split("/").filter(Boolean).pop() ?? "";
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "").slice(0, 64);
+  return /^[a-z0-9]/.test(slug) ? slug : null;
+}
+
+/**
+ * Write this checkout's org (and room) into `.run402.json`.
+ *
+ * WHY THIS PICKS FOR YOU WHEN YOU OWN EXACTLY ONE ORG, while the resolution
+ * chain never does: they are different acts. The chain runs on EVERY command
+ * and must not change meaning the day you are invited to a second org — so it
+ * refuses to infer. This runs ONCE, because you asked it to, and it WRITES THE
+ * ANSWER DOWN. Nothing is inferred afterwards; the file is read verbatim
+ * forever after. An explicit act with a recorded result is not a heuristic.
+ *
+ * With two or more orgs there is nothing to pick, so it lists them and stops.
+ */
+async function bind(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--org", "--room"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, { min: 0, max: 0, command: "run402 org bind [--org <org_id>] [--room <key>]" });
+
+  let orgId = flagValue(a, "--org");
+  let picked = "flag";
+  if (!orgId) {
+    let orgs;
+    try {
+      orgs = await getSdk().orgs.list();
+    } catch (err) {
+      reportSdkError(err);
+      return;
+    }
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    if (rows.length === 0) {
+      fail({
+        code: "NO_ORGS",
+        message: "This wallet is a member of no organization yet.",
+        hint: "Run 'run402 init' to provision one, or ask an owner to add you with 'run402 org member add'.",
+        next_actions: [nextAction("initialize_wallet", { command: "run402 init", why: "Provision this wallet's organization, then retry." })],
+      });
+    }
+    if (rows.length > 1) {
+      fail({
+        code: "AMBIGUOUS_ORG",
+        message: `This wallet belongs to ${rows.length} organizations — name the one to bind.`,
+        hint: "run402 org bind --org <org_id>",
+        details: { orgs: rows.map((o) => ({ org_id: o.org_id, display_name: o.display_name ?? null, role: o.role ?? null })) },
+        next_actions: [nextAction("edit_request", { command: "run402 org bind --org <org_id>", why: "Name which organization this checkout coordinates in." })],
+      });
+    }
+    orgId = rows[0].org_id;
+    picked = "sole_membership";
+  }
+
+  const room = flagValue(a, "--room") ?? roomKeyFromDir(process.cwd());
+  const { contents, file } = updateBindingFile(process.cwd(), {
+    org: requireOrgIdShape(orgId, picked === "flag" ? "--org" : "org list"),
+    ...(room ? { room } : {}),
+  });
+  console.log(JSON.stringify({
+    org_id: orgId,
+    room_key: room ?? null,
+    org_source: picked,
+    file: ".run402.json",
+    path: file,
+    bound: true,
+    safe_to_commit: true,
+    note: "Safe to commit — an org id is an identifier, not a credential; authorization stays server-side.",
+    binding: contents,
+  }, null, 2));
+}
+
+async function unbind(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org unbind" });
+  const previous = readBindingFile(process.cwd());
+  const { contents, removed } = updateBindingFile(process.cwd(), { org: null, room: null });
+  console.log(JSON.stringify({
+    file: ".run402.json",
+    unbound: previous.org !== undefined || previous.room !== undefined,
+    removed,
+    binding: contents,
+  }, null, 2));
+}
+
 async function current(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
@@ -534,6 +634,8 @@ export async function run(sub, args) {
     case "use": await use(args); break;
     case "current": await current(args); break;
     case "clear": await clear(args); break;
+    case "bind": await bind(args); break;
+    case "unbind": await unbind(args); break;
     case "audit": await audit(args); break;
     default:
       failUnknownSubcommand("org", sub);

package/lib/wallet-context.mjs

@@ -19,7 +19,7 @@
  * wallets and no flag is given, that is a hard error (not a silent pick).
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
@@ -27,6 +27,7 @@ import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-d
 import { readAllowance } from "../core-dist/allowance.js";
 
 const DEFAULT = "default";
+const BINDING_FILE = ".run402.json";
 const GLOBAL_FLAGS = new Set(["--wallet", "--profile"]);
 // The `wallets` group is the management + escape surface — it must work even
 // when selection is ambiguous (so you can `wallets unbind`), and it validates
@@ -84,6 +85,45 @@ function readBindingKeyFrom(dir, key) {
   return null;
 }
 
+/** Path of the committed binding file for a directory. */
+export function bindingFilePath(dir = process.cwd()) {
+  return join(dir, BINDING_FILE);
+}
+
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export function readBindingFile(dir = process.cwd()) {
+  try {
+    const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * MERGE keys into a directory's binding file. A `null` value removes its key;
+ * a file left with no keys is deleted rather than committed empty.
+ *
+ * The file is shared by tiers (`wallet` from `wallets bind`, `org`/`room` from
+ * `org bind`) and unknown keys are preserved, so one tier can never clobber
+ * another's binding — which a whole-file write did until this existed.
+ */
+export function updateBindingFile(dir, patch) {
+  const file = bindingFilePath(dir);
+  const next = { ...readBindingFile(dir) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null || v === undefined) delete next[k];
+    else next[k] = v;
+  }
+  if (Object.keys(next).length === 0) {
+    const existed = existsSync(file);
+    if (existed) rmSync(file, { force: true });
+    return { file, contents: null, removed: existed };
+  }
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { file, contents: next, removed: false };
+}
+
 /**
  * Nearest binding carrying `key`, walking up from `startDir` to the root.
  *

package/lib/wallets.mjs

@@ -32,6 +32,7 @@ import {
 } from "../core-dist/profiles.js";
 import { readAllowance, saveAllowance } from "../core-dist/allowance.js";
 import { getSdk } from "./sdk.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
 
 const DEFAULT = "default";
 const PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
@@ -208,14 +209,15 @@ async function cmdRename(args) {
 function cmdBind(args) {
   let name = args.find((a) => a && !a.startsWith("-"));
   name = name ? requireName(name) : getActiveProfile();
-  const file = join(process.cwd(), ".run402.json");
-  writeFileSync(file, JSON.stringify({ wallet: name }, null, 2) + "\n");
+  // MERGE, never clobber: the same file carries `org`/`room` from `org bind`.
+  const { contents } = updateBindingFile(process.cwd(), { wallet: name });
   const result = {
     wallet: name,
     file: ".run402.json",
     bound: true,
     safe_to_commit: true,
     note: "Safe to commit — contains no secrets, only the wallet name.",
+    binding: contents,
   };
   if (name !== DEFAULT && !profileExists(name)) {
     result.warning = `No local wallet named '${name}' yet — create it with 'run402 wallets new ${name}'.`;
@@ -224,10 +226,12 @@ function cmdBind(args) {
 }
 
 function cmdUnbind() {
-  const file = join(process.cwd(), ".run402.json");
-  const existed = existsSync(file);
-  if (existed) rmSync(file, { force: true });
-  out({ file: ".run402.json", unbound: existed });
+  // Removes only the WALLET key. An `org`/`room` binding in the same file
+  // belongs to another tier and must survive; the file is deleted only when
+  // unbinding leaves nothing behind.
+  const had = readBindingFile(process.cwd()).wallet !== undefined;
+  const { contents, removed } = updateBindingFile(process.cwd(), { wallet: null });
+  out({ file: ".run402.json", unbound: had, removed, binding: contents });
 }
 
 async function cmdImport(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {