run402 1.54.2 → 1.54.3

package/lib/functions.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs";
+import { readFileSync, existsSync, statSync } from "fs";
 import { findProject, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
@@ -141,6 +141,29 @@ Examples:
   run402 functions update prj_abc123 send-reminders --schedule '0 */4 * * *'
   run402 functions update prj_abc123 send-reminders --schedule-remove
   run402 functions update prj_abc123 my-func --timeout 15 --memory 256
+`,
+  list: `run402 functions list — List all functions for a project
+
+Usage:
+  run402 functions list <project_id>
+
+Arguments:
+  <project_id>        Target project ID
+
+Examples:
+  run402 functions list prj_abc123
+`,
+  delete: `run402 functions delete — Delete a function from a project
+
+Usage:
+  run402 functions delete <project_id> <name>
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name to delete
+
+Examples:
+  run402 functions delete prj_abc123 stripe-webhook
 `,
 };
 
@@ -158,6 +181,24 @@ async function deploy(projectId, name, args) {
   if (!opts.file) {
     fail({ code: "BAD_USAGE", message: "Missing --file <file>" });
   }
+  if (!existsSync(opts.file)) {
+    fail({
+      code: "FILE_NOT_FOUND",
+      message: `File not found: ${opts.file}`,
+      field: "--file",
+      path: opts.file,
+      hint: "Check that --file points to an existing source file.",
+    });
+  }
+  const stat = statSync(opts.file);
+  if (!stat.isFile()) {
+    fail({
+      code: "NOT_A_FILE",
+      message: `--file points to a ${stat.isDirectory() ? "directory" : "non-regular file"}: ${opts.file}`,
+      field: "--file",
+      path: opts.file,
+    });
+  }
   const code = readFileSync(opts.file, "utf-8");
 
   const deployOpts = { name, code };

package/lib/image.mjs

@@ -27,12 +27,44 @@ Notes:
   - Use --output to save directly to a file instead of printing base64
 `;
 
+const SUB_HELP = {
+  generate: `run402 image generate — Generate an AI image from a text prompt
+
+Usage:
+  run402 image generate "<prompt>" [options]
+
+Arguments:
+  <prompt>            Text prompt describing the image (quote it)
+
+Options:
+  --aspect <ratio>    Image aspect ratio: square | landscape | portrait
+                      (default: square)
+  --output <file>     Save image to file (e.g. output.png). If omitted,
+                      returns base64 JSON to stdout.
+
+Notes:
+  - Requires a funded allowance (run402 allowance create && run402 allowance fund)
+  - Payments are processed automatically via x402 micropayments
+  - Use --output to save directly to a file instead of printing base64
+
+Examples:
+  run402 image generate "a startup mascot, pixel art"
+  run402 image generate "futuristic city at night" --aspect landscape
+  run402 image generate "portrait of a cat CEO" --aspect portrait --output cat.png
+`,
+};
+
 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);
+  }
+
   if (sub !== "generate") {
     console.error(`Unknown subcommand: ${sub}\n`);
     console.log(HELP);
@@ -43,7 +75,7 @@ export async function run(sub, args) {
   let i = 0;
   if (i < args.length && !args[i].startsWith("--")) opts.prompt = args[i++];
   while (i < args.length) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(HELP); process.exit(0); }
+    if (args[i] === "--help" || args[i] === "-h") { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
     else if (args[i] === "--aspect" && args[i + 1]) { opts.aspect = args[++i]; }
     else if (args[i] === "--output" && args[i + 1]) { opts.output = args[++i]; }
     i++;

package/lib/message.mjs

@@ -10,21 +10,68 @@ Usage:
 Notes:
   - Requires an active tier (run402 tier set <tier>)
   - Requires an allowance (run402 allowance create)
+  - Messages are capped at 8 KB (8192 bytes UTF-8) to keep the developer
+    inbox useful and prevent payload-dump misuse. Trim or summarize long
+    content (e.g. stack traces) before sending.
 
 Examples:
   run402 message send "Hello from my agent!"
 `;
 
+// Cap message body at a Twitter-ish but engineer-generous size: enough for
+// a few paragraphs and a stack-trace excerpt, small enough that a misbehaving
+// agent script can't dump arbitrary content into the developer inbox in one
+// call. UTF-8 bytes (not characters) — emoji and accented chars count as
+// multiple bytes.
+const MESSAGE_MAX_BYTES = 8192;
+
+const SUB_HELP = {
+  send: `run402 message send — Send a message to Run402 developers
+
+Usage:
+  run402 message send <text>
+
+Arguments:
+  <text>              Message body (quote it; remaining args are joined with
+                      spaces if multiple positional words are provided)
+
+Notes:
+  - Requires an active tier (run402 tier set <tier>)
+  - Requires an allowance (run402 allowance create)
+  - Messages are capped at 8 KB (8192 bytes UTF-8) to keep the developer
+    inbox useful and prevent payload-dump misuse.
+
+Examples:
+  run402 message send "Hello from my agent!"
+`,
+};
+
 async function send(text) {
-  if (!text) {
+  if (!text || typeof text !== "string") {
     fail({ code: "BAD_USAGE", message: "Missing message text." });
   }
+  // Cap check runs BEFORE the allowance check so oversized payloads surface
+  // a structured size error instead of being masked by a missing-allowance
+  // exit.
+  const bytes = Buffer.byteLength(text, "utf-8");
+  if (bytes > MESSAGE_MAX_BYTES) {
+    fail({
+      code: "MESSAGE_TOO_LONG",
+      message: `Message is ${bytes} bytes; maximum is ${MESSAGE_MAX_BYTES} bytes (~8 KB).`,
+      hint: "Trim or summarize the message.",
+      details: { bytes, max_bytes: MESSAGE_MAX_BYTES },
+    });
+  }
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/message/v1");
 
   try {
     await getSdk().admin.sendMessage(text);
-    console.log(JSON.stringify({ status: "ok", message: "Message sent to Run402 developers." }));
+    console.log(JSON.stringify({
+      status: "ok",
+      message: "Message sent to Run402 developers.",
+      bytes_sent: bytes,
+    }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -33,7 +80,7 @@ async function send(text) {
 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);
   }
   if (sub !== "send") {

package/lib/projects.mjs

@@ -2,7 +2,7 @@ import { readFileSync } from "fs";
 import { findProject, loadKeyStore, API, allowanceAuthHeaders, resolveProjectId, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
-import { assertKnownFlags, failBadProjectId, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, failBadProjectId, hasHelp, normalizeArgv, positionalArgs, resolvePositionalProject } from "./argparse.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -123,7 +123,37 @@ async function provision(args) {
   const opts = { tier: "prototype", name: undefined };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
-    if (args[i] === "--name" && args[i + 1]) opts.name = args[++i];
+    // Use !== undefined so an empty-string value is captured (and rejected
+    // below) rather than silently dropped by the falsy-check pattern (GH-176).
+    if (args[i] === "--name" && args[i + 1] !== undefined) opts.name = args[++i];
+  }
+  // Validate --name when provided. Omitted --name lets the server pick a
+  // default. The same envelope should also be enforced server-side (GH-176).
+  if (opts.name !== undefined) {
+    if (opts.name === "") {
+      fail({
+        code: "BAD_PROJECT_NAME",
+        message: "--name must not be empty.",
+        details: { field: "--name" },
+        hint: "Provide a 1-128 character name, or omit --name to use the server-assigned default.",
+      });
+    }
+    if (opts.name.length > 128) {
+      fail({
+        code: "BAD_PROJECT_NAME",
+        message: `--name must be 1-128 characters, got ${opts.name.length}.`,
+        details: { field: "--name", length: opts.name.length, max: 128 },
+      });
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(opts.name)) {
+      fail({
+        code: "BAD_PROJECT_NAME",
+        message: "--name contains control characters (newline, tab, etc).",
+        details: { field: "--name" },
+        hint: "Project names should be a single-line label.",
+      });
+    }
   }
   // Preserve the aggressive early exit when no allowance is configured —
   // gives the user a more specific prompt than the SDK's 401/402 path.
@@ -259,6 +289,13 @@ async function sqlCmd(projectId, args = []) {
 }
 
 async function rest(projectId, table, queryParams) {
+  if (!table) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <table> argument. Usage: run402 projects rest [id] <table> [\"<query>\"]",
+      hint: "Run 'run402 projects schema <id>' to list tables.",
+    });
+  }
   const p = findProject(projectId);
   const res = await fetch(`${API}/rest/v1/${table}${queryParams ? '?' + queryParams : ''}`, { headers: { "apikey": p.anon_key } });
   const data = await res.json();
@@ -373,35 +410,6 @@ async function deleteProject(projectId, args = []) {
   }
 }
 
-// Resolve a positional project_id argument with active-project fallback (GH-102).
-// Callers can tighten the legacy shorthand when a bare non-prj positional is
-// more likely a mistyped project id than an argument for the active project.
-function resolvePositionalProject(args, opts = {}) {
-  const first = Array.isArray(args) ? args[0] : undefined;
-  if (typeof first === "string" && first.startsWith("prj_")) {
-    return { projectId: first, rest: args.slice(1) };
-  }
-  if (
-    typeof first === "string" &&
-    first.length > 0 &&
-    !first.startsWith("-") &&
-    Array.isArray(opts.rejectBareFirstWhenFlagPresent) &&
-    opts.rejectBareFirstWhenFlagPresent.some((flag) => args.includes(flag))
-  ) {
-    failBadProjectId(first);
-  }
-  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.rejectBareFirst) {
-    failBadProjectId(first);
-  }
-  if (typeof first === "string" && first.length > 0 && !first.startsWith("-") && opts.maxBarePositionals !== undefined) {
-    const bare = positionalArgs(args, opts.valueFlags ?? []);
-    if (bare.length > opts.maxBarePositionals) {
-      failBadProjectId(first);
-    }
-  }
-  return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
-}
-
 const FLAGS_BY_SUB = {
   provision: { known: ["--tier", "--name"], values: ["--tier", "--name"] },
   sql: { known: ["--file", "--params"], values: ["--file", "--params"] },

package/lib/sdk-errors.mjs

@@ -29,7 +29,7 @@
  * validation: the call wasn't sent, so retrying is safe and won't help unless
  * the user fixes input.
  */
-export function fail({ message, code, hint, details, next_actions, retryable = false, safe_to_retry = true, exit_code = 1 } = {}) {
+export function fail({ message, code, hint, details, next_actions, field, retryable = false, safe_to_retry = true, exit_code = 1 } = {}) {
   const envelope = {
     status: "error",
     code: code ?? "BAD_USAGE",
@@ -39,6 +39,7 @@ export function fail({ message, code, hint, details, next_actions, retryable = f
   };
   if (hint !== undefined) envelope.hint = hint;
   if (details !== undefined) envelope.details = details;
+  if (field !== undefined) envelope.field = field;
   envelope.next_actions = Array.isArray(next_actions) ? next_actions : [];
   envelope.trace_id = null;
   console.error(JSON.stringify(envelope));

package/lib/secrets.mjs

@@ -45,6 +45,33 @@ Notes:
 Examples:
   run402 secrets set prj_abc123 STRIPE_KEY sk-1234
   run402 secrets set prj_abc123 TLS_CERT --file cert.pem
+`,
+  list: `run402 secrets list — List all secrets for a project
+
+Usage:
+  run402 secrets list <id>
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+
+Notes:
+  - Returns secret keys with a value_hash (first 8 hex chars of SHA-256)
+    for verifying the correct value was set; raw values are write-only
+
+Examples:
+  run402 secrets list prj_abc123
+`,
+  delete: `run402 secrets delete — Delete a secret from a project
+
+Usage:
+  run402 secrets delete <id> <key>
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+  <key>               Secret key name to remove
+
+Examples:
+  run402 secrets delete prj_abc123 STRIPE_KEY
 `,
 };
 

package/lib/sender-domain.mjs

@@ -22,6 +22,83 @@ Examples:
   run402 sender-domain inbound-disable kysigned.com
 `;
 
+const SUB_HELP = {
+  register: `run402 sender-domain register — Register a custom sender domain
+
+Usage:
+  run402 sender-domain register <domain> [--project <id>]
+
+Arguments:
+  <domain>            Custom sender domain (e.g. kysigned.com)
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Notes:
+  - Returns DNS records (DKIM, SPF, DMARC) to add at your DNS provider
+  - Use 'run402 sender-domain status' to poll until verified
+
+Examples:
+  run402 sender-domain register kysigned.com
+  run402 sender-domain register kysigned.com --project prj_abc123
+`,
+  status: `run402 sender-domain status — Check verification status of the project's sender domain
+
+Usage:
+  run402 sender-domain status [--project <id>]
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 sender-domain status
+  run402 sender-domain status --project prj_abc123
+`,
+  remove: `run402 sender-domain remove — Remove the project's custom sender domain
+
+Usage:
+  run402 sender-domain remove [--project <id>]
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 sender-domain remove
+  run402 sender-domain remove --project prj_abc123
+`,
+  "inbound-enable": `run402 sender-domain inbound-enable — Enable inbound email for a sender domain
+
+Usage:
+  run402 sender-domain inbound-enable <domain> [--project <id>]
+
+Arguments:
+  <domain>            Custom sender domain to enable inbound on
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Notes:
+  - Requires the domain to be DKIM-verified first
+
+Examples:
+  run402 sender-domain inbound-enable kysigned.com
+`,
+  "inbound-disable": `run402 sender-domain inbound-disable — Disable inbound email for a sender domain
+
+Usage:
+  run402 sender-domain inbound-disable <domain> [--project <id>]
+
+Arguments:
+  <domain>            Custom sender domain to disable inbound on
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 sender-domain inbound-disable kysigned.com
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -106,7 +183,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); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "register": await register(args); break;
     case "status": await status(args); break;

package/lib/service.mjs

@@ -13,6 +13,35 @@ Notes:
     balance, tier, projects), use 'run402 status'.
 `;
 
+const SUB_HELP = {
+  status: `run402 service status — Public service availability report
+
+Usage:
+  run402 service status
+
+Notes:
+  - Unauthenticated and free; no allowance required
+  - Returns uptime, supported capabilities, operator, and deployment info
+  - For account state (allowance, balance, tier, projects), use
+    'run402 status' instead
+
+Examples:
+  run402 service status
+`,
+  health: `run402 service health — Service liveness check
+
+Usage:
+  run402 service health
+
+Notes:
+  - Unauthenticated and free; no allowance required
+  - Returns per-dependency status and the deployed version
+
+Examples:
+  run402 service health
+`,
+};
+
 async function status() {
   try {
     const data = await getSdk().service.status();
@@ -34,7 +63,7 @@ async function health() {
 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/subdomains.mjs

@@ -48,6 +48,35 @@ Notes:
 Examples:
   run402 subdomains claim myapp
   run402 subdomains claim myapp --deployment dpl_abc123 --project prj_abc123
+`,
+  list: `run402 subdomains list — List subdomains claimed by a project
+
+Usage:
+  run402 subdomains list [<id>]
+
+Arguments:
+  <id>                Project ID (defaults to the active project)
+
+Examples:
+  run402 subdomains list
+  run402 subdomains list prj_abc123
+`,
+  delete: `run402 subdomains delete — Release a claimed subdomain
+
+Usage:
+  run402 subdomains delete <name> --confirm [--project <id>]
+
+Arguments:
+  <name>              Subdomain name to release
+
+Options:
+  --confirm           Required: releasing a subdomain is irreversible and
+                      makes it available for any other project to claim
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 subdomains delete myapp --confirm
+  run402 subdomains delete myapp --confirm --project prj_abc123
 `,
 };
 

package/lib/tier.mjs

@@ -24,6 +24,46 @@ Examples:
   run402 tier set hobby
 `;
 
+const SUB_HELP = {
+  status: `run402 tier status — Show current tier subscription state
+
+Usage:
+  run402 tier status
+
+Notes:
+  - Returns the current tier name, status, and expiry
+  - Use 'run402 tier set <tier>' to subscribe, renew, or upgrade
+
+Examples:
+  run402 tier status
+`,
+  set: `run402 tier set — Subscribe, renew, or upgrade your tier
+
+Usage:
+  run402 tier set <tier>
+
+Arguments:
+  <tier>              One of: prototype, hobby, team
+
+Tiers:
+  prototype           $0.10/7d (free with testnet faucet)
+  hobby               $5/30d
+  team                $20/30d
+
+Notes:
+  Server auto-detects action based on current allowance state:
+    - No tier or expired -> subscribe
+    - Same tier, active  -> renew (extends from expiry)
+    - Higher tier        -> upgrade (prorated refund to allowance)
+    - Lower tier, active -> rejected (wait for expiry)
+  Pays via x402 micropayments.
+
+Examples:
+  run402 tier set prototype
+  run402 tier set hobby
+`,
+};
+
 async function status() {
   try {
     const data = await getSdk().tier.status();
@@ -55,7 +95,7 @@ export async function run(sub, args) {
     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/webhooks.mjs

@@ -1,6 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { validateWebhookUrl } from "./argparse.mjs";
 
 const HELP = `run402 email webhooks — Manage mailbox webhooks
 
@@ -121,6 +122,11 @@ async function update(args) {
   if (!url && !eventsRaw) {
     fail({ code: "BAD_USAGE", message: "Provide at least --url or --events" });
   }
+  // GH-192: scheme-only local validation. Server-side SSRF defenses are out
+  // of scope for the CLI (private-IP / DNS rebinding / IMDS belongs on the
+  // gateway). `validateWebhookUrl` is a no-op when `url` is null/undefined,
+  // so partial updates that change only `--events` still work.
+  validateWebhookUrl(url, "--url");
 
   try {
     const data = await getSdk().email.webhooks.update(projectId, webhookId, {
@@ -146,6 +152,10 @@ async function register(args) {
       hint: "run402 email webhooks register --url <url> --events <e1,e2>",
     });
   }
+  // GH-192: validate scheme locally before any network call. Catches
+  // javascript:/file:/http:/data: schemes that the gateway would reject
+  // anyway, but with a friendlier round-trip-free error.
+  validateWebhookUrl(url, "--url");
   if (!eventsRaw) {
     fail({
       code: "BAD_USAGE",

package/package.json

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

package/sdk/core-dist/allowance-auth.js

@@ -87,6 +87,11 @@ export function formatSIWEMessage(opts, address) {
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
 export function getAllowanceAuthHeaders(path, allowancePath) {
+    // GH-194: readAllowance throws on a malformed-shape allowance file. The
+    // CLI's higher-level readAllowance wrapper surfaces this as a structured
+    // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
+    // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
+    // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
     const allowance = readAllowance(allowancePath);
     if (!allowance || !allowance.address || !allowance.privateKey)
         return null;