requestshield 0.1.6 → 0.1.8

package/skills/requestshield/references/cli.md

@@ -3,14 +3,42 @@
 Check `requestshield --version` and `requestshield --help` against this guide.
 An older published version may not contain these commands. Use the CLI for its
 supported application and credential operations; do not invent endpoints for
-unavailable commands.
+unavailable commands. Command/group help comes from the same registry as parsing.
+Legacy aliases are removed; use singular app/secret groups and positional names.
+All result commands support --json, with one document on stdout and diagnostics
+on stderr. Human output is the default; help/version remain text. JSON does not
+skip confirmation: supply --yes only when the action is authorized.
+
+## Public integration contract
+
+```console
+requestshield contract
+requestshield contract --json
+```
+
+This public read fetches the selected environment's customer-docs manifest without
+login, local session access or file writes. It accepts no version-selection flag.
+JSON returns `{data: ...}` with `schemaVersion`, `contractVersion`, `environment`,
+`services.challengeUrl`, `browser`, `backend` and `documentation`.
+Use `browser.scriptUrl` with its matching `integrity`, `tokenHeader` and
+`availableModes`. Merge `browser.cspAdditions` into the application's existing CSP.
+Use `backend.sdkVersion`, `minJdk`, `mavenRepository`, `core` and `springBoot3`
+coordinates for the selected backend path. Configure the same returned challenge
+URL in both SDKs. Metadata describes a selected release, not service health or
+application protection.
+
+`CONTRACT_NOT_PUBLISHED` means the docs host returned 404; `CONTRACT_FETCH_FAILED`
+means network/HTTP failure; `CONTRACT_INVALID` means the response failed validation.
+These exit 1. Do not invent a manifest or silently substitute another environment
+or SDK version. An older CLI may not implement this command: use verified release
+documentation for a manual integration and report the missing command or manifest.
 
 ## Authentication and local commands
 
 ```console
-requestshield signin [--no-open]
+requestshield login [--no-open]
 requestshield auth status [--json]
-requestshield signout
+requestshield logout
 requestshield --help
 requestshield --version
 ```
@@ -28,11 +56,11 @@ provider grant.
 ## Applications
 
 ```console
-requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
-requestshield apps get <app-key>
-requestshield apps rename <app-key> --name <name> [--idempotency-key <key>]
-requestshield apps enable <app-key> [--idempotency-key <key>]
-requestshield apps disable <app-key> [--idempotency-key <key>] [--yes]
+requestshield app list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
+requestshield app get <app-key>
+requestshield app rename <app-key> <name> [--idempotency-key <key>]
+requestshield app enable <app-key> [--idempotency-key <key>]
+requestshield app disable <app-key> [--idempotency-key <key>] [--yes]
 ```
 
 These commands require sign-in. Existing-app commands use exact App Keys; names
@@ -41,8 +69,8 @@ fails for repeated cursors or unfinished traversal at that bound. It cannot be
 combined with `--cursor`. For name discovery, inspect all necessary pages and
 resolve ambiguity with the user before choosing an App Key.
 
-JSON list output is `{data:Application[],nextCursor}`. Detail and rename output
-is `{data:Application}`. Application has exactly `appKey`, `name`, `status`,
+JSON list output is `{data:Application[],nextCursor}`. Detail and rename with
+`--json` return `{data:Application}`. Application has exactly `appKey`, `name`, `status`,
 `createdAt`, `updatedAt`. Status is `pending`, `enabled`, `disabled`, `revoked`
 or `attention_required`; it describes configuration, not traffic or enforcement.
 Pending, attention and disabled states do not expose the exact credential state.
@@ -55,10 +83,10 @@ values stay out of tool output and transcripts. Give the exact command and
 confirm storage by presence only.
 
 ```console
-requestshield keys create --app-name <name> [--idempotency-key <key>]
-requestshield keys rotate <app-key> [--idempotency-key <key>] [--yes]
-requestshield keys reveal <app-key> [--yes]
-requestshield keys revoke <app-key> [--idempotency-key <key>] [--yes]
+requestshield app create <name> [--idempotency-key <key>]
+requestshield secret rotate <app-key> [--idempotency-key <key>] [--yes]
+requestshield secret reveal <app-key> [--yes]
+requestshield secret revoke <app-key> [--idempotency-key <key>] [--yes]
 ```
 
 Create makes a new application and initial secret. Rotate preserves the App Key
@@ -83,7 +111,9 @@ without running it. HTTP 202 and `enabled` do not prove global propagation.
 
 ```console
 requestshield agent setup [--codex | --claude] [--force]
+requestshield agent status [--codex | --claude]
 requestshield update check
+requestshield update apply [--yes]
 ```
 
 Agent setup copies the skill to `~/.agents/skills/requestshield` for Codex or
@@ -91,17 +121,51 @@ Agent setup copies the skill to `~/.agents/skills/requestshield` for Codex or
 agent or asks if both are available. `--force` replaces an existing installation.
 It does not edit repository `AGENTS.md` or customer application code.
 
-Production update check queries npm and asks before a global installation.
-Explain that target before accepting an update; it does not update a pinned
-invocation or source checkout. Repository-only QAT/STG runners return local
-source-update guidance without registry access or installation.
-
-## Unavailable commands
-
-Integration contract, service health, credential-status metadata, challenge
-volume and billing are not implemented CLI capabilities. `contract`,
-`challenge volume` and `get billing` fail with `COMMAND_UNAVAILABLE` before
-configuration, authentication or network access. `server` and
-`credentials status` are unsupported. Use the published SDK documentation for
-the chosen release and safe browser/backend observations for integration checks.
-Do not infer traffic or enforcement from `apps get` status.
+Agent status inspects both agents by default and returns `installed`, `missing`
+or `invalid` file state. It does not establish that an agent has loaded the Skill.
+
+Production update check queries npm without prompting or installing. Update apply
+checks and asks before installing the exact available version globally; --yes
+explicitly confirms. Explain the target when an update is requested. A global
+update does not change a pinned invocation or source checkout. Repository-only
+QAT/STG runners return local source-update guidance for both commands without
+registry access or installation.
+
+## Complete command catalog
+
+All result commands support --json. See command help for additional flags.
+
+| Command after `requestshield` | Availability |
+| --- | --- |
+| `--help`, `-h` | Implemented |
+| `--version`, `-v` | Implemented |
+| `login [--no-open]` | Implemented |
+| `logout` | Implemented |
+| `auth status` | Implemented |
+| `app create <name>` | Implemented |
+| `app list` | Implemented |
+| `app get <app-key>` | Implemented |
+| `app rename <app-key> <name>` | Implemented |
+| `app enable <app-key>` | Implemented |
+| `app disable <app-key>` | Implemented |
+| `secret rotate <app-key>` | Implemented |
+| `secret reveal <app-key>` | Implemented |
+| `secret revoke <app-key>` | Implemented |
+| `agent setup [--codex \| --claude] [--force]` | Implemented |
+| `agent status [--codex \| --claude]` | Implemented |
+| `update check` | Implemented |
+| `update apply [--yes]` | Implemented |
+| `contract` | Implemented |
+| `service status` | [coming soon] |
+| `secret status <app-key>` | [coming soon] |
+| `usage challenges <app-key>` | [coming soon] |
+| `billing get <app-key>` | [coming soon] |
+
+The four placeholders validate syntax and return COMMAND_UNAVAILABLE with exit
+code 2 before configuration, authentication, network or writes. Usage accepts
+--from, --to and --granularity hour|day as placeholder syntax only. Never use
+placeholder results as evidence, infer secret state from application status or
+call reveal as a status probe. Doctor and app watch are not commands.
+
+Use published SDK documentation for the selected release and safe browser/backend
+observations for integration checks. App status is not traffic or enforcement.

package/skills/requestshield/references/integration-planning.md

@@ -72,7 +72,7 @@ Confirm that the backend actually reads or maps that variable before treating it
 valid RequestShield credential.
 
 If the App Key is known, inspect its aggregate application configuration with
-`requestshield apps get <app-key>`. That status does not prove the exact credential
+`requestshield app get <app-key>`. That status does not prove the exact credential
 state or that the deployed backend has received its secret. The CLI has no separate
 credential-status command; check runtime injection by presence only.
 
@@ -91,7 +91,7 @@ Report only what was confirmed:
 | No credential pair has been provisioned | Ask the user to provision credentials before continuing with backend setup. |
 
 If no pair has been provisioned yet, the user creates it. You may run the read-only
-`requestshield apps list` to see whether an application already exists. Everything that
+`requestshield app list` to see whether an application already exists. Everything that
 mints or changes a secret stays with the user; see **Key and secret management** in
 `SKILL.md`.
 
@@ -180,11 +180,13 @@ last one to run wins rather than the two merging.
 
 ## Contract check
 
-After detecting the current integration, consult the customer Browser SDK and Java
-SDK documentation for the selected release. Confirm the script URL, token header,
-supported browser modes, backend languages and minimum Java version before editing.
-The CLI integration-contract command is unavailable; do not require it as a preflight
-or fabricate its output.
+After detecting the current integration, run `requestshield contract --json`
+with the runner for the intended environment. It requires no login. Confirm the
+script URL and matching integrity, token header, available modes, CSP additions,
+challenge URL and Java/Maven requirements, then consult its documentation links.
+See `cli.md` for field names and failure handling. If the command or manifest is
+unavailable, report that gap and use verified customer documentation for the
+selected release; never fabricate values or substitute another environment.
 
 The documented backend paths here require Java 17 or newer. The Spring Boot starter
 also requires Spring Boot 3 with Spring MVC; Java core is a separate supported path.
@@ -320,7 +322,7 @@ the page issues the protected request.
 Always report the evidence with file and line references:
 
 ```text
-Backend: theair-customer-backend/build.gradle.kts
+Backend: customer-backend/build.gradle.kts
   Java 21           - java.toolchain.languageVersion (line 14)
   Spring Boot 3.2.1 - org.springframework.boot plugin (line 3)
   Spring MVC        - spring-boot-starter-web (line 20)

package/skills/requestshield/references/troubleshooting.md

@@ -8,7 +8,7 @@ header, the backend never verified it, or one token was verified twice.
 
 ```console
 requestshield auth status --json
-requestshield apps get <app-key>
+requestshield app get <app-key>
 ```
 
 Session status is local only. Application status is configuration state, not
@@ -105,7 +105,7 @@ If the API Secret appears in a repo, a log, a build artifact, or a chat transcri
 rotate it — deleting the line does not un-expose it:
 
 ```bash
-requestshield keys rotate <app-key>
+requestshield secret rotate <app-key>
 ```
 
 The App Key is unchanged, so no browser edit is needed. Deploy the new secret to backend

package/src/api-client.mjs

@@ -107,7 +107,7 @@ export class ManagementApiClient {
         if (!response.ok) {
           const providerCode = objectString(body?.error, "code");
           const safeCode = providerCode && API_ERRORS.has(providerCode) ? providerCode : undefined;
-          const guidance = response.status === 401 ? "; run `requestshield signin` again"
+          const guidance = response.status === 401 ? "; run `requestshield login` again"
             : safeCode === "insufficient_scope" ? "; this session lacks the required permissions" : "";
           throw new CliError(`RequestShield API error: HTTP ${response.status}${safeCode ? ` (${safeCode})` : ""}${guidance}`, {
             code: response.status === 401 ? "UNAUTHENTICATED" : "API_ERROR",

package/src/args.mjs

@@ -1,145 +1,137 @@
 // @ts-check
 import { CliError } from "./errors.mjs";
+import { COMMAND_REGISTRY, commandUsage, renderHelp } from "./command-registry.mjs";
 
-const HELP = `RequestShield CLI
-
-Usage:
-  requestshield signin [--no-open]
-  requestshield auth status [--json]
-  requestshield signout
-  requestshield keys create --app-name <name> [--idempotency-key <key>]
-  requestshield keys rotate <app-key> [--idempotency-key <key>] [--yes]
-  requestshield keys reveal <app-key> [--yes]
-  requestshield keys revoke <app-key> [--idempotency-key <key>] [--yes]
-  requestshield apps list [--json] [--limit <1-100>] [--cursor <cursor> | --all]
-  requestshield apps get <app-key>
-  requestshield apps rename <app-key> --name <name> [--idempotency-key <key>]
-  requestshield apps enable <app-key> [--idempotency-key <key>]
-  requestshield apps disable <app-key> [--idempotency-key <key>] [--yes]
-  requestshield agent setup [--force]
-  requestshield agent setup --codex [--force]
-  requestshield agent setup --claude [--force]
-  requestshield update check
-  requestshield --help
-  requestshield --version
-
-List defaults to one page. Use --all for a bounded complete listing.
-contract, challenge volume and get billing are not available yet.`;
+export const HELP = renderHelp();
 
 /**
- * @typedef {{command:"help",help:string} | {command:"version"|"update-check"|"signout"}
- * | {command:"signin",noOpen:boolean} | {command:"auth-status",json:boolean}
- * | {command:"keys-create",appName:string,yes:boolean,idempotencyKey?:string}
- * | {command:"keys-rotate"|"keys-reveal"|"keys-revoke",appKey:string,yes:boolean,idempotencyKey?:string}
- * | {command:"apps-list",json:boolean,all:boolean,limit?:number,cursor?:string}
- * | {command:"apps-get",appKey:string}
- * | {command:"apps-rename",appKey:string,name:string,yes:boolean,idempotencyKey?:string}
- * | {command:"apps-enable"|"apps-disable",appKey:string,enabled:boolean,yes:boolean,idempotencyKey?:string}
- * | {command:"agent-setup",agent?:"codex"|"claude",force:boolean}} ParsedArgs
+ * @typedef {{command:"help",help:string} | {command:"version"}
+ * | {command:"update-check"|"logout"|"auth-status"|"contract",json:boolean}
+ * | {command:"update-apply",yes:boolean,json:boolean}
+ * | {command:"login",noOpen:boolean,json:boolean}
+ * | {command:"app-create",appName:string,yes:boolean,json:boolean,idempotencyKey?:string}
+ * | {command:"secret-rotate"|"secret-reveal"|"secret-revoke",appKey:string,yes:boolean,json:boolean,idempotencyKey?:string}
+ * | {command:"app-list",json:boolean,all:boolean,limit?:number,cursor?:string}
+ * | {command:"app-get",appKey:string,json:boolean}
+ * | {command:"app-rename",appKey:string,name:string,yes:boolean,json:boolean,idempotencyKey?:string}
+ * | {command:"app-enable"|"app-disable",appKey:string,enabled:boolean,yes:boolean,json:boolean,idempotencyKey?:string}
+ * | {command:"agent-setup",agent?:"codex"|"claude",force:boolean,json:boolean}
+ * | {command:"agent-status",agent?:"codex"|"claude",json:boolean}} ParsedArgs
  */
 
 /** @param {string[]} argv @returns {ParsedArgs} */
 export function parseArgs(argv) {
-  if (!argv.length || argv.includes("--help") || argv.includes("-h")) return {command:"help",help:HELP};
-  if (argv.length === 1 && ["--version","-v","-V"].includes(argv[0])) return {command:"version"};
-  const [group, action] = argv;
-  if (group === "contract" || group === "challenge" && action === "volume" || group === "get" && action === "billing") {
-    throw new CliError("This command is not available: its Management API endpoint has not been implemented.", {code:"COMMAND_UNAVAILABLE",exitCode:2});
-  }
-  if (group === "signin") {
-    const flags = parseFlags(argv.slice(1), ["--no-open"]);
-    return {command:"signin",noOpen:flags.has("--no-open")};
-  }
-  if (group === "signout") { parseFlags(argv.slice(1), []); return {command:"signout"}; }
-  if (group === "auth" && action === "status") {
-    const flags = parseFlags(argv.slice(2), ["--json"]);
-    return {command:"auth-status",json:flags.has("--json")};
+  if (!argv.length) return {command:"help",help:HELP};
+  const definition = COMMAND_REGISTRY.find((command) => command.path.every((part,index) => argv[index] === part)
+    || command.shortcuts?.includes(argv[0]) && command.path.length === 1);
+  if (!definition) {
+    const group = argv[0];
+    const isGroup = COMMAND_REGISTRY.some((command) => command.path.length > 1 && command.path[0] === group);
+    if (isGroup && (argv.length === 1 || argv.length === 2 && ["--help","-h"].includes(argv[1]))) {
+      return {command:"help",help:renderHelp(group)};
+    }
+    throw invalid("Unknown command. Use requestshield --help to list commands.");
   }
-  if (group === "update" && action === "check") { parseFlags(argv.slice(2), []); return {command:"update-check"}; }
-  if (group === "keys" && action === "create") {
-    const flags = parseFlags(argv.slice(2), ["--yes"], ["--app-name","--idempotency-key"]);
-    const name = flags.get("--app-name");
-    if (typeof name !== "string") usage("keys create --app-name <name> [--idempotency-key <key>]");
-    return {command:"keys-create",appName:applicationName(name),...mutationFlags(flags)};
+  const args = argv.slice(definition.path.length);
+  const endOfOptions = args.indexOf("--");
+  if (args.slice(0,endOfOptions === -1 ? args.length : endOfOptions).some((value) => ["--help","-h"].includes(value))) {
+    return {command:"help",help:renderHelp(definition)};
   }
-  if (group === "keys" && ["rotate","reveal","revoke"].includes(action)) {
-    const appKey = requiredAppKey(argv, `keys ${action} <app-key>`);
-    const flags = parseFlags(argv.slice(3), ["--yes"], action === "reveal" ? [] : ["--idempotency-key"]);
-    return {command:/** @type {"keys-rotate"|"keys-reveal"|"keys-revoke"} */ (`keys-${action}`),appKey,...mutationFlags(flags)};
+  const {flags,positionals} = parseOptions(args,definition.flags);
+  const requiredCount = definition.arguments.filter((argument) => argument.required).length;
+  if (positionals.length < requiredCount || positionals.length > definition.arguments.length) {
+    throw invalid(`Usage: requestshield ${commandUsage(definition)}`);
   }
-  if (group === "apps" && action === "list") {
-    const flags = parseFlags(argv.slice(2), ["--json","--all"], ["--limit","--cursor"]);
-    const limit = flags.get("--limit");
-    if (limit !== undefined && (typeof limit !== "string" || !/^[1-9][0-9]{0,2}$/.test(limit) || Number(limit) > 100)) {
-      throw invalid("--limit must be an integer from 1 to 100");
-    }
-    const cursor = flags.get("--cursor");
-    if (cursor !== undefined && (typeof cursor !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(cursor))) throw invalid("Invalid --cursor");
-    if (cursor !== undefined && flags.has("--all")) throw invalid("--cursor and --all cannot be combined");
-    return {command:"apps-list",json:flags.has("--json"),all:flags.has("--all"),
-      ...(limit !== undefined ? {limit:Number(limit)} : {}),...(typeof cursor === "string" ? {cursor} : {})};
+  /** @type {Record<string,string>} */
+  const values = {};
+  for (const [index,argument] of definition.arguments.entries()) {
+    if (positionals[index] !== undefined) values[argument.field] = argument.kind === "app-name" ? applicationName(positionals[index]) : validateAppKey(positionals[index]);
   }
-  if (group === "apps" && action === "get") {
-    const appKey = requiredAppKey(argv, "apps get <app-key>");
-    parseFlags(argv.slice(3), []);
-    return {command:"apps-get",appKey};
+  if (definition.availability === "placeholder") {
+    throw new CliError("This command is not available yet.",{code:"COMMAND_UNAVAILABLE",exitCode:2});
   }
-  if (group === "apps" && ["rename","enable","disable"].includes(action)) {
-    const appKey = requiredAppKey(argv, `apps ${action} <app-key>${action === "rename" ? " --name <name>" : ""}`);
-    const flags = parseFlags(argv.slice(3), ["--yes"], ["--idempotency-key",...(action === "rename" ? ["--name"] : [])]);
-    if (action === "rename") {
-      const name = flags.get("--name");
-      if (typeof name !== "string") usage("apps rename <app-key> --name <name>");
-      return {command:"apps-rename",appKey,name:applicationName(name),...mutationFlags(flags)};
+  const json = flags.has("--json");
+  switch (definition.id) {
+    case "help": return {command:"help",help:HELP};
+    case "version": return {command:"version"};
+    case "login": return {command:"login",noOpen:flags.has("--no-open"),json};
+    case "logout": case "auth-status": case "update-check": case "contract": return {command:definition.id,json};
+    case "update-apply": return {command:"update-apply",yes:flags.has("--yes"),json};
+    case "app-create": return {command:"app-create",appName:values.appName,json,...mutationFlags(flags)};
+    case "app-get": return {command:"app-get",appKey:values.appKey,json};
+    case "app-rename": return {command:"app-rename",appKey:values.appKey,name:values.name,json,...mutationFlags(flags)};
+    case "app-enable": case "app-disable": return {command:definition.id,appKey:values.appKey,enabled:definition.id === "app-enable",json,...mutationFlags(flags)};
+    case "secret-rotate": case "secret-reveal": case "secret-revoke": return {command:definition.id,appKey:values.appKey,json,...mutationFlags(flags)};
+    case "app-list": {
+      const limit = flags.get("--limit");
+      if (limit !== undefined && (typeof limit !== "string" || !/^[1-9][0-9]{0,2}$/.test(limit) || Number(limit) > 100)) throw invalid("--limit must be an integer from 1 to 100");
+      const cursor = flags.get("--cursor");
+      if (cursor !== undefined && (typeof cursor !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(cursor))) throw invalid("Invalid --cursor");
+      if (cursor !== undefined && flags.has("--all")) throw invalid("--cursor and --all cannot be combined");
+      return {command:"app-list",json,all:flags.has("--all"),...(limit !== undefined ? {limit:Number(limit)} : {}),...(typeof cursor === "string" ? {cursor} : {})};
     }
-    return {command:action === "enable" ? "apps-enable" : "apps-disable",appKey,enabled:action === "enable",...mutationFlags(flags)};
+    case "agent-setup": return {command:"agent-setup",force:flags.has("--force"),json,...agentOption(flags)};
+    case "agent-status": return {command:"agent-status",json,...agentOption(flags)};
+    default: throw new Error("Implemented command has no parser result mapping");
   }
-  if (group === "agent" && action === "setup") {
-    const flags = parseFlags(argv.slice(2), ["--codex","--claude","--force"]);
-    if (flags.has("--codex") && flags.has("--claude")) throw invalid("Only one of --codex or --claude may be provided");
-    return {command:"agent-setup",force:flags.has("--force"),
-      ...(flags.has("--codex") ? {agent:/** @type {const} */ ("codex")} : flags.has("--claude") ? {agent:/** @type {const} */ ("claude")} : {})};
-  }
-  throw invalid(`Unknown command.\n\n${HELP}`);
 }
 
-/** @param {string[]} args @param {string[]} booleans @param {string[]} [values] */
-function parseFlags(args, booleans, values = []) {
+/** @param {string[]} args @param {import('./command-registry.mjs').FlagDefinition[]} options */
+function parseOptions(args,options) {
   /** @type {Map<string,string|true>} */
   const flags = new Map();
+  /** @type {string[]} */
+  const positionals = [];
+  let positionalOnly = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (!booleans.includes(arg) && !values.includes(arg)) throw invalid(`Unknown option: ${arg}`);
-    if (flags.has(arg)) throw invalid(`${arg} may only be provided once`);
-    if (booleans.includes(arg)) flags.set(arg, true);
-    else {
-      const value = args[++i];
-      if (!value || value.startsWith("--")) throw invalid(`${arg} requires a value`);
-      flags.set(arg,value);
+    if (positionalOnly) { positionals.push(arg); continue; }
+    if (arg === "--") { positionalOnly = true; continue; }
+    if (!arg.startsWith("-")) { positionals.push(arg); continue; }
+    const equals = arg.indexOf("=");
+    const name = equals === -1 ? arg : arg.slice(0,equals);
+    const option = options.find((item) => item.name === name);
+    if (!option) throw invalid(`Unknown option: ${name}`);
+    if (flags.has(name)) throw invalid(`${name} may only be provided once`);
+    if (option.kind === "boolean") {
+      if (equals !== -1) throw invalid(`${name} does not accept a value`);
+      flags.set(name,true);
+    } else {
+      const value = equals === -1 ? args[++i] : arg.slice(equals + 1);
+      if (!value || equals === -1 && value.startsWith("-")) throw invalid(`${name} requires a value`);
+      if (option.choices && !option.choices.includes(value)) throw invalid(`${name} must be one of: ${option.choices.join(", ")}`);
+      flags.set(name,value);
     }
   }
-  return flags;
+  return {flags,positionals};
 }
+
+/** @param {Map<string,string|true>} flags */
+function agentOption(flags) {
+  const selections = ["--codex","--claude"];
+  if (selections.filter((name) => flags.has(name)).length > 1) throw invalid(`Only one of ${selections.join(", ")} may be provided`);
+  return flags.has("--codex") ? {agent:/** @type {const} */ ("codex")} : flags.has("--claude") ? {agent:/** @type {const} */ ("claude")} : {};
+}
+
 /** @param {Map<string,string|true>} flags */
 function mutationFlags(flags) {
   const key = flags.get("--idempotency-key");
   if (key !== undefined && (typeof key !== "string" || !/^[A-Za-z0-9._~-]{1,128}$/.test(key))) throw invalid("Invalid --idempotency-key");
   return {yes:flags.has("--yes"),...(typeof key === "string" ? {idempotencyKey:key} : {})};
 }
-/** @param {string[]} argv @param {string} help */
-function requiredAppKey(argv, help) {
-  if (!argv[2] || argv[2].startsWith("--")) usage(help);
-  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(argv[2])) throw invalid("App Key must be 1-128 letters, numbers, '.', '_', '~' or '-'");
-  return argv[2];
+
+/** @param {string} value */
+export function validateAppKey(value) {
+  if (!/^[A-Za-z0-9._~-]{1,128}$/.test(value)) throw invalid("App Key must be 1-128 letters, numbers, '.', '_', '~' or '-'");
+  return value;
 }
+
 /** @param {string} value */
-function applicationName(value) {
+export function applicationName(value) {
   const name = value.trim();
   if (!name || [...name].length > 100 || /[\p{Cc}\p{Cs}]/u.test(name)) throw invalid("Application name must contain 1-100 characters without control characters");
   return name;
 }
-/** @param {string} command @returns {never} */
-function usage(command) { throw invalid(`Usage: requestshield ${command}`); }
+
 /** @param {string} message */
 function invalid(message) { return new CliError(message,{code:"INVALID_ARGUMENT",exitCode:2}); }
-export { HELP };