@indigoai-us/hq-cli 5.11.0 → 5.12.0

package/src/commands/feedback.test.ts

@@ -0,0 +1,369 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Readable } from "node:stream";
+import { Command } from "commander";
+
+vi.mock("../utils/cognito-session.js", () => ({
+  ensureCognitoToken: vi.fn(),
+}));
+
+vi.mock("../utils/vault-api.js", () => ({
+  vaultApiFetch: vi.fn(),
+}));
+
+vi.mock("../utils/feedback-diagnostics.js", () => ({
+  collectDiagnostics: vi.fn(() => ({
+    cliVersion: "5.11.0",
+    nodeVersion: process.version,
+    os: { platform: "linux", release: "5.15.0", arch: "x64" },
+    command: ["feedback", "bug"],
+    cwd: "/home/user",
+    git: { branch: "main", head: "abc1234", dirty: false, remoteUrl: null },
+    recentSentryBreadcrumbs: [],
+  })),
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    promises: {
+      ...actual.promises,
+      readFile: vi.fn(),
+    },
+  };
+});
+
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
+import * as fs from "node:fs";
+import {
+  submitFeedback,
+  readBodyFile,
+  registerFeedbackCommand,
+  BODY_MAX_BYTES,
+} from "./feedback.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const mockEnsureCognitoToken = vi.mocked(ensureCognitoToken);
+const mockVaultApiFetch = vi.mocked(vaultApiFetch);
+const mockCollectDiagnostics = vi.mocked(collectDiagnostics);
+const mockReadFile = vi.mocked(fs.promises.readFile);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockCollectDiagnostics.mockReturnValue({
+    cliVersion: "5.11.0",
+    nodeVersion: process.version,
+    os: { platform: "linux", release: "5.15.0", arch: "x64" },
+    command: ["feedback", "bug"],
+    cwd: "/home/user",
+    git: { branch: "main", head: "abc1234", dirty: false, remoteUrl: null },
+    recentSentryBreadcrumbs: [],
+  });
+});
+
+// ---------------------------------------------------------------------------
+// submitFeedback
+// ---------------------------------------------------------------------------
+
+describe("submitFeedback", () => {
+  it("returns the id from a successful bug submission", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_abc123" }),
+    );
+
+    const result = await submitFeedback({
+      type: "bug",
+      title: "Something broke",
+      body: "Details here",
+      token: "test-token",
+    });
+
+    expect(result.id).toBe("feedback_abc123");
+  });
+
+  it("sends type=feature for feature requests", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_feature1" }),
+    );
+
+    await submitFeedback({
+      type: "feature",
+      title: "Add dark mode",
+      body: "Would be great",
+      token: "test-token",
+    });
+
+    const call = mockVaultApiFetch.mock.calls[0][0];
+    expect(call.body).toMatchObject({ type: "feature" });
+  });
+
+  it("sends POST to /v1/feedback with the correct title and body", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_xyz" }),
+    );
+
+    await submitFeedback({
+      type: "bug",
+      title: "My title",
+      body: "My body text",
+      token: "tok",
+    });
+
+    const call = mockVaultApiFetch.mock.calls[0][0];
+    expect(call.path).toBe("/v1/feedback");
+    expect(call.method).toBe("POST");
+    expect(call.body).toMatchObject({ title: "My title", body: "My body text" });
+  });
+
+  it("includes company when provided", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_co1" }),
+    );
+
+    await submitFeedback({
+      type: "bug",
+      title: "Bug with company",
+      body: "Details",
+      company: "acme",
+      token: "tok",
+    });
+
+    const call = mockVaultApiFetch.mock.calls[0][0];
+    expect((call.body as Record<string, unknown>).company).toBe("acme");
+  });
+
+  it("omits company key when not provided", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_noco" }),
+    );
+
+    await submitFeedback({
+      type: "bug",
+      title: "No company",
+      body: "Details",
+      token: "tok",
+    });
+
+    const call = mockVaultApiFetch.mock.calls[0][0];
+    expect((call.body as Record<string, unknown>)).not.toHaveProperty("company");
+  });
+
+  it("attaches diagnostics from collectDiagnostics to the request body", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_diag" }),
+    );
+
+    await submitFeedback({
+      type: "bug",
+      title: "With diag",
+      body: "Body",
+      token: "tok",
+    });
+
+    expect(mockCollectDiagnostics).toHaveBeenCalledOnce();
+    const call = mockVaultApiFetch.mock.calls[0][0];
+    expect((call.body as Record<string, unknown>).diagnostics).toBeDefined();
+    expect(
+      ((call.body as Record<string, unknown>).diagnostics as Record<string, unknown>).cliVersion,
+    ).toBe("5.11.0");
+  });
+
+  it("throws with the error from the response body on non-2xx", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(400, { error: "title too long" }),
+    );
+
+    await expect(
+      submitFeedback({
+        type: "bug",
+        title: "Bad",
+        body: "Body",
+        token: "tok",
+      }),
+    ).rejects.toThrow("title too long");
+  });
+
+  it("throws with statusText when response has no parseable error body", async () => {
+    mockVaultApiFetch.mockResolvedValueOnce(
+      new Response("internal error", { status: 500, statusText: "Internal Server Error" }),
+    );
+
+    await expect(
+      submitFeedback({
+        type: "bug",
+        title: "Server fail",
+        body: "Body",
+        token: "tok",
+      }),
+    ).rejects.toThrow(/Internal Server Error/);
+  });
+
+  it("throws before fetching when body exceeds 64 KiB", async () => {
+    const largeBody = "x".repeat(BODY_MAX_BYTES + 1);
+
+    await expect(
+      submitFeedback({
+        type: "bug",
+        title: "Big body",
+        body: largeBody,
+        token: "tok",
+      }),
+    ).rejects.toThrow(/64 KiB limit/);
+
+    expect(mockVaultApiFetch).not.toHaveBeenCalled();
+  });
+
+  it("accepts a body exactly at the 64 KiB limit", async () => {
+    const exactBody = "x".repeat(BODY_MAX_BYTES);
+    mockVaultApiFetch.mockResolvedValueOnce(
+      jsonResponse(200, { id: "feedback_exact" }),
+    );
+
+    const result = await submitFeedback({
+      type: "bug",
+      title: "Exact size",
+      body: exactBody,
+      token: "tok",
+    });
+
+    expect(result.id).toBe("feedback_exact");
+  });
+
+  it("throws before fetching when body is empty or whitespace-only", async () => {
+    await expect(
+      submitFeedback({
+        type: "bug",
+        title: "Empty",
+        body: "   \n\t  ",
+        token: "tok",
+      }),
+    ).rejects.toThrow(/must not be empty/);
+
+    expect(mockVaultApiFetch).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// readBodyFile
+// ---------------------------------------------------------------------------
+
+describe("readBodyFile", () => {
+  it("reads content from a file path", async () => {
+    mockReadFile.mockResolvedValueOnce("file body content" as never);
+
+    const content = await readBodyFile("/tmp/body.md");
+
+    expect(mockReadFile).toHaveBeenCalledWith("/tmp/body.md", "utf-8");
+    expect(content).toBe("file body content");
+  });
+
+  it('reads content from stdin when path is "-"', async () => {
+    const mockStdin = new Readable({
+      read() {
+        this.push("stdin content");
+        this.push(null);
+      },
+    });
+
+    const content = await readBodyFile("-", mockStdin as NodeJS.ReadableStream);
+
+    expect(content).toBe("stdin content");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// registerFeedbackCommand — action integration
+// ---------------------------------------------------------------------------
+
+describe("registerFeedbackCommand — action integration", () => {
+  function makeProgram(): Command {
+    const p = new Command();
+    p.exitOverride();
+    registerFeedbackCommand(p);
+    return p;
+  }
+
+  beforeEach(() => {
+    mockEnsureCognitoToken.mockResolvedValue("test-token");
+  });
+
+  it("success: prints Submitted: <id> and does not call process.exit", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    mockReadFile.mockResolvedValueOnce("Valid bug report body." as never);
+    mockVaultApiFetch.mockResolvedValueOnce(jsonResponse(200, { id: "feedback_abc123" }));
+
+    await makeProgram().parseAsync([
+      "node", "hq", "feedback", "bug",
+      "--title", "Test bug",
+      "--body-file", "/tmp/body.md",
+    ]);
+
+    expect(logSpy).toHaveBeenCalledWith("Submitted: feedback_abc123");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("error: API error routes to chalk error prefix and process.exit(1)", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    mockReadFile.mockResolvedValueOnce("Some body text." as never);
+    mockVaultApiFetch.mockResolvedValueOnce(jsonResponse(400, { error: "title too long" }));
+
+    await makeProgram().parseAsync([
+      "node", "hq", "feedback", "bug",
+      "--title", "Bad",
+      "--body-file", "/tmp/body.md",
+    ]);
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Error"),
+      expect.stringContaining("title too long"),
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("auth error: ensureCognitoToken throws → chalk error prefix and process.exit(1)", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    mockEnsureCognitoToken.mockRejectedValueOnce(new Error("not authenticated"));
+
+    await makeProgram().parseAsync([
+      "node", "hq", "feedback", "feature",
+      "--title", "Nice feat",
+      "--body-file", "/tmp/body.md",
+    ]);
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Error"),
+      "not authenticated",
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("oversize body: submitFeedback throws 64 KiB error → process.exit(1)", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    const largeBody = "x".repeat(BODY_MAX_BYTES + 1);
+    mockReadFile.mockResolvedValueOnce(largeBody as never);
+
+    await makeProgram().parseAsync([
+      "node", "hq", "feedback", "bug",
+      "--title", "Big",
+      "--body-file", "/tmp/big.md",
+    ]);
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Error"),
+      expect.stringContaining("64 KiB limit"),
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/commands/feedback.ts

@@ -0,0 +1,136 @@
+import * as fs from "node:fs";
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { collectDiagnostics } from "../utils/feedback-diagnostics.js";
+
+export const BODY_MAX_BYTES = 64 * 1024;
+
+export interface FeedbackResult {
+  id: string;
+}
+
+export interface FeedbackSubmitOptions {
+  type: "bug" | "feature";
+  title: string;
+  body: string;
+  company?: string;
+  token: string;
+}
+
+export async function readBodyFile(
+  bodyFile: string,
+  stdin?: NodeJS.ReadableStream,
+): Promise<string> {
+  if (bodyFile === "-") {
+    const stream = stdin ?? process.stdin;
+    if ((stream as NodeJS.ReadStream).isTTY) {
+      throw new Error(
+        "--body-file - requires piped stdin (got interactive terminal).",
+      );
+    }
+    return new Promise((resolve, reject) => {
+      let data = "";
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk: string) => {
+        data += chunk;
+      });
+      stream.on("end", () => resolve(data));
+      stream.on("error", reject);
+    });
+  }
+  return fs.promises.readFile(bodyFile, "utf-8");
+}
+
+export async function submitFeedback(
+  opts: FeedbackSubmitOptions,
+): Promise<FeedbackResult> {
+  if (opts.body.trim().length === 0) {
+    throw new Error(
+      "body must not be empty. Provide at least one non-whitespace character.",
+    );
+  }
+
+  const bodyBytes = Buffer.byteLength(opts.body, "utf8");
+  if (bodyBytes > BODY_MAX_BYTES) {
+    throw new Error(
+      `Body exceeds 64 KiB limit (${bodyBytes} bytes). Reduce the body size before submitting.`,
+    );
+  }
+
+  const diagnostics = collectDiagnostics();
+
+  const requestBody: Record<string, unknown> = {
+    type: opts.type,
+    title: opts.title,
+    body: opts.body,
+    diagnostics,
+  };
+  if (opts.company) {
+    requestBody.company = opts.company;
+  }
+
+  const res = await vaultApiFetch({
+    token: opts.token,
+    path: "/v1/feedback",
+    method: "POST",
+    body: requestBody,
+  });
+
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    const errMsg =
+      data &&
+      typeof data === "object" &&
+      !Array.isArray(data) &&
+      typeof (data as { error?: unknown }).error === "string"
+        ? (data as { error: string }).error
+        : res.statusText;
+    throw new Error(`Failed to submit feedback: ${errMsg}`);
+  }
+
+  const data = (await res.json()) as { id: string };
+  return { id: data.id };
+}
+
+function registerSubcommand(feedbackCmd: Command, type: "bug" | "feature"): void {
+  feedbackCmd
+    .command(type)
+    .description(type === "bug" ? "Report a bug" : "Request a feature")
+    .requiredOption("--title <text>", "Short title for the report")
+    .requiredOption(
+      "--body-file <path>",
+      "Path to a markdown file with the body; use - to read from stdin",
+    )
+    .option("--company <slug>", "Company slug to associate with the report")
+    .action(async (opts: { title: string; bodyFile: string; company?: string }) => {
+      try {
+        const token = await ensureCognitoToken({ interactive: false });
+        const body = await readBodyFile(opts.bodyFile);
+        const result = await submitFeedback({
+          type,
+          title: opts.title,
+          body,
+          company: opts.company,
+          token,
+        });
+        console.log(`Submitted: ${result.id}`);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}
+
+export function registerFeedbackCommand(program: Command): void {
+  const feedbackCmd = program
+    .command("feedback")
+    .description("Submit a bug report or feature request to HQ");
+
+  registerSubcommand(feedbackCmd, "bug");
+  registerSubcommand(feedbackCmd, "feature");
+}

package/src/index.ts

@@ -28,6 +28,8 @@ import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerMembersCommand } from "./commands/members.js";
+import { registerFeedbackCommand } from "./commands/feedback.js";
+import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 
 initSentry();
 
@@ -36,7 +38,7 @@ const program = new Command();
 program
   .name("hq")
   .description("HQ management CLI — modules, packages, and cloud sync")
-  .version("5.8.6");
+  .version("5.12.0");
 
 // Module management subcommand group
 const modulesCmd = program
@@ -109,8 +111,16 @@ registerMembersCommand(program);
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);
 
+// Feedback (subcommand group — hq feedback bug|feature)
+registerFeedbackCommand(program);
+
 (async () => {
   try {
+    Sentry.addBreadcrumb({
+      category: "command",
+      message: sanitizeArgv(process.argv.slice(2)).join(" "),
+      level: "info",
+    });
     await program.parseAsync();
   } catch (err) {
     Sentry.captureException(err);

package/src/sentry.ts

@@ -1,6 +1,7 @@
 import * as Sentry 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";
 
 export function initSentry(): void {
   const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
@@ -13,6 +14,7 @@ export function initSentry(): void {
       tags: { repo: "hq-cli" },
     },
     beforeSend,
+    beforeBreadcrumb,
   });
 }
 

package/src/utils/breadcrumb-buffer.ts

@@ -0,0 +1,18 @@
+import type { Breadcrumb } from "@sentry/node";
+
+const BUFFER_SIZE = 20;
+const _buffer: Breadcrumb[] = [];
+
+// Sentry beforeBreadcrumb hook: records every breadcrumb in a ring buffer
+// and returns it unchanged so Sentry still processes it normally.
+export function beforeBreadcrumb(breadcrumb: Breadcrumb): Breadcrumb | null {
+  _buffer.push(breadcrumb);
+  if (_buffer.length > BUFFER_SIZE) {
+    _buffer.shift();
+  }
+  return breadcrumb;
+}
+
+export function getRecentBreadcrumbs(): Breadcrumb[] {
+  return [..._buffer];
+}