@vigilbase/cli 0.2.2 → 0.2.4

package/dist/commands/public-tools.js

@@ -1,13 +1,14 @@
-import { z } from 'zod';
-import { toolNameSchema, validateArguments } from './legacy-validation.js';
+import { InvalidArgumentError, targetValue, toolNameValue, validateArguments } from './legacy-validation.js';
 import { NetworkError } from '../lib/network.js';
 import { PUBLIC_TOOLS_PATH, VigilbaseApiError } from '../lib/client.js';
 import { getOneAccessToken, getOptionalOneAccessToken, hasUsableSignIn, readCredentials } from '../auth/index.js';
-import { SignInUnsupportedError } from '../auth/store.js';
-import { formatExecuteResult, formatToolDescription, formatToolsList, } from '../lib/format.js';
+import { CredentialsPathError, NotSignedInError, SignInUnsupportedError } from '../auth/store.js';
+import { formatExecuteResult, formatToolDescription, formatToolsList, isSuccessfulScan, } from '../lib/format.js';
 import { isOneAuthRequiredTool, isOneExecutableTool, ONE_AUTH_REQUIRED_TOOLS, resolveToolDefinition, VigilbaseOneClient, } from '../lib/one-client.js';
 import { EXIT, ok, outputJson, withSpinner, } from './helpers.js';
-const ONE_SIGN_IN_REQUIRED = 'This tool needs a Vigilbase One sign-in: run `vigilbase login`.';
+function unknownTool(toolName) {
+    return new InvalidArgumentError(`Unknown tool "${toolName}". Run \`vigilbase list\` for the allowlist.`);
+}
 /**
  * For --via one and auth-required tools only: any sign-in problem fails. Specific errors keep their
  * message; those that don't already point to `vigilbase login` get it as their hint.
@@ -18,14 +19,15 @@ async function requireOneSignIn(config) {
         accessToken = await getOneAccessToken(config);
     }
     catch (error) {
-        // Windows cannot sign in at all, so pointing to login would mislead.
-        if (error instanceof Error && !(error instanceof SignInUnsupportedError) && !error.message.includes('`vigilbase login`')) {
-            Object.assign(error, { hint: ONE_SIGN_IN_REQUIRED });
+        // Windows cannot sign in at all, and login stops on an unsafe credentials path too, so pointing to it would mislead.
+        const isLoginBlocked = error instanceof SignInUnsupportedError || error instanceof CredentialsPathError;
+        if (error instanceof Error && !isLoginBlocked && !error.message.includes('`vigilbase login`')) {
+            Object.assign(error, { hint: new NotSignedInError().message });
         }
         throw error;
     }
     if (!accessToken)
-        throw new Error(ONE_SIGN_IN_REQUIRED);
+        throw new NotSignedInError();
     return accessToken;
 }
 /** Public tools work without login. Auth-required tools need Vigilbase One. */
@@ -39,6 +41,7 @@ export const handleList = async (ctx) => {
             ...catalog,
             authenticated,
             authRequiredTools: [...ONE_AUTH_REQUIRED_TOOLS],
+            // Signed out, nothing runs through One.
             oneExecutableTools: authenticated
                 ? [
                     ...new Set([
@@ -46,7 +49,7 @@ export const handleList = async (ctx) => {
                         ...ONE_AUTH_REQUIRED_TOOLS,
                     ]),
                 ]
-                : catalog.tools.map((tool) => tool.toolName),
+                : [],
         });
     }
     else {
@@ -78,17 +81,23 @@ export const handleRun = async (ctx) => {
     }
     if (!toolName || !target)
         throw new Error(`Usage: ${usage}`);
-    toolName = toolNameSchema.parse(toolName);
-    target = z.string().trim().min(1).max(2048).refine((value) => !/[\u0000-\u001f\u007f]/.test(value), 'Target must not contain control characters.').parse(target);
+    toolName = toolNameValue(toolName);
+    target = targetValue(target);
+    // Known tools are those One can run: the public ones and the One-only ones.
+    if (!isOneExecutableTool(toolName))
+        throw unknownTool(toolName);
     const via = ctx.values.via;
     if (ctx.values.isPublic && via === 'one') {
         throw new Error('--public cannot be combined with --via one.');
     }
-    if (via && via !== 'one' && via !== 'public') {
-        throw new Error('--via must be one of: public, one');
+    if (via !== undefined && via !== 'one' && via !== 'public') {
+        throw new InvalidArgumentError('--via must be one of: public, one.');
     }
     const forcePublic = Boolean(ctx.values.isPublic) || via === 'public';
     const forceOne = via === 'one';
+    if (forcePublic && isOneAuthRequiredTool(toolName)) {
+        throw new Error(`${toolName} runs only through Vigilbase One: drop ${ctx.values.isPublic ? '--public' : '--via public'} and run \`vigilbase login\`.`);
+    }
     // Public tools stay free unless forced onto One. Auth-required tools need login.
     // The public route is anonymous and never reads the credential store.
     const useOne = !forcePublic && (forceOne || isOneAuthRequiredTool(toolName));
@@ -99,33 +108,38 @@ export const handleRun = async (ctx) => {
         }
         const oneClient = new VigilbaseOneClient(ctx.config, accessToken, true);
         const oneResult = await withSpinner(ctx, `Running ${toolName} against ${target}`, () => oneClient.executeTool(toolName, target));
-        formatExecuteResult({
-            success: Boolean(oneResult.success),
+        const unassessed = oneResult.code === 'scan_unassessed';
+        const toolRunId = oneResult.data?.toolRunId;
+        const result = {
+            success: oneResult.success === true,
             toolName,
             target,
             grade: oneResult.data?.grade ?? null,
             gradeScore: oneResult.data?.gradeScore ?? null,
-            result: oneResult.data?.result ?? null,
-            error: oneResult.error ?? null,
+            // Only a completed scan, or one the scanner could not assess, carries the scanner's result.
+            result: oneResult.success === true || unassessed ? oneResult.data?.result ?? null : null,
+            // One's error text is server text; a failed scan prints the CLI's own message.
+            error: null,
             uiUrl: `${ctx.config.oneBaseUrl}/dashboard/tools/${toolName}`,
-        }, ctx.mode, ctx.writer);
-        return oneResult.success ? ok() : EXIT.ERROR;
+            ...(unassessed ? { status: 422, code: 'scan_unassessed', ...(toolRunId ? { toolRunId } : {}) } : {}),
+        };
+        formatExecuteResult(result, ctx.mode, ctx.writer);
+        return isSuccessfulScan(result) ? ok() : EXIT.ERROR;
     }
     const result = await withSpinner(ctx, `Running ${toolName} against ${target}`, () => ctx.publicClient.executeTool(toolName, target));
     formatExecuteResult(result, ctx.mode, ctx.writer);
-    return result.success ? ok() : EXIT.ERROR;
+    return isSuccessfulScan(result) ? ok() : EXIT.ERROR;
 };
 export const handleDescribe = async (ctx) => {
     validateArguments(ctx, 1, ['isNoSkill'], 'vigilbase describe <tool>');
-    toolNameSchema.parse(ctx.rest[0]);
+    toolNameValue(ctx.rest[0]);
     const toolName = ctx.rest[0];
     if (!toolName)
         throw new Error('Usage: vigilbase describe <tool>');
     const catalog = await withSpinner(ctx, 'Loading tool catalog', () => ctx.publicClient.listTools());
     const tool = resolveToolDefinition(toolName, catalog.tools, ctx.config.oneBaseUrl);
-    if (!tool) {
-        throw new Error(`Unknown tool "${toolName}". Run \`vigilbase list\` for the allowlist.`);
-    }
+    if (!tool)
+        throw unknownTool(toolName);
     let skillMarkdown;
     if (!ctx.values.isNoSkill) {
         try {
@@ -140,18 +154,18 @@ export const handleDescribe = async (ctx) => {
 };
 export const handleSkill = async (ctx) => {
     validateArguments(ctx, 1, [], 'vigilbase skill <tool>');
-    toolNameSchema.parse(ctx.rest[0]);
+    toolNameValue(ctx.rest[0]);
     const toolName = ctx.rest[0];
     if (!toolName)
         throw new Error('Usage: vigilbase skill <tool>');
     const catalog = await withSpinner(ctx, 'Loading tool catalog', () => ctx.publicClient.listTools());
     const definition = resolveToolDefinition(toolName, catalog.tools, ctx.config.oneBaseUrl);
-    if (!definition) {
-        throw new Error(`Unknown tool "${toolName}". Run \`vigilbase list\` for the allowlist.`);
-    }
+    if (!definition)
+        throw unknownTool(toolName);
     const skillMarkdown = await withSpinner(ctx, 'Fetching skill docs', () => ctx.publicClient.fetchSkillMarkdown(definition.skillUrl));
     if (ctx.mode === 'json') {
         outputJson(ctx, {
+            success: true,
             toolName: definition.toolName,
             skillUrl: definition.skillUrl,
             content: skillMarkdown,
@@ -162,18 +176,35 @@ export const handleSkill = async (ctx) => {
     }
     return ok();
 };
+/** The badge route's domain rule (apps/com/app/api/badge/[domain]/route.ts). */
+const BADGE_DOMAIN = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/** The hostname the badge route accepts: a URL gives its hostname; case, a trailing dot and www. don't matter. */
+function badgeDomain(value) {
+    let domain = value.trim();
+    try {
+        const url = new URL(domain);
+        if (url.protocol === 'https:' || url.protocol === 'http:')
+            domain = url.hostname;
+    }
+    catch {
+        // Not a URL: a bare domain.
+    }
+    domain = domain.toLowerCase().replace(/\.$/, '').replace(/^www\./, '');
+    if (domain.length > 253 || !BADGE_DOMAIN.test(domain)) {
+        throw new InvalidArgumentError('Enter a domain such as vigilbase.com. Usage: vigilbase badge <domain>');
+    }
+    return domain;
+}
 export const handleBadge = async (ctx) => {
     validateArguments(ctx, 1, ['style'], 'vigilbase badge <domain>');
-    const domain = ctx.rest[0];
-    if (!domain)
-        throw new Error('Usage: vigilbase badge <domain>');
+    const domain = badgeDomain(ctx.rest[0] ?? '');
     const styleRaw = ctx.values.style ?? 'default';
     if (styleRaw !== 'default' && styleRaw !== 'compact' && styleRaw !== 'mini') {
-        throw new Error('--style must be one of: default, compact, mini');
+        throw new InvalidArgumentError('--style must be one of: default, compact, mini.');
     }
     const url = ctx.publicClient.badgeUrl(domain, styleRaw);
     if (ctx.mode === 'json') {
-        outputJson(ctx, { domain, style: styleRaw, url });
+        outputJson(ctx, { success: true, domain, style: styleRaw, url });
     }
     else {
         ctx.writer.stdout(url);
@@ -240,7 +271,7 @@ export const handleDoctor = async (ctx) => {
     const payload = {
         ok: isOk,
         success: isOk,
-        ...(firstFailure ? { error: firstFailure.error, status: firstFailure.status } : {}),
+        ...(firstFailure ? { error: firstFailure.error, status: firstFailure.status, ...(firstFailure.code ? { code: firstFailure.code } : {}) } : {}),
         publicBaseUrl: ctx.config.publicBaseUrl,
         oneBaseUrl: ctx.config.oneBaseUrl,
         clientId: ctx.config.clientId,

package/dist/commands/runs.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { limitValue, toolNameSchema, validateArguments } from './legacy-validation.js';
+import { limitValue, parseArgument, toolNameValue, unknownSubcommand, validateArguments } from './legacy-validation.js';
 import { asArray, asRecord, ok, outputJson, requireOneClient, withSpinner, } from './helpers.js';
 export const handleRuns = async (ctx) => {
     const subcommand = (ctx.rest[0] ?? 'list').toLowerCase();
@@ -7,16 +7,16 @@ export const handleRuns = async (ctx) => {
     if (subcommand === 'list' || subcommand === 'ls') {
         validateArguments(ctx, ctx.rest[0] === undefined ? 0 : 1, ['tool', 'limit']);
         limit = limitValue(ctx.values.limit, 50, 200);
-        toolName = toolNameSchema.optional().parse(ctx.values.tool);
+        toolName = ctx.values.tool === undefined ? undefined : toolNameValue(ctx.values.tool);
     }
     else if (subcommand === 'get' || subcommand === 'show') {
         validateArguments(ctx, 2, [], `vigilbase runs ${subcommand} <UUID>`);
-        z.string().uuid().parse(ctx.rest[1]);
+        parseArgument(z.string().uuid(), ctx.rest[1], 'A valid UUID is required. Copy the full run ID from `vigilbase runs list`.');
     }
     else if (z.string().uuid().safeParse(subcommand).success)
         validateArguments(ctx, 1);
     else
-        throw new Error('Usage: vigilbase runs [list|get <UUID>]');
+        throw unknownSubcommand('runs', ctx.rest[0] ?? '');
     const one = await requireOneClient(ctx);
     if (subcommand === 'list' || subcommand === 'ls') {
         const payload = await withSpinner(ctx, 'Loading tool runs', () => one.listToolRuns({
@@ -36,7 +36,7 @@ export const handleRuns = async (ctx) => {
             const run = asRecord(raw);
             if (!run)
                 continue;
-            ctx.writer.stdout(`${String(run.id).slice(0, 8)}  ${String(run.tool_name).padEnd(18)} ${String(run.status).padEnd(10)} ${String(run.grade ?? '-')}  ${String(run.target)}`);
+            ctx.writer.stdout(`${String(run.id)}  ${String(run.tool_name).padEnd(18)} ${String(run.status).padEnd(10)} ${String(run.grade ?? '-')}  ${String(run.target)}`);
         }
         return ok();
     }

package/dist/commands/security.d.ts

@@ -2,4 +2,4 @@ import { type SecurityRequest } from '../lib/security-client.js';
 import { type CommandContext, type CommandHandler } from './helpers.js';
 export declare function buildSecurityRequest(ctx: CommandContext): SecurityRequest;
 export declare const handleSecurity: CommandHandler;
-export declare const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";
+export declare const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction\n                                        --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --start --end --limit --cursor --sort\n                                        --asset-id --provider --dataset\n                                        --search --frs-min\n  audit                                 --limit --cursor\n                                        --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips>\n  analytics <bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>.\nInternal View-as: --customer-id <One customer UUID>.\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for endpoints, supported values, aliases and pagination.\n";

package/dist/commands/security.js

@@ -1,22 +1,20 @@
 import { z } from 'zod';
 import { SecurityClient } from '../lib/security-client.js';
 import { assertCommandFlags, asArray, asRecord, ok, outputJson, requireOneClient, withSpinner } from './helpers.js';
-import { missingArguments } from './legacy-validation.js';
+import { InvalidArgumentError, inRange, isoDateTime, missingArguments, oneOf, parseArgument, textValue, unknownSubcommand } from './legacy-validation.js';
 const statuses = ['open', 'active', 'acknowledged', 'investigating', 'mitigating', 'mitigated', 'resolved', 'false_positive'];
 const updateStatuses = ['acknowledged', 'mitigating', 'resolved', 'false_positive'];
 function textFlag(ctx, flag) {
     const value = ctx.values[flag];
-    if (value === undefined)
-        return undefined;
-    return z.string().trim().min(1, `--${flag} must not be empty.`).max(2048).parse(value);
+    return value === undefined ? undefined : textValue(`--${flag}`, String(value), 2048);
 }
 function integer(ctx, flag, max, fallback) {
     const value = textFlag(ctx, flag);
     if (value === undefined)
         return fallback;
     if (!/^\d+$/.test(value))
-        throw new Error(`--${flag} must be an integer.`);
-    return z.number().int().min(['limit', 'hours', 'min-weight'].includes(flag) ? 1 : 0).max(max).parse(Number(value));
+        throw new InvalidArgumentError(`--${flag} must be an integer.`);
+    return inRange(`--${flag}`, Number(value), ['limit', 'hours', 'min-weight'].includes(flag) ? 1 : 0, max);
 }
 function allowed(ctx, flags) {
     assertCommandFlags(ctx, [...flags, 'customer-id']);
@@ -28,6 +26,10 @@ function arity(ctx, length, usage) {
     if (ctx.rest.length > length)
         throw new Error('Unexpected security arguments. Run `vigilbase security --help` for usage.');
 }
+/** The entry of a command table named by user input; never an inherited Object.prototype member. */
+function own(table, name) {
+    return name !== undefined && Object.hasOwn(table, name) ? table[name] : undefined;
+}
 function uuid(value) {
     const parsed = z.string().uuid().safeParse(value);
     if (!parsed.success)
@@ -44,8 +46,8 @@ function extendedSecurityRequest(ctx, scope) {
         if (Boolean(start) !== Boolean(end))
             throw new Error('--start and --end must be supplied together as ISO timestamps.');
         if (start && end) {
-            z.iso.datetime({ offset: true }).parse(start);
-            z.iso.datetime({ offset: true }).parse(end);
+            isoDateTime('--start', start);
+            isoDateTime('--end', end);
             if (Date.parse(start) >= Date.parse(end))
                 throw new Error('--start must be before --end.');
             if (ctx.values.hours !== undefined)
@@ -79,9 +81,9 @@ function extendedSecurityRequest(ctx, scope) {
                 throw new Error('--search must be at most 200 characters for provider events.');
             return request('/analytics/provider-events', 'providerEvents', { provider_id: provider, dataset_id: dataset, start: query.start, end: query.end, asset_ids: query.asset_id, search, limit: integer(ctx, 'limit', 500, 200) });
         }
-        const view = views[operation];
+        const view = own(views, operation);
         if (!view)
-            throw new Error(`Unknown analytics command: ${operation}`);
+            throw unknownSubcommand('security analytics', operation);
         const query = window(operation === 'overview' ? ['metrics'] : []);
         if (operation === 'overview') {
             const metrics = textFlag(ctx, 'metrics') ?? 'hourly,by_domain,by_dataset';
@@ -94,26 +96,28 @@ function extendedSecurityRequest(ctx, scope) {
     }
     if (group === 'zero-trust') {
         const views = { 'device-health': 'deviceHealth', 'app-tests': 'appTests', gateway: 'gateway', access: 'access', sessions: 'sessions', 'device-posture': 'devicePosture' };
-        if (!sub || !views[sub])
+        const view = own(views, sub);
+        if (!sub || !view)
             throw new Error('Choose a zero-trust command: device-health, app-tests, gateway, access, sessions, device-posture.');
         arity(ctx, sub === 'gateway' ? 3 : 2, 'zero-trust gateway <dns|http|network>');
         const query = window();
         if (sub === 'gateway')
-            query.surface = z.enum(['dns', 'http', 'network']).parse(id);
-        return request(`/zero-trust/${sub}`, views[sub], query);
+            query.surface = oneOf('Gateway surface', ['dns', 'http', 'network'], id);
+        return request(`/zero-trust/${sub}`, view, query);
     }
     if (group === 'cloudflare-account') {
         const operation = sub ?? 'inventory';
         const views = { inventory: 'accountInventory', audit: 'accountAudit', ingestion: 'accountIngestion', posture: 'accountPosture' };
-        if (!views[operation])
-            throw new Error(`Unknown Cloudflare account security command: ${operation}`);
+        const view = own(views, operation);
+        if (!view)
+            throw unknownSubcommand('security cloudflare-account', operation);
         arity(ctx, sub === undefined ? 1 : 2);
         let query = {};
         if (operation === 'inventory')
             allowed(ctx, []);
         else
             query = window();
-        return request(`/cloudflare-account/${operation}`, views[operation], query);
+        return request(`/cloudflare-account/${operation}`, view, query);
     }
     if (group === 'providers') {
         arity(ctx, 1);
@@ -123,9 +127,9 @@ function extendedSecurityRequest(ctx, scope) {
     if (group === 'notifications') {
         const operation = sub ?? 'list';
         const routes = { list: ['/notifications', 'notifications'], settings: ['/notifications/settings', 'notificationSettings'], preferences: ['/notifications/preferences', 'preferences'], 'slack-channels': ['/notifications/slack/channels', 'slackChannels'] };
-        const route = routes[operation];
+        const route = own(routes, operation);
         if (!route)
-            throw new Error(`Unknown notifications command: ${operation}`);
+            throw unknownSubcommand('security notifications', operation);
         arity(ctx, sub === undefined ? 1 : 2);
         allowed(ctx, operation === 'list' ? ['limit'] : []);
         return request(...route, operation === 'list' ? { limit: integer(ctx, 'limit', 100, 100) } : {});
@@ -136,9 +140,9 @@ function extendedSecurityRequest(ctx, scope) {
             remediation: (assetId) => [`/assets/${assetId}/remediation-settings`, 'assetRemediation'], autonomy: (assetId) => [`/assets/${assetId}/vigil-autonomy`, 'autonomy'],
             datasets: (assetId) => [`/fabric/assets/${assetId}/datasets`, 'datasets'], graph: (assetId) => [`/fabric/assets/${assetId}/graph`, 'graph'],
         };
-        const route = Object.hasOwn(routes, sub) ? routes[sub] : undefined;
+        const route = own(routes, sub);
         if (!route)
-            throw new Error(`Unknown assets command: ${sub}`);
+            throw unknownSubcommand('security assets', sub);
         arity(ctx, 3, `assets ${sub} <asset-id>`);
         if (sub !== 'graph')
             allowed(ctx, []);
@@ -174,12 +178,12 @@ function extendedSecurityRequest(ctx, scope) {
             return request(`/alerts/${uuid(id)}`, 'alert');
         }
         if (sub !== undefined && sub !== 'list')
-            throw new Error(`Unknown alerts command: ${sub}`);
+            throw unknownSubcommand('security alerts', sub);
         arity(ctx, sub === undefined ? 1 : 2);
         allowed(ctx, ['limit', 'asset-id', 'start']);
         const since = textFlag(ctx, 'start');
         if (since)
-            z.iso.datetime({ offset: true }).parse(since);
+            isoDateTime('--start', since);
         return request('/alerts', 'alerts', { limit: integer(ctx, 'limit', 100, 100), asset_id: ctx.values['asset-id'] !== undefined ? uuid(ctx.values['asset-id']) : undefined, since });
     }
     if (group === 'incidents' && (sub === 'fabric' || sub === 'share-links')) {
@@ -190,7 +194,7 @@ function extendedSecurityRequest(ctx, scope) {
     }
     if (group === 'settings') {
         const routes = { 'lifecycle-emails': ['/settings/lifecycle-emails', 'lifecycleEmails'], 'broadcast-emails': ['/settings/broadcast-emails', 'broadcastEmails'], applications: ['/integrations/grants', 'applications'] };
-        const route = sub && routes[sub];
+        const route = own(routes, sub);
         if (!route)
             throw new Error('Choose settings lifecycle-emails, broadcast-emails, or applications.');
         arity(ctx, 2);
@@ -228,13 +232,13 @@ export function buildSecurityRequest(ctx) {
             arity(ctx, 4, 'incidents update <id> <status>');
             allowed(ctx, ['note', 'isConfirm']);
             const id = uuid(ctx.rest[2]);
-            const status = z.enum(updateStatuses).parse(ctx.rest[3]);
+            const status = oneOf('Status', updateStatuses, ctx.rest[3]);
             if (!ctx.values.isConfirm)
                 throw new Error('Updating an incident requires --confirm. Your One permissions still apply.');
             return { ...request(`/incidents/${id}`, 'update'), body: { status, ...(ctx.values.note !== undefined ? { note: textFlag(ctx, 'note') } : {}) } };
         }
         if (command !== 'list' && command !== 'ls')
-            throw new Error(`Unknown security ${group} command: ${command}`);
+            throw unknownSubcommand(`security ${group}`, command);
         arity(ctx, ctx.rest[1] === undefined ? 1 : 2);
         if (group === 'connections') {
             allowed(ctx, []);
@@ -247,11 +251,11 @@ export function buildSecurityRequest(ctx) {
         allowed(ctx, ['limit', 'offset', 'status', 'severity', 'attack-category', 'order-by', 'order-direction']);
         return request('/incidents', 'incidents', {
             limit: integer(ctx, 'limit', 100, 50), offset: integer(ctx, 'offset', 1_000_000),
-            status: z.enum(statuses).optional().parse(textFlag(ctx, 'status')),
-            severity: z.enum(['critical', 'high', 'medium', 'low']).optional().parse(textFlag(ctx, 'severity')),
+            status: oneOf('--status', statuses, textFlag(ctx, 'status')),
+            severity: oneOf('--severity', ['critical', 'high', 'medium', 'low'], textFlag(ctx, 'severity')),
             attack_category: textFlag(ctx, 'attack-category'),
-            order_by: z.enum(['last_alert_at', 'first_alert_at', 'created_at', 'severity_rank', 'combined_score', 'alert_count']).optional().parse(textFlag(ctx, 'order-by')),
-            order_direction: z.enum(['asc', 'desc']).optional().parse(textFlag(ctx, 'order-direction')),
+            order_by: oneOf('--order-by', ['last_alert_at', 'first_alert_at', 'created_at', 'severity_rank', 'combined_score', 'alert_count'], textFlag(ctx, 'order-by')),
+            order_direction: oneOf('--order-direction', ['asc', 'desc'], textFlag(ctx, 'order-direction')),
         });
     }
     if (group === 'assets') {
@@ -274,8 +278,8 @@ export function buildSecurityRequest(ctx) {
         if (Boolean(start) !== Boolean(end))
             throw new Error('--start and --end must be supplied together as ISO timestamps.');
         if (start && end) {
-            z.iso.datetime({ offset: true }).parse(start);
-            z.iso.datetime({ offset: true }).parse(end);
+            isoDateTime('--start', start);
+            isoDateTime('--end', end);
             if (Date.parse(start) >= Date.parse(end))
                 throw new Error('--start must be before --end.');
         }
@@ -283,7 +287,7 @@ export function buildSecurityRequest(ctx) {
             limit: integer(ctx, 'limit', 1000, 100), asset_id: ctx.values['asset-id'] !== undefined ? uuid(ctx.values['asset-id']) : undefined,
             provider: textFlag(ctx, 'provider'), dataset: textFlag(ctx, 'dataset'), search: textFlag(ctx, 'search'),
             start_time: start, end_time: end, cursor: textFlag(ctx, 'cursor'),
-            sort: z.enum(['ts', 'frs', 'frs_desc']).optional().parse(textFlag(ctx, 'sort')),
+            sort: oneOf('--sort', ['ts', 'frs', 'frs_desc'], textFlag(ctx, 'sort')),
             frs_min: integer(ctx, 'frs-min', 100),
         });
     }
@@ -292,7 +296,7 @@ export function buildSecurityRequest(ctx) {
         allowed(ctx, ['limit', 'cursor', 'action-prefix', 'outcome']);
         return request('/vigilbase-one/audit-events', 'audit', {
             limit: integer(ctx, 'limit', 100, 50), cursor: textFlag(ctx, 'cursor'), action_prefix: textFlag(ctx, 'action-prefix'),
-            outcome: z.enum(['success', 'failure', 'denied']).optional().parse(textFlag(ctx, 'outcome')),
+            outcome: oneOf('--outcome', ['success', 'failure', 'denied'], textFlag(ctx, 'outcome')),
         });
     }
     if (group === 'intel') {
@@ -302,11 +306,11 @@ export function buildSecurityRequest(ctx) {
             return request('/intel/quota', 'quota');
         }
         arity(ctx, 3, 'intel <ip|asn|cidr|ja3|ja4> <query>');
-        const type = z.enum(['ip', 'asn', 'cidr', 'ja3', 'ja4']).parse(command);
-        const q = z.string().trim().min(1).max(512).parse(ctx.rest[2]);
+        const type = oneOf('Lookup type', ['ip', 'asn', 'cidr', 'ja3', 'ja4'], command);
+        const q = parseArgument(z.string().trim().min(1).max(512), ctx.rest[2], 'The intel query must be 1-512 characters.');
         return request('/intel/lookup', 'intel', { q, type });
     }
-    throw new Error(`Unknown security command: ${group}. Run \`vigilbase security --help\`.`);
+    throw unknownSubcommand('security', group);
 }
 function cell(value) {
     // Security evidence may contain attacker-controlled text; keep each terminal row literal.
@@ -399,4 +403,4 @@ export const handleSecurity = async (ctx) => {
         display(ctx, request, payload);
     return ok();
 };
-export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --limit --asset-id --provider --dataset --search\n                                        --start --end --sort --frs-min --cursor\n  audit                                 --limit --cursor --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips|bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>, --customer-id <One customer UUID> (internal View-as).\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for every endpoint, supported value, alias, and pagination contract.\n";
+export const SECURITY_HELP = "vigilbase security \u2014 managed security in Vigilbase One\n\n  [overview]\n  incidents [list]                      --status --severity --attack-category\n                                        --order-by --order-direction\n                                        --limit --offset\n  incidents show <id>\n  incidents timeline <id>               --limit --before\n  incidents fabric <id>                 --dataset --min-weight --limit\n  incidents share-links <id>\n  incidents update <id> <status>        --confirm [--note]\n  alerts [list]                         --limit --asset-id --start\n  alerts show <id>\n  logs                                  --start --end --limit --cursor --sort\n                                        --asset-id --provider --dataset\n                                        --search --frs-min\n  audit                                 --limit --cursor\n                                        --action-prefix --outcome\n  assets\n  assets <allowlist|blocklist|remediation|autonomy|datasets> <asset-id>\n  assets graph <asset-id>               --dataset --hours --min-weight --limit\n  fabric default-asset\n  detections --asset-id <asset-id>\n  providers\n  connections [list]\n  connections show <id>\n  connections <available-assets|remediation> <id>\n  connections <logpush-status|worker-stats> <connection-id> <job-id>\n  analytics [overview]                  --metrics + time-window flags\n  analytics <security-analysis|bot-activity|top-attacker-ips>\n  analytics <bot-asns|dns-security|page-shield>\n  analytics provider-events             --provider --dataset --start --end\n                                        [--asset-id --search --limit]\n  zero-trust <device-health|app-tests|access|sessions|device-posture>\n  zero-trust gateway <dns|http|network>\n  cloudflare-account [inventory]\n  cloudflare-account <audit|ingestion|posture>\n  notifications [list]                  --limit\n  notifications <settings|preferences|slack-channels>\n  reports [list]                        --limit --offset\n  reports show <id>\n  reports settings\n  intel quota\n  intel <ip|asn|cidr|ja3|ja4> <query>\n  settings <lifecycle-emails|broadcast-emails|applications>\n\nTime-window flags: --hours (1\u2013720, default 24) or --start/--end ISO timestamps;\noptional --asset-id. Apply to analytics (except provider-events), zero-trust,\nand cloudflare-account audit/ingestion/posture. Inventory has no window flags.\nLimits: list incidents/reports/audit 1\u2013100 (default 50); alerts/notifications\n1\u2013100 (default 100); timeline 1\u2013200 (default 100); logs 1\u20131000 (default 100);\nprovider-events 1\u2013500 (default 200); graph 1\u20131000 (default 200).\nOffsets: 0\u20131000000. Graph min-weight: 1\u20131000000 (default 1).\nAll: --json, --timeout <ms>.\nInternal View-as: --customer-id <One customer UUID>.\nAll operations read data except confirmed incident status updates.\nUpdate status: acknowledged, mitigating, resolved, false_positive.\nSee SECURITY.md for endpoints, supported values, aliases and pagination.\n";

package/dist/commands/watchdog.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { limitValue, validateArguments } from './legacy-validation.js';
+import { limitValue, parseArgument, unknownSubcommand, validateArguments } from './legacy-validation.js';
 import { asArray, asRecord, ok, outputJson, requireOneClient, withSpinner, } from './helpers.js';
 export const handleWatchdog = async (ctx) => {
     const subcommand = (ctx.rest[0] ?? 'list').toLowerCase();
@@ -7,12 +7,12 @@ export const handleWatchdog = async (ctx) => {
     if (subcommand === 'scans' || subcommand === 'scan') {
         validateArguments(ctx, 1, ['target-id', 'limit']);
         limit = limitValue(ctx.values.limit, 20, 100);
-        targetId = z.string().uuid().optional().parse(ctx.values['target-id']);
+        targetId = parseArgument(z.string().uuid().optional(), ctx.values['target-id'], '--target-id must be a UUID. Copy the full ID from its list command.');
     }
     else if (['list', 'targets', 'status'].includes(subcommand))
         validateArguments(ctx, ctx.rest[0] === undefined ? 0 : 1);
     else
-        throw new Error('Usage: vigilbase watchdog [list|scans]');
+        throw unknownSubcommand('watchdog', ctx.rest[0] ?? '');
     const one = await requireOneClient(ctx);
     if (subcommand === 'list' || subcommand === 'targets' || subcommand === 'status') {
         const payload = await withSpinner(ctx, 'Loading watchdog targets', () => one.getWatchdogTargets());
@@ -29,7 +29,7 @@ export const handleWatchdog = async (ctx) => {
             const target = asRecord(raw);
             if (!target)
                 continue;
-            ctx.writer.stdout(`${String(target.domain).padEnd(28)} ${String(target.uptimeStatus || '-')}${typeof target.uptime24h === 'number'
+            ctx.writer.stdout(`${String(target.id ?? '-')}  ${String(target.domain).padEnd(28)} ${String(target.uptimeStatus || '-')}${typeof target.uptime24h === 'number'
                 ? `  24h=${Math.round(target.uptime24h * 100) / 100}`
                 : ''}`);
         }
@@ -53,7 +53,7 @@ export const handleWatchdog = async (ctx) => {
             const scan = asRecord(raw);
             if (!scan)
                 continue;
-            ctx.writer.stdout(`${String(scan.id).slice(0, 8)}  ${String(scan.status || '-').padEnd(10)} ${String(scan.scanType || '-')}  ${String(scan.createdAt || '')}`);
+            ctx.writer.stdout(`${String(scan.id)}  ${String(scan.status || '-').padEnd(10)} ${String(scan.scanType || '-')}  ${String(scan.createdAt || '')}`);
         }
         return ok();
     }

package/dist/lib/banner.d.ts

@@ -2,27 +2,21 @@
  * Compact Vigilbase flare mark + wordmark for human CLI surfaces.
  * Static strings only — no I/O, no deps, skipped entirely in --json mode.
  */
-/**
- * Compact square Vigilbase flare (inverted V).
- * Left wing (full block) = terminal default fg; right wing (medium shade) = brand yellow.
- */
-/** Compact flare used on help/version (keeps the first viewport short). */
+/** Compact square Vigilbase flare (inverted V), used on help/version (keeps the first viewport short). */
 export declare const VIGILBASE_ASCII_MARK: string;
 export type BannerOptions = {
     /** Include version line under the mark. */
     version?: string;
     /** One-line tagline. */
     tagline?: string;
-    /** Force ANSI on/off. Default: auto from TTY + env. */
-    useColor?: boolean;
 };
+/** Whether the checkup terminal UI (tui.ts) may colour this stream. */
 export declare function shouldUseColor(stream: {
     isTTY?: boolean;
 } | undefined, env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldShowBanner(mode?: 'text' | 'json', env?: NodeJS.ProcessEnv): boolean;
 /**
- * Banner composition (flare + wordmark + tagline).
+ * Banner composition (flare + wordmark + tagline). Plain text: the writer strips terminal
+ * sequences from every line, so the banner carries no colour.
  */
-export declare function renderBanner(options?: BannerOptions, stream?: {
-    isTTY?: boolean;
-} | undefined, env?: NodeJS.ProcessEnv): string;
+export declare function renderBanner(options?: BannerOptions): string;