requestshield 0.1.3 → 0.1.4

package/README.md

@@ -1,127 +1,246 @@
 # 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.4`.
 
 ## 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 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`. Set
+`REQUESTSHIELD_API_URL` to use a different management API during development.
 
-## Commands
+## Implemented commands
 
 ```console
 requestshield signin
+requestshield keys create [--yes]
+requestshield agent setup [--force]
+requestshield agent setup --codex [--force]
+requestshield agent setup --claude [--force]
+requestshield update check
+requestshield --help
+requestshield --version
+```
+
+### 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.
+
+### 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:
 
-`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.
+- Codex: `~/.agents/skills/requestshield`
+- Claude: `~/.claude/skills/requestshield`
 
-`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.
+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`.
 
-## Management API contract
+Existing Skill content is preserved. Add `--force` to replace it:
 
-### Start sign-in
+```console
+requestshield agent setup --codex --force
+```
 
-`POST /v1/cli/signin`
+Restart the selected agent or start a new task after installation.
 
-```json
-{
-  "client": "requestshield-cli"
-}
+### Check for updates
+
+```console
+requestshield update check
 ```
 
-The response contains `deviceCode`, `userCode`, `verificationUri`,
-`expiresIn`, and `interval`.
+Checks the npm registry for the latest `requestshield` version. When a newer
+version exists, the CLI displays the current and latest versions and asks:
 
-### Poll sign-in
+```text
+Update to RequestShield <version>? (y/N):
+```
 
-`POST /v1/cli/signin/token` with `{ "deviceCode": "..." }`.
+Entering `y` runs the equivalent of:
 
-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@<latest-version>
+```
 
-### Rotate keys
+This command requires an interactive terminal, Node.js, and npm. It updates a
+global npm installation; it does not replace a standalone Windows executable.
 
-`POST /v1/cli/keys/rotate` with Bearer authentication and an empty JSON body.
-The response contains `appKey` and one-time `apiSecret`.
+## Install with npm
 
-## Development
+Install globally:
 
 ```console
-pnpm --filter requestshield lint
-pnpm --filter requestshield typecheck
-pnpm --filter requestshield test
-pnpm --filter requestshield build
+npm install --global requestshield
+requestshield --help
+requestshield --version
 ```
-## Quick start
-
-RequestShield requires Node.js 22.13 or newer.
 
-Run without installing globally:
+Run a specific version without installing globally:
 
 ```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
+npx --yes requestshield@0.1.4 --help
+npx --yes requestshield@0.1.4 signin
 ```
 
-Pin a specific version for reproducible usage:
+To invoke the update command through npx, include the package name:
 
 ```console
-npx requestshield@0.1.0 --help
+npx --yes requestshield@0.1.4 update check
 ```
 
-## Packaging the bundled skill
+Do not run `npx update check`; npm interprets `update` as the name of a different
+npm package.
 
-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.
+## Local development
 
-Build and inspect a local package from this directory:
+From the `requestshield-cli` directory:
 
 ```console
-npm test
-npm run typecheck
+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.5"
+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
 ```
 
-To exercise the package entry point and bundled skill, create a tarball and run
-the command through that tarball:
+Create a local tarball:
 
 ```console
 npm pack
-npx --yes --package=./requestshield-0.1.0.tgz requestshield agent setup --codex
 ```
 
-To automatically accept npm's installation prompt:
+## 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 requestshield version
+npm run lint
+npm run typecheck
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+Verify the published package:
 
 ```console
-npx --yes requestshield@0.1.0 --help
+npm view requestshield version
+npm dist-tag ls requestshield
+npx --yes requestshield@0.1.4 --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,
+  test fixtures, or committed files.
+- The CLI does not persist the Secret Key returned by `keys create`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "requestshield",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Customer CLI for IntelliFend RequestShield.",
   "type": "module",
   "bin": {
@@ -14,20 +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",
-    "prepack": "node scripts/package-skill.mjs stage",
-    "postpack": "node scripts/package-skill.mjs clean",
-    "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"
+  }
+}