run402 4.18.0 → 4.18.1

package/lib/credentials.mjs

@@ -36,6 +36,7 @@ Subcommands:
   status --project <id>               Show one cached entry, redacted
   import --project <id> --service-key-stdin
   import --project <id> --service-key-env <env>
+  import --project <id> --anon-key-env <env>   Rotate only the anon key
   export --project <id> --reveal       Print cached keys, including secrets
   remove --project <id>                Remove one cached key entry
 
@@ -44,6 +45,9 @@ Notes:
   - list/status never reveal full keys.
   - export requires --reveal.
   - import accepts service keys through stdin or an environment variable, not argv.
+  - import writes the whole entry, so the FIRST import must supply a service key.
+    Afterwards --anon-key-env alone rotates the anon key and keeps the cached
+    service key, so an anon rotation never puts a service key through a shell.
 `;
 
 function parseProjectKeyFlags(args, extraKnown = [], valueFlagsExtra = []) {
@@ -143,7 +147,7 @@ async function status(args) {
   console.log(JSON.stringify(redactedEntry(id, getProject(id)), null, 2));
 }
 
-function readSecretInput(parsed) {
+function readSecretInput(parsed, { projectId, anonEnv, existing } = {}) {
   const fromEnv = flagValue(parsed, "--service-key-env");
   const fromStdin = parsed.includes("--service-key-stdin");
   if (fromEnv && fromStdin) {
@@ -161,6 +165,23 @@ function readSecretInput(parsed) {
     return value.trim();
   }
   if (fromStdin) return readFileSync(0, "utf-8").trim();
+
+  // Anon-only rotation: the caller passed --anon-key-env and the entry already
+  // caches a service key. Reuse it rather than making them round-trip a service
+  // key through --reveal and a shell just to change the anon key.
+  if (anonEnv && existing?.service_key) return existing.service_key;
+
+  // Still no service key. Report the flags the caller actually passed — an error
+  // that names only the service-key flags reads as "--anon-key-env is not a flag".
+  if (anonEnv) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Importing an anon key also requires a service key, because import writes the whole cache entry and no service key is cached for ${projectId} yet.`,
+      hint: "Add --service-key-stdin or --service-key-env <env> to this first import. Once an entry exists, --anon-key-env alone rotates the anon key and keeps the cached service key.",
+      details: { project_id: projectId, anon_key_env: anonEnv },
+    });
+  }
+
   fail({
     code: "BAD_USAGE",
     message: "Import requires --service-key-stdin or --service-key-env <env>.",
@@ -178,16 +199,19 @@ async function importKey(args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys import: ${rest[0]}` });
   }
   const id = requireProjectFlag(projectId, "run402 credentials project-keys import --project <id> --service-key-stdin");
-  const serviceKey = readSecretInput(parsed);
-  if (!serviceKey) {
-    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
-  }
+  // Resolve --anon-key-env before requiring a service key, so a missing service
+  // key can report against the flags actually passed and an anon-only rotation
+  // can reuse the cached service key.
   const anonEnv = flagValue(parsed, "--anon-key-env");
   const anonKey = anonEnv ? process.env[anonEnv] : undefined;
   if (anonEnv && !anonKey) {
     fail({ code: "BAD_ENV", message: `Environment variable ${anonEnv} is empty or unset.`, details: { env: anonEnv } });
   }
   const existing = getProject(id);
+  const serviceKey = readSecretInput(parsed, { projectId: id, anonEnv, existing });
+  if (!serviceKey) {
+    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
+  }
   saveProject(id, {
     anon_key: anonKey ?? existing?.anon_key ?? "",
     service_key: serviceKey,

package/lib/pay.mjs

@@ -16,11 +16,13 @@ Usage:
 
 Options:
   --method <M>              HTTP method (default: GET)
-  --body <json-or-text>     Request body (not valid with GET/HEAD)
+  --body <json-or-text>     Request body — the ONLY way to send a payload
+                            (not valid with GET/HEAD)
   --max-usd <amount>        Maximum payment in USD (default: 0.10)
   --idempotency-key <key>   Forward a stable Idempotency-Key to the seller
   --require-receipt         Require verified merchant evidence
-  --json                    Print the response and payment receipt as JSON
+  --json                    No-op; pay always prints JSON. Takes no value —
+                            to send a payload use --body
   --help, -h                Show this help
 
 Examples:
@@ -50,10 +52,11 @@ export async function run(args = [], deps = {}) {
   );
   const positionals = positionalArgs(parsed, VALUE_FLAGS);
   if (positionals.length !== 1) {
+    const stray = positionals[1];
     fail({
       code: "BAD_USAGE",
-      message: positionals.length === 0 ? "URL required." : `Unexpected argument: ${positionals[1]}`,
-      hint: "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]",
+      message: positionals.length === 0 ? "URL required." : `Unexpected argument: ${stray}`,
+      hint: strayArgumentHint(parsed, stray),
     });
   }
 
@@ -113,6 +116,34 @@ export function parseUsdMicros(value) {
   return micros;
 }
 
+const USAGE_HINT = "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]";
+
+// `--json` selects output format and takes no value; `--body` sends the payload.
+// Reaching for `--json '<payload>'` is the predictable confusion, and it lands
+// here as a stray positional. Name the flag the caller actually wanted.
+export function strayArgumentHint(parsed, stray) {
+  if (typeof stray !== "string") return USAGE_HINT;
+  const jsonIndex = parsed.indexOf("--json");
+  if (jsonIndex !== -1 && parsed[jsonIndex + 1] === stray) {
+    return `--json only selects JSON output and takes no value; the request body flag is --body. Retry with: --method POST --body '${stray}'`;
+  }
+  if (looksLikeJson(stray)) {
+    return `To send this payload, pass it as a body: --method POST --body '${stray}'`;
+  }
+  return USAGE_HINT;
+}
+
+function looksLikeJson(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
+  try {
+    JSON.parse(trimmed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function validateUrl(value) {
   try {
     const parsed = new URL(value);

package/lib/pay.test.mjs

@@ -1,7 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
-import { parseUsdMicros, run } from "./pay.mjs";
+import { parseUsdMicros, run, strayArgumentHint } from "./pay.mjs";
 
 describe("run402 pay", () => {
   it("converts decimal USD to micros without floating-point rounding", () => {
@@ -10,6 +10,28 @@ describe("run402 pay", () => {
     assert.equal(parseUsdMicros("0"), 0);
   });
 
+  // `--json` selects output format, `--body` sends the payload. An agent
+  // reaching for `--json '<payload>'` gets a stray positional; the hint has to
+  // name --body or the usage error reads as "the payload was accepted".
+  it("points --json '<payload>' at --body", () => {
+    const payload = '{"kind":"anon"}';
+    const hint = strayArgumentHint(["https://s.example/x", "--json", payload], payload);
+    assert.match(hint, /--json only selects JSON output and takes no value/);
+    assert.match(hint, /--body '\{"kind":"anon"\}'/);
+  });
+
+  it("points a bare JSON positional at --body even without --json", () => {
+    const payload = '{"kind":"anon"}';
+    const hint = strayArgumentHint(["https://s.example/x", payload], payload);
+    assert.match(hint, /pass it as a body: --method POST --body/);
+  });
+
+  it("falls back to plain usage for a stray non-JSON argument", () => {
+    const hint = strayArgumentHint(["https://s.example/x", "stray"], "stray");
+    assert.equal(hint, "run402 pay <url> [--method POST] [--body <value>] [--max-usd 0.10]");
+    assert.equal(strayArgumentHint(["https://s.example/x"], undefined), hint);
+  });
+
   it("delegates to SDK pay.fetch and prints the receipt", async () => {
     let captured;
     const output = [];

package/package.json

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