@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/files.ts

@@ -1,1446 +0,0 @@
-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";
-
-// ---------------------------------------------------------------------------
-// Pure helpers (exported for unit tests)
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
- * milliseconds. Returns null on parse failure. Mirrors the parser used in
- * `secrets generate-link` but kept local so files.ts can be tested in
- * isolation without importing the much larger secrets command surface.
- */
-export function parseDuration(input: string): number | null {
-  const match = input.match(/^(\d+)(m|h|d)$/);
-  if (!match) return null;
-  const value = parseInt(match[1], 10);
-  const unit = match[2];
-  if (unit === "m") return value * 60 * 1000;
-  if (unit === "h") return value * 60 * 60 * 1000;
-  if (unit === "d") return value * 24 * 60 * 60 * 1000;
-  return null;
-}
-
-/** PRD upper bound on browser-launch share-session expiry. */
-export const MAX_SHARE_SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24h
-
-export interface ShareSessionResponse {
-  url: string;
-  token?: string;
-  expiresAt: string;
-  nonce?: string;
-  paths?: string[];
-  maxPermissionByPath?: Record<string, string>;
-}
-
-export interface MintShareSessionParams {
-  token: string;
-  companyUid: string;
-  paths: string[];
-  expiresInMs?: number;
-}
-
-/**
- * POST /files/{companyUid}/share-session — mint a browser-launch share
- * session token. Returns the parsed response. Throws ShareSessionHttpError
- * with a status + actionable message for any non-2xx so callers can render
- * a single consistent error path.
- */
-export async function mintShareSession(
-  params: MintShareSessionParams,
-): Promise<ShareSessionResponse> {
-  const body: Record<string, unknown> = { paths: params.paths };
-  if (params.expiresInMs != null) body.expiresInMs = params.expiresInMs;
-
-  const res = await vaultApiFetch({
-    token: params.token,
-    path: `/files/${encodeURIComponent(params.companyUid)}/share-session`,
-    method: "POST",
-    body,
-  });
-
-  if (!res.ok) {
-    const errBody = (await res.json().catch(() => ({}))) as Record<
-      string,
-      string
-    >;
-    throw new ShareSessionHttpError(
-      res.status,
-      errBody.message ?? errBody.error ?? res.statusText,
-      errBody.path,
-    );
-  }
-
-  return (await res.json()) as ShareSessionResponse;
-}
-
-export class ShareSessionHttpError extends Error {
-  constructor(
-    public readonly status: number,
-    message: string,
-    public readonly path?: string,
-  ) {
-    super(message);
-    this.name = "ShareSessionHttpError";
-  }
-}
-
-/**
- * Map a ShareSessionHttpError to user-facing copy. Centralizes the
- * status → message mapping so the share command and any future caller
- * stay in sync.
- */
-export function formatShareSessionError(err: ShareSessionHttpError): string {
-  if (err.status === 401) {
-    return "Not authenticated — please run `hq login`";
-  }
-  if (err.status === 403) {
-    if (err.path) {
-      return `Not authorized to share '${err.path}' — you need read access on every path`;
-    }
-    return "Not authorized — you need to be a company member with read access on every path";
-  }
-  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})`;
-}
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerFilesCommand(program: Command): Command {
-  const files = program
-    .command("files")
-    .description("Manage file access controls in HQ vault")
-    .option("--company <slug>", "Company slug (resolves to companyUid)");
-
-  files
-    .command("share [paths...]")
-    .description(
-      "Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.",
-    )
-    .option(
-      "--with <principal>",
-      "Email address, group id, or '@all' to share with every active company member",
-    )
-    .option("--permission <level>", "Permission level (only with --with): read | write")
-    .option(
-      "--full",
-      "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.",
-    )
-    .option(
-      "--expires <duration>",
-      "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.",
-    )
-    .option("--no-open", "Print the share-session URL but do not launch the browser")
-    .action(
-      async (
-        paths: string[],
-        opts: {
-          with?: string;
-          permission?: string;
-          full?: boolean;
-          expires?: string;
-          open: boolean;
-        },
-      ) => {
-        try {
-          // Full-vault grant: a glob-safe affordance for "give this person the
-          // whole vault" so admins never have to quote a `*` (an unquoted glob
-          // expands to local filenames and instantly fails the one-prefix
-          // check). Maps to the single `*` wildcard grant, which the server
-          // coalesces to one policy entry — sidestepping the per-prefix STS
-          // session-policy budget. Defaults to write permission.
-          if (opts.full) {
-            if (opts.with === undefined) {
-              console.error(
-                chalk.red(
-                  "--full grants whole-vault access to a principal and requires --with <principal>.",
-                ),
-              );
-              process.exit(1);
-            }
-            if (paths && paths.length > 0) {
-              console.error(
-                chalk.red(
-                  "--full grants the entire vault; do not also pass file paths.",
-                ),
-              );
-              process.exit(1);
-            }
-            await runDirectGrant({
-              prefix: "*",
-              principal: opts.with,
-              permission: opts.permission ?? "write",
-              companySlug: files.opts().company as string | undefined,
-              fullVault: true,
-            });
-            return;
-          }
-
-          if (!paths || paths.length === 0) {
-            console.error(
-              chalk.red("usage: hq files share <paths...> [--with <principal>]"),
-            );
-            process.exit(1);
-          }
-
-          // Fork: --with present → existing direct-grant path. No --with →
-          // browser-launch share-session path. Per PRD, the direct-grant
-          // path is unchanged from US-001 and operates on a single prefix.
-          if (opts.with !== undefined) {
-            if (paths.length !== 1) {
-              console.error(
-                chalk.red(
-                  "Direct grant (--with) takes exactly one prefix. Pass multiple paths only when minting a share-session URL.",
-                ),
-              );
-              process.exit(1);
-            }
-            await runDirectGrant({
-              prefix: paths[0],
-              principal: opts.with,
-              permission: opts.permission,
-              companySlug: files.opts().company as string | undefined,
-            });
-            return;
-          }
-
-          await runShareSession({
-            paths,
-            expires: opts.expires,
-            launchBrowser: opts.open,
-            companySlug: files.opts().company as string | undefined,
-          });
-        } catch (err) {
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  files
-    .command("unshare <prefix>")
-    .description("Remove a file access grant")
-    .requiredOption(
-      "--with <principal>",
-      "Email address, group id, or '@all' to remove the company-wide grant",
-    )
-    .action(async (prefix: string, opts: { with: string }) => {
-      try {
-        const canonicalPrefix = normalizeFilePrefix(prefix);
-
-        const principal = opts.with;
-        const isAll = principal === "@all";
-        const isEmail = !isAll && EMAIL_PATTERN.test(principal);
-        const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
-        if (!isAll && !isEmail && !isGroup) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
-          process.exit(1);
-        }
-        const granteeType = isAll
-          ? "company-wide"
-          : isEmail
-            ? "email"
-            : "group";
-        const granteeId = isAll
-          ? ""
-          : isEmail
-            ? principal.trim().toLowerCase()
-            : principal;
-        const principalLabel = isAll ? "everyone in the company" : granteeId;
-
-        const token = await ensureCognitoToken();
-        const companySlug = files.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
-
-        const res = await vaultApiFetch({
-          token,
-          path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
-          method: "POST",
-          body: { prefix: canonicalPrefix, granteeType, granteeId },
-        });
-
-        if (!res.ok) {
-          const body = await res.json().catch(() => ({})) as Record<string, string>;
-          if (res.status === 401) {
-            console.error(chalk.red("Not authenticated — please run `hq login`"));
-          } else if (res.status === 403) {
-            console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
-          } else if (res.status === 404) {
-            // A 404 means ZERO rows were removed — never report a green success
-            // that implies a revoke happened. Distinguish the two causes:
-            //   ACL_NOT_FOUND  — the prefix has no ACL at all (nothing was ever
-            //                    shared here): genuinely, benignly absent.
-            //   GRANT_NOT_FOUND (or an older server with no code) — the ACL
-            //                    exists but no grant matched this principal:
-            //                    surface it as a warning so a typo'd/stale
-            //                    principal isn't mistaken for a real removal.
-            if (body.code === "ACL_NOT_FOUND") {
-              console.log(
-                chalk.dim(`Nothing to remove — '${canonicalPrefix}' has no sharing grants.`),
-              );
-            } else {
-              console.warn(
-                chalk.yellow(
-                  `No matching grant for ${principalLabel} on '${canonicalPrefix}' — nothing was removed.`,
-                ),
-              );
-            }
-            return;
-          } else if (res.status >= 500) {
-            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
-          } else {
-            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
-          }
-          process.exit(1);
-        }
-
-        console.log(chalk.green(`Removed grant for ${principalLabel} on '${canonicalPrefix}'`));
-      } catch (err) {
-        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  files
-    .command("acl <prefix>")
-    .description("Show the ACL (access control list) for a file prefix")
-    .action(async (prefix: string) => {
-      try {
-        const canonicalPrefix = normalizeFilePrefix(prefix);
-
-        const token = await ensureCognitoToken();
-        const companySlug = files.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
-
-        // `/acl/tree` carries the prefix's own row metadata (directRow) and the
-        // caller's effectivePermission alongside direct/inherited/children, so
-        // a single request returns everything the "files acl" view needs.
-        const treeRes = await vaultApiFetch({
-          token,
-          path: `/files/${encodeURIComponent(companyUid)}/acl/tree`,
-          query: { prefix: canonicalPrefix },
-        });
-
-        if (!treeRes.ok) {
-          const body = (await treeRes.json().catch(() => ({}))) as Record<string, string>;
-          if (treeRes.status === 401) {
-            console.error(chalk.red("Not authenticated — please run `hq login`"));
-          } else if (treeRes.status === 403) {
-            console.error(chalk.red("Not authorized to view this file prefix's ACL"));
-          } else if (treeRes.status >= 500) {
-            console.error(chalk.red(`Server error: ${body.error ?? treeRes.statusText}`));
-          } else {
-            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
-          }
-          process.exit(1);
-        }
-
-        type AclEntry = {
-          granteeType: string;
-          granteeId: string;
-          permission: string;
-          grantedBy: string;
-          grantedAt: string;
-        };
-        type TreeResponse = {
-          prefix: string;
-          direct: AclEntry[];
-          inherited: Array<AclEntry & { sourcePrefix: string }>;
-          children: Array<AclEntry & { sourcePrefix: string }>;
-          directRow: {
-            creatorUid: string;
-            open: boolean;
-            createdAt: string;
-            updatedAt: string;
-          } | null;
-          effectivePermission: string | null;
-        };
-
-        const tree = (await treeRes.json()) as TreeResponse;
-        const row = tree.directRow;
-
-        // No own row AND nothing inherited or granted below — preserve the
-        // original "no ACL record" exit path.
-        if (!row && tree.inherited.length === 0 && tree.children.length === 0) {
-          console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
-          process.exit(1);
-        }
-
-        const aclStatus = row?.open ? "open" : "restricted";
-
-        console.log(chalk.green(`ACL for ${tree.prefix} (${aclStatus})`));
-        if (row) {
-          console.log(`Creator: ${row.creatorUid}`);
-        } else {
-          console.log(chalk.gray(
-            "No direct ACL row — access flows from the inherited/descendant grants below.",
-          ));
-        }
-        if (tree.effectivePermission) {
-          console.log(`Your effective permission: ${tree.effectivePermission}`);
-        }
-
-        // Display labels for grantee identifiers — `company-wide` entries
-        // store `granteeId === ""` on the wire, but a blank cell is confusing
-        // in tabular output, so we render a human-readable phrase instead.
-        function displayGrantee(e: { granteeType: string; granteeId: string }): string {
-          if (e.granteeType === "company-wide") return "Everyone in company";
-          return e.granteeId;
-        }
-
-        function printEntryTable(
-          rows: Array<AclEntry & { sourcePrefix?: string }>,
-          showSource: boolean,
-        ): void {
-          const TYPE_W = Math.max(4, ...rows.map((e) => e.granteeType.length));
-          const GRANTEE_W = Math.max(7, ...rows.map((e) => displayGrantee(e).length));
-          const PERM_W = Math.max(10, ...rows.map((e) => e.permission.length));
-          const BY_W = Math.max(10, ...rows.map((e) => e.grantedBy.length));
-          const SRC_W = showSource
-            ? Math.max(6, ...rows.map((e) => (e.sourcePrefix ?? "").length))
-            : 0;
-          const headerCols = [
-            "TYPE".padEnd(TYPE_W),
-            "GRANTEE".padEnd(GRANTEE_W),
-            "PERMISSION".padEnd(PERM_W),
-            "GRANTED_BY".padEnd(BY_W),
-            "GRANTED_AT",
-          ];
-          if (showSource) headerCols.splice(4, 0, "SOURCE".padEnd(SRC_W));
-          console.log(chalk.bold(headerCols.join("  ")));
-          for (const e of rows) {
-            const grantedAt = e.grantedAt.slice(0, 10);
-            const cols = [
-              e.granteeType.padEnd(TYPE_W),
-              displayGrantee(e).padEnd(GRANTEE_W),
-              e.permission.padEnd(PERM_W),
-              e.grantedBy.padEnd(BY_W),
-              grantedAt,
-            ];
-            if (showSource) cols.splice(4, 0, (e.sourcePrefix ?? "").padEnd(SRC_W));
-            console.log(cols.join("  "));
-          }
-        }
-
-        const directEntries = tree.direct;
-        if (directEntries.length === 0) {
-          if (row?.open) {
-            console.log(chalk.gray("Open ACL — all active members have read access."));
-          } else if (row) {
-            console.log(chalk.gray("No explicit grants on this prefix — only creator has access."));
-          }
-        } else {
-          console.log("\nDirect entries (granted on this prefix):");
-          printEntryTable(directEntries, false);
-        }
-
-        if (tree.inherited.length > 0) {
-          console.log("\nInherited (granted on an ancestor prefix):");
-          printEntryTable(tree.inherited, true);
-        }
-
-        if (tree.children.length > 0) {
-          console.log("\nGranted on descendant prefixes (do not affect this prefix's access):");
-          printEntryTable(tree.children, true);
-        }
-      } catch (err) {
-        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-        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. Use --personal to target your own personal vault instead of a company.",
-    )
-    .option(
-      "--dry-run",
-      "List what WOULD be deleted without deleting anything",
-    )
-    .option(
-      "--personal",
-      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
-    )
-    .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
-    .action(
-      async (
-        prefix: string,
-        opts: { dryRun?: boolean; yes?: boolean; personal?: boolean },
-      ) => {
-        try {
-          const companySlug = files.opts().company as string | undefined;
-          const personal = opts.personal === true;
-          if (personal && companySlug) {
-            console.error(
-              chalk.red(
-                "Pass either --personal or --company, not both.",
-              ),
-            );
-            process.exit(1);
-          }
-          await runFilesDelete({
-            prefix,
-            dryRun: opts.dryRun === true,
-            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("versions <path>")
-    .description(
-      "List prior content versions and delete markers for one exact vault key. Restore a listed version with restore --version-id <id>. 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 with --version-id 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 <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; versionId?: string },
-      ) => {
-        try {
-          const companySlug = files.opts().company as string | undefined;
-          const personal = opts.personal === true;
-          assertRecoveryScope(personal, companySlug);
-          await runFilesRestore({
-            key: path,
-            versionId: opts.versionId,
-            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.
-  return files;
-}
-
-// ---------------------------------------------------------------------------
-// Direct-grant flow (existing US-001 behavior, refactored out of the action
-// closure so the new share-session fork stays readable). Behavior unchanged.
-// ---------------------------------------------------------------------------
-
-interface DirectGrantParams {
-  prefix: string;
-  principal: string;
-  permission: string | undefined;
-  companySlug: string | undefined;
-  /**
-   * Set by the `--full` affordance: the grant targets the whole vault (the
-   * `*` wildcard prefix). Only affects the success message wording — the
-   * request shape is identical to any other prefix grant.
-   */
-  fullVault?: boolean;
-}
-
-async function runDirectGrant(params: DirectGrantParams): Promise<void> {
-  const canonicalPrefix = normalizeFilePrefix(params.prefix);
-
-  if (!params.permission) {
-    console.error(
-      chalk.red("--permission is required when --with is set (read | write)"),
-    );
-    process.exit(1);
-  }
-  if (!["read", "write"].includes(params.permission)) {
-    console.error(
-      chalk.red(`Invalid permission '${params.permission}': must be one of read, write`),
-    );
-    process.exit(1);
-  }
-
-  const principal = params.principal;
-  // `@all` is the company-wide sentinel — maps to a single typed
-  // 'company-wide' ACL entry whose applicability is computed at resolve
-  // time from the active-member list. We send granteeId as the empty
-  // string to match the canonical storage form on the server.
-  const isAll = principal === "@all";
-  const isEmail = !isAll && EMAIL_PATTERN.test(principal);
-  const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
-  if (!isAll && !isEmail && !isGroup) {
-    console.error(
-      chalk.red(
-        `Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`,
-      ),
-    );
-    process.exit(1);
-  }
-  const granteeType = isAll ? "company-wide" : isEmail ? "email" : "group";
-  const granteeId = isAll
-    ? ""
-    : isEmail
-      ? principal.trim().toLowerCase()
-      : principal;
-  // Display label used in success messages — `@all` reads better than `""`.
-  const principalLabel = isAll ? "everyone in the company" : granteeId;
-
-  const token = await ensureCognitoToken();
-  const companyUid = await getCompanyUid(token, params.companySlug);
-
-  let res = await vaultApiFetch({
-    token,
-    path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
-    method: "POST",
-    body: {
-      prefix: canonicalPrefix,
-      granteeType,
-      granteeId,
-      permission: params.permission,
-    },
-  });
-
-  // No ACL row exists yet for this prefix. Auto-create one with this
-  // grant as its first entry, then report success — saves the caller
-  // from needing a separate "create" step.
-  let autoCreated = false;
-  if (res.status === 404) {
-    res = await vaultApiFetch({
-      token,
-      path: `/files/${encodeURIComponent(companyUid)}/acl`,
-      method: "POST",
-      body: {
-        prefix: canonicalPrefix,
-        entries: [{ granteeType, granteeId, permission: params.permission }],
-      },
-    });
-    autoCreated = res.ok;
-  }
-
-  if (!res.ok) {
-    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
-    if (res.status === 401) {
-      console.error(chalk.red("Not authenticated — please run `hq login`"));
-    } else if (res.status === 403) {
-      console.error(chalk.red("Not authorized to share this file prefix"));
-    } else if (res.status === 404) {
-      console.error(
-        chalk.red("ACL record not found — the prefix may not have an ACL yet"),
-      );
-    } else if (res.status === 409) {
-      console.error(chalk.red("Concurrent modification — please retry"));
-    } else if (res.status >= 500) {
-      console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
-    } else {
-      console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
-    }
-    process.exit(1);
-  }
-
-  const data = (await res.json()) as {
-    acl?: { path?: string; prefix?: string };
-  };
-  const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
-  const verb = autoCreated ? "Created ACL and granted" : "Granted";
-  if (params.fullVault) {
-    console.log(
-      chalk.green(
-        `${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`,
-      ),
-    );
-  } else {
-    console.log(
-      chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Share-session (browser-launch) flow — net-new for US-006
-// ---------------------------------------------------------------------------
-
-interface RunShareSessionParams {
-  paths: string[];
-  expires: string | undefined;
-  launchBrowser: boolean;
-  companySlug: string | undefined;
-}
-
-async function runShareSession(params: RunShareSessionParams): Promise<void> {
-  // Normalize every path through the shared prefix helper so a trailing
-  // `/` becomes `/*` consistently with the direct-grant path.
-  const normalizedPaths = params.paths.map(normalizeFilePrefix);
-
-  let expiresInMs: number | undefined;
-  if (params.expires !== undefined) {
-    const parsed = parseDuration(params.expires);
-    if (parsed === null) {
-      console.error(
-        chalk.red(
-          `Invalid duration '${params.expires}'. Use formats like 15m, 1h, 24h.`,
-        ),
-      );
-      process.exit(1);
-    }
-    if (parsed > MAX_SHARE_SESSION_EXPIRY_MS) {
-      console.error(
-        chalk.red(
-          "Maximum share-session expiry is 24h. For longer sharing, use `hq files share <prefix> --with <principal>`.",
-        ),
-      );
-      process.exit(1);
-    }
-    expiresInMs = parsed;
-  }
-
-  const token = await ensureCognitoToken();
-  const companyUid = await getCompanyUid(token, params.companySlug);
-
-  let session: ShareSessionResponse;
-  try {
-    session = await mintShareSession({
-      token,
-      companyUid,
-      paths: normalizedPaths,
-      expiresInMs,
-    });
-  } catch (err) {
-    if (err instanceof ShareSessionHttpError) {
-      console.error(chalk.red(formatShareSessionError(err)));
-      process.exit(1);
-    }
-    throw err;
-  }
-
-  console.log(chalk.green("Share-session URL generated:"));
-  console.log(`\n  ${session.url}\n`);
-  console.log(chalk.dim(`  Paths:   ${normalizedPaths.join(", ")}`));
-  console.log(chalk.dim(`  Expires: ${session.expiresAt}`));
-
-  if (params.launchBrowser) {
-    // Best-effort browser launch — failures (no display, missing handler)
-    // shouldn't fail the command since the URL is already printed.
-    try {
-      await open(session.url);
-    } catch (err) {
-      console.error(
-        chalk.yellow(
-          `Couldn't launch browser automatically (${err instanceof Error ? err.message : String(err)}). Copy the URL above.`,
-        ),
-      );
-    }
-  } else {
-    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.
- *
- * Scope is EITHER a company vault (`companyUid` set) OR the caller's personal
- * vault (`personal: true`). For the personal case the server resolves the target
- * person + bucket from the authenticated caller — we send NO uid, just the
- * `personal` flag — so there is nothing for the client to get wrong or spoof.
- */
-async function callDeleteEndpoint(params: {
-  token: string;
-  companyUid?: string;
-  personal?: boolean;
-  prefix: string;
-  dryRun: boolean;
-}): Promise<FilesDeleteResponse> {
-  const res = await vaultApiFetch({
-    token: params.token,
-    path: "/v1/files/delete",
-    method: "POST",
-    body: params.personal
-      ? {
-          personal: true,
-          prefix: params.prefix,
-          dryRun: params.dryRun,
-        }
-      : {
-          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;
-  /** Target the caller's personal vault instead of a company vault. */
-  personal?: 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`));
-  }
-}
-
-/**
- * The vault bucket is already company-scoped, so a delete prefix must be
- * BUCKET-RELATIVE (e.g. `projects/foo/*`). A caller who pastes an HQ *local*
- * tree path (`companies/<slug>/projects/foo`) over-prefixes it; the server then
- * rejects it with INVALID_PREFIX_COMPANIES_SCOPED (HTTP 400), the source of the
- * recurring Sentry warning HQ-8F. Strip a redundant leading `companies/<slug>/`
- * so the local-looking path is normalized to the bucket-relative key the vault
- * actually stores. Returns the stripped slug for a one-line notice, or null when
- * there was nothing to strip. Pure → unit-testable.
- *
- * This runs UPSTREAM of the server's exact-vs-glob branch, so it covers both
- * the glob spelling (`companies/<slug>/projects/foo/*` → `validatePrefix`,
- * HQ-8F) and the EXACT-key spelling (`companies/<slug>/notes/foo.md` →
- * `validateObjectKey`, HQ-CA) with the same normalization.
- */
-export function stripRedundantCompanyScope(
-  prefix: string,
-): { prefix: string; strippedSlug: string } | null {
-  const m = /^companies\/([^/]+)(?:\/(.*))?$/.exec(prefix);
-  if (!m) return null;
-  return { prefix: m[2] ?? "", strippedSlug: m[1] };
-}
-
-export async function runFilesDelete(
-  params: RunFilesDeleteParams,
-  deps: { confirm?: ConfirmFn } = {},
-): Promise<void> {
-  const confirm = deps.confirm ?? realConfirm;
-
-  // The vault is already company-scoped — a `companies/<slug>/` prefix is the HQ
-  // LOCAL tree layout, not a vault key, and the server 400s it (HQ-8F). Strip it
-  // here so a pasted local path is gracefully normalized to bucket-relative
-  // BEFORE the dry-run/preview (so the operator still sees the exact keys and
-  // confirms the right target). If stripping empties the prefix, the root-reject
-  // below catches it with a clear message.
-  const scope = stripRedundantCompanyScope(params.prefix);
-  if (scope) {
-    console.error(
-      chalk.yellow(
-        `Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
-          `is already company-scoped; using bucket-relative ` +
-          `'${scope.prefix || "(root)"}'.`,
-      ),
-    );
-  }
-  const rawPrefix = scope ? scope.prefix : params.prefix;
-
-  // 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(rawPrefix);
-  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();
-  // Personal scope resolves the vault server-side from the caller's identity —
-  // no company to look up. Company scope resolves the companyUid as before.
-  const companyUid = params.personal
-    ? undefined
-    : await getCompanyUid(token, params.companySlug);
-  const scopeArgs = params.personal
-    ? { personal: true as const }
-    : { companyUid };
-
-  // 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,
-      ...scopeArgs,
-      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(
-      params.personal
-        ? `Delete ${preview.matched} ${noun}? This removes them from your personal vault.`
-        : `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,
-      ...scopeArgs,
-      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.`,
-      ),
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-}