requestshield 0.0.0-stage → 1.0.0-stg.276

package/src/api-client.mjs

@@ -0,0 +1,155 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { validateBearerToken, validatedUrl } from "./config.mjs";
+
+const APPLICATIONS = "/v1/applications";
+const MAX_BODY_BYTES = 1024 * 1024;
+const API_ERRORS = new Set(["invalid_request", "invalid_token", "insufficient_scope", "application_not_found",
+  "idempotency_conflict", "secret_revoked", "email_not_verified", "identity_not_found", "dependency_unavailable", "rate_limited"]);
+
+export class ManagementApiClient {
+  /** @param {{baseUrl: string, fetchImpl?: typeof fetch, timeoutMs?: number}} options */
+  constructor({baseUrl, fetchImpl = fetch, timeoutMs = 15_000}) {
+    this.baseUrl = validatedUrl(baseUrl, "API_URL");
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  /** @param {string} token @param {{limit?: number, cursor?: string}} [options] */
+  listApps(token, options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    return this.#request(`${APPLICATIONS}${query.size ? `?${query}` : ""}`, token, "GET");
+  }
+
+  /** @param {string} token @param {string} appKey */
+  getApp(token, appKey) { return this.#request(appPath(appKey), token, "GET"); }
+
+  /** @param {string} token @param {string} appKey */
+  getBilling(token, appKey) { return this.#request(`${appPath(appKey)}/billing`, token, "GET"); }
+
+  /** @param {string} token @param {string} appKey @param {{from?: string, to?: string}} [options] */
+  getUsage(token, appKey, options = {}) {
+    const query = new URLSearchParams();
+    if (options.from !== undefined) query.set("from", options.from);
+    if (options.to !== undefined) query.set("to", options.to);
+    return this.#request(`${appPath(appKey)}/usage${query.size ? `?${query}` : ""}`, token, "GET");
+  }
+
+  /** @param {string} token @param {{name: string, idempotencyKey: string}} options */
+  createApp(token, {name, idempotencyKey}) {
+    return this.#request(APPLICATIONS, token, "POST", {name}, idempotencyKey);
+  }
+
+  /** @param {string} token @param {string} appKey @param {{name: string, idempotencyKey: string}} options */
+  renameApp(token, appKey, {name, idempotencyKey}) {
+    return this.#request(appPath(appKey), token, "PATCH", {name}, idempotencyKey);
+  }
+
+  /** @param {string} token @param {string} appKey @param {{enabled: boolean, idempotencyKey: string}} options */
+  setAppEnabled(token, appKey, {enabled, idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/${enabled ? "enable" : "disable"}`, token, "POST", undefined, idempotencyKey);
+  }
+
+  /** @param {string} token @param {string} appKey @param {{idempotencyKey: string}} options */
+  rotateSecret(token, appKey, {idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/secret/rotate`, token, "POST", undefined, idempotencyKey);
+  }
+
+  /** @param {string} token @param {string} appKey */
+  revealSecret(token, appKey) { return this.#request(`${appPath(appKey)}/secret/reveal`, token, "POST"); }
+
+  /** @param {string} token @param {string} appKey @param {{idempotencyKey: string}} options */
+  revokeSecret(token, appKey, {idempotencyKey}) {
+    return this.#request(`${appPath(appKey)}/secret/revoke`, token, "POST", undefined, idempotencyKey);
+  }
+
+  /** No retries: a lost mutation response may represent a committed operation.
+   * @param {string} path @param {string} token @param {string} method
+   * @param {{name: string}} [payload] @param {string} [idempotencyKey]
+   */
+  async #request(path, token, method, payload, idempotencyKey) {
+    const headers = {Accept: "application/json", Authorization: `Bearer ${validateBearerToken(token)}`};
+    if (idempotencyKey !== undefined) {
+      if (!/^[A-Za-z0-9._~-]{1,128}$/.test(idempotencyKey)) {
+        throw new CliError("Invalid idempotency key", {code: "INVALID_ARGUMENT", exitCode: 2});
+      }
+      Object.assign(headers, {"Idempotency-Key": idempotencyKey});
+    }
+    if (payload !== undefined) Object.assign(headers, {"Content-Type": "application/json"});
+    const controller = new AbortController();
+    /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+    let reader;
+    let expired = false;
+    const deadline = new Promise((_, reject) => {
+      controller.signal.addEventListener("abort", () => reject(new CliError(
+        "The RequestShield API request timed out. Check connectivity and try again.",
+        {code: "REQUEST_TIMEOUT", exitCode: 7},
+      )), {once: true});
+    });
+    const timer = setTimeout(() => { expired = true; controller.abort(); }, this.timeoutMs);
+    try {
+      const operation = (async () => {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+          method, headers, ...(payload !== undefined ? {body: JSON.stringify(payload)} : {}),
+          signal: controller.signal, redirect: "error", credentials: "omit", cache: "no-store",
+        });
+        if (expired) { void response.body?.cancel().catch(() => {}); throw new Error(); }
+        if (Number(response.headers.get("content-length")) > MAX_BODY_BYTES) {
+          void response.body?.cancel().catch(() => {}); throw invalidResponse();
+        }
+        const chunks = [];
+        let size = 0;
+        if (response.body) {
+          reader = response.body.getReader();
+          while (true) {
+            const {done, value} = await reader.read();
+            if (expired) throw new Error();
+            if (done) break;
+            size += value.length;
+            if (size > MAX_BODY_BYTES) throw invalidResponse();
+            chunks.push(value);
+          }
+        }
+        let body;
+        try { body = JSON.parse(new TextDecoder("utf-8", {fatal: true}).decode(Buffer.concat(chunks))); }
+        catch { if (response.ok) throw invalidResponse(); }
+        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 login` again"
+            : safeCode === "insufficient_scope" ? "; this session lacks the required permissions"
+            : safeCode === "email_not_verified" ? "; verify your email, then retry app creation"
+            : safeCode === "identity_not_found" ? "; run `requestshield login` again with a valid account" : "";
+          throw new CliError(`RequestShield API error: HTTP ${response.status}${safeCode ? ` (${safeCode})` : ""}${guidance}`, {
+            code: response.status === 401 ? "UNAUTHENTICATED" : "API_ERROR",
+            exitCode: response.status === 401 || response.status === 403 ? 3 : 1,
+            httpStatus: response.status, apiErrorCode: safeCode,
+          });
+        }
+        if (!body || typeof body !== "object" || Array.isArray(body)) throw invalidResponse();
+        return {ok: true, status: response.status, body, replayed: response.headers.get("Idempotency-Replayed") === "true"};
+      })();
+      return await Promise.race([operation, /** @type {Promise<never>} */ (deadline)]);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError("Could not reach the RequestShield API", {code: "NETWORK_ERROR", exitCode: 7});
+    } finally {
+      clearTimeout(timer);
+      if (reader) { void reader.cancel().catch(() => {}); }
+      controller.abort();
+    }
+  }
+}
+
+/** @param {string} appKey */
+function appPath(appKey) { return `${APPLICATIONS}/${encodeURIComponent(appKey)}`; }
+function invalidResponse() { return new CliError("The RequestShield API returned an invalid or oversized response", {code: "INVALID_RESPONSE"}); }
+
+/** @param {unknown} value @param {string} property */
+export function objectString(value, property) {
+  if (!value || typeof value !== "object") return undefined;
+  const found = Reflect.get(value, property);
+  return typeof found === "string" ? found : undefined;
+}

package/src/args.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+import { CliError } from "./errors.mjs";
+import { COMMAND_REGISTRY, commandUsage } from "./command-registry.mjs";
+import { validateUsageRange } from "./usage-time.mjs";
+import { validateOutputPath } from "./secret-output.mjs";
+
+/**
+ * @typedef {{command:"help",scope?:import('./command-registry.mjs').CommandDefinition|string} | {command:"version"}
+ * | {command:"update-check"|"logout"|"auth-status"|"contract"|"service-status",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,output?:string}
+ * | {command:"secret-rotate"|"secret-reveal",appKey:string,yes:boolean,json:boolean,idempotencyKey?:string,output?:string}
+ * | {command:"secret-revoke",appKey:string,yes:boolean,json:boolean,idempotencyKey?:string}
+ * | {command:"app-list",json:boolean,all:boolean,limit?:number,cursor?:string}
+ * | {command:"app-get"|"billing-get",appKey:string,json:boolean}
+ * | {command:"usage",appKey:string,json:boolean,from?:string,to?:string}
+ * | {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) return {command:"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",scope:group};
+    }
+    throw invalid("Unknown command. Use requestshield --help to list commands.");
+  }
+  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",scope:definition};
+  }
+  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)}`);
+  }
+  /** @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]);
+  }
+  const json = flags.has("--json");
+  switch (definition.id) {
+    case "help": return {command:"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": case "service-status": 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),...outputFlag(flags)};
+    case "app-get": case "billing-get": return {command:definition.id,appKey:values.appKey,json};
+    case "usage": return {command:"usage",appKey:values.appKey,json,...validateUsageRange({
+      from:/** @type {string | undefined} */ (flags.get("--from")),
+      to:/** @type {string | undefined} */ (flags.get("--to")),
+    })};
+    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": return {command:definition.id,appKey:values.appKey,json,...mutationFlags(flags),...outputFlag(flags)};
+    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} : {})};
+    }
+    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");
+  }
+}
+
+/** @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 (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,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 {Map<string,string|true>} flags */
+function outputFlag(flags) {
+  const output = flags.get("--output");
+  return typeof output === "string" ? {output: validateOutputPath(output)} : {};
+}
+
+/** @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 */
+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} message */
+function invalid(message) { return new CliError(message,{code:"INVALID_ARGUMENT",exitCode:2}); }

package/src/browser-opener.mjs

@@ -0,0 +1,32 @@
+// @ts-check
+import { spawn } from "node:child_process";
+import { CliError } from "./errors.mjs";
+
+/** Uses argument arrays and a fixed Windows script; never interpolate URL into shell code.
+ * @param {string} url
+ * @param {{signal?: AbortSignal, platform?: NodeJS.Platform, spawnImpl?: typeof spawn}} [options]
+ */
+export async function openBrowser(url, {signal, platform = process.platform, spawnImpl = spawn} = {}) {
+  const failure = () => new CliError("Could not open the browser automatically", {code: "BROWSER_OPEN_FAILED"});
+  const command = platform === "win32" ? "powershell.exe" : platform === "darwin" ? "open" : "xdg-open";
+  const args = platform === "win32"
+    ? ["-NoProfile", "-NonInteractive", "-Command", "Start-Process -FilePath $env:REQUESTSHIELD_SIGNIN_BROWSER_URL"]
+    : [url];
+  await new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(failure()); return; }
+    let child;
+    try {
+      child = spawnImpl(command, args, {
+        windowsHide: true, stdio: "ignore", shell: false,
+        env: platform === "win32" ? {...process.env, REQUESTSHIELD_SIGNIN_BROWSER_URL: url} : process.env,
+      });
+    } catch { reject(failure()); return; }
+    const abort = () => { cleanup(); child.kill(); reject(failure()); };
+    const timer = setTimeout(abort, 10_000);
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); };
+    child.once("error", () => { cleanup(); reject(failure()); });
+    child.once("exit", code => { cleanup(); code === 0 ? resolve(undefined) : reject(failure()); });
+    signal?.addEventListener("abort", abort, {once: true});
+    if (signal?.aborted) abort();
+  });
+}

package/src/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// @ts-check
+import { parseArgs } from "./args.mjs";
+import { getCommandDefinition, renderHelp } from "./command-registry.mjs";
+import { rendererFor, resolveTerminal } from "./terminal.mjs";
+import { ManagementApiClient } from "./api-client.mjs";
+import { SessionStore } from "./session-store.mjs";
+import { OAuthClient } from "./oauth-client.mjs";
+import { signin } from "./commands/signin.mjs";
+import { createKeys } from "./commands/keys-create.mjs";
+import { renameApp, setAppEnabled } from "./commands/application-mutations.mjs";
+import { rotateSecret, revealSecret, revokeSecret } from "./commands/secret-commands.mjs";
+import { showAuthStatus } from "./commands/auth-status.mjs";
+import { signout } from "./commands/signout.mjs";
+import { listApps } from "./commands/apps-list.mjs";
+import { getApp } from "./commands/apps-get.mjs";
+import { showUsage } from "./commands/usage.mjs";
+import { showBilling } from "./commands/billing.mjs";
+import { setupAgent } from "./commands/agent-setup.mjs";
+import { showAgentStatus } from "./commands/agent-status.mjs";
+import { checkForUpdate, applyUpdate } from "./commands/update-check.mjs";
+import { showContract } from "./commands/contract.mjs";
+import { showServiceStatus } from "./commands/service-status.mjs";
+import packageJson from "../package.json" with { type: "json" };
+import { getPackageProfile } from "./package-profile.mjs";
+import { getApiUrl, getAuthorizationIssuer, getCommandInvocation, getCommandName, getOAuthConfig } from "./config.mjs";
+
+/** @typedef {{
+ * log: (message: string) => void, warn?: (message: string) => void,
+ * terminal?: import('./terminal.mjs').TerminalContext,
+ * api?: ManagementApiClient, sessions?: SessionStore, oauth?: OAuthClient,
+ * authorizationIssuer?: string, openBrowser?: typeof import('./browser-opener.mjs').openBrowser,
+ * signal?: AbortSignal, env?: NodeJS.ProcessEnv, profile?: import('./config.mjs').Profile,
+ * homeDir?: string, sourceDir?: string, executablePath?: string,
+ * detectAgents?: () => Promise<Array<'codex' | 'claude'>>,
+ * selectAgent?: (detected: Array<'codex' | 'claude'>) => Promise<'codex' | 'claude'>,
+ * confirm?: () => Promise<boolean>, fetchImpl?: typeof fetch,
+ * secretOutput?: import('./secret-output.mjs').SecretOutputOptions,
+ * confirmUpdate?: () => Promise<boolean>, installLatest?: (packageName: string, version: string) => Promise<void>
+ * }} CommandContext */
+
+/** Runtime bindings only. Syntax, help and dependency policy live in the registry.
+ * @type {Record<string, (parsed: any, context: CommandContext) => unknown | Promise<unknown>>} */
+export const COMMAND_HANDLERS = {
+  help: (parsed, context) => context.log(renderHelp(parsed.scope, {
+    invocation: getCommandInvocation(context.profile), version: packageJson.version, renderer: rendererFor(context),
+  })),
+  version: (_parsed, context) => context.log(`${getCommandName(context.profile)} ${packageJson.version}`),
+  login: login,
+  logout: (parsed, context) => signout(parsed, {...context, sessions: localSessions(context)}),
+  "auth-status": (parsed, context) => showAuthStatus(parsed, {...context, sessions: localSessions(context)}),
+  contract: (parsed, context) => showContract(parsed, context),
+  "service-status": (parsed, context) => showServiceStatus(parsed, context),
+  "app-create": (parsed, context) => createKeys(parsed, requireApiSession(context)),
+  "app-list": (parsed, context) => listApps(parsed, requireApiSession(context)),
+  "app-get": (parsed, context) => getApp(parsed, requireApiSession(context)),
+  usage: (parsed, context) => showUsage(parsed, requireApiSession(context)),
+  "billing-get": (parsed, context) => showBilling(parsed, requireApiSession(context)),
+  "app-rename": (parsed, context) => renameApp(parsed, requireApiSession(context)),
+  "app-enable": (parsed, context) => setAppEnabled(parsed, requireApiSession(context)),
+  "app-disable": (parsed, context) => setAppEnabled(parsed, requireApiSession(context)),
+  "secret-rotate": (parsed, context) => rotateSecret(parsed, requireApiSession(context)),
+  "secret-reveal": (parsed, context) => revealSecret(parsed, requireApiSession(context)),
+  "secret-revoke": (parsed, context) => revokeSecret(parsed, requireApiSession(context)),
+  "agent-setup": (parsed, context) => setupAgent(parsed, context),
+  "agent-status": (parsed, context) => showAgentStatus(parsed, context),
+  "update-check": (parsed, context) => checkForUpdate(updateOptions(parsed, context)),
+  "update-apply": (parsed, context) => applyUpdate(updateOptions(parsed, context)),
+};
+
+/** @param {{json?: boolean, yes?: boolean}} parsed @param {CommandContext} context */
+function updateOptions(parsed, context) {
+  return {...parsed, profile: context.profile, currentVersion: packageJson.version, packageName: packageJson.name,
+    log: context.log, warn: context.warn, terminal: context.terminal, fetchImpl: context.fetchImpl, confirm: context.confirmUpdate, install: context.installLatest};
+}
+
+/** @param {{noOpen?: boolean, json?: boolean}} parsed @param {CommandContext} context */
+function login(parsed, context) {
+  const env = context.env ?? process.env;
+  const oauth = context.oauth ?? new OAuthClient({config: getOAuthConfig(context.profile), fetchImpl: context.fetchImpl});
+  const authorizationIssuer = context.authorizationIssuer ?? (context.oauth
+    ? oauth.config.issuer : getAuthorizationIssuer(context.profile, oauth.config.issuer));
+  const sessions = context.sessions ?? new SessionStore({env, homeDir: context.homeDir, oauth, config: oauth.config, profile: context.profile});
+  return signin(parsed, {...context, oauth, sessions, authorizationIssuer});
+}
+
+/** @param {CommandContext} context */
+function localSessions(context) {
+  return context.sessions ?? new SessionStore({env: context.env, homeDir: context.homeDir, profile: context.profile});
+}
+
+/** @param {CommandContext} context */
+function requireApiSession(context) {
+  if (!context.api || !context.sessions) throw new Error("Authenticated command context was not initialized");
+  return {...context, api: context.api, sessions: context.sessions};
+}
+
+/** @param {string[]} argv @param {Partial<CommandContext>} [deps] */
+export async function run(argv, deps = {}) {
+  // Parse and reject unknown commands before reading configuration or sessions.
+  const parsed = parseArgs(argv);
+  const profile = deps.profile ?? getPackageProfile();
+  getCommandName(profile);
+  const definition = getCommandDefinition(parsed.command);
+  const handler = definition?.handler ? COMMAND_HANDLERS[definition.handler] : undefined;
+  if (!handler) throw new Error("Unsupported command handler");
+  const context = {...deps, profile, terminal: resolveTerminal(deps), log: deps.log ?? console.log, warn: deps.warn ?? console.error};
+  if (definition?.requiresApiSession) {
+    return handler(parsed, {...context,
+      api: deps.api ?? new ManagementApiClient({baseUrl: getApiUrl(profile), fetchImpl: deps.fetchImpl}),
+      sessions: localSessions(context),
+    });
+  }
+  return handler(parsed, context);
+}

package/src/command-completion.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+/** A command that has already printed its result can set its process outcome. */
+export class CommandCompletion {
+  /** @param {0 | 1} exitCode */
+  constructor(exitCode) {
+    this.exitCode = exitCode;
+    Object.freeze(this);
+  }
+}

package/src/command-registry.mjs

@@ -0,0 +1,151 @@
+// @ts-check
+import { createRenderer, displayWidth } from "./terminal.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+/**
+ * @typedef {"help"|"version"|"login"|"logout"|"auth-status"|"app-create"|"app-list"|"app-get"|"app-rename"|"app-enable"|"app-disable"|"secret-rotate"|"secret-reveal"|"secret-revoke"|"agent-setup"|"agent-status"|"update-check"|"update-apply"|"contract"|"service-status"|"usage"|"billing-get"} CommandId
+ * @typedef {{name:string,field:string,required:boolean,kind:"app-name"|"app-key",description:string}} ArgumentDefinition
+ * @typedef {{name:string,kind:"boolean"|"value",description:string,value?:string,choices?:string[]}} FlagDefinition
+ * @typedef {"account"|"applications"|"developer"} HelpCategory
+ * @typedef {{id:CommandId,path:string[],handler:CommandId,requiresApiSession:boolean,availability:"implemented",arguments:ArgumentDefinition[],flags:FlagDefinition[],summary:string,examples:string[],notes?:string[],shortcuts?:string[],order:number,category?:HelpCategory,icon?:string,navigationSummary?:string}} CommandDefinition
+ * @typedef {{name:string,summary:string,category:HelpCategory,icon?:string,order:number}} GroupDefinition
+ * @typedef {{invocation?:string,version?:string,renderer?:ReturnType<typeof createRenderer>}} HelpOptions
+ */
+
+/** @type {{id:HelpCategory,label:string,order:number}[]} */
+export const HELP_CATEGORIES = [
+  {id:"account",label:"ACCOUNT",order:10},
+  {id:"applications",label:"APPLICATIONS & SECRETS",order:20},
+  {id:"developer",label:"DEVELOPER TOOLS",order:30},
+];
+
+/** Navigation metadata for the immediate command groups. @type {GroupDefinition[]} */
+export const COMMAND_GROUPS = [
+  {name:"auth",summary:"Inspect local authentication",category:"account",icon:"👤",order:30},
+  {name:"app",summary:"Manage applications",category:"applications",icon:"📦",order:10},
+  {name:"secret",summary:"Manage application secrets",category:"applications",icon:"🔐",order:20},
+  {name:"agent",summary:"Set up coding-agent Skills",category:"developer",icon:"🤖",order:20},
+  {name:"update",summary:"Check for and install CLI updates",category:"developer",icon:"📥",order:30},
+  {name:"service",summary:"Check service availability",category:"developer",order:40},
+  {name:"billing",summary:"View account usage and estimated cost",category:"account",order:40},
+];
+
+/** @type {FlagDefinition} */
+const json = {name:"--json",kind:"boolean",description:"Write one JSON result to stdout."};
+/** @type {FlagDefinition} */
+const yes = {name:"--yes",kind:"boolean",description:"Confirm this operation without prompting."};
+/** @type {FlagDefinition} */
+const idempotency = {name:"--idempotency-key",kind:"value",value:"key",description:"Reuse the same key when retrying the identical request within seven days."};
+/** @type {FlagDefinition} */
+const output = {name:"--output",kind:"value",value:"file",description:"Save App Key and API Secret in a new private ENV file instead of printing the secret."};
+/** @type {FlagDefinition} */
+const noOpen = {name:"--no-open",kind:"boolean",description:"Print the login URL without opening a browser."};
+/** @type {FlagDefinition[]} */
+const agents = [
+  {name:"--codex",kind:"boolean",description:"Use the Codex RequestShield Skill."},
+  {name:"--claude",kind:"boolean",description:"Use the Claude RequestShield Skill."},
+];
+/** @type {ArgumentDefinition} */
+const appKey = {name:"app-key",field:"appKey",required:true,kind:"app-key",description:"The exact App Key, not the application name."};
+/** @param {string} field @param {boolean} [required] @returns {ArgumentDefinition} */
+const appName = (field, required = true) => ({name:"name",field,required,kind:"app-name",description:"Application name (1–100 characters); quote names containing spaces."});
+const propagation = "Changes may take a moment. Check the application status before relying on the change.";
+
+/**
+ * The complete public surface. Parsing, help and dispatch share this registry.
+ * @type {CommandDefinition[]}
+ */
+export const COMMAND_REGISTRY = [
+  {id:"help",order:10,path:["--help"],shortcuts:["-h"],handler:"help",requiresApiSession:false,availability:"implemented",arguments:[],flags:[],summary:"Show help for the CLI, a group or a command.",examples:["--help","app create --help"]},
+  {id:"version",order:20,path:["--version"],shortcuts:["-v"],handler:"version",requiresApiSession:false,availability:"implemented",arguments:[],flags:[],summary:"Print the installed CLI version.",examples:["--version"]},
+  {id:"login",order:10,category:"account",icon:"🔑",navigationSummary:"Sign in to RequestShield",path:["login"],handler:"login",requiresApiSession:false,availability:"implemented",arguments:[],flags:[noOpen,json],summary:"Sign in through your browser.",examples:["login","login --no-open"]},
+  {id:"logout",order:20,category:"account",icon:"🚪",navigationSummary:"Remove your saved session",path:["logout"],handler:"logout",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Remove your saved local session.",examples:["logout"],notes:["Your browser stays signed in."]},
+  {id:"auth-status",order:10,path:["auth","status"],handler:"auth-status",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Inspect saved local session metadata.",examples:["auth status --json"],notes:["Does not renew the session or check online access."]},
+  {id:"app-create",order:10,path:["app","create"],handler:"app-create",requiresApiSession:true,availability:"implemented",arguments:[appName("appName")],flags:[idempotency,output,json],summary:"Create an app and its first secret.",examples:["app create \"Checkout API\"","app create \"Checkout API\" --output ./private/checkout.env --json"],notes:["Without --output, copy the printed secret into protected backend configuration.","--output never overwrites a file. Configure your backend to load the saved ENV file.","Receipt replay can return no secret; --output then fails with OUTPUT_SECRET_UNAVAILABLE. Reveal explicitly to save it.",propagation]},
+  {id:"app-list",order:20,path:["app","list"],handler:"app-list",requiresApiSession:true,availability:"implemented",arguments:[],flags:[{name:"--limit",kind:"value",value:"1-100",description:"Number of applications per page."},{name:"--cursor",kind:"value",value:"cursor",description:"Continue from an opaque page cursor."},{name:"--all",kind:"boolean",description:"Read every page, up to 100 pages."},json],summary:"List your apps.",examples:["app list","app list --all --json"],notes:["Defaults to one page. --cursor and --all are mutually exclusive.","App status is configuration state, not evidence of traffic or a working integration."]},
+  {id:"app-get",order:30,path:["app","get"],handler:"app-get",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[json],summary:"Show an app's information.",examples:["app get pk_example --json"]},
+  {id:"app-rename",order:40,path:["app","rename"],handler:"app-rename",requiresApiSession:true,availability:"implemented",arguments:[appKey,appName("name")],flags:[idempotency,json],summary:"Change an app's display name.",examples:["app rename pk_example \"New name\""]},
+  {id:"app-enable",order:50,path:["app","enable"],handler:"app-enable",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[idempotency,json],summary:"Enable an app.",examples:["app enable pk_example"],notes:[propagation]},
+  {id:"app-disable",order:60,path:["app","disable"],handler:"app-disable",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[idempotency,yes,json],summary:"Disable an app while retaining its secret.",examples:["app disable pk_example --yes"],notes:[propagation]},
+  {id:"secret-rotate",order:10,path:["secret","rotate"],handler:"secret-rotate",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[idempotency,yes,output,json],summary:"Replace the current secret, keeping the App Key and enabled state.",examples:["secret rotate pk_example --yes","secret rotate pk_example --output ./private/checkout-new.env --yes"],notes:["Without --output, copy the printed secret into protected backend configuration.","--output requires a new file. Load that file into the backend after rotation.","Receipt replay can return no secret; --output then fails with OUTPUT_SECRET_UNAVAILABLE. Reveal explicitly to save it.",propagation]},
+  {id:"secret-reveal",order:20,path:["secret","reveal"],handler:"secret-reveal",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[yes,output,json],summary:"Explicitly retrieve the current active secret.",examples:["secret reveal pk_example --yes","secret reveal pk_example --output ./private/checkout.env --yes"],notes:["This command retrieves sensitive backend credentials and records the retrieval in the audit log.","--output saves credentials in a new private ENV file and does not print the secret. Configure your backend to load it."]},
+  {id:"secret-revoke",order:30,path:["secret","revoke"],handler:"secret-revoke",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[idempotency,yes,json],summary:"Revoke the current secret.",examples:["secret revoke pk_example --yes"],notes:[propagation]},
+  {id:"agent-setup",order:10,path:["agent","setup"],handler:"agent-setup",requiresApiSession:false,availability:"implemented",arguments:[],flags:[...agents,{name:"--force",kind:"boolean",description:"Replace the selected existing Skill installation."},json],summary:"Install the RequestShield Skill for Codex or Claude.",examples:["agent setup --codex","agent setup --claude --force"],notes:["--codex and --claude are mutually exclusive."]},
+  {id:"agent-status",order:20,path:["agent","status"],handler:"agent-status",requiresApiSession:false,availability:"implemented",arguments:[],flags:[...agents,json],summary:"Check whether Agent Skill files are installed, missing or invalid.",examples:["agent status","agent status --codex --json"],notes:["Checks both agents by default. File presence does not prove an agent has loaded the Skill."]},
+  {id:"update-check",order:10,path:["update","check"],handler:"update-check",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Check for a newer CLI version without installing it.",examples:["update check"],notes:[]},
+  {id:"update-apply",order:20,path:["update","apply"],handler:"update-apply",requiresApiSession:false,availability:"implemented",arguments:[],flags:[yes,json],summary:"Check and install the available version into the global npm installation.",examples:["update apply","update apply --yes"],notes:["Requires confirmation unless --yes is supplied."]},
+  {id:"contract",order:10,category:"developer",icon:"📖",navigationSummary:"View integration settings and SDK versions",path:["contract"],handler:"contract",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Get the public integration contract and SDK versions.",examples:["contract","contract --json"],notes:["Reads public integration settings without signing in or accessing a saved session.","Returns published integration metadata; it does not install SDKs, modify project files or verify your application integration."]},
+  {id:"service-status",order:10,path:["service","status"],handler:"service-status",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Check Management API and Challenge Service availability.",examples:["service status","service status --json"],notes:["Checks both public /health endpoints without signing in or reading a saved session.","Each request has a five-second deadline. No retries or redirects are followed.","Test a protected request to verify your application integration.","Exits 0 when both checks pass, 1 when either check fails, or 2 for invalid configuration."]},
+  {id:"usage",order:30,category:"applications",navigationSummary:"Monitor recent application requests",path:["usage"],handler:"usage",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[{name:"--from",kind:"value",value:"UTC-time",description:"Start of the time range; provide together with --to."},{name:"--to",kind:"value",value:"UTC-time",description:"End of the time range; provide together with --from."},json],summary:"Monitor recent request totals for an app.",examples:["usage pk_example","usage pk_example --json"],notes:["Defaults to the last 24 hours. Requested times must fall within the last seven days and end in Z, with at most three fractional digits.","Counts are approximate monitoring data; data can be delayed or incomplete. They are not billing totals. Usage reports cover API v2 requests only. API v1 activity is not included.","Retries count separately. Successful verifies are successful attempts, not unique challenges. Requests without an identified app are excluded."]},
+  {id:"billing-get",order:10,path:["billing","get"],handler:"billing-get",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[json],summary:"Show account billing for an owned App Key.",examples:["billing get pk_example","billing get pk_example --json"],notes:["Uses your saved session. All applications in your account share the plan, billing period, allowance and totals shown here.","Counts authenticated API v2 token verification requests, including rejected requests and retries. API v1 and service errors are excluded.","Usage, remaining quota and overage are approximate. Data may be delayed or incomplete; the usage cutoff is not a guarantee of complete reporting.","Estimated cost includes the period's base charge and usage reported so far, before taxes. It is not a final invoice.","Missing current-period data is shown as Unavailable (null in JSON), never as zero."]},
+];
+
+/** @param {string} id */
+export function getCommandDefinition(id) { return COMMAND_REGISTRY.find((command) => command.id === id); }
+
+/** @param {CommandDefinition} command */
+export function commandUsage(command) {
+  return [command.path.join(" "),...command.arguments.map((argument) => argument.required ? `<${argument.name}>` : `[${argument.name}]`),
+    ...command.flags.map((flag) => `[${flag.name}${flag.value ? ` <${flag.value}>` : ""}]`)].join(" ");
+}
+
+/** Command syntax without flag details, for progressive-disclosure help.
+ * @param {CommandDefinition} command */
+function positionalUsage(command) {
+  return [command.path.join(" "),...command.arguments.map((argument) => argument.required ? `<${argument.name}>` : `[${argument.name}]`)].join(" ");
+}
+
+/** @param {CommandDefinition|string} [scope] @param {HelpOptions} [options] */
+export function renderHelp(scope, options = {}) {
+  const {invocation = "requestshield", version = packageJson.version, renderer = createRenderer()} = options;
+  const title = `RequestShield ${version}${scope ? ` — ${typeof scope === "string" ? scope : scope.path.join(" ")}` : ""}`;
+  const sections = [renderer.heading(title,"🛡")];
+  /** @param {string} title @param {string} contents */
+  const section = (title, contents) => `${renderer.section(title)}\n${contents}`;
+  const helpOption = {label:"-h, --help",description:"Show help"};
+  if (typeof scope === "object") {
+    sections.push(renderer.paragraph(scope.summary));
+    sections.push(section("USAGE",`  ${renderer.command(`${invocation} ${positionalUsage(scope)} [options]`)}`));
+    if (scope.arguments.length) {
+      sections.push(section("ARGUMENTS",renderer.rows(scope.arguments.map((argument) => ({
+        label:argument.required ? `<${argument.name}>` : `[${argument.name}]`,description:argument.description,
+      })))));
+    }
+    sections.push(section("OPTIONS",renderer.rows([
+      ...scope.flags.map((flag) => ({label:`${flag.name}${flag.value ? ` <${flag.value}>` : ""}`,description:flag.description})),
+      {...helpOption,description:"Show help for this command"},
+    ])));
+    sections.push(section("EXAMPLES",scope.examples.map((example) => `  ${renderer.command(`${invocation} ${example}`)}`).join("\n")));
+    const notes = scope.notes ?? [];
+    if (notes.length) sections.push(section("NOTES",notes.map((note) => renderer.paragraph(note)).join("\n\n")));
+    return sections.join("\n\n");
+  }
+  if (scope) {
+    const group = COMMAND_GROUPS.find((candidate) => candidate.name === scope);
+    if (!group) throw new Error(`Unknown help group: ${scope}`);
+    sections.push(renderer.paragraph(group.summary));
+    sections.push(section("USAGE",`  ${renderer.command(`${invocation} ${scope} <command> [options]`)}`));
+    const commands = COMMAND_REGISTRY.filter((command) => command.path[0] === scope).sort((a,b) => a.order - b.order);
+    sections.push(section("COMMANDS",renderer.rows(commands.map((command) => ({
+      label:`${invocation} ${positionalUsage(command)}`,description:command.summary,icon:command.icon,
+    })))));
+    sections.push(section("OPTIONS",renderer.rows([{...helpOption,description:"Show help for this group"}])));
+    sections.push(renderer.muted(renderer.paragraph(`Use ${invocation} ${scope} <command> --help for details.`)));
+    return sections.join("\n\n");
+  }
+  sections.push(section("USAGE",`  ${renderer.command(`${invocation} <command> [options]`)}`));
+  const navigation = [
+    ...COMMAND_GROUPS.map((group) => ({label:`${invocation} ${group.name}`,description:group.summary,category:group.category,icon:group.icon,order:group.order})),
+    ...COMMAND_REGISTRY.filter((command) => command.category).map((command) => ({
+      label:`${invocation} ${command.path.join(" ")}`,description:command.navigationSummary ?? command.summary,category:command.category,icon:command.icon,order:command.order,
+    })),
+  ];
+  const labelWidth = Math.max(...navigation.map(entry => displayWidth(entry.label)));
+  for (const category of [...HELP_CATEGORIES].sort((a,b) => a.order - b.order)) {
+    const members = navigation.filter((entry) => entry.category === category.id).sort((a,b) => a.order - b.order);
+    if (members.length) sections.push(section(category.label,renderer.rows(members,{labelWidth})));
+  }
+  sections.push(section("OPTIONS",renderer.rows([helpOption,{label:"-v, --version",description:"Show version"}])));
+  sections.push(renderer.muted(renderer.paragraph(`Use ${invocation} <command> --help for details.\nAdd --json to result commands for machine-readable output.`)));
+  return sections.join("\n\n");
+}