@indigoai-us/hq-cli 5.76.0 → 5.77.1

package/src/commands/files.ts

@@ -512,6 +512,100 @@ export function registerFilesCommand(program: Command): Command {
       },
     );
 
+  files
+    .command("versions <path>")
+    .description(
+      "List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .action(async (path: string, opts: { personal?: boolean }) => {
+      try {
+        const companySlug = files.opts().company as string | undefined;
+        const personal = opts.personal === true;
+        assertRecoveryScope(personal, companySlug);
+        await runFilesVersions({ key: path, personal, companySlug });
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  files
+    .command("restore <path>")
+    .description(
+      "Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .option("--version <id>", "Content version ID to restore")
+    .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
+    .action(
+      async (
+        path: string,
+        opts: { personal?: boolean; yes?: boolean; version?: string },
+      ) => {
+        try {
+          const companySlug = files.opts().company as string | undefined;
+          const personal = opts.personal === true;
+          assertRecoveryScope(personal, companySlug);
+          await runFilesRestore({
+            key: path,
+            versionId: opts.version,
+            yes: opts.yes === true,
+            personal,
+            companySlug,
+          });
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
+  files
+    .command("trash")
+    .description(
+      "List deleted vault keys retained as tombstones. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .option("--prefix <prefix>", "Literal key prefix to filter tombstones")
+    .option("--cursor <cursor>", "Continue from an opaque tombstone cursor")
+    .action(
+      async (opts: { personal?: boolean; prefix?: string; cursor?: string }) => {
+        try {
+          const companySlug = files.opts().company as string | undefined;
+          const personal = opts.personal === true;
+          assertRecoveryScope(personal, companySlug);
+          await runFilesTrash({
+            prefix: opts.prefix ?? "",
+            cursor: opts.cursor,
+            personal,
+            companySlug,
+          });
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
   // Return the `files` Commander group so callers (src/index.ts) can attach
   // additional subcommands (e.g. `hq files browse`/`hq files cat` from
   // files-browse.ts) onto the same group without re-creating it.
@@ -1034,3 +1128,319 @@ export async function runFilesDelete(
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Version history + recovery commands
+// ---------------------------------------------------------------------------
+
+export interface FileVersionRow {
+  versionId: string;
+  isLatest: boolean;
+  lastModified: string;
+  size: number;
+  isDeleteMarker?: boolean;
+}
+
+export interface FilesVersionsResponse {
+  key: string;
+  versions: FileVersionRow[];
+  computedAt: string;
+}
+
+export interface FileTombstoneRow {
+  key: string;
+  deletedAt: string;
+  deletedBy: string;
+  deletedPrefix: string;
+}
+
+export interface FilesTrashResponse {
+  companyUid?: string;
+  personal?: true;
+  tombstones: FileTombstoneRow[];
+  cursor?: string | null;
+  truncated: boolean;
+  computedAt: string;
+}
+
+export interface FilesRestoreResponse {
+  key: string;
+  wasDeleted: boolean;
+  restoredFromVersionId: string;
+  newVersionId: string;
+}
+
+export class FilesRecoveryHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code?: string,
+  ) {
+    super(message);
+    this.name = "FilesRecoveryHttpError";
+  }
+}
+
+function assertRecoveryScope(personal: boolean, companySlug: string | undefined): void {
+  if (personal && companySlug) {
+    throw new Error("Pass either --personal or --company, not both.");
+  }
+}
+
+function assertExactRecoveryKey(key: string): void {
+  if (!key || key.includes("*")) {
+    throw new Error(
+      "Restore and version history require one exact, wildcard-free vault key.",
+    );
+  }
+}
+
+function quoteRecoveryShellArg(value: string): string {
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return String(bytes) + " B";
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KiB";
+  if (bytes < 1024 * 1024 * 1024) {
+    return (bytes / (1024 * 1024)).toFixed(1) + " MiB";
+  }
+  return (bytes / (1024 * 1024 * 1024)).toFixed(1) + " GiB";
+}
+
+/** Render the exact-key version history, including S3 delete markers. */
+export function formatFilesVersionsTable(rows: FileVersionRow[]): string {
+  if (rows.length === 0) {
+    return "No version history exists for that key.";
+  }
+
+  const cols = ["VERSION", "TYPE", "LATEST", "MODIFIED", "SIZE"];
+  const data = rows.map((row) => [
+    row.versionId,
+    row.isDeleteMarker ? "delete marker" : "content",
+    row.isLatest ? "yes" : "",
+    row.lastModified,
+    row.isDeleteMarker ? "—" : formatBytes(row.size),
+  ]);
+  const widths = cols.map((col, index) =>
+    Math.max(col.length, ...data.map((row) => row[index].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+  return [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+    ...data.map(renderRow),
+  ].join("\n");
+}
+
+/** Render durable delete tombstones without implying the objects still exist. */
+export function formatFilesTrashTable(rows: FileTombstoneRow[]): string {
+  if (rows.length === 0) {
+    return "Trash is empty.";
+  }
+
+  const cols = ["KEY", "DELETED", "DELETED BY", "DELETE PREFIX"];
+  const data = rows.map((row) => [
+    row.key,
+    row.deletedAt,
+    row.deletedBy,
+    row.deletedPrefix,
+  ]);
+  const widths = cols.map((col, index) =>
+    Math.max(col.length, ...data.map((row) => row[index].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+  return [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+    ...data.map(renderRow),
+  ].join("\n");
+}
+
+function throwRecoveryHttpError(
+  status: number,
+  body: Record<string, string>,
+  statusText: string,
+): never {
+  throw new FilesRecoveryHttpError(
+    status,
+    body.message ?? body.error ?? statusText,
+    body.code,
+  );
+}
+
+function formatFilesRecoveryError(err: FilesRecoveryHttpError, key?: string): string {
+  if (err.status === 401) {
+    return "Not authenticated — please run hq login";
+  }
+  if (err.status === 403) {
+    return key
+      ? "Not authorized to modify '" + key + "' — you need write access on it"
+      : "Not authorized to view this vault path";
+  }
+  if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
+    return "That version is unavailable or is a delete marker.";
+  }
+  if (err.code === "FILES_RESTORE_NO_PRIOR_VERSION") {
+    return "There is no prior content version to restore.";
+  }
+  if (err.code === "FILES_RESTORE_NO_RECOVERABLE_VERSION") {
+    return "There is no recoverable content version for this key.";
+  }
+  if (err.status === 400) {
+    return "Invalid request: " + err.message;
+  }
+  if (err.status >= 500) {
+    return "Server error: " + err.message;
+  }
+  return err.message || "Request failed (" + String(err.status) + ")";
+}
+
+interface RecoveryScope {
+  token: string;
+  companyUid?: string;
+  personal: boolean;
+}
+
+async function resolveRecoveryScope(params: {
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<RecoveryScope> {
+  assertRecoveryScope(params.personal, params.companySlug);
+  const token = await ensureCognitoToken();
+  if (params.personal) {
+    return { token, personal: true };
+  }
+  return {
+    token,
+    personal: false,
+    companyUid: await getCompanyUid(token, params.companySlug),
+  };
+}
+
+export async function runFilesVersions(params: {
+  key: string;
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<FilesVersionsResponse> {
+  assertExactRecoveryKey(params.key);
+  const scope = await resolveRecoveryScope(params);
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/versions",
+    query: scope.personal
+      ? { personal: "1", key: params.key }
+      : { company: scope.companyUid!, key: params.key },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throwRecoveryHttpError(res.status, body, res.statusText);
+  }
+  const data = (await res.json()) as FilesVersionsResponse;
+  console.log(chalk.green("Versions for '" + data.key + "':"));
+  console.log(formatFilesVersionsTable(data.versions));
+  return data;
+}
+
+export async function runFilesRestore(
+  params: {
+    key: string;
+    versionId?: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+  },
+  deps: { confirm?: ConfirmFn } = {},
+): Promise<FilesRestoreResponse | undefined> {
+  assertExactRecoveryKey(params.key);
+  if (params.versionId !== undefined && params.versionId.trim() === "") {
+    throw new Error("versionId must not be empty.");
+  }
+
+  const confirm = deps.confirm ?? realConfirm;
+  if (!params.yes) {
+    const ok = await confirm(
+      params.personal
+        ? "Restore '" + params.key + "' in your personal vault? This overwrites current content."
+        : "Restore '" + params.key + "'? This overwrites current content in the shared vault.",
+    );
+    if (!ok) {
+      console.log(chalk.dim("Aborted — nothing was restored."));
+      return undefined;
+    }
+  }
+
+  const scope = await resolveRecoveryScope(params);
+  const body: Record<string, unknown> = scope.personal
+    ? { personal: true, key: params.key }
+    : { company: scope.companyUid, key: params.key };
+  if (params.versionId !== undefined) body.versionId = params.versionId;
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/restore",
+    method: "POST",
+    body,
+  });
+  if (!res.ok) {
+    const errBody = (await res.json().catch(() => ({}))) as Record<string, string>;
+    const err = new FilesRecoveryHttpError(
+      res.status,
+      errBody.message ?? errBody.error ?? res.statusText,
+      errBody.code,
+    );
+    throw new Error(formatFilesRecoveryError(err, params.key));
+  }
+  const data = (await res.json()) as FilesRestoreResponse;
+  const verb = data.wasDeleted ? "Undeleted" : "Restored";
+  console.log(
+    chalk.green(
+      verb + " '" + data.key + "' from version '" + data.restoredFromVersionId + "'.",
+    ),
+  );
+  console.log(chalk.dim("New version: " + data.newVersionId));
+  return data;
+}
+
+export async function runFilesTrash(params: {
+  prefix: string;
+  cursor?: string;
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<FilesTrashResponse> {
+  if (params.prefix.includes("*")) {
+    throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");
+  }
+  const scope = await resolveRecoveryScope(params);
+  const query: Record<string, string> = scope.personal
+    ? { personal: "1" }
+    : { company: scope.companyUid! };
+  if (params.prefix) query.prefix = params.prefix;
+  if (params.cursor) query.cursor = params.cursor;
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/tombstones",
+    query,
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throwRecoveryHttpError(res.status, body, res.statusText);
+  }
+  const data = (await res.json()) as FilesTrashResponse;
+  console.log(formatFilesTrashTable(data.tombstones));
+  if (data.truncated && data.cursor) {
+    let continuation = "hq files";
+    if (params.companySlug) {
+      continuation += " --company " + quoteRecoveryShellArg(params.companySlug);
+    }
+    continuation += " trash";
+    if (params.personal) continuation += " --personal";
+    if (params.prefix) {
+      continuation += " --prefix " + quoteRecoveryShellArg(params.prefix);
+    }
+    continuation += " --cursor " + quoteRecoveryShellArg(data.cursor);
+    console.log(chalk.dim("More results: " + continuation));
+  }
+  return data;
+}

package/src/commands/outposts.test.ts

@@ -365,6 +365,43 @@ describe("hq outposts provision (billing gate)", () => {
     const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
     expect(printed).toContain("https://checkout.stripe.com/outpost");
   });
+
+  it("surfaces the DECLINE reason on 402 payment_failed — never the 'No card on file' copy", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    // hq-pro's payment_failed envelope: a card EXISTS and was declined. The
+    // server's `message` carries the friendly decline copy; telling this user
+    // "No card on file" sends them down the wrong remediation path entirely.
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          message: "Your card was declined. Try a different card or contact your bank.",
+          billing: {
+            status: "payment_failed",
+            setup: {
+              payerType: "person",
+              path: "/v1/billing/checkout/person",
+              method: "POST",
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/update-card" }),
+      );
+
+    await expect(run(["outposts", "provision", "--yes"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+
+    const printed = [...errSpy.mock.calls, ...logSpy.mock.calls]
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toContain("declined");
+    expect(printed).not.toContain("No card on file");
+    // The card-capture link still surfaces — as the way to UPDATE the card.
+    expect(printed).toContain("https://checkout.stripe.com/update-card");
+  });
 });
 
 describe("hq outposts exec", () => {

package/src/commands/outposts.ts

@@ -37,7 +37,7 @@ import {
   OUTPOST_PRICE_CENTS,
   confirmChargeOrExit,
   parseBillingPayload,
-  surfaceBillingRequired,
+  surfaceBillingBlocked,
   type BillingErrorPayload,
 } from "../utils/billing-gate.js";
 
@@ -1288,7 +1288,7 @@ export function registerOutpostsCommand(
             err.status === 402 &&
             err.billing
           ) {
-            await surfaceBillingRequired(token, err.billing);
+            await surfaceBillingBlocked(token, err.billing, err.message);
             process.exit(1);
           }
           // Already at the per-person cap → say so and name the box they own,

package/src/main.ts

@@ -75,6 +75,10 @@ import {
 } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { settleWithin } from "./utils/settle-with-timeout.js";
+
+/** Hard upper bound for non-user-visible release-health finalization. */
+const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
 // the pipe early. This covers the ASYNC path — an 'error' event emitted on the
@@ -351,6 +355,13 @@ export async function runCli(): Promise<void> {
   } finally {
     // Release health: finalize the per-run session before the flush.
     Sentry.endSession();
-    await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
+    // Neither task may turn a successful command into Node's
+    // `unsettled top-level await` exit. They are observability-only after the
+    // command has completed, so a bounded best-effort wait is the terminal
+    // lifecycle boundary for this invocation.
+    await settleWithin(
+      [refreshVersionCache(), Sentry.flush(2000)],
+      RELEASE_HEALTH_SETTLE_TIMEOUT_MS,
+    );
   }
 }

package/src/utils/billing-gate.ts

@@ -180,3 +180,49 @@ export async function surfaceBillingRequired(
   console.log(chalk.dim("Once a card is added, re-run the same command."));
   return url;
 }
+
+/**
+ * Status-aware surface for a 402 billing block. hq-pro's envelope carries two
+ * distinct remediations that must never be conflated (mirroring the server's
+ * own P1-C classification):
+ *   - `payment_failed`   — a card EXISTS and the charge was DECLINED. The
+ *     server's `message` already carries the friendly decline copy ("Your
+ *     card was declined…", "insufficient funds", …). Telling this user
+ *     "No card on file" sends them down the wrong remediation path entirely
+ *     (observed live 2026-07-20: a declined $80 Outpost proration surfaced
+ *     as "no card", triggering a hunt for a missing card that existed).
+ *     The capture link still surfaces — as the way to UPDATE the card.
+ *   - anything else (`billing_required`) — genuinely no usable card on
+ *     file; the existing add-a-card copy is correct.
+ */
+export async function surfaceBillingBlocked(
+  token: string,
+  billing: BillingErrorPayload,
+  serverMessage?: string,
+): Promise<string | null> {
+  if (billing.status !== "payment_failed") {
+    return surfaceBillingRequired(token, billing);
+  }
+  console.error(
+    chalk.yellow(
+      serverMessage?.trim() ||
+        "Your payment failed. Try a different card or contact your bank.",
+    ),
+  );
+  if (!billing.setup) return null;
+  try {
+    const url = await mintPaymentLink(token, billing.setup);
+    console.log(
+      "Update or replace the card here (safe to share with whoever owns billing):\n  " +
+        chalk.cyan(url),
+    );
+    console.log(
+      chalk.dim("Once the payment method is sorted, re-run the same command."),
+    );
+    return url;
+  } catch {
+    // Link minting is best-effort on the decline path — the decline reason
+    // above is the essential part; the console billing page also works.
+    return null;
+  }
+}

package/src/utils/settle-with-timeout.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { settleWithin } from "./settle-with-timeout.js";
+
+describe("settleWithin", () => {
+  it("settles normally when all finalizers finish", async () => {
+    await expect(settleWithin([Promise.resolve(), Promise.reject(new Error("ignored"))], 100))
+      .resolves.toBe("settled");
+  });
+
+  it("settles the caller when a best-effort finalizer never resolves", async () => {
+    vi.useFakeTimers();
+    try {
+      const result = settleWithin([new Promise<void>(() => {})], 1_000);
+      await vi.advanceTimersByTimeAsync(1_000);
+      await expect(result).resolves.toBe("timed_out");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/utils/settle-with-timeout.ts

@@ -0,0 +1,22 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export async function settleWithin(
+  promises: readonly Promise<unknown>[],
+  timeoutMs: number,
+): Promise<"settled" | "timed_out"> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<"timed_out">((resolve) => {
+    timer = setTimeout(() => resolve("timed_out"), timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      Promise.allSettled(promises).then(() => "settled" as const),
+      timedOut,
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/utils/vault-api.test.ts

@@ -8,6 +8,7 @@ import { Sentry } from '../sentry.js';
 import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
 import { isAuthError } from './auth-error.js';
 import { isCompanySelectionError } from './company-selection-error.js';
+import { isExpectedUserError } from './expected-cli-error.js';
 
 const fetchMock = vi.fn();
 const originalFetch = globalThis.fetch;
@@ -142,6 +143,19 @@ describe('getEntityUid', () => {
     expect(fetchMock.mock.calls[1][0]).toMatch(/\/entity\/by-slug\/company\/acme/);
   });
 
+  it('classifies a global by-slug entity miss as an expected user error (HQ-CLI-8)', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(mockResponse(404, { error: 'Entity not found' }));
+
+    const err = await getEntityUid('tok', { companySlug: 'missing-co' }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(isExpectedUserError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/Company slug 'missing-co' was not found/);
+  });
+
   it('on residual global ambiguity (not in namespace) gives actionable --company <uid> guidance', async () => {
     // Caller belongs to no "acme"; the slug matches multiple strangers'
     // companies. The server 409s with the colliding uids and the CLI must tell

package/src/utils/vault-api.ts

@@ -217,6 +217,14 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
           body.uids.map((u) => `  --company ${u}`).join('\n'),
       );
     }
+    if (res.status === 404 && body.error === "Entity not found") {
+      throw Object.assign(
+        new Error(
+          `Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`,
+        ),
+        { expected: true as const },
+      );
+    }
     throw new Error(
       `Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`,
     );