@indigoai-us/hq-cli 5.12.2 → 5.12.4

package/src/commands/files.ts

@@ -1,9 +1,123 @@
 import { Command } from "commander";
 import chalk from "chalk";
+import open from "open";
 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): void {
   const files = program
     .command("files")
@@ -11,102 +125,105 @@ export function registerFilesCommand(program: Command): void {
     .option("--company <slug>", "Company slug (resolves to companyUid)");
 
   files
-    .command("share <prefix>")
-    .description("Share a file prefix with a person or group")
-    .requiredOption("--with <principal>", "Email address or group id to share with")
-    .requiredOption("--permission <level>", "Permission level: read | write")
-    .action(async (prefix: string, opts: { with: string; permission: string }) => {
-      try {
-        const canonicalPrefix = normalizeFilePrefix(prefix);
-
-        if (!["read", "write"].includes(opts.permission)) {
-          console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write`));
-          process.exit(1);
-        }
-
-        const principal = opts.with;
-        const isEmail = EMAIL_PATTERN.test(principal);
-        const isGroup = GROUP_ID_PATTERN.test(principal);
-        if (!isEmail && !isGroup) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
-          process.exit(1);
-        }
-        const granteeType = isEmail ? "email" : "group";
-        const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
-
-        const token = await ensureCognitoToken();
-        const companySlug = files.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
+    .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(
+      "--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;
+          expires?: string;
+          open: boolean;
+        },
+      ) => {
+        try {
+          if (!paths || paths.length === 0) {
+            console.error(
+              chalk.red("usage: hq files share <paths...> [--with <principal>]"),
+            );
+            process.exit(1);
+          }
 
-        let res = await vaultApiFetch({
-          token,
-          path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
-          method: "POST",
-          body: { prefix: canonicalPrefix, granteeType, granteeId, permission: opts.permission },
-        });
+          // 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;
+          }
 
-        // 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: opts.permission }],
-            },
+          await runShareSession({
+            paths,
+            expires: opts.expires,
+            launchBrowser: opts.open,
+            companySlug: files.opts().company as string | undefined,
           });
-          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"));
-          }
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
           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";
-        console.log(chalk.green(`${verb} ${opts.permission} on ${printedPrefix} to ${granteeId}`));
-      } 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 or group id to remove")
+    .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 isEmail = EMAIL_PATTERN.test(principal);
-        const isGroup = GROUP_ID_PATTERN.test(principal);
-        if (!isEmail && !isGroup) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+        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 = isEmail ? "email" : "group";
-        const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+        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;
@@ -126,7 +243,7 @@ export function registerFilesCommand(program: Command): void {
           } else if (res.status === 403) {
             console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
           } else if (res.status === 404) {
-            console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${granteeId}`));
+            console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${principalLabel}`));
             return;
           } else if (res.status >= 500) {
             console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
@@ -136,7 +253,7 @@ export function registerFilesCommand(program: Command): void {
           process.exit(1);
         }
 
-        console.log(chalk.green(`Removed grant for ${granteeId} on '${canonicalPrefix}'`));
+        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);
@@ -154,37 +271,23 @@ export function registerFilesCommand(program: Command): void {
         const companySlug = files.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
 
-        // Fetch the prefix's own ACL row (creator, open flag, effective
-        // permission) and the inherited/descendant tree in parallel so the
-        // user sees every grant that affects this prefix in one shot.
-        const [aclRes, treeRes] = await Promise.all([
-          vaultApiFetch({
-            token,
-            path: `/files/${encodeURIComponent(companyUid)}/acl`,
-            query: { prefix: canonicalPrefix },
-          }),
-          vaultApiFetch({
-            token,
-            path: `/files/${encodeURIComponent(companyUid)}/acl/tree`,
-            query: { prefix: canonicalPrefix },
-          }),
-        ]);
-
-        async function readErrorBody(res: Response): Promise<Record<string, string>> {
-          return (await res.json().catch(() => ({}))) as Record<string, string>;
-        }
+        // `/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 },
+        });
 
-        // Auth/server failures from either call are treated identically — bail
-        // out with a single message rather than printing a half-rendered view.
-        for (const res of [aclRes, treeRes]) {
-          if (res.ok || res.status === 404) continue;
-          const body = await readErrorBody(res);
-          if (res.status === 401) {
+        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 (res.status === 403) {
+          } else if (treeRes.status === 403) {
             console.error(chalk.red("Not authorized to view this file prefix's ACL"));
-          } else if (res.status >= 500) {
-            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+          } 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"));
           }
@@ -198,60 +301,58 @@ export function registerFilesCommand(program: Command): void {
           grantedBy: string;
           grantedAt: string;
         };
-        type AclResponse = {
-          acl: {
-            itemType: string;
-            companyUid: string;
-            // Server returns `path` (the FileAcl field name); older builds
-            // used `prefix`. Read both so the CLI works against either.
-            path?: string;
-            prefix?: string;
-            creatorUid: string;
-            open?: boolean;
-            entries: AclEntry[];
-            effectivePermission?: string | null;
-            createdAt: string;
-            updatedAt: 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 acl = aclRes.ok ? (await aclRes.json() as AclResponse).acl : null;
-        const tree = treeRes.ok ? (await treeRes.json()) as TreeResponse : null;
+        const tree = (await treeRes.json()) as TreeResponse;
+        const row = tree.directRow;
 
-        // No own row AND nothing inherited or granted below — original
-        // "no ACL record" exit path.
-        if (!acl && (!tree || (tree.inherited.length === 0 && tree.children.length === 0))) {
+        // 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 aclPrefix = acl?.path ?? acl?.prefix ?? tree?.prefix ?? canonicalPrefix;
-        const aclStatus = acl?.open ? "open" : "restricted";
+        const aclStatus = row?.open ? "open" : "restricted";
 
-        console.log(chalk.green(`ACL for ${aclPrefix} (${aclStatus})`));
-        if (acl) {
-          console.log(`Creator: ${acl.creatorUid}`);
-          if (acl.effectivePermission) {
-            console.log(`Your effective permission: ${acl.effectivePermission}`);
-          }
+        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) => e.granteeId.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
@@ -270,7 +371,7 @@ export function registerFilesCommand(program: Command): void {
             const grantedAt = e.grantedAt.slice(0, 10);
             const cols = [
               e.granteeType.padEnd(TYPE_W),
-              e.granteeId.padEnd(GRANTEE_W),
+              displayGrantee(e).padEnd(GRANTEE_W),
               e.permission.padEnd(PERM_W),
               e.grantedBy.padEnd(BY_W),
               grantedAt,
@@ -280,11 +381,11 @@ export function registerFilesCommand(program: Command): void {
           }
         }
 
-        const directEntries = acl?.entries ?? tree?.direct ?? [];
+        const directEntries = tree.direct;
         if (directEntries.length === 0) {
-          if (acl?.open) {
+          if (row?.open) {
             console.log(chalk.gray("Open ACL — all active members have read access."));
-          } else if (acl) {
+          } else if (row) {
             console.log(chalk.gray("No explicit grants on this prefix — only creator has access."));
           }
         } else {
@@ -292,12 +393,12 @@ export function registerFilesCommand(program: Command): void {
           printEntryTable(directEntries, false);
         }
 
-        if (tree && tree.inherited.length > 0) {
+        if (tree.inherited.length > 0) {
           console.log("\nInherited (granted on an ancestor prefix):");
           printEntryTable(tree.inherited, true);
         }
 
-        if (tree && tree.children.length > 0) {
+        if (tree.children.length > 0) {
           console.log("\nGranted on descendant prefixes (do not affect this prefix's access):");
           printEntryTable(tree.children, true);
         }
@@ -307,3 +408,197 @@ export function registerFilesCommand(program: Command): void {
       }
     });
 }
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+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";
+  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."));
+  }
+}