@indigoai-us/hq-cli 5.94.1 → 5.94.2

package/dist/commands/company-transfer.js

@@ -0,0 +1,664 @@
+import chalk from "chalk";
+import * as readline from "node:readline";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getEntityUid } from "../utils/vault-api.js";
+import { listActiveMembers } from "./members.js";
+/**
+ * `hq company transfer` — company ownership handover (client-service-pack
+ * US-010). The server adds ZERO new API routes (vault-api-hq-prod sits at the
+ * 600-route quota), so the CLI half multiplexes onto two EXISTING routes:
+ *
+ *   - WRITES ride `POST /membership/role` with a body discriminator
+ *     `action: "transfer-initiate" | "transfer-accept" | "transfer-decline" |
+ *     "transfer-cancel"`. The ordinary role payload has never carried an
+ *     `action` field, so the shapes cannot collide.
+ *   - The READ rides `GET /membership/company/{companyUid}?view=transfers`;
+ *     without that exact `view` value the route returns the member roster as
+ *     before.
+ *
+ * TWO-PARTY BY CONSTRUCTION. `initiate` NOMINATES; it does not transfer
+ * anything. Ownership moves only when the nominee runs `accept`. The four write
+ * transitions (initiate / accept / decline / cancel) all multiplex through one
+ * POST with an explicit `action`, matching the server's route shape.
+ *
+ * ABSENT-FIELD DISCIPLINE (policy `hq-absent-field-never-means-constraining-value`).
+ * This flow spans two repos that deploy in EITHER order, so absence is load
+ * bearing in both directions and is handled in both directions here:
+ *
+ *   - REQUESTS: a flag the operator did not pass is OMITTED from the body — it
+ *     is never defaulted to a value on the wire. `--initiator-role` unset sends
+ *     no `initiatorRole` at all, so the server applies its own reversible
+ *     "keep them as admin" default; the CLI can therefore never turn silence
+ *     into `remove`. Same for `--transfer-id` (absent = "the pending one").
+ *   - RESPONSES: fields are read with presence and value SEPARATELY
+ *     ({@link readWireField}), because an OLDER server omits fields a newer CLI
+ *     knows about. An absent `effects.initiator` renders as "not reported",
+ *     never as "removed" — the CLI must not narrate a destructive outcome it
+ *     was never actually told about.
+ *
+ * Conventions mirror `company.ts` / `files.ts`: ensureCognitoToken() →
+ * getEntityUid() → vaultApiFetch() → error-check → chalk output, with the
+ * confirmation prompt behind an injectable seam so tests can drive it.
+ */
+/** The four write transitions the server accepts. */
+export const TRANSFER_ACTIONS = [
+    "initiate",
+    "accept",
+    "decline",
+    "cancel",
+];
+/**
+ * Legal `--initiator-role` values. `owner` is deliberately absent: a handover
+ * where the outgoing owner keeps `owner` is not a handover. `remove` is the
+ * ONLY value that takes them off the company, and it can only ever arrive from
+ * an explicit flag.
+ */
+export const INITIATOR_ROLE_VALUES = [
+    "admin",
+    "member",
+    "guest",
+    "remove",
+];
+/**
+ * What the SERVER falls back to when `initiatorRole` is absent. Mirrored here
+ * only so the confirmation preview can tell the operator what will happen; the
+ * CLI never puts this value on the wire, because sending it would defeat the
+ * point of leaving the field absent.
+ */
+export const DEFAULT_INITIATOR_ROLE = "admin";
+/**
+ * Read a field off a server response reporting presence and value SEPARATELY.
+ *
+ * The CLI-side twin of hq-pro's `readField`. `body.x ?? fallback` is wrong here
+ * because it makes an OLDER server's omitted field indistinguishable from a
+ * newer server explicitly sending `null`/`false`/`""` — and every caller below
+ * needs to say "this server didn't tell me" rather than invent an answer.
+ */
+export function readWireField(body, key) {
+    if (!body || typeof body !== "object") {
+        return { present: false, value: undefined };
+    }
+    if (!Object.prototype.hasOwnProperty.call(body, key)) {
+        return { present: false, value: undefined };
+    }
+    const value = body[key];
+    if (value === undefined)
+        return { present: false, value: undefined };
+    return { present: true, value: value };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse `--initiator-role`.
+ *
+ * Returns `undefined` when the flag was NOT passed, and that `undefined` means
+ * "omit the field entirely" — never "remove", and never a substituted default.
+ * A present-but-invalid value throws instead of falling back, so a typo can
+ * never be silently reinterpreted as a different disposition.
+ */
+export function parseInitiatorRole(raw) {
+    if (raw === undefined)
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === "owner") {
+        throw new Error("--initiator-role cannot be 'owner' — a transfer must downgrade the outgoing owner");
+    }
+    if (INITIATOR_ROLE_VALUES.includes(v)) {
+        return v;
+    }
+    throw new Error(`--initiator-role must be one of ${INITIATOR_ROLE_VALUES.join(", ")} (got '${raw}')`);
+}
+/**
+ * The wire prefix that turns `POST /membership/role` into a transfer request.
+ * Mirrors the server's `TRANSFER_ACTION_PREFIX` in `_ownership-transfer.ts`:
+ * a body whose `action` starts with `transfer-` is a transfer; anything else
+ * (including no `action` at all) is an ordinary role change.
+ */
+export const TRANSFER_ACTION_PREFIX = "transfer-";
+/**
+ * The query discriminator on `GET /membership/company/{companyUid}` that
+ * selects the transfer surface instead of the member roster. Mirrors the
+ * server's `TRANSFER_HISTORY_VIEW` (exact match on the server side).
+ */
+export const TRANSFER_HISTORY_VIEW = "transfers";
+/**
+ * Build the `POST /membership/role` transfer body. The CLI-side `action`
+ * ("initiate" | …) is prefixed to the wire discriminator ("transfer-initiate"
+ * | …) HERE, so no call site can accidentally post an unprefixed action that
+ * the server would route to the ordinary role-change handler.
+ *
+ * Every optional field is included ONLY when the caller actually supplied it.
+ * This is the single choke point for the request half of the absent-field rule:
+ * if a value is not here, the server sees no key at all and applies its own
+ * safe default, which keeps the CLI correct against a server that predates any
+ * of these fields.
+ */
+export function buildTransferBody(params) {
+    const body = {
+        companyUid: params.companyUid,
+        action: `${TRANSFER_ACTION_PREFIX}${params.action}`,
+    };
+    if (params.targetPersonUid !== undefined) {
+        body.targetPersonUid = params.targetPersonUid;
+    }
+    if (params.initiatorRole !== undefined) {
+        body.initiatorRole = params.initiatorRole;
+    }
+    if (params.transferId !== undefined)
+        body.transferId = params.transferId;
+    if (params.reason !== undefined)
+        body.reason = params.reason;
+    return body;
+}
+// ---------------------------------------------------------------------------
+// Human-readable outcome descriptions
+// ---------------------------------------------------------------------------
+/**
+ * Describe what the confirmation prompt should say happens to the OUTGOING
+ * owner. Absence resolves to the reversible, non-destructive sentence.
+ */
+export function describeInitiatorOutcome(role) {
+    if (role === undefined) {
+        return `stay on the company as ${DEFAULT_INITIATOR_ROLE} (the default — NOT removed)`;
+    }
+    if (role === "remove")
+        return "be REMOVED from the company entirely";
+    return `be downgraded to ${role}`;
+}
+/**
+ * Render the `effects` block of an accepted transfer.
+ *
+ * Reads every field for PRESENCE first. An older server that does not send
+ * `effects`, or omits a field inside it, gets an honest "not reported" line —
+ * inventing "removed" or "unchanged" here would be the CLI asserting a
+ * destructive outcome it has no evidence for.
+ */
+export function describeEffects(rawEffects) {
+    const effects = asRecord(rawEffects);
+    if (!effects) {
+        return [
+            "This server did not report the resulting changes. Run " +
+                "`hq company transfer status` to confirm what actually moved.",
+        ];
+    }
+    const lines = [];
+    const targetRole = readWireField(effects, "targetRole");
+    lines.push(targetRole.present
+        ? `New owner role:   ${String(targetRole.value)}`
+        : "New owner role:   not reported by this server");
+    const initiator = readWireField(effects, "initiator");
+    const initiatorRole = readWireField(effects, "initiatorRole");
+    if (!initiator.present) {
+        lines.push("Previous owner:   not reported by this server (no removal implied)");
+    }
+    else if (initiator.value === "removed") {
+        lines.push("Previous owner:   REMOVED from the company");
+    }
+    else if (initiator.value === "downgraded") {
+        lines.push(`Previous owner:   downgraded to ${initiatorRole.present ? String(initiatorRole.value) : "a non-owner role"}`);
+    }
+    else if (initiator.value === "already-at-role") {
+        lines.push(`Previous owner:   already at ${initiatorRole.present ? String(initiatorRole.value) : "the target role"}`);
+    }
+    else {
+        lines.push(`Previous owner:   ${String(initiator.value)}`);
+    }
+    const custody = readWireField(effects, "custody");
+    lines.push(custody.present
+        ? `Vault custody:    ${String(custody.value)}`
+        : "Vault custody:    not reported by this server");
+    const billingFollowed = readWireField(effects, "billingOwnerFollowed");
+    if (billingFollowed.present) {
+        lines.push(`Billing owner:    ${billingFollowed.value === true ? "follows the new owner" : "unchanged"}`);
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// Error rendering
+// ---------------------------------------------------------------------------
+/** Server failure codes → an operator-readable sentence. */
+const FAILURE_MESSAGES = {
+    NOT_AN_OWNER: "You must be an active owner of this company.",
+    TARGET_NOT_MEMBER: "That person is not a member of this company.",
+    TARGET_NOT_ACTIVE: "That person's membership is not active yet.",
+    TARGET_IS_SELF: "You cannot transfer the company to yourself.",
+    AGENT_ROLE_CAP: "A fleet agent cannot be made owner of a company.",
+    NO_PENDING_TRANSFER: "There is no pending ownership transfer for this company.",
+    TRANSFER_ID_MISMATCH: "That transfer id does not match the currently pending transfer.",
+    NOT_THE_NOMINEE: "Only the nominated person can accept or decline.",
+    NOT_THE_INITIATOR: "Only the owner who initiated it can cancel.",
+    OWNERSHIP_TRANSFER_CONFLICT: "The transfer changed underneath this request — re-check status and retry.",
+};
+function renderApiError(status, body) {
+    const code = readWireField(body, "code");
+    if (code.present && FAILURE_MESSAGES[String(code.value)]) {
+        return FAILURE_MESSAGES[String(code.value)];
+    }
+    const error = readWireField(body, "error");
+    if (error.present && typeof error.value === "string")
+        return error.value;
+    return `Request failed (HTTP ${status})`;
+}
+/**
+ * The real prompt. Refuses (rather than assuming yes) when stdin is not a TTY,
+ * so a transfer can never be initiated or accepted by a pipeline that simply
+ * had nobody to ask. `--yes` is the only non-interactive path, and it is an
+ * explicit operator act.
+ *
+ * Exported ONLY so the non-TTY refusal — the one confirmation path the
+ * injectable seam hides from the command tests — can be covered directly.
+ */
+export function realConfirm(message) {
+    if (!process.stdin.isTTY) {
+        console.error(chalk.red("Refusing to continue without confirmation: stdin is not a terminal. " +
+            "Re-run interactively, or pass --yes if you have already verified the change."));
+        return Promise.resolve(false);
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Target resolution
+// ---------------------------------------------------------------------------
+const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
+/**
+ * Resolve `--to` to a `personUid`. A uid is used as-is; anything else is
+ * matched (case-insensitively) against the company's ACTIVE roster by email,
+ * slug, or name, because the server requires a uid and only accepts a target
+ * who is already an active member.
+ */
+export function matchMemberTarget(members, target) {
+    const needle = target.trim().toLowerCase();
+    return members.find((m) => m.personEmail?.toLowerCase() === needle ||
+        m.personSlug?.toLowerCase() === needle ||
+        m.personName?.toLowerCase() === needle ||
+        m.personUid?.toLowerCase() === needle);
+}
+export async function resolveTargetPersonUid(token, companyUid, target) {
+    const trimmed = target.trim();
+    if (PERSON_UID_PATTERN.test(trimmed) || AGENT_UID_PATTERN.test(trimmed)) {
+        return { personUid: trimmed, label: trimmed };
+    }
+    const members = await listActiveMembers(token, companyUid);
+    const match = matchMemberTarget(members, trimmed);
+    if (!match) {
+        throw new Error(`No active member of this company matches '${target}'. ` +
+            "Pass a prs_… uid, or check `hq members list`.");
+    }
+    const label = match.personEmail
+        ? `${match.personEmail} (${match.personUid})`
+        : match.personUid;
+    return { personUid: match.personUid, label };
+}
+/**
+ * Post one transition. Returns the parsed success body, or throws with an
+ * operator-readable message.
+ */
+async function postTransfer(token, body) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/membership/role",
+        method: "POST",
+        body,
+    });
+    const parsed = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(renderApiError(res.status, parsed));
+    return parsed;
+}
+/** Look up the currently pending nomination, for the accept/decline preview. */
+async function fetchCurrent(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/membership/company/${encodeURIComponent(companyUid)}`,
+        // `view=transfers` (exact match) is the discriminator that selects the
+        // transfer surface; without it this route returns the member roster.
+        query: { view: TRANSFER_HISTORY_VIEW },
+    });
+    if (!res.ok)
+        return undefined;
+    const body = (await res.json().catch(() => ({})));
+    const pending = readWireField(body, "pending");
+    if (pending.present)
+        return asRecord(pending.value);
+    return asRecord(readWireField(body, "transfer").value);
+}
+/**
+ * `hq company transfer initiate|accept|decline|cancel`.
+ *
+ * `initiate` and `accept` are the two transitions that move (or commit to
+ * moving) ownership, so both stop for an explicit confirmation that spells out
+ * who becomes owner and what happens to the outgoing owner. `decline` and
+ * `cancel` only ever ABORT a nomination, so they do not prompt.
+ */
+export async function runCompanyTransfer(params, deps = {}) {
+    const confirm = deps.confirm ?? realConfirm;
+    // `--yes` is an explicit operator act and the ONLY way past the prompt. The
+    // change summary is printed either way, so even a scripted run leaves a
+    // record of exactly what was about to happen. Absence of `--yes` never
+    // resolves to "assume yes".
+    const gate = async (message) => params.yes === true ? true : confirm(message);
+    // Parsed BEFORE any network call so an invalid value never reaches the wire.
+    const initiatorRole = parseInitiatorRole(params.initiatorRoleRaw);
+    const token = await ensureCognitoToken();
+    const companyUid = await getEntityUid(token, {
+        companySlug: params.companySlug,
+    });
+    if (params.action === "initiate") {
+        if (!params.to) {
+            throw new Error("--to <email|prs_uid> is required for `initiate`.");
+        }
+        const target = await resolveTargetPersonUid(token, companyUid, params.to);
+        console.log(chalk.bold("\nOwnership transfer — nomination"));
+        console.log(`  Company:        ${params.companySlug} (${companyUid})`);
+        console.log(`  Becomes owner:  ${target.label}`);
+        console.log(`  You will:       ${describeInitiatorOutcome(initiatorRole)}`);
+        console.log(chalk.yellow("\n  This NOMINATES them. Ownership moves only once they accept.\n" +
+            "  On acceptance, owner role, billing authority, and vault custody all move."));
+        const ok = await gate(`\nNominate ${target.label} as owner of ${params.companySlug}?`);
+        if (!ok) {
+            console.log(chalk.yellow("Aborted — nothing was changed."));
+            return;
+        }
+        const result = await postTransfer(token, buildTransferBody({
+            companyUid,
+            action: "initiate",
+            targetPersonUid: target.personUid,
+            ...(initiatorRole !== undefined ? { initiatorRole } : {}),
+            ...(params.reason !== undefined ? { reason: params.reason } : {}),
+        }));
+        const transfer = asRecord(readWireField(result, "transfer").value);
+        const id = readWireField(transfer, "transferId");
+        console.log(chalk.green(`\nNominated ${target.label} as owner of ${params.companySlug}.`));
+        if (id.present)
+            console.log(`  Transfer id: ${String(id.value)}`);
+        console.log("  They must run `hq company transfer accept --company " +
+            `${params.companySlug}\` to complete it.`);
+        return;
+    }
+    if (params.action === "accept") {
+        const current = await fetchCurrent(token, companyUid);
+        const from = readWireField(current, "fromPersonUid");
+        // The disposition the outgoing owner PROPOSED. Absent (older server, or no
+        // readable pending row) must not be narrated as a removal.
+        const proposed = asRecord(readWireField(current, "proposedInitiatorDisposition").value);
+        const proposedKind = readWireField(proposed, "kind");
+        const proposedRole = readWireField(proposed, "role");
+        let outgoing;
+        if (initiatorRole !== undefined) {
+            outgoing = `${describeInitiatorOutcome(initiatorRole)} (your override)`;
+        }
+        else if (!proposedKind.present) {
+            outgoing =
+                `stay on as ${DEFAULT_INITIATOR_ROLE} unless they proposed otherwise ` +
+                    "(this server did not report the proposal)";
+        }
+        else if (proposedKind.value === "remove") {
+            outgoing = "be REMOVED from the company entirely (as they proposed)";
+        }
+        else {
+            outgoing = `be downgraded to ${proposedRole.present ? String(proposedRole.value) : DEFAULT_INITIATOR_ROLE} (as they proposed)`;
+        }
+        console.log(chalk.bold("\nOwnership transfer — accept"));
+        console.log(`  Company:        ${params.companySlug} (${companyUid})`);
+        console.log(`  You become:     owner`);
+        console.log(`  Current owner:  ${from.present ? String(from.value) : "not reported by this server"}`);
+        console.log(`  They will:      ${outgoing}`);
+        console.log(chalk.yellow("\n  This is the step that actually moves ownership: owner role,\n" +
+            "  billing authority, and vault custody. It is hard to reverse —\n" +
+            "  undoing it needs the NEW owner to transfer back."));
+        const ok = await gate(`\nAccept ownership of ${params.companySlug}?`);
+        if (!ok) {
+            console.log(chalk.yellow("Aborted — nothing was changed. The nomination is still pending."));
+            return;
+        }
+        const result = await postTransfer(token, buildTransferBody({
+            companyUid,
+            action: "accept",
+            ...(initiatorRole !== undefined ? { initiatorRole } : {}),
+            ...(params.transferId !== undefined
+                ? { transferId: params.transferId }
+                : {}),
+            ...(params.reason !== undefined ? { reason: params.reason } : {}),
+        }));
+        console.log(chalk.green(`\nYou are now the owner of ${params.companySlug}.`));
+        for (const line of describeEffects(readWireField(result, "effects").value)) {
+            console.log(`  ${line}`);
+        }
+        return;
+    }
+    // decline / cancel — both only ABORT a nomination, so neither prompts.
+    const result = await postTransfer(token, buildTransferBody({
+        companyUid,
+        action: params.action,
+        ...(params.transferId !== undefined
+            ? { transferId: params.transferId }
+            : {}),
+        ...(params.reason !== undefined ? { reason: params.reason } : {}),
+    }));
+    const transfer = asRecord(readWireField(result, "transfer").value);
+    const status = readWireField(transfer, "status");
+    console.log(chalk.green(params.action === "decline"
+        ? `Declined the ownership transfer for ${params.companySlug}.`
+        : `Cancelled the ownership transfer for ${params.companySlug}.`));
+    if (status.present)
+        console.log(`  Status: ${String(status.value)}`);
+}
+/** `hq company transfer status` — the pending nomination plus the audit trail. */
+export async function runCompanyTransferStatus(params) {
+    const token = await ensureCognitoToken();
+    const companyUid = await getEntityUid(token, {
+        companySlug: params.companySlug,
+    });
+    const query = { view: TRANSFER_HISTORY_VIEW };
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    const res = await vaultApiFetch({
+        token,
+        path: `/membership/company/${encodeURIComponent(companyUid)}`,
+        query,
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(renderApiError(res.status, body));
+    if (params.json) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    // `transfer` is sent as an explicit null when nothing has ever happened, so
+    // ABSENCE means the server is older and has no transfer surface at all —
+    // a genuinely different answer from "no transfer".
+    const transferRead = readWireField(body, "transfer");
+    if (!transferRead.present) {
+        console.log(chalk.yellow("This server did not report transfer state — it may predate company " +
+            "ownership transfer."));
+        return;
+    }
+    const current = asRecord(transferRead.value);
+    if (!current) {
+        console.log(`No ownership transfer has been recorded for ${params.companySlug}.`);
+    }
+    else {
+        const status = readWireField(current, "status");
+        const id = readWireField(current, "transferId");
+        const from = readWireField(current, "fromPersonUid");
+        const to = readWireField(current, "toPersonUid");
+        console.log(chalk.bold(`\nOwnership transfer — ${params.companySlug}`));
+        console.log(`  Status:      ${status.present ? String(status.value) : "unknown"}`);
+        if (id.present)
+            console.log(`  Transfer id: ${String(id.value)}`);
+        if (from.present)
+            console.log(`  From:        ${String(from.value)}`);
+        if (to.present)
+            console.log(`  To:          ${String(to.value)}`);
+        if (status.present && status.value === "pending") {
+            console.log(chalk.yellow("  Pending — ownership has NOT moved yet; the nominee must accept."));
+        }
+    }
+    const audit = readWireField(body, "audit");
+    const rows = Array.isArray(audit.value) ? audit.value : [];
+    if (rows.length > 0) {
+        console.log(chalk.bold("\nHistory"));
+        for (const raw of rows) {
+            const row = asRecord(raw);
+            const event = readWireField(row, "event");
+            const ts = readWireField(row, "timestamp");
+            const actor = readWireField(row, "actorPersonUid");
+            console.log(`  ${ts.present ? String(ts.value) : "?"}  ` +
+                `${event.present ? String(event.value) : "?"}  ` +
+                `by ${actor.present ? String(actor.value) : "?"}`);
+        }
+    }
+    const nextCursor = readWireField(body, "nextCursor");
+    if (nextCursor.present) {
+        console.log(`\n  More history: --cursor ${String(nextCursor.value)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Commander wiring
+// ---------------------------------------------------------------------------
+function fail(err) {
+    console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+/** Resolve `--company` from the transfer subcommand or the parent `company`. */
+function requireCompanySlug(local, parent) {
+    const slug = local ?? parent;
+    if (!slug)
+        throw new Error("--company <slug> is required.");
+    return slug;
+}
+export function registerCompanyTransferCommand(company, deps = {}) {
+    const transfer = company
+        .command("transfer")
+        .description("Transfer company ownership. Two-party: `initiate` nominates, and " +
+        "ownership moves only when the nominee runs `accept`.")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    const companyOf = (opts) => requireCompanySlug(opts.company ?? transfer.opts().company, company.opts().company);
+    transfer
+        .command("initiate")
+        .description("Nominate an active member as the new owner. Does NOT transfer ownership " +
+        "— the nominee must accept. Prompts for confirmation unless --yes.")
+        .requiredOption("--to <email|prs_uid>", "The member to nominate as owner")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--initiator-role <admin|member|guest|remove>", "What happens to you after the handover. Omit to keep the safe default " +
+        "(stay on as admin); only an explicit 'remove' takes you off.")
+        .option("--reason <text>", "Note recorded on the audit trail")
+        .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+        .action(async (opts) => {
+        try {
+            await runCompanyTransfer({
+                companySlug: companyOf(opts),
+                action: "initiate",
+                to: opts.to,
+                initiatorRoleRaw: opts.initiatorRole,
+                reason: opts.reason,
+                yes: opts.yes === true,
+            }, deps);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    transfer
+        .command("accept")
+        .description("Accept a pending nomination and become the owner. This is the step that " +
+        "actually moves ownership. Prompts for confirmation unless --yes.")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--transfer-id <id>", "Target a specific transfer. Omit to accept the currently pending one.")
+        .option("--initiator-role <admin|member|guest|remove>", "Override what happens to the outgoing owner. Omit to confirm what they " +
+        "proposed.")
+        .option("--reason <text>", "Note recorded on the audit trail")
+        .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+        .action(async (opts) => {
+        try {
+            await runCompanyTransfer({
+                companySlug: companyOf(opts),
+                action: "accept",
+                initiatorRoleRaw: opts.initiatorRole,
+                transferId: opts.transferId,
+                reason: opts.reason,
+                yes: opts.yes === true,
+            }, deps);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    transfer
+        .command("decline")
+        .description("Decline a pending nomination (nominee only).")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--transfer-id <id>", "Target a specific transfer. Omit to decline the currently pending one.")
+        .option("--reason <text>", "Note recorded on the audit trail")
+        .action(async (opts) => {
+        try {
+            await runCompanyTransfer({
+                companySlug: companyOf(opts),
+                action: "decline",
+                transferId: opts.transferId,
+                reason: opts.reason,
+            }, deps);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    transfer
+        .command("cancel")
+        .description("Cancel a nomination you initiated (initiating owner only).")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--transfer-id <id>", "Target a specific transfer. Omit to cancel the currently pending one.")
+        .option("--reason <text>", "Note recorded on the audit trail")
+        .action(async (opts) => {
+        try {
+            await runCompanyTransfer({
+                companySlug: companyOf(opts),
+                action: "cancel",
+                transferId: opts.transferId,
+                reason: opts.reason,
+            }, deps);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    transfer
+        .command("status")
+        .description("Show the current nomination and the company's transfer history.")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--limit <n>", "History page size")
+        .option("--cursor <cursor>", "History page cursor")
+        .option("--json", "Emit the raw server response")
+        .action(async (opts) => {
+        try {
+            await runCompanyTransferStatus({
+                companySlug: companyOf(opts),
+                limit: opts.limit,
+                cursor: opts.cursor,
+                json: opts.json === true,
+            });
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+//# sourceMappingURL=company-transfer.js.map

package/dist/commands/company.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getEntityUid } from "../utils/vault-api.js";
+import { registerCompanyTransferCommand } from "./company-transfer.js";
 /**
  * Parse a `--flag <true|false>` string into a boolean, or throw. Commander
  * passes the raw string; we validate strictly so a typo never silently writes
@@ -19,6 +20,8 @@ export function registerCompanyCommand(program) {
         .command("company")
         .description("Company-level settings")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
+    // `hq company transfer …` — ownership handover (client-service-pack US-010).
+    registerCompanyTransferCommand(company);
     const settings = company
         .command("settings")
         .description("Per-company settings (owner-only)");