requestshield 0.1.3 → 0.1.5

package/README.md

@@ -1,43 +1,290 @@
 # RequestShield CLI
 
-Customer-facing CLI for signing in, rotating RequestShield application keys,
-and installing the RequestShield skill for Codex or Claude.
+Customer-facing CLI for IntelliFend RequestShield. It allows customers to sign
+in, rotate application credentials, install the RequestShield Skill for Codex
+or Claude, and update an npm-installed CLI.
+
+Current package version: `0.1.5`.
 
 ## Requirements
 
 - Node.js 22.13 or newer.
-- A customer management API implementing the contract below.
+- A RequestShield customer management API.
+- npm for local development and publishing.
+
+The management API defaults to `https://api.intellifend.ai`. Set
+`REQUESTSHIELD_API_URL` to use a different management API during development.
+
+## Implemented commands
 
-The API defaults to `https://api.intellifend.ai`. For development, set
-`REQUESTSHIELD_API_URL` to the management API origin.
+```console
+requestshield signin
+requestshield keys create [--yes]
+requestshield contract
+requestshield apps list [--json]
+requestshield apps get <app-key>
+requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
+requestshield get billing <app-key>
+requestshield agent setup [--force]
+requestshield agent setup --codex [--force]
+requestshield agent setup --claude [--force]
+requestshield update check
+requestshield --help
+requestshield --version
+```
 
-## Commands
+### Sign in
 
 ```console
 requestshield signin
+```
+
+Starts the device authorization flow. The CLI prints the verification URL and
+user code without opening the browser automatically. After authorization, the
+session is stored for the current operating-system user.
+
+For CI or automation, provide `REQUESTSHIELD_ACCESS_TOKEN`. A token supplied by
+the environment is used directly and is not persisted by the CLI.
+
+### Create new keys
+
+```console
 requestshield keys create
+```
+
+Asks the customer to type `ROTATE`, then calls the management API to deactivate
+the previous credentials and create a new `appKey` and `apiSecret`.
+
+- `appKey` is the public application identifier.
+- `apiSecret` is a backend-only secret displayed once.
+- The CLI does not save the returned `apiSecret`.
+- `--yes` skips the confirmation prompt for non-interactive automation.
+
+Store the Secret Key in a backend secret manager immediately after creation.
+
+### Get the integration contract
+
+```console
+requestshield contract
+```
+
+Returns the current authoritative integration contract as JSON, including any
+additional SDK-version or CSP fields supplied by the API. The command requires a
+saved sign-in session and validates the core browser, backend, and release fields
+before printing the response.
+
+### List applications
+
+```console
+requestshield apps list
+```
+
+Lists the applications the signed-in user is allowed to access:
+
+```text
+APP KEY  NAME                STATUS
+app_123  Production Website  pending
+app_456  Staging Website     active
+```
+
+Use `--json` to print the stable `{ "data": [...], "nextCursor": null }`
+response shape. The CLI allowlists `appKey`, `name`, `status`, `createdAt`, and
+`updatedAt`; it never prints an API Secret returned accidentally by the service.
+
+### Get an application
+
+```console
+requestshield apps get app_123
+```
+
+Returns `app_key`, `name`, and the application's current status as JSON.
+Valid statuses are:
+
+- `ready` — the application key was just created and no traffic has been received.
+- `active` — the application is receiving traffic.
+- `deactivated` — the application has been deactivated.
+
+The requested App Key must exactly match the key in the API response.
+
+### Get challenge volume
+
+```console
+requestshield challenge volume app_123 \
+  --from 2026-08-01T00:00:00Z \
+  --to 2026-08-27T23:59:59Z \
+  --granularity day
+```
+
+Returns challenge/request volume as JSON. Times must be ISO-8601 timestamps, and
+`--from` cannot be later than `--to`. Granularity values such as `hour` and `day`
+are passed to the API, which owns the supported set.
+
+Challenge volume proves that traffic reached the platform; it does not prove
+that the protected backend rejects requests without a valid token.
+
+### Get billing information
+
+```console
+requestshield get billing app_123
+```
+
+Returns the selected application's current plan, billing cycle, charges, quota,
+and usage as JSON. The command is read-only and requires a saved sign-in session.
+
+### Install the Agent Skill
+
+Let the CLI detect the installed coding agent:
+
+```console
 requestshield agent setup
+```
+
+Or select an agent explicitly:
+
+```console
 requestshield agent setup --codex
 requestshield agent setup --claude
 ```
 
-`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.
+The CLI installs the Skill into:
+
+- Codex: `~/.agents/skills/requestshield`
+- Claude: `~/.claude/skills/requestshield`
+
+If exactly one supported agent is detected, it is selected automatically. If
+both are detected in an interactive terminal, the CLI asks which one to use.
+If neither is detected, select one with `--codex` or `--claude`.
+
+Existing Skill content is preserved. Add `--force` to replace it:
+
+```console
+requestshield agent setup --codex --force
+```
+
+Restart the selected agent or start a new task after installation.
+
+### Check for updates
+
+```console
+requestshield update check
+```
+
+Checks the npm registry for the latest `@intellifend/requestshield` version.
+When a newer version exists, the CLI displays the current and latest versions
+and asks:
+
+```text
+Update to RequestShield <version>? (y/N):
+```
+
+Entering `y` runs the equivalent of:
+
+```console
+npm install --global @intellifend/requestshield@<latest-version>
+```
+
+This command requires an interactive terminal, Node.js, and npm. It updates a
+global npm installation; it does not replace a standalone Windows executable.
+
+## Install with npm
+
+Install globally:
+
+```console
+npm install --global @intellifend/requestshield
+requestshield --help
+requestshield --version
+```
+
+Run a specific version without installing globally:
 
-`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.
+```console
+npx --yes --package=@intellifend/requestshield@0.1.5 requestshield --help
+npx --yes --package=@intellifend/requestshield@0.1.5 requestshield signin
+```
+
+To invoke the update command through npx, include the package name:
+
+```console
+npx --yes --package=@intellifend/requestshield@0.1.5 requestshield update check
+```
+
+Do not run `npx update check`; npm interprets `update` as the name of a different
+npm package.
+
+## Local development
+
+From the `requestshield-cli` directory:
+
+```console
+npm install
+npm run lint
+npm run typecheck
+npm test
+npm run build
+node src/main.mjs --help
+node src/main.mjs --version
+```
+
+The current `build` script validates the syntax of the `.mjs` source files. It
+does not generate a standalone executable.
+
+### Test the update flow locally
+
+The manual update test mocks the registry and install operation, so it does not
+publish a package or change the installed version:
+
+```powershell
+$env:REQUESTSHIELD_MOCK_LATEST_VERSION = "0.1.6"
+npm run test:update-check:manual
+Remove-Item Env:REQUESTSHIELD_MOCK_LATEST_VERSION
+```
+
+After entering `y`, the test prints `[MOCK] Would install ...`.
+
+## Packaging the RequestShield Skill
+
+The canonical Skill is stored at `../skills/requestshield`. Do not maintain a
+second source copy inside this package.
+
+Before npm creates the package, the `prepack` hook temporarily copies the
+canonical Skill to `skills/requestshield`. The `postpack` hook removes that
+generated copy after packaging.
+
+Inspect the files that npm will publish:
+
+```console
+npm pack --dry-run
+```
+
+Create a local tarball:
+
+```console
+npm pack
+```
+
+## Publish to npm
+
+npm does not allow an existing package version to be overwritten. Check the
+published version, merge the latest team changes, then choose a new version in
+`package.json` before publishing.
+
+```console
+npm view @intellifend/requestshield version
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+npm publish --access public
+```
 
-`agent setup` detects Codex or Claude and installs the bundled `requestshield`
-skill into `~/.agents/skills` for Codex or `~/.claude/skills` for Claude. Use
-`--codex` or `--claude` to select one directly. When both agents are detected,
-an interactive terminal asks which one to use; non-interactive callers must
-provide one of the flags. Existing content is preserved unless `--force` is
-supplied.
+Verify the published package:
+
+```console
+npm view @intellifend/requestshield version
+npm dist-tag ls @intellifend/requestshield
+npx --yes --package=@intellifend/requestshield@0.1.5 requestshield --version
+```
 
 ## Management API contract
 
@@ -51,8 +298,8 @@ supplied.
 }
 ```
 
-The response contains `deviceCode`, `userCode`, `verificationUri`,
-`expiresIn`, and `interval`.
+The response contains `deviceCode`, `userCode`, `verificationUri`, `expiresIn`,
+and `interval`.
 
 ### Poll sign-in
 
@@ -65,63 +312,133 @@ metadata.
 ### Rotate keys
 
 `POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
-The response contains `appKey` and one-time `apiSecret`.
+The response contains `appKey` and the one-time `apiSecret`.
 
-## Development
+### List applications
 
-```console
-pnpm --filter requestshield lint
-pnpm --filter requestshield typecheck
-pnpm --filter requestshield test
-pnpm --filter requestshield build
+`GET /v1/applications` with Bearer authentication and no request body. The API must
+scope results to the authenticated user.
+
+```json
+{
+  "data": [
+    {
+      "appKey": "pk_AAAAAAAAAAAAAAAAAAAAAAAA",
+      "name": "Checkout",
+      "status": "pending",
+      "createdAt": "2026-09-11T00:00:00.000Z",
+      "updatedAt": "2026-09-11T00:00:00.000Z"
+    }
+  ],
+  "nextCursor": null
+}
 ```
-## Quick start
 
-RequestShield requires Node.js 22.13 or newer.
+Every application requires `appKey`, `name`, `status`, `createdAt`, and `updatedAt`.
+`nextCursor` must be a non-empty string or `null`. An account with no applications
+returns `200` with an empty `data` array. A missing or rejected session returns
+`401`. The response must never contain an API Secret.
 
-Run without installing globally:
+### Get an application
 
-```console
-npx requestshield --help
-npx requestshield signin
-npx requestshield keys create
-npx requestshield agent setup
-npx requestshield agent setup --codex
-npx requestshield agent setup --claude
+`GET /v1/applications/{appKey}` with Bearer authentication and no request body.
+The path segment is URL-encoded by the CLI.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "app_key": "app_123",
+    "name": "Website",
+    "status": "active"
+  }
+}
 ```
 
-Pin a specific version for reproducible usage:
+`status` must be `ready`, `active`, or `deactivated`. The response App Key must
+match the requested key. The CLI rebuilds the output from these three fields so
+unexpected response fields cannot be printed.
 
-```console
-npx requestshield@0.1.0 --help
+### Get challenge volume
+
+`GET /v1/applications/{appKey}/challenge-volume` with Bearer authentication and
+optional `from`, `to`, and `granularity` query parameters.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "app_key": "app_123",
+    "from": "2026-08-01T00:00:00Z",
+    "to": "2026-08-27T23:59:59Z",
+    "granularity": "day",
+    "challenge_count": 125430
+  }
+}
 ```
 
-## Packaging the bundled skill
+The CLI requires a matching App Key, valid ordered timestamps, a non-empty
+granularity, and a non-negative safe-integer `challenge_count`. It rebuilds the
+output from these fields so unexpected API fields cannot be printed.
 
-The canonical RequestShield skill lives at `../skills/requestshield`, outside
-this npm package directory. The `prepack` hook temporarily copies the complete
-skill into `skills/requestshield`, and `postpack` removes that generated copy
-after npm creates the tarball. Do not edit the generated copy.
+### Get billing information
 
-Build and inspect a local package from this directory:
+`GET /v1/applications/{appKey}/billing` with Bearer authentication and no
+request body.
 
-```console
-npm test
-npm run typecheck
-npm run lint
-npm pack --dry-run
+```json
+{
+  "ok": true,
+  "data": {
+    "plan": {
+      "tier": "pro",
+      "current_cycle": [
+        "2026-07-07T07:07:07",
+        "2027-07-07T07:07:07"
+      ],
+      "billing": 1080,
+      "next_charge": "2027-07-07T07:07:07"
+    },
+    "usage": {
+      "monthly_quota": 100000,
+      "current_usage": 110000,
+      "overage_charge": 10
+    }
+  }
+}
 ```
 
-To exercise the package entry point and bundled skill, create a tarball and run
-the command through that tarball:
+The CLI validates all documented fields and rebuilds the nested result so
+unexpected response fields cannot be printed.
 
-```console
-npm pack
-npx --yes --package=./requestshield-0.1.0.tgz requestshield agent setup --codex
-```
+### Get the integration contract
 
-To automatically accept npm's installation prompt:
+`GET /v1/integration-contract` with Bearer authentication and no request body.
 
-```console
-npx --yes requestshield@0.1.0 --help
+```json
+{
+  "ok": true,
+  "data": {
+    "contract_version": "2026-08-27",
+    "browser": {
+      "script_url": "https://intellifend.ai/intellifend.js",
+      "token_header": "X-IntelliFend-Token",
+      "available_modes": ["manual"]
+    },
+    "backend": {
+      "supported_languages": ["java"],
+      "min_jdk": 17
+    },
+    "release_state": "released"
+  }
+}
 ```
+
+The CLI requires these core fields and preserves additional authoritative
+contract fields returned by the API. Credential-shaped fields are rejected.
+
+## Security notes
+
+- Never place an access token or Secret Key in URLs, command arguments, logs,
+  test fixtures, or committed files.
+- The CLI does not persist the Secret Key returned by `keys create`.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "requestshield",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Customer CLI for IntelliFend RequestShield.",
   "type": "module",
   "bin": {
     "requestshield": "src/main.mjs"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "src/",
     "skills/",
@@ -18,6 +21,7 @@
     "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",
     "prepack": "node scripts/package-skill.mjs stage",
     "postpack": "node scripts/package-skill.mjs clean",

package/skills/requestshield/SKILL.md

@@ -57,7 +57,7 @@ single CLI call or a short answer. Match on what the user wants, not on exact wo
 | **Uninstall** | "remove it", "roll it back" | `references/integration-planning.md` (Detect existing integration only) → **Uninstalling**. |
 | **Verify / troubleshoot** | "is it set up right?", "why is it not blocking?", a reason code | `references/integration-planning.md` (Detect existing integration only) → **Verifying**. For a reason code, also read `references/troubleshooting.md`. |
 | **Challenge volume** | "how much traffic", "how many challenges", "show me the volume" | Ask for the time range first. `challenge volume` takes `--from`/`--to`/`--granularity`; a guessed window produces a confident wrong answer. Then run it with the App Key. |
-| **Billing** | "am I being charged", "what plan", "what are my limits" | `requestshield get billing`. |
+| **Billing** | "am I being charged", "what plan", "what are my limits" | Resolve the application, then run `requestshield get billing <app-key>`. |
 | **Service health** | "is the service up", "is it degraded" | `requestshield server`. |
 | **Agent setup** | "set this up for Codex too", "install the skill for Claude" | Run `requestshield agent setup` for auto-detection, or pass the requested agent: `--agent codex` or `--agent claude`. This installs agent guidance; it does not mint keys or edit customer application code. |
 | **Anything else** | | Look the command up in `references/cli.md`. If it is not there, run `requestshield --help` rather than guessing at a flag. |

package/skills/requestshield/references/cli.md

@@ -120,10 +120,11 @@ requestshield apps get <app-key>
 ```
 
 **auth.** `apps list` returns the applications the current user can access, each with
-`app_key`, `name`, and `status`. Use it to resolve a human-supplied app name to a key
-rather than asking the user to retype one.
+`appKey`, `name`, `status`, `createdAt`, and `updatedAt`; JSON output also includes
+`nextCursor`. Use it to resolve a human-supplied app name to a key rather than asking
+the user to retype one.
 
-`apps get <app-key>` returns `app_id`, `app_name`, and `status`. Status distinguishes a
+`apps get <app-key>` returns `app_key`, `name`, and `status`. Status distinguishes a
 key that has never seen traffic (`ready`) from one in normal service (`active`) — which
 is exactly the difference between "the integration is not wired up yet" and "it is
 working", so check it before spending time debugging code.
@@ -161,11 +162,11 @@ mode's reference file.
 ## Billing
 
 ```bash
-requestshield get billing
+requestshield get billing <app-key>
 ```
 
-**auth.** Current plan and usage for the application. Read-only; surface it when the
-user asks about cost or limits.
+**auth.** Current plan and usage for the explicitly selected application. Read-only;
+surface it when the user asks about cost or limits.
 
 ## Agent integration
 

package/src/agent-detector.mjs

@@ -12,9 +12,21 @@ import path from "node:path";
  * @returns {Promise<Array<"codex" | "claude">>}
  */
 export async function detectAgents(options = {}) {
-  const env = options.env ?? process.env;
-  const homeDir = options.homeDir ?? os.homedir();
-  const codexHome = env.CODEX_HOME ?? path.join(homeDir, ".codex");
+
+  const env = options.env ??
+    process.env;
+
+  const homeDir = options.homeDir ??
+    os.homedir();
+
+  const codexHome = env.CODEX_HOME ??
+    path.join(homeDir, ".codex");
+
+  const codexConfigPath =
+    path.join(codexHome, "config.toml");
+
+  const claudeConfigPath =
+    path.join(homeDir, ".claude.json");
 
   // Executables prove the CLI is on PATH. Configuration files cover desktop
   // installs and agents that were previously configured but are not on PATH.
@@ -29,8 +41,14 @@ export async function detectAgents(options = {}) {
 
   /** @type {Array<"codex" | "claude">} */
   const detected = [];
-  if (codexCommand || codexConfig) detected.push("codex");
-  if (claudeCommand || claudeConfig || claudeState) detected.push("claude");
+
+  if (codexCommand || codexConfig) {
+    detected.push("codex")
+  };
+
+  if (claudeCommand || claudeConfig || claudeState) {
+    detected.push("claude")
+  };
   return detected;
 }
 
@@ -41,19 +59,29 @@ export async function detectAgents(options = {}) {
  * @param {NodeJS.ProcessEnv} env
  */
 async function commandExists(command, env) {
-  const searchPath = env.PATH ?? env.Path ?? "";
-  const extensions = process.platform === "win32"
-    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+
+  const searchPath = env.PATH ??
+    env.Path ?? "";
+
+  const extensions =
+    process.platform === "win32"
+      ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+        .split(";")
+        .filter(Boolean)
     : [""];
 
   for (const directory of searchPath.split(path.delimiter)) {
-    if (!directory) continue;
+    if (!directory) {
+      continue
+    };
+
     for (const extension of extensions) {
       try {
         await access(
           path.join(directory, `${command}${extension}`),
           process.platform === "win32" ? constants.F_OK : constants.X_OK,
         );
+
         return true;
       } catch {
         // Continue through the remaining executable candidates.