run402 2.26.0 → 2.28.0

package/lib/wallet-context.mjs

@@ -0,0 +1,223 @@
+/**
+ * Active-wallet (profile) resolution for the CLI edge.
+ *
+ * Runs at the top of cli.mjs BEFORE any subcommand module (and therefore
+ * before cli/lib/config.mjs snapshots its paths) is loaded. Resolves which
+ * named wallet a command operates on, sets `process.env.RUN402_WALLET` so all
+ * core path functions resolve under it, and emits a provenance line for
+ * non-default selections. Core itself stays env-only — the `--wallet` flag and
+ * the per-directory `.run402.json` binding are translated into the env var
+ * here, at the edge.
+ *
+ * Precedence (highest first):
+ *   1. --wallet <name> / --profile <name>   (flag)
+ *   2. RUN402_WALLET / RUN402_PROFILE        (env)
+ *   3. nearest .run402.local.json/.run402.json (directory binding, walk up)
+ *   4. config.json active_wallet              (global `wallets use`)
+ *   5. "default"                              (root wallet)
+ *
+ * The flag is also the conflict resolver: when env and binding name different
+ * wallets and no flag is given, that is a hard error (not a silent pick).
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fail } from "./sdk-errors.mjs";
+import { isValidProfileName } from "../core-dist/config.js";
+import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-dist/profiles.js";
+import { readAllowance } from "../core-dist/allowance.js";
+
+const DEFAULT = "default";
+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
+// its own positional targets. `init` creates wallets, so it must not fail
+// closed on a not-yet-existing name.
+const CONFLICT_EXEMPT = new Set(["wallets"]);
+const EXISTENCE_EXEMPT = new Set(["wallets", "init"]);
+
+/**
+ * Split the global --wallet/--profile flag (and its value) out of argv so the
+ * subcommand never sees it. Pure: no core imports, no side effects. Returns
+ * the cleaned argv and the selected flag (`{ flag, value }` or null). Last
+ * occurrence wins. A missing value is left as `value: undefined` for
+ * resolveWallet to reject with a precise error.
+ */
+export function splitWalletFlag(rawArgv = []) {
+  const argv = [];
+  let flag = null;
+  for (let i = 0; i < rawArgv.length; i++) {
+    const a = rawArgv[i];
+    if (typeof a === "string" && a.startsWith("--") && a.includes("=")) {
+      const name = a.slice(0, a.indexOf("="));
+      if (GLOBAL_FLAGS.has(name)) {
+        flag = { flag: name, value: a.slice(a.indexOf("=") + 1) };
+        continue;
+      }
+    }
+    if (typeof a === "string" && GLOBAL_FLAGS.has(a)) {
+      const next = rawArgv[i + 1];
+      if (next === undefined || (typeof next === "string" && next.startsWith("-"))) {
+        flag = { flag: a, value: undefined };
+      } else {
+        flag = { flag: a, value: next };
+        i += 1;
+      }
+      continue;
+    }
+    argv.push(a);
+  }
+  return { argv, walletFlag: flag };
+}
+
+function readBindingFrom(dir) {
+  // .run402.local.json (gitignored personal override) beats .run402.json.
+  for (const fname of [".run402.local.json", ".run402.json"]) {
+    const p = join(dir, fname);
+    try {
+      const parsed = JSON.parse(readFileSync(p, "utf8"));
+      const w = parsed?.wallet;
+      if (typeof w === "string" && w.trim()) return { wallet: w.trim(), file: p };
+    } catch {
+      /* missing / unreadable / malformed → skip */
+    }
+  }
+  return null;
+}
+
+/** Nearest binding walking up from `startDir` to the filesystem root. */
+export function findBinding(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    const b = readBindingFrom(dir);
+    if (b) return b;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function assertValidName(name, origin) {
+  if (name === DEFAULT || isValidProfileName(name)) return;
+  fail({
+    code: "BAD_WALLET_NAME",
+    message: `Invalid wallet name ${JSON.stringify(name)} (from ${origin}).`,
+    hint: "Wallet names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-').",
+    details: { name, origin },
+  });
+}
+
+/** Pure precedence resolution + conflict detection. Returns { name, source, sourceDetail }. */
+export function resolveWallet({ walletFlag, env = {}, cwd = process.cwd(), cmd } = {}) {
+  if (walletFlag) {
+    if (walletFlag.value === undefined || walletFlag.value === "") {
+      fail({ code: "BAD_FLAG", message: `${walletFlag.flag} requires a value`, details: { flag: walletFlag.flag } });
+    }
+    assertValidName(walletFlag.value, walletFlag.flag);
+    return { name: walletFlag.value, source: "flag", sourceDetail: walletFlag.flag };
+  }
+
+  const envRaw = env.RUN402_WALLET ?? env.RUN402_PROFILE;
+  const envName = typeof envRaw === "string" && envRaw.trim() ? envRaw.trim() : null;
+  const binding = findBinding(cwd);
+
+  if (envName && binding && envName !== binding.wallet && !CONFLICT_EXEMPT.has(cmd)) {
+    fail({
+      code: "WALLET_SELECTION_CONFLICT",
+      message: `Ambiguous wallet: RUN402_WALLET=${envName} but ${binding.file} selects '${binding.wallet}'.`,
+      hint: "Resolve with one of: pass --wallet <name>, unset RUN402_WALLET, or run402 wallets unbind.",
+      details: { env_wallet: envName, binding_wallet: binding.wallet, binding_file: binding.file },
+    });
+  }
+
+  if (envName) {
+    assertValidName(envName, "RUN402_WALLET");
+    return { name: envName, source: "env", sourceDetail: "RUN402_WALLET" };
+  }
+  if (binding) {
+    assertValidName(binding.wallet, binding.file);
+    return { name: binding.wallet, source: "binding", sourceDetail: binding.file };
+  }
+  const def = getDefaultWallet();
+  if (def && def !== DEFAULT) return { name: def, source: "config", sourceDetail: "wallets use" };
+  return { name: DEFAULT, source: "default", sourceDetail: null };
+}
+
+function looksLikeAddress(s) {
+  return typeof s === "string" && /^0x[a-fA-F0-9]{40}$/.test(s);
+}
+
+/** Fail closed when a non-default selection names a wallet that does not exist locally. */
+export function enforceWalletExists({ name, source }, cmd) {
+  if (name === DEFAULT) return;
+  if (EXISTENCE_EXEMPT.has(cmd)) return;
+  if (profileExists(name)) return;
+  const hint = looksLikeAddress(name)
+    ? `'${name}' looks like an address. For billing use: run402 billing ... --wallet-address ${name}`
+    : `Run 'run402 wallets list' to see wallets, or 'run402 wallets new ${name}' to create it.`;
+  fail({
+    code: "WALLET_NOT_FOUND",
+    message: `No local wallet named '${name}'.`,
+    hint,
+    details: { wallet: name, source },
+  });
+}
+
+function shortAddr(a) {
+  return typeof a === "string" && a.length >= 12 ? `${a.slice(0, 6)}…${a.slice(-4)}` : a;
+}
+
+/** Best-effort address for display: meta.json (no key) first, allowance second. */
+function walletAddress(name) {
+  const meta = readMeta(name);
+  if (meta?.address) return meta.address;
+  try {
+    return readAllowance(join(profileDir(name), "allowance.json"))?.address ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Emit the stderr provenance line for non-default selections (silent for default). */
+export function emitProvenance({ name, source, sourceDetail }, { cmd, quiet } = {}) {
+  if (quiet) return;
+  if (name === DEFAULT) return;
+  if (cmd === "wallets") return; // the wallets group reports its own context
+  const where =
+    source === "env" ? "RUN402_WALLET" :
+    source === "config" ? "wallets use" :
+    sourceDetail || source;
+  const addr = walletAddress(name);
+  const addrPart = addr ? ` (${shortAddr(addr)})` : "";
+  process.stderr.write(`  ↪ wallet: ${name}${addrPart}   ← ${where}\n`);
+}
+
+/**
+ * Orchestrate edge resolution: resolve → fail-closed → publish to the env so
+ * core paths resolve → provenance. Returns the resolved selection.
+ */
+export function applyWalletSelection({ walletFlag, cmd, cwd = process.cwd(), env = process.env, quiet = false } = {}) {
+  // Capture the pre-resolution signals so `wallets current` can report
+  // provenance and any env-vs-binding divergence (it can't recompute them once
+  // we overwrite RUN402_WALLET below).
+  const envRaw = env.RUN402_WALLET ?? env.RUN402_PROFILE;
+  const envName = typeof envRaw === "string" && envRaw.trim() ? envRaw.trim() : null;
+  const binding = findBinding(cwd);
+
+  const resolved = resolveWallet({ walletFlag, env, cwd, cmd });
+  enforceWalletExists(resolved, cmd);
+
+  // Publish to the env so all core path functions resolve under this wallet.
+  env.RUN402_WALLET = resolved.name;
+  env.RUN402_ACTIVE_WALLET_JSON = JSON.stringify({
+    name: resolved.name,
+    source: resolved.source,
+    sourceDetail: resolved.sourceDetail,
+    binding: binding ? { wallet: binding.wallet, file: binding.file } : null,
+    envName,
+    diverged: !!(envName && binding && envName !== binding.wallet),
+  });
+
+  emitProvenance(resolved, { cmd, quiet });
+  return resolved;
+}

package/lib/wallet-context.test.mjs

@@ -0,0 +1,228 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  splitWalletFlag,
+  findBinding,
+  resolveWallet,
+  enforceWalletExists,
+  emitProvenance,
+} from "./wallet-context.mjs";
+import { ensureProfileDir, setDefaultWallet } from "../core-dist/profiles.js";
+
+const origConfigDir = process.env.RUN402_CONFIG_DIR;
+let tmp;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "wallet-ctx-"));
+  process.env.RUN402_CONFIG_DIR = tmp;
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+  if (origConfigDir !== undefined) process.env.RUN402_CONFIG_DIR = origConfigDir;
+  else delete process.env.RUN402_CONFIG_DIR;
+});
+
+// Capture a fail() invocation: fail() does console.error(envelope) + process.exit.
+function captureFail(fn) {
+  const origExit = process.exit;
+  const origErr = console.error;
+  let envelope = null;
+  let exited = false;
+  console.error = (s) => { try { envelope = JSON.parse(s); } catch { envelope = s; } };
+  process.exit = () => { exited = true; throw new Error("__EXIT__"); };
+  try {
+    fn();
+  } catch (e) {
+    if (!String(e?.message).startsWith("__EXIT__")) throw e;
+  } finally {
+    process.exit = origExit;
+    console.error = origErr;
+  }
+  return { envelope, exited };
+}
+
+function bindingDir(wallet, localWallet) {
+  const dir = mkdtempSync(join(tmpdir(), "binding-"));
+  if (wallet) writeFileSync(join(dir, ".run402.json"), JSON.stringify({ wallet }));
+  if (localWallet) writeFileSync(join(dir, ".run402.local.json"), JSON.stringify({ wallet: localWallet }));
+  return dir;
+}
+
+describe("splitWalletFlag", () => {
+  it("passes through argv with no global flag", () => {
+    assert.deepEqual(splitWalletFlag(["status"]), { argv: ["status"], walletFlag: null });
+  });
+  it("strips --wallet <value>", () => {
+    const r = splitWalletFlag(["--wallet", "kychon", "status"]);
+    assert.deepEqual(r.argv, ["status"]);
+    assert.deepEqual(r.walletFlag, { flag: "--wallet", value: "kychon" });
+  });
+  it("strips --wallet=<value> mid-args", () => {
+    const r = splitWalletFlag(["deploy", "apply", "--wallet=foo", "--manifest", "x"]);
+    assert.deepEqual(r.argv, ["deploy", "apply", "--manifest", "x"]);
+    assert.equal(r.walletFlag.value, "foo");
+  });
+  it("accepts --profile as an alias", () => {
+    const r = splitWalletFlag(["--profile", "p", "status"]);
+    assert.equal(r.walletFlag.flag, "--profile");
+    assert.equal(r.walletFlag.value, "p");
+  });
+  it("last occurrence wins", () => {
+    const r = splitWalletFlag(["--wallet", "a", "--wallet", "b", "status"]);
+    assert.equal(r.walletFlag.value, "b");
+    assert.deepEqual(r.argv, ["status"]);
+  });
+  it("records a missing value as undefined", () => {
+    const r = splitWalletFlag(["status", "--wallet"]);
+    assert.deepEqual(r.argv, ["status"]);
+    assert.equal(r.walletFlag.value, undefined);
+  });
+});
+
+describe("findBinding", () => {
+  it("finds the nearest .run402.json walking up", () => {
+    const root = bindingDir("client-a");
+    const sub = join(root, "api");
+    mkdirSync(sub);
+    const b = findBinding(sub);
+    assert.equal(b.wallet, "client-a");
+    rmSync(root, { recursive: true, force: true });
+  });
+  it(".run402.local.json overrides .run402.json in the same dir", () => {
+    const dir = bindingDir("client-a", "client-a-staging");
+    assert.equal(findBinding(dir).wallet, "client-a-staging");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("returns null when no binding exists in the tree", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    assert.equal(findBinding(dir), null);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("resolveWallet — precedence", () => {
+  it("flag beats everything", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ walletFlag: { flag: "--wallet", value: "kychon" }, env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "flag");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("env beats binding when they agree is moot; env returned when no binding", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: { RUN402_WALLET: "kychon" }, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "env");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("binding used when no flag/env", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "client-a");
+    assert.equal(r.source, "binding");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("global default (wallets use) applies when no flag/env/binding", () => {
+    setDefaultWallet("kychon");
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "kychon");
+    assert.equal(r.source, "config");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("falls back to default when nothing selects", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const r = resolveWallet({ env: {}, cwd: dir, cmd: "status" });
+    assert.equal(r.name, "default");
+    assert.equal(r.source, "default");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("resolveWallet — conflict + validation", () => {
+  it("env vs binding mismatch is a hard error (non-wallets command)", () => {
+    const dir = bindingDir("client-a");
+    const { envelope, exited } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "deploy" }));
+    assert.ok(exited);
+    assert.equal(envelope.code, "WALLET_SELECTION_CONFLICT");
+    assert.match(envelope.message, /personal/);
+    assert.match(envelope.message, /client-a/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("matching env and binding proceed without error", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: { RUN402_WALLET: "client-a" }, cwd: dir, cmd: "deploy" });
+    assert.equal(r.name, "client-a");
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("the wallets group is exempt from the conflict error", () => {
+    const dir = bindingDir("client-a");
+    const r = resolveWallet({ env: { RUN402_WALLET: "personal" }, cwd: dir, cmd: "wallets" });
+    assert.equal(r.name, "personal"); // env still wins; no error
+    rmSync(dir, { recursive: true, force: true });
+  });
+  it("rejects an invalid wallet name", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const { envelope } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: "../evil" }, cwd: dir, cmd: "status" }));
+    assert.equal(envelope.code, "BAD_WALLET_NAME");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("enforceWalletExists — fail closed", () => {
+  it("no-op for default", () => {
+    assert.doesNotThrow(() => enforceWalletExists({ name: "default", source: "default" }, "deploy"));
+  });
+  it("no-op for an existing wallet", () => {
+    ensureProfileDir("client-a");
+    writeFileSync(join(tmp, "profiles", "client-a", "allowance.json"), "{}");
+    assert.doesNotThrow(() => enforceWalletExists({ name: "client-a", source: "binding" }, "deploy"));
+  });
+  it("fails closed for a missing wallet on a normal command", () => {
+    const { envelope, exited } = captureFail(() =>
+      enforceWalletExists({ name: "ghost", source: "binding" }, "deploy"));
+    assert.ok(exited);
+    assert.equal(envelope.code, "WALLET_NOT_FOUND");
+  });
+  it("wallets + init are exempt (create paths)", () => {
+    assert.doesNotThrow(() => enforceWalletExists({ name: "ghost", source: "flag" }, "wallets"));
+    assert.doesNotThrow(() => enforceWalletExists({ name: "ghost", source: "flag" }, "init"));
+  });
+  it("address-looking name hints at billing --wallet-address", () => {
+    const { envelope } = captureFail(() =>
+      enforceWalletExists({ name: "0x" + "a".repeat(40), source: "flag" }, "deploy"));
+    assert.match(envelope.hint, /--wallet-address/);
+  });
+});
+
+describe("emitProvenance", () => {
+  function captureStderr(fn) {
+    const orig = process.stderr.write.bind(process.stderr);
+    let out = "";
+    process.stderr.write = (c) => { out += typeof c === "string" ? c : Buffer.from(c).toString("utf8"); return true; };
+    try { fn(); } finally { process.stderr.write = orig; }
+    return out;
+  }
+  it("stays silent for the default wallet", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "default", source: "default" }, { cmd: "status" })), "");
+  });
+  it("emits a provenance line for a named wallet", () => {
+    ensureProfileDir("kychon");
+    writeFileSync(join(tmp, "profiles", "kychon", "meta.json"), JSON.stringify({ name: "kychon", address: "0x1234567890abcdef" }));
+    const out = captureStderr(() => emitProvenance({ name: "kychon", source: "env", sourceDetail: "RUN402_WALLET" }, { cmd: "status" }));
+    assert.match(out, /wallet: kychon/);
+    assert.match(out, /RUN402_WALLET/);
+  });
+  it("honors --quiet", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "kychon", source: "env" }, { cmd: "status", quiet: true })), "");
+  });
+  it("stays silent for the wallets group", () => {
+    assert.equal(captureStderr(() => emitProvenance({ name: "kychon", source: "flag" }, { cmd: "wallets" })), "");
+  });
+});