@vigilbase/cli 0.2.3 → 0.2.5

package/dist/commands/cloudflare.js

@@ -1,37 +1,48 @@
 import { z } from 'zod';
 import { CloudflareClient, accountResourceSchema, cloudflareScopeSchema, workspaceSectionSchema, } from '../lib/cloudflare-client.js';
 import { assertCommandFlags, asArray, asRecord, ok, outputJson, requireOneClient, withSpinner, } from './helpers.js';
-const usage = 'Usage: vigilbase cf [zones|zone <id>|accounts|account <id>|workspace [section]|dns <zone-id>|waf <zone-id>|speed-settings <zone-id>|audit-logs <account-id>|zero-trust <account-id>|developer-platform <account-id>|magic-transit <account-id>|analytics|checkup] [--customer-id …] [--account-id …] [--json]';
+import { InvalidArgumentError, inRange, oneOf, unknownSubcommand } from './legacy-validation.js';
 const checkupUsage = 'Usage: vigilbase cf checkup [status|start|progress <run-id>|result <run-id>] [--customer-id …] [--account-id …] [--json]';
 export const CLOUDFLARE_HELP = `Usage: vigilbase cf <command> [options]
 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
+  zones                         List zones (default)
+                                --customer-id --account-id --zone-id
+  zone <zone-id>                Zone detail; --customer-id for live details,
+                                optional --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
-    Sections: overview, reports, zones, rule-analyzer, accounts, checkups, settings
+  workspace [section]           Workspace bootstrap or one section
+                                --customer-id --account-id --zone-id
+    Sections: overview, reports, zones, rule-analyzer,
+    accounts, checkups, settings
 
 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
+  waf <zone-id>                 WAF rules, expressions, analytics and
+                                suggestions
   speed-settings <zone-id>      Performance settings (internal users only)
 
 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
+  audit-logs <account-id>       Latest provider audit events (up to 100)
+                                Needs service-read permission.
+  zero-trust <account-id>       Users, Access applications, tunnels and
+                                authentication analytics
   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]
+  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.
@@ -44,7 +55,7 @@ See CLOUDFLARE.md for full grammar, API mapping, data limits and examples.`;
 function validate(schema, input) {
     const result = schema.safeParse(input);
     if (!result.success)
-        throw new Error(result.error.issues.map((issue) => issue.message).join(' '));
+        throw new InvalidArgumentError(result.error.issues.map((issue) => issue.message).join(' '));
     return result.data;
 }
 function dataOf(payload) {
@@ -85,7 +96,7 @@ export const handleCloudflare = async (ctx) => {
     if (scope.zoneId && ['accounts', 'account', ...accountResourceSchema.options, 'checkup', 'checkups'].includes(subcommand))
         throw new Error(`cf ${subcommand} does not support --zone-id.`);
     const args = ctx.rest.slice(1);
-    const noExtraArgs = (count, message = usage) => {
+    const noExtraArgs = (count, message = `Unexpected arguments. Run \`vigilbase ${ctx.command} --help\` for usage.`) => {
         if (args.length > count)
             throw new Error(message);
     };
@@ -100,7 +111,7 @@ export const handleCloudflare = async (ctx) => {
     };
     // Validate commands before requesting credentials or making API calls.
     if (!['zones', 'zone', 'accounts', 'workspace', 'dns', 'waf', 'speed-settings', 'account', ...accountResourceSchema.options, 'analytics', 'checkup', 'checkups'].includes(subcommand)) {
-        throw new Error(usage);
+        throw unknownSubcommand(ctx.command, ctx.rest[0] ?? '');
     }
     let zoneId;
     let accountId;
@@ -132,7 +143,7 @@ export const handleCloudflare = async (ctx) => {
         noExtraArgs(0);
     }
     const section = subcommand === 'workspace'
-        ? (noExtraArgs(1), args[0] ? validate(workspaceSectionSchema, args[0]) : undefined)
+        ? (noExtraArgs(1), oneOf('Workspace section', workspaceSectionSchema.options, args[0]))
         : undefined;
     let days = 7;
     if (subcommand === 'analytics') {
@@ -140,7 +151,10 @@ export const handleCloudflare = async (ctx) => {
             throw new Error('Cloudflare analytics requires --customer-id <uuid>. Find it with `vigilbase cf accounts --json`.');
         if (scope.zoneId && scope.accountId)
             throw new Error('Choose either --zone-id or --account-id for analytics.');
-        days = validate(z.coerce.number().int().min(1).max(30), ctx.values.days ?? 7);
+        const raw = ctx.values.days ?? '7';
+        if (!/^\d+$/.test(raw))
+            throw new InvalidArgumentError('--days must be an integer.');
+        days = inRange('--days', Number(raw), 1, 30);
     }
     const action = (args[0] ?? 'status').toLowerCase();
     let runId;

package/dist/commands/helpers.js

@@ -2,6 +2,7 @@ import { printJson as writeJson } from '../lib/format.js';
 import { withProgress } from '../lib/progress.js';
 import { EXIT } from '../types.js';
 import { getOneAccessToken } from '../auth/index.js';
+import { NotSignedInError } from '../auth/store.js';
 import { VigilbaseOneClient as OneClient } from '../lib/one-client.js';
 /** Reject known flags from other command groups instead of silently ignoring filters. */
 export function assertCommandFlags(ctx, allowed) {
@@ -33,9 +34,8 @@ export function asArray(value) {
 }
 export async function requireOneClient(ctx) {
     const accessToken = await getOneAccessToken(ctx.config);
-    if (!accessToken) {
-        throw new Error('This command requires Vigilbase One auth. Run `vigilbase login` first.');
-    }
+    if (!accessToken)
+        throw new NotSignedInError();
     return new OneClient(ctx.config, accessToken, true);
 }
 export async function withSpinner(ctx, label, work) {

package/dist/commands/index.d.ts

@@ -7,4 +7,5 @@ import type { CommandHandler } from './helpers.js';
  * `cloudflare-checkup` is the top-level alias of `local cloudflare-checkup`.
  */
 export declare const COMMAND_HANDLERS: Record<string, CommandHandler>;
+/** Own entries only: names such as constructor or __proto__ are not commands. */
 export declare function getCommandHandler(command: string): CommandHandler | null;

package/dist/commands/index.js

@@ -43,6 +43,7 @@ export const COMMAND_HANDLERS = {
     local: handleLocal,
     'cloudflare-checkup': handleCloudflareCheckup,
 };
+/** Own entries only: names such as constructor or __proto__ are not commands. */
 export function getCommandHandler(command) {
-    return COMMAND_HANDLERS[command] ?? null;
+    return Object.hasOwn(COMMAND_HANDLERS, command) ? COMMAND_HANDLERS[command] : null;
 }

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

@@ -1,12 +1,28 @@
 import { z } from 'zod';
 import { type CommandContext } from './helpers.js';
+/** A flag or argument the CLI rejected before any request; `--json` reports it as code INVALID_ARGUMENT. */
+export declare class InvalidArgumentError extends Error {
+    readonly code = "INVALID_ARGUMENT";
+    constructor(message: string);
+}
 /**
  * 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.
+ * An empty or whitespace-only argument counts as missing.
  */
 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;
+/** 'Unknown security command "x". Run `vigilbase security --help` for usage.' The pointer names the top-level group. */
+export declare function unknownSubcommand(group: string, subcommand: string): Error;
+/** Parses user input with `schema`, throwing `message` instead of Zod's issue list. */
+export declare function parseArgument<T>(schema: z.ZodType<T>, value: unknown, message: string): T;
+/** An integer already checked as digits, within [min, max]. */
+export declare function inRange(label: string, value: number, min: number, max: number): number;
+export declare function oneOf<const T extends readonly string[]>(label: string, values: T, value: string | undefined): T[number] | undefined;
+/** A trimmed, non-empty flag value of at most `max` characters. */
+export declare function textValue(label: string, value: string | undefined, max: number): string | undefined;
+export declare function isoDateTime(label: string, value: string): string;
 export declare function limitValue(raw: string | undefined, fallback: number, max: number): number;
 export declare const invitationSchema: z.ZodObject<{
     email: z.ZodString;
@@ -23,4 +39,8 @@ export declare const invitationSchema: z.ZodObject<{
         sales_only: "sales_only";
     }>>;
 }, z.core.$strip>;
+export declare function invitationValue(email: string | undefined, role: string | undefined): z.infer<typeof invitationSchema>;
 export declare const toolNameSchema: z.ZodString;
+export declare function toolNameValue(value: string): string;
+/** A scan target: trimmed, 1-2048 characters, no control characters. */
+export declare function targetValue(value: string): string;

package/dist/commands/legacy-validation.js

@@ -1,14 +1,31 @@
 import { z } from 'zod';
 import { assertCommandFlags } from './helpers.js';
+/** A flag or argument the CLI rejected before any request; `--json` reports it as code INVALID_ARGUMENT. */
+export class InvalidArgumentError extends Error {
+    code = 'INVALID_ARGUMENT';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArgumentError';
+    }
+}
 /**
  * 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.
+ * An empty or whitespace-only argument counts as missing.
  */
 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.`);
+    const blank = ctx.rest.flatMap((value, index) => value.trim() ? [] : [index]);
+    if (blank.length) {
+        const placeholders = usage?.match(/<[^>]+>/g) ?? [];
+        const missing = blank.map((index) => placeholders[index - (count - placeholders.length)]);
+        throw new Error(missing.every(Boolean) && usage
+            ? `Missing ${missing.join(' and ')}. Usage: ${usage}`
+            : `Missing 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. */
@@ -18,15 +35,72 @@ export function missingArguments(command, missingCount, usage) {
         return `Missing arguments. Run \`vigilbase ${command} --help\` for usage.`;
     return `Missing ${missing.join(' and ')}. Usage: ${usage}`;
 }
+/** 'Unknown security command "x". Run `vigilbase security --help` for usage.' The pointer names the top-level group. */
+export function unknownSubcommand(group, subcommand) {
+    return new InvalidArgumentError(`Unknown ${group} command "${subcommand.slice(0, 80)}". Run \`vigilbase ${group.split(' ')[0]} --help\` for usage.`);
+}
+/** Parses user input with `schema`, throwing `message` instead of Zod's issue list. */
+export function parseArgument(schema, value, message) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new InvalidArgumentError(message);
+    return result.data;
+}
+/** An integer already checked as digits, within [min, max]. */
+export function inRange(label, value, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        throw new InvalidArgumentError(`${label} must be between ${min} and ${max}.`);
+    return value;
+}
+export function oneOf(label, values, value) {
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value))
+        throw new InvalidArgumentError(`${label} must be one of: ${values.join(', ')}.`);
+    return value;
+}
+/** A trimmed, non-empty flag value of at most `max` characters. */
+export function textValue(label, value, max) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new InvalidArgumentError(`${label} must not be empty.`);
+    if (trimmed.length > max)
+        throw new InvalidArgumentError(`${label} must be at most ${max} characters.`);
+    return trimmed;
+}
+export function isoDateTime(label, value) {
+    return parseArgument(z.iso.datetime({ offset: true }), value, `${label} must be an ISO 8601 date-time with an offset, for example 2026-10-12T00:00:00Z.`);
+}
 export function limitValue(raw, fallback, max) {
     if (raw === undefined)
         return fallback;
     if (!/^\d+$/.test(raw))
-        throw new Error('--limit must be an integer.');
-    return z.number().int().min(1).max(max).parse(Number(raw));
+        throw new InvalidArgumentError('--limit must be an integer.');
+    return inRange('--limit', Number(raw), 1, max);
 }
+const invitationRoles = ['admin', 'member', 'readonly', 'partner_owner', 'partner_sales', 'partner_operations', 'partner_finance', 'partner_readonly', 'billing_only', 'sales_only'];
 export const invitationSchema = z.object({
     email: z.string().trim().email(),
-    role: z.enum(['admin', 'member', 'readonly', 'partner_owner', 'partner_sales', 'partner_operations', 'partner_finance', 'partner_readonly', 'billing_only', 'sales_only']).default('member'),
+    role: z.enum(invitationRoles).default('member'),
 });
+export function invitationValue(email, role) {
+    return {
+        email: parseArgument(invitationSchema.shape.email, email, 'Enter a valid email address for the invitation.'),
+        role: oneOf('--role', invitationRoles, role) ?? 'member',
+    };
+}
 export const toolNameSchema = z.string().trim().min(1).max(128).regex(/^[a-z0-9-]+$/, 'Tool names must contain lowercase letters, digits, or hyphens.');
+export function toolNameValue(value) {
+    return parseArgument(toolNameSchema, value, 'Tool names must contain lowercase letters, digits, or hyphens.');
+}
+/** A scan target: trimmed, 1-2048 characters, no control characters. */
+export function targetValue(value) {
+    const trimmed = value.trim();
+    if (/[\u0000-\u001f\u007f]/.test(trimmed))
+        throw new InvalidArgumentError('Target must not contain control characters.');
+    if (!trimmed || trimmed.length > 2048)
+        throw new InvalidArgumentError('Target must be 1-2048 characters.');
+    return trimmed;
+}