run402 1.54.2 → 1.54.4

package/lib/argparse.mjs

@@ -1,4 +1,6 @@
+import { existsSync, statSync } from "node:fs";
 import { fail } from "./sdk-errors.mjs";
+import { resolveProjectId } from "./config.mjs";
 
 export function normalizeArgv(argv = []) {
   const out = [];
@@ -99,6 +101,89 @@ export function failBadProjectId(value) {
   });
 }
 
+/**
+ * Validate a webhook URL: parse it locally and reject non-https:// schemes.
+ *
+ * Scope (GH-192): scheme-only validation. Reject `javascript:`, `file:`,
+ * `http:`, `data:`, `ftp:`, etc. before the request leaves the CLI process.
+ * Server-side SSRF defenses (private-IP filtering, DNS rebinding, IMDS
+ * blocking) live on the gateway, not here — this helper is the cheap
+ * client-side guard against the obvious classes.
+ *
+ * No-op when `url` is null/undefined/empty so callers can pass optional
+ * flag values directly. Required-vs-optional handling stays at the call
+ * site (e.g. `webhooks register` does its own missing-flag check first).
+ *
+ * On failure: `fail()` writes the canonical error envelope and exits 1.
+ *
+ * @param {string|null|undefined} url - The webhook URL to validate.
+ * @param {string} fieldName - The CLI flag name for the error envelope (e.g. "--url", "--webhook").
+ */
+export function validateWebhookUrl(url, fieldName = "--url") {
+  if (!url) return;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    fail({
+      code: "BAD_WEBHOOK_URL",
+      message: `${fieldName} is not a valid URL: ${JSON.stringify(url)}`,
+      field: fieldName,
+      hint: "Webhook URL must be a fully-qualified https:// URL.",
+      details: { flag: fieldName, value: url },
+    });
+  }
+  if (parsed.protocol !== "https:") {
+    fail({
+      code: "BAD_WEBHOOK_URL",
+      message: `${fieldName} must use https://, got ${parsed.protocol}`,
+      field: fieldName,
+      hint: "Webhook URLs must be https:// for transport security.",
+      details: { flag: fieldName, value: url, scheme: parsed.protocol },
+    });
+  }
+}
+
+/**
+ * Validate that a CLI flag pointing at a filesystem path resolves to an
+ * existing regular file. Replaces the GH-195 inline pattern that was
+ * duplicated across `functions deploy`, `secrets set`, `projects sql`,
+ * and `projects apply-expose` (GH-233).
+ *
+ * Without this guard, `readFileSync` against a missing path leaks a raw
+ * `node:fs` ENOENT/EISDIR stack to stderr (with the V8 source pointer),
+ * which violates the CLI's structured-error contract.
+ *
+ * No-op: this helper is meant to be called only when the flag is set.
+ * Callers handle the optional/required dichotomy themselves.
+ *
+ * On failure: `fail()` writes a `FILE_NOT_FOUND` or `NOT_A_FILE` envelope
+ * to stderr and exits 1.
+ *
+ * @param {string} path - The filesystem path captured from the flag.
+ * @param {string} fieldName - The flag name for the envelope (default "--file").
+ */
+export function validateRegularFile(path, fieldName = "--file") {
+  if (!existsSync(path)) {
+    fail({
+      code: "FILE_NOT_FOUND",
+      message: `File not found: ${path}`,
+      field: fieldName,
+      path,
+      hint: `Check that ${fieldName} points to an existing file.`,
+    });
+  }
+  const stat = statSync(path);
+  if (!stat.isFile()) {
+    fail({
+      code: "NOT_A_FILE",
+      message: `${fieldName} points to a ${stat.isDirectory() ? "directory" : "non-regular file"}: ${path}`,
+      field: fieldName,
+      path,
+    });
+  }
+}
+
 export function positionalArgs(args = [], flagsWithValues = []) {
   const valueFlags = new Set(flagsWithValues);
   const out = [];
@@ -114,6 +199,49 @@ export function positionalArgs(args = [], flagsWithValues = []) {
   return out;
 }
 
+// Resolve a positional project_id argument with active-project fallback (GH-102, GH-187).
+// If the first positional starts with "prj_", treat it as the project id and
+// strip it from the rest. Otherwise, fall through to the active project from
+// the keystore. 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.
+//
+// Options:
+//   rejectBareFirst:                   when true, error if the first positional
+//                                      is non-empty and doesn't start with "prj_".
+//   rejectBareFirstWhenFlagPresent:    when one of these flags is present in
+//                                      args AND the first positional doesn't
+//                                      start with "prj_", error out.
+//   maxBarePositionals + valueFlags:   when set, count the bare (non-flag)
+//                                      positionals using `positionalArgs(args,
+//                                      valueFlags)` and error if the count
+//                                      exceeds maxBarePositionals.
+export 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 : [] };
+}
+
 function closestFlag(flag, candidates) {
   let best = null;
   let bestDistance = Number.POSITIVE_INFINITY;

package/lib/auth.mjs

@@ -187,10 +187,23 @@ async function settings(args) {
       message: "Missing --allow-password-set <true|false>",
     });
   }
+  // Reject anything that isn't literally "true" or "false". Without this guard,
+  // the previous `=== "true"` coercion silently turned every other input
+  // (including "1", "yes", "TRUE", "bogus") into `false` and printed
+  // `{"status":"ok"}`, giving the user the OPPOSITE of what they likely
+  // intended for this security-adjacent flag. See GH-204.
+  if (allowPasswordSet !== "true" && allowPasswordSet !== "false") {
+    fail({
+      code: "BAD_FLAG",
+      message: "--allow-password-set must be 'true' or 'false'",
+      hint: "Use the literal strings 'true' or 'false'.",
+    });
+  }
 
+  const allow = allowPasswordSet === "true";
   try {
-    await getSdk().auth.settings(projectId, { allow_password_set: allowPasswordSet === "true" });
-    console.log(JSON.stringify({ status: "ok", allow_password_set: allowPasswordSet === "true" }));
+    await getSdk().auth.settings(projectId, { allow_password_set: allow });
+    console.log(JSON.stringify({ status: "ok", allow_password_set: allow }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/billing.mjs

@@ -84,6 +84,41 @@ Options:
 Examples:
   run402 billing history user@example.com
   run402 billing history 0x1234... --limit 100
+`,
+  balance: `run402 billing balance — Show balance for an email or wallet
+
+Usage:
+  run402 billing balance <identifier>
+
+Arguments:
+  <identifier>        Email address or wallet (0x...)
+
+Examples:
+  run402 billing balance user@example.com
+  run402 billing balance 0x1234abcd...
+`,
+  "create-email": `run402 billing create-email — Create an email billing account
+
+Usage:
+  run402 billing create-email <email>
+
+Arguments:
+  <email>             Email address to register as a billing account
+
+Examples:
+  run402 billing create-email user@example.com
+`,
+  "link-wallet": `run402 billing link-wallet — Link a wallet to an email billing account
+
+Usage:
+  run402 billing link-wallet <account_id> <wallet>
+
+Arguments:
+  <account_id>        Billing account ID (e.g. acct_abc123)
+  <wallet>            Wallet address (0x...) to link
+
+Examples:
+  run402 billing link-wallet acct_abc123 0x1234abcd...
 `,
 };
 

package/lib/config.mjs

@@ -14,8 +14,27 @@ export const ALLOWANCE_FILE = getAllowancePath();
 export const PROJECTS_FILE = getKeystorePath();
 export const API = getApiBase();
 
+/**
+ * Wraps core's `readAllowance()` and converts the malformed-shape throw
+ * (GH-194) into the canonical CLI failure envelope. Without this guard, every
+ * CLI subcommand that touches the allowance leaks a Node stack trace and
+ * source paths the moment a user has a malformed `allowance.json`.
+ *
+ * The unparseable-JSON case still returns `null` (matching the historical
+ * "no_allowance" UX); only valid-JSON-but-wrong-shape becomes a structured
+ * error with `code: BAD_ALLOWANCE_FILE`.
+ */
 export function readAllowance() {
-  return coreReadAllowance();
+  try {
+    return coreReadAllowance();
+  } catch (err) {
+    fail({
+      code: "BAD_ALLOWANCE_FILE",
+      message: err?.message ?? "allowance.json is malformed",
+      hint: "Back up ~/.config/run402/allowance.json and run 'run402 init' to recreate it.",
+      details: { path: ALLOWANCE_FILE },
+    });
+  }
 }
 
 export function saveAllowance(data) {

package/lib/contracts.mjs

@@ -83,6 +83,47 @@ Usage:
 
 Usage:
   run402 contracts delete <project_id> <wallet_id> --confirm
+`,
+  "get-wallet": `run402 contracts get-wallet — Get wallet metadata + live balance
+
+Usage:
+  run402 contracts get-wallet <project_id> <wallet_id>
+
+Arguments:
+  <project_id>        Project ID that owns the wallet
+  <wallet_id>         Wallet ID (e.g. cwlt_abc123)
+
+Examples:
+  run402 contracts get-wallet prj_abc123 cwlt_abc123
+`,
+  "list-wallets": `run402 contracts list-wallets — List all KMS wallets for a project
+
+Usage:
+  run402 contracts list-wallets <project_id>
+
+Arguments:
+  <project_id>        Project ID to list wallets for
+
+Notes:
+  - Includes deleted wallets
+
+Examples:
+  run402 contracts list-wallets prj_abc123
+`,
+  status: `run402 contracts status — Get a contract call's status and receipt
+
+Usage:
+  run402 contracts status <project_id> <call_id>
+
+Arguments:
+  <project_id>        Project ID that submitted the call
+  <call_id>           Contract call ID returned from 'contracts call'
+
+Notes:
+  - Returns status, gas used, gas cost (USD-micros), and receipt
+
+Examples:
+  run402 contracts status prj_abc123 ccall_abc123
 `,
 };
 

package/lib/deploy-v2.mjs

@@ -166,6 +166,43 @@ async function applyCmd(args) {
     });
   }
 
+  // GH-232: Reject empty specs client-side. Without this guard,
+  // `run402 deploy apply --spec '{}'` (and `--manifest <empty>`) would silently
+  // send an empty ReleaseSpec to /deploy/v2/plans with no signal that nothing
+  // was deployed. This mirrors the GH-185 guard already in place for the
+  // legacy `run402 deploy --manifest` path.
+  //
+  // `deploy apply` is v2-only — only meaningful keys are the v2 ReleaseSpec
+  // shape (database, site, functions, secrets, subdomains, domains).
+  // For object-typed sections the "container is non-empty" check isn't enough
+  // — `site:{replace:{}}` has one key but ships nothing. We recurse one level
+  // so any object whose own values are all empty containers is still empty.
+  const meaningful = ["database", "site", "functions", "secrets", "subdomains", "domains"];
+  function hasContent(v) {
+    if (v == null) return false;
+    if (Array.isArray(v)) return v.length > 0;
+    if (typeof v === "object") {
+      const keys = Object.keys(v);
+      if (keys.length === 0) return false;
+      return keys.some((k) => hasContent(v[k]));
+    }
+    if (typeof v === "string") return v.length > 0;
+    return true;
+  }
+  const hasMeaningfulContent = spec && typeof spec === "object" && !Array.isArray(spec) && meaningful.some((key) => hasContent(spec[key]));
+  if (!hasMeaningfulContent) {
+    fail({
+      code: "MANIFEST_EMPTY",
+      message: `Manifest contains no deployable sections. Expected at least one of: ${meaningful.join(", ")}`,
+      hint: "Did you mean to write a 'site.replace' or 'database.migrations' block? See https://run402.com/schemas/manifest.v1.json",
+      details: {
+        field: opts.manifest ? "manifest" : opts.spec ? "spec" : "stdin",
+        ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
+        meaningful_keys: meaningful,
+      },
+    });
+  }
+
   if (opts.manifest) resolveFileDataPaths(spec, dirname(resolve(opts.manifest)));
 
   if (opts.project && spec.project_id && spec.project_id !== opts.project) {

package/lib/deploy.mjs

@@ -16,77 +16,100 @@ Options:
   --project <id>       Project ID to deploy to     (default: active project)
   --help, -h           Show this help message
 
-Manifest format (JSON):
+Subcommands (recommended for new manifests):
+  run402 deploy apply --manifest <file>     unified deploy primitive (v1.34+)
+  run402 deploy resume <operation_id>       resume a stuck operation
+  run402 deploy list [--project <id>]       list recent deploy operations
+  run402 deploy events <operation_id>       fetch event stream for an operation
+
+Manifest format (JSON, v2 ReleaseSpec — recommended):
   {
     "project_id": "prj_...",
-    "migrations": "CREATE TABLE items (...)",
-    "migrations_file": "setup.sql",
-    "secrets": [{ "key": "OPENAI_API_KEY", "value": "sk-..." }],
-    "functions": [{
-      "name": "my-fn",
-      "code": "export default async (req) => new Response('ok')"
-    }],
-    "files": [
-      {
-        "file": "manifest.json",
-        "data": "{\\"version\\":\\"1\\",\\"tables\\":[{\\"name\\":\\"items\\",\\"expose\\":true,\\"policy\\":\\"public_read_write_UNRESTRICTED\\",\\"i_understand_this_is_unrestricted\\":true}]}"
-      },
-      { "file": "index.html", "data": "<html>...</html>" },
-      { "file": "style.css", "path": "./dist/style.css" }
-    ],
-    "subdomain": "my-app"
+    "database": {
+      "migrations": [
+        { "id": "001_init", "sql": "CREATE TABLE IF NOT EXISTS items (...)" }
+      ],
+      "expose": {
+        "version": "1",
+        "tables": [
+          { "name": "items", "expose": true, "policy": "public_read_authenticated_write" }
+        ]
+      }
+    },
+    "secrets":   { "set": { "OPENAI_API_KEY": { "value": "sk-..." } } },
+    "functions": {
+      "replace": {
+        "api": {
+          "runtime": "node22",
+          "source": { "data": "export default async (req) => new Response('ok')" }
+        }
+      }
+    },
+    "site": {
+      "replace": {
+        "index.html": { "data": "<!doctype html><html>...</html>" },
+        "assets/logo.png": { "data": "iVBORw0KGgo...", "encoding": "base64" }
+      }
+    },
+    "subdomains": { "set": ["my-app"] }
   }
 
   project_id is required (provision first with 'run402 provision').
-  All other fields are optional.
-
-  Migrations can be inline or read from a file:
-    "migrations": "CREATE TABLE ..."              ← inline SQL
-    "migrations_file": "setup.sql"                ← read from disk
-  Use migrations_file when your SQL contains JSONB literals or other
-  characters that are painful to escape inside a JSON string.
-  Paths are resolved relative to the manifest file's directory.
-  If both are present, migrations_file wins.
-
-  Files can use either inline "data" or a local "path":
-    { "file": "index.html", "data": "<html>...</html>" }   ← inline content
-    { "file": "style.css",  "path": "./dist/style.css" }   ← read from disk
-  Paths are resolved relative to the manifest file's directory.
-  Binary files (images, fonts, etc.) are auto-detected and base64-encoded.
-
-  Authorization (manifest.json file pattern):
-    Tables are dark by default — anon/authenticated can't read them until a
-    manifest declares them with expose:true. Ship a "manifest.json" entry in
-    files[] (preferred — auth-as-SDLC) and the platform reads, validates,
-    applies, and strips it before the site deploys. Schema:
-    https://run402.com/schemas/manifest.v1.json
-
-    Per-table policies:
-      user_owns_rows                    users see only their own rows. Requires
-                                        "owner_column"; with
-                                        "force_owner_on_insert": true the gateway
-                                        sets it from auth.uid() automatically.
-                                        uuid columns get index-friendly policies.
-      public_read_authenticated_write   anyone reads; any authenticated user can
-                                        INSERT/UPDATE/DELETE any row (not just
-                                        their own). For collaborative content
-                                        like shared boards or announcements.
-      public_read_write_UNRESTRICTED    ⚠  fully open — anon_key can read AND
-                                        write any row. Only for intentionally
-                                        public tables (guestbooks, waitlists,
-                                        feedback forms). REQUIRES
+  All other fields are optional. Top-level absence = "leave untouched".
+
+  Source of truth for the v2 ReleaseSpec shape:
+    https://run402.com/llms-cli.txt  (search for "Unified Deploy")
+
+  Replace vs patch semantics per resource:
+    "site": { "replace": {...} }        whole-site (omitted files removed)
+    "site": { "patch": { "put": {...}, "delete": [...] } }   surgical updates
+  Same for "functions" and "secrets". Migrations are always additive (each
+  is keyed by id; re-shipping the same id+sql is a registry noop, same id
+  with different sql is a hard MIGRATION_CHECKSUM_MISMATCH error).
+
+  File entries accept inline "data", a local "path", or a "sql_path"
+  (migrations only) — paths are resolved relative to the manifest file's
+  directory. Binary files (images, fonts, PDFs) take "encoding": "base64";
+  text defaults to UTF-8.
+
+  Authorization (database.expose):
+    Tables are dark by default — anon/authenticated can't read them until
+    you declare them via "database.expose". Per-table policies:
+      user_owns_rows                    users see only their own rows.
+                                        Requires "owner_column"; with
+                                        "force_owner_on_insert": true the
+                                        gateway sets it from auth.uid()
+                                        automatically.
+      public_read_authenticated_write   anyone reads; any authenticated
+                                        user can INSERT/UPDATE/DELETE any
+                                        row (not just their own).
+      public_read_write_UNRESTRICTED    ⚠  fully open — anon_key reads AND
+                                        writes. REQUIRES
                                         "i_understand_this_is_unrestricted":
                                         true on the table entry.
-      custom                            escape hatch. Provide "custom_sql" with
-                                        CREATE POLICY statements.
+      custom                            escape hatch. Provide "custom_sql"
+                                        with CREATE POLICY statements.
+  Schema for the expose section: https://run402.com/schemas/manifest.v1.json
 
-  ⚠️  Without a manifest, tables are unreachable via anon_key. If your app
-  reads or writes data from the browser, you need a manifest.json entry.
+  ⚠️  Without an "expose" entry, tables are unreachable via anon_key.
+
+Legacy v1 bundle format (still accepted via compatibility shim):
+  Existing manifests with top-level "migrations" (string), "secrets" (array),
+  "functions" (array), "files" (array), "subdomain" (string), and the
+  "files[].file/data/path" + inline "manifest.json" entry continue to work —
+  the SDK translates them into a v2 ReleaseSpec under the hood. Prefer the
+  v2 shape above for new manifests; the legacy form is preserved for the
+  deprecation window so existing scripts don't break.
+
+  "migrations_file": "setup.sql"   (legacy convenience) reads SQL from disk
+  relative to the manifest file. Useful when JSONB literals make inline
+  strings painful. Still supported on the legacy code path.
 
 Examples:
   run402 deploy --manifest app.json
   run402 deploy --manifest app.json --project prj_123_1
   cat app.json | run402 deploy
+  run402 deploy apply --manifest app.json   # unified primitive (recommended)
 
 Prerequisites:
   - run402 init                     Set up allowance and funding
@@ -157,6 +180,50 @@ async function loadManifest(opts) {
     });
   }
 
+  // GH-185: Reject empty manifests client-side. Without this guard,
+  // `echo '{}' | run402 deploy` silently succeeds against the gateway with
+  // no signal that nothing was deployed. The MCP `deploy` tool was hardened
+  // for the same class of bug in #133; this is the CLI-side analog.
+  //
+  // "Meaningful" = at least one of these keys exists with non-empty content.
+  // We accept both shapes because this CLI path receives v1 manifests
+  // (translated by the bundleDeploy shim) and may also receive v2 manifests.
+  //   v1: migrations, migrations_file, secrets, functions, files, subdomain
+  //   v2: database, site, functions, secrets, subdomains, domains
+  // For object-typed v2 sections (site, database, functions, secrets,
+  // subdomains, domains) the "container is non-empty" check isn't enough —
+  // `site:{replace:{}}` has one key but ships nothing. We recurse one level
+  // so any object whose own values are all empty containers is still empty.
+  const meaningfulV1 = ["migrations", "migrations_file", "secrets", "functions", "files", "subdomain"];
+  const meaningfulV2 = ["database", "site", "functions", "secrets", "subdomains", "domains"];
+  const meaningful = [...new Set([...meaningfulV1, ...meaningfulV2])];
+
+  function hasContent(v) {
+    if (v == null) return false;
+    if (Array.isArray(v)) return v.length > 0;
+    if (typeof v === "object") {
+      const keys = Object.keys(v);
+      if (keys.length === 0) return false;
+      return keys.some((k) => hasContent(v[k]));
+    }
+    if (typeof v === "string") return v.length > 0;
+    return true;
+  }
+
+  const hasMeaningfulContent = manifest && typeof manifest === "object" && !Array.isArray(manifest) && meaningful.some((key) => hasContent(manifest[key]));
+  if (!hasMeaningfulContent) {
+    fail({
+      code: "MANIFEST_EMPTY",
+      message: `Manifest contains no deployable sections. Expected at least one of: ${meaningful.join(", ")}`,
+      hint: "Did you mean to write a 'site.replace' or 'database.migrations' block? See https://run402.com/schemas/manifest.v1.json",
+      details: {
+        field: opts.manifest ? "manifest" : "stdin",
+        ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
+        meaningful_keys: meaningful,
+      },
+    });
+  }
+
   if (opts.manifest) {
     try {
       resolveMigrationsFile(manifest, baseDir);

package/lib/domains.mjs

@@ -9,7 +9,7 @@ Usage:
 
 Subcommands:
   add    <domain> <subdomain_name> [--project <id>]   Register a custom domain
-  list   [<id>]                                        List custom domains for a project
+  list   [<id>] | list --project <id>                  List custom domains for a project
   status <domain> [--project <id>]                     Check domain DNS/SSL status
   delete <domain> --confirm [--project <id>]           Release a custom domain. Requires --confirm.
 
@@ -26,6 +26,74 @@ Notes:
   - The domain must CNAME to domains.run402.com (or ALIAS for apex domains)
 `;
 
+const SUB_HELP = {
+  add: `run402 domains add — Register a custom domain for a project
+
+Usage:
+  run402 domains add <domain> <subdomain_name> [--project <id>]
+
+Arguments:
+  <domain>            Custom domain (e.g. example.com)
+  <subdomain_name>    Existing subdomain to map the custom domain to
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Notes:
+  - After adding, configure DNS as shown in the response
+  - Poll 'run402 domains status <domain>' until active
+  - The domain must CNAME to domains.run402.com (or ALIAS for apex domains)
+
+Examples:
+  run402 domains add example.com myapp
+  run402 domains add example.com myapp --project prj_abc123
+`,
+  list: `run402 domains list — List custom domains for a project
+
+Usage:
+  run402 domains list [<id>]
+
+Arguments:
+  <id>                Project ID (defaults to the active project)
+
+Examples:
+  run402 domains list
+  run402 domains list prj_abc123
+`,
+  status: `run402 domains status — Check DNS/SSL status of a custom domain
+
+Usage:
+  run402 domains status <domain> [--project <id>]
+
+Arguments:
+  <domain>            Custom domain to check
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 domains status example.com
+  run402 domains status example.com --project prj_abc123
+`,
+  delete: `run402 domains delete — Release a custom domain
+
+Usage:
+  run402 domains delete <domain> --confirm [--project <id>]
+
+Arguments:
+  <domain>            Custom domain to release
+
+Options:
+  --confirm           Required: releasing detaches the domain from this
+                      project and clears its DNS/SSL configuration
+                      (irreversible)
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 domains delete example.com --confirm
+`,
+};
+
 function parseProjectFlag(args) {
   let project = null;
   const rest = [];
@@ -56,8 +124,14 @@ async function add(args) {
   }
 }
 
-async function list(projectIdArg) {
-  const projectId = resolveProjectId(projectIdArg);
+async function list(args) {
+  const argList = Array.isArray(args) ? args : [];
+  const { project, rest } = parseProjectFlag(argList);
+  // Either --project <id> or a positional id is accepted; --project wins
+  // when both are supplied. Falls back to the active project when neither
+  // is given. Keeps backward-compat with the legacy `domains list <id>`
+  // form (GH-209).
+  const projectId = resolveProjectId(project || rest[0]);
   try {
     const data = await getSdk().domains.list(projectId);
     console.log(JSON.stringify(data, null, 2));
@@ -113,10 +187,10 @@ async function deleteDomain(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 "add":    await add(args); break;
-    case "list":   await list(args[0]); break;
+    case "list":   await list(args); break;
     case "status": await status(args); break;
     case "delete": await deleteDomain(args); break;
     default: