run402 4.8.0 → 4.10.0

package/lib/asset-wire.mjs

@@ -0,0 +1,59 @@
+/**
+ * toWireAssetRef — project an SDK AssetRef (which carries camelCase TS
+ * conveniences like `cdnUrl`, `immutableUrl`, `contentSha256`, `size`) onto
+ * the CANONICAL gateway wire shape: snake_case keys only, no duplicate
+ * values under two casings.
+ *
+ * Canonical key set (gateway asset envelope):
+ *   key, sha256, size_bytes, content_type, visibility, immutable,
+ *   url, immutable_url, cdn_url, cdn_immutable_url, sri, etag,
+ *   content_digest, + the v1.49/v1.50/v1.54 image fields
+ *   (width_px, height_px, blurhash, variant_spec_version, display_url,
+ *   display_immutable_url, variants, metadata, image_format, image_info,
+ *   image_exif, image_exif_policy, blurhash_data_url, asset_schema).
+ *
+ * Unknown snake_case keys from newer gateways are preserved as-is; every
+ * camelCase key (the documented SDK aliases and any future ones) is dropped,
+ * with the aliases mapped back to their canonical snake twin when the snake
+ * form is missing from the input.
+ *
+ * The SDK keeps its camelCase conveniences for typed consumers (e.g.
+ * @run402/astro reads `cdnUrl`); this projector is the CLI/MCP output
+ * boundary only.
+ */
+
+// SDK-only convenience keys that must never appear in wire output. `size`
+// and `cdn` are lowercase but still SDK-only: `size` duplicates
+// `size_bytes`, `cdn` is the SDK's invalidation envelope (camelCase inner
+// keys, locally synthesized).
+const SDK_ONLY_KEYS = new Set(["size", "cdn"]);
+
+export function toWireAssetRef(ref) {
+  if (!ref || typeof ref !== "object" || Array.isArray(ref)) return ref;
+  const out = {};
+  for (const [key, value] of Object.entries(ref)) {
+    if (typeof value === "function") continue; // tag emitters (scriptTag, …)
+    if (SDK_ONLY_KEYS.has(key)) continue;
+    if (/[A-Z]/.test(key)) continue; // camelCase SDK aliases/conveniences
+    out[key] = value;
+  }
+  // Canonical fields whose only SDK source is a camelCase convenience.
+  if (out.content_type === undefined && typeof ref.contentType === "string") {
+    out.content_type = ref.contentType;
+  }
+  // SDK naming vs wire naming: `cdnUrl` is the IMMUTABLE cdn url,
+  // `cdnMutableUrl` the mutable one.
+  if (out.cdn_url === undefined && ref.cdnMutableUrl !== undefined) {
+    out.cdn_url = ref.cdnMutableUrl;
+  }
+  if (out.cdn_immutable_url === undefined && ref.cdnUrl !== undefined) {
+    out.cdn_immutable_url = ref.cdnUrl;
+  }
+  if (out.content_digest === undefined && ref.contentDigest !== undefined) {
+    out.content_digest = ref.contentDigest;
+  }
+  if (out.immutable === undefined) {
+    out.immutable = ref.immutable_url !== null && ref.immutable_url !== undefined;
+  }
+  return out;
+}

package/lib/assets.mjs

@@ -31,7 +31,8 @@ import { pipeline } from "node:stream/promises";
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, failUnknownSubcommand } from "./argparse.mjs";
+import { toWireAssetRef } from "./asset-wire.mjs";
 
 const HELP = `run402 blob — Direct-to-S3 blob storage
 
@@ -54,7 +55,7 @@ Options:
   --exif-policy keep|strip  v1.50: EXIF retention policy for image uploads (default keep).
   --stream            NDJSON per-file progress events (for agent consumption).
                       Without --stream, only the final results array is
-                      printed. --json is a deprecated alias for --stream.
+                      printed. --json is an accepted alias for --stream.
   --prefix <p>        Prefix filter (ls only)
   --limit <n>         Max results (ls only; default 100, max 1000)
   --sort <key>        v1.50 ls only: key:asc | createdAt:asc | createdAt:desc (default key:asc).
@@ -103,7 +104,7 @@ Options:
                       from the stored bytes and the image_exif response field.
   --stream            Emit NDJSON per-file progress events on stdout (for
                       agent consumption). Default: emit only the final
-                      results array (also JSON). --json is a deprecated
+                      results array (also JSON). --json is an accepted
                       alias for --stream.
 
 Examples:
@@ -256,12 +257,10 @@ function parseArgs(rawArgs) {
     else if (a === "--concurrency") out.concurrency = parseIntegerFlag("--concurrency", args[++i], { min: 1 });
     else if (a === "--no-resume") out.resume = false;
     else if (a === "--stream") out.stream = true;
-    else if (a === "--json") {
-      out.stream = true;
-      process.stderr.write(
-        "# warning: `--json` on `assets put` is deprecated and will be removed in a future release. Use `--stream` (alias means the same thing — NDJSON progress events on stdout).\n",
-      );
-    }
+    // `--json` and `--stream` are permanent aliases on `assets put` (both mean
+    // NDJSON progress events on stdout); elsewhere `--json` is a no-op since
+    // stdout is already JSON.
+    else if (a === "--json") { out.stream = true; }
     else if (a === "--prefix") out.prefix = args[++i];
     else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
@@ -460,8 +459,11 @@ async function putOne(projectId, filePath, opts) {
     ...(opts.metadata ? { metadata: opts.metadata } : {}),
     ...(opts.exifPolicy ? { exifPolicy: opts.exifPolicy } : {}),
   });
-  log(opts, { event: "done", ...result });
-  return result;
+  // Canonical wire shape only on stdout: snake_case keys, no camelCase
+  // duplicates (the SDK's AssetRef carries both; toWireAssetRef projects).
+  const wire = toWireAssetRef(result);
+  log(opts, { event: "done", ...wire });
+  return wire;
 }
 
 function computeDestKey(filePath, keyOpt) {
@@ -683,6 +685,6 @@ export async function run(sub, args) {
     case "sign":     await sign(defaultProject, args); break;
     case "diagnose": await diagnose(defaultProject, args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown assets subcommand: ${sub}`, hint: "Run `run402 assets --help` for usage.", details: { command: "assets", subcommand: sub } });
+      failUnknownSubcommand("assets", sub);
   }
 }

package/lib/auth.mjs

@@ -1,7 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 auth — Manage project user authentication
 
@@ -757,6 +757,6 @@ export async function run(sub, args) {
     case "providers": await providers(args); break;
     case "scaffold-roles": scaffoldRoles(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown auth subcommand: ${sub}`, hint: "Run `run402 auth --help` for usage.", details: { command: "auth", subcommand: sub } });
+      failUnknownSubcommand("auth", sub);
   }
 }

package/lib/billing.mjs

@@ -1,6 +1,6 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 billing — Email organizations and org checkouts
 
@@ -232,18 +232,20 @@ async function createEmail(args) {
 
 async function linkWallet(args) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
+  assertKnownFlags(parsedArgs, ["--wallet", "--help", "-h"], ["--wallet"]);
+  const walletFlag = flagValue(parsedArgs, "--wallet");
+  const positionals = positionalArgs(parsedArgs, ["--wallet"]);
   const organizationId = positionals[0];
-  const wallet = positionals[1];
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[2]}` });
+  const wallet = walletFlag ?? positionals[1];
+  const max = walletFlag ? 1 : 2;
+  if (positionals.length > max) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[max]}` });
   }
   if (!organizationId || !wallet) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <org_id> and/or <wallet_address>.",
-      hint: "run402 billing link-wallet <org_id> <wallet_address>",
+      hint: "run402 billing link-wallet <org_id> --wallet <wallet_address>",
     });
   }
   try {
@@ -262,19 +264,21 @@ async function linkWallet(args) {
 
 async function autoRecharge(args) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--threshold"];
+  const valueFlags = ["--threshold", "--state"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const stateFlag = flagValue(parsedArgs, "--state");
   const positionals = positionalArgs(parsedArgs, valueFlags);
   const organizationId = positionals[0];
-  const state = positionals[1];
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[2]}` });
+  const state = stateFlag ?? positionals[1];
+  const max = stateFlag ? 1 : 2;
+  if (positionals.length > max) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[max]}` });
   }
   if (!organizationId || !state || !["on", "off"].includes(state)) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <org_id> and/or <on|off>.",
-      hint: "run402 billing auto-recharge <org_id> <on|off> [--threshold <n>]",
+      hint: "run402 billing auto-recharge <org_id> --state <on|off> [--threshold <n>]",
     });
   }
   const thresholdStr = flagValue(parsedArgs, "--threshold");
@@ -355,6 +359,6 @@ export async function run(sub, args) {
     case "balance": await balance(args); break;
     case "history": await history(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown billing subcommand: ${sub}`, hint: "Run `run402 billing --help` for usage.", details: { command: "billing", subcommand: sub } });
+      failUnknownSubcommand("billing", sub);
   }
 }

package/lib/branches.mjs

@@ -8,19 +8,24 @@ import {
   normalizeArgv,
   parseIntegerFlag,
   positionalArgs,
+  resolveProjectSelector,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
-import { resolveProjectId } from "./config.mjs";
 
 const HELP = `run402 branches — Contained project data branches
 
 Usage:
-  run402 branches create [project-id] [--from-snapshot <snapshot-id>] [--name <label>] [--email-mode sandbox|off] [--enable-cron] [--ttl-days <n>] [--json]
-  run402 branches list [project-id] [--json]
-  run402 branches renew [project-id] <branch-project-id> [--ttl-days <n>] [--json]
-  run402 branches delete [project-id] <branch-project-id> [--json]
+  run402 branches create [--project <id>] [--from-snapshot <snapshot-id>] [--name <label>] [--email-mode sandbox|off] [--enable-cron] [--ttl-days <n>] [--json]
+  run402 branches list [--project <id>] [--json]
+  run402 branches renew <branch-project-id> [--project <id>] [--ttl-days <n>] [--json]
+  run402 branches delete <branch-project-id> [--project <id>] [--json]
+
+Legacy (still supported): a leading prj_... parent-project positional,
+e.g. run402 branches renew prj_parent prj_branch. --project defaults to the
+active project.
 `;
 
-const FLAG_VALUES = ["--from-snapshot", "--name", "--email-mode", "--ttl-days"];
+const FLAG_VALUES = ["--project", "--from-snapshot", "--name", "--email-mode", "--ttl-days"];
 const FLAGS = new Set([...FLAG_VALUES, "--enable-cron", "--json", "--help", "-h"]);
 
 export async function run(sub, args = []) {
@@ -37,17 +42,12 @@ export async function run(sub, args = []) {
     case "renew": return renew(rest);
     case "delete": return deleteBranch(rest);
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown branches subcommand: ${sub}`,
-        hint: "Run `run402 branches --help` for usage.",
-        details: { command: "branches", subcommand: sub },
-      });
+      failUnknownSubcommand("branches", sub);
   }
 }
 
 async function create(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   const emailMode = flagValue(args, "--email-mode") ?? undefined;
   if (emailMode !== undefined) assertAllowedValue(emailMode, ["sandbox", "off"], "--email-mode");
   const ttlDaysFlag = flagValue(args, "--ttl-days");
@@ -67,7 +67,7 @@ async function create(args) {
 }
 
 async function list(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   try {
     const result = await getSdk().branches.list(projectId);
     console.log(JSON.stringify({ project_id: projectId, ...result }, null, 2));
@@ -100,14 +100,13 @@ async function deleteBranch(args) {
   }
 }
 
-function resolveOptionalProject(value) {
-  if (value && String(value).startsWith("prj_")) return value;
-  return resolveProjectId(null);
-}
-
 function resolveProjectAndBranch(args, usage) {
-  const pos = positionalArgs(args, FLAG_VALUES);
-  if (pos.length === 1) return { projectId: resolveProjectId(null), branchProjectId: pos[0] };
-  if (pos.length === 2 && pos[0].startsWith("prj_")) return { projectId: pos[0], branchProjectId: pos[1] };
-  fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  // Canonical: `<branch-project-id> [--project <parent-id>]`. Branch ids are
+  // themselves prj_..., so a leading prj_ positional is only treated as the
+  // PARENT project when a second positional follows (requireRestPositional) —
+  // the legacy `renew prj_parent prj_branch` form.
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES, requireRestPositional: true });
+  const pos = positionalArgs(rest, FLAG_VALUES);
+  if (pos.length !== 1) fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  return { projectId, branchProjectId: pos[0] };
 }

package/lib/cache.mjs

@@ -18,7 +18,7 @@
 
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 import { editRequestAction } from "./next-actions.mjs";
 
 // Locally-defined helpers — argparse.mjs's normalized form is a flat
@@ -99,11 +99,7 @@ export async function run(sub, args) {
       await invalidate(args);
       break;
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown cache subcommand: ${sub}`,
-        hint: "Run `run402 cache --help` for usage.",
-        details: { command: "cache", subcommand: sub },
+      failUnknownSubcommand("cache", sub, {
         next_actions: [editRequestAction("run402 cache --help", "Choose a supported cache subcommand.")],
       });
   }

package/lib/cdn.mjs

@@ -16,7 +16,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -135,6 +135,6 @@ export async function run(sub, args) {
       await waitFresh(defaultProject, args);
       break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown cdn subcommand: ${sub}`, hint: "Run `run402 cdn --help` for usage.", details: { command: "cdn", subcommand: sub } });
+      failUnknownSubcommand("cdn", sub);
   }
 }

package/lib/ci.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { failUnknownSubcommand } from "./argparse.mjs";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -96,6 +97,8 @@ function parseFlags(args, allowed, { repeatable = new Set() } = {}) {
       positional.push(arg);
       continue;
     }
+    // CLI-wide convention: --json is accepted everywhere (stdout is already JSON).
+    if (arg === "--json") continue;
     if (!allowed.has(arg)) {
       fail({
         code: "BAD_USAGE",
@@ -457,6 +460,6 @@ export async function run(sub, args) {
     case "revoke": await revoke(args); break;
     case "set-asset-scopes": await setAssetScopes(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown ci subcommand: ${sub}`, hint: "Run `run402 ci --help` for usage.", details: { command: "ci", subcommand: sub } });
+      failUnknownSubcommand("ci", sub);
   }
 }

package/lib/cloud.mjs

@@ -3,14 +3,18 @@ import { dirname, resolve } from "node:path";
 
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
-import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 cloud — Run402 Cloud portability commands
 
 Usage:
-  run402 cloud archives create <project-id> [options]
-  run402 cloud archives download <project-id> <archive-id> --output <file> [--json]
-  run402 cloud archives status <project-id> <archive-id> [--json]
+  run402 cloud archives create [--project <id>] [options]
+  run402 cloud archives download <archive-id> --output <file> [--project <id>] [--json]
+  run402 cloud archives status <archive-id> [--project <id>] [--json]
+
+Legacy (still supported): a leading prj_... positional selects the project,
+e.g. run402 cloud archives download <project-id> <archive-id> --output <file>.
+--project defaults to the active project.
 
 Canonical agent path:
   run402 cloud archives create prj_... \\
@@ -31,6 +35,7 @@ Options for create:
 `;
 
 const FLAG_VALUES = [
+  "--project",
   "--scope",
   "--auth",
   "--consistency",
@@ -55,11 +60,7 @@ export async function run(sub, args = []) {
     return;
   }
   if (sub !== "archives") {
-    fail({
-      code: "UNKNOWN_SUBCOMMAND",
-      message: `Unknown cloud subcommand: ${sub}`,
-      hint: "Run `run402 cloud --help` for usage.",
-      details: { command: "cloud", subcommand: sub },
+    failUnknownSubcommand("cloud", sub, {
       next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
     });
   }
@@ -68,11 +69,7 @@ export async function run(sub, args = []) {
   if (action === "create") return create(rest);
   if (action === "download") return download(rest);
   if (action === "status") return status(rest);
-  fail({
-    code: "UNKNOWN_SUBCOMMAND",
-    message: `Unknown cloud archives subcommand: ${action}`,
-    hint: "Run `run402 cloud archives --help` for usage.",
-    details: { command: "cloud archives", subcommand: action },
+  failUnknownSubcommand("cloud archives", action, {
     next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
   });
 }
@@ -80,10 +77,10 @@ export async function run(sub, args = []) {
 async function create(rawArgs) {
   const args = normalizeArgv(rawArgs);
   assertKnownFlags(args, [...FLAGS], FLAG_VALUES);
-  const pos = positionalArgs(args, FLAG_VALUES);
-  const projectId = pos[0];
-  if (!projectId) {
-    fail({ code: "BAD_PROJECT_ID", message: "Missing project id." });
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
+  const extraPos = positionalArgs(rest, FLAG_VALUES);
+  if (extraPos.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for cloud archives create: ${extraPos[0]}` });
   }
   const scope = flagValue(args, "--scope") ?? "portable-runtime-v1";
   const auth = flagValue(args, "--auth") ?? "stubs";
@@ -170,12 +167,13 @@ async function create(rawArgs) {
 
 async function download(rawArgs) {
   const args = normalizeArgv(rawArgs);
-  assertKnownFlags(args, ["--output", "--json", "--help", "-h"], ["--output"]);
-  const pos = positionalArgs(args, ["--output"]);
-  const [projectId, archiveId] = pos;
+  assertKnownFlags(args, ["--project", "--output", "--json", "--help", "-h"], ["--project", "--output"]);
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: ["--project", "--output"] });
+  const pos = positionalArgs(rest, ["--project", "--output"]);
+  const [archiveId] = pos;
   const output = flagValue(args, "--output");
-  if (!projectId || !archiveId || !output) {
-    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives download <project-id> <archive-id> --output <file> [--json]" });
+  if (!archiveId || pos.length > 1 || !output) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives download <archive-id> --output <file> [--project <id>] [--json]" });
   }
   try {
     const download = await getSdk().archives.download(projectId, archiveId);
@@ -200,11 +198,12 @@ async function download(rawArgs) {
 
 async function status(rawArgs) {
   const args = normalizeArgv(rawArgs);
-  assertKnownFlags(args, ["--json", "--help", "-h"], []);
-  const pos = positionalArgs(args, []);
-  const [projectId, archiveId] = pos;
-  if (!projectId || !archiveId) {
-    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives status <project-id> <archive-id> [--json]" });
+  assertKnownFlags(args, ["--project", "--json", "--help", "-h"], ["--project"]);
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: ["--project"] });
+  const pos = positionalArgs(rest, ["--project"]);
+  const [archiveId] = pos;
+  if (!archiveId || pos.length > 1) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives status <archive-id> [--project <id>] [--json]" });
   }
   try {
     const archive = await getSdk().archives.get(projectId, archiveId);