@vigilbase/cli 0.2.3 → 0.2.4

package/dist/lib/client.js

@@ -82,6 +82,14 @@ function publicApiError(fallback, response, body) {
         isCliAuthored: !reason,
     });
 }
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** com's 422 for a scan the scanner could not assess (apps/com/lib/agent/handlers.ts): it still carries the result. */
+const unassessedScanSchema = z.object({
+    success: z.literal(false),
+    toolName: z.string(),
+    target: z.string(),
+    result: z.object({ status: z.literal('error') }).passthrough(),
+});
 /** The versioned public tools API. The unversioned /api/agent/tools aliases sunset on 2027-09-01. */
 export const PUBLIC_TOOLS_PATH = '/api/v1/agent/tools';
 /**
@@ -100,6 +108,7 @@ export class VigilbaseClient {
         const url = `${this.origin}${path.startsWith('/') ? path : `/${path}`}`;
         const { response, text } = await requestText(this.config, url, {
             ...init,
+            option: '--base-url',
             headers: {
                 Accept: 'application/json',
                 'User-Agent': this.config.userAgent,
@@ -142,7 +151,16 @@ export class VigilbaseClient {
             throw new VigilbaseApiError('Invalid tool execution response. Check the API URL or retry later.', { status: response.status });
         }
         if (!parsed.success) {
-            throw publicApiError(SCAN_FAILED_MESSAGE, response, body);
+            const unassessed = response.status === 422 ? unassessedScanSchema.safeParse(body) : null;
+            if (!unassessed?.success)
+                throw publicApiError(SCAN_FAILED_MESSAGE, response, body);
+            // A scan the scanner could not assess keeps its result, as One's route does.
+            const { toolName: name, target: scanned, result } = unassessed.data;
+            const toolRunId = typeof result.toolRunId === 'string' && UUID.test(result.toolRunId) ? result.toolRunId : undefined;
+            return {
+                success: false, toolName: name, target: scanned, grade: null, gradeScore: null, result,
+                error: null, status: 422, code: 'scan_unassessed', ...(toolRunId ? { toolRunId } : {}),
+            };
         }
         return parsed;
     }

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

@@ -7,13 +7,13 @@ export declare const cloudflareScopeSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type CloudflareScope = z.infer<typeof cloudflareScopeSchema>;
 export declare const workspaceSectionSchema: z.ZodEnum<{
+    zones: "zones";
+    settings: "settings";
     overview: "overview";
     reports: "reports";
-    zones: "zones";
     "rule-analyzer": "rule-analyzer";
     accounts: "accounts";
     checkups: "checkups";
-    settings: "settings";
 }>;
 export type WorkspaceSection = z.infer<typeof workspaceSectionSchema>;
 export declare const accountResourceSchema: z.ZodEnum<{

package/dist/lib/config.d.ts

@@ -23,12 +23,15 @@ export type CliConfigLegacy = CliConfig & {
 export declare function parseOrigin(raw: string, option: string): string;
 /** Default request timeout; also used when library callers omit `timeoutMs`. */
 export declare const DEFAULT_TIMEOUT_MS = 60000;
+/** localhost, 127.0.0.0/8 or [::1]: the hosts every origin option accepts for local development. */
+export declare function isLoopbackHostname(hostname: string): boolean;
 export declare function resolvePublicBaseUrl(explicit?: string | null): string;
 export declare function resolveOneBaseUrl(explicit?: string | null): string;
 /** Validate at transport boundaries too: library callers may construct config objects. */
 export declare function validateOneOrigin(raw: string): string;
 /** Production Identity: the only issuer trusted unless --auth-url / VIGILBASE_AUTH_URL names another. */
 export declare const DEFAULT_IDENTITY_ISSUER = "https://auth.vigilbase.com";
+/** Internal: accepted when named explicitly, but not offered to users (it isn't deployed publicly). */
 export declare const STAGING_IDENTITY_ISSUER = "https://identity-staging.vigilbase.com";
 export declare function resolveIdentityBaseUrl(raw: string): string;
 /**
@@ -38,6 +41,11 @@ export declare function resolveIdentityBaseUrl(raw: string): string;
  */
 export declare function trustedIdentityIssuer(config: Pick<CliConfig, 'oneBaseUrl' | 'identityBaseUrl'>): string;
 export declare function resolveClientId(explicit?: string | null): string;
+/** Why a config directory that isn't absolute was refused, naming the variable it came from. */
+export declare function relativeConfigDirProblem(configDir: string, env?: NodeJS.ProcessEnv): {
+    reason: string;
+    remedy: string;
+};
 /** The config directory, which must be absolute. */
 export declare function resolveConfigDir(explicit?: string | null, env?: NodeJS.ProcessEnv): string;
 export declare function createConfig(options?: {
@@ -48,6 +56,14 @@ export declare function createConfig(options?: {
     identityBaseUrl?: string | null;
     configDir?: string | null;
     timeoutMs?: number;
+    /**
+     * Which origins to validate now; both by default. The CLI leaves out those a command never contacts, so a bad
+     * value for them cannot fail it. Every One and Identity transport validates its origin again at use.
+     */
+    checkOrigins?: {
+        public: boolean;
+        one: boolean;
+    };
 }): CliConfigLegacy;
 /**
  * Config for `vigilbase local …` and `vigilbase cloudflare-checkup`. Local

package/dist/lib/config.js

@@ -20,41 +20,63 @@ export function parseOrigin(raw, option) {
 const timeoutSchema = z.number().int().min(1).max(2_147_483_647);
 /** Default request timeout; also used when library callers omit `timeoutMs`. */
 export const DEFAULT_TIMEOUT_MS = 60_000;
+/** localhost, 127.0.0.0/8 or [::1]: the hosts every origin option accepts for local development. */
+export function isLoopbackHostname(hostname) {
+    return hostname === 'localhost' || hostname === '[::1]' || /^127\.(?:\d{1,3}\.){2}\d{1,3}$/.test(hostname);
+}
+/** An option given as an empty string is a mistake (an unset shell variable), not a request for the default. */
+function explicitValue(raw, option) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!raw.trim())
+        throw new Error(`${option} is empty. Pass an origin or leave the option out.`);
+    return raw.trim();
+}
+/** The first set value with the name it came from; blank variables count as unset. */
+function firstSet(sources) {
+    for (const [name, value] of sources)
+        if (value?.trim())
+            return [name, value.trim()];
+    return undefined;
+}
 export function resolvePublicBaseUrl(explicit) {
-    const raw = explicit?.trim() ||
-        process.env.VIGILBASE_BASE_URL?.trim() ||
-        process.env.VIGILBASE_API_URL?.trim() ||
-        process.env.VIGILBASE_PUBLIC_URL?.trim() ||
-        DEFAULT_PUBLIC_BASE_URL;
-    return parseOrigin(raw, '--base-url / VIGILBASE_BASE_URL');
+    const [name, raw] = firstSet([
+        ['--base-url', explicitValue(explicit, '--base-url')],
+        ['VIGILBASE_BASE_URL', process.env.VIGILBASE_BASE_URL],
+        ['VIGILBASE_API_URL', process.env.VIGILBASE_API_URL],
+        ['VIGILBASE_PUBLIC_URL', process.env.VIGILBASE_PUBLIC_URL],
+    ]) ?? ['--base-url', DEFAULT_PUBLIC_BASE_URL];
+    const origin = parseOrigin(raw, name);
+    const url = new URL(origin);
+    if (url.protocol !== 'https:' && !isLoopbackHostname(url.hostname)) {
+        throw new Error(`${name} requires HTTPS; HTTP is allowed only for loopback development.`);
+    }
+    return origin;
 }
 export function resolveOneBaseUrl(explicit) {
-    const raw = explicit?.trim() ||
-        process.env.VIGILBASE_ONE_URL?.trim() ||
-        DEFAULT_ONE_BASE_URL;
-    return validateOneOrigin(raw);
+    return validateOneOrigin(explicitValue(explicit, '--one-url') || process.env.VIGILBASE_ONE_URL?.trim() || DEFAULT_ONE_BASE_URL);
 }
 /** Validate at transport boundaries too: library callers may construct config objects. */
 export function validateOneOrigin(raw) {
     const origin = parseOrigin(raw, '--one-url / VIGILBASE_ONE_URL');
     const url = new URL(origin);
-    const loopback = url.hostname === 'localhost' || url.hostname === '[::1]' || /^127\.(?:\d{1,3}\.){2}\d{1,3}$/.test(url.hostname);
-    if (url.protocol !== 'https:' && !loopback) {
+    if (url.protocol !== 'https:' && !isLoopbackHostname(url.hostname)) {
         throw new Error('--one-url / VIGILBASE_ONE_URL requires HTTPS; HTTP is allowed only for loopback development.');
     }
     return origin;
 }
 /** Production Identity: the only issuer trusted unless --auth-url / VIGILBASE_AUTH_URL names another. */
 export const DEFAULT_IDENTITY_ISSUER = 'https://auth.vigilbase.com';
+/** Internal: accepted when named explicitly, but not offered to users (it isn't deployed publicly). */
 export const STAGING_IDENTITY_ISSUER = 'https://identity-staging.vigilbase.com';
 const IDENTITY_OPTION = '--auth-url / VIGILBASE_AUTH_URL';
 function isIdentityLoopback(origin) {
-    return ['localhost', '127.0.0.1', '[::1]'].includes(new URL(origin).hostname);
+    return isLoopbackHostname(new URL(origin).hostname);
 }
 export function resolveIdentityBaseUrl(raw) {
     const origin = parseOrigin(raw, IDENTITY_OPTION);
     if (origin !== DEFAULT_IDENTITY_ISSUER && origin !== STAGING_IDENTITY_ISSUER && !isIdentityLoopback(origin)) {
-        throw new Error(`${IDENTITY_OPTION} must be ${DEFAULT_IDENTITY_ISSUER}, ${STAGING_IDENTITY_ISSUER} or a loopback development origin.`);
+        throw new Error(`${IDENTITY_OPTION} must be ${DEFAULT_IDENTITY_ISSUER} or a loopback development origin.`);
     }
     return origin;
 }
@@ -85,18 +107,54 @@ function configDirFromEnvironment(explicit, env) {
     const custom = explicit?.trim() || env.VIGILBASE_CONFIG_DIR?.trim();
     if (custom)
         return custom;
+    // Set but blank: '' is not absolute, so the store rejects it rather than falling back to another directory.
+    if (env.VIGILBASE_CONFIG_DIR !== undefined)
+        return '';
     const xdg = env.XDG_CONFIG_HOME?.trim();
     return xdg && isAbsolute(xdg) ? join(xdg, 'vigilbase') : join(homedir(), '.config', 'vigilbase');
 }
+/** Why a config directory that isn't absolute was refused, naming the variable it came from. */
+export function relativeConfigDirProblem(configDir, env = process.env) {
+    if (!configDir && env.VIGILBASE_CONFIG_DIR !== undefined) {
+        return { reason: 'VIGILBASE_CONFIG_DIR is empty', remedy: 'Set it to an absolute path or unset it.' };
+    }
+    if (env.VIGILBASE_CONFIG_DIR === undefined && !isAbsolute(homedir()) && configDir === join(homedir(), '.config', 'vigilbase')) {
+        const xdg = env.XDG_CONFIG_HOME?.trim() ? ', and a relative XDG_CONFIG_HOME is ignored' : '';
+        return { reason: `HOME (${homedir()}) is not an absolute path${xdg}`, remedy: 'Set HOME or VIGILBASE_CONFIG_DIR to an absolute path.' };
+    }
+    return { reason: `${configDir} is not an absolute path`, remedy: 'Set VIGILBASE_CONFIG_DIR to an absolute path.' };
+}
 /** The config directory, which must be absolute. */
 export function resolveConfigDir(explicit, env = process.env) {
     const configDir = configDirFromEnvironment(explicit, env);
-    if (!isAbsolute(configDir))
-        throw new Error('VIGILBASE_CONFIG_DIR must be an absolute path.');
+    if (!isAbsolute(configDir)) {
+        const { reason, remedy } = relativeConfigDirProblem(configDir, env);
+        throw new Error(`${reason}. ${remedy}`);
+    }
     return configDir;
 }
+/** The origin when it is valid, otherwise the value as given: left for the transport that uses it to reject. */
+function checkedLater(resolve, raw) {
+    try {
+        return resolve();
+    }
+    catch {
+        return raw;
+    }
+}
 export function createConfig(options) {
-    const publicBaseUrl = resolvePublicBaseUrl(options?.publicBaseUrl ?? options?.baseUrl);
+    const checks = options?.checkOrigins ?? { public: true, one: true };
+    const explicitPublic = options?.publicBaseUrl ?? options?.baseUrl;
+    const publicBaseUrl = checks.public
+        ? resolvePublicBaseUrl(explicitPublic)
+        : checkedLater(() => resolvePublicBaseUrl(explicitPublic), explicitPublic?.trim() || process.env.VIGILBASE_BASE_URL?.trim() ||
+            process.env.VIGILBASE_API_URL?.trim() || process.env.VIGILBASE_PUBLIC_URL?.trim() || DEFAULT_PUBLIC_BASE_URL);
+    const oneBaseUrl = checks.one
+        ? resolveOneBaseUrl(options?.oneBaseUrl)
+        : checkedLater(() => resolveOneBaseUrl(options?.oneBaseUrl), options?.oneBaseUrl?.trim() || process.env.VIGILBASE_ONE_URL?.trim() || DEFAULT_ONE_BASE_URL);
+    const authUrl = checks.one
+        ? explicitValue(options?.identityBaseUrl, '--auth-url') || process.env.VIGILBASE_AUTH_URL?.trim()
+        : options?.identityBaseUrl?.trim() || process.env.VIGILBASE_AUTH_URL?.trim();
     const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     if (!timeoutSchema.safeParse(timeoutMs).success) {
         throw new Error('Request timeout must be an integer between 1 and 2147483647 milliseconds.');
@@ -105,8 +163,8 @@ export function createConfig(options) {
         publicBaseUrl,
         /** Alias used by the current public tools client. */
         baseUrl: publicBaseUrl,
-        oneBaseUrl: resolveOneBaseUrl(options?.oneBaseUrl),
-        ...(options?.identityBaseUrl || process.env.VIGILBASE_AUTH_URL ? { identityBaseUrl: resolveIdentityBaseUrl(options?.identityBaseUrl || process.env.VIGILBASE_AUTH_URL) } : {}),
+        oneBaseUrl,
+        ...(authUrl ? { identityBaseUrl: checks.one ? resolveIdentityBaseUrl(authUrl) : checkedLater(() => resolveIdentityBaseUrl(authUrl), authUrl) } : {}),
         clientId: resolveClientId(options?.clientId),
         configDir: configDirFromEnvironment(options?.configDir, process.env),
         userAgent: `@vigilbase/cli/${CLI_VERSION} (+https://vigilbase.com; node/${process.version})`,

package/dist/lib/format.d.ts

@@ -5,7 +5,7 @@ export type Writer = {
 };
 /** A scan that ended without a result: com's copy (apps/com/lib/tools/execute-internal-scan.ts). */
 export declare const SCAN_FAILED_MESSAGE = "The scan couldn't be completed. Try again later.";
-/** Untrusted API data must never become terminal control sequences or bidi overrides. */
+/** Untrusted API data must never become terminal control sequences, bidi overrides or invisible text. */
 export declare function sanitizeTerminal(value: string): string;
 /** One sanitised line, cut to `maxLength` characters with an ellipsis. */
 export declare function singleLine(value: string, maxLength?: number): string;

package/dist/lib/format.js

@@ -1,10 +1,18 @@
 import { stripVTControlCharacters } from 'node:util';
+import { LOCAL_ERROR_CODES } from '../local/cloudflare-checkup/errors.js';
 /** A scan that ended without a result: com's copy (apps/com/lib/tools/execute-internal-scan.ts). */
 export const SCAN_FAILED_MESSAGE = "The scan couldn't be completed. Try again later.";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/** Untrusted API data must never become terminal control sequences or bidi overrides. */
+/**
+ * Terminal controls, bidi overrides, and invisible characters an agent reads but a person can't
+ * see: zero-width characters, word joiners, the BOM, line separators and tag characters.
+ */
+const TERMINAL_UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu;
+/** The same, less the C0 controls JSON.stringify already escapes. */
+const JSON_UNSAFE = /[\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu;
+/** Untrusted API data must never become terminal control sequences, bidi overrides or invisible text. */
 export function sanitizeTerminal(value) {
-    return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
+    return stripVTControlCharacters(value).replace(TERMINAL_UNSAFE, '');
 }
 /** One sanitised line, cut to `maxLength` characters with an ellipsis. */
 export function singleLine(value, maxLength = 300) {
@@ -25,7 +33,7 @@ export function createWriter(stdout = process.stdout, stderr = process.stderr) {
 }
 export function printJson(writer, value) {
     // Keep JSON lossless while preventing literal terminal/bidi controls in rendered output.
-    writer.stdout(JSON.stringify(value, null, 2).replace(/[\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`));
+    writer.stdout(JSON.stringify(value, null, 2).replace(JSON_UNSAFE, (char) => [...Array(char.length).keys()].map((index) => `\\u${char.charCodeAt(index).toString(16).padStart(4, '0')}`).join('')));
 }
 function asRecord(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -156,6 +164,9 @@ function collectFindings(result) {
                 if (!header)
                     continue;
                 const status = typeof header.status === 'string' ? header.status : '';
+                // An absent header the scanner graded good (X-XSS-Protection) is not a finding.
+                if (status === 'good')
+                    continue;
                 if (status !== 'missing' && status !== 'misconfigured' && header.present !== false) {
                     continue;
                 }
@@ -191,30 +202,49 @@ function collectFindings(result) {
     return findings;
 }
 const MAX_FINDING_LINES = 12;
+/** The shareable report link, only when it is a plain https://vigilbase.com URL. */
+function reportUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' || url.hostname !== 'vigilbase.com' || url.port || url.username || url.password)
+        return null;
+    return url.href;
+}
 /** Compact human lines for a scan result (no UI/skill links, no summary dump). */
 function summarizeResultCompact(result) {
     if (!result)
         return [];
+    // Server text never starts a line of its own: each message line is indented like the rest.
     const lines = [];
     const message = typeof result.message === 'string' ? result.message : null;
     if (message)
-        lines.push(message);
+        lines.push(...sanitizeTerminal(message).split('\n').map((line) => line.trim()).filter(Boolean));
     const counts = summarizeCounts(result);
     if (counts)
         lines.push(counts);
     const findings = collectFindings(result);
     for (const finding of findings.slice(0, MAX_FINDING_LINES)) {
-        const sev = finding.severity ? ` ${finding.severity}` : '';
+        const sev = finding.severity ? ` ${singleLine(finding.severity, 20)}` : '';
         if (finding.recommendation) {
-            lines.push(`✗${sev}  ${finding.title} — ${finding.recommendation}`);
+            lines.push(`✗${sev}  ${singleLine(finding.title)} — ${singleLine(finding.recommendation)}`);
         }
         else {
-            lines.push(`✗${sev}  ${finding.title}`);
+            lines.push(`✗${sev}  ${singleLine(finding.title)}`);
         }
     }
     if (findings.length > MAX_FINDING_LINES) {
         lines.push(`… +${findings.length - MAX_FINDING_LINES} more (use --json)`);
     }
+    const report = reportUrl(result.shareableUrl);
+    if (report)
+        lines.push(`Report: ${report}`);
     return lines;
 }
 export function formatToolsList(catalog, mode, writer, options) {
@@ -222,11 +252,12 @@ export function formatToolsList(catalog, mode, writer, options) {
         printJson(writer, catalog);
         return;
     }
-    const publicNames = catalog.tools.map((tool) => tool.toolName).join('  ');
+    // Catalog names are the server's: a newline in one must not start a line of its own.
+    const publicNames = catalog.tools.map((tool) => singleLine(tool.toolName, 100)).join('  ');
     writer.stdout(`public     ${publicNames || '(none)'}`);
     const authRequired = options?.authRequiredTools ?? options?.sensitiveTools ?? [];
     if (authRequired.length) {
-        writer.stdout(`auth-req   ${authRequired.join('  ')}`);
+        writer.stdout(`auth-req   ${authRequired.map((name) => singleLine(name, 100)).join('  ')}`);
     }
     if (typeof options?.isAuthenticated === 'boolean') {
         writer.stdout(options.isAuthenticated ? 'auth       signed in' : 'auth       signed out');
@@ -234,23 +265,24 @@ export function formatToolsList(catalog, mode, writer, options) {
 }
 export function formatToolDescription(tool, mode, writer, skillMarkdown) {
     if (mode === 'json') {
-        printJson(writer, { ...tool, skillMarkdown: skillMarkdown ?? null });
+        printJson(writer, { success: true, ...tool, skillMarkdown: skillMarkdown ?? null });
         return;
     }
-    writer.stdout(`${tool.toolName}  ${tool.name}`);
-    const blurb = tool.description.length > 100
-        ? `${tool.description.slice(0, 97).trimEnd()}…`
-        : tool.description;
-    writer.stdout(blurb);
-    writer.stdout(`vigilbase run ${tool.toolName} <target>`);
+    // Catalog text is the server's: each field stays on its own line.
+    writer.stdout(`${singleLine(tool.toolName, 100)}  ${singleLine(tool.name)}`);
+    writer.stdout(singleLine(tool.description, 2000));
+    if (tool.targetDescription)
+        writer.stdout(`Target: ${singleLine(tool.targetDescription)}`);
+    writer.stdout(`vigilbase run ${singleLine(tool.toolName, 100)} <target>`);
     if (skillMarkdown) {
         writer.stdout();
         writer.stdout(skillMarkdown.trimEnd());
     }
 }
 /**
- * Why a scan failed, or null when it has a result. A scan com could not grade comes back
- * inside a successful response as `status: "error"` with a message and no grade.
+ * Why a scan failed, or null when it has a result. A scan the scanner could not grade has
+ * `status: "error"` with a message and no grade: One and vigilbase.com both send it as a 422,
+ * which the clients turn into a `scan_unassessed` result.
  */
 function scanFailure(result) {
     if (result.success && result.result?.status !== 'error')
@@ -273,24 +305,37 @@ export function formatExecuteResult(result, mode, writer) {
         printJson(writer, failure === null ? result : { ...result, success: false, error: failure, grade: null, gradeScore: null });
         return;
     }
-    const tool = result.toolName ?? 'tool';
-    const target = result.target ?? '';
+    const tool = singleLine(result.toolName ?? 'tool', 100);
+    const target = singleLine(result.target ?? '', 2100);
+    const gradeLetter = result.grade != null ? singleLine(String(result.grade), 10) : '';
     const grade = failure === null && result.grade != null
-        ? `${result.grade}${result.gradeScore != null ? ` ${result.gradeScore}` : ''}`
+        ? `${gradeLetter}${result.gradeScore != null ? ` ${singleLine(String(result.gradeScore), 10)}` : ''}`
         : 'n/a';
     if (failure !== null) {
         writer.stderr(`✗ ${tool} · ${target} · ${grade}`);
         writer.stderr(`  ${failure}`);
         return;
     }
-    writer.stdout(`✓ ${tool} · ${target} · ${grade}`);
+    // A graded scan exits 0 whatever the grade; only a secure one without an F gets the ✓.
+    const isClean = result.result?.status === 'secure' && gradeLetter.toUpperCase() !== 'F';
+    writer.stdout(`${isClean ? '✓' : '•'} ${tool} · ${target} · ${grade}`);
     for (const line of summarizeResultCompact(result.result)) {
         writer.stdout(`  ${line}`);
     }
 }
+/** Issues of a ZodError, also one from another copy of zod. */
+function zodErrorIssues(error) {
+    if (!(error instanceof Error) || error.name !== 'ZodError' || !('issues' in error) || !Array.isArray(error.issues))
+        return null;
+    return error.issues;
+}
 export function formatError(error, mode, writer) {
     let message = error instanceof Error ? error.message : String(error);
     let reason = '';
+    const zodIssues = zodErrorIssues(error);
+    // A ZodError's message is its serialised issue list; show the issue messages instead.
+    if (zodIssues)
+        message = zodIssues.map((issue) => `${issue.path?.length ? `${issue.path.map(String).join('.')}: ` : ''}${singleLine(String(issue.message))}`).join(' ') || 'Invalid argument.';
     // Server bodies can contain credentials, customer data, or arbitrary error text, so an error that
     // carries one shows only text the CLI wrote, or the reason the public client accepted.
     if (error && typeof error === 'object' && 'body' in error && error.body != null && 'status' in error && typeof error.status === 'number') {
@@ -308,6 +353,8 @@ export function formatError(error, mode, writer) {
         success: false,
         error: message,
     };
+    if (zodIssues)
+        payload.code = 'INVALID_ARGUMENT';
     if (error && typeof error === 'object') {
         if ('status' in error && typeof error.status === 'number' &&
             Number.isInteger(error.status) && error.status >= 0 && error.status <= 599) {
@@ -339,9 +386,13 @@ export function formatError(error, mode, writer) {
         printJson(writer, payload);
         return;
     }
-    writer.stderr(`Error: ${message}${reason && typeof payload.code === 'string' ? ` (${payload.code})` : ''}`);
+    // Local checkup codes show as in the terminal UI; invalid-argument messages already name the flag.
+    const isLocalCode = LOCAL_ERROR_CODES.includes(payload.code);
+    writer.stderr(`Error: ${message}${(reason || isLocalCode) && typeof payload.code === 'string' ? ` (${payload.code})` : ''}`);
     if (typeof payload.retryAfterSec === 'number') {
-        writer.stderr(`Retry after ${payload.retryAfterSec}s`);
+        // Quotas reset after up to an hour: minutes read better than thousands of seconds.
+        const seconds = payload.retryAfterSec;
+        writer.stderr(seconds < 120 ? `Retry after ${seconds}s` : `Retry after about ${Math.round(seconds / 60)} minutes`);
     }
     if (typeof payload.hint === 'string') {
         writer.stderr(`Hint: ${payload.hint}`);

package/dist/lib/help.js

@@ -19,6 +19,52 @@ export function isCatalogTool(name) {
 }
 /** Column where descriptions start in the main help: two-space indent, term, at least two spaces. */
 const DESCRIPTION_COLUMN = 31;
+/** Help lines fit an 80-column terminal. */
+const HELP_WIDTH = 80;
+/**
+ * Where a wrapped line continues: under the description of a row, under the text of a usage
+ * line, at the indent of a note, or at the margin for prose.
+ */
+function continuationIndent(line) {
+    const described = /^ {2}\S.*? {2,}(?=\S)/.exec(line);
+    if (described)
+        return described[0].length;
+    if (line.startsWith('Usage: '))
+        return 'Usage: '.length;
+    const indent = /^ */.exec(line)[0].length;
+    return indent === 0 ? 0 : Math.max(indent, 4);
+}
+/** Where to cut a line at most `width` long: before an option group, else at a space, else after a |. */
+function breakPoint(line, from, width) {
+    const head = line.slice(0, width + 1);
+    const bracket = head.lastIndexOf(' [');
+    if (bracket > from + (width - from) / 2)
+        return { cut: bracket, skip: 1 };
+    const space = head.lastIndexOf(' ');
+    if (space > from)
+        return { cut: space, skip: 1 };
+    const bar = line.slice(0, width).lastIndexOf('|');
+    return bar > from ? { cut: bar + 1, skip: 0 } : null;
+}
+/** Wraps help lines longer than HELP_WIDTH, keeping descriptions aligned. */
+function wrapHelp(text) {
+    return text.split('\n').flatMap((line) => {
+        const lines = [];
+        const pad = ' '.repeat(continuationIndent(line));
+        let rest = line;
+        // Past the first cut, only cut after the indent, so every line is shorter than the last.
+        let from = /^ */.exec(line)[0].length;
+        while (rest.length > HELP_WIDTH) {
+            const at = breakPoint(rest, from, HELP_WIDTH);
+            if (!at)
+                break;
+            lines.push(rest.slice(0, at.cut).trimEnd());
+            rest = `${pad}${rest.slice(at.cut + at.skip).trimStart()}`;
+            from = pad.length;
+        }
+        return [...lines, rest];
+    }).join('\n');
+}
 /** Two-column help rows whose descriptions all start at DESCRIPTION_COLUMN. */
 function helpRows(rows) {
     return rows
@@ -35,7 +81,7 @@ const GLOBAL_OPTIONS = helpRows([
     ['--auth-url <origin>', 'Identity issuer (default: auth.vigilbase.com)'],
     ['--client-id <id>', 'Device authorization client ID'],
 ]);
-export const HELP_TEXT = `Usage: vigilbase <command>
+export const HELP_TEXT = wrapHelp(`Usage: vigilbase <command>
 
 Public tools (no login)
   list                         List available tools
@@ -63,7 +109,7 @@ Account (login required)
   cf <command>                 Cloudflare accounts, zones, DNS, WAF, analytics
   security <command>           Incidents, logs, assets, detections, intel, reports
   watchdog [list|scans]        Watchdog targets / scans
-  customers <command>          Customer records, billing, reports, investigations
+  customers <command>          Customers, billing, reports, investigations
   orgs <command>               Organizations, members, permission roles
   monitoring <command>         Health, probes, metrics, customer targets
   support tickets              Support ticket history
@@ -81,7 +127,7 @@ Examples
   vigilbase runs list --json
   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)) {
@@ -100,6 +146,10 @@ Details: vigilbase describe ${tool}`;
 }
 export const HELP_USAGE = 'Usage: vigilbase help [<command> | <tool>]';
 export function helpForCommand(command) {
+    const help = commandHelp(command);
+    return help === null ? null : wrapHelp(help);
+}
+function commandHelp(command) {
     switch (command) {
         case 'help':
             return `${HELP_USAGE}
@@ -127,13 +177,14 @@ Run vigilbase help <tool> for a tool's usage.`;
 
 Checks the public tools API, your session (Identity's userinfo endpoint when
 signed in through Identity, otherwise One's session endpoint) and any saved
-sign-in independently. Login is optional. Exits with status 1 if any check fails.
-Use --base-url, --one-url, --auth-url and --timeout to check other environments.`;
+sign-in independently. Login is optional. Exits with status 1 if any check
+fails. Use --base-url, --one-url, --auth-url and --timeout to check other
+environments.`;
         case 'account':
             return `Usage: vigilbase account [services|org|endpoints|sessions|invites|billing] [--json]
 
 Requires \`vigilbase login\`.
-  account invites create --email user@example.com [--role member] --confirm`;
+  account invites create <email>|--email <email> [--role <role>] --confirm`;
         case 'runhistory':
         case 'runs':
             return `Usage: vigilbase runs [list|get <UUID>] [--json]

package/dist/lib/network.d.ts

@@ -1,10 +1,14 @@
 import type { CliConfig } from './config.js';
 export declare class NetworkError extends Error {
     readonly code: string;
+    readonly hint?: string | undefined;
     readonly status = 0;
-    constructor(message: string, code: string, cause?: unknown);
+    /** `hint` is printed after the error; doctor, which is the connectivity check, leaves it out. */
+    constructor(message: string, code: string, cause?: unknown, hint?: string | undefined);
 }
 export declare function networkError(error: unknown, url: string, timeoutMs: number, timedOut: boolean): NetworkError;
+/** The option that sets each service's origin, which a caller names for the redirect message. */
+export type OriginOption = '--base-url' | '--one-url' | '--auth-url';
 export declare const MAX_RESPONSE_BYTES: number;
 /** Bound decoded bytes even when Content-Length is absent, compressed, or dishonest. */
 export declare function readBoundedBody(response: Response, signal: AbortSignal, maxBytes?: number): Promise<string>;
@@ -18,8 +22,13 @@ export declare function anySignal(signals: AbortSignal[]): {
     signal: AbortSignal;
     dispose: () => void;
 };
-/** Keep the timeout active until the complete response body has been read. */
-export declare function requestText(config: CliConfig, url: string, init?: RequestInit): Promise<{
+/**
+ * Keep the timeout active until the complete response body has been read. `option` names the option that sets the
+ * service's origin, for the message when it redirects.
+ */
+export declare function requestText(config: CliConfig, url: string, { option, ...init }?: RequestInit & {
+    option?: OriginOption;
+}): Promise<{
     response: Response;
     text: string;
 }>;