requestshield 0.1.6 → 0.1.8

package/src/cli.mjs

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 // @ts-check
-
 import { parseArgs } from "./args.mjs";
+import { getCommandDefinition } from "./command-registry.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";
@@ -15,263 +14,90 @@ import { signout } from "./commands/signout.mjs";
 import { listApps } from "./commands/apps-list.mjs";
 import { getApp } from "./commands/apps-get.mjs";
 import { setupAgent } from "./commands/agent-setup.mjs";
-import { checkForUpdate } from "./commands/update-check.mjs";
-
+import { showAgentStatus } from "./commands/agent-status.mjs";
+import { checkForUpdate, applyUpdate } from "./commands/update-check.mjs";
+import { showContract } from "./commands/contract.mjs";
 import packageJson from "../package.json" with { type: "json" };
 import { getApiUrl, getAuthorizationIssuer, getCommandInvocation, getCommandName, getOAuthConfig } from "./config.mjs";
 
-/**
- * @typedef {{
- *   log: (message: string) => void,
- *   warn?: (message: string) => void,
- *   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">,
- *   wait?: (milliseconds: number) => Promise<unknown>,
- *   confirm?: () => Promise<boolean>,
- *   fetchImpl?: typeof fetch,
- *   confirmUpdate?: () => Promise<boolean>,
- *   installLatest?: (
- *     packageName: string,
- *     version: string
- *   ) => Promise<void>
- * }} CommandContext
- */
-
-/**
- * @typedef {CommandContext & {
- *   api: ManagementApiClient,
- *   sessions: SessionStore
- * }} AuthenticatedCommandContext
- */
-
-/**
- * @typedef {{
- *   requiresApiSession: boolean,
- *   handler: (
- *     parsed: any,
- *     context: CommandContext
- *   ) => unknown | Promise<unknown>
- * }} CommandHandler
- */
-
-/**
- * Put every CLI command handler here.
- *
- * @type {Record<string, CommandHandler>}
- */
-const COMMAND_HANDLERS = {
-  "help": {
-    requiresApiSession: false,
-    handler: (parsed, context) =>
-      context.log(parsed.help.replace(/^  requestshield /gm, `  ${getCommandInvocation(context.profile)} `)),
-  },
-
-  "version": {
-    requiresApiSession: false,
-    handler: (_parsed, context) =>
-      context.log(`${getCommandName(context.profile)} ${packageJson.version}`),
-  },
-
-  "update-check": {
-    requiresApiSession: false,
-    handler: (_parsed, context) =>
-      checkForUpdate({
-        profile: context.profile,
-        currentVersion: packageJson.version,
-        packageName: packageJson.name,
-        log: context.log,
-        fetchImpl: context.fetchImpl,
-        confirm: context.confirmUpdate,
-        install: context.installLatest,
-      }),
-  },
-
-  "agent-setup": {
-    requiresApiSession: false,
-    handler: (parsed, context) =>
-      setupAgent(parsed, context),
-  },
-
-  "signin": {
-    requiresApiSession: false,
-    handler: (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});
-    },
-  },
-
-  "keys-create": {
-    requiresApiSession: true,
-    handler: (parsed, context) =>
-      createKeys(parsed, requireApiSession(context)),
-  },
-
-  "keys-rotate": {requiresApiSession: true, handler: (parsed, context) => rotateSecret(parsed, requireApiSession(context))},
-  "keys-reveal": {requiresApiSession: true, handler: (parsed, context) => revealSecret(parsed, requireApiSession(context))},
-  "keys-revoke": {requiresApiSession: true, handler: (parsed, context) => revokeSecret(parsed, requireApiSession(context))},
-  "apps-rename": {requiresApiSession: true, handler: (parsed, context) => renameApp(parsed, requireApiSession(context))},
-  "apps-enable": {requiresApiSession: true, handler: (parsed, context) => setAppEnabled(parsed, requireApiSession(context))},
-  "apps-disable": {requiresApiSession: true, handler: (parsed, context) => setAppEnabled(parsed, requireApiSession(context))},
-  "auth-status": {requiresApiSession: false, handler: (parsed, context) => showAuthStatus(parsed, {...context, sessions: localSessions(context)})},
-  "signout": {requiresApiSession: false, handler: (parsed, context) => signout(parsed, {...context, sessions: localSessions(context)})},
-
-  "apps-list": {
-    requiresApiSession: true,
-    handler: (parsed, context) =>
-      listApps(parsed, requireApiSession(context)),
-  },
+/** @typedef {{
+ * log: (message: string) => void, warn?: (message: string) => void,
+ * 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,
+ * 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(parsed.help.replace(/^  requestshield /gm, `  ${getCommandInvocation(context.profile)} `)),
+  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),
+  "app-create": (parsed, context) => createKeys(parsed, requireApiSession(context)),
+  "app-list": (parsed, context) => listApps(parsed, requireApiSession(context)),
+  "app-get": (parsed, context) => getApp(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)),
+};
 
-  "apps-get": {
-    requiresApiSession: true,
-    handler: (parsed, context) =>
-      getApp(parsed, requireApiSession(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, 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});
 }
 
-/**
- * Narrow the shared context before an authenticated handler can use it.
- *
- * @param {CommandContext} context
- * @returns {AuthenticatedCommandContext}
- */
+/** @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,
-  };
+  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 {{
- *   log?: (message: string) => void,
- *   warn?: (message: string) => void,
- *   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">,
- *   wait?: (milliseconds: number) => Promise<unknown>,
- *   confirm?: () => Promise<boolean>,
- *   fetchImpl?: typeof fetch,
- *   confirmUpdate?: () => Promise<boolean>,
- *   installLatest?: (
- *     packageName: string,
- *     version: string
- *   ) => Promise<void>
- * }} [deps]
- */
+/** @param {string[]} argv @param {Partial<CommandContext>} [deps] */
 export async function run(argv, deps = {}) {
+  // Parse and reject unavailable commands before reading configuration or sessions.
+  const parsed = parseArgs(argv);
   const profile = deps.profile ?? "prod";
   getCommandName(profile);
-  const parsed = parseArgs(argv);
-
-  const log =
-    deps.log ??
-    ((message) => console.log(message));
-
-  /*
-   * Find the requested command.
-   */
-  const command = COMMAND_HANDLERS[parsed.command];
-
-  if (!command) {
-    throw new Error(
-      `Unsupported command: ${String(parsed.command)}`
-    );
+  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, 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),
+    });
   }
-
-  /*
-  * Dependencies available to every command.
-  */
-  /** @type {CommandContext} */
-  const context = {
-    ...deps,
-    profile,
-    log,
-    warn: deps.warn ?? ((message) => console.error(message)),
-  };
-
-  /*
-   * Only initialize the Management API and session
-   * for commands that require them.
-   */
-  if (command.requiresApiSession) {
-    const env =
-      deps.env ??
-      process.env;
-
-    const api =
-      deps.api ??
-      new ManagementApiClient({
-        baseUrl: getApiUrl(profile),
-        fetchImpl: deps.fetchImpl,
-      });
-
-    const sessions =
-      deps.sessions ??
-      new SessionStore({
-        env,
-        homeDir: deps.homeDir,
-        profile,
-      });
-
-    const authenticatedContext = {
-      ...context,
-      env,
-      api,
-      sessions,
-    };
-
-    return command.handler(
-      parsed,
-      authenticatedContext
-    );
-  }
-
-  /*
-   * Execute commands that do not need an API session.
-   */
-  return command.handler(
-    parsed,
-    context
-  );
+  return handler(parsed, context);
 }

package/src/command-registry.mjs

@@ -0,0 +1,97 @@
+// @ts-check
+
+/**
+ * @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"|"secret-status"|"usage-challenges"|"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 {{id:CommandId,path:string[],handler:CommandId|null,requiresApiSession:boolean,availability:"implemented"|"placeholder",arguments:ArgumentDefinition[],flags:FlagDefinition[],summary:string,examples:string[],notes?:string[],shortcuts?:string[]}} CommandDefinition
+ */
+
+/** @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 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 = "Accepted changes propagate asynchronously. Acceptance does not mean the change is globally active.";
+
+/**
+ * The complete public surface. Parsing, help and dispatch share this registry.
+ * @type {CommandDefinition[]}
+ */
+export const COMMAND_REGISTRY = [
+  {id:"help",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",path:["--version"],shortcuts:["-v"],handler:"version",requiresApiSession:false,availability:"implemented",arguments:[],flags:[],summary:"Print the installed CLI version.",examples:["--version"]},
+  {id:"login",path:["login"],handler:"login",requiresApiSession:false,availability:"implemented",arguments:[],flags:[noOpen,json],summary:"Sign in through the browser using OAuth.",examples:["login","login --no-open"]},
+  {id:"logout",path:["logout"],handler:"logout",requiresApiSession:false,availability:"implemented",arguments:[],flags:[json],summary:"Remove the saved session for this profile.",examples:["logout"],notes:["Does not end your browser session or revoke the provider grant."]},
+  {id:"auth-status",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 refresh the session or verify that the provider accepts it."]},
+  {id:"app-create",path:["app","create"],handler:"app-create",requiresApiSession:true,availability:"implemented",arguments:[appName("appName")],flags:[idempotency,json],summary:"Create an app and its first secret.",examples:["app create \"Checkout API\""],notes:["Copy the returned secret into protected backend configuration; the CLI does not save it.","Receipt replay can return apiSecret: null and never automatically reveals a secret.",propagation]},
+  {id:"app-list",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",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",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",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",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",path:["secret","rotate"],handler:"secret-rotate",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[idempotency,yes,json],summary:"Replace the current secret, keeping the App Key and enabled state.",examples:["secret rotate pk_example --yes"],notes:["Copy the returned secret into protected backend configuration. A receipt replay can return apiSecret: null.",propagation]},
+  {id:"secret-reveal",path:["secret","reveal"],handler:"secret-reveal",requiresApiSession:true,availability:"implemented",arguments:[appKey],flags:[yes,json],summary:"Explicitly retrieve the current active secret.",examples:["secret reveal pk_example --yes"],notes:["This command discloses sensitive backend credentials and records the retrieval in the audit log."]},
+  {id:"secret-revoke",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",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",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",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:["QAT/STG runners return local source-update guidance without querying npm."]},
+  {id:"update-apply",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. QAT/STG runners only provide source-update guidance."]},
+  {id:"contract",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 the selected profile's public documentation 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",path:["service","status"],handler:null,requiresApiSession:false,availability:"placeholder",arguments:[],flags:[json],summary:"Check service availability.",examples:["service status"]},
+  {id:"secret-status",path:["secret","status"],handler:null,requiresApiSession:false,availability:"placeholder",arguments:[appKey],flags:[json],summary:"Get secret status metadata without revealing the secret.",examples:["secret status pk_example"]},
+  {id:"usage-challenges",path:["usage","challenges"],handler:null,requiresApiSession:false,availability:"placeholder",arguments:[appKey],flags:[{name:"--from",kind:"value",value:"time",description:"Start of the requested time range."},{name:"--to",kind:"value",value:"time",description:"End of the requested time range."},{name:"--granularity",kind:"value",value:"hour|day",choices:["hour","day"],description:"Requested aggregation period."},json],summary:"Get challenge usage for an app.",examples:["usage challenges pk_example --granularity day"]},
+  {id:"billing-get",path:["billing","get"],handler:null,requiresApiSession:false,availability:"placeholder",arguments:[appKey],flags:[json],summary:"Get an app's plan and billing information.",examples:["billing get pk_example"]},
+];
+
+/** @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(" ");
+}
+
+/** @param {CommandDefinition|string} [scope] */
+export function renderHelp(scope) {
+  if (typeof scope === "object") {
+    const unavailable = scope.availability === "placeholder";
+    return [
+      `RequestShield CLI — ${scope.path.join(" ")}${unavailable ? " [coming soon]" : ""}`,
+      "",scope.summary,"","Usage:",`  requestshield ${commandUsage(scope)}`,
+      ...(scope.arguments.length ? ["","Arguments:",...scope.arguments.map((arg) => `  ${arg.required ? `<${arg.name}>` : `[${arg.name}]`}  ${arg.description}`)] : []),
+      "","Options:",...scope.flags.map((flag) => `  ${flag.name}${flag.value ? ` <${flag.value}>` : ""}  ${flag.description}`),
+      "  --help, -h  Show help for this command.",
+      "","Examples:",...scope.examples.map((example) => `  requestshield ${example}`),
+      ...(scope.notes?.length ? ["",...scope.notes] : []),
+      ...(unavailable ? ["","This command is not available yet. It returns COMMAND_UNAVAILABLE (exit code 2) without configuration, authentication or network access."] : []),
+    ].join("\n");
+  }
+  const commands = scope ? COMMAND_REGISTRY.filter((command) => command.path[0] === scope) : COMMAND_REGISTRY;
+  const groups = scope ? [scope] : ["General",...new Set(commands.filter((command) => command.path.length > 1).map((command) => command.path[0]))];
+  const lines = [`RequestShield CLI${scope ? ` — ${scope}` : ""}`,"","Usage:",`  requestshield ${scope ? `${scope} <command>` : "<command>"} [options]`];
+  for (const group of groups) {
+    const members = commands.filter((command) => group === "General" ? command.path.length === 1 : command.path[0] === group);
+    if (!members.length) continue;
+    lines.push("",`${group === "General" ? group : `${group[0].toUpperCase()}${group.slice(1)}`} commands:`);
+    for (const command of members) {
+      const syntax = commandUsage(command);
+      lines.push(`  requestshield ${syntax}${command.shortcuts?.length ? ` (${command.shortcuts.join(", ")})` : ""}${command.availability === "placeholder" ? " [coming soon]" : ""}`,`    ${command.summary}`);
+    }
+  }
+  lines.push("","Use --help after a group or command for detailed usage and examples.","Commands marked [coming soon] return COMMAND_UNAVAILABLE and perform no work.");
+  return lines.join("\n");
+}

package/src/commands/agent-setup.mjs

@@ -1,27 +1,22 @@
 // @ts-check
 
 import { cp, lstat, mkdir, readFile, realpath, rename, rm } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { CliError } from "../errors.mjs";
 import { detectAgents } from "../agent-detector.mjs";
+import { agentSkillPath } from "./agent-status.mjs";
 
 /**
- * @param {{ agent?: "codex" | "claude", force: boolean }} options
+ * @param {{ agent?: "codex" | "claude", force: boolean, json?: boolean }} options
  * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
  */
 export async function setupAgent(options, deps) {
-  const agent = await resolveAgent(options.agent, deps);
-  const homeDir = deps.homeDir ?? os.homedir();
-
-  // Codex and Claude discover personal skills from different directories.
-  const skillsRoot = agent === "codex"
-    ? path.join(homeDir, ".agents", "skills")
-    : path.join(homeDir, ".claude", "skills");
-  const destination = path.join(skillsRoot, "requestshield");
+  const agent = await resolveAgent(options.agent, deps, !options.json);
+  const destination = agentSkillPath(agent, deps);
+  const skillsRoot = path.dirname(destination);
   await mkdir(skillsRoot, { recursive: true });
 
   const exists = await pathExists(destination);
@@ -56,8 +51,13 @@ export async function setupAgent(options, deps) {
     throw error;
   }
   const agentLabel = agent === "codex" ? "Codex" : "Claude";
-  deps.log(`Installed RequestShield skill for ${agentLabel} at ${destination}`);
-  deps.log(`Restart ${agentLabel} or start a new task before using the skill.`);
+  const result = { agent, path: destination, status: /** @type {const} */ ("installed") };
+  if (options.json) deps.log(JSON.stringify({ data: result }, null, 2));
+  else {
+    deps.log(`Installed RequestShield skill for ${agentLabel} at ${destination}`);
+    deps.log(`Restart ${agentLabel} or start a new task before using the skill.`);
+  }
+  return result;
 }
 
 /** @param {string} [executablePath] */
@@ -93,9 +93,10 @@ async function resolveSkillSource(executablePath) {
  *
  * @param {"codex" | "claude" | undefined} requested
  * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
+ * @param {boolean} allowPrompt
  * @returns {Promise<"codex" | "claude">}
  */
-async function resolveAgent(requested, deps) {
+async function resolveAgent(requested, deps, allowPrompt) {
   // A command-line choice is authoritative and avoids probing the machine.
   if (requested) return requested;
 
@@ -119,6 +120,12 @@ async function resolveAgent(requested, deps) {
 
   // Never choose silently when both agents are present. Interactive users get
   // a prompt; non-interactive callers receive a stable conflict error.
+  if (!allowPrompt) {
+    throw new CliError("Multiple coding agents detected. Choose --codex or --claude explicitly when using --json.", {
+      code: "INSTALL_CONFLICT",
+      exitCode: 2,
+    });
+  }
   const selectAgent = deps.selectAgent ?? promptForAgent;
   const selected = await selectAgent(detected);
   if (!detected.includes(selected)) {
@@ -136,7 +143,7 @@ async function resolveAgent(requested, deps) {
  * @returns {Promise<"codex" | "claude">}
  */
 async function promptForAgent() {
-  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+  if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
     throw new CliError(
       [
         "Multiple coding agents detected.",
@@ -151,10 +158,10 @@ async function promptForAgent() {
 
   const prompt = createInterface({
     input: process.stdin,
-    output: process.stdout,
+    output: process.stderr,
   });
   try {
-    process.stdout.write(
+    process.stderr.write(
       "Multiple coding agents detected.\n\n  1. Codex\n  2. Claude\n\n",
     );
     while (true) {
@@ -163,7 +170,7 @@ async function promptForAgent() {
         .toLowerCase();
       if (answer === "1" || answer === "codex") return "codex";
       if (answer === "2" || answer === "claude") return "claude";
-      process.stdout.write("Enter 1 for Codex or 2 for Claude.\n");
+      process.stderr.write("Enter 1 for Codex or 2 for Claude.\n");
     }
   } finally {
     prompt.close();

package/src/commands/agent-status.mjs

@@ -0,0 +1,60 @@
+// @ts-check
+
+import { lstat, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/** @typedef {"codex" | "claude"} Agent */
+/** @typedef {{ agent: Agent, path: string, status: "installed" | "missing" | "invalid" }} AgentInstallation */
+
+/** @param {Agent} agent @param {{ homeDir?: string }} [deps] */
+export function agentSkillPath(agent, deps = {}) {
+  return path.join(deps.homeDir ?? os.homedir(), agent === "codex" ? ".agents" : ".claude", "skills", "requestshield");
+}
+
+/**
+ * Inspect the personal Skill installation only; this does not prove an agent
+ * has loaded the Skill, and never probes executables or creates directories.
+ * @param {Agent} agent
+ * @param {{ homeDir?: string }} [deps]
+ * @returns {Promise<AgentInstallation>}
+ */
+export async function inspectAgent(agent, deps = {}) {
+  const destination = agentSkillPath(agent, deps);
+  try {
+    await lstat(destination);
+  } catch (error) {
+    return { agent, path: destination, status: /** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT" ? "missing" : "invalid" };
+  }
+
+  try {
+    // stat follows an intentional directory symlink; broken links are invalid.
+    if (!(await stat(destination)).isDirectory()) return { agent, path: destination, status: "invalid" };
+    const contents = await readFile(path.join(destination, "SKILL.md"), "utf8");
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(contents);
+    const valid = frontmatter !== null
+      && /^name:\s*(?:requestshield|"requestshield"|'requestshield')\s*$/m.test(frontmatter[1])
+      && frontmatter[2].trim().length > 0;
+    return { agent, path: destination, status: valid ? "installed" : "invalid" };
+  } catch {
+    return { agent, path: destination, status: "invalid" };
+  }
+}
+
+/**
+ * @param {{ agent?: Agent, json?: boolean }} options
+ * @param {{ homeDir?: string, log: (message: string) => void }} deps
+ */
+export async function showAgentStatus(options, deps) {
+  const agents = options.agent ? [options.agent] : /** @type {Agent[]} */ (["codex", "claude"]);
+  const result = await Promise.all(agents.map((agent) => inspectAgent(agent, deps)));
+  if (options.json) {
+    deps.log(JSON.stringify({ data: result }, null, 2));
+  } else {
+    for (const installation of result) {
+      deps.log(`${installation.agent === "codex" ? "Codex" : "Claude"}: ${installation.status} (${installation.path})`);
+    }
+    deps.log("This checks installed Skill files, not whether an agent has loaded them.");
+  }
+  return result;
+}