requestshield 0.1.0 → 0.1.2

package/README.md

@@ -1,96 +1,233 @@
 # RequestShield CLI
 
-Customer-facing CLI for signing in, rotating RequestShield application keys,
-and installing the RequestShield skill for Codex.
+Customer-facing command-line tool for RequestShield. The CLI lets a customer
+sign in, rotate application credentials, install the RequestShield Skill for
+Codex, and check for a newer npm release.
+
+Current package version: `0.1.2`.
 
 ## Requirements
 
-- Node.js 22.13 or newer.
-- A customer management API implementing the contract below.
+- Node.js 22.13 or newer when running from source, npm, or npx.
+- pnpm for local development and release builds.
+- A RequestShield customer management API.
+- Windows x64 and Inno Setup 6 when building the Windows installer.
 
-The API defaults to `https://api.intellifend.ai`. For development, set
-`REQUESTSHIELD_API_URL` to the management API origin.
+The management API defaults to `https://api.intellifend.ai`. During local
+development, set `REQUESTSHIELD_API_URL` to another API origin when needed.
 
-## Commands
+## Implemented commands
 
 ```console
 requestshield signin
+requestshield keys create [--yes]
+requestshield agent setup --agent codex [--force]
+requestshield update check
+requestshield --help
+requestshield --version
+```
+
+The full command catalog shown by `requestshield --help` includes planned
+commands. Only the commands listed above are currently implemented.
+
+### Sign in
+
+```console
+requestshield signin
+```
+
+Starts the device authorization flow. The CLI prints the verification URL and
+user code but does not open a browser automatically. After authorization, the
+session is saved in the current user's application-data directory.
+
+For CI or automation, `REQUESTSHIELD_ACCESS_TOKEN` may provide the access token.
+An environment token is never persisted by the CLI.
+
+### Create new keys
+
+```console
 requestshield keys create
+```
+
+Asks the customer to type `ROTATE`, then atomically deactivates the previous
+credentials and creates a new `appKey` and `apiSecret`.
+
+- `appKey` identifies the application and may be used by the client integration.
+- `apiSecret` is a backend-only secret, is displayed once, and is not saved by
+  the CLI.
+- `--yes` skips the interactive confirmation and is intended for automation.
+
+Store the Secret Key in a backend secret manager immediately after creation.
+
+### Install the Codex Skill
+
+```console
 requestshield agent setup --agent codex
 ```
 
-`signin` starts a device authorization flow and prints the verification URL and
-code for the customer to open manually. The returned session is stored under the user's standard
-application-data directory with permissions restricted to that user. CI may
-instead provide `REQUESTSHIELD_ACCESS_TOKEN`; environment tokens are never
-persisted.
+Installs the bundled RequestShield Skill into
+`$CODEX_HOME/skills/requestshield`, or `~/.codex/skills/requestshield` when
+`CODEX_HOME` is not set. Restart Codex or start a new task after installation.
 
-`keys create` asks for confirmation, then atomically deactivates the previous
-application credentials and creates a new `appKey` + `apiSecret`. The public
-app key and the backend-only secret are printed after success. The secret is
-not stored by the CLI and cannot be retrieved again.
+If that Skill already exists, the command preserves it. Use `--force` to
+replace the existing copy:
 
-`agent setup --agent codex` installs the bundled `requestshield` skill into
-`$CODEX_HOME/skills`, or `~/.codex/skills` when `CODEX_HOME` is unset. Existing
-content is preserved unless `--force` is supplied.
+```console
+requestshield agent setup --agent codex --force
+```
 
-## Management API contract
+### Check for updates
 
-### Start sign-in
+```console
+requestshield update check
+```
 
-`POST /v1/cli/signin`
+Reads the latest `requestshield` version from the npm registry. If a newer
+version exists, the CLI displays the current and latest versions, asks the user
+to confirm with `y`, then runs:
 
-```json
-{
-  "client": "requestshield-cli"
-}
+```console
+npm install --global requestshield@<latest-version>
 ```
 
-The response contains `deviceCode`, `userCode`, `verificationUri`,
-`expiresIn`, and `interval`.
+This updater is for npm global installations and requires `node` and `npm` on
+the customer's machine. It does not replace an executable installed by the
+Windows Inno Setup installer.
 
-### Poll sign-in
+## Install and run with npm
 
-`POST /v1/cli/signin/token` with `{ "deviceCode": "..." }`.
+Install globally so `requestshield` is available from any directory:
 
-Pending responses use HTTP 400 with `code` set to `authorization_pending` or
-`slow_down`. A successful response contains `accessToken` and optional account
-metadata.
+```console
+npm install --global requestshield
+requestshield --help
+```
 
-### Rotate keys
+Run without a global installation:
 
-`POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
-The response contains `appKey` and one-time `apiSecret`.
+```console
+npx --yes requestshield@0.1.2 --help
+npx --yes requestshield@0.1.2 signin
+```
 
-## Development
+## Local development
+
+From the `requestshield-cli` directory:
 
 ```console
-pnpm --filter requestshield lint
-pnpm --filter requestshield typecheck
-pnpm --filter requestshield test
-pnpm --filter requestshield build
+pnpm install
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+node src/main.mjs --help
+node src/main.mjs --version
+```
+
+`build` currently validates the syntax of all `.mjs` files. It does not create
+the standalone Windows executable.
+
+To test the update interaction without publishing or installing anything:
+
+```powershell
+$env:REQUESTSHIELD_MOCK_LATEST_VERSION = "0.1.3"
+pnpm test:update-check:manual
+Remove-Item Env:REQUESTSHIELD_MOCK_LATEST_VERSION
 ```
-## Quick start
 
-RequestShield requires Node.js 22.13 or newer.
+The manual test prints `[MOCK] Would install ...`; it intentionally does not
+change the installed CLI version.
+
+## Build the standalone Windows executable
+
+The project uses Node.js Single Executable Applications (SEA). Run these steps
+from the `requestshield-cli` directory in PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .\dist | Out-Null
+pnpm exec esbuild .\src\main.mjs --bundle --platform=node --format=cjs --target=node22 --outfile=.\dist\requestshield.cjs
+node --experimental-sea-config .\sea-config.json
+Copy-Item (Get-Command node.exe).Source .\dist\requestshield.exe -Force
+pnpm exec postject .\dist\requestshield.exe NODE_SEA_BLOB .\dist\requestshield.blob --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2
+.\dist\requestshield.exe --help
+```
+
+The generated file is `dist\requestshield.exe`. It contains Node.js and does
+not require Node.js to be installed on the customer's machine.
+
+## Build the Windows installer
 
-Run without installing globally:
+Install Inno Setup 6, then compile the installer and pass the current package
+version explicitly:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .\release | Out-Null
+& "$env:LOCALAPPDATA\Programs\Inno Setup 6\ISCC.exe" "/DAppVersion=0.1.2" "/FRequestShieldSetup-0.1.2-windows-x64" ".\installer\requestshield.iss"
+```
+
+The installer is written to `release\RequestShieldSetup-0.1.2-windows-x64.exe`.
+It installs `requestshield.exe` under the current user's local application-data
+directory and adds that directory to the user `PATH`. The customer must open a
+new terminal before running:
 
 ```console
-npx requestshield --help
-npx requestshield signin
-npx requestshield keys create
-npx requestshield agent setup --agent codex
+requestshield --help
 ```
 
-Pin a specific version for reproducible usage:
+## Publish to npm
+
+Before publishing, update `version` in `package.json`, run the checks, and
+inspect the package contents:
 
 ```console
-npx requestshield@0.1.0 --help
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm pack --dry-run
+pnpm publish --access public --no-git-checks
 ```
 
-To automatically accept npm's installation prompt:
+npm may ask for a one-time password in the interactive terminal. After
+publishing, verify the registry state:
 
 ```console
-npx --yes requestshield@0.1.0 --help
+npm view requestshield version
+npm dist-tag ls requestshield
+npx --yes requestshield@0.1.2 --version
+```
+
+## Management API contract
+
+### Start sign-in
+
+`POST /v1/cli/signin`
+
+```json
+{
+  "client": "requestshield-cli"
+}
 ```
+
+The response contains `deviceCode`, `userCode`, `verificationUri`, `expiresIn`,
+and `interval`.
+
+### Poll sign-in
+
+`POST /v1/cli/signin/token` with `{ "deviceCode": "..." }`.
+
+Pending responses use HTTP 400 with `code` set to `authorization_pending` or
+`slow_down`. A successful response contains `accessToken` and optional account
+metadata.
+
+### Rotate keys
+
+`POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
+The response contains `appKey` and the one-time `apiSecret`.
+
+## Security notes
+
+- Never place an access token or Secret Key in URLs, command arguments, logs,
+  fixtures, or committed files.
+- The CLI does not persist the Secret Key returned by `keys create`.
+- Sign the Windows executable and installer before distributing them to
+  customers, and publish a checksum through a trusted release channel.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "requestshield",
-  "version": "0.1.0",
-  "description": "Customer CLI for IntelliFend RequestShield.",
+  "version": "0.1.2",
+  "description": "Customer CLI for RequestShield.",
   "type": "module",
   "bin": {
     "requestshield": "src/main.mjs"
@@ -14,18 +14,18 @@
   "engines": {
     "node": ">=22.13"
   },
-  "scripts": {
-    "build": "node scripts/check-package.mjs",
-    "lint": "node scripts/check-package.mjs",
-    "test": "node --test",
-    "typecheck": "tsc -p jsconfig.json --noEmit",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm test"
-  },
   "devDependencies": {
     "@types/node": "26.1.1",
     "esbuild": "^0.28.1",
     "postject": "1.0.0-alpha.6",
     "typescript": "^6.0.3"
   },
-  "license": "UNLICENSED"
-}
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "node scripts/check-package.mjs",
+    "lint": "node scripts/check-package.mjs",
+    "test": "node --test",
+    "test:update-check:manual": "node scripts/manual-update-check.mjs",
+    "typecheck": "tsc -p jsconfig.json --noEmit"
+  }
+}

package/src/args.mjs

@@ -2,18 +2,61 @@
 
 import { CliError } from "./errors.mjs";
 
-const HELP = `RequestShield customer CLI
+const HELP = `RequestShield CLI
 
 Usage:
-  requestshield signin
-  requestshield keys create [--yes]
-  requestshield agent setup --agent codex [--force]
-  requestshield --help
-  requestshield --version`;
+  requestshield [command] [options]
+
+Commands:
+  update
+    check                           Check for and install the latest CLI version
+
+  auth
+    signin                         Sign in to RequestShield
+    status                         Show authentication status
+
+  keys
+    create                         Create a new application and key pair
+    deactivate                     Deactivate application credentials
+    rotate                         Rotate the Secret Key for an application
+
+  agent
+    setup                          Install the RequestShield Agent Skill
+    setup --agent codex            Install the Skill for Codex
+    setup --agent claude           Install the Skill for Claude
+    setup --status                 Show Agent Skill installation status
+
+  contract
+    get                            Get the RequestShield integration contract
+
+  apps
+    list                           List accessible applications
+    get <app-key>                  Get application information
+    readiness <app-key>            Check application readiness
+
+  credentials
+    status <app-key>               Show credential status without exposing secrets
+
+  challenge
+    volume <app-key>               Get challenge volume for an application
+
+  billing
+    get <app-key>                  Get billing and plan information
+
+  protect
+    list <app-key>                 List protected endpoints
+    add                            Add a protected endpoint
+    remove                         Remove a protected endpoint
+
+Options:
+  -h, --help                       Show help
+  -v, --version                    Show CLI version
+  --json                           Output machine-readable JSON`;
 
 /**
  * @typedef {{ command: "help", help: string }
  * | { command: "version" }
+ * | { command: "update-check" }
  * | { command: "signin" }
  * | { command: "keys-create", yes: boolean }
  * | { command: "agent-setup", agent: "codex", force: boolean }} ParsedArgs
@@ -24,9 +67,13 @@ export function parseArgs(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
     return { command: "help", help: HELP };
   }
-  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-V")) {
+  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V")) {
     return { command: "version" };
   }
+  if (argv[0] === "update" && argv[1] === "check") {
+    assertOnly(argv.slice(2), new Set());
+    return { command: "update-check" };
+  }
   if (argv[0] === "signin") {
     assertOnly(argv.slice(1), new Set());
     return { command: "signin" };

package/src/cli.mjs

@@ -7,17 +7,28 @@ import { SessionStore } from "./session-store.mjs";
 import { signin } from "./commands/signin.mjs";
 import { createKeys } from "./commands/keys-create.mjs";
 import { setupAgent } from "./commands/agent-setup.mjs";
+import { checkForUpdate } from "./commands/update-check.mjs";
 import packageJson from "../package.json" with { type: "json" };
 
 /**
  * @param {string[]} argv
- * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean> }} [deps]
+ * @param {{ log?: (message: string) => void, api?: ManagementApiClient, sessions?: SessionStore, env?: NodeJS.ProcessEnv, homeDir?: string, sourceDir?: string, wait?: (milliseconds: number) => Promise<unknown>, confirm?: () => Promise<boolean>, fetchImpl?: typeof fetch, confirmUpdate?: () => Promise<boolean>, installLatest?: (packageName: string, version: string) => Promise<void> }} [deps]
  */
 export async function run(argv, deps = {}) {
   const parsed = parseArgs(argv);
   const log = deps.log ?? ((message) => console.log(message));
   if (parsed.command === "help") return log(parsed.help);
-  if (parsed.command === "version") return log(packageJson.version);
+  if (parsed.command === "version") return log("requestshield " + packageJson.version);
+  if (parsed.command === "update-check") {
+    return checkForUpdate({
+      currentVersion: packageJson.version,
+      packageName: packageJson.name,
+      log,
+      fetchImpl: deps.fetchImpl,
+      confirm: deps.confirmUpdate,
+      install: deps.installLatest,
+    });
+  }
 
   if (parsed.command === "agent-setup") {
     return setupAgent(parsed, { log, ...deps });

package/src/commands/update-check.mjs

@@ -0,0 +1,139 @@
+// @ts-check
+
+import readline from "node:readline/promises";
+import { spawn } from "node:child_process";
+import { stdin, stdout } from "node:process";
+import { CliError } from "../errors.mjs";
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+
+/**
+ * @param {{ currentVersion: string, packageName: string, log: (message: string) => void, fetchImpl?: typeof fetch, confirm?: () => Promise<boolean>, install?: (packageName: string, version: string) => Promise<void> }} options
+ */
+export async function checkForUpdate(options) {
+  const latestVersion = await fetchLatestVersion(
+    options.packageName,
+    options.fetchImpl ?? fetch,
+  );
+
+  options.log(`Current version: ${options.currentVersion}`);
+  options.log(`Latest version: ${latestVersion}`);
+
+  if (compareVersions(latestVersion, options.currentVersion) <= 0) {
+    options.log("RequestShield is already up to date.");
+    return;
+  }
+
+  const accepted = await (options.confirm ?? confirmUpdate)(latestVersion);
+  if (!accepted) {
+    options.log("Update cancelled.");
+    return;
+  }
+
+  options.log(`Updating RequestShield to ${latestVersion}...`);
+  await (options.install ?? installWithNpm)(options.packageName, latestVersion);
+  options.log(`RequestShield ${latestVersion} was installed successfully.`);
+  options.log("Open a new terminal before running RequestShield again.");
+}
+
+/** @param {string} packageName @param {typeof fetch} fetchImpl */
+async function fetchLatestVersion(packageName, fetchImpl) {
+  const url = `${DEFAULT_REGISTRY}/${encodeURIComponent(packageName)}/latest`;
+  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)}`, {
+      code: "UPDATE_CHECK_FAILED",
+      exitCode: 7,
+    });
+  }
+
+  if (!response.ok) {
+    throw new CliError(`Could not check the latest RequestShield version: HTTP ${response.status}`, {
+      code: "UPDATE_CHECK_FAILED",
+      exitCode: 7,
+    });
+  }
+
+  const body = await response.json();
+  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", {
+      code: "INVALID_UPDATE_RESPONSE",
+    });
+  }
+  return version;
+}
+
+/** @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 });
+  try {
+    const answer = await prompt.question(`Update to RequestShield ${latestVersion}? (y/N): `);
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    prompt.close();
+  }
+}
+
+/** @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",
+      windowsHide: true,
+    });
+    child.once("error", (error) => {
+      reject(new CliError(`Could not start npm: ${error.message}`, {
+        code: "UPDATE_FAILED",
+        exitCode: 1,
+      }));
+    });
+    child.once("exit", (code) => {
+      if (code === 0) resolve(undefined);
+      else reject(new CliError(`npm update failed with exit code ${code ?? "unknown"}`, {
+        code: "UPDATE_FAILED",
+        exitCode: 1,
+      }));
+    });
+  });
+}
+
+/** @param {string} left @param {string} right */
+function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) throw new CliError("RequestShield has an invalid semantic version");
+  for (let index = 0; index < 3; index++) {
+    if (a.numbers[index] !== b.numbers[index]) return a.numbers[index] - b.numbers[index];
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === undefined) return 1;
+  if (b.prerelease === undefined) return -1;
+  return a.prerelease.localeCompare(b.prerelease, "en", { numeric: true });
+}
+
+/** @param {string} value */
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+  if (!match) return undefined;
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4],
+  };
+}
+
+/** @param {unknown} error */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export { compareVersions };