@drakon-systems/multi-clawd 1.3.0 → 1.4.0

package/README.md

@@ -11,7 +11,7 @@ same model, next account, full harness on every hop.
 
 [![OpenClaw plugin](https://img.shields.io/badge/OpenClaw-plugin-ff4f00)](https://docs.openclaw.ai/plugins)
 [![npm](https://img.shields.io/badge/npm-%40drakon--systems%2Fmulti--clawd-cb3837)](https://www.npmjs.com/package/@drakon-systems/multi-clawd)
-[![version](https://img.shields.io/badge/version-1.0.1-4c9aff)](CHANGELOG.md)
+[![version](https://img.shields.io/npm/v/%40drakon-systems%2Fmulti-clawd?color=4c9aff&label=version)](CHANGELOG.md)
 [![license: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
 
@@ -21,6 +21,38 @@ same model, next account, full harness on every hop.
 
 ---
 
+## Quick start
+
+```bash
+npm i -g @drakon-systems/multi-clawd   # the CLI (once)
+
+multi-clawd update    # install (or update) the OpenClaw plugin — right flags, restart, doctor
+multi-clawd setup     # guided wizard: accounts, isolated second login, pool, watchdog
+multi-clawd login claw2   # launch the right Claude sign-in for an account (or re-auth it)
+multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
+multi-clawd doctor    # health check (add --probe for a live end-to-end turn)
+```
+
+That's the entire lifecycle. `update` installs the plugin when it's missing and
+upgrades it when it's not — nobody types registry flags. `setup` walks you
+through the whole shape below and merges config **non-destructively** (backup
+first, existing accounts never overwritten, re-runs are no-ops). Prefer not to
+install anything? Every command also runs as
+`npx @drakon-systems/multi-clawd <command>`.
+
+**The 3-step picture** `setup` walks you through:
+
+1. **Main account** — your existing `claude` login, used as-is (nothing to do).
+2. **Second account** — lives in its **own isolated config dir** (a separate
+   Claude "app", e.g. `~/.claw2`), so the two logins can never clobber each
+   other; token via a secret-manager reference (recommended), token file, or
+   the dir's own login.
+3. **The pool** — one backend id (`clawd/…`) fronting both: every launch runs
+   on the first account that isn't nearly maxed out, and your fallback chain
+   routes through it.
+
+Then `multi-clawd explain` shows you exactly what you built.
+
 ## Why
 
 OpenClaw's bundled `claude-cli` backend runs Claude Code on a **single**
@@ -113,20 +145,24 @@ Code backend runs.
 
 ## Install
 
-**From npm (recommended):**
+**The CLI does it all (recommended)** — see [Quick start](#quick-start):
+
+```bash
+npm i -g @drakon-systems/multi-clawd && multi-clawd update
+```
+
+`update` runs the registry install with the right flags, offers the gateway
+restart, and finishes with a doctor health check. Prefer the raw form?
 
 ```bash
 openclaw plugins install @drakon-systems/multi-clawd --pin
 openclaw gateway restart
 ```
 
-The gateway pulls the prebuilt package — no clone, no build step, nothing to
-keep in sync. `--pin` records the exact resolved version, so an upgrade is a
-deliberate `@latest`, never a surprise. `openclaw` itself is a *peer*
-dependency (the host provides it), so the install stays lean. Confirm with
-`openclaw plugins list` (expect `multi-clawd` enabled) — it also shows the
-install path; run the doctor from there:
-`node <install-path>/scripts/doctor.mjs`.
+Either way the gateway pulls the prebuilt package — no clone, no build step,
+nothing to keep in sync. `--pin` records the exact resolved version, so an
+upgrade is a deliberate act, never a surprise. `openclaw` itself is a *peer*
+dependency (the host provides it), so the install stays lean.
 
 **From ClawHub (alternative registry):**
 

package/dist/login-plan.js

@@ -0,0 +1,43 @@
+export function loginPlanForAccount(acc) {
+    if (acc.native) {
+        return {
+            command: ["claude", "auth", "login"],
+            clearConfigDir: true,
+            verify: "auth-status",
+        };
+    }
+    if (acc.oauthTokenRef) {
+        return {
+            command: ["claude", "setup-token"],
+            configDir: acc.configDir,
+            ensureDir: acc.configDir !== undefined,
+            clearConfigDir: false,
+            scratchDir: acc.configDir === undefined,
+            verify: "manual",
+            afterNote: `store the printed setup-token in your ${acc.oauthTokenRef.provider ?? "secret"} ` +
+                `provider at the item your secret reference points to — the gateway resolves it from there; ` +
+                `this tool never touches the token itself`,
+            warn: acc.configDir === undefined
+                ? "this account has no config dir of its own — running in a temporary scratch dir so your default login is untouched"
+                : undefined,
+        };
+    }
+    if (acc.oauthTokenFile) {
+        return {
+            command: ["claude", "setup-token"],
+            configDir: acc.configDir,
+            ensureDir: acc.configDir !== undefined,
+            clearConfigDir: false,
+            scratchDir: acc.configDir === undefined,
+            verify: "token-file",
+            afterNote: `save the printed setup-token to ${acc.oauthTokenFile} and chmod 600 it`,
+        };
+    }
+    return {
+        command: ["claude", "auth", "login"],
+        configDir: acc.configDir,
+        ensureDir: true,
+        clearConfigDir: false,
+        verify: "auth-status",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account.",
   "type": "module",
   "license": "MIT",

package/scripts/cli.mjs

@@ -33,6 +33,7 @@ function usage() {
 ${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
 
   ${BOLD}setup${RESET}     guided setup wizard (accounts, pool, watchdog)
+  ${BOLD}login${RESET}     log a configured account in (or re-auth it) — right dir, right env
   ${BOLD}explain${RESET}   your setup in plain English — accounts, pool, fallback chain
   ${BOLD}update${RESET}    update the plugin to the latest version
   ${BOLD}doctor${RESET}    health check (add --probe for a live turn)
@@ -270,10 +271,102 @@ async function explain() {
   console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
 }
 
+/**
+ * `login <account>` — launch the RIGHT Claude login flow for a configured
+ * account: correct config-dir environment, dir created if missing, verified
+ * afterwards (shows which email is signed in). The human does the OAuth; this
+ * never captures, stores, or prints a token value.
+ */
+async function login() {
+  const { readFileSync: rf, existsSync, mkdirSync, chmodSync, statSync, mkdtempSync, rmSync } =
+    await import("node:fs");
+  const { homedir, tmpdir } = await import("node:os");
+  let lp, ec;
+  try {
+    lp = await import(resolve(__dirname, "..", "dist", "login-plan.js"));
+    ec = await import(resolve(__dirname, "..", "dist", "explain-core.js"));
+  } catch {
+    console.error("login: built dist/ is missing — reinstall the package.");
+    process.exit(1);
+  }
+  let config = {};
+  try {
+    config = JSON.parse(rf(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
+  } catch {
+    console.error("login: could not read ~/.openclaw/openclaw.json — run `multi-clawd setup` first.");
+    process.exit(1);
+  }
+  const accounts = config?.plugins?.entries?.["multi-clawd"]?.config?.accounts ?? [];
+  if (accounts.length === 0) {
+    console.error("login: no multi-clawd accounts configured — run `multi-clawd setup` first.");
+    process.exit(1);
+  }
+  const target = rest[0];
+  const acc = accounts.find((a) => a.id === target);
+  if (!acc) {
+    console.log(`\n${BOLD}Which account?${RESET}  multi-clawd login <id>\n`);
+    for (const a of accounts) {
+      console.log(`  ${BOLD}${a.id}${RESET}${a.label ? `  "${a.label}"` : ""}`);
+      console.log(`    → ${ec.describeAccount(a)}`);
+    }
+    process.exit(target ? 1 : 0);
+  }
+  const plan = lp.loginPlanForAccount(acc);
+  const expand = (p) => (p.startsWith("~/") ? join(homedir(), p.slice(2)) : p);
+  const env = { ...process.env };
+  delete env.CLAUDE_CONFIG_DIR;
+  let scratch;
+  if (plan.scratchDir) {
+    scratch = mkdtempSync(join(tmpdir(), "multi-clawd-login-"));
+    env.CLAUDE_CONFIG_DIR = scratch;
+  } else if (plan.configDir) {
+    const dir = expand(plan.configDir);
+    if (plan.ensureDir && !existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    env.CLAUDE_CONFIG_DIR = dir;
+  }
+  if (plan.warn) console.log(`  ⚠ ${plan.warn}`);
+  console.log(`\n  Launching ${DIM}${plan.command.join(" ")}${RESET} for ${BOLD}${acc.id}${RESET}${acc.label ? ` ("${acc.label}")` : ""}.`);
+  console.log(`  ${BOLD}Sign in as the account this slot is for${RESET} — not your other one!\n`);
+  const r = spawnSync(plan.command[0], plan.command.slice(1), { stdio: "inherit", env });
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+  if (r.status !== 0) {
+    console.error(`\n  ❌ ${plan.command.join(" ")} exited with ${r.status ?? "an error"}.`);
+    process.exit(1);
+  }
+  if (plan.verify === "auth-status") {
+    try {
+      const out = spawnSync("claude", ["auth", "status"], { encoding: "utf8", env }).stdout ?? "";
+      const email = out.match(/"email"\s*:\s*"([^"]+)"/)?.[1];
+      const loggedIn = /"loggedIn"\s*:\s*true/.test(out);
+      if (loggedIn) console.log(`\n  ✅ ${acc.id} is signed in${email ? ` as ${BOLD}${email}${RESET}` : ""} — double-check that's the right account for this slot.`);
+      else console.log("\n  ⚠ auth status does not show a login — try again or check `claude auth status` yourself.");
+    } catch {
+      console.log("\n  (could not verify — run `claude auth status` to confirm)");
+    }
+  } else if (plan.verify === "token-file" && acc.oauthTokenFile) {
+    const f = expand(acc.oauthTokenFile);
+    console.log(`\n  Now: ${plan.afterNote}`);
+    if (await askYes("  Done — token saved?")) {
+      if (existsSync(f) && statSync(f).size > 0) {
+        chmodSync(f, 0o600);
+        console.log(`  ✅ ${f} present (permissions set to 600). Restart the gateway to pick it up.`);
+      } else {
+        console.log(`  ❌ ${f} is missing or empty — the account won't authenticate until it's there.`);
+      }
+    }
+  } else if (plan.afterNote) {
+    console.log(`\n  Now: ${plan.afterNote}`);
+    console.log("  Then restart the gateway; its login probe will confirm within ~15 min (or run `multi-clawd doctor`).");
+  }
+}
+
 switch (cmd) {
   case "setup":
     runSibling("setup.mjs", rest);
     break;
+  case "login":
+    await login();
+    break;
   case "explain":
     await explain();
     break;

package/scripts/setup.mjs

@@ -156,8 +156,12 @@ async function secondAccountFlow(id, prior) {
     console.log(`  ✗ ${err}`);
   }
   console.log(`
-  Now log the SECOND account in (you, in your own terminal — the wizard
-  cannot and must not do this for you):
+  Now log the SECOND account in (you — it needs your browser and your
+  credentials). Easiest AFTER this wizard finishes:
+
+      multi-clawd login ${id}      # launches the right flow, right dir, verified
+
+  or manually, right now, in your own terminal:
 
       CLAUDE_CONFIG_DIR=${configDir} claude setup-token
 
@@ -395,6 +399,7 @@ if (DRY_RUN || !wroteConfig) {
 console.log(`
 Done. Finish with:
 
+  multi-clawd login <account-id>   # if any account still needs its Claude sign-in
   openclaw gateway restart
   node ${join(__dirname, "doctor.mjs")}     # expect READY