run402 1.54.0 → 1.54.2

package/lib/domains.mjs

@@ -1,6 +1,6 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 domains — Manage custom domains
 
@@ -40,7 +40,13 @@ async function add(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest[0];
   const subdomainName = rest[1];
-  if (!domain || !subdomainName) { console.error("Usage: run402 domains add <domain> <subdomain_name> [--project <id>]"); process.exit(1); }
+  if (!domain || !subdomainName) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain> and/or <subdomain_name>.",
+      hint: "run402 domains add <domain> <subdomain_name> [--project <id>]",
+    });
+  }
   const projectId = resolveProjectId(project);
   try {
     const data = await getSdk().domains.add(projectId, domain, subdomainName);
@@ -63,7 +69,13 @@ async function list(projectIdArg) {
 async function status(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest[0];
-  if (!domain) { console.error("Usage: run402 domains status <domain> [--project <id>]"); process.exit(1); }
+  if (!domain) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain>.",
+      hint: "run402 domains status <domain> [--project <id>]",
+    });
+  }
   const projectId = resolveProjectId(project);
   try {
     const data = await getSdk().domains.status(projectId, domain);
@@ -76,15 +88,19 @@ async function status(args) {
 async function deleteDomain(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest.find((a) => !a.startsWith("--"));
-  if (!domain) { console.error("Usage: run402 domains delete <domain> --confirm [--project <id>]"); process.exit(1); }
+  if (!domain) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain>.",
+      hint: "run402 domains delete <domain> --confirm [--project <id>]",
+    });
+  }
   if (!Array.isArray(args) || !args.includes("--confirm")) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
       code: "CONFIRMATION_REQUIRED",
       message: `Destructive: releasing custom domain '${domain}' detaches it from this project and clears its DNS/SSL configuration. This is irreversible. Re-run with --confirm to proceed.`,
       details: { domain },
-    }));
-    process.exit(1);
+    });
   }
   const projectId = resolveProjectId(project);
   try {

package/lib/email.mjs

@@ -1,6 +1,6 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 
 const HELP = `run402 email — Send emails from your project
 
@@ -130,14 +130,12 @@ function parseVars(args) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--vars" && args[i + 1]) {
       const raw = args[++i];
-      let parsed;
-      try { parsed = JSON.parse(raw); } catch {
-        console.error(JSON.stringify({ status: "error", message: "Invalid JSON for --vars. Expected a JSON object, e.g. '{\"key\":\"value\"}'" }));
-        process.exit(1);
-      }
+      const parsed = parseFlagJson("--vars", raw);
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        console.error(JSON.stringify({ status: "error", message: "--vars must be a JSON object, e.g. '{\"key\":\"value\"}'" }));
-        process.exit(1);
+        fail({
+          code: "BAD_USAGE",
+          message: "--vars must be a JSON object, e.g. '{\"key\":\"value\"}'",
+        });
       }
       for (const [k, v] of Object.entries(parsed)) vars[k] = typeof v === "string" ? v : String(v);
     }
@@ -161,8 +159,11 @@ async function create(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!slug) {
-    console.error(JSON.stringify({ status: "error", message: "Missing slug. Usage: run402 email create <slug>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing slug.",
+      hint: "run402 email create <slug>",
+    });
   }
 
   try {
@@ -184,8 +185,7 @@ async function send(args) {
   const variables = parseVars(args);
 
   if (!to) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --to <email>" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Missing --to <email>" });
   }
 
   try {
@@ -228,8 +228,11 @@ async function get(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email get <message_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: "run402 email get <message_id>",
+    });
   }
   try {
     const data = await getSdk().email.get(projectId, messageId);
@@ -250,8 +253,11 @@ async function getRaw(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email get-raw <message_id> [--output <file>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: "run402 email get-raw <message_id> [--output <file>]",
+    });
   }
 
   try {
@@ -286,12 +292,17 @@ async function reply(args) {
   const projectId = resolveProjectId(projectOpt);
 
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email reply <message_id> --html \"...\"" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: 'run402 email reply <message_id> --html "..."',
+    });
   }
   if (!html && !text) {
-    console.error(JSON.stringify({ status: "error", message: "Provide --html and/or --text for the reply body" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide --html and/or --text for the reply body",
+    });
   }
 
   try {
@@ -299,12 +310,11 @@ async function reply(args) {
     const original = await getSdk().email.get(projectId, messageId);
     const replyTo = original.from || original.from_address || original.sender || null;
     if (!replyTo) {
-      console.error(JSON.stringify({
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: "Original message has no from address to reply to",
-        original_keys: Object.keys(original),
-      }));
-      process.exit(1);
+        details: { original_keys: Object.keys(original) },
+      });
     }
     const origSubject = typeof original.subject === "string" ? original.subject : "";
     const defaultSubject = origSubject && origSubject.toLowerCase().startsWith("re:")
@@ -339,11 +349,10 @@ async function deleteMailbox(args) {
   const confirmed = args.includes("--confirm");
 
   if (!confirmed) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "CONFIRMATION_REQUIRED",
       message: "Destructive: deleting a mailbox is irreversible (drops all messages and webhook subscriptions). Re-run with --confirm to proceed.",
-    }));
-    process.exit(1);
+    });
   }
 
   try {

package/lib/functions.mjs

@@ -1,7 +1,8 @@
 import { readFileSync } from "fs";
 import { findProject, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag } from "./argparse.mjs";
 
 const HELP = `run402 functions — Manage serverless functions
 
@@ -21,18 +22,18 @@ Subcommands:
   delete <id> <name>                   Delete a function
 
 Examples:
-  run402 functions deploy abc123 stripe-webhook --file handler.ts
-  run402 functions deploy abc123 send-reminders --file remind.ts --schedule '*/15 * * * *'
-  run402 functions deploy abc123 send-reminders --file remind.ts --schedule ''   # remove schedule
-  run402 functions invoke abc123 stripe-webhook --body '{"event":"test"}'
-  run402 functions logs abc123 stripe-webhook --tail 100
-  run402 functions logs abc123 stripe-webhook --since 2026-03-29T14:00:00Z
-  run402 functions logs abc123 stripe-webhook --follow
-  run402 functions update abc123 send-reminders --schedule '0 */4 * * *'
-  run402 functions update abc123 send-reminders --schedule-remove
-  run402 functions update abc123 my-func --timeout 15 --memory 256
-  run402 functions list abc123
-  run402 functions delete abc123 stripe-webhook
+  run402 functions deploy prj_abc123 stripe-webhook --file handler.ts
+  run402 functions deploy prj_abc123 send-reminders --file remind.ts --schedule '*/15 * * * *'
+  run402 functions deploy prj_abc123 send-reminders --file remind.ts --schedule ''   # remove schedule
+  run402 functions invoke prj_abc123 stripe-webhook --body '{"event":"test"}'
+  run402 functions logs prj_abc123 stripe-webhook --tail 100
+  run402 functions logs prj_abc123 stripe-webhook --since 2026-03-29T14:00:00Z
+  run402 functions logs prj_abc123 stripe-webhook --follow
+  run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
+  run402 functions update prj_abc123 send-reminders --schedule-remove
+  run402 functions update prj_abc123 my-func --timeout 15 --memory 256
+  run402 functions list prj_abc123
+  run402 functions delete prj_abc123 stripe-webhook
 
 Notes:
   - Code must export a default async function: export default async (req: Request) => Response
@@ -77,10 +78,10 @@ Notes:
     notes such as bundle-size advisories
 
 Examples:
-  run402 functions deploy abc123 stripe-webhook --file handler.ts
-  run402 functions deploy abc123 send-reminders --file remind.ts \\
+  run402 functions deploy prj_abc123 stripe-webhook --file handler.ts
+  run402 functions deploy prj_abc123 send-reminders --file remind.ts \\
     --schedule '*/15 * * * *'
-  run402 functions deploy abc123 send-reminders --file remind.ts --schedule ''
+  run402 functions deploy prj_abc123 send-reminders --file remind.ts --schedule ''
 `,
   invoke: `run402 functions invoke — Invoke a deployed function
 
@@ -96,8 +97,8 @@ Options:
   --body <json>       Request body (ignored for GET/HEAD)
 
 Examples:
-  run402 functions invoke abc123 stripe-webhook --body '{"event":"test"}'
-  run402 functions invoke abc123 ping --method GET
+  run402 functions invoke prj_abc123 stripe-webhook --body '{"event":"test"}'
+  run402 functions invoke prj_abc123 ping --method GET
 `,
   logs: `run402 functions logs — Fetch or tail function logs
 
@@ -114,9 +115,9 @@ Options:
   --follow            Poll every 3s and stream new entries (Ctrl-C to stop)
 
 Examples:
-  run402 functions logs abc123 stripe-webhook --tail 100
-  run402 functions logs abc123 stripe-webhook --since 2026-03-29T14:00:00Z
-  run402 functions logs abc123 stripe-webhook --follow
+  run402 functions logs prj_abc123 stripe-webhook --tail 100
+  run402 functions logs prj_abc123 stripe-webhook --since 2026-03-29T14:00:00Z
+  run402 functions logs prj_abc123 stripe-webhook --follow
 `,
   update: `run402 functions update — Update function config without re-deploying
 
@@ -137,22 +138,26 @@ Notes:
   Must provide at least one of the options above.
 
 Examples:
-  run402 functions update abc123 send-reminders --schedule '0 */4 * * *'
-  run402 functions update abc123 send-reminders --schedule-remove
-  run402 functions update abc123 my-func --timeout 15 --memory 256
+  run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
+  run402 functions update prj_abc123 send-reminders --schedule-remove
+  run402 functions update prj_abc123 my-func --timeout 15 --memory 256
 `,
 };
 
 async function deploy(projectId, name, args) {
+  assertRequiredProjectAndName(projectId, name, "run402 functions deploy <project_id> <name> --file <file>");
+  assertKnownFlags(args, ["--file", "--timeout", "--memory", "--deps", "--schedule", "--help", "-h"], ["--file", "--timeout", "--memory", "--deps", "--schedule"]);
   const opts = { file: null, timeout: undefined, memory: undefined, deps: undefined, schedule: undefined };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--file" && args[i + 1]) opts.file = args[++i];
-    if (args[i] === "--timeout" && args[i + 1]) opts.timeout = parseInt(args[++i]);
-    if (args[i] === "--memory" && args[i + 1]) opts.memory = parseInt(args[++i]);
+    if (args[i] === "--timeout") opts.timeout = parseIntegerFlag("--timeout", args[++i], { min: 1 });
+    if (args[i] === "--memory") opts.memory = parseIntegerFlag("--memory", args[++i], { min: 1 });
     if (args[i] === "--deps" && args[i + 1]) opts.deps = args[++i].split(",");
     if (args[i] === "--schedule" && i + 1 < args.length) opts.schedule = args[++i];
   }
-  if (!opts.file) { console.error(JSON.stringify({ status: "error", message: "Missing --file <file>" })); process.exit(1); }
+  if (!opts.file) {
+    fail({ code: "BAD_USAGE", message: "Missing --file <file>" });
+  }
   const code = readFileSync(opts.file, "utf-8");
 
   const deployOpts = { name, code };
@@ -173,6 +178,8 @@ async function deploy(projectId, name, args) {
 }
 
 async function invoke(projectId, name, args) {
+  assertRequiredProjectAndName(projectId, name, "run402 functions invoke <project_id> <name> [--method <M>] [--body <json>]");
+  assertKnownFlags(args, ["--method", "--body", "--help", "-h"], ["--method", "--body"]);
   const opts = { method: "POST", body: undefined };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--method" && args[i + 1]) opts.method = args[++i];
@@ -196,11 +203,13 @@ async function invoke(projectId, name, args) {
 }
 
 async function logs(projectId, name, args) {
+  assertRequiredProjectAndName(projectId, name, "run402 functions logs <project_id> <name> [--tail <n>]");
+  assertKnownFlags(args, ["--tail", "--since", "--follow", "--help", "-h"], ["--tail", "--since"]);
   let tail = 50;
   let since = undefined;
   let follow = false;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--tail" && args[i + 1]) tail = parseInt(args[++i]);
+    if (args[i] === "--tail") tail = parseIntegerFlag("--tail", args[++i], { min: 1 });
     if (args[i] === "--since" && args[i + 1]) since = args[++i];
     if (args[i] === "--follow") follow = true;
   }
@@ -212,7 +221,13 @@ async function logs(projectId, name, args) {
   if (since !== undefined) {
     const parsed = Number(since);
     const ms = Number.isNaN(parsed) ? new Date(since).getTime() : parsed;
-    if (Number.isNaN(ms)) { console.error(JSON.stringify({ status: "error", message: `Invalid --since value: ${since}` })); process.exit(1); }
+    if (Number.isNaN(ms)) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Invalid --since value: ${since}`,
+        details: { flag: "--since", value: since },
+      });
+    }
     sinceIso = new Date(ms).toISOString();
   }
 
@@ -261,6 +276,8 @@ async function logs(projectId, name, args) {
 }
 
 async function update(projectId, name, args) {
+  assertRequiredProjectAndName(projectId, name, "run402 functions update <project_id> <name> [options]");
+  assertKnownFlags(args, ["--schedule", "--schedule-remove", "--timeout", "--memory", "--help", "-h"], ["--schedule", "--timeout", "--memory"]);
   let schedule = undefined;
   let scheduleRemove = false;
   let timeout = undefined;
@@ -268,8 +285,8 @@ async function update(projectId, name, args) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--schedule" && i + 1 < args.length) schedule = args[++i];
     if (args[i] === "--schedule-remove") scheduleRemove = true;
-    if (args[i] === "--timeout" && args[i + 1]) timeout = parseInt(args[++i]);
-    if (args[i] === "--memory" && args[i + 1]) memory = parseInt(args[++i]);
+    if (args[i] === "--timeout") timeout = parseIntegerFlag("--timeout", args[++i], { min: 1 });
+    if (args[i] === "--memory") memory = parseIntegerFlag("--memory", args[++i], { min: 1 });
   }
 
   const updateOpts = {};
@@ -282,8 +299,10 @@ async function update(projectId, name, args) {
   if (memory !== undefined) updateOpts.memory = memory;
 
   if (Object.keys(updateOpts).length === 0) {
-    console.error(JSON.stringify({ status: "error", message: "Provide at least one of: --schedule, --schedule-remove, --timeout, --memory" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide at least one of: --schedule, --schedule-remove, --timeout, --memory",
+    });
   }
 
   try {
@@ -295,6 +314,7 @@ async function update(projectId, name, args) {
 }
 
 async function list(projectId) {
+  assertRequiredProject(projectId, "run402 functions list <project_id>");
   try {
     const data = await getSdk().functions.list(projectId);
     console.log(JSON.stringify(data, null, 2));
@@ -304,6 +324,7 @@ async function list(projectId) {
 }
 
 async function deleteFunction(projectId, name) {
+  assertRequiredProjectAndName(projectId, name, "run402 functions delete <project_id> <name>");
   try {
     await getSdk().functions.delete(projectId, name);
     console.log(JSON.stringify({ status: "ok", message: `Function '${name}' deleted.` }));
@@ -314,7 +335,8 @@ async function deleteFunction(projectId, name) {
 
 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"))) {
+  args = normalizeArgv(args);
+  if (Array.isArray(args) && hasHelp(args)) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
@@ -331,3 +353,24 @@ export async function run(sub, args) {
       process.exit(1);
   }
 }
+
+function assertRequiredProject(projectId, usage) {
+  if (!projectId || String(projectId).startsWith("-")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <project_id>.",
+      hint: usage,
+    });
+  }
+}
+
+function assertRequiredProjectAndName(projectId, name, usage) {
+  assertRequiredProject(projectId, usage);
+  if (!name || String(name).startsWith("-")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <name>.",
+      hint: usage,
+    });
+  }
+}

package/lib/image.mjs

@@ -1,6 +1,6 @@
 import { writeFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 image — Generate AI images via x402 micropayments
 
@@ -49,7 +49,13 @@ export async function run(sub, args) {
     i++;
   }
 
-  if (!opts.prompt) { console.error(JSON.stringify({ status: "error", message: "Prompt required. Usage: run402 image generate \"your prompt\"" })); process.exit(1); }
+  if (!opts.prompt) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Prompt required.",
+      hint: 'run402 image generate "your prompt"',
+    });
+  }
 
   try {
     const data = await getSdk().ai.generateImage({ prompt: opts.prompt, aspect: opts.aspect });

package/lib/message.mjs

@@ -1,6 +1,6 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 message — Send messages to Run402 developers
 
@@ -16,7 +16,9 @@ Examples:
 `;
 
 async function send(text) {
-  if (!text) { console.error(JSON.stringify({ status: "error", message: "Missing message text" })); process.exit(1); }
+  if (!text) {
+    fail({ code: "BAD_USAGE", message: "Missing message text." });
+  }
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/message/v1");