@vigilbase/cli 0.1.3 → 0.2.0

package/CLOUDFLARE.md

@@ -2,6 +2,8 @@
 
 `vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first. Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
 
+`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup` (also shown at https://vigilbase.com/tools/cloudflare-checkup?mode=local), verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm (see [LOCAL.md](./LOCAL.md)).
+
 Customer provider access requires an `active` or `trialing` Cloudflare service
 entitlement for the selected account. Historical/inactive rows and legacy account
 pointers cannot grant live access. Historical restrictions on the same customer

package/COMMANDS.md

@@ -12,6 +12,7 @@ The CLI uses public scanner APIs on `vigilbase.com` and authenticated APIs on
 | Cloudflare | [CLOUDFLARE.md](./CLOUDFLARE.md) |
 | Security | [SECURITY.md](./SECURITY.md) |
 | Customers, organizations, monitoring, support | [ONE.md](./ONE.md) |
+| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](./LOCAL.md) |
 | Authentication, setup, network troubleshooting | [README.md](./README.md) |
 
 The references identify supported operations, filters, response/pagination
@@ -26,6 +27,7 @@ supported API surface, not every internal endpoint in the monorepo.
 | `--help`, `-h` | Help for the named command; makes no API request |
 | `--version`, `-V` | Package version |
 | `--one-url <origin>` | One origin; default `https://one.vigilbase.com` |
+| `--auth-url <origin>` | Explicit registered issuer or loopback development issuer; One discovery chooses the active provider |
 | `--base-url <origin>` | Public origin; default `https://vigilbase.com` |
 | `--timeout <ms>` | Per-request timeout, integer 1–2147483647; default 60000 |
 | `--client-id <id>` | Device authorization client; default `vigilbase-cli` |
@@ -41,15 +43,16 @@ signed-in role lacks access. Unknown flags, unsupported command-specific flags
 
 | Command | Options and behavior | One API |
 | --- | --- | --- |
-| `login` | Device authorization; `--no-open` for remote terminals | POST `/api/auth/device/code`, POST `/api/auth/device/token` |
+| `login` | Device authorization; `--no-open` for remote terminals | One protected-resource discovery; legacy device endpoints or Identity device code + form token exchange |
 | `login --token-stdin` | Validate and save a token piped from a secret manager; input is bounded and never echoed | GET `/api/auth/get-session` |
 | `login --token <bearer>` | Legacy input; discouraged because arguments can appear in process lists/history. `VIGILBASE_ONE_TOKEN` is also supported; neither combines with `--token-stdin` | GET `/api/auth/get-session` |
-| `whoami` | Verify the saved session; signed-out is a successful status query | GET `/api/auth/get-session` when a usable token exists |
-| `logout` | Remove local credentials; does not revoke the server session | Local only |
+| `whoami` | Verify the saved session; signed-out is a successful status query | Legacy session or Identity userinfo when a usable grant exists |
+| `logout` | Revoke Identity refresh grant, then remove local credentials; legacy logout stays local | Identity revocation, when using v2 credentials |
 | `doctor` | Independently check public catalog and One session connectivity | GET `/api/agent/tools`, GET `/api/auth/get-session` |
 
 Tokens are saved atomically with owner-only file permissions and tied to their
-issuing One origin. See README for config directory overrides and certificate
+issuing One origin and, for Identity grants, issuer/client/resource. Rotating
+refresh tokens are coordinated across CLI processes. See README for config directory overrides and certificate
 trust. Login polling handles pending approval, denial, expiry, and transient
 transport failures. Access tokens are never included in successful CLI output.
 
@@ -109,6 +112,31 @@ output, printing, or opening; Windows requires manual opening.
 
 Customer-specific Watchdog and monitoring views are documented in ONE.md.
 
+## Local Cloudflare Checkup (no login)
+
+| Command | Options | Requests |
+| --- | --- | --- |
+| `cloudflare-checkup` (≡ `local cloudflare-checkup [run]`) | `--email`, `--account-id`, `--out`, `--overwrite`, `--yes`, `--confirm`, `--no-open`, `--cf-auth auto\|profile\|env\|default` (default `auto`), `--profile`, `--cf-bin`, `--max-requests-per-5min`, `--base-url` (vigilbase.com or loopback), `--timeout` | POST `/api/v1/tools/cloudflare-checkup/local-session/request` and `…/verify` (email verification), GET `…/local-session` (before cf runs and again before the upload), allowlisted read-only cf commands, POST `…/local-session/snapshot` after an explicit confirmation; npm only to install the pinned cf when none is usable (asks first) |
+| `cloudflare-checkup login` | `--profile`, `--no-open`, `--dry-run`, `--cf-bin` | Runs `cf auth create <profile> --scopes …` interactively |
+| `cloudflare-checkup doctor` | `--cf-auth`, `--profile`, `--cf-bin` | Offline cf mapping check, one `cf auth whoami` |
+| `cloudflare-checkup accounts` | `--cf-auth`, `--profile`, `--cf-bin` | `cf accounts list` (all pages) |
+| `cloudflare-checkup collect` | `--out` (required), `--account-id`, `--overwrite`, `--dry-run`, `--max-requests-per-5min`, cf options | Allowlisted read-only cf commands; writes the snapshot |
+| `cloudflare-checkup inspect <file>` | — | None |
+| `cloudflare-checkup submit <file>` | `--email`, `--yes`/`--confirm`, `--no-open`, `--base-url`, `--timeout` | POST `…/local-session/request` and `…/verify`, GET `…/local-session`, POST `…/local-session/snapshot` |
+| `cloudflare-checkup logout` | `--profile`, `--cf-bin` | Runs `cf auth delete <profile>` interactively, then removes the cf Vigilbase installed |
+
+Each subcommand also works as `local cloudflare-checkup <subcommand>`. The one
+command and `submit` verify your work email first: the CLI asks for it (or
+takes `--email`), vigilbase.com emails a 6-digit code, and the CLI asks for the
+code (without a terminal, both are read from stdin, one line each; add
+`--yes`). In a terminal both show an interactive timeline on stderr (inputs,
+arrow-key questions, spinners, a collection progress bar); pipes, CI,
+`TERM=dumb` and `--json` keep the plain lines and prompts. Ctrl-C exits 130. The address, the code and the session code are never echoed, logged,
+stored or passed to cf or npm. cf output and stderr are never echoed; failures
+carry a stable `code` and `hint` that point at running the same command again.
+See [LOCAL.md](./LOCAL.md) for the email verification, the managed cf install,
+the allowlist, environment policy, uploaded data and error codes.
+
 ## Output, effects, and testing
 
 Exit codes: **0** success, **1** validation/API/network failure, **2** HTTP 429
@@ -124,7 +152,14 @@ JSON for automation and evidence export.
 
 Provider credentials, signed delegation claims, internal bearer tokens, and
 organization-authority overrides are never CLI inputs. New commands use named
-One routes. Webhooks, cron/admin repair endpoints, interactive OAuth handoffs,
+One routes. Exceptions: local provider reads and the two named vigilbase.com
+local-session routes. `vigilbase cloudflare-checkup` runs Cloudflare's own
+`cf` CLI on your machine with a fixed allowlist of read-only commands; cf owns
+your Cloudflare login, and the Vigilbase CLI never reads, prints, stores or
+uploads it. Its only Vigilbase requests are `GET /api/v1/tools/cloudflare-checkup/local-session`
+and, after you confirm, `POST /api/v1/tools/cloudflare-checkup/local-session/snapshot`
+with the exact snapshot file, authorised by the code the page minted for your
+verified email (see [LOCAL.md](./LOCAL.md)). Webhooks, cron/admin repair endpoints, interactive OAuth handoffs,
 streaming/binary downloads, and endpoints that auto-provision on GET are outside
 this expansion. Remediation effects requiring durable approval/receipt workflows
 remain in their existing supported One/Vigil flows.
@@ -132,7 +167,9 @@ remain in their existing supported One/Vigil flows.
 ```bash
 pnpm --filter @vigilbase/cli check
 # Includes typecheck, unit tests, production build, login lifecycle smoke,
-# and every fixture-listed command over HTTP in both JSON and text modes.
+# every fixture-listed command over HTTP in both JSON and text modes, and the
+# local checkup smoke (fake cf on a restricted PATH, a fake npm for the managed
+# cf install, loopback local-session routes).
 
 VIGILBASE_BASE_URL=https://vigilbase.com \
   VIGILBASE_SMOKE_ARTIFACTS="$PWD/.context/cli-live-smoke" \