@indigoai-us/hq-cli 5.9.0 → 5.10.1

package/src/commands/members.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Unit tests for `hq members invite|list|revoke` (members.ts).
+ *
+ * Coverage:
+ *   - detectTarget — pure validation for email vs personUid vs invalid
+ *   - getCallerPersonUid — happy path + missing-person-entity branch
+ *   - inviteMember — email + personUid targets, --paths gating, HTTP errors
+ *   - listPendingInvites — happy path + 403
+ *   - revokeInvite — happy path + 404
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
+
+import {
+  InviteHttpError,
+  detectTarget,
+  formatInviteHttpError,
+  getCallerPersonUid,
+  inviteMember,
+  listPendingInvites,
+  revokeInvite,
+} from "./members.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// detectTarget
+// ---------------------------------------------------------------------------
+
+describe("detectTarget", () => {
+  it("recognizes plain emails and lowercases them", () => {
+    expect(detectTarget("Alice@Example.com")).toEqual({
+      type: "email",
+      value: "alice@example.com",
+    });
+  });
+
+  it("recognizes person UIDs", () => {
+    expect(detectTarget("prs_bob123")).toEqual({
+      type: "person",
+      value: "prs_bob123",
+    });
+  });
+
+  it("returns null for invalid targets", () => {
+    expect(detectTarget("not-a-target")).toBeNull();
+    expect(detectTarget("cmp_company")).toBeNull();
+    expect(detectTarget("")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getCallerPersonUid
+// ---------------------------------------------------------------------------
+
+describe("getCallerPersonUid", () => {
+  it("returns the personUid from the first membership", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", personUid: "prs_admin", companyUid: "cmp_a", role: "owner", status: "active" },
+        ],
+      }),
+    );
+
+    const uid = await getCallerPersonUid("test-token");
+    expect(uid).toBe("prs_admin");
+  });
+
+  it("throws if the caller has no person entity yet", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { memberships: [] }));
+    await expect(getCallerPersonUid("test-token")).rejects.toThrow(/no person entity/);
+  });
+
+  it("throws on auth failure", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(401, { error: "unauthorized" }));
+    await expect(getCallerPersonUid("test-token")).rejects.toThrow(/run `hq login`/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// inviteMember
+// ---------------------------------------------------------------------------
+
+describe("inviteMember", () => {
+  it("creates an invite for an email target and returns a magic link", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { role: "member", status: "pending" },
+        inviteToken: "tok_abc",
+      }),
+    );
+
+    const result = await inviteMember({
+      target: "alice@example.com",
+      role: "member",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    expect(result.magicLink).toBe("hq://accept/tok_abc");
+    expect(result.membership.role).toBe("member");
+
+    const call = fetchSpy.mock.calls[0];
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      companyUid: "cmp_acme",
+      role: "member",
+      invitedBy: "prs_admin",
+      inviteeEmail: "alice@example.com",
+    });
+  });
+
+  it("creates an invite for a personUid target", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { role: "admin", status: "pending" },
+        inviteToken: "tok_456",
+      }),
+    );
+
+    await inviteMember({
+      target: "prs_bob",
+      role: "admin",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    const body = JSON.parse((fetchSpy.mock.calls[0][1]?.body as string) ?? "{}");
+    expect(body.personUid).toBe("prs_bob");
+    expect(body.inviteeEmail).toBeUndefined();
+  });
+
+  it("forwards allowedPrefixes when --paths is set with --role guest", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membership: { role: "guest", status: "pending" },
+        inviteToken: "tok_guest",
+      }),
+    );
+
+    await inviteMember({
+      target: "alice@example.com",
+      role: "guest",
+      paths: "docs/, shared/",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    const body = JSON.parse((fetchSpy.mock.calls[0][1]?.body as string) ?? "{}");
+    expect(body.allowedPrefixes).toEqual(["docs/", "shared/"]);
+  });
+
+  it("rejects --paths with a non-guest role", async () => {
+    await expect(
+      inviteMember({
+        target: "alice@example.com",
+        role: "member",
+        paths: "docs/",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/--paths is only valid with --role guest/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects an invalid target", async () => {
+    await expect(
+      inviteMember({
+        target: "not-a-target",
+        role: "member",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/Invalid target/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects an unknown role", async () => {
+    await expect(
+      inviteMember({
+        target: "alice@example.com",
+        role: "superuser",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/Invalid role/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("wraps non-2xx responses in InviteHttpError", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(409, { error: "duplicate" }));
+
+    await expect(
+      inviteMember({
+        target: "alice@example.com",
+        role: "member",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toBeInstanceOf(InviteHttpError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listPendingInvites
+// ---------------------------------------------------------------------------
+
+describe("listPendingInvites", () => {
+  it("returns the parsed invites array", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        invites: [
+          {
+            membershipKey: "k1",
+            inviteeEmail: "alice@example.com",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "pending",
+            invitedBy: "prs_admin",
+            invitedAt: "2026-05-04T12:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    const invites = await listPendingInvites("test-token", "cmp_acme");
+    expect(invites).toHaveLength(1);
+    expect(invites[0].inviteeEmail).toBe("alice@example.com");
+  });
+
+  it("throws InviteHttpError on 403", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(403, { error: "forbidden" }));
+    await expect(listPendingInvites("test-token", "cmp_acme")).rejects.toBeInstanceOf(
+      InviteHttpError,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// revokeInvite
+// ---------------------------------------------------------------------------
+
+describe("revokeInvite", () => {
+  it("posts membershipKey + companyUid", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+
+    await revokeInvite("test-token", "k1", "cmp_acme");
+
+    const body = JSON.parse((fetchSpy.mock.calls[0][1]?.body as string) ?? "{}");
+    expect(body).toEqual({ membershipKey: "k1", companyUid: "cmp_acme" });
+  });
+
+  it("throws InviteHttpError on 404", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(404, { error: "not found" }));
+    await expect(revokeInvite("test-token", "k1", "cmp_acme")).rejects.toBeInstanceOf(
+      InviteHttpError,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatInviteHttpError
+// ---------------------------------------------------------------------------
+
+describe("formatInviteHttpError", () => {
+  it("maps 401 to a login hint", () => {
+    expect(formatInviteHttpError(401, "ignored")).toMatch(/run `hq login`/);
+  });
+  it("maps 403 to admin/owner hint", () => {
+    expect(formatInviteHttpError(403, "ignored")).toMatch(/admins and owners/);
+  });
+  it("maps 409 to duplicate-invite hint", () => {
+    expect(formatInviteHttpError(409, "ignored")).toMatch(/already has a membership/);
+  });
+  it("prefixes 5xx with 'Server error:'", () => {
+    expect(formatInviteHttpError(500, "boom")).toBe("Server error: boom");
+  });
+  it("falls through to the message for unmapped statuses", () => {
+    expect(formatInviteHttpError(400, "bad input")).toBe("bad input");
+  });
+});

package/src/commands/members.ts

@@ -0,0 +1,367 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+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"]);
+
+export type Role = "owner" | "admin" | "member" | "guest";
+
+export interface PendingInvite {
+  membershipKey: string;
+  personUid?: string;
+  inviteeEmail?: string;
+  companyUid: string;
+  role: string;
+  status: string;
+  inviteToken?: string;
+  invitedBy: string;
+  invitedAt: string;
+}
+
+interface MyMembership {
+  membershipKey: string;
+  personUid: string;
+  companyUid: string;
+  role: string;
+  status: string;
+}
+
+export interface InviteOptions {
+  target: string;
+  role: string;
+  paths?: string;
+  companyUid: string;
+  callerUid: string;
+  token: string;
+}
+
+export interface InviteResult {
+  inviteToken: string;
+  magicLink: string;
+  membership: { role: string; status: string };
+}
+
+export interface DetectedTarget {
+  type: "email" | "person";
+  value: string;
+}
+
+export function detectTarget(target: string): DetectedTarget | null {
+  if (EMAIL_PATTERN.test(target)) {
+    return { type: "email", value: target.trim().toLowerCase() };
+  }
+  if (PERSON_UID_PATTERN.test(target)) {
+    return { type: "person", value: target };
+  }
+  return null;
+}
+
+export function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+/**
+ * Resolve the caller's personUid by reading their own membership list.
+ * The server infers the JWT identity, so this returns the canonical
+ * personUid attached to the caller's active memberships.
+ */
+export async function getCallerPersonUid(token: string): Promise<string> {
+  const res = await vaultApiFetch({ token, path: "/membership/me" });
+  if (!res.ok) {
+    throw new Error(
+      "Failed to resolve caller identity — run `hq login` and try again",
+    );
+  }
+  const data = (await res.json()) as { memberships: MyMembership[] };
+  const personUid = data.memberships.find((m) => m.personUid)?.personUid;
+  if (!personUid) {
+    throw new Error(
+      "Your account has no person entity yet. Run `hq onboard create-company` or accept an invite first.",
+    );
+  }
+  return personUid;
+}
+
+/** Send a `/membership/invite` request and return the magic link. */
+export async function inviteMember(
+  options: InviteOptions,
+): Promise<InviteResult> {
+  if (!VALID_ROLES.has(options.role)) {
+    throw new Error(
+      `Invalid role '${options.role}': must be one of owner, admin, member, guest`,
+    );
+  }
+  if (options.paths && options.role !== "guest") {
+    throw new Error(
+      "--paths is only valid with --role guest (allowedPrefixes are only meaningful for the guest role)",
+    );
+  }
+
+  const detected = detectTarget(options.target);
+  if (!detected) {
+    throw new Error(
+      `Invalid target '${options.target}': must be an email address or a personUid matching prs_<alphanumeric>`,
+    );
+  }
+
+  const allowedPrefixes = options.paths
+    ? options.paths.split(",").map((p) => p.trim()).filter(Boolean)
+    : undefined;
+
+  const body: Record<string, unknown> = {
+    companyUid: options.companyUid,
+    role: options.role,
+    invitedBy: options.callerUid,
+  };
+  if (detected.type === "email") body.inviteeEmail = detected.value;
+  else body.personUid = detected.value;
+  if (allowedPrefixes) body.allowedPrefixes = allowedPrefixes;
+
+  const res = await vaultApiFetch({
+    token: options.token,
+    path: "/membership/invite",
+    method: "POST",
+    body,
+  });
+
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new InviteHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+    );
+  }
+
+  const data = (await res.json()) as {
+    membership: { role: string; status: string };
+    inviteToken: string;
+  };
+  return {
+    inviteToken: data.inviteToken,
+    magicLink: `hq://accept/${data.inviteToken}`,
+    membership: data.membership,
+  };
+}
+
+export class InviteHttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = "InviteHttpError";
+  }
+}
+
+export function formatInviteHttpError(status: number, fallback: string): string {
+  if (status === 401) return "Not authenticated — please run `hq login`";
+  if (status === 403) {
+    return "Not authorized — only admins and owners can invite members";
+  }
+  if (status === 409) {
+    return "This person already has a membership or pending invite for this company";
+  }
+  if (status >= 500) return `Server error: ${fallback}`;
+  return fallback;
+}
+
+export async function listPendingInvites(
+  token: string,
+  companyUid: string,
+): Promise<PendingInvite[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: `/membership/company/${encodeURIComponent(companyUid)}/pending`,
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new InviteHttpError(
+      res.status,
+      err.message ?? err.error ?? res.statusText,
+    );
+  }
+  const data = (await res.json()) as { invites: PendingInvite[] };
+  return data.invites;
+}
+
+export async function revokeInvite(
+  token: string,
+  tokenOrKey: string,
+  companyUid: string,
+): Promise<void> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/membership/revoke",
+    method: "POST",
+    body: { membershipKey: tokenOrKey, 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,
+    );
+  }
+}
+
+export function registerMembersCommand(program: Command): void {
+  const members = program
+    .command("members")
+    .description("Manage company memberships and invites")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  members
+    .command("invite <target>")
+    .description(
+      "Invite a person to the company by email or personUid (prints a magic link)",
+    )
+    .option(
+      "--role <role>",
+      "Role for the invitee: owner, admin, member, or guest",
+      "member",
+    )
+    .option(
+      "--paths <prefixes>",
+      "Comma-separated allowed prefixes (only valid with --role guest)",
+    )
+    .action(
+      async (
+        target: string,
+        opts: { role: string; paths?: string },
+      ) => {
+        try {
+          const token = await ensureCognitoToken();
+          const companySlug = members.opts().company as string | undefined;
+          const companyUid = await getCompanyUid(token, companySlug);
+          const callerUid = await getCallerPersonUid(token);
+
+          const result = await inviteMember({
+            target,
+            role: opts.role,
+            paths: opts.paths,
+            companyUid,
+            callerUid,
+            token,
+          });
+
+          console.log(
+            chalk.green(
+              `Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`,
+            ),
+          );
+          console.log();
+          console.log(chalk.bold("Magic link:"));
+          console.log(`  ${result.magicLink}`);
+          console.log();
+          console.log(
+            chalk.dim(
+              "Share this link with the invitee. They can run `hq onboard join --invite-token <token>` to accept.",
+            ),
+          );
+        } catch (err) {
+          if (err instanceof InviteHttpError) {
+            console.error(chalk.red(formatInviteHttpError(err.status, err.message)));
+            process.exit(1);
+          }
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
+  members
+    .command("list")
+    .description("List pending invites for the company")
+    .action(async () => {
+      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 (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("  "),
+          );
+        }
+      } catch (err) {
+        if (err instanceof InviteHttpError) {
+          const msg =
+            err.status === 403
+              ? "Not authorized — only admins and owners can list invites"
+              : formatInviteHttpError(err.status, err.message);
+          console.error(chalk.red(msg));
+          process.exit(1);
+        }
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  members
+    .command("revoke <tokenOrKey>")
+    .description("Revoke a pending invite (accepts the inviteToken or membershipKey)")
+    .action(async (tokenOrKey: 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}'`));
+      } catch (err) {
+        if (err instanceof InviteHttpError) {
+          const msg =
+            err.status === 403
+              ? "Not authorized — only admins and owners can revoke invites"
+              : err.status === 404
+                ? "Invite not found — it may have already been accepted or revoked"
+                : formatInviteHttpError(err.status, err.message);
+          console.error(chalk.red(msg));
+          process.exit(1);
+        }
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { registerListCommand } from "./commands/list.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
+import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
 import { registerLogoutCommand } from "./commands/logout.js";
 import { registerWhoamiCommand } from "./commands/whoami.js";
@@ -26,6 +27,7 @@ import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
+import { registerMembersCommand } from "./commands/members.js";
 
 initSentry();
 
@@ -78,6 +80,7 @@ const cloudCmd = program
   );
 
 registerCloudProvisionCommands(cloudCmd);
+registerCloudDemoteCommands(cloudCmd);
 
 // Team commands (top-level)
 registerTeamSyncCommand(program);
@@ -100,6 +103,9 @@ registerGroupsCommand(program);
 // Files ACL management (subcommand group — hq files share|unshare|acl)
 registerFilesCommand(program);
 
+// Membership management (subcommand group — hq members invite|list|revoke)
+registerMembersCommand(program);
+
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);