@indigoai-us/hq-cli 5.76.0 → 5.77.1

package/src/commands/agents.test.ts

@@ -363,6 +363,47 @@ describe("hq agents provision (billing gate)", () => {
     expect(printed).toContain("https://checkout.stripe.com/card");
   });
 
+  it("surfaces the DECLINE reason on 402 payment_failed (message-first decoding)", async () => {
+    // The payment_failed envelope carries BOTH the generic error AND the
+    // friendly decline message — the decode must prefer `message` or the
+    // decline copy is lost and the operator sees "add a card" for a card
+    // that exists and was declined.
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          message:
+            "Your card was declined. Try a different card or contact your bank.",
+          code: "PAYMENT_FAILED",
+          billing: {
+            status: "payment_failed",
+            setup: {
+              payerType: "company",
+              path: "/v1/billing/checkout/org",
+              method: "POST",
+              body: { companyUid: "cmp_acme" },
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/update" }),
+      );
+
+    const logSpyLocal = vi.spyOn(console, "log").mockImplementation(() => {});
+    const errSpyLocal = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    const printed = [...errSpyLocal.mock.calls, ...logSpyLocal.mock.calls]
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toContain("declined");
+    expect(printed).not.toContain("No card on file");
+    expect(printed).toContain("https://checkout.stripe.com/update");
+  });
+
   it("requires --api-key-env for --auth-mode apiKey (before any charge)", async () => {
     await expect(
       run([

package/src/commands/agents.ts

@@ -31,7 +31,7 @@ import {
   AGENT_PRICE_CENTS,
   confirmChargeOrExit,
   parseBillingPayload,
-  surfaceBillingRequired,
+  surfaceBillingBlocked,
   type BillingErrorPayload,
 } from "../utils/billing-gate.js";
 
@@ -125,7 +125,11 @@ export async function agentsRequest<T>(opts: {
     };
     throw new AgentsHttpError(
       res.status,
-      body.error ?? body.message ?? res.statusText,
+      // `message` FIRST: on a payment_failed envelope it carries the friendly
+      // decline copy ("Your card was declined…") while `error` is the generic
+      // "payment required" — error-first would feed surfaceBillingBlocked the
+      // generic string and lose the decline reason (mirrors outpostRequest).
+      body.message ?? body.error ?? res.statusText,
       body.code,
       parseBillingPayload(body),
     );
@@ -592,7 +596,7 @@ export function registerAgentsCommand(program: Command): void {
             err.status === 402 &&
             err.billing
           ) {
-            await surfaceBillingRequired(token, err.billing);
+            await surfaceBillingBlocked(token, err.billing, err.message);
             process.exit(1);
           }
           throw err;

package/src/commands/cloud.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { configureSyncLockTimeout } from "./cloud.js";
+
+const originalLockTimeout = process.env.HQ_OP_LOCK_TIMEOUT;
+
+afterEach(() => {
+  if (originalLockTimeout === undefined) {
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
+  } else {
+    process.env.HQ_OP_LOCK_TIMEOUT = originalLockTimeout;
+  }
+});
+
+describe("configureSyncLockTimeout", () => {
+  it("supplies a finite foreground wait when the caller has not configured one", () => {
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
+    configureSyncLockTimeout(undefined);
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("300");
+  });
+
+  it("honors an explicit zero-second refusal", () => {
+    configureSyncLockTimeout("0");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("0");
+  });
+
+  it("honors a valid inherited lock timeout", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "17";
+    configureSyncLockTimeout(undefined);
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("17");
+  });
+
+  it("rejects an invalid timeout instead of silently waiting forever", () => {
+    expect(() => configureSyncLockTimeout("forever")).toThrow("--lock-timeout");
+  });
+
+  it("rejects an invalid inherited timeout instead of restoring an infinite wait", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "forever";
+    expect(() => configureSyncLockTimeout(undefined)).toThrow("--lock-timeout");
+  });
+});

package/src/commands/cloud.ts

@@ -97,6 +97,24 @@ function resolveDeletePolicy(): "owned-only" | "currency-gated" | "all" {
 interface CommonSyncOptions {
   hqRoot: string;
   company?: string;
+  lockTimeout?: string;
+}
+
+const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
+
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export function configureSyncLockTimeout(raw: string | undefined): void {
+  const value = raw ?? process.env.HQ_OP_LOCK_TIMEOUT ?? String(DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS);
+  const seconds = Number(value);
+  if (!Number.isInteger(seconds) || seconds < 0) {
+    throw new Error("--lock-timeout must be a non-negative integer number of seconds");
+  }
+  process.env.HQ_OP_LOCK_TIMEOUT = String(seconds);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -821,6 +839,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--message <msg>",
       "Optional message attached to journal entries for these uploads",
@@ -884,6 +906,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "push");
         } catch (err) {
           console.error(
@@ -1118,6 +1141,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--on-conflict <strategy>",
       "Conflict strategy: overwrite | keep | abort (omit for interactive)",
@@ -1168,6 +1195,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "pull");
         } catch (err) {
           console.error(
@@ -1410,6 +1438,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--message <msg>",
       "Optional message attached to journal entries for the push leg",
@@ -1460,6 +1492,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "now");
           if (options.all) {
             // `options.personal === false` is Commander's auto-negation

package/src/commands/files-recovery.test.ts

@@ -0,0 +1,361 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("open", () => ({ default: vi.fn(() => Promise.resolve({ pid: 0 })) }));
+
+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 {
+  formatFilesTrashTable,
+  formatFilesVersionsTable,
+  registerFilesCommand,
+  runFilesRestore,
+  runFilesTrash,
+  runFilesVersions,
+} from "./files.js";
+import { Command } from "commander";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function membershipResponse(): Response {
+  return jsonResponse(200, {
+    memberships: [
+      {
+        membershipKey: "k1",
+        companyUid: "cmp_acme",
+        role: "member",
+        status: "active",
+      },
+    ],
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let logSpy: MockInstance<typeof console.log>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function requestedUrl(index: number): URL {
+  return new URL(String(fetchSpy.mock.calls[index][0]));
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerFilesCommand(program);
+  return program;
+}
+
+describe("hq files versions", () => {
+  it("renders delete markers alongside content versions", () => {
+    const table = formatFilesVersionsTable([
+      {
+        versionId: "marker",
+        isLatest: true,
+        isDeleteMarker: true,
+        lastModified: "2026-07-20T12:00:00.000Z",
+        size: 0,
+      },
+      {
+        versionId: "content",
+        isLatest: false,
+        lastModified: "2026-07-19T12:00:00.000Z",
+        size: 1024,
+      },
+    ]);
+
+    expect(table).toContain("delete marker");
+    expect(table).toContain("1.0 KiB");
+    expect(table).toContain("VERSION");
+    expect(table).toContain("LATEST");
+  });
+
+  it("uses the company selector for an exact-key history request", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        key: "notes/a.md",
+        versions: [],
+        computedAt: "2026-07-20T12:00:00.000Z",
+      }),
+    );
+
+    await runFilesVersions({
+      key: "notes/a.md",
+      personal: false,
+      companySlug: undefined,
+    });
+
+    const url = requestedUrl(1);
+    expect(url.pathname).toBe("/v1/files/versions");
+    expect(url.searchParams.get("company")).toBe("cmp_acme");
+    expect(url.searchParams.get("key")).toBe("notes/a.md");
+    expect(url.searchParams.get("personal")).toBeNull();
+  });
+
+  it("uses only the caller-owned personal selector", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        key: "notes/private.md",
+        versions: [],
+        computedAt: "2026-07-20T12:00:00.000Z",
+      }),
+    );
+
+    await runFilesVersions({
+      key: "notes/private.md",
+      personal: true,
+      companySlug: undefined,
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const url = requestedUrl(0);
+    expect(url.searchParams.get("personal")).toBe("1");
+    expect(url.searchParams.get("company")).toBeNull();
+  });
+});
+
+describe("hq files restore", () => {
+  it("does not call the API when the overwrite confirmation is declined", async () => {
+    const confirm = vi.fn(async () => false);
+    const result = await runFilesRestore(
+      {
+        key: "notes/a.md",
+        yes: false,
+        personal: false,
+        companySlug: undefined,
+      },
+      { confirm },
+    );
+
+    expect(result).toBeUndefined();
+    expect(confirm).toHaveBeenCalledWith(
+      expect.stringContaining("overwrites current content"),
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("Aborted"));
+  });
+
+  it("uses CopyObject restore endpoint shape and bypasses confirm with --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        key: "notes/a.md",
+        wasDeleted: true,
+        restoredFromVersionId: "old-version",
+        newVersionId: "new-version",
+      }),
+    );
+
+    const confirm = vi.fn(async () => {
+      throw new Error("--yes must bypass confirmation");
+    });
+    await runFilesRestore(
+      {
+        key: "notes/a.md",
+        versionId: "old-version",
+        yes: true,
+        personal: false,
+        companySlug: undefined,
+      },
+      { confirm },
+    );
+
+    expect(confirm).not.toHaveBeenCalled();
+    expect(requestedUrl(1).pathname).toBe("/v1/files/restore");
+    expect(fetchSpy.mock.calls[1][1]?.method).toBe("POST");
+    expect(JSON.parse(String(fetchSpy.mock.calls[1][1]?.body))).toEqual({
+      company: "cmp_acme",
+      key: "notes/a.md",
+      versionId: "old-version",
+    });
+  });
+
+  it("uses the caller-owned personal restore body without a company lookup", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        key: "notes/private.md",
+        wasDeleted: false,
+        restoredFromVersionId: "prior-version",
+        newVersionId: "copied-version",
+      }),
+    );
+
+    await runFilesRestore(
+      {
+        key: "notes/private.md",
+        yes: true,
+        personal: true,
+        companySlug: undefined,
+      },
+      { confirm: async () => true },
+    );
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(requestedUrl(0).pathname).toBe("/v1/files/restore");
+    expect(fetchSpy.mock.calls[0][1]?.method).toBe("POST");
+    expect(JSON.parse(String(fetchSpy.mock.calls[0][1]?.body))).toEqual({
+      personal: true,
+      key: "notes/private.md",
+    });
+  });
+});
+
+describe("hq files trash", () => {
+  it("formats durable tombstones", () => {
+    expect(
+      formatFilesTrashTable([
+        {
+          key: "notes/deleted.md",
+          deletedAt: "2026-07-20T12:00:00.000Z",
+          deletedBy: "per_owner",
+          deletedPrefix: "notes/",
+        },
+      ]),
+    ).toContain("notes/deleted.md");
+    expect(formatFilesTrashTable([])).toBe("Trash is empty.");
+  });
+
+  it("uses company scope with a literal prefix", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        companyUid: "cmp_acme",
+        tombstones: [],
+        truncated: false,
+        computedAt: "2026-07-20T12:00:00.000Z",
+      }),
+    );
+
+    await runFilesTrash({
+      prefix: "notes/",
+      personal: false,
+      companySlug: undefined,
+    });
+
+    const url = requestedUrl(1);
+    expect(url.pathname).toBe("/v1/files/tombstones");
+    expect(url.searchParams.get("company")).toBe("cmp_acme");
+    expect(url.searchParams.get("prefix")).toBe("notes/");
+    expect(url.searchParams.get("personal")).toBeNull();
+  });
+
+  it("uses personal scope with literal prefix and cursor", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        personal: true,
+        tombstones: [],
+        cursor: "next",
+        truncated: true,
+        computedAt: "2026-07-20T12:00:00.000Z",
+      }),
+    );
+
+    await runFilesTrash({
+      prefix: "notes/",
+      cursor: "cursor-1",
+      personal: true,
+      companySlug: undefined,
+    });
+
+    const url = requestedUrl(0);
+    expect(url.pathname).toBe("/v1/files/tombstones");
+    expect(url.searchParams.get("personal")).toBe("1");
+    expect(url.searchParams.get("prefix")).toBe("notes/");
+    expect(url.searchParams.get("cursor")).toBe("cursor-1");
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "hq files trash --personal --prefix 'notes/' --cursor 'next'",
+      ),
+    );
+  });
+
+  it("rejects wildcard trash prefixes without making a request", async () => {
+    await expect(
+      runFilesTrash({
+        prefix: "notes/*",
+        personal: true,
+        companySlug: undefined,
+      }),
+    ).rejects.toThrow(/literal/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq files recovery command help", () => {
+  it("documents the finalized --version and --prefix option forms", () => {
+    const program = buildProgram();
+    const files = program.commands.find((command) => command.name() === "files");
+    const restore = files?.commands.find((command) => command.name() === "restore");
+    const trash = files?.commands.find((command) => command.name() === "trash");
+
+    expect(files?.helpInformation()).toContain("versions [options] <path>");
+    expect(restore?.helpInformation()).toContain("--version <id>");
+    expect(trash?.helpInformation()).toContain("--prefix <prefix>");
+  });
+
+  it("passes --version to the restore request", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        key: "notes/a.md",
+        wasDeleted: false,
+        restoredFromVersionId: "old-version",
+        newVersionId: "new-version",
+      }),
+    );
+
+    await buildProgram().parseAsync(
+      ["files", "restore", "notes/a.md", "--version", "old-version", "--yes"],
+      { from: "user" },
+    );
+
+    expect(JSON.parse(String(fetchSpy.mock.calls[1][1]?.body))).toMatchObject({
+      versionId: "old-version",
+    });
+  });
+
+  it("passes --prefix to the trash request", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        personal: true,
+        tombstones: [],
+        truncated: false,
+        computedAt: "2026-07-20T12:00:00.000Z",
+      }),
+    );
+
+    await buildProgram().parseAsync(
+      ["files", "trash", "--personal", "--prefix", "notes/"],
+      { from: "user" },
+    );
+
+    const url = requestedUrl(0);
+    expect(url.searchParams.get("prefix")).toBe("notes/");
+  });
+});