@indigoai-us/hq-cli 5.28.0 → 5.30.0

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

@@ -1,17 +1,22 @@
 /**
  * Unit tests for `hq files browse` + `hq files cat` (files-browse.ts).
  *
- * Stubs VaultClient.vend / listMyExplicitGrants / entity.findInMyNamespace
- * and the S3 client so we cover the three acceptance criteria the unit
- * suite is responsible for (acceptance 6):
+ * Stubs the multi-tenant STS vend routes (`sts.vend` / `sts.vendSelf`),
+ * listMyExplicitGrants, entity.findInMyNamespace/get, and the S3 client.
+ * Coverage focus:
  *
- *   1. vend uses `purpose: 'browse'` (NOT `'sync'`) for both subcommands.
- *   2. `--out` refuses any destination under `<hqRoot>/companies/`.
- *   3. ACL-source classification: keys with a covering explicit grant →
- *      `shared-with-you`; keys with no covering grant → `role-bypass`.
+ *   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, classifyAclSource,
- * assertOutPathOutsideCompanies, formatBrowseTable).
+ * Plus the pure helpers (parseCompanySlugFromPath, toBucketRelative,
+ * toCompanyAnchored, classifyAclSource, assertOutPathOutsideCompanies,
+ * formatBrowseTable).
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -25,16 +30,24 @@ import {
   classifyAclSource,
   formatBrowseTable,
   parseCompanySlugFromPath,
+  toBucketRelative,
+  toCompanyAnchored,
   runBrowse,
   runCat,
+  runSearch,
+  runGet,
+  readPins,
+  addPin,
+  pinFilePath,
   runSharedWithMe,
   formatSharedWithMeTable,
+  type BrowseVendResult,
   type FilesBrowseS3Client,
   type FilesBrowseVaultClient,
   type FilesSharedWithMeVaultClient,
   type S3ClientFactory,
 } from "./files-browse.js";
-import type { ExplicitGrant, VendResult } from "@indigoai-us/hq-cloud";
+import type { ExplicitGrant } from "@indigoai-us/hq-cloud";
 import {
   ListObjectsV2Command,
   GetObjectCommand,
@@ -68,24 +81,17 @@ function fakeGrant(p: string): ExplicitGrant {
   };
 }
 
-function fakeVendResult(overrides: Partial<VendResult> = {}): VendResult {
+function fakeStsVend(): BrowseVendResult {
   return {
     credentials: {
       accessKeyId: "ASIA-test",
       secretAccessKey: "secret-test",
       sessionToken: "session-test",
-      expiration: new Date(Date.now() + 900_000).toISOString(),
     },
-    paths: ["companies/indigo/"],
-    operations: "read-only",
-    purpose: "browse",
-    policySize: 512,
-    ...overrides,
   };
 }
 
 interface StubVaultOpts {
-  vend?: VendResult;
   grants?: ExplicitGrant[];
   entity?:
     | { uid: string; slug: string; name?: string; bucketName?: string }
@@ -95,7 +101,8 @@ interface StubVaultOpts {
 function makeStubVaultClient(opts: StubVaultOpts = {}): {
   client: FilesBrowseVaultClient;
   spies: {
-    vend: ReturnType<typeof vi.fn>;
+    stsVend: ReturnType<typeof vi.fn>;
+    vendSelf: ReturnType<typeof vi.fn>;
     listMyExplicitGrants: ReturnType<typeof vi.fn>;
     findInMyNamespace: ReturnType<typeof vi.fn>;
   };
@@ -109,7 +116,8 @@ function makeStubVaultClient(opts: StubVaultOpts = {}): {
           name: "Indigo",
           bucketName: "hq-vault-cmp-indigo",
         });
-  const vend = vi.fn(async () => opts.vend ?? fakeVendResult());
+  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) => {
@@ -117,11 +125,14 @@ function makeStubVaultClient(opts: StubVaultOpts = {}): {
     return entity;
   });
   const client: FilesBrowseVaultClient = {
-    vend,
+    sts: { vend: stsVend, vendSelf },
     listMyExplicitGrants,
     entity: { get, findInMyNamespace },
   };
-  return { client, spies: { vend, listMyExplicitGrants, findInMyNamespace } };
+  return {
+    client,
+    spies: { stsVend, vendSelf, listMyExplicitGrants, findInMyNamespace },
+  };
 }
 
 interface StubS3Opts {
@@ -174,36 +185,83 @@ describe("parseCompanySlugFromPath", () => {
   });
 });
 
+// ── 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 prefixes the key", () => {
-    const grants = [fakeGrant("companies/indigo/scratch/")];
-    expect(
-      classifyAclSource("companies/indigo/scratch/foo.txt", grants),
-    ).toBe("shared-with-you");
+  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 covers the key", () => {
-    const grants = [fakeGrant("companies/indigo/scratch/")];
-    expect(
-      classifyAclSource("companies/indigo/secrets/db.txt", grants),
-    ).toBe("role-bypass");
+  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("companies/indigo/anything/x", [])).toBe(
-      "role-bypass",
-    );
+    expect(classifyAclSource("anything/x", [])).toBe("role-bypass");
   });
 
-  it("matches against the first covering grant — multiple grants are fine", () => {
-    const grants = [
-      fakeGrant("companies/other/"),
-      fakeGrant("companies/indigo/scratch/"),
-    ];
+  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("companies/indigo/scratch/sub/y.bin", grants),
+      classifyAclSource("scratch/sub/y.bin", ["other/", "scratch/"]),
     ).toBe("shared-with-you");
   });
 });
@@ -300,9 +358,9 @@ describe("formatBrowseTable", () => {
 // ── runBrowse ───────────────────────────────────────────────────────────────
 
 describe("runBrowse", () => {
-  it("vends with purpose='browse' (NOT 'sync') for the requested prefix", async () => {
+  it("vends via /sts/vend (company) and lists the company-relative prefix", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { factory, sendSpy } = makeStubS3Factory({
       listResponses: [{ Contents: [] }],
     });
     await runBrowse({
@@ -311,29 +369,32 @@ describe("runBrowse", () => {
       s3Factory: factory,
       region: "us-east-1",
     });
-    expect(spies.vend).toHaveBeenCalledTimes(1);
-    const arg = spies.vend.mock.calls[0][0];
-    expect(arg.purpose).toBe("browse");
-    expect(arg.purpose).not.toBe("sync");
-    expect(arg.operations).toBe("read-only");
-    expect(arg.paths).toEqual(["companies/indigo/scratch/"]);
+    // Vend through the multi-tenant STS route — NOT the legacy POST /vend.
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    expect(spies.vendSelf).not.toHaveBeenCalled();
+    // S3 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 and classifies each key's ACL source", async () => {
+  it("paginates ListObjectsV2 fully, classifies ACL, and re-anchors keys for display", async () => {
     const { client } = makeStubVaultClient({
-      grants: [fakeGrant("companies/indigo/scratch/")],
+      // Real grants are glob/anchored; normalization folds this to "scratch/".
+      grants: [fakeGrant("companies/indigo/scratch/*")],
     });
     const { factory, sendSpy } = makeStubS3Factory({
+      // S3 keys are company-relative (no companies/<slug>/ prefix).
       listResponses: [
         {
           Contents: [
             {
-              Key: "companies/indigo/scratch/a.txt",
+              Key: "scratch/a.txt",
               Size: 10,
               LastModified: new Date("2026-01-01T00:00:00Z"),
             },
             {
-              Key: "companies/indigo/secrets/db.txt",
+              Key: "secrets/db.txt",
               Size: 20,
               LastModified: new Date("2026-01-02T00:00:00Z"),
             },
@@ -343,13 +404,13 @@ describe("runBrowse", () => {
         {
           Contents: [
             {
-              Key: "companies/indigo/scratch/sub/b.bin",
+              Key: "scratch/sub/b.bin",
               Size: 30,
               LastModified: new Date("2026-01-03T00:00:00Z"),
             },
             // S3 directory marker — should be filtered out.
             {
-              Key: "companies/indigo/scratch/empty/",
+              Key: "scratch/empty/",
               Size: 0,
               LastModified: new Date("2026-01-04T00:00:00Z"),
             },
@@ -365,6 +426,7 @@ describe("runBrowse", () => {
     });
     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",
@@ -394,13 +456,11 @@ describe("runBrowse", () => {
   // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
   //
   // Personal mode resolves the entity via `entity.get(personalUid)` (skipping
-  // the company-namespace lookup), omits the explicit-grants fetch, and tags
-  // every row with `aclSource: "personal-vault"`. The path arg is bucket-
-  // relative — companies/<slug>/ prefix is NOT required (and would be
-  // incorrect, since the person bucket is owner-only with no companies/
-  // subtree).
+  // 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 entity via entity.get(personalUid), skips namespace lookup", async () => {
+  it("personalMode: resolves via entity.get, vends /sts/vend-self, skips namespace + grants", async () => {
     const { client, spies } = makeStubVaultClient({
       entity: {
         uid: "prs_test",
@@ -431,10 +491,9 @@ describe("runBrowse", () => {
     expect(spies.findInMyNamespace).not.toHaveBeenCalled();
     // Grants graph is a company concept — must not be fetched.
     expect(spies.listMyExplicitGrants).not.toHaveBeenCalled();
-    // Vend still issued for browse purpose, no policy difference.
-    expect(spies.vend).toHaveBeenCalledWith(
-      expect.objectContaining({ purpose: "browse", operations: "read-only" }),
-    );
+    // 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 () => {
@@ -540,9 +599,9 @@ describe("runBrowse", () => {
 // ── runCat ──────────────────────────────────────────────────────────────────
 
 describe("runCat", () => {
-  it("vends with purpose='browse' for a cat call", async () => {
+  it("vends via /sts/vend and GetObjects the company-relative key", async () => {
     const { client, spies } = makeStubVaultClient({});
-    const { factory } = makeStubS3Factory({
+    const { factory, sendSpy } = makeStubS3Factory({
       getResponse: {
         Body: Readable.from(Buffer.from("hello world")),
       } as GetObjectCommandOutput,
@@ -557,8 +616,14 @@ describe("runCat", () => {
       hqRoot: tmpRoot,
       stdout: sink,
     });
-    expect(spies.vend).toHaveBeenCalledTimes(1);
-    expect(spies.vend.mock.calls[0][0].purpose).toBe("browse");
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+    expect(spies.stsVend.mock.calls[0][0]).toEqual({ companyUid: "cmp_indigo" });
+    // GetObject key is company-relative (anchor stripped).
+    const getCmd = sendSpy.mock.calls.find(
+      (c) => c[0] instanceof GetObjectCommand,
+    )?.[0] as GetObjectCommand;
+    expect(getCmd.input.Bucket).toBe("hq-vault-cmp-indigo");
+    expect(getCmd.input.Key).toBe("scratch/a.txt");
   });
 
   it("writes to --out when outside the companies tree and reports byte count", async () => {
@@ -601,7 +666,8 @@ describe("runCat", () => {
     ).rejects.toThrow(/Refusing to write/);
     // Critically: no vend was issued (guard runs first) and no S3 call
     // was made — failing closed is the whole point of the guard.
-    expect(spies.vend).not.toHaveBeenCalled();
+    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);
@@ -623,7 +689,7 @@ describe("runCat", () => {
 
   // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
 
-  it("personalMode: streams from the person bucket, no slug parse on the key", async () => {
+  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" },
     });
@@ -657,14 +723,10 @@ describe("runCat", () => {
 
     expect(result.destination.kind).toBe("stdout");
     expect(spies.findInMyNamespace).not.toHaveBeenCalled();
-    // Vend issued against the bucket-relative key, browse purpose.
-    expect(spies.vend).toHaveBeenCalledWith(
-      expect.objectContaining({
-        paths: [".claude/CLAUDE.md"],
-        purpose: "browse",
-      }),
-    );
-    // GetObject targeted the person bucket.
+    // 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;
@@ -774,3 +836,201 @@ describe("runSharedWithMe", () => {
     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 { factory } = 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,
+      s3Factory: factory,
+      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",
+    ]);
+    // Vends via the multi-tenant route (inherited from runBrowse).
+    expect(spies.stsVend).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns an empty array when nothing matches", async () => {
+    const { client } = makeStubVaultClient({});
+    const { factory } = makeStubS3Factory({
+      listResponses: [
+        { Contents: [{ Key: "knowledge/a.md", Size: 1, LastModified: new Date() }] },
+      ],
+    });
+    const rows = await runSearch({
+      query: "zzz-no-match",
+      companySlug: "indigo",
+      vaultClient: client,
+      s3Factory: factory,
+      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;
+}): { factory: S3ClientFactory; 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}`);
+  });
+  const factory = vi.fn(
+    () => ({ send: sendSpy }) as unknown as FilesBrowseS3Client,
+  ) as unknown as S3ClientFactory;
+  return { factory, sendSpy };
+}
+
+describe("runGet", () => {
+  it("materializes a prefix in-place under companies/<slug>/ and registers a pin", async () => {
+    const { client, spies } = makeStubVaultClient({});
+    const { factory, 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,
+      s3Factory: factory,
+      region: "us-east-1",
+    });
+
+    // Vends via the multi-tenant company route.
+    expect(spies.stsVend).toHaveBeenCalledWith({ companyUid: "cmp_indigo" });
+    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 { factory } = 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,
+      s3Factory: factory,
+      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 { factory } = makeGetStubS3({
+      listKeys: [],
+      bodyFor: () => Buffer.from(""),
+    });
+    await expect(
+      runGet({
+        path: "companies/indigo/nope/",
+        hqRoot: tmpRoot,
+        companySlug: "indigo",
+        vaultClient: client,
+        s3Factory: factory,
+        region: "us-east-1",
+      }),
+    ).rejects.toThrow(/No objects under/);
+  });
+});