@indigoai-us/hq-cli 5.18.2 → 5.19.0

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 = (() => {

package/src/commands/members.test.ts

@@ -18,6 +18,7 @@ import {
   getCallerPersonUid,
   inviteMember,
   listPendingInvites,
+  resolveRevokeTargetToMembershipKey,
   revokeInvite,
 } from "./members.js";
 
@@ -414,6 +415,58 @@ describe("revokeInvite", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// resolveRevokeTargetToMembershipKey
+// ---------------------------------------------------------------------------
+
+describe("resolveRevokeTargetToMembershipKey", () => {
+  // Regression: `hq members revoke alice@example.com` used to send the raw
+  // email straight to /membership/revoke, which the server rejects with 404
+  // "Invite not found" because it keys on `email:<email>#<companyUid>`. Live
+  // smoke 2026-05-21 reproduced this against indigo.
+  it("wraps a bare email into the email-keyed membership shape", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey("alice@example.com", "cmp_abc"),
+    ).toBe("email:alice@example.com#cmp_abc");
+  });
+
+  it("lowercases the email when wrapping", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey("Alice@Example.COM", "cmp_abc"),
+    ).toBe("email:alice@example.com#cmp_abc");
+  });
+
+  it("wraps a bare personUid into the personUid-keyed membership shape", () => {
+    expect(resolveRevokeTargetToMembershipKey("prs_bob123", "cmp_abc")).toBe(
+      "prs_bob123#cmp_abc",
+    );
+  });
+
+  it("passes through a full email-keyed membership key unchanged", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey(
+        "email:alice@example.com#cmp_abc",
+        "cmp_other",
+      ),
+    ).toBe("email:alice@example.com#cmp_abc");
+  });
+
+  it("passes through a full personUid-keyed membership key unchanged", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey("prs_bob#cmp_abc", "cmp_other"),
+    ).toBe("prs_bob#cmp_abc");
+  });
+
+  it("passes through unrecognized strings (legacy inviteToken, garbage)", () => {
+    // A schemaVersion-1 inviteToken is opaque base64url; we can't tell it
+    // apart from garbage. Send it to the server and let the server 404 if
+    // it doesn't resolve.
+    expect(
+      resolveRevokeTargetToMembershipKey("some-opaque-token", "cmp_abc"),
+    ).toBe("some-opaque-token");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // formatInviteHttpError
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -248,6 +248,37 @@ export async function listPendingInvites(
   return data?.pending ?? data?.invites ?? [];
 }
 
+/**
+ * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
+ * the server requires. Accepts three input forms:
+ *
+ *   1. Full membership key — already has `#<companyUid>`; passed through.
+ *      Examples: `email:alice@example.com#cmp_abc`, `prs_abc#cmp_abc`.
+ *   2. Bare email — wrap as `email:<email>#<companyUid>`.
+ *   3. Bare personUid (`prs_*`) — wrap as `<personUid>#<companyUid>`.
+ *   4. Anything else (e.g. legacy schemaVersion-1 inviteToken) — pass through
+ *      so the server can decide. Server may 404 if the token doesn't resolve.
+ *
+ * Pure function — no I/O — so it's trivially unit-testable. The previous
+ * shape sent the user's raw arg straight through, which meant `hq members
+ * revoke alice@example.com` always 404'd ("Invite not found") even when
+ * that exact email was just shown by `hq members list`.
+ */
+export function resolveRevokeTargetToMembershipKey(
+  arg: string,
+  companyUid: string,
+): string {
+  if (arg.includes("#")) return arg;
+  const detected = detectTarget(arg);
+  if (detected?.type === "email") {
+    return `email:${detected.value}#${companyUid}`;
+  }
+  if (detected?.type === "person") {
+    return `${detected.value}#${companyUid}`;
+  }
+  return arg;
+}
+
 export async function revokeInvite(
   token: string,
   tokenOrKey: string,
@@ -328,24 +359,47 @@ export function registerMembersCommand(program: Command): void {
           } else {
             // schemaVersion 2+ — email-keyed authoritative membership row.
             // No magic link to share; invitee accepts by signing into HQ.
+            //
+            // CRITICAL UX NOTE: this CLI command does NOT send any email.
+            // hq-pro only writes the DDB pending row; only the hq-console UI
+            // path triggers Resend. Operators who run `hq members invite`
+            // expecting an email to fly out get silently broken flows. The
+            // output below uses chalk.yellow + an explicit "no email sent"
+            // line so this never sneaks past again.
             const inviteeEmail =
               result.membership.inviteeEmail ??
               (typeof target === "string" && target.includes("@")
                 ? target
                 : undefined);
-            console.log(chalk.bold("Next step:"));
             console.log(
-              `  Tell ${inviteeEmail ?? "the invitee"} to sign into HQ at https://hq.getindigo.ai with that email.`,
+              chalk.yellow(
+                "⚠ No email was sent. `hq members invite` only creates the pending membership row.",
+              ),
+            );
+            console.log();
+            console.log(chalk.bold("To complete the invite, do ONE of:"));
+            console.log(
+              `  1. Manually notify ${inviteeEmail ?? "the invitee"}: ask them to sign into HQ`,
+            );
+            console.log(
+              `     at https://hq.getindigo.ai with that email address.`,
+            );
+            console.log(
+              `  2. Or use the hq-console UI at https://hq.getindigo.ai to issue the`,
             );
+            console.log(
+              `     invite instead — the UI path triggers an automated email via Resend.`,
+            );
+            console.log();
             console.log(
               chalk.dim(
-                "  The pending membership row claims itself on first sign-in — no separate token redemption.",
+                "The pending membership row claims itself on the invitee's first sign-in.",
               ),
             );
             if (result.membership.membershipKey) {
               console.log();
               console.log(
-                chalk.dim(`  Membership key: ${result.membership.membershipKey}`),
+                chalk.dim(`Membership key: ${result.membership.membershipKey}`),
               );
             }
           }
@@ -431,16 +485,22 @@ export function registerMembersCommand(program: Command): void {
     });
 
   members
-    .command("revoke <tokenOrKey>")
-    .description("Revoke a pending invite (accepts the inviteToken or membershipKey)")
-    .action(async (tokenOrKey: string) => {
+    .command("revoke <target>")
+    .description(
+      "Revoke a pending invite. Accepts an email, personUid, full membershipKey, or legacy inviteToken.",
+    )
+    .action(async (target: string) => {
       try {
         const token = await ensureCognitoToken();
         const companySlug = members.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
 
-        await revokeInvite(token, tokenOrKey, companyUid);
-        console.log(chalk.green(`Revoked invite '${tokenOrKey}'`));
+        const membershipKey = resolveRevokeTargetToMembershipKey(
+          target,
+          companyUid,
+        );
+        await revokeInvite(token, membershipKey, companyUid);
+        console.log(chalk.green(`Revoked invite '${membershipKey}'`));
       } catch (err) {
         if (err instanceof InviteHttpError) {
           const msg =