@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/files.js

@@ -4,10 +4,22 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
-import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+import { GROUP_ID_PATTERN, EMAIL_PATTERN, isPrivateFolderPattern, normalizeFilePrefix, toSharedFolderGlob, } from "./_patterns.js";
 import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
 import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
+import { fetchChannels, matchChannelsByName } from "./dm.js";
+import { resolveCompanySlug, resolvePersonWithRosterFallback, } from "./people.js";
+import { findHqRoot } from "../utils/manifest.js";
+import { maxLength } from "../utils/table-width.js";
+import { resolveCompanyFlagGate } from "../lib/flag-registry.js";
+const PERSON_UID_PATTERN = /^(prs|agt)_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+export const FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG = "files.share-empty-prefix-warning";
+const FILES_SHARE_EMPTY_PREFIX_CHECK_TIMEOUT_MS = 5_000;
+function collectMentions(value, previous) {
+    return [...previous, value];
+}
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
@@ -33,6 +45,27 @@ export function parseDuration(input) {
 }
 /** PRD upper bound on browser-launch share-session expiry. */
 export const MAX_SHARE_SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24h
+/** Render the ACL-specific meaning of a path without changing its wire value. */
+function displayAclPattern(prefix) {
+    return isPrivateFolderPattern(prefix)
+        ? `${prefix} (private folder)`
+        : prefix;
+}
+function privateFolderExplanation(prefix) {
+    return (`Private folder '${prefix}' — write can create only a new direct child. ` +
+        "Children are creator-only; this grant does not read, list, overwrite, or delete them.");
+}
+function formatAclPatternConflict(prefix, serverMessage) {
+    const privatePattern = prefix.endsWith("/*")
+        ? prefix.slice(0, -1)
+        : prefix.endsWith("/")
+            ? prefix
+            : `${prefix}/`;
+    const sharedPattern = `${privatePattern}*`;
+    const detail = serverMessage ? `${serverMessage}. ` : "";
+    return (`${detail}A private folder '${privatePattern}' and shared folder glob ` +
+        `'${sharedPattern}' cannot both exist. Remove the conflicting ACL pattern and retry.`);
+}
 /**
  * POST /files/{companyUid}/share-session — mint a browser-launch share
  * session token. Returns the parsed response. Throws ShareSessionHttpError
@@ -94,7 +127,7 @@ export function formatShareSessionError(err) {
 export function registerFilesCommand(program) {
     const files = program
         .command("files")
-        .description("Manage file access controls in HQ vault")
+        .description("Manage file access controls in HQ vault. A trailing folder slash (foo/) is a private folder; the quoted glob 'foo/*' shares all children.")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     // An exported HQ_API_KEY must never fall back to the caller's Cognito session
     // (that would ignore the key's scope entirely), so every subcommand is gated.
@@ -123,14 +156,29 @@ export function registerFilesCommand(program) {
     });
     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.")
+        .description("Share file paths. foo/ is a private folder (children stay creator-only); quote the shared-folder glob 'foo/*' so the shell passes it literally. 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")
+        .option("--channel <name>", "Post the share record to this named channel instead of a DM")
+        .option("--mention <person>", "Mention a person on the channel share record (repeatable)", collectMentions, [])
         .action(async (paths, opts) => {
         try {
+            const mentions = opts.mention ?? [];
+            if (mentions.length > 0 && opts.channel === undefined) {
+                console.error(chalk.red("--mention requires --channel <name>."));
+                process.exit(1);
+            }
+            const companySlug = files.opts().company;
+            const channelTarget = opts.channel !== undefined
+                ? await resolveShareChannelTarget({
+                    channelName: opts.channel,
+                    mentions,
+                    companySlug,
+                })
+                : undefined;
             // 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
@@ -150,8 +198,9 @@ export function registerFilesCommand(program) {
                     prefix: "*",
                     principal: opts.with,
                     permission: opts.permission ?? "write",
-                    companySlug: files.opts().company,
+                    companySlug,
                     fullVault: true,
+                    ...channelTarget,
                 });
                 return;
             }
@@ -159,9 +208,9 @@ export function registerFilesCommand(program) {
                 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. The direct-grant path
-            // operates on a single prefix.
+            // Fork: --with present → existing direct-grant path. --channel without
+            // --with grants each --mention as a person. No --with and no --channel
+            // → browser-launch share-session path.
             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."));
@@ -171,15 +220,42 @@ export function registerFilesCommand(program) {
                     prefix: paths[0],
                     principal: opts.with,
                     permission: opts.permission,
-                    companySlug: files.opts().company,
+                    companySlug,
+                    ...channelTarget,
                 });
                 return;
             }
+            if (channelTarget) {
+                if (channelTarget.mentionPersonUids.length === 0) {
+                    console.error(chalk.red("--channel requires --with <principal> or --mention <person>."));
+                    process.exit(1);
+                }
+                if (paths.length !== 1) {
+                    console.error(chalk.red("Channel share takes exactly one prefix. Pass multiple paths only when minting a share-session URL."));
+                    process.exit(1);
+                }
+                const permission = opts.permission ?? "read";
+                for (const [index, uid] of channelTarget.mentionPersonUids.entries()) {
+                    await runDirectGrant({
+                        prefix: paths[0],
+                        principal: uid,
+                        permission,
+                        companySlug,
+                        ...(index === 0
+                            ? {
+                                channelId: channelTarget.channelId,
+                                mentionPersonUids: channelTarget.mentionPersonUids,
+                            }
+                            : {}),
+                    });
+                }
+                return;
+            }
             await runShareSession({
                 paths,
                 expires: opts.expires,
                 launchBrowser: opts.open,
-                companySlug: files.opts().company,
+                companySlug,
             });
         }
         catch (err) {
@@ -189,15 +265,16 @@ export function registerFilesCommand(program) {
     });
     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")
+        .description("Remove a file access grant. A trailing slash targets the private-folder row exactly.")
+        .requiredOption("--with <principal>", "Person uid, agent uid, email address, group id, or '@all' to remove the grant")
         .action(async (prefix, opts) => {
         try {
-            // Unshare MUTATES access with no preview, and it resolves the target
-            // company from --company (not from the pasted anchor), so a mismatched
-            // anchor would revoke a real grant in the wrong company.
+            // Unshare MUTATES access with no preview. Anchored content paths remain
+            // refused; the exact company-root ACL row is the sole exception and
+            // resolves its anchor against the selected company before revoking.
             const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
                 mutating: true,
+                allowCompanyRootAclRow: true,
                 ...(files.opts().company !== undefined
                     ? { companySlug: files.opts().company }
                     : {}),
@@ -206,15 +283,21 @@ export function registerFilesCommand(program) {
             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>`));
+            const isAgent = !isAll && !isEmail && !isGroup && AGENT_UID_PATTERN.test(principal);
+            const isPerson = !isAll && !isEmail && !isGroup && !isAgent && PERSON_UID_PATTERN.test(principal);
+            if (!isAll && !isEmail && !isGroup && !isPerson && !isAgent) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid matching prs_<alphanumeric>, an agent uid matching agt_<alphanumeric>, or a group id matching grp_<alphanumeric>`));
                 process.exit(1);
             }
+            // The vault ACL API stores first-class agent access on its backwards-
+            // compatible person tuple: { granteeType: "person", granteeId: "agt_*" }.
             const granteeType = isAll
                 ? "company-wide"
                 : isEmail
                     ? "email"
-                    : "group";
+                    : isGroup
+                        ? "group"
+                        : "person";
             const granteeId = isAll
                 ? ""
                 : isEmail
@@ -222,8 +305,14 @@ export function registerFilesCommand(program) {
                     : principal;
             const principalLabel = isAll ? "everyone in the company" : granteeId;
             const token = (await resolveVaultCredential()).token;
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            const explicitCompanySlug = files.opts().company;
+            const companyRootSlug = stripRedundantCompanyScope(prefix)?.prefix === ""
+                ? companySlugFromAnchor(prefix)
+                : undefined;
+            const companyUid = await resolveCompanyUidForAnchoredPath(token, {
+                explicit: explicitCompanySlug,
+                anchorSlug: companyRootSlug,
+            });
             const res = await vaultApiFetch({
                 token,
                 path: `/files/${encodeURIComponent(companyUid)}/acl/revoke`,
@@ -266,7 +355,7 @@ export function registerFilesCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Removed grant for ${principalLabel} on '${canonicalPrefix}'`));
+            console.log(chalk.green(`Removed grant for ${principalLabel} on '${displayAclPattern(canonicalPrefix)}'`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -275,13 +364,15 @@ export function registerFilesCommand(program) {
     });
     files
         .command("acl <prefix>")
-        .description("Show the ACL (access control list) for a file prefix")
-        .action(async (prefix) => {
+        .description("Show the ACL (access control list) for a file prefix. foo/ is a private folder whose children are creator-only; the quoted glob 'foo/*' is shared.")
+        .option("--json", "Output structured ACL data, including explicit absence")
+        .action(async (prefix, opts) => {
         try {
             // Read-only, so stripping is safe — but a mismatched anchor would show
             // a DIFFERENT company's ACL than the one the operator pasted.
             const explicitCompany = files.opts().company;
             const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                allowCompanyRootAclRow: true,
                 ...(explicitCompany !== undefined
                     ? { companySlug: explicitCompany }
                     : {}),
@@ -321,7 +412,16 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             const tree = (await treeRes.json());
+            if (!tree || typeof tree.prefix !== 'string' || !Array.isArray(tree.direct)
+                || !Array.isArray(tree.inherited) || !Array.isArray(tree.children)
+                || !(tree.directRow === null || (typeof tree.directRow === 'object' && tree.directRow))) {
+                throw new Error('Invalid ACL tree response');
+            }
             const row = tree.directRow;
+            if (opts.json) {
+                console.log(JSON.stringify({ ...tree, schemaVersion: 1, companyUid, exists: row !== null }, null, 2));
+                return;
+            }
             // 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) {
@@ -329,7 +429,10 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             const aclStatus = row?.open ? "open" : "restricted";
-            console.log(chalk.green(`ACL for ${tree.prefix} (${aclStatus})`));
+            console.log(chalk.green(`ACL for ${displayAclPattern(tree.prefix)} (${aclStatus})`));
+            if (isPrivateFolderPattern(tree.prefix)) {
+                console.log(chalk.gray(privateFolderExplanation(tree.prefix)));
+            }
             if (row) {
                 console.log(`Creator: ${row.creatorUid}`);
             }
@@ -353,7 +456,7 @@ export function registerFilesCommand(program) {
                 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))
+                    ? Math.max(6, ...rows.map((e) => displayAclPattern(e.sourcePrefix ?? "").length))
                     : 0;
                 const headerCols = [
                     "TYPE".padEnd(TYPE_W),
@@ -375,7 +478,7 @@ export function registerFilesCommand(program) {
                         grantedAt,
                     ];
                     if (showSource)
-                        cols.splice(4, 0, (e.sourcePrefix ?? "").padEnd(SRC_W));
+                        cols.splice(4, 0, displayAclPattern(e.sourcePrefix ?? "").padEnd(SRC_W));
                     console.log(cols.join("  "));
                 }
             }
@@ -408,7 +511,7 @@ export function registerFilesCommand(program) {
     });
     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.")
+        .description("Delete vault objects by exact key or bounded prefix. A trailing slash expands recursively; use * for an explicit wildcard prefix. 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)")
@@ -501,6 +604,114 @@ export function registerFilesCommand(program) {
     // files-browse.ts) onto the same group without re-creating it.
     return files;
 }
+/** Best-effort, default-off warning after the ACL grant has succeeded. */
+async function warnIfEmptySharePrefix(params) {
+    if (isPrivateFolderPattern(params.prefix))
+        return;
+    let enabled;
+    try {
+        enabled = await resolveCompanyFlagGate(params.companyUid, params.token, FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG, { fallback: false }, () => false);
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown error";
+        console.error(`hq: Could not resolve ${FILES_SHARE_EMPTY_PREFIX_WARNING_FLAG} (${errorClass}); using its fallback.`);
+        return;
+    }
+    if (!enabled)
+        return;
+    const listPrefix = params.fullVault
+        ? ""
+        : params.prefix.endsWith("*")
+            ? params.prefix.slice(0, -1)
+            : params.prefix;
+    try {
+        const query = {
+            company: params.companyUid,
+        };
+        if (listPrefix)
+            query.prefix = listPrefix;
+        const listed = await vaultApiFetch({
+            token: params.token,
+            path: "/v1/files/list",
+            query,
+            signal: AbortSignal.timeout(FILES_SHARE_EMPTY_PREFIX_CHECK_TIMEOUT_MS),
+        });
+        if (!listed.ok)
+            throw new Error(`files list failed (${listed.status})`);
+        const body = (await listed.json());
+        const objects = Array.isArray(body.objects) ? body.objects : [];
+        const hasMatchingObject = params.fullVault || params.prefix.endsWith("*")
+            ? objects.length > 0
+            : objects.some((object) => object.key === listPrefix);
+        if (!hasMatchingObject) {
+            console.warn(chalk.yellow(`Warning: no files exist under '${displayAclPattern(params.prefix)}'. ` +
+                `The recipient will see nothing until files sync there.`));
+        }
+    }
+    catch (error) {
+        const errorClass = error instanceof Error ? error.name : "unknown error";
+        console.warn(chalk.yellow(`Could not check whether '${displayAclPattern(params.prefix)}' has files; ` +
+            `the share succeeded (${errorClass}).`));
+    }
+}
+async function resolveShareChannelTarget(params) {
+    const token = (await resolveVaultCredential()).token;
+    const channels = await fetchChannels(token);
+    const matches = matchChannelsByName(channels, params.channelName);
+    if (matches.length === 0) {
+        console.error(chalk.red(`No channel named '${params.channelName}' — run \`hq channels\` to see your channels.`));
+        process.exit(1);
+    }
+    if (matches.length > 1) {
+        const scopes = matches
+            .map((c) => c.scope ?? "unknown")
+            .join(", ");
+        console.error(chalk.red(`'${params.channelName}' matches ${matches.length} channels (${scopes}) — this is ambiguous.`));
+        process.exit(1);
+    }
+    const channelId = matches[0].channelId;
+    const mentionPersonUids = [];
+    for (const mention of params.mentions) {
+        mentionPersonUids.push(await resolveMentionPersonUid(mention, params.companySlug));
+    }
+    return { channelId, mentionPersonUids };
+}
+async function resolveMentionPersonUid(mention, companySlug) {
+    const trimmed = mention.trim();
+    if (PERSON_UID_PATTERN.test(trimmed))
+        return trimmed;
+    const hqRoot = findHqRoot();
+    const slug = resolveCompanySlug(hqRoot, companySlug);
+    const result = await resolvePersonWithRosterFallback({
+        hqRoot,
+        slug,
+        name: trimmed,
+    });
+    if (result.status === "found" && result.person.personUid) {
+        return result.person.personUid;
+    }
+    if (result.status === "ambiguous") {
+        const names = result.matches.map((p) => p.name).join(", ");
+        console.error(chalk.red(`'${trimmed}' matches multiple people (${names}) — use a person uid or email.`));
+        process.exit(1);
+    }
+    const membership = await resolvePersonWithRosterFallback({
+        hqRoot,
+        slug,
+        name: trimmed,
+        opts: { membershipOnly: true },
+    });
+    if (membership.status === "found" && membership.person.personUid) {
+        return membership.person.personUid;
+    }
+    if (membership.status === "ambiguous") {
+        const names = membership.matches.map((p) => p.name).join(", ");
+        console.error(chalk.red(`'${trimmed}' matches multiple people (${names}) — use a person uid or email.`));
+        process.exit(1);
+    }
+    console.error(chalk.red(`Could not resolve --mention '${trimmed}' to a person.`));
+    process.exit(1);
+}
 async function runDirectGrant(params) {
     const canonicalPrefix = normalizeCompanyFilePrefix(params.prefix, {
         mutating: true,
@@ -525,11 +736,18 @@ async function runDirectGrant(params) {
     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>`));
+    const isPerson = !isAll && !isEmail && !isGroup && PERSON_UID_PATTERN.test(principal);
+    if (!isAll && !isEmail && !isGroup && !isPerson) {
+        console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, a person uid, or a group id matching grp_<alphanumeric>`));
         process.exit(1);
     }
-    const granteeType = isAll ? "company-wide" : isEmail ? "email" : "group";
+    const granteeType = isAll
+        ? "company-wide"
+        : isEmail
+            ? "email"
+            : isPerson
+                ? "person"
+                : "group";
     const granteeId = isAll
         ? ""
         : isEmail
@@ -548,6 +766,10 @@ async function runDirectGrant(params) {
             granteeType,
             granteeId,
             permission: params.permission,
+            ...(params.channelId ? { channelId: params.channelId } : {}),
+            ...(params.mentionPersonUids && params.mentionPersonUids.length > 0
+                ? { mentionPersonUids: params.mentionPersonUids }
+                : {}),
         },
     });
     // No ACL row exists yet for this prefix. Auto-create one with this
@@ -562,6 +784,10 @@ async function runDirectGrant(params) {
             body: {
                 prefix: canonicalPrefix,
                 entries: [{ granteeType, granteeId, permission: params.permission }],
+                ...(params.channelId ? { channelId: params.channelId } : {}),
+                ...(params.mentionPersonUids && params.mentionPersonUids.length > 0
+                    ? { mentionPersonUids: params.mentionPersonUids }
+                    : {}),
             },
         });
         autoCreated = res.ok;
@@ -580,6 +806,9 @@ async function runDirectGrant(params) {
         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 && body.code === "ACL_PATTERN_CONFLICT") {
+            console.error(chalk.red(formatAclPatternConflict(canonicalPrefix, body.message)));
+        }
         else if (res.status === 409) {
             console.error(chalk.red("Concurrent modification — please retry"));
         }
@@ -593,12 +822,26 @@ async function runDirectGrant(params) {
     }
     const data = (await res.json());
     const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
+    await warnIfEmptySharePrefix({
+        token,
+        companyUid,
+        prefix: canonicalPrefix,
+        fullVault: params.fullVault === true,
+    });
     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}`));
+        console.log(chalk.green(`${verb} ${params.permission} on ${displayAclPattern(printedPrefix)} to ${principalLabel}`));
+    }
+    if (isPrivateFolderPattern(printedPrefix)) {
+        console.log(chalk.gray(privateFolderExplanation(printedPrefix)));
+    }
+    if (typeof data.record?.error === "string" &&
+        typeof data.record.status === "number" &&
+        data.record.status >= 400) {
+        console.log(data.record.error);
     }
 }
 async function runShareSession(params) {
@@ -707,7 +950,7 @@ function realConfirm(message) {
  * 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) {
+export async function callDeleteEndpoint(params) {
     const res = await vaultApiFetch({
         token: params.token,
         path: "/v1/files/delete",
@@ -854,9 +1097,11 @@ export function companySlugFromAnchor(prefix, personal) {
  * Normalize company paths at the CLI boundary, preserving personal keys.
  *
  * `mutating` marks a route that CHANGES access and has no preview or
- * confirmation step (grant, share, unshare). Those refuse an anchored path
- * outright rather than guessing, because stripping the anchor changes which
+ * confirmation step (grant, share, unshare). Those refuse anchored content
+ * paths rather than guessing, because stripping the anchor changes which
  * objects the operation reaches and there is nothing downstream to catch it.
+ * `allowCompanyRootAclRow` is limited to exact-root ACL inspect/revoke calls:
+ * those need the original anchor to match a legacy company-root ACL row.
  *
  * `companySlug` is the company the command is actually targeting. When the
  * anchor names a DIFFERENT company we refuse in every mode: stripping would
@@ -884,9 +1129,12 @@ function normalizeCompanyFilePrefix(prefix, options = {}) {
             `operation to '${options.companySlug}' instead. Re-run with ` +
             `--company ${scope.strippedSlug}, or pass the bucket-relative path.`);
     }
-    // A bare anchor strips to nothing. The ACL routes would ship that empty
-    // prefix to a server that answers 400, so fail here with a message that says
-    // what to do instead. `deferRootReject` is for callers that already have a
+    if (!scope.prefix && options.allowCompanyRootAclRow) {
+        return normalizeFilePrefix(prefix);
+    }
+    // A bare anchor strips to nothing. Content operations must fail with a
+    // message that says what to do instead; exact-root ACL operations preserve
+    // the original anchor above. `deferRootReject` is for callers that already have a
     // root guard with better copy — `runFilesDelete` says "Refusing to delete the
     // vault root", which beats anything this generic helper could write.
     if (!scope.prefix && !options.deferRootReject) {
@@ -911,19 +1159,20 @@ export async function runFilesDelete(params, deps = {}) {
     const confirm = deps.confirm ?? realConfirm;
     // Strip the local company anchor before preview/confirmation (HQ-8F/HQ-CA).
     // Personal keys are already bucket-relative and must keep any such anchor.
-    // Normalize trailing `/` to `/*`, then reject the root/empty prefix before
+    // Deletion intentionally expands a folder spelling to a recursive glob, then
+    // rejects the root/empty prefix before
     // any network call, including when stripping a bare company anchor empties it.
     // The anchor names a company. Compare it with --company (refusing a
     // mismatch), and when --company was omitted ADOPT it rather than letting the
     // membership fallback pick a different company to delete from.
     const anchorSlug = companySlugFromAnchor(params.prefix, params.personal);
-    const normalized = normalizeCompanyFilePrefix(params.prefix, {
+    const normalized = toSharedFolderGlob(normalizeCompanyFilePrefix(params.prefix, {
         personal: params.personal,
         deferRootReject: true,
         ...(params.companySlug !== undefined
             ? { companySlug: params.companySlug }
             : {}),
-    });
+    }));
     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);
@@ -1058,13 +1307,15 @@ export function formatFilesVersionsTable(rows) {
         row.lastModified,
         row.isDeleteMarker ? "—" : formatBytes(row.size),
     ]);
-    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const widths = cols.map((col, index) => maxLength(data, (row) => row[index].length, col.length));
     const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
-    return [
+    const lines = [
         chalk.bold(renderRow(cols)),
         chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
-        ...data.map(renderRow),
-    ].join("\n");
+    ];
+    for (const row of data)
+        lines.push(renderRow(row));
+    return lines.join("\n");
 }
 /** Render durable delete tombstones without implying the objects still exist. */
 export function formatFilesTrashTable(rows) {
@@ -1078,13 +1329,15 @@ export function formatFilesTrashTable(rows) {
         row.deletedBy,
         row.deletedPrefix,
     ]);
-    const widths = cols.map((col, index) => Math.max(col.length, ...data.map((row) => row[index].length)));
+    const widths = cols.map((col, index) => maxLength(data, (row) => row[index].length, col.length));
     const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
-    return [
+    const lines = [
         chalk.bold(renderRow(cols)),
         chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
-        ...data.map(renderRow),
-    ].join("\n");
+    ];
+    for (const row of data)
+        lines.push(renderRow(row));
+    return lines.join("\n");
 }
 function throwRecoveryHttpError(status, body, statusText) {
     throw new FilesRecoveryHttpError(status, body.message ?? body.error ?? statusText, body.code);

package/dist/commands/group-grants.js

@@ -242,8 +242,9 @@ export function registerGroupGrantsCommand(program) {
     });
     grants
         .command("outbound")
-        .description("List grants a source-company group holds on other companies")
-        .requiredOption("--group <groupId>", "Group id to inspect")
+        .description("List grants a source-company group holds on other companies; " +
+        "requires --group <groupId>.")
+        .requiredOption("--group <groupId>", "Group id to inspect (required)")
         .action(async (opts) => {
         try {
             const token = await ensureCognitoToken();

package/dist/commands/groups.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN } from "./_patterns.js";
+import { maxLength } from "../utils/table-width.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
 const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
@@ -261,9 +262,9 @@ export function registerGroupsCommand(program) {
                 console.log(chalk.gray("No groups in this company yet."));
                 return;
             }
-            const idW = Math.max(8, ...data.groups.map((g) => g.groupId.length));
-            const nameW = Math.max(4, ...data.groups.map((g) => g.name.length));
-            const descW = Math.max(11, ...data.groups.map((g) => (g.description ?? "").length));
+            const idW = maxLength(data.groups, (group) => group.groupId.length, 8);
+            const nameW = maxLength(data.groups, (group) => group.name.length, 4);
+            const descW = maxLength(data.groups, (group) => (group.description ?? "").length, 11);
             console.log(chalk.bold([
                 "GROUP_ID".padEnd(idW),
                 "NAME".padEnd(nameW),
@@ -326,8 +327,8 @@ export function registerGroupsCommand(program) {
                 console.log(chalk.gray("No members yet — use 'hq groups add' to add."));
                 return;
             }
-            const uidW = Math.max(10, ...data.members.map((m) => m.personUid.length));
-            const byW = Math.max(8, ...data.members.map((m) => m.addedBy.length));
+            const uidW = maxLength(data.members, (member) => member.personUid.length, 10);
+            const byW = maxLength(data.members, (member) => member.addedBy.length, 8);
             console.log(chalk.bold([
                 "PERSON_UID".padEnd(uidW),
                 "ADDED_BY".padEnd(byW),