run402 1.34.2 → 1.35.1

package/cli.mjs

@@ -28,7 +28,8 @@ Commands:
   deploy      Deploy a full-stack app or static site (requires active tier)
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
-  storage     Manage file storage (upload, download, list, delete)
+  blob        Direct-to-S3 blob storage (put, get, ls, rm, sign) — up to 5 TiB
+  storage     Legacy file storage (deprecated — sunset 2026-06-01, use 'blob')
   sites       Deploy static sites
   subdomains  Manage custom subdomains (claim, list, delete)
   domains     Manage custom domains (add, list, status, delete)
@@ -115,10 +116,19 @@ switch (cmd) {
     break;
   }
   case "storage": {
+    process.stderr.write(
+      "run402 storage is deprecated — sunset 2026-06-01. Use `run402 blob` instead.\n" +
+      "See https://run402.com/docs/blob#migration\n\n",
+    );
     const { run } = await import("./lib/storage.mjs");
     await run(sub, rest);
     break;
   }
+  case "blob": {
+    const { run } = await import("./lib/blob.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "sites": {
     const { run } = await import("./lib/sites.mjs");
     await run(sub, rest);

package/lib/blob.mjs

@@ -0,0 +1,449 @@
+/**
+ * run402 blob — direct-to-S3 storage CLI.
+ *
+ * Usage:
+ *   run402 blob put <file> [files...] [--project <id>] [--key <dest>] [--private] [--immutable] [--concurrency N] [--no-resume]
+ *   run402 blob get <key> --output <file> [--project <id>]
+ *   run402 blob ls [--project <id>] [--prefix <p>] [--limit <n>]
+ *   run402 blob rm <key> [--project <id>]
+ *   run402 blob sign <key> [--project <id>] [--ttl <seconds>]
+ *
+ * For any file ≤ 5 GiB a single presigned PUT is used. Larger files use S3
+ * multipart uploads with 16 MiB parts (640 parts at 10 GiB; up to 10 000
+ * parts at 5 TiB). The gateway never carries upload bytes — PUTs go straight
+ * to S3 from the client.
+ *
+ * Resumable uploads are enabled by default. The CLI persists per-upload
+ * state to ~/.run402/uploads/<upload_id>.json so a Ctrl-C'd upload can be
+ * resumed by re-running the same command.
+ */
+
+import {
+  createReadStream,
+  statSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  unlinkSync,
+  readdirSync,
+  createWriteStream,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
+import { pipeline } from "node:stream/promises";
+
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 blob — Direct-to-S3 blob storage
+
+Usage:
+  run402 blob put <file> [files...] [options]
+  run402 blob get <key> --output <file> [options]
+  run402 blob ls [options]
+  run402 blob rm <key> [options]
+  run402 blob sign <key> [options]
+
+Options:
+  --project <id>      Project ID (defaults to active project from 'run402 projects use')
+  --key <dest>        Destination key (put only; defaults to file basename)
+  --private           Upload as private (not served by CDN; apikey required to read)
+  --immutable         Adds a content-hash suffix to the URL so overwrites produce distinct URLs.
+                      Requires computing SHA-256 over the file (CLI does this automatically).
+  --concurrency N     Concurrent part PUTs (default 4)
+  --no-resume         Start fresh; ignore any cached state
+  --json              NDJSON progress events (for agent consumption)
+  --prefix <p>        Prefix filter (ls only)
+  --limit <n>         Max results (ls only; default 100, max 1000)
+  --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
+`;
+
+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 parseArgs(args) {
+  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 };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--project") out.project = args[++i];
+    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 === "--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 === "--output" || a === "-o") out.output = args[++i];
+    else if (a === "--ttl") out.ttl = parseInt(args[++i], 10);
+    else if (!a.startsWith("--")) out.positional.push(a);
+  }
+  return out;
+}
+
+function resolveProject(projectId) {
+  if (!projectId) die("--project is required (or run 'run402 projects use <id>' to set default)");
+  const p = findProject(projectId);
+  if (!p) die(`Project not found: ${projectId}`);
+  return p;
+}
+
+async function sha256File(filePath) {
+  const h = createHash("sha256");
+  const stream = createReadStream(filePath);
+  for await (const chunk of stream) h.update(chunk);
+  return h.digest("hex");
+}
+
+function loadState(uploadId) {
+  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch { return null; }
+}
+
+function saveState(state) {
+  mkdirSync(UPLOAD_STATE_DIR, { recursive: true });
+  writeFileSync(join(UPLOAD_STATE_DIR, `${state.upload_id}.json`), JSON.stringify(state, null, 2));
+}
+
+function removeState(uploadId) {
+  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+function findResumableStateForFile(projectId, localPath, key) {
+  if (!existsSync(UPLOAD_STATE_DIR)) return null;
+  for (const f of readdirSync(UPLOAD_STATE_DIR)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(readFileSync(join(UPLOAD_STATE_DIR, f), "utf8"));
+      if (s.project_id === projectId && s.local_path === localPath && s.key === key) return s;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// put
+// ---------------------------------------------------------------------------
+
+async function putOne(project, filePath, opts) {
+  const stat = statSync(filePath);
+  const size = stat.size;
+  const destKey = computeDestKey(filePath, opts.key);
+  const absLocal = resolvePath(filePath);
+
+  // Compute sha256 for immutable uploads up front; otherwise lazy.
+  const needSha = opts.immutable;
+  const sha256 = needSha ? await sha256File(filePath) : undefined;
+
+  // Attempt to resume
+  let state = opts.resume
+    ? findResumableStateForFile(project.id, absLocal, destKey)
+    : null;
+  let initRes;
+  if (state) {
+    // Re-poll the session; if it's still active, resume. Otherwise start fresh.
+    const poll = await apiFetch(`${API}/storage/v1/uploads/${state.upload_id}`, "GET", project, null);
+    if (poll.status === 200 && poll.body.status === "active") {
+      log(opts, { event: "resume", upload_id: state.upload_id, key: destKey });
+      initRes = { upload_id: state.upload_id, mode: state.mode, parts: state.parts, part_count: state.part_count, part_size_bytes: state.part_size_bytes };
+    } else {
+      removeState(state.upload_id);
+      state = null;
+    }
+  }
+
+  if (!state) {
+    const init = await apiFetch(`${API}/storage/v1/uploads`, "POST", project, {
+      key: destKey,
+      size_bytes: size,
+      content_type: guessContentType(destKey),
+      visibility: opts.private ? "private" : "public",
+      immutable: opts.immutable,
+      sha256,
+    });
+    if (init.status !== 201) die(`Init failed: HTTP ${init.status}: ${JSON.stringify(init.body)}`);
+    initRes = init.body;
+    saveState({
+      upload_id: initRes.upload_id,
+      project_id: project.id,
+      local_path: absLocal,
+      key: destKey,
+      mode: initRes.mode,
+      part_size_bytes: initRes.part_size_bytes,
+      part_count: initRes.part_count,
+      parts: initRes.parts,
+      parts_done: {},
+      sha256,
+      started_at: new Date().toISOString(),
+    });
+    state = loadState(initRes.upload_id);
+  }
+
+  // Upload parts with concurrency limit. For single-PUT mode part_count=1 and
+  // this loop runs once.
+  const etags = Array(initRes.part_count);
+  for (const pn of Object.keys(state.parts_done || {})) {
+    const pd = state.parts_done[pn];
+    // Legacy resume state stored just the etag string; new code stores
+    // { etag, sha256 }. Normalize on load.
+    etags[parseInt(pn, 10) - 1] = typeof pd === "string" ? { etag: pd, sha256: undefined } : pd;
+  }
+
+  // Presigned URLs are signed WITHOUT ChecksumAlgorithm (see gateway
+  // s3-presign.ts). The client-asserted sha256 declared at init is the
+  // integrity attestation — no x-amz-checksum-sha256 header on PUTs, and
+  // the gateway trusts the declared value at complete when S3 has none.
+  const todo = initRes.parts.filter((p) => !(state.parts_done || {})[String(p.part_number)]);
+  await withConcurrency(todo, opts.concurrency, async (part) => {
+    const { etag } = await putPart(filePath, part);
+    etags[part.part_number - 1] = { etag };
+    state.parts_done[String(part.part_number)] = { etag };
+    saveState(state);
+    log(opts, { event: "part", upload_id: state.upload_id, part_number: part.part_number, etag });
+  });
+
+  // Complete
+  const body = initRes.mode === "multipart"
+    ? { 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)}`);
+
+  removeState(state.upload_id);
+  log(opts, { event: "done", ...complete.body });
+  return complete.body;
+}
+
+function computeDestKey(filePath, keyOpt) {
+  if (!keyOpt) return basename(filePath);
+  if (keyOpt.endsWith("/")) return keyOpt + basename(filePath);
+  return keyOpt;
+}
+
+async function putPart(filePath, part) {
+  const start = part.byte_start ?? 0;
+  const end = part.byte_end ?? (statSync(filePath).size - 1);
+  const stream = createReadStream(filePath, { start, end });
+  const chunks = [];
+  for await (const c of stream) chunks.push(c);
+  const body = Buffer.concat(chunks);
+
+  const res = await fetch(part.url, { method: "PUT", body });
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => "");
+    throw new Error(`Part ${part.part_number} PUT failed: ${res.status} ${res.statusText}${errBody ? " — " + errBody.slice(0, 200) : ""}`);
+  }
+  const etag = res.headers.get("etag") ?? "";
+  return { etag };
+}
+
+async function withConcurrency(items, limit, worker) {
+  const running = [];
+  for (const item of items) {
+    const p = Promise.resolve().then(() => worker(item));
+    running.push(p);
+    if (running.length >= limit) {
+      await Promise.race(running.map((r) => r.catch(() => {})));
+      for (let i = running.length - 1; i >= 0; i--) {
+        if (isSettled(running[i])) running.splice(i, 1);
+      }
+    }
+  }
+  await Promise.all(running);
+}
+
+function isSettled(p) {
+  const marker = {};
+  return Promise.race([p, marker]).then(
+    (v) => v !== marker,
+    () => true,
+  );
+}
+
+async function put(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+
+  if (opts.positional.length === 0) die("At least one file path is required");
+  if (opts.immutable && opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
+    die("--key with --immutable across multiple files requires a directory prefix (ending with /)");
+  }
+
+  const results = [];
+  for (const filePath of opts.positional) {
+    if (!existsSync(filePath)) die(`File not found: ${filePath}`);
+    const r = await putOne(project, filePath, opts);
+    results.push({ file: filePath, ...r });
+  }
+  if (!opts.json) console.log(JSON.stringify(results, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// get
+// ---------------------------------------------------------------------------
+
+async function get(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  if (!opts.output) die("--output <file> required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}`, {
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  if (!res.ok) die(`GET failed: HTTP ${res.status}`);
+  if (!res.body) die("Empty response body");
+
+  mkdirSync(dirname(resolvePath(opts.output)), { recursive: true });
+  await pipeline(res.body, createWriteStream(opts.output));
+  console.log(JSON.stringify({ status: "ok", key, output: opts.output }));
+}
+
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+
+async function ls(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+
+  const qs = new URLSearchParams();
+  if (opts.prefix) qs.set("prefix", opts.prefix);
+  if (opts.limit) qs.set("limit", String(opts.limit));
+  const url = `${API}/storage/v1/blobs${qs.toString() ? "?" + qs.toString() : ""}`;
+
+  const res = await fetch(url, {
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// rm
+// ---------------------------------------------------------------------------
+
+async function rm(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}`, {
+    method: "DELETE",
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// sign
+// ---------------------------------------------------------------------------
+
+async function sign(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}/sign`, {
+    method: "POST",
+    headers: { "content-type": "application/json", apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+    body: JSON.stringify(opts.ttl ? { ttl_seconds: opts.ttl } : {}),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function encodeKey(key) {
+  // Encode each path segment; preserve `/` as separator.
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+
+function guessContentType(key) {
+  const ext = key.slice(key.lastIndexOf(".") + 1).toLowerCase();
+  const map = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif",
+    svg: "image/svg+xml", webp: "image/webp",
+    html: "text/html", css: "text/css", js: "text/javascript", json: "application/json",
+    txt: "text/plain", md: "text/markdown", pdf: "application/pdf",
+    mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime",
+    zip: "application/zip", tgz: "application/gzip", gz: "application/gzip",
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+
+async function apiFetch(url, method, project, body) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      apikey: project.anon_key,
+      Authorization: `Bearer ${project.anon_key}`,
+    },
+    body: body === null ? undefined : JSON.stringify(body ?? {}),
+  });
+  const txt = await res.text();
+  let parsed; try { parsed = txt ? JSON.parse(txt) : null; } catch { parsed = txt; }
+  return { status: res.status, body: parsed };
+}
+
+function log(opts, event) {
+  if (opts.json) console.log(JSON.stringify(event));
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const defaultProject = process.env.RUN402_PROJECT ?? null;
+  switch (sub) {
+    case "put":   await put(defaultProject, args); break;
+    case "get":   await get(defaultProject, args); break;
+    case "ls":    await ls(defaultProject, args); break;
+    case "rm":    await rm(defaultProject, args); break;
+    case "sign":  await sign(defaultProject, args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/init.mjs

@@ -12,6 +12,8 @@ const HELP = `run402 init — Set up allowance, funding, and check tier status
 Usage:
   run402 init          Set up with x402 (Base Sepolia) — default
   run402 init mpp      Set up with MPP (Tempo Moderato)
+  run402 init --json   Same as init, but emit a JSON summary on stdout
+                       (human lines go to stderr — for agent automation)
 
 Steps (idempotent — safe to re-run):
   1. Creates config directory (~/.config/run402)
@@ -25,12 +27,28 @@ Run this once to get started, or again to check your setup.
 `;
 
 function short(addr) { return addr.slice(0, 6) + "..." + addr.slice(-4); }
-function line(label, value) { console.log(`  ${label.padEnd(10)} ${value}`); }
 
 export async function run(args = []) {
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
+  const jsonMode = args.includes("--json");
   const isMpp = args[0] === "mpp";
-  console.log();
+
+  // In --json mode, human-readable lines go to stderr so stdout stays clean for
+  // agents. We also collect structured data for the final JSON emit.
+  const write = jsonMode ? (s) => console.error(s) : (s) => console.log(s);
+  const line = (label, value) => write(`  ${label.padEnd(10)} ${value}`);
+  const summary = {
+    config_dir: CONFIG_DIR,
+    allowance: null,
+    rail: null,
+    network: null,
+    balance: null,
+    tier: null,
+    projects_saved: 0,
+    next_step: null,
+  };
+
+  write("");
 
   // 1. Config directory
   mkdirSync(CONFIG_DIR, { recursive: true });
@@ -58,6 +76,10 @@ export async function run(args = []) {
     line("Allowance", short(allowance.address));
   }
 
+  summary.allowance = { address: allowance.address, funded: allowance.funded || false };
+  summary.network = isMpp ? "tempo-moderato" : "base-sepolia";
+  summary.rail = isMpp ? "mpp" : "x402";
+
   line("Network", isMpp ? "Tempo Moderato (testnet)" : "Base Sepolia (testnet)");
   line("Rail", isMpp ? "mpp" : "x402");
 
@@ -110,6 +132,7 @@ export async function run(args = []) {
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} pathUSD`);
     }
+    summary.balance = { symbol: "pathUSD", usd_micros: balance };
   } else {
     // Base Sepolia: read USDC balance (existing behavior)
     const { createPublicClient, http } = await import("viem");
@@ -152,6 +175,7 @@ export async function run(args = []) {
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} USDC`);
     }
+    summary.balance = { symbol: "USDC", usd_micros: balance };
   }
 
   // Show note if switching rails
@@ -176,19 +200,32 @@ export async function run(args = []) {
   if (tierInfo && tierInfo.tier && tierInfo.active) {
     const expiry = tierInfo.lease_expires_at ? tierInfo.lease_expires_at.split("T")[0] : "unknown";
     line("Tier", `${tierInfo.tier} (expires ${expiry})`);
+    summary.tier = { name: tierInfo.tier, expires: tierInfo.lease_expires_at || null };
   } else {
     line("Tier", "(none)");
+    summary.tier = null;
   }
 
-  // 5. Projects
-  line("Projects", `${Object.keys(store.projects).length} active`);
+  // 5. Projects — count locally saved project entries. Note: "saved" (not
+  // "active") — these are all projects in the keystore, regardless of whether
+  // the server considers them active.
+  summary.projects_saved = Object.keys(store.projects).length;
+  line("Projects", `${summary.projects_saved} saved`);
 
   // 6. Next step
-  console.log();
+  write("");
+  const nextStep = (!tierInfo || !tierInfo.tier || !tierInfo.active)
+    ? "run402 tier set prototype"
+    : "run402 deploy --manifest app.json";
   if (!tierInfo || !tierInfo.tier || !tierInfo.active) {
-    console.log("  Next: run402 tier set prototype");
+    write("  Next: run402 tier set prototype");
   } else {
-    console.log("  Ready to deploy. Run: run402 deploy --manifest app.json");
+    write("  Ready to deploy. Run: run402 deploy --manifest app.json");
+  }
+  write("");
+  summary.next_step = nextStep;
+
+  if (jsonMode) {
+    console.log(JSON.stringify(summary, null, 2));
   }
-  console.log();
 }

package/lib/projects.mjs

@@ -141,13 +141,17 @@ async function sqlCmd(projectId, args = []) {
   const headers = { "Authorization": `Bearer ${p.service_key}`, "Content-Type": useParams ? "application/json" : "text/plain" };
   const body = useParams ? JSON.stringify({ sql, params }) : sql;
   const res = await fetch(`${API}/projects/v1/admin/${projectId}/sql`, { method: "POST", headers, body });
-  console.log(JSON.stringify(await res.json(), null, 2));
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
 }
 
 async function rest(projectId, table, queryParams) {
   const p = findProject(projectId);
   const res = await fetch(`${API}/rest/v1/${table}${queryParams ? '?' + queryParams : ''}`, { headers: { "apikey": p.anon_key } });
-  console.log(JSON.stringify(await res.json(), null, 2));
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
 }
 
 async function usage(projectId) {

package/lib/status.mjs

@@ -8,6 +8,7 @@ Usage:
 
 Displays:
   - Allowance address and funding status
+  - Wallet on-chain USDC/pathUSD balance (wallet_balance_usd_micros)
   - Billing balance (available + held)
   - Tier subscription (name, status, expiry)
   - Projects (from server, with fallback to local keystore)
@@ -16,6 +17,63 @@ Displays:
 Output is JSON. Requires an existing allowance (run 'run402 init' first).
 `;
 
+// USDC / pathUSD constants (match allowance.mjs)
+const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
+const USDC_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+const PATH_USD = "0x20c0000000000000000000000000000000000000";
+const TEMPO_RPC = "https://rpc.moderato.tempo.xyz/";
+
+/**
+ * Read the on-chain wallet balance in USD micros for the current rail.
+ * For x402: read Base mainnet + Base Sepolia USDC and sum funded networks.
+ * For mpp:  read pathUSD on Tempo Moderato.
+ * Returns null if every read fails (e.g. offline or RPC down).
+ */
+async function readWalletBalanceUsdMicros(rail, address) {
+  try {
+    const { createPublicClient, http, defineChain } = await import("viem");
+    if (rail === "mpp") {
+      const tempoModerato = defineChain({
+        id: 42431,
+        name: "Tempo Moderato",
+        nativeCurrency: { name: "pathUSD", symbol: "pathUSD", decimals: 6 },
+        rpcUrls: { default: { http: [TEMPO_RPC] } },
+      });
+      const client = createPublicClient({ chain: tempoModerato, transport: http() });
+      try {
+        const raw = await client.readContract({ address: PATH_USD, abi: USDC_ABI, functionName: "balanceOf", args: [address] });
+        return Number(raw);
+      } catch { return null; }
+    }
+    // x402 rail — read Base mainnet + Base Sepolia in parallel; sum any that succeed.
+    const { base, baseSepolia } = await import("viem/chains");
+    const mainnetClient = createPublicClient({ chain: base, transport: http() });
+    const sepoliaClient = createPublicClient({ chain: baseSepolia, transport: http() });
+    const [mainnet, sepolia] = await Promise.all([
+      mainnetClient.readContract({ address: USDC_MAINNET, abi: USDC_ABI, functionName: "balanceOf", args: [address] }).then(Number).catch(() => null),
+      sepoliaClient.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [address] }).then(Number).catch(() => null),
+    ]);
+    if (mainnet === null && sepolia === null) return null;
+    return (mainnet || 0) + (sepolia || 0);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize a project entry to the agreed-on shape: always expose `project_id`
+ * (matching `projects list`). The remote /wallets/v1/:wallet/projects endpoint
+ * returns entries keyed as `id`, so we map them here and drop the raw `id`
+ * field to avoid having two aliases for the same identity.
+ */
+function normalizeProject(raw) {
+  if (!raw || typeof raw !== "object") return raw;
+  const projectId = raw.project_id || raw.id;
+  const { id: _dropId, project_id: _dropPid, ...rest } = raw;
+  return { project_id: projectId, ...rest };
+}
+
 export async function run(args = []) {
   if (args.includes("--help") || args.includes("-h")) { console.log(HELP); process.exit(0); }
   const allowance = readAllowance();
@@ -26,14 +84,16 @@ export async function run(args = []) {
 
   const wallet = allowance.address.toLowerCase();
   const authHeaders = getAllowanceAuthHeaders("/tiers/v1/status");
+  const rail = allowance.rail || "x402";
 
-  // Parallel API calls: tier + billing balance + server-side projects
-  const [tierRes, balanceRes, projectsRes] = await Promise.all([
+  // Parallel API calls: tier + billing balance + server-side projects + on-chain wallet balance
+  const [tierRes, balanceRes, projectsRes, walletBalance] = await Promise.all([
     authHeaders
       ? fetch(`${API}/tiers/v1/status`, { headers: { ...authHeaders } }).catch(() => null)
       : null,
     fetch(`${API}/billing/v1/accounts/${wallet}`).catch(() => null),
     fetch(`${API}/wallets/v1/${wallet}/projects`).catch(() => null),
+    readWalletBalanceUsdMicros(rail, allowance.address),
   ]);
 
   const tier = tierRes?.ok ? await tierRes.json() : null;
@@ -44,18 +104,29 @@ export async function run(args = []) {
   const store = loadKeyStore();
   const activeId = getActiveProjectId();
 
+  const projects = remote?.projects
+    ? remote.projects.map(normalizeProject)
+    : Object.keys(store.projects).map(id => ({ project_id: id }));
+
   const result = {
     allowance: {
       address: allowance.address,
       funded: allowance.funded || false,
     },
+    rail,
     tier: tier && tier.tier
       ? { name: tier.tier, status: tier.status, expires: tier.lease_expires_at }
       : null,
-    balance: billing && billing.exists
+    // GH-32: `balance` used to mean the billing-account balance, which
+    // confused people who expected their on-chain wallet balance. Split into
+    // two unambiguous fields:
+    //   - billing: credits held by Run402 (available + held), null if no account
+    //   - wallet_balance_usd_micros: on-chain USDC/pathUSD, null if RPC fails
+    billing: billing && billing.exists
       ? { available_usd_micros: billing.available_usd_micros, held_usd_micros: billing.held_usd_micros }
       : null,
-    projects: remote?.projects || Object.keys(store.projects).map(id => ({ id })),
+    wallet_balance_usd_micros: walletBalance,
+    projects,
     active_project: activeId || null,
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.34.2",
+  "version": "1.35.1",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {