Merge pull request #230 from kychee-com/claude/cranky-hamilton-d53ca6

fix: bug triage batch — 14 issues across CLI/core/SDK

Author: MajorTal

cli-e2e.test.mjs

@@ -0,0 +1,119 @@
+/**
+ * cli-env.test.mjs — Subprocess tests for environment-variable validation.
+ *
+ * Bug GH-197: RUN402_API_BASE was previously read with `||` fallback, which
+ * meant an empty string silently used the default and any non-URL/junk value
+ * produced opaque "fetch failed" errors. The fix in `core/src/config.ts` adds
+ * URL validation and a stderr warning for set-but-empty values.
+ *
+ * These tests spawn the CLI as a subprocess so each scenario gets its own
+ * process with a freshly read env, which is what real users hit.
+ *
+ * Run:  node --test cli-env.test.mjs
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { once } from "node:events";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = join(__dirname, "cli", "cli.mjs");
+
+async function runCli(argv, env) {
+  const configDir = mkdtempSync(join(tmpdir(), "run402-env-"));
+  const child = spawn(process.execPath, [CLI_PATH, ...argv], {
+    env: {
+      ...process.env,
+      RUN402_CONFIG_DIR: configDir,
+      HOME: configDir,
+      ...env,
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (d) => { stdout += d.toString(); });
+  child.stderr.on("data", (d) => { stderr += d.toString(); });
+
+  const killTimer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+  const [code] = await once(child, "exit");
+  clearTimeout(killTimer);
+
+  rmSync(configDir, { recursive: true, force: true });
+  return { code, stdout, stderr };
+}
+
+describe("RUN402_API_BASE env-var validation", () => {
+  it("invalid scheme (javascript:) produces clear error mentioning the env var", async () => {
+    const r = await runCli(
+      ["allowance", "status"],
+      { RUN402_API_BASE: "javascript:alert(1)" },
+    );
+    assert.equal(r.code, 1, `expected exit 1, got ${r.code}\nstderr:\n${r.stderr}`);
+    assert.match(r.stderr, /RUN402_API_BASE/,
+      `stderr must mention the env var name; got: ${r.stderr}`);
+    assert.match(r.stderr, /javascript:/,
+      `stderr must mention the bad scheme; got: ${r.stderr}`);
+    // Must NOT be the opaque "fetch failed" or generic Node stack trace.
+    assert.doesNotMatch(r.stderr, /fetch failed/,
+      `stderr must not be the opaque generic error; got: ${r.stderr}`);
+  });
+
+  it("invalid scheme (file:) produces clear error mentioning the env var", async () => {
+    const r = await runCli(
+      ["allowance", "status"],
+      { RUN402_API_BASE: "file:///etc/passwd" },
+    );
+    assert.equal(r.code, 1, `expected exit 1, got ${r.code}\nstderr:\n${r.stderr}`);
+    assert.match(r.stderr, /RUN402_API_BASE/);
+    assert.match(r.stderr, /file:/);
+  });
+
+  it("no scheme (api.run402.com) produces clear error mentioning the env var", async () => {
+    const r = await runCli(
+      ["allowance", "status"],
+      { RUN402_API_BASE: "api.run402.com" },
+    );
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /RUN402_API_BASE/,
+      `must mention env var so the user knows where to look; got: ${r.stderr}`);
+    assert.match(r.stderr, /not a valid URL|http\(s\)/i);
+  });
+
+  it("empty string emits a stderr warning and falls back to default", async () => {
+    // We avoid actually hitting the real production API by checking only that
+    // the warning is on stderr — we also force the command to be one that
+    // exits without making a network call (--help).
+    const r = await runCli(
+      ["allowance", "--help"],
+      { RUN402_API_BASE: "" },
+    );
+    assert.equal(r.code, 0, `--help should exit 0; got ${r.code}\nstderr:\n${r.stderr}`);
+    assert.match(r.stderr, /RUN402_API_BASE/,
+      `expected a warning naming the env var; got stderr: ${r.stderr}`);
+    assert.match(r.stderr, /empty/i);
+  });
+
+  it("valid http://localhost URL is accepted (test/local dev shape)", async () => {
+    // We give the CLI an unreachable localhost port for a command that DOES
+    // try to hit the API (status). The validation should pass (we don't
+    // expect the structured "BAD_ENV" / scheme-validation message), and any
+    // failure must come from the network attempt, not URL validation.
+    const r = await runCli(
+      ["service", "health"],
+      { RUN402_API_BASE: "http://127.0.0.1:1" },
+    );
+    // We don't care what exit code we get from the unreachable port —
+    // we only care that the URL validation didn't reject it.
+    assert.doesNotMatch(r.stderr, /not a valid URL/i,
+      `valid http:// URL must not be rejected; got: ${r.stderr}`);
+    assert.doesNotMatch(r.stderr, /must use http\(s\):/i,
+      `valid http:// URL must not be rejected; got: ${r.stderr}`);
+  });
+});

cli-env.test.mjs

@@ -53,7 +53,7 @@ const MATRIX = {
     shared: ["status", "create", "fund", "balance", "export"],
     specific: ["checkout", "history"],
   },
-  tier: { shared: ["status", "set"], specific: [] },
+  tier: { shared: [], specific: ["status", "set"] },
   projects: {
     shared: [
       "quote", "use", "list", "info", "keys", "rest",
@@ -63,48 +63,49 @@ const MATRIX = {
   },
   deploy: { shared: [], specific: [] },
   functions: {
-    shared: ["list", "delete"],
-    specific: ["deploy", "invoke", "logs", "update"],
+    shared: [],
+    specific: ["deploy", "invoke", "logs", "update", "list", "delete"],
   },
-  secrets: { shared: ["list", "delete"], specific: ["set"] },
+  secrets: { shared: [], specific: ["set", "list", "delete"] },
   blob: {
     shared: [],
     specific: ["put", "get", "ls", "rm", "sign"],
   },
   sites: { shared: ["status"], specific: ["deploy", "deploy-dir"] },
-  subdomains: { shared: ["delete", "list"], specific: ["claim"] },
-  domains: { shared: ["add", "list", "status", "delete"], specific: [] },
+  subdomains: { shared: [], specific: ["claim", "list", "delete"] },
+  domains: { shared: [], specific: ["add", "list", "status", "delete"] },
   apps: {
-    shared: ["versions", "inspect", "delete"],
-    specific: ["browse", "fork", "publish", "update"],
+    shared: [],
+    specific: ["browse", "fork", "publish", "update", "versions", "inspect", "delete"],
   },
-  ai: { shared: ["moderate", "usage"], specific: ["translate"] },
-  image: { shared: ["generate"], specific: [] },
+  ai: { shared: [], specific: ["translate", "moderate", "usage"] },
+  image: { shared: [], specific: ["generate"] },
   email: {
-    shared: ["create", "get"],
-    specific: ["info", "status", "send", "list", "get-raw", "reply", "delete"],
+    shared: [],
+    specific: ["info", "status", "send", "list", "get-raw", "reply", "delete", "create", "get"],
   },
-  message: { shared: ["send"], specific: [] },
+  message: { shared: [], specific: ["send"] },
   auth: {
     shared: [],
     specific: ["magic-link", "verify", "set-password", "settings", "providers"],
   },
   "sender-domain": {
-    shared: ["register", "status", "remove", "inbound-enable", "inbound-disable"],
-    specific: [],
+    shared: [],
+    specific: ["register", "status", "remove", "inbound-enable", "inbound-disable"],
   },
   billing: {
-    shared: ["create-email", "link-wallet", "balance"],
-    specific: ["tier-checkout", "buy-email-pack", "auto-recharge", "history"],
+    shared: [],
+    specific: ["tier-checkout", "buy-email-pack", "auto-recharge", "history", "create-email", "link-wallet", "balance"],
   },
   contracts: {
-    shared: ["get-wallet", "list-wallets", "status"],
+    shared: [],
     specific: [
       "provision-wallet", "set-recovery", "set-alert", "call", "read", "drain", "delete",
+      "get-wallet", "list-wallets", "status",
     ],
   },
-  agent: { shared: ["contact"], specific: [] },
-  service: { shared: ["status", "health"], specific: [] },
+  agent: { shared: [], specific: ["contact"] },
+  service: { shared: [], specific: ["status", "health"] },
 };
 
 // `run402 email webhooks <action>` delegates to lib/webhooks.mjs.
@@ -272,4 +273,81 @@ describe("CLI --help contract", () => {
       });
     }
   });
+
+  // GH-198 — `run402 deploy --help` was showing the v1 bundle manifest format
+  // (top-level `migrations` string, `secrets` array, `functions` array, `files`
+  // array) which the v2 gateway rejects. The example must match the v2
+  // ReleaseSpec shape documented in cli/llms-cli.txt: object trees rooted at
+  // `database`, `site`, `functions.replace`, `secrets.set`, `subdomains`.
+  describe("run402 deploy --help shows v2 manifest format (GH-198)", () => {
+    it("deploy --help example uses v2 keys (database/site/replace), not v1 arrays", async () => {
+      const result = await runCli(["deploy", "--help"]);
+      assertHelp(result, "run402 deploy --help");
+
+      const out = result.stdout;
+
+      // v2 keys must be present in the example block.
+      assert.match(out, /"database":/,
+        `deploy --help: example must contain a top-level "database": key (v2 ReleaseSpec)\nstdout:\n${out}`);
+      assert.match(out, /"site":/,
+        `deploy --help: example must contain a top-level "site": key (v2 ReleaseSpec)\nstdout:\n${out}`);
+      assert.match(out, /"replace":/,
+        `deploy --help: example must contain a "replace": key (v2 site/functions shape)\nstdout:\n${out}`);
+      assert.match(out, /"set":/,
+        `deploy --help: example must contain a "set": key (v2 secrets/subdomains shape)\nstdout:\n${out}`);
+      assert.match(out, /"subdomains":/,
+        `deploy --help: example must contain a "subdomains": key (v2 ReleaseSpec)\nstdout:\n${out}`);
+
+      // v1 shapes that are NOT accepted by the v2 gateway must be gone.
+      // - top-level `"migrations":` as a string (v1) — v2 nests under database.migrations as an array of {id, sql}
+      assert.doesNotMatch(out, /^\s*"migrations":\s*"/m,
+        `deploy --help: example must not have v1 top-level "migrations": "<string>" (use database.migrations: [{id, sql}])\nstdout:\n${out}`);
+      // - top-level `"files":` as an array (v1) — v2 uses site.replace as an object map
+      assert.doesNotMatch(out, /^\s*"files":\s*\[/m,
+        `deploy --help: example must not have v1 top-level "files": [...] array (use site.replace: { "<path>": {...} })\nstdout:\n${out}`);
+      // - top-level `"secrets":` as an array (v1) — v2 uses secrets.set as an object map
+      assert.doesNotMatch(out, /^\s*"secrets":\s*\[/m,
+        `deploy --help: example must not have v1 top-level "secrets": [...] array (use secrets.set: { "<KEY>": {...} })\nstdout:\n${out}`);
+      // - top-level `"functions":` as an array (v1) — v2 uses functions.replace as an object map
+      assert.doesNotMatch(out, /^\s*"functions":\s*\[/m,
+        `deploy --help: example must not have v1 top-level "functions": [...] array (use functions.replace: { "<name>": {...} })\nstdout:\n${out}`);
+      // - top-level `"subdomain":` (singular, v1) — v2 uses `subdomains.set: ["..."]`
+      assert.doesNotMatch(out, /^\s*"subdomain":/m,
+        `deploy --help: example must not have v1 top-level "subdomain" (singular); use "subdomains": { "set": [...] }\nstdout:\n${out}`);
+    });
+  });
+
+  // Regression test for GH-188: confirm the previously-broken subcommands now
+  // print their own per-subcommand help instead of falling back to the parent
+  // namespace's help page. The MATRIX above also covers these (each one moved
+  // from `shared` to `specific`), but this explicit suite spot-checks a
+  // representative sample across namespaces and asserts both that the
+  // subcommand-specific title is present AND that the parent's general
+  // "Manage ..." headline is NOT.
+  describe("GH-188 regression — SUB_HELP entries for previously-broken subs", () => {
+    const cases = [
+      // [command sequence, parent-help heading that should NOT appear]
+      [["secrets", "list"],            "run402 secrets — Manage project secrets"],
+      [["functions", "list"],          "run402 functions — Manage serverless functions"],
+      [["domains", "list"],            "run402 domains — Manage custom domains"],
+      [["ai", "moderate"],             "run402 ai — AI translation and moderation tools"],
+      [["tier", "status"],             "run402 tier — Manage your Run402 tier subscription"],
+      [["service", "status"],          "run402 service — Run402 service health and availability"],
+      [["sender-domain", "register"],  "run402 sender-domain — Manage custom email sender domain"],
+      [["contracts", "get-wallet"],    "run402 contracts — KMS-backed Ethereum wallets"],
+    ];
+    for (const [argv, parentHeading] of cases) {
+      it(`run402 ${argv.join(" ")} --help shows per-subcommand title`, async () => {
+        const result = await runCli([...argv, "--help"]);
+        const expectedHeading = `run402 ${argv.join(" ")}`;
+        assertHelp(result, `run402 ${argv.join(" ")} --help`, {
+          expectHeadingStartsWith: expectedHeading,
+        });
+        // Belt-and-suspenders: parent-only headline must NOT be the first line.
+        const firstLine = result.stdout.trimStart().split(/\r?\n/, 1)[0];
+        assert.ok(!firstLine.startsWith(parentHeading.split(" — ")[0] + " —"),
+          `run402 ${argv.join(" ")} --help fell through to parent help: first line was "${firstLine}"`);
+      });
+    }
+  });
 });

cli-help.test.mjs

@@ -74,6 +74,23 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   process.exit(0);
 }
 
+try {
+  await dispatch();
+} catch (err) {
+  // Surface env/config errors (e.g. invalid RUN402_API_BASE) as a clean
+  // JSON envelope on stderr instead of a raw stack trace. We import the
+  // helper lazily so a broken env doesn't fail this catch handler too.
+  const { fail } = await import("./lib/sdk-errors.mjs");
+  fail({
+    code: "BAD_ENV",
+    message: err && err.message ? err.message : String(err),
+    hint: typeof err?.message === "string" && err.message.includes("RUN402_API_BASE")
+      ? "Check the RUN402_API_BASE env var."
+      : undefined,
+  });
+}
+
+async function dispatch() {
 switch (cmd) {
   case "init": {
     const { run } = await import("./lib/init.mjs");
@@ -200,3 +217,4 @@ switch (cmd) {
     console.log(HELP);
     process.exit(1);
 }
+}

cli/cli.mjs

@@ -1,6 +1,7 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { validateWebhookUrl } from "./argparse.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
@@ -17,6 +18,29 @@ Examples:
   run402 agent contact --name my-agent --email ops@example.com --webhook https://example.com/hook
 `;
 
+const SUB_HELP = {
+  contact: `run402 agent contact — Register agent contact info
+
+Usage:
+  run402 agent contact --name <name> [--email <email>] [--webhook <url>]
+
+Options:
+  --name <name>       Required: agent name (e.g. "my-agent")
+  --email <email>     Optional: contact email address
+  --webhook <url>     Optional: webhook URL Run402 can call to reach the
+                      agent
+
+Notes:
+  - Free with allowance auth (run an 'allowance create' first)
+  - Registers contact info so Run402 can reach your agent
+
+Examples:
+  run402 agent contact --name my-agent
+  run402 agent contact --name my-agent --email ops@example.com \\
+    --webhook https://example.com/hook
+`,
+};
+
 async function contact(args) {
   let name = null, email = null, webhook = null;
   for (let i = 0; i < args.length; i++) {
@@ -27,6 +51,10 @@ async function contact(args) {
   if (!name) {
     fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
   }
+  // GH-192: validate webhook scheme locally BEFORE the allowance check so
+  // bad URLs fail fast even without an allowance configured. No-op when
+  // --webhook is omitted (it's optional).
+  validateWebhookUrl(webhook, "--webhook");
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/agent/v1/contact");
 
@@ -45,7 +73,7 @@ async function contact(args) {
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   if (sub !== "contact") {