@vigilbase/cli 0.2.1 → 0.2.3

package/dist/lib/help.d.ts

@@ -1,3 +1,6 @@
 export declare const HELP_TAGLINE = "one \u00B7 security \u00B7 tools";
+/** A tool from the catalog the CLI knows offline: it runs as `run <tool> <target>`, not as a command. */
+export declare function isCatalogTool(name: string): boolean;
 export declare const HELP_TEXT: string;
+export declare const HELP_USAGE = "Usage: vigilbase help [<command> | <tool>]";
 export declare function helpForCommand(command: string): string | null;

package/dist/lib/help.js

@@ -2,7 +2,21 @@ import { CLOUDFLARE_HELP } from '../commands/cloudflare.js';
 import { LOCAL_HELP } from '../commands/local.js';
 import { ONE_HELP } from '../commands/one.js';
 import { SECURITY_HELP } from '../commands/security.js';
+import { isOneAuthRequiredTool, ONE_AUTH_REQUIRED_TOOLS } from './one-client.js';
 export const HELP_TAGLINE = 'one · security · tools';
+/** vigilbase.com's public catalog, with each tool's shortcut command. `help <tool>` answers offline. */
+const PUBLIC_TOOL_SHORTCUTS = {
+    'security-headers': 'headers <url>',
+    'email-security': 'email <domain>',
+};
+const PUBLIC_TOOLS = Object.keys(PUBLIC_TOOL_SHORTCUTS);
+function isPublicTool(name) {
+    return Object.hasOwn(PUBLIC_TOOL_SHORTCUTS, name);
+}
+/** A tool from the catalog the CLI knows offline: it runs as `run <tool> <target>`, not as a command. */
+export function isCatalogTool(name) {
+    return isPublicTool(name) || isOneAuthRequiredTool(name);
+}
 /** Column where descriptions start in the main help: two-space indent, term, at least two spaces. */
 const DESCRIPTION_COLUMN = 31;
 /** Two-column help rows whose descriptions all start at DESCRIPTION_COLUMN. */
@@ -32,7 +46,7 @@ Public tools (no login)
   badge <domain> · doctor      Badge URL · connectivity
 
 Auth-required tools (after login)
-  website-security · react2shell · fortibleed-check
+${ONE_AUTH_REQUIRED_TOOLS.map((tool) => `  run ${tool} <target>`).join('\n')}
 
 On this machine (no login)
   cloudflare-checkup           Run the Cloudflare Checkup on this machine in one
@@ -57,7 +71,7 @@ Account (login required)
 Options
 ${GLOBAL_OPTIONS}
 
-Use vigilbase <command> --help for command options.
+Use vigilbase <command> --help or vigilbase help <tool> for usage.
 
 Examples
   vigilbase headers https://vigilbase.com
@@ -68,16 +82,40 @@ Examples
   vigilbase cf zones
   vigilbase security incidents --severity high
 `;
+/** How to run a catalog tool: `help <tool>` and `<tool> --help`, since tools run as `run <tool> <target>`. */
+function helpForTool(tool) {
+    if (isPublicTool(tool)) {
+        return `Usage: vigilbase run ${tool} <target> [--json] [--via public|one] [--public]
+
+Public tool, no login needed. Shortcut: vigilbase ${PUBLIC_TOOL_SHORTCUTS[tool]}
+Details: vigilbase describe ${tool}`;
+    }
+    if (isOneAuthRequiredTool(tool)) {
+        return `Usage: vigilbase run ${tool} <target> [--json]
+
+Runs through Vigilbase One: run \`vigilbase login\` first.
+Details: vigilbase describe ${tool}`;
+    }
+    return null;
+}
+export const HELP_USAGE = 'Usage: vigilbase help [<command> | <tool>]';
 export function helpForCommand(command) {
     switch (command) {
+        case 'help':
+            return `${HELP_USAGE}
+
+Shows the usage of a command or of a tool, for example vigilbase help run or
+vigilbase help website-security. Without one, shows every command.`;
         case 'tools':
         case 'list':
             return `Usage: vigilbase list [--json]`;
         case 'run':
             return `Usage: vigilbase run <tool> <target> [--json] [--via public|one] [--public]
 
-Public: security-headers, email-security
-Login:  website-security, react2shell, fortibleed-check`;
+Public: ${PUBLIC_TOOLS.join(', ')}
+Login:  ${ONE_AUTH_REQUIRED_TOOLS.join(', ')}
+
+Run vigilbase help <tool> for a tool's usage.`;
         case 'describe':
             return `Usage: vigilbase describe <tool> [--json] [--no-skill]`;
         case 'skill':
@@ -131,6 +169,6 @@ Prefer --token-stdin with piped input to keep tokens out of command arguments.`;
         case 'email':
             return `Usage: vigilbase email <domain> [--json] [--via public|one] [--public]`;
         default:
-            return null;
+            return helpForTool(command);
     }
 }

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

@@ -7,6 +7,8 @@ import type { CliConfig } from './config.js';
 export type OneToolExecuteResponse = {
     success: boolean;
     error?: string;
+    /** `scan_unassessed`: the scanner ran but could not assess the target. */
+    code?: string;
     data?: {
         toolRunId?: string;
         status?: string;
@@ -54,6 +56,8 @@ export declare class VigilbaseOneClient {
     /** Authenticated JSON transport shared by the One command clients. */
     requestJson<T extends ApiErrorBody = Record<string, unknown>>(path: string, init?: RequestInit, options?: {
         allowStatuses?: number[];
+        /** Whether the request names a customer outside the query string (a JSON body). */
+        hasCustomerScope?: boolean;
     }): Promise<T>;
     getSession(): Promise<OneSessionResponse>;
     getAccount(): Promise<Record<string, unknown>>;

package/dist/lib/one-client.js

@@ -6,6 +6,8 @@ import { z } from 'zod';
 import { validateOneOrigin } from './config.js';
 import { validateStripePortalUrl } from './open-url.js';
 import { parseJsonResponse, requestText } from './network.js';
+import { oneErrorHint } from './one-error-hints.js';
+import { SCAN_FAILED_MESSAGE } from './format.js';
 import { retryAfterSeconds, VigilbaseApiError } from './client.js';
 /**
  * Tools that require Vigilbase One authentication (auth-required scanners).
@@ -129,9 +131,15 @@ export class VigilbaseOneClient {
         if (errorDetails.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
             message = 'Select a customer with --customer-id <customer UUID> for security commands.';
         }
+        const hint = response.ok ? undefined : oneErrorHint({
+            method: init?.method ?? 'GET', path, status: response.status, code: errorDetails.code, hasCustomerScope: options?.hasCustomerScope,
+        });
+        // Every message below is the CLI's own; One's error text stays in the body, which is never printed.
         if (response.status === 401 || response.status === 403) {
-            throw new VigilbaseApiError(message ||
-                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code });
+            throw new VigilbaseApiError(message || (response.status === 401
+                ? 'Authentication required. Run `vigilbase login`.'
+                // Signed in, but One refuses this user or this request: logging in again won't help.
+                : "You don't have access to this."), { status: response.status, body: parsed, code: errorDetails.code, hint, isCliAuthored: true });
         }
         if (response.status === 429) {
             throw new VigilbaseApiError(message || 'Rate limit exceeded.', {
@@ -139,18 +147,21 @@ export class VigilbaseOneClient {
                 body: parsed,
                 retryAfterSec: retryAfterSeconds(response, body),
                 code: errorDetails.code,
+                isCliAuthored: true,
             });
         }
         const allowed = options?.allowStatuses ?? [];
         if (!response.ok && !allowed.includes(response.status)) {
             throw new VigilbaseApiError(message ||
-                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code });
+                `Request failed (HTTP ${response.status}).`, { status: response.status, body: parsed, code: errorDetails.code, hint, isCliAuthored: true });
         }
         if (!z.record(z.string(), z.unknown()).safeParse(body).success) {
             throw new VigilbaseApiError('Invalid One API response. Expected a JSON object.', { status: response.status });
         }
         if (parsed.success === false || ('ok' in parsed && parsed.ok === false)) {
-            throw new VigilbaseApiError('One API reported an unsuccessful operation.', { status: response.status, body: parsed, code: errorDetails.code });
+            throw new VigilbaseApiError('One API reported an unsuccessful operation.', {
+                status: response.status, body: parsed, code: errorDetails.code, isCliAuthored: true,
+            });
         }
         return parsed;
     }
@@ -184,7 +195,7 @@ export class VigilbaseOneClient {
         }
         const { response, body } = await this.request('/api/auth/get-session');
         if (!response.ok) {
-            throw new VigilbaseApiError(`Failed to load One session (HTTP ${response.status})`, { status: response.status, body });
+            throw new VigilbaseApiError(`Failed to load One session (HTTP ${response.status})`, { status: response.status, body, isCliAuthored: true });
         }
         const schema = z.object({
             session: z.record(z.string(), z.unknown()).nullable().optional(),
@@ -279,10 +290,70 @@ export class VigilbaseOneClient {
         return this.requestJson(`/api/tool-runs/${encodeURIComponent(id)}`);
     }
     async executeTool(toolName, target) {
-        return this.requestJson(`/api/tools/${encodeURIComponent(toolName)}/execute`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ target }),
-        }, { allowStatuses: [422] });
+        try {
+            return await this.requestJson(`/api/tools/${encodeURIComponent(toolName)}/execute`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ target }),
+            }, { allowStatuses: [422] });
+        }
+        catch (error) {
+            const unassessed = unassessedScan(error);
+            if (unassessed)
+                return unassessed;
+            throw failedScanError(error) ?? error;
+        }
     }
 }
+/** One's answer when the scan itself failed, for example when com ran out of memory. */
+const failedScanSchema = z.object({
+    success: z.literal(false),
+    data: z.object({ status: z.literal('failed'), toolRunId: z.unknown().optional() }).passthrough(),
+}).passthrough();
+const unassessedScanSchema = z.object({
+    code: z.literal('scan_unassessed'),
+    data: z.object({
+        toolRunId: z.unknown().optional(),
+        result: z.object({ status: z.literal('error'), message: z.string() }).passthrough(),
+    }),
+});
+/**
+ * A scan the scanner ran but could not assess (a bot verification challenge, an
+ * error page). The result carries the scanner's message, which the formatter
+ * prints bounded like any scanner result; One's error text stays unused.
+ */
+function unassessedScan(error) {
+    if (!(error instanceof VigilbaseApiError) || error.status !== 422)
+        return undefined;
+    const unassessed = unassessedScanSchema.safeParse(error.body);
+    if (!unassessed.success)
+        return undefined;
+    const toolRunId = z.string().uuid().safeParse(unassessed.data.data.toolRunId);
+    return {
+        success: false,
+        code: 'scan_unassessed',
+        data: {
+            toolRunId: toolRunId.success ? toolRunId.data : undefined,
+            status: 'failed',
+            grade: null,
+            gradeScore: null,
+            result: unassessed.data.data.result,
+        },
+    };
+}
+/** com's copy for a 422 failed scan, with the run One recorded; One's error text stays hidden. */
+function failedScanError(error) {
+    if (!(error instanceof VigilbaseApiError) || error.status !== 422)
+        return undefined;
+    const failed = failedScanSchema.safeParse(error.body);
+    if (!failed.success)
+        return undefined;
+    const toolRunId = z.string().uuid().safeParse(failed.data.data.toolRunId);
+    return new VigilbaseApiError(SCAN_FAILED_MESSAGE, {
+        status: 422,
+        body: error.body,
+        code: error.code,
+        isCliAuthored: true,
+        toolRunId: toolRunId.success ? toolRunId.data : undefined,
+    });
+}

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

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

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

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

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

@@ -10,6 +10,8 @@ export declare const LOCAL_ERROR_HINTS: Record<LocalCheckupErrorCode, string>;
  * hint names both ways out.
  */
 export declare const ENV_TOKEN_AUTH_HINT = "Set CLOUDFLARE_API_TOKEN in this shell to a valid read-only Cloudflare API token (read -rs CLOUDFLARE_API_TOKEN && export CLOUDFLARE_API_TOKEN) and run the same command again, or unset it (or use --cf-auth profile) to sign in with your browser instead.";
+/** SNAPSHOT_INVALID for an `inspect` or `submit` path with no file: nothing to collect again, so how to make one. */
+export declare const SNAPSHOT_MISSING_HINT = "Check the file path. To collect a snapshot into a file, run `npx @vigilbase/cli cloudflare-checkup collect --out <file>`.";
 /** CF_PERMISSION_DENIED in env mode: the token lacks a read permission; the browser sign-in is the other way out. */
 export declare const ENV_TOKEN_PERMISSION_HINT = "The API token in CLOUDFLARE_API_TOKEN cannot read everything the checkup needs. Add the read permissions to it, or unset it (or use --cf-auth profile) to sign in with your browser instead, then run the same command again.";
 export declare class LocalCheckupError extends Error {

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

@@ -75,6 +75,8 @@ export const LOCAL_ERROR_HINTS = {
  * hint names both ways out.
  */
 export const ENV_TOKEN_AUTH_HINT = `Set ${CF_TOKEN_ENV} in this shell to a valid read-only Cloudflare API token (read -rs ${CF_TOKEN_ENV} && export ${CF_TOKEN_ENV}) and run the same command again, or unset it (or use --cf-auth profile) to sign in with your browser instead.`;
+/** SNAPSHOT_INVALID for an `inspect` or `submit` path with no file: nothing to collect again, so how to make one. */
+export const SNAPSHOT_MISSING_HINT = 'Check the file path. To collect a snapshot into a file, run `npx @vigilbase/cli cloudflare-checkup collect --out <file>`.';
 /** CF_PERMISSION_DENIED in env mode: the token lacks a read permission; the browser sign-in is the other way out. */
 export const ENV_TOKEN_PERMISSION_HINT = `The API token in ${CF_TOKEN_ENV} cannot read everything the checkup needs. Add the read permissions to it, or unset it (or use --cf-auth profile) to sign in with your browser instead, then run the same command again.`;
 export class LocalCheckupError extends Error {

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

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

package/dist/types.d.ts

@@ -53,6 +53,10 @@ export type AgentToolExecuteResponse = {
     error?: AgentApiError | string | null;
     uiUrl?: string;
     skillUrl?: string;
+    /** A One scan the scanner could not assess: One's status and code, and the run it recorded. */
+    status?: number;
+    code?: string;
+    toolRunId?: string;
     retryAfterSec?: number;
     toolsUrl?: string;
     skillsIndex?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vigilbase/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.",
   "keywords": [
     "vigilbase",