@bli-cockpit/cli 0.2.53 → 0.2.55

package/dist/commands/local-args-tower-admin.js

@@ -0,0 +1,456 @@
+/**
+ * The commands that manage this machine's account or watch the pipeline
+ * rather than carry on a conversation: `cockpit scout`, `cockpit ops`,
+ * `cockpit slack`, `cockpit settings`, `cockpit team`, and `cockpit model`.
+ * Split out of local-args-tower.ts (BLI-3636).
+ *
+ * Every parser moved verbatim: same flags, same defaults, same refusal
+ * sentences. The two constants this family publishes
+ * (`SCOUT_MIN_PREFIX_LENGTH`, `SLACK_WORKSPACE_KEYS`) are re-exported from
+ * `./local-args-tower.js`, the address they have always had.
+ */
+import { optionalEmail, optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+import { isTeamDeviceRevokeReasonLabel, TEAM_DEVICE_REVOKE_REASON_LABELS, } from "./team-device-reasons.js";
+/** The shortest prefix `cockpit scout start` will resolve. Below this, ids collide. */
+export const SCOUT_MIN_PREFIX_LENGTH = 6;
+/**
+ * `cockpit scout [--days <n>]` reads the board; `cockpit scout start|dismiss|undo
+ * <id>` moves one card. Positional shape modelled on `autostart`: an optional
+ * action word first, then what it acts on.
+ */
+export function parseScoutArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--days", "--json"],
+        valueFlags: ["--home", "--dashboard-url", "--days"],
+    });
+    if (values.positionals.length > 2) {
+        throw new Error("scout accepts at most an action (start|dismiss|undo) and one experiment id.");
+    }
+    const [rawAction, rawRef] = values.positionals;
+    const base = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        days: optionalPositiveInteger(values.flags.get("--days"), "--days"),
+        json: values.booleans.has("--json"),
+    };
+    if (!rawAction)
+        return { kind: "scout", action: "board", ...base };
+    if (rawAction !== "start" && rawAction !== "dismiss" && rawAction !== "undo") {
+        throw new Error("scout action must be start, dismiss, or undo.");
+    }
+    const experimentRef = optionalNonEmpty(rawRef);
+    if (!experimentRef) {
+        throw new Error(`scout ${rawAction} needs an experiment id from the board.`);
+    }
+    if (experimentRef.length < SCOUT_MIN_PREFIX_LENGTH) {
+        throw new Error(`scout ${rawAction} needs a full experiment id or a prefix of at least ${SCOUT_MIN_PREFIX_LENGTH} characters.`);
+    }
+    return { kind: "scout", action: rawAction, experimentRef, ...base };
+}
+/**
+ * `cockpit ops status [--job <id>] [--skips]` and
+ * `cockpit ops recompile --person <p> [--dry-run]` (BLI-3462).
+ *
+ * There is deliberately **no `--cadence`** on `recompile`. The compile path
+ * behind it (`writePageAgain` → `publishPage`) takes no cadence and writes a
+ * daily; accepting the flag and dropping it is the silent breakage BLI-2490
+ * forbids, and threading cadence through that path is its own change. Ask for a
+ * weekly or a monthly with the compile script, which does support it.
+ */
+export function parseOpsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--job",
+            "--skips",
+            "--person",
+            "--dry-run",
+            "--json",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--job", "--person"],
+    });
+    if (values.positionals.length > 1) {
+        throw new Error("ops accepts one action: status or recompile.");
+    }
+    const rawAction = values.positionals[0] ?? "status";
+    if (rawAction !== "status" && rawAction !== "recompile") {
+        throw new Error("ops action must be status or recompile.");
+    }
+    const base = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    if (rawAction === "status") {
+        return {
+            kind: "ops",
+            action: "status",
+            job: optionalNonEmpty(values.flags.get("--job")),
+            skips: values.booleans.has("--skips"),
+            ...base,
+        };
+    }
+    const person = optionalNonEmpty(values.flags.get("--person"));
+    if (!person) {
+        throw new Error("ops recompile needs --person <email|name|id>. Nothing is recompiled by default, on purpose.");
+    }
+    return {
+        kind: "ops",
+        action: "recompile",
+        person,
+        dryRun: values.booleans.has("--dry-run"),
+        ...base,
+    };
+}
+/** The workspaces Cockpit collects. A typo is refused here rather than searched for. */
+export const SLACK_WORKSPACE_KEYS = ["bli", "blue_pearl"];
+/**
+ * `cockpit slack coverage [--workspace <key>] [--stale-only]` and
+ * `cockpit slack read [--person|--channel|--query|--since|--until|--limit]`
+ * (BLI-3462).
+ */
+export function parseSlackArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--workspace",
+            "--stale-only",
+            "--person",
+            "--channel",
+            "--query",
+            "--since",
+            "--until",
+            "--limit",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--workspace",
+            "--person",
+            "--channel",
+            "--query",
+            "--since",
+            "--until",
+            "--limit",
+        ],
+    });
+    if (values.positionals.length > 1) {
+        throw new Error("slack accepts one action: coverage or read.");
+    }
+    const rawAction = values.positionals[0] ?? "coverage";
+    if (rawAction !== "coverage" && rawAction !== "read") {
+        throw new Error("slack action must be coverage or read.");
+    }
+    const base = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    if (rawAction === "coverage") {
+        // `--workspace` here is a Slack workspace key, NOT the collection-root
+        // `--workspace <path>` every setup command takes. Named at the point of use
+        // so the two cannot be confused silently.
+        const workspace = optionalNonEmpty(values.flags.get("--workspace"));
+        if (workspace && !SLACK_WORKSPACE_KEYS.includes(workspace)) {
+            throw new Error(`slack --workspace must be one of ${SLACK_WORKSPACE_KEYS.join(", ")}; got ${workspace}.`);
+        }
+        return {
+            kind: "slack",
+            action: "coverage",
+            workspace,
+            staleOnly: values.booleans.has("--stale-only"),
+            ...base,
+        };
+    }
+    const person = optionalNonEmpty(values.flags.get("--person"));
+    const channel = optionalNonEmpty(values.flags.get("--channel"));
+    const query = optionalNonEmpty(values.flags.get("--query"));
+    if (!person && !channel && !query) {
+        throw new Error("slack read needs at least one of --person, --channel or --query. An unfiltered dump of every " +
+            "message is not something this command offers.");
+    }
+    return {
+        kind: "slack",
+        action: "read",
+        person,
+        channel,
+        query,
+        since: optionalNonEmpty(values.flags.get("--since")),
+        until: optionalNonEmpty(values.flags.get("--until")),
+        limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit"),
+        ...base,
+    };
+}
+const SETTINGS_SECTIONS = ["personal", "switches", "models", "env", "cli-floor"];
+/**
+ * `cockpit settings [section] [verb] [args]` (BLI-3461).
+ *
+ * The flag set is the UNION across sections and the combinations are checked
+ * afterwards, per section — the same shape `parseDoctorArgs` uses. A flag that
+ * belongs to another section is refused by name rather than silently ignored,
+ * because a dropped `--project` on an env write is a change a person believes
+ * they made.
+ */
+export function parseSettingsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--json",
+            "--chat-model",
+            "--brief-model",
+            "--chat",
+            "--memory",
+            "--project",
+            "--file",
+            "--id",
+            "--content-stdin",
+            "--yes",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--chat-model",
+            "--brief-model",
+            "--chat",
+            "--memory",
+            "--project",
+            "--file",
+            "--id",
+        ],
+    });
+    const [rawSection, ...rest] = values.positionals;
+    const common = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        yes: values.booleans.has("--yes"),
+        json: values.booleans.has("--json"),
+    };
+    if (!rawSection) {
+        if (rest.length > 0)
+            throw new Error("settings does not accept that argument.");
+        return { kind: "settings", section: "overview", action: "show", ...common };
+    }
+    if (!SETTINGS_SECTIONS.includes(rawSection)) {
+        throw new Error(`settings section must be one of ${SETTINGS_SECTIONS.join(", ")} — or nothing, for all of them.`);
+    }
+    const section = rawSection;
+    if (section === "personal") {
+        if (rest.length > 0)
+            throw new Error("settings personal does not accept positional arguments.");
+        const chatModel = optionalNonEmpty(values.flags.get("--chat-model"));
+        const briefModel = optionalNonEmpty(values.flags.get("--brief-model"));
+        return {
+            kind: "settings",
+            section,
+            action: chatModel || briefModel ? "set" : "show",
+            chatModel,
+            briefModel,
+            ...common,
+        };
+    }
+    if (section === "switches") {
+        if (rest.length === 0) {
+            return { kind: "settings", section, action: "show", ...common };
+        }
+        if (rest[0] !== "set") {
+            throw new Error("settings switches takes no verb, or `set <key> <value>`.");
+        }
+        const [, key, value, ...extra] = rest;
+        if (!key || !value || extra.length > 0) {
+            throw new Error("settings switches set needs exactly a key and a value.");
+        }
+        return { kind: "settings", section, action: "set", switchKey: key, switchValue: value, ...common };
+    }
+    /**
+     * BLI-3557: `settings cli-floor` shows the fleet forced-update floor,
+     * `settings cli-floor <version>` raises it. There is no `set` verb because
+     * there is nothing else to do to a floor, and no flag for the version because
+     * a bare positional is how a release says it: `cockpit settings cli-floor
+     * 0.2.48`. The server refuses a LOWER version; the terminal does not
+     * second-guess that decision locally.
+     */
+    if (section === "cli-floor") {
+        if (rest.length === 0) {
+            return { kind: "settings", section, action: "show", ...common };
+        }
+        const [version, ...extra] = rest;
+        if (!version || extra.length > 0) {
+            throw new Error("settings cli-floor takes no argument, or one version: `cli-floor 0.2.48`.");
+        }
+        return { kind: "settings", section, action: "set", floorVersion: version, ...common };
+    }
+    if (section === "models") {
+        if (rest.length === 0) {
+            return { kind: "settings", section, action: "show", ...common };
+        }
+        if (rest[0] !== "set" || rest.length > 1) {
+            throw new Error("settings models takes no verb, or `set --chat <key>` / `set --memory <id>`.");
+        }
+        const orgChatModel = optionalNonEmpty(values.flags.get("--chat"));
+        const orgMemoryModel = optionalNonEmpty(values.flags.get("--memory"));
+        if (!orgChatModel && !orgMemoryModel) {
+            throw new Error("settings models set needs --chat <key>, --memory <id>, or both.");
+        }
+        return { kind: "settings", section, action: "set", orgChatModel, orgMemoryModel, ...common };
+    }
+    // env
+    const verb = rest[0] ?? "list";
+    if (rest.length > 1)
+        throw new Error("settings env takes one verb: list, set, or delete.");
+    if (verb === "list") {
+        return { kind: "settings", section, action: "list", ...common };
+    }
+    if (verb === "set") {
+        const envProject = optionalNonEmpty(values.flags.get("--project"));
+        const envFile = optionalNonEmpty(values.flags.get("--file"));
+        if (!envProject || !envFile) {
+            throw new Error("settings env set needs --project <project> and --file <file name>.");
+        }
+        if (!values.booleans.has("--content-stdin")) {
+            // Deliberate: there is no `--content <value>` flag and never will be. A
+            // secret on a command line lands in shell history and in every process
+            // listing on the machine.
+            throw new Error("settings env set reads the file contents from stdin: add --content-stdin and pipe the file in.");
+        }
+        return {
+            kind: "settings",
+            section,
+            action: "set",
+            envProject,
+            envFile,
+            contentStdin: true,
+            ...common,
+        };
+    }
+    if (verb === "delete") {
+        const envId = optionalNonEmpty(values.flags.get("--id"));
+        if (!envId)
+            throw new Error("settings env delete needs --id <uuid>.");
+        return { kind: "settings", section, action: "delete", envId, ...common };
+    }
+    throw new Error("settings env takes one verb: list, set, or delete.");
+}
+/**
+ * `cockpit team [members|invite <email>|role <userId>|device list|device
+ * revoke <id|name>]` (BLI-3461; `device` added BLI-3559).
+ */
+export function parseTeamArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--json",
+            "--role",
+            "--team-id",
+            "--yes",
+            "--reason",
+            "--note",
+        ],
+        valueFlags: ["--home", "--dashboard-url", "--role", "--team-id", "--reason", "--note"],
+    });
+    const common = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        teamId: optionalNonEmpty(values.flags.get("--team-id")),
+        yes: values.booleans.has("--yes"),
+        json: values.booleans.has("--json"),
+    };
+    const [verb, ...rest] = values.positionals;
+    if (verb === "device") {
+        return parseTeamDeviceArgs(rest, values.flags, common);
+    }
+    const [subject, ...extra] = rest;
+    if (extra.length > 0)
+        throw new Error("team does not accept that many arguments.");
+    if (!verb || verb === "members") {
+        if (subject)
+            throw new Error("team members does not accept positional arguments.");
+        return { kind: "team", action: "members", ...common };
+    }
+    if (verb === "invite") {
+        if (!subject)
+            throw new Error("team invite needs an email address.");
+        const email = optionalEmail(subject);
+        const role = optionalNonEmpty(values.flags.get("--role"));
+        if (!role)
+            throw new Error("team invite needs --role <role>.");
+        return { kind: "team", action: "invite", email, role, ...common };
+    }
+    if (verb === "role") {
+        if (!subject)
+            throw new Error("team role needs the user id whose role is changing.");
+        const role = optionalNonEmpty(values.flags.get("--role"));
+        if (!role)
+            throw new Error("team role needs --role <role>.");
+        return { kind: "team", action: "role", targetUserId: subject, role, ...common };
+    }
+    throw new Error("team takes one verb: members, invite, role, or device.");
+}
+/**
+ * `cockpit team device [list] [--json]` or
+ * `cockpit team device revoke <id|name> --reason <label> [--note "<text>"]`
+ * (BLI-3559). The reason label is validated here (a closed vocabulary is
+ * worth refusing a typo locally) but the note's 120-char cap is left to the
+ * server — this file has no business re-deciding a limit that lives in the
+ * route's schema.
+ */
+function parseTeamDeviceArgs(rest, flags, common) {
+    const [deviceVerb, deviceRef, ...extra] = rest;
+    if (extra.length > 0)
+        throw new Error("team device does not accept that many arguments.");
+    if (!deviceVerb || deviceVerb === "list") {
+        if (deviceRef)
+            throw new Error("team device list does not accept positional arguments.");
+        return { kind: "team", action: "device-list", ...common };
+    }
+    if (deviceVerb === "revoke") {
+        if (!deviceRef)
+            throw new Error("team device revoke needs a device id or name.");
+        const reasonLabel = optionalNonEmpty(flags.get("--reason"));
+        if (!reasonLabel) {
+            throw new Error(`team device revoke needs --reason <label> (${TEAM_DEVICE_REVOKE_REASON_LABELS.join(", ")}).`);
+        }
+        if (!isTeamDeviceRevokeReasonLabel(reasonLabel)) {
+            throw new Error(`team device revoke --reason must be one of ${TEAM_DEVICE_REVOKE_REASON_LABELS.join(", ")}; got ${reasonLabel}.`);
+        }
+        return {
+            kind: "team",
+            action: "device-revoke",
+            deviceRef,
+            reasonLabel,
+            reasonNote: optionalNonEmpty(flags.get("--note")),
+            ...common,
+        };
+    }
+    throw new Error("team device takes one verb: list or revoke <id|name>.");
+}
+/** `cockpit model [show|set <key>]` — the alias surface for the personal chat model. */
+export function parseModelArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--json"],
+        valueFlags: ["--home", "--dashboard-url"],
+    });
+    const [verb, key, ...extra] = values.positionals;
+    if (extra.length > 0)
+        throw new Error("model does not accept that many arguments.");
+    const common = {
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        json: values.booleans.has("--json"),
+    };
+    if (!verb || verb === "show") {
+        if (key)
+            throw new Error("model show does not accept positional arguments.");
+        return { kind: "model", action: "show", ...common };
+    }
+    if (verb === "set") {
+        if (!key)
+            throw new Error("model set needs a model key, e.g. openai:gpt-5.6-terra.");
+        return { kind: "model", action: "set", modelKey: key, ...common };
+    }
+    throw new Error("model takes one verb: show or set <key>.");
+}

package/dist/commands/local-args-tower-chat.js

@@ -0,0 +1,194 @@
+/**
+ * The two commands that carry a conversation forward with JARVIS: asking it
+ * something (`cockpit jarvis`) and telling it a line on the page was wrong
+ * (`cockpit correct`). Split out of local-args-tower.ts (BLI-3636) — `correct`
+ * moved here rather than beside `brief` because it is the same act as
+ * `jarvis`: a person addressing JARVIS directly, not reading a page.
+ *
+ * Every parser moved verbatim: same flags, same defaults, same refusal
+ * sentences.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+export function parseJarvisArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--prompt",
+            "--as",
+            "--thread",
+            "--model",
+            "--image",
+            "--file",
+            "--no-stream",
+            // BLI-3484: which day's page this turn is about.
+            "--date",
+            // BLI-3458: reading back what was already said, rather than saying
+            // something new. Neither takes a turn or reaches the model.
+            "--threads",
+            "--history",
+            // BLI-3560: reading back what a turn DID — the step tree of one turn.
+            "--trace",
+            "--limit",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--prompt",
+            "--as",
+            "--thread",
+            "--model",
+            "--trace",
+            "--image",
+            "--file",
+            "--date",
+            "--limit",
+        ],
+    });
+    const flaggedPrompt = optionalNonEmpty(values.flags.get("--prompt"));
+    const positionalPrompt = optionalNonEmpty(values.positionals.join(" "));
+    if (flaggedPrompt && positionalPrompt) {
+        throw new Error("jarvis accepts either --prompt or positional text, not both.");
+    }
+    const thread = optionalNonEmpty(values.flags.get("--thread")) ?? "main";
+    if (!/^[A-Za-z0-9_-]{1,40}$/.test(thread)) {
+        throw new Error("jarvis --thread must use 1 to 40 letters, numbers, underscores, or hyphens.");
+    }
+    // BLI-3414: `--file` is a plain alias for `--image` — same flag, whichever
+    // word a person reaches for first.
+    const image = optionalNonEmpty(values.flags.get("--image"));
+    const file = optionalNonEmpty(values.flags.get("--file"));
+    if (image && file) {
+        throw new Error("jarvis accepts either --image or --file, not both — they are the same flag.");
+    }
+    // BLI-3458. Reading history and asking a question are different acts, and a
+    // command that quietly did one while you asked for the other would be worse
+    // than a refusal — `--threads` with a question would silently drop the
+    // question.
+    const threads = values.booleans.has("--threads");
+    const history = values.booleans.has("--history");
+    if (threads && history) {
+        throw new Error("jarvis --threads lists every thread; --history replays one. Pass one, not both.");
+    }
+    if ((threads || history) && (flaggedPrompt || positionalPrompt)) {
+        throw new Error("jarvis --threads and --history read back what was already said; they do not take a question.");
+    }
+    if ((threads || history) && image) {
+        throw new Error("jarvis --threads and --history do not take an attachment.");
+    }
+    // BLI-3484. `--date` binds the page that was live on one of the subject's
+    // days, so a turn can be about Sunday's page. Refused on the two reading
+    // commands for the same reason an attachment is: they replay what was said
+    // and bind no page at all.
+    const date = optionalNonEmpty(values.flags.get("--date"));
+    if ((threads || history) && date) {
+        throw new Error("jarvis --threads and --history replay what was said; they bind no page.");
+    }
+    // BLI-3560. `--trace` reads back what a turn DID, the same class of act as
+    // `--threads` and `--history`, and refused alongside them for the same
+    // reason: a command that quietly asked a question while you asked to see one
+    // is worse than a refusal.
+    const trace = optionalNonEmpty(values.flags.get("--trace"));
+    if (trace && (threads || history)) {
+        throw new Error("jarvis --trace shows one turn's steps; --threads and --history replay what was said. Pass one.");
+    }
+    if (trace && (flaggedPrompt || positionalPrompt)) {
+        throw new Error("jarvis --trace shows a turn that already ran; it does not take a question.");
+    }
+    if (trace && image) {
+        throw new Error("jarvis --trace does not take an attachment.");
+    }
+    if (trace !== undefined && !/^(last|[A-Za-z0-9_-]{1,64})$/.test(trace)) {
+        throw new Error("jarvis --trace takes `last` or a trace id (up to 64 letters, numbers, underscores or hyphens).");
+    }
+    return {
+        kind: "jarvis",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        prompt: flaggedPrompt ?? positionalPrompt,
+        subject: optionalNonEmpty(values.flags.get("--as")),
+        thread,
+        threads,
+        history,
+        ...(trace ? { trace } : {}),
+        limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit"),
+        // BLI-3381: no client-side allowlist — the dashboard forwards this key
+        // to the inference server's own allowlist and relays its refusal.
+        model: optionalNonEmpty(values.flags.get("--model")),
+        ...(date ? { date } : {}),
+        imagePath: image ?? file,
+        // BLI-3457: streaming is on unless a caller opts out. A dashboard that
+        // does not stream yet still answers plain JSON, so this flag is for
+        // callers that want the single-body shape on purpose, not a compat knob.
+        stream: !values.booleans.has("--no-stream"),
+        json: values.booleans.has("--json"),
+    };
+}
+/**
+ * `cockpit correct` (BLI-3458) — say that one line on the page is wrong.
+ *
+ * `--claim` is required and comes from `cockpit brief --claims`, which prints
+ * the id beside every line it names. A correction with no claim would be a note
+ * about the page in general, and the panel has a sentinel for that; the
+ * terminal does not offer it, because a person who has just read
+ * `[claimId] the sentence` has the id in front of them.
+ *
+ * `--text` may be omitted when something is piped in — `git log | cockpit
+ * correct --claim x` — and the command reads stdin instead. Absent both, the
+ * command refuses rather than filing an empty correction.
+ */
+export function parseCorrectArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--claim",
+            "--text",
+            "--for",
+            "--as",
+            "--version",
+            "--supersedes",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--claim",
+            "--text",
+            "--for",
+            "--as",
+            "--version",
+            "--supersedes",
+        ],
+    });
+    const claimId = optionalNonEmpty(values.flags.get("--claim"));
+    if (!claimId) {
+        throw new Error("correct needs --claim <claimId>. Run `cockpit brief --claims` to see the id beside every line.");
+    }
+    const flaggedText = optionalNonEmpty(values.flags.get("--text"));
+    const positionalText = optionalNonEmpty(values.positionals.join(" "));
+    if (flaggedText && positionalText) {
+        throw new Error("correct accepts either --text or positional text, not both.");
+    }
+    const text = flaggedText ?? positionalText;
+    if (text && text.length > 4000) {
+        throw new Error("A correction is limited to 4000 characters.");
+    }
+    const forPerson = optionalNonEmpty(values.flags.get("--for"));
+    const asPerson = optionalNonEmpty(values.flags.get("--as"));
+    if (forPerson && asPerson && forPerson !== asPerson) {
+        throw new Error("correct --for and --as must name the same person.");
+    }
+    return {
+        kind: "correct",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        claimId,
+        text,
+        subject: forPerson ?? asPerson,
+        version: optionalNonEmpty(values.flags.get("--version")),
+        supersedes: optionalNonEmpty(values.flags.get("--supersedes")),
+        json: values.booleans.has("--json"),
+    };
+}