run402 1.36.0 → 1.37.0

package/lib/projects.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "fs";
-import { findProject, loadKeyStore, saveProject, removeProject, API, allowanceAuthHeaders, setActiveProjectId, getActiveProjectId } from "./config.mjs";
+import { findProject, loadKeyStore, saveProject, removeProject, API, allowanceAuthHeaders, setActiveProjectId, getActiveProjectId, resolveProjectId } from "./config.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -11,17 +11,17 @@ Subcommands:
   provision [--tier <tier>] [--name <n>]  Provision a new Postgres project (pays via x402)
   use   <id>                              Set the active project (used as default for other commands)
   list                                    List all your projects (IDs, URLs, active marker)
-  info  <id>                              Show project details: REST URL, keys
-  keys  <id>                              Print anon_key and service_key as JSON
-  sql   <id> "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
-  rest  <id> <table> [params]             Query a table via the REST API (PostgREST)
-  usage <id>                              Show compute/storage usage for a project
-  schema <id>                             Inspect the database schema
-  rls   <id> <template> <tables_json>     Apply Row-Level Security policies
-  delete <id>                             Immediately and irreversibly delete a project (cascade purge) and remove from local state
-  pin   <id>                              Pin a project (prevents expiry/GC)
-  promote-user <id> <email>               Promote a user to project_admin role
-  demote-user  <id> <email>               Demote a user from project_admin role
+  info  [id]                              Show project details: REST URL, keys
+  keys  [id]                              Print anon_key and service_key as JSON
+  sql   [id] "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
+  rest  [id] <table> [params]             Query a table via the REST API (PostgREST)
+  usage [id]                              Show compute/storage usage for a project
+  schema [id]                             Inspect the database schema
+  rls   [id] <template> <tables_json>     Apply Row-Level Security policies
+  delete [id]                             Immediately and irreversibly delete a project (cascade purge) and remove from local state
+  pin   [id]                              Pin a project (prevents expiry/GC)
+  promote-user [id] <email>               Promote a user to project_admin role
+  demote-user  [id] <email>               Demote a user from project_admin role
 
 Examples:
   run402 projects quote
@@ -41,8 +41,10 @@ Examples:
   run402 projects delete abc123
 
 Notes:
-  - <id> is the project_id shown in 'run402 projects list'
-  - Most commands that take <id> default to the active project if omitted
+  - <id> is the project_id shown in 'run402 projects list' (prefix: 'prj_')
+  - Most commands that take <id> default to the active project when omitted
+    (set it with 'run402 projects use <id>'). Project IDs start with 'prj_';
+    any first positional that doesn't is treated as the next argument instead.
   - 'rest' uses PostgREST query syntax (table name + optional query string)
   - 'provision' requires a funded allowance — payment is automatic via x402
   - RLS templates (prefer user_owns_rows for user-scoped data):
@@ -52,6 +54,48 @@ Notes:
                                         that includes "i_understand_this_is_unrestricted": true
 `;
 
+const SUB_HELP = {
+  provision: `run402 projects provision — Provision a new Postgres project
+
+Usage:
+  run402 projects provision [--tier <tier>] [--name <name>]
+
+Options:
+  --tier <tier>       Tier for the new project (default: prototype)
+  --name <name>       Human-readable name for the project
+
+Notes:
+  - Payment is automatic via x402; requires a funded allowance
+  - The new project becomes the active project after provisioning
+
+Examples:
+  run402 projects provision
+  run402 projects provision --tier prototype
+  run402 projects provision --tier hobby --name my-app
+`,
+  sql: `run402 projects sql — Run a SQL query against a project's database
+
+Usage:
+  run402 projects sql [id] "<query>" [options]
+  run402 projects sql [id] --file <path> [options]
+
+Arguments:
+  [id]                Project ID (defaults to the active project if omitted;
+                      must start with 'prj_' — any other first arg is treated
+                      as the query instead)
+  <query>             Inline SQL query (quote it to preserve spaces)
+
+Options:
+  --file <path>       Read SQL from a file instead of an inline query
+  --params '<json>'   JSON array of parameters for a parameterized query
+
+Examples:
+  run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects sql abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
+  run402 projects sql abc123 --file setup.sql
+`,
+};
+
 async function quote() {
   const res = await fetch(`${API}/tiers/v1`);
   const data = await res.json();
@@ -73,8 +117,34 @@ async function provision(args) {
     headers: { "Content-Type": "application/json", ...authHeaders },
     body: JSON.stringify(body),
   });
-  const data = await res.json();
-  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  // Content-type aware parsing: gateways (ALB, CloudFront, etc.) return HTML on
+  // 502/504/etc., which would otherwise crash res.json() with SyntaxError (GH-84).
+  const contentType = res.headers.get("content-type") || "";
+  let data = null;
+  let parseError = null;
+  let bodyText = null;
+  if (contentType.includes("application/json")) {
+    try {
+      data = await res.json();
+    } catch (e) {
+      parseError = e;
+      try { bodyText = await res.text(); } catch { bodyText = ""; }
+    }
+  } else {
+    try { bodyText = await res.text(); } catch { bodyText = ""; }
+  }
+  if (!res.ok || parseError || data === null) {
+    const err = { status: "error", http: res.status, content_type: contentType || null };
+    if (data && typeof data === "object") {
+      Object.assign(err, data);
+    } else {
+      const preview = typeof bodyText === "string" ? bodyText.slice(0, 500) : "";
+      err.body_preview = preview;
+      if (parseError) err.parse_error = "response body was not valid JSON";
+    }
+    console.error(JSON.stringify(err));
+    process.exit(1);
+  }
   // Save project credentials locally and set as active
   if (data.project_id) {
     saveProject(data.project_id, {
@@ -231,13 +301,26 @@ async function deleteProject(projectId) {
   }
 }
 
+// Resolve a positional project_id argument with active-project fallback (GH-102).
+// Heuristic: real project IDs start with "prj_". If args[0] is missing OR
+// doesn't start with "prj_", fall back to the active project and return the
+// full args array as remaining positionals. Otherwise consume args[0] as the
+// project_id and return args.slice(1) as remaining positionals.
+function resolvePositionalProject(args) {
+  const first = Array.isArray(args) ? args[0] : undefined;
+  if (typeof first === "string" && first.startsWith("prj_")) {
+    return { projectId: first, rest: args.slice(1) };
+  }
+  return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
+}
+
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') {
     console.log(HELP);
     process.exit(0);
   }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   switch (sub) {
@@ -245,17 +328,17 @@ export async function run(sub, args) {
     case "provision": await provision(args); break;
     case "use":       await use(args[0]); break;
     case "list":      await list(); break;
-    case "info":      await info(args[0]); break;
-    case "keys":      await keys(args[0]); break;
-    case "sql":       await sqlCmd(args[0], args.slice(1)); break;
-    case "rest":      await rest(args[0], args[1], args[2]); break;
-    case "usage":     await usage(args[0]); break;
-    case "schema":    await schema(args[0]); break;
-    case "rls":       await rls(args[0], args[1], args[2]); break;
-    case "delete":    await deleteProject(args[0]); break;
-    case "pin":          await pin(args[0]); break;
-    case "promote-user": await promoteUser(args[0], args[1]); break;
-    case "demote-user":  await demoteUser(args[0], args[1]); break;
+    case "info":      { const { projectId } = resolvePositionalProject(args); await info(projectId); break; }
+    case "keys":      { const { projectId } = resolvePositionalProject(args); await keys(projectId); break; }
+    case "sql":       { const { projectId, rest } = resolvePositionalProject(args); await sqlCmd(projectId, rest); break; }
+    case "rest":      { const { projectId, rest: restArgs } = resolvePositionalProject(args); await rest(projectId, restArgs[0], restArgs[1]); break; }
+    case "usage":     { const { projectId } = resolvePositionalProject(args); await usage(projectId); break; }
+    case "schema":    { const { projectId } = resolvePositionalProject(args); await schema(projectId); break; }
+    case "rls":       { const { projectId, rest } = resolvePositionalProject(args); await rls(projectId, rest[0], rest[1]); break; }
+    case "delete":    { const { projectId } = resolvePositionalProject(args); await deleteProject(projectId); break; }
+    case "pin":       { const { projectId } = resolvePositionalProject(args); await pin(projectId); break; }
+    case "promote-user": { const { projectId, rest } = resolvePositionalProject(args); await promoteUser(projectId, rest[0]); break; }
+    case "demote-user":  { const { projectId, rest } = resolvePositionalProject(args); await demoteUser(projectId, rest[0]); break; }
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/secrets.mjs

@@ -22,6 +22,31 @@ Notes:
   - Values are write-only — list returns keys with a value_hash (first 8 hex chars of SHA-256) for verifying the correct value was set
 `;
 
+const SUB_HELP = {
+  set: `run402 secrets set — Set a secret on a project
+
+Usage:
+  run402 secrets set <id> <key> <value> [--file <path>]
+  run402 secrets set <id> <key> --file <path>
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+  <key>               Secret key name (exposed as process.env.<key>)
+  <value>             Inline secret value (omit if using --file)
+
+Options:
+  --file <path>       Read the secret value from a file instead of inline
+
+Notes:
+  - Secrets are injected as process.env in serverless functions
+  - Values are write-only; 'list' returns a value_hash for verification
+
+Examples:
+  run402 secrets set abc123 STRIPE_KEY sk-1234
+  run402 secrets set abc123 TLS_CERT --file cert.pem
+`,
+};
+
 async function set(projectId, key, args = []) {
   const p = findProject(projectId);
   let file = null;
@@ -69,7 +94,7 @@ async function deleteSecret(projectId, key) {
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   switch (sub) {

package/lib/sender-domain.mjs

@@ -117,6 +117,7 @@ async function inboundToggle(action, args) {
 
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(HELP); process.exit(0); }
   switch (sub) {
     case "register": await register(args); break;
     case "status": await status(args); break;

package/lib/service.mjs

@@ -17,15 +17,15 @@ async function fetchAndEmit(path) {
   try {
     res = await fetch(`${API}${path}`);
   } catch (err) {
-    console.log(JSON.stringify({ error: "fetch_failed", message: err?.message || String(err) }));
-    return;
+    console.error(JSON.stringify({ status: "error", message: err?.message || String(err) }));
+    process.exit(1);
   }
   const text = await res.text();
   let body;
   try { body = JSON.parse(text); } catch { body = text; }
   if (!res.ok) {
-    console.log(JSON.stringify({ error: "non_2xx", status: res.status, body }, null, 2));
-    return;
+    console.error(JSON.stringify({ status: "error", http: res.status, body }));
+    process.exit(1);
   }
   console.log(JSON.stringify(body, null, 2));
 }

package/lib/sites.mjs

@@ -45,6 +45,41 @@ Notes:
   - Free with active tier — requires allowance auth
 `;
 
+const SUB_HELP = {
+  deploy: `run402 sites deploy — Deploy a static site from a manifest
+
+Usage:
+  run402 sites deploy --manifest <file> [--project <id>] [--target <target>] [--inherit]
+  cat manifest.json | run402 sites deploy [--project <id>] [--target <target>]
+
+Options:
+  --manifest <file>   Path to manifest JSON file (or read from stdin)
+  --project <id>      Project ID (defaults to the active project)
+  --target <target>   Deployment target (e.g. 'production')
+  --inherit           Copy unchanged files from the previous deployment
+                      (only upload changed files)
+
+Manifest format (JSON):
+  {
+    "files": [
+      { "file": "index.html", "data": "<html>...</html>" },
+      { "file": "style.css", "path": "./dist/style.css" }
+    ]
+  }
+  Paths are resolved relative to the manifest file's directory.
+  Binary files are auto-detected and base64-encoded.
+
+Notes:
+  - Must include at least index.html in the files array
+  - Free with active tier — requires allowance auth
+
+Examples:
+  run402 sites deploy --manifest site.json
+  run402 sites deploy --manifest site.json --target production --inherit
+  cat site.json | run402 sites deploy
+`,
+};
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -96,6 +131,7 @@ async function status(args) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "deploy":  await deploy(args); break;
     case "status":  await status(args); break;

package/lib/storage.mjs

@@ -25,6 +25,29 @@ Notes:
   - Upload reads from --file or stdin if no --file is given
 `;
 
+const SUB_HELP = {
+  upload: `run402 storage upload — Upload a file to a project's storage bucket
+
+Usage:
+  run402 storage upload <id> <bucket> <path> [--file <local>] [--content-type <mime>]
+  echo "..." | run402 storage upload <id> <bucket> <path> [--content-type <mime>]
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+  <bucket>            Target bucket name
+  <path>              Destination path within the bucket
+
+Options:
+  --file <local>      Local file to upload; if omitted, content is read from stdin
+  --content-type <mime>  MIME type of the upload (default: text/plain)
+
+Examples:
+  run402 storage upload abc123 assets logo.png --file ./logo.png \\
+    --content-type image/png
+  echo "hello" | run402 storage upload abc123 data notes.txt
+`,
+};
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -88,6 +111,7 @@ async function list(projectId, bucket) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "upload":   await upload(args[0], args[1], args[2], args.slice(3)); break;
     case "download": await download(args[0], args[1], args[2]); break;

package/lib/subdomains.mjs

@@ -24,6 +24,31 @@ Notes:
   - Creates <name>.run402.com pointing to the deployment
 `;
 
+const SUB_HELP = {
+  claim: `run402 subdomains claim — Claim a custom subdomain for a deployment
+
+Usage:
+  run402 subdomains claim <name> [--project <id>] [--deployment <id>]
+
+Arguments:
+  <name>              Subdomain name (3-63 chars, lowercase alphanumeric +
+                      hyphens). Creates <name>.run402.com.
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+  --deployment <id>   Deployment ID to point at (defaults to the project's
+                      last deployment)
+
+Notes:
+  - Legacy syntax 'claim <deployment_id> <name>' is still supported
+  - Deploy a site first (or pass --deployment) so there is a target to claim
+
+Examples:
+  run402 subdomains claim myapp
+  run402 subdomains claim myapp --deployment dpl_abc123 --project proj123
+`,
+};
+
 async function claim(positionalArgs, flagArgs) {
   const opts = { project: null, deployment: null };
   for (let i = 0; i < flagArgs.length; i++) {
@@ -85,6 +110,7 @@ async function list(projectId) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "claim": {
       const positional = [];

package/lib/tier.mjs

@@ -29,7 +29,14 @@ async function status() {
   const res = await fetch(`${API}/tiers/v1/status`, {
     headers: { ...authHeaders },
   });
-  const data = await res.json();
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    console.error(JSON.stringify({ status: "error", http: res.status, message: "Non-JSON response from server", body: text.slice(0, 500) }));
+    process.exit(1);
+  }
   if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
   console.log(JSON.stringify(data, null, 2));
 }

package/lib/webhooks.mjs

@@ -21,6 +21,47 @@ Examples:
   run402 email webhooks delete whk_123
 `;
 
+const SUB_HELP = {
+  update: `run402 email webhooks update — Update an existing webhook
+
+Usage:
+  run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--project <id>]
+
+Arguments:
+  <webhook_id>        Webhook ID to update
+
+Options:
+  --url <url>         New delivery URL for the webhook
+  --events <e1,e2>    Comma-separated event list to replace the current events
+                      Valid: delivery, bounced, complained, reply_received
+  --project <id>      Project ID (defaults to the active project)
+
+Notes:
+  - Provide at least one of --url or --events
+
+Examples:
+  run402 email webhooks update whk_123 --url https://new.example.com/hook
+  run402 email webhooks update whk_123 --events delivery,bounced
+`,
+  register: `run402 email webhooks register — Register a new webhook
+
+Usage:
+  run402 email webhooks register --url <url> --events <e1,e2> [--project <id>]
+
+Options:
+  --url <url>         Delivery URL for the webhook (required)
+  --events <e1,e2>    Comma-separated event list (required)
+                      Valid: delivery, bounced, complained, reply_received
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 email webhooks register --url https://example.com/hook \\
+    --events delivery,bounced
+  run402 email webhooks register --url https://example.com/hook \\
+    --events reply_received --project proj123
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -207,6 +248,7 @@ async function register(args) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "list":     await list(args); break;
     case "get":      await get(args); break;

package/package.json

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