@vigilbase/cli 0.2.0 → 0.2.2

package/dist/lib/one-client.js

@@ -6,6 +6,7 @@ import { z } from 'zod';
 import { validateOneOrigin } from './config.js';
 import { validateStripePortalUrl } from './open-url.js';
 import { parseJsonResponse, requestText } from './network.js';
+import { oneErrorHint } from './one-error-hints.js';
 import { retryAfterSeconds, VigilbaseApiError } from './client.js';
 /**
  * Tools that require Vigilbase One authentication (auth-required scanners).
@@ -84,6 +85,8 @@ export class VigilbaseOneClient {
     config;
     accessToken;
     managed;
+    /** The userinfo endpoint Identity discovery named for the last getSession, if it used Identity. */
+    userinfoEndpoint;
     constructor(config, accessToken, managed = false) {
         this.config = config;
         this.accessToken = accessToken;
@@ -127,9 +130,12 @@ export class VigilbaseOneClient {
         if (errorDetails.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
             message = 'Select a customer with --customer-id <customer UUID> for security commands.';
         }
+        const hint = response.ok ? undefined : oneErrorHint({
+            method: init?.method ?? 'GET', path, status: response.status, code: errorDetails.code, hasCustomerScope: options?.hasCustomerScope,
+        });
         if (response.status === 401 || response.status === 403) {
             throw new VigilbaseApiError(message ||
-                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code });
+                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code, hint });
         }
         if (response.status === 429) {
             throw new VigilbaseApiError(message || 'Rate limit exceeded.', {
@@ -142,7 +148,7 @@ export class VigilbaseOneClient {
         const allowed = options?.allowStatuses ?? [];
         if (!response.ok && !allowed.includes(response.status)) {
             throw new VigilbaseApiError(message ||
-                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code });
+                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code, hint });
         }
         if (!z.record(z.string(), z.unknown()).safeParse(body).success) {
             throw new VigilbaseApiError('Invalid One API response. Expected a JSON object.', { status: response.status });
@@ -157,6 +163,7 @@ export class VigilbaseOneClient {
         const issuer = this.config.authProvider?.issuer ?? (saved?.version === 2 ? saved.one?.issuer : undefined);
         if (issuer) {
             const provider = await identityProvider(this.config, issuer);
+            this.userinfoEndpoint = provider.userinfoEndpoint;
             if (this.managed) {
                 const token = await managedAccessToken(this.config);
                 if (!token)
@@ -283,4 +290,3 @@ export class VigilbaseOneClient {
         }, { allowStatuses: [422] });
     }
 }
-//# sourceMappingURL=one-client.js.map

package/dist/lib/one-error-hints.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI-authored hints for One errors the CLI recognises. They are chosen only
+ * from the request (method, route, whether a customer was selected), the HTTP
+ * status and One's own error codes. One's free-text messages are never shown:
+ * they can describe its configuration.
+ */
+export declare const STAFF_CUSTOMER_SCOPE_HINT = "Vigilbase staff: add --customer-id <uuid>.";
+export declare const PERSONAL_SETTINGS_HINT = "Personal settings belong to each user, so View-as (--customer-id) cannot read them.";
+export declare const BROWSER_SESSION_HINT = "Invitations need a One browser session: manage them at https://one.vigilbase.com.";
+export type OneErrorContext = {
+    method: string;
+    /** The One path the CLI requested, with its query string. */
+    path: string;
+    status: number;
+    code?: string;
+    /** Whether the request named a customer; defaults to a `customerId` query parameter. */
+    hasCustomerScope?: boolean;
+};
+export declare function oneErrorHint(context: OneErrorContext): string | undefined;

package/dist/lib/one-error-hints.js

@@ -0,0 +1,47 @@
+/**
+ * CLI-authored hints for One errors the CLI recognises. They are chosen only
+ * from the request (method, route, whether a customer was selected), the HTTP
+ * status and One's own error codes. One's free-text messages are never shown:
+ * they can describe its configuration.
+ */
+export const STAFF_CUSTOMER_SCOPE_HINT = 'Vigilbase staff: add --customer-id <uuid>.';
+export const PERSONAL_SETTINGS_HINT = 'Personal settings belong to each user, so View-as (--customer-id) cannot read them.';
+export const BROWSER_SESSION_HINT = 'Invitations need a One browser session: manage them at https://one.vigilbase.com.';
+/** One's security boundary codes that already explain a 403 (apps/one/src/lib/flarehawk/access.ts). */
+const SECURITY_ACCESS_CODES = new Set([
+    'FLAREHAWK_CUSTOMER_ACCESS_DENIED',
+    'FLAREHAWK_ROLE_UNSUPPORTED',
+    'FLAREHAWK_ROLE_INSUFFICIENT',
+    'FLAREHAWK_ORGANIZATION_REQUIRED',
+    'FLAREHAWK_VIEW_AS_REQUIRED',
+]);
+const RULES = [
+    // Staff sessions must name the customer; One answers 400 without one.
+    { method: 'GET', route: /^\/api\/support\/tickets$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'GET', route: /^\/api\/services\/cloudflare\/checkups$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'POST', route: /^\/api\/services\/cloudflare\/checkups\/start$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    { method: 'GET', route: /^\/api\/services\/cloudflare\/workspace(?:\/[a-z-]+)?$/u, status: 400, hasCustomerScope: false, hint: STAFF_CUSTOMER_SCOPE_HINT },
+    // Personal security settings are per user; a View-as read is refused.
+    {
+        method: 'GET',
+        route: /^\/api\/flarehawk\/(?:settings\/(?:lifecycle-emails|broadcast-emails)|integrations\/grants|notifications\/preferences)$/u,
+        status: 403,
+        hasCustomerScope: true,
+        hint: PERSONAL_SETTINGS_HINT,
+        excludedCodes: SECURITY_ACCESS_CODES,
+    },
+    // Identity's management API accepts only One browser sessions, so CLI tokens can't read or send invitations.
+    { method: 'GET', route: /^\/api\/auth\/orgs\/invitations$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
+    { method: 'POST', route: /^\/api\/auth\/orgs\/invite$/u, status: 403, hasCustomerScope: false, hint: BROWSER_SESSION_HINT, code: 'browser_session_required' },
+];
+export function oneErrorHint(context) {
+    const [pathname = '', query = ''] = context.path.split('?', 2);
+    const hasCustomerScope = context.hasCustomerScope ?? new URLSearchParams(query).has('customerId');
+    const method = context.method.toUpperCase();
+    return RULES.find((rule) => rule.method === method &&
+        rule.status === context.status &&
+        rule.hasCustomerScope === hasCustomerScope &&
+        rule.route.test(pathname) &&
+        (rule.code === undefined || rule.code === context.code) &&
+        !(context.code !== undefined && rule.excludedCodes?.has(context.code)))?.hint;
+}

package/dist/lib/one-operations.d.ts

@@ -8,4 +8,3 @@ export interface OneOperation {
 export declare function executeOneOperation(client: VigilbaseOneClient, operation: OneOperation): Promise<Record<string, unknown>>;
 /** Render all fields, including pagination and degraded-health metadata. */
 export declare function formatOnePayload(value: unknown, indent?: string): string[];
-//# sourceMappingURL=one-operations.d.ts.map

package/dist/lib/one-operations.js

@@ -64,4 +64,3 @@ export function formatOnePayload(value, indent = '') {
         return [`${indent}${safeText(key)}: ${safeText(item)}`];
     });
 }
-//# sourceMappingURL=one-operations.js.map

package/dist/lib/open-url.d.ts

@@ -24,4 +24,3 @@ export declare function resolveDeviceVerificationUrl(oneBaseUrl: string, device:
     verification_uri?: string;
     verification_uri_complete?: string;
 }): string;
-//# sourceMappingURL=open-url.d.ts.map

package/dist/lib/open-url.js

@@ -110,4 +110,3 @@ export function resolveDeviceVerificationUrl(oneBaseUrl, device) {
     // redirect parameters, fragments, or paths, even when they share One's origin.
     return fallback;
 }
-//# sourceMappingURL=open-url.js.map

package/dist/lib/platform.d.ts

@@ -0,0 +1,2 @@
+/** The host platform. A function rather than a constant so tests can simulate Windows. */
+export declare function platform(): NodeJS.Platform;

package/dist/lib/platform.js

@@ -0,0 +1,4 @@
+/** The host platform. A function rather than a constant so tests can simulate Windows. */
+export function platform() {
+    return process.platform;
+}

package/dist/lib/progress.d.ts

@@ -17,4 +17,3 @@ export declare function shouldShowProgress(mode: 'text' | 'json', env?: NodeJS.P
 }): boolean;
 /** Tiny helper so call sites stay readable. */
 export declare function withProgress<T>(label: string, mode: 'text' | 'json', work: () => Promise<T>, writer?: Writer): Promise<T>;
-//# sourceMappingURL=progress.d.ts.map

package/dist/lib/progress.js

@@ -77,4 +77,3 @@ export async function withProgress(label, mode, work, writer) {
         throw error;
     }
 }
-//# sourceMappingURL=progress.js.map

package/dist/lib/security-client.d.ts

@@ -276,4 +276,3 @@ export declare class SecurityClient {
     constructor(one: VigilbaseOneClient);
     request(input: SecurityRequest): Promise<SecurityPayload>;
 }
-//# sourceMappingURL=security-client.d.ts.map

package/dist/lib/security-client.js

@@ -108,4 +108,3 @@ export class SecurityClient {
         return payload;
     }
 }
-//# sourceMappingURL=security-client.js.map

package/dist/lib/skill-fetch.d.ts

@@ -4,4 +4,3 @@ export declare function isPublicSkillAddress(address: string): boolean;
 export declare function validateSkillUrl(raw: string): URL;
 /** Resolve once, reject mixed private/public DNS, and pin the validated address to TLS. */
 export declare function fetchSkillText(config: CliConfig, raw: string): Promise<string>;
-//# sourceMappingURL=skill-fetch.d.ts.map

package/dist/lib/skill-fetch.js

@@ -99,4 +99,3 @@ export async function fetchSkillText(config, raw) {
         clearTimeout(timer);
     }
 }
-//# sourceMappingURL=skill-fetch.js.map

package/dist/lib/system-trust.d.ts

@@ -5,4 +5,3 @@ type SystemTrustApi = {
 /** CLI startup only: preserve bundled/extra CAs and add OS-managed trust. */
 export declare function configureSystemTrust(api?: SystemTrustApi): boolean;
 export {};
-//# sourceMappingURL=system-trust.d.ts.map

package/dist/lib/system-trust.js

@@ -8,4 +8,3 @@ export function configureSystemTrust(api = tls) {
     ]);
     return true;
 }
-//# sourceMappingURL=system-trust.js.map

package/dist/lib/tui.d.ts

@@ -306,4 +306,3 @@ export declare function wasRendered(error: unknown): boolean;
  * own. Leading spaces (an indented line) are kept on every line.
  */
 export declare function wrapWords(text: string, width: number): string[];
-//# sourceMappingURL=tui.d.ts.map

package/dist/lib/tui.js

@@ -844,4 +844,3 @@ function tail(text, width) {
         used += charWidth(chars[--start]);
     return chars.slice(start).join('');
 }
-//# sourceMappingURL=tui.js.map

package/dist/local/cloudflare-checkup/cf/allowlist.d.ts

@@ -92,4 +92,3 @@ export declare function loginArgv(profile: string, scopes: readonly string[], op
  */
 export declare function logoutArgv(profile: string): string[];
 export {};
-//# sourceMappingURL=allowlist.d.ts.map

package/dist/local/cloudflare-checkup/cf/allowlist.js

@@ -181,4 +181,3 @@ export function loginArgv(profile, scopes, options) {
 export function logoutArgv(profile) {
     return ['auth', 'delete', validateProfileName(profile)];
 }
-//# sourceMappingURL=allowlist.js.map

package/dist/local/cloudflare-checkup/cf/auth-lifecycle.d.ts

@@ -110,4 +110,3 @@ export declare class CfScheduler {
 }
 /** `null` for a clean exit; otherwise the classified failure. */
 export declare function toFailure(result: CfProcessResult): CfCallFailure | null;
-//# sourceMappingURL=auth-lifecycle.d.ts.map

package/dist/local/cloudflare-checkup/cf/auth-lifecycle.js

@@ -310,4 +310,3 @@ export function toFailure(result) {
     }
     return classified;
 }
-//# sourceMappingURL=auth-lifecycle.js.map

package/dist/local/cloudflare-checkup/cf/child-env.d.ts

@@ -29,4 +29,3 @@ export declare function childEnvVariableNames(parent: NodeJS.ProcessEnv, authMod
 /** Shown in profile and default modes when the token variable is set in the parent shell. */
 export declare function strippedTokenNotice(authMode: CfAuthMode): string;
 export declare function missingEnvTokenMessage(): string;
-//# sourceMappingURL=child-env.d.ts.map

package/dist/local/cloudflare-checkup/cf/child-env.js

@@ -78,4 +78,3 @@ export function strippedTokenNotice(authMode) {
 export function missingEnvTokenMessage() {
     return `--cf-auth env requires ${CF_TOKEN_ENV} in this shell. cf reads it itself; the Vigilbase CLI only passes it through by name.`;
 }
-//# sourceMappingURL=child-env.js.map

package/dist/local/cloudflare-checkup/cf/install.d.ts

@@ -103,4 +103,3 @@ export declare function removeManagedCf(configDir: string): Promise<{
     path: string;
     removed: boolean;
 }>;
-//# sourceMappingURL=install.d.ts.map

package/dist/local/cloudflare-checkup/cf/install.js

@@ -306,4 +306,3 @@ export async function removeManagedCf(configDir) {
     await rm(root, { recursive: true, force: true });
     return { path: root, removed: true };
 }
-//# sourceMappingURL=install.js.map

package/dist/local/cloudflare-checkup/cf/locate.d.ts

@@ -41,4 +41,3 @@ export type CfVersionInfo = {
 };
 /** Gate the version cf prints against its package.json and `CF_SUPPORTED`. */
 export declare function checkCfVersion(printed: string, packageVersion: string): CfVersionInfo;
-//# sourceMappingURL=locate.d.ts.map

package/dist/local/cloudflare-checkup/cf/locate.js

@@ -225,4 +225,3 @@ export function checkCfVersion(printed, packageVersion) {
     }
     return { version, tested: CF_SUPPORTED.tested.includes(version) };
 }
-//# sourceMappingURL=locate.js.map

package/dist/local/cloudflare-checkup/cf/run-cf.d.ts

@@ -86,4 +86,3 @@ export declare function parseCfJson(stdout: string, shape: 'array' | 'object'):
 } | {
     ok: false;
 };
-//# sourceMappingURL=run-cf.d.ts.map

package/dist/local/cloudflare-checkup/cf/run-cf.js

@@ -272,4 +272,3 @@ export function parseCfJson(stdout, shape) {
         return { ok: true, value };
     return { ok: false };
 }
-//# sourceMappingURL=run-cf.js.map

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

@@ -45,4 +45,3 @@ export declare function buildSnapshot(accountId: string, collector: SnapshotColl
     snapshot: CloudflareCheckupSnapshotV1;
     text: string;
 };
-//# sourceMappingURL=collector.d.ts.map

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

@@ -293,4 +293,3 @@ export function buildSnapshot(accountId, collector, entries) {
     }
     return { snapshot: parsed.data, text };
 }
-//# sourceMappingURL=collector.js.map

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

@@ -33,6 +33,8 @@ export declare const SESSION_CODE_REGEX: RegExp;
 export declare const PRODUCTION_ORIGIN: "https://vigilbase.com";
 export declare const LOCAL_SESSION_PATH: "/api/v1/tools/cloudflare-checkup/local-session";
 export declare const LOCAL_SNAPSHOT_PATH: "/api/v1/tools/cloudflare-checkup/local-session/snapshot";
+/** Before asking for an email, the CLI checks that local checkups are on and what they accept (no auth, no side effects). */
+export declare const LOCAL_AVAILABILITY_PATH: "/api/v1/tools/cloudflare-checkup/local-session/availability";
 /** The CLI asks vigilbase.com to email a verification code (no browser, no Turnstile). */
 export declare const LOCAL_REQUEST_PATH: "/api/v1/tools/cloudflare-checkup/local-session/request";
 /** The CLI trades the verification token and the emailed code for a session code. */
@@ -2707,6 +2709,15 @@ export declare const LocalSessionResponseSchema: z.ZodObject<{
         minCliVersion: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const LocalAvailabilityResponseSchema: z.ZodObject<{
+    enabled: z.ZodLiteral<true>;
+    minCliVersion: z.ZodString;
+    accepts: z.ZodObject<{
+        schemaVersions: z.ZodArray<z.ZodString>;
+        maxBytes: z.ZodNumber;
+        maxZones: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export declare const LocalSnapshotResponseSchema: z.ZodObject<{
     success: z.ZodLiteral<true>;
     replayed: z.ZodBoolean;
@@ -2749,6 +2760,8 @@ export declare const LocalErrorResponseSchema: z.ZodObject<{
     code: z.ZodString;
     reason: z.ZodOptional<z.ZodEnum<{
         rate_limited: "rate_limited";
+        length_required: "length_required";
+        unsupported_media_type: "unsupported_media_type";
         snapshot_invalid: "snapshot_invalid";
         snapshot_incomplete: "snapshot_incomplete";
         secret_like_value: "secret_like_value";
@@ -2761,8 +2774,6 @@ export declare const LocalErrorResponseSchema: z.ZodObject<{
         browser_origin: "browser_origin";
         malformed_json: "malformed_json";
         digest_mismatch: "digest_mismatch";
-        unsupported_media_type: "unsupported_media_type";
-        length_required: "length_required";
         snapshot_too_large: "snapshot_too_large";
         account_mismatch: "account_mismatch";
         snapshot_stale: "snapshot_stale";
@@ -2783,6 +2794,7 @@ export declare const LocalErrorResponseSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type LocalSessionResponse = z.infer<typeof LocalSessionResponseSchema>;
+export type LocalAvailabilityResponse = z.infer<typeof LocalAvailabilityResponseSchema>;
 export type LocalSnapshotResponse = z.infer<typeof LocalSnapshotResponseSchema>;
 export type LocalErrorResponse = z.infer<typeof LocalErrorResponseSchema>;
 export type LocalRequestBody = z.infer<typeof LocalRequestBodySchema>;
@@ -2790,4 +2802,3 @@ export type LocalVerifyBody = z.infer<typeof LocalVerifyBodySchema>;
 export type LocalRequestResponse = z.infer<typeof LocalRequestResponseSchema>;
 export type LocalVerifyResponse = z.infer<typeof LocalVerifyResponseSchema>;
 export {};
-//# sourceMappingURL=contract.d.ts.map

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

@@ -37,6 +37,8 @@ export const SESSION_CODE_REGEX = /^vbcs1_[A-Za-z0-9_-]{66}$/;
 export const PRODUCTION_ORIGIN = 'https://vigilbase.com';
 export const LOCAL_SESSION_PATH = '/api/v1/tools/cloudflare-checkup/local-session';
 export const LOCAL_SNAPSHOT_PATH = '/api/v1/tools/cloudflare-checkup/local-session/snapshot';
+/** Before asking for an email, the CLI checks that local checkups are on and what they accept (no auth, no side effects). */
+export const LOCAL_AVAILABILITY_PATH = '/api/v1/tools/cloudflare-checkup/local-session/availability';
 /** The CLI asks vigilbase.com to email a verification code (no browser, no Turnstile). */
 export const LOCAL_REQUEST_PATH = '/api/v1/tools/cloudflare-checkup/local-session/request';
 /** The CLI trades the verification token and the emailed code for a session code. */
@@ -1586,12 +1588,17 @@ export const LOCAL_ERROR_REASONS = ['session_invalid', 'session_expired', 'sessi
     'collector_unsupported', 'secret_like_value', 'evaluation_failed', 'rate_limited', 'local_mode_disabled', 'storage_unavailable',
     'request_invalid', 'email_invalid', 'code_invalid', 'verification_invalid', 'verification_expired'];
 export const LOCAL_SESSION_STATES = ['awaiting_upload', 'processing', 'completed'];
+const LocalAcceptsSchema = z.object({ schemaVersions: z.array(z.string()).min(1), maxBytes: z.number().int().positive(),
+    maxZones: z.number().int().positive() });
 // `accountId` is null until an uploaded snapshot binds the run (the CLI chooses the account); runs created
 // with an account keep it, and a completed run reports the evaluated account.
 export const LocalSessionResponseSchema = z.object({ success: z.literal(true), session: z.object({ accountId: hex32.nullable(),
         requester: z.string().max(260), expiresAt: iso, state: z.enum(LOCAL_SESSION_STATES),
-        accepts: z.object({ schemaVersions: z.array(z.string()).min(1), maxBytes: z.number().int().positive(),
-            maxZones: z.number().int().positive() }), minCliVersion: semver }) });
+        accepts: LocalAcceptsSchema, minCliVersion: semver }) });
+// `GET local-session/availability`: local checkups are on, with what a checkup would accept. While they are
+// off it answers 503 `local_mode_disabled`, like every local-session route.
+export const LocalAvailabilityResponseSchema = z.object({ enabled: z.literal(true), minCliVersion: semver,
+    accepts: LocalAcceptsSchema });
 // `resultsUrl` is the run's results page; the CLI opens it only when it is on the upload origin.
 export const LocalSnapshotResponseSchema = z.object({ success: z.literal(true), replayed: z.boolean(),
     snapshotSha256: z.string().regex(/^[0-9a-f]{64}$/),
@@ -1611,4 +1618,3 @@ export const LocalVerifyResponseSchema = z.object({ success: z.literal(true), se
 export const LocalErrorResponseSchema = z.object({ success: z.literal(false), status: z.number().int(), code: z.string(),
     reason: z.enum(LOCAL_ERROR_REASONS).optional(), retryAfterSec: z.number().int().nonnegative().optional(),
     issues: z.array(z.object({ path: z.string().max(200), code: z.string().max(64) })).max(20).optional() });
-//# sourceMappingURL=contract.js.map

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

@@ -122,4 +122,3 @@ export declare const SAME_ADDRESS_WAIT = "The same address can get a new code 8
  * same address would be refused for 8 minutes.
  */
 export declare function verifyEmail(options: EmailVerificationOptions): Promise<VerifiedEmail>;
-//# sourceMappingURL=email-verification.d.ts.map

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

@@ -209,4 +209,3 @@ export async function verifyEmail(options) {
         }
     }
 }
-//# sourceMappingURL=email-verification.js.map

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

@@ -1,5 +1,7 @@
 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>;
 /**
@@ -8,6 +10,8 @@ export declare const LOCAL_ERROR_HINTS: Record<LocalCheckupErrorCode, string>;
  * 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.";
+/** SNAPSHOT_INVALID for an `inspect` or `submit` path with no file: nothing to collect again, so how to make one. */
+export declare const SNAPSHOT_MISSING_HINT = "Check the file path. To collect a snapshot into a file, run `npx @vigilbase/cli cloudflare-checkup collect --out <file>`.";
 /** 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 {
@@ -25,4 +29,3 @@ export declare class LocalCheckupError extends Error {
     get isRateLimited(): boolean;
 }
 export declare function isLocalCheckupError(error: unknown): error is LocalCheckupError;
-//# sourceMappingURL=errors.d.ts.map

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

@@ -8,6 +8,7 @@
  * 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',
@@ -25,6 +26,10 @@ export const LOCAL_ERROR_CODES = [
     '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.',
@@ -59,7 +64,7 @@ export const LOCAL_ERROR_HINTS = {
     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: 'Local checkups are temporarily unavailable. Use the browser token mode on vigilbase.com, or try later.',
+    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.',
@@ -70,6 +75,8 @@ export const LOCAL_ERROR_HINTS = {
  * 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.`;
+/** SNAPSHOT_INVALID for an `inspect` or `submit` path with no file: nothing to collect again, so how to make one. */
+export const SNAPSHOT_MISSING_HINT = 'Check the file path. To collect a snapshot into a file, run `npx @vigilbase/cli cloudflare-checkup collect --out <file>`.';
 /** 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 {
@@ -96,4 +103,3 @@ export class LocalCheckupError extends Error {
 export function isLocalCheckupError(error) {
     return error instanceof LocalCheckupError;
 }
-//# sourceMappingURL=errors.js.map

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

@@ -21,4 +21,3 @@ export type CountsProgress = {
 };
 /** A single updating stderr line, or nothing when progress is disabled. */
 export declare function startCountsProgress(enabled: boolean, stream?: NodeJS.WritableStream): CountsProgress;
-//# sourceMappingURL=output.d.ts.map

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

@@ -86,4 +86,3 @@ export function startCountsProgress(enabled, stream = process.stderr) {
         },
     };
 }
-//# sourceMappingURL=output.js.map

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

@@ -38,4 +38,3 @@ export declare function confirmUpload(io: PromptIO, question: string, options: {
  * CONFIRMATION_REQUIRED.
  */
 export declare function confirmDefaultYes(io: PromptIO, question: string): Promise<boolean>;
-//# sourceMappingURL=prompts.d.ts.map

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

@@ -137,4 +137,3 @@ export async function confirmDefaultYes(io, question) {
 function inputEnded(message) {
     return new LocalCheckupError('CONFIRMATION_REQUIRED', message, { hint: 'Run the same command again and answer the question, or add --yes.' });
 }
-//# sourceMappingURL=prompts.js.map

package/dist/local/cloudflare-checkup/rate-budget.d.ts

@@ -39,4 +39,3 @@ export declare class RequestBudget {
 }
 /** Seconds a full bucket needs to admit `requests` calls at `limit` per 5 minutes. */
 export declare function estimateBudgetSeconds(limit: number, requests: number, burst?: number): number;
-//# sourceMappingURL=rate-budget.d.ts.map

package/dist/local/cloudflare-checkup/rate-budget.js

@@ -77,4 +77,3 @@ export class RequestBudget {
 export function estimateBudgetSeconds(limit, requests, burst = BUDGET_BURST) {
     return Math.max(0, ((requests - burst) * BUDGET_WINDOW_MS) / (limit - burst) / 1000);
 }
-//# sourceMappingURL=rate-budget.js.map

package/dist/local/cloudflare-checkup/snapshot-file.d.ts

@@ -50,4 +50,3 @@ export type DataCategories = {
 export declare function dataCategories(snapshot: CloudflareCheckupSnapshotV1): DataCategories;
 export declare function zoneCount(snapshot: CloudflareCheckupSnapshotV1): number;
 export declare function accountName(snapshot: CloudflareCheckupSnapshotV1): string | null;
-//# sourceMappingURL=snapshot-file.d.ts.map

package/dist/local/cloudflare-checkup/snapshot-file.js

@@ -13,7 +13,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { link, open, readFile, rename, rm, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { CloudflareCheckupSnapshotV1Schema, SNAPSHOT_LIMITS, SNAPSHOT_SCHEMA_VERSION, expandRuleRuns, snapshotIssueList, snapshotRejectReason, } from './contract.js';
-import { LocalCheckupError } from './errors.js';
+import { LocalCheckupError, SNAPSHOT_MISSING_HINT } from './errors.js';
 export function sha256Hex(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
@@ -90,8 +90,10 @@ export function snapshotParseError(issues) {
 /** Read, hash and validate a snapshot file against the vendored contract. */
 export async function loadSnapshotFile(path) {
     const info = await stat(path).catch(() => null);
-    if (!info || !info.isFile())
-        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file does not exist or is not a regular file.');
+    if (!info)
+        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file does not exist.', { hint: SNAPSHOT_MISSING_HINT });
+    if (!info.isFile())
+        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot path is not a file.', { hint: SNAPSHOT_MISSING_HINT });
     if (info.size > SNAPSHOT_LIMITS.maxBytes) {
         throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', `The snapshot is larger than the ${SNAPSHOT_LIMITS.maxBytes / 1024 / 1024} MiB contract limit.`);
     }
@@ -183,4 +185,3 @@ export function accountName(snapshot) {
     const account = snapshot.entries.find((entry) => entry.kind === 'account');
     return account && account.kind === 'account' && account.result.ok ? account.result.data.name : null;
 }
-//# sourceMappingURL=snapshot-file.js.map

package/dist/local/cloudflare-checkup/submit-client.d.ts

@@ -1,20 +1,26 @@
-import { type LocalRequestBody, type LocalRequestResponse, type LocalSessionResponse, type LocalVerifyBody, type LocalVerifyResponse } from './contract.js';
+import { type LocalAvailabilityResponse, type LocalRequestBody, type LocalRequestResponse, type LocalSessionResponse, type LocalVerifyBody, type LocalVerifyResponse } from './contract.js';
 /**
  * `GET local-session`. The account is chosen in the CLI and bound by the
  * uploaded snapshot, so `accountId` is `null` until then; runs created before
  * that change still carry their bound account.
  */
 export type LocalSession = LocalSessionResponse['session'];
+/** `GET local-session/availability`: local checkups are on, with the oldest CLI and the snapshots vigilbase.com accepts. */
+export type LocalAvailability = LocalAvailabilityResponse;
 /** `POST local-session/request`: the token naming the run that awaits its emailed code. */
 export type PendingVerification = LocalRequestResponse['verification'];
 /** `POST local-session/verify`: the session code for the upload (kept in memory only). */
 export type VerifiedSession = LocalVerifyResponse['session'];
 export declare const GET_TIMEOUT_MS = 30000;
+/** The availability check is skipped (the run goes on) when vigilbase.com does not answer it within this. */
+export declare const AVAILABILITY_TIMEOUT_MS = 10000;
 export declare const POST_TIMEOUT_MS = 120000;
 export declare const MAX_SUBMIT_RESPONSE_BYTES: number;
 export declare const POST_RETRY_DELAYS_MS: readonly [2000, 5000];
 /** A verify that failed on the network or with a 503 is sent once more, after this pause. */
 export declare const VERIFY_RETRY_DELAYS_MS: readonly [2000];
+/** True for http(s) loopback origins (local development), the only ones besides production that `--base-url` accepts. */
+export declare function isLoopbackOrigin(origin: string): boolean;
 /**
  * The submit origin. Only `https://vigilbase.com` and loopback origins are
  * accepted; there is no `*.vigilbase.com` wildcard (other subdomains are
@@ -52,7 +58,8 @@ declare abstract class LocalHttpClient {
     }>;
 }
 /**
- * Email verification without a bearer. A code request is never retried: a
+ * The requests before the session code, without a bearer: the availability
+ * check and the email verification. A code request is never retried: a
  * repeated request would send a second email. A verify that failed on the
  * network (or timed out) or with a 503 is sent once more, after 2 s, with the
  * same token and code: One counts only wrong codes, and the right code
@@ -61,6 +68,14 @@ declare abstract class LocalHttpClient {
  */
 export declare class VerificationClient extends LocalHttpClient {
     private postJson;
+    /**
+     * `GET local-session/availability`, before the email is asked for: what
+     * vigilbase.com accepts, or null when it gave no usable answer (a 404 from a
+     * server without the route, a network error, a timeout, a challenge or any
+     * other response), and the run goes on as before. Throws LOCAL_MODE_DISABLED
+     * when it answers that local checkups are switched off. Never retried.
+     */
+    availability(): Promise<LocalAvailability | null>;
     /** `POST local-session/request`: vigilbase.com emails a 6-digit code and returns the token for it. */
     requestCode(body: LocalRequestBody): Promise<PendingVerification>;
     /** `POST local-session/verify`: trades the token and the emailed code for a session code (the next one on every call). */
@@ -87,12 +102,11 @@ export declare class SubmitClient extends LocalHttpClient {
      */
     postSnapshot(bytes: Buffer, sha256: string): Promise<UploadResult>;
 }
-/** Refuse a server that requires a newer CLI, or does not accept this schema version. */
-export declare function assertSessionAccepts(session: LocalSession, cliVersion: string, schemaVersion: string): void;
+/** Refuse a server (its session, or its availability answer) that requires a newer CLI, or does not accept this schema version. */
+export declare function assertServerAccepts(server: Pick<LocalSession, 'accepts' | 'minCliVersion'>, cliVersion: string, schemaVersion: string): void;
 /**
  * The masked address as the server masks it (first character, `***`, the
  * domain); any other text from the server is replaced by `fallback`.
  */
 export declare function displayRequester(requester: string, fallback?: string): string;
 export {};
-//# sourceMappingURL=submit-client.d.ts.map