run402 3.8.0 → 3.8.1

package/README.md

@@ -7,13 +7,13 @@ For the full CLI reference (every flag, every subcommand) see **<https://docs.ru
 ## Install
 
 ```bash
-npm install -g run402
+npm install -g run402@latest
 ```
 
 Or run without installing:
 
 ```bash
-npx run402 <command>
+npx -y run402@latest <command>
 ```
 
 ## 30-second start
@@ -29,6 +29,8 @@ That's a real Postgres database + a deployed static site, paid for autonomously
 
 Every command prints **JSON to stdout**, **JSON errors to stderr**, and exits **0 on success / 1 on failure**. Designed for shells, scripts, and agent loops — pipe everything to `jq`.
 
+Stale CLI notices are advisory and never pollute success stdout. When a cached npm check says a newer `run402` exists, normal commands may emit a structured `cli.update_available` JSON object on stderr, or an NDJSON event in `--json-stream`. Run `run402 doctor --refresh` for the explicit live check; it reports whether this invocation is local, global, npx/npm exec, pnpm/yarn/bun, or custom, and includes an `upgrade_client` action with both `command` and `argv`.
+
 ## Common commands
 
 ### One-command app deploy

package/lib/deploy-v2.mjs

@@ -38,6 +38,7 @@ import { normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./operator.mjs";
 import { editRequestAction, nextAction, retryAction } from "./next-actions.mjs";
+import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -444,6 +445,7 @@ function parsePromoteArgs(args) {
 
 async function promoteCmd(args) {
   const opts = parsePromoteArgs(args);
+  emitDeployUpdateNotice("promote", args, { quiet: opts.quiet });
   const projectId = opts.project ?? resolveProjectId(null);
 
   // Preserve the aggressive early-exit when no allowance is configured
@@ -500,6 +502,13 @@ function makeStderrEventWriter(quiet) {
   };
 }
 
+function emitDeployUpdateNotice(subcommand, args, { quiet = false } = {}) {
+  const scheduler = createUpdateCheckScheduler({
+    command: ["run402", "deploy", subcommand, ...args],
+  });
+  emitUpdateNotice(scheduler.cachedNotice, { quiet });
+}
+
 function parseApplyArgs(args) {
   const opts = {
     manifest: null,
@@ -787,6 +796,7 @@ async function applyCmd(args) {
   const opts = parseApplyArgs(args);
   const { source, error: sourceError } = resolveApplySource(opts, hasStdinSource());
   if (sourceError) fail(sourceError);
+  emitDeployUpdateNotice("apply", args, { quiet: opts.quiet });
 
   let raw;
   let manifestPath = null;
@@ -1377,6 +1387,7 @@ async function resumeCmd(args) {
     project: parsed.flags["--project"] ?? null,
     quiet: Boolean(parsed.flags["--quiet"]),
   };
+  emitDeployUpdateNotice("resume", args, { quiet: opts.quiet });
   const project = resolveProjectId(opts.project);
 
   allowanceAuthHeaders("/apply/v1/operations");

package/lib/doctor.mjs

@@ -19,22 +19,25 @@ import {
   scanSourceTree,
   SCAN_SEVERITY,
 } from "./doctor-source-scan.mjs";
+import { doctorUpdateCheck } from "./update-check.mjs";
 
 const HELP = `run402 doctor — Health and config diagnostics
 
 Usage:
-  run402 doctor [--verbose] [--no-scan] [--scan-dir <D>]
+  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>]
 
 Output:
   Stdout is a JSON report { ok, checks: [{ name, status, value?, hint?, message? }] }.
 
 Options:
   --verbose      Include extra detail (timing, error messages)
+  --refresh      Wait for a bounded live npm version check for the run402 CLI
   --no-scan      Skip the source-tree scan (config / health checks only)
   --scan-dir D   Scan a custom directory instead of \`<cwd>/src\`
 
 Checks performed:
   - Config directory exists and is writable
+  - Installed run402 CLI version and update guidance
   - Allowance is configured and on a valid rail (x402 / mpp)
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
@@ -60,6 +63,7 @@ export async function run(sub, args = []) {
     return;
   }
   const verbose = all.includes("--verbose");
+  const refresh = all.includes("--refresh");
   const skipScan = all.includes("--no-scan");
   const scanDirArgIdx = all.indexOf("--scan-dir");
   const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
@@ -87,6 +91,18 @@ export async function run(sub, args = []) {
     });
   }
 
+  // 1b. CLI version/update state. This is advisory: stale or unknown version
+  // state should help the user, not hide the rest of doctor.
+  try {
+    checks.push(await doctorUpdateCheck({ refresh }));
+  } catch (err) {
+    checks.push({
+      name: "cli_update",
+      status: "unknown",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   // 2. Allowance.
   try {
     const allowance = readAllowance();
@@ -324,7 +340,7 @@ export async function run(sub, args = []) {
   // 'warning' counts as ok for exit-code purposes — gaps are surfaced in
   // output but don't fail the doctor. Only hard 'error' / 'missing' /
   // 'empty' fail.
-  const allOk = checks.every((c) => c.status === "ok" || c.status === "warning" || c.status === "skipped");
+  const allOk = checks.every((c) => c.status === "ok" || c.status === "warning" || c.status === "skipped" || c.status === "unknown");
 
   console.log(JSON.stringify({ ok: allOk, checks }, null, 2));
   process.exit(allOk ? 0 : 1);

package/lib/up.mjs

@@ -3,6 +3,7 @@ import { stdin as input, stderr as output } from "node:process";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
 
 const HELP = `run402 up — Provision/link/deploy the current app
 
@@ -44,6 +45,11 @@ Options:
   --json-stream       Emit NDJSON progress events on stdout and a final result event.
   --quiet             Suppress action progress events on stderr.
 
+Update notices:
+  Stale CLI notices are advisory and never change the result payload or exit
+  code. Non-streaming notices are JSON on stderr; --json-stream emits
+  cli.update_available as an NDJSON event.
+
 Project resolution:
   explicit --project > .run402/project.json > manifest project_id > approved
   project creation from --name > approved active-project fallback.
@@ -184,6 +190,10 @@ export async function run(args = []) {
     });
   }
   const allowWarningCodes = collectRepeatedValues(parsed, "--allow-warning");
+  const updateScheduler = createUpdateCheckScheduler({
+    command: ["run402", "up", ...parsed],
+  });
+  emitUpdateNotice(updateScheduler.cachedNotice, { jsonStream, quiet });
 
   try {
     const sdk = getSdk();
@@ -224,11 +234,20 @@ export async function run(args = []) {
     } else {
       console.log(JSON.stringify(result, null, 2));
     }
+    if (shouldExitNonZeroForUpResult(result)) {
+      process.exitCode = 1;
+    }
   } catch (err) {
     reportSdkError(err);
   }
 }
 
+export function shouldExitNonZeroForUpResult(result) {
+  return result?.action === "up" &&
+    result?.mode === "apply" &&
+    result?.result?.app_result?.status === "deployed_unverified";
+}
+
 function parseExecutionMode(args) {
   const modes = [];
   if (args.includes("--check")) modes.push("--check");

package/lib/up.test.mjs

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { shouldExitNonZeroForUpResult } from "./up.mjs";
+
+test("run402 up exits nonzero for deployed-but-unverified app results", () => {
+  assert.equal(shouldExitNonZeroForUpResult({
+    action: "up",
+    mode: "apply",
+    result: {
+      app_result: { status: "deployed_unverified" },
+    },
+  }), true);
+
+  assert.equal(shouldExitNonZeroForUpResult({
+    action: "up",
+    mode: "apply",
+    result: {
+      app_result: { status: "succeeded" },
+    },
+  }), false);
+
+  assert.equal(shouldExitNonZeroForUpResult({
+    action: "up",
+    mode: "check",
+    result: {
+      app_result: { status: "deployed_unverified" },
+    },
+  }), false);
+});