@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/utils/environmental-error.ts

@@ -1,39 +0,0 @@
-// 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.
-//
-// 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.
-
-/**
- * Node errno codes for "the filesystem cannot accept this write" — purely
- * environmental, never a code bug. Mapped to the message shown to the user.
- */
-const ENVIRONMENTAL_FS_CODES: Record<string, string> = {
-  ENOSPC: "No space left on device. Free up disk space and try again.",
-  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.",
-};
-
-/**
- * If `err` is an environmental disk/quota/read-only filesystem error, return a
- * short, user-facing message explaining it; otherwise return `null`.
- *
- * A non-null result means the caller should print the message and SKIP Sentry
- * capture — the condition is the user's machine, not a bug HQ can fix. A null
- * result means "this is a normal error; handle it as usual (capture to Sentry)".
- */
-export function environmentalFsErrorMessage(err: unknown): string | null {
-  const code = (err as NodeJS.ErrnoException | null | undefined)?.code;
-  if (typeof code !== "string") return null;
-  return ENVIRONMENTAL_FS_CODES[code] ?? null;
-}

package/src/utils/epipe.test.ts

@@ -1,28 +0,0 @@
-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

@@ -1,29 +0,0 @@
-// 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/expected-cli-error.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isExpectedUserError } from "./expected-cli-error.js";
-
-describe("isExpectedUserError", () => {
-  it("matches an Error explicitly marked expected", () => {
-    expect(isExpectedUserError(Object.assign(new Error("usage"), { expected: true }))).toBe(
-      true,
-    );
-  });
-
-  it("does NOT match Errors marked expected false or unmarked", () => {
-    expect(isExpectedUserError(Object.assign(new Error("boom"), { expected: false }))).toBe(
-      false,
-    );
-    expect(isExpectedUserError(new Error("boom"))).toBe(false);
-  });
-
-  it("does NOT match a plain object carrying expected true", () => {
-    expect(isExpectedUserError({ message: "usage", expected: true })).toBe(false);
-  });
-
-  it("does NOT match non-error values", () => {
-    expect(isExpectedUserError(null)).toBe(false);
-    expect(isExpectedUserError(undefined)).toBe(false);
-    expect(isExpectedUserError(42)).toBe(false);
-    expect(isExpectedUserError("usage")).toBe(false);
-  });
-});

package/src/utils/expected-cli-error.ts

@@ -1,39 +0,0 @@
-// src/utils/expected-cli-error.ts
-//
-// Classify errors that are the CALLER's request/state/permission rather than an
-// hq-cli code defect: a bad flag, malformed input, a correctly-denied client
-// 4xx (e.g. a non-owner running `hq integrations approve`). These are
-// user-facing and actionable — the CLI prints a clear message and does NOT
-// report them to Sentry, otherwise a correctly-enforced authorization denial
-// floods the tracker with identical, unfixable crash reports.
-//
-// This is the caller-side analog of hq-pro's `expectedDenialResponse`, and a
-// sibling of `environmental-error.ts` (HQ-CLI-2) and
-// `intercepted-process-exit.ts` (HQ-CLI-3): errors that are NOT hq-cli defects
-// are surfaced to the user but skipped for Sentry capture.
-//
-// HQ-CLI-6: `hq integrations approve|reject` by a non-owner got a correct 403
-// ("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.
-
-/**
- * An error the CLI should surface to the user (clear message, exit 1) but NOT
- * report to Sentry. Carriers set `expected: true`.
- */
-export interface ExpectedUserError extends Error {
-  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
- * capture. Anything else (unmarked errors, non-Error values) returns false so
- * genuine faults still reach Sentry.
- */
-export function isExpectedUserError(err: unknown): err is ExpectedUserError {
-  return (
-    err instanceof Error &&
-    (err as { expected?: unknown }).expected === true
-  );
-}

package/src/utils/feedback-diagnostics.test.ts

@@ -1,183 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import * as os from "os";
-
-vi.mock("child_process", () => ({
-  execFileSync: vi.fn(),
-}));
-
-vi.mock("./breadcrumb-buffer.js", () => ({
-  getRecentBreadcrumbs: vi.fn(() => []),
-}));
-
-import { execFileSync } from "child_process";
-import { getRecentBreadcrumbs } from "./breadcrumb-buffer.js";
-import { collectDiagnostics, sanitizeArgv } from "./feedback-diagnostics.js";
-import { CLI_VERSION } from "../cli-version.js";
-
-function mockGitSuccess(remoteUrl = "https://github.com/acme/repo.git"): void {
-  vi.mocked(execFileSync).mockImplementation(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (_cmd: string, args?: any): any => {
-      const a: string[] = args ?? [];
-      if (a[0] === "rev-parse" && a[1] === "--abbrev-ref") return "main\n";
-      if (a[0] === "rev-parse" && a[1] === "--short") return "abc1234\n";
-      if (a[0] === "status") return "";
-      if (a[0] === "remote") return `${remoteUrl}\n`;
-      return "";
-    },
-  );
-}
-
-beforeEach(() => {
-  vi.resetAllMocks();
-  vi.mocked(getRecentBreadcrumbs).mockReturnValue([]);
-  mockGitSuccess();
-});
-
-describe("sanitizeArgv", () => {
-  it("passes through non-secret args unchanged", () => {
-    expect(sanitizeArgv(["feedback", "bug", "--title", "test"])).toEqual([
-      "feedback",
-      "bug",
-      "--title",
-      "test",
-    ]);
-  });
-
-  it("redacts value following a secret flag", () => {
-    expect(sanitizeArgv(["secrets", "set", "NAME", "--token", "abc123"])).toEqual([
-      "secrets",
-      "set",
-      "NAME",
-      "--token",
-      "***",
-    ]);
-  });
-
-  it("redacts --password and --secret flags", () => {
-    expect(sanitizeArgv(["--password", "hunter2", "--secret", "s3cr3t"])).toEqual([
-      "--password",
-      "***",
-      "--secret",
-      "***",
-    ]);
-  });
-
-  it("does not redact a secret flag at the end with no following value", () => {
-    expect(sanitizeArgv(["--token"])).toEqual(["--token"]);
-  });
-
-  it("redacts value in --flag=value form for secret flags", () => {
-    expect(sanitizeArgv(["--token=abc123", "--password=hunter2"])).toEqual([
-      "--token=***",
-      "--password=***",
-    ]);
-  });
-
-  it("passes non-secret --flag=value forms through unchanged", () => {
-    expect(sanitizeArgv(["--title=foo", "--company=acme"])).toEqual([
-      "--title=foo",
-      "--company=acme",
-    ]);
-  });
-});
-
-describe("collectDiagnostics", () => {
-  it("populates cliVersion from the bundled CLI_VERSION constant (not env var)", () => {
-    const saved = process.env.npm_package_version;
-    delete process.env.npm_package_version;
-    const blob = collectDiagnostics();
-    expect(blob.cliVersion).toBe(CLI_VERSION);
-    if (saved !== undefined) process.env.npm_package_version = saved;
-  });
-
-  it("attaches a versions block carrying the cli version (core/sync best-effort)", () => {
-    const blob = collectDiagnostics();
-    expect(blob.versions.cli).toBe(CLI_VERSION);
-    // core + sync are environment-dependent; they must be present as
-    // string | null, never undefined, so triage always gets the shape.
-    expect(blob.versions).toHaveProperty("core");
-    expect(blob.versions).toHaveProperty("sync");
-    expect(["string", "object"]).toContain(typeof blob.versions.core); // string | null
-    expect(["string", "object"]).toContain(typeof blob.versions.sync); // string | null
-  });
-
-  it("cliVersion is unaffected by npm_package_version env var", () => {
-    process.env.npm_package_version = "99.99.99";
-    const blob = collectDiagnostics();
-    expect(blob.cliVersion).toBe(CLI_VERSION);
-    delete process.env.npm_package_version;
-  });
-
-  it("sanitizes secret flags in the captured command", () => {
-    const saved = process.argv;
-    process.argv = ["node", "/usr/bin/hq", "secrets", "set", "NAME", "--token", "secret123"];
-    const blob = collectDiagnostics();
-    expect(blob.command).toEqual(["secrets", "set", "NAME", "--token", "***"]);
-    process.argv = saved;
-  });
-
-  it("sanitizes --flag=value secret flags in the captured command", () => {
-    const saved = process.argv;
-    process.argv = ["node", "/usr/bin/hq", "secrets", "set", "NAME", "--token=secretXYZ"];
-    const blob = collectDiagnostics();
-    expect(blob.command).toEqual(["secrets", "set", "NAME", "--token=***"]);
-    process.argv = saved;
-  });
-
-  it("captures command as process.argv slice from index 2", () => {
-    const saved = process.argv;
-    process.argv = ["node", "/usr/bin/hq", "feedback", "bug"];
-    const blob = collectDiagnostics();
-    expect(blob.command).toEqual(["feedback", "bug"]);
-    process.argv = saved;
-  });
-
-  it("populates nodeVersion and os fields from process and os module", () => {
-    const blob = collectDiagnostics();
-    expect(blob.nodeVersion).toBe(process.version);
-    expect(blob.os.platform).toBe(os.platform());
-    expect(blob.os.release).toBe(os.release());
-    expect(blob.os.arch).toBe(os.arch());
-  });
-
-  it("sanitizes credentials embedded in HTTPS remote URLs", () => {
-    mockGitSuccess("https://user:s3cr3t@github.com/acme/repo.git");
-    const blob = collectDiagnostics();
-    expect(blob.git.remoteUrl).toBe("https://***@github.com/acme/repo.git");
-  });
-
-  it("returns null git context when not inside a git repo", () => {
-    vi.mocked(execFileSync).mockImplementation(() => {
-      throw new Error("not a git repo");
-    });
-    const blob = collectDiagnostics();
-    expect(blob.git.branch).toBeNull();
-    expect(blob.git.head).toBeNull();
-    expect(blob.git.remoteUrl).toBeNull();
-    expect(blob.git.dirty).toBe(false);
-  });
-
-  it("includes recentSentryBreadcrumbs from the ring buffer", () => {
-    const crumb = { category: "http", message: "GET /v1/foo", level: "info" as const };
-    vi.mocked(getRecentBreadcrumbs).mockReturnValue([crumb]);
-    const blob = collectDiagnostics();
-    expect(blob.recentSentryBreadcrumbs).toEqual([crumb]);
-  });
-
-  it("reports dirty=true when git status shows uncommitted changes", () => {
-    vi.mocked(execFileSync).mockImplementation(
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      (_cmd: string, args?: any): any => {
-        const a: string[] = args ?? [];
-        if (a[0] === "rev-parse" && a[1] === "--abbrev-ref") return "main\n";
-        if (a[0] === "rev-parse" && a[1] === "--short") return "abc1234\n";
-        if (a[0] === "status") return " M src/index.ts\n";
-        if (a[0] === "remote") return "https://github.com/acme/repo.git\n";
-        return "";
-      },
-    );
-    const blob = collectDiagnostics();
-    expect(blob.git.dirty).toBe(true);
-  });
-});

package/src/utils/feedback-diagnostics.ts

@@ -1,123 +0,0 @@
-import * as os from "os";
-import { execFileSync } from "child_process";
-import { getRecentBreadcrumbs } from "./breadcrumb-buffer.js";
-import { CLI_VERSION } from "../cli-version.js";
-import { collectVersions, type VersionInfo } from "./feedback-versions.js";
-
-export interface GitContext {
-  branch: string | null;
-  head: string | null;
-  dirty: boolean;
-  remoteUrl: string | null;
-}
-
-export interface DiagnosticsBlob {
-  cliVersion: string;
-  /**
-   * The hq-cli, hq-core, and hq-sync versions from the submitter's
-   * environment. `cliVersion` above is retained for back-compat; new
-   * consumers should read `versions` (which carries core + sync too).
-   */
-  versions: VersionInfo;
-  nodeVersion: string;
-  os: { platform: string; release: string; arch: string };
-  command: string[];
-  cwd: string;
-  git: GitContext;
-  recentSentryBreadcrumbs: unknown[];
-}
-
-const SECRET_FLAGS = new Set([
-  "--token",
-  "--secret",
-  "--password",
-  "--key",
-  "--api-key",
-  "--access-token",
-  "--auth-token",
-]);
-
-export function sanitizeArgv(argv: string[]): string[] {
-  const result: string[] = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg.startsWith("--") && arg.includes("=")) {
-      const eqIdx = arg.indexOf("=");
-      const flag = arg.slice(0, eqIdx);
-      if (SECRET_FLAGS.has(flag)) {
-        result.push(`${flag}=***`);
-        continue;
-      }
-    }
-    result.push(arg);
-    if (SECRET_FLAGS.has(arg) && i + 1 < argv.length) {
-      result.push("***");
-      i++;
-    }
-  }
-  return result;
-}
-
-function sanitizeRemoteUrl(url: string): string {
-  return url.replace(/https?:\/\/[^@]+@/, "https://***@");
-}
-
-function runGit(args: string[]): string {
-  return execFileSync("git", args, {
-    encoding: "utf-8",
-    timeout: 2000,
-    stdio: ["ignore", "pipe", "ignore"],
-  }).trim();
-}
-
-function collectGitContext(): GitContext {
-  let branch: string | null = null;
-  let head: string | null = null;
-  let dirty = false;
-  let remoteUrl: string | null = null;
-
-  try {
-    branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"]);
-  } catch {
-    return { branch: null, head: null, dirty: false, remoteUrl: null };
-  }
-
-  try {
-    head = runGit(["rev-parse", "--short", "HEAD"]);
-  } catch {
-    // best-effort
-  }
-
-  try {
-    const statusOut = runGit(["status", "--porcelain"]);
-    dirty = statusOut.length > 0;
-  } catch {
-    // best-effort
-  }
-
-  try {
-    const raw = runGit(["remote", "get-url", "origin"]);
-    remoteUrl = sanitizeRemoteUrl(raw);
-  } catch {
-    // no origin remote
-  }
-
-  return { branch, head, dirty, remoteUrl };
-}
-
-export function collectDiagnostics(): DiagnosticsBlob {
-  return {
-    cliVersion: CLI_VERSION,
-    versions: collectVersions(),
-    nodeVersion: process.version,
-    os: {
-      platform: os.platform(),
-      release: os.release(),
-      arch: os.arch(),
-    },
-    command: sanitizeArgv(process.argv.slice(2)),
-    cwd: process.cwd(),
-    git: collectGitContext(),
-    recentSentryBreadcrumbs: getRecentBreadcrumbs(),
-  };
-}

package/src/utils/feedback-screenshots.test.ts

@@ -1,134 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-vi.mock("./vault-api.js", () => ({
-  vaultApiFetch: vi.fn(),
-}));
-
-import { vaultApiFetch } from "./vault-api.js";
-import {
-  MAX_SCREENSHOTS,
-  contentTypeForPath,
-  loadScreenshots,
-  uploadScreenshots,
-} from "./feedback-screenshots.js";
-
-let tmp: string;
-
-beforeEach(() => {
-  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "shots-"));
-  vi.mocked(vaultApiFetch).mockReset();
-});
-afterEach(() => {
-  fs.rmSync(tmp, { recursive: true, force: true });
-});
-
-function writePng(name: string, bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47])): string {
-  const p = path.join(tmp, name);
-  fs.writeFileSync(p, bytes);
-  return p;
-}
-
-describe("contentTypeForPath", () => {
-  it("maps known image extensions (case-insensitive)", () => {
-    expect(contentTypeForPath("a.png")).toBe("image/png");
-    expect(contentTypeForPath("a.JPG")).toBe("image/jpeg");
-    expect(contentTypeForPath("a.jpeg")).toBe("image/jpeg");
-    expect(contentTypeForPath("a.webp")).toBe("image/webp");
-    expect(contentTypeForPath("a.gif")).toBe("image/gif");
-  });
-  it("rejects unsupported extensions", () => {
-    expect(() => contentTypeForPath("a.pdf")).toThrow(/unsupported screenshot type/);
-    expect(() => contentTypeForPath("a")).toThrow(/unsupported screenshot type/);
-  });
-});
-
-describe("loadScreenshots", () => {
-  it("reads valid images with their content types", () => {
-    const a = writePng("a.png");
-    const loaded = loadScreenshots([a]);
-    expect(loaded).toHaveLength(1);
-    expect(loaded[0].contentType).toBe("image/png");
-    expect(loaded[0].bytes.byteLength).toBeGreaterThan(0);
-  });
-  it("rejects more than MAX_SCREENSHOTS", () => {
-    const paths = Array.from({ length: MAX_SCREENSHOTS + 1 }, (_, i) => writePng(`s${i}.png`));
-    expect(() => loadScreenshots(paths)).toThrow(new RegExp(`at most ${MAX_SCREENSHOTS}`));
-  });
-  it("rejects a missing file", () => {
-    expect(() => loadScreenshots([path.join(tmp, "nope.png")])).toThrow(/cannot read screenshot/);
-  });
-  it("rejects an empty file", () => {
-    expect(() => loadScreenshots([writePng("empty.png", Buffer.alloc(0))])).toThrow(/empty/);
-  });
-});
-
-describe("uploadScreenshots", () => {
-  it("returns [] without calling the API when no paths given", async () => {
-    const keys = await uploadScreenshots({ paths: [], token: "t" });
-    expect(keys).toEqual([]);
-    expect(vaultApiFetch).not.toHaveBeenCalled();
-  });
-
-  it("presigns, PUTs each image to S3, and returns the keys", async () => {
-    const a = writePng("a.png");
-    const b = writePng("b.jpg");
-    vi.mocked(vaultApiFetch).mockResolvedValue({
-      ok: true,
-      json: async () => ({
-        screenshots: [
-          { key: "feedback-screenshots/prs_a/sub/0.png", url: "https://s3/put0", contentType: "image/png" },
-          { key: "feedback-screenshots/prs_a/sub/1.jpg", url: "https://s3/put1", contentType: "image/jpeg" },
-        ],
-      }),
-    } as unknown as Response);
-    const putCalls: Array<{ url: string; method?: string; contentType?: unknown }> = [];
-    const fetchImpl = vi.fn(async (url: string, init: { method?: string; headers?: Record<string, string> }) => {
-      putCalls.push({ url, method: init.method, contentType: init.headers?.["Content-Type"] });
-      return { ok: true, status: 200 } as Response;
-    }) as unknown as typeof fetch;
-
-    const keys = await uploadScreenshots({ paths: [a, b], token: "tok", fetchImpl });
-
-    expect(keys).toEqual([
-      "feedback-screenshots/prs_a/sub/0.png",
-      "feedback-screenshots/prs_a/sub/1.jpg",
-    ]);
-    // Presign request asked for the right content types.
-    const presignBody = vi.mocked(vaultApiFetch).mock.calls[0][0].body;
-    expect(presignBody).toEqual({ contentTypes: ["image/png", "image/jpeg"] });
-    // One PUT per image, to the presigned URL, with the right Content-Type.
-    expect(putCalls).toEqual([
-      { url: "https://s3/put0", method: "PUT", contentType: "image/png" },
-      { url: "https://s3/put1", method: "PUT", contentType: "image/jpeg" },
-    ]);
-  });
-
-  it("throws when the presign call fails", async () => {
-    const a = writePng("a.png");
-    vi.mocked(vaultApiFetch).mockResolvedValue({
-      ok: false,
-      statusText: "Bad Request",
-      json: async () => ({ error: "at most 5 screenshots are allowed" }),
-    } as unknown as Response);
-    await expect(uploadScreenshots({ paths: [a], token: "t" })).rejects.toThrow(
-      /Failed to presign screenshots: at most 5/,
-    );
-  });
-
-  it("throws when an S3 upload fails", async () => {
-    const a = writePng("a.png");
-    vi.mocked(vaultApiFetch).mockResolvedValue({
-      ok: true,
-      json: async () => ({
-        screenshots: [{ key: "feedback-screenshots/prs_a/sub/0.png", url: "https://s3/put0", contentType: "image/png" }],
-      }),
-    } as unknown as Response);
-    const fetchImpl = vi.fn(async () => ({ ok: false, status: 403 }) as Response) as unknown as typeof fetch;
-    await expect(uploadScreenshots({ paths: [a], token: "t", fetchImpl })).rejects.toThrow(
-      /Failed to upload screenshot .*: HTTP 403/,
-    );
-  });
-});