@vigilbase/cli 0.1.4 → 0.2.1

package/CLOUDFLARE.md

@@ -1,6 +1,8 @@
 # Cloudflare CLI reference
 
-`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.
+`vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first (signing in isn't supported on Windows yet). 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`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md)).
 
 Customer provider access requires an `active` or `trialing` Cloudflare service
 entitlement for the selected account. Historical/inactive rows and legacy account
@@ -107,6 +109,3 @@ Checkup progress reads once and does not poll automatically. Run the command aga
 
 Malformed IDs, conflicting selections, extra positional arguments and unsupported scope combinations fail before a network request. Authentication, permission, HTTP and explicit `success:false` API failures return a nonzero exit status. Provider configuration writes, token management, cache purge, account deletion and DNS edits are not exposed by this command group.
 
-## Verification
-
-`pnpm --filter @vigilbase/cli test` runs command contract tests, including tenant filters, exact paths, bearer authentication, rejected input, permission failures and terminal text handling. Cloudflare fixtures in `scripts/fixtures/cloudflare.mjs` cover every command and workspace section for the compiled CLI end-to-end harness. These fixtures execute against a local HTTP server; the checkup-start case never contacts production.

package/COMMANDS.md

@@ -2,73 +2,118 @@
 
 The CLI uses public scanner APIs on `vigilbase.com` and authenticated APIs on
 `one.vigilbase.com`. Use `vigilbase <command> --help` or
-`vigilbase help <command>` for built-in help. Examples below omit optional
-`--json`, which every command supports.
+`vigilbase help <command>` for built-in help. Examples below omit `--json`,
+which every command supports.
 
 ## References
 
 | Area | Complete command and API reference |
 | --- | --- |
-| Cloudflare | [CLOUDFLARE.md](./CLOUDFLARE.md) |
-| Security | [SECURITY.md](./SECURITY.md) |
-| Customers, organizations, monitoring, support | [ONE.md](./ONE.md) |
-| Authentication, setup, network troubleshooting | [README.md](./README.md) |
+| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/CLOUDFLARE.md) |
+| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/SECURITY.md) |
+| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/ONE.md) |
+| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/LOCAL.md) |
+| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.1/files/README.md) |
 
-The references identify supported operations, filters, response/pagination
-behavior, API endpoints, and access requirements. They describe the CLI's
-supported API surface, not every internal endpoint in the monorepo.
+The references list the supported operations, filters, response and pagination
+behaviour, API endpoints and access requirements of the CLI.
 
 ## Global options
 
 | Flag | Meaning |
 | --- | --- |
-| `--json`, `-j` | JSON on stdout; progress/browser instructions on stderr |
+| `--json`, `-j` | JSON on stdout; progress and browser instructions on stderr |
 | `--help`, `-h` | Help for the named command; makes no API request |
-| `--version`, `-V` | Package version |
+| `--version`, `-V` | The installed version: the banner in a terminal, only the version number when stdout is a pipe or a file, `{"name":"@vigilbase/cli","version":"…"}` with `--json` |
 | `--one-url <origin>` | One origin; default `https://one.vigilbase.com` |
+| `--auth-url <origin>` | The Identity issuer to trust; default `https://auth.vigilbase.com`. Staging (`https://identity-staging.vigilbase.com`) or a loopback issuer is trusted only when set here or in `VIGILBASE_AUTH_URL` |
 | `--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` |
 
-Origins must be HTTP(S) URLs without credentials, paths, query strings, or
-fragments. One requires HTTPS, except HTTP loopback development. `--customer-id` is a command-specific One customer UUID; it does not
-change the session's permissions. API-backed reads may still return 403 when the
-signed-in role lacks access. Unknown flags, unsupported command-specific flags
-(including scope flags), and extra positional arguments fail before API access.
-`--style` applies only to `badge`.
+Origins must be HTTP(S) URLs without credentials, paths, query strings or
+fragments. One requires HTTPS, except HTTP for loopback development.
+`--customer-id` is a command-specific One customer UUID; it does not change the
+session's permissions. API reads may still return 403 when the signed-in role
+lacks access. Unknown flags, flags a command doesn't take (including scope
+flags) and extra arguments fail before any API request. `--style` applies only
+to `badge`.
 
 ## Authentication
 
-| Command | Options and behavior | One API |
+Paths on One are relative to `--one-url`; Identity endpoints come from the
+issuer's `/.well-known/openid-configuration` (for production,
+`https://auth.vigilbase.com/api/auth/…`).
+
+| Command | Options and behaviour | Requests |
 | --- | --- | --- |
-| `login` | Device authorization; `--no-open` for remote terminals | POST `/api/auth/device/code`, POST `/api/auth/device/token` |
-| `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 |
-| `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
-trust. Login polling handles pending approval, denial, expiry, and transient
-transport failures. Access tokens are never included in successful CLI output.
+| `login` | Device sign-in; `--no-open` for remote terminals. Signing in again with Identity first revokes and removes the sign-in it replaces (before the new device code), unless that one's last refresh had an uncertain result | One `GET /.well-known/oauth-protected-resource`. Identity: discovery, `POST /api/auth/device/code`, polling the token endpoint, then userinfo; you approve at `https://auth.vigilbase.com/device`. Legacy: One `POST /api/auth/device/code`, `POST /api/auth/device/token`, `GET /api/auth/get-session`; you approve at One's `/device` |
+| `login --token-stdin` | Check and save a token piped from a secret manager; the input is bounded and never echoed. A saved Identity sign-in is revoked and removed before the token is saved | One `GET /api/auth/get-session`; Identity revocation when a sign-in is saved |
+| `login --token <bearer>` | Older input, discouraged because arguments can appear in process lists and history. `VIGILBASE_ONE_TOKEN` also works; neither combines with `--token-stdin` | Same as `--token-stdin` |
+| `whoami` | Shows the saved session; signed out is a successful answer. Notes a CLI 0.2.0 `credentials.json` that is being ignored | Identity: discovery and userinfo (a refresh first if due). Legacy: One `GET /api/auth/get-session` |
+| `logout` | Revokes every saved Identity sign-in, signs a legacy session out, then deletes the credential files. A sign-in Identity has already ended counts as revoked; any other failed Identity revocation keeps every file | Identity: discovery, then `POST /api/auth/oauth2/revoke` per saved sign-in. Legacy: One `POST /api/auth/sign-out` (best effort) |
+| `doctor` | Checks the public API, your session and your saved sign-in independently; exits 1 if any check fails | `GET {base-url}/api/agent/tools`. Signed out or legacy: One `GET /api/auth/get-session`. Identity: `GET {issuer}/.well-known/openid-configuration`, then the userinfo endpoint it names (One is not contacted); a refresh at the token endpoint first if the access token expires within 60 seconds |
+
+Credentials are saved atomically with owner-only permissions in
+`identity-credentials.json` (Identity) or `credentials.json` (legacy One
+sessions, shared with CLI 0.1.x), and are tied to the One origin and, for
+Identity, the issuer, client and One resource they were issued for. Rotating
+refresh tokens are coordinated across CLI processes by `credentials.json.lock`.
+Login polling handles pending approval, denial, expiry and short network
+failures. Access tokens never appear in CLI output. Signing in isn't supported
+on Windows yet. The README covers the files, CLI 0.1.x/0.2.0 compatibility,
+logout, directory checks and the config directory.
+
+`doctor` JSON has `checks.publicApi`, `checks.one` and `checks.signIn`, each
+`{ok, url?, error?, status?, code?}`. `checks.one.url` is the endpoint it
+checked: One's `get-session`, the discovered userinfo endpoint, or the
+issuer's discovery URL when discovery itself failed. `checks.signIn` has no
+`url`.
 
 ## Public scanners and authenticated scans
 
 | Command | Options | API |
 | --- | --- | --- |
-| `list` (alias `tools`) | Lists the public catalog and authenticated scanner names | GET `/api/agent/tools` |
-| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/agent/tools/<tool>/execute` or One POST `/api/tools/<tool>/execute` |
+| `list` (alias `tools`) | Lists the public catalog and the One-only scanners | GET `/api/agent/tools` |
+| `run <tool> <target>` | `--via public\|one`; `--public` forces the public API | POST `/api/agent/tools/<tool>/execute` (anonymous) or One POST `/api/tools/<tool>/execute` |
 | `headers <url>` | Shortcut for `run security-headers`; same routing options | Same as `run` |
 | `email <domain>` | Shortcut for `run email-security`; same routing options | Same as `run` |
 | `describe <tool>` | `--no-skill` skips fetching skill Markdown | Catalog plus the tool's published skill URL |
-| `skill <tool>` | Prints the complete published skill; JSON includes URL/content | Catalog plus the tool's skill URL |
-| `badge <domain>` | `--style default\|compact\|mini` | Generates a public badge URL locally |
+| `skill <tool>` | Prints the complete published skill; JSON includes URL and content | Catalog plus the tool's skill URL |
+| `badge <domain>` | `--style default\|compact\|mini` | None; builds the public badge URL locally |
+
+Public tools: `security-headers`, `email-security`. One-only tools:
+`website-security`, `react2shell`, `fortibleed-check`. Public scans use the
+public API unless you add `--via one`; being signed in doesn't change that.
+`--public` and `--via one` cannot be combined.
+
+The public route is anonymous and never reads your saved sign-in, the
+credentials lock or Identity, so sign-in problems cannot make it fail. Runs
+that go through One (`--via one` and the One-only tools) need a sign-in.
+Without one they stop with this error:
+
+```
+Error: This tool needs a Vigilbase One sign-in: run `vigilbase login`.
+```
 
-Public tools: `security-headers`, `email-security`. Login-required tools:
-`website-security`, `react2shell`, `fortibleed-check`. Public scans stay on the
-public API unless explicitly routed to One. A saved login alone does not change
-that choice. `--public` and `--via one` cannot be combined.
+Other sign-in errors keep their own message, with that sentence as the hint
+unless the message already says to run `vigilbase login`.
+
+`list` reads your saved sign-in from disk only (no refresh, no network, no wait
+for the lock). In JSON, `authenticated` says whether it looks usable and
+`oneExecutableTools` follows it. If it can't be used, `list` still prints the
+catalog, shows you as signed out and prints one stderr line per run:
+``Couldn't use your saved sign-in (<reason>); running anonymously. Run `vigilbase login` to fix.``
+For an unsafe config path or credentials file, which `login` would refuse too,
+the line ends with the fix instead, for example
+``Couldn't use your saved sign-in (/tmp is a symbolic link); running anonymously. Set VIGILBASE_CONFIG_DIR to a private directory without symbolic links in its path.``
+`list` and `doctor` ignore a config path that fails the checks when no
+credentials file is there.
+
+When a public scan fails and vigilbase.com explains why with a known error
+code, the CLI prints `Error: <message> (<code>)` (JSON: `error`, `code`,
+`status`), with the message cleaned to one line of at most 300 characters.
+Otherwise it prints `Request failed (HTTP <status>).`
 
 ## Account and billing
 
@@ -81,21 +126,20 @@ that choice. `--public` and `--via one` cannot be combined.
 | `account sessions` | `session` | GET `/api/account/sessions` |
 | `account invites` | `invitations`; optional `list` or `ls` | GET `/api/auth/orgs/invitations` |
 | `account invites create` | `add` alias; `--email <email>`, `--role <role>` (default member), required `--confirm` | POST `/api/auth/orgs/invite` |
-| `account billing` | Delegates to billing commands | Same as billing |
+| `account billing` | Same as the billing commands | Same as billing |
 | `billing` | `summary`, `show`, `status` | GET `/api/account/billing` |
 | `billing portal` | `open`; `--no-open` prints the portal URL without opening a browser | POST `/api/billing/portal` |
 
-Invitation creation sends an invitation; billing portal creation starts a Stripe
-portal session. These are explicit actions. Billing data comes from One's Stripe
-integration; the CLI does not persist invoices or payment information locally.
+Creating an invitation sends it; `billing portal` starts a Stripe portal
+session. Both are explicit actions. Billing data comes from One's Stripe
+integration; the CLI does not store invoices or payment information.
 
-Invitations validate the email and role locally and generate a fresh UUID
-`operationId` for each invocation. Accepted roles: `admin`, `member`, `readonly`,
+Invitations check the email and role locally and send a fresh UUID
+`operationId` each time. Accepted roles: `admin`, `member`, `readonly`,
 `partner_owner`, `partner_sales`, `partner_operations`, `partner_finance`,
-`partner_readonly`, `billing_only`, and `sales_only`. The API still checks whether
-the caller may assign the chosen role. `--confirm` is required.
-Portal URLs are validated against the HTTPS Stripe billing host before JSON
-output, printing, or opening; Windows requires manual opening.
+`partner_readonly`, `billing_only` and `sales_only`. One still checks whether
+you may assign the role. `--confirm` is required. Portal URLs must be HTTPS on
+Stripe's billing host before they are printed, opened or put in JSON.
 
 ## Run history and account Watchdog
 
@@ -103,45 +147,76 @@ output, printing, or opening; Windows requires manual opening.
 | --- | --- | --- |
 | `runs` | `list`, `ls`; `--tool <name>`, `--limit <n>` (1–200, default 50) | GET `/api/tool-runs` |
 | `runs get <id>` | `show <id>` or `runs <UUID>` | GET `/api/tool-runs/<id>` |
-| `runhistory` | Alias of the entire `runs` group | Same as runs |
+| `runhistory` | Alias of the whole `runs` group | Same as runs |
 | `watchdog` | `list`, `targets`, `status` | GET `/api/account/watchdog/targets` |
 | `watchdog scans` | `scan`; `--target-id <UUID>`, `--limit <n>` (1–100, default 20) | GET `/api/account/watchdog/scans` |
 
-Customer-specific Watchdog and monitoring views are documented in ONE.md.
+Customer-specific Watchdog and monitoring views are in ONE.md.
 
-## Output, effects, and testing
+## Local Cloudflare Checkup (no sign-in)
 
-Exit codes: **0** success, **1** validation/API/network failure, **2** HTTP 429
-rate limiting. A completed scan whose result is unsuccessful also exits 1.
-`whoami` being signed out is not an API failure. A healthy `doctor` does not
-require login. API error JSON retains status, code, and retry delay when available.
+All vigilbase.com paths below are under
+`https://vigilbase.com/api/v1/tools/cloudflare-checkup/local-session`.
 
-New security/customer operations preserve JSON response envelopes and pagination
-fields. Cloudflare inventory commands may apply the explicitly requested account
-or zone filter locally as well as sending it to One; zone detail returns the
-selected object. See each reference for details. Text output is for people; use
-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,
-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.
-
-```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.
-
-VIGILBASE_BASE_URL=https://vigilbase.com \
-  VIGILBASE_SMOKE_ARTIFACTS="$PWD/.context/cli-live-smoke" \
-  pnpm --filter @vigilbase/cli smoke:e2e
-```
-
-The command suite uses temporary local HTTP fixtures and credentials; all writes
-stay local. It checks exact methods/paths/filters/bodies, bearer handling, output,
-permission failures, rate limits, malformed responses, and documentation presence.
-The live smoke separately checks public services and actual public scans. Real
-customer-data access additionally requires a valid One session and suitable role;
-local fixtures do not prove production provider configuration or data health.
+| 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` | In order: GET `…/availability` (before the email is asked for), POST `…/request` and `…/verify` (email verification), GET `…/local-session` (before cf runs), allowlisted read-only cf commands, GET `…/local-session` again and POST `…/local-session/snapshot` after you confirm. 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` | After checking the file: GET `…/availability`, POST `…/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` first ask vigilbase.com whether local checkups are
+available (no email, no credentials). When they are switched off, the command
+stops before asking for your email with
+`Local checkups aren't available right now.` and the hint
+`Run the Cloudflare Checkup in your browser instead: https://vigilbase.com/tools/cloudflare-checkup`
+(`LOCAL_MODE_DISABLED`). When vigilbase.com needs a newer CLI, it stops with
+`CLI_UPGRADE_REQUIRED`, also before any email. If vigilbase.com doesn't answer
+the check, the command goes on.
+
+Then they verify your work email: 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
+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 a `hint` that
+usually says to run the same command again. See LOCAL.md for the email
+verification, the managed cf install, the allowlist, the environment policy,
+the uploaded data and the error codes.
+
+## Output and effects
+
+Exit codes: **0** success, **1** validation, API, network or sign-in failure,
+**2** HTTP 429 rate limiting. A completed scan whose result is unsuccessful
+also exits 1. A signed-out `whoami` is not a failure, and a healthy `doctor`
+does not need a sign-in. API error JSON keeps the status, code and retry delay
+when available.
+
+Security and customer operations keep JSON response envelopes and pagination
+fields. Cloudflare inventory commands may apply the account or zone filter you
+asked for locally as well as sending it to One; zone detail returns the
+selected object. Text output is for people; use JSON for automation and
+evidence export.
+
+Provider credentials, signed delegation claims, internal bearer tokens and
+organization overrides are never CLI inputs. Commands use named One routes,
+with two exceptions. Local provider reads: `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. And the vigilbase.com local-session routes, which
+are the checkup's only Vigilbase requests: GET `…/availability`, POST
+`…/request` and POST `…/verify` without a credential, then GET `…/local-session`
+and, after you confirm, POST `…/local-session/snapshot` with the exact snapshot
+file, both authorized by the session code the email verification returned (see
+LOCAL.md). Webhooks, cron and admin repair endpoints, interactive OAuth
+handoffs, streaming or binary downloads, and endpoints that create records on
+GET are not exposed. Remediation that needs durable approval and receipts stays
+in its existing One and Vigil flows.