run402 1.53.0 → 1.54.0

package/core-dist/keystore.js

@@ -1,7 +1,34 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getKeystorePath } from "./config.js";
+function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
+    const lockDir = path + ".lock";
+    mkdirSync(dirname(path), { recursive: true });
+    for (let i = 0; i < retries; i++) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            const until = Date.now() + delayMs;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmdirSync(lockDir);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    throw new Error(`Could not acquire keystore lock after ${retries} retries: ${lockDir}`);
+}
 /**
  * Load the keystore from disk.
  * Auto-migrates legacy formats:
@@ -13,7 +40,6 @@ export function loadKeyStore(path) {
     try {
         const data = readFileSync(p, "utf-8");
         const parsed = JSON.parse(data);
-        // Auto-migrate array format (CLI legacy) to object format
         if (Array.isArray(parsed)) {
             const projects = {};
             for (const item of parsed) {
@@ -29,7 +55,6 @@ export function loadKeyStore(path) {
             return { projects };
         }
         if (parsed && typeof parsed === "object" && parsed.projects) {
-            // Strip legacy fields (tier, lease_expires_at, expires_at) from projects
             for (const proj of Object.values(parsed.projects)) {
                 const rec = proj;
                 delete rec.tier;
@@ -38,6 +63,7 @@ export function loadKeyStore(path) {
             }
             return {
                 ...(parsed.active_project_id && { active_project_id: parsed.active_project_id }),
+                ...(parsed.previous_active_project_id && { previous_active_project_id: parsed.previous_active_project_id }),
                 projects: parsed.projects,
             };
         }
@@ -62,27 +88,40 @@ export function getProject(projectId, path) {
 }
 export function saveProject(projectId, project, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.projects[projectId] = project;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        store.projects[projectId] = project;
+        saveKeyStore(store, p);
+    });
 }
 export function updateProject(projectId, update, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    const existing = store.projects[projectId];
-    if (existing) {
-        store.projects[projectId] = { ...existing, ...update };
-        saveKeyStore(store, p);
-    }
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        const existing = store.projects[projectId];
+        if (existing) {
+            store.projects[projectId] = { ...existing, ...update };
+            saveKeyStore(store, p);
+        }
+    });
 }
 export function removeProject(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    delete store.projects[projectId];
-    if (store.active_project_id === projectId) {
-        delete store.active_project_id;
-    }
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        delete store.projects[projectId];
+        if (store.active_project_id === projectId) {
+            const fallback = store.previous_active_project_id;
+            if (fallback && fallback !== projectId && store.projects[fallback]) {
+                store.active_project_id = fallback;
+            }
+            else {
+                delete store.active_project_id;
+            }
+            delete store.previous_active_project_id;
+        }
+        saveKeyStore(store, p);
+    });
 }
 export function getActiveProjectId(path) {
     const store = loadKeyStore(path);
@@ -90,8 +129,13 @@ export function getActiveProjectId(path) {
 }
 export function setActiveProjectId(projectId, path) {
     const p = path ?? getKeystorePath();
-    const store = loadKeyStore(p);
-    store.active_project_id = projectId;
-    saveKeyStore(store, p);
+    withFileLock(p, () => {
+        const store = loadKeyStore(p);
+        if (store.active_project_id && store.active_project_id !== projectId) {
+            store.previous_active_project_id = store.active_project_id;
+        }
+        store.active_project_id = projectId;
+        saveKeyStore(store, p);
+    });
 }
 //# sourceMappingURL=keystore.js.map

package/lib/apps.mjs

@@ -72,7 +72,7 @@ Arguments:
 Options:
   --description <d>   Human-readable description of the app
   --tags <t1,t2>      Comma-separated list of tags
-  --visibility <v>    Visibility: 'public' or 'private'
+  --visibility <v>    Visibility: 'public', 'unlisted', or 'private'
   --fork-allowed      Allow other users to fork this app
 
 Examples:

package/lib/domains.mjs

@@ -11,14 +11,14 @@ Subcommands:
   add    <domain> <subdomain_name> [--project <id>]   Register a custom domain
   list   [<id>]                                        List custom domains for a project
   status <domain> [--project <id>]                     Check domain DNS/SSL status
-  delete <domain> [--project <id>]                     Release a custom domain
+  delete <domain> --confirm [--project <id>]           Release a custom domain. Requires --confirm.
 
 Examples:
   run402 domains add example.com myapp
   run402 domains add example.com myapp --project prj_123
   run402 domains list
   run402 domains status example.com
-  run402 domains delete example.com
+  run402 domains delete example.com --confirm
 
 Notes:
   - After adding a domain, configure DNS as shown in the response
@@ -75,8 +75,17 @@ async function status(args) {
 
 async function deleteDomain(args) {
   const { project, rest } = parseProjectFlag(args);
-  const domain = rest[0];
-  if (!domain) { console.error("Usage: run402 domains delete <domain> [--project <id>]"); process.exit(1); }
+  const domain = rest.find((a) => !a.startsWith("--"));
+  if (!domain) { console.error("Usage: run402 domains delete <domain> --confirm [--project <id>]"); process.exit(1); }
+  if (!Array.isArray(args) || !args.includes("--confirm")) {
+    console.error(JSON.stringify({
+      status: "error",
+      code: "CONFIRMATION_REQUIRED",
+      message: `Destructive: releasing custom domain '${domain}' detaches it from this project and clears its DNS/SSL configuration. This is irreversible. Re-run with --confirm to proceed.`,
+      details: { domain },
+    }));
+    process.exit(1);
+  }
   const projectId = resolveProjectId(project);
   try {
     await getSdk().domains.remove(domain, { projectId });

package/lib/email.mjs

@@ -167,12 +167,7 @@ async function create(args) {
 
   try {
     const data = await getSdk().email.createMailbox(projectId, slug);
-    // SDK may return CreateMailboxResult (with slug) on success, or MailboxInfo on 409 idempotency.
-    if (data.slug) {
-      console.log(JSON.stringify({ status: "ok", mailbox_id: data.mailbox_id, address: data.address, slug: data.slug }));
-    } else {
-      console.log(JSON.stringify({ status: "ok", mailbox_id: data.mailbox_id, address: data.address, already_existed: true }));
-    }
+    console.log(JSON.stringify({ status: "ok", mailbox_id: data.mailbox_id, address: data.address, slug: data.slug }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -203,7 +198,7 @@ async function send(args) {
       text: text ?? undefined,
       from_name: fromName ?? undefined,
     });
-    console.log(JSON.stringify({ status: "ok", message_id: data.id, to: data.to, template: data.template || null, subject: data.subject || null }));
+    console.log(JSON.stringify({ status: "ok", message_id: data.message_id, to: data.to, template: data.template, subject: data.subject }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -325,7 +320,7 @@ async function reply(args) {
       from_name: fromName ?? undefined,
       in_reply_to: messageId,
     });
-    console.log(JSON.stringify({ status: "ok", message_id: data.id, to: data.to, subject: replySubject, in_reply_to: messageId }));
+    console.log(JSON.stringify({ status: "ok", message_id: data.message_id, to: data.to, subject: replySubject, in_reply_to: messageId }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -352,8 +347,8 @@ async function deleteMailbox(args) {
   }
 
   try {
-    await getSdk().email.deleteMailbox(projectId, positional ?? undefined);
-    console.log(JSON.stringify({ status: "ok", mailbox_id: positional ?? "(resolved)", deleted: true }));
+    const data = await getSdk().email.deleteMailbox(projectId, positional ?? undefined);
+    console.log(JSON.stringify({ status: "ok", mailbox_id: data.mailbox_id, address: data.address, deleted: true }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/init.mjs

@@ -10,12 +10,23 @@ const TEMPO_RPC = "https://rpc.moderato.tempo.xyz/";
 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)
+  run402 init                Set up with x402 (Base Sepolia) — default
+  run402 init mpp            Set up with MPP (Tempo Moderato)
+  run402 init <rail> --switch-rail
+                             Switch the persisted payment rail to <rail>.
+                             Required when an allowance already exists on
+                             the other rail; protects scripted re-runs from
+                             silently flipping billing networks.
+  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):
+Options:
+  --switch-rail   Confirm switching the persisted payment rail. Re-running
+                  init with the SAME rail as the existing allowance is always
+                  idempotent and does not need this flag.
+  --json          Emit a structured JSON summary on stdout.
+
+Steps (idempotent when re-run with the same rail; pass --switch-rail to change rails):
   1. Creates config directory (~/.config/run402)
   2. Creates agent allowance if none exists
   3. Checks on-chain balance; requests faucet if zero
@@ -32,6 +43,19 @@ 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";
+  const requestedRail = isMpp ? "mpp" : "x402";
+  const switchRailConfirmed = args.includes("--switch-rail");
+
+  const existingAllowance = readAllowance();
+  if (existingAllowance?.rail && existingAllowance.rail !== requestedRail && !switchRailConfirmed) {
+    console.error(JSON.stringify({
+      status: "error",
+      code: "RAIL_SWITCH_REQUIRES_CONFIRM",
+      message: `Already on rail '${existingAllowance.rail}'. Pass --switch-rail to switch to '${requestedRail}'.`,
+      details: { current_rail: existingAllowance.rail, requested_rail: requestedRail },
+    }));
+    process.exit(1);
+  }
 
   // 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.
@@ -55,7 +79,7 @@ export async function run(args = []) {
   line("Config", CONFIG_DIR);
 
   // 2. Allowance
-  let allowance = readAllowance();
+  let allowance = existingAllowance;
   const previousRail = allowance?.rail;
   if (!allowance) {
     const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");

package/lib/projects.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "fs";
-import { findProject, loadKeyStore, API, allowanceAuthHeaders, resolveProjectId } from "./config.mjs";
+import { findProject, loadKeyStore, API, allowanceAuthHeaders, resolveProjectId, getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError } from "./sdk-errors.mjs";
 
@@ -22,7 +22,7 @@ Subcommands:
   apply-expose [id] <manifest_json>       Apply a declarative authorization manifest
   apply-expose [id] --file <path>         Apply a manifest from a JSON file
   get-expose   [id]                       Get the current authorization manifest
-  delete [id]                             Immediately and irreversibly delete a project (cascade purge) and remove from local state
+  delete [id] --confirm                   Immediately and irreversibly delete a project (cascade purge) and remove from local state. Requires --confirm.
   pin   [id]                              Pin a project (admin only; project owners get 403 admin_required)
   promote-user [id] <email>               Promote a user to project_admin role
   demote-user  [id] <email>               Demote a user from project_admin role
@@ -43,7 +43,7 @@ Examples:
   run402 projects apply-expose abc123 --file manifest.json
   run402 projects get-expose abc123
   run402 projects keys abc123
-  run402 projects delete abc123
+  run402 projects delete abc123 --confirm
 
 Notes:
   - <id> is the project_id shown in 'run402 projects list' (prefix: 'prj_')
@@ -128,9 +128,16 @@ async function provision(args) {
   // gives the user a more specific prompt than the SDK's 401/402 path.
   allowanceAuthHeaders("/projects/v1");
 
+  const activeBefore = getActiveProjectId();
   try {
     const data = await getSdk().projects.provision({ tier: opts.tier, name: opts.name });
-    console.log(JSON.stringify(data, null, 2));
+    const activeAfter = getActiveProjectId();
+    const out = { ...data };
+    if (activeBefore && activeAfter && activeBefore !== activeAfter) {
+      out.note = `active project changed: ${activeBefore} -> ${activeAfter}`;
+      out.previous_active_project_id = activeBefore;
+    }
+    console.log(JSON.stringify(out, null, 2));
   } catch (err) {
     reportSdkError(err);
   }
@@ -302,7 +309,17 @@ async function demoteUser(projectId, email) {
   console.log(JSON.stringify(data, null, 2));
 }
 
-async function deleteProject(projectId) {
+async function deleteProject(projectId, args = []) {
+  const confirmed = Array.isArray(args) && args.includes("--confirm");
+  if (!confirmed) {
+    console.error(JSON.stringify({
+      status: "error",
+      code: "CONFIRMATION_REQUIRED",
+      message: `Destructive: deleting project ${projectId} drops all DB schemas, functions, subdomains, mailbox, blobs, and secrets. This is irreversible. Re-run with --confirm to proceed.`,
+      details: { project_id: projectId, destroys: ["schemas", "functions", "subdomains", "mailbox", "blobs", "secrets"] },
+    }));
+    process.exit(1);
+  }
   try {
     await getSdk().projects.delete(projectId);
     console.log(JSON.stringify({ status: "ok", message: `Project ${projectId} deleted.` }));
@@ -346,7 +363,7 @@ export async function run(sub, args) {
     case "schema":    { const { projectId } = resolvePositionalProject(args); await schema(projectId); break; }
     case "apply-expose": { const { projectId, rest } = resolvePositionalProject(args); await applyExpose(projectId, rest); break; }
     case "get-expose":   { const { projectId } = resolvePositionalProject(args); await getExpose(projectId); break; }
-    case "delete":    { const { projectId } = resolvePositionalProject(args); await deleteProject(projectId); break; }
+    case "delete":    { const { projectId, rest } = resolvePositionalProject(args); await deleteProject(projectId, rest); 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; }

package/lib/sites.mjs

@@ -1,11 +1,14 @@
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { dirname, join, resolve } from "path";
+import { fileSetFromDir } from "#sdk/node";
 import { allowanceAuthHeaders, resolveProjectId, updateProject } from "./config.mjs";
 import { resolveFilePathsInManifest } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError } from "./sdk-errors.mjs";
 
+const SMALL_DIR_THRESHOLD = 5;
+
 const HELP = `run402 sites - Deploy and manage static sites
 
 Usage:
@@ -28,6 +31,9 @@ Options (deploy-dir):
   --project <id>        Project ID (defaults to active project)
   --target <target>     Deployment target (e.g. 'production')
   --quiet               Suppress progress events on stderr
+  --dry-run             Plan-only: print the diff envelope and exit
+  --confirm-prune       Required when <path> has fewer files than the
+                        small-dir guardrail threshold
 
 Manifest format (JSON):
   {
@@ -97,6 +103,7 @@ Examples:
 
 Usage:
   run402 sites deploy-dir <path> [--project <id>] [--target <target>] [--quiet]
+                                  [--dry-run] [--confirm-prune]
 
 Arguments:
   <path>              Local directory to deploy (positional, required)
@@ -106,11 +113,23 @@ Options:
   --target <target>   Deployment target (e.g. 'production')
   --quiet             Suppress progress events on stderr (events are on by
                       default — see Progress events below)
+  --dry-run           Plan the deploy and print a JSON envelope describing
+                      what would happen, then exit. Does NOT upload bytes
+                      or commit a release.
+  --confirm-prune     Acknowledge that deploying <path> may remove files
+                      that exist in the current site but are absent from
+                      <path>. Required when <path> contains fewer than
+                      ${SMALL_DIR_THRESHOLD} files (the small-dir guardrail).
 
 Behavior:
   - Walks <path> recursively, skips .git / node_modules / .DS_Store
   - Computes per-file SHA-256 and uploads only bytes the gateway doesn't
     already have (CAS-backed unified deploy primitive)
+  - A static-site deploy REPLACES the live release: any path in the current
+    site that is absent from <path> is removed from the new release. To
+    avoid accidentally wiping a multi-page site by deploying a single-file
+    directory, a small <path> (fewer than ${SMALL_DIR_THRESHOLD} files) requires
+    --confirm-prune.
   - Symlinks are rejected (no following)
   - Paths in the manifest are POSIX-style relative to <path>
 
@@ -131,6 +150,8 @@ Examples:
   run402 sites deploy-dir ./dist --project prj_abc
   run402 sites deploy-dir ./my-site --project prj_abc --target production
   run402 sites deploy-dir ./dist --project prj_abc --quiet
+  run402 sites deploy-dir ./tiny-site --project prj_abc --confirm-prune
+  run402 sites deploy-dir ./dist --project prj_abc --dry-run
 `,
 };
 
@@ -207,12 +228,21 @@ async function deploy(args) {
 }
 
 async function deployDir(args) {
-  const opts = { dir: null, project: undefined, target: undefined, quiet: false };
+  const opts = {
+    dir: null,
+    project: undefined,
+    target: undefined,
+    quiet: false,
+    dryRun: false,
+    confirmPrune: false,
+  };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--help" || args[i] === "-h") { console.log(SUB_HELP["deploy-dir"]); process.exit(0); }
     if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
     if (args[i] === "--target" && args[i + 1]) { opts.target = args[++i]; continue; }
     if (args[i] === "--quiet") { opts.quiet = true; continue; }
+    if (args[i] === "--dry-run") { opts.dryRun = true; continue; }
+    if (args[i] === "--confirm-prune") { opts.confirmPrune = true; continue; }
     if (args[i] === "--inherit") {
       console.error(JSON.stringify({
         status: "error",
@@ -231,6 +261,59 @@ async function deployDir(args) {
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/deploy/v2/plans");
 
+  let fileSet;
+  try {
+    fileSet = await fileSetFromDir(opts.dir);
+  } catch (err) {
+    reportSdkError(err);
+    return;
+  }
+  const fileCount = Object.keys(fileSet).length;
+
+  if (
+    fileCount < SMALL_DIR_THRESHOLD &&
+    !opts.confirmPrune &&
+    !opts.dryRun
+  ) {
+    console.error(JSON.stringify({
+      status: "error",
+      code: "PRUNE_CONFIRMATION_REQUIRED",
+      message:
+        `sites deploy-dir would replace the entire site with ${fileCount} ` +
+        `file(s) from ${opts.dir}. Any files in the current release that ` +
+        `are absent from this directory will be removed. Pass ` +
+        `--confirm-prune to proceed, or --dry-run to preview the diff.`,
+      details: {
+        local_file_count: fileCount,
+        threshold: SMALL_DIR_THRESHOLD,
+        dir: opts.dir,
+      },
+    }));
+    process.exit(1);
+  }
+
+  if (opts.dryRun) {
+    try {
+      const { plan } = await getSdk().deploy.plan({
+        project: projectId,
+        site: { replace: fileSet },
+      });
+      console.log(JSON.stringify({
+        status: "ok",
+        dry_run: true,
+        local_file_count: fileCount,
+        plan_id: plan.plan_id,
+        operation_id: plan.operation_id,
+        manifest_digest: plan.manifest_digest,
+        diff: plan.diff,
+        missing_content_count: plan.missing_content.filter((p) => !p.present).length,
+      }, null, 2));
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
   try {
     const data = await getSdk().sites.deployDir({
       project: projectId,

package/lib/subdomains.mjs

@@ -9,7 +9,7 @@ Usage:
 
 Subcommands:
   claim  <name> [--project <id>] [--deployment <id>]   Claim a subdomain
-  delete <name> [--project <id>]                        Release a subdomain
+  delete <name> --confirm [--project <id>]              Release a subdomain. Requires --confirm.
   list   [<id>]                                         List subdomains for a project
 
 Options default to the active project and its last deployment when omitted.
@@ -18,7 +18,7 @@ Legacy syntax 'claim <deployment_id> <name>' is still supported.
 Examples:
   run402 subdomains claim myapp
   run402 subdomains claim myapp --deployment dpl_abc123 --project proj123
-  run402 subdomains delete myapp
+  run402 subdomains delete myapp --confirm
   run402 subdomains list
 
 Notes:
@@ -77,10 +77,26 @@ async function claim(positionalArgs, flagArgs) {
   }
 }
 
-async function deleteSubdomain(name, args) {
-  const opts = { project: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+async function deleteSubdomain(allArgs) {
+  const argList = Array.isArray(allArgs) ? allArgs : [];
+  let opts = { project: null };
+  let name = null;
+  for (let i = 0; i < argList.length; i++) {
+    if (argList[i] === "--project" && argList[i + 1]) { opts.project = argList[++i]; }
+    else if (!argList[i].startsWith("--") && !name) { name = argList[i]; }
+  }
+  if (!name) {
+    console.error(JSON.stringify({ status: "error", message: "Usage: run402 subdomains delete <name> --confirm [--project <id>]" }));
+    process.exit(1);
+  }
+  if (!argList.includes("--confirm")) {
+    console.error(JSON.stringify({
+      status: "error",
+      code: "CONFIRMATION_REQUIRED",
+      message: `Destructive: releasing subdomain '${name}' makes it available for any other project to claim. This is irreversible. Re-run with --confirm to proceed.`,
+      details: { name },
+    }));
+    process.exit(1);
   }
   const projectId = resolveProjectId(opts.project);
   try {
@@ -116,7 +132,7 @@ export async function run(sub, args) {
       await claim(positional, flags);
       break;
     }
-    case "delete": await deleteSubdomain(args[0], args.slice(1)); break;
+    case "delete": await deleteSubdomain(args); break;
     case "list":   await list(args[0]); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);

package/package.json

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