run402 1.69.4 → 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/ai.mjs

@@ -1,7 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { resolvePositionalProject } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, resolvePositionalProject } from "./argparse.mjs";
 
 const HELP = `run402 ai — AI translation and moderation tools
 
@@ -103,20 +103,19 @@ 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;
-}
-
 // translate has value-bearing flags (--to, --from, --context, --project) that
 // must not be mistaken for positional bare args when prefix-matching.
 const TRANSLATE_VALUE_FLAGS = ["--to", "--from", "--context", "--project"];
 
 async function translate(args) {
+  args = normalizeArgv(args);
+  assertKnownFlags(args, TRANSLATE_VALUE_FLAGS, TRANSLATE_VALUE_FLAGS);
+
   // --project <id> wins over positional, mirroring previous behavior.
-  const projectOpt = parseFlag(args, "--project");
+  const projectOpt = flagValue(args, "--project");
+  const to = flagValue(args, "--to");
+  const from = flagValue(args, "--from");
+  const context = flagValue(args, "--context");
   let projectId;
   let rest;
   if (projectOpt) {
@@ -139,10 +138,6 @@ async function translate(args) {
     break;
   }
 
-  const to = parseFlag(args, "--to");
-  const from = parseFlag(args, "--from");
-  const context = parseFlag(args, "--context");
-
   if (!text) {
     fail({
       code: "BAD_USAGE",
@@ -165,7 +160,10 @@ async function translate(args) {
 const MODERATE_VALUE_FLAGS = ["--project"];
 
 async function moderate(args) {
-  const projectOpt = parseFlag(args, "--project");
+  args = normalizeArgv(args);
+  assertKnownFlags(args, MODERATE_VALUE_FLAGS, MODERATE_VALUE_FLAGS);
+
+  const projectOpt = flagValue(args, "--project");
   let projectId;
   let rest;
   if (projectOpt) {
@@ -203,7 +201,10 @@ async function moderate(args) {
 }
 
 async function usage(args) {
-  const projectOpt = parseFlag(args, "--project");
+  args = normalizeArgv(args);
+  assertKnownFlags(args, MODERATE_VALUE_FLAGS, MODERATE_VALUE_FLAGS);
+
+  const projectOpt = flagValue(args, "--project");
   let projectId;
   if (projectOpt) {
     projectId = resolveProjectId(projectOpt);

package/lib/allowance.mjs

@@ -1,6 +1,7 @@
 import { readAllowance, saveAllowance, ALLOWANCE_FILE } 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 allowance — Manage your agent allowance
 
@@ -258,17 +259,25 @@ async function checkout(args) {
       hint: "Run: run402 allowance create",
     });
   }
-  let amount = null;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--amount" && args[i + 1]) amount = parseInt(args[++i], 10);
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--amount", "--help", "-h"], ["--amount"]);
+  const bare = positionalArgs(parsedArgs, ["--amount"]);
+  if (bare.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for allowance checkout: ${bare[0]}`,
+      details: { argument: bare[0] },
+    });
   }
-  if (!amount) {
+  const amountRaw = flagValue(parsedArgs, "--amount");
+  if (amountRaw === null) {
     fail({
       code: "BAD_USAGE",
       message: "Missing --amount <usd_micros>",
       hint: "e.g. --amount 5000000 for $5",
     });
   }
+  const amount = parseIntegerFlag("--amount", amountRaw, { min: 1 });
   try {
     const data = await getSdk().billing.createCheckout(w.address, amount);
     console.log(JSON.stringify(data, null, 2));
@@ -286,10 +295,17 @@ async function history(args) {
       hint: "Run: run402 allowance create",
     });
   }
-  let limit = 20;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--limit" && args[i + 1]) limit = parseInt(args[++i], 10);
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--limit", "--help", "-h"], ["--limit"]);
+  const bare = positionalArgs(parsedArgs, ["--limit"]);
+  if (bare.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for allowance history: ${bare[0]}`,
+      details: { argument: bare[0] },
+    });
   }
+  const limit = parseIntegerFlag("--limit", flagValue(parsedArgs, "--limit"), { min: 1, def: 20 });
   try {
     const data = await getSdk().billing.history(w.address, limit);
     console.log(JSON.stringify(data, null, 2));

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`,
@@ -75,6 +82,13 @@ export function parseIntegerFlag(name, value, { min = 1, max = Number.POSITIVE_I
     });
   }
   const n = Number.parseInt(raw, 10);
+  if (!Number.isSafeInteger(n)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be a safe integer, got: ${raw}`,
+      details: { flag: name, value: raw },
+    });
+  }
   if (n < min) {
     fail({
       code: "BAD_FLAG",
@@ -92,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",
@@ -199,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/auth.mjs

@@ -1,6 +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";
 
 const HELP = `run402 auth — Manage project user authentication
 
@@ -230,6 +231,61 @@ Examples:
 `,
 };
 
+const AUTH_FLAGS = {
+  "magic-link": {
+    known: ["--email", "--redirect", "--intent", "--state", "--project", "--help", "-h"],
+    values: ["--email", "--redirect", "--intent", "--state", "--project"],
+  },
+  "create-user": {
+    known: ["--email", "--admin", "--invite", "--redirect", "--state", "--project", "--help", "-h"],
+    values: ["--email", "--admin", "--redirect", "--state", "--project"],
+  },
+  "invite-user": {
+    known: ["--email", "--redirect", "--admin", "--state", "--project", "--help", "-h"],
+    values: ["--email", "--redirect", "--admin", "--state", "--project"],
+  },
+  verify: {
+    known: ["--token", "--project", "--help", "-h"],
+    values: ["--token", "--project"],
+  },
+  "set-password": {
+    known: ["--token", "--new", "--current", "--project", "--help", "-h"],
+    values: ["--token", "--new", "--current", "--project"],
+  },
+  settings: {
+    known: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--project", "--help", "-h"],
+    values: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--project"],
+  },
+  "passkey-register-options": {
+    known: ["--token", "--app-origin", "--project", "--help", "-h"],
+    values: ["--token", "--app-origin", "--project"],
+  },
+  "passkey-register-verify": {
+    known: ["--token", "--challenge", "--response", "--label", "--project", "--help", "-h"],
+    values: ["--token", "--challenge", "--response", "--label", "--project"],
+  },
+  "passkey-login-options": {
+    known: ["--app-origin", "--email", "--project", "--help", "-h"],
+    values: ["--app-origin", "--email", "--project"],
+  },
+  "passkey-login-verify": {
+    known: ["--challenge", "--response", "--project", "--help", "-h"],
+    values: ["--challenge", "--response", "--project"],
+  },
+  passkeys: {
+    known: ["--token", "--project", "--help", "-h"],
+    values: ["--token", "--project"],
+  },
+  "delete-passkey": {
+    known: ["--token", "--id", "--project", "--help", "-h"],
+    values: ["--token", "--id", "--project"],
+  },
+  providers: {
+    known: ["--project", "--help", "-h"],
+    values: ["--project"],
+  },
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -557,10 +613,15 @@ async function providers(args) {
 
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") { console.log(HELP); process.exit(0); }
-  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+  args = normalizeArgv(args);
+  if (Array.isArray(args) && hasHelp(args)) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
+  const flagSpec = AUTH_FLAGS[sub];
+  if (flagSpec) {
+    assertKnownFlags(args, flagSpec.known, flagSpec.values);
+  }
   switch (sub) {
     case "magic-link": await magicLink(args); break;
     case "verify": await verify(args); break;