@indigoai-us/hq-cli 5.18.2 → 5.19.0

package/src/commands/cloud.selectors.test.ts

@@ -11,6 +11,7 @@
 import { describe, expect, it, vi } from "vitest";
 
 import {
+  assertNoPersonalPositionalPaths,
   assertSingleSelector,
   resolveCanonicalPersonUid,
   type PullAllVaultClient,
@@ -76,6 +77,58 @@ describe("assertSingleSelector", () => {
   });
 });
 
+// ── assertNoPersonalPositionalPaths (hq-cli#25) ─────────────────────────────
+//
+// The combination `--personal <path>` silently bypasses
+// PERSONAL_VAULT_EXCLUDED_TOP_LEVEL (which is only applied by
+// computePersonalVaultPaths). Real incident: 196 companies/{slug}/** objects
+// uploaded to a personal vault. Refusal forces the operator to drop one of
+// the two — either `--personal` (full vault scope) or the positional paths
+// (specific subset against the active company).
+
+describe("assertNoPersonalPositionalPaths", () => {
+  it("accepts --personal alone (no positional paths)", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, undefined)).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, [])).not.toThrow();
+  });
+
+  it("accepts positional paths without --personal", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: false }, ["./scratch"])).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({}, ["./scratch"])).not.toThrow();
+  });
+
+  it("accepts neither --personal nor positional paths", () => {
+    expect(() => assertNoPersonalPositionalPaths({}, undefined)).not.toThrow();
+    expect(() => assertNoPersonalPositionalPaths({}, [])).not.toThrow();
+  });
+
+  it("throws when --personal combines with one positional path", () => {
+    expect(() => assertNoPersonalPositionalPaths({ personal: true }, ["./scratch"])).toThrow(
+      /--personal.*cannot be combined with explicit \[paths\]/,
+    );
+  });
+
+  it("throws when --personal combines with multiple positional paths", () => {
+    expect(() =>
+      assertNoPersonalPositionalPaths({ personal: true }, ["./a", "./b", "./c"]),
+    ).toThrow(/PERSONAL_VAULT_EXCLUDED_TOP_LEVEL/);
+  });
+
+  it("error message names the dangerous prefixes so the operator understands the risk", () => {
+    let caught: Error | null = null;
+    try {
+      assertNoPersonalPositionalPaths({ personal: true }, ["/Users/corey/Documents/HQ"]);
+    } catch (e) {
+      caught = e as Error;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain(".git/");
+    expect(caught!.message).toContain("companies/");
+    expect(caught!.message).toContain("repos/");
+    expect(caught!.message).toContain("workspace/");
+  });
+});
+
 // ── resolveCanonicalPersonUid ──────────────────────────────────────────────
 
 function makeClient(persons: Array<{

package/src/commands/cloud.ts

@@ -451,6 +451,35 @@ export async function resolveCanonicalPersonUid(
   return pick.uid;
 }
 
+/**
+ * Refuse `hq sync push --personal <path>` — the combination silently
+ * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
+ * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
+ * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
+ * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
+ * objects to a personal vault before being killed. Cleanup required a
+ * hand-rolled S3 sweep. Closes hq-cli#25.
+ *
+ * Refusal — not silent filtering — is intentional: explicit is better than
+ * implicit guesswork, and the legitimate "I want to push a subset of my
+ * personal vault" use case has a clean workaround (drop `--personal`, the
+ * subset upload targets the active company via standard semantics).
+ */
+export function assertNoPersonalPositionalPaths(opts: {
+  personal?: boolean;
+}, paths: string[] | undefined): void {
+  if (opts.personal && paths && paths.length > 0) {
+    throw new Error(
+      "`--personal` cannot be combined with explicit [paths]: " +
+        "positional paths bypass the PERSONAL_VAULT_EXCLUDED_TOP_LEVEL " +
+        "guard (skips .git/, companies/, repos/, workspace/), risking " +
+        "cross-scope upload of company data to the personal vault. " +
+        "Use bare `--personal` to push the whole personal scope, OR " +
+        "drop `--personal` to push specific paths to the active company.",
+    );
+  }
+}
+
 /**
  * Refuse ambiguous selector combinations. `--all`, `--personal`, and
  * `--company` are mutually exclusive — at most one may be set per
@@ -675,6 +704,8 @@ export function registerCloudCommands(program: Command): void {
                 "to have already resolved entity + credentials. Pick one.",
             );
           }
+          // Closes hq-cli#25 — see `assertNoPersonalPositionalPaths` doc-block.
+          assertNoPersonalPositionalPaths(options, paths);
 
           log(chalk.bold("\nHQ Sync — Push"));
           log(`  HQ root:  ${options.hqRoot}`);

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

@@ -387,6 +387,151 @@ describe("runBrowse", () => {
       }),
     ).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), 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).
+
+  it("personalMode: resolves entity via entity.get(personalUid), skips namespace lookup", 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();
+    // Vend still issued for browse purpose, no policy difference.
+    expect(spies.vend).toHaveBeenCalledWith(
+      expect.objectContaining({ purpose: "browse", operations: "read-only" }),
+    );
+  });
+
+  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 ──────────────────────────────────────────────────────────────────
@@ -472,4 +617,71 @@ describe("runCat", () => {
       }),
     ).rejects.toThrow(/Expected a path starting with 'companies\//);
   });
+
+  // ── personalMode (hq-cli#26) ──────────────────────────────────────────────
+
+  it("personalMode: streams from the person bucket, no slug parse on the key", 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();
+    // 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.
+    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/);
+  });
 });