run402 1.54.0 → 1.54.2

package/lib/blob.mjs

@@ -36,7 +36,8 @@ import { pipeline } from "node:stream/promises";
 
 import { resolveProject, resolveProjectId, 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 blob — Direct-to-S3 blob storage
 
@@ -62,13 +63,13 @@ Options:
   --ttl <seconds>     Signed-URL TTL (sign only; default 3600, max 604800)
 
 Examples:
-  run402 blob put ./artifact.tgz --project abc123
-  run402 blob put ./dist/**/*.png --project abc123 --key assets/
-  run402 blob put huge.bin --project abc123 --immutable
-  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
-  run402 blob ls --project abc123 --prefix images/
-  run402 blob rm images/logo.png --project abc123
-  run402 blob sign images/logo.png --project abc123 --ttl 600
+  run402 blob put ./artifact.tgz --project prj_abc123
+  run402 blob put ./dist/**/*.png --project prj_abc123 --key assets/
+  run402 blob put huge.bin --project prj_abc123 --immutable
+  run402 blob get images/logo.png --output /tmp/logo.png --project prj_abc123
+  run402 blob ls --project prj_abc123 --prefix images/
+  run402 blob rm images/logo.png --project prj_abc123
+  run402 blob sign images/logo.png --project prj_abc123 --ttl 600
 `;
 
 const SUB_HELP = {
@@ -90,9 +91,9 @@ Options:
   --json              Emit NDJSON progress events on stdout (for agent consumption)
 
 Examples:
-  run402 blob put ./artifact.tgz --project abc123
-  run402 blob put ./dist/**/*.png --project abc123 --key assets/
-  run402 blob put huge.bin --project abc123 --immutable --concurrency 8
+  run402 blob put ./artifact.tgz --project prj_abc123
+  run402 blob put ./dist/**/*.png --project prj_abc123 --key assets/
+  run402 blob put huge.bin --project prj_abc123 --immutable --concurrency 8
 `,
   get: `run402 blob get — Download a blob by key
 
@@ -107,7 +108,7 @@ Options:
   --project <id>      Project ID (defaults to active project)
 
 Examples:
-  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
+  run402 blob get images/logo.png --output /tmp/logo.png --project prj_abc123
 `,
   ls: `run402 blob ls — List blob keys in a project
 
@@ -120,8 +121,8 @@ Options:
   --limit <n>         Max results (default 100, max 1000)
 
 Examples:
-  run402 blob ls --project abc123
-  run402 blob ls --project abc123 --prefix images/ --limit 500
+  run402 blob ls --project prj_abc123
+  run402 blob ls --project prj_abc123 --prefix images/ --limit 500
 `,
   rm: `run402 blob rm — Delete a blob
 
@@ -135,7 +136,7 @@ Options:
   --project <id>      Project ID (defaults to active project)
 
 Examples:
-  run402 blob rm images/logo.png --project abc123
+  run402 blob rm images/logo.png --project prj_abc123
 `,
   sign: `run402 blob sign — Create a presigned download URL for a blob
 
@@ -150,7 +151,7 @@ Options:
   --ttl <seconds>     Signed-URL TTL (default 3600, max 604800)
 
 Examples:
-  run402 blob sign reports/2025-q4.pdf --project abc123 --ttl 600
+  run402 blob sign reports/2025-q4.pdf --project prj_abc123 --ttl 600
 `,
   diagnose: `run402 blob diagnose — Inspect the live CDN state for a public blob URL
 
@@ -182,12 +183,42 @@ Examples:
 
 const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
-function parseArgs(args) {
+function dieApiFailure(prefix, http, body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const envelope = { status: "error", http, ...body };
+    if (!envelope.message && envelope.error) envelope.message = envelope.error;
+    console.error(JSON.stringify(envelope));
+    process.exit(1);
+  }
+  fail({
+    message: `${prefix}: HTTP ${http}${typeof body === "string" && body ? `: ${body.slice(0, 500)}` : ""}`,
+    details: { http },
+  });
+}
+
+function parseArgs(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  const valueFlags = ["--project", "--key", "--concurrency", "--prefix", "--limit", "--output", "-o", "--ttl"];
+  assertKnownFlags(args, [
+    "--project",
+    "--key",
+    "--private",
+    "--immutable",
+    "--concurrency",
+    "--no-resume",
+    "--json",
+    "--prefix",
+    "--limit",
+    "--output",
+    "-o",
+    "--ttl",
+    "--help",
+    "-h",
+  ], valueFlags);
   const out = { positional: [], project: null, key: null, private: false, immutable: false,
                  concurrency: 4, resume: true, json: false, prefix: null, limit: null,
                  output: null, ttl: null };
@@ -197,13 +228,13 @@ function parseArgs(args) {
     else if (a === "--key") out.key = args[++i];
     else if (a === "--private") out.private = true;
     else if (a === "--immutable") out.immutable = true;
-    else if (a === "--concurrency") out.concurrency = parseInt(args[++i], 10);
+    else if (a === "--concurrency") out.concurrency = parseIntegerFlag("--concurrency", args[++i], { min: 1 });
     else if (a === "--no-resume") out.resume = false;
     else if (a === "--json") out.json = true;
     else if (a === "--prefix") out.prefix = args[++i];
-    else if (a === "--limit") out.limit = parseInt(args[++i], 10);
+    else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
-    else if (a === "--ttl") out.ttl = parseInt(args[++i], 10);
+    else if (a === "--ttl") out.ttl = parseIntegerFlag("--ttl", args[++i], { min: 1, max: 604800 });
     else if (!a.startsWith("--")) out.positional.push(a);
   }
   return out;
@@ -285,7 +316,7 @@ async function putOne(project, filePath, opts) {
       immutable: opts.immutable,
       sha256,
     });
-    if (init.status !== 201) die(`Init failed: HTTP ${init.status}: ${JSON.stringify(init.body)}`);
+    if (init.status !== 201) dieApiFailure("Init failed", init.status, init.body);
     initRes = init.body;
     saveState({
       upload_id: initRes.upload_id,
@@ -331,7 +362,7 @@ async function putOne(project, filePath, opts) {
     ? { parts: etags.map((e, i) => ({ part_number: i + 1, etag: e.etag })) }
     : {};
   const complete = await apiFetch(`${API}/storage/v1/uploads/${state.upload_id}/complete`, "POST", project, body);
-  if (complete.status !== 200) die(`Complete failed: HTTP ${complete.status}: ${JSON.stringify(complete.body)}`);
+  if (complete.status !== 200) dieApiFailure("Complete failed", complete.status, complete.body);
 
   removeState(state.upload_id);
   log(opts, { event: "done", ...complete.body });
@@ -566,7 +597,8 @@ export async function run(sub, args) {
     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);
   }

package/lib/cdn.mjs

@@ -15,7 +15,7 @@
 
 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 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -68,9 +68,8 @@ Examples:
 `,
 };
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
 function parseArgs(args) {

package/lib/config.mjs

@@ -7,6 +7,7 @@ import { getApiBase, getConfigDir, getKeystorePath, getAllowancePath } from "../
 import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance } from "../core-dist/allowance.js";
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
+import { fail } from "./sdk-errors.mjs";
 
 export const CONFIG_DIR = getConfigDir();
 export const ALLOWANCE_FILE = getAllowancePath();
@@ -23,31 +24,54 @@ export function saveAllowance(data) {
 
 export function allowanceAuthHeaders(path) {
   const headers = coreGetAllowanceAuthHeaders(path);
-  if (!headers) { console.error(JSON.stringify({ status: "error", message: "No agent allowance found. Run: run402 allowance create" })); process.exit(1); }
+  if (!headers) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance found.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   return headers;
 }
 
 export function findProject(id) {
   const p = getProject(id);
   if (!p) {
-    const hint = id && !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);
+    const idStr = id ?? "";
+    const hint = idStr && !String(idStr).startsWith("prj_")
+      ? `project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
+      : undefined;
+    fail({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project ${idStr} not found in local registry.`,
+      hint,
+      details: { project_id: idStr, source: "local_registry" },
+    });
   }
   return p;
 }
 
 export function resolveProject(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return findProject(projectId);
 }
 
 export function resolveProjectId(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return projectId;
 }
 

package/lib/contracts.mjs

@@ -1,6 +1,6 @@
 import { findProject, API } 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 contracts — KMS-backed Ethereum wallets for smart-contract calls
 
@@ -100,8 +100,10 @@ async function provisionWallet(projectId, args) {
   const p = findProject(projectId);
   const chain = parseFlag(args, "--chain");
   if (!chain) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --chain (base-mainnet or base-sepolia)" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --chain (base-mainnet or base-sepolia)",
+    });
   }
   const recovery = parseFlag(args, "--recovery");
   // Soft default of one wallet — confirm if project already has one. This
@@ -115,8 +117,11 @@ async function provisionWallet(projectId, args) {
       const list = await listRes.json();
       const active = (list.wallets || []).filter((w) => w.status === "active");
       if (active.length >= 1 && !hasFlag(args, "--yes")) {
-        console.error(`This project already has ${active.length} active wallet(s). Adding another costs $0.04/day each ($1.20/month). Re-run with --yes to confirm.`);
-        process.exit(1);
+        fail({
+          code: "CONFIRMATION_REQUIRED",
+          message: `This project already has ${active.length} active wallet(s). Adding another costs $0.04/day each ($1.20/month). Re-run with --yes to confirm.`,
+          details: { active_wallets: active.length },
+        });
       }
     }
   } catch { /* best-effort */ }
@@ -154,8 +159,10 @@ async function setRecovery(projectId, walletId, args) {
   const clear = hasFlag(args, "--clear");
   const address = parseFlag(args, "--address");
   if (!clear && !address) {
-    console.error(JSON.stringify({ status: "error", message: "Provide --address 0x... or --clear" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide --address 0x... or --clear",
+    });
   }
   try {
     await getSdk().contracts.setRecovery(projectId, walletId, clear ? null : address);
@@ -168,8 +175,7 @@ async function setRecovery(projectId, walletId, args) {
 async function setAlert(projectId, walletId, args) {
   const threshold = parseFlag(args, "--threshold-wei");
   if (!threshold) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --threshold-wei <n>" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Missing --threshold-wei <n>" });
   }
   try {
     await getSdk().contracts.setLowBalanceAlert(projectId, walletId, threshold);
@@ -188,17 +194,22 @@ async function call(projectId, walletId, args) {
   const chain = parseFlag(args, "--chain") || "base-mainnet";
   const idempotency = parseFlag(args, "--idempotency-key");
   if (!to || !abi || !fn || !argsJson) {
-    console.error(JSON.stringify({ status: "error", message: "Required flags: --to, --abi, --fn, --args. Cost: chain gas + $0.000005 KMS sign fee." }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required flags: --to, --abi, --fn, --args.",
+      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+    });
   }
+  const abiFragment = parseFlagJson("--abi", abi);
+  const callArgs = parseFlagJson("--args", argsJson);
   try {
     const data = await getSdk().contracts.call(projectId, {
       walletId,
       chain,
       contractAddress: to,
-      abiFragment: JSON.parse(abi),
+      abiFragment,
       functionName: fn,
-      args: JSON.parse(argsJson),
+      args: callArgs,
       value: value ?? undefined,
       idempotencyKey: idempotency ?? undefined,
     });
@@ -215,16 +226,20 @@ async function read(args) {
   const fn = parseFlag(args, "--fn");
   const argsJson = parseFlag(args, "--args");
   if (!chain || !to || !abi || !fn || !argsJson) {
-    console.error(JSON.stringify({ status: "error", message: "Required flags: --chain, --to, --abi, --fn, --args" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required flags: --chain, --to, --abi, --fn, --args",
+    });
   }
+  const abiFragment = parseFlagJson("--abi", abi);
+  const callArgs = parseFlagJson("--args", argsJson);
   try {
     const data = await getSdk().contracts.read({
       chain,
       contractAddress: to,
-      abiFragment: JSON.parse(abi),
+      abiFragment,
       functionName: fn,
-      args: JSON.parse(argsJson),
+      args: callArgs,
     });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
@@ -244,8 +259,11 @@ async function status(projectId, callId) {
 async function drain(projectId, walletId, args) {
   const to = parseFlag(args, "--to");
   if (!to || !hasFlag(args, "--confirm")) {
-    console.error(JSON.stringify({ status: "error", message: "Required: --to 0x... and --confirm. Cost: chain gas + $0.000005 KMS sign fee." }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required: --to 0x... and --confirm.",
+      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+    });
   }
   try {
     const data = await getSdk().contracts.drain(projectId, walletId, to);
@@ -257,8 +275,7 @@ async function drain(projectId, walletId, args) {
 
 async function deleteWallet(projectId, walletId, args) {
   if (!hasFlag(args, "--confirm")) {
-    console.error(JSON.stringify({ status: "error", message: "Required: --confirm" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Required: --confirm" });
   }
   try {
     const data = await getSdk().contracts.deleteWallet(projectId, walletId);

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;