@indigoai-us/hq-cli 5.76.0 → 5.77.0

package/dist/commands/agents.js

@@ -25,7 +25,7 @@ import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
     "minimal",
@@ -64,7 +64,12 @@ export async function agentsRequest(opts) {
     const res = await vaultApiFetch(opts);
     if (!res.ok) {
         const body = (await res.json().catch(() => ({})));
-        throw new AgentsHttpError(res.status, body.error ?? body.message ?? res.statusText, body.code, parseBillingPayload(body));
+        throw new AgentsHttpError(res.status, 
+        // `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));
     }
     return (await res.json());
 }
@@ -371,7 +376,7 @@ export function registerAgentsCommand(program) {
                 if (err instanceof AgentsHttpError &&
                     err.status === 402 &&
                     err.billing) {
-                    await surfaceBillingRequired(token, err.billing);
+                    await surfaceBillingBlocked(token, err.billing, err.message);
                     process.exit(1);
                 }
                 throw err;

package/dist/commands/files.d.ts

@@ -92,5 +92,66 @@ export declare function stripRedundantCompanyScope(prefix: string): {
 export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
     confirm?: ConfirmFn;
 }): Promise<void>;
+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 declare class FilesRecoveryHttpError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/** Render the exact-key version history, including S3 delete markers. */
+export declare function formatFilesVersionsTable(rows: FileVersionRow[]): string;
+/** Render durable delete tombstones without implying the objects still exist. */
+export declare function formatFilesTrashTable(rows: FileTombstoneRow[]): string;
+export declare function runFilesVersions(params: {
+    key: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesVersionsResponse>;
+export declare function runFilesRestore(params: {
+    key: string;
+    versionId?: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+}, deps?: {
+    confirm?: ConfirmFn;
+}): Promise<FilesRestoreResponse | undefined>;
+export declare function runFilesTrash(params: {
+    prefix: string;
+    cursor?: string;
+    personal: boolean;
+    companySlug: string | undefined;
+}): Promise<FilesTrashResponse>;
 export {};
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -379,6 +379,69 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    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, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            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, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            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) => {
+        try {
+            const companySlug = files.opts().company;
+            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.
@@ -737,4 +800,215 @@ export async function runFilesDelete(params, deps = {}) {
         console.log(chalk.dim(`${result.skipped} object(s) under this prefix you can't delete were left untouched.`));
     }
 }
+export class FilesRecoveryHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FilesRecoveryHttpError";
+    }
+}
+function assertRecoveryScope(personal, companySlug) {
+    if (personal && companySlug) {
+        throw new Error("Pass either --personal or --company, not both.");
+    }
+}
+function assertExactRecoveryKey(key) {
+    if (!key || key.includes("*")) {
+        throw new Error("Restore and version history require one exact, wildcard-free vault key.");
+    }
+}
+function quoteRecoveryShellArg(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function formatBytes(bytes) {
+    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) {
+    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) => 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) {
+    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) => 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, body, statusText) {
+    throw new FilesRecoveryHttpError(status, body.message ?? body.error ?? statusText, body.code);
+}
+function formatFilesRecoveryError(err, key) {
+    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) + ")";
+}
+async function resolveRecoveryScope(params) {
+    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) {
+    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(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    console.log(chalk.green("Versions for '" + data.key + "':"));
+    console.log(formatFilesVersionsTable(data.versions));
+    return data;
+}
+export async function runFilesRestore(params, deps = {}) {
+    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 = 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(() => ({})));
+        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());
+    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) {
+    if (params.prefix.includes("*")) {
+        throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");
+    }
+    const scope = await resolveRecoveryScope(params);
+    const query = 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(() => ({})));
+        throwRecoveryHttpError(res.status, body, res.statusText);
+    }
+    const data = (await res.json());
+    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;
+}
 //# sourceMappingURL=files.js.map

package/dist/commands/outposts.js

@@ -31,7 +31,7 @@ import * as yaml from "js-yaml";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
+import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
 export function parseCappedPayload(body) {
     if (!body || typeof body !== "object")
@@ -825,7 +825,7 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 if (err instanceof OutpostHttpError &&
                     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/dist/utils/billing-gate.d.ts

@@ -74,4 +74,19 @@ export declare function mintPaymentLink(token: string, setup: BillingSetupAction
  * to act on. Never prints tokens or secrets.
  */
 export declare function surfaceBillingRequired(token: string, billing: BillingErrorPayload): Promise<string | null>;
+/**
+ * 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 declare function surfaceBillingBlocked(token: string, billing: BillingErrorPayload, serverMessage?: string): Promise<string | null>;
 //# sourceMappingURL=billing-gate.d.ts.map

package/dist/utils/billing-gate.js

@@ -121,4 +121,39 @@ export async function surfaceBillingRequired(token, billing) {
     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, billing, serverMessage) {
+    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;
+    }
+}
 //# sourceMappingURL=billing-gate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.76.0",
+  "version": "5.77.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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;