@indigoai-us/hq-cli 5.45.1 → 5.46.0

package/dist/commands/files.d.ts

@@ -41,4 +41,35 @@ export declare class ShareSessionHttpError extends Error {
  */
 export declare function formatShareSessionError(err: ShareSessionHttpError): string;
 export declare function registerFilesCommand(program: Command): Command;
+/** Server response shape for POST /v1/files/delete. */
+export interface FilesDeleteResponse {
+    prefix: string;
+    mode: "exact" | "prefix";
+    dryRun: boolean;
+    matched: number;
+    deleted: number;
+    skipped: number;
+    tombstoned: number;
+    keys: string[];
+    keysTruncated: boolean;
+}
+export declare class FilesDeleteHttpError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/** Map a FilesDeleteHttpError to user-facing copy. */
+export declare function formatFilesDeleteError(err: FilesDeleteHttpError, prefix: string): string;
+/** Injectable yes/no confirmation seam (stubbed in tests). */
+export type ConfirmFn = (message: string) => Promise<boolean>;
+interface RunFilesDeleteParams {
+    prefix: string;
+    dryRun: boolean;
+    yes: boolean;
+    companySlug: string | undefined;
+}
+export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
+    confirm?: ConfirmFn;
+}): Promise<void>;
+export {};
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -1,7 +1,8 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8068c3b8-ee9c-5296-9b49-aa10bf38ccbd")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5f5242f3-b24f-58b0-a3ee-381c42c755fc")}catch(e){}}();
 import chalk from "chalk";
 import open from "open";
+import * as readline from "node:readline";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -328,6 +329,25 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    files
+        .command("delete <prefix>")
+        .description("Delete vault objects under a prefix (bounded + scoped). Always previews the exact count first; prompts for confirmation unless --yes.")
+        .option("--dry-run", "List what WOULD be deleted without deleting anything")
+        .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+        .action(async (prefix, opts) => {
+        try {
+            await runFilesDelete({
+                prefix,
+                dryRun: opts.dryRun === true,
+                yes: opts.yes === true,
+                companySlug: files.opts().company,
+            });
+        }
+        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.
@@ -472,5 +492,160 @@ async function runShareSession(params) {
         console.log(chalk.dim("  --no-open: copy the URL above to share manually."));
     }
 }
+export class FilesDeleteHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "FilesDeleteHttpError";
+    }
+}
+/** Map a FilesDeleteHttpError to user-facing copy. */
+export function formatFilesDeleteError(err, prefix) {
+    if (err.status === 401) {
+        return "Not authenticated — please run `hq login`";
+    }
+    if (err.status === 403) {
+        return `Not authorized to delete '${prefix}' — you need write access on it`;
+    }
+    if (err.status === 400) {
+        return `Invalid request: ${err.message}`;
+    }
+    if (err.status >= 500) {
+        return `Server error: ${err.message}`;
+    }
+    return err.message || `Request failed (${err.status})`;
+}
+function realConfirm(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/**
+ * POST /v1/files/delete. Throws FilesDeleteHttpError on any non-2xx so the one
+ * caller renders a single consistent error path.
+ */
+async function callDeleteEndpoint(params) {
+    const res = await vaultApiFetch({
+        token: params.token,
+        path: "/v1/files/delete",
+        method: "POST",
+        body: {
+            company: params.companyUid,
+            prefix: params.prefix,
+            dryRun: params.dryRun,
+        },
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new FilesDeleteHttpError(res.status, body.message ?? body.error ?? res.statusText, body.code);
+    }
+    return (await res.json());
+}
+/** How many would-delete keys to list before truncating the preview. */
+const DELETE_PREVIEW_KEYS = 20;
+function printKeyPreview(resp) {
+    const shown = resp.keys.slice(0, DELETE_PREVIEW_KEYS);
+    for (const key of shown) {
+        console.log(chalk.dim(`    ${key}`));
+    }
+    const hiddenInList = resp.keys.length - shown.length;
+    if (hiddenInList > 0) {
+        console.log(chalk.dim(`    … and ${hiddenInList} more`));
+    }
+    else if (resp.keysTruncated) {
+        console.log(chalk.dim(`    … and ${resp.matched - resp.keys.length} more`));
+    }
+}
+export async function runFilesDelete(params, deps = {}) {
+    const confirm = deps.confirm ?? realConfirm;
+    // Normalize exactly as the share/unshare/acl paths do (trailing `/` → `/*`),
+    // then reject the root/empty prefix CLIENT-side so a typo never reaches the
+    // server as a vault-wide delete. The server enforces this too (defense in
+    // depth), but failing fast here is clearer and avoids a wasted round-trip.
+    const normalized = normalizeFilePrefix(params.prefix);
+    if (normalized === "" || normalized === "*" || normalized === "/*") {
+        console.error(chalk.red("Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key."));
+        process.exit(1);
+    }
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, params.companySlug);
+    // 1. Always preview first — this is how we print the EXACT key count before
+    //    deleting anything (and the whole behavior of --dry-run).
+    let preview;
+    try {
+        preview = await callDeleteEndpoint({
+            token,
+            companyUid,
+            prefix: normalized,
+            dryRun: true,
+        });
+    }
+    catch (err) {
+        if (err instanceof FilesDeleteHttpError) {
+            console.error(chalk.red(formatFilesDeleteError(err, normalized)));
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (preview.matched === 0) {
+        console.log(chalk.dim(`Nothing to delete under '${normalized}'.`));
+        return;
+    }
+    const noun = preview.matched === 1 ? "object" : "objects";
+    if (params.dryRun) {
+        console.log(chalk.green(`[dry-run] Would delete ${preview.matched} ${noun} under '${normalized}':`));
+        printKeyPreview(preview);
+        if (preview.skipped > 0) {
+            console.log(chalk.dim(`  (${preview.skipped} more under this prefix you can't delete would be left untouched)`));
+        }
+        console.log(chalk.dim("Nothing was deleted (--dry-run)."));
+        return;
+    }
+    // 2. Real delete — show what's about to happen, then confirm.
+    console.log(chalk.yellow(`About to delete ${preview.matched} ${noun} under '${normalized}':`));
+    printKeyPreview(preview);
+    if (preview.skipped > 0) {
+        console.log(chalk.dim(`  (${preview.skipped} more under this prefix you can't delete will be left untouched)`));
+    }
+    if (!params.yes) {
+        const ok = await confirm(`Delete ${preview.matched} ${noun}? This removes them from the shared vault for everyone.`);
+        if (!ok) {
+            console.log(chalk.dim("Aborted — nothing was deleted."));
+            return;
+        }
+    }
+    // 3. Execute the delete.
+    let result;
+    try {
+        result = await callDeleteEndpoint({
+            token,
+            companyUid,
+            prefix: normalized,
+            dryRun: false,
+        });
+    }
+    catch (err) {
+        if (err instanceof FilesDeleteHttpError) {
+            console.error(chalk.red(formatFilesDeleteError(err, normalized)));
+            process.exit(1);
+        }
+        throw err;
+    }
+    const deletedNoun = result.deleted === 1 ? "object" : "objects";
+    console.log(chalk.green(`Deleted ${result.deleted} ${deletedNoun} under '${normalized}'.`));
+    if (result.skipped > 0) {
+        console.log(chalk.dim(`${result.skipped} object(s) under this prefix you can't delete were left untouched.`));
+    }
+}
 //# sourceMappingURL=files.js.map
-//# debugId=8068c3b8-ee9c-5296-9b49-aa10bf38ccbd
+//# debugId=5f5242f3-b24f-58b0-a3ee-381c42c755fc

package/package.json

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

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

@@ -0,0 +1,268 @@
+/**
+ * Unit tests for `hq files delete <prefix>` (files.ts).
+ *
+ * Coverage (mirrors the server-side regression list from the caller's side):
+ *   - --dry-run previews the key set and deletes nothing;
+ *   - a real delete previews the EXACT count, then deletes only after confirm;
+ *   - --yes bypasses the confirmation prompt;
+ *   - a declined confirmation deletes nothing;
+ *   - the root/empty prefix is rejected CLIENT-side before any network call;
+ *   - a 403 from the server is surfaced as a clear "not authorized" message;
+ *   - the request body shape is exactly { company, prefix, dryRun }.
+ *
+ * Mirrors files.test.ts: globalThis.fetch + process.exit are spied; the
+ * `__EXIT__:<code>` throw mimics how Commander aborts on a failure path.
+ */
+
+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 { Command } from "commander";
+import {
+  registerFilesCommand,
+  runFilesDelete,
+  FilesDeleteHttpError,
+  formatFilesDeleteError,
+  type FilesDeleteResponse,
+} from "./files.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/** A membership response so getCompanyUid resolves a single active company. */
+function membershipResponse(): Response {
+  return jsonResponse(200, {
+    memberships: [
+      { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+    ],
+  });
+}
+
+function deleteResponse(overrides: Partial<FilesDeleteResponse>): Response {
+  return jsonResponse(200, {
+    prefix: "reports/*",
+    mode: "prefix",
+    dryRun: false,
+    matched: 0,
+    deleted: 0,
+    skipped: 0,
+    tombstoned: 0,
+    keys: [],
+    keysTruncated: false,
+    ...overrides,
+  });
+}
+
+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");
+  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();
+});
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerFilesCommand(program);
+  return program;
+}
+
+function deleteCalls() {
+  return fetchSpy.mock.calls.filter((c) => String(c[0]).includes("/v1/files/delete"));
+}
+
+function deleteCallBodies(): Array<{ company: string; prefix: string; dryRun: boolean }> {
+  return deleteCalls().map((c) => JSON.parse((c[1]?.body as string) ?? "{}"));
+}
+
+function printed(): string {
+  return logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+}
+function printedErr(): string {
+  return errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+}
+
+describe("hq files delete — --dry-run", () => {
+  it("previews the key set, sends only a dryRun:true request, deletes nothing", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({
+        dryRun: true,
+        matched: 2,
+        keys: ["reports/a.md", "reports/b.md"],
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(["files", "delete", "reports/", "--dry-run"], { from: "user" });
+
+    const bodies = deleteCallBodies();
+    expect(bodies).toHaveLength(1);
+    expect(bodies[0]).toEqual({ company: "cmp_acme", prefix: "reports/*", dryRun: true });
+    expect(printed()).toContain("[dry-run]");
+    expect(printed()).toContain("reports/a.md");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq files delete — real delete with --yes", () => {
+  it("previews then deletes (dryRun:true then dryRun:false), no confirm needed", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 2, keys: ["reports/a.md", "reports/b.md"] }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ matched: 2, deleted: 2, tombstoned: 2, keys: ["reports/a.md", "reports/b.md"] }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(["files", "delete", "reports/*", "--yes"], { from: "user" });
+
+    const bodies = deleteCallBodies();
+    expect(bodies).toHaveLength(2);
+    expect(bodies[0].dryRun).toBe(true); // preview first
+    expect(bodies[1].dryRun).toBe(false); // then the real delete
+    expect(printed()).toContain("Deleted 2");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq files delete — confirmation gating", () => {
+  it("a declined confirmation deletes nothing (no dryRun:false request)", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 3, keys: ["x/a", "x/b", "x/c"] }),
+    );
+
+    await runFilesDelete(
+      { prefix: "x/*", dryRun: false, yes: false, companySlug: undefined },
+      { confirm: async () => false },
+    );
+
+    const bodies = deleteCallBodies();
+    expect(bodies).toHaveLength(1); // only the preview
+    expect(bodies[0].dryRun).toBe(true);
+    expect(printed()).toContain("Aborted");
+  });
+
+  it("an accepted confirmation proceeds with the delete", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 1, keys: ["x/a"] }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ matched: 1, deleted: 1, tombstoned: 1, keys: ["x/a"] }),
+    );
+
+    await runFilesDelete(
+      { prefix: "x/*", dryRun: false, yes: false, companySlug: undefined },
+      { confirm: async () => true },
+    );
+
+    const bodies = deleteCallBodies();
+    expect(bodies).toHaveLength(2);
+    expect(bodies[1].dryRun).toBe(false);
+    expect(printed()).toContain("Deleted 1");
+  });
+
+  it("reports skipped keys (peer files the caller can't delete) in the preview", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 1, skipped: 2, keys: ["x/mine.md"] }),
+    );
+
+    await runFilesDelete(
+      { prefix: "x/*", dryRun: false, yes: false, companySlug: undefined },
+      { confirm: async () => false },
+    );
+
+    expect(printed()).toContain("2 more under this prefix you can't delete");
+  });
+});
+
+describe("hq files delete — nothing to delete", () => {
+  it("prints a no-op message and makes no second request", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(deleteResponse({ dryRun: true, matched: 0, keys: [] }));
+
+    let confirmCalled = false;
+    await runFilesDelete(
+      { prefix: "empty/*", dryRun: false, yes: false, companySlug: undefined },
+      { confirm: async () => { confirmCalled = true; return true; } },
+    );
+
+    expect(deleteCallBodies()).toHaveLength(1);
+    expect(confirmCalled).toBe(false);
+    expect(printed()).toContain("Nothing to delete");
+  });
+});
+
+describe("hq files delete — root/empty prefix rejected client-side", () => {
+  for (const prefix of ["", "*", "/", "/*"]) {
+    it(`rejects ${JSON.stringify(prefix)} before any network call`, async () => {
+      const program = buildProgram();
+      await expect(
+        program.parseAsync(["files", "delete", prefix], { from: "user" }),
+      ).rejects.toThrow(/__EXIT__:1/);
+      expect(fetchSpy).not.toHaveBeenCalled();
+      expect(printedErr()).toContain("Refusing to delete the vault root");
+    });
+  }
+});
+
+describe("hq files delete — server error mapping", () => {
+  it("403 surfaces a clear not-authorized message and exits 1", async () => {
+    fetchSpy.mockResolvedValueOnce(membershipResponse());
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "forbidden", code: "FILES_DELETE_FORBIDDEN" }),
+    );
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "delete", "reports/*"], { from: "user" }),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    expect(printedErr()).toContain("Not authorized to delete 'reports/*'");
+    // Only the preview call happened; no delete was issued.
+    expect(deleteCallBodies()).toHaveLength(1);
+  });
+
+  it("formatFilesDeleteError maps statuses to copy", () => {
+    expect(formatFilesDeleteError(new FilesDeleteHttpError(401, "x"), "p")).toMatch(/hq login/);
+    expect(formatFilesDeleteError(new FilesDeleteHttpError(403, "x"), "p/*")).toMatch(/Not authorized to delete 'p\/\*'/);
+    expect(formatFilesDeleteError(new FilesDeleteHttpError(400, "bad"), "p")).toMatch(/Invalid request: bad/);
+    expect(formatFilesDeleteError(new FilesDeleteHttpError(500, "boom"), "p")).toMatch(/Server error: boom/);
+  });
+});

package/src/commands/files.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import open from "open";
+import * as readline from "node:readline";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
@@ -426,6 +427,35 @@ export function registerFilesCommand(program: Command): Command {
       }
     });
 
+  files
+    .command("delete <prefix>")
+    .description(
+      "Delete vault objects under a prefix (bounded + scoped). Always previews the exact count first; prompts for confirmation unless --yes.",
+    )
+    .option(
+      "--dry-run",
+      "List what WOULD be deleted without deleting anything",
+    )
+    .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+    .action(
+      async (prefix: string, opts: { dryRun?: boolean; yes?: boolean }) => {
+        try {
+          await runFilesDelete({
+            prefix,
+            dryRun: opts.dryRun === true,
+            yes: opts.yes === true,
+            companySlug: files.opts().company as string | undefined,
+          });
+        } 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.
@@ -625,3 +655,248 @@ async function runShareSession(params: RunShareSessionParams): Promise<void> {
     console.log(chalk.dim("  --no-open: copy the URL above to share manually."));
   }
 }
+
+// ---------------------------------------------------------------------------
+// Scoped delete flow — `hq files delete <prefix>`
+//
+// Talks to the bounded server-side delete endpoint (POST /v1/files/delete).
+// The server is the authority on scope + authorization + the actual S3 delete;
+// this command is a careful front door:
+//   1. normalize + reject the root/empty prefix CLIENT-side (defense in depth);
+//   2. ALWAYS run a dry-run first to fetch + print the exact key count;
+//   3. for a real delete, require confirmation unless --yes;
+//   4. NEVER infer scope from local filesystem state.
+// ---------------------------------------------------------------------------
+
+/** Server response shape for POST /v1/files/delete. */
+export interface FilesDeleteResponse {
+  prefix: string;
+  mode: "exact" | "prefix";
+  dryRun: boolean;
+  matched: number;
+  deleted: number;
+  skipped: number;
+  tombstoned: number;
+  keys: string[];
+  keysTruncated: boolean;
+}
+
+export class FilesDeleteHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code?: string,
+  ) {
+    super(message);
+    this.name = "FilesDeleteHttpError";
+  }
+}
+
+/** Map a FilesDeleteHttpError to user-facing copy. */
+export function formatFilesDeleteError(
+  err: FilesDeleteHttpError,
+  prefix: string,
+): string {
+  if (err.status === 401) {
+    return "Not authenticated — please run `hq login`";
+  }
+  if (err.status === 403) {
+    return `Not authorized to delete '${prefix}' — you need write access on it`;
+  }
+  if (err.status === 400) {
+    return `Invalid request: ${err.message}`;
+  }
+  if (err.status >= 500) {
+    return `Server error: ${err.message}`;
+  }
+  return err.message || `Request failed (${err.status})`;
+}
+
+/** Injectable yes/no confirmation seam (stubbed in tests). */
+export type ConfirmFn = (message: string) => Promise<boolean>;
+
+function realConfirm(message: string): Promise<boolean> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+/**
+ * POST /v1/files/delete. Throws FilesDeleteHttpError on any non-2xx so the one
+ * caller renders a single consistent error path.
+ */
+async function callDeleteEndpoint(params: {
+  token: string;
+  companyUid: string;
+  prefix: string;
+  dryRun: boolean;
+}): Promise<FilesDeleteResponse> {
+  const res = await vaultApiFetch({
+    token: params.token,
+    path: "/v1/files/delete",
+    method: "POST",
+    body: {
+      company: params.companyUid,
+      prefix: params.prefix,
+      dryRun: params.dryRun,
+    },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new FilesDeleteHttpError(
+      res.status,
+      body.message ?? body.error ?? res.statusText,
+      body.code,
+    );
+  }
+  return (await res.json()) as FilesDeleteResponse;
+}
+
+interface RunFilesDeleteParams {
+  prefix: string;
+  dryRun: boolean;
+  yes: boolean;
+  companySlug: string | undefined;
+}
+
+/** How many would-delete keys to list before truncating the preview. */
+const DELETE_PREVIEW_KEYS = 20;
+
+function printKeyPreview(resp: FilesDeleteResponse): void {
+  const shown = resp.keys.slice(0, DELETE_PREVIEW_KEYS);
+  for (const key of shown) {
+    console.log(chalk.dim(`    ${key}`));
+  }
+  const hiddenInList = resp.keys.length - shown.length;
+  if (hiddenInList > 0) {
+    console.log(chalk.dim(`    … and ${hiddenInList} more`));
+  } else if (resp.keysTruncated) {
+    console.log(chalk.dim(`    … and ${resp.matched - resp.keys.length} more`));
+  }
+}
+
+export async function runFilesDelete(
+  params: RunFilesDeleteParams,
+  deps: { confirm?: ConfirmFn } = {},
+): Promise<void> {
+  const confirm = deps.confirm ?? realConfirm;
+
+  // Normalize exactly as the share/unshare/acl paths do (trailing `/` → `/*`),
+  // then reject the root/empty prefix CLIENT-side so a typo never reaches the
+  // server as a vault-wide delete. The server enforces this too (defense in
+  // depth), but failing fast here is clearer and avoids a wasted round-trip.
+  const normalized = normalizeFilePrefix(params.prefix);
+  if (normalized === "" || normalized === "*" || normalized === "/*") {
+    console.error(
+      chalk.red(
+        "Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key.",
+      ),
+    );
+    process.exit(1);
+  }
+
+  const token = await ensureCognitoToken();
+  const companyUid = await getCompanyUid(token, params.companySlug);
+
+  // 1. Always preview first — this is how we print the EXACT key count before
+  //    deleting anything (and the whole behavior of --dry-run).
+  let preview: FilesDeleteResponse;
+  try {
+    preview = await callDeleteEndpoint({
+      token,
+      companyUid,
+      prefix: normalized,
+      dryRun: true,
+    });
+  } catch (err) {
+    if (err instanceof FilesDeleteHttpError) {
+      console.error(chalk.red(formatFilesDeleteError(err, normalized)));
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (preview.matched === 0) {
+    console.log(chalk.dim(`Nothing to delete under '${normalized}'.`));
+    return;
+  }
+
+  const noun = preview.matched === 1 ? "object" : "objects";
+
+  if (params.dryRun) {
+    console.log(
+      chalk.green(
+        `[dry-run] Would delete ${preview.matched} ${noun} under '${normalized}':`,
+      ),
+    );
+    printKeyPreview(preview);
+    if (preview.skipped > 0) {
+      console.log(
+        chalk.dim(
+          `  (${preview.skipped} more under this prefix you can't delete would be left untouched)`,
+        ),
+      );
+    }
+    console.log(chalk.dim("Nothing was deleted (--dry-run)."));
+    return;
+  }
+
+  // 2. Real delete — show what's about to happen, then confirm.
+  console.log(
+    chalk.yellow(`About to delete ${preview.matched} ${noun} under '${normalized}':`),
+  );
+  printKeyPreview(preview);
+  if (preview.skipped > 0) {
+    console.log(
+      chalk.dim(
+        `  (${preview.skipped} more under this prefix you can't delete will be left untouched)`,
+      ),
+    );
+  }
+
+  if (!params.yes) {
+    const ok = await confirm(
+      `Delete ${preview.matched} ${noun}? This removes them from the shared vault for everyone.`,
+    );
+    if (!ok) {
+      console.log(chalk.dim("Aborted — nothing was deleted."));
+      return;
+    }
+  }
+
+  // 3. Execute the delete.
+  let result: FilesDeleteResponse;
+  try {
+    result = await callDeleteEndpoint({
+      token,
+      companyUid,
+      prefix: normalized,
+      dryRun: false,
+    });
+  } catch (err) {
+    if (err instanceof FilesDeleteHttpError) {
+      console.error(chalk.red(formatFilesDeleteError(err, normalized)));
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const deletedNoun = result.deleted === 1 ? "object" : "objects";
+  console.log(
+    chalk.green(`Deleted ${result.deleted} ${deletedNoun} under '${normalized}'.`),
+  );
+  if (result.skipped > 0) {
+    console.log(
+      chalk.dim(
+        `${result.skipped} object(s) under this prefix you can't delete were left untouched.`,
+      ),
+    );
+  }
+}