run402 1.69.5 → 1.69.6

package/lib/agent.mjs

@@ -1,7 +1,7 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { validateWebhookUrl } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateWebhookUrl } from "./argparse.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
@@ -76,12 +76,20 @@ contact email. Requires assurance_level=email_verified first.
 };
 
 async function contact(args) {
-  let name = null, email = null, webhook = null;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--name" && args[i + 1]) name = args[++i];
-    if (args[i] === "--email" && args[i + 1]) email = args[++i];
-    if (args[i] === "--webhook" && args[i + 1]) webhook = args[++i];
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--name", "--email", "--webhook"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const extra = positionalArgs(parsedArgs, valueFlags);
+  if (extra.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for agent contact: ${extra[0]}`,
+      hint: "Use `run402 agent contact --name <name> [--email <email>] [--webhook <url>]`.",
+    });
   }
+  const name = flagValue(parsedArgs, "--name");
+  const email = flagValue(parsedArgs, "--email");
+  const webhook = flagValue(parsedArgs, "--webhook");
   if (!name) {
     fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
   }
@@ -104,7 +112,13 @@ async function contact(args) {
   }
 }
 
-async function status() {
+async function status(args = []) {
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const extra = positionalArgs(parsedArgs);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for agent status: ${extra[0]}` });
+  }
   allowanceAuthHeaders("/agent/v1/contact/status");
 
   try {
@@ -115,7 +129,13 @@ async function status() {
   }
 }
 
-async function verifyEmail() {
+async function verifyEmail(args = []) {
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const extra = positionalArgs(parsedArgs);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for agent verify-email: ${extra[0]}` });
+  }
   allowanceAuthHeaders("/agent/v1/contact/verify-email");
 
   try {
@@ -127,7 +147,13 @@ async function verifyEmail() {
 }
 
 async function passkey(args) {
-  const action = args[0];
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  const action = positionals[0];
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for agent passkey: ${positionals[1]}` });
+  }
   if (action !== "enroll") {
     fail({ code: "BAD_USAGE", message: "Usage: run402 agent passkey enroll" });
   }
@@ -152,10 +178,10 @@ export async function run(sub, args) {
       await contact(args);
       return;
     case "status":
-      await status();
+      await status(args);
       return;
     case "verify-email":
-      await verifyEmail();
+      await verifyEmail(args);
       return;
     case "passkey":
       await passkey(args);

package/lib/apps.mjs

@@ -1,6 +1,7 @@
 import { allowanceAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -9,7 +10,7 @@ Usage:
 
 Subcommands:
   browse  [--tag <tag>]                   Browse public apps
-  fork    <version_id> <name> [--tier <tier>] [--subdomain <name>]
+  fork    <version_id> <name> [--subdomain <name>]
                                            Fork a published app into your own project
   publish <id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
                                            Publish a project as an app
@@ -22,7 +23,7 @@ Subcommands:
 Examples:
   run402 apps browse
   run402 apps browse --tag auth
-  run402 apps fork ver_abc123 my-todo --tier prototype
+  run402 apps fork ver_abc123 my-todo
   run402 apps publish prj_abc123 --description "Todo app" --tags todo,auth --visibility public --fork-allowed
   run402 apps versions prj_abc123
   run402 apps inspect ver_abc123
@@ -54,12 +55,11 @@ Arguments:
   <name>              Name for the forked project
 
 Options:
-  --tier <tier>       Tier for the new project (default: prototype)
   --subdomain <name>  Claim a subdomain for the forked project
 
 Examples:
   run402 apps fork ver_abc123 my-todo
-  run402 apps fork ver_abc123 my-todo --tier hobby --subdomain todo-v2
+  run402 apps fork ver_abc123 my-todo --subdomain todo-v2
 `,
   publish: `run402 apps publish — Publish a project as an app
 
@@ -137,9 +137,16 @@ Examples:
 };
 
 async function browse(args) {
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--tag"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const extra = positionalArgs(parsedArgs, valueFlags);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps browse: ${extra[0]}` });
+  }
   const tags = [];
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--tag" && args[i + 1]) tags.push(args[++i]);
+  for (let i = 0; i < parsedArgs.length; i++) {
+    if (parsedArgs[i] === "--tag") tags.push(parsedArgs[++i]);
   }
   try {
     const data = await getSdk().apps.browse(tags.length > 0 ? tags : undefined);
@@ -150,18 +157,24 @@ async function browse(args) {
 }
 
 async function fork(versionId, name, args) {
-  const opts = { tier: "prototype", subdomain: undefined };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
-    if (args[i] === "--subdomain" && args[i + 1]) opts.subdomain = args[++i];
+  const parsedArgs = normalizeArgv([versionId, name, ...args].filter((arg) => arg !== undefined));
+  const valueFlags = ["--subdomain"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  if (positionals.length < 2) {
+    fail({ code: "BAD_USAGE", message: "Missing <version_id> and/or <name>." });
   }
+  if (positionals.length > 2) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[2]}` });
+  }
+  const opts = { subdomain: flagValue(parsedArgs, "--subdomain") ?? undefined };
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/fork/v1");
 
   try {
     const data = await getSdk().apps.fork({
-      versionId,
-      name,
+      versionId: positionals[0],
+      name: positionals[1],
       subdomain: opts.subdomain,
     });
 
@@ -181,15 +194,24 @@ async function fork(versionId, name, args) {
 }
 
 async function publish(projectId, args) {
-  const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--description" && args[i + 1]) opts.description = args[++i];
-    if (args[i] === "--tags" && args[i + 1]) opts.tags = args[++i].split(",");
-    if (args[i] === "--visibility" && args[i + 1]) opts.visibility = args[++i];
-    if (args[i] === "--fork-allowed") opts.forkAllowed = true;
+  const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
+  const valueFlags = ["--description", "--tags", "--visibility"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  if (positionals.length < 1) {
+    fail({ code: "BAD_USAGE", message: "Missing <id>." });
   }
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps publish: ${positionals[1]}` });
+  }
+  const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
+  opts.description = flagValue(parsedArgs, "--description") ?? undefined;
+  opts.tags = flagValue(parsedArgs, "--tags")?.split(",");
+  opts.visibility = flagValue(parsedArgs, "--visibility") ?? undefined;
+  if (opts.visibility) assertAllowedValue(opts.visibility, ["public", "unlisted", "private"], "--visibility");
+  if (parsedArgs.includes("--fork-allowed")) opts.forkAllowed = true;
   try {
-    const data = await getSdk().apps.publish(projectId, {
+    const data = await getSdk().apps.publish(positionals[0], {
       description: opts.description,
       tags: opts.tags,
       visibility: opts.visibility,
@@ -201,21 +223,30 @@ async function publish(projectId, args) {
   }
 }
 
-async function versions(projectId) {
+async function versions(projectId, args = []) {
+  const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  if (positionals.length !== 1) {
+    fail({ code: "BAD_USAGE", message: positionals.length === 0 ? "Missing <id>." : `Unexpected argument for apps versions: ${positionals[1]}` });
+  }
   try {
-    const data = await getSdk().apps.listVersions(projectId);
+    const data = await getSdk().apps.listVersions(positionals[0]);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function inspect(versionId) {
-  if (!versionId) {
-    fail({ code: "BAD_USAGE", message: "Missing version ID" });
+async function inspect(versionId, args = []) {
+  const parsedArgs = normalizeArgv([versionId, ...args].filter((arg) => arg !== undefined));
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  if (positionals.length !== 1) {
+    fail({ code: "BAD_USAGE", message: positionals.length === 0 ? "Missing version ID" : `Unexpected argument for apps inspect: ${positionals[1]}` });
   }
   try {
-    const data = await getSdk().apps.getApp(versionId);
+    const data = await getSdk().apps.getApp(positionals[0]);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -223,26 +254,47 @@ async function inspect(versionId) {
 }
 
 async function update(projectId, versionId, args) {
-  const opts = {};
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--description" && args[i + 1]) opts.description = args[++i];
-    if (args[i] === "--tags" && args[i + 1]) opts.tags = args[++i].split(",");
-    if (args[i] === "--visibility" && args[i + 1]) opts.visibility = args[++i];
-    if (args[i] === "--fork-allowed") opts.fork_allowed = true;
-    if (args[i] === "--no-fork") opts.fork_allowed = false;
+  const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
+  const valueFlags = ["--description", "--tags", "--visibility"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--no-fork", "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  if (positionals.length < 2) {
+    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  }
+  if (positionals.length > 2) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps update: ${positionals[2]}` });
+  }
+  if (parsedArgs.includes("--fork-allowed") && parsedArgs.includes("--no-fork")) {
+    fail({ code: "BAD_USAGE", message: "Provide either --fork-allowed or --no-fork, not both." });
   }
+  const opts = {};
+  opts.description = flagValue(parsedArgs, "--description") ?? undefined;
+  opts.tags = flagValue(parsedArgs, "--tags")?.split(",");
+  opts.visibility = flagValue(parsedArgs, "--visibility") ?? undefined;
+  if (opts.visibility) assertAllowedValue(opts.visibility, ["public", "unlisted", "private"], "--visibility");
+  if (parsedArgs.includes("--fork-allowed")) opts.fork_allowed = true;
+  if (parsedArgs.includes("--no-fork")) opts.fork_allowed = false;
   try {
-    await getSdk().apps.updateVersion(projectId, versionId, opts);
-    console.log(JSON.stringify({ status: "ok", project_id: projectId, version_id: versionId }));
+    await getSdk().apps.updateVersion(positionals[0], positionals[1], opts);
+    console.log(JSON.stringify({ status: "ok", project_id: positionals[0], version_id: positionals[1] }));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function deleteVersion(projectId, versionId) {
+async function deleteVersion(projectId, versionId, args = []) {
+  const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  if (positionals.length < 2) {
+    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  }
+  if (positionals.length > 2) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps delete: ${positionals[2]}` });
+  }
   try {
-    await getSdk().apps.deleteVersion(projectId, versionId);
-    console.log(JSON.stringify({ status: "ok", message: `Version ${versionId} deleted.` }));
+    await getSdk().apps.deleteVersion(positionals[0], positionals[1]);
+    console.log(JSON.stringify({ status: "ok", message: `Version ${positionals[1]} deleted.` }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -255,10 +307,10 @@ export async function run(sub, args) {
     case "browse":   await browse(args); break;
     case "fork":     await fork(args[0], args[1], args.slice(2)); break;
     case "publish":  await publish(args[0], args.slice(1)); break;
-    case "versions": await versions(args[0]); break;
-    case "inspect":  await inspect(args[0]); break;
+    case "versions": await versions(args[0], args.slice(1)); break;
+    case "inspect":  await inspect(args[0], args.slice(1)); break;
     case "update":   await update(args[0], args[1], args.slice(2)); break;
-    case "delete":   await deleteVersion(args[0], args[1]); break;
+    case "delete":   await deleteVersion(args[0], args[1], args.slice(2)); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/argparse.mjs

@@ -25,6 +25,13 @@ export function assertKnownFlags(args = [], knownFlags = [], flagsWithValues = [
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (valueFlags.has(arg)) {
+      if (i + 1 >= args.length || (typeof args[i + 1] === "string" && args[i + 1].startsWith("--"))) {
+        fail({
+          code: "BAD_FLAG",
+          message: `${arg} requires a value`,
+          details: { flag: arg },
+        });
+      }
       i += 1;
       continue;
     }
@@ -47,7 +54,7 @@ export function failUnknownFlag(flag, knownFlags = []) {
 export function flagValue(args, flag) {
   const idx = args.indexOf(flag);
   if (idx === -1) return null;
-  if (idx + 1 >= args.length) {
+  if (idx + 1 >= args.length || (typeof args[idx + 1] === "string" && args[idx + 1].startsWith("--"))) {
     fail({
       code: "BAD_FLAG",
       message: `${flag} requires a value`,
@@ -99,6 +106,26 @@ export function parseIntegerFlag(name, value, { min = 1, max = Number.POSITIVE_I
   return n;
 }
 
+export function assertAllowedValue(value, allowed, fieldName) {
+  if (!allowed.includes(value)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${fieldName} must be one of: ${allowed.join(", ")}`,
+      details: { field: fieldName, value, allowed },
+    });
+  }
+}
+
+export function validateEvmAddress(value, fieldName = "address") {
+  if (typeof value !== "string" || !/^0x[a-fA-F0-9]{40}$/.test(value)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${fieldName} must be a 0x-prefixed 20-byte EVM address`,
+      details: { field: fieldName, value },
+    });
+  }
+}
+
 export function failBadProjectId(value) {
   fail({
     code: "BAD_PROJECT_ID",
@@ -206,6 +233,31 @@ export function positionalArgs(args = [], flagsWithValues = []) {
   return out;
 }
 
+export function requirePositionalCount(args = [], flagsWithValues = [], opts = {}) {
+  const {
+    min = 0,
+    max = min,
+    command = "command",
+    missing = "Missing required argument.",
+  } = opts;
+  const pos = positionalArgs(args, flagsWithValues);
+  if (pos.length < min) {
+    fail({
+      code: "BAD_USAGE",
+      message: missing,
+      hint: command,
+    });
+  }
+  if (pos.length > max) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for ${command}: ${pos[max]}`,
+      hint: `Use \`${command}\`.`,
+    });
+  }
+  return pos;
+}
+
 // 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

package/lib/billing.mjs

@@ -1,6 +1,6 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { parseIntegerFlag } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
 
 const HELP = `run402 billing — Email billing accounts, Stripe tier checkout, email packs
 
@@ -122,13 +122,6 @@ Examples:
 `,
 };
 
-function parseFlag(args, flag) {
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === flag && args[i + 1]) return args[i + 1];
-  }
-  return null;
-}
-
 function requireSingleBillingIdentifier(email, wallet) {
   if (email && wallet) {
     fail({
@@ -147,7 +140,13 @@ function requireSingleBillingIdentifier(email, wallet) {
 }
 
 async function createEmail(args) {
-  const email = args[0];
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  const email = positionals[0];
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing create-email: ${positionals[1]}` });
+  }
   if (!email) {
     fail({
       code: "BAD_USAGE",
@@ -164,8 +163,14 @@ async function createEmail(args) {
 }
 
 async function linkWallet(args) {
-  const accountId = args[0];
-  const wallet = args[1];
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  const accountId = positionals[0];
+  const wallet = positionals[1];
+  if (positionals.length > 2) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[2]}` });
+  }
   if (!accountId || !wallet) {
     fail({
       code: "BAD_USAGE",
@@ -182,7 +187,14 @@ async function linkWallet(args) {
 }
 
 async function tierCheckout(args) {
-  const tier = args[0];
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--email", "--wallet"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  const tier = positionals[0];
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing tier-checkout: ${positionals[1]}` });
+  }
   if (!tier) {
     fail({
       code: "BAD_USAGE",
@@ -190,8 +202,8 @@ async function tierCheckout(args) {
       hint: "run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]",
     });
   }
-  const email = parseFlag(args, "--email");
-  const wallet = parseFlag(args, "--wallet");
+  const email = flagValue(parsedArgs, "--email");
+  const wallet = flagValue(parsedArgs, "--wallet");
   requireSingleBillingIdentifier(email, wallet);
   try {
     const data = await getSdk().billing.tierCheckout(tier, { email: email ?? undefined, wallet: wallet ?? undefined });
@@ -202,8 +214,15 @@ async function tierCheckout(args) {
 }
 
 async function buyPack(args) {
-  const email = parseFlag(args, "--email");
-  const wallet = parseFlag(args, "--wallet");
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--email", "--wallet"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const extra = positionalArgs(parsedArgs, valueFlags);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing buy-email-pack: ${extra[0]}` });
+  }
+  const email = flagValue(parsedArgs, "--email");
+  const wallet = flagValue(parsedArgs, "--wallet");
   requireSingleBillingIdentifier(email, wallet);
   try {
     const data = await getSdk().billing.buyEmailPack({ email: email ?? undefined, wallet: wallet ?? undefined });
@@ -214,8 +233,15 @@ async function buyPack(args) {
 }
 
 async function autoRecharge(args) {
-  const accountId = args[0];
-  const state = args[1];
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--threshold"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  const accountId = positionals[0];
+  const state = positionals[1];
+  if (positionals.length > 2) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[2]}` });
+  }
   if (!accountId || !state || !["on", "off"].includes(state)) {
     fail({
       code: "BAD_USAGE",
@@ -223,8 +249,8 @@ async function autoRecharge(args) {
       hint: "run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]",
     });
   }
-  const thresholdStr = parseFlag(args, "--threshold");
-  const threshold = args.includes("--threshold")
+  const thresholdStr = flagValue(parsedArgs, "--threshold");
+  const threshold = parsedArgs.includes("--threshold")
     ? parseIntegerFlag("--threshold", thresholdStr, { min: 0 })
     : undefined;
   try {
@@ -240,7 +266,13 @@ async function autoRecharge(args) {
 }
 
 async function balance(args) {
-  const id = args[0];
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"]);
+  const positionals = positionalArgs(parsedArgs);
+  const id = positionals[0];
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing balance: ${positionals[1]}` });
+  }
   if (!id) {
     fail({
       code: "BAD_USAGE",
@@ -257,7 +289,14 @@ async function balance(args) {
 }
 
 async function history(args) {
-  const id = args[0];
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--limit"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(parsedArgs, valueFlags);
+  const id = positionals[0];
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing history: ${positionals[1]}` });
+  }
   if (!id) {
     fail({
       code: "BAD_USAGE",
@@ -265,9 +304,11 @@ async function history(args) {
       hint: "run402 billing history <email-or-wallet> [--limit <n>]",
     });
   }
-  const limit = parseFlag(args, "--limit") || "50";
+  const limit = parsedArgs.includes("--limit")
+    ? parseIntegerFlag("--limit", flagValue(parsedArgs, "--limit"), { min: 1 })
+    : 50;
   try {
-    const data = await getSdk().billing.getHistory(id, Number(limit));
+    const data = await getSdk().billing.getHistory(id, limit);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);

package/lib/blob.mjs

@@ -438,8 +438,8 @@ async function put(projectId, argv) {
   const resolvedId = resolveProjectId(opts.project);
 
   if (opts.positional.length === 0) die("At least one file path is required");
-  if (opts.immutable && opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
-    die("--key with --immutable across multiple files requires a directory prefix (ending with /)");
+  if (opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
+    die("--key across multiple files requires a directory prefix (ending with /)");
   }
 
   const results = [];

package/lib/cdn.mjs

@@ -16,6 +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";
 
 const HELP = `run402 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -73,14 +74,19 @@ function die(msg, exit_code = 1) {
 }
 
 function parseArgs(args) {
-  const opts = { positional: [] };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--sha") opts.sha = args[++i];
-    else if (a === "--timeout") opts.timeout = Number(args[++i]);
-    else if (a === "--project") opts.project = args[++i];
-    else if (a.startsWith("--")) die(`Unknown option: ${a}`);
-    else opts.positional.push(a);
+  const normalized = normalizeArgv(args);
+  const valueFlags = ["--sha", "--timeout", "--project"];
+  assertKnownFlags(normalized, [...valueFlags, "--help", "-h"], valueFlags);
+  const opts = {
+    positional: positionalArgs(normalized, valueFlags),
+    sha: flagValue(normalized, "--sha"),
+    timeout: normalized.includes("--timeout")
+      ? parseIntegerFlag("--timeout", flagValue(normalized, "--timeout"), { min: 1 })
+      : undefined,
+    project: flagValue(normalized, "--project"),
+  };
+  if (opts.positional.length > 1) {
+    die(`Unexpected argument for cdn wait-fresh: ${opts.positional[1]}`);
   }
   return opts;
 }
@@ -92,6 +98,13 @@ async function waitFresh(projectId, argv) {
   if (opts.positional.length === 0) die("URL required");
   const url = opts.positional[0];
   if (!opts.sha) die("--sha is required");
+  if (!/^[a-fA-F0-9]{64}$/.test(opts.sha)) {
+    fail({
+      code: "BAD_FLAG",
+      message: "--sha must be a 64-character hex SHA-256 digest",
+      details: { flag: "--sha", value: opts.sha },
+    });
+  }
 
   const timeoutMs = (opts.timeout ?? 60) * 1000;
   try {