@indigoai-us/hq-cli 5.50.2 → 5.52.0

package/src/commands/members.test.ts

@@ -34,10 +34,12 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
 import {
   InviteHttpError,
+  changeMemberRole,
   detectTarget,
   formatInviteHttpError,
   getCallerPersonUid,
   inviteMember,
+  listActiveMembers,
   listPendingInvites,
   registerMembersCommand,
   resendInvite,
@@ -743,6 +745,181 @@ describe("listPendingInvites", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// listActiveMembers
+// ---------------------------------------------------------------------------
+
+describe("listActiveMembers", () => {
+  it("GETs /membership/company/{uid} and returns the members array", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        members: [
+          {
+            membershipKey: "k1",
+            personUid: "prs_alice",
+            companyUid: "cmp_acme",
+            role: "owner",
+            status: "active",
+            personEmail: "alice@example.com",
+            personName: "Alice",
+          },
+        ],
+      }),
+    );
+
+    const members = await listActiveMembers("test-token", "cmp_acme");
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/company\/cmp_acme$/);
+    expect(members).toHaveLength(1);
+    expect(members[0].personEmail).toBe("alice@example.com");
+    expect(members[0].role).toBe("owner");
+  });
+
+  it("returns [] when the members key is missing", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).resolves.toEqual([]);
+  });
+
+  it("returns [] when members is null", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { members: null }));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).resolves.toEqual([]);
+  });
+
+  it("throws InviteHttpError on non-ok", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(403, { error: "forbidden" }));
+    await expect(
+      listActiveMembers("test-token", "cmp_acme"),
+    ).rejects.toBeInstanceOf(InviteHttpError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// registerMembersCommand list
+// ---------------------------------------------------------------------------
+
+describe("registerMembersCommand list", () => {
+  it("defaults to ACTIVE members: renders EMAIL/ROLE/NAME + the share hint", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        members: [
+          {
+            membershipKey: "k1",
+            personUid: "prs_alice",
+            companyUid: "cmp_acme",
+            role: "owner",
+            status: "active",
+            personEmail: "alice@example.com",
+            personName: "Alice",
+          },
+          {
+            membershipKey: "k2",
+            personUid: "prs_bob",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+            personSlug: "bob",
+          },
+        ],
+      }),
+    );
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/company\/cmp_acme$/);
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("EMAIL");
+    expect(output).toContain("ROLE");
+    expect(output).toContain("NAME");
+    expect(output).toContain("alice@example.com");
+    expect(output).toContain("owner");
+    expect(output).toContain("Alice");
+    // unresolved email falls back to personUid; name falls back to slug
+    expect(output).toContain("prs_bob");
+    expect(output).toContain("bob");
+    expect(output).toContain(
+      "hq secrets share <path> --with <email>",
+    );
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("default active: empty roster prints the no-active-members message", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { members: [] }));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list"],
+      { from: "user" },
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No active members found for this company."),
+    );
+  });
+
+  it("--pending preserves the OLD pending-invites table verbatim", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        pending: [
+          {
+            membershipKey: "email:alice@example.com#cmp_acme",
+            inviteeEmail: "alice@example.com",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "pending",
+            invitedBy: "prs_admin",
+            invitedAt: "2026-05-21T12:00:00Z",
+          },
+        ],
+      }),
+    );
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list", "--pending"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(
+      /\/membership\/company\/cmp_acme\/pending$/,
+    );
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("TARGET");
+    expect(output).toContain("INVITED_BY");
+    expect(output).toContain("MEMBERSHIP_KEY");
+    expect(output).toContain("alice@example.com");
+    // the active-only share hint must NOT appear in the pending view
+    expect(output).not.toContain("hq secrets share");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("--pending: empty invites prints the no-pending-invites message", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { pending: [] }));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "list", "--pending"],
+      { from: "user" },
+    );
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No pending invites for this company."),
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // revokeInvite
 // ---------------------------------------------------------------------------
@@ -822,6 +999,121 @@ describe("registerMembersCommand set-role", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// changeMemberRole + the unified `promote` command (alias `set-role`)
+// ---------------------------------------------------------------------------
+
+describe("changeMemberRole", () => {
+  it("rejects an invalid role WITHOUT making a network call", async () => {
+    await expect(
+      changeMemberRole(
+        "test-token",
+        "cmp_acme",
+        "prs_x#cmp_acme",
+        "superuser" as never,
+      ),
+    ).rejects.toThrow("must be one of owner, admin, member, guest");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("accepts the full role set and POSTs to /membership/role", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await changeMemberRole("test-token", "cmp_acme", "prs_x#cmp_acme", "guest");
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/role$/);
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "prs_x#cmp_acme",
+      newRole: "guest",
+    });
+  });
+});
+
+describe("registerMembersCommand promote", () => {
+  it("resolves an email target and promotes to a full-set role the old set-role couldn't (admin)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "promote", "alice@example.com", "admin"],
+      { from: "user" },
+    );
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toMatch(/\/membership\/role$/);
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "email:alice@example.com#cmp_acme",
+      newRole: "admin",
+    });
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Updated role for 'alice@example.com' to admin"),
+    );
+  });
+
+  it("forwards a personUid target and the guest role (beyond set-role's admin|member cap)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "promote", "prs_bob", "guest"],
+      { from: "user" },
+    );
+
+    const body = JSON.parse(
+      (fetchSpy.mock.calls[0]?.[1]?.body as string) ?? "{}",
+    );
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      membershipKey: "prs_bob#cmp_acme",
+      newRole: "guest",
+    });
+  });
+
+  it("rejects an invalid role at the CLI and exits non-zero without a network call", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+
+    await expect(
+      buildMembersProgram().parseAsync(
+        ["members", "--company", "acme", "promote", "alice@example.com", "wizard"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow("__EXIT__:1");
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("must be one of owner, admin, member, guest"),
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a backend 403 verbatim (server-enforced authorization)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "Only an owner may promote a member to owner" }),
+    );
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.spyOn(console, "log").mockImplementation(() => undefined);
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+
+    await expect(
+      buildMembersProgram().parseAsync(
+        ["members", "--company", "acme", "promote", "prs_bob", "owner"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow("__EXIT__:1");
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Only an owner may promote a member to owner"),
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // resolveRevokeTargetToMembershipKey
 // ---------------------------------------------------------------------------

package/src/commands/members.ts

@@ -6,10 +6,8 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
-const VALID_MEMBER_SET_ROLES = new Set(["admin", "member"]);
 
 export type Role = "owner" | "admin" | "member" | "guest";
-type MemberSetRole = "admin" | "member";
 
 export interface PendingInvite {
   membershipKey: string;
@@ -31,6 +29,23 @@ interface MyMembership {
   status: string;
 }
 
+/**
+ * An ACTIVE member of a company, as returned by
+ * `GET /membership/company/{companyUid}`. The server filters to
+ * `status: "active"` and enriches each row with resolved person metadata
+ * (`personEmail` / `personName` / `personSlug`) when available.
+ */
+export interface ActiveMember {
+  membershipKey: string;
+  personUid: string;
+  companyUid: string;
+  role: string;
+  status: string;
+  personEmail?: string;
+  personName?: string;
+  personSlug?: string;
+}
+
 export interface InviteOptions {
   target: string;
   role: string;
@@ -374,6 +389,30 @@ export async function listPendingInvites(
   return data?.pending ?? data?.invites ?? [];
 }
 
+export async function listActiveMembers(
+  token: string,
+  companyUid: string,
+): Promise<ActiveMember[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: `/membership/company/${encodeURIComponent(companyUid)}`,
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new InviteHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+      err.code,
+    );
+  }
+  // Server schema: `{ members: [...] }` — active members only, enriched with
+  // resolved person metadata (personEmail / personName / personSlug).
+  const data = (await res.json()) as {
+    members?: ActiveMember[] | null;
+  };
+  return data?.members ?? [];
+}
+
 /**
  * Resolve a `revoke` CLI argument into the canonical `membershipKey` shape
  * the server requires. Accepts three input forms:
@@ -457,15 +496,24 @@ export async function revokeInvite(
   }
 }
 
-async function setMemberRole(
+/**
+ * Change a member's role via `POST /membership/role`, accepting the FULL role
+ * set (owner|admin|member|guest). This is a GENERAL role change — it can promote
+ * OR demote. Authorization (owner-or-admin `changeRoles`, owner-only
+ * promote-to-owner / change-an-owner) is enforced SERVER-side; this function
+ * only validates the role string locally and surfaces the server's error.
+ * Role string is validated BEFORE any network call so callers/tests can rely on
+ * a synchronous-shaped rejection for a bad role.
+ */
+export async function changeMemberRole(
   token: string,
   companyUid: string,
   membershipKey: string,
-  newRole: MemberSetRole,
+  newRole: Role,
 ): Promise<void> {
-  if (!VALID_MEMBER_SET_ROLES.has(newRole)) {
+  if (!VALID_ROLES.has(newRole)) {
     throw new Error(
-      `Invalid role '${newRole}': must be one of admin, member`,
+      `Invalid role '${newRole}': must be one of owner, admin, member, guest`,
     );
   }
 
@@ -491,23 +539,41 @@ export function registerMembersCommand(program: Command): void {
     .description("Manage company memberships and invites")
     .option("--company <slug>", "Company slug (resolves to companyUid)");
 
+  // Canonical role-change command. `promote` is the discoverable verb users
+  // reach for; `set-role` is kept as an alias for the older name. The route is a
+  // GENERAL role change, so the help text and success message are honest that it
+  // can demote as well as promote. Authorization is enforced server-side.
   members
-    .command("set-role <membershipKey> <role>")
-    .description("Change a member or agent role to admin or member")
-    .action(async (membershipKey: string, role: string) => {
+    .command("promote <target> <newRole>")
+    .alias("set-role")
+    .description(
+      "Change a member's role (owner|admin|member|guest) — promotes OR demotes. " +
+        "<target> may be an email, a prs_ personUid, or a full membership key. " +
+        "Owner-or-admin only; setting a target to owner (or changing an owner) is owner-only. Server-enforced.",
+    )
+    .action(async (target: string, newRole: string) => {
       try {
+        const role = newRole.trim().toLowerCase();
+        if (!VALID_ROLES.has(role)) {
+          console.error(
+            chalk.red(
+              `Invalid role '${newRole}': must be one of owner, admin, member, guest`,
+            ),
+          );
+          process.exit(1);
+        }
+
         const token = await ensureCognitoToken();
         const companySlug = members.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
-
-        await setMemberRole(
-          token,
+        const membershipKey = resolveRevokeTargetToMembershipKey(
+          target,
           companyUid,
-          membershipKey,
-          role as MemberSetRole,
         );
+
+        await changeMemberRole(token, companyUid, membershipKey, role as Role);
         console.log(
-          chalk.green(`Updated role for '${membershipKey}' to ${role}`),
+          chalk.green(`Updated role for '${target}' to ${role}`),
         );
       } catch (err) {
         if (err instanceof InviteHttpError) {
@@ -746,55 +812,99 @@ export function registerMembersCommand(program: Command): void {
 
   members
     .command("list")
-    .description("List pending invites for the company")
-    .action(async () => {
+    .description(
+      "List the company's active members (use --pending for pending invites)",
+    )
+    .option("--pending", "List pending invites instead of active members")
+    .action(async (opts: { pending?: boolean }) => {
       try {
         const token = await ensureCognitoToken();
         const companySlug = members.opts().company as string | undefined;
         const companyUid = await getCompanyUid(token, companySlug);
 
-        const invites = await listPendingInvites(token, companyUid);
+        if (opts.pending) {
+          // --pending: preserve the original pending-invites view verbatim.
+          const invites = await listPendingInvites(token, companyUid);
+
+          if (invites.length === 0) {
+            console.log(chalk.gray("No pending invites for this company."));
+            return;
+          }
+
+          const targetW = Math.max(
+            6,
+            ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length),
+          );
+          const roleW = Math.max(4, ...invites.map((i) => i.role.length));
+          const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
+          const keyW = Math.max(
+            14,
+            ...invites.map((i) => i.membershipKey.length),
+          );
+          console.log(
+            chalk.bold(
+              [
+                "TARGET".padEnd(targetW),
+                "ROLE".padEnd(roleW),
+                "INVITED_BY".padEnd(byW),
+                "INVITED_AT",
+                "MEMBERSHIP_KEY".padEnd(keyW),
+              ].join("  "),
+            ),
+          );
+          for (const inv of invites) {
+            const target = inv.inviteeEmail ?? inv.personUid ?? "";
+            console.log(
+              [
+                target.padEnd(targetW),
+                inv.role.padEnd(roleW),
+                inv.invitedBy.padEnd(byW),
+                shortDate(inv.invitedAt),
+                inv.membershipKey.padEnd(keyW),
+              ].join("  "),
+            );
+          }
+          return;
+        }
+
+        // Default: list ACTIVE members so their emails drop straight into
+        // `hq secrets share <path> --with <email>`.
+        const activeMembers = await listActiveMembers(token, companyUid);
 
-        if (invites.length === 0) {
-          console.log(chalk.gray("No pending invites for this company."));
+        if (activeMembers.length === 0) {
+          console.log(chalk.gray("No active members found for this company."));
           return;
         }
 
-        const targetW = Math.max(
-          6,
-          ...invites.map((i) => (i.inviteeEmail ?? i.personUid ?? "").length),
+        const emailW = Math.max(
+          5,
+          ...activeMembers.map((m) => (m.personEmail ?? m.personUid).length),
         );
-        const roleW = Math.max(4, ...invites.map((i) => i.role.length));
-        const byW = Math.max(10, ...invites.map((i) => i.invitedBy.length));
-        const keyW = Math.max(14, ...invites.map((i) => i.membershipKey.length));
+        const roleW = Math.max(4, ...activeMembers.map((m) => m.role.length));
         console.log(
           chalk.bold(
-            [
-              "TARGET".padEnd(targetW),
-              "ROLE".padEnd(roleW),
-              "INVITED_BY".padEnd(byW),
-              "INVITED_AT",
-              "MEMBERSHIP_KEY".padEnd(keyW),
-            ].join("  "),
+            ["EMAIL".padEnd(emailW), "ROLE".padEnd(roleW), "NAME"].join("  "),
           ),
         );
-        for (const inv of invites) {
-          const target = inv.inviteeEmail ?? inv.personUid ?? "";
+        for (const m of activeMembers) {
+          const email = m.personEmail ?? m.personUid;
+          const name = m.personName ?? m.personSlug ?? "";
           console.log(
-            [
-              target.padEnd(targetW),
-              inv.role.padEnd(roleW),
-              inv.invitedBy.padEnd(byW),
-              shortDate(inv.invitedAt),
-              inv.membershipKey.padEnd(keyW),
-            ].join("  "),
+            [email.padEnd(emailW), m.role.padEnd(roleW), name].join("  "),
           );
         }
+        console.log(
+          chalk.gray(
+            "Share a secret with a member: hq secrets share <path> --with <email>",
+          ),
+        );
       } catch (err) {
         if (err instanceof InviteHttpError) {
           const msg =
             err.status === 403
-              ? "Not authorized — only admins and owners can list invites"
+              ? opts.pending
+                ? "Not authorized — only admins and owners can list invites"
+                : "Not authorized — only company members can list members"
               : formatInviteHttpError(err.status, err.message);
           console.error(chalk.red(msg));
           process.exit(1);