run402 1.35.0 → 1.35.2

package/lib/blob.mjs

@@ -34,7 +34,7 @@ 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";
+import { resolveProject, API } from "./config.mjs";
 
 const HELP = `run402 blob — Direct-to-S3 blob storage
 
@@ -97,13 +97,6 @@ function parseArgs(args) {
   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);

package/lib/deploy.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { Agent, fetch as undiciFetch } from "undici";
-import { API, allowanceAuthHeaders, findProject } from "./config.mjs";
+import { API, allowanceAuthHeaders, resolveProjectId } from "./config.mjs";
 import { resolveFilePathsInManifest, resolveMigrationsFile } from "./manifest.mjs";
 
 // Custom undici dispatcher with longer timeouts for large-batch deploys.
@@ -158,6 +158,91 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf-8");
 }
 
+/**
+ * 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.
+ *
+ * The returned error shape (GH-44):
+ *   { status: "error", message, field, path?, hint? }
+ * where `field` is one of: "manifest", "stdin", "migrations_file", "files[<i>].path".
+ */
+async function loadManifest(opts) {
+  let raw;
+  let baseDir = null;
+
+  // Step 1: read the manifest source.
+  if (opts.manifest) {
+    const manifestAbs = resolve(opts.manifest);
+    baseDir = dirname(manifestAbs);
+    try {
+      raw = readFileSync(opts.manifest, "utf-8");
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        return { error: {
+          status: "error",
+          message: `File not found: ${manifestAbs}`,
+          field: "manifest",
+          path: manifestAbs,
+          hint: "Check that --manifest points to an existing JSON file.",
+        } };
+      }
+      return { error: {
+        status: "error",
+        message: err && err.message ? err.message : String(err),
+        field: "manifest",
+        path: manifestAbs,
+        ...(err && err.code ? { code: err.code } : {}),
+      } };
+    }
+  } else {
+    raw = await readStdin();
+  }
+
+  // Step 2: parse JSON.
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch (err) {
+    return { error: {
+      status: "error",
+      message: `Manifest is not valid JSON: ${err.message}`,
+      field: opts.manifest ? "manifest" : "stdin",
+      ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
+    } };
+  }
+
+  // Step 3: resolve file paths (only when reading from a manifest file — we
+  // can't resolve relative paths without a baseDir).
+  if (opts.manifest) {
+    try {
+      resolveMigrationsFile(manifest, baseDir);
+      resolveFilePathsInManifest(manifest, baseDir);
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        return { error: {
+          status: "error",
+          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}).`,
+        } };
+      }
+      return { error: {
+        status: "error",
+        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 } : {}),
+      } };
+    }
+  }
+
+  return { manifest };
+}
+
 export async function run(args) {
   const opts = { manifest: null, project: null };
   for (let i = 0; i < args.length; i++) {
@@ -166,21 +251,42 @@ export async function run(args) {
     if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
   }
 
-  const raw = opts.manifest ? readFileSync(opts.manifest, "utf-8") : await readStdin();
-  const manifest = JSON.parse(raw);
-  if (opts.manifest) {
-    const baseDir = dirname(resolve(opts.manifest));
-    resolveMigrationsFile(manifest, baseDir);
-    resolveFilePathsInManifest(manifest, baseDir);
+  // Load + parse the manifest. Errors here (missing --manifest path, malformed
+  // JSON, or any referenced files[].path / migrations_file that doesn't exist)
+  // must be surfaced as structured JSON on stderr — never as a raw Node stack
+  // trace (GH-44). The CLI is agent-first; stack traces break JSON consumers.
+  const manifestResult = await loadManifest(opts);
+  if (manifestResult.error) {
+    console.error(JSON.stringify(manifestResult.error));
+    process.exit(1);
+  }
+  const manifest = manifestResult.manifest;
+
+  // If both sources set project_id and they disagree, refuse to deploy rather
+  // than silently shipping to the wrong target. Agents and humans should be
+  // forced to be explicit when the two sources conflict (GH-42).
+  if (opts.project && manifest.project_id && opts.project !== manifest.project_id) {
+    const err = {
+      status: "error",
+      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);
   }
 
-  // --project flag overrides manifest's project_id
+  // --project flag fills in manifest's project_id when the manifest doesn't
+  // specify one. (When both are set they must already agree — enforced above.)
   if (opts.project) manifest.project_id = opts.project;
 
-  // If no project_id in manifest, use active project
+  // If no project_id in manifest, fall back to the active project.
+  // resolveProjectId() returns the active project id when its argument is
+  // falsy, and emits a clear error + exits non-zero when no active project
+  // is set either.
   if (!manifest.project_id) {
-    const { id } = findProject(null);
-    manifest.project_id = id;
+    manifest.project_id = resolveProjectId(null);
   }
 
   // Remove legacy 'name' field if present

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/manifest.mjs

@@ -11,6 +11,12 @@ const TEXT_EXTS = new Set([
  * read the SQL from that file path and set `migrations` to its contents.
  * `migrations_file` is resolved relative to `baseDir`.
  *
+ * On read failure, re-throws the underlying fs error with additional context
+ * attached:
+ *   err.field = "migrations_file"
+ *   err.absPath = <absolute path that was attempted>
+ * (the original Error.code / Error.message / Error.path are preserved).
+ *
  * @param {object} manifest  Parsed manifest JSON (mutated in place)
  * @param {string} baseDir   Directory to resolve relative paths from
  * @returns {object}         The same manifest object
@@ -18,7 +24,13 @@ const TEXT_EXTS = new Set([
 export function resolveMigrationsFile(manifest, baseDir) {
   if (!manifest.migrations_file) return manifest;
   const abs = resolve(baseDir, manifest.migrations_file);
-  manifest.migrations = readFileSync(abs, "utf-8");
+  try {
+    manifest.migrations = readFileSync(abs, "utf-8");
+  } catch (err) {
+    err.field = "migrations_file";
+    err.absPath = abs;
+    throw err;
+  }
   delete manifest.migrations_file;
   return manifest;
 }
@@ -31,6 +43,12 @@ export function resolveMigrationsFile(manifest, baseDir) {
  *
  * Entries with `data` already set are left untouched.
  *
+ * On read failure, re-throws the underlying fs error with additional context
+ * attached:
+ *   err.field = `files[<i>].path`
+ *   err.absPath = <absolute path that was attempted>
+ * (the original Error.code / Error.message / Error.path are preserved).
+ *
  * @param {object} manifest  Parsed manifest JSON (mutated in place)
  * @param {string} baseDir   Directory to resolve relative paths from
  * @returns {object}         The same manifest object
@@ -38,18 +56,25 @@ export function resolveMigrationsFile(manifest, baseDir) {
 export function resolveFilePathsInManifest(manifest, baseDir) {
   if (!Array.isArray(manifest.files)) return manifest;
 
-  for (const entry of manifest.files) {
+  for (let i = 0; i < manifest.files.length; i++) {
+    const entry = manifest.files[i];
     if (!entry.path || entry.data !== undefined) continue;
 
     const abs = resolve(baseDir, entry.path);
     const ext = extname(abs).toLowerCase();
     const isText = TEXT_EXTS.has(ext);
 
-    if (isText) {
-      entry.data = readFileSync(abs, "utf-8");
-    } else {
-      entry.data = readFileSync(abs).toString("base64");
-      entry.encoding = "base64";
+    try {
+      if (isText) {
+        entry.data = readFileSync(abs, "utf-8");
+      } else {
+        entry.data = readFileSync(abs).toString("base64");
+        entry.encoding = "base64";
+      }
+    } catch (err) {
+      err.field = `files[${i}].path`;
+      err.absPath = abs;
+      throw err;
     }
 
     // If no explicit file (deploy target name), use the path value

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.35.0",
+  "version": "1.35.2",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {