run402 1.54.0 → 1.54.1

package/lib/deploy-v2.mjs

@@ -26,7 +26,7 @@
 import { readFileSync } from "node:fs";
 import { resolve, dirname, isAbsolute, join } from "node:path";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { allowanceAuthHeaders, resolveProjectId } from "./config.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
@@ -107,8 +107,11 @@ export async function runDeployV2(sub, args) {
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
-  console.error(JSON.stringify({ status: "error", message: `Unknown deploy subcommand: ${sub}` }));
-  process.exit(1);
+  fail({
+    code: "BAD_USAGE",
+    message: `Unknown deploy subcommand: ${sub}`,
+    details: { subcommand: sub },
+  });
 }
 
 async function readStdin() {
@@ -142,8 +145,11 @@ async function applyCmd(args) {
       const manifestPath = isAbsolute(opts.manifest) ? opts.manifest : resolve(process.cwd(), opts.manifest);
       raw = readFileSync(manifestPath, "utf-8");
     } catch (err) {
-      console.error(JSON.stringify({ status: "error", message: `Failed to read manifest: ${err.message}` }));
-      process.exit(1);
+      fail({
+        code: "BAD_USAGE",
+        message: `Failed to read manifest: ${err.message}`,
+        details: { flag: "--manifest", path: opts.manifest },
+      });
     }
   } else {
     raw = await readStdin();
@@ -153,18 +159,21 @@ async function applyCmd(args) {
   try {
     spec = JSON.parse(raw);
   } catch (err) {
-    console.error(JSON.stringify({ status: "error", message: `Manifest is not valid JSON: ${err.message}` }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: `Manifest is not valid JSON: ${err.message}`,
+      details: { source: opts.manifest ? "manifest" : opts.spec ? "spec" : "stdin", parse_error: err.message },
+    });
   }
 
   if (opts.manifest) resolveFileDataPaths(spec, dirname(resolve(opts.manifest)));
 
   if (opts.project && spec.project_id && spec.project_id !== opts.project) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `project_id conflict: spec.project_id=${spec.project_id} but --project=${opts.project}`,
-    }));
-    process.exit(1);
+      details: { spec_project_id: spec.project_id, flag_project_id: opts.project },
+    });
   }
   if (opts.project) spec.project_id = opts.project;
   if (!spec.project_id) spec.project_id = resolveProjectId(null);
@@ -198,8 +207,11 @@ async function resumeCmd(args) {
     if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
   }
   if (!opts.operationId) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 deploy resume <operation_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy resume <operation_id>",
+    });
   }
 
   allowanceAuthHeaders("/deploy/v2/operations");
@@ -243,8 +255,11 @@ async function eventsCmd(args) {
     if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
   }
   if (!opts.operationId) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 deploy events <operation_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy events <operation_id>",
+    });
   }
 
   const project = resolveProjectId(opts.project);
@@ -383,11 +398,11 @@ function resolveFileDataPaths(spec, baseDir) {
           m.sql = readFileSync(p, "utf-8");
           delete m.sql_path;
         } catch (err) {
-          console.error(JSON.stringify({
-            status: "error",
+          fail({
+            code: "BAD_USAGE",
             message: `Failed to read migration sql_path '${m.sql_path}': ${err.message}`,
-          }));
-          process.exit(1);
+            details: { migration_id: m.id, sql_path: m.sql_path },
+          });
         }
       }
     }
@@ -421,10 +436,10 @@ function readFileEntry(entry, baseDir) {
     if (entry.contentType) out.contentType = entry.contentType;
     return out;
   } catch (err) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `Failed to read file '${entry.path}': ${err.message}`,
-    }));
-    process.exit(1);
+      details: { path: entry.path },
+    });
   }
 }

package/lib/deploy.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from "path";
 import { resolveProjectId } from "./config.mjs";
 import { resolveFilePathsInManifest, resolveMigrationsFile } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 deploy — Deploy to an existing project on Run402
 
@@ -111,8 +111,8 @@ async function readStdin() {
  * Load + parse the manifest from --manifest file or stdin, and resolve any
  * referenced files[].path / migrations_file against the manifest's directory.
  *
- * Returns { manifest } on success, or { error } with a structured error object
- * on any fs / parse failure. Never throws.
+ * Returns the parsed manifest on success. On any fs / parse failure, calls
+ * `fail()` (which writes the canonical error envelope to stderr and exits 1).
  */
 async function loadManifest(opts) {
   let raw;
@@ -125,21 +125,18 @@ async function loadManifest(opts) {
       raw = readFileSync(opts.manifest, "utf-8");
     } catch (err) {
       if (err && err.code === "ENOENT") {
-        return { error: {
-          status: "error",
+        fail({
+          code: "BAD_USAGE",
           message: `File not found: ${manifestAbs}`,
-          field: "manifest",
-          path: manifestAbs,
           hint: "Check that --manifest points to an existing JSON file.",
-        } };
+          details: { field: "manifest", path: manifestAbs },
+        });
       }
-      return { error: {
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: err && err.message ? err.message : String(err),
-        field: "manifest",
-        path: manifestAbs,
-        ...(err && err.code ? { code: err.code } : {}),
-      } };
+        details: { field: "manifest", path: manifestAbs, ...(err && err.code ? { syscall_code: err.code } : {}) },
+      });
     }
   } else {
     raw = await readStdin();
@@ -149,12 +146,15 @@ async function loadManifest(opts) {
   try {
     manifest = JSON.parse(raw);
   } catch (err) {
-    return { error: {
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `Manifest is not valid JSON: ${err.message}`,
-      field: opts.manifest ? "manifest" : "stdin",
-      ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
-    } };
+      details: {
+        field: opts.manifest ? "manifest" : "stdin",
+        ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
+        parse_error: err.message,
+      },
+    });
   }
 
   if (opts.manifest) {
@@ -163,25 +163,29 @@ async function loadManifest(opts) {
       resolveFilePathsInManifest(manifest, baseDir);
     } catch (err) {
       if (err && err.code === "ENOENT") {
-        return { error: {
-          status: "error",
+        fail({
+          code: "BAD_USAGE",
           message: `File not found: ${err.absPath || err.path || "<unknown>"}`,
-          field: err.field || "manifest",
-          ...(err.absPath || err.path ? { path: err.absPath || err.path } : {}),
           hint: `Paths in manifest.${err.field || "files[].path"} are resolved relative to the manifest file's directory (${baseDir}).`,
-        } };
+          details: {
+            field: err.field || "manifest",
+            ...(err.absPath || err.path ? { path: err.absPath || err.path } : {}),
+          },
+        });
       }
-      return { error: {
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: err && err.message ? err.message : String(err),
-        ...(err && err.field ? { field: err.field } : {}),
-        ...(err && (err.absPath || err.path) ? { path: err.absPath || err.path } : {}),
-        ...(err && err.code ? { code: err.code } : {}),
-      } };
+        details: {
+          ...(err && err.field ? { field: err.field } : {}),
+          ...(err && (err.absPath || err.path) ? { path: err.absPath || err.path } : {}),
+          ...(err && err.code ? { syscall_code: err.code } : {}),
+        },
+      });
     }
   }
 
-  return { manifest };
+  return manifest;
 }
 
 export async function run(args) {
@@ -210,25 +214,20 @@ export async function run(args) {
     if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
   }
 
-  const manifestResult = await loadManifest(opts);
-  if (manifestResult.error) {
-    console.error(JSON.stringify(manifestResult.error));
-    process.exit(1);
-  }
-  const manifest = manifestResult.manifest;
+  const manifest = await loadManifest(opts);
 
   // If both sources set project_id and they disagree, refuse to deploy rather
   // than silently shipping to the wrong target.
   if (opts.project && manifest.project_id && opts.project !== manifest.project_id) {
-    const err = {
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `project_id conflict: manifest.project_id=${manifest.project_id} but --project=${opts.project}`,
-      manifest_project_id: manifest.project_id,
-      flag_project_id: opts.project,
       hint: "Remove one of them or make them match. The --project flag and manifest.project_id must agree (or only one of them must be set).",
-    };
-    console.error(JSON.stringify(err));
-    process.exit(1);
+      details: {
+        manifest_project_id: manifest.project_id,
+        flag_project_id: opts.project,
+      },
+    });
   }
 
   if (opts.project) manifest.project_id = opts.project;

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,7 @@
 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";
 
 const HELP = `run402 functions — Manage serverless functions
 
@@ -152,7 +152,9 @@ async function deploy(projectId, name, args) {
     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 };
@@ -212,7 +214,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();
   }
 
@@ -282,8 +290,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 {

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");
 

package/lib/projects.mjs

@@ -1,7 +1,7 @@
 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";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -153,12 +153,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 +231,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 +284,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 +300,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 +316,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 +335,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",