requestshield 0.1.7 → 0.1.9

package/src/commands/application-mutations.mjs

@@ -1,14 +1,16 @@
 // @ts-check
 import { parseApplicationResponse } from "./application-response.mjs";
+import { outputContext, printApplication } from "./output.mjs";
 import { confirmAction, mutationKey, parseAccepted, printAccepted, validateHttpStatus, withMutationRecovery } from "./mutation-support.mjs";
 
 /** @typedef {import('./mutation-support.mjs').MutationResponse} MutationResponse */
 /** @typedef {import('./mutation-support.mjs').CommandOutput & {sessions: {loadToken(): Promise<string>}}} Dependencies */
 
-/** @param {{appKey: string, name: string, yes?: boolean, idempotencyKey?: string}} options
+/** @param {{appKey: string, name: string, json?: boolean, yes?: boolean, idempotencyKey?: string}} options
  * @param {Dependencies & {api: {renameApp(token: string, appKey: string, options: {name: string, idempotencyKey: string}): Promise<MutationResponse>}}} deps
  */
 export async function renameApp(options, deps) {
+  deps = outputContext(options, deps);
   const idempotencyKey = mutationKey(options.idempotencyKey);
   const token = await deps.sessions.loadToken();
   const application = await withMutationRecovery(idempotencyKey, deps, async () => {
@@ -16,18 +18,20 @@ export async function renameApp(options, deps) {
     validateHttpStatus(result, 200);
     return parseApplicationResponse(result.body, options.appKey);
   });
-  deps.log(JSON.stringify({data: application}, null, 2));
+  printApplication(application, options, deps);
+  return application;
 }
 
-/** @param {{appKey: string, enabled: boolean, yes?: boolean, idempotencyKey?: string}} options
+/** @param {{appKey: string, enabled: boolean, json?: boolean, yes?: boolean, idempotencyKey?: string}} options
  * @param {Dependencies & {api: {setAppEnabled(token: string, appKey: string, options: {enabled: boolean, idempotencyKey: string}): Promise<MutationResponse>}}} deps
  */
 export async function setAppEnabled(options, deps) {
+  deps = outputContext(options, deps);
   if (!options.enabled) await confirmAction(options, deps, `Disable application ${options.appKey}?`, "DISABLE");
   const idempotencyKey = mutationKey(options.idempotencyKey);
   const token = await deps.sessions.loadToken();
   await withMutationRecovery(idempotencyKey, deps, async () => {
     parseAccepted(await deps.api.setAppEnabled(token, options.appKey, {enabled: options.enabled, idempotencyKey}));
   });
-  printAccepted(options.enabled ? "Application enable" : "Application disable", options.appKey, deps);
+  return printAccepted(options.enabled ? "Application enable" : "Application disable", options.appKey, deps, options);
 }

package/src/commands/apps-get.mjs

@@ -1,20 +1,28 @@
 // @ts-check
 
 import { parseApplicationResponse } from "./application-response.mjs";
+import { printApplication } from "./output.mjs";
 
 /**
- * @param {{ appKey: string }} options
+ * @param {{ appKey: string, json?: boolean }} options
  * @param {{ api: { getApp(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
  */
 export async function getApp(options, deps) {
+  const app = await fetchApp(options.appKey, deps);
+  printApplication(app, options, deps);
+  return app;
+}
+
+/** @param {string} appKey @param {Pick<Parameters<typeof getApp>[1], 'api' | 'sessions'>} deps */
+export async function fetchApp(appKey, deps) {
   const accessToken =
     await deps.sessions.loadToken();
   
   const result =
-    await deps.api.getApp(accessToken, options.appKey);
+    await deps.api.getApp(accessToken, appKey);
   
   const app =
-    parseApplicationResponse(result.body, options.appKey);
+    parseApplicationResponse(result.body, appKey);
   
-  deps.log(JSON.stringify({ data: app }, null, 2));
+  return app;
 }

package/src/commands/apps-list.mjs

@@ -14,6 +14,25 @@ const MAX_PAGES = 100;
  * @param {{api: {listApps(accessToken: string, options: {limit?: number, cursor?: string}): Promise<{body: unknown}>}, sessions: {loadToken(): Promise<string>}, log: (message: string) => void, profile?: import('../config.mjs').Profile}} deps
  */
 export async function listApps(options, deps) {
+  const result = await collectApps(options, deps);
+  const {data: apps, nextCursor} = result;
+  if (options.json) deps.log(JSON.stringify(result, null, 2));
+  else {
+    if (apps.length === 0) {
+      deps.log(nextCursor === null && !options.cursor
+        ? "No applications are available to this account."
+        : "No applications were returned on this page.");
+    } else {
+      for (const line of formatTable(apps)) deps.log(line);
+    }
+    if (nextCursor !== null) deps.log(`More applications are available. Continue with \`${getCommandInvocation(deps.profile)} app list --cursor ${nextCursor}\` or use --all.`);
+  }
+  return result;
+}
+
+/** @param {{limit?: number, cursor?: string, all?: boolean}} options
+ * @param {Pick<Parameters<typeof listApps>[1], 'api' | 'sessions'>} deps */
+export async function collectApps(options, deps) {
   /** @type {App[]} */
   const apps = [];
   let cursor = options.cursor;
@@ -41,19 +60,7 @@ export async function listApps(options, deps) {
     }
   }
 
-  if (options.json) {
-    deps.log(JSON.stringify({ data: apps, nextCursor }, null, 2));
-    return;
-  }
-
-  if (apps.length === 0) {
-    deps.log(nextCursor === null && !options.cursor
-      ? "No applications are available to this account."
-      : "No applications were returned on this page.");
-  } else {
-    for (const line of formatTable(apps)) deps.log(line);
-  }
-  if (nextCursor !== null) deps.log(`More applications are available. Continue with \`${getCommandInvocation(deps.profile)} apps list --cursor ${nextCursor}\` or use --all.`);
+  return {data: apps, nextCursor};
 }
 
 /** @param {unknown} body @returns {{ data: App[], nextCursor: string | null }} */

package/src/commands/contract.mjs

@@ -0,0 +1,25 @@
+// @ts-check
+import { getDocsUrl } from "../config.mjs";
+import { IntegrationContractClient } from "../integration-contract-client.mjs";
+
+/**
+ * @param {{json?: boolean}} options
+ * @param {{profile?: import('../config.mjs').Profile, fetchImpl?: typeof fetch, log(message: string): void}} deps
+ */
+export async function showContract(options, deps) {
+  const profile = deps.profile ?? "prod";
+  const contract = await new IntegrationContractClient({
+    docsUrl: getDocsUrl(profile), environment: profile, fetchImpl: deps.fetchImpl,
+  }).getContract();
+  if (options.json) deps.log(JSON.stringify(contract, null, 2));
+  else {
+    const {data} = contract;
+    deps.log(`Integration contract: ${data.contractVersion} (schema ${data.schemaVersion})\nEnvironment: ${data.environment}`);
+    deps.log(`Challenge service: ${data.services.challengeUrl}`);
+    deps.log(`Browser SDK: ${data.browser.sdkVersion}\nScript: ${data.browser.scriptUrl}\nIntegrity: ${data.browser.integrity}\nToken header: ${data.browser.tokenHeader}\nModes: ${data.browser.availableModes.join(", ")}`);
+    deps.log(`CSP additions:\n  script-src: ${data.browser.cspAdditions.scriptSrc.join(" ")}\n  connect-src: ${data.browser.cspAdditions.connectSrc.join(" ")}\n  worker-src: ${data.browser.cspAdditions.workerSrc.join(" ")}`);
+    deps.log(`Java SDK: ${data.backend.sdkVersion} (JDK ${data.backend.minJdk}+)\nMaven repository: ${data.backend.mavenRepository}\nCore: ${data.backend.core.groupId}:${data.backend.core.artifactId}:${data.backend.sdkVersion}\n${data.backend.springBoot3.framework}: ${data.backend.springBoot3.groupId}:${data.backend.springBoot3.artifactId}:${data.backend.sdkVersion}`);
+    deps.log(`Documentation:\n  Browser SDK: ${data.documentation.browserSdk}\n  Java SDK: ${data.documentation.javaSdk}\n  Domains and CSP: ${data.documentation.domainsAndCsp}`);
+  }
+  return contract;
+}

package/src/commands/keys-create.mjs

@@ -1,15 +1,18 @@
 // @ts-check
 
 import { mutationKey, parseIssuance, printIssuance, withMutationRecovery } from "./mutation-support.mjs";
+import { outputContext } from "./output.mjs";
 
 /**
- * @param {{appName: string, yes?: boolean, idempotencyKey?: string}} options
+ * @param {{appName: string, json?: boolean, yes?: boolean, idempotencyKey?: string}} options
  * @param {import('./mutation-support.mjs').CommandOutput & {api: {createApp(token: string, options: {name: string, idempotencyKey: string}): Promise<import('./mutation-support.mjs').MutationResponse>}, sessions: {loadToken(): Promise<string>}}} deps
  */
 export async function createKeys(options, deps) {
+  deps = outputContext(options, deps);
   const idempotencyKey = mutationKey(options.idempotencyKey);
   const token = await deps.sessions.loadToken();
   const issuance = await withMutationRecovery(idempotencyKey, deps, async () =>
     parseIssuance(await deps.api.createApp(token, {name: options.appName, idempotencyKey}), 201));
-  printIssuance(issuance, deps);
+  printIssuance(issuance, deps, options);
+  return issuance;
 }

package/src/commands/mutation-support.mjs

@@ -1,7 +1,8 @@
 // @ts-check
 import { randomUUID } from "node:crypto";
 import readline from "node:readline/promises";
-import { stdin, stdout } from "node:process";
+import { stdin, stderr } from "node:process";
+import { printData } from "./output.mjs";
 import { CliError } from "../errors.mjs";
 import { getCommandInvocation } from "../config.mjs";
 import { APPLICATION_STATUSES, invalidResponse, responseObject } from "./application-response.mjs";
@@ -18,16 +19,17 @@ export function mutationKey(supplied) {
   return key;
 }
 
-/** @param {{yes?: boolean}} options @param {CommandOutput} deps @param {string} prompt @param {string} word */
+/** @param {{yes?: boolean, json?: boolean}} options @param {CommandOutput} deps @param {string} prompt @param {string} word */
 export async function confirmAction(options, deps, prompt, word) {
   if (options.yes) return;
+  if (options.json) throw new CliError("This action requires confirmation; use --yes with --json", {code: "CONFIRMATION_REQUIRED", exitCode: 2});
   let accepted;
   if (deps.confirm) accepted = await deps.confirm();
   else {
-    if (!stdin.isTTY || !stdout.isTTY) {
+    if (!stdin.isTTY || !stderr.isTTY) {
       throw new CliError("This action requires confirmation; use --yes in a non-interactive terminal", {code: "CONFIRMATION_REQUIRED", exitCode: 2});
     }
-    const terminal = readline.createInterface({input: stdin, output: stdout});
+    const terminal = readline.createInterface({input: stdin, output: stderr});
     try { accepted = await terminal.question(`${prompt} Type ${word} to continue: `) === word; }
     finally { terminal.close(); }
   }
@@ -81,18 +83,26 @@ export function isApiSecret(value) {
   return typeof value === "string" && /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(value);
 }
 
-/** @param {{appKey: string, status: string, apiSecret: string | null}} issuance @param {CommandOutput} deps */
-export function printIssuance(issuance, deps) {
+/** @param {{appKey: string, status: string, apiSecret: string | null}} issuance @param {CommandOutput} deps @param {{json?: boolean}} [options] */
+export function printIssuance(issuance, deps, options = {}) {
   const invocation = getCommandInvocation(deps.profile);
+  if (options.json) {
+    printData(issuance, deps);
+    const warn = deps.warn ?? console.error;
+    if (issuance.apiSecret === null) warn(`This is an idempotency replay; the API did not return a secret. Run \`${invocation} secret reveal ${issuance.appKey}\` to retrieve the current active secret.`);
+    else warn("Store this secret in your backend secret manager. The CLI did not save it.");
+    (deps.warn ?? console.error)("Configuration publication is asynchronous; this response does not confirm propagation.");
+    return;
+  }
   deps.log(`App Key: ${issuance.appKey}`);
   deps.log(`Status: ${issuance.status}`);
   if (issuance.apiSecret === null) {
-    deps.log(`This is an idempotency replay; the API did not return a secret. Run \`${invocation} keys reveal ${issuance.appKey}\` to retrieve the current active secret.`);
+    deps.log(`This is an idempotency replay; the API did not return a secret. Run \`${invocation} secret reveal ${issuance.appKey}\` to retrieve the current active secret.`);
   } else {
     deps.log(`Secret Key: ${issuance.apiSecret}`);
     deps.log("Store this secret in your backend secret manager. The CLI did not save it.");
   }
-  deps.log("Configuration publication is asynchronous; this response does not confirm propagation.");
+  (deps.warn ?? deps.log)("Configuration publication is asynchronous; this response does not confirm propagation.");
 }
 
 /** @param {MutationResponse} result */
@@ -103,8 +113,12 @@ export function parseAccepted(result) {
   }
 }
 
-/** @param {string} action @param {string} appKey @param {CommandOutput} deps */
-export function printAccepted(action, appKey, deps) {
-  deps.log(`${action} accepted for ${appKey}. Configuration publication is asynchronous.`);
-  deps.log(`Run \`${getCommandInvocation(deps.profile)} apps get ${appKey}\` to check the current application status.`);
+/** @param {string} action @param {string} appKey @param {CommandOutput} deps @param {{json?: boolean}} [options] */
+export function printAccepted(action, appKey, deps, options = {}) {
+  const data = {appKey, status: "accepted"};
+  if (options.json) printData(data, deps);
+  else deps.log(`${action} accepted for ${appKey}.`);
+  (deps.warn ?? deps.log)("Configuration publication is asynchronous.");
+  (deps.warn ?? deps.log)(`Run \`${getCommandInvocation(deps.profile)} app get ${appKey}\` to check the current application status.`);
+  return data;
 }

package/src/commands/output.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+
+/** @param {unknown} data @param {{log(message: string): void}} deps */
+export function printData(data, deps) {
+  deps.log(JSON.stringify({data}, null, 2));
+}
+
+/** Keep diagnostics separate from machine-readable results, including direct callers.
+ * @template {{log: (message: string) => void, warn?: (message: string) => void}} T
+ * @param {{json?: boolean}} options @param {T} deps @returns {T}
+ */
+export function outputContext(options, deps) {
+  return {...deps, warn: deps.warn ?? (options.json ? console.error : deps.log)};
+}
+
+/** @param {import('./application-response.mjs').Application} app
+ * @param {{json?: boolean}} options @param {{log(message: string): void}} deps */
+export function printApplication(app, options, deps) {
+  if (options.json) return printData(app, deps);
+  deps.log(`App Key: ${app.appKey}\nName: ${app.name}\nStatus: ${app.status}\nCreated: ${app.createdAt}\nUpdated: ${app.updatedAt}`);
+}

package/src/commands/secret-commands.mjs

@@ -1,45 +1,52 @@
 // @ts-check
 import { invalidResponse, responseObject } from "./application-response.mjs";
+import { outputContext, printData } from "./output.mjs";
 import { confirmAction, isApiSecret, mutationKey, parseAccepted, parseIssuance, printAccepted, printIssuance, validateHttpStatus, withMutationRecovery } from "./mutation-support.mjs";
 
 /** @typedef {import('./mutation-support.mjs').MutationResponse} MutationResponse */
 /** @typedef {import('./mutation-support.mjs').CommandOutput & {sessions: {loadToken(): Promise<string>}}} Dependencies */
-/** @typedef {{appKey: string, yes?: boolean, idempotencyKey?: string}} MutationOptions */
+/** @typedef {{appKey: string, yes?: boolean, json?: boolean, idempotencyKey?: string}} MutationOptions */
 
 /** @param {MutationOptions} options
  * @param {Dependencies & {api: {rotateSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
  */
 export async function rotateSecret(options, deps) {
+  deps = outputContext(options, deps);
   await confirmAction(options, deps, `Replace the current secret for ${options.appKey}? Existing backend configuration will need the new secret.`, "ROTATE");
   const idempotencyKey = mutationKey(options.idempotencyKey);
   const token = await deps.sessions.loadToken();
   const issuance = await withMutationRecovery(idempotencyKey, deps, async () =>
     parseIssuance(await deps.api.rotateSecret(token, options.appKey, {idempotencyKey}), 200, options.appKey));
-  printIssuance(issuance, deps);
+  printIssuance(issuance, deps, options);
+  return issuance;
 }
 
-/** @param {{appKey: string, yes?: boolean}} options
+/** @param {{appKey: string, yes?: boolean, json?: boolean}} options
  * @param {Dependencies & {api: {revealSecret(token: string, appKey: string): Promise<MutationResponse>}}} deps
  */
 export async function revealSecret(options, deps) {
+  deps = outputContext(options, deps);
   await confirmAction(options, deps, `Display the current API secret for ${options.appKey} in this terminal?`, "REVEAL");
   const token = await deps.sessions.loadToken();
   const result = await deps.api.revealSecret(token, options.appKey);
   validateHttpStatus(result, 200);
   const {apiSecret} = responseObject(result.body);
   if (!isApiSecret(apiSecret)) throw invalidResponse("The reveal response did not contain a valid API secret");
-  deps.log(`Secret Key: ${apiSecret}`);
-  deps.log("Store this secret in your backend secret manager. The CLI did not save it.");
+  if (options.json) printData({apiSecret}, deps);
+  else deps.log(`Secret Key: ${apiSecret}`);
+  (deps.warn ?? deps.log)("Store this secret in your backend secret manager. The CLI did not save it.");
+  return {apiSecret};
 }
 
 /** @param {MutationOptions} options
  * @param {Dependencies & {api: {revokeSecret(token: string, appKey: string, options: {idempotencyKey: string}): Promise<MutationResponse>}}} deps
  */
 export async function revokeSecret(options, deps) {
+  deps = outputContext(options, deps);
   await confirmAction(options, deps, `Revoke the current API secret for ${options.appKey}?`, "REVOKE");
   const idempotencyKey = mutationKey(options.idempotencyKey);
   const token = await deps.sessions.loadToken();
   await withMutationRecovery(idempotencyKey, deps, async () =>
     parseAccepted(await deps.api.revokeSecret(token, options.appKey, {idempotencyKey})));
-  printAccepted("Secret revocation", options.appKey, deps);
+  return printAccepted("Secret revocation", options.appKey, deps, options);
 }

package/src/commands/signin.mjs

@@ -4,12 +4,15 @@ import { CliError } from "../errors.mjs";
 import { REQUESTED_OAUTH_SCOPES, validateAuthorizationIssuer } from "../config.mjs";
 import { createLoopbackReceiver } from "../oauth-loopback.mjs";
 import { openBrowser } from "../browser-opener.mjs";
+import { printData, outputContext } from "./output.mjs";
 
 /** @typedef {{
  * oauth: Pick<import('../oauth-client.mjs').OAuthClient, 'discover' | 'exchangeCode' | 'config'>,
  * authorizationIssuer?: string,
  * sessions: {save(credentials: import('../oauth-client.mjs').OAuthCredentials): Promise<void>},
  * log: (message: string) => void,
+ * warn?: (message: string) => void,
+ * profile?: import('../config.mjs').Profile,
  * openBrowser?: typeof openBrowser,
  * signal?: AbortSignal,
  * timeoutMs?: number,
@@ -17,8 +20,11 @@ import { openBrowser } from "../browser-opener.mjs";
  * }} SigninDependencies
  */
 
-/** @param {{noOpen?: boolean}} options @param {SigninDependencies} deps */
-export async function signin({noOpen = false}, deps) {
+/** @param {{noOpen?: boolean, json?: boolean}} options @param {SigninDependencies} deps */
+export async function signin(options, deps) {
+  const {noOpen = false} = options;
+  deps = outputContext(options, deps);
+  const progress = deps.warn ?? deps.log;
   const authorizationIssuer = validateAuthorizationIssuer(deps.authorizationIssuer ?? deps.oauth.config.issuer);
   const controller = new AbortController();
   let expired = false;
@@ -45,13 +51,13 @@ export async function signin({noOpen = false}, deps) {
       code_challenge_method: "S256", state, scope: REQUESTED_OAUTH_SCOPES.join(" "),
     }).toString();
     if (noOpen) {
-      deps.log(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
+      progress(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
     } else {
-      deps.log("Opening your browser to sign in. Complete authorization on this computer.");
+      progress("Opening your browser to sign in. Complete authorization on this computer.");
       try { await (deps.openBrowser ?? openBrowser)(authorizeUrl.href, {signal}); }
       catch {
         signal.throwIfAborted();
-        deps.log(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
+        progress(`Open this authorization URL in a browser on this computer:\n${authorizeUrl.href}`);
       }
     }
     const {code} = await receiver.result;
@@ -61,14 +67,17 @@ export async function signin({noOpen = false}, deps) {
     await deps.sessions.save(credentials);
     signal.throwIfAborted();
     receiver.complete(true);
-    deps.log("Signed in successfully. The session is stored for the current user.");
+    const result = {profile: deps.profile ?? "prod", signedIn: true};
+    if (options.json) printData(result, deps);
+    else deps.log("Signed in successfully. The session is stored for the current user.");
+    return result;
   } catch (error) {
     receiver?.complete(false);
     if (controller.signal.aborted) throw new CliError(expired
-      ? "Sign-in expired; run `requestshield signin` again"
+      ? "Sign-in expired; run `requestshield login` again"
       : "Sign-in was cancelled", {code: expired ? "SIGNIN_EXPIRED" : "SIGNIN_CANCELLED", exitCode: 3});
     if (error instanceof CliError) throw error;
-    throw new CliError("Sign-in failed; run `requestshield signin` again", {code: "SIGNIN_FAILED", exitCode: 3});
+    throw new CliError("Sign-in failed; run `requestshield login` again", {code: "SIGNIN_FAILED", exitCode: 3});
   } finally {
     clearTimeout(timer);
     interruptSource.removeListener("SIGINT", cancel);

package/src/commands/signout.mjs

@@ -1,9 +1,13 @@
 // @ts-check
 
-/** @param {{}} _options
+import { printData } from "./output.mjs";
+
+/** @param {{json?: boolean}} options
  * @param {{sessions: {signout(): Promise<{profile: import('../config.mjs').Profile, removed: boolean}>}, log: (message: string) => void}} deps
  */
-export async function signout(_options, deps) {
+export async function signout(options, deps) {
   const { profile, removed } = await deps.sessions.signout();
-  deps.log(removed ? `Signed out locally from ${profile}.` : `No saved local session for ${profile}.`);
+  if (options.json) printData({profile, removed}, deps);
+  else deps.log(removed ? `Signed out locally from ${profile}.` : `No saved local session for ${profile}.`);
+  return {profile, removed};
 }

package/src/commands/update-check.mjs

@@ -2,46 +2,93 @@
 
 import readline from "node:readline/promises";
 import { spawn } from "node:child_process";
-import { stdin, stdout } from "node:process";
+import { stdin, stderr } from "node:process";
 import { CliError } from "../errors.mjs";
 
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 
 /**
- * @param {{ currentVersion: string, packageName: string, profile?: "qat" | "stg" | "prod", log: (message: string) => void, fetchImpl?: typeof fetch, confirm?: (latestVersion: string) => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void> }} options
+ * @typedef {{ currentVersion: string, packageName: string, profile?: "qat" | "stg" | "prod", json?: boolean, yes?: boolean, log: (message: string) => void, warn?: (message: string) => void, fetchImpl?: typeof fetch, confirm?: (latestVersion: string) => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void> }} UpdateOptions
+ * @typedef {{ profile: "qat" | "stg" | "prod", currentVersion: string, latestVersion: string | null, updateAvailable: boolean | null, action: "check" | "apply", outcome: "source_checkout" | "up_to_date" | "available" | "installed" | "cancelled", target?: string }} UpdateResult
  */
+
+/** @param {UpdateOptions} options */
 export async function checkForUpdate(options) {
+  const result = await inspectUpdate(options, "check");
+  printResult(result, options);
+  return result;
+}
+
+/** @param {UpdateOptions} options */
+export async function applyUpdate(options) {
+  const result = await inspectUpdate(options, "apply");
+  if (result.outcome !== "available" || result.latestVersion === null) {
+    printResult(result, options);
+    return result;
+  }
+
+  const warn = options.warn ?? ((message) => console.error(message));
+  warn(`Update target: global npm installation of ${options.packageName}.`);
+  if (options.json && !options.yes) {
+    throw confirmationRequired();
+  }
+  const accepted = options.yes || await (options.confirm ?? confirmUpdate)(result.latestVersion);
+  if (!accepted) {
+    result.outcome = "cancelled";
+    printResult(result, options);
+    return result;
+  }
+
+  warn(`Installing RequestShield ${result.latestVersion} globally with npm...`);
+  await (options.install ?? installWithNpm)(options.packageName, result.latestVersion);
+  result.outcome = "installed";
+  printResult(result, options);
+  return result;
+}
+
+/** @param {UpdateOptions} options @param {"check" | "apply"} action @returns {Promise<UpdateResult>} */
+async function inspectUpdate(options, action) {
   const profile = options.profile ?? "prod";
   if (profile !== "prod") {
-    options.log(`requestshield-${profile} runs this local repository checkout and has no separately published npm release.`);
-    options.log("Update the checkout with your normal Git workflow.");
-    options.log(`Then run from requestshield-cli/: npx --offline --prefix ./dev requestshield-${profile} <command>`);
-    return;
+    return { profile, currentVersion: options.currentVersion, latestVersion: null, updateAvailable: null, action, outcome: "source_checkout" };
   }
-  const latestVersion = await fetchLatestVersion(
-    options.packageName,
-    options.fetchImpl ?? fetch,
-  );
-
-  options.log(`Current version: ${options.currentVersion}`);
-  options.log(`Latest version: ${latestVersion}`);
+  const latestVersion = await fetchLatestVersion(options.packageName, options.fetchImpl ?? fetch);
+  const updateAvailable = compareVersions(latestVersion, options.currentVersion) > 0;
+  return {
+    profile,
+    currentVersion: options.currentVersion,
+    latestVersion,
+    updateAvailable,
+    action,
+    outcome: updateAvailable ? "available" : "up_to_date",
+    target: `global npm installation of ${options.packageName}`,
+  };
+}
 
-  if (compareVersions(latestVersion, options.currentVersion) <= 0) {
-    options.log("RequestShield is already up to date.");
+/** @param {UpdateResult} result @param {UpdateOptions} options */
+function printResult(result, options) {
+  if (options.json) {
+    options.log(JSON.stringify({ data: result }, null, 2));
     return;
   }
-
-  options.log(`Update target: global npm installation of ${options.packageName}.`);
-  const accepted = await (options.confirm ?? confirmUpdate)(latestVersion);
-  if (!accepted) {
-    options.log("Update cancelled.");
+  if (result.outcome === "source_checkout") {
+    options.log(`requestshield-${result.profile} runs this local repository checkout and has no separately published npm release.`);
+    options.log("Update the checkout with your normal Git workflow.");
+    options.log(`Then run from requestshield-cli/: npx --offline --prefix ./dev requestshield-${result.profile} <command>`);
     return;
   }
-
-  options.log(`Installing RequestShield ${latestVersion} globally with npm...`);
-  await (options.install ?? installWithNpm)(options.packageName, latestVersion);
-  options.log(`RequestShield ${latestVersion} was installed successfully (global npm installation).`);
-  options.log("Open a new terminal before running RequestShield again.");
+  options.log(`Current version: ${result.currentVersion}`);
+  options.log(`Latest version: ${result.latestVersion}`);
+  if (result.outcome === "up_to_date") options.log("RequestShield is already up to date.");
+  if (result.outcome === "available") {
+    options.log("Run requestshield update apply to install the update.");
+    options.log(`Update target: ${result.target}.`);
+  }
+  if (result.outcome === "cancelled") options.log("Update cancelled.");
+  if (result.outcome === "installed") {
+    options.log(`RequestShield ${result.latestVersion} was installed successfully (global npm installation).`);
+    options.log("Open a new terminal before running RequestShield again.");
+  }
 }
 
 /** @param {string} packageName @param {typeof fetch} fetchImpl */
@@ -50,8 +97,8 @@ async function fetchLatestVersion(packageName, fetchImpl) {
   let response;
   try {
     response = await fetchImpl(url, { signal: AbortSignal.timeout(15_000) });
-  } catch (error) {
-    throw new CliError(`Could not check the latest RequestShield version: ${messageOf(error)}`, {
+  } catch {
+    throw new CliError("Could not check the latest RequestShield version. Check your connection and retry.", {
       code: "UPDATE_CHECK_FAILED",
       exitCode: 7,
     });
@@ -64,7 +111,14 @@ async function fetchLatestVersion(packageName, fetchImpl) {
     });
   }
 
-  const body = await response.json();
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new CliError("The npm registry returned an invalid RequestShield version", {
+      code: "INVALID_UPDATE_RESPONSE",
+    });
+  }
   const version = body && typeof body === "object" ? Reflect.get(body, "version") : undefined;
   if (typeof version !== "string" || !parseVersion(version)) {
     throw new CliError("The npm registry returned an invalid RequestShield version", {
@@ -76,13 +130,8 @@ async function fetchLatestVersion(packageName, fetchImpl) {
 
 /** @param {string} latestVersion */
 async function confirmUpdate(latestVersion) {
-  if (!stdin.isTTY || !stdout.isTTY) {
-    throw new CliError(`RequestShield ${latestVersion} is available, but confirmation requires an interactive terminal`, {
-      code: "UPDATE_CONFIRMATION_REQUIRED",
-      exitCode: 2,
-    });
-  }
-  const prompt = readline.createInterface({ input: stdin, output: stdout });
+  if (!stdin.isTTY || !stderr.isTTY) throw confirmationRequired();
+  const prompt = readline.createInterface({ input: stdin, output: stderr });
   try {
     const answer = await prompt.question(`Install RequestShield ${latestVersion} globally with npm? (y/N): `);
     return answer.trim().toLowerCase() === "y";
@@ -91,16 +140,26 @@ async function confirmUpdate(latestVersion) {
   }
 }
 
+function confirmationRequired() {
+  return new CliError("Installing an update requires confirmation. Use an interactive terminal or pass --yes to requestshield update apply.", {
+    code: "UPDATE_CONFIRMATION_REQUIRED",
+    exitCode: 2,
+  });
+}
+
 /** @param {string} packageName @param {string} version */
 async function installWithNpm(packageName, version) {
   await new Promise((resolve, reject) => {
     const child = spawn("npm", ["install", "--global", `${packageName}@${version}`], {
       shell: process.platform === "win32",
-      stdio: "inherit",
+      // npm's output is diagnostic. Keep command stdout available for JSON.
+      stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
     });
-    child.once("error", (error) => {
-      reject(new CliError(`Could not start npm: ${error.message}`, {
+    child.stdout?.pipe(stderr, { end: false });
+    child.stderr?.pipe(stderr, { end: false });
+    child.once("error", () => {
+      reject(new CliError("Could not start npm. Check that npm is installed and available.", {
         code: "UPDATE_FAILED",
         exitCode: 1,
       }));
@@ -139,9 +198,4 @@ function parseVersion(value) {
   };
 }
 
-/** @param {unknown} error */
-function messageOf(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export { compareVersions };