@vigilbase/cli 0.2.3 → 0.2.5

package/dist/commands/local.js

@@ -12,7 +12,7 @@
  * cf owns the Cloudflare login: this process never reads, prints, stores or
  * uploads a Cloudflare credential. See LOCAL.md.
  */
-import { access, constants, stat } from 'node:fs/promises';
+import { access, constants, lstat, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { z } from 'zod';
@@ -21,9 +21,9 @@ import { resolveConfigDir } from '../lib/config.js';
 import { isHeadlessEnvironment, openUrlInBrowser } from '../lib/open-url.js';
 import { shouldShowProgress } from '../lib/progress.js';
 import { CF_SUPPORTED, NOT_COLLECTABLE_ZONE_KINDS, PRODUCTION_ORIGIN, RECOMMENDED_CF_SCOPES, SNAPSHOT_COLLECTOR_NAME, SNAPSHOT_LIMITS, SNAPSHOT_SCHEMA_VERSION, } from '../local/cloudflare-checkup/contract.js';
-import { ENV_TOKEN_AUTH_HINT, LOCAL_ERROR_HINTS, LocalCheckupError } from '../local/cloudflare-checkup/errors.js';
+import { CF_DAMAGED_HINT, CF_NOT_FOUND_ADVANCED_HINT, ENV_TOKEN_AUTH_HINT, LOCAL_ERROR_HINTS, LocalCheckupError, SNAPSHOT_STALE_FILE_HINT, } from '../local/cloudflare-checkup/errors.js';
 import { CF_TOKEN_ENV, buildChildEnv, childEnvVariableNames, hasEnvToken, missingEnvTokenMessage, strippedTokenNotice, } from '../local/cloudflare-checkup/cf/child-env.js';
-import { assertLocalRuntimeSupported, checkCfVersion, isNodeSupported, locateCf } from '../local/cloudflare-checkup/cf/locate.js';
+import { assertLocalRuntimeSupported, checkCfVersion, currentDirectory, isNodeSupported, locateCf } from '../local/cloudflare-checkup/cf/locate.js';
 import { CfInstallError, MANAGED_CF, ensurePrivateDir, findManagedCf, installManagedCf, managedCfRoot, removeManagedCf } from '../local/cloudflare-checkup/cf/install.js';
 import { withCfRunner } from '../local/cloudflare-checkup/cf/run-cf.js';
 import { CRITICAL_TEMPLATES, DEFAULT_PROFILE, PREFLIGHT_ACCOUNT_ID, TEMPLATES, TEMPLATE_IDS, dryRunMatches, loginArgv, logoutArgv, preflightChecks, templateDisplay, validateProfileName, versionArgv, whoamiArgv, } from '../local/cloudflare-checkup/cf/allowlist.js';
@@ -34,9 +34,9 @@ import { accountName, countEntries, countEntriesByKind, dataCategories, loadSnap
 import { confirmDefaultYes, confirmUpload, hasInteractiveInput, promptLine } from '../local/cloudflare-checkup/prompts.js';
 import { SAME_ADDRESS_WAIT, emailLocale, parseEmailFlag, verifyEmail } from '../local/cloudflare-checkup/email-verification.js';
 import { SubmitClient, VerificationClient, assertServerAccepts, displayRequester, isLoopbackOrigin, resolveSubmitOrigin, } from '../local/cloudflare-checkup/submit-client.js';
-import { displayText, formatBytes, formatClock, formatDuration, maskId, readsSummary, shortSha, startCountsProgress } from '../local/cloudflare-checkup/output.js';
+import { displayFileName, displayText, formatBytes, formatClock, formatDuration, maskId, readsSummary, shortSha, startCountsProgress } from '../local/cloudflare-checkup/output.js';
 import { CheckupTui } from '../local/cloudflare-checkup/terminal-ui.js';
-import { EXIT, assertCommandFlags, ok, outputJson } from './helpers.js';
+import { EXIT, ok, outputJson } from './helpers.js';
 /**
  * How the page, the docs and the hints spell the command: the bare package,
  * no version. vigilbase.com refuses CLIs older than it accepts, and that
@@ -63,17 +63,22 @@ uploads it.
 Options (the default command, also called run):
   --email <address>              Your work email (asked for when omitted)
   --account-id <id>              Skip the account picker
-  --out <file>                   Snapshot path (default: <config dir>/checkups/…);
-                                 --overwrite replaces an existing file
+  --out <file>                   Where to save the snapshot (default:
+                                 <config dir>/checkups/…); --overwrite
+                                 replaces an existing file
   --yes                          Install cf and upload without asking
                                  (--confirm answers only the upload question)
   --no-open                      Print the results link; do not open a browser
   --cf-auth auto|profile|env|default
-                                 auto (default): env when ${CF_TOKEN_ENV} is set
-                                 in this shell (cf reads it itself), else profile
+                                 auto (default): env when
+                                 ${CF_TOKEN_ENV} is set in this shell
+                                 (cf reads it itself), else profile
   --profile <name>               cf profile (default ${DEFAULT_PROFILE})
   --cf-bin <path>                Use this cf package; never install one
-  --max-requests-per-5min <n>    Cloudflare request budget, 100..1100 (default 900)
+  --max-requests-per-5min <n>    Cloudflare requests per 5 minutes,
+                                 100..1100 (default 900)
+  --base-url <origin>            Upload origin: ${PRODUCTION_ORIGIN}
+                                 (default) or a loopback origin
   --timeout <milliseconds> · --json
 
 Without a terminal, add --yes: the email (unless --email is given) and the
@@ -82,18 +87,22 @@ code are read from stdin, one line each, after their prompts on stderr.
 Advanced commands:
   login                          Create or refresh the read-only cf profile
                                  [--profile] [--no-open] [--dry-run] [--cf-bin]
-  doctor                         Check Node, cf, the offline command mapping and cf auth
+  doctor                         Check Node, cf, the offline command mapping
+                                 and cf auth
   accounts                       List the Cloudflare account IDs cf can read
-  collect --out <file>           Collect only; --dry-run shows every cf command (offline)
+  collect --out <file>           Collect only [--overwrite] [--account-id];
+                                 --dry-run shows every cf command (offline)
   inspect <file>                 Validate a snapshot and show what it contains
-  submit <file>                  Verify your email, then upload a collected snapshot
-                                 [--email] [--yes] [--no-open]
-  logout                         Delete the read-only cf profile and the cf this CLI
-                                 installed [--profile] [--cf-bin]
+  submit <file>                  Verify your email, then upload a snapshot
+                                 [--email] [--yes|--confirm] [--no-open]
+                                 [--base-url] [--timeout]
+  logout                         Delete the read-only cf profile and the cf
+                                 this CLI installed [--profile] [--cf-bin]
 
 Results go to the verified email address. Uploads go only to
 ${PRODUCTION_ORIGIN} (or a loopback --base-url).
-Exit codes: 0 success, 1 error, 2 rate limited. See LOCAL.md for details.`;
+Exit codes: 0 success, 1 error, 2 rate limited, 130 cancelled (Ctrl-C).
+See LOCAL.md for details.`;
 const CF_FLAGS = ['profile', 'cf-auth', 'cf-bin'];
 const COLLECT_FLAGS = [...CF_FLAGS, 'account-id', 'out', 'isOverwrite', 'max-requests-per-5min'];
 const SUBMIT_FLAGS = ['email', 'isNoOpen', 'isConfirm', 'isYes', 'base-url', 'timeout'];
@@ -107,15 +116,18 @@ const ALLOWED_FLAGS = {
     submit: [...SUBMIT_FLAGS, 'isJson'],
     logout: ['profile', 'cf-bin', 'isJson'],
 };
-/** Validate flags before any spawn, file or network access. */
+/**
+ * Validate flags before any spawn, file or network access. Every refused flag
+ * (including the global origin flags, which local commands do not take) is
+ * named with the subcommand.
+ */
 function assertLocalFlags(ctx, subcommand) {
     const allowed = ALLOWED_FLAGS[subcommand];
-    assertCommandFlags(ctx, allowed);
-    // assertCommandFlags always permits the global origin flags; local commands do not.
-    for (const key of ['base-url', 'one-url', 'auth-url', 'client-id', 'timeout']) {
-        if (ctx.values[key] !== undefined && !allowed.includes(key)) {
-            throw new Error(`--${key} is not supported for cloudflare-checkup ${subcommand}.`);
-        }
+    for (const [key, value] of Object.entries(ctx.values)) {
+        if (value === undefined || value === false || ['isHelp', 'isVersion'].includes(key) || allowed.includes(key))
+            continue;
+        const flag = key.startsWith('is') ? key.slice(2).replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase() : key;
+        throw new Error(`--${flag} is not supported for cloudflare-checkup ${subcommand}.`);
     }
 }
 const accountIdSchema = z.string()
@@ -167,7 +179,8 @@ function parseLocalOptions(ctx, subcommand, args) {
         authAuto: requested === 'auto',
         ...(cfBin !== undefined ? { cfBin } : {}),
         ...(values['account-id'] !== undefined ? { accountId: parse(accountIdSchema, values['account-id']) } : {}),
-        ...(out !== undefined ? { out: resolve(out) } : {}),
+        // A relative --out never reaches resolve()'s implicit process.cwd(), which fails raw in a deleted directory.
+        ...(out !== undefined ? { out: isAbsolute(out) ? resolve(out) : resolve(currentDirectory(), out) } : {}),
         maxRequests: parseRequestBudget(values['max-requests-per-5min']),
         // Environment variables never choose the submit origin.
         ...(subcommand === 'submit' || subcommand === 'run' ? { origin: resolveSubmitOrigin(values['base-url']) } : {}),
@@ -296,13 +309,16 @@ function warn(ctx, warnings, warning) {
     if (ctx.mode !== 'json')
         ctx.writer.stderr(`Warning: ${warning.message}`);
 }
+/** `--cf-auth env` needs the token variable in this shell (presence only; the value is never read). */
+function assertEnvToken(ctx, options) {
+    if (options.auth.authMode === 'env' && !hasEnvToken(ctx.env)) {
+        throw new LocalCheckupError('CF_AUTH_REQUIRED', missingEnvTokenMessage(), { hint: ENV_TOKEN_AUTH_HINT });
+    }
+}
 /** Env-mode presence check and the profile-mode notice; the value is never read. */
 function checkAuthEnvironment(ctx, options, warnings) {
-    if (options.auth.authMode === 'env') {
-        if (!hasEnvToken(ctx.env))
-            throw new LocalCheckupError('CF_AUTH_REQUIRED', missingEnvTokenMessage(), { hint: ENV_TOKEN_AUTH_HINT });
-    }
-    else if (hasEnvToken(ctx.env)) {
+    assertEnvToken(ctx, options);
+    if (options.auth.authMode !== 'env' && hasEnvToken(ctx.env)) {
         warn(ctx, warnings, { code: 'ENV_TOKEN_NOT_USED', message: strippedTokenNotice(options.auth.authMode) });
     }
 }
@@ -311,13 +327,29 @@ async function managedDirFor(options) {
         return null;
     return findManagedCf(options.configDir);
 }
-async function locateAndWarn(ctx, options, warnings, managedDir) {
+/**
+ * Find cf (filesystem only, nothing is spawned). Only the one command without
+ * `--cf-bin` can install cf, so everywhere else CF_NOT_FOUND names the one
+ * command, npm and `--cf-bin` instead.
+ */
+async function locate(ctx, options, managedDir) {
     const managed = managedDir === undefined ? await managedDirFor(options) : managedDir;
-    const location = await locateCf({
-        ...(options.cfBin !== undefined ? { cfBin: options.cfBin } : {}),
-        ...(managed ? { managedDir: managed } : {}),
-        env: ctx.env,
-    });
+    try {
+        return await locateCf({
+            ...(options.cfBin !== undefined ? { cfBin: options.cfBin } : {}),
+            ...(managed ? { managedDir: managed } : {}),
+            env: ctx.env,
+        });
+    }
+    catch (error) {
+        if (error instanceof LocalCheckupError && error.code === 'CF_NOT_FOUND' && (options.subcommand !== 'run' || options.cfBin !== undefined)) {
+            throw new LocalCheckupError('CF_NOT_FOUND', error.message, { hint: CF_NOT_FOUND_ADVANCED_HINT });
+        }
+        throw error;
+    }
+}
+async function locateAndWarn(ctx, options, warnings, managedDir) {
+    const location = await locate(ctx, options, managedDir);
     if (location.insideCwd) {
         warn(ctx, warnings, { code: 'CF_INSIDE_CWD', message: 'The cf package found lies inside the current directory; make sure it is the copy you installed.' });
     }
@@ -331,7 +363,7 @@ async function checkVersion(ctx, runner, location, authMode, warnings) {
     if (result.exitCode !== 0) {
         if (/cf requires Node\.js/.test(result.stderr))
             throw new LocalCheckupError('NODE_UNSUPPORTED', 'cf refused to run under this Node.js version.');
-        throw new LocalCheckupError('CF_WRONG_BINARY', 'cf --version failed; the package may be damaged. Reinstall cf.');
+        throw new LocalCheckupError('CF_WRONG_BINARY', 'cf --version failed; the package may be damaged.', { hint: CF_DAMAGED_HINT });
     }
     const prepared = checkCfVersion(result.stdout, location.packageVersion);
     if (!prepared.tested) {
@@ -505,6 +537,9 @@ async function writeToTarget(target, accountId, startedAt, text, overwrite) {
 async function runLogin(ctx, options) {
     const argv = loginArgv(options.auth.profile, RECOMMENDED_CF_SCOPES, { noBrowser: Boolean(ctx.values.isNoOpen) });
     if (ctx.values.isDryRun) {
+        // A --cf-bin that a real login would refuse is refused here too (filesystem only, nothing runs).
+        if (options.cfBin !== undefined)
+            await locate(ctx, options);
         if (ctx.mode === 'json')
             outputJson(ctx, { success: true, dryRun: true, argv: ['cf', ...argv] });
         else
@@ -571,8 +606,8 @@ async function runLogout(ctx, options) {
             });
         }
         catch (error) {
-            // A cf that cannot run must not stop a broken managed install from being removed (unless --cf-bin named it).
-            if (options.cfBin !== undefined || !(error instanceof LocalCheckupError))
+            // A cf that cannot run must not stop a broken managed install from being removed (unless --cf-bin named it); Ctrl-C stops logout.
+            if (options.cfBin !== undefined || !(error instanceof LocalCheckupError) || error.code === 'CANCELLED')
                 throw error;
             cfProblem = error;
         }
@@ -645,6 +680,8 @@ async function runDoctor(ctx, options) {
         authenticated: false,
         scopes: 'unknown',
     };
+    /** Whether the sign-in was looked at; without a cf that runs it cannot be. */
+    let authChecked = false;
     let runtimeOk = true;
     try {
         assertLocalRuntimeSupported();
@@ -678,6 +715,7 @@ async function runDoctor(ctx, options) {
             if (preflight.mismatched.length > 0) {
                 problems.push({ code: 'CF_ALLOWLIST_MISMATCH', message: `${preflight.mismatched.length} of ${preflight.total} command templates do not map in this cf release.` });
             }
+            authChecked = true;
             try {
                 checkAuthEnvironment(ctx, options, warnings);
                 auth = doctorAuth(await createScheduler(ctx, runner, options.auth, DOCTOR_BUDGET).start(), options.auth.authMode, options.auth.profile);
@@ -692,7 +730,7 @@ async function runDoctor(ctx, options) {
     }
     const success = nodeSupported && cf.supported && commands.mismatched.length === 0 && auth.authenticated && problems.length === 0;
     if (ctx.mode === 'json') {
-        outputJson(ctx, { success, node: { version: process.versions.node, supported: nodeSupported }, cf, auth, commands, warnings, problems });
+        outputJson(ctx, { success, node: { version: process.versions.node, supported: nodeSupported }, cf, auth: { ...auth, checked: authChecked }, commands, warnings, problems });
         return success ? EXIT.OK : EXIT.ERROR;
     }
     const mark = (isOk) => (isOk ? '✓' : '✗');
@@ -700,7 +738,8 @@ async function runDoctor(ctx, options) {
     ctx.writer.stdout(`${mark(cf.supported)} cf ${cf.version ?? (cf.found ? '(version check failed)' : 'not found')}${cf.path ? `  ${cf.path}` : ''}${cf.supported && !cf.tested ? ' (untested)' : ''}`);
     ctx.writer.stdout(`${mark(commands.mismatched.length === 0 && commands.verified > 0)} ${commands.verified} command templates mapped offline${commands.mismatched.length ? `; not mapped: ${commands.mismatched.join(', ')}` : ''}`);
     const authLabel = options.auth.authMode === 'profile' ? `profile "${options.auth.profile}"` : options.auth.authMode === 'env' ? 'API token from this shell' : 'default profile';
-    ctx.writer.stdout(`${mark(auth.authenticated)} cf auth (${authLabel}): ${auth.authenticated ? 'signed in' : 'not signed in'}${auth.expiresAt ? ` · expires ${formatClock(auth.expiresAt)}` : ''}`);
+    const authState = auth.authenticated ? 'signed in' : authChecked ? 'not signed in' : `not checked (${cf.found ? 'cf could not run' : 'cf not found'})`;
+    ctx.writer.stdout(`${mark(auth.authenticated)} cf auth (${authLabel}): ${authState}${auth.expiresAt ? ` · expires ${formatClock(auth.expiresAt)}` : ''}`);
     if (auth.authenticated && auth.scopes === 'unknown')
         ctx.writer.stdout('  scopes: unknown (API token permissions cannot be introspected)');
     if (auth.missingRecommendedScopes?.length)
@@ -748,6 +787,15 @@ const REQUEST_FORMULA = 'about 19 + extra pages + zones × (33 + rulesets per zo
 async function runCollectDryRun(ctx, options) {
     assertLocalRuntimeSupported();
     const warnings = [];
+    // What a real collect would say about the shell token, as warnings: a dry run makes no authenticated call.
+    try {
+        checkAuthEnvironment(ctx, options, warnings);
+    }
+    catch (error) {
+        if (!(error instanceof LocalCheckupError))
+            throw error;
+        warn(ctx, warnings, { code: error.code, message: `${error.message} Without it, a real collect would stop here.` });
+    }
     const location = await locateAndWarn(ctx, options, warnings);
     const { prepared, preflight } = await withCfRunner(location.entry, async (runner) => ({
         prepared: await checkVersion(ctx, runner, location, options.auth.authMode, warnings),
@@ -799,13 +847,19 @@ async function runCollectDryRun(ctx, options) {
 /**
  * Advisory pre-flight for --out, before any cf spawn, so a typo cannot throw
  * away a whole collection. writeSnapshotFile stays the race-safe final guard.
+ * The entry itself is looked at (lstat): any symlink, even a dangling one, is
+ * an existing file, which --overwrite replaces without following it.
  */
 async function assertOutWritable(out, overwrite) {
-    const existing = await stat(out).catch(() => null);
+    const existing = await lstat(out).catch(() => null);
+    // With --overwrite, the final write also refuses a link to a directory (or another non-file).
+    const linked = existing?.isSymbolicLink() && overwrite ? await stat(out).catch(() => null) : null;
+    const entry = linked ?? existing;
+    if (entry && !entry.isFile() && !entry.isSymbolicLink()) {
+        throw new LocalCheckupError('OUTPUT_EXISTS', `--out names a ${entry.isDirectory() ? 'directory' : 'special file'}; it must name a regular file. Nothing was collected.`, { hint: 'Choose a file path, for example <directory>/snapshot.json.' });
+    }
     if (existing && !overwrite)
         throw new LocalCheckupError('OUTPUT_EXISTS', 'The --out file already exists; nothing was collected.');
-    if (existing && !existing.isFile())
-        throw new Error('--out must name a regular file; nothing was collected.');
     const dir = dirname(out);
     const parent = await stat(dir).catch(() => null);
     if (!parent || !parent.isDirectory())
@@ -828,10 +882,40 @@ async function prepareOutput(ctx, options, overwrite) {
         await ensurePrivateDir(dir);
     }
     catch {
-        throw new Error(`Could not create ${displayPath(dir, ctx.env)} for the snapshot; pass --out <file> instead.`);
+        throw checkupsDirError(ctx, dir);
     }
     return { kind: 'default', dir };
 }
+function checkupsDirError(ctx, dir) {
+    return new Error(`Could not create ${displayPath(dir, ctx.env)} for the snapshot; pass --out <file> instead.`);
+}
+/**
+ * Before the email: prepareOutput's checks without writing anything. The
+ * checkups directory exists as a real directory this user can write to, or
+ * its nearest existing parent is one, so it can be created later.
+ */
+async function assertOutputPossible(ctx, options, overwrite) {
+    if (options.out !== undefined)
+        return assertOutWritable(options.out, overwrite);
+    const dir = join(options.configDir, 'checkups');
+    const writable = (target) => access(target, constants.W_OK | constants.X_OK).then(() => true, () => false);
+    const leaf = await lstat(dir).catch(() => null);
+    if (leaf) {
+        if (!leaf.isDirectory() || !(await writable(dir)))
+            throw checkupsDirError(ctx, dir);
+        return;
+    }
+    for (let current = dirname(dir);; current = dirname(current)) {
+        const info = await stat(current).catch(() => null);
+        if (info) {
+            if (!info.isDirectory() || !(await writable(current)))
+                throw checkupsDirError(ctx, dir);
+            return;
+        }
+        if (dirname(current) === current)
+            throw checkupsDirError(ctx, dir);
+    }
+}
 /**
  * Why a located cf cannot be used, found before any authenticated call: none
  * at all, a different program, an unsupported version, or (after `--version`
@@ -1069,7 +1153,14 @@ async function collectSnapshot(ctx, options, session) {
                     message: `The snapshot is larger than ${SNAPSHOT_LIMITS.defaultServerMaxBytes / 1024 / 1024} MiB, the default upload limit.`,
                 });
             }
+            // A cancelled run writes no snapshot, and undoes one that was being written when it was cancelled.
+            if (runner.cancellation)
+                throw runner.cancellation;
             const written = await writeToTarget(target, accountId, startedAt, text, overwrite);
+            if (runner.cancellation) {
+                await rm(written.path, { force: true }).catch(() => undefined);
+                throw runner.cancellation;
+            }
             return { ...written, snapshot, version: prepared.version, cfInvocations: scheduler.invocations };
         }
         finally {
@@ -1162,16 +1253,24 @@ function clientOptions(ctx, origin) {
 }
 /**
  * Before the email is asked for (or `--email` is used): vigilbase.com says
- * whether local checkups are on and which CLI and snapshot schema it accepts,
- * so a switched-off local mode (LOCAL_MODE_DISABLED) or an old CLI
+ * whether local checkups are on and which CLI, snapshot schema and size it
+ * accepts, so a switched-off local mode (LOCAL_MODE_DISABLED) or an old CLI
  * (CLI_UPGRADE_REQUIRED) never costs an emailed code. Without a usable answer
- * the run goes on, and the session check after the email decides as before.
+ * (null) the run goes on, and the session check after the email decides as before.
  */
 async function checkAvailability(ctx, origin, schemaVersion) {
     const client = new VerificationClient(clientOptions(ctx, origin));
-    const availability = await busy(ctx, 'Checking vigilbase.com', () => client.availability());
+    const availability = await busy(ctx, `Checking ${new URL(origin).host}`, () => client.availability());
     if (availability)
         assertServerAccepts(availability, CLI_VERSION, schemaVersion);
+    return availability ?? null;
+}
+/** The size and zone limits vigilbase.com announced (availability) or set for the checkup (session). */
+function assertWithinLimits(server, loaded) {
+    const { maxBytes, maxZones } = server.accepts;
+    if (loaded.bytes.byteLength > maxBytes || zoneCount(loaded.snapshot) > maxZones) {
+        throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', `The snapshot is over the vigilbase.com limit (${formatBytes(maxBytes)}, ${maxZones} zones). Nothing was uploaded.`);
+    }
 }
 /**
  * The email verification (prompts on stderr, answers from piped stdin
@@ -1308,9 +1407,12 @@ async function runOneCommand(ctx, options) {
     else
         say(ctx, BANNER);
     assertLocalRuntimeSupported();
-    // A bad --out never costs an emailed code (collectSnapshot checks it again).
-    if (options.out !== undefined)
-        await assertOutWritable(options.out, Boolean(ctx.values.isOverwrite));
+    // What can be checked on this machine never costs an emailed code (collectSnapshot checks it again):
+    // the token for --cf-auth env, the --out path or the checkups directory, and a --cf-bin (nothing runs).
+    assertEnvToken(ctx, options);
+    await assertOutputPossible(ctx, options, Boolean(ctx.values.isOverwrite));
+    if (options.cfBin !== undefined)
+        await locate(ctx, options);
     // 1-3. Availability, then the email, then the checkup it started are checked before cf is touched.
     await checkAvailability(ctx, origin, SNAPSHOT_SCHEMA_VERSION);
     const checkup = new CheckupSession(ctx, origin, await verifyRequester(ctx, options, origin));
@@ -1367,6 +1469,14 @@ async function runInspect(ctx, options) {
     const name = accountName(snapshot);
     const categories = dataCategories(snapshot);
     const byKind = countEntriesByKind(snapshot.entries);
+    const freshness = snapshotFreshness(snapshot);
+    const warnings = [];
+    if (loaded.bytes.byteLength > SNAPSHOT_LIMITS.defaultServerMaxBytes) {
+        warn(ctx, warnings, {
+            code: 'SNAPSHOT_OVER_DEFAULT_UPLOAD_LIMIT',
+            message: `The snapshot is larger than ${SNAPSHOT_LIMITS.defaultServerMaxBytes / 1024 / 1024} MiB, the default upload limit.`,
+        });
+    }
     if (ctx.mode === 'json') {
         outputJson(ctx, {
             success: true,
@@ -1380,20 +1490,25 @@ async function runInspect(ctx, options) {
                 zoneCount: zoneCount(snapshot),
                 collectedAt: snapshot.collector.finishedAt,
                 collector: snapshot.collector,
+                uploadable: freshness === 'fresh',
+                ...(freshness !== 'fresh' ? { notUploadableReason: freshness } : {}),
             },
             entries: { byKind },
             dataCategories: categories,
+            warnings,
         });
         return ok();
     }
     const counts = countEntries(snapshot.entries);
     const { collector } = snapshot;
     const lines = [
-        `Snapshot   ${options.file}  ${formatBytes(loaded.bytes.byteLength)}  sha256 ${loaded.sha256}`,
+        `Snapshot   ${displayFileName(options.file)}  ${formatBytes(loaded.bytes.byteLength)}  sha256 ${loaded.sha256}`,
         `Schema     ${snapshot.schemaVersion} (valid)`,
         `Account    ${snapshot.accountId}${name !== null ? `  ${name} (as reported)` : ''}`,
         `Zones      ${zoneCount(snapshot)}`,
         `Collected  ${collector.finishedAt} by ${collector.name} ${collector.version} with cf ${collector.cf.version} (${collector.authSource}, ${collector.platform}, ${collector.cfInvocations} cf calls)`,
+        ...(freshness === 'older_than_24_hours' ? ['Upload     no longer accepted (collected more than 24 hours ago)']
+            : freshness === 'dated_in_the_future' ? ['Upload     not accepted (dated in the future)'] : []),
         `Reads      ${counts.total} · ${counts.ok} ok · ${counts.httpError} HTTP error · ${counts.notCollected} not collectable with cf · ${counts.collectionFailed} collection failed`,
         ...Object.entries(byKind).map(([kind, kindCounts]) => {
             const notOk = kindCounts.total - kindCounts.ok;
@@ -1416,9 +1531,10 @@ function runSubmit(ctx, options) {
 async function submitFile(ctx, options) {
     const origin = options.origin ?? PRODUCTION_ORIGIN;
     const loaded = await loadSnapshotFile(options.file);
-    assertFresh(loaded.snapshot);
+    // Running submit again reads the same file, so the hint says how to collect a fresh one.
+    assertFresh(loaded.snapshot, SNAPSHOT_STALE_FILE_HINT);
     const zones = zoneCount(loaded.snapshot);
-    const head = `Snapshot  ${options.file}  ${formatBytes(loaded.bytes.byteLength)}  sha256 ${shortSha(loaded.sha256)}  account ${maskId(loaded.snapshot.accountId)}  ${zones} zone${zones === 1 ? '' : 's'}  collected ${formatClock(loaded.snapshot.collector.finishedAt)}`;
+    const head = `Snapshot  ${displayFileName(options.file)}  ${formatBytes(loaded.bytes.byteLength)}  sha256 ${shortSha(loaded.sha256)}  account ${maskId(loaded.snapshot.accountId)}  ${zones} zone${zones === 1 ? '' : 's'}  collected ${formatClock(loaded.snapshot.collector.finishedAt)}`;
     if (ctx.tui) {
         ctx.tui.intro();
         const { ellipsis } = ctx.tui;
@@ -1434,8 +1550,10 @@ async function submitFile(ctx, options) {
         ctx.writer.stderr(head);
     else
         ctx.writer.stdout(head);
-    // The file, then vigilbase.com's availability, are checked before the email is verified, so neither costs a code.
-    await checkAvailability(ctx, origin, loaded.snapshot.schemaVersion);
+    // The file, then vigilbase.com's availability and limits, are checked before the email is verified, so none costs a code.
+    const availability = await checkAvailability(ctx, origin, loaded.snapshot.schemaVersion);
+    if (availability)
+        assertWithinLimits(availability, loaded);
     const checkup = new CheckupSession(ctx, origin, await verifyRequester(ctx, options, origin));
     const session = await busy(ctx, 'Checking the checkup', () => checkup.getSession());
     const result = await uploadLoaded(ctx, { checkup, session, origin, loaded });
@@ -1443,11 +1561,17 @@ async function submitFile(ctx, options) {
         outputJson(ctx, result);
     return ok();
 }
-/** Refused locally: vigilbase.com accepts snapshots finished in the last 24 h (5 min clock skew). */
-function assertFresh(snapshot, now = Date.now()) {
+/** vigilbase.com accepts snapshots finished in the last 24 h (5 min clock skew). */
+function snapshotFreshness(snapshot, now = Date.now()) {
     const finished = Date.parse(snapshot.collector.finishedAt);
-    if (!(finished >= now - SNAPSHOT_LIMITS.maxAgeHours * 3_600_000) || finished > now + SNAPSHOT_LIMITS.maxFutureSkewSeconds * 1_000) {
-        throw new LocalCheckupError('SNAPSHOT_STALE', 'The snapshot was collected more than 24 hours ago (or is dated in the future).');
+    if (finished > now + SNAPSHOT_LIMITS.maxFutureSkewSeconds * 1_000)
+        return 'dated_in_the_future';
+    return finished >= now - SNAPSHOT_LIMITS.maxAgeHours * 3_600_000 ? 'fresh' : 'older_than_24_hours';
+}
+/** Refused locally, before anything is sent. */
+function assertFresh(snapshot, hint) {
+    if (snapshotFreshness(snapshot) !== 'fresh') {
+        throw new LocalCheckupError('SNAPSHOT_STALE', 'The snapshot was collected more than 24 hours ago (or is dated in the future).', hint !== undefined ? { hint } : {});
     }
 }
 function numberAt(value, ...path) {
@@ -1484,10 +1608,7 @@ async function uploadLoaded(ctx, input) {
     if (session.accountId !== null && session.accountId !== snapshot.accountId) {
         throw new LocalCheckupError('ACCOUNT_MISMATCH', `This checkup is bound to Cloudflare account ${maskId(session.accountId)}, but the snapshot is for ${maskId(snapshot.accountId)}. Nothing was uploaded.`);
     }
-    const zones = zoneCount(snapshot);
-    if (loaded.bytes.byteLength > session.accepts.maxBytes || zones > session.accepts.maxZones) {
-        throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', `The snapshot is over the vigilbase.com limit (${formatBytes(session.accepts.maxBytes)}, ${session.accepts.maxZones} zones). Nothing was uploaded.`);
-    }
+    assertWithinLimits(session, loaded);
     const requester = displayRequester(session.requester);
     const question = `Results go to ${requester}. Upload ${formatBytes(loaded.bytes.byteLength)} to ${origin}?`;
     const flag = ctx.values.isYes ? '--yes' : '--confirm';

package/dist/commands/one.js

@@ -1,19 +1,19 @@
 import { z } from 'zod';
 import { executeOneOperation, formatOnePayload } from '../lib/one-operations.js';
 import { assertCommandFlags, ok, outputJson, requireOneClient, withSpinner } from './helpers.js';
-import { missingArguments } from './legacy-validation.js';
+import { InvalidArgumentError, inRange, isoDateTime, missingArguments, oneOf, textValue, unknownSubcommand } from './legacy-validation.js';
 const regions = ['ams', 'nyc', 'lon', 'sgp', 'iad', 'sfo', 'fra', 'dub', 'tok', 'syd', 'cpt', 'gru', 'dxb', 'ewr', 'lhr', 'jnb', 'atl', 'blr', 'bom', 'cdg', 'del', 'dfw', 'hnl', 'icn', 'itm', 'lax', 'mad', 'man', 'mel', 'mex', 'mia', 'mxp', 'nrt', 'ord', 'sao', 'scl', 'sea', 'sjc', 'sto', 'tlv', 'waw', 'yto'];
 function flag(ctx, name, max = 2048) {
     const value = ctx.values[name];
-    return value === undefined ? undefined : z.string().trim().min(1, `--${name} must not be empty.`).max(max).parse(value);
+    return value === undefined ? undefined : textValue(`--${name}`, String(value), max);
 }
 function integer(ctx, name, min, max) {
     const value = flag(ctx, name);
     if (value === undefined)
         return undefined;
     if (!/^\d+$/.test(value))
-        throw new Error(`--${name} must be an integer.`);
-    return z.number().int().min(min).max(max).parse(Number(value));
+        throw new InvalidArgumentError(`--${name} must be an integer.`);
+    return inRange(`--${name}`, Number(value), min, max);
 }
 function uuid(value) {
     const result = z.string().uuid().safeParse(value);
@@ -89,7 +89,7 @@ export function buildOneOperation(ctx) {
             if (before && cursor)
                 throw new Error('--before and --cursor are mutually exclusive.');
             if (before)
-                z.iso.datetime({ offset: true }).parse(before);
+                isoDateTime('--before', before);
             return operation(`/api/customers/${uuid(ctx.rest[1])}/vigil/investigations`, {
                 limit: integer(ctx, 'limit', 1, 100), cursor, before, issueId: flag(ctx, 'issue-id', 256),
             });
@@ -100,13 +100,13 @@ export function buildOneOperation(ctx) {
         }
         if (command === 'contracts') {
             check(ctx, 2, ['status']);
-            return operation(`/api/customers/${uuid(ctx.rest[1])}/contracts`, { status: z.enum(['draft', 'pending', 'active', 'expired', 'terminated']).optional().parse(flag(ctx, 'status')) });
+            return operation(`/api/customers/${uuid(ctx.rest[1])}/contracts`, { status: oneOf('--status', ['draft', 'pending', 'active', 'expired', 'terminated'], flag(ctx, 'status')) });
         }
         if (command === 'invoices') {
             check(ctx, 2, ['status', 'limit']);
             return operation(`/api/customers/${uuid(ctx.rest[1])}/stripe/invoices`, {
                 limit: integer(ctx, 'limit', 1, 100),
-                status: z.enum(['draft', 'open', 'paid', 'uncollectible', 'void']).optional().parse(flag(ctx, 'status')),
+                status: oneOf('--status', ['draft', 'open', 'paid', 'uncollectible', 'void'], flag(ctx, 'status')),
             });
         }
     }
@@ -149,8 +149,8 @@ export function buildOneOperation(ctx) {
             if (command === 'status')
                 return operation(path, { light: ctx.values.isLight ? true : undefined });
             return operation(path, {
-                range: z.enum(['24h', '7d', '30d']).optional().parse(flag(ctx, 'range')),
-                region: z.enum(regions).optional().parse(flag(ctx, 'region')),
+                range: oneOf('--range', ['24h', '7d', '30d'], flag(ctx, 'range')),
+                region: oneOf('--region', regions, flag(ctx, 'region')),
                 target_id: ctx.values['target-id'] === undefined ? undefined : uuid(ctx.values['target-id']),
             });
         }
@@ -162,7 +162,7 @@ export function buildOneOperation(ctx) {
             customerId: ctx.values['customer-id'] === undefined ? undefined : uuid(ctx.values['customer-id']),
         });
     }
-    throw new Error(`Unknown ${ctx.command} command: ${command}. Run \`vigilbase ${ctx.command} --help\` for usage.`);
+    throw unknownSubcommand(ctx.command, command);
 }
 export const handleOne = async (ctx) => {
     const operation = buildOneOperation(ctx);
@@ -190,11 +190,14 @@ export const ONE_HELP = {
   watchdog-scans <customer-id>       --limit 1..100 --offset 0..1000000 --target-id UUID
   reports <customer-id>              Recon reports; --limit 1..100
   report <customer-id> <report-id>   Recon report detail
-  investigations <customer-id>       --limit 1..100 --cursor TEXT or --before ISO; --issue-id TEXT
+  investigations <customer-id>       --limit 1..100 --issue-id TEXT
+                                     --cursor TEXT or --before ISO
   investigation <customer-id> <id>   --revision 1..2147483647
-  contracts <customer-id>            --status draft|pending|active|expired|terminated
+  contracts <customer-id>            --status <status>, one of draft, pending,
+                                     active, expired, terminated
   billing <customer-id>              Billing overview
-  invoices <customer-id>             --limit 1..100 --status draft|open|paid|uncollectible|void
+  invoices <customer-id>             --limit 1..100 --status <status>, one of
+                                     draft, open, paid, uncollectible, void
   subscriptions <customer-id>        Stripe subscriptions
   projects <customer-id>             Linked projects (internal operators)
 Customer, target, report, and investigation IDs must be UUIDs. Investigations require internal Vigil access.