run402 1.54.2 → 1.54.4

package/cli.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);
 }
+}

package/core-dist/allowance-auth.js

@@ -87,6 +87,11 @@ export function formatSIWEMessage(opts, address) {
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
 export function getAllowanceAuthHeaders(path, allowancePath) {
+    // GH-194: readAllowance throws on a malformed-shape allowance file. The
+    // CLI's higher-level readAllowance wrapper surfaces this as a structured
+    // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
+    // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
+    // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
     const allowance = readAllowance(allowancePath);
     if (!allowance || !allowance.address || !allowance.privateKey)
         return null;

package/core-dist/allowance.js

@@ -2,16 +2,64 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSy
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getAllowancePath } from "./config.js";
+// 0x-prefixed 40-hex EVM address.
+const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+// 0x-prefixed 64-hex secp256k1 private key (32 bytes).
+const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
+/**
+ * Load the agent allowance from disk.
+ *
+ * Returns `null` for the two "no allowance configured" cases:
+ *   - the file does not exist
+ *   - the file exists but is not parseable JSON (preserve existing UX —
+ *     consumers print "no_allowance" and tell the user to run init)
+ *
+ * Throws a structured `Error` (GH-194) when the file parses as JSON but the
+ * shape is wrong (missing/wrong-type/wrong-length fields). Without this guard
+ * downstream callers crash with raw stack traces:
+ *   - `cli/lib/status.mjs` reaches for `allowance.address.toLowerCase()`
+ *     and crashes with `TypeError: Cannot read properties of undefined`.
+ *   - `core/src/allowance-auth.ts` passes a malformed `privateKey` to
+ *     `@noble/curves` which throws "expected 32 bytes, got N".
+ *
+ * The CLI's `cli/lib/config.mjs:readAllowance()` wrapper and the MCP
+ * `src/tools/{status,init}.ts` callers translate the throw into their own
+ * structured envelopes (`code: BAD_ALLOWANCE_FILE`).
+ */
 export function readAllowance(path) {
     const p = path ?? getAllowancePath();
     if (!existsSync(p))
         return null;
+    let raw;
     try {
-        return JSON.parse(readFileSync(p, "utf-8"));
+        raw = readFileSync(p, "utf-8");
     }
     catch {
         return null;
     }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Preserve historical UX — completely unparseable input reads as "no
+        // allowance configured" rather than as an error. Consumers already handle
+        // null with a friendly "run 'run402 init'" message.
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`allowance.json must contain a JSON object (got ${Array.isArray(parsed) ? "array" : parsed === null ? "null" : typeof parsed}). Back up the file and run 'run402 init' to recreate it.`);
+    }
+    const data = parsed;
+    if (typeof data.address !== "string" || !ADDRESS_RE.test(data.address)) {
+        throw new Error("allowance.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
+            "Back up the file and run 'run402 init' to recreate it.");
+    }
+    if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
+        throw new Error("allowance.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
+            "Back up the file and run 'run402 init' to recreate it.");
+    }
+    return data;
 }
 export function saveAllowance(data, path) {
     const p = path ?? getAllowancePath();

package/core-dist/config.js

@@ -1,8 +1,39 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { existsSync, renameSync, mkdirSync } from "node:fs";
+const DEFAULT_API_BASE = "https://api.run402.com";
+/**
+ * Validate a user-supplied API base URL. Throws a clear error message that
+ * names the env var when the URL is malformed or uses a scheme other than
+ * http(s). Empty string is treated as "set but empty" (almost always a
+ * templating mishap) and emits a stderr warning before falling back to
+ * `fallback`.
+ *
+ * Returns the validated URL string (unchanged) or `null` if the env var was
+ * unset.
+ */
+function validateApiBase(envVar, raw, fallback) {
+    if (raw == null)
+        return null;
+    if (raw === "") {
+        process.stderr.write(`warning: ${envVar} is set but empty - using default. Unset the env var to suppress this warning.\n`);
+        return fallback;
+    }
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new Error(`${envVar} is not a valid URL: ${JSON.stringify(raw)}. Expected an http(s) URL like https://api.run402.com.`);
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+        throw new Error(`${envVar} must use http(s):, got ${u.protocol} (full value: ${JSON.stringify(raw)}).`);
+    }
+    return raw;
+}
 export function getApiBase() {
-    return process.env.RUN402_API_BASE || "https://api.run402.com";
+    const validated = validateApiBase("RUN402_API_BASE", process.env.RUN402_API_BASE, DEFAULT_API_BASE);
+    return validated ?? DEFAULT_API_BASE;
 }
 /**
  * API base for the deploy-v2 routes. Defaults to the same value as
@@ -12,7 +43,9 @@ export function getApiBase() {
  * should not need this override.
  */
 export function getDeployApiBase() {
-    return process.env.RUN402_DEPLOY_API_BASE || getApiBase();
+    const fallback = getApiBase();
+    const validated = validateApiBase("RUN402_DEPLOY_API_BASE", process.env.RUN402_DEPLOY_API_BASE, fallback);
+    return validated ?? fallback;
 }
 export function getConfigDir() {
     return process.env.RUN402_CONFIG_DIR || join(homedir(), ".config", "run402");

package/core-dist/wallet-auth.js

@@ -0,0 +1,62 @@
+/**
+ * Wallet auth helper — generates EIP-191 signature headers for Run402 API.
+ * Uses @noble/curves (lighter than viem) for signing.
+ */
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+import { readWallet } from "./wallet.js";
+/**
+ * EIP-191 personal_sign: sign a message with the wallet's private key.
+ */
+function personalSign(privateKeyHex, address, message) {
+    const msgBytes = new TextEncoder().encode(message);
+    const prefix = new TextEncoder().encode(`\x19Ethereum Signed Message:\n${msgBytes.length}`);
+    const prefixed = new Uint8Array(prefix.length + msgBytes.length);
+    prefixed.set(prefix);
+    prefixed.set(msgBytes, prefix.length);
+    const hash = keccak_256(prefixed);
+    const pkHex = privateKeyHex.startsWith("0x")
+        ? privateKeyHex.slice(2)
+        : privateKeyHex;
+    const pkBytes = Uint8Array.from(Buffer.from(pkHex, "hex"));
+    const rawSig = secp256k1.sign(hash, pkBytes);
+    const sig = secp256k1.Signature.fromBytes(rawSig);
+    // Determine recovery bit by trying both and matching the address
+    let recovery = 0;
+    for (const v of [0, 1]) {
+        try {
+            const recovered = sig.addRecoveryBit(v).recoverPublicKey(hash);
+            const pubBytes = recovered.toBytes(false).slice(1); // uncompressed, drop 04 prefix
+            const addrBytes = keccak_256(pubBytes).slice(-20);
+            if ("0x" + bytesToHex(addrBytes) === address.toLowerCase()) {
+                recovery = v;
+                break;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    const r = sig.r.toString(16).padStart(64, "0");
+    const s = sig.s.toString(16).padStart(64, "0");
+    const vHex = (recovery + 27).toString(16).padStart(2, "0");
+    return "0x" + r + s + vHex;
+}
+/**
+ * Get wallet auth headers for the Run402 API.
+ * Returns null if no wallet is configured.
+ */
+export function getWalletAuthHeaders(walletPath) {
+    const wallet = readWallet(walletPath);
+    if (!wallet || !wallet.address || !wallet.privateKey)
+        return null;
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const signature = personalSign(wallet.privateKey, wallet.address, `run402:${timestamp}`);
+    return {
+        "X-Run402-Wallet": wallet.address,
+        "X-Run402-Signature": signature,
+        "X-Run402-Timestamp": timestamp,
+    };
+}
+//# sourceMappingURL=wallet-auth.js.map

package/core-dist/wallet.js

@@ -0,0 +1,25 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getWalletPath } from "./config.js";
+export function readWallet(path) {
+    const p = path ?? getWalletPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveWallet(data, path) {
+    const p = path ?? getWalletPath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.wallet.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+//# sourceMappingURL=wallet.js.map

package/lib/agent.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") {

package/lib/ai.mjs

@@ -1,6 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { resolvePositionalProject } from "./argparse.mjs";
 
 const HELP = `run402 ai — AI translation and moderation tools
 
@@ -8,17 +9,23 @@ Usage:
   run402 ai <subcommand> [args...]
 
 Subcommands:
-  translate <project_id> <text> --to <lang> [--from <lang>] [--context <hint>]
-  moderate  <project_id> <text>
-  usage     <project_id>
+  translate [project_id] <text> --to <lang> [--from <lang>] [--context <hint>]
+  moderate  [project_id] <text>
+  usage     [project_id]
 
 Examples:
+  run402 ai translate "Hello world" --to es                  # uses active project
   run402 ai translate prj_abc123 "Hello world" --to es
   run402 ai translate prj_abc123 "Hello" --to ja --from en --context "formal business email"
+  run402 ai moderate "content to check"                      # uses active project
   run402 ai moderate prj_abc123 "content to check"
+  run402 ai usage                                            # uses active project
   run402 ai usage prj_abc123
 
 Notes:
+  - [project_id] defaults to the active project when omitted (set with
+    'run402 projects use <id>'). Project IDs start with 'prj_'; any first
+    positional that doesn't is treated as the next argument instead.
   - translate requires the AI Translation add-on on the project
   - moderate is free for all projects
   - usage shows translation word quota for the current billing period
@@ -28,25 +35,71 @@ const SUB_HELP = {
   translate: `run402 ai translate — Translate text to another language
 
 Usage:
-  run402 ai translate <project_id> <text> --to <lang> [--from <lang>] [--context <hint>]
+  run402 ai translate [project_id] <text> --to <lang> [--from <lang>] [--context <hint>]
 
 Arguments:
-  <project_id>        Project ID (defaults to the active project if omitted)
+  [project_id]        Project ID (defaults to the active project if omitted).
+                      Project IDs start with 'prj_'; any first positional that
+                      doesn't is treated as the <text> argument instead.
   <text>              Text to translate (quote it to preserve spaces)
 
 Options:
   --to <lang>         Target language code (required, e.g. es, ja, fr)
   --from <lang>       Source language code (optional; auto-detected if omitted)
   --context <hint>    Optional translation hint (e.g. "formal business email")
+  --project <id>      Project ID (alternative to the positional argument)
 
 Notes:
   - Requires the AI Translation add-on on the project
   - Counts against the project's translation word quota
 
 Examples:
+  run402 ai translate "Hello world" --to es                  # uses active project
   run402 ai translate prj_abc123 "Hello world" --to es
   run402 ai translate prj_abc123 "Hello" --to ja --from en \\
     --context "formal business email"
+`,
+  moderate: `run402 ai moderate — Run content moderation on text
+
+Usage:
+  run402 ai moderate [project_id] <text>
+
+Arguments:
+  [project_id]        Project ID (defaults to the active project if omitted).
+                      Project IDs start with 'prj_'; any first positional that
+                      doesn't is treated as the <text> argument instead.
+  <text>              Text to check (quote it to preserve spaces)
+
+Options:
+  --project <id>      Project ID (alternative to the positional argument)
+
+Notes:
+  - Free for all projects; uses the project's service key
+  - Returns a JSON object with 'flagged' (boolean), 'categories' and 'category_scores'
+
+Examples:
+  run402 ai moderate "content to check"          # uses active project
+  run402 ai moderate prj_abc123 "content to check"
+`,
+  usage: `run402 ai usage — Show AI translation word usage for the current billing cycle
+
+Usage:
+  run402 ai usage [project_id]
+
+Arguments:
+  [project_id]        Project ID (defaults to the active project if omitted).
+                      Must start with 'prj_'; any other first positional is an error.
+
+Options:
+  --project <id>      Project ID (alternative to the positional argument)
+
+Notes:
+  - Reports translation word quota and usage; only meaningful with the
+    AI Translation add-on enabled on the project.
+
+Examples:
+  run402 ai usage                  # uses active project
+  run402 ai usage prj_abc123
 `,
 };
 
@@ -57,20 +110,34 @@ function parseFlag(args, flag) {
   return null;
 }
 
+// translate has value-bearing flags (--to, --from, --context, --project) that
+// must not be mistaken for positional bare args when prefix-matching.
+const TRANSLATE_VALUE_FLAGS = ["--to", "--from", "--context", "--project"];
+
 async function translate(args) {
-  let projectOpt = null;
-  let text = null;
-  const positional = [];
-  let i = 0;
-  while (i < args.length) {
-    if (args[i] === "--project" && args[i + 1]) { projectOpt = args[++i]; }
-    else if (args[i] === "--to" || args[i] === "--from" || args[i] === "--context") { i++; }
-    else if (!args[i].startsWith("--")) { positional.push(args[i]); }
-    i++;
+  // --project <id> wins over positional, mirroring previous behavior.
+  const projectOpt = parseFlag(args, "--project");
+  let projectId;
+  let rest;
+  if (projectOpt) {
+    projectId = resolveProjectId(projectOpt);
+    rest = args;
+  } else {
+    ({ projectId, rest } = resolvePositionalProject(args, {
+      valueFlags: TRANSLATE_VALUE_FLAGS,
+    }));
   }
 
-  const projectId = resolveProjectId(projectOpt || positional[0]);
-  text = positional[1] || null;
+  // Walk `rest` as the post-project argv, collecting bare positionals while
+  // skipping value-flag pairs. The first bare positional becomes <text>.
+  let text = null;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (TRANSLATE_VALUE_FLAGS.includes(arg)) { i++; continue; }
+    if (typeof arg === "string" && arg.startsWith("--")) continue;
+    text = arg;
+    break;
+  }
 
   const to = parseFlag(args, "--to");
   const from = parseFlag(args, "--from");
@@ -80,7 +147,7 @@ async function translate(args) {
     fail({
       code: "BAD_USAGE",
       message: "Text required.",
-      hint: "run402 ai translate <project_id> <text> --to <lang>",
+      hint: "run402 ai translate [project_id] <text> --to <lang>",
     });
   }
   if (!to) {
@@ -95,25 +162,35 @@ async function translate(args) {
   }
 }
 
+const MODERATE_VALUE_FLAGS = ["--project"];
+
 async function moderate(args) {
-  let projectOpt = null;
-  let text = null;
-  const positional = [];
-  let i = 0;
-  while (i < args.length) {
-    if (args[i] === "--project" && args[i + 1]) { projectOpt = args[++i]; }
-    else if (!args[i].startsWith("--")) { positional.push(args[i]); }
-    i++;
+  const projectOpt = parseFlag(args, "--project");
+  let projectId;
+  let rest;
+  if (projectOpt) {
+    projectId = resolveProjectId(projectOpt);
+    rest = args;
+  } else {
+    ({ projectId, rest } = resolvePositionalProject(args, {
+      valueFlags: MODERATE_VALUE_FLAGS,
+    }));
   }
 
-  const projectId = resolveProjectId(projectOpt || positional[0]);
-  text = positional[1] || null;
+  let text = null;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (MODERATE_VALUE_FLAGS.includes(arg)) { i++; continue; }
+    if (typeof arg === "string" && arg.startsWith("--")) continue;
+    text = arg;
+    break;
+  }
 
   if (!text) {
     fail({
       code: "BAD_USAGE",
       message: "Text required.",
-      hint: "run402 ai moderate <project_id> <text>",
+      hint: "run402 ai moderate [project_id] <text>",
     });
   }
 
@@ -126,17 +203,16 @@ async function moderate(args) {
 }
 
 async function usage(args) {
-  let projectOpt = null;
-  const positional = [];
-  let i = 0;
-  while (i < args.length) {
-    if (args[i] === "--project" && args[i + 1]) { projectOpt = args[++i]; }
-    else if (!args[i].startsWith("--")) { positional.push(args[i]); }
-    i++;
+  const projectOpt = parseFlag(args, "--project");
+  let projectId;
+  if (projectOpt) {
+    projectId = resolveProjectId(projectOpt);
+  } else {
+    // No bare-text positional is meaningful here, so reject any non-prj first
+    // positional with a clear error.
+    ({ projectId } = resolvePositionalProject(args, { rejectBareFirst: true }));
   }
 
-  const projectId = resolveProjectId(projectOpt || positional[0]);
-
   try {
     const data = await getSdk().ai.usage(projectId);
     console.log(JSON.stringify({ status: "ok", ...data }));

package/lib/apps.mjs

@@ -99,6 +99,40 @@ Examples:
   run402 apps update prj_abc123 ver_abc123 --description "Updated"
   run402 apps update prj_abc123 ver_abc123 --tags todo,auth --fork-allowed
   run402 apps update prj_abc123 ver_abc123 --no-fork
+`,
+  inspect: `run402 apps inspect — Inspect a published app version
+
+Usage:
+  run402 apps inspect <version_id>
+
+Arguments:
+  <version_id>        Published version ID (e.g. ver_abc123)
+
+Examples:
+  run402 apps inspect ver_abc123
+`,
+  versions: `run402 apps versions — List published versions of a project
+
+Usage:
+  run402 apps versions <id>
+
+Arguments:
+  <id>                Project ID (e.g. prj_abc123)
+
+Examples:
+  run402 apps versions prj_abc123
+`,
+  delete: `run402 apps delete — Delete a published version
+
+Usage:
+  run402 apps delete <project_id> <version_id>
+
+Arguments:
+  <project_id>        Project ID that owns the version
+  <version_id>        Published version ID to delete
+
+Examples:
+  run402 apps delete prj_abc123 ver_abc123
 `,
 };