@indigoai-us/hq-cli 5.129.0 → 5.131.0

package/dist/utils/environmental-error.js

@@ -1,16 +1,20 @@
 // src/utils/environmental-error.ts
 //
 // Classify errors that stem from the user's machine/filesystem state rather
-// than an HQ code defect. These are unactionable from our side: a full disk, an
-// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
-// actionable message and does NOT report them to Sentry — otherwise a single
-// full disk floods the issue tracker with identical, unfixable crash reports.
+// than an HQ code defect. Full-disk conditions have a known remedy and remain
+// quiet; permission and file-lock conditions remain captured with bounded
+// attribution so the next occurrence can identify the real cause.
 //
 // HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
 // (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
 // propagated uncaught to the CLI's top-level handler, which captured it to
 // Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
 // message telling the user their disk was full.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { COMMAND_CATALOG } from "../command-catalog.generated.js";
+import { CLI_VERSION } from "../cli-version.js";
+import { redactErrorText } from "./redact-error-text.js";
 /**
  * Node errno codes for "the filesystem cannot accept this write" — purely
  * environmental, never a code bug. Mapped to the message shown to the user.
@@ -20,6 +24,24 @@ const ENVIRONMENTAL_FS_CODES = {
     EDQUOT: "Disk quota exceeded. Free up space (or raise your quota) and try again.",
     EROFS: "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
 };
+const MAX_CAUSE_DEPTH = 4;
+function errorRecord(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+function findErrorWithCode(err, codes) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const record = errorRecord(current);
+        if (!record || seen.has(record))
+            return null;
+        seen.add(record);
+        if (typeof record.code === "string" && codes.has(record.code))
+            return record;
+        current = record.cause;
+    }
+    return null;
+}
 /**
  * If `err` is an environmental disk/quota/read-only filesystem error, return a
  * short, user-facing message explaining it; otherwise return `null`.
@@ -29,9 +51,220 @@ const ENVIRONMENTAL_FS_CODES = {
  * result means "this is a normal error; handle it as usual (capture to Sentry)".
  */
 export function environmentalFsErrorMessage(err) {
-    const code = err?.code;
-    if (typeof code !== "string")
+    const record = findErrorWithCode(err, new Set(Object.keys(ENVIRONMENTAL_FS_CODES)));
+    return record && typeof record.code === "string"
+        ? ENVIRONMENTAL_FS_CODES[record.code] ?? null
+        : null;
+}
+const CAPTURED_FS_CODES = new Set(["EPERM", "EACCES", "EBUSY", "UNKNOWN"]);
+const CAPTURED_FS_SYSCALLS = new Set(["open", "symlink", "rename", "unlink"]);
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function pathFromMessage(message, syscall) {
+    const text = stringField(message);
+    if (!text)
+        return null;
+    const escapedSyscall = syscall.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`${escapedSyscall}\\s+['"]([^'"]+)['"]`, "i").exec(text);
+    return match?.[1] ?? null;
+}
+function findFilesystemError(err) {
+    const seen = new Set();
+    let current = err;
+    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
+        const record = errorRecord(current);
+        if (!record || seen.has(record))
+            return null;
+        seen.add(record);
+        const code = stringField(record.code);
+        const syscall = stringField(record.syscall);
+        if (code && syscall && CAPTURED_FS_CODES.has(code) && CAPTURED_FS_SYSCALLS.has(syscall)) {
+            const rawPath = stringField(record.path) ??
+                stringField(record.dest) ??
+                pathFromMessage(record.message, syscall) ??
+                "unknown";
+            return { record, code, syscall, rawPath };
+        }
+        current = record.cause;
+    }
+    return null;
+}
+function canonicalPath(rawPath) {
+    if (rawPath === "unknown")
+        return "";
+    const resolved = path.resolve(rawPath);
+    try {
+        return path.normalize(requireRealpath(resolved));
+    }
+    catch {
+        // The failed path may not exist. Resolving its parent still canonicalizes
+        // symlinked HQ roots without turning missing-file attribution into a throw.
+        const parent = path.dirname(resolved);
+        try {
+            return path.join(requireRealpath(parent), path.basename(resolved));
+        }
+        catch {
+            return resolved;
+        }
+    }
+}
+function requireRealpath(candidate) {
+    // Keep the filesystem read behind one tiny seam so the classifier remains
+    // safe when the failed target has already disappeared.
+    return fs.realpathSync.native(candidate);
+}
+function pathSegments(value) {
+    return value
+        .replaceAll("\\", "/")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => segment.toLowerCase());
+}
+function pathKind(rawPath, resolvedPath) {
+    if (rawPath === "unknown")
+        return "other";
+    const segments = pathSegments(`${resolvedPath}/${rawPath}`);
+    if (segments.includes("node_modules") || segments.includes(".pnpm"))
+        return "install-tree";
+    if (segments.includes("worktree") || segments.includes("worktrees"))
+        return "worktree";
+    if (segments.includes("companies"))
+        return "companies";
+    if (segments.includes("workspace"))
+        return "workspace";
+    if (segments.includes("hq"))
+        return "hq-root";
+    return "other";
+}
+function syncedFolder(resolvedPath) {
+    if (!resolvedPath)
+        return "none";
+    const segments = pathSegments(resolvedPath);
+    // iCloud is identified from canonical path components, not a display-name
+    // substring: Desktop/Documents aliases can point into this container.
+    for (let i = 0; i + 1 < segments.length; i += 1) {
+        if (segments[i] === "library" && segments[i + 1] === "mobile documents")
+            return "icloud";
+    }
+    if (segments.some((segment) => segment === "onedrive" || segment.startsWith("onedrive -")))
+        return "onedrive";
+    if (segments.includes("dropbox"))
+        return "dropbox";
+    if (segments.some((segment) => segment === "google drive" || segment === "google-drive" || segment === "googledrive")) {
+        return "google-drive";
+    }
+    return "none";
+}
+function redactedPath(rawPath) {
+    if (rawPath === "unknown")
+        return "unknown";
+    const segments = rawPath.replaceAll("\\", "/").split("/").filter(Boolean);
+    const tail = segments.slice(-2).join("/");
+    return redactErrorText(tail) || "unknown";
+}
+function fileAttributes(record, rawPath) {
+    const metadata = [record.fileAttributes, record.attributes]
+        .map(stringField)
+        .filter((value) => value !== null)
+        .join(" ")
+        .toLowerCase();
+    if (metadata.includes("offline") || record.offline === true)
+        return "offline";
+    if (metadata.includes("readonly") || metadata.includes("read-only") || record.readonly === true)
+        return "readonly";
+    const leaf = rawPath.replaceAll("\\", "/").split("/").filter(Boolean).at(-1) ?? rawPath;
+    if (metadata.includes("hidden") || record.hidden === true || leaf.startsWith("."))
+        return "hidden";
+    return "none";
+}
+function findRegisteredCommand(commands, token) {
+    return commands.find((command) => command.name === token || command.aliases.includes(token)) ?? null;
+}
+function optionTakesValue(command, token) {
+    const optionName = token.split("=", 1)[0];
+    return command.options.some((option) => {
+        const names = option.flags
+            .split(",")
+            .map((flag) => flag.trim().split(/\s+/, 1)[0])
+            .filter((name) => Boolean(name));
+        return names.includes(optionName) && /(?:<[^>]+>|\[[^\]]+\])/.test(option.flags);
+    });
+}
+/** Return only the registered command path, never positional user data. */
+export function hqCommand(argv = process.argv) {
+    const commandPath = [];
+    let commands = COMMAND_CATALOG;
+    let currentCommand = null;
+    for (let index = 2; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token || token === "--")
+            break;
+        if (token.startsWith("-")) {
+            if (!token.includes("=") && currentCommand && optionTakesValue(currentCommand, token)) {
+                index += 1;
+            }
+            continue;
+        }
+        const command = findRegisteredCommand(commands, token);
+        if (!command)
+            break;
+        commandPath.push(command.name);
+        currentCommand = command;
+        commands = command.subcommands;
+    }
+    return commandPath.join(" ") || "unknown";
+}
+function pathLengthBucket(rawPath) {
+    if (rawPath.length < 200)
+        return "<200";
+    if (rawPath.length <= 260)
+        return "200-260";
+    return ">260";
+}
+/**
+ * Build stable Sentry context for known OS filesystem refusals. The failure is
+ * intentionally still captured: this is instrumentation for the OneDrive /
+ * antivirus / path-length hypotheses, not an expected-error suppression.
+ */
+export function filesystemErrorCaptureContext(err, argv = process.argv) {
+    const details = findFilesystemError(err);
+    if (!details)
+        return null;
+    const resolvedPath = canonicalPath(details.rawPath);
+    const safePath = redactedPath(details.rawPath);
+    const command = hqCommand(argv);
+    return {
+        fingerprint: ["fs-error", details.code, details.syscall, command],
+        tags: {
+            fs_code: details.code,
+            fs_syscall: details.syscall,
+            path_kind: pathKind(details.rawPath, resolvedPath),
+            synced_folder: syncedFolder(resolvedPath),
+            path_len_bucket: pathLengthBucket(details.rawPath),
+            file_attributes: fileAttributes(details.record, details.rawPath),
+            hq_command: command,
+            platform: process.platform,
+            hq_cli_version: CLI_VERSION,
+        },
+        extra: {
+            fs_path: safePath,
+            fs_reason: redactErrorText(`${details.code} ${details.syscall} failed at ${safePath}`),
+        },
+    };
+}
+/** Plain operator guidance for a captured filesystem failure. */
+export function filesystemErrorMessage(err) {
+    const details = findFilesystemError(err);
+    if (!details)
         return null;
-    return ENVIRONMENTAL_FS_CODES[code] ?? null;
+    const resolvedPath = canonicalPath(details.rawPath);
+    const safePath = redactedPath(details.rawPath);
+    const synced = syncedFolder(resolvedPath);
+    const permissionDenied = details.code === "EACCES" || details.code === "EPERM";
+    const remedy = permissionDenied && process.platform !== "win32" && synced === "none"
+        ? "Check file and folder permissions, close the file, then retry."
+        : "Close the file or exclude its folder from cloud sync; if it persists, check permissions, then retry.";
+    return `Filesystem operation ${details.syscall} failed (${details.code}) at ${safePath}. ${remedy}`;
 }
 //# sourceMappingURL=environmental-error.js.map

package/dist/utils/expected-cli-error.d.ts

@@ -5,6 +5,8 @@
 export interface ExpectedUserError extends Error {
     expected: true;
 }
+/** Stamp an existing Error with the boundary's caller-owned disposition. */
+export declare function markExpectedUserError<T extends Error>(err: T): T & ExpectedUserError;
 /**
  * True when `err` is an Error explicitly marked `expected === true`. A non-null
  * result means the top-level handler should print `err.message` and skip Sentry

package/dist/utils/expected-cli-error.js

@@ -16,6 +16,10 @@
 // ("Only a company owner can approve or reject queued integration writes"); the
 // thrown error propagated to the top-level handler, which captured it to Sentry
 // as an error-level crash and printed nothing to the user.
+/** Stamp an existing Error with the boundary's caller-owned disposition. */
+export function markExpectedUserError(err) {
+    return Object.assign(err, { expected: true });
+}
 /**
  * True when `err` is an Error explicitly marked `expected === true`. A non-null
  * result means the top-level handler should print `err.message` and skip Sentry

package/dist/utils/vault-api.d.ts

@@ -11,6 +11,7 @@ export interface VaultApiOptions {
     method?: string;
     body?: Record<string, unknown>;
     query?: Record<string, string>;
+    headers?: Record<string, string>;
     signal?: AbortSignal;
 }
 /**

package/dist/utils/vault-api.js

@@ -6,6 +6,8 @@ import { CompanySelectionError } from './company-selection-error.js';
 import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
 import { networkTransportErrorCode } from './network-transport-error.js';
 import { planGateErrorFromResponse } from './plan-gate-error.js';
+import { markExpectedUserError } from './expected-cli-error.js';
+import { redactErrorText } from './redact-error-text.js';
 /**
  * Identity / company resolution lookups must never hang forever. These small
  * GETs run BEFORE a command does its real work (e.g. `hq secrets env` resolves
@@ -193,6 +195,7 @@ export async function vaultApiFetch(opts) {
                 // skew on EVERY authenticated request, not only health heartbeats.
                 // Fixed build constant, never caller-supplied; attribution only.
                 'x-hq-client-version': CLI_VERSION,
+                ...opts.headers,
             },
             body: opts.body ? JSON.stringify(opts.body) : undefined,
             signal: opts.signal,
@@ -342,6 +345,9 @@ function formatSlugLookupReason(res, body) {
         return fromStatus;
     return `HTTP ${res.status}`;
 }
+function redactedSlugLookupMessage(message) {
+    return redactErrorText(message) || 'Company lookup failed.';
+}
 function isTransientSlugLookupStatus(status) {
     return status === 408 || status === 425 || status === 429 || status >= 500;
 }
@@ -475,14 +481,15 @@ async function resolveCompanyUid(token, ref) {
         // failure — treating it as not-found sent owners to check a slug that
         // was fine (Shepherd #2306).
         if (res.status === 404 && mine.kind === "miss") {
-            throw Object.assign(new Error(`Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`), { expected: true });
+            throw Object.assign(new Error(redactedSlugLookupMessage(`Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`)), { expected: true });
         }
         const reason = formatSlugLookupReason(res, body);
         const retryable = mine.kind === "transient" || isTransientSlugLookupStatus(res.status);
         const hint = retryable
             ? " This is a temporary lookup failure, not a missing company. Retry the command."
             : "";
-        throw new Error(`Failed to resolve company slug '${ref}': ${reason}.${hint}`);
+        const error = new Error(redactedSlugLookupMessage(`Failed to resolve company slug '${ref}': ${reason}.${hint}`));
+        throw retryable ? error : markExpectedUserError(error);
     }
     const data = (await res.json());
     return data.entity.uid;
@@ -494,7 +501,8 @@ async function resolveCompanyFromMemberships(token) {
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
-        throw new Error("Failed to fetch memberships — run `hq login` and try again");
+        const error = new Error("Failed to fetch memberships — run `hq login` and try again");
+        throw res.status === 401 ? markExpectedUserError(error) : error;
     }
     const data = (await res.json());
     const active = data.memberships.filter((m) => m.status === 'active');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.129.0",
+  "version": "5.131.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -17,7 +17,8 @@
     "assets/lanes-hooks",
     "templates",
     "CHANGELOG.md",
-    "README.md"
+    "README.md",
+    "contracts"
   ],
   "scripts": {
     "build": "node scripts/generate-dsn.mjs && tsc && node scripts/generate-command-catalog.mjs --check && node scripts/copy-schemas.mjs && node scripts/chmod-bins.mjs",