@vigilbase/cli 0.2.0 → 0.2.1

package/LOCAL.md

@@ -1,50 +1,66 @@
 # Local Cloudflare Checkup reference
 
-The local mode of <https://vigilbase.com/tools/cloudflare-checkup?mode=local>
-collects your Cloudflare configuration **on your own machine** with
+`vigilbase cloudflare-checkup` runs the Vigilbase Cloudflare Checkup in local
+mode: it collects your Cloudflare configuration **on your own machine** with
 Cloudflare's own CLI, `cf`, writes a minimised snapshot you can inspect, and
 uploads exactly that file to vigilbase.com after you confirm. vigilbase.com
-evaluates it with the same scanner as the browser token mode. Results are
-labelled **self-reported**; they go to your verified work email, and the
-results page opens in your browser.
+evaluates it with the same scanner as the checkup in your browser, which uses a
+read-only Cloudflare API token instead. Results are labelled **self-reported**;
+they go to your verified work email, and the results page opens in your
+browser.
+
+Local mode is available while vigilbase.com has it switched on. The CLI checks
+before it asks for your email; when local mode is off it stops with
+`Local checkups aren't available right now.` and points you to the checkup in
+your browser at <https://vigilbase.com/tools/cloudflare-checkup>.
 
 `vigilbase cf checkup` runs on Vigilbase One's servers with stored credentials
-(see [CLOUDFLARE.md](./CLOUDFLARE.md)); `vigilbase cloudflare-checkup` runs on
-your machine and needs no Vigilbase login.
+(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md));
+`vigilbase cloudflare-checkup` runs on your machine and needs no Vigilbase
+login.
 
 ## Quick start: one command
 
-Run this in a terminal (the checkup page shows the same command):
+Run this in a terminal (while local mode is on, the checkup page at
+<https://vigilbase.com/tools/cloudflare-checkup> shows the same command):
 
 ```bash
 npx @vigilbase/cli cloudflare-checkup
 ```
 
+If it answers `Unknown command "cloudflare-checkup"`, an older global install
+of the CLI (0.1.x) is running instead: `npx` prefers an installed global
+`@vigilbase/cli`. Run `npx @vigilbase/cli@latest cloudflare-checkup` once, or
+update the global install with `npm install -g @vigilbase/cli@latest`.
+
 The command does everything, in this order, and stops at the first problem
 before any slower step:
 
 1. Checks Node.js (22.18 or newer; macOS, Linux or Windows x64).
-2. Asks for your work email (`Work email for your results:`), and
+2. Asks vigilbase.com whether local checkups are available and accept this CLI
+   version (nothing about you is sent). If not, it stops here, before asking
+   for your email.
+3. Asks for your work email (`Work email for your results:`), and
    vigilbase.com emails you a 6-digit code. You enter it at
    `Code from the email:` (`123456`, `123 456` and `123-456` all work), and
    the CLI prints `✓ Verified j***@acme.com`.
-3. Finds Cloudflare's `cf`. If none is usable (including a newer cf that
+4. Finds Cloudflare's `cf`. If none is usable (including a newer cf that
    renamed a command the checkup needs), it offers to install the tested
    release for Vigilbase (asks first; `--yes` answers for you). Your own cf is
    left alone.
-4. Signs in to Cloudflare with a **read-only** cf login (your browser opens) if
+5. Signs in to Cloudflare with a **read-only** cf login (your browser opens) if
    the cf profile `vigilbase-checkup` is missing or expired. With
    `CLOUDFLARE_API_TOKEN` set in the shell, cf uses that token instead and the
    browser sign-in is not offered: unset the variable, or add
    `--cf-auth profile`, to sign in with your browser.
-5. Lets you choose the account (one account is used as is; several get a
+6. Lets you choose the account (one account is used as is; several get a
    list to choose from).
-6. Collects with read-only cf commands, at most 900 requests per 5 minutes.
-7. Saves the snapshot to `~/.config/vigilbase/checkups/…` (mode 0600) and
+7. Collects with read-only cf commands, at most 900 requests per 5 minutes.
+8. Saves the snapshot to `~/.config/vigilbase/checkups/…` (mode 0600) and
    shows what it contains.
-8. Asks `Results go to j***@acme.com. Upload 182 KB to https://vigilbase.com? [y/N]`
+9. Asks `Results go to j***@acme.com. Upload 182 KB to https://vigilbase.com? [y/N]`
    and uploads exactly that file only after an explicit `y`.
-9. Prints the results link and opens it in your browser.
+10. Prints the results link and opens it in your browser.
 
 In a terminal, the steps show as an interactive timeline (see
 [Terminal UI and plain output](#terminal-ui-and-plain-output)):
@@ -137,12 +153,13 @@ and `vigilbase local cloudflare-checkup run` are the same command.
 | `--json` | One JSON object on stdout; status lines and prompts go to stderr. |
 
 Before anything slow, the command checks every flag (no I/O, and `--email`
-only for its shape), then Node, then that its questions can be answered: on a
-terminal, or with `--yes` without one (`--confirm` answers only the upload
-question, not installing cf), so no code is emailed for a run that could not
-install cf or confirm the upload. It verifies your email before cf runs, and
-checks that the snapshot location is writable before collecting, so a long
-collection is never wasted.
+only for its shape), that its questions can be answered (on a terminal, or
+with `--yes` without one; `--confirm` answers only the upload question, not
+installing cf), then Node, then that `--out` is writable, then that
+vigilbase.com has local checkups on and accepts this CLI. So no code is emailed
+for a run that could not install cf, confirm the upload or be accepted. It
+verifies your email before cf runs, and checks that the snapshot location is
+writable before collecting, so a long collection is never wasted.
 
 Two problems can show only once cf runs, after the email was verified: without
 a terminal, a missing cf login (`CF_AUTH_REQUIRED`) and several accounts
@@ -164,9 +181,10 @@ never answered from stdin: use `--account-id` and `--yes`.
 
 In a terminal, the one command and `submit` show their steps as a timeline on
 stderr (◆ the current step, ◇ a finished one, │ notes, ▲ a warning, ■ the error
-that stopped the run, └ the result). Spinners run while vigilbase.com sends or
-checks the code, while the session is checked, while cf is found, checked and
-installed, and while the upload is scored; a progress bar runs while
+that stopped the run, └ the result). Spinners run while the CLI checks that
+local checkups are available, while vigilbase.com sends or checks the code,
+while the session is checked, while cf is found, checked and installed, and
+while the upload is scored; a progress bar runs while
 collecting (zones done, cf reads done of the estimate, and the time left, from
 the request budget and the pace so far). Everything is redrawn in place and fits
 the terminal width, also after a resize.
@@ -225,6 +243,17 @@ between the items of a summary line, in every step, spinner and message.
 The CLI verifies your email itself; there is no browser step and no bot check
 on this path.
 
+- **Availability first.** Before asking for your email, the one command and
+  `submit` send `GET …/local-session/availability`, with no email, no
+  credentials and no body. If local checkups are switched off, the command
+  stops with `LOCAL_MODE_DISABLED`: `Local checkups aren't available right now.`
+  and the hint
+  `Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup`.
+  Nothing is emailed and cf is not touched. If vigilbase.com needs a newer CLI
+  or doesn't accept this snapshot format, it stops with `CLI_UPGRADE_REQUIRED`.
+  If vigilbase.com doesn't answer the check (for example a network error or a
+  timeout, after 10 seconds or `--timeout`), the command goes on, and the same
+  checks happen when the checkup starts.
 - **What vigilbase.com receives.** Your email address goes to vigilbase.com
   (`POST …/local-session/request`) so it can send you the code, together with
   the email language (`en`, `pt-PT` or `ar`, from `LC_ALL`, `LC_MESSAGES` or
@@ -276,9 +305,10 @@ removed from npm's environment when the CLI installs cf.)
   stores, inspects or uploads it.
 - **The only Vigilbase requests** go to
   `https://vigilbase.com/api/v1/tools/cloudflare-checkup/local-session`:
-  `POST …/request` and `POST …/verify` (the email verification, JSON bodies,
-  no credential), then `GET` of the session and `POST …/snapshot`, authorised
-  by the session code the verification returned. The upload is the exact bytes
+  `GET …/availability` (no body, no credential), `POST …/request` and
+  `POST …/verify` (the email verification, JSON bodies, no credential), then
+  `GET` of the session and `POST …/snapshot`, authorised by the session code
+  the verification returned. The upload is the exact bytes
   of the file you can inspect; the CLI re-reads and re-hashes it and checks the
   server's echoed SHA-256.
 - **Installing cf** contacts only the npm registry your npm is configured for,
@@ -379,7 +409,8 @@ The snapshot is kept whatever happens to the upload: when it cannot go ahead
 (`SESSION_*`, `VERIFICATION_*`, `SUBMIT_FAILED`, `VIGILBASE_*`,
 `LOCAL_MODE_DISABLED`), the command prints, next to the error,
 `npx @vigilbase/cli cloudflare-checkup submit <saved file>` to upload it
-later without collecting again (it verifies your email again).
+later without collecting again (it verifies your email again). When the run
+used a loopback `--base-url`, that command ends with the same `--base-url`.
 
 ## Advanced commands
 
@@ -399,9 +430,10 @@ All are `vigilbase cloudflare-checkup <command>` or
 the one command. `collect --dry-run` prints every cf command with
 `<ZONE_ID>`/`<RULESET_ID>` placeholders, the child-environment variable names
 (never values), the not-collected list and the request formula; it makes no
-Cloudflare and no Vigilbase requests. `submit` checks the file, verifies your
-email like the one command, then uploads a snapshot collected earlier
-(accepted for 24 hours) and prints the results link.
+Cloudflare and no Vigilbase requests. `submit` checks the file, checks that
+vigilbase.com has local checkups on, verifies your email like the one command,
+then uploads a snapshot collected earlier (accepted for 24 hours) and prints
+the results link.
 
 `logout` runs `cf auth delete <profile>` through the cf it finds (an
 interactive passthrough, so cf's own message is shown; cf 1.0.0-beta.13 takes
@@ -543,8 +575,8 @@ before every expiry in a long run.
 
 ## Scopes
 
-The sign-in (and `login`) requests these read scopes (names verified against cf 1.0.0-beta.13;
-whether they suffice for every read is confirmed before launch):
+The sign-in (and `login`) requests these read scopes (names verified against
+cf 1.0.0-beta.13):
 
 `account:read account-settings.read memberships.read user:read user-details.read
 zone:read zone.read zone-settings.read dns.read dns_records:read
@@ -639,11 +671,11 @@ are never echoed.
 | `CF_ERROR` | Run the same command again in a few minutes. |
 | `ACCOUNT_SELECTION_REQUIRED` | Run the same command again in a terminal to choose, or add `--account-id <ACCOUNT_ID>` (listed in the error). |
 | `ACCOUNT_NOT_VISIBLE` | Check that your Cloudflare user can read the account and its zones. |
-| `ACCOUNT_TOO_LARGE` | Over 100 zones: use the browser token mode. |
+| `ACCOUNT_TOO_LARGE` | Over 100 zones: run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
 | `ACCOUNT_MISMATCH` | The checkup is bound to another account; run the same command again without `--account-id`. |
 | `OUTPUT_EXISTS` | Choose another `--out`, or pass `--overwrite`. |
 | `SNAPSHOT_INVALID` / `SNAPSHOT_SECRET_LIKE_VALUE` | Run the same command again (remove the credential-like text from the rule or name first). |
-| `SNAPSHOT_TOO_LARGE` | Use the browser token mode. |
+| `SNAPSHOT_TOO_LARGE` | Run the checkup in your browser instead, https://vigilbase.com/tools/cloudflare-checkup. |
 | `SNAPSHOT_STALE` | Snapshots are accepted for 24 hours; run the same command again. |
 | `EMAIL_INVALID` | Use your work email (personal and disposable addresses are refused), then run the same command again. |
 | `EMAIL_CODE_INVALID` | Five codes were wrong or not 6 digits; run the same command again for a new code. |
@@ -653,8 +685,8 @@ are never echoed.
 | `SESSION_BUSY` | A snapshot for this checkup is still being processed; wait for the results email, or run the same command again. |
 | `SUBMIT_ORIGIN_UNTRUSTED` | Upload only to https://vigilbase.com (or loopback for testing). |
 | `CONFIRMATION_REQUIRED` | Run the command in a terminal, or add `--yes` (and, without `--email`, pipe the address and the code to stdin). |
-| `CLI_UPGRADE_REQUIRED` | Run `npx @vigilbase/cli@latest cloudflare-checkup`, or `npm install --global @vigilbase/cli@latest`. |
-| `LOCAL_MODE_DISABLED` | Use the browser token mode, or try later. |
+| `CLI_UPGRADE_REQUIRED` | vigilbase.com needs a newer CLI (checked before your email is asked for). Run `npx @vigilbase/cli@latest cloudflare-checkup`, or `npm install --global @vigilbase/cli@latest`. |
+| `LOCAL_MODE_DISABLED` | Local checkups aren't available right now. Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup. |
 | `VIGILBASE_RATE_LIMITED` | Wait as long as the error says (`retryAfterSec` in JSON), then run the same command again. |
 | `VIGILBASE_CHALLENGED` | vigilbase.com challenged the request; try another network or contact help@vigilbase.com. |
 | `SUBMIT_FAILED` | Run the same command again later. |
@@ -676,9 +708,9 @@ Windows x64 is supported as beta without CI coverage: cf runs via
 `process.execPath` with the entry beside `cf.cmd` (npm's global layout), never
 through `cmd.exe`; and the managed install uses the `npm-cli.js` beside
 `node.exe`. The results page is not opened on Windows (the link is printed).
-Windows on ARM is not supported. pnpm and
-Volta global installs are found automatically; otherwise pass `--cf-bin` as
-above.
+Windows on ARM is not supported. The checkup needs no Vigilbase sign-in, so it
+works on Windows even though `vigilbase login` doesn't yet. pnpm and Volta
+global installs are found automatically; otherwise pass `--cf-bin` as above.
 
 ## Cleanup
 
@@ -687,45 +719,3 @@ npx @vigilbase/cli cloudflare-checkup logout   # cf auth delete vigilbase-checku
 rm ~/.config/vigilbase/checkups/cloudflare-checkup-*.json   # the snapshots are yours; delete them when done
 ```
 
-## Test it locally (contributors)
-
-From a checkout of the monorepo, one command runs the whole flow on your
-machine: vigilbase.com (`next dev`, local mode on), an in-memory fake of One's
-tool-runs API, and this CLI built from source.
-
-```bash
-pnpm dev:checkup-local             # your own cf: sign in to your Cloudflare account (read-only)
-pnpm dev:checkup-local --fake-cf   # a fake cf with two accounts: no Cloudflare account needed
-pnpm dev:checkup-local --help      # every option
-```
-
-It needs Node 22.18+ (it finds Homebrew's or nvm's Node 22 when the shell has
-another version) and an Infisical login for the dev environment
-(`infisical login`). It builds the CLI when `packages/cli/dist` is older than
-`src`, starts com on port 3011 (or the next free one) with the Infisical dev
-values overridden for local mode, and runs the CLI against
-`http://localhost:<port>`. Server output goes to a log, never the terminal.
-
-- **Email** is never sent. Each message lands in a local inbox
-  (`$TMPDIR/vigilbase-checkup-local/inbox/`) and verification emails open in
-  your browser like a real inbox. `latest-email.json` beside it holds the
-  newest email, code included, for scripts.
-- **Results** open from the CLI as usual. vigilbase.com keeps running after the
-  CLI finishes so the results page works: press Enter to stop, or `r` to run
-  the CLI again without restarting the server.
-- **Options**: `--page` also opens the checkup page in local mode; `--no-open`
-  opens nothing (no inbox tabs, no results page); `--port <n>` picks the port;
-  `--one-budgets` applies One's creation budgets (one run per address every
-  8 minutes, as in production). Options after `--` go to the CLI, for example
-  `pnpm dev:checkup-local -- --email you@company.com` or `-- submit <file>`.
-- **Logs**: `com.log` and `fake-one.log` in the same directory. The next run
-  overwrites them and the inbox; set `VIGILBASE_CHECKUP_LOCAL_DIR` to use
-  another directory.
-- **CLI config** is a persistent `~/.config/vigilbase-checkup-local/` (`cli/`
-  with your cf, `fake-cf/` with the fake), separate from `~/.config/vigilbase`:
-  the managed cf install happens once, and dev checkups never mix with real
-  ones. The read-only cf profile itself is cf's, shared with real runs. Clean
-  up with `pnpm dev:checkup-local -- logout` (deletes that profile and the
-  managed cf) and `rm -rf ~/.config/vigilbase-checkup-local`.
-
-Ctrl-C stops everything: no server keeps running after the command exits.

package/ONE.md

@@ -1,6 +1,6 @@
 # Vigilbase One CLI reference
 
-Log in with `vigilbase login`. These command groups use the configured One origin (`--one-url`, `VIGILBASE_ONE_URL`, default `https://one.vigilbase.com`) and the saved device-login credential. Every operation in this reference sends GET. Customer, organization, role, and integration access remains enforced by One; selecting an ID never grants access.
+Log in with `vigilbase login` (signing in isn't supported on Windows yet). These command groups use the configured One origin (`--one-url`, `VIGILBASE_ONE_URL`, default `https://one.vigilbase.com`) and your saved sign-in. Every operation in this reference sends GET. Customer, organization, role, and integration access remains enforced by One; selecting an ID never grants access.
 
 Use `--json` to retain the complete API response and pagination metadata. Plain/pretty output shows all fields as an indented tree, including null/unknown metrics, degraded status, totals, and cursors. `--timeout <milliseconds>` controls request timeouts. No command automatically follows pagination. Only documented flags are accepted; unrelated flags fail before authentication or network requests.
 
@@ -94,6 +94,4 @@ vigilbase support tickets [--all] [--limit 1..100] [--json]
 
 ## Related commands and validation
 
-See [README.md](README.md) for login, account, billing, public scanners, run history, Watchdog, Cloudflare (`cf`/`cloudflare`), and security command references. The read operations above do not replace the existing explicitly confirmed write commands.
-
-The test suite validates argument rejection, auth failures, tenant ID encoding, API errors, response rendering, and read transport. `pnpm --filter @vigilbase/cli smoke:commands` builds the actual binary and exercises each named operation against independently authored local HTTP fixtures in `scripts/fixtures/one.mjs`. This verifies the binary, argument parser, credential store, HTTP request, and JSON/text output without writing production data. These fixtures do not assert deployed provider availability or that a particular production user has permissions.
+See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.