@indigoai-us/hq-cli 5.50.2 → 5.51.0

package/src/node-preflight.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for the runtime Node version guard.
+ *
+ * The guard fails the CLI fast on Node < 20 (where prebuilt native modules hit
+ * an ABI mismatch and `util.styleText` is missing) with an actionable upgrade
+ * message, and is a no-op on Node 20+.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { MIN_NODE_MAJOR, checkNodeVersion } from "./node-preflight.js";
+
+describe("checkNodeVersion", () => {
+  it("rejects Node 18 with an actionable upgrade message", () => {
+    const result = checkNodeVersion("18.19.0");
+
+    expect(result.ok).toBe(false);
+    expect(result.major).toBe(18);
+    expect(result.message).toContain(`Node.js ${MIN_NODE_MAJOR} or newer`);
+    expect(result.message).toContain("18.19.0");
+    expect(result.message).toMatch(/upgrade/i);
+  });
+
+  it("rejects every major below the minimum", () => {
+    for (const version of ["14.21.3", "16.20.2", "19.9.0"]) {
+      const result = checkNodeVersion(version);
+      expect(result.ok).toBe(false);
+      expect(result.message).toBeDefined();
+    }
+  });
+
+  it("accepts Node 20 (the minimum) without a message", () => {
+    const result = checkNodeVersion("20.11.1");
+
+    expect(result.ok).toBe(true);
+    expect(result.major).toBe(20);
+    expect(result.message).toBeUndefined();
+  });
+
+  it("accepts newer majors (22, 24)", () => {
+    for (const version of ["22.3.0", "24.0.0"]) {
+      const result = checkNodeVersion(version);
+      expect(result.ok).toBe(true);
+      expect(result.message).toBeUndefined();
+    }
+  });
+
+  it("treats an unparseable version as supported (never blocks on a bad string)", () => {
+    const result = checkNodeVersion("not-a-version");
+
+    expect(result.ok).toBe(true);
+    expect(result.message).toBeUndefined();
+  });
+
+  it("defaults to the running runtime, which is supported in CI", () => {
+    // The test runner itself must be on a supported Node, so the default-arg
+    // path returns ok — also proving importing this module did not exit.
+    expect(checkNodeVersion().ok).toBe(true);
+  });
+});

package/src/node-preflight.ts

@@ -0,0 +1,67 @@
+/**
+ * Runtime Node.js version guard for the hq CLI.
+ *
+ * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
+ * the CLI dies with cryptic failures long before reaching any of its own code:
+ * a native-module ABI mismatch from a prebuilt dependency, and a missing
+ * `util.styleText` (added in Node 20). Those errors give the user no hint that
+ * the real problem is just an old Node.
+ *
+ * This module exists to fail fast with an actionable message instead. It is
+ * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
+ * so the check runs before commander, Sentry, or any dependency that needs a
+ * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
+ * imports in source order, so as long as this is the first import in the entry
+ * module, the guard short-circuits an unsupported runtime cleanly.
+ *
+ * Keep this file dependency-free — it must not import anything that could itself
+ * fail to load on the very runtime it is trying to detect.
+ */
+
+export const MIN_NODE_MAJOR = 20;
+
+export interface NodeVersionCheck {
+  ok: boolean;
+  major: number;
+  message?: string;
+}
+
+/**
+ * Pure check: is the given Node version string (e.g. "18.19.0") supported?
+ * Defaults to the running runtime's version. An unparseable version is treated
+ * as supported so we never block a user on a version string we can't read.
+ */
+export function checkNodeVersion(
+  versionString: string = process.versions.node,
+): NodeVersionCheck {
+  const major = Number.parseInt(String(versionString).split(".")[0] ?? "", 10);
+
+  if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) {
+    return { ok: true, major };
+  }
+
+  const message =
+    `hq requires Node.js ${MIN_NODE_MAJOR} or newer — you are running Node ${versionString}.\n` +
+    `Older versions fail with native-module ABI mismatches and missing APIs.\n` +
+    `Please upgrade to Node ${MIN_NODE_MAJOR}+ (https://nodejs.org/) and run hq again.`;
+
+  return { ok: false, major, message };
+}
+
+/**
+ * Side-effecting guard run on import: prints the upgrade message to stderr and
+ * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
+ * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
+ * runs on a supported Node).
+ */
+export function enforceNodeVersion(): void {
+  if (process.env.HQ_SKIP_NODE_PREFLIGHT) return;
+
+  const result = checkNodeVersion();
+  if (!result.ok && result.message) {
+    process.stderr.write(`${result.message}\n`);
+    process.exit(1);
+  }
+}
+
+enforceNodeVersion();

package/src/sentry-epipe.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ErrorEvent, EventHint } from "@sentry/node";
+
+// sentry.ts reads BUNDLED_DSN at import time; stub it so the module loads
+// without a real DSN (mirrors sentry.test.ts).
+vi.mock("./sentry-dsn.generated.js", () => ({ BUNDLED_DSN: "" }));
+
+import { epipeAwareBeforeSend } from "./sentry.js";
+
+describe("epipeAwareBeforeSend (HQ-6B)", () => {
+  it("drops an EPIPE crash before it can ship a fatal", () => {
+    const epipe = Object.assign(new Error("write EPIPE"), { code: "EPIPE" });
+    const event = {
+      exception: { values: [{ type: "Error", value: "write EPIPE" }] },
+    } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {
+      originalException: epipe,
+    } as EventHint);
+    expect(out).toBeNull();
+  });
+
+  it("forwards a genuine error to the scrubber (still reported)", () => {
+    const err = new Error("boom");
+    const event = { message: "boom" } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {
+      originalException: err,
+    } as EventHint);
+    expect(out).not.toBeNull();
+    expect(out?.message).toBe("boom");
+  });
+
+  it("forwards when there is no originalException hint", () => {
+    const event = { message: "no hint" } as ErrorEvent;
+    const out = epipeAwareBeforeSend(event, {} as EventHint);
+    expect(out).not.toBeNull();
+  });
+});

package/src/sentry-release.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+// `@sentry/node`'s `init` is a non-configurable export, so it can't be spied
+// in place — replace it via importOriginal spread (every OTHER Sentry export
+// stays real, so initSentry's setUser/startSession remain harmless no-ops with
+// no real SDK init). We only need to inspect the options handed to `init`.
+const { initMock } = vi.hoisted(() => ({ initMock: vi.fn() }));
+vi.mock("@sentry/node", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@sentry/node")>();
+  return { ...actual, init: initMock };
+});
+// A DSN must be present for initSentry to reach Sentry.init.
+vi.mock("./sentry-dsn.generated.js", () => ({
+  BUNDLED_DSN: "https://examplePublicKey@o0.ingest.sentry.io/0",
+}));
+
+import { initSentry } from "./sentry.js";
+import { CLI_VERSION } from "./cli-version.js";
+
+const PKG_VERSION = (
+  JSON.parse(
+    readFileSync(
+      path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+      "utf-8",
+    ),
+  ) as { version: string }
+).version;
+
+describe("initSentry — release tag carries the real CLI version (resolve-by-release)", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Locks the resolve-by-release path for hq-cli: every event must be stamped
+  // with the REAL package version so Sentry's "resolved in next release" works
+  // and old-version stragglers (the legacy `hq-cli@0.0.0` events from pre-#8
+  // installs) sort as the oldest release and stay suppressed. Regression guard
+  // against ever reverting to the `npm_package_version` 0.0.0 pitfall.
+  it("stamps release = hq-cli@<package.json version>, never the 0.0.0 placeholder", () => {
+    initSentry();
+
+    expect(initMock).toHaveBeenCalledTimes(1);
+    const opts = initMock.mock.calls[0][0] as { release?: string };
+
+    // CLI_VERSION resolves from package.json at runtime (not npm_package_version).
+    expect(CLI_VERSION).toBe(PKG_VERSION);
+    expect(CLI_VERSION).not.toBe("0.0.0");
+    expect(opts.release).toBe(`hq-cli@${PKG_VERSION}`);
+    expect(opts.release).not.toBe("hq-cli@0.0.0");
+  });
+});

package/src/sentry.ts

@@ -1,9 +1,29 @@
 import * as Sentry from "@sentry/node";
+import type { ErrorEvent, EventHint } from "@sentry/node";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
+import { isEpipe } from "./utils/epipe.js";
+
+/**
+ * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
+ * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
+ * Unix behavior with no user-facing degradation — never a defect to report.
+ * This is the path-independent catch-all for HQ-6B: whichever way an EPIPE
+ * surfaces (a synchronous throw into the command catch, an async stream
+ * 'error', or a write outside the top-level try), it never ships a fatal. The
+ * clean-exit handlers in index.ts still keep exit code 0 for the common paths.
+ * Consistent with the swallow-EPIPE posture established in #138.
+ */
+export function epipeAwareBeforeSend(
+  event: ErrorEvent,
+  hint: EventHint,
+): ErrorEvent | null {
+  if (isEpipe(hint?.originalException)) return null;
+  return beforeSend(event, hint);
+}
 
 export function initSentry(): void {
   const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
@@ -18,7 +38,7 @@ export function initSentry(): void {
     initialScope: {
       tags: { repo: "hq-cli" },
     },
-    beforeSend,
+    beforeSend: epipeAwareBeforeSend,
     beforeBreadcrumb,
   });
   // Attribute events to the logged-in HQ identity (best-effort; null when not

package/src/utils/epipe.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { isEpipe } from "./epipe.js";
+
+describe("isEpipe", () => {
+  it("matches a real Node EPIPE error", () => {
+    const err = Object.assign(new Error("write EPIPE"), { code: "EPIPE" });
+    expect(isEpipe(err)).toBe(true);
+  });
+
+  it("matches a plain object carrying code EPIPE", () => {
+    expect(isEpipe({ code: "EPIPE" })).toBe(true);
+  });
+
+  it("does NOT match other errno codes (so real faults still report)", () => {
+    expect(isEpipe(Object.assign(new Error("disk full"), { code: "ENOSPC" }))).toBe(
+      false,
+    );
+    expect(isEpipe(Object.assign(new Error("nope"), { code: "EACCES" }))).toBe(false);
+    expect(isEpipe(new Error("plain error with no code"))).toBe(false);
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isEpipe(null)).toBe(false);
+    expect(isEpipe(undefined)).toBe(false);
+    expect(isEpipe("EPIPE")).toBe(false);
+    expect(isEpipe(42)).toBe(false);
+  });
+});

package/src/utils/epipe.ts

@@ -0,0 +1,29 @@
+// src/utils/epipe.ts
+//
+// Classify the "broken pipe" (EPIPE) error: a downstream reader closed the
+// pipe before the CLI finished writing to stdout/stderr. This is normal,
+// expected Unix behavior — `hq … | head`, `source <(hq …)`, or a parent
+// process that exits while `hq` is still printing — NOT an HQ code defect.
+//
+// HQ-6B: a synchronous `write EPIPE` thrown from `console.log` (the Sentry
+// console-instrumentation wraps it) propagated out of an awaited command into
+// the CLI's top-level `catch`, which captured it via `Sentry.captureException`
+// and shipped a fatal — even though the only thing that happened is the
+// consumer of `hq`'s output went away. The async path (an emitted stream
+// 'error' event) was already handled by the stdout/stderr listeners in
+// index.ts; this predicate closes the synchronous-throw path too, mirroring
+// the environmental-error carve-out (HQ-CLI-2).
+
+/**
+ * True when `err` is a Node EPIPE error — the pipe `hq` was writing to was
+ * closed by its reader. Callers should treat this as a clean, expected exit
+ * (code 0) and SKIP Sentry capture: there is no defect and no user-facing
+ * degradation to fix.
+ */
+export function isEpipe(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as NodeJS.ErrnoException).code === "EPIPE"
+  );
+}

package/src/utils/intercepted-process-exit.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { isInterceptedProcessExit } from "./intercepted-process-exit.js";
+
+describe("isInterceptedProcessExit", () => {
+  it("matches the fuzz harness's intercepted-process.exit marker error", () => {
+    expect(isInterceptedProcessExit(new Error("fuzz-intercepted-process-exit"))).toBe(true);
+  });
+
+  it("matches when the marker is wrapped in a longer message", () => {
+    expect(
+      isInterceptedProcessExit(new Error("audit: fuzz-intercepted-process-exit code=1")),
+    ).toBe(true);
+  });
+
+  it("matches a plain object carrying the marker message", () => {
+    expect(isInterceptedProcessExit({ message: "fuzz-intercepted-process-exit" })).toBe(true);
+  });
+
+  it("matches a bare string carrying the marker", () => {
+    expect(isInterceptedProcessExit("fuzz-intercepted-process-exit")).toBe(true);
+  });
+
+  it("does NOT match genuine errors (so real faults still report)", () => {
+    expect(isInterceptedProcessExit(new Error("boom"))).toBe(false);
+    expect(isInterceptedProcessExit(new Error("ENOENT: no such file or directory"))).toBe(false);
+    expect(isInterceptedProcessExit(Object.assign(new Error("nope"), { code: "EACCES" }))).toBe(
+      false,
+    );
+  });
+
+  it("does NOT match non-error values", () => {
+    expect(isInterceptedProcessExit(null)).toBe(false);
+    expect(isInterceptedProcessExit(undefined)).toBe(false);
+    expect(isInterceptedProcessExit(42)).toBe(false);
+    expect(isInterceptedProcessExit({})).toBe(false);
+  });
+});

package/src/utils/intercepted-process-exit.ts

@@ -0,0 +1,36 @@
+// src/utils/intercepted-process-exit.ts
+//
+// Classify the "intercepted process.exit" synthetic error (HQ-CLI-3).
+//
+// Security/audit FUZZ harnesses (e.g. `/opt/audit/fuzz-exports.js`) monkey-patch
+// `process.exit` to THROW a marker instead of actually terminating, so the
+// fuzzer can keep exercising a binary's entrypoints. When such a harness drives
+// `hq` (e.g. `hq <unknown-command>`), commander legitimately calls
+// `process.exit(1)` — and the patched exit turns that normal CLI control-flow
+// into a thrown `Error: fuzz-intercepted-process-exit` that propagates out of
+// `program.parseAsync()` into the CLI's top-level catch, which then shipped it to
+// Sentry as a fatal.
+//
+// This is a test-harness artifact, NOT an hq-cli defect: a real user's
+// `process.exit` exits the process and nothing is ever thrown or captured.
+// There is no user-facing degradation to fix, so the top-level catch skips
+// Sentry capture for it — the genuine "expected, non-actionable" carve-out,
+// mirroring the EPIPE (HQ-6B) and environmental-FS (HQ-CLI-2) carve-outs.
+
+/** The marker a fuzz/audit harness throws in place of a real `process.exit`. */
+const INTERCEPTED_PROCESS_EXIT_MARKER = "fuzz-intercepted-process-exit";
+
+/**
+ * True when `err` is a fuzz/audit harness's intercepted-`process.exit` marker
+ * rather than a genuine fault. Callers should SKIP Sentry capture (no defect, no
+ * user-facing degradation) while preserving the intended exit code.
+ */
+export function isInterceptedProcessExit(err: unknown): boolean {
+  if (typeof err === "object" && err !== null) {
+    const message = (err as { message?: unknown }).message;
+    if (typeof message === "string" && message.includes(INTERCEPTED_PROCESS_EXIT_MARKER)) {
+      return true;
+    }
+  }
+  return typeof err === "string" && err.includes(INTERCEPTED_PROCESS_EXIT_MARKER);
+}