@vigilbase/cli 0.2.0 → 0.2.2

package/dist/cli.js

@@ -4,7 +4,7 @@ import { VigilbaseApiError, VigilbaseClient } from './lib/client.js';
 import { createConfig, createLocalCommandConfig } from './lib/config.js';
 import { renderBanner, shouldShowBanner } from './lib/banner.js';
 import { createWriter, formatError } from './lib/format.js';
-import { HELP_TAGLINE, HELP_TEXT, helpForCommand } from './lib/help.js';
+import { HELP_TAGLINE, HELP_TEXT, HELP_USAGE, helpForCommand, isCatalogTool } from './lib/help.js';
 import { wasRendered } from './lib/tui.js';
 import { getCommandHandler } from './commands/index.js';
 import { LocalCheckupError } from './local/cloudflare-checkup/errors.js';
@@ -163,7 +163,8 @@ function resolveMode(jsonFlag) {
 }
 export async function runCli(options = {}) {
     const argv = options.argv ?? process.argv.slice(2);
-    const writer = createWriter(options.stdout, options.stderr);
+    const stdoutStream = options.stdout ?? process.stdout;
+    const writer = createWriter(stdoutStream, options.stderr);
     const previousEnv = process.env;
     if (options.env) {
         process.env = options.env;
@@ -182,12 +183,16 @@ export async function runCli(options = {}) {
             if (parsed.values.isVersion && parsed.positionals.length)
                 throw new Error('Usage: vigilbase --version');
             if (parsed.positionals[0] === 'help' && parsed.positionals.length > 2)
-                throw new Error('Usage: vigilbase help [command]');
+                throw new Error(HELP_USAGE);
         }
         if (parsed.values.isVersion) {
             if (mode === 'json') {
                 writer.stdout(JSON.stringify({ name: '@vigilbase/cli', version: CLI_VERSION }, null, 2));
             }
+            else if (!stdoutStream.isTTY) {
+                // Pipes and files get only the version, for scripts.
+                writer.stdout(CLI_VERSION);
+            }
             else if (shouldShowBanner(mode)) {
                 writer.stdout(renderBanner({ version: CLI_VERSION, tagline: HELP_TAGLINE }));
             }
@@ -238,7 +243,10 @@ export async function runCli(options = {}) {
         const publicClient = new VigilbaseClient(config);
         const handler = getCommandHandler(command);
         if (!handler) {
-            throw new Error(`Unknown command "${command}". Run \`vigilbase help\` for usage.`);
+            // Tools are not commands of their own (no aliases): point to how they run.
+            throw new Error(isCatalogTool(command)
+                ? `Unknown command "${command}". Run the tool with \`vigilbase run ${command} <target>\`.`
+                : `Unknown command "${command}". Run \`vigilbase help\` for usage.`);
         }
         return await handler({
             command,
@@ -250,7 +258,7 @@ export async function runCli(options = {}) {
             publicClient,
             env: process.env,
             stdin: options.stdin,
-            stdoutStream: options.stdout ?? process.stdout,
+            stdoutStream,
             stderrStream: options.stderr ?? process.stderr,
             loginHandler: options.loginHandler,
         });
@@ -266,11 +274,6 @@ export async function runCli(options = {}) {
         if (error instanceof LocalCheckupError && error.isRateLimited) {
             return EXIT.RATE_LIMITED;
         }
-        if (error instanceof DeviceAuthError && error.code === 'not_enabled') {
-            if (mode !== 'json') {
-                writer.stderr('Public tools remain available without login: `vigilbase list`, `vigilbase run …`');
-            }
-        }
         return EXIT.ERROR;
     }
     finally {
@@ -279,4 +282,3 @@ export async function runCli(options = {}) {
         }
     }
 }
-//# sourceMappingURL=cli.js.map

package/dist/commands/account.d.ts

@@ -1,3 +1,2 @@
 import { type CommandHandler } from './helpers.js';
 export declare const handleAccount: CommandHandler;
-//# sourceMappingURL=account.d.ts.map

package/dist/commands/account.js

@@ -18,7 +18,7 @@ export const handleAccount = async (ctx) => {
         else if (action === 'create' || action === 'add') {
             if (ctx.values.email !== undefined && ctx.rest[2] !== undefined)
                 throw new Error('Specify the invite email either positionally or with --email, not both.');
-            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm']);
+            validateArguments(ctx, ctx.values.email === undefined ? 3 : 2, ['email', 'role', 'isConfirm'], 'vigilbase account invites create <email> --confirm');
             invitation = invitationSchema.parse({ email: ctx.values.email ?? ctx.rest[2], role: ctx.values.role });
             if (!ctx.values.isConfirm)
                 throw new Error('Sending an organization invitation requires --confirm.');
@@ -184,4 +184,3 @@ export const handleAccount = async (ctx) => {
     }
     throw new Error('Usage: vigilbase account [services|org|endpoints|sessions|invites|billing] [--json]');
 };
-//# sourceMappingURL=account.js.map

package/dist/commands/auth.d.ts

@@ -3,4 +3,3 @@ export declare function readTokenFromStdin(input?: NodeJS.ReadableStream): Promi
 export declare const handleLogin: CommandHandler;
 export declare const handleLogout: CommandHandler;
 export declare const handleWhoami: CommandHandler;
-//# sourceMappingURL=auth.d.ts.map

package/dist/commands/auth.js

@@ -1,6 +1,7 @@
 import { readIdentityTokenMetadata } from '../auth/token-metadata.js';
 import { discoverAuthProvider } from '../auth/provider.js';
-import { revokeSavedCredentials, withCredentialsLock } from '../auth/refresh.js';
+import { revokeIdentityCredentials, revokeIdentityGrant, revokeSavedCredentials, withCredentialsLock } from '../auth/refresh.js';
+import { checkCredentialsLocation, clearIdentityCredentials, clearOneCredentials, hasIgnoredIdentityCredentials, readReplacedIdentityGrant, readStoredCredentials } from '../auth/store.js';
 import { getOneAccessToken, readCredentials, requestDeviceCode, waitForDeviceAuthorization, writeOneCredentials, } from '../auth/index.js';
 import { VigilbaseOneClient, ONE_AUTH_REQUIRED_TOOLS } from '../lib/one-client.js';
 import { VigilbaseApiError } from '../lib/client.js';
@@ -22,6 +23,30 @@ export async function readTokenFromStdin(input = process.stdin) {
         throw new Error('Token input must contain exactly one nonempty token.');
     return token;
 }
+/**
+ * Revoke the Identity grant a new login replaces, before the new grant exists. Identity treats a revoked refresh
+ * token presented again as reuse and ends every CLI grant of the user, so revoking after the new grant was issued
+ * could end it too. The lock is held from the read to the removal of the old file, so no concurrent command can
+ * refresh with the token in between, and no later command presents it again.
+ */
+async function retirePreviousIdentityGrant(ctx) {
+    await withCredentialsLock(ctx.config, async () => {
+        const previous = await readReplacedIdentityGrant(ctx.config);
+        // After a refresh with an uncertain result the token may be rotated already; presenting it trips the same check.
+        if (!previous || previous.refreshPending)
+            return;
+        try {
+            await revokeIdentityGrant(ctx.config, previous);
+        }
+        catch {
+            ctx.writer.stderr("Warning: Couldn't revoke your previous sign-in; it will expire on its own.");
+            return;
+        }
+        // The grant came from identity-credentials.json, or from a CLI 0.2.0 credentials.json when that file is absent.
+        const { identity } = await readStoredCredentials(ctx.config, () => { });
+        await (identity ? clearIdentityCredentials(ctx.config) : clearOneCredentials(ctx.config));
+    }, true);
+}
 export const handleLogin = async (ctx) => {
     if (ctx.rest.length)
         throw new Error('Usage: vigilbase login [--token-stdin | --token <bearer>] [--no-open]');
@@ -29,6 +54,9 @@ export const handleLogin = async (ctx) => {
     if (ctx.loginHandler) {
         return ctx.loginHandler(ctx.config);
     }
+    // Fail on Windows or an unsafe credentials directory or file before validating a token or starting device
+    // authorization: once a device grant is approved, a failed save would leave it unsaved and unrevoked.
+    await checkCredentialsLocation(ctx.config);
     if (ctx.values.isTokenStdin && (ctx.values.token !== undefined || ctx.env.VIGILBASE_ONE_TOKEN !== undefined)) {
         throw new Error('Use --token-stdin without --token or VIGILBASE_ONE_TOKEN.');
     }
@@ -50,15 +78,19 @@ export const handleLogin = async (ctx) => {
             email: session.user.email ?? undefined,
             name: session.user.name ?? undefined,
         };
-        await withCredentialsLock(ctx.config, () => writeOneCredentials(ctx.config, {
-            accessToken: explicitToken,
-            tokenType: 'Bearer',
-            expiresAt: typeof session.session?.expiresAt === 'string'
-                ? session.session.expiresAt
-                : undefined,
-            user,
-            obtainedAt: new Date().toISOString(),
-        }), true);
+        await withCredentialsLock(ctx.config, async () => {
+            // Identity credentials win when tokens are read, so revoke them before saving this session.
+            await revokeIdentityCredentials(ctx.config);
+            await writeOneCredentials(ctx.config, {
+                accessToken: explicitToken,
+                tokenType: 'Bearer',
+                expiresAt: typeof session.session?.expiresAt === 'string'
+                    ? session.session.expiresAt
+                    : undefined,
+                user,
+                obtainedAt: new Date().toISOString(),
+            });
+        }, true);
         if (ctx.mode === 'json') {
             outputJson(ctx, {
                 success: true,
@@ -76,6 +108,8 @@ export const handleLogin = async (ctx) => {
     const preferNoOpen = Boolean(ctx.values.isNoOpen) || isHeadlessEnvironment(ctx.env);
     ctx.writer.stderr(`login  ${ctx.config.oneBaseUrl}`);
     ctx.config.authProvider = await discoverAuthProvider(ctx.config);
+    if (ctx.config.authProvider)
+        await retirePreviousIdentityGrant(ctx);
     const device = await withSpinner(ctx, 'Requesting device code', () => requestDeviceCode(ctx.config));
     const verifyUrl = resolveDeviceVerificationUrl(ctx.config.authProvider?.issuer ?? ctx.config.oneBaseUrl, device);
     const prettyCode = formatUserCode(device.user_code);
@@ -131,15 +165,20 @@ export const handleLogin = async (ctx) => {
     if (ctx.config.authProvider && (!token.refresh_token || !expiresAt || !token.expires_in || token.expires_in > 300))
         throw new Error('Identity returned an invalid token grant.');
     const identityMetadata = ctx.config.authProvider ? readIdentityTokenMetadata(token.access_token, { issuer: ctx.config.authProvider.issuer, clientId: ctx.config.clientId, resource: ctx.config.authProvider.resource }) : undefined;
-    await withCredentialsLock(ctx.config, () => writeOneCredentials(ctx.config, {
-        ...(ctx.config.authProvider ? { issuer: ctx.config.authProvider.issuer, clientId: ctx.config.clientId, resource: ctx.config.authProvider.resource, refreshToken: token.refresh_token, orgId: identityMetadata?.organizationId } : {}),
-        accessToken: token.access_token,
-        tokenType: token.token_type,
-        scope: token.scope,
-        expiresAt,
-        user,
-        obtainedAt: new Date().toISOString(),
-    }), true);
+    await withCredentialsLock(ctx.config, async () => {
+        // A legacy session is saved in credentials.json, which saved Identity credentials would override.
+        if (!ctx.config.authProvider)
+            await revokeIdentityCredentials(ctx.config);
+        await writeOneCredentials(ctx.config, {
+            ...(ctx.config.authProvider ? { issuer: ctx.config.authProvider.issuer, clientId: ctx.config.clientId, resource: ctx.config.authProvider.resource, refreshToken: token.refresh_token, orgId: identityMetadata?.organizationId } : {}),
+            accessToken: token.access_token,
+            tokenType: token.token_type,
+            scope: token.scope,
+            expiresAt,
+            user,
+            obtainedAt: new Date().toISOString(),
+        });
+    }, true);
     if (ctx.mode === 'json') {
         outputJson(ctx, {
             success: true,
@@ -160,7 +199,10 @@ export const handleLogout = async (ctx) => {
     if (ctx.rest.length)
         throw new Error('Usage: vigilbase logout');
     assertCommandFlags(ctx, []);
-    const cleared = await revokeSavedCredentials(ctx.config);
+    const cleared = await revokeSavedCredentials(ctx.config, (warning) => {
+        if (ctx.mode !== 'json')
+            ctx.writer.stderr(`Warning: ${warning}`);
+    });
     if (ctx.mode === 'json') {
         outputJson(ctx, { success: true, cleared });
     }
@@ -176,7 +218,7 @@ export const handleWhoami = async (ctx) => {
     if (ctx.rest.length)
         throw new Error('Usage: vigilbase whoami');
     assertCommandFlags(ctx, []);
-    const credentials = await readCredentials(ctx.config);
+    const legacyIdentityFileIgnored = await hasIgnoredIdentityCredentials(ctx.config);
     const accessToken = await getOneAccessToken(ctx.config);
     let liveUser = null;
     if (accessToken) {
@@ -199,6 +241,8 @@ export const handleWhoami = async (ctx) => {
         }
     }
     const signedIn = Boolean(liveUser);
+    // Read after the token and session calls: either may have refreshed the sign-in, which saves a new expiry and scope.
+    const credentials = await readCredentials(ctx.config);
     const payload = {
         authenticated: signedIn,
         oneBaseUrl: ctx.config.oneBaseUrl,
@@ -211,7 +255,10 @@ export const handleWhoami = async (ctx) => {
         scope: signedIn ? credentials.one?.scope ?? null : null,
         obtainedAt: signedIn ? credentials.one?.obtainedAt ?? null : null,
         authRequiredTools: signedIn ? [...ONE_AUTH_REQUIRED_TOOLS] : [],
+        legacyIdentityFileIgnored,
     };
+    // CLI 0.2.0 can save a second Identity grant in credentials.json; logout revokes it.
+    const legacyNote = 'Note: found a credentials file from CLI 0.2.0. `vigilbase logout` will revoke and remove it.';
     if (ctx.mode === 'json') {
         outputJson(ctx, payload);
     }
@@ -219,6 +266,7 @@ export const handleWhoami = async (ctx) => {
         outputLines(ctx, [
             'Not signed in. Public tools still work.',
             'Run `vigilbase login` to unlock auth-required tools (website-security, react2shell, fortibleed-check).',
+            ...(legacyIdentityFileIgnored ? [legacyNote] : []),
         ]);
     }
     else {
@@ -229,8 +277,9 @@ export const handleWhoami = async (ctx) => {
             lines.push(`Expires: ${credentials.one.expiresAt}`);
         }
         lines.push(`Auth-required tools: ${ONE_AUTH_REQUIRED_TOOLS.join(', ')}`);
+        if (legacyIdentityFileIgnored)
+            lines.push(legacyNote);
         outputLines(ctx, lines);
     }
     return ok();
 };
-//# sourceMappingURL=auth.js.map

package/dist/commands/billing.d.ts

@@ -1,3 +1,2 @@
 import { type CommandHandler } from './helpers.js';
 export declare const handleBilling: CommandHandler;
-//# sourceMappingURL=billing.d.ts.map

package/dist/commands/billing.js

@@ -48,4 +48,3 @@ export const handleBilling = async (ctx) => {
     }
     throw new Error('Usage: vigilbase billing [summary|portal] [--json] [--no-open]');
 };
-//# sourceMappingURL=billing.js.map

package/dist/commands/cloudflare.d.ts

@@ -1,4 +1,3 @@
 import { type CommandHandler } from './helpers.js';
-export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default); --customer-id, --account-id, --zone-id\n  zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id\n  accounts                     List accessible accounts; --customer-id, --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]          Workspace bootstrap or section; --customer-id, --account-id, --zone-id\n    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings\n\nZone reads (optional --customer-id; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)\n  zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics\n  developer-platform <account-id>  Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]             Latest completed checkup; --customer-id, --account-id\n  checkup start                Start and persist a scan; --customer-id, --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
+export declare const CLOUDFLARE_HELP = "Usage: vigilbase cf <command> [options]\nAlias: vigilbase cloudflare\n\nInventory and workspace:\n  zones                         List zones (default); --customer-id, --account-id, --zone-id\n  zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id\n  accounts                      List accessible accounts; --customer-id, --account-id\n  account <account-id>          Stored account detail; --customer-id\n  workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id\n    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings\n\nZone reads (--customer-id <uuid> required; IDs can use --zone-id):\n  dns <zone-id>                 DNS records, TTL and proxy state\n  waf <zone-id>                 WAF rules, expressions, analytics and suggestions\n  speed-settings <zone-id>      Performance settings (internal users only)\n\nAccount reads (optional --customer-id; IDs can use --account-id):\n  audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)\n  zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics\n  developer-platform <account-id>\n                                Workers, Workers analytics and Pages\n  magic-transit <account-id>    Prefixes, routes and traffic analytics\n    Zero Trust, Developer Platform and Magic Transit require deployment-read permission.\n\nAnalytics and checkups:\n  analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]\n    Default 7 days; live zone analytics uses the most recent 23 hours.\n  checkup [status]              Latest completed checkup; --customer-id, --account-id\n  checkup start                 Start and persist a scan; --customer-id, --account-id\n  checkup progress <run-uuid>   Read saved progress once\n  checkup result <run-uuid>     Read the stored Cloudflare checkup result\n    checkups aliases checkup; list/show alias status; run aliases start.\n\nCommon options: --json, --one-url <origin>, --timeout <milliseconds>, --help\nCustomer IDs are UUIDs; account and zone IDs are 32 hexadecimal characters.\nOne login, tenant bindings and permissions apply to every command.\nCheckup start creates a scan run. These commands do not edit provider configuration.\nSee CLOUDFLARE.md for full grammar, API mapping, data limits and examples.";
 export declare const handleCloudflare: CommandHandler;
-//# sourceMappingURL=cloudflare.d.ts.map

package/dist/commands/cloudflare.js

@@ -9,12 +9,12 @@ Alias: vigilbase cloudflare
 Inventory and workspace:
   zones                         List zones (default); --customer-id, --account-id, --zone-id
   zone <zone-id>                Zone detail; --customer-id selects live details, optional --account-id
-  accounts                     List accessible accounts; --customer-id, --account-id
+  accounts                      List accessible accounts; --customer-id, --account-id
   account <account-id>          Stored account detail; --customer-id
-  workspace [section]          Workspace bootstrap or section; --customer-id, --account-id, --zone-id
+  workspace [section]           Workspace bootstrap or section; --customer-id, --account-id, --zone-id
     Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings
 
-Zone reads (optional --customer-id; IDs can use --zone-id):
+Zone reads (--customer-id <uuid> required; IDs can use --zone-id):
   dns <zone-id>                 DNS records, TTL and proxy state
   waf <zone-id>                 WAF rules, expressions, analytics and suggestions
   speed-settings <zone-id>      Performance settings (internal users only)
@@ -22,15 +22,16 @@ Zone reads (optional --customer-id; IDs can use --zone-id):
 Account reads (optional --customer-id; IDs can use --account-id):
   audit-logs <account-id>       Latest provider audit events (up to 100; service-read permission)
   zero-trust <account-id>       Users, Access applications, tunnels and authentication analytics
-  developer-platform <account-id>  Workers, Workers analytics and Pages
+  developer-platform <account-id>
+                                Workers, Workers analytics and Pages
   magic-transit <account-id>    Prefixes, routes and traffic analytics
     Zero Trust, Developer Platform and Magic Transit require deployment-read permission.
 
 Analytics and checkups:
   analytics --customer-id <uuid> [--account-id <id> | --zone-id <id>] [--days 1..30]
     Default 7 days; live zone analytics uses the most recent 23 hours.
-  checkup [status]             Latest completed checkup; --customer-id, --account-id
-  checkup start                Start and persist a scan; --customer-id, --account-id
+  checkup [status]              Latest completed checkup; --customer-id, --account-id
+  checkup start                 Start and persist a scan; --customer-id, --account-id
   checkup progress <run-uuid>   Read saved progress once
   checkup result <run-uuid>     Read the stored Cloudflare checkup result
     checkups aliases checkup; list/show alias status; run aliases start.
@@ -110,7 +111,7 @@ export const handleCloudflare = async (ctx) => {
             throw new Error('The positional account ID and --account-id must match.');
         accountId = args[0] ?? scope.accountId;
         if (!accountId)
-            throw new Error(`Usage: vigilbase cf ${subcommand} <account-id> [--customer-id …] [--json]`);
+            throw new Error(`Missing <account-id>. Usage: vigilbase cf ${subcommand} <account-id> [--customer-id <uuid>] [--json]`);
         validate(cloudflareScopeSchema, { accountId });
     }
     else if (['dns', 'waf', 'zone', 'speed-settings'].includes(subcommand)) {
@@ -120,9 +121,12 @@ export const handleCloudflare = async (ctx) => {
         zoneId = args[0] ?? scope.zoneId;
         // Preserve the historical `cf zone` alias for the zone inventory.
         if (subcommand !== 'zone' && !zoneId)
-            throw new Error(`Usage: vigilbase cf ${subcommand} <zone-id> [--customer-id …] [--json]`);
+            throw new Error(`Missing <zone-id>. Usage: vigilbase cf ${subcommand} <zone-id> --customer-id <uuid> [--json]`);
         if (zoneId)
             validate(cloudflareScopeSchema, { zoneId });
+        // One answers 400 to every caller that leaves the customer out of a zone read.
+        if (subcommand !== 'zone' && !scope.customerId)
+            throw new Error(`cf ${subcommand} requires --customer-id <uuid>. Find it with \`vigilbase cf accounts --json\`.`);
     }
     else if (!['workspace', 'checkup', 'checkups'].includes(subcommand)) {
         noExtraArgs(0);
@@ -143,6 +147,8 @@ export const handleCloudflare = async (ctx) => {
     if (subcommand === 'checkup' || subcommand === 'checkups') {
         if (['progress', 'result'].includes(action)) {
             noExtraArgs(2, checkupUsage);
+            if (args[1] === undefined)
+                throw new Error(`Missing <run-uuid>. Usage: vigilbase cf checkup ${action} <run-uuid> [--json]`);
             runId = validate(z.string().uuid('A checkup run UUID is required.'), args[1]);
             if (scope.customerId || scope.accountId)
                 throw new Error(`cf checkup ${action} is scoped by run ID and does not accept --customer-id or --account-id.`);
@@ -338,4 +344,3 @@ export const handleCloudflare = async (ctx) => {
             fields(ctx, report);
     });
 };
-//# sourceMappingURL=cloudflare.js.map

package/dist/commands/helpers.d.ts

@@ -96,4 +96,3 @@ export declare function requireOneClient(ctx: CommandContext): Promise<Vigilbase
 export declare function withSpinner<T>(ctx: CommandContext, label: string, work: () => Promise<T>): Promise<T>;
 export declare function ok(): ExitCode;
 export { EXIT };
-//# sourceMappingURL=helpers.d.ts.map

package/dist/commands/helpers.js

@@ -45,4 +45,3 @@ export function ok() {
     return EXIT.OK;
 }
 export { EXIT };
-//# sourceMappingURL=helpers.js.map

package/dist/commands/index.d.ts

@@ -8,4 +8,3 @@ import type { CommandHandler } from './helpers.js';
  */
 export declare const COMMAND_HANDLERS: Record<string, CommandHandler>;
 export declare function getCommandHandler(command: string): CommandHandler | null;
-//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.js

@@ -46,4 +46,3 @@ export const COMMAND_HANDLERS = {
 export function getCommandHandler(command) {
     return COMMAND_HANDLERS[command] ?? null;
 }
-//# sourceMappingURL=index.js.map

package/dist/commands/legacy-validation.d.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod';
 import { type CommandContext } from './helpers.js';
-export declare function validateArguments(ctx: CommandContext, count: number, flags?: readonly string[]): void;
+/**
+ * Exactly `count` positional arguments. When some are missing, they are named from the trailing `<placeholders>`
+ * of `usage` (for example `vigilbase run <tool> <target>`), so `usage` lists only positional placeholders.
+ */
+export declare function validateArguments(ctx: CommandContext, count: number, flags?: readonly string[], usage?: string): void;
+/** "Missing <target>. Usage: vigilbase headers <url>", or a pointer to --help without a usage. */
+export declare function missingArguments(command: string, missingCount: number, usage?: string): string;
 export declare function limitValue(raw: string | undefined, fallback: number, max: number): number;
 export declare const invitationSchema: z.ZodObject<{
     email: z.ZodString;
@@ -18,4 +24,3 @@ export declare const invitationSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export declare const toolNameSchema: z.ZodString;
-//# sourceMappingURL=legacy-validation.d.ts.map

package/dist/commands/legacy-validation.js

@@ -1,10 +1,23 @@
 import { z } from 'zod';
 import { assertCommandFlags } from './helpers.js';
-export function validateArguments(ctx, count, flags = []) {
-    if (ctx.rest.length !== count)
+/**
+ * Exactly `count` positional arguments. When some are missing, they are named from the trailing `<placeholders>`
+ * of `usage` (for example `vigilbase run <tool> <target>`), so `usage` lists only positional placeholders.
+ */
+export function validateArguments(ctx, count, flags = [], usage) {
+    if (ctx.rest.length < count)
+        throw new Error(missingArguments(ctx.command, count - ctx.rest.length, usage));
+    if (ctx.rest.length > count)
         throw new Error(`Unexpected arguments. Run \`vigilbase ${ctx.command} --help\` for usage.`);
     assertCommandFlags(ctx, flags);
 }
+/** "Missing <target>. Usage: vigilbase headers <url>", or a pointer to --help without a usage. */
+export function missingArguments(command, missingCount, usage) {
+    const missing = usage?.match(/<[^>]+>/g)?.slice(-missingCount) ?? [];
+    if (!usage || missing.length !== missingCount)
+        return `Missing arguments. Run \`vigilbase ${command} --help\` for usage.`;
+    return `Missing ${missing.join(' and ')}. Usage: ${usage}`;
+}
 export function limitValue(raw, fallback, max) {
     if (raw === undefined)
         return fallback;
@@ -17,4 +30,3 @@ export const invitationSchema = z.object({
     role: z.enum(['admin', 'member', 'readonly', 'partner_owner', 'partner_sales', 'partner_operations', 'partner_finance', 'partner_readonly', 'billing_only', 'sales_only']).default('member'),
 });
 export const toolNameSchema = z.string().trim().min(1).max(128).regex(/^[a-z0-9-]+$/, 'Tool names must contain lowercase letters, digits, or hyphens.');
-//# sourceMappingURL=legacy-validation.js.map

package/dist/commands/local.d.ts

@@ -27,4 +27,9 @@ export declare function displayPath(path: string, env?: NodeJS.ProcessEnv, platf
  * `-2`, `-3`, … only when a run in the same second already used the name.
  */
 export declare function defaultSnapshotName(accountId: string, at: Date, attempt?: number): string;
-//# sourceMappingURL=local.d.ts.map
+/**
+ * `submit` for a saved file. A loopback origin is named with `--base-url`, so a
+ * development run never suggests an upload to production; production is the
+ * CLI's default and is not named.
+ */
+export declare function submitCommand(path: string, origin: string): string;

package/dist/commands/local.js

@@ -33,7 +33,7 @@ import { buildSnapshot, collectAccount, estimateRequests, listAccounts } from '.
 import { accountName, countEntries, countEntriesByKind, dataCategories, loadSnapshotFile, writeSnapshotFile, zoneCount, } from '../local/cloudflare-checkup/snapshot-file.js';
 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, assertSessionAccepts, displayRequester, resolveSubmitOrigin, } from '../local/cloudflare-checkup/submit-client.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 { CheckupTui } from '../local/cloudflare-checkup/terminal-ui.js';
 import { EXIT, assertCommandFlags, ok, outputJson } from './helpers.js';
@@ -134,7 +134,8 @@ function parse(schema, value) {
 function parseLocalOptions(ctx, subcommand, args) {
     const takesFile = subcommand === 'inspect' || subcommand === 'submit';
     if (takesFile ? args.length !== 1 : args.length !== 0) {
-        throw new Error(takesFile ? `Usage: vigilbase cloudflare-checkup ${subcommand} <file>` : usage);
+        const fileUsage = `Usage: vigilbase cloudflare-checkup ${subcommand} <file>`;
+        throw new Error(!takesFile ? usage : args.length === 0 ? `Missing <file>. ${fileUsage}` : fileUsage);
     }
     const values = ctx.values;
     const requested = parse(z.enum(['auto', 'profile', 'env', 'default'], { message: '--cf-auth must be auto, profile, env or default.' }), values['cf-auth'] ?? (subcommand === 'run' ? 'auto' : 'profile'));
@@ -1159,10 +1160,23 @@ function clientOptions(ctx, origin) {
         ...(ctx.values.timeout !== undefined ? { timeoutMs: ctx.config.timeoutMs } : {}),
     };
 }
+/**
+ * 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
+ * (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.
+ */
+async function checkAvailability(ctx, origin, schemaVersion) {
+    const client = new VerificationClient(clientOptions(ctx, origin));
+    const availability = await busy(ctx, 'Checking vigilbase.com', () => client.availability());
+    if (availability)
+        assertServerAccepts(availability, CLI_VERSION, schemaVersion);
+}
 /**
  * The email verification (prompts on stderr, answers from piped stdin
- * without a terminal), then `✓ Verified j***@acme.com`. Nothing is sent
- * before an address is entered, and cf is not touched before it is verified.
+ * without a terminal), then `✓ Verified j***@acme.com`. No address is sent
+ * before one is entered, and cf is not touched before it is verified.
  */
 async function verifyRequester(ctx, options, origin) {
     const verified = await verifyEmail({
@@ -1230,16 +1244,25 @@ class CheckupSession {
 /** Failures after the snapshot is saved that a later `submit <file>` can fix without collecting again. */
 const UPLOAD_LATER_CODES = new Set(['SESSION_INVALID', 'SESSION_EXPIRED', 'SESSION_CLOSED', 'VERIFICATION_EXPIRED', 'VERIFICATION_INVALID',
     'SUBMIT_FAILED', 'VIGILBASE_RATE_LIMITED', 'VIGILBASE_CHALLENGED', 'LOCAL_MODE_DISABLED']);
+/**
+ * `submit` for a saved file. A loopback origin is named with `--base-url`, so a
+ * development run never suggests an upload to production; production is the
+ * CLI's default and is not named.
+ */
+export function submitCommand(path, origin) {
+    const baseUrl = isLoopbackOrigin(origin) ? ` --base-url ${shellArg(origin)}` : '';
+    return `${NPX_COMMAND} cloudflare-checkup submit ${shellArg(path)}${baseUrl}`;
+}
 /**
  * Right before such an error is reported (stderr, both modes): the `submit`
  * command for the saved file. A line of its own, because hints are capped at
  * 300 characters and a path has no fixed length; in the terminal UI, the
  * command has a line of its own too, never wrapped, so it can be copied.
  */
-function noteSavedSnapshot(ctx, error, path) {
+function noteSavedSnapshot(ctx, error, path, origin) {
     if (!(error instanceof LocalCheckupError) || !UPLOAD_LATER_CODES.has(error.code))
         return;
-    const submit = `${NPX_COMMAND} cloudflare-checkup submit ${shellArg(path)}`;
+    const submit = submitCommand(path, origin);
     if (ctx.tui)
         ctx.tui.uploadLater(submit);
     else
@@ -1247,7 +1270,7 @@ function noteSavedSnapshot(ctx, error, path) {
 }
 /** Session checks that need no upload: CLI version, single use, and the bound account. */
 function assertSessionUsable(session, accountId) {
-    assertSessionAccepts(session, CLI_VERSION, SNAPSHOT_SCHEMA_VERSION);
+    assertServerAccepts(session, CLI_VERSION, SNAPSHOT_SCHEMA_VERSION);
     if (session.state === 'completed')
         throw new LocalCheckupError('SESSION_USED', 'This checkup already has results, so it cannot accept a new snapshot.');
     // A checkup the email verification just started is never processing; this guards any other state.
@@ -1288,7 +1311,8 @@ async function runOneCommand(ctx, options) {
     // A bad --out never costs an emailed code (collectSnapshot checks it again).
     if (options.out !== undefined)
         await assertOutWritable(options.out, Boolean(ctx.values.isOverwrite));
-    // 1-3. The email is verified, and the checkup it started is checked, before cf is touched.
+    // 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));
     const early = await busy(ctx, 'Checking the checkup', () => checkup.getSession());
     assertSessionUsable(early, options.accountId);
@@ -1312,7 +1336,7 @@ async function runOneCommand(ctx, options) {
         result = await uploadLoaded(ctx, { checkup, session, origin, loaded });
     }
     catch (error) {
-        noteSavedSnapshot(ctx, error, outcome.path);
+        noteSavedSnapshot(ctx, error, outcome.path, origin);
         throw error;
     }
     if (ctx.mode === 'json') {
@@ -1410,7 +1434,8 @@ async function submitFile(ctx, options) {
         ctx.writer.stderr(head);
     else
         ctx.writer.stdout(head);
-    // The file is checked before the email is verified, so a bad file never sends a code.
+    // 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);
     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 });
@@ -1455,7 +1480,7 @@ async function uploadLoaded(ctx, input) {
     const { checkup, session, origin, loaded } = input;
     const { snapshot } = loaded;
     assertFresh(snapshot);
-    assertSessionAccepts(session, CLI_VERSION, snapshot.schemaVersion);
+    assertServerAccepts(session, CLI_VERSION, snapshot.schemaVersion);
     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.`);
     }
@@ -1517,4 +1542,3 @@ async function uploadLoaded(ctx, input) {
         ...(result.resultsUrl !== undefined ? { resultsUrl: result.resultsUrl } : {}),
     };
 }
-//# sourceMappingURL=local.js.map

package/dist/commands/one.d.ts

@@ -3,4 +3,3 @@ import { type CommandContext, type CommandHandler } from './helpers.js';
 export declare function buildOneOperation(ctx: CommandContext): OneOperation;
 export declare const handleOne: CommandHandler;
 export declare const ONE_HELP: Record<string, string>;
-//# sourceMappingURL=one.d.ts.map