@vigilbase/cli 0.2.2 → 0.2.4

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

@@ -1,8 +1,11 @@
+import { CheckupCancelledError, type CancelSignal, type CancelSignalSource } from '../errors.js';
 export declare const CF_CALL_TIMEOUT_MS = 45000;
 export declare const STDOUT_CAP_BYTES: number;
 /** `rulesets get` bodies can be large managed rulesets. */
 export declare const RULESET_STDOUT_CAP_BYTES: number;
 export declare const STDERR_CAP_BYTES: number;
+/** After a cancel, how long withCfRunner waits for `work` to finish (or undo) what it was doing. */
+export declare const WORK_SETTLE_MS = 2000;
 /**
  * Flags that skip confirmations, switch cf to local simulation or project
  * config, or send a request body. No allowlisted argv contains them; the
@@ -30,6 +33,9 @@ export declare class CfProcessRunner {
     readonly privateDir: string;
     private readonly active;
     private disposed;
+    private disposing;
+    /** Set by `cancel`: every pending and later call rejects with it. */
+    private cancelledBy;
     /** Set once the runner kills its children (abort or shutdown), so those kills are not read as timeouts. */
     private terminating;
     private constructor();
@@ -46,13 +52,22 @@ export declare class CfProcessRunner {
     get activeCount(): number;
     /** SIGTERM every live child, then SIGKILL whatever is still running after 2 s. */
     terminateAll(): Promise<void>;
+    /** Stop every child and remove the private directory; every caller waits for the same cleanup. */
     dispose(): Promise<void>;
+    /** The run was interrupted by `signal`: calls reject with CANCELLED from now on, then everything is disposed. */
+    cancel(signal: CancelSignal): Promise<void>;
+    get cancellation(): CheckupCancelledError | null;
 }
 /**
- * Run `work` with a private cf runner; the directory is removed afterwards and
- * on SIGINT, when live children get SIGTERM and then SIGKILL.
+ * Run `work` with a private cf runner; the directory is removed afterwards.
+ * On SIGINT, SIGTERM or SIGHUP live children get SIGTERM (then SIGKILL), and
+ * this rejects with CANCELLED (`CheckupCancelledError`) once the directory is
+ * gone and `work` has settled (every cf call rejects by then; whatever else it
+ * waits on gets WORK_SETTLE_MS), so no result of a cancelled run is printed and
+ * nothing `work` writes lands after CANCELLED. `work` checks `runner.cancellation`
+ * before (and after) writing anything.
  */
-export declare function withCfRunner<T>(entry: string, work: (runner: CfProcessRunner) => Promise<T>): Promise<T>;
+export declare function withCfRunner<T>(entry: string, work: (runner: CfProcessRunner) => Promise<T>, signals?: CancelSignalSource): Promise<T>;
 export type CfFailure = {
     kind: 'node_unsupported';
 } | {

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

@@ -12,6 +12,7 @@ import { chmod, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
+import { CANCEL_SIGNALS, CheckupCancelledError } from '../errors.js';
 import { CF_TOKEN_ENV } from './child-env.js';
 export const CF_CALL_TIMEOUT_MS = 45_000;
 export const STDOUT_CAP_BYTES = 8 * 1024 * 1024;
@@ -19,6 +20,8 @@ export const STDOUT_CAP_BYTES = 8 * 1024 * 1024;
 export const RULESET_STDOUT_CAP_BYTES = 16 * 1024 * 1024;
 export const STDERR_CAP_BYTES = 64 * 1024;
 const KILL_GRACE_MS = 2_000;
+/** After a cancel, how long withCfRunner waits for `work` to finish (or undo) what it was doing. */
+export const WORK_SETTLE_MS = 2_000;
 /**
  * Flags that skip confirmations, switch cf to local simulation or project
  * config, or send a request body. No allowlisted argv contains them; the
@@ -38,6 +41,9 @@ export class CfProcessRunner {
     privateDir;
     active = new Set();
     disposed = false;
+    disposing = null;
+    /** Set by `cancel`: every pending and later call rejects with it. */
+    cancelledBy = null;
     /** Set once the runner kills its children (abort or shutdown), so those kills are not read as timeouts. */
     terminating = false;
     constructor(entry, privateDir) {
@@ -51,11 +57,13 @@ export class CfProcessRunner {
     }
     run(argv, options) {
         assertSafeCfArgv(argv);
+        if (this.cancelledBy)
+            return Promise.reject(this.cancelledBy);
         if (this.disposed)
             return Promise.resolve(failedToStart());
         const timeoutMs = options.timeoutMs ?? CF_CALL_TIMEOUT_MS;
         const stdoutCap = options.stdoutCapBytes ?? STDOUT_CAP_BYTES;
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             let child;
             try {
                 child = spawn(process.execPath, [this.entry, ...argv], {
@@ -112,6 +120,10 @@ export class CfProcessRunner {
                 settled = true;
                 clearTimeout(timer);
                 this.active.delete(child);
+                if (this.cancelledBy) {
+                    reject(this.cancelledBy);
+                    return;
+                }
                 // A child killed by a signal we did not send for the stdout cap or a
                 // shutdown was killed by the spawn timeout.
                 if (signal !== null && !stdoutTooLarge && !this.terminating)
@@ -136,6 +148,8 @@ export class CfProcessRunner {
      */
     runInteractive(argv, env, options = {}) {
         assertSafeCfArgv(argv);
+        if (this.cancelledBy)
+            return Promise.reject(this.cancelledBy);
         return new Promise((resolve, reject) => {
             const child = spawn(process.execPath, [this.entry, ...argv], {
                 shell: false, cwd: this.privateDir, env, stdio: ['inherit', options.stdoutToStderr ? 2 : 'inherit', 'inherit'], windowsHide: true,
@@ -147,7 +161,10 @@ export class CfProcessRunner {
             });
             child.once('close', (code) => {
                 this.active.delete(child);
-                resolve(typeof code === 'number' ? code : 1);
+                if (this.cancelledBy)
+                    reject(this.cancelledBy);
+                else
+                    resolve(typeof code === 'number' ? code : 1);
             });
         });
     }
@@ -178,32 +195,73 @@ export class CfProcessRunner {
             }, () => undefined);
         });
     }
-    async dispose() {
-        if (this.disposed)
-            return;
-        this.disposed = true;
-        await this.terminateAll();
-        await rm(this.privateDir, { recursive: true, force: true });
+    /** Stop every child and remove the private directory; every caller waits for the same cleanup. */
+    dispose() {
+        this.disposing ??= (async () => {
+            this.disposed = true;
+            await this.terminateAll();
+            await rm(this.privateDir, { recursive: true, force: true });
+        })();
+        return this.disposing;
+    }
+    /** The run was interrupted by `signal`: calls reject with CANCELLED from now on, then everything is disposed. */
+    cancel(signal) {
+        this.cancelledBy ??= new CheckupCancelledError(signal);
+        return this.dispose();
+    }
+    get cancellation() {
+        return this.cancelledBy;
     }
 }
 function failedToStart() {
     return { exitCode: null, stdout: '', stderr: '', timedOut: false, stdoutTooLarge: false, spawnFailed: true };
 }
+/** Wait for `promise` to settle, at most `ms`. */
+async function settleWithin(promise, ms) {
+    let timer;
+    await Promise.race([
+        promise.then(() => undefined, () => undefined),
+        new Promise((resolve) => { timer = setTimeout(resolve, ms); }),
+    ]);
+    clearTimeout(timer);
+}
 /**
- * Run `work` with a private cf runner; the directory is removed afterwards and
- * on SIGINT, when live children get SIGTERM and then SIGKILL.
+ * Run `work` with a private cf runner; the directory is removed afterwards.
+ * On SIGINT, SIGTERM or SIGHUP live children get SIGTERM (then SIGKILL), and
+ * this rejects with CANCELLED (`CheckupCancelledError`) once the directory is
+ * gone and `work` has settled (every cf call rejects by then; whatever else it
+ * waits on gets WORK_SETTLE_MS), so no result of a cancelled run is printed and
+ * nothing `work` writes lands after CANCELLED. `work` checks `runner.cancellation`
+ * before (and after) writing anything.
  */
-export async function withCfRunner(entry, work) {
+export async function withCfRunner(entry, work, signals = process) {
     const runner = await CfProcessRunner.create(entry);
-    const onSignal = () => {
-        void runner.dispose().finally(() => process.exit(130));
-    };
-    process.once('SIGINT', onSignal);
+    let interrupt = () => undefined;
+    const interrupted = new Promise((_resolve, reject) => { interrupt = reject; });
+    const listeners = CANCEL_SIGNALS.map((signal) => {
+        const listener = () => {
+            runner.cancel(signal).catch(() => undefined);
+            interrupt(runner.cancellation);
+        };
+        signals.on(signal, listener);
+        return { signal, listener };
+    });
+    let working;
     try {
-        return await work(runner);
+        working = work(runner);
+        const result = await Promise.race([working, interrupted]);
+        if (runner.cancellation)
+            throw runner.cancellation;
+        return result;
+    }
+    catch (error) {
+        if (runner.cancellation && working)
+            await settleWithin(working, WORK_SETTLE_MS);
+        throw runner.cancellation ?? error;
     }
     finally {
-        process.removeListener('SIGINT', onSignal);
+        for (const { signal, listener } of listeners)
+            signals.removeListener(signal, listener);
         await runner.dispose();
     }
 }

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

@@ -205,9 +205,9 @@ export declare const RulesetDetailData: z.ZodObject<{
 export declare const PageRuleData: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodEnum<{
-            waf: "waf";
             security_level: "security_level";
             browser_check: "browser_check";
+            waf: "waf";
             disable_security: "disable_security";
             disable_performance: "disable_performance";
         }>;
@@ -560,7 +560,6 @@ export declare const SnapshotEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"zone_setting">;
     zoneId: z.ZodString;
     settingId: z.ZodEnum<{
-        waf: "waf";
         ssl: "ssl";
         always_use_https: "always_use_https";
         min_tls_version: "min_tls_version";
@@ -575,6 +574,7 @@ export declare const SnapshotEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         minify: "minify";
         early_hints: "early_hints";
         rocket_loader: "rocket_loader";
+        waf: "waf";
         automatic_https_rewrites: "automatic_https_rewrites";
         security_header: "security_header";
         opportunistic_encryption: "opportunistic_encryption";
@@ -790,9 +790,9 @@ export declare const SnapshotEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         data: z.ZodArray<z.ZodObject<{
             actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 id: z.ZodEnum<{
-                    waf: "waf";
                     security_level: "security_level";
                     browser_check: "browser_check";
+                    waf: "waf";
                     disable_security: "disable_security";
                     disable_performance: "disable_performance";
                 }>;
@@ -1263,7 +1263,6 @@ declare const SnapshotObjectSchema: z.ZodObject<{
         kind: z.ZodLiteral<"zone_setting">;
         zoneId: z.ZodString;
         settingId: z.ZodEnum<{
-            waf: "waf";
             ssl: "ssl";
             always_use_https: "always_use_https";
             min_tls_version: "min_tls_version";
@@ -1278,6 +1277,7 @@ declare const SnapshotObjectSchema: z.ZodObject<{
             minify: "minify";
             early_hints: "early_hints";
             rocket_loader: "rocket_loader";
+            waf: "waf";
             automatic_https_rewrites: "automatic_https_rewrites";
             security_header: "security_header";
             opportunistic_encryption: "opportunistic_encryption";
@@ -1493,9 +1493,9 @@ declare const SnapshotObjectSchema: z.ZodObject<{
             data: z.ZodArray<z.ZodObject<{
                 actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     id: z.ZodEnum<{
-                        waf: "waf";
                         security_level: "security_level";
                         browser_check: "browser_check";
+                        waf: "waf";
                         disable_security: "disable_security";
                         disable_performance: "disable_performance";
                     }>;
@@ -1962,7 +1962,6 @@ export declare const CloudflareCheckupSnapshotV1Schema: z.ZodObject<{
         kind: z.ZodLiteral<"zone_setting">;
         zoneId: z.ZodString;
         settingId: z.ZodEnum<{
-            waf: "waf";
             ssl: "ssl";
             always_use_https: "always_use_https";
             min_tls_version: "min_tls_version";
@@ -1977,6 +1976,7 @@ export declare const CloudflareCheckupSnapshotV1Schema: z.ZodObject<{
             minify: "minify";
             early_hints: "early_hints";
             rocket_loader: "rocket_loader";
+            waf: "waf";
             automatic_https_rewrites: "automatic_https_rewrites";
             security_header: "security_header";
             opportunistic_encryption: "opportunistic_encryption";
@@ -2192,9 +2192,9 @@ export declare const CloudflareCheckupSnapshotV1Schema: z.ZodObject<{
             data: z.ZodArray<z.ZodObject<{
                 actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     id: z.ZodEnum<{
-                        waf: "waf";
                         security_level: "security_level";
                         browser_check: "browser_check";
+                        waf: "waf";
                         disable_security: "disable_security";
                         disable_performance: "disable_performance";
                     }>;
@@ -2637,6 +2637,12 @@ export declare function createRuleBodyEncoder(): RuleBodyEncoder;
 export interface IpPseudonymizer {
     /** Pseudonymise one A/AAAA content string; memoised by the exact string. */
     pseudonymize(content: string): ProjectionResult<string>;
+    /**
+     * Pseudonymise one record list, all or nothing: when one content fails, the
+     * numbering is left as it was, so later pseudonyms never skip a number
+     * (`validateSnapshotSemantics` rejects a gap).
+     */
+    pseudonymizeAll(contents: readonly string[]): ProjectionResult<string[]>;
 }
 /**
  * Per-prefix sequential pseudonyms, applied in zone list order and record API
@@ -2672,7 +2678,8 @@ export interface AssembleSnapshotInput {
  *    failure in list order) and keeps no `zone_ruleset` entries, so the scanner
  *    never falls back to rule-less heads (874-891).
  * 2. IP pseudonymisation over `zone_dns_records` in zone list order and record
- *    order; a list with unrepresentable content becomes `collection_failed`.
+ *    order; a list with unrepresentable content becomes `collection_failed`
+ *    and uses up no pseudonym numbers.
  * 3. Canonical entry order (`expectedEntryKeys`); unexpected entries go last.
  * 4. Rule bodies encoded and deduplicated in that order.
  * The result is not validated: parse it with `CloudflareCheckupSnapshotV1Schema`.
@@ -2697,9 +2704,9 @@ export declare const LocalSessionResponseSchema: z.ZodObject<{
         requester: z.ZodString;
         expiresAt: z.ZodISODateTime;
         state: z.ZodEnum<{
-            completed: "completed";
             awaiting_upload: "awaiting_upload";
             processing: "processing";
+            completed: "completed";
         }>;
         accepts: z.ZodObject<{
             schemaVersions: z.ZodArray<z.ZodString>;

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

@@ -579,12 +579,60 @@ export function validateSnapshotSemantics(snapshot, ctx) {
     if (!(started <= finished) || finished - started > SNAPSHOT_LIMITS.maxCollectionHours * 3_600_000) {
         issue('collection_window', ['collector', 'finishedAt']);
     }
-    // 6. Credential tripwire over every string (and record key) in the snapshot.
+    // 6. DNS contents are `per_prefix_sequential/1` pseudonyms: each prefix
+    // numbers its addresses 1, 2, 3, … with no gap, so an address that is not a
+    // pseudonym (a real one, or numbers past the count) is rejected.
+    const numbersByPrefix = new Map();
+    entries.forEach((entry, i) => {
+        if (entry.kind !== 'zone_dns_records' || !entry.result.ok)
+            return;
+        entry.result.data.forEach((record, r) => {
+            const path = ['entries', i, 'result', 'data', r, 'content'];
+            const pseudonym = parsePseudonym(record.content);
+            if (pseudonym === null) {
+                issue('ip_not_pseudonymized', path);
+                return;
+            }
+            const numbers = numbersByPrefix.get(pseudonym.prefix) ?? new Map();
+            if (!numbers.has(pseudonym.n))
+                numbers.set(pseudonym.n, path);
+            numbersByPrefix.set(pseudonym.prefix, numbers);
+        });
+    });
+    for (const numbers of numbersByPrefix.values()) {
+        for (const [n, path] of numbers)
+            if (n > numbers.size)
+                issue('ip_not_pseudonymized', path);
+    }
+    // 7. Credential tripwire over every string (and record key) in the snapshot.
     walkStrings(snapshot, [], (value, path) => {
         if (containsSecretLikeValue(value))
             issue('secret_like_value', path, 'secret_like_value');
     });
 }
+const PSEUDONYM_V4_PART_RE = /^(?:0|[1-9][0-9]{0,2})$/;
+const PSEUDONYM_V6_N_RE = /^[1-9a-f][0-9a-f]{0,3}$/;
+/**
+ * The family and prefix (`createIpPseudonymizer`'s counter key) and the number
+ * `n` of a pseudonym, or null when `content` is not one: IPv4 `a.b.${n >> 8}.${n & 255}`
+ * or IPv6 `${g0}:${g1}:${g2}:ffff:${n.toString(16)}`, with 1 <= n <= 65535.
+ */
+function parsePseudonym(content) {
+    if (content.includes(':')) {
+        const groups = content.split(':');
+        if (groups.length !== 5 || groups[3] !== 'ffff' || !PSEUDONYM_V6_N_RE.test(groups[4]))
+            return null;
+        return { prefix: `6|${groups.slice(0, 3).join(':')}`, n: parseInt(groups[4], 16) };
+    }
+    const parts = content.split('.');
+    if (parts.length !== 4 || !PSEUDONYM_V4_PART_RE.test(parts[2]) || !PSEUDONYM_V4_PART_RE.test(parts[3]))
+        return null;
+    const high = Number(parts[2]);
+    const low = Number(parts[3]);
+    if (high > 255 || low > 255 || high + low === 0)
+        return null;
+    return { prefix: `4|${parts[0]}.${parts[1]}`, n: high * 256 + low };
+}
 /**
  * The `wafAnalysis.issues` one reference to a rule body produces under a
  * ruleset phase, and the UTF-8 bytes of the rule text those issues print
@@ -1375,7 +1423,7 @@ const MAX_PSEUDONYMS_PER_PREFIX = 65_535;
 export function createIpPseudonymizer() {
     const memo = new Map();
     const counters = new Map();
-    return {
+    const pseudonymizer = {
         pseudonymize(content) {
             const known = memo.get(content);
             if (known !== undefined)
@@ -1411,7 +1459,29 @@ export function createIpPseudonymizer() {
             memo.set(content, pseudonym);
             return { ok: true, data: pseudonym };
         },
+        pseudonymizeAll(contents) {
+            const savedCounters = new Map(counters);
+            const added = [];
+            const out = [];
+            for (const content of contents) {
+                const known = memo.has(content);
+                const pseudonym = pseudonymizer.pseudonymize(content);
+                if (!pseudonym.ok) {
+                    for (const key of added)
+                        memo.delete(key);
+                    counters.clear();
+                    for (const [key, n] of savedCounters)
+                        counters.set(key, n);
+                    return pseudonym;
+                }
+                if (!known)
+                    added.push(content);
+                out.push(pseudonym.data);
+            }
+            return { ok: true, data: out };
+        },
     };
+    return pseudonymizer;
 }
 /**
  * Build the snapshot from collected entries. In order:
@@ -1420,7 +1490,8 @@ export function createIpPseudonymizer() {
  *    failure in list order) and keeps no `zone_ruleset` entries, so the scanner
  *    never falls back to rule-less heads (874-891).
  * 2. IP pseudonymisation over `zone_dns_records` in zone list order and record
- *    order; a list with unrepresentable content becomes `collection_failed`.
+ *    order; a list with unrepresentable content becomes `collection_failed`
+ *    and uses up no pseudonym numbers.
  * 3. Canonical entry order (`expectedEntryKeys`); unexpected entries go last.
  * 4. Rule bodies encoded and deduplicated in that order.
  * The result is not validated: parse it with `CloudflareCheckupSnapshotV1Schema`.
@@ -1463,20 +1534,15 @@ export function assembleSnapshot(input) {
                 continue;
             const records = entry.result.data;
             const invalidContent = records.some((record) => !pseudonymFormatOk(record.content));
-            let failed = invalidContent ? 'invalid_output' : undefined;
-            const mapped = [];
-            for (const record of failed ? [] : records) {
-                const pseudonym = pseudonymizer.pseudonymize(record.content);
-                if (!pseudonym.ok) {
-                    failed = pseudonym.detail;
-                    break;
-                }
-                mapped.push({ ...record, content: pseudonym.data });
-            }
+            const pseudonyms = invalidContent
+                ? { ok: false, detail: 'invalid_output' }
+                : pseudonymizer.pseudonymizeAll(records.map((record) => record.content));
             pseudonymized.set(entry, {
                 kind: 'zone_dns_records',
                 zoneId,
-                result: failed ? collectionFailedResult(failed) : { ok: true, data: mapped },
+                result: pseudonyms.ok
+                    ? { ok: true, data: records.map((record, r) => ({ ...record, content: pseudonyms.data[r] })) }
+                    : collectionFailedResult(pseudonyms.detail),
             });
         }
     }

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

@@ -1,4 +1,4 @@
-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 declare const LOCAL_ERROR_CODES: readonly ["NODE_UNSUPPORTED", "CWD_UNAVAILABLE", "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", "CANCELLED", "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;
@@ -12,6 +12,20 @@ export declare const LOCAL_ERROR_HINTS: Record<LocalCheckupErrorCode, string>;
 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>`.";
+/** SNAPSHOT_INVALID for a file that cannot be read: its permissions, not its contents. */
+export declare const SNAPSHOT_UNREADABLE_HINT = "Check the permissions of the file and of its directories, or copy it somewhere you can read it.";
+/**
+ * A snapshot file that cannot be uploaded, from a command that only reads it
+ * (inspect, submit, or the re-read before the one command uploads): running
+ * that command again reads the same file, so how to collect a fresh one.
+ */
+export declare const SNAPSHOT_INVALID_FILE_HINT = "The file is not a valid snapshot. Collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`).";
+export declare const SNAPSHOT_STALE_FILE_HINT = "Snapshots are accepted for 24 hours. Collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`).";
+export declare const SNAPSHOT_SECRET_FILE_HINT = "Remove the credential-like value from your Cloudflare settings. Collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`).";
+/** CF_NOT_FOUND from the advanced commands (and `--cf-bin`), which never install cf. */
+export declare const CF_NOT_FOUND_ADVANCED_HINT = "Run `npx @vigilbase/cli cloudflare-checkup` without --cf-bin (it can install cf), install cf with `npm install --global cf@1.0.0-beta.13`, or pass --cf-bin <path> to a cf package.";
+/** CF_WRONG_BINARY when a cf package was found but `cf --version` fails. */
+export declare const CF_DAMAGED_HINT = "Reinstall cf with `npm install --global cf@1.0.0-beta.13`, or run `npx @vigilbase/cli cloudflare-checkup` without --cf-bin and let it install the tested cf.";
 /** 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 {
@@ -29,3 +43,22 @@ export declare class LocalCheckupError extends Error {
     get isRateLimited(): boolean;
 }
 export declare function isLocalCheckupError(error: unknown): error is LocalCheckupError;
+/** The signals that cancel a cf run or the cf install, and the exit code each gives (128 + its number). */
+export declare const CANCEL_EXIT_CODES: Readonly<{
+    readonly SIGINT: 130;
+    readonly SIGTERM: 143;
+    readonly SIGHUP: 129;
+}>;
+export type CancelSignal = keyof typeof CANCEL_EXIT_CODES;
+export declare const CANCEL_SIGNALS: CancelSignal[];
+/** Where cancellation is heard: the process, or a plain emitter in tests. */
+export type CancelSignalSource = {
+    on(event: CancelSignal, listener: () => void): unknown;
+    removeListener(event: CancelSignal, listener: () => void): unknown;
+};
+/** CANCELLED: cf (or npm) was stopped and its files removed; `runCli` exits with `exitCode` and prints no result. */
+export declare class CheckupCancelledError extends LocalCheckupError {
+    readonly signal: CancelSignal;
+    readonly exitCode: (typeof CANCEL_EXIT_CODES)[CancelSignal];
+    constructor(signal: CancelSignal);
+}

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

@@ -11,8 +11,8 @@ 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',
+    'NODE_UNSUPPORTED', 'CWD_UNAVAILABLE', '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', 'CANCELLED',
     // Account
     'ACCOUNT_SELECTION_REQUIRED', 'ACCOUNT_NOT_VISIBLE', 'ACCOUNT_TOO_LARGE', 'ACCOUNT_MISMATCH',
     // Files and snapshots
@@ -26,6 +26,8 @@ export const LOCAL_ERROR_CODES = [
     'VIGILBASE_RATE_LIMITED', 'VIGILBASE_CHALLENGED', 'SUBMIT_FAILED',
 ];
 const INSTALL_CF = '`npm install --global cf@1.0.0-beta.13`';
+/** How to get a fresh snapshot, for hints of the commands that only read one (inspect, submit). */
+const COLLECT_FRESH = 'Collect a fresh one with `npx @vigilbase/cli cloudflare-checkup` (or `npx @vigilbase/cli cloudflare-checkup collect --out <file>`).';
 /** 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`;
@@ -33,6 +35,7 @@ export function browserCheckupHint(origin) {
 /** 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.',
+    CWD_UNAVAILABLE: 'Change to a directory that exists and that you can read (for example `cd ~`), 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}.`,
@@ -45,13 +48,13 @@ export const LOCAL_ERROR_HINTS = {
     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_TOO_LARGE: `Local collection supports up to 100 zones. ${browserCheckupHint(PRODUCTION_ORIGIN)}`,
     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_TOO_LARGE: `The snapshot is over the upload limit. ${browserCheckupHint(PRODUCTION_ORIGIN)}`,
     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.',
+    SNAPSHOT_SECRET_LIKE_VALUE: 'The snapshot contains a value that looks like a credential. Remove it from your Cloudflare settings (a name, description or other text field), 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.',
@@ -68,6 +71,7 @@ export const LOCAL_ERROR_HINTS = {
     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.',
+    CANCELLED: 'Nothing was uploaded. Run the same command again when you are ready.',
 };
 /**
  * CF_AUTH_REQUIRED in env mode (`--cf-auth env`, or `auto` with the variable
@@ -77,6 +81,20 @@ export const LOCAL_ERROR_HINTS = {
 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>`.';
+/** SNAPSHOT_INVALID for a file that cannot be read: its permissions, not its contents. */
+export const SNAPSHOT_UNREADABLE_HINT = 'Check the permissions of the file and of its directories, or copy it somewhere you can read it.';
+/**
+ * A snapshot file that cannot be uploaded, from a command that only reads it
+ * (inspect, submit, or the re-read before the one command uploads): running
+ * that command again reads the same file, so how to collect a fresh one.
+ */
+export const SNAPSHOT_INVALID_FILE_HINT = `The file is not a valid snapshot. ${COLLECT_FRESH}`;
+export const SNAPSHOT_STALE_FILE_HINT = `Snapshots are accepted for 24 hours. ${COLLECT_FRESH}`;
+export const SNAPSHOT_SECRET_FILE_HINT = `Remove the credential-like value from your Cloudflare settings. ${COLLECT_FRESH}`;
+/** CF_NOT_FOUND from the advanced commands (and `--cf-bin`), which never install cf. */
+export const CF_NOT_FOUND_ADVANCED_HINT = `Run \`npx @vigilbase/cli cloudflare-checkup\` without --cf-bin (it can install cf), install cf with ${INSTALL_CF}, or pass --cf-bin <path> to a cf package.`;
+/** CF_WRONG_BINARY when a cf package was found but `cf --version` fails. */
+export const CF_DAMAGED_HINT = `Reinstall cf with ${INSTALL_CF}, or run \`npx @vigilbase/cli cloudflare-checkup\` without --cf-bin and let it install the tested cf.`;
 /** 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 {
@@ -103,3 +121,16 @@ export class LocalCheckupError extends Error {
 export function isLocalCheckupError(error) {
     return error instanceof LocalCheckupError;
 }
+/** The signals that cancel a cf run or the cf install, and the exit code each gives (128 + its number). */
+export const CANCEL_EXIT_CODES = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 });
+export const CANCEL_SIGNALS = Object.keys(CANCEL_EXIT_CODES);
+/** CANCELLED: cf (or npm) was stopped and its files removed; `runCli` exits with `exitCode` and prints no result. */
+export class CheckupCancelledError extends LocalCheckupError {
+    signal;
+    exitCode;
+    constructor(signal) {
+        super('CANCELLED', 'Cancelled.');
+        this.signal = signal;
+        this.exitCode = CANCEL_EXIT_CODES[signal];
+    }
+}

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

@@ -5,6 +5,12 @@ import type { EntryCounts } from './snapshot-file.js';
  * (`...` on an ASCII-only console).
  */
 export declare function displayText(value: string, max: number, ellipsis?: string): string;
+/**
+ * A file name the user passed, in a line of plain output: controls, line
+ * breaks and invisible format characters become visible escapes (`\n`,
+ * `\u001b`), so a crafted name cannot add or rewrite lines.
+ */
+export declare function displayFileName(value: 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` */

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

@@ -14,6 +14,15 @@ 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;
 }
+/**
+ * A file name the user passed, in a line of plain output: controls, line
+ * breaks and invisible format characters become visible escapes (`\n`,
+ * `\u001b`), so a crafted name cannot add or rewrite lines.
+ */
+export function displayFileName(value) {
+    const named = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+    return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, (char) => named[char] ?? `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
 /** `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;