run402 1.54.0 → 1.54.2

package/lib/projects.mjs

@@ -1,7 +1,8 @@
 import { readFileSync } from "fs";
 import { findProject, loadKeyStore, API, allowanceAuthHeaders, resolveProjectId, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
+import { assertKnownFlags, failBadProjectId, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -33,17 +34,17 @@ Examples:
   run402 projects provision --tier hobby --name my-app
   run402 projects use prj_abc123
   run402 projects list
-  run402 projects info abc123
-  run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
-  run402 projects sql abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
-  run402 projects sql abc123 --file setup.sql
-  run402 projects rest abc123 users "limit=10&select=id,name"
-  run402 projects usage abc123
-  run402 projects schema abc123
-  run402 projects apply-expose abc123 --file manifest.json
-  run402 projects get-expose abc123
-  run402 projects keys abc123
-  run402 projects delete abc123 --confirm
+  run402 projects info prj_abc123
+  run402 projects sql prj_abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects sql prj_abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
+  run402 projects sql prj_abc123 --file setup.sql
+  run402 projects rest prj_abc123 users "limit=10&select=id,name"
+  run402 projects usage prj_abc123
+  run402 projects schema prj_abc123
+  run402 projects apply-expose prj_abc123 --file manifest.json
+  run402 projects get-expose prj_abc123
+  run402 projects keys prj_abc123
+  run402 projects delete prj_abc123 --confirm
 
 Notes:
   - <id> is the project_id shown in 'run402 projects list' (prefix: 'prj_')
@@ -103,9 +104,9 @@ Options:
   --params '<json>'   JSON array of parameters for a parameterized query
 
 Examples:
-  run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
-  run402 projects sql abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
-  run402 projects sql abc123 --file setup.sql
+  run402 projects sql prj_abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects sql prj_abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
+  run402 projects sql prj_abc123 --file setup.sql
 `,
 };
 
@@ -153,12 +154,21 @@ async function applyExpose(projectId, args = []) {
   }
   const raw = file ? readFileSync(file, "utf-8") : inline;
   if (!raw) {
-    console.error(JSON.stringify({ status: "error", message: "Missing manifest. Provide inline JSON or use --file <path>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing manifest.",
+      hint: "Provide inline JSON or use --file <path>",
+    });
   }
   let manifest;
   try { manifest = JSON.parse(raw); }
-  catch { console.error(JSON.stringify({ status: "error", message: "Invalid JSON for manifest" })); process.exit(1); }
+  catch (err) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Invalid JSON for manifest",
+      details: { parse_error: err.message },
+    });
+  }
   const res = await fetch(`${API}/projects/v1/admin/${projectId}/expose`, {
     method: "POST",
     headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
@@ -222,11 +232,22 @@ async function sqlCmd(projectId, args = []) {
     else if (!query && !args[i].startsWith("--")) { query = args[i]; }
   }
   const sql = file ? readFileSync(file, "utf-8") : query;
-  if (!sql) { console.error(JSON.stringify({ status: "error", message: "Missing SQL query. Provide inline or use --file <path>" })); process.exit(1); }
+  if (!sql) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing SQL query.",
+      hint: "Provide inline or use --file <path>",
+    });
+  }
   let params;
   if (paramsRaw) {
-    try { params = JSON.parse(paramsRaw); } catch { console.error(JSON.stringify({ status: "error", message: "Invalid JSON for --params. Expected a JSON array, e.g. '[42, \"hello\"]'" })); process.exit(1); }
-    if (!Array.isArray(params)) { console.error(JSON.stringify({ status: "error", message: "--params must be a JSON array, e.g. '[42, \"hello\"]'" })); process.exit(1); }
+    params = parseFlagJson("--params", paramsRaw);
+    if (!Array.isArray(params)) {
+      fail({
+        code: "BAD_USAGE",
+        message: "--params must be a JSON array, e.g. '[42, \"hello\"]'",
+      });
+    }
   }
   const useParams = params && params.length > 0;
   const headers = { "Authorization": `Bearer ${p.service_key}`, "Content-Type": useParams ? "application/json" : "text/plain" };
@@ -264,7 +285,13 @@ async function schema(projectId) {
 }
 
 async function use(projectId) {
-  if (!projectId) { console.error("Usage: run402 projects use <project_id>"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <project_id>.",
+      hint: "run402 projects use <project_id>",
+    });
+  }
   try {
     await getSdk().projects.use(projectId);
     console.log(JSON.stringify({ status: "ok", active_project_id: projectId }));
@@ -274,7 +301,13 @@ async function use(projectId) {
 }
 
 async function pin(projectId) {
-  if (!projectId) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 projects pin <project_id>" })); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <project_id>.",
+      hint: "run402 projects pin <project_id>",
+    });
+  }
   try {
     const data = await getSdk().projects.pin(projectId);
     console.log(JSON.stringify(data, null, 2));
@@ -284,7 +317,13 @@ async function pin(projectId) {
 }
 
 async function promoteUser(projectId, email) {
-  if (!email) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 projects promote-user <project_id> <email>" })); process.exit(1); }
+  if (!email) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email>.",
+      hint: "run402 projects promote-user <project_id> <email>",
+    });
+  }
   const p = findProject(projectId);
   const res = await fetch(`${API}/projects/v1/admin/${projectId}/promote-user`, {
     method: "POST",
@@ -297,7 +336,13 @@ async function promoteUser(projectId, email) {
 }
 
 async function demoteUser(projectId, email) {
-  if (!email) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 projects demote-user <project_id> <email>" })); process.exit(1); }
+  if (!email) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email>.",
+      hint: "run402 projects demote-user <project_id> <email>",
+    });
+  }
   const p = findProject(projectId);
   const res = await fetch(`${API}/projects/v1/admin/${projectId}/demote-user`, {
     method: "POST",
@@ -329,42 +374,72 @@ async function deleteProject(projectId, args = []) {
 }
 
 // Resolve a positional project_id argument with active-project fallback (GH-102).
-// Heuristic: real project IDs start with "prj_". If args[0] is missing OR
-// doesn't start with "prj_", fall back to the active project and return the
-// full args array as remaining positionals. Otherwise consume args[0] as the
-// project_id and return args.slice(1) as remaining positionals.
-function resolvePositionalProject(args) {
+// Callers can tighten the legacy shorthand when a bare non-prj positional is
+// more likely a mistyped project id than an argument for the active project.
+function resolvePositionalProject(args, opts = {}) {
   const first = Array.isArray(args) ? args[0] : undefined;
   if (typeof first === "string" && first.startsWith("prj_")) {
     return { projectId: first, rest: args.slice(1) };
   }
+  if (
+    typeof first === "string" &&
+    first.length > 0 &&
+    !first.startsWith("-") &&
+    Array.isArray(opts.rejectBareFirstWhenFlagPresent) &&
+    opts.rejectBareFirstWhenFlagPresent.some((flag) => args.includes(flag))
+  ) {
+    failBadProjectId(first);
+  }
+  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.rejectBareFirst) {
+    failBadProjectId(first);
+  }
+  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.maxBarePositionals !== undefined) {
+    const bare = positionalArgs(args, opts.valueFlags ?? []);
+    if (bare.length > opts.maxBarePositionals) {
+      failBadProjectId(first);
+    }
+  }
   return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
 }
 
+const FLAGS_BY_SUB = {
+  provision: { known: ["--tier", "--name"], values: ["--tier", "--name"] },
+  sql: { known: ["--file", "--params"], values: ["--file", "--params"] },
+  "apply-expose": { known: ["--file"], values: ["--file"] },
+  delete: { known: ["--confirm"], values: [] },
+};
+
+function validateFlags(sub, args) {
+  const spec = FLAGS_BY_SUB[sub] ?? { known: [], values: [] };
+  assertKnownFlags(args, [...spec.known, "--help", "-h"], spec.values);
+}
+
 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);
   }
+  validateFlags(sub, args);
   switch (sub) {
     case "quote":     await quote(); break;
     case "provision": await provision(args); break;
     case "use":       await use(args[0]); break;
     case "list":      await list(); break;
-    case "info":      { const { projectId } = resolvePositionalProject(args); await info(projectId); break; }
-    case "keys":      { const { projectId } = resolvePositionalProject(args); await keys(projectId); break; }
-    case "sql":       { const { projectId, rest } = resolvePositionalProject(args); await sqlCmd(projectId, rest); break; }
+    case "info":      { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await info(projectId); break; }
+    case "keys":      { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await keys(projectId); break; }
+    case "sql":       { const { projectId, rest } = resolvePositionalProject(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB.sql.values, rejectBareFirstWhenFlagPresent: ["--file"] }); await sqlCmd(projectId, rest); break; }
     case "rest":      { const { projectId, rest: restArgs } = resolvePositionalProject(args); await rest(projectId, restArgs[0], restArgs[1]); break; }
-    case "usage":     { const { projectId } = resolvePositionalProject(args); await usage(projectId); break; }
-    case "schema":    { const { projectId } = resolvePositionalProject(args); await schema(projectId); break; }
-    case "apply-expose": { const { projectId, rest } = resolvePositionalProject(args); await applyExpose(projectId, rest); break; }
-    case "get-expose":   { const { projectId } = resolvePositionalProject(args); await getExpose(projectId); break; }
-    case "delete":    { const { projectId, rest } = resolvePositionalProject(args); await deleteProject(projectId, rest); break; }
-    case "pin":       { const { projectId } = resolvePositionalProject(args); await pin(projectId); break; }
+    case "usage":     { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await usage(projectId); break; }
+    case "schema":    { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await schema(projectId); break; }
+    case "apply-expose": { const { projectId, rest } = resolvePositionalProject(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB["apply-expose"].values, rejectBareFirstWhenFlagPresent: ["--file"] }); await applyExpose(projectId, rest); break; }
+    case "get-expose":   { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await getExpose(projectId); break; }
+    case "delete":    { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true }); await deleteProject(projectId, rest); break; }
+    case "pin":       { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await pin(projectId); break; }
     case "promote-user": { const { projectId, rest } = resolvePositionalProject(args); await promoteUser(projectId, rest[0]); break; }
     case "demote-user":  { const { projectId, rest } = resolvePositionalProject(args); await demoteUser(projectId, rest[0]); break; }
     default:

package/lib/sdk-errors.mjs

@@ -1,25 +1,81 @@
 /**
  * CLI-side SDK error translator.
  *
- * Maps SDK `Run402Error` subclasses into the CLI's existing error output
- * format: `{status: "error", http: ?, ...bodyFields}` on stderr, `process.exit(1)`.
- * Preserves specific behaviors:
- *   - `ProjectNotFound` → plain-text "Project <id> not found in local registry"
- *     with the "Hint: project IDs start with prj_" guidance when the id
- *     doesn't start with `prj_`.
+ * Maps SDK `Run402Error` subclasses into the CLI's canonical error envelope:
+ * `{status: "error", code, message, retryable, safe_to_retry, ...}` on stderr,
+ * `process.exit(1)`. Preserves specific behaviors:
+ *   - `ProjectNotFound` → canonical envelope with `code: "PROJECT_NOT_FOUND"`
+ *     and `details.source: "local_registry"` so callers can distinguish the
+ *     local-registry miss from a gateway 404.
  *   - HTML / non-JSON error bodies → `body_preview` field (first 500 chars),
  *     matching GH-84 behavior.
  *   - Network errors → `{status: "error", message: "..."}`.
+ *
+ * For client-side validation failures (missing flags, bad JSON, no-op
+ * environments), use `fail()` instead — `reportSdkError` is strictly for
+ * thrown `Run402Error` instances.
  */
 
+/**
+ * Canonical client-side failure emitter.
+ *
+ * Writes a single JSON envelope to stderr and exits with `exit_code` (default 1).
+ * The envelope shape matches the gateway's structured error contract so callers
+ * branching on `code` / `retryable` / `safe_to_retry` work uniformly across
+ * client-side validation errors and SDK-thrown errors.
+ *
+ * `code` defaults to "BAD_USAGE" so the helper is safe to call without one.
+ * `retryable: false` and `safe_to_retry: true` are sane defaults for client-side
+ * validation: the call wasn't sent, so retrying is safe and won't help unless
+ * the user fixes input.
+ */
+export function fail({ message, code, hint, details, next_actions, retryable = false, safe_to_retry = true, exit_code = 1 } = {}) {
+  const envelope = {
+    status: "error",
+    code: code ?? "BAD_USAGE",
+    message,
+    retryable,
+    safe_to_retry,
+  };
+  if (hint !== undefined) envelope.hint = hint;
+  if (details !== undefined) envelope.details = details;
+  envelope.next_actions = Array.isArray(next_actions) ? next_actions : [];
+  envelope.trace_id = null;
+  console.error(JSON.stringify(envelope));
+  process.exit(exit_code);
+}
+
+/**
+ * Parse a JSON-bearing CLI flag value, naming the flag in the failure envelope.
+ *
+ * Wraps `JSON.parse` so the failure says which flag was bad and includes a
+ * truncated value preview, instead of leaking a raw V8 `JSON.parse` message
+ * that doesn't tell the caller which flag failed.
+ */
+export function parseFlagJson(name, value) {
+  try {
+    return JSON.parse(value);
+  } catch (e) {
+    fail({
+      code: "BAD_JSON_FLAG",
+      message: `${name} value is not valid JSON`,
+      details: { flag: name, value_preview: String(value).slice(0, 32), parse_error: e.message },
+    });
+  }
+}
+
 export function reportSdkError(err) {
   if (err?.name === "ProjectNotFound") {
     const id = err.projectId || "";
     const hint = id && !String(id).startsWith("prj_")
-      ? ` Hint: project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
-      : "";
-    console.error(`Project ${id} not found in local registry.${hint}`);
-    process.exit(1);
+      ? `project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
+      : undefined;
+    fail({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project ${id} not found in local registry.`,
+      hint,
+      details: { project_id: id, source: "local_registry" },
+    });
   }
 
   const payload = { status: "error" };

package/lib/secrets.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 secrets — Manage project secrets
 
@@ -13,10 +13,10 @@ Subcommands:
   delete <id> <key>            Delete a secret from a project
 
 Examples:
-  run402 secrets set abc123 STRIPE_KEY sk-1234
-  run402 secrets set abc123 TLS_CERT --file cert.pem
-  run402 secrets list abc123
-  run402 secrets delete abc123 STRIPE_KEY
+  run402 secrets set prj_abc123 STRIPE_KEY sk-1234
+  run402 secrets set prj_abc123 TLS_CERT --file cert.pem
+  run402 secrets list prj_abc123
+  run402 secrets delete prj_abc123 STRIPE_KEY
 
 Notes:
   - Secrets are injected as process.env in serverless functions
@@ -43,8 +43,8 @@ Notes:
   - Values are write-only; 'list' returns a value_hash for verification
 
 Examples:
-  run402 secrets set abc123 STRIPE_KEY sk-1234
-  run402 secrets set abc123 TLS_CERT --file cert.pem
+  run402 secrets set prj_abc123 STRIPE_KEY sk-1234
+  run402 secrets set prj_abc123 TLS_CERT --file cert.pem
 `,
 };
 
@@ -56,7 +56,13 @@ async function set(projectId, key, args = []) {
     else if (!value && !args[i].startsWith("--")) { value = args[i]; }
   }
   const val = file ? readFileSync(file, "utf-8") : value;
-  if (!val) { console.error(JSON.stringify({ status: "error", message: "Missing secret value. Provide inline or use --file <path>" })); process.exit(1); }
+  if (!val) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing secret value.",
+      hint: "Provide inline or use --file <path>",
+    });
+  }
   try {
     await getSdk().secrets.set(projectId, key, val);
     console.log(JSON.stringify({ status: "ok", message: `Secret '${key}' set for project ${projectId}.` }));

package/lib/sender-domain.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 sender-domain — Manage custom email sender domain
 
@@ -39,8 +39,11 @@ async function register(args) {
   const projectId = resolveProjectId(projectOpt);
 
   if (!domain) {
-    console.error(JSON.stringify({ status: "error", message: "Missing domain. Usage: run402 sender-domain register <domain>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing domain.",
+      hint: "run402 sender-domain register <domain>",
+    });
   }
 
   try {
@@ -81,8 +84,11 @@ async function inboundToggle(action, args) {
   const projectId = resolveProjectId(projectOpt);
 
   if (!domain) {
-    console.error(JSON.stringify({ status: "error", message: `Missing domain. Usage: run402 sender-domain inbound-${action} <domain>` }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing domain.",
+      hint: `run402 sender-domain inbound-${action} <domain>`,
+    });
   }
 
   try {

package/lib/sites.mjs

@@ -5,7 +5,7 @@ import { fileSetFromDir } from "#sdk/node";
 import { allowanceAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
 import { resolveFilePathsInManifest } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const SMALL_DIR_THRESHOLD = 5;
 
@@ -244,17 +244,19 @@ async function deployDir(args) {
     if (args[i] === "--dry-run") { opts.dryRun = true; continue; }
     if (args[i] === "--confirm-prune") { opts.confirmPrune = true; continue; }
     if (args[i] === "--inherit") {
-      console.error(JSON.stringify({
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: "--inherit is removed; the SDK now uploads only changed files automatically.",
-      }));
-      process.exit(1);
+      });
     }
     if (!args[i].startsWith("-") && opts.dir === null) { opts.dir = args[i]; continue; }
   }
   if (!opts.dir) {
-    console.error(JSON.stringify({ status: "error", message: "Missing <path>. Usage: run402 sites deploy-dir <path> --project <id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <path>.",
+      hint: "run402 sites deploy-dir <path> --project <id>",
+    });
   }
   const projectId = resolveProjectId(opts.project);
 

package/lib/status.mjs

@@ -1,5 +1,6 @@
 import { readAllowance, loadKeyStore, getActiveProjectId, API } from "./config.mjs";
 import { getAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
+import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
 
 const HELP = `run402 status — Show full account state in one shot
 
@@ -75,11 +76,13 @@ function normalizeProject(raw) {
 }
 
 export async function run(args = []) {
-  if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
+  args = normalizeArgv(args);
+  if (hasHelp(args)) { console.log(HELP); process.exit(0); }
+  assertKnownFlags(args, ["--help", "-h"]);
   const allowance = readAllowance();
   if (!allowance) {
     console.log(JSON.stringify({ status: "no_allowance", message: "No agent allowance found. Run: run402 init" }));
-    return;
+    process.exit(1);
   }
 
   const wallet = allowance.address.toLowerCase();

package/lib/subdomains.mjs

@@ -1,6 +1,6 @@
 import { resolveProject, 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 subdomains — Manage custom subdomains
 
@@ -17,7 +17,7 @@ Legacy syntax 'claim <deployment_id> <name>' is still supported.
 
 Examples:
   run402 subdomains claim myapp
-  run402 subdomains claim myapp --deployment dpl_abc123 --project proj123
+  run402 subdomains claim myapp --deployment dpl_abc123 --project prj_abc123
   run402 subdomains delete myapp --confirm
   run402 subdomains list
 
@@ -47,7 +47,7 @@ Notes:
 
 Examples:
   run402 subdomains claim myapp
-  run402 subdomains claim myapp --deployment dpl_abc123 --project proj123
+  run402 subdomains claim myapp --deployment dpl_abc123 --project prj_abc123
 `,
 };
 
@@ -64,11 +64,25 @@ async function claim(positionalArgs, flagArgs) {
   } else if (positionalArgs.length === 1) {
     name = positionalArgs[0];
   }
-  if (!name) { console.error("Usage: run402 subdomains claim <name> [--project <id>] [--deployment <id>]"); process.exit(1); }
+  if (!name) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <name>.",
+      hint: "run402 subdomains claim <name> [--project <id>] [--deployment <id>]",
+    });
+  }
   const projectId = resolveProjectId(opts.project);
   const p = resolveProject(opts.project);
   deploymentId = opts.deployment || deploymentId || p.last_deployment_id;
-  if (!deploymentId) { console.error("Error: no deployment_id specified and no recent deployment found. Deploy a site first or pass --deployment <id>."); process.exit(1); }
+  if (!deploymentId) {
+    fail({
+      code: "NO_DEPLOYMENT",
+      message: "no deployment_id specified and no recent deployment found.",
+      hint: "Deploy a site first or pass --deployment <id>.",
+      details: { project_id: projectId },
+      next_actions: [{ action: "deploy_site_first" }],
+    });
+  }
   try {
     const data = await getSdk().subdomains.claim(name, deploymentId, { projectId });
     console.log(JSON.stringify(data, null, 2));
@@ -86,17 +100,18 @@ async function deleteSubdomain(allArgs) {
     else if (!argList[i].startsWith("--") && !name) { name = argList[i]; }
   }
   if (!name) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 subdomains delete <name> --confirm [--project <id>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <name>.",
+      hint: "run402 subdomains delete <name> --confirm [--project <id>]",
+    });
   }
   if (!argList.includes("--confirm")) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
       code: "CONFIRMATION_REQUIRED",
       message: `Destructive: releasing subdomain '${name}' makes it available for any other project to claim. This is irreversible. Re-run with --confirm to proceed.`,
       details: { name },
-    }));
-    process.exit(1);
+    });
   }
   const projectId = resolveProjectId(opts.project);
   try {

package/lib/tier.mjs

@@ -1,5 +1,5 @@
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 tier — Manage your Run402 tier subscription
 
@@ -34,7 +34,13 @@ async function status() {
 }
 
 async function set(tierName) {
-  if (!tierName) { console.error(JSON.stringify({ status: "error", message: "Usage: run402 tier set <prototype|hobby|team>" })); process.exit(1); }
+  if (!tierName) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <tier>.",
+      hint: "run402 tier set <prototype|hobby|team>",
+    });
+  }
   try {
     const data = await getSdk().tier.set(tierName);
     console.log(JSON.stringify(data, null, 2));

package/lib/webhooks.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 email webhooks — Manage mailbox webhooks
 
@@ -62,8 +62,11 @@ async function get(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!webhookId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing webhook_id. Usage: run402 email webhooks get <webhook_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing webhook_id.",
+      hint: "run402 email webhooks get <webhook_id>",
+    });
   }
   try {
     const data = await getSdk().email.webhooks.get(projectId, webhookId);
@@ -82,8 +85,11 @@ async function del(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!webhookId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing webhook_id. Usage: run402 email webhooks delete <webhook_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing webhook_id.",
+      hint: "run402 email webhooks delete <webhook_id>",
+    });
   }
   try {
     await getSdk().email.webhooks.delete(projectId, webhookId);
@@ -106,12 +112,14 @@ async function update(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!webhookId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing webhook_id. Usage: run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing webhook_id.",
+      hint: "run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>]",
+    });
   }
   if (!url && !eventsRaw) {
-    console.error(JSON.stringify({ status: "error", message: "Provide at least --url or --events" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Provide at least --url or --events" });
   }
 
   try {
@@ -132,12 +140,18 @@ async function register(args) {
   const projectId = resolveProjectId(projectOpt);
 
   if (!url) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --url. Usage: run402 email webhooks register --url <url> --events <e1,e2>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --url.",
+      hint: "run402 email webhooks register --url <url> --events <e1,e2>",
+    });
   }
   if (!eventsRaw) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --events. Valid events: delivery, bounced, complained, reply_received" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --events.",
+      hint: "Valid events: delivery, bounced, complained, reply_received",
+    });
   }
 
   const events = eventsRaw.split(",").map((e) => e.trim());