@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/members.ts

@@ -1,1181 +0,0 @@
-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_-]+$/;
-const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
-/** Fleet agent machine email: agt-…@agents.getindigo.ai */
-const AGENT_EMAIL_PATTERN =
-  /^agt-[a-z0-9]+@agents\.getindigo\.ai$/i;
-export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
-/** Roles allowed when inviting an existing fleet agent into a company. */
-export const AGENT_INVITE_ROLES = new Set(["admin", "member"]);
-
-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;
-}
-
-/**
- * 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;
-  paths?: string;
-  /** Email-keyed invites only — secret-group ids to attach on claim. */
-  groupIds?: string[];
-  /**
-   * Opt the server-side Resend send in/out. When `true`, hq-pro renders +
-   * sends the invitation email server-side and returns `emailSent` /
-   * `emailSkipped` / `emailError`. When `false` or unset, the legacy
-   * no-email path runs and the CLI prints the manual sign-in instructions.
-   * Requires hq-pro that supports `sendEmail` (older servers ignore the
-   * field; CLI falls back to the legacy printout in that case).
-   */
-  sendEmail?: boolean;
-  companyUid: string;
-  callerUid: string;
-  token: string;
-}
-
-/**
- * Outcome of `hq members invite`. Two shapes depending on server schema:
- *
- *  - **schemaVersion ≤ 1** — server returns a random `inviteToken` the
- *    invitee redeems via the `hq://accept/{token}` magic link. `magicLink`
- *    is populated so the caller can print or paste it.
- *  - **schemaVersion 2+** (current production) — membership row is
- *    email-keyed and authoritative. There is no token; the invitee
- *    accepts by signing into HQ with the same email. `inviteToken` +
- *    `magicLink` are both `undefined`; the caller prints sign-in
- *    instructions instead.
- *
- * `membership` is always populated when the server returned 2xx.
- *
- * Email-related fields are populated only when hq-pro performed a
- * server-side Resend send (caller passed `sendEmail: true` AND the
- * server supports it). Pre-resend servers omit them entirely.
- */
-export interface InviteResult {
-  inviteToken?: string;
-  magicLink?: string;
-  membership: {
-    membershipKey?: string;
-    role: string;
-    status: string;
-    inviteToken?: string;
-    inviteeEmail?: string;
-  };
-  /** Resend send actually fired and accepted by Resend. */
-  emailSent?: boolean;
-  /** Resend skipped because the server has no RESEND_API_KEY configured. */
-  emailSkipped?: boolean;
-  /** Resend was attempted but failed — human-readable reason. */
-  emailError?: string;
-  /**
-   * Present when hq-pro treated the target as a fleet agent (guest invite).
-   * Always `false` on the agent path — host keeps billing.
-   */
-  activationBilled?: boolean;
-  /** Host company uid when the server returned an agent guest-invite result. */
-  hostCompanyUid?: string;
-}
-
-export interface ResendInviteOptions {
-  inviteeEmail: string;
-  companyUid: string;
-  callerUid: string;
-  token: string;
-}
-
-/**
- * Outcome of `hq members invite --resend`. No new membership row was
- * created — the server's `resend: true` short-circuit just re-fires the
- * Resend email against the existing pending row.
- */
-export interface ResendInviteResult {
-  resent: true;
-  emailSent: boolean;
-  emailSkipped: boolean;
-  emailError?: string;
-}
-
-export interface DetectedTarget {
-  type: "email" | "person" | "agent";
-  value: string;
-  /** True when the target is a fleet agent (uid or machine email). */
-  isAgent?: boolean;
-}
-
-export function detectTarget(target: string): DetectedTarget | null {
-  const trimmed = target.trim();
-  if (AGENT_UID_PATTERN.test(trimmed)) {
-    return { type: "agent", value: trimmed, isAgent: true };
-  }
-  if (AGENT_EMAIL_PATTERN.test(trimmed)) {
-    return {
-      type: "email",
-      value: trimmed.toLowerCase(),
-      isAgent: true,
-    };
-  }
-  if (EMAIL_PATTERN.test(trimmed)) {
-    return { type: "email", value: trimmed.toLowerCase() };
-  }
-  if (PERSON_UID_PATTERN.test(trimmed)) {
-    return { type: "person", value: trimmed };
-  }
-  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, personUid (prs_…), agent uid (agt_…), or agent email (agt-…@agents.getindigo.ai)`,
-    );
-  }
-
-  // Fleet agents: same invite command as humans, but only member|admin.
-  // Host company keeps billing — server never double-bills on guest invite.
-  if (detected.isAgent) {
-    if (!AGENT_INVITE_ROLES.has(options.role)) {
-      throw new Error(
-        `Agents can only be invited as member or admin (got '${options.role}'). Host company keeps billing.`,
-      );
-    }
-    if (options.paths) {
-      throw new Error(
-        "--paths / guest role is not valid for agents — invite as member or admin",
-      );
-    }
-    if (options.groupIds && options.groupIds.length > 0) {
-      throw new Error(
-        "--groups is not supported on agent invites — share secrets after membership with `hq secrets share`",
-      );
-    }
-  }
-
-  if (
-    options.groupIds &&
-    options.groupIds.length > 0 &&
-    (detected.type === "person" || detected.type === "agent")
-  ) {
-    throw new Error(
-      "--groups is only valid on email-keyed invites (server rejects personUid + groupIds with 400)",
-    );
-  }
-
-  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;
-  if (options.groupIds && options.groupIds.length > 0) {
-    body.groupIds = options.groupIds;
-  }
-  if (options.sendEmail === true) body.sendEmail = true;
-
-  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,
-      err.code,
-    );
-  }
-
-  const data = (await res.json()) as {
-    membership?: {
-      membershipKey?: string;
-      role: string;
-      status: string;
-      inviteToken?: string;
-      inviteeEmail?: string;
-      schemaVersion?: number;
-    };
-    inviteToken?: string;
-    emailSent?: boolean;
-    emailSkipped?: boolean;
-    emailError?: string;
-    activationBilled?: boolean;
-    hostCompanyUid?: string;
-  };
-  if (!data.membership) {
-    const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
-    throw new Error(
-      `Invite endpoint returned 2xx with no membership row (response keys: ${keys}). ` +
-        "This is a server-side regression — file an issue.",
-    );
-  }
-  // Two server schemas in the wild:
-  //   - Legacy (schemaVersion ≤ 1): response carries a random `inviteToken`
-  //     the invitee redeems via `hq://accept/{token}`.
-  //   - Current (schemaVersion 2+): membership row is email-keyed and
-  //     authoritative — there is no token. The invitee accepts by signing
-  //     into HQ with the invited email. The CLI must NOT throw here
-  //     (previously did: "response did not include an invite token") — the
-  //     invite IS successfully created on the server; the caller just gets
-  //     undefined for inviteToken/magicLink and prints sign-in instructions.
-  const inviteToken = data.inviteToken ?? data.membership.inviteToken;
-  return {
-    ...(inviteToken
-      ? { inviteToken, magicLink: `hq://accept/${inviteToken}` }
-      : {}),
-    membership: data.membership,
-    // Pre-resend hq-pro versions omit these fields entirely — leave the
-    // result fields undefined so the caller's "is server-side email
-    // supported?" check works via `typeof result.emailSent === 'boolean'`.
-    ...(typeof data.emailSent === "boolean" ? { emailSent: data.emailSent } : {}),
-    ...(typeof data.emailSkipped === "boolean"
-      ? { emailSkipped: data.emailSkipped }
-      : {}),
-    ...(data.emailError ? { emailError: data.emailError } : {}),
-    ...(typeof data.activationBilled === "boolean"
-      ? { activationBilled: data.activationBilled }
-      : {}),
-    ...(typeof data.hostCompanyUid === "string"
-      ? { hostCompanyUid: data.hostCompanyUid }
-      : {}),
-  };
-}
-
-/**
- * Re-fire the invite email against an existing pending row without
- * creating a new membership row. Maps to hq-pro `/membership/invite`
- * with `{ resend: true }` (see hq-pro PR #140). Server gates on the
- * caller's admin/owner role.
- *
- * Returns the email-send status. 404 here means "no pending row exists
- * for this email+company pair — re-invite without --resend first."
- */
-export async function resendInvite(
-  options: ResendInviteOptions,
-): Promise<ResendInviteResult> {
-  const detected = detectTarget(options.inviteeEmail);
-  if (!detected || detected.type !== "email") {
-    throw new Error(
-      "--resend requires an email target (the resend path is email-keyed-row only)",
-    );
-  }
-
-  const res = await vaultApiFetch({
-    token: options.token,
-    path: "/membership/invite",
-    method: "POST",
-    body: {
-      companyUid: options.companyUid,
-      // Server's invite handler still requires `role` even on the resend
-      // short-circuit. Pass the safe default — server ignores it on this
-      // path (the pending row already has its real role).
-      role: "member",
-      inviteeEmail: detected.value,
-      invitedBy: options.callerUid,
-      resend: true,
-    },
-  });
-
-  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,
-    );
-  }
-
-  const data = (await res.json()) as {
-    resent?: boolean;
-    emailSent?: boolean;
-    emailSkipped?: boolean;
-    emailError?: string;
-  };
-  if (data.resent !== true) {
-    throw new Error(
-      "Resend endpoint returned 2xx without `resent: true` — the connected hq-pro likely doesn't support `resend: true` yet. Upgrade hq-pro or re-invite without --resend.",
-    );
-  }
-  return {
-    resent: true,
-    emailSent: data.emailSent === true,
-    emailSkipped: data.emailSkipped === true,
-    ...(data.emailError ? { emailError: data.emailError } : {}),
-  };
-}
-
-export class InviteHttpError extends Error {
-  constructor(
-    public status: number,
-    message: string,
-    public code?: string,
-  ) {
-    super(message);
-    this.name = "InviteHttpError";
-  }
-}
-
-export function formatInviteHttpError(
-  status: number,
-  fallback: string,
-  code?: string,
-): string {
-  if (status === 401) return "Not authenticated — please run `hq login`";
-  if (status === 403) {
-    if (code === "ADMIN_ROLE_TARGET_RESTRICTED") {
-      return "Admin can only invite at role=member; ask an owner to invite at this role";
-    }
-    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,
-      err.code,
-    );
-  }
-  // Server schema: `{ pending: [...] }`. Earlier dev branches used
-  // `{ invites: [...] }` which the CLI still accepts as a fallback for
-  // operators running staging stages that haven't caught up yet.
-  const data = (await res.json()) as {
-    pending?: PendingInvite[] | null;
-    invites?: PendingInvite[] | null;
-  };
-  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 role-change target to an active membership key.
- *
- * Pending invites are email-keyed, but claimed active memberships are keyed by
- * personUid. Consequently, role changes must look up email targets in the
- * active member list instead of synthesizing an `email:...#company` key.
- */
-export async function resolveRoleChangeTarget(
-  token: string,
-  companyUid: string,
-  target: string,
-): Promise<string> {
-  if (target.includes("#")) return target;
-
-  const detected = detectTarget(target);
-  if (detected?.type === "person" || detected?.type === "agent") {
-    return `${detected.value}#${companyUid}`;
-  }
-  if (detected?.type === "email") {
-    // Active fleet-agent guest memberships are keyed agt_…#cmp_…, not by
-    // personEmail enrichment. Map machine emails the same way revoke does
-    // before falling through to the human roster lookup.
-    if (detected.isAgent) {
-      const local = detected.value.split("@")[0] ?? "";
-      const m = local.match(/^agt-(.+)$/i);
-      if (m) return `agt_${m[1].toUpperCase()}#${companyUid}`;
-    }
-
-    const members = await listActiveMembers(token, companyUid);
-    const member = members.find(
-      (candidate) =>
-        candidate.personEmail?.trim().toLowerCase() === detected.value,
-    );
-    if (member) return member.membershipKey;
-
-    throw new Error(
-      `No active member has email '${detected.value}' in this company. ` +
-        "Run `hq members list` to find the member, or use their prs_ personUid.",
-    );
-  }
-
-  throw new Error(
-    `Invalid target '${target}': use an email, prs_ personUid, agt_ agentUid, or full membership key`,
-  );
-}
-
-/**
- * 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") {
-    // Active agent guest memberships are personUid-keyed (agt_…#cmp_…), not
-    // email-keyed. Map machine emails to that key so revoke works after invite.
-    if (detected.isAgent) {
-      const local = detected.value.split("@")[0] ?? "";
-      const m = local.match(/^agt-(.+)$/i);
-      if (m) return `agt_${m[1].toUpperCase()}#${companyUid}`;
-    }
-    return `email:${detected.value}#${companyUid}`;
-  }
-  if (detected?.type === "person" || detected?.type === "agent") {
-    return `${detected.value}#${companyUid}`;
-  }
-  return arg;
-}
-
-function printEmailStatus(opts: {
-  recipient: string;
-  sent: boolean;
-  skipped: boolean;
-  error?: string;
-}): void {
-  if (opts.sent) {
-    console.log(
-      chalk.green(`✓ Invitation email sent to ${opts.recipient.toLowerCase()}`),
-    );
-    return;
-  }
-  if (opts.skipped) {
-    console.log(
-      chalk.yellow(
-        `⚠ Email send skipped — hq-pro has no RESEND_API_KEY configured for this stage.`,
-      ),
-    );
-    return;
-  }
-  if (opts.error) {
-    console.log(chalk.yellow(`⚠ Email send failed: ${opts.error}`));
-    return;
-  }
-  console.log(
-    chalk.yellow(
-      `⚠ Email status unknown — hq-pro returned no email fields (likely a pre-resend deploy).`,
-    ),
-  );
-}
-
-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,
-      err.code,
-    );
-  }
-}
-
-/**
- * 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: Role,
-): Promise<void> {
-  if (!VALID_ROLES.has(newRole)) {
-    throw new Error(
-      `Invalid role '${newRole}': must be one of owner, admin, member, guest`,
-    );
-  }
-
-  const res = await vaultApiFetch({
-    token,
-    path: "/membership/role",
-    method: "POST",
-    body: { companyUid, membershipKey, newRole },
-  });
-  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,
-    );
-  }
-}
-
-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)");
-
-  // 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("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);
-        const membershipKey = await resolveRoleChangeTarget(
-          token,
-          companyUid,
-          target,
-        );
-
-        await changeMemberRole(token, companyUid, membershipKey, role as Role);
-        console.log(
-          chalk.green(`Updated role for '${target}' to ${role}`),
-        );
-        if (role === "owner" || role === "admin") {
-          // Clarify the common confusion: owners/admins already get full
-          // access to ALL company context automatically via the role bypass
-          // (hq-pro resolveEffectivePermission) — there is no separate context
-          // grant to give them. What they SEE locally is governed by their sync
-          // mode, not by access.
-          console.log(
-            chalk.dim(
-              `${role === "owner" ? "Owners" : "Admins"} automatically have full read and write access to all of this company's context — no separate context grant is needed.\n` +
-                `What they actually see synced to their machine is governed by their sync mode (\`hq sync mode\`), not by access.`,
-            ),
-          );
-        }
-      } catch (err) {
-        if (err instanceof InviteHttpError) {
-          console.error(chalk.red(err.message));
-          process.exit(1);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  members
-    .command("invite <target>")
-    .description(
-      "Invite a person or fleet agent to the company. People: email or prs_…. Agents: agt_… or agt-…@agents.getindigo.ai (member|admin; host keeps billing, no double charge).",
-    )
-    .option(
-      "--role <role>",
-      "Role: person → owner|admin|member|guest; agent → member|admin only",
-      "member",
-    )
-    .option(
-      "--paths <prefixes>",
-      "Comma-separated allowed prefixes (only valid with --role guest)",
-    )
-    .option(
-      "--groups <ids>",
-      "Comma-separated secret-group ids the invitee will be added to on claim (email-keyed invites only)",
-    )
-    .option(
-      "--send-email",
-      "Have hq-pro send an invitation email via Resend (default true for email-keyed invites). Pre-resend hq-pro versions ignore this and the legacy 'no email sent' instructions print instead.",
-      true,
-    )
-    .option(
-      "--no-send-email",
-      "Skip the server-side Resend send — only create the pending DDB row. Useful when you're scripting bulk invites and will send the announcement out-of-band.",
-    )
-    .option(
-      "--resend",
-      "Re-fire the invitation email against an existing pending row without creating a new row. Maps to hq-pro `resend: true` short-circuit. Email-keyed invites only.",
-    )
-    .action(
-      async (
-        target: string,
-        opts: {
-          role: string;
-          paths?: string;
-          groups?: string;
-          sendEmail: boolean;
-          resend?: boolean;
-        },
-      ) => {
-        let token: string | undefined;
-        let companyUid: string | undefined;
-        let companySlug: string | undefined;
-        try {
-          token = await ensureCognitoToken();
-          companySlug = members.opts().company as string | undefined;
-          companyUid = await getCompanyUid(token, companySlug);
-          const callerUid = await getCallerPersonUid(token);
-
-          // --resend short-circuits to the server's re-fire path. No new row.
-          if (opts.resend === true) {
-            const resendResult = await resendInvite({
-              inviteeEmail: target,
-              companyUid,
-              callerUid,
-              token,
-            });
-            console.log(
-              chalk.green(
-                `Re-fired invite email for ${target.toLowerCase()} (existing pending row left untouched)`,
-              ),
-            );
-            console.log();
-            printEmailStatus({
-              recipient: target,
-              sent: resendResult.emailSent,
-              skipped: resendResult.emailSkipped,
-              error: resendResult.emailError,
-            });
-            return;
-          }
-
-          const groupIds = opts.groups
-            ? opts.groups.split(",").map((g) => g.trim()).filter(Boolean)
-            : undefined;
-
-          const result = await inviteMember({
-            target,
-            role: opts.role,
-            paths: opts.paths,
-            groupIds,
-            // Agents join actively — no Resend email.
-            sendEmail: detectTarget(target)?.isAgent ? false : opts.sendEmail,
-            companyUid,
-            callerUid,
-            token,
-          });
-
-          const agentTarget = detectTarget(target)?.isAgent === true;
-          console.log(
-            chalk.green(
-              `Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`,
-            ),
-          );
-          // Agent path is confirmed only when the server returned the guest-invite
-          // envelope (activationBilled present) AND status is active. A pending
-          // row means this hq-pro stage has not rolled the agent invite path yet —
-          // do NOT claim active join / no-double-bill.
-          if (
-            agentTarget &&
-            result.membership.status === "active" &&
-            typeof result.activationBilled === "boolean"
-          ) {
-            console.log(
-              chalk.dim(
-                `Fleet agent: active membership granted immediately` +
-                  (result.hostCompanyUid
-                    ? ` (host ${result.hostCompanyUid} keeps billing)`
-                    : " (host keeps billing, no double charge)") +
-                  `. Next: share secrets / vault paths as needed (\`hq secrets share\`, \`/new-agent\`).`,
-              ),
-            );
-            console.log();
-            return;
-          }
-          if (agentTarget && result.membership.status !== "active") {
-            console.log(
-              chalk.yellow(
-                "⚠ Agent invite landed as a pending membership — this hq-pro stage may not yet have multi-company agent invite. Wait for prod deploy of the agent membership path, then re-invite (or revoke this pending row).",
-              ),
-            );
-            console.log();
-            return;
-          }
-          console.log();
-          if (result.magicLink) {
-            // Legacy server schema — magic-link redemption.
-            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.",
-              ),
-            );
-            return;
-          }
-
-          // schemaVersion 2+ — email-keyed authoritative membership row.
-          // Three output branches depending on whether the server-side
-          // Resend send fired:
-          //   (a) emailSent === true  → "email sent" success line
-          //   (b) emailSkipped === true → server has no RESEND_API_KEY;
-          //       fall back to the manual-notify instructions
-          //   (c) emailSent/emailSkipped both undefined → pre-resend
-          //       hq-pro, doesn't understand `sendEmail` at all; fall
-          //       back to the manual-notify instructions
-          const inviteeEmail =
-            result.membership.inviteeEmail ??
-            (typeof target === "string" && target.includes("@")
-              ? target
-              : undefined);
-          const emailDelivered = result.emailSent === true;
-          if (emailDelivered) {
-            printEmailStatus({
-              recipient: inviteeEmail ?? target,
-              sent: true,
-              skipped: false,
-              error: undefined,
-            });
-            if (result.membership.membershipKey) {
-              console.log();
-              console.log(
-                chalk.dim(`Membership key: ${result.membership.membershipKey}`),
-              );
-            }
-            return;
-          }
-          // Email-send failed or wasn't attempted — surface the manual path.
-          if (result.emailError) {
-            console.log(
-              chalk.yellow(`⚠ Email send failed: ${result.emailError}`),
-            );
-            console.log();
-          }
-          console.log(
-            chalk.yellow(
-              "⚠ No email was sent. The pending membership row exists; the invitee needs to sign in manually to claim it.",
-            ),
-          );
-          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.computer with that email address.`,
-          );
-          console.log(
-            `  2. Or use the hq-console UI at https://hq.computer to issue the`,
-          );
-          console.log(
-            `     invite instead — the UI path triggers an automated email via Resend.`,
-          );
-          if (result.emailSkipped !== true && result.emailSent === undefined) {
-            console.log();
-            console.log(
-              chalk.dim(
-                "Tip: this hq-pro deploy doesn't support server-side email yet (`sendEmail` ignored). Ask an operator to ship hq-pro PR #140 + provision the ResendApiKey SST secret.",
-              ),
-            );
-          } else if (result.emailSkipped === true) {
-            console.log();
-            console.log(
-              chalk.dim(
-                "Tip: hq-pro reported `emailSkipped: true` — its `RESEND_API_KEY` SST secret isn't set for this stage.",
-              ),
-            );
-          }
-          console.log();
-          console.log(
-            chalk.dim(
-              "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}`),
-            );
-          }
-        } catch (err) {
-          // A 409 may refer to either an active membership or an existing
-          // pending invite. Probe both views so email targets get actionable
-          // guidance while preserving the terminal exit-0 behavior for bulk
-          // invite scripts.
-          if (
-            err instanceof InviteHttpError &&
-            err.code === "MEMBERSHIP_ALREADY_EXISTS"
-          ) {
-            const detected = detectTarget(target);
-            const normalizedEmail =
-              detected?.type === "email" ? detected.value : undefined;
-
-            if (normalizedEmail && token && companyUid) {
-              // Preserve --company in copy-paste hints so multi-company
-              // callers don't hit "Multiple active companies" on --resend.
-              const companyFlag = companySlug
-                ? ` --company ${companySlug}`
-                : "";
-              const resendHint =
-                `hq members invite ${normalizedEmail}${companyFlag} --resend`;
-
-              try {
-                const pending = await listPendingInvites(token, companyUid);
-                if (
-                  pending.some(
-                    (invite) =>
-                      invite.inviteeEmail?.trim().toLowerCase() ===
-                      normalizedEmail,
-                  )
-                ) {
-                  console.log(
-                    chalk.yellow(
-                      `${normalizedEmail} already has a pending invite. ` +
-                        `Use \`${resendHint}\` to re-send it.`,
-                    ),
-                  );
-                  return;
-                }
-              } catch {
-                // Pending-list visibility can vary by server version or role.
-                // Fall through to the active-member probe and generic copy.
-              }
-
-              try {
-                const activeMembers = await listActiveMembers(token, companyUid);
-                if (
-                  activeMembers.some(
-                    (member) =>
-                      member.personEmail?.trim().toLowerCase() ===
-                      normalizedEmail,
-                  )
-                ) {
-                  console.log(
-                    chalk.yellow(
-                      `${normalizedEmail} is already a member of this company — nothing to do.`,
-                    ),
-                  );
-                  return;
-                }
-              } catch {
-                // Preserve the original conflict as the source of truth and
-                // use copy that remains accurate when the probes are hidden.
-              }
-
-              console.log(
-                chalk.yellow(
-                  `${normalizedEmail} already has a membership or pending invite for this company. ` +
-                    `If the invite is pending, use \`${resendHint}\`.`,
-                ),
-              );
-              return;
-            }
-
-            console.log(
-              chalk.yellow(
-                `${target.toLowerCase()} is already a member of this company — nothing to do.`,
-              ),
-            );
-            return;
-          }
-          if (err instanceof InviteHttpError) {
-            console.error(
-              chalk.red(
-                formatInviteHttpError(err.status, err.message, err.code),
-              ),
-            );
-            process.exit(1);
-          }
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  members
-    .command("list")
-    .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);
-
-        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 (activeMembers.length === 0) {
-          console.log(chalk.gray("No active members found for this company."));
-          return;
-        }
-
-        const emailW = Math.max(
-          5,
-          ...activeMembers.map((m) => (m.personEmail ?? m.personUid).length),
-        );
-        const roleW = Math.max(4, ...activeMembers.map((m) => m.role.length));
-        console.log(
-          chalk.bold(
-            ["EMAIL".padEnd(emailW), "ROLE".padEnd(roleW), "NAME"].join("  "),
-          ),
-        );
-        for (const m of activeMembers) {
-          const email = m.personEmail ?? m.personUid;
-          const name = m.personName ?? m.personSlug ?? "";
-          console.log(
-            [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
-              ? 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);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  members
-    .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);
-
-        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 =
-            err.status === 403
-              ? err.code === "ADMIN_ROLE_TARGET_RESTRICTED"
-                ? "Admin can only revoke role=member; ask an owner to revoke this membership"
-                : "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, err.code);
-          console.error(chalk.red(msg));
-          process.exit(1);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-}