@vigilbase/cli 0.2.3 → 0.2.5

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

@@ -5,6 +5,12 @@ import type { EntryCounts } from './snapshot-file.js';
  * (`...` on an ASCII-only console).
  */
 export declare function displayText(value: string, max: number, ellipsis?: string): string;
+/**
+ * A file name the user passed, in a line of plain output: controls, line
+ * breaks and invisible format characters become visible escapes (`\n`,
+ * `\u001b`), so a crafted name cannot add or rewrite lines.
+ */
+export declare function displayFileName(value: string): string;
 /** `0123…cdef` (`0123...cdef` with the ASCII `ellipsis` of the terminal UI). */
 export declare function maskId(id: string, ellipsis?: string): string;
 /** `9f2c…a71e` */

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

@@ -14,6 +14,15 @@ export function displayText(value, max, ellipsis = '…') {
     const flat = sanitizeTerminal(value.replace(/[\s\u0085\u2028\u2029]+/g, ' ')).trim();
     return flat.length > max ? `${flat.slice(0, Math.max(0, max - ellipsis.length))}${ellipsis}` : flat;
 }
+/**
+ * A file name the user passed, in a line of plain output: controls, line
+ * breaks and invisible format characters become visible escapes (`\n`,
+ * `\u001b`), so a crafted name cannot add or rewrite lines.
+ */
+export function displayFileName(value) {
+    const named = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+    return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, (char) => named[char] ?? `\\u${char.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
 /** `0123…cdef` (`0123...cdef` with the ASCII `ellipsis` of the terminal UI). */
 export function maskId(id, ellipsis = '…') {
     return id.length > 8 ? `${id.slice(0, 4)}${ellipsis}${id.slice(-4)}` : id;

package/dist/local/cloudflare-checkup/snapshot-file.d.ts

@@ -14,13 +14,17 @@ export type LoadedSnapshot = {
     sha256: string;
     snapshot: CloudflareCheckupSnapshotV1;
 };
-/** Map a failed contract parse to the CLI error (no values, issue codes only). */
+/**
+ * Map a failed contract parse to the CLI error (no values, issue codes only).
+ * `file`: the snapshot was read from a file, so the hint says how to collect
+ * a fresh one instead of running the same command again.
+ */
 export declare function snapshotParseError(issues: ReadonlyArray<{
     code?: string;
     message?: string;
     path?: ReadonlyArray<PropertyKey>;
     params?: unknown;
-}>): LocalCheckupError;
+}>, file?: boolean): LocalCheckupError;
 /** Read, hash and validate a snapshot file against the vendored contract. */
 export declare function loadSnapshotFile(path: string): Promise<LoadedSnapshot>;
 export type EntryCounts = {

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

@@ -13,7 +13,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { link, open, readFile, rename, rm, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { CloudflareCheckupSnapshotV1Schema, SNAPSHOT_LIMITS, SNAPSHOT_SCHEMA_VERSION, expandRuleRuns, snapshotIssueList, snapshotRejectReason, } from './contract.js';
-import { LocalCheckupError, SNAPSHOT_MISSING_HINT } from './errors.js';
+import { LocalCheckupError, SNAPSHOT_INVALID_FILE_HINT, SNAPSHOT_MISSING_HINT, SNAPSHOT_SECRET_FILE_HINT, SNAPSHOT_UNREADABLE_HINT, } from './errors.js';
 export function sha256Hex(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
 }
@@ -78,27 +78,41 @@ export async function writeSnapshotFile(path, text, options) {
     }
     return { bytes: bytes.byteLength, sha256: sha256Hex(bytes) };
 }
-/** Map a failed contract parse to the CLI error (no values, issue codes only). */
-export function snapshotParseError(issues) {
+/**
+ * Map a failed contract parse to the CLI error (no values, issue codes only).
+ * `file`: the snapshot was read from a file, so the hint says how to collect
+ * a fresh one instead of running the same command again.
+ */
+export function snapshotParseError(issues, file = false) {
     const reason = snapshotRejectReason(issues);
     const codes = [...new Set(snapshotIssueList(issues).map((issue) => issue.code))].slice(0, 5).join(', ');
     if (reason === 'secret_like_value') {
-        return new LocalCheckupError('SNAPSHOT_SECRET_LIKE_VALUE', 'The snapshot contains a value that looks like a credential, so it will not be written or uploaded.');
+        return new LocalCheckupError('SNAPSHOT_SECRET_LIKE_VALUE', 'The snapshot contains a value that looks like a credential, so it will not be written or uploaded.', file ? { hint: SNAPSHOT_SECRET_FILE_HINT } : {});
     }
-    return new LocalCheckupError('SNAPSHOT_INVALID', `The snapshot does not match ${SNAPSHOT_SCHEMA_VERSION} (${codes || 'invalid'}).`);
+    return new LocalCheckupError('SNAPSHOT_INVALID', `The snapshot does not match ${SNAPSHOT_SCHEMA_VERSION} (${codes || 'invalid'}).`, file ? { hint: SNAPSHOT_INVALID_FILE_HINT } : {});
+}
+/** A stat or read failure of the snapshot path, without Node's raw error text. */
+function unreadable(error) {
+    const code = error.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file does not exist.', { hint: SNAPSHOT_MISSING_HINT });
+    if (code === 'ELOOP')
+        return new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot path is a symbolic-link loop.', { hint: SNAPSHOT_MISSING_HINT });
+    if (code === 'EACCES' || code === 'EPERM') {
+        return new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file cannot be read (permission denied).', { hint: SNAPSHOT_UNREADABLE_HINT });
+    }
+    return new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file cannot be read.', { hint: SNAPSHOT_UNREADABLE_HINT });
 }
 /** Read, hash and validate a snapshot file against the vendored contract. */
 export async function loadSnapshotFile(path) {
-    const info = await stat(path).catch(() => null);
-    if (!info)
-        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file does not exist.', { hint: SNAPSHOT_MISSING_HINT });
+    const info = await stat(path).catch((error) => { throw unreadable(error); });
     if (!info.isFile())
         throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot path is not a file.', { hint: SNAPSHOT_MISSING_HINT });
     if (info.size > SNAPSHOT_LIMITS.maxBytes) {
         throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', `The snapshot is larger than the ${SNAPSHOT_LIMITS.maxBytes / 1024 / 1024} MiB contract limit.`);
     }
     // no-dd-sa:javascript-node-security/detect-non-literal-fs-filename — the user's own snapshot path.
-    const bytes = await readFile(path);
+    const bytes = await readFile(path).catch((error) => { throw unreadable(error); });
     if (bytes.byteLength > SNAPSHOT_LIMITS.maxBytes)
         throw new LocalCheckupError('SNAPSHOT_TOO_LARGE', 'The snapshot is larger than the contract limit.');
     let raw;
@@ -106,11 +120,11 @@ export async function loadSnapshotFile(path) {
         raw = JSON.parse(bytes.toString('utf8'));
     }
     catch {
-        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file is not valid JSON.');
+        throw new LocalCheckupError('SNAPSHOT_INVALID', 'The snapshot file is not valid JSON.', { hint: SNAPSHOT_INVALID_FILE_HINT });
     }
     const parsed = CloudflareCheckupSnapshotV1Schema.safeParse(raw);
     if (!parsed.success)
-        throw snapshotParseError(parsed.error.issues);
+        throw snapshotParseError(parsed.error.issues, true);
     return { path, bytes, sha256: sha256Hex(bytes), snapshot: parsed.data };
 }
 export function countEntries(entries) {

package/dist/local/cloudflare-checkup/submit-client.js

@@ -382,9 +382,15 @@ export class SubmitClient extends LocalHttpClient {
 }
 /** Refuse a server (its session, or its availability answer) that requires a newer CLI, or does not accept this schema version. */
 export function assertServerAccepts(server, cliVersion, schemaVersion) {
-    if (!server.accepts.schemaVersions.includes(schemaVersion) || compareSemver(cliVersion, server.minCliVersion) < 0) {
+    if (compareSemver(cliVersion, server.minCliVersion) < 0) {
         throw new LocalCheckupError('CLI_UPGRADE_REQUIRED', `vigilbase.com requires @vigilbase/cli ${server.minCliVersion.slice(0, 40)} or newer for this snapshot.`);
     }
+    // This CLI is new enough, so the file's format is the problem (an old snapshot, or a server that moved on).
+    if (!server.accepts.schemaVersions.includes(schemaVersion)) {
+        throw new LocalCheckupError('CLI_UPGRADE_REQUIRED', `vigilbase.com does not accept snapshots in the ${schemaVersion.slice(0, 80)} format.`, {
+            hint: 'Collect a fresh snapshot with the latest CLI: `npx @vigilbase/cli@latest cloudflare-checkup`.',
+        });
+    }
 }
 /**
  * The masked address as the server masks it (first character, `***`, the

package/dist/types.d.ts

@@ -62,7 +62,8 @@ export type AgentToolExecuteResponse = {
     skillsIndex?: string;
 };
 export type CliOutputMode = 'text' | 'json';
-export type ExitCode = 0 | 1 | 2;
+/** 129, 130 and 143: a local checkup cancelled by SIGHUP, SIGINT or SIGTERM. */
+export type ExitCode = 0 | 1 | 2 | 129 | 130 | 143;
 /** Exit codes used by the CLI. Documented for agents. */
 export declare const EXIT: {
     OK: 0;

package/esm-only.cjs

@@ -0,0 +1,3 @@
+'use strict'
+// require('@vigilbase/cli') resolves here: the library is an ES module (dist/index.js).
+throw Object.assign(new Error('@vigilbase/cli is ESM-only. Use import() or the vigilbase command.'), { code: 'ERR_REQUIRE_ESM' })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vigilbase/cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.",
   "keywords": [
     "vigilbase",
@@ -28,8 +28,10 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "import": "./dist/index.js",
+      "require": "./esm-only.cjs"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -39,7 +41,8 @@
     "SECURITY.md",
     "ONE.md",
     "LOCAL.md",
-    "LICENSE"
+    "LICENSE",
+    "esm-only.cjs"
   ],
   "publishConfig": {
     "access": "public",