@vigilbase/cli 0.1.4 → 0.2.1

package/dist/local/cloudflare-checkup/email-verification.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Email verification in the CLI: the one command and `submit` start with it.
+ *
+ * The CLI asks for a work email (or takes `--email`) and POSTs it to
+ * `local-session/request`; vigilbase.com creates the checkup and emails a
+ * 6-digit code. The CLI asks for the code and POSTs it with the returned
+ * verification token to `local-session/verify`, which answers with the
+ * session code for the upload. There is no bot check on this path; the server
+ * accepts business addresses only and rate-limits per mailbox (`+tag`
+ * variants included), per domain, per IP (an IPv6 /64 counts as one) and
+ * overall.
+ *
+ * The address, the emailed code, the token and the session code stay in this
+ * process's memory. They are never printed (only the masked address the server
+ * returns, `j***@acme.com`), logged, written to disk, put in a URL or JSON
+ * output, or passed to cf or npm. The token and the code are kept only so the
+ * session can be renewed once when it expires during a long collection.
+ */
+import type { LocalEmailLocale } from './contract.js';
+import { LocalCheckupError } from './errors.js';
+import { type PromptIO } from './prompts.js';
+import { type VerificationClient } from './submit-client.js';
+export declare const EMAIL_PROMPT = "Work email for your results: ";
+export declare const CODE_PROMPT = "Code from the email: ";
+/** Addresses asked for before giving up (a malformed one, or one vigilbase.com does not accept). */
+export declare const MAX_EMAIL_ATTEMPTS = 3;
+/** Codes asked for before giving up; One locks a checkup after 5 wrong codes. */
+export declare const MAX_CODE_ATTEMPTS = 5;
+/**
+ * On a terminal, how often the code is asked for again after vigilbase.com did
+ * not answer the verify (twice: the client already sent it once more). These
+ * are not tries: only a wrong code uses one.
+ */
+export declare const MAX_UNANSWERED_VERIFIES = 2;
+/** One `@` with text on both sides, no spaces or control characters, at most 254 characters. */
+export declare function isEmailShaped(value: string): boolean;
+/** `--email <address>`: checked before anything runs; the value is never echoed. */
+export declare function parseEmailFlag(value: string): string;
+/** The six digits of a typed code; `123 456` and `123-456` are accepted too. Null for anything else. */
+export declare function normalizeEmailCode(input: string): string | null;
+/** The email language from LC_ALL, LC_MESSAGES or LANG (the first one set): `pt*` → pt-PT, `ar*` → ar, else en. */
+export declare function emailLocale(env: NodeJS.ProcessEnv): LocalEmailLocale;
+/**
+ * A verified email and the session code it earned. Private fields keep the
+ * token, the emailed code and the session code out of `JSON.stringify` and
+ * `util.inspect`.
+ */
+export declare class VerifiedEmail {
+    #private;
+    /** The masked address from vigilbase.com, safe to print. */
+    readonly requester: string;
+    constructor(client: VerificationClient, token: string, emailCode: string, session: {
+        code: string;
+        requester: string;
+        expiresAt: string;
+    });
+    /** The current session code: in memory only, sent only as the upload's bearer. */
+    get sessionCode(): string;
+    get expiresAt(): string;
+    /** True until `renew` has been used. */
+    get renewable(): boolean;
+    /**
+     * Once per run: verify again with the same token and code, and vigilbase.com
+     * mints the next session code for the same checkup (the previous one stops
+     * working). It fails once the emailed code expired or the checkup closed.
+     */
+    renew(): Promise<void>;
+    toJSON(): {
+        requester: string;
+    };
+}
+/**
+ * How the verification asks and reports. The default is the plain prompts
+ * (`Work email for your results:` and `Code from the email:`, a visible line or
+ * one line of piped stdin) and status lines through `say` and `notice`; the
+ * terminal UI brings its own inputs and spinners.
+ */
+export type EmailVerificationView = {
+    /** The address as entered; null when the input ended. */
+    askEmail(): Promise<string | null>;
+    /** The emailed code as entered; null when the input ended. */
+    askCode(): Promise<string | null>;
+    /** The code went to `sentTo` (the masked address) and is valid until `expiresAt`. */
+    codeSent(sentTo: string, expiresAt: string): void;
+    /** Why the next question is asked again. */
+    notice(line: string): void;
+    /** The code request to vigilbase.com. */
+    requesting<T>(work: () => Promise<T>): Promise<T>;
+    /** The code check at vigilbase.com. */
+    verifying<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * A rate-limited code request (VIGILBASE_RATE_LIMITED): true to ask for
+     * another address. Asked only without `--email` and while addresses are
+     * left; without it the error stops the run (exit 2).
+     */
+    rateLimited?(error: LocalCheckupError): Promise<boolean>;
+};
+export type EmailVerificationOptions = {
+    client: VerificationClient;
+    io: PromptIO;
+    locale: LocalEmailLocale;
+    /** `--email`, already checked with `parseEmailFlag`; it is never asked for again. */
+    email?: string;
+    /** A status line ("We emailed a 6-digit code to …"). */
+    say(line: string): void;
+    /** Why a prompt is asked again (stderr). */
+    notice(line: string): void;
+    /** Replaces the plain prompts and lines built from `io`, `say` and `notice`. */
+    view?: EmailVerificationView;
+};
+/** vigilbase.com starts one checkup per address every 8 minutes (One's creation budget). No final period. */
+export declare const SAME_ADDRESS_WAIT = "The same address can get a new code 8 minutes after the last one";
+/**
+ * Request a code, then ask for it until vigilbase.com accepts it (up to 5
+ * tries; One locks the checkup after 5 wrong codes). A wrong address is asked
+ * for again (up to 3), except with `--email`. An expired verification and a
+ * rate limit stop with their own codes (VERIFICATION_EXPIRED, and
+ * VIGILBASE_RATE_LIMITED with the retry time, exit 2), unless the view offers
+ * another address for a rate limit. A verify vigilbase.com did not answer is
+ * sent once more by the client; if that fails too, a terminal asks for the
+ * code again (twice at most, without using a try), since a new code for the
+ * same address would be refused for 8 minutes.
+ */
+export declare function verifyEmail(options: EmailVerificationOptions): Promise<VerifiedEmail>;

package/dist/local/cloudflare-checkup/email-verification.js

@@ -0,0 +1,211 @@
+import { LocalCheckupError } from './errors.js';
+import { formatClock } from './output.js';
+import { hasInteractiveInput, promptAnswer } from './prompts.js';
+import { displayRequester } from './submit-client.js';
+export const EMAIL_PROMPT = 'Work email for your results: ';
+export const CODE_PROMPT = 'Code from the email: ';
+/** Addresses asked for before giving up (a malformed one, or one vigilbase.com does not accept). */
+export const MAX_EMAIL_ATTEMPTS = 3;
+/** Codes asked for before giving up; One locks a checkup after 5 wrong codes. */
+export const MAX_CODE_ATTEMPTS = 5;
+/**
+ * On a terminal, how often the code is asked for again after vigilbase.com did
+ * not answer the verify (twice: the client already sent it once more). These
+ * are not tries: only a wrong code uses one.
+ */
+export const MAX_UNANSWERED_VERIFIES = 2;
+const MAX_EMAIL_LENGTH = 254;
+const EMAIL_SHAPE = /^[^\s@\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]+@[^\s@\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]+$/u;
+/** One `@` with text on both sides, no spaces or control characters, at most 254 characters. */
+export function isEmailShaped(value) {
+    return value.length <= MAX_EMAIL_LENGTH && EMAIL_SHAPE.test(value);
+}
+/** `--email <address>`: checked before anything runs; the value is never echoed. */
+export function parseEmailFlag(value) {
+    const email = value.trim();
+    if (!isEmailShaped(email))
+        throw new LocalCheckupError('EMAIL_INVALID', '--email is not an email address.');
+    return email;
+}
+/** The six digits of a typed code; `123 456` and `123-456` are accepted too. Null for anything else. */
+export function normalizeEmailCode(input) {
+    const digits = input.replace(/[\s-]/g, '');
+    return /^\d{6}$/.test(digits) ? digits : null;
+}
+/** The email language from LC_ALL, LC_MESSAGES or LANG (the first one set): `pt*` → pt-PT, `ar*` → ar, else en. */
+export function emailLocale(env) {
+    const value = [env.LC_ALL, env.LC_MESSAGES, env.LANG].find((candidate) => candidate !== undefined && candidate.trim() !== '') ?? '';
+    const language = value.trim().toLowerCase();
+    return language.startsWith('pt') ? 'pt-PT' : language.startsWith('ar') ? 'ar' : 'en';
+}
+/**
+ * A verified email and the session code it earned. Private fields keep the
+ * token, the emailed code and the session code out of `JSON.stringify` and
+ * `util.inspect`.
+ */
+export class VerifiedEmail {
+    #client;
+    #token;
+    #emailCode;
+    #sessionCode;
+    #expiresAt;
+    #renewed = false;
+    /** The masked address from vigilbase.com, safe to print. */
+    requester;
+    constructor(client, token, emailCode, session) {
+        this.#client = client;
+        this.#token = token;
+        this.#emailCode = emailCode;
+        this.#sessionCode = session.code;
+        this.#expiresAt = session.expiresAt;
+        this.requester = displayRequester(session.requester);
+    }
+    /** The current session code: in memory only, sent only as the upload's bearer. */
+    get sessionCode() {
+        return this.#sessionCode;
+    }
+    get expiresAt() {
+        return this.#expiresAt;
+    }
+    /** True until `renew` has been used. */
+    get renewable() {
+        return !this.#renewed;
+    }
+    /**
+     * Once per run: verify again with the same token and code, and vigilbase.com
+     * mints the next session code for the same checkup (the previous one stops
+     * working). It fails once the emailed code expired or the checkup closed.
+     */
+    async renew() {
+        if (this.#renewed)
+            throw new LocalCheckupError('SESSION_EXPIRED', 'The checkup session expired again after it was renewed.');
+        this.#renewed = true;
+        const session = await this.#client.verifyCode({ verification: this.#token, code: this.#emailCode });
+        this.#sessionCode = session.code;
+        this.#expiresAt = session.expiresAt;
+    }
+    toJSON() {
+        return { requester: this.requester };
+    }
+}
+/** The plain prompts and status lines. */
+function plainView(options) {
+    return {
+        askEmail: () => promptAnswer(options.io, EMAIL_PROMPT),
+        askCode: () => promptAnswer(options.io, CODE_PROMPT),
+        codeSent: (sentTo, expiresAt) => options.say(`We emailed a 6-digit code to ${sentTo} (valid until ${formatClock(expiresAt)}). Check spam if it doesn't arrive.`),
+        notice: (line) => options.notice(line),
+        requesting: (work) => work(),
+        verifying: (work) => work(),
+    };
+}
+const PIPE_HINT = 'Run the command in a terminal, or pass --email <address> and pipe the code from the email to it once it asks (`Code from the email:` on stderr).';
+/** vigilbase.com starts one checkup per address every 8 minutes (One's creation budget). No final period. */
+export const SAME_ADDRESS_WAIT = 'The same address can get a new code 8 minutes after the last one';
+/** The input ended (Ctrl-D on a terminal, or the end of piped stdin) before an answer. */
+function noAnswer(options, what) {
+    const hint = !hasInteractiveInput(options.io.stdin) ? PIPE_HINT
+        : what === 'code' ? `Run the same command again. ${SAME_ADDRESS_WAIT}.` : 'Run the same command again and enter your work email.';
+    return new LocalCheckupError('CONFIRMATION_REQUIRED', `No ${what} was entered, and the input ended.`, { hint });
+}
+/**
+ * Ask for the address until vigilbase.com accepts one and emails a code (up to
+ * 3 addresses). A rate limit stops the run, unless the view offers another
+ * address and the user takes it.
+ */
+async function requestCode(options, view) {
+    for (let attempt = 1;; attempt++) {
+        let email = options.email;
+        if (email === undefined) {
+            const answer = (await view.askEmail())?.trim() ?? null;
+            if (answer === null)
+                throw noAnswer(options, 'email address');
+            if (!isEmailShaped(answer)) {
+                if (attempt >= MAX_EMAIL_ATTEMPTS)
+                    throw new LocalCheckupError('EMAIL_INVALID', 'That is not an email address.');
+                view.notice('That is not an email address. Enter your work email.');
+                continue;
+            }
+            email = answer;
+        }
+        const address = email;
+        try {
+            return await view.requesting(() => options.client.requestCode({ email: address, locale: options.locale }));
+        }
+        catch (error) {
+            if (!(error instanceof LocalCheckupError))
+                throw error;
+            if (error.code === 'VIGILBASE_RATE_LIMITED') {
+                if (options.email === undefined && attempt < MAX_EMAIL_ATTEMPTS && view.rateLimited && await view.rateLimited(error))
+                    continue;
+                throw error;
+            }
+            if (error.code !== 'EMAIL_INVALID')
+                throw error;
+            if (options.email !== undefined) {
+                throw new LocalCheckupError('EMAIL_INVALID', 'vigilbase.com does not accept the --email address: use your work email (not a personal or disposable one).', { status: error.status });
+            }
+            if (attempt >= MAX_EMAIL_ATTEMPTS)
+                throw error;
+            view.notice('vigilbase.com accepts work email addresses only (not personal or disposable ones). Enter another address.');
+        }
+    }
+}
+/** No answer to the verify (a network error or a timeout), or a 503: the code may be sent again. */
+function isUnanswered(error) {
+    return error.code === 'SUBMIT_FAILED' && (error.status === 0 || error.status === 503);
+}
+/**
+ * Request a code, then ask for it until vigilbase.com accepts it (up to 5
+ * tries; One locks the checkup after 5 wrong codes). A wrong address is asked
+ * for again (up to 3), except with `--email`. An expired verification and a
+ * rate limit stop with their own codes (VERIFICATION_EXPIRED, and
+ * VIGILBASE_RATE_LIMITED with the retry time, exit 2), unless the view offers
+ * another address for a rate limit. A verify vigilbase.com did not answer is
+ * sent once more by the client; if that fails too, a terminal asks for the
+ * code again (twice at most, without using a try), since a new code for the
+ * same address would be refused for 8 minutes.
+ */
+export async function verifyEmail(options) {
+    const view = options.view ?? plainView(options);
+    const pending = await requestCode(options, view);
+    view.codeSent(displayRequester(pending.requester, 'the address you entered'), pending.expiresAt);
+    let unanswered = 0;
+    for (let attempt = 1;; attempt++) {
+        const left = MAX_CODE_ATTEMPTS - attempt;
+        const answer = await view.askCode();
+        if (answer === null)
+            throw noAnswer(options, 'code');
+        const code = normalizeEmailCode(answer);
+        if (code === null) {
+            if (left <= 0)
+                throw new LocalCheckupError('EMAIL_CODE_INVALID', 'No valid 6-digit code was entered.');
+            view.notice(`Enter the 6 digits from the email (${left} ${left === 1 ? 'try' : 'tries'} left).`);
+            continue;
+        }
+        try {
+            // The client already sent a verify that got no answer, or a 503, once more.
+            const session = await view.verifying(() => options.client.verifyCode({ verification: pending.token, code }));
+            return new VerifiedEmail(options.client, pending.token, code, session);
+        }
+        catch (error) {
+            if (error instanceof LocalCheckupError && isUnanswered(error) && unanswered < MAX_UNANSWERED_VERIFIES && hasInteractiveInput(options.io.stdin)) {
+                unanswered++;
+                // Not one of the 5 tries: the same code is still valid, and asking again costs nothing.
+                attempt--;
+                view.notice('vigilbase.com did not answer. Enter the same code again to retry.');
+                continue;
+            }
+            if (error instanceof LocalCheckupError && error.code === 'SUBMIT_FAILED') {
+                // A new code now would be refused for this address: say how long to wait.
+                throw new LocalCheckupError('SUBMIT_FAILED', error.message, {
+                    hint: `Run the same command again in a few minutes. ${SAME_ADDRESS_WAIT}.`,
+                    ...(error.status !== undefined ? { status: error.status } : {}),
+                });
+            }
+            if (!(error instanceof LocalCheckupError) || error.code !== 'EMAIL_CODE_INVALID' || left <= 0)
+                throw error;
+            view.notice(`That code is not correct (${left} ${left === 1 ? 'try' : 'tries'} left).`);
+        }
+    }
+}

package/dist/local/cloudflare-checkup/errors.d.ts

@@ -0,0 +1,29 @@
+export declare const LOCAL_ERROR_CODES: readonly ["NODE_UNSUPPORTED", "CF_NOT_FOUND", "CF_WRONG_BINARY", "CF_UNSUPPORTED_VERSION", "CF_ALLOWLIST_MISMATCH", "CF_INSTALL_FAILED", "CF_AUTH_REQUIRED", "CF_PERMISSION_DENIED", "CF_RATE_LIMITED", "CF_ERROR", "ACCOUNT_SELECTION_REQUIRED", "ACCOUNT_NOT_VISIBLE", "ACCOUNT_TOO_LARGE", "ACCOUNT_MISMATCH", "OUTPUT_EXISTS", "SNAPSHOT_INVALID", "SNAPSHOT_TOO_LARGE", "SNAPSHOT_STALE", "SNAPSHOT_SECRET_LIKE_VALUE", "EMAIL_INVALID", "EMAIL_CODE_INVALID", "VERIFICATION_INVALID", "VERIFICATION_EXPIRED", "SESSION_INVALID", "SESSION_EXPIRED", "SESSION_USED", "SESSION_BUSY", "SESSION_CLOSED", "SUBMIT_ORIGIN_UNTRUSTED", "CONFIRMATION_REQUIRED", "CLI_UPGRADE_REQUIRED", "LOCAL_MODE_DISABLED", "VIGILBASE_RATE_LIMITED", "VIGILBASE_CHALLENGED", "SUBMIT_FAILED"];
+export type LocalCheckupErrorCode = (typeof LOCAL_ERROR_CODES)[number];
+/** LOCAL_MODE_DISABLED: the browser checkup on the origin the CLI talks to (vigilbase.com, or a loopback dev server). */
+export declare function browserCheckupHint(origin: string): string;
+/** One fix per code; shown after the error and in `--json` as `hint`. */
+export declare const LOCAL_ERROR_HINTS: Record<LocalCheckupErrorCode, string>;
+/**
+ * CF_AUTH_REQUIRED in env mode (`--cf-auth env`, or `auto` with the variable
+ * set): the browser sign-in is never offered while the token is used, so the
+ * hint names both ways out.
+ */
+export declare const ENV_TOKEN_AUTH_HINT = "Set CLOUDFLARE_API_TOKEN in this shell to a valid read-only Cloudflare API token (read -rs CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN) and run the same command again, or unset it (or use --cf-auth profile) to sign in with your browser instead.";
+/** CF_PERMISSION_DENIED in env mode: the token lacks a read permission; the browser sign-in is the other way out. */
+export declare const ENV_TOKEN_PERMISSION_HINT = "The API token in CLOUDFLARE_API_TOKEN cannot read everything the checkup needs. Add the read permissions to it, or unset it (or use --cf-auth profile) to sign in with your browser instead, then run the same command again.";
+export declare class LocalCheckupError extends Error {
+    readonly code: LocalCheckupErrorCode;
+    readonly hint: string;
+    /** HTTP status of the Cloudflare or Vigilbase response, when one caused the error. */
+    readonly status?: number;
+    readonly retryAfterSec?: number;
+    constructor(code: LocalCheckupErrorCode, message: string, options?: {
+        hint?: string;
+        status?: number;
+        retryAfterSec?: number;
+    });
+    /** Mapped to exit code 2 by `runCli`. */
+    get isRateLimited(): boolean;
+}
+export declare function isLocalCheckupError(error: unknown): error is LocalCheckupError;

package/dist/local/cloudflare-checkup/errors.js

@@ -0,0 +1,103 @@
+/**
+ * Stable error codes for `vigilbase cloudflare-checkup` (spec §F8).
+ *
+ * Every code matches `formatError`'s code pattern. Messages and hints are
+ * authored here; cf stderr and Vigilbase server text are never echoed. Hints
+ * point at the one command ("run the same command again", `--yes`,
+ * `--account-id`), not at the advanced subcommands. The browser
+ * troubleshooting accordion mirrors the code set.
+ */
+import { CF_TOKEN_ENV } from './cf/child-env.js';
+import { PRODUCTION_ORIGIN } from './contract.js';
+export const LOCAL_ERROR_CODES = [
+    // Environment and cf
+    'NODE_UNSUPPORTED', 'CF_NOT_FOUND', 'CF_WRONG_BINARY', 'CF_UNSUPPORTED_VERSION', 'CF_ALLOWLIST_MISMATCH',
+    'CF_INSTALL_FAILED', 'CF_AUTH_REQUIRED', 'CF_PERMISSION_DENIED', 'CF_RATE_LIMITED', 'CF_ERROR',
+    // Account
+    'ACCOUNT_SELECTION_REQUIRED', 'ACCOUNT_NOT_VISIBLE', 'ACCOUNT_TOO_LARGE', 'ACCOUNT_MISMATCH',
+    // Files and snapshots
+    'OUTPUT_EXISTS', 'SNAPSHOT_INVALID', 'SNAPSHOT_TOO_LARGE', 'SNAPSHOT_STALE', 'SNAPSHOT_SECRET_LIKE_VALUE',
+    // Email verification
+    'EMAIL_INVALID', 'EMAIL_CODE_INVALID', 'VERIFICATION_INVALID', 'VERIFICATION_EXPIRED',
+    // Session
+    'SESSION_INVALID', 'SESSION_EXPIRED', 'SESSION_USED', 'SESSION_BUSY', 'SESSION_CLOSED',
+    // Submission
+    'SUBMIT_ORIGIN_UNTRUSTED', 'CONFIRMATION_REQUIRED', 'CLI_UPGRADE_REQUIRED', 'LOCAL_MODE_DISABLED',
+    'VIGILBASE_RATE_LIMITED', 'VIGILBASE_CHALLENGED', 'SUBMIT_FAILED',
+];
+const INSTALL_CF = '`npm install --global cf@1.0.0-beta.13`';
+/** LOCAL_MODE_DISABLED: the browser checkup on the origin the CLI talks to (vigilbase.com, or a loopback dev server). */
+export function browserCheckupHint(origin) {
+    return `Run the Cloudflare Checkup in your browser instead: ${origin}/tools/cloudflare-checkup`;
+}
+/** One fix per code; shown after the error and in `--json` as `hint`. */
+export const LOCAL_ERROR_HINTS = {
+    NODE_UNSUPPORTED: 'Install Node.js 22.18 or newer from https://nodejs.org (cf runs under the same Node), then run the same command again.',
+    CF_NOT_FOUND: `Run the same command again in a terminal and let it install cf (add --yes when no terminal is available), or install it yourself with ${INSTALL_CF}.`,
+    CF_WRONG_BINARY: `Another program named cf (for example the Cloud Foundry CLI, or a pnpm or Volta shim) was found. Run the same command again without --cf-bin and let it install cf, or pass --cf-bin "$(npm root -g)/cf".`,
+    CF_UNSUPPORTED_VERSION: `Run the same command again without --cf-bin and let it install the tested cf 1.0.0-beta.13, or install it yourself with ${INSTALL_CF}.`,
+    // Without --cf-bin the one command offers the managed install itself; the user's own cf is left alone.
+    CF_ALLOWLIST_MISMATCH: 'This cf release renamed commands the checkup needs. Run the same command again without --cf-bin and let it install the tested cf 1.0.0-beta.13 for Vigilbase; your own cf is left alone.',
+    CF_INSTALL_FAILED: `Install cf yourself with ${INSTALL_CF}, then run the same command again.`,
+    CF_AUTH_REQUIRED: `Run the same command again in a terminal to sign in to Cloudflare with a read-only login, or set ${CF_TOKEN_ENV} in this shell first.`,
+    CF_PERMISSION_DENIED: 'Your Cloudflare login cannot read this account\'s zones. Check its permissions, then run the same command again.',
+    CF_RATE_LIMITED: 'Cloudflare paused your API access. Wait 5 minutes, then run the same command again; add --max-requests-per-5min 600 if it repeats.',
+    CF_ERROR: 'Run the same command again in a few minutes. If it persists, contact help@vigilbase.com.',
+    ACCOUNT_SELECTION_REQUIRED: 'Run the same command again in a terminal to choose the account, or add --account-id <ACCOUNT_ID> with one of the IDs listed.',
+    ACCOUNT_NOT_VISIBLE: 'Check that your Cloudflare user can read the account and its zones, then run the same command again.',
+    ACCOUNT_TOO_LARGE: 'Local collection supports up to 100 zones. Use the browser token mode on vigilbase.com instead.',
+    ACCOUNT_MISMATCH: 'This checkup is for a different Cloudflare account. Run the same command again without --account-id to start a new checkup.',
+    OUTPUT_EXISTS: 'Choose another --out path, or pass --overwrite to replace the file.',
+    SNAPSHOT_INVALID: 'The file is not a valid snapshot. Run the same command again to collect a fresh one.',
+    SNAPSHOT_TOO_LARGE: 'The snapshot is over the upload limit. Use the browser token mode on vigilbase.com instead.',
+    SNAPSHOT_STALE: 'Snapshots are accepted for 24 hours. Run the same command again to collect a fresh one.',
+    SNAPSHOT_SECRET_LIKE_VALUE: 'The snapshot contains a value that looks like a credential. Remove it from the Cloudflare rule description or name, then run the same command again.',
+    EMAIL_INVALID: 'Use your work email address (personal and disposable addresses are not accepted), then run the same command again.',
+    EMAIL_CODE_INVALID: 'Run the same command again to get a new code, and enter the 6 digits from the newest email.',
+    VERIFICATION_INVALID: 'Run the same command again to get a new code by email.',
+    VERIFICATION_EXPIRED: 'Run the same command again to get a new code by email, and enter it before the time shown.',
+    SESSION_INVALID: 'Run the same command again to verify your email and start a new checkup.',
+    SESSION_EXPIRED: 'Run the same command again to verify your email and start a new checkup.',
+    SESSION_USED: 'This checkup already has results. Run the same command again to start a new checkup.',
+    SESSION_BUSY: 'A snapshot for this checkup is still being processed. Wait for the results email, or run the same command again to start a new checkup.',
+    SESSION_CLOSED: 'This checkup was cancelled or has expired. Run the same command again to start a new one.',
+    SUBMIT_ORIGIN_UNTRUSTED: 'Upload only to https://vigilbase.com (or a loopback origin for local testing).',
+    CONFIRMATION_REQUIRED: 'Run the command in a terminal to confirm the upload, or add --yes.',
+    CLI_UPGRADE_REQUIRED: 'Run `npx @vigilbase/cli@latest cloudflare-checkup`, or upgrade with `npm install --global @vigilbase/cli@latest`.',
+    LOCAL_MODE_DISABLED: browserCheckupHint(PRODUCTION_ORIGIN),
+    VIGILBASE_RATE_LIMITED: 'Too many requests to vigilbase.com. Wait as long as the error says (a few minutes if it says nothing), then run the same command again.',
+    VIGILBASE_CHALLENGED: 'vigilbase.com asked for a browser challenge. Try another network, or contact help@vigilbase.com.',
+    SUBMIT_FAILED: 'Run the same command again in a few minutes. If it persists, contact help@vigilbase.com.',
+};
+/**
+ * CF_AUTH_REQUIRED in env mode (`--cf-auth env`, or `auto` with the variable
+ * set): the browser sign-in is never offered while the token is used, so the
+ * hint names both ways out.
+ */
+export const ENV_TOKEN_AUTH_HINT = `Set ${CF_TOKEN_ENV} in this shell to a valid read-only Cloudflare API token (read -rs ${CF_TOKEN_ENV} && export ${CF_TOKEN_ENV}) and run the same command again, or unset it (or use --cf-auth profile) to sign in with your browser instead.`;
+/** CF_PERMISSION_DENIED in env mode: the token lacks a read permission; the browser sign-in is the other way out. */
+export const ENV_TOKEN_PERMISSION_HINT = `The API token in ${CF_TOKEN_ENV} cannot read everything the checkup needs. Add the read permissions to it, or unset it (or use --cf-auth profile) to sign in with your browser instead, then run the same command again.`;
+export class LocalCheckupError extends Error {
+    code;
+    hint;
+    /** HTTP status of the Cloudflare or Vigilbase response, when one caused the error. */
+    status;
+    retryAfterSec;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'LocalCheckupError';
+        this.code = code;
+        this.hint = options.hint ?? LOCAL_ERROR_HINTS[code];
+        if (options.status !== undefined)
+            this.status = options.status;
+        if (options.retryAfterSec !== undefined)
+            this.retryAfterSec = options.retryAfterSec;
+    }
+    /** Mapped to exit code 2 by `runCli`. */
+    get isRateLimited() {
+        return this.code === 'CF_RATE_LIMITED' || this.code === 'VIGILBASE_RATE_LIMITED';
+    }
+}
+export function isLocalCheckupError(error) {
+    return error instanceof LocalCheckupError;
+}

package/dist/local/cloudflare-checkup/output.d.ts

@@ -0,0 +1,23 @@
+import type { EntryCounts } from './snapshot-file.js';
+/**
+ * Untrusted single-line text (account names from cf): controls and line
+ * breaks collapsed, length bounded. The terminal UI passes its `ellipsis`
+ * (`...` on an ASCII-only console).
+ */
+export declare function displayText(value: string, max: number, ellipsis?: string): string;
+/** `0123…cdef` (`0123...cdef` with the ASCII `ellipsis` of the terminal UI). */
+export declare function maskId(id: string, ellipsis?: string): string;
+/** `9f2c…a71e` */
+export declare function shortSha(sha256: string): string;
+export declare function formatBytes(bytes: number): string;
+/** Local `HH:MM` for an ISO timestamp. */
+export declare function formatClock(iso: string): string;
+export declare function formatDuration(seconds: number): string;
+/** `3 reads denied (HTTP 403) · 60 reads not collectable with cf` */
+export declare function readsSummary(counts: EntryCounts, denied: number): string;
+export type CountsProgress = {
+    update(text: string): void;
+    stop(): void;
+};
+/** A single updating stderr line, or nothing when progress is disabled. */
+export declare function startCountsProgress(enabled: boolean, stream?: NodeJS.WritableStream): CountsProgress;

package/dist/local/cloudflare-checkup/output.js

@@ -0,0 +1,88 @@
+/**
+ * Terminal formatting for local checkups. Progress shows counts only, never
+ * account or zone names, and is written to stderr. Every other line goes
+ * through the CLI writer, which strips terminal controls from untrusted text.
+ */
+import { sanitizeTerminal } from '../../lib/format.js';
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/**
+ * Untrusted single-line text (account names from cf): controls and line
+ * breaks collapsed, length bounded. The terminal UI passes its `ellipsis`
+ * (`...` on an ASCII-only console).
+ */
+export function displayText(value, max, ellipsis = '…') {
+    const flat = sanitizeTerminal(value.replace(/[\s\u0085\u2028\u2029]+/g, ' ')).trim();
+    return flat.length > max ? `${flat.slice(0, Math.max(0, max - ellipsis.length))}${ellipsis}` : flat;
+}
+/** `0123…cdef` (`0123...cdef` with the ASCII `ellipsis` of the terminal UI). */
+export function maskId(id, ellipsis = '…') {
+    return id.length > 8 ? `${id.slice(0, 4)}${ellipsis}${id.slice(-4)}` : id;
+}
+/** `9f2c…a71e` */
+export function shortSha(sha256) {
+    return `${sha256.slice(0, 4)}…${sha256.slice(-4)}`;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+/** Local `HH:MM` for an ISO timestamp. */
+export function formatClock(iso) {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime()))
+        return iso;
+    return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+export function formatDuration(seconds) {
+    if (seconds < 90)
+        return `~${Math.max(1, Math.round(seconds))} s`;
+    return `~${Math.round(seconds / 60)} min`;
+}
+/** `3 reads denied (HTTP 403) · 60 reads not collectable with cf` */
+export function readsSummary(counts, denied) {
+    const parts = [];
+    if (denied > 0)
+        parts.push(`${denied} ${denied === 1 ? 'read' : 'reads'} denied (HTTP 403)`);
+    const otherHttp = counts.httpError - denied;
+    if (otherHttp > 0)
+        parts.push(`${otherHttp} ${otherHttp === 1 ? 'read' : 'reads'} failed with another HTTP error`);
+    if (counts.collectionFailed > 0)
+        parts.push(`${counts.collectionFailed} ${counts.collectionFailed === 1 ? 'read' : 'reads'} could not be collected`);
+    if (counts.notCollected > 0)
+        parts.push(`${counts.notCollected} reads not collectable with cf`);
+    return parts.join(' · ');
+}
+/** A single updating stderr line, or nothing when progress is disabled. */
+export function startCountsProgress(enabled, stream = process.stderr) {
+    if (!enabled)
+        return { update: () => undefined, stop: () => undefined };
+    let text = '';
+    let frame = 0;
+    let closed = false;
+    let width = 0;
+    const draw = () => {
+        if (closed)
+            return;
+        const line = `${SPINNER[frame++ % SPINNER.length]} ${sanitizeTerminal(text).replace(/[\n\t]/g, ' ')}`;
+        width = Math.max(width, line.length);
+        stream.write(`\r${line.padEnd(width)}`);
+    };
+    const timer = setInterval(draw, 80);
+    timer.unref?.();
+    return {
+        update(next) {
+            text = next;
+            draw();
+        },
+        stop() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            stream.write(`\r${' '.repeat(width)}\r`);
+        },
+    };
+}

package/dist/local/cloudflare-checkup/prompts.d.ts

@@ -0,0 +1,40 @@
+/** One piped answer is at most this long (an email address is at most 254 bytes). */
+export declare const MAX_ANSWER_BYTES = 256;
+export type PromptIO = {
+    stdin?: NodeJS.ReadableStream;
+    stderr: NodeJS.WritableStream;
+};
+export declare function hasInteractiveInput(stdin: NodeJS.ReadableStream | undefined): boolean;
+/**
+ * A visible one-line prompt on a TTY (account picker, confirmations): the
+ * trimmed answer, or null when the input ended (Ctrl-D) before one.
+ */
+export declare function promptLine(io: PromptIO, label: string): Promise<string | null>;
+/**
+ * One line of piped input, without consuming the next one: whatever follows
+ * the newline is pushed back onto the stream for the next prompt. Bytes past
+ * `MAX_ANSWER_BYTES` are dropped up to the newline, so an overlong line comes
+ * back too long and fails validation. Null at the end of the input.
+ */
+export declare function readPipedLine(stdin: NodeJS.ReadableStream): Promise<string | null>;
+/**
+ * A visible prompt for the email verification. On a terminal it is
+ * `promptLine`; without one the label still goes to stderr and the answer is
+ * one line of piped stdin. Null when the input ended without an answer.
+ */
+export declare function promptAnswer(io: PromptIO, label: string): Promise<string | null>;
+/**
+ * `[y/N]` upload confirmation: an explicit `y` is required. `--yes` (or its
+ * alias `--confirm`) answers yes; without a terminal and without them it is
+ * CONFIRMATION_REQUIRED.
+ */
+export declare function confirmUpload(io: PromptIO, question: string, options: {
+    isConfirmed: boolean;
+    flag?: string;
+}): Promise<boolean>;
+/**
+ * `[Y/n]` question where Enter means yes (installing cf). The caller handles
+ * `--yes` and the no-terminal case; an input that ends before an answer is
+ * CONFIRMATION_REQUIRED.
+ */
+export declare function confirmDefaultYes(io: PromptIO, question: string): Promise<boolean>;