@indigoai-us/hq-cli 5.17.0 → 5.18.1

package/dist/commands/cloud.d.ts

@@ -13,10 +13,12 @@
  *   hq sync status            — show local journal summary
  */
 import { Command } from "commander";
-import { type ConflictStrategy } from "@indigoai-us/hq-cloud";
+import { type ConflictStrategy, type MembershipSyncConfig } from "@indigoai-us/hq-cloud";
+import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 export interface PullAllVaultClient {
     listMyMemberships(): Promise<Array<{
         companyUid: string;
+        membershipKey?: string;
     }>>;
     listPersonEntities(): Promise<Array<{
         uid: string;
@@ -29,6 +31,13 @@ export interface PullAllVaultClient {
         slug?: string;
         name?: string;
     } | null>;
+    /**
+     * US-011: optional — when present, `pullAll` calls it once per
+     * membership to surface the narrow-hint banner for all-mode owners.
+     * Absent on legacy adapters (push-all et al.) where the banner is not
+     * applicable.
+     */
+    getMembershipSyncConfig?: (membershipId: string) => Promise<MembershipSyncConfig>;
 }
 export interface SyncCallOptions {
     company: string;
@@ -52,6 +61,22 @@ export interface PullAllDeps {
 export interface PullAllOptions {
     hqRoot: string;
     onConflict?: ConflictStrategy;
+    /**
+     * US-011: banner level for the narrow-hint nudge. Defaults to `'hint'`
+     * — see `resolveBannerLevel` for the env-driven override. The
+     * `'strict'` level causes `pullAll` to refuse to sync any membership
+     * still on `syncMode: 'all'` unless `modeAllOverride` is true.
+     *
+     * TODO(hq-core-staging release N+2): default flips to 'warning'.
+     * TODO(hq-core-staging release N+3): default flips to 'strict'.
+     */
+    narrowHintLevel?: BannerLevel;
+    /**
+     * US-011: when `true`, strict-mode does NOT refuse all-mode
+     * memberships — the operator has explicitly opted into keeping the
+     * legacy behavior for this run via `--mode-all`.
+     */
+    modeAllOverride?: boolean;
 }
 export interface PullAllRow {
     slug: string;
@@ -138,5 +163,42 @@ export declare function assertSingleSelector(opts: {
     personal?: boolean;
     company?: string;
 }, command: string): void;
+/**
+ * Per-company pull resolution helper used by `hq sync pull --company <slug>`
+ * (US-011 fix, 2026-05-21). Mirrors the inline lookup that `runNowSingle`
+ * does for sync-now. Pulled out so the action handler stays thin AND so
+ * unit tests can exercise the banner / strict-refusal decision without
+ * spinning up commander + a real VaultClient.
+ *
+ * Input shape:
+ *   - `targetCompany` — slug or UID the caller passed to `--company`. If
+ *     undefined, the helper short-circuits to a "no resolution" result
+ *     (the action handler falls back to .hq/config.json via sync()).
+ *   - `client` — minimal VaultClient surface: listMyMemberships + entity.get
+ *     + getMembershipSyncConfig.
+ *
+ * Output: `{ resolvedCompanyUid, resolvedMode }` — either may be undefined
+ * if the membership / sync-config call failed. Both undefined is a clean
+ * degradation — the caller pulls without a banner.
+ */
+export interface PerCompanyPullResolveClient {
+    listMyMemberships(): Promise<Array<{
+        companyUid: string;
+        membershipKey: string;
+    }>>;
+    getMembershipSyncConfig(membershipKey: string): Promise<{
+        syncMode: MembershipSyncConfig["syncMode"];
+    }>;
+    entity: {
+        get(uid: string): Promise<{
+            slug?: string;
+        }>;
+    };
+}
+export interface PerCompanyPullResolveResult {
+    resolvedCompanyUid: string | undefined;
+    resolvedMode: MembershipSyncConfig["syncMode"] | undefined;
+}
+export declare function resolvePerCompanyPullPlan(client: PerCompanyPullResolveClient, targetCompany: string | undefined): Promise<PerCompanyPullResolveResult>;
 export declare function registerCloudCommands(program: Command): void;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -13,12 +13,13 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7bc55d66-7b02-5b45-9444-710bb6d8dfd6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4672d875-1dc8-56a2-bef1-49c7f4ff6c76")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
 import { share, sync, readJournal, getJournalPath, loadCachedTokens, VaultClient, computePersonalVaultPaths, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { emitNarrowHint, isStrictRefusal, resolveBannerLevel, } from "../lib/narrow-hint-banner.js";
 // Oldest-first by createdAt, ties broken by uid lexicographic — matches
 // `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
 // the same person bucket that `hq-sync-runner` picks.
@@ -35,6 +36,8 @@ function pickCanonicalPerson(persons) {
 export async function pullAll(options, deps) {
     const memberships = await deps.vaultClient.listMyMemberships();
     const persons = await deps.vaultClient.listPersonEntities();
+    const narrowHintLevel = options.narrowHintLevel ?? "hint";
+    const getSyncConfig = deps.vaultClient.getMembershipSyncConfig;
     const plan = [];
     for (const m of memberships) {
         let slug = m.companyUid;
@@ -48,6 +51,8 @@ export async function pullAll(options, deps) {
         }
         plan.push({
             slug,
+            companyUid: m.companyUid,
+            ...(m.membershipKey ? { membershipKey: m.membershipKey } : {}),
             syncOptions: {
                 company: m.companyUid,
                 hqRoot: options.hqRoot,
@@ -78,12 +83,57 @@ export async function pullAll(options, deps) {
     };
     for (const entry of plan) {
         result.attempted += 1;
+        // US-011: resolve the membership's effective sync mode so we can
+        // either nudge an all-mode owner toward `hq sync narrow` OR refuse
+        // the leg outright when strict-mode is on and the operator didn't
+        // pass `--mode-all`. Sync-config lookup is best-effort — a 404 or
+        // network blip should never block the sync itself, so we fall back
+        // to syncMode='all' (the legacy default) and skip the banner.
+        let resolvedMode;
+        if (entry.membershipKey && getSyncConfig) {
+            try {
+                const cfg = await getSyncConfig(entry.membershipKey);
+                resolvedMode = cfg.syncMode;
+            }
+            catch {
+                resolvedMode = undefined;
+            }
+        }
+        if (resolvedMode === "all" &&
+            isStrictRefusal(resolvedMode, narrowHintLevel) &&
+            !options.modeAllOverride &&
+            entry.companyUid) {
+            // Emit the strict-level banner once, then mark the leg as errored
+            // without invoking sync(). The operator either narrows the
+            // membership (`hq sync narrow --apply`) or passes `--mode-all` to
+            // opt back in.
+            emitNarrowHint({
+                companyUid: entry.companyUid,
+                syncMode: resolvedMode,
+                level: narrowHintLevel,
+            });
+            const message = "Refusing to pull all-mode membership in strict mode. " +
+                "Run `hq sync narrow --apply` to migrate, or re-run with --mode-all.";
+            result.errors.push({ company: entry.slug, message });
+            result.perCompany.push({ slug: entry.slug, error: message });
+            continue;
+        }
         try {
             const r = await deps.sync(entry.syncOptions);
             result.filesDownloaded += r.filesDownloaded;
             result.bytesDownloaded += r.bytesDownloaded;
             result.conflicts += r.conflicts;
             result.perCompany.push({ slug: entry.slug, result: r });
+            // Banner emitted AFTER the leg succeeds so it appears alongside
+            // the per-company summary line and doesn't get scrolled off by
+            // sync chatter.
+            if (resolvedMode === "all" && entry.companyUid) {
+                emitNarrowHint({
+                    companyUid: entry.companyUid,
+                    syncMode: resolvedMode,
+                    level: narrowHintLevel,
+                });
+            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -202,6 +252,54 @@ export function assertSingleSelector(opts, command) {
             `--company; got: ${selectors.join(", ")}.`);
     }
 }
+export async function resolvePerCompanyPullPlan(client, targetCompany) {
+    if (!targetCompany)
+        return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+    try {
+        const memberships = await client.listMyMemberships();
+        // Direct UID / membershipKey match first (cheapest).
+        const direct = memberships.find((m) => m.companyUid === targetCompany || m.membershipKey === targetCompany);
+        if (direct) {
+            let mode;
+            try {
+                const cfg = await client.getMembershipSyncConfig(direct.membershipKey);
+                mode = cfg.syncMode;
+            }
+            catch {
+                mode = undefined;
+            }
+            return { resolvedCompanyUid: direct.companyUid, resolvedMode: mode };
+        }
+        // Slug match — listMyMemberships returns companyUid only, so fan out
+        // entity.get to find the row whose slug matches the caller's input.
+        for (const m of memberships) {
+            try {
+                const entity = await client.entity.get(m.companyUid);
+                if (entity.slug === targetCompany) {
+                    let mode;
+                    try {
+                        const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+                        mode = cfg.syncMode;
+                    }
+                    catch {
+                        mode = undefined;
+                    }
+                    return { resolvedCompanyUid: m.companyUid, resolvedMode: mode };
+                }
+            }
+            catch {
+                // Entity not visible — skip and continue. Worst case the loop ends
+                // with no match and we return undefined for both — the pull still
+                // proceeds, banner just stays quiet.
+            }
+        }
+    }
+    catch {
+        // listMyMemberships failed — degrade silently. Sync still works without
+        // the banner; this matches the runPullAll catch behavior.
+    }
+    return { resolvedCompanyUid: undefined, resolvedMode: undefined };
+}
 export function registerCloudCommands(program) {
     program
         .command("push")
@@ -407,6 +505,10 @@ export function registerCloudCommands(program) {
         "(no companies/<slug>/ prefix). Resolves the person UID automatically " +
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.")
+        .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
+        "Has no effect today (default narrow-hint level is 'hint'); " +
+        "wired so future hq-core-staging releases can flip the default to " +
+        "'strict' without re-touching this command.")
         .action(async (options) => {
         try {
             assertSingleSelector(options, "pull");
@@ -416,7 +518,7 @@ export function registerCloudCommands(program) {
             process.exit(1);
         }
         if (options.all) {
-            await runPullAll(options.hqRoot, options.onConflict);
+            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true);
             return;
         }
         if (options.personal) {
@@ -428,10 +530,37 @@ export function registerCloudCommands(program) {
             console.log(`  HQ root:  ${options.hqRoot}`);
             console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
             const accessToken = await ensureCognitoToken();
+            const vaultConfig = buildVaultConfig(accessToken);
+            // US-011 (2026-05-21 fix): resolve the caller's sync-config for
+            // the targeted membership BEFORE the pull, so we can (a) emit the
+            // narrow-hint banner after success if still on all-mode and
+            // (b) respect strict-mode refusal mirror of the --all + sync-now
+            // paths. Failure to resolve degrades silently — pull still works,
+            // banner just stays quiet (same as the catch in runPullAll).
+            const narrowHintLevel = resolveBannerLevel();
+            const { resolvedCompanyUid, resolvedMode } = await resolvePerCompanyPullPlan(new VaultClient(vaultConfig), options.company);
+            // Strict-mode refusal: matches runPullAll + runNowSingle behavior.
+            // Default banner level is 'hint' which never triggers refusal —
+            // wired now so future hq-core-staging releases can flip the
+            // default to 'strict' without re-touching this command.
+            if (resolvedMode === "all" &&
+                isStrictRefusal(resolvedMode, narrowHintLevel) &&
+                options.modeAll !== true &&
+                resolvedCompanyUid) {
+                emitNarrowHint({
+                    companyUid: resolvedCompanyUid,
+                    syncMode: resolvedMode,
+                    level: narrowHintLevel,
+                });
+                console.error(chalk.red("\n✗ Pull refused: strict narrow-hint mode is on and this " +
+                    "membership still pulls everything. Run `hq sync narrow --apply` " +
+                    "to migrate, or re-run with --mode-all."));
+                process.exit(1);
+            }
             const result = await sync({
                 company: options.company,
                 onConflict: options.onConflict,
-                vaultConfig: buildVaultConfig(accessToken),
+                vaultConfig,
                 hqRoot: options.hqRoot,
             });
             if (result.aborted) {
@@ -439,6 +568,16 @@ export function registerCloudCommands(program) {
                 process.exit(1);
             }
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
+            // US-011 (2026-05-21 fix): emit the hint banner after success
+            // so it appears alongside the summary line. Mirrors the wiring
+            // in runPullAll (cloud.ts:331) and runNowSingle (cloud.ts:1371).
+            if (resolvedMode === "all" && resolvedCompanyUid) {
+                emitNarrowHint({
+                    companyUid: resolvedCompanyUid,
+                    syncMode: resolvedMode,
+                    level: narrowHintLevel,
+                });
+            }
         }
         catch (err) {
             console.error(chalk.red("\n✗ Pull failed:"), err instanceof Error ? err.message : String(err));
@@ -502,14 +641,17 @@ export function registerCloudCommands(program) {
         "--personal.")
         .option("--personal", "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.")
+        .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
+        "No-op today; wired so future hq-core-staging releases can flip " +
+        "the default narrow-hint level to 'strict'.")
         .action(async (options) => {
         try {
             assertSingleSelector(options, "now");
             if (options.all) {
-                await runNowAll(options.hqRoot, options.message, options.onConflict);
+                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true);
                 return;
             }
-            await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict);
+            await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true);
         }
         catch (err) {
             console.error(chalk.red("\n✗ Sync now failed:"), err instanceof Error ? err.message : String(err));
@@ -517,7 +659,7 @@ export function registerCloudCommands(program) {
         }
     });
 }
-async function runPullAll(hqRoot, onConflict) {
+async function runPullAll(hqRoot, onConflict, modeAllOverride) {
     console.log(chalk.bold("\nHQ Sync — Pull (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
@@ -537,8 +679,14 @@ async function runPullAll(hqRoot, onConflict) {
                     return null;
                 }
             },
+            getMembershipSyncConfig: (id) => realClient.getMembershipSyncConfig(id),
         };
-        result = await pullAll({ hqRoot, ...(onConflict ? { onConflict } : {}) }, {
+        result = await pullAll({
+            hqRoot,
+            ...(onConflict ? { onConflict } : {}),
+            narrowHintLevel: resolveBannerLevel(),
+            ...(modeAllOverride ? { modeAllOverride: true } : {}),
+        }, {
             vaultClient: adapter,
             sync: (opts) => sync({
                 company: opts.company,
@@ -687,7 +835,7 @@ async function runPushAll(hqRoot, message, onConflict) {
     if (errored > 0)
         process.exit(1);
 }
-async function runNowSingle(hqRoot, company, personal, message, onConflict) {
+async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride) {
     console.log(chalk.bold("\nHQ Sync — Now"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
@@ -752,6 +900,49 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             process.exit(1);
         }
+        // US-011: resolve membership sync-config so we can either nudge an
+        // all-mode owner or refuse the pull when strict-mode is on. Skipped
+        // for personal targets (personal vault has no membership row) and
+        // for resolution failures (best-effort — never block sync). The
+        // lookup runs BEFORE the pull leg so strict refusal can short-circuit
+        // without burning a sync.
+        const narrowHintLevel = resolveBannerLevel();
+        let resolvedMode;
+        let resolvedCompanyUid;
+        if (!personalMode && targetCompany) {
+            try {
+                const client = new VaultClient(vaultConfig);
+                const memberships = await client.listMyMemberships();
+                const match = memberships.find((m) => m.companyUid === targetCompany || m.membershipKey === targetCompany);
+                if (match) {
+                    resolvedCompanyUid = match.companyUid;
+                    try {
+                        const cfg = await client.getMembershipSyncConfig(match.membershipKey);
+                        resolvedMode = cfg.syncMode;
+                    }
+                    catch {
+                        resolvedMode = undefined;
+                    }
+                }
+            }
+            catch {
+                resolvedMode = undefined;
+            }
+        }
+        if (resolvedMode === "all" &&
+            isStrictRefusal(resolvedMode, narrowHintLevel) &&
+            !modeAllOverride &&
+            resolvedCompanyUid) {
+            emitNarrowHint({
+                companyUid: resolvedCompanyUid,
+                syncMode: resolvedMode,
+                level: narrowHintLevel,
+            });
+            console.error(chalk.red("\n✗ Sync now refused: strict narrow-hint mode is on and this " +
+                "membership still pulls everything. Run `hq sync narrow --apply` " +
+                "to migrate, or re-run with --mode-all."));
+            process.exit(1);
+        }
         console.log(chalk.dim("  → pull leg"));
         const pullResult = await sync({
             company: targetCompany,
@@ -769,6 +960,15 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict) {
             console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
             process.exit(1);
         }
+        // US-011: emit the hint banner after a successful pull so it
+        // appears at the bottom of the summary rather than mid-stream.
+        if (resolvedMode === "all" && resolvedCompanyUid) {
+            emitNarrowHint({
+                companyUid: resolvedCompanyUid,
+                syncMode: resolvedMode,
+                level: narrowHintLevel,
+            });
+        }
         console.log(chalk.green("\n✓ Sync now complete"));
     }
     catch (err) {
@@ -776,7 +976,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict) {
         process.exit(1);
     }
 }
-async function runNowAll(hqRoot, message, onConflict) {
+async function runNowAll(hqRoot, message, onConflict, modeAllOverride) {
     console.log(chalk.bold("\nHQ Sync — Now (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
@@ -786,7 +986,10 @@ async function runNowAll(hqRoot, message, onConflict) {
     console.log(chalk.dim("→ push --all"));
     await runPushAll(hqRoot, message, onConflict);
     console.log(chalk.dim("\n→ pull --all"));
-    await runPullAll(hqRoot, onConflict);
+    // US-011: forward --mode-all so the strict refusal applies to the
+    // pull leg (push doesn't need a narrow-hint — the narrow ritual is
+    // pull-side).
+    await runPullAll(hqRoot, onConflict, modeAllOverride);
 }
 /**
  * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
@@ -860,4 +1063,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=7bc55d66-7b02-5b45-9444-710bb6d8dfd6
+//# debugId=4672d875-1dc8-56a2-bef1-49c7f4ff6c76

package/dist/commands/files-browse.d.ts

@@ -0,0 +1,178 @@
+/**
+ * `hq files browse <path>` + `hq files cat <path> [--out <file>]` (US-008).
+ *
+ * Peek at a company's vault files **without** ever materialising them under
+ * `companies/{co}/` in the local HQ tree. Distinct from the sync path:
+ *
+ *   - `browse`  — `ListObjectsV2` under the given prefix, prints
+ *                 `{key, size, lastModified, aclSource}` rows. The
+ *                 `aclSource` hint distinguishes prefixes the caller can
+ *                 see via an EXPLICIT grant (`shared-with-you`) from
+ *                 prefixes they can see only because owner/admin
+ *                 role-bypass widened the vended policy (`role-bypass`).
+ *   - `cat`     — `GetObject`, stream the body to stdout. With `--out
+ *                 <file>` write the body to a path the user picked, but
+ *                 only after a bright-line guard refuses any destination
+ *                 inside `<hqRoot>/companies/` — that's the exact tree
+ *                 `hq sync` owns, and writing a peeked object there would
+ *                 silently re-import it into the sync envelope.
+ *
+ * Both subcommands vend via the new `purpose: 'browse'` path
+ * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
+ * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
+ * keeping browse on its own vend call is the acceptance-criteria-1
+ * separation we need.
+ *
+ * Cross-package note: depends on `VendInput`/`VendResult` + the
+ * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
+ * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
+ * `pnpm.overrides` until that release ships to npm.
+ */
+import { Command } from "commander";
+import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
+import { type VendResult, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+/**
+ * Subset of `VaultClient` this command actually uses — exposed so tests
+ * can stub vend + grants without standing up a real `VaultClient`.
+ */
+export interface FilesBrowseVaultClient {
+    vend(input: {
+        paths: string[];
+        operations: "read-only" | "read-write" | "staged-write";
+        purpose: "sync" | "browse";
+        duration?: number;
+    }): Promise<VendResult>;
+    listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
+    entity: {
+        get(uid: string): Promise<{
+            uid: string;
+            slug: string;
+            name?: string;
+            bucketName?: string;
+        }>;
+        findInMyNamespace(type: string, slug: string): Promise<{
+            uid: string;
+            slug: string;
+            name?: string;
+            bucketName?: string;
+        } | null>;
+    };
+}
+/** Subset of `S3Client` this command actually uses — for test stubs. */
+export interface FilesBrowseS3Client {
+    send(cmd: ListObjectsV2Command): Promise<ListObjectsV2CommandOutput>;
+    send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
+}
+/** Factory for an S3 client given vended credentials. Injectable for tests. */
+export type S3ClientFactory = (input: {
+    region: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken: string;
+    };
+}) => FilesBrowseS3Client;
+/** ACL provenance for a single listed key. */
+export type AclSource = "shared-with-you" | "role-bypass";
+export interface BrowseRow {
+    key: string;
+    size: number;
+    lastModified: Date | undefined;
+    aclSource: AclSource;
+}
+/**
+ * Parse the company slug from a vault prefix. Vault paths are anchored at
+ * `companies/<slug>/...`; anything else is rejected so we never try to
+ * browse a non-company tree (e.g. `personal/`) with a company-vend.
+ */
+export declare function parseCompanySlugFromPath(prefix: string): string;
+/**
+ * Classify a single S3 key against the caller's explicit-grant list. Any
+ * grant whose `path` is a prefix of the key contributes `shared-with-you`;
+ * otherwise the key is only visible via role-bypass on the vend call.
+ *
+ * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
+ * `coalescePrefixes` would shrink the list further but isn't required for
+ * correctness — `startsWith` already short-circuits on the first match.
+ */
+export declare function classifyAclSource(key: string, grants: ExplicitGrant[]): AclSource;
+/**
+ * Bright-line guard for `--out`: refuse to write any byte beneath
+ * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
+ * slug-by-slug — `companies/` is the entire surface hq-sync owns, so a
+ * containment check on that parent suffices and avoids drift with the
+ * manifest file. Returns the resolved absolute output path on success;
+ * throws when the destination would land inside the protected tree.
+ */
+export declare function assertOutPathOutsideCompanies(outPath: string, hqRoot: string): string;
+/**
+ * Render a browse listing as a padded table. Mirrors the chalk + padEnd
+ * pattern used by `hq sync mode --show` so the CLI surface stays
+ * stylistically consistent.
+ */
+export declare function formatBrowseTable(rows: BrowseRow[]): string;
+export interface RunBrowseInput {
+    /** Vault path prefix, e.g. `companies/indigo/scratch/`. */
+    pathPrefix: string;
+    /** Caller-overridden company slug (defaults to slug parsed from path). */
+    companySlug?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+}
+export interface RunBrowseResult {
+    rows: BrowseRow[];
+    vend: VendResult;
+}
+/**
+ * `hq files browse <path>` orchestrator.
+ *
+ *   1. Parse slug from prefix (or use override).
+ *   2. Resolve companyUid + bucketName via VaultClient.entity.
+ *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   5. Fetch explicit grants once, classify each key.
+ *
+ * Pure-ish: no console output, no process.exit — caller renders + exits.
+ */
+export declare function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>;
+export interface RunCatInput {
+    /** Single vault key, e.g. `companies/indigo/scratch/foo.txt`. */
+    key: string;
+    /**
+     * Where to write the body. `undefined` ⇒ stdout. Bright-line-guarded
+     * against `<hqRoot>/companies/` by `assertOutPathOutsideCompanies`.
+     */
+    out?: string;
+    hqRoot: string;
+    companySlug?: string;
+    vaultClient: FilesBrowseVaultClient;
+    s3Factory: S3ClientFactory;
+    region: string;
+    /** Destination stream for the stdout path. Injectable for tests. */
+    stdout?: NodeJS.WritableStream;
+}
+export interface RunCatResult {
+    bytesWritten: number;
+    destination: {
+        kind: "stdout";
+    } | {
+        kind: "file";
+        absPath: string;
+    };
+    vend: VendResult;
+}
+/**
+ * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
+ * streams the object body either to stdout or to `--out` (after the
+ * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
+ */
+export declare function runCat(input: RunCatInput): Promise<RunCatResult>;
+/**
+ * Wire `hq files browse` + `hq files cat` onto an existing `files`
+ * Commander group. `registerFilesCommand` in files.ts builds the group
+ * and registers `share`/`unshare`/`acl`; this function appends the two
+ * new browse-vs-sync subcommands so they share the `--company` switch.
+ */
+export declare function registerFilesBrowseCommands(filesCmd: Command): void;
+//# sourceMappingURL=files-browse.d.ts.map