@bli-cockpit/cli 0.2.41 → 0.2.42

package/dist/commands/brief-edit.js

@@ -0,0 +1,289 @@
+/**
+ * `cockpit brief edit` — rewrite the page like a document (BLI-3458, S2.7).
+ *
+ * The browser has had this since BLI-3120: click into a line, fix the words,
+ * press save, and the edit IS the correction — the exact wrong words, the exact
+ * right words, and optionally why, which is strictly more than any complaint
+ * could carry. This is the same door from a terminal.
+ *
+ * Four steps, and the order matters:
+ *
+ *   1. `GET /api/jarvis/brief?editable=1` — the page as a file, one
+ *      `[claimId] the prose` line per rewritable claim. The server builds it
+ *      from the SAME `indexClaims` the edit door diffs against, so an untouched
+ *      line comes back byte-identical instead of being filed as an edit.
+ *   2. Open `$VISUAL`/`$EDITOR` on a temp copy (`editor.ts` owns that, and it is
+ *      the one place in this package that spawns a program a PERSON chose). No
+ *      editor, or nothing to open one on — piped input, a script, CI — and the
+ *      edited document is read from stdin instead.
+ *   3. Diff HERE, not on the server. Only lines that really changed are sent, so
+ *      an accidental save writes nothing and publishes no version.
+ *   4. `POST /api/jarvis/edit` — the same door the browser's save posts to.
+ *
+ * Two refusals happen before anything is sent, both by name:
+ *
+ * - **A claim id that vanished.** The document is a set of lines, not a text
+ *   file: deleting one is not "delete that sentence", it is "I have no opinion
+ *   about it", and the two are indistinguishable to a diff. Sending it as an
+ *   emptied line would publish a page with a hole in it.
+ * - **A claim id that was invented.** Filing a correction against a clause
+ *   nobody can find is how a ledger fills with rows that mean nothing.
+ */
+import { colorEnabled, dim, isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { editInEditor, resolveEditorCommand } from "./editor.js";
+import { loadPairedSession, towerJsonRequest } from "../tower-client.js";
+const REQUEST_DEADLINE_MS = 120_000;
+/** A page is long; a document that arrives bigger than this is not one of ours. */
+const MAX_DOCUMENT_CHARS = 400_000;
+export async function runBriefEdit(command, io) {
+    const session = await loadPairedSession("brief edit", command.homeDir);
+    const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
+    const log = (line) => writeLine(io.stderr, line);
+    const startedAt = Date.now();
+    // ── 1. The page, as a document ────────────────────────────────────────────
+    const read = await towerJsonRequest({
+        dashboardUrl,
+        path: `/api/jarvis/brief${briefQuery(command)}`,
+        deviceToken: session.device_token,
+        fetch: io.fetch,
+        method: "GET",
+        label: "brief:edit",
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+    });
+    if (!read.ok)
+        return fail(command, io, read.reason, read.detail);
+    const brief = read.body;
+    const personId = brief.page?.personId;
+    const original = brief.editable?.document;
+    const lines = (brief.editable?.lines ?? []).filter((line) => typeof line.claimId === "string" && typeof line.text === "string");
+    if (!brief.ok || !personId || typeof original !== "string" || lines.length === 0) {
+        return fail(command, io, brief.error ?? "no_page", brief.reply ?? "There is no page to edit.");
+    }
+    // ── 2. Their editor, or their stdin ───────────────────────────────────────
+    const edited = await collectEditedDocument(io, original, log);
+    if (!edited.ok)
+        return fail(command, io, edited.reason, edited.detail);
+    // ── 3. The diff, here ─────────────────────────────────────────────────────
+    const diff = diffDocument(lines, edited.text);
+    if (diff.invented.length > 0) {
+        return fail(command, io, "invented_claim", `The page has no line called “${diff.invented[0]}”. Change the words after an id, never the id ` +
+            "itself — nothing has been sent to Tower.");
+    }
+    if (diff.deleted.length > 0) {
+        return fail(command, io, "deleted_claim", `The line [${diff.deleted[0]}] is missing from what you saved. Put it back — a line you delete ` +
+            "reads as no opinion at all, not as a sentence to remove, and Tower cannot tell those apart. " +
+            "Nothing has been sent.");
+    }
+    if (diff.edits.length === 0) {
+        const styled = colorEnabled(io);
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({ ok: true, saved: 0, reason: "nothing_changed" }));
+        }
+        else {
+            writeLine(io.stdout, dim("Nothing changed, so nothing was written.", styled));
+        }
+        writeLine(io.stderr, `[brief edit] nothing changed ${JSON.stringify({
+            lines: lines.length,
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return 0;
+    }
+    // ── 4. The same door the browser's save posts to ──────────────────────────
+    const saved = await towerJsonRequest({
+        dashboardUrl,
+        path: "/api/jarvis/edit",
+        deviceToken: session.device_token,
+        fetch: io.fetch,
+        label: "brief:edit:save",
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+        body: {
+            personId,
+            pageId: brief.page?.pageId ?? null,
+            edits: diff.edits,
+            ...(command.reason ? { reason: command.reason } : {}),
+        },
+    });
+    if (!saved.ok)
+        return fail(command, io, saved.reason, saved.detail);
+    const answer = saved.body;
+    writeOutcome(command, io, answer, diff.edits.length);
+    writeLine(io.stderr, `[brief edit] saved ${JSON.stringify({
+        sent: diff.edits.length,
+        saved: answer.saved ?? null,
+        versions: answer.versions ?? null,
+        skipped: answer.skipped?.length ?? 0,
+        overruled: answer.overruled?.length ?? 0,
+        reason: answer.reason ?? null,
+        had_reason: command.reason != null,
+        subject: command.subject ? "selected" : "caller",
+        elapsed_ms: Date.now() - startedAt,
+    })}`);
+    return 0;
+}
+function briefQuery(command) {
+    const params = new URLSearchParams({ editable: "1" });
+    if (command.subject)
+        params.set("p", command.subject);
+    if (command.version)
+        params.set("v", command.version);
+    return `?${params.toString()}`;
+}
+/**
+ * The edited document.
+ *
+ * Piped stdin wins, and deliberately: somebody who prepared a file has already
+ * done the editing, and opening an editor on top of it would be the command
+ * ignoring what it was handed. Otherwise the editor opens — and when there is
+ * neither, the refusal names both ways out rather than guessing `vi` at
+ * somebody who has never used it.
+ */
+async function collectEditedDocument(io, original, log) {
+    if (!isInteractiveStdin(io)) {
+        let piped;
+        try {
+            piped = await readPipedText(io.stdin, {
+                maxChars: MAX_DOCUMENT_CHARS,
+                overflowMessage: `An edited page is limited to ${MAX_DOCUMENT_CHARS} characters.`,
+            });
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: "stdin_unreadable",
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+        if (piped.trim() === "") {
+            return {
+                ok: false,
+                reason: "nothing_on_stdin",
+                detail: "Nothing arrived on stdin. Run `cockpit brief edit` in a terminal to open your editor, " +
+                    "or pipe the edited document in: `cockpit brief --editable > page.md; … ; " +
+                    "cockpit brief edit < page.md`.",
+            };
+        }
+        log(`[brief edit] read from stdin ${JSON.stringify({ chars: piped.length })}`);
+        return { ok: true, text: piped, via: "stdin" };
+    }
+    if (!resolveEditorCommand(io.env)) {
+        return {
+            ok: false,
+            reason: "no_editor_configured",
+            detail: "No editor is configured. Set EDITOR (or VISUAL) — `export EDITOR=nano` — or pipe the " +
+                "edited document in on stdin instead.",
+        };
+    }
+    const session = await editInEditor({
+        contents: original,
+        suffix: ".md",
+        env: io.env,
+        log,
+    });
+    if (!session.ok)
+        return { ok: false, reason: session.reason, detail: session.detail };
+    return { ok: true, text: session.text, via: "editor" };
+}
+/**
+ * What actually changed, decided here rather than on the server.
+ *
+ * The parse mirrors `apps/dashboard/src/lib/jarvis/serialize/editable-document.ts`,
+ * which produced the document: `#` is a comment, a `[id]` starts a line, a
+ * following un-prefixed line is that line wrapped rather than a new one. It only
+ * ever has to read what the server wrote, and the `unchanged` case proves it
+ * did — a parser that got this wrong would report every line as an edit, which
+ * is exactly the failure `editable-document.test.ts` holds the server side to.
+ */
+export function diffDocument(original, edited) {
+    const before = new Map(original.filter((line) => line.rewritable).map((line) => [line.claimId, normalize(line.text)]));
+    const seen = new Set();
+    const diff = { edits: [], invented: [], deleted: [] };
+    for (const parsed of parseDocument(edited)) {
+        if (seen.has(parsed.claimId))
+            continue;
+        seen.add(parsed.claimId);
+        const stored = before.get(parsed.claimId);
+        if (stored === undefined) {
+            diff.invented.push(parsed.claimId);
+            continue;
+        }
+        const after = normalize(parsed.text);
+        if (after !== stored)
+            diff.edits.push({ claimId: parsed.claimId, after });
+    }
+    for (const claimId of before.keys()) {
+        if (!seen.has(claimId))
+            diff.deleted.push(claimId);
+    }
+    return diff;
+}
+/** The same collapse `normalizeEditedText` does server-side, so the two agree. */
+function normalize(text) {
+    return text.replace(/ /g, " ").replace(/\s+/g, " ").trim();
+}
+const CLAIM_LINE = /^\[([^\]\s]+)\]\s?(.*)$/;
+export function parseDocument(text) {
+    const out = [];
+    let current = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("#")) {
+            current = null;
+            continue;
+        }
+        const match = CLAIM_LINE.exec(line);
+        if (match) {
+            current = { claimId: match[1], text: (match[2] ?? "").trim() };
+            out.push(current);
+            continue;
+        }
+        if (line === "") {
+            current = null;
+            continue;
+        }
+        if (current)
+            current.text = `${current.text} ${line}`.trim();
+    }
+    return out;
+}
+function writeOutcome(command, io, answer, sent) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: true, sent, ...answer }));
+        return;
+    }
+    const styled = colorEnabled(io);
+    const saved = answer.saved ?? 0;
+    const versions = answer.versions;
+    writeLine(io.stdout, saved === 1
+        ? "One line rewritten, and Tower has it."
+        : `${saved} lines rewritten, and Tower has them.`);
+    if (typeof versions === "number") {
+        writeLine(io.stdout, dim(`Your page now has ${versions} versions.`, styled));
+    }
+    else if (answer.reason) {
+        // The edit is on the record and the page did not move. Never silent: the
+        // server named which of the four reasons it was and it goes straight out.
+        writeLine(io.stdout, dim(`The page itself was not republished (${answer.reason}); your words are on the record.`, styled));
+    }
+    for (const skip of answer.skipped ?? []) {
+        writeLine(io.stdout, dim(`Not applied: [${skip.claimId ?? "?"}] — ${skip.reason ?? "no reason given"}.`, styled));
+    }
+    // The push-back is the point, not an error path: the record disagreed with
+    // what they typed, their words were kept anyway, and the disagreement is said
+    // out loud rather than quietly stored.
+    for (const overruled of answer.overruled ?? []) {
+        if (overruled.pushBack)
+            writeLine(io.stdout, overruled.pushBack);
+    }
+}
+function fail(command, io, reason, detail) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(io.stderr, detail);
+    }
+    writeLine(io.stderr, `[brief edit] not saved ${JSON.stringify({ reason })}`);
+    return 1;
+}

package/dist/commands/brief-rewrite.js

@@ -0,0 +1,260 @@
+/**
+ * `cockpit brief rewrite` — ask for the page to be written again (BLI-3458, S2.8).
+ *
+ * The website has a button; this is that button. What is different here is not
+ * the permission — an admin may ask about anybody, everyone else about their own
+ * page, decided by the row policy on `jarvis_recompile_requests` and nowhere
+ * else — it is the WAITING.
+ *
+ * **Why this polls instead of holding the connection.** Writing a page is a
+ * multi-minute job: `/api/jarvis/recompile` is budgeted to 800 seconds and a
+ * real run has taken seven attempts. A terminal's own fetch wall is 300. So a
+ * synchronous ask would abort ON THIS SIDE with the compile still running, and
+ * "it timed out" would be indistinguishable from "it failed" — the exact
+ * confusion this repo keeps paying for. Instead `mode: "queue"` answers 202 the
+ * moment the ask exists, and this command watches the person's own page until a
+ * new version shows up.
+ *
+ * Three outcomes, and they are kept apart on purpose:
+ *
+ *   - **written** — a new page id appeared. Exit 0.
+ *   - **still running** — the wait ran out. The compile is very likely still
+ *     going; this is NOT a failure and says so, with the one command that will
+ *     show the answer later. Exit non-zero, because what was asked for has not
+ *     happened yet.
+ *   - **queue only** — the deployment could not schedule the compile at all
+ *     (`compileScheduled: false`). The ask is on the record and the daily job
+ *     will reach it; nothing is pretended.
+ */
+import { colorEnabled, dim, writeLine } from "./cli-io.js";
+import { loadPairedSession, towerJsonRequest } from "../tower-client.js";
+const REQUEST_DEADLINE_MS = 60_000;
+/**
+ * How long to watch. The server's own compile budget is 800s; this allows for
+ * that plus the queue's own latency, and then says plainly that it stopped
+ * watching rather than that anything failed.
+ */
+const WATCH_CEILING_MS = 900_000;
+const POLL_EVERY_MS = 10_000;
+export async function runBriefRewrite(command, io, watchOptions = {}) {
+    const session = await loadPairedSession("brief rewrite", command.homeDir);
+    const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
+    const log = (line) => writeLine(io.stderr, line);
+    const styled = colorEnabled(io);
+    const startedAt = Date.now();
+    // Which page, and what it looks like NOW — the "before" the poll compares
+    // against. Read first for a second reason: it is the only way this command
+    // learns the person id, and it is the same read that decides whether this
+    // caller may see that page at all.
+    const before = await readPage(command, io, session.device_token, dashboardUrl, log);
+    if (!before.ok)
+        return fail(command, io, before.reason, before.detail);
+    const personId = before.page.page?.personId;
+    if (!personId) {
+        return fail(command, io, before.page.error ?? "no_page", before.page.reply ??
+            "There is no page here to write again yet. The first one is compiled by the daily job.");
+    }
+    const beforePageId = before.page.page?.pageId ?? null;
+    const queued = await towerJsonRequest({
+        dashboardUrl,
+        path: "/api/jarvis/recompile",
+        deviceToken: session.device_token,
+        fetch: io.fetch,
+        label: "brief:rewrite",
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+        body: { personIds: [personId], mode: "queue" },
+    });
+    if (!queued.ok)
+        return fail(command, io, queued.reason, queued.detail);
+    const answer = queued.body;
+    const request = (answer.queued ?? [])[0];
+    if (!answer.ok || !request?.requestId) {
+        return fail(command, io, "not_queued", answer.reply ?? "Tower did not accept that ask.");
+    }
+    const whose = request.name ?? before.page.page?.displayName ?? "that page";
+    const scheduled = answer.compileScheduled !== false;
+    writeLine(io.stderr, `[brief rewrite] queued ${JSON.stringify({
+        request_id: request.requestId,
+        compile_scheduled: scheduled,
+        compile_reason: answer.compileReason ?? null,
+        waiting: command.wait !== false,
+    })}`);
+    if (!scheduled) {
+        // Queue-only, said as queue-only. The ask is a real row; what is missing is
+        // somebody to run it in the next minute, and pretending otherwise would
+        // leave a person watching a page that was never going to change.
+        const sentence = `${whose} is on the list to be written again, but this Tower could not start the work now ` +
+            `(${answer.compileReason ?? "no reason given"}). The daily compile will reach it. Nothing is lost.`;
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                ok: true,
+                outcome: "queued_only",
+                requestId: request.requestId,
+                personId,
+                compileScheduled: false,
+                compileReason: answer.compileReason ?? null,
+            }));
+        }
+        else {
+            writeLine(io.stdout, sentence);
+        }
+        return 0;
+    }
+    if (command.wait === false) {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                ok: true,
+                outcome: "queued",
+                requestId: request.requestId,
+                personId,
+                compileScheduled: true,
+            }));
+        }
+        else {
+            writeLine(io.stdout, `Asked. ${whose} is being written again.`);
+            writeLine(io.stdout, dim("Run `cockpit brief` in a few minutes to read it.", styled));
+        }
+        return 0;
+    }
+    writeLine(io.stderr, dim(`Writing ${whose} again. This takes a few minutes; watching for the new version…`, styled));
+    const watched = await watchForNewVersion({
+        command,
+        io,
+        deviceToken: session.device_token,
+        dashboardUrl,
+        beforePageId,
+        log,
+        pollEveryMs: watchOptions.pollEveryMs ?? POLL_EVERY_MS,
+        ceilingMs: watchOptions.ceilingMs ?? WATCH_CEILING_MS,
+    });
+    if (watched.outcome === "written") {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                ok: true,
+                outcome: "written",
+                requestId: request.requestId,
+                personId,
+                pageId: watched.pageId,
+                waitedMs: watched.waitedMs,
+            }));
+        }
+        else {
+            writeLine(io.stdout, `${whose} has been written again.`);
+            writeLine(io.stdout, dim("Run `cockpit brief` to read it.", styled));
+        }
+        writeLine(io.stderr, `[brief rewrite] written ${JSON.stringify({
+            request_id: request.requestId,
+            polls: watched.polls,
+            waited_ms: watched.waitedMs,
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return 0;
+    }
+    // Not a failure, and named so it cannot be read as one. Nothing observed here
+    // says the compile stopped — only that this command stopped watching.
+    const sentence = watched.outcome === "watch_failed"
+        ? `I stopped being able to read the page while waiting (${watched.detail}). The rewrite may ` +
+            "still finish; run `cockpit brief` in a few minutes."
+        : `Still running after ${Math.round(watched.waitedMs / 1000)}s. Tower has not finished writing ` +
+            `${whose} yet — that is normal for a long page, and the work is still going. Run ` +
+            "`cockpit brief` in a few minutes.";
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: false,
+            outcome: watched.outcome,
+            requestId: request.requestId,
+            personId,
+            waitedMs: watched.waitedMs,
+            ...(watched.outcome === "watch_failed" ? { detail: watched.detail } : {}),
+        }));
+    }
+    else {
+        writeLine(io.stderr, sentence);
+    }
+    writeLine(io.stderr, `[brief rewrite] not confirmed ${JSON.stringify({
+        request_id: request.requestId,
+        reason: watched.outcome,
+        polls: watched.polls,
+        waited_ms: watched.waitedMs,
+    })}`);
+    return 1;
+}
+/**
+ * Watch the person's own page until its id changes.
+ *
+ * The page id, not `compiledAt`: a new version is a new row, and an id that
+ * differs is the one signal that cannot be produced by a clock skew or by a
+ * re-read of the same row. `compiledAt` is logged alongside because it is what a
+ * human reads, but the decision is the id.
+ */
+async function watchForNewVersion(input) {
+    const startedAt = Date.now();
+    let polls = 0;
+    while (Date.now() - startedAt < input.ceilingMs) {
+        await sleep(input.pollEveryMs);
+        polls += 1;
+        const read = await readPage(input.command, input.io, input.deviceToken, input.dashboardUrl, input.log);
+        const waitedMs = Date.now() - startedAt;
+        if (!read.ok) {
+            // A single blip while waiting is not an answer about the compile. Only a
+            // refusal is, and that one stops the watch rather than spinning.
+            if (read.httpStatus === 403 || read.httpStatus === 401) {
+                return { outcome: "watch_failed", detail: read.detail, polls, waitedMs };
+            }
+            input.log(`[brief rewrite] poll failed ${JSON.stringify({ poll: polls, reason: read.reason })}`);
+            continue;
+        }
+        const pageId = read.page.page?.pageId ?? null;
+        input.log(`[brief rewrite] polled ${JSON.stringify({
+            poll: polls,
+            changed: pageId != null && pageId !== input.beforePageId,
+            compiled_at: read.page.page?.compiledAt ?? null,
+            waited_ms: waitedMs,
+        })}`);
+        if (pageId && pageId !== input.beforePageId) {
+            return { outcome: "written", pageId, polls, waitedMs };
+        }
+    }
+    return { outcome: "still_running", polls, waitedMs: Date.now() - startedAt };
+}
+async function readPage(command, io, deviceToken, dashboardUrl, log) {
+    const params = new URLSearchParams({ tldr: "1" });
+    if (command.subject)
+        params.set("p", command.subject);
+    const result = await towerJsonRequest({
+        dashboardUrl,
+        path: `/api/jarvis/brief?${params.toString()}`,
+        deviceToken,
+        fetch: io.fetch,
+        method: "GET",
+        label: "brief:rewrite:read",
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+    });
+    if (!result.ok) {
+        return {
+            ok: false,
+            reason: result.reason,
+            detail: result.detail,
+            ...(result.httpStatus === undefined ? {} : { httpStatus: result.httpStatus }),
+        };
+    }
+    return { ok: true, page: result.body };
+}
+/** Injected nowhere: a real pause. Tests drive the clock through `io.fetch`. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function fail(command, io, reason, detail) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(io.stderr, detail);
+    }
+    writeLine(io.stderr, `[brief rewrite] not asked ${JSON.stringify({ reason })}`);
+    return 1;
+}

package/dist/commands/editor.js

@@ -0,0 +1,204 @@
+/**
+ * Opening the person's own editor on a temp file (BLI-3458, slice S2.7).
+ *
+ * This is the ONE place in the collector that starts a child process for a
+ * PERSON rather than for a tool we chose, so the rules are written here and
+ * nowhere else:
+ *
+ * 1. **`spawnSync` with an ARRAY of arguments, never a shell string.** A
+ *    person's `$EDITOR` is theirs — `code -w`, `"C:\\Program Files\\…\\Code.exe"
+ *    -w`, `emacsclient -nw`. Building `${editor} ${path}` and handing it to a
+ *    shell would make a path with a space into two arguments and a path with a
+ *    semicolon into two commands. `shell: false` is the default and stays the
+ *    default; nothing here interpolates.
+ * 2. **`EDITOR` / `VISUAL` are taken VERBATIM as the program**, after one
+ *    tokenisation that understands quotes — because that is how every other
+ *    tool on the machine reads them, and a person who wrote `code -w` means the
+ *    flag. The tokeniser splits on unquoted whitespace and nothing else: it
+ *    performs no expansion, no globbing, and no substitution, so a token can
+ *    never turn into a command.
+ * 3. **On Windows the program is spawned as given.** Node resolves `notepad`,
+ *    `notepad.exe` and an absolute `.exe` path itself; a `.cmd`/`.bat` shim
+ *    needs `shell: true`, which is exactly what rule 1 forbids, so it is
+ *    REFUSED by name with the fix (point EDITOR at the `.exe`) rather than run
+ *    through cmd.exe with a person's own path interpolated into a command line.
+ *    That refusal is deliberate and is the only thing this module will not do.
+ *
+ * The file itself carries page text, which is not a secret — but it is somebody
+ * else's writing, so it lives in the OS temp directory with a random name and is
+ * deleted in a `finally`, whatever happened.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stripLeadingBom } from "./cli-io.js";
+/**
+ * The editor a person has actually chosen, or the platform's last resort.
+ *
+ * `VISUAL` wins over `EDITOR` — that is the POSIX order and every other tool on
+ * the machine follows it. Windows falls back to `notepad`, which is present on
+ * every install and needs no shell; macOS and Linux do NOT fall back, because
+ * guessing `vi` at somebody who has never used it strands them in a modal editor
+ * with no way out that they know. They get a named reason and a one-line fix.
+ */
+export function resolveEditorCommand(env, platform = process.platform) {
+    const configured = (env["VISUAL"] ?? env["EDITOR"] ?? "").trim();
+    if (configured) {
+        const tokens = tokenizeCommand(configured);
+        const program = tokens[0];
+        if (program)
+            return { program, args: tokens.slice(1) };
+    }
+    if (platform === "win32")
+        return { program: "notepad", args: [] };
+    return null;
+}
+/**
+ * Splits a configured editor into program and arguments.
+ *
+ * Quotes are honoured because a Windows editor path routinely contains a space
+ * (`"C:\Program Files\Microsoft VS Code\Code.exe" -w`). NOTHING else is
+ * interpreted: no `$VAR`, no `~`, no globbing, no `&&`. A token comes out of
+ * this function exactly as it went in, minus the quotes that grouped it, and
+ * goes into `spawnSync`'s array — so there is no stage at which a shell could
+ * see any of it.
+ */
+export function tokenizeCommand(command) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let started = false;
+    for (const char of command) {
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/u.test(char)) {
+            if (started)
+                tokens.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * Writes `contents` to a temp file, opens the editor on it, and hands back what
+ * was there when the editor closed. Never throws.
+ */
+export async function editInEditor(options) {
+    const platform = options.platform ?? process.platform;
+    const log = options.log ?? ((line) => console.error(line));
+    const chosen = resolveEditorCommand(options.env, platform);
+    if (!chosen) {
+        return {
+            ok: false,
+            reason: "no_editor_configured",
+            detail: "No editor is configured. Set EDITOR (or VISUAL) — for example `export EDITOR=nano` — " +
+                "or pipe the edited page in on stdin instead.",
+        };
+    }
+    // A `.cmd` or `.bat` is a batch script; Node cannot execute one without
+    // handing the whole line to cmd.exe, and that is the one thing this module
+    // will not do with a person's own path in it.
+    if (platform === "win32" && /\.(cmd|bat)$/i.test(chosen.program)) {
+        return {
+            ok: false,
+            reason: "editor_needs_a_shell",
+            detail: `EDITOR points at a .cmd/.bat wrapper (${basenameOf(chosen.program)}), which cannot be ` +
+                "started without a shell. Point EDITOR at the editor's .exe instead — for example " +
+                "notepad, or the full path to Code.exe.",
+        };
+    }
+    let directory;
+    let file;
+    try {
+        directory = await mkdtemp(join(tmpdir(), "cockpit-brief-"));
+        file = join(directory, `brief-${randomBytes(4).toString("hex")}${options.suffix ?? ".md"}`);
+        await writeFile(file, options.contents, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "scratch_file_failed",
+            detail: `The page could not be written to a scratch file (${messageOf(error)}).`,
+        };
+    }
+    try {
+        const spawn = options.spawn ?? spawnSync;
+        log(`[brief edit] editor opening ${JSON.stringify({
+            program: basenameOf(chosen.program),
+            extra_args: chosen.args.length,
+            bytes: Buffer.byteLength(options.contents, "utf8"),
+        })}`);
+        // `stdio: "inherit"` hands the terminal over: a full-screen editor needs the
+        // real tty. `shell: false` is the default and is stated to make the rule
+        // above impossible to lose in a refactor.
+        const result = spawn(chosen.program, [...chosen.args, file], {
+            stdio: "inherit",
+            shell: false,
+            env: options.env,
+        });
+        if (result.error) {
+            return {
+                ok: false,
+                reason: "editor_not_started",
+                detail: `Your editor (${basenameOf(chosen.program)}) could not be started ` +
+                    `(${messageOf(result.error)}). Check EDITOR, or pipe the edited page in on stdin.`,
+            };
+        }
+        if (typeof result.status === "number" && result.status !== 0) {
+            return {
+                ok: false,
+                reason: "editor_exited_nonzero",
+                detail: `Your editor exited with status ${result.status}, so nothing was changed. ` +
+                    "Nothing has been sent to Tower.",
+            };
+        }
+        const text = stripLeadingBom(await readFile(file, "utf8"));
+        log(`[brief edit] editor closed ${JSON.stringify({
+            program: basenameOf(chosen.program),
+            status: result.status ?? null,
+            bytes: Buffer.byteLength(text, "utf8"),
+        })}`);
+        return { ok: true, text, program: basenameOf(chosen.program) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "scratch_file_failed",
+            detail: `The edited page could not be read back (${messageOf(error)}).`,
+        };
+    }
+    finally {
+        // Whatever happened. The page is not a secret, but it is somebody's writing
+        // and it does not belong in /tmp after the command returns.
+        await rm(directory, { recursive: true, force: true }).catch(() => {
+            // Deliberately silent: the temp directory is the OS's to reap, and a
+            // failure to remove it must not turn a saved edit into a failed command.
+        });
+    }
+}
+/** The program's own name, never the directories around it. */
+function basenameOf(program) {
+    const parts = program.split(/[\\/]/u);
+    return parts[parts.length - 1] || program;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message.split("\n")[0] ?? error.name : String(error);
+}

package/dist/commands/local-args.js

@@ -1009,16 +1009,45 @@ function parseBriefArgs(args) {
             "--full",
             "--versions",
             "--claims",
+            "--reason",
+            "--wait",
+            "--no-wait",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--for", "--as", "--version"],
+        valueFlags: ["--home", "--dashboard-url", "--for", "--as", "--version", "--reason"],
     });
-    assertNoPositionals(values.positionals, "brief");
+    // Bare `cockpit brief` reads the page, which is what somebody typing it almost
+    // always wants — the same shape `cockpit notes` and `cockpit scout` have.
+    const first = values.positionals[0];
+    const action = (first === undefined ? "read" : first);
+    if (!["read", "edit", "rewrite"].includes(action)) {
+        throw new Error(`Unknown brief command: ${first}. Try edit or rewrite, or nothing to read it.`);
+    }
+    if (values.positionals.length > (first === undefined ? 0 : 1)) {
+        throw new Error(`brief ${action} does not take "${values.positionals[1]}".`);
+    }
     const tldr = values.booleans.has("--tldr");
     const full = values.booleans.has("--full");
     if (tldr && full) {
         throw new Error("brief accepts either --tldr or --full, not both.");
     }
+    const wait = values.booleans.has("--wait");
+    const noWait = values.booleans.has("--no-wait");
+    if (wait && noWait) {
+        throw new Error("brief rewrite accepts either --wait or --no-wait, not both.");
+    }
+    const reason = optionalNonEmpty(values.flags.get("--reason"));
+    if (reason && reason.length > 280) {
+        // The server's own ceiling (`REASON_MAX`). Said here so the person is told
+        // before the page is opened rather than after they have finished editing.
+        throw new Error("A reason is limited to 280 characters.");
+    }
+    if (action !== "edit" && reason) {
+        throw new Error("--reason belongs to `cockpit brief edit`.");
+    }
+    if (action !== "rewrite" && (wait || noWait)) {
+        throw new Error("--wait and --no-wait belong to `cockpit brief rewrite`.");
+    }
     // `--as` is accepted as an alias so the two conversational commands read the
     // same way; `cockpit jarvis --as <person>` has meant this since BLI-3380.
     const forPerson = optionalNonEmpty(values.flags.get("--for"));
@@ -1028,6 +1057,7 @@ function parseBriefArgs(args) {
     }
     return {
         kind: "brief",
+        action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         subject: forPerson ?? asPerson,
@@ -1035,6 +1065,10 @@ function parseBriefArgs(args) {
         tldr,
         versions: values.booleans.has("--versions"),
         claims: values.booleans.has("--claims"),
+        ...(reason ? { reason } : {}),
+        // Waiting is the default; only an explicit `--no-wait` turns it off. A
+        // person who typed `rewrite` wants the page, not a receipt.
+        ...(noWait ? { wait: false } : {}),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-help.js

@@ -60,7 +60,7 @@ export function localCommandHelp(command) {
         "  cockpit settings [personal [--chat-model <key>] [--brief-model <key>] | switches [set <key> <value>] | models [set --chat <key>] [--memory <id>] | env list|set --project <p> --file <f> --content-stdin|delete --id <uuid> [--yes]] [--json]",
         "  cockpit team [members | invite <email> --role <role> [--team-id <uuid>] | role <userId> --role <role> [--yes]] [--json]",
         "  cockpit workbook [<project> [<doc>]] [--section <id>] [--markdown] [--width <n>] [--dashboard-url <url>] [--json]",
-        "  cockpit brief [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--dashboard-url <url>] [--json]",
+        "  cockpit brief [edit|rewrite] [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
         "  cockpit correct --claim <claimId> --text \"<what is wrong>\" [--for <person>] [--version <pageId>] [--supersedes <id>] [--dashboard-url <url>] [--json]",
         "  cockpit notes [list|show <id>|shelf|shelves|upload <paths...>|paste|share <id>|unshare <id>|move <id>] [--series <shelf>] [--kind <kind>] [--since <YYYY-MM-DD>] [--until <YYYY-MM-DD>] [--limit <n>] [--file <path>] [--name <n>] [--exclude \"<sentence>\"] [--to \"<shelf>\"|--clear-shelf] [--yes] [--dashboard-url <url>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--max-depth <n>] [--max-repos <n>] [--yes] [--workspace <path>] [--json]",
@@ -326,7 +326,7 @@ function localSubcommandHelp(command) {
         [
             "brief",
             [
-                "Usage: cockpit brief [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit brief [edit|rewrite] [--for <person>] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the TODAY page — the same page the Tower website shows, rendered for a terminal.",
                 "--for opens somebody else's page; the website's own rule decides whether you may, and it refuses in plain words when you may not.",
@@ -334,6 +334,17 @@ function localSubcommandHelp(command) {
                 "--version <pageId> steps back to one exact earlier version; --versions lists them with their ids.",
                 "--claims prints the [claimId] beside every line, which is what `cockpit correct --claim` takes.",
                 "Reading it here counts as opening it, exactly as opening it in a browser does.",
+                "",
+                "edit — opens the page in $VISUAL/$EDITOR as a document: one [claimId] line per sentence you may rewrite, everything else a # comment. Change the words after an id, save, close. Only the lines that really changed are sent, so an accidental save writes nothing.",
+                "  An id you delete or invent is refused by name BEFORE anything is sent: a missing line reads as no opinion at all, not as a sentence to remove, and Tower cannot tell those apart.",
+                "  --reason \"<why>\" rides on every row, exactly like a commit message. Optional; the before-and-after already teaches on its own.",
+                "  With no editor, or with something piped in, the edited document is read from stdin instead — `cockpit brief edit < page.md`.",
+                "  The edit IS the correction: each changed line is filed in the ledger before the page is republished, so a publish that falls over never costs you the edit.",
+                "",
+                "rewrite — asks Tower to compile the page again and waits for the new version. Writing a page takes minutes, so this queues the work and watches your page rather than holding one long request open.",
+                "  --no-wait returns as soon as the ask is on the record. Waiting is the default.",
+                "  Running out of patience is not a failure and says so: the work is still going, and `cockpit brief` will show it when it lands.",
+                "  Whose page you may ask about is the website's own rule — your own always, anybody's if you are an admin.",
                 "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
             ],
         ],

package/dist/commands/local.js

@@ -22,6 +22,9 @@
  *   workbook.ts          `cockpit workbook` — the project document library
  *                        (+ workbook-render.ts, the pure layout half)
  *   brief.ts             `cockpit brief` — the TODAY page in the terminal
+ *   brief-edit.ts        `cockpit brief edit` — rewrite it like a document
+ *   brief-rewrite.ts     `cockpit brief rewrite` — have Tower compile it again
+ *   editor.ts            the one place a person's own $EDITOR is spawned
  *   correct.ts           `cockpit correct` — one line on it is wrong
  *   notes.ts             `cockpit notes` — the meeting-notes surface, typed
  *   notes-file.ts        the local screen a note file passes before it is sent
@@ -52,6 +55,8 @@ import { runTeam } from "./team.js";
 import { asRecord, callTower, openTower } from "./tower-command.js";
 import { runWorkbook } from "./workbook.js";
 import { runBrief } from "./brief.js";
+import { runBriefEdit } from "./brief-edit.js";
+import { runBriefRewrite } from "./brief-rewrite.js";
 import { runCorrect } from "./correct.js";
 import { runNotes } from "./notes.js";
 import { createCollectorServer } from "../server.js";
@@ -133,6 +138,14 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
             case "workbook":
                 return await runWorkbook(command, io);
             case "brief":
+                // BLI-3458 S2.7/S2.8: `edit` and `rewrite` are the two PANEL actions
+                // reaching the terminal. Dispatched here rather than inside `brief.ts`
+                // so each one stays its own module — `brief.ts` owns reading and
+                // nothing else.
+                if (command.action === "edit")
+                    return await runBriefEdit(command, io);
+                if (command.action === "rewrite")
+                    return await runBriefRewrite(command, io);
                 return await runBrief(command, io);
             case "correct":
                 return await runCorrect(command, io);

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.41");
+    writeLine(io?.stdout ?? process.stdout, "0.2.42");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.41",
+  "version": "0.2.42",
   "private": false,
   "type": "module",
   "bin": {