@indigoai-us/hq-cli 5.12.1 → 5.12.3

package/src/commands/files.test.ts

@@ -0,0 +1,504 @@
+/**
+ * Unit tests for `hq files share` (files.ts).
+ *
+ * Coverage:
+ *   - parseDuration — pure parser
+ *   - mintShareSession — happy path + error mapping (401, 403 with path)
+ *   - formatShareSessionError — status → user copy
+ *   - registerFilesCommand share action — fork by --with presence:
+ *       * no --with: calls mint endpoint, prints URL, --no-open suppresses launch
+ *       * with --with: calls existing direct-grant endpoint, NEVER mints
+ *       * no paths: prints usage and exits non-zero
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
+
+// Mock the `open` package BEFORE importing files.ts so the action handler
+// resolves to the mock. Returning a resolved promise mirrors open()'s real
+// signature without launching a real browser.
+vi.mock("open", () => ({
+  default: vi.fn(() => Promise.resolve({ pid: 0 })),
+}));
+
+// `ensureCognitoToken` hits a real keychain/disk path otherwise. Stub it so
+// the action runs without I/O and we can assert pure behavior.
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+import { Command } from "commander";
+import open from "open";
+import {
+  MAX_SHARE_SESSION_EXPIRY_MS,
+  ShareSessionHttpError,
+  formatShareSessionError,
+  mintShareSession,
+  parseDuration,
+  registerFilesCommand,
+} from "./files.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let exitSpy: MockInstance<typeof process.exit>;
+let logSpy: MockInstance<typeof console.log>;
+let errSpy: MockInstance<typeof console.error>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  // process.exit gets thrown so the action's try/catch doesn't keep running
+  // after a failure path — mirrors how Commander aborts in real usage.
+  exitSpy = vi
+    .spyOn(process, "exit")
+    .mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(open).mockClear();
+});
+
+// ---------------------------------------------------------------------------
+// parseDuration
+// ---------------------------------------------------------------------------
+
+describe("parseDuration", () => {
+  it("parses minutes/hours/days into ms", () => {
+    expect(parseDuration("15m")).toBe(15 * 60 * 1000);
+    expect(parseDuration("1h")).toBe(60 * 60 * 1000);
+    expect(parseDuration("24h")).toBe(24 * 60 * 60 * 1000);
+    expect(parseDuration("2d")).toBe(2 * 24 * 60 * 60 * 1000);
+  });
+
+  it("returns null for invalid formats", () => {
+    expect(parseDuration("15")).toBeNull();
+    expect(parseDuration("abc")).toBeNull();
+    expect(parseDuration("15s")).toBeNull();
+    expect(parseDuration("")).toBeNull();
+  });
+
+  it("agrees with the documented 24h ceiling constant", () => {
+    expect(parseDuration("24h")).toBe(MAX_SHARE_SESSION_EXPIRY_MS);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mintShareSession
+// ---------------------------------------------------------------------------
+
+describe("mintShareSession", () => {
+  it("POSTs paths to /files/{companyUid}/share-session and returns the response", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        url: "https://share.hq/abc",
+        token: "tok_share_xyz",
+        expiresAt: "2026-05-11T12:00:00Z",
+        nonce: "nnnnnn",
+        paths: ["docs/", "reports/q1.pdf"],
+        maxPermissionByPath: { "docs/": "read", "reports/q1.pdf": "read" },
+      }),
+    );
+
+    const session = await mintShareSession({
+      token: "test-token",
+      companyUid: "cmp_acme",
+      paths: ["docs/", "reports/q1.pdf"],
+    });
+
+    expect(session.url).toBe("https://share.hq/abc");
+    expect(session.expiresAt).toBe("2026-05-11T12:00:00Z");
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/files\/cmp_acme\/share-session$/);
+    expect(call[1]?.method).toBe("POST");
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({ paths: ["docs/", "reports/q1.pdf"] });
+  });
+
+  it("includes expiresInMs only when supplied", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://share.hq/x", expiresAt: "now" }),
+    );
+
+    await mintShareSession({
+      token: "test-token",
+      companyUid: "cmp_acme",
+      paths: ["foo"],
+      expiresInMs: 15 * 60 * 1000,
+    });
+
+    const body = JSON.parse(
+      (fetchSpy.mock.calls[0][1]?.body as string) ?? "{}",
+    );
+    expect(body).toEqual({ paths: ["foo"], expiresInMs: 15 * 60 * 1000 });
+  });
+
+  it("throws ShareSessionHttpError on 401", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(401, { error: "unauth" }));
+    await expect(
+      mintShareSession({
+        token: "bad",
+        companyUid: "cmp_acme",
+        paths: ["foo"],
+      }),
+    ).rejects.toBeInstanceOf(ShareSessionHttpError);
+  });
+
+  it("propagates the offending path on 403 forbidden-per-path", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "forbidden", path: "secrets/" }),
+    );
+    try {
+      await mintShareSession({
+        token: "test-token",
+        companyUid: "cmp_acme",
+        paths: ["secrets/"],
+      });
+      expect.fail("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ShareSessionHttpError);
+      expect((err as ShareSessionHttpError).status).toBe(403);
+      expect((err as ShareSessionHttpError).path).toBe("secrets/");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatShareSessionError
+// ---------------------------------------------------------------------------
+
+describe("formatShareSessionError", () => {
+  it("maps 401 to a login hint", () => {
+    expect(
+      formatShareSessionError(new ShareSessionHttpError(401, "unauth")),
+    ).toMatch(/run `hq login`/);
+  });
+
+  it("maps 403 with a path to a per-path message", () => {
+    const err = new ShareSessionHttpError(403, "forbidden", "secrets/");
+    expect(formatShareSessionError(err)).toMatch(/'secrets\/'/);
+  });
+
+  it("maps 403 without a path to a generic membership hint", () => {
+    expect(
+      formatShareSessionError(new ShareSessionHttpError(403, "forbidden")),
+    ).toMatch(/company member/);
+  });
+
+  it("prefixes 5xx with 'Server error:'", () => {
+    expect(
+      formatShareSessionError(new ShareSessionHttpError(500, "boom")),
+    ).toMatch(/^Server error: boom/);
+  });
+
+  it("falls through to the message for unmapped statuses", () => {
+    expect(
+      formatShareSessionError(new ShareSessionHttpError(418, "tea")),
+    ).toMatch(/tea/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Command action — share fork: no --with → mint, with --with → direct grant
+// ---------------------------------------------------------------------------
+
+/** Build a fresh program + register `files` so each test gets a clean parser. */
+function buildProgram(): Command {
+  const program = new Command();
+  // exitOverride keeps Commander from killing the process on parse errors —
+  // we want any failure to surface as a thrown error or a process.exit spy.
+  program.exitOverride();
+  registerFilesCommand(program);
+  return program;
+}
+
+describe("hq files share — browser-launch fork (no --with)", () => {
+  it("PRD scenario 1: --no-open prints URL, exits 0, does not call open()", async () => {
+    // 1) /membership/me — used by getCompanyUid fallback
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/share-session
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        url: "https://share.hq/fixture-url",
+        expiresAt: "2026-05-11T13:00:00Z",
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "fooPath", "--no-open"],
+      { from: "user" },
+    );
+
+    // Mint endpoint was called, with the right body.
+    const mintCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCall).toBeDefined();
+    const body = JSON.parse((mintCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({ paths: ["fooPath"] });
+
+    // URL printed to stdout.
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://share.hq/fixture-url");
+
+    // Browser was NOT launched.
+    expect(open).not.toHaveBeenCalled();
+
+    // No process.exit on the success path.
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("forwards --expires as ms to the mint endpoint", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        url: "https://share.hq/x",
+        expiresAt: "2026-05-11T13:00:00Z",
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "foo", "--expires", "1h", "--no-open"],
+      { from: "user" },
+    );
+
+    const mintCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/share-session"),
+    )!;
+    const body = JSON.parse((mintCall[1]?.body as string) ?? "{}");
+    expect(body).toEqual({ paths: ["foo"], expiresInMs: 60 * 60 * 1000 });
+  });
+
+  it("rejects --expires beyond the 24h CLI ceiling", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "foo", "--expires", "2d", "--no-open"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/Maximum share-session expiry is 24h/);
+    // No fetch should have happened — pre-validation rejected early.
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("prints a usage message when no paths are supplied", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "share"], { from: "user" }),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/usage: hq files share <paths\.\.\.>/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a 401 from the mint endpoint as an actionable error", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(401, { error: "unauth" }));
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "foo", "--no-open"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/run `hq login`/);
+  });
+});
+
+describe("hq files share — direct-grant fork (with --with)", () => {
+  it("PRD scenario 2: --with email --permission read writes a direct grant and never calls the mint endpoint", async () => {
+    // 1) /membership/me for company resolution
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/acl/grant
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { acl: { path: "fooPath" } }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "files",
+        "share",
+        "fooPath",
+        "--with",
+        "user@example.com",
+        "--permission",
+        "read",
+      ],
+      { from: "user" },
+    );
+
+    // The mint endpoint MUST NOT have been called.
+    const mintCalls = fetchSpy.mock.calls.filter((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCalls).toHaveLength(0);
+
+    // The grant endpoint WAS called with the right body.
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    expect(grantCall).toBeDefined();
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "fooPath",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "read",
+    });
+
+    // Browser must not have launched in the direct-grant flow.
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("rejects multiple paths when --with is set", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        [
+          "files",
+          "share",
+          "a",
+          "b",
+          "--with",
+          "user@example.com",
+          "--permission",
+          "read",
+        ],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/exactly one prefix/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("US-001 regression: --with @all writes a company-wide grant (granteeType:'company-wide', granteeId:'')", async () => {
+    // 1) /membership/me for company resolution
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/acl/grant
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { acl: { path: "fooPath" } }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "fooPath", "--with", "@all", "--permission", "write"],
+      { from: "user" },
+    );
+
+    // Mint endpoint MUST NOT have been called — direct-grant fork only.
+    const mintCalls = fetchSpy.mock.calls.filter((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCalls).toHaveLength(0);
+
+    // Grant endpoint received a company-wide entry per US-001.
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    expect(grantCall).toBeDefined();
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "fooPath",
+      granteeType: "company-wide",
+      granteeId: "",
+      permission: "write",
+    });
+
+    // Browser must not have launched in the direct-grant flow.
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("rejects --with without --permission", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "foo", "--with", "user@example.com"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/--permission is required/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});