@indigoai-us/hq-cli 5.18.3 → 5.20.0

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/);
+  });
 });

package/src/commands/files-browse.ts

@@ -57,6 +57,7 @@ import {
   buildVaultConfig,
 } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
+import { resolveCanonicalPersonUid } from "./cloud.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
@@ -99,8 +100,17 @@ export type S3ClientFactory = (input: {
   };
 }) => FilesBrowseS3Client;
 
-/** ACL provenance for a single listed key. */
-export type AclSource = "shared-with-you" | "role-bypass";
+/**
+ * ACL provenance for a single listed key.
+ *   - `shared-with-you`: an explicit grant the caller holds covers the key.
+ *   - `role-bypass`: the caller has no covering explicit grant, but
+ *      owner/admin role widened the browse-vend policy to include it.
+ *   - `personal-vault`: the key lives in the caller's own person-entity
+ *      vault, where no grants graph applies — the caller is the only
+ *      principal with access by construction. Emitted only when
+ *      `runBrowse({ personalMode: true })`.
+ */
+export type AclSource = "shared-with-you" | "role-bypass" | "personal-vault";
 
 export interface BrowseRow {
   key: string;
@@ -201,10 +211,30 @@ export function formatBrowseTable(rows: BrowseRow[]): string {
 // ── Orchestrators ───────────────────────────────────────────────────────────
 
 export interface RunBrowseInput {
-  /** Vault path prefix, e.g. `companies/indigo/scratch/`. */
+  /**
+   * Vault path prefix.
+   *   - Company mode (`personalMode: false | undefined`): must start with
+   *     `companies/<slug>/`, e.g. `companies/indigo/scratch/`.
+   *   - Personal mode (`personalMode: true`): bucket-relative; empty string
+   *     lists the whole personal vault root.
+   */
   pathPrefix: string;
-  /** Caller-overridden company slug (defaults to slug parsed from path). */
+  /** Caller-overridden company slug (defaults to slug parsed from path). Ignored under `personalMode`. */
   companySlug?: string;
+  /**
+   * Personal-vault mode. Skips the `companies/<slug>/` path requirement,
+   * resolves the entity via `entity.get(personalUid)` instead of the
+   * company namespace, omits the explicit-grants fetch (no grants graph
+   * on a person bucket), and marks every row's `aclSource` as
+   * `"personal-vault"`. Closes hq-cli#26 (audit gap for personal vault).
+   */
+  personalMode?: boolean;
+  /**
+   * Canonical person-entity UID (e.g. `prs_…`). Required when
+   * `personalMode: true`; ignored otherwise. Caller resolves via
+   * `resolveCanonicalPersonUid` to keep this orchestrator pure.
+   */
+  personalUid?: string;
   vaultClient: FilesBrowseVaultClient;
   s3Factory: S3ClientFactory;
   region: string;
@@ -227,25 +257,52 @@ export interface RunBrowseResult {
  * Pure-ish: no console output, no process.exit — caller renders + exits.
  */
 export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult> {
-  const { pathPrefix, vaultClient, s3Factory, region } = input;
-  const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
-
-  const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-  if (!entity) {
-    throw new Error(
-      `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
-    );
-  }
-  if (!entity.bucketName) {
-    throw new Error(
-      `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
-    );
+  const { pathPrefix, vaultClient, s3Factory, region, personalMode } = input;
+
+  // Branch by mode. Company mode parses slug from path and looks up by
+  // namespace; personal mode resolves the entity directly by the supplied
+  // person UID and skips the slug + grants machinery (a person bucket has
+  // no grants graph — the owner is the only principal). The vend call is
+  // identical for both modes once we have the entity in hand.
+  let bucket: string;
+  let entityUid: string;
+  if (personalMode) {
+    if (!input.personalUid) {
+      throw new Error(
+        "runBrowse: personalMode requires personalUid. Resolve via " +
+          "resolveCanonicalPersonUid() before calling.",
+      );
+    }
+    const entity = await vaultClient.entity.get(input.personalUid);
+    if (!entity.bucketName) {
+      throw new Error(
+        `Personal entity '${input.personalUid}' has no provisioned bucket.`,
+      );
+    }
+    entityUid = entity.uid;
+    bucket = entity.bucketName;
+  } else {
+    const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
+    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+    if (!entity) {
+      throw new Error(
+        `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
+      );
+    }
+    if (!entity.bucketName) {
+      throw new Error(
+        `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
+      );
+    }
+    entityUid = entity.uid;
+    bucket = entity.bucketName;
   }
-  const companyUid = entity.uid;
-  const bucket = entity.bucketName;
 
   // Distinct vend call from sync — `purpose: 'browse'` opts the request
-  // into the role-bypass-allowed code path on the server (US-009).
+  // into the role-bypass-allowed code path on the server (US-009). The
+  // personal mode vends against the person entity which is owner-only by
+  // construction; the vend response shape is identical so downstream
+  // S3Client construction doesn't branch.
   const vend = await vaultClient.vend({
     paths: [pathPrefix],
     operations: "read-only",
@@ -262,8 +319,12 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
   });
 
   // Pull the caller's explicit-grant graph once so per-key classification
-  // is O(grants) without N round-trips.
-  const grants = await vaultClient.listMyExplicitGrants(companyUid);
+  // is O(grants) without N round-trips. Skipped in personal mode — the
+  // grants graph is a company concept; a person bucket marks every row
+  // as `"personal-vault"` directly.
+  const grants = personalMode
+    ? ([] as ExplicitGrant[])
+    : await vaultClient.listMyExplicitGrants(entityUid);
 
   const rows: BrowseRow[] = [];
   let continuationToken: string | undefined;
@@ -285,7 +346,7 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
         key: obj.Key,
         size: obj.Size ?? 0,
         lastModified: obj.LastModified,
-        aclSource: classifyAclSource(obj.Key, grants),
+        aclSource: personalMode ? "personal-vault" : classifyAclSource(obj.Key, grants),
       });
     }
 
@@ -296,7 +357,11 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
 }
 
 export interface RunCatInput {
-  /** Single vault key, e.g. `companies/indigo/scratch/foo.txt`. */
+  /**
+   * Single vault key.
+   *   - Company mode: must be a `companies/<slug>/...` path.
+   *   - Personal mode: bucket-relative, e.g. `.claude/CLAUDE.md`.
+   */
   key: string;
   /**
    * Where to write the body. `undefined` ⇒ stdout. Bright-line-guarded
@@ -305,6 +370,10 @@ export interface RunCatInput {
   out?: string;
   hqRoot: string;
   companySlug?: string;
+  /** Personal-vault mode — see `RunBrowseInput.personalMode`. */
+  personalMode?: boolean;
+  /** Canonical person-entity UID; required when `personalMode: true`. */
+  personalUid?: string;
   vaultClient: FilesBrowseVaultClient;
   s3Factory: S3ClientFactory;
   region: string;
@@ -324,8 +393,7 @@ export interface RunCatResult {
  * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
  */
 export async function runCat(input: RunCatInput): Promise<RunCatResult> {
-  const { key, vaultClient, s3Factory, region, hqRoot } = input;
-  const slug = input.companySlug ?? parseCompanySlugFromPath(key);
+  const { key, vaultClient, s3Factory, region, hqRoot, personalMode } = input;
 
   // Acceptance 5: refuse BEFORE vending — no point pulling credentials
   // for a request we're already going to abort.
@@ -334,16 +402,37 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
     absOut = assertOutPathOutsideCompanies(input.out, hqRoot);
   }
 
-  const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-  if (!entity) {
-    throw new Error(
-      `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
-    );
-  }
-  if (!entity.bucketName) {
-    throw new Error(
-      `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
-    );
+  // Same branch logic as runBrowse — see that function's doc-block for
+  // the personal-vs-company rationale.
+  let bucket: string;
+  if (personalMode) {
+    if (!input.personalUid) {
+      throw new Error(
+        "runCat: personalMode requires personalUid. Resolve via " +
+          "resolveCanonicalPersonUid() before calling.",
+      );
+    }
+    const entity = await vaultClient.entity.get(input.personalUid);
+    if (!entity.bucketName) {
+      throw new Error(
+        `Personal entity '${input.personalUid}' has no provisioned bucket.`,
+      );
+    }
+    bucket = entity.bucketName;
+  } else {
+    const slug = input.companySlug ?? parseCompanySlugFromPath(key);
+    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+    if (!entity) {
+      throw new Error(
+        `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
+      );
+    }
+    if (!entity.bucketName) {
+      throw new Error(
+        `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
+      );
+    }
+    bucket = entity.bucketName;
   }
 
   const vend = await vaultClient.vend({
@@ -362,7 +451,7 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   });
 
   const resp = (await s3.send(
-    new GetObjectCommand({ Bucket: entity.bucketName, Key: key }),
+    new GetObjectCommand({ Bucket: bucket, Key: key }),
   )) as GetObjectCommandOutput;
 
   if (!resp.Body) {
@@ -403,6 +492,13 @@ const defaultS3Factory: S3ClientFactory = ({ region, credentials }) =>
 interface FilesBrowseCliOptions {
   company?: string;
   hqRoot: string;
+  /**
+   * Personal-vault mode (hq-cli#26). Skips the `companies/<slug>/`
+   * requirement on the path arg, resolves the entity from the caller's
+   * canonical person UID, and emits rows tagged `personal-vault`.
+   * Mutually exclusive with `--company`.
+   */
+  personal?: boolean;
 }
 
 interface FilesCatCliOptions extends FilesBrowseCliOptions {
@@ -417,25 +513,69 @@ interface FilesCatCliOptions extends FilesBrowseCliOptions {
  */
 export function registerFilesBrowseCommands(filesCmd: Command): void {
   filesCmd
-    .command("browse <path>")
+    .command("browse [path]")
     .description(
-      "List vault objects under <path> without syncing them locally. Uses the browse-vend path (role-bypass allowed).",
+      "List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.",
     )
     .option(
       "--company <slug>",
       "Company slug (defaults to the slug parsed from <path>)",
     )
+    .option(
+      "--personal",
+      "Browse the caller's canonical personal vault. [path] is treated as " +
+        "bucket-relative (omit it to list the vault root). Mutually exclusive " +
+        "with --company.",
+    )
     .option(
       "--hq-root <path>",
       `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
       DEFAULT_HQ_ROOT,
     )
-    .action(async (pathArg: string, options: FilesBrowseCliOptions) => {
+    .action(async (pathArg: string | undefined, options: FilesBrowseCliOptions) => {
       try {
+        if (options.personal && options.company) {
+          throw new Error(
+            "--personal and --company are mutually exclusive. Pick one.",
+          );
+        }
+
         const accessToken = await ensureCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const client = new VaultClient(vaultConfig);
 
+        if (options.personal) {
+          // Personal-vault path. Resolve the caller's canonical person
+          // entity once; the orchestrator does the bucket lookup + vend.
+          // Empty [path] → list bucket root.
+          const personalUid = await resolveCanonicalPersonUid({
+            listMyMemberships: () => client.listMyMemberships(),
+            listPersonEntities: () => client.entity.listByType("person"),
+            getEntity: async () => null,
+          });
+
+          const result = await runBrowse({
+            pathPrefix: pathArg ?? "",
+            personalMode: true,
+            personalUid,
+            vaultClient: client,
+            s3Factory: defaultS3Factory,
+            region: DEFAULT_COGNITO.region,
+          });
+
+          console.log(formatBrowseTable(result.rows));
+          return;
+        }
+
+        // Company path. [path] is required here — the slug parse needs it.
+        if (!pathArg) {
+          throw new Error(
+            "browse: [path] is required when --personal is not set. " +
+              "Pass a companies/<slug>/... path, or add --personal to " +
+              "browse your personal vault.",
+          );
+        }
+
         // Resolve slug — CLI flag wins, otherwise parse from path arg.
         const slug = options.company ?? parseCompanySlugFromPath(pathArg);
 
@@ -496,7 +636,7 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
   filesCmd
     .command("cat <path>")
     .description(
-      "Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path.",
+      "Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path. Pass --personal to read from the caller's personal vault.",
     )
     .option(
       "--out <file>",
@@ -506,6 +646,11 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
       "--company <slug>",
       "Company slug (defaults to the slug parsed from <path>)",
     )
+    .option(
+      "--personal",
+      "Read from the caller's canonical personal vault. <path> is treated as " +
+        "bucket-relative. Mutually exclusive with --company.",
+    )
     .option(
       "--hq-root <path>",
       `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
@@ -513,10 +658,43 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
     )
     .action(async (keyArg: string, options: FilesCatCliOptions) => {
       try {
+        if (options.personal && options.company) {
+          throw new Error(
+            "--personal and --company are mutually exclusive. Pick one.",
+          );
+        }
+
         const accessToken = await ensureCognitoToken();
         const vaultConfig = buildVaultConfig(accessToken);
         const client = new VaultClient(vaultConfig);
 
+        if (options.personal) {
+          const personalUid = await resolveCanonicalPersonUid({
+            listMyMemberships: () => client.listMyMemberships(),
+            listPersonEntities: () => client.entity.listByType("person"),
+            getEntity: async () => null,
+          });
+
+          const result = await runCat({
+            key: keyArg,
+            out: options.out,
+            hqRoot: options.hqRoot,
+            personalMode: true,
+            personalUid,
+            vaultClient: client,
+            s3Factory: defaultS3Factory,
+            region: DEFAULT_COGNITO.region,
+          });
+
+          if (result.destination.kind === "file") {
+            console.error(
+              chalk.green("✓"),
+              `Wrote ${result.bytesWritten} bytes to ${result.destination.absPath}`,
+            );
+          }
+          return;
+        }
+
         const slug = options.company ?? parseCompanySlugFromPath(keyArg);
         if (options.company !== undefined) {
           const fromPath = (() => {