@indigoai-us/hq-cli 5.77.13 → 5.78.0

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

@@ -1,1249 +0,0 @@
-/**
- * Unit tests for `hq files browse` + `hq files cat` (files-browse.ts).
- *
- * Stubs the multi-tenant STS vend routes (`sts.vend` / `sts.vendSelf`),
- * listMyExplicitGrants, entity.findInMyNamespace/get, and the S3 client.
- * Coverage focus:
- *
- *   1. Browse/cat vend via `/sts/vend` (company) and `/sts/vend-self`
- *      (personal) — NOT the legacy `POST /vend`, which is non-functional in
- *      multi-tenant prod (undefined BUCKET_ARN → MalformedPolicyDocument).
- *   2. Namespace translation: company vault keys are company-relative, so the
- *      S3 list/get prefix is the bucket-relative form while the CLI surface
- *      stays anchored at `companies/<slug>/`.
- *   3. `--out` refuses any destination under `<hqRoot>/companies/`.
- *   4. ACL-source classification over the company-relative key space.
- *
- * Plus the pure helpers (parseCompanySlugFromPath, toBucketRelative,
- * toCompanyAnchored, classifyAclSource, assertOutPathOutsideCompanies,
- * formatBrowseTable).
- */
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { Command } from "commander";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { Readable, Writable } from "node:stream";
-
-import {
-  assertOutPathOutsideCompanies,
-  classifyAclSource,
-  formatBrowseTable,
-  parseCompanySlugFromPath,
-  toBucketRelative,
-  toCompanyAnchored,
-  runBrowse,
-  runCat,
-  runSearch,
-  runGet,
-  readPins,
-  addPin,
-  pinFilePath,
-  runSharedWithMe,
-  formatSharedWithMeTable,
-  createCompanyPresignClient,
-  type BrowseVendResult,
-  type FilesBrowseS3Client,
-  type FilesBrowseVaultClient,
-  type FilesSharedWithMeVaultClient,
-  type S3ClientFactory,
-  type CompanyBrowseClientFactory,
-} from "./files-browse.js";
-import type { ExplicitGrant } from "@indigoai-us/hq-cloud";
-import {
-  ListObjectsV2Command,
-  GetObjectCommand,
-  type ListObjectsV2CommandOutput,
-  type GetObjectCommandOutput,
-} from "@aws-sdk/client-s3";
-
-// ── Fixtures ────────────────────────────────────────────────────────────────
-
-let tmpRoot: string;
-
-beforeEach(() => {
-  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-files-browse-"));
-  // Create the companies/ subtree so the guard has a real path to compare
-  // against (the guard's check is string-level so this isn't strictly
-  // required, but it mirrors the real layout).
-  fs.mkdirSync(path.join(tmpRoot, "companies", "indigo"), { recursive: true });
-});
-
-afterEach(() => {
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
-  vi.restoreAllMocks();
-});
-
-function fakeGrant(p: string): ExplicitGrant {
-  return {
-    companyUid: "cmp_indigo",
-    path: p,
-    permission: "read",
-    source: "person",
-  };
-}
-
-function fakeStsVend(): BrowseVendResult {
-  return {
-    credentials: {
-      accessKeyId: "ASIA-test",
-      secretAccessKey: "secret-test",
-      sessionToken: "session-test",
-    },
-  };
-}
-
-interface StubVaultOpts {
-  grants?: ExplicitGrant[];
-  entity?:
-    | { uid: string; slug: string; name?: string; bucketName?: string }
-    | null;
-}
-
-function makeStubVaultClient(opts: StubVaultOpts = {}): {
-  client: FilesBrowseVaultClient;
-  spies: {
-    stsVend: ReturnType<typeof vi.fn>;
-    vendSelf: ReturnType<typeof vi.fn>;
-    listMyExplicitGrants: ReturnType<typeof vi.fn>;
-    findInMyNamespace: ReturnType<typeof vi.fn>;
-  };
-} {
-  const entity =
-    opts.entity === null
-      ? null
-      : (opts.entity ?? {
-          uid: "cmp_indigo",
-          slug: "indigo",
-          name: "Indigo",
-          bucketName: "hq-vault-cmp-indigo",
-        });
-  const stsVend = vi.fn(async () => fakeStsVend());
-  const vendSelf = vi.fn(async () => fakeStsVend());
-  const listMyExplicitGrants = vi.fn(async () => opts.grants ?? []);
-  const findInMyNamespace = vi.fn(async () => entity);
-  const get = vi.fn(async (uid: string) => {
-    if (!entity) throw new Error(`entity ${uid} not found`);
-    return entity;
-  });
-  const client: FilesBrowseVaultClient = {
-    sts: { vend: stsVend, vendSelf },
-    listMyExplicitGrants,
-    entity: { get, findInMyNamespace },
-  };
-  return {
-    client,
-    spies: { stsVend, vendSelf, listMyExplicitGrants, findInMyNamespace },
-  };
-}
-
-interface StubS3Opts {
-  listResponses?: ListObjectsV2CommandOutput[];
-  getResponse?: GetObjectCommandOutput;
-}
-
-function makeStubS3Factory(opts: StubS3Opts): {
-  factory: S3ClientFactory;
-  /**
-   * The SAME stub typed as a company-mode client factory. Company browse/cat/
-   * get/search now inject `companyClient` (the presign/list seam) instead of
-   * `s3Factory`; the stub ignores its factory arg either way, so one stub
-   * serves both. Personal-mode tests use `factory`; company-mode tests use
-   * `companyFactory`.
-   */
-  companyFactory: CompanyBrowseClientFactory;
-  sendSpy: ReturnType<typeof vi.fn>;
-  factorySpy: ReturnType<typeof vi.fn>;
-} {
-  const responses = [...(opts.listResponses ?? [])];
-  const sendSpy = vi.fn(async (cmd: unknown) => {
-    if (cmd instanceof ListObjectsV2Command) {
-      const next = responses.shift() ?? { Contents: [] };
-      return next;
-    }
-    if (cmd instanceof GetObjectCommand) {
-      return opts.getResponse ?? { Body: undefined };
-    }
-    throw new Error(`unexpected command: ${cmd}`);
-  });
-  const factorySpy = vi.fn(
-    () =>
-      ({
-        send: sendSpy,
-      }) as unknown as FilesBrowseS3Client,
-  );
-  return {
-    factory: factorySpy as unknown as S3ClientFactory,
-    companyFactory: factorySpy as unknown as CompanyBrowseClientFactory,
-    sendSpy,
-    factorySpy,
-  };
-}
-
-// ── parseCompanySlugFromPath ────────────────────────────────────────────────
-
-describe("parseCompanySlugFromPath", () => {
-  it("extracts slug from a canonical prefix", () => {
-    expect(parseCompanySlugFromPath("companies/indigo/scratch/")).toBe("indigo");
-  });
-
-  it("tolerates leading slashes", () => {
-    expect(parseCompanySlugFromPath("/companies/acme/foo")).toBe("acme");
-  });
-
-  it("rejects paths not anchored at companies/", () => {
-    expect(() => parseCompanySlugFromPath("personal/notes/")).toThrow(
-      /Expected a path starting with 'companies\//,
-    );
-    expect(() => parseCompanySlugFromPath("")).toThrow();
-    expect(() => parseCompanySlugFromPath("companies/")).toThrow();
-  });
-});
-
-// ── toBucketRelative / toCompanyAnchored (namespace translation) ────────────
-
-describe("toBucketRelative", () => {
-  it("strips the companies/<slug>/ anchor to a company-relative key", () => {
-    expect(toBucketRelative("companies/indigo/knowledge/foo.md", "indigo")).toBe(
-      "knowledge/foo.md",
-    );
-  });
-
-  it("strips the anchor for a bare prefix (trailing slash preserved)", () => {
-    expect(toBucketRelative("companies/indigo/scratch/", "indigo")).toBe(
-      "scratch/",
-    );
-  });
-
-  it("yields empty string for the bare company root", () => {
-    expect(toBucketRelative("companies/indigo/", "indigo")).toBe("");
-  });
-
-  it("tolerates leading slashes", () => {
-    expect(toBucketRelative("/companies/indigo/x/y", "indigo")).toBe("x/y");
-  });
-
-  it("passes through a path that lacks the anchor (e.g. already relative)", () => {
-    expect(toBucketRelative("knowledge/foo.md", "indigo")).toBe(
-      "knowledge/foo.md",
-    );
-  });
-
-  it("does not strip a different company's anchor", () => {
-    expect(toBucketRelative("companies/acme/x", "indigo")).toBe(
-      "companies/acme/x",
-    );
-  });
-});
-
-describe("toCompanyAnchored", () => {
-  it("re-attaches the companies/<slug>/ anchor", () => {
-    expect(toCompanyAnchored("knowledge/foo.md", "indigo")).toBe(
-      "companies/indigo/knowledge/foo.md",
-    );
-  });
-
-  it("round-trips with toBucketRelative", () => {
-    const anchored = "companies/indigo/a/b/c.md";
-    expect(toCompanyAnchored(toBucketRelative(anchored, "indigo"), "indigo")).toBe(
-      anchored,
-    );
-  });
-});
-
-// ── classifyAclSource ───────────────────────────────────────────────────────
-
-describe("classifyAclSource", () => {
-  it("returns shared-with-you when any grant prefix covers the key", () => {
-    expect(classifyAclSource("scratch/foo.txt", ["scratch/"])).toBe(
-      "shared-with-you",
-    );
-  });
-
-  it("returns role-bypass when no grant prefix covers the key", () => {
-    expect(classifyAclSource("secrets/db.txt", ["scratch/"])).toBe(
-      "role-bypass",
-    );
-  });
-
-  it("returns role-bypass on an empty grant list", () => {
-    expect(classifyAclSource("anything/x", [])).toBe("role-bypass");
-  });
-
-  it("treats an empty-string prefix as a company-wide grant (shared)", () => {
-    expect(classifyAclSource("anything/x", [""])).toBe("shared-with-you");
-  });
-
-  it("matches against the first covering prefix — multiple are fine", () => {
-    expect(
-      classifyAclSource("scratch/sub/y.bin", ["other/", "scratch/"]),
-    ).toBe("shared-with-you");
-  });
-});
-
-// ── assertOutPathOutsideCompanies (writes-guard) ───────────────────────────
-
-describe("assertOutPathOutsideCompanies", () => {
-  it("refuses a destination directly under <hqRoot>/companies/", () => {
-    const dest = path.join(tmpRoot, "companies", "indigo", "leaked.txt");
-    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow(
-      /Refusing to write/,
-    );
-  });
-
-  it("refuses a destination deep under <hqRoot>/companies/", () => {
-    const dest = path.join(
-      tmpRoot,
-      "companies",
-      "indigo",
-      "scratch",
-      "deep",
-      "leaked.txt",
-    );
-    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow();
-  });
-
-  it("refuses the bare companies/ root", () => {
-    const dest = path.join(tmpRoot, "companies");
-    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).toThrow();
-  });
-
-  it("permits a destination outside <hqRoot>/companies/ (e.g. /tmp)", () => {
-    const dest = path.join(tmpRoot, "scratch.txt");
-    expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).not.toThrow();
-    expect(assertOutPathOutsideCompanies(dest, tmpRoot)).toBe(
-      path.resolve(dest),
-    );
-  });
-
-  it("permits an absolute path under /tmp that is unrelated to hqRoot", () => {
-    // Use a sibling tmp dir as the "outside" location so the test is
-    // platform-portable (no hard-coded /tmp/foo paths).
-    const otherRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-out-"));
-    try {
-      const dest = path.join(otherRoot, "leaked.txt");
-      expect(() => assertOutPathOutsideCompanies(dest, tmpRoot)).not.toThrow();
-    } finally {
-      fs.rmSync(otherRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("refuses a relative path that resolves under companies/", () => {
-    // On macOS the OS tmp dir is a symlink (`/tmp` → `/private/tmp`,
-    // `/var/folders/...` is the canonical form). Resolving the realpath
-    // on both sides keeps `path.resolve`'s output and the guard's
-    // protected-root match on the same physical tree, so a cwd-relative
-    // "companies/indigo/…" lookup is correctly classified as protected.
-    const realRoot = fs.realpathSync(tmpRoot);
-    const cwd = process.cwd();
-    process.chdir(realRoot);
-    try {
-      expect(() =>
-        assertOutPathOutsideCompanies("companies/indigo/foo.txt", realRoot),
-      ).toThrow();
-    } finally {
-      process.chdir(cwd);
-    }
-  });
-});
-
-// ── formatBrowseTable ───────────────────────────────────────────────────────
-
-describe("formatBrowseTable", () => {
-  it("renders an empty marker when no rows", () => {
-    expect(formatBrowseTable([])).toMatch(/No objects/);
-  });
-
-  it("includes key, size, modified, and ACL source in the row", () => {
-    const out = formatBrowseTable([
-      {
-        key: "companies/indigo/scratch/a.txt",
-        size: 42,
-        lastModified: new Date("2026-01-15T10:00:00Z"),
-        aclSource: "shared-with-you",
-      },
-    ]);
-    expect(out).toContain("companies/indigo/scratch/a.txt");
-    expect(out).toContain("42");
-    expect(out).toContain("2026-01-15");
-    expect(out).toContain("shared-with-you");
-  });
-});
-
-// ── runBrowse ───────────────────────────────────────────────────────────────
-
-describe("runBrowse", () => {
-  it("company mode lists via the presign/list client (no STS vend) on the company-relative prefix", async () => {
-    const { client, spies } = makeStubVaultClient({});
-    const { companyFactory, sendSpy } = makeStubS3Factory({
-      listResponses: [{ Contents: [] }],
-    });
-    await runBrowse({
-      pathPrefix: "companies/indigo/scratch/",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-    // HQ-59: company browse no longer vends STS creds — it goes through the
-    // server-side list API, so NEITHER vend route is touched.
-    expect(spies.stsVend).not.toHaveBeenCalled();
-    expect(spies.vendSelf).not.toHaveBeenCalled();
-    // List prefix is company-relative (the bug: was anchored → 0 results).
-    const listCmd = sendSpy.mock.calls[0][0] as ListObjectsV2Command;
-    expect(listCmd.input.Prefix).toBe("scratch/");
-  });
-
-  it("paginates ListObjectsV2 fully, classifies ACL, and re-anchors keys for display", async () => {
-    const { client } = makeStubVaultClient({
-      // Real grants are glob/anchored; normalization folds this to "scratch/".
-      grants: [fakeGrant("companies/indigo/scratch/*")],
-    });
-    const { companyFactory, sendSpy } = makeStubS3Factory({
-      // List objects are company-relative (no companies/<slug>/ prefix).
-      listResponses: [
-        {
-          Contents: [
-            {
-              Key: "scratch/a.txt",
-              Size: 10,
-              LastModified: new Date("2026-01-01T00:00:00Z"),
-            },
-            {
-              Key: "secrets/db.txt",
-              Size: 20,
-              LastModified: new Date("2026-01-02T00:00:00Z"),
-            },
-          ],
-          NextContinuationToken: "page2",
-        },
-        {
-          Contents: [
-            {
-              Key: "scratch/sub/b.bin",
-              Size: 30,
-              LastModified: new Date("2026-01-03T00:00:00Z"),
-            },
-            // S3 directory marker — should be filtered out.
-            {
-              Key: "scratch/empty/",
-              Size: 0,
-              LastModified: new Date("2026-01-04T00:00:00Z"),
-            },
-          ],
-        },
-      ],
-    });
-    const result = await runBrowse({
-      pathPrefix: "companies/indigo/scratch/",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-    expect(sendSpy).toHaveBeenCalledTimes(2); // pagination
-    expect(result.rows).toHaveLength(3);
-    // Displayed keys are re-anchored to companies/<slug>/.
-    const byKey = Object.fromEntries(result.rows.map((r) => [r.key, r]));
-    expect(byKey["companies/indigo/scratch/a.txt"].aclSource).toBe(
-      "shared-with-you",
-    );
-    expect(byKey["companies/indigo/scratch/sub/b.bin"].aclSource).toBe(
-      "shared-with-you",
-    );
-    // Visible only via role-bypass — this is the leak-out-of-grant case.
-    expect(byKey["companies/indigo/secrets/db.txt"].aclSource).toBe(
-      "role-bypass",
-    );
-  });
-
-  it("throws when the slug doesn't resolve in the caller's namespace", async () => {
-    const { client } = makeStubVaultClient({ entity: null });
-    const { factory } = makeStubS3Factory({ listResponses: [] });
-    await expect(
-      runBrowse({
-        pathPrefix: "companies/notmine/scratch/",
-        vaultClient: client,
-        s3Factory: factory,
-        region: "us-east-1",
-      }),
-    ).rejects.toThrow(/No company found for slug 'notmine'/);
-  });
-
-  // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
-  //
-  // Personal mode resolves the entity via `entity.get(personalUid)` (skipping
-  // the company-namespace lookup), vends via `/sts/vend-self`, omits the
-  // explicit-grants fetch, and tags every row `aclSource: "personal-vault"`.
-  // The path arg is bucket-relative — companies/<slug>/ prefix is NOT required.
-
-  it("personalMode: resolves via entity.get, vends /sts/vend-self, skips namespace + grants", async () => {
-    const { client, spies } = makeStubVaultClient({
-      entity: {
-        uid: "prs_test",
-        slug: "personal",
-        bucketName: "hq-vault-prs-test",
-      },
-    });
-    const { factory } = makeStubS3Factory({
-      listResponses: [
-        {
-          Contents: [{ Key: ".claude/CLAUDE.md", Size: 100, LastModified: new Date() }],
-        },
-      ],
-    });
-
-    const result = await runBrowse({
-      pathPrefix: ".claude/",
-      personalMode: true,
-      personalUid: "prs_test",
-      vaultClient: client,
-      s3Factory: factory,
-      region: "us-east-1",
-    });
-
-    expect(result.rows).toHaveLength(1);
-    expect(result.rows[0].key).toBe(".claude/CLAUDE.md");
-    // findInMyNamespace is the company-mode lookup — must not be touched.
-    expect(spies.findInMyNamespace).not.toHaveBeenCalled();
-    // Grants graph is a company concept — must not be fetched.
-    expect(spies.listMyExplicitGrants).not.toHaveBeenCalled();
-    // Personal vends self, never the company route.
-    expect(spies.vendSelf).toHaveBeenCalledWith({ personUid: "prs_test" });
-    expect(spies.stsVend).not.toHaveBeenCalled();
-  });
-
-  it("personalMode: empty pathPrefix lists the bucket root", async () => {
-    const { client } = makeStubVaultClient({
-      entity: { uid: "prs_test", slug: "personal", bucketName: "hq-vault-prs-test" },
-    });
-    const { factory, sendSpy } = makeStubS3Factory({
-      listResponses: [
-        {
-          Contents: [
-            { Key: ".claude/CLAUDE.md", Size: 100, LastModified: new Date() },
-            { Key: "core/policies/foo.md", Size: 50, LastModified: new Date() },
-          ],
-        },
-      ],
-    });
-
-    const result = await runBrowse({
-      pathPrefix: "",
-      personalMode: true,
-      personalUid: "prs_test",
-      vaultClient: client,
-      s3Factory: factory,
-      region: "us-east-1",
-    });
-
-    expect(result.rows).toHaveLength(2);
-    // ListObjectsV2 issued with an empty Prefix means "list everything".
-    const listCmd = sendSpy.mock.calls[0][0] as ListObjectsV2Command;
-    expect(listCmd.input.Prefix).toBe("");
-  });
-
-  it("personalMode: every row is tagged aclSource='personal-vault'", async () => {
-    const { client } = makeStubVaultClient({
-      entity: { uid: "prs_test", slug: "personal", bucketName: "hq-vault-prs-test" },
-      // Note: even if grants WERE present, personalMode would skip the
-      // lookup entirely — no chance of accidentally tagging a personal
-      // key as `shared-with-you`.
-      grants: [fakeGrant("companies/indigo/")],
-    });
-    const { factory } = makeStubS3Factory({
-      listResponses: [
-        {
-          Contents: [
-            { Key: ".claude/CLAUDE.md", Size: 1, LastModified: new Date() },
-            { Key: "core/policies/_digest.md", Size: 2, LastModified: new Date() },
-            { Key: "personal/notes.md", Size: 3, LastModified: new Date() },
-          ],
-        },
-      ],
-    });
-
-    const result = await runBrowse({
-      pathPrefix: "",
-      personalMode: true,
-      personalUid: "prs_test",
-      vaultClient: client,
-      s3Factory: factory,
-      region: "us-east-1",
-    });
-
-    for (const row of result.rows) {
-      expect(row.aclSource).toBe("personal-vault");
-    }
-  });
-
-  it("personalMode: throws when personalUid is missing", async () => {
-    const { client } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({});
-
-    await expect(
-      runBrowse({
-        pathPrefix: "",
-        personalMode: true,
-        // personalUid intentionally omitted
-        vaultClient: client,
-        s3Factory: factory,
-        region: "us-east-1",
-      }),
-    ).rejects.toThrow(/personalMode requires personalUid/);
-  });
-
-  it("personalMode: throws when entity has no provisioned bucket", async () => {
-    // Force entity.get to return a bucket-less entity.
-    const { client } = makeStubVaultClient({
-      entity: { uid: "prs_test", slug: "personal" },
-    });
-    const { factory } = makeStubS3Factory({});
-
-    await expect(
-      runBrowse({
-        pathPrefix: "",
-        personalMode: true,
-        personalUid: "prs_test",
-        vaultClient: client,
-        s3Factory: factory,
-        region: "us-east-1",
-      }),
-    ).rejects.toThrow(/no provisioned bucket/);
-  });
-});
-
-// ── runCat ──────────────────────────────────────────────────────────────────
-
-describe("runCat", () => {
-  it("company mode fetches the company-relative key via presign (no STS vend)", async () => {
-    const { client, spies } = makeStubVaultClient({});
-    const { companyFactory, sendSpy } = makeStubS3Factory({
-      getResponse: {
-        Body: Readable.from(Buffer.from("hello world")),
-      } as GetObjectCommandOutput,
-    });
-    // Drain to a sink so process.stdout isn't touched.
-    const sink = new Writable({ write(_c, _e, cb) { cb(); } });
-    await runCat({
-      key: "companies/indigo/scratch/a.txt",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-      hqRoot: tmpRoot,
-      stdout: sink,
-    });
-    // HQ-59: company cat goes through the presign API — no STS vend.
-    expect(spies.stsVend).not.toHaveBeenCalled();
-    expect(spies.vendSelf).not.toHaveBeenCalled();
-    // GetObject key is company-relative (anchor stripped).
-    const getCmd = sendSpy.mock.calls.find(
-      (c) => c[0] instanceof GetObjectCommand,
-    )?.[0] as GetObjectCommand;
-    expect(getCmd.input.Key).toBe("scratch/a.txt");
-  });
-
-  it("writes to --out when outside the companies tree and reports byte count", async () => {
-    const { client } = makeStubVaultClient({});
-    const payload = Buffer.from("safe-payload");
-    const { companyFactory } = makeStubS3Factory({
-      getResponse: {
-        Body: Readable.from(payload),
-      } as GetObjectCommandOutput,
-    });
-    const outFile = path.join(tmpRoot, "safe.txt");
-    const result = await runCat({
-      key: "companies/indigo/scratch/a.txt",
-      out: outFile,
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-      hqRoot: tmpRoot,
-    });
-    expect(result.destination).toEqual({ kind: "file", absPath: outFile });
-    expect(fs.readFileSync(outFile, "utf-8")).toBe("safe-payload");
-    expect(result.bytesWritten).toBe(payload.length);
-  });
-
-  it("refuses --out under <hqRoot>/companies/ BEFORE vending (no leak)", async () => {
-    const { client, spies } = makeStubVaultClient({});
-    const { companyFactory, sendSpy } = makeStubS3Factory({
-      getResponse: { Body: Readable.from(Buffer.from("nope")) } as GetObjectCommandOutput,
-    });
-    const badOut = path.join(tmpRoot, "companies", "indigo", "leaked.txt");
-    await expect(
-      runCat({
-        key: "companies/indigo/scratch/a.txt",
-        out: badOut,
-        vaultClient: client,
-        companyClient: companyFactory,
-        region: "us-east-1",
-        hqRoot: tmpRoot,
-      }),
-    ).rejects.toThrow(/Refusing to write/);
-    // Critically: the guard runs FIRST — no vend, and no list/presign/S3 call
-    // was made. Failing closed is the whole point of the guard.
-    expect(spies.stsVend).not.toHaveBeenCalled();
-    expect(spies.vendSelf).not.toHaveBeenCalled();
-    expect(sendSpy).not.toHaveBeenCalled();
-    // And no file was written under the protected tree.
-    expect(fs.existsSync(badOut)).toBe(false);
-  });
-
-  it("rejects a vault key that isn't anchored at companies/", async () => {
-    const { client } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({});
-    await expect(
-      runCat({
-        key: "personal/notes/x.txt",
-        vaultClient: client,
-        s3Factory: factory,
-        region: "us-east-1",
-        hqRoot: tmpRoot,
-      }),
-    ).rejects.toThrow(/Expected a path starting with 'companies\//);
-  });
-
-  // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
-
-  it("personalMode: streams from the person bucket via /sts/vend-self, no slug parse", async () => {
-    const { client, spies } = makeStubVaultClient({
-      entity: { uid: "prs_test", slug: "personal", bucketName: "hq-vault-prs-test" },
-    });
-    const body = new Readable({
-      read() {
-        this.push("hello personal");
-        this.push(null);
-      },
-    });
-    const { factory, sendSpy } = makeStubS3Factory({
-      getResponse: { Body: body as unknown as GetObjectCommandOutput["Body"] },
-    });
-
-    // The key has no `companies/<slug>/` prefix — would normally fail
-    // parseCompanySlugFromPath. Under personalMode, that parse is skipped.
-    const sink = new Writable({
-      write(_chunk, _enc, cb) {
-        cb();
-      },
-    });
-    const result = await runCat({
-      key: ".claude/CLAUDE.md",
-      personalMode: true,
-      personalUid: "prs_test",
-      vaultClient: client,
-      s3Factory: factory,
-      region: "us-east-1",
-      hqRoot: tmpRoot,
-      stdout: sink,
-    });
-
-    expect(result.destination.kind).toBe("stdout");
-    expect(spies.findInMyNamespace).not.toHaveBeenCalled();
-    // Personal vends self, against the bucket-relative key.
-    expect(spies.vendSelf).toHaveBeenCalledWith({ personUid: "prs_test" });
-    expect(spies.stsVend).not.toHaveBeenCalled();
-    // GetObject targeted the person bucket with the bucket-relative key.
-    const getCmd = sendSpy.mock.calls.find(
-      (c) => c[0] instanceof GetObjectCommand,
-    )?.[0] as GetObjectCommand;
-    expect(getCmd.input.Bucket).toBe("hq-vault-prs-test");
-    expect(getCmd.input.Key).toBe(".claude/CLAUDE.md");
-  });
-
-  it("personalMode: throws when personalUid is missing", async () => {
-    const { client } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({});
-    await expect(
-      runCat({
-        key: ".claude/CLAUDE.md",
-        personalMode: true,
-        // personalUid omitted
-        vaultClient: client,
-        s3Factory: factory,
-        region: "us-east-1",
-        hqRoot: tmpRoot,
-      }),
-    ).rejects.toThrow(/personalMode requires personalUid/);
-  });
-});
-
-// ── runSharedWithMe ──────────────────────────────────────────────────────────
-
-function sharedWithMeClient(opts: {
-  memberships?: Array<{ companyUid: string }>;
-  grantsByCompany?: Record<string, ExplicitGrant[]>;
-  slugByUid?: Record<string, string>;
-}): FilesSharedWithMeVaultClient {
-  return {
-    listMyMemberships: async () => opts.memberships ?? [],
-    listMyExplicitGrants: async (companyUid: string) =>
-      opts.grantsByCompany?.[companyUid] ?? [],
-    entity: {
-      get: async (uid: string) => ({
-        uid,
-        slug: opts.slugByUid?.[uid] ?? uid,
-      }),
-    },
-  };
-}
-
-describe("runSharedWithMe", () => {
-  it("lists explicit grants for a single company (companyUid supplied)", async () => {
-    const rows = await runSharedWithMe({
-      vaultClient: sharedWithMeClient({
-        grantsByCompany: {
-          cmp_indigo: [fakeGrant("knowledge/"), fakeGrant("reports/q3.pdf")],
-        },
-      }),
-      companyUid: "cmp_indigo",
-      companySlug: "indigo",
-    });
-    expect(rows).toEqual([
-      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
-      { companySlug: "indigo", path: "reports/q3.pdf", permission: "read", source: "person" },
-    ]);
-  });
-
-  it("rolls up across every membership when no company is supplied", async () => {
-    const rows = await runSharedWithMe({
-      vaultClient: sharedWithMeClient({
-        memberships: [{ companyUid: "cmp_b" }, { companyUid: "cmp_a" }],
-        slugByUid: { cmp_a: "acme", cmp_b: "beta" },
-        grantsByCompany: {
-          cmp_a: [fakeGrant("docs/")],
-          cmp_b: [fakeGrant("shared/")],
-        },
-      }),
-    });
-    // Sorted by company slug, then path.
-    expect(rows.map((r) => [r.companySlug, r.path])).toEqual([
-      ["acme", "docs/"],
-      ["beta", "shared/"],
-    ]);
-  });
-
-  it("skips a company whose grant fetch throws (best-effort roll-up)", async () => {
-    const client: FilesSharedWithMeVaultClient = {
-      listMyMemberships: async () => [{ companyUid: "cmp_ok" }, { companyUid: "cmp_bad" }],
-      listMyExplicitGrants: async (uid: string) => {
-        if (uid === "cmp_bad") throw new Error("boom");
-        return [fakeGrant("ok/")];
-      },
-      entity: { get: async (uid: string) => ({ uid, slug: uid }) },
-    };
-    const rows = await runSharedWithMe({ vaultClient: client });
-    expect(rows).toEqual([
-      { companySlug: "cmp_ok", path: "ok/", permission: "read", source: "person" },
-    ]);
-  });
-
-  it("formats an empty result with the role-bypass caveat", () => {
-    const out = formatSharedWithMeTable([]);
-    expect(out).toContain("Nothing is explicitly shared with you");
-    expect(out).toContain("role-bypass");
-  });
-
-  it("formats rows as a table with company + path + permission + source", () => {
-    const out = formatSharedWithMeTable([
-      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
-    ]);
-    expect(out).toContain("COMPANY");
-    expect(out).toContain("indigo");
-    expect(out).toContain("knowledge/");
-  });
-});
-
-// ── runSearch ─────────────────────────────────────────────────────────────
-
-describe("runSearch", () => {
-  it("filters the company listing by case-insensitive substring on the key", async () => {
-    const { client, spies } = makeStubVaultClient({});
-    const { companyFactory } = makeStubS3Factory({
-      listResponses: [
-        {
-          Contents: [
-            { Key: "knowledge/Roadmap.md", Size: 1, LastModified: new Date() },
-            { Key: "reports/q3.pdf", Size: 2, LastModified: new Date() },
-            { Key: "knowledge/notes.md", Size: 3, LastModified: new Date() },
-          ],
-        },
-      ],
-    });
-    const rows = await runSearch({
-      query: "roadmap", // lower-case query matches mixed-case key
-      companySlug: "indigo",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-    // Keys are re-anchored for display; only the matching one survives.
-    expect(rows.map((r) => r.key)).toEqual([
-      "companies/indigo/knowledge/Roadmap.md",
-    ]);
-    // HQ-59: search lists via the presign/list API (inherited from runBrowse) —
-    // no STS vend.
-    expect(spies.stsVend).not.toHaveBeenCalled();
-  });
-
-  it("returns an empty array when nothing matches", async () => {
-    const { client } = makeStubVaultClient({});
-    const { companyFactory } = makeStubS3Factory({
-      listResponses: [
-        { Contents: [{ Key: "knowledge/a.md", Size: 1, LastModified: new Date() }] },
-      ],
-    });
-    const rows = await runSearch({
-      query: "zzz-no-match",
-      companySlug: "indigo",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-    expect(rows).toEqual([]);
-  });
-});
-
-// ── pin set (readPins / addPin) ─────────────────────────────────────────────
-
-describe("pin set", () => {
-  it("readPins returns an empty set when the file is missing", () => {
-    expect(readPins(tmpRoot)).toEqual({ version: 1, pins: {} });
-  });
-
-  it("addPin creates the file, dedups, and sorts prefixes", () => {
-    addPin(tmpRoot, "indigo", "knowledge/");
-    addPin(tmpRoot, "indigo", "knowledge/"); // duplicate — ignored
-    addPin(tmpRoot, "indigo", "data/");
-    const pf = readPins(tmpRoot);
-    expect(pf.pins.indigo).toEqual(["data/", "knowledge/"]);
-    expect(fs.existsSync(pinFilePath(tmpRoot))).toBe(true);
-  });
-
-  it("addPin keeps per-company lists separate", () => {
-    addPin(tmpRoot, "indigo", "knowledge/");
-    addPin(tmpRoot, "acme", "docs/");
-    const pf = readPins(tmpRoot);
-    expect(pf.pins).toEqual({ indigo: ["knowledge/"], acme: ["docs/"] });
-  });
-
-  it("readPins tolerates a corrupt pins.json (→ fresh)", () => {
-    fs.mkdirSync(path.dirname(pinFilePath(tmpRoot)), { recursive: true });
-    fs.writeFileSync(pinFilePath(tmpRoot), "{ not valid json");
-    expect(readPins(tmpRoot)).toEqual({ version: 1, pins: {} });
-  });
-});
-
-// ── runGet ────────────────────────────────────────────────────────────────
-
-function makeGetStubS3(opts: {
-  listKeys: Array<{ Key: string; Size: number }>;
-  bodyFor: (key: string) => Buffer;
-}): { companyFactory: CompanyBrowseClientFactory; sendSpy: ReturnType<typeof vi.fn> } {
-  const sendSpy = vi.fn(async (cmd: unknown) => {
-    if (cmd instanceof ListObjectsV2Command) {
-      return {
-        Contents: opts.listKeys.map((k) => ({ ...k, LastModified: new Date() })),
-      } as ListObjectsV2CommandOutput;
-    }
-    if (cmd instanceof GetObjectCommand) {
-      const key = (cmd as GetObjectCommand).input.Key as string;
-      return {
-        Body: Readable.from(opts.bodyFor(key)),
-      } as unknown as GetObjectCommandOutput;
-    }
-    throw new Error(`unexpected command: ${cmd}`);
-  });
-  // `get` is company-only now, so the stub is the presign/list seam.
-  const companyFactory = vi.fn(
-    () => ({ send: sendSpy }) as unknown as FilesBrowseS3Client,
-  ) as unknown as CompanyBrowseClientFactory;
-  return { companyFactory, sendSpy };
-}
-
-describe("runGet", () => {
-  it("materializes a prefix in-place under companies/<slug>/ and registers a pin", async () => {
-    const { client, spies } = makeStubVaultClient({});
-    const { companyFactory, sendSpy } = makeGetStubS3({
-      listKeys: [
-        { Key: "knowledge/a.md", Size: 3 },
-        { Key: "knowledge/sub/b.md", Size: 3 },
-      ],
-      bodyFor: (k) => Buffer.from(k === "knowledge/a.md" ? "AAA" : "BBB"),
-    });
-
-    const result = await runGet({
-      path: "companies/indigo/knowledge/",
-      hqRoot: tmpRoot,
-      companySlug: "indigo",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-
-    // HQ-59: get materializes through the presign/list API — no STS vend.
-    expect(spies.stsVend).not.toHaveBeenCalled();
-    expect(result.filesWritten).toBe(2);
-
-    // Files landed in place under companies/<slug>/.
-    expect(
-      fs.readFileSync(
-        path.join(tmpRoot, "companies", "indigo", "knowledge", "a.md"),
-        "utf-8",
-      ),
-    ).toBe("AAA");
-    expect(
-      fs.readFileSync(
-        path.join(tmpRoot, "companies", "indigo", "knowledge", "sub", "b.md"),
-        "utf-8",
-      ),
-    ).toBe("BBB");
-
-    // GetObject used company-relative keys (no companies/<slug>/ anchor).
-    const getKeys = sendSpy.mock.calls
-      .filter((c) => c[0] instanceof GetObjectCommand)
-      .map((c) => (c[0] as GetObjectCommand).input.Key);
-    expect(getKeys).toEqual(["knowledge/a.md", "knowledge/sub/b.md"]);
-
-    // Pin registered for the in-place prefix.
-    expect(readPins(tmpRoot).pins.indigo).toEqual(["knowledge/"]);
-    expect(result.pinned).toEqual({ companySlug: "indigo", prefix: "knowledge/" });
-  });
-
-  it("--into writes outside companies/ and registers NO pin", async () => {
-    const into = path.join(tmpRoot, "extract");
-    const { client } = makeStubVaultClient({});
-    const { companyFactory } = makeGetStubS3({
-      listKeys: [{ Key: "knowledge/a.md", Size: 3 }],
-      bodyFor: () => Buffer.from("AAA"),
-    });
-
-    const result = await runGet({
-      path: "companies/indigo/knowledge/",
-      into,
-      hqRoot: tmpRoot,
-      companySlug: "indigo",
-      vaultClient: client,
-      companyClient: companyFactory,
-      region: "us-east-1",
-    });
-
-    // Written relative to the requested prefix, under --into.
-    expect(fs.readFileSync(path.join(into, "a.md"), "utf-8")).toBe("AAA");
-    // No pin — --into is outside the sync envelope.
-    expect(result.pinned).toBeUndefined();
-    expect(fs.existsSync(pinFilePath(tmpRoot))).toBe(false);
-  });
-
-  it("throws when no objects exist under the path", async () => {
-    const { client } = makeStubVaultClient({});
-    const { companyFactory } = makeGetStubS3({
-      listKeys: [],
-      bodyFor: () => Buffer.from(""),
-    });
-    await expect(
-      runGet({
-        path: "companies/indigo/nope/",
-        hqRoot: tmpRoot,
-        companySlug: "indigo",
-        vaultClient: client,
-        companyClient: companyFactory,
-        region: "us-east-1",
-      }),
-    ).rejects.toThrow(/No objects under/);
-  });
-});
-
-// ── --company parent-binding (regression) ───────────────────────────────────
-//
-// The `files` parent group declares `--company`, so commander binds the flag
-// to the PARENT command, not the subcommand — `subcommand.opts().company` is
-// empty. The browse/cat/search/get/shared-with-me actions therefore resolve
-// it via `command.optsWithGlobals().company`. This guards that contract so a
-// future refactor doesn't silently regress `hq files <sub> ... --company X`
-// back to the swallowed-flag bug.
-
-describe("--company parent binding (optsWithGlobals)", () => {
-  it("a subcommand sees --company declared on the parent group", () => {
-    const program = new Command();
-    const files = program
-      .command("files")
-      .option("--company <slug>", "Company slug");
-    let seen: string | undefined = "UNSET";
-    files
-      .command("search <query>")
-      .option("--personal")
-      .action((_query: string, _options: unknown, command: Command) => {
-        seen = command.optsWithGlobals().company as string | undefined;
-      });
-    program.parse(
-      ["files", "search", "README", "--company", "indigo"],
-      { from: "user" } as never,
-    );
-    expect(seen).toBe("indigo");
-  });
-
-  it("documents the bug: subcommand-local opts.company is empty for a parent-bound flag", () => {
-    const program = new Command();
-    const files = program
-      .command("files")
-      .option("--company <slug>", "Company slug");
-    let local: string | undefined = "UNSET";
-    files
-      .command("search <query>")
-      .action((_query: string, options: { company?: string }) => {
-        local = options.company;
-      });
-    program.parse(
-      ["files", "search", "README", "--company", "indigo"],
-      { from: "user" } as never,
-    );
-    expect(local).toBeUndefined();
-  });
-});
-
-// ── createCompanyPresignClient (HQ-59 list/presign translation) ─────────────
-//
-// The company-mode browse client. Verifies it translates the S3-shaped
-// commands the orchestrators issue into the server-side list/presign API:
-//   - ListObjectsV2Command → GET  /v1/files/list  (company-relative objects)
-//   - GetObjectCommand     → POST /v1/files/presign → fetch(url) → Body
-// fetch is the single network seam (vaultApiFetch uses it; the presigned
-// download uses it), so we spy on globalThis.fetch and route by URL.
-
-describe("createCompanyPresignClient", () => {
-  let fetchSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    fetchSpy = vi.spyOn(globalThis, "fetch");
-  });
-  afterEach(() => {
-    fetchSpy.mockRestore();
-  });
-
-  function json(status: number, body: unknown): Response {
-    return new Response(JSON.stringify(body), {
-      status,
-      headers: { "content-type": "application/json" },
-    });
-  }
-
-  it("ListObjectsV2 → GET /v1/files/list, mapping objects + cursor onto the S3 shape", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      json(200, {
-        prefix: "scratch/",
-        objects: [
-          {
-            key: "scratch/a.txt",
-            size: 12,
-            lastModified: "2026-01-01T00:00:00.000Z",
-            etag: "abc123",
-            permission: "read",
-          },
-        ],
-        cursor: "next-page",
-        truncated: true,
-      }),
-    );
-
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    const out = await client.send(
-      new ListObjectsV2Command({
-        Bucket: "ignored",
-        Prefix: "scratch/",
-        ContinuationToken: undefined,
-      }),
-    );
-
-    // Request: GET to /v1/files/list with company + prefix query, bearer token.
-    const [url, init] = fetchSpy.mock.calls[0];
-    expect(String(url)).toContain("/v1/files/list");
-    expect(String(url)).toContain("company=cmp_indigo");
-    expect(String(url)).toContain("prefix=scratch%2F");
-    expect((init?.headers as Record<string, string>).Authorization).toBe("Bearer tok");
-
-    // Response mapped onto the ListObjectsV2 shape the orchestrators read.
-    expect(out.Contents).toHaveLength(1);
-    expect(out.Contents?.[0].Key).toBe("scratch/a.txt");
-    expect(out.Contents?.[0].Size).toBe(12);
-    expect(out.Contents?.[0].ETag).toBe('"abc123"');
-    expect(out.Contents?.[0].LastModified?.toISOString()).toBe("2026-01-01T00:00:00.000Z");
-    expect(out.NextContinuationToken).toBe("next-page");
-    expect(out.IsTruncated).toBe(true);
-  });
-
-  it("ListObjectsV2 forwards the ContinuationToken as the cursor query param", async () => {
-    fetchSpy.mockResolvedValueOnce(json(200, { objects: [], cursor: null, truncated: false }));
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    await client.send(new ListObjectsV2Command({ Bucket: "b", Prefix: "k/", ContinuationToken: "page2" }));
-    expect(String(fetchSpy.mock.calls[0][0])).toContain("cursor=page2");
-  });
-
-  it("ListObjectsV2 throws on a non-2xx list response", async () => {
-    fetchSpy.mockResolvedValueOnce(json(403, { error: "Forbidden", code: "X" }));
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    await expect(
-      client.send(new ListObjectsV2Command({ Bucket: "b", Prefix: "k/" })),
-    ).rejects.toThrow(/Forbidden/);
-  });
-
-  it("GetObject → POST /v1/files/presign then fetches the URL and returns a Body", async () => {
-    // 1) presign POST → returns a URL; 2) the URL fetch → returns the bytes.
-    fetchSpy
-      .mockResolvedValueOnce(
-        json(200, { results: [{ key: "scratch/a.txt", op: "get", url: "https://s3.example/presigned" }] }),
-      )
-      .mockResolvedValueOnce(new Response("file-bytes-here", { status: 200 }));
-
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    const out = await client.send(
-      new GetObjectCommand({ Bucket: "ignored", Key: "scratch/a.txt" }),
-    );
-
-    // First call: POST presign with the right body.
-    const [presignUrl, presignInit] = fetchSpy.mock.calls[0];
-    expect(String(presignUrl)).toContain("/v1/files/presign");
-    expect(presignInit?.method).toBe("POST");
-    expect(JSON.parse(presignInit?.body as string)).toEqual({
-      company: "cmp_indigo",
-      key: "scratch/a.txt",
-      op: "get",
-    });
-    // Second call: fetch the presigned URL.
-    expect(String(fetchSpy.mock.calls[1][0])).toBe("https://s3.example/presigned");
-
-    // Body is a readable stream of the downloaded bytes.
-    const chunks: Buffer[] = [];
-    for await (const c of out.Body as unknown as AsyncIterable<Buffer>) {
-      chunks.push(Buffer.from(c));
-    }
-    expect(Buffer.concat(chunks).toString("utf-8")).toBe("file-bytes-here");
-  });
-
-  it("GetObject throws the per-key error when presign denies the key (no URL)", async () => {
-    fetchSpy.mockResolvedValueOnce(
-      json(200, {
-        results: [
-          { key: "secret/x", op: "get", error: "Caller lacks read permission on 'secret/x'", code: "FILES_PRESIGN_FORBIDDEN" },
-        ],
-      }),
-    );
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    await expect(
-      client.send(new GetObjectCommand({ Bucket: "b", Key: "secret/x" })),
-    ).rejects.toThrow(/lacks read permission/);
-    // The denial short-circuits BEFORE any download fetch.
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
-  });
-
-  it("GetObject throws when the presigned download itself fails", async () => {
-    fetchSpy
-      .mockResolvedValueOnce(
-        json(200, { results: [{ key: "k", op: "get", url: "https://s3.example/x" }] }),
-      )
-      .mockResolvedValueOnce(new Response("nope", { status: 500 }));
-    const client = createCompanyPresignClient({ token: "tok", companyUid: "cmp_indigo" });
-    await expect(
-      client.send(new GetObjectCommand({ Bucket: "b", Key: "k" })),
-    ).rejects.toThrow(/Failed to download 'k'/);
-  });
-});