@vigilbase/cli 0.2.2 → 0.2.4

package/dist/lib/banner.js

@@ -2,11 +2,8 @@
  * 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). */
+import { isCi } from './platform.js';
+/** Compact square Vigilbase flare (inverted V), used on help/version (keeps the first viewport short). */
 export const VIGILBASE_ASCII_MARK = [
     '\u2588\u2588\u2588\u2588\u2588   \u2592\u2592\u2592',
     ' \u2588\u2588\u2588\u2588  \u2592\u2592\u2592\u2592',
@@ -14,13 +11,7 @@ export const VIGILBASE_ASCII_MARK = [
     '   \u2588\u2592\u2592\u2592\u2592   ',
     '    \u2592\u2592\u2592    ',
 ].join('\n');
-const ANSI = {
-    reset: '\u001b[0m',
-    dim: '\u001b[2m',
-    bold: '\u001b[1m',
-    /** Brand yellow (#f9e75e / #FFE74D family) — 256-color approximation. */
-    brand: '\u001b[38;5;221m',
-};
+/** Whether the checkup terminal UI (tui.ts) may colour this stream. */
 export function shouldUseColor(stream, env = process.env) {
     if (env.NO_COLOR != null && env.NO_COLOR !== '')
         return false;
@@ -28,7 +19,7 @@ export function shouldUseColor(stream, env = process.env) {
         return false;
     if (env.FORCE_COLOR && env.FORCE_COLOR !== '0')
         return true;
-    if (env.CI === '1' || env.CI === 'true')
+    if (isCi(env))
         return false;
     return Boolean(stream?.isTTY);
 }
@@ -39,29 +30,18 @@ export function shouldShowBanner(mode = 'text', env = process.env) {
         return false;
     return true;
 }
-function paintMarkLine(line, useColor) {
-    if (!useColor)
-        return line;
-    // Left wing stays terminal default fg; right wing is brand yellow.
-    return line.replace(/\u2592+/g, (run) => `${ANSI.brand}${run}${ANSI.reset}`);
-}
 /**
- * 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 function renderBanner(options = {}, stream = process.stdout, env = process.env) {
-    const useColor = options.useColor ?? shouldUseColor(stream, env);
+export function renderBanner(options = {}) {
     const tagline = options.tagline ?? 'one \u00b7 tools';
     const version = options.version ? ` \u00b7 v${options.version}` : '';
-    const mark = VIGILBASE_ASCII_MARK.split('\n');
-    const brand = (text) => useColor ? `${ANSI.brand}${ANSI.bold}${text}${ANSI.reset}` : text;
-    const dim = (text) => useColor ? `${ANSI.dim}${text}${ANSI.reset}` : text;
-    const painted = mark.map((line) => paintMarkLine(line, useColor));
-    const lines = painted.map((line, index) => {
+    return VIGILBASE_ASCII_MARK.split('\n').map((line, index) => {
         if (index === 0)
-            return `${line}  ${brand('vigilbase')}`;
+            return `${line}  vigilbase`;
         if (index === 1)
-            return `${line}  ${dim(`${tagline}${version}`)}`;
+            return `${line}  ${tagline}${version}`;
         return line;
-    });
-    return lines.join('\n');
+    }).join('\n');
 }

package/dist/lib/client.d.ts

@@ -9,6 +9,13 @@ export declare class VigilbaseApiError extends Error {
     readonly reason?: string;
     /** CLI-authored remediation, never server text (see one-error-hints.ts). */
     readonly hint?: string;
+    /**
+     * The message is the CLI's own text, never the server's, so formatError prints it although the
+     * error carries a body. Unmarked errors with a body print only a generic `Request failed`.
+     */
+    readonly isCliAuthored: boolean;
+    /** The One tool run a failed scan recorded. */
+    readonly toolRunId?: string;
     constructor(message: string, options: {
         status: number;
         body?: unknown;
@@ -16,6 +23,8 @@ export declare class VigilbaseApiError extends Error {
         code?: string;
         reason?: string;
         hint?: string;
+        isCliAuthored?: boolean;
+        toolRunId?: string;
     });
 }
 export declare function retryAfterSeconds(response: Response, body: unknown): number | undefined;

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { singleLine } from './format.js';
+import { SCAN_FAILED_MESSAGE, singleLine } from './format.js';
 import { parseJsonResponse, requestText } from './network.js';
 import { fetchSkillText } from './skill-fetch.js';
 import { AGENT_API_ERROR_CODES, } from '../types.js';
@@ -12,6 +12,13 @@ export class VigilbaseApiError extends Error {
     reason;
     /** CLI-authored remediation, never server text (see one-error-hints.ts). */
     hint;
+    /**
+     * The message is the CLI's own text, never the server's, so formatError prints it although the
+     * error carries a body. Unmarked errors with a body print only a generic `Request failed`.
+     */
+    isCliAuthored;
+    /** The One tool run a failed scan recorded. */
+    toolRunId;
     constructor(message, options) {
         super(message);
         this.name = 'VigilbaseApiError';
@@ -21,6 +28,8 @@ export class VigilbaseApiError extends Error {
         this.code = options.code;
         this.reason = options.reason;
         this.hint = options.hint;
+        this.isCliAuthored = options.isCliAuthored ?? false;
+        this.toolRunId = options.toolRunId;
     }
 }
 export function retryAfterSeconds(response, body) {
@@ -61,6 +70,7 @@ function problemReason(response, body) {
     const message = singleLine(problem.data.error.message);
     return message ? { code: code.data, message } : undefined;
 }
+/** `fallback` is the CLI's own message, used when com gave no reason it accepts. */
 function publicApiError(fallback, response, body) {
     const reason = problemReason(response, body);
     return new VigilbaseApiError(reason?.message ?? fallback, {
@@ -69,8 +79,17 @@ function publicApiError(fallback, response, body) {
         retryAfterSec: retryAfterSeconds(response, body),
         code: reason?.code,
         reason: reason?.message,
+        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';
 /**
@@ -89,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,
@@ -131,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('Tool execution was unsuccessful.', 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

@@ -3,7 +3,9 @@ export type Writer = {
     stdout: (line?: string) => void;
     stderr: (line?: string) => void;
 };
-/** Untrusted API data must never become terminal control sequences or bidi overrides. */
+/** 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, 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;
@@ -16,5 +18,7 @@ export declare function formatToolsList(catalog: AgentToolsCatalogResponse, mode
     isAuthenticated?: boolean;
 }): void;
 export declare function formatToolDescription(tool: AgentToolDefinition, mode: CliOutputMode, writer: Writer, skillMarkdown?: string): void;
+/** Whether a scan produced a result; the exit code follows it. */
+export declare function isSuccessfulScan(result: AgentToolExecuteResponse): boolean;
 export declare function formatExecuteResult(result: AgentToolExecuteResponse, mode: CliOutputMode, writer: Writer): void;
 export declare function formatError(error: unknown, mode: CliOutputMode, writer: Writer): void;