@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/approvals.js

@@ -0,0 +1,518 @@
+import { readPositiveInt } from "../cli-values.js";
+import { COLLAB_BETA_NOTE, COLLAB_SUBJECT_PATH_HELP, COLLAB_SUBJECT_REF_HELP, collabSnippet, collabStyles, collabText, collabTrailer, collectRepeatable, formatCollabAge, formatCollabWriteResult, handleCollabAction, readCollabPath, renderTextTable, requireCollabSubject } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { COLLAB_GATE_KINDS, COLLAB_GATE_PROSE, COLLAB_SUBJECT_KINDS, COLLAB_SUBJECT_LABELS, GATE_KIND_SUBJECTS } from "@oxygen/shared/collab";
+import { Command } from "commander";
+/** Every gate, what it means, and which kinds it can be required on. */
+const COLLAB_GATE_GLOSS = COLLAB_GATE_KINDS
+    .map((gate) => `${gate} — ${COLLAB_GATE_PROSE[gate]}; set it on ${GATE_KIND_SUBJECTS[gate]
+    .map((kind) => COLLAB_SUBJECT_LABELS[kind].many)
+    .join(" or ")}`)
+    .join(". ");
+const COLLAB_GATE_FLAG_HELP = `Which gate: ${COLLAB_GATE_KINDS.join(" | ")}. ${COLLAB_GATE_GLOSS}.`;
+function requireCollabGate(value) {
+    const raw = readOption(value);
+    const gate = COLLAB_GATE_KINDS.find((candidate) => candidate === raw);
+    if (!gate) {
+        throw new OxygenError("invalid_request", `--gate must be one of: ${COLLAB_GATE_KINDS.join(", ")}. ${COLLAB_GATE_GLOSS}.`, {
+            details: { gate: raw, valid_gate_kinds: [...COLLAB_GATE_KINDS] },
+            exitCode: 2,
+        });
+    }
+    return gate;
+}
+function requireCollabSubjectKind(value) {
+    const raw = readOption(value);
+    const kind = COLLAB_SUBJECT_KINDS.find((candidate) => candidate === raw);
+    if (!kind) {
+        throw new OxygenError("invalid_subject_ref", `--default must be one of: ${COLLAB_SUBJECT_KINDS.join(", ")}.`, {
+            details: { subject_kind: raw, valid_kinds: [...COLLAB_SUBJECT_KINDS] },
+            exitCode: 2,
+        });
+    }
+    return kind;
+}
+/**
+ * At least one assignee. Commander cannot enforce this (the repeatable
+ * collector's `[]` default satisfies its mandatory check), and a request with
+ * nobody on it is the exact failure the API refuses to create: it looks filed,
+ * blocks the gate, and is discovered the next morning.
+ */
+function requireCollabAssignees(values) {
+    const assignees = values.map((value) => value.trim()).filter(Boolean);
+    if (assignees.length === 0) {
+        throw new OxygenError("invalid_request", "--assignee <email> is required: name at least one workspace member who can decide.", { exitCode: 2 });
+    }
+    return assignees;
+}
+/**
+ * Exactly one of --approve / --reject / --changes-requested. Neither zero nor
+ * two is guessable: `changes_requested` is a real decision that does NOT open
+ * the gate, so silently defaulting either way would either stall a campaign or
+ * launch one the client never agreed to.
+ */
+function requireCollabDecision(options) {
+    const selected = [];
+    if (options.approve)
+        selected.push("approve");
+    if (options.reject)
+        selected.push("reject");
+    if (options.changesRequested)
+        selected.push("changes_requested");
+    if (selected.length !== 1) {
+        throw new OxygenError("invalid_request", selected.length === 0
+            ? "Pass exactly one decision: --approve, --reject, or --changes-requested (asks for edits; does NOT open the gate)."
+            : `Pass only one decision flag — got ${selected.length}: --approve, --reject, and --changes-requested are mutually exclusive.`, { details: { decisions_passed: selected }, exitCode: 2 });
+    }
+    return selected[0];
+}
+/** Exactly one scope (--on or --default) and exactly one requirement flag. */
+function collabGateSetBody(options) {
+    const on = readOption(options.on);
+    const asDefault = readOption(options.default);
+    if (Boolean(on) === Boolean(asDefault)) {
+        throw new OxygenError("invalid_request", "Pass exactly one scope: --on <kind>:<id> for one object, or --default <kind> for every object of that kind.", { details: { on, default: asDefault }, exitCode: 2 });
+    }
+    if (Boolean(options.required) === Boolean(options.notRequired)) {
+        throw new OxygenError("invalid_request", "Pass exactly one of --required or --not-required.", { exitCode: 2 });
+    }
+    const gateKind = requireCollabGate(options.gate);
+    const subject = on ? requireCollabSubject(on) : null;
+    const subjectKind = subject ? subject.kind : requireCollabSubjectKind(asDefault ?? undefined);
+    if (!GATE_KIND_SUBJECTS[gateKind].includes(subjectKind)) {
+        throw new OxygenError("invalid_request", `The ${gateKind} gate applies to ${GATE_KIND_SUBJECTS[gateKind].map((kind) => COLLAB_SUBJECT_LABELS[kind].many).join(" or ")}, not ${COLLAB_SUBJECT_LABELS[subjectKind].many}.`, { details: { gate_kind: gateKind, subject_kind: subjectKind, applies_to: [...GATE_KIND_SUBJECTS[gateKind]] }, exitCode: 2 });
+    }
+    return {
+        subject_kind: subjectKind,
+        // null is meaningful here: it is what makes the policy the workspace
+        // default for the kind rather than a row about one object.
+        subject_id: subject ? subject.id : null,
+        gate_kind: gateKind,
+        required: Boolean(options.required),
+    };
+}
+function collabRequestRow(request) {
+    return [
+        collabText(request.id),
+        collabText(request.subject),
+        collabText(request.gate_kind),
+        collabText(request.status),
+        collabText(request.requested_by_email, "—"),
+        formatCollabAge(request.created_at),
+    ];
+}
+const COLLAB_REQUEST_HEADERS = ["ID", "SUBJECT", "GATE", "STATUS", "REQUESTED BY", "AGE"];
+function formatCollabRequestList(data) {
+    const styles = collabStyles();
+    const requests = Array.isArray(data.requests) ? data.requests.filter(isRecord) : [];
+    const lines = ["", styles.bold(`Approval requests (${requests.length})`)];
+    if (requests.length === 0) {
+        lines.push(`  ${styles.dim(collabText(data.hint, "No approval requests match those filters."))}`);
+    }
+    else {
+        lines.push(...renderTextTable(COLLAB_REQUEST_HEADERS, requests.map(collabRequestRow)));
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * The daily surface. Two sections and nothing else: what needs a decision from
+ * this reader, and where they were named. An item the reader cannot act on has
+ * no business being here, so there is no "everything else" section.
+ */
+function formatCollabInbox(data) {
+    const styles = collabStyles();
+    const pending = Array.isArray(data.pending_approvals) ? data.pending_approvals.filter(isRecord) : [];
+    const mentions = Array.isArray(data.mentions) ? data.mentions.filter(isRecord) : [];
+    const lines = ["", styles.bold(`Waiting on you (${pending.length})`)];
+    if (pending.length === 0) {
+        lines.push(`  ${styles.dim("No approvals are assigned to you.")}`);
+    }
+    else {
+        lines.push(...renderTextTable(COLLAB_REQUEST_HEADERS, pending.map(collabRequestRow)));
+    }
+    lines.push("", styles.bold(`Threads that name you (${mentions.length})`));
+    if (mentions.length === 0) {
+        lines.push(`  ${styles.dim("Nobody has mentioned you in an open thread.")}`);
+    }
+    else {
+        lines.push(...renderTextTable(["THREAD", "SUBJECT", "LAST COMMENT", "AGE"], mentions.map((thread) => {
+            const comments = Array.isArray(thread.comments) ? thread.comments.filter(isRecord) : [];
+            const last = comments[comments.length - 1];
+            return [
+                collabText(thread.id),
+                collabText(thread.subject),
+                collabSnippet(last?.body, 44) || collabText(thread.title, "—"),
+                formatCollabAge(thread.updated_at ?? thread.created_at),
+            ];
+        })));
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * `approvals show`. The reader here usually arrived from a link in an email and
+ * knows nothing but the id, so this answers the four questions a table cell
+ * cannot: what is being asked, on what, who owes the answer, and whether the
+ * request can still be decided. An expired request says so in the headline —
+ * `approvals decide` on it is refused by the API.
+ */
+function formatCollabRequestDetail(data) {
+    const styles = collabStyles();
+    const request = isRecord(data.request) ? data.request : data;
+    const status = collabText(request.status);
+    const lapsed = request.lapsed === true;
+    const badge = lapsed
+        ? styles.yellow("[EXPIRED]")
+        : request.opens_gate === true
+            ? styles.green("[APPROVED]")
+            : status === "pending"
+                ? styles.dim("[PENDING]")
+                : styles.yellow(`[${status.toUpperCase()}]`);
+    const assignees = Array.isArray(request.assignee_emails)
+        ? request.assignee_emails.filter((value) => typeof value === "string")
+        : [];
+    const lines = [
+        "",
+        `  ${badge} ${collabText(request.title, "Approval request")}`,
+        `  ${styles.dim("Request")}  ${collabText(request.id)}`,
+        `  ${styles.dim("Subject")}  ${collabText(request.subject)}`,
+        `  ${styles.dim("Gate")}     ${collabText(request.gate_kind)} — ${collabText(request.gate_meaning, "")}`,
+        `  ${styles.dim("Asked by")} ${collabText(request.requested_by_email, "someone")}`,
+        `  ${styles.dim("Decides")}  ${assignees.length > 0 ? assignees.join(", ") : "—"}`,
+    ];
+    const body = collabSnippet(request.body, 72);
+    if (body)
+        lines.push(`  ${styles.dim("Asking")}   ${body}`);
+    if (typeof request.expires_at === "string") {
+        lines.push(`  ${styles.dim("Expires")}  ${request.expires_at}${lapsed ? styles.yellow(" — already passed") : ""}`);
+    }
+    const note = collabText(request.decision_note, "");
+    if (note)
+        lines.push(`  ${styles.dim("Note")}     ${note}`);
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * `approvals client list`. The column that matters is ACCESS: a blank role cell
+ * means FULL access, not a restricted one, and reading it the other way is how
+ * an agency convinces itself a client login is limited when it is not.
+ */
+function formatCollabMembers(data) {
+    const styles = collabStyles();
+    const members = Array.isArray(data.members) ? data.members.filter(isRecord) : [];
+    const lines = ["", styles.bold(`Workspace members (${members.length})`)];
+    if (members.length === 0) {
+        lines.push(`  ${styles.dim("No members resolved for this workspace.")}`);
+    }
+    else {
+        lines.push(...renderTextTable(["EMAIL", "WORKSPACE ROLE", "OXYGEN ROLE", "ACCESS"], members.map((member) => [
+            collabText(member.email, collabText(member.user_id)),
+            collabText(member.workspace_role),
+            member.oxygen_role === "client" ? "client" : "—",
+            collabText(member.access),
+        ])));
+        // Why a grant on a given row would be refused. The payload has carried this
+        // since the web page needed it; printing it is what stops the terminal from
+        // being the surface that only finds out by failing — on an all-admin
+        // workspace EVERY grant is refused, and the table alone never says so.
+        const blocked = members.filter((member) => member.can_restrict === false);
+        if (blocked.length > 0) {
+            lines.push("", `  ${styles.dim("Cannot be restricted to the client role:")}`);
+            for (const member of blocked) {
+                lines.push(`    ${styles.yellow("!")} ${collabText(member.restrict_blocked_reason)}`);
+            }
+        }
+    }
+    // Invited but not joined. They hold nothing yet, so they are listed apart from
+    // the members rather than mixed in with a blank role that reads as access.
+    const invitations = Array.isArray(data.pending_invitations)
+        ? data.pending_invitations.filter(isRecord)
+        : [];
+    if (invitations.length > 0) {
+        lines.push("", styles.bold(`Invited, not joined yet (${invitations.length})`));
+        lines.push(...renderTextTable(["EMAIL", "INVITED AS", "ON JOIN", "INVITED"], invitations.map((invitation) => [
+            collabText(invitation.email),
+            collabText(invitation.workspace_role),
+            invitation.oxygen_role_on_join === "client" ? "client" : "full access",
+            formatCollabAge(invitation.invited_at),
+        ])));
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+function formatCollabRequestWrite(data) {
+    const styles = collabStyles();
+    // The request is nested; the resolved assignee emails are not.
+    const request = isRecord(data.request) ? data.request : data;
+    const assignees = Array.isArray(data.assignee_emails)
+        ? data.assignee_emails.filter((value) => typeof value === "string")
+        : [];
+    const lines = [
+        "",
+        `  ${styles.green("[OK]")} Asked ${assignees.length > 0 ? assignees.join(", ") : "the assignees"} to decide.`,
+        `  ${styles.dim("Request")}  ${collabText(request.id)}`,
+        `  ${styles.dim("Subject")}  ${collabText(request.subject)}`,
+        `  ${styles.dim("Gate")}     ${collabText(request.gate_kind)} — ${collabText(request.gate_meaning, "")}`,
+    ];
+    if (typeof request.expires_at === "string") {
+        lines.push(`  ${styles.dim("Expires")}  ${request.expires_at} ${styles.dim("(an expired request does not open the gate)")}`);
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * A decision's headline is `opens_gate`, never the status alone: "the client
+ * replied" and "the client said yes" are the two states an agency must never
+ * confuse, and `changes_requested` is the one that reads like the second and
+ * behaves like the first.
+ */
+function formatCollabDecision(data) {
+    const styles = collabStyles();
+    const request = isRecord(data.request) ? data.request : data;
+    const status = collabText(request.status);
+    const opensGate = request.opens_gate === true || data.gate_opened === true;
+    const lines = [
+        "",
+        `  ${opensGate ? styles.green("[APPROVED]") : styles.yellow(`[${status.toUpperCase()}]`)} ${collabText(request.subject)} — request ${collabText(request.id)}`,
+        `  ${styles.dim("Gate")}     ${opensGate
+            ? `open — the ${collabText(request.gate_kind)} gate no longer blocks this.`
+            : `still shut — a ${collabText(request.gate_kind)} gate only opens on --approve.`}`,
+    ];
+    const note = collabText(request.decision_note, "");
+    if (note)
+        lines.push(`  ${styles.dim("Note")}     ${note}`);
+    if (data.already === true)
+        lines.push(`  ${styles.dim("Replay of the same decision; nothing changed.")}`);
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+function formatCollabGateSet(data) {
+    const styles = collabStyles();
+    const policy = isRecord(data.policy) ? data.policy : {};
+    const required = policy.required === true;
+    const scope = collabText(data.scope, "subject") === "workspace_default"
+        ? `every ${collabText(policy.subject_kind)}`
+        : `${collabText(policy.subject_kind)}:${collabText(policy.subject_id)}`;
+    const lines = [
+        "",
+        `  ${required ? styles.green("[GATE ON]") : styles.dim("[GATE OFF]")} ${collabText(policy.gate_kind)} on ${scope}`,
+        `  ${styles.dim("Means")}    ${collabText(policy.gate_meaning, "")}`,
+    ];
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+function formatCollabGateList(data) {
+    const styles = collabStyles();
+    const policies = Array.isArray(data.policies) ? data.policies.filter(isRecord) : [];
+    const effective = Array.isArray(data.effective) ? data.effective.filter(isRecord) : [];
+    const lines = ["", styles.bold(`Gate policies (${policies.length})`)];
+    if (policies.length === 0) {
+        lines.push(`  ${styles.dim("No gate is required anywhere in this workspace.")}`);
+    }
+    else {
+        lines.push(...renderTextTable(["GATE", "SCOPE", "APPLIES TO", "REQUIRED"], policies.map((policy) => [
+            collabText(policy.gate_kind),
+            collabText(policy.scope),
+            collabText(policy.subject_id, `every ${collabText(policy.subject_kind)}`),
+            policy.required === true ? "yes" : "no",
+        ])));
+    }
+    if (effective.length > 0) {
+        lines.push("", styles.bold(`Effective for ${collabText(data.subject)}`));
+        lines.push(...renderTextTable(["GATE", "REQUIRED", "SOURCE", "BLOCKED NOW", "PENDING REQUEST"], effective.map((entry) => [
+            collabText(entry.gate_kind),
+            entry.required === true ? "yes" : "no",
+            collabText(entry.source),
+            entry.blocked === true ? "yes" : "no",
+            collabText(entry.pending_request_id, "—"),
+        ])));
+    }
+    lines.push(...collabTrailer(data));
+    lines.push("");
+    return lines.join("\n");
+}
+export function registerApprovalsFamily(program, handleAsyncAction) {
+    program
+        .command("approvals")
+        .description(`Second-party approvals: ask a named person to decide, and optionally make that decision a hard gate on the live action. Gates: ${COLLAB_GATE_GLOSS}. Asking never blocks anything by itself — a gate is separate, admin-set workspace policy (\`approvals gate set\`), and the owning primitive honors it (a gated sequence still previews and dry-runs; only the live start is refused). Only \`--approve\` opens a gate: \`--changes-requested\` is a real answer that asks for edits and leaves the gate shut. \`approvals client grant <email>\` hands a client a restricted login that can read the work, comment, and decide what is assigned to them — nothing else. ${COLLAB_BETA_NOTE}`)
+        .addCommand(new Command("request")
+        .description("Ask a named second party to decide. Assignees are workspace member EMAILS, and never your own: assigning yourself is refused, because a request you can answer yourself is not an approval. An address that is not a member is refused by name rather than silently dropped, because a request nobody can decide is only discovered the next morning.")
+        .requiredOption("--on <kind:id>", COLLAB_SUBJECT_REF_HELP)
+        .requiredOption("--gate <gate>", COLLAB_GATE_FLAG_HELP)
+        // requiredOption keeps `required: true` in the machine-readable manifest,
+        // but commander's mandatory check is satisfied by the collector's []
+        // default — so the action asserts non-empty itself (requireCollabAssignees).
+        .requiredOption("--assignee <email>", "Who decides — someone other than you. Repeatable: any one of them can answer. Required.", collectRepeatable, [])
+        .option("--path <path>", COLLAB_SUBJECT_PATH_HELP)
+        .option("--title <text>", "Short headline for the ask.")
+        .option("--body <text>", "What you want them to check.")
+        .option("--expires-hours <n>", "Deadline for the ANSWER: an undecided request lapses to expired after N hours, and an expired request never opens the gate. It does not put a clock on a yes — an approval given before the deadline keeps the gate open until the approved content changes.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals request", options, () => {
+            const subject = requireCollabSubject(options.on);
+            const gateKind = requireCollabGate(options.gate);
+            const assignees = requireCollabAssignees(options.assignee);
+            const path = readCollabPath(options.path);
+            const title = readOption(options.title);
+            const body = readOption(options.body);
+            const expiresInHours = readPositiveInt(options.expiresHours);
+            return requestOxygen("/api/cli/collab/requests", {
+                method: "POST",
+                body: {
+                    subject_kind: subject.kind,
+                    subject_id: subject.id,
+                    ...(path ? { subject_path: path } : {}),
+                    gate_kind: gateKind,
+                    ...(title ? { title } : {}),
+                    ...(body ? { body } : {}),
+                    assignees,
+                    ...(expiresInHours !== undefined ? { expires_in_hours: expiresInHours } : {}),
+                },
+            });
+        }, formatCollabRequestWrite);
+    }))
+        .addCommand(new Command("list")
+        .description("Approval requests in this workspace, newest first. Use --mine for the ones assigned to you, or `approvals inbox` for the daily view.")
+        .option("--status <status>", `Filter by status: ${["pending", "approved", "changes_requested", "rejected", "cancelled", "expired"].join(", ")}.`)
+        .option("--mine", "Only requests assigned to you.")
+        .option("--on <kind:id>", `Only requests on one subject. ${COLLAB_SUBJECT_REF_HELP}`)
+        .option("--limit <n>", "Maximum requests to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            if (options.mine)
+                params.set("assigned_to_me", "true");
+            const on = readOption(options.on);
+            if (on) {
+                const subject = requireCollabSubject(on);
+                params.set("subject", `${subject.kind}:${subject.id}`);
+            }
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            const query = params.toString();
+            return requestOxygen(`/api/cli/collab/requests${query ? `?${query}` : ""}`);
+        }, formatCollabRequestList);
+    }))
+        .addCommand(new Command("inbox")
+        .description("What is waiting on YOU: pending approvals assigned to you plus open threads that name you, each with the command that answers it. This is the surface a client logs in to.")
+        .option("--limit <n>", "Maximum items per section.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals inbox", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen(`/api/cli/collab/inbox${limit !== undefined ? `?limit=${limit}` : ""}`);
+        }, formatCollabInbox);
+    }))
+        .addCommand(new Command("show")
+        .description("One approval request by its own id: what is being asked, on what, by whom, who must decide, and whether it can still be decided at all. Run this on the id in a 'you have been asked to approve' email or a `/collab/approvals/<id>` link — `list` cannot find an id you have no subject for. An expired request is reported as such, with the command that clears it.")
+        .argument("<requestId>", "Request id (from a notification email, a deep-link, or `oxygen approvals inbox`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (requestId, options) => {
+        await handleCollabAction("approvals show", options, () => requestOxygen(`/api/cli/collab/requests/${encodeURIComponent(requestId)}`), formatCollabRequestDetail);
+    }))
+        .addCommand(new Command("decide")
+        .description("Answer a pending request. Exactly one of --approve / --reject / --changes-requested. Assignees decide; a workspace admin may decide for the workspace; the requester may NOT decide their own request (that is the whole point) — withdraw it with `approvals cancel` instead. ONLY --approve opens a gate.")
+        .argument("<requestId>", "Request id (from `oxygen approvals inbox`).")
+        .option("--approve", "Approve it. This is the only decision that opens a gate.")
+        .option("--reject", "Refuse it. The gate stays shut.")
+        .option("--changes-requested", "Ask for edits. A real answer that does NOT open the gate — the requester revises and asks again.")
+        .option("--note <text>", "Why. Stored on the request and quoted back to whoever is blocked by it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (requestId, options) => {
+        await handleCollabAction("approvals decide", options, () => {
+            const decision = requireCollabDecision(options);
+            const note = readOption(options.note);
+            return requestOxygen(`/api/cli/collab/requests/${encodeURIComponent(requestId)}/decide`, {
+                method: "POST",
+                body: { decision, ...(note ? { note } : {}) },
+            });
+        }, formatCollabDecision);
+    }))
+        .addCommand(new Command("cancel")
+        .description("Withdraw a pending request you filed (or, as an admin, clear a stale one). Replaying a cancel is a success flagged `already`; cancelling something already approved or rejected is refused, because a silent no-op would leave you believing a live action is still gated when it is not.")
+        .argument("<requestId>", "Request id.")
+        .option("--note <text>", "Why you are withdrawing it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (requestId, options) => {
+        await handleCollabAction("approvals cancel", options, () => {
+            const note = readOption(options.note);
+            return requestOxygen(`/api/cli/collab/requests/${encodeURIComponent(requestId)}/cancel`, {
+                method: "POST",
+                body: note ? { note } : {},
+            });
+        }, formatCollabWriteResult);
+    }))
+        .addCommand(new Command("gate")
+        .description("The opt-in hard gate. Off everywhere until an admin turns it on, so shipping this changed nobody's workflow.")
+        .addCommand(new Command("set")
+        .description(`Require (or stop requiring) an approval before the live action. ADMIN ONLY — a member who can switch the gate off at will is not a gate. Scope it to one object with --on, or to every object of a kind with --default. ${COLLAB_GATE_GLOSS}.`)
+        .option("--on <kind:id>", `Gate one object. ${COLLAB_SUBJECT_REF_HELP}`)
+        .option("--default <kind>", `Gate every object of a kind (the workspace default). One of: ${COLLAB_SUBJECT_KINDS.join(", ")}.`)
+        .requiredOption("--gate <gate>", COLLAB_GATE_FLAG_HELP)
+        .option("--required", "Turn the gate ON.")
+        .option("--not-required", "Turn the gate OFF.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals gate set", options, () => requestOxygen("/api/cli/collab/gates", {
+            method: "POST",
+            body: collabGateSetBody(options),
+        }), formatCollabGateSet);
+    }))
+        .addCommand(new Command("list")
+        .description("Which gates this workspace requires. Pass --on to also get the EFFECTIVE answer for one object — its own policy, then the workspace default for its kind, then 'not required' — plus whether it is blocked right now.")
+        .option("--on <kind:id>", `Also resolve the effective gates for one object. ${COLLAB_SUBJECT_REF_HELP}`)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals gate list", options, () => {
+            const on = readOption(options.on);
+            if (!on)
+                return requestOxygen("/api/cli/collab/gates");
+            const subject = requireCollabSubject(on);
+            return requestOxygen(`/api/cli/collab/gates?subject=${encodeURIComponent(`${subject.kind}:${subject.id}`)}`);
+        }, formatCollabGateList);
+    })))
+        .addCommand(new Command("client")
+        .description("The restricted login an agency hands its client: read the work, comment on it, decide the approvals assigned to them, nothing else. ADMIN ONLY. Invite them to the workspace first — this grants the overlay on an existing membership.")
+        .addCommand(new Command("grant")
+        .description("Restrict a member to the client role. An address that is INVITED but has not joined works too: the role is recorded against the invitation and applies the moment they accept, so you do not have to watch for the acceptance and come back.")
+        .argument("<email>", "Workspace member's email, or a pending invitation's email.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleCollabAction("approvals client", options, () => requestOxygen("/api/cli/collab/members/role", {
+            method: "POST",
+            body: { email, role: "client" },
+        }), formatCollabWriteResult);
+    }))
+        .addCommand(new Command("revoke")
+        .description("Clear the client role and restore full workspace access. Works on a pending invitation too, clearing what that address would land as.")
+        .argument("<email>", "Workspace member's email, or a pending invitation's email.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleCollabAction("approvals client", options, () => requestOxygen("/api/cli/collab/members/role", {
+            method: "POST",
+            body: { email, role: null },
+        }), formatCollabWriteResult);
+    }))
+        .addCommand(new Command("list")
+        .description("Every member of this workspace and what they may do — the workspace role plus the Oxygen client overlay — followed by anyone invited who has not joined yet, and what they will land as. Also names, per member, why a client grant on them would be refused. Same read the /collab/members page renders.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleCollabAction("approvals client list", options, () => requestOxygen("/api/cli/collab/members"), formatCollabMembers);
+    })));
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerAuthFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;