@bli-cockpit/cli 0.2.239 → 0.2.240

package/dist/commands/local-args-tower-docs-msg.js

@@ -8,14 +8,14 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 import { parseDocsExportFlags } from "./local-args-docs-export.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export", "mutation-status"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export", "mutation-status", "share", "access"]);
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 // BLI-10450: `read` moved to its own branch in `parseDocsDocumentReference` —
 // it takes SEVERAL references now, so it no longer shares the "exactly one"
 // rule `update`/`link` still enforce. BLI‑10555: `delete` takes several too
 // (the same door, called once per ref), so it joined `read`'s branch rather
 // than this set.
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export", "mutation-status"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export", "mutation-status", "share", "access"]);
 const DOCS_ALLOWED_FLAGS = [
     "--home",
     "--dashboard-url",
@@ -37,6 +37,9 @@ const DOCS_ALLOWED_FLAGS = [
     "--offset",
     "--format",
     "--out",
+    "--add",
+    "--remove",
+    "--reason",
     "--json",
 ];
 const DOCS_VALUE_FLAGS = [
@@ -54,6 +57,9 @@ const DOCS_VALUE_FLAGS = [
     "--offset",
     "--format",
     "--out",
+    "--add",
+    "--remove",
+    "--reason",
 ];
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, { allowedFlags: DOCS_ALLOWED_FLAGS, valueFlags: DOCS_VALUE_FLAGS });
@@ -123,7 +129,7 @@ function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, export, or mutation-status.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, export, mutation-status, share, or access.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -233,6 +239,26 @@ function parseDocsReadFlags(action, values) {
         throw new Error("--offset belongs to `cockpit docs read`.");
     return { query, wholeWord, limit, bodies, section, offset };
 }
+/**
+ * BLI-21313: `docs share <doc> --add <email> | --remove <email> [--reason <text>]` names or removes a page editor;
+ * `docs access <doc>` reads who may edit and why. A person is an exact email address, never a fuzzy name.
+ */
+function parseDocsShareFlags(action, values) {
+    const addPerson = optionalNonEmpty(values.flags.get("--add"));
+    const removePerson = optionalNonEmpty(values.flags.get("--remove"));
+    const reason = optionalNonEmpty(values.flags.get("--reason"));
+    if ((addPerson || removePerson || reason) && action !== "share") {
+        throw new Error("--add, --remove and --reason belong to `cockpit docs share`.");
+    }
+    if (action === "share") {
+        if (Boolean(addPerson) === Boolean(removePerson)) {
+            throw new Error("docs share needs exactly one of --add <email> or --remove <email>.");
+        }
+        if (reason && reason.length > 200)
+            throw new Error("--reason can be at most 200 characters.");
+    }
+    return { ...(addPerson ? { addPerson } : {}), ...(removePerson ? { removePerson } : {}), ...(reason ? { reason } : {}) };
+}
 function parseDocsOffset(raw) {
     const offsetRaw = optionalNonEmpty(raw);
     if (offsetRaw === undefined)
@@ -268,6 +294,7 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(link.notionPage ? { notionPage: link.notionPage } : {}),
         ...(link.clearLink ? { clearLink: true } : {}),
         ...parseDocsExportFlags(action, values),
+        ...parseDocsShareFlags(action, values),
         json: values.booleans.has("--json"),
     };
 }

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

@@ -54,7 +54,7 @@ export function parseDrillsArgs(args) {
     if (action === "theme-set") {
         theme = rest.join(" ").trim();
         if (!theme)
-            throw new Error("`cockpit drills theme set` takes a theme: video-game, boxing, muay-thai, crime-drama, anime, sports, or your own words.");
+            throw new Error("`cockpit drills theme set` takes a theme: plain (no theme, the default), video-game, sports, movies-tv, music, anime, cooking, or anything you're into in your own words.");
     }
     else if (rest.length > 0)
         throw new Error(`\`cockpit drills ${action}\` takes no positional arguments.`);

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

@@ -1,5 +1,6 @@
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
-const MSG_ACTIONS = new Set(["channels", "read", "send", "thread", "create", "dm", "show", "unread"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MSG_ACTIONS = new Set(["channels", "read", "send", "thread", "create", "dm", "show", "unread", "edit", "delete", "outcome"]);
 const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send", "unread"]);
 /**
  * `--members a@x.test,b@y.test` — addresses only, split on commas, never
@@ -37,9 +38,14 @@ export function parseMsgArgs(args) {
             "--description",
             "--from",
             "--mark-read",
+            "--request-id",
+            "--expected-revision",
             "--json",
         ],
-        valueFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit", "--members", "--description", "--before", "--from"],
+        valueFlags: [
+            "--home", "--dashboard-url", "--channel", "--thread", "--limit", "--members", "--description", "--before", "--from",
+            "--request-id", "--expected-revision",
+        ],
     });
     const { action, rest } = parseMsgAction(values.positionals);
     if (values.flags.has("--before") && action !== "read" && action !== "thread") {
@@ -49,7 +55,35 @@ export function parseMsgArgs(args) {
     const { channelName, dmEmail } = parseMsgCreateTarget(action, rest);
     const { isPrivate, memberEmails, description } = parseMsgCreateFlags(action, values);
     const { channelRef, threadId, limit } = parseMsgReadTarget(action, rest, values);
-    return buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom);
+    const writeSafety = parseMsgWriteSafety(action, rest, values);
+    return buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom, writeSafety);
+}
+/** `send|edit|delete --request-id`, `edit|delete --expected-revision`, and the id `edit`/`delete`/`outcome` name (BLI-21314). */
+function parseMsgWriteSafety(action, rest, values) {
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID_PATTERN.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    if (requestId && action !== "send" && action !== "edit" && action !== "delete") {
+        throw new Error("--request-id belongs to `cockpit msg send`, `edit` or `delete`.");
+    }
+    const expectedRevision = optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision");
+    if (expectedRevision !== undefined && action !== "edit" && action !== "delete") {
+        throw new Error("--expected-revision belongs to `cockpit msg edit` or `delete`.");
+    }
+    let targetId;
+    if (action === "edit" || action === "delete" || action === "outcome") {
+        targetId = optionalNonEmpty(rest[0]);
+        if (!targetId) {
+            throw new Error(action === "outcome"
+                ? "msg outcome needs the request UUID, e.g. `cockpit msg outcome <request-uuid>`."
+                : `msg ${action} needs a message id, e.g. \`cockpit msg ${action} <message-id>\`.`);
+        }
+        if (rest.length > 1)
+            throw new Error(`msg ${action} takes one id, not ${rest.length}.`);
+        if (action === "outcome" && !UUID_PATTERN.test(targetId))
+            throw new Error("msg outcome takes a request UUID.");
+    }
+    return { targetId, requestId, expectedRevision };
 }
 /** `read --mark-read` and `unread --from <message-id>` (BLI-21299): the read line, moved on purpose. */
 function parseMsgReadLineFlags(action, values) {
@@ -68,7 +102,7 @@ function parseMsgAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "channels" : first);
     if (!MSG_ACTIONS.has(action)) {
-        throw new Error(`Unknown msg command: ${first}. Try channels, read, unread, send, thread, create, dm, or show.`);
+        throw new Error(`Unknown msg command: ${first}. Try channels, read, unread, send, thread, create, dm, or show; to change a message: edit, delete or outcome.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -129,7 +163,7 @@ function parseMsgReadTarget(action, rest, values) {
         if (rest.length > 1)
             throw new Error(`msg thread takes one thread id, not ${rest.length}.`);
     }
-    else if (action !== "create" && action !== "dm" && rest.length > 0) {
+    else if (action !== "create" && action !== "dm" && action !== "edit" && action !== "delete" && action !== "outcome" && rest.length > 0) {
         throw new Error(`msg ${action} does not take "${rest[0]}".`);
     }
     const threadFlag = optionalNonEmpty(values.flags.get("--thread"));
@@ -145,7 +179,7 @@ function parseMsgReadTarget(action, rest, values) {
     }
     return { channelRef, threadId, limit };
 }
-function buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom) {
+function buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit, markRead, unreadFrom, writeSafety) {
     return {
         kind: "msg",
         action,
@@ -162,6 +196,9 @@ function buildMsgCommand(values, action, channelRef, channelName, dmEmail, membe
         ...(limit === undefined ? {} : { limit }),
         ...(markRead ? { markRead } : {}),
         ...(unreadFrom ? { unreadFrom } : {}),
+        ...(writeSafety.targetId ? { targetId: writeSafety.targetId } : {}),
+        ...(writeSafety.requestId ? { requestId: writeSafety.requestId } : {}),
+        ...(writeSafety.expectedRevision === undefined ? {} : { expectedRevision: writeSafety.expectedRevision }),
         json: values.booleans.has("--json"),
     };
 }

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

@@ -68,6 +68,15 @@ const ISSUE_ALLOWED_FLAGS = [
     "--parent",
     "--file",
     "--version",
+    "--cursor",
+    "--q",
+    "--created-after",
+    "--created-before",
+    "--updated-after",
+    "--updated-before",
+    "--sort",
+    "--dir",
+    "--all",
     "--body-stdin",
     "--json",
 ];
@@ -88,6 +97,14 @@ const ISSUE_VALUE_FLAGS = [
     "--parent",
     "--file",
     "--version",
+    "--cursor",
+    "--q",
+    "--created-after",
+    "--created-before",
+    "--updated-after",
+    "--updated-before",
+    "--sort",
+    "--dir",
 ];
 export function parseIssueArgs(args) {
     const values = parseNamedArgs(args, {
@@ -108,9 +125,13 @@ export function parseIssueArgs(args) {
     validateIssueState(moveState, "issue move state must be one of: ");
     const stateFilter = readIssueStateFilter(action, values);
     const title = readIssueTitle(action, values);
-    if (action !== "board" && (values.flags.has("--label") || values.flags.has("--rows"))) {
-        throw new Error("--label and --rows filter cockpit tickets board only.");
+    if (action !== "board" && values.flags.has("--rows")) {
+        throw new Error("--rows widens cockpit tickets board only.");
     }
+    if (action !== "board" && action !== "list" && values.flags.has("--label")) {
+        throw new Error("--label filters cockpit tickets board and cockpit tickets list.");
+    }
+    const page = readIssuePage(action, values);
     const boardProject = optionalNonEmpty(values.flags.get("--project"));
     if (action === "board" && boardProject && !UUID_PATTERN.test(boardProject))
         throw new Error("board --project requires a uuid.");
@@ -119,7 +140,51 @@ export function parseIssueArgs(args) {
     const assignee = readIssueAssignee(action, values);
     const limit = readIssueLimit(action, values);
     const versionNumber = readIssueVersion(action, values);
-    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber);
+    return buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page);
+}
+const INSTANT = /^\d{4}-\d\d-\d\d(?:T\d\d:\d\d:\d\d(?:\.\d{1,6})?(?:Z|[+-]\d\d:\d\d))?$/;
+/** BLI-21315: the cursor contract's flags. Filters and sort belong to `list`; `--cursor` also to `history`. */
+function readIssuePage(action, values) {
+    const named = ["--q", "--created-after", "--created-before", "--updated-after", "--updated-before", "--sort", "--dir"];
+    for (const flag of named) {
+        if (values.flags.has(flag) && action !== "list")
+            throw new Error(`${flag} belongs to \`cockpit ticket list\`.`);
+    }
+    if (values.booleans.has("--all") && action !== "list")
+        throw new Error("--all belongs to `cockpit ticket list`.");
+    if (values.flags.has("--cursor") && action !== "list" && action !== "history") {
+        throw new Error("--cursor belongs to `cockpit ticket list` and `cockpit ticket history`.");
+    }
+    const instants = {};
+    for (const flag of ["--created-after", "--created-before", "--updated-after", "--updated-before"]) {
+        const value = optionalNonEmpty(values.flags.get(flag));
+        if (value !== undefined && (!INSTANT.test(value) || !Number.isFinite(Date.parse(value)))) {
+            throw new Error(`${flag} must be a UTC instant like 2026-10-01T00:00:00Z or a date like 2026-10-01.`);
+        }
+        instants[flag] = value;
+    }
+    const sort = optionalNonEmpty(values.flags.get("--sort"));
+    if (sort !== undefined && sort !== "updated_at" && sort !== "created_at")
+        throw new Error("--sort must be updated_at or created_at.");
+    const dir = optionalNonEmpty(values.flags.get("--dir"));
+    if (dir !== undefined && dir !== "asc" && dir !== "desc")
+        throw new Error("--dir must be asc or desc.");
+    const all = values.booleans.has("--all");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    if (all && cursor)
+        throw new Error("--all walks from the start; drop --cursor, or pass --cursor without --all to read one page.");
+    const q = optionalNonEmpty(values.flags.get("--q"));
+    return {
+        ...(cursor ? { cursor } : {}),
+        ...(q ? { q } : {}),
+        ...(instants["--created-after"] ? { createdAfter: instants["--created-after"] } : {}),
+        ...(instants["--created-before"] ? { createdBefore: instants["--created-before"] } : {}),
+        ...(instants["--updated-after"] ? { updatedAfter: instants["--updated-after"] } : {}),
+        ...(instants["--updated-before"] ? { updatedBefore: instants["--updated-before"] } : {}),
+        ...(sort ? { sort } : {}),
+        ...(dir ? { dir } : {}),
+        ...(all ? { all } : {}),
+    };
 }
 function readIssueAction(values) {
     const first = values.positionals[0];
@@ -230,7 +295,7 @@ function readIssueLimit(action, values) {
     }
     return limit;
 }
-function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber) {
+function buildIssueCommand(values, action, issueRef, issueRefs, moveState, stateFilter, title, priority, estimate, assignee, limit, versionNumber, page) {
     return {
         kind: "issue",
         requestId: optionalNonEmpty(values.flags.get("--request-id")),
@@ -247,6 +312,7 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
         rows: optionalNonEmpty(values.flags.get("--rows")),
         project: optionalNonEmpty(values.flags.get("--project")),
         ...(limit === undefined ? {} : { limit }),
+        ...page,
         ...(versionNumber === undefined ? {} : { versionNumber }),
         title,
         ...(priority === undefined ? {} : { priority }),
@@ -259,8 +325,8 @@ function buildIssueCommand(values, action, issueRef, issueRefs, moveState, state
 }
 export function parseProjectArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--dashboard-url", "--archived", "--json"],
-        valueFlags: ["--home", "--dashboard-url"],
+        allowedFlags: ["--home", "--dashboard-url", "--archived", "--cursor", "--limit", "--json"],
+        valueFlags: ["--home", "--dashboard-url", "--cursor", "--limit"],
     });
     const first = values.positionals[0];
     const action = (first === undefined ? "list" : first);
@@ -275,6 +341,8 @@ export function parseProjectArgs(args) {
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         includeArchived: values.booleans.has("--archived"),
+        ...(optionalNonEmpty(values.flags.get("--cursor")) ? { cursor: optionalNonEmpty(values.flags.get("--cursor")) } : {}),
+        ...(values.flags.has("--limit") ? { limit: optionalPositiveInteger(values.flags.get("--limit"), "--limit") } : {}),
         json: values.booleans.has("--json"),
     };
 }

package/dist/commands/local-help-commands-tower-ops.js

@@ -197,10 +197,10 @@ export const TOWER_OPS_COMMAND_HELP = [
             "  cockpit drills start                          open the next drill: the change or command, what it printed, and the question. The cause is NOT shown",
             "  cockpit drills answer --confidence <1-5>      your answer on stdin (or --text), and how sure you are; then the real cause and the guard are shown",
             "  cockpit drills theme                          your theme and the choices",
-            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    video-game (the default), boxing, muay-thai, crime-drama, anime, sports, or your own words",
+            "  cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]    plain (the default: no theme), video-game, sports, movies-tv, music, anime, cooking, or anything you're into",
             "  cockpit drills review                         your own week: hits, wins, highs, lows, where you have stopped improving, what to practise",
-            "A drill replays a real mistake the team already paid for. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
-            "Each of your top patterns is a boss: pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
+            "A drill replays a real mistake the team already paid for, shown straight with no theme unless you pick one. You answer first, so a wrong answer you were sure about is the one you remember; it comes back 1, 3 and 7 days later.",
+            "Each of your top patterns is something to beat (a boss, if you pick a theme): pass its drills, then a stretch of your own PRs without taking that hit again. There is no leaderboard; these are your own rows only.",
             "Anything that needs your hit history says so when it is not connected yet, instead of showing a zero.",
             "--home <dir> and --dashboard-url <url> are for tests and staging.",
             "--json writes one object to stdout (the door's body) and nothing else; a refusal is { ok: false, error, detail } and exits 1.",

package/dist/commands/local-help-commands-tower.js

@@ -47,7 +47,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "docs",
         [
-            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]|mutation-status <request-uuid>] [flags]",
+            "Usage: cockpit docs [list|tree|read <id|slug> [<id|slug>...]|read --parent <id> --bodies|create|update <id>|delete <id|slug> [<id|slug>...]|link <id|slug> <notion-page>|sync-status [<id|slug>]|export <id|slug> [--format md|pdf|docx|txt] [--out <path>]|mutation-status <request-uuid>|share <id|slug> --add|--remove <email>|access <id|slug>] [flags]",
             "",
             "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
             "list [--parent <id>|root] [--query <text> [--word]] [--limit <n>] — every document you may see: id, visibility, body size, slug, title. Metadata only — a list never carries a body, so it stays cheap enough for an agent to call (--json was 604 KB for 155 documents before BLI-3737, and is now a few tens of KB). --json shape: { documents: [{ id, slug, title, visibility, parent_id, source, updated_at, body_chars }] }.",
@@ -67,20 +67,21 @@ export const TOWER_COMMAND_HELP = [
             "  --request-id <uuid> makes a retry apply once (minted and printed when absent). Reusing it with different input is request_id_reused. If the response is lost, run `cockpit docs mutation-status <uuid>`, then retry the SAME input with the SAME id.",
             "mutation-status <request-uuid> — your own save receipt: committed (with the stored revision), not_committed (with the reason) or unknown_check_again (no receipt yet; it never proves nothing changed). --json shape: { mutation }.",
             "  --allow-empty clears the page on purpose. A body that would empty a document that holds text is refused (refused_empty_body) unless you say so, because far more often it is a surface that lost the content than a person who meant it.",
+            "access <id|slug> — who may do what on a page and why, in plain sentences (BLI-21313): your role (author, admin, granted_editor, reader), can_read/can_edit/can_manage, the named editors you may see (the owner and administrators see all; a named editor sees only their own grant), and the grant history for the owner and administrators. The same explanation the page, its versions and its export carry. --json shape: { ok, document_id, permission: { role, can_read, can_edit, can_manage, editors, editors_complete, reasons }, events }.",
+            "share <id|slug> --add <email> | --remove <email> [--reason \"<note>\"] — owner or administrator only. Names (or removes) an editor of an ORGANIZATION page by exact email, never fuzzy. An editor can change the title and text; they cannot change visibility, move, delete or manage editors, and nobody new gains the right to read. A page you made private refuses with private_page_grant_needs_decision (sharing a private page waits for a decision) and nothing is written. Other refusals: not_grant_manager, person_not_found, grantee_is_author, document_not_found_or_unreadable. Adding someone already named, or removing someone not named, answers outcome unchanged. --json shape: { ok, outcome, reason, document_id, grantee_id, request_id, permission }.",
             "delete <id|slug> [<id|slug>...] — soft-deletes one or more documents (BLI-10555): the browser's own delete, sets deleted_at, never a real SQL DELETE. Recoverable — only a super_admin clearing deleted_at brings it back, there is no self-service undo. Deleting a parent does NOT delete its children; they keep their own parent_id and stay exactly where they were. Several refs resolve against ONE shared list call, then one DELETE each — one bad ref never loses the rest. --json shape: one ref answers { ok, document_id }; several answer { documents: [{ ref, ok, document_id } | { ref, ok: false, error, detail }] }.",
             "link <id|slug> <notion-url|page-id> — ties the document to a Notion page so the two-way sync moves it both ways. The page is the truth from then on: the next sync pulls it over this copy and keeps the copy as a version. `link <id|slug> --clear` unties it. Refusals: invalid_notion_page, notion_page_already_linked, document_not_writable.",
             "sync-status [<id|slug>] — every linked document's Notion sync state, or one's: synced (the body is what both sides last agreed on), tower_changed (edited here since; the next write-back pushes it), never_synced (linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull, not here. Metadata only, never a body.",
             "export <id|slug> [--format md|pdf|docx|txt] [--out <path>] — writes the document as a file (ticket 20694): md is the stored Markdown exactly, txt is readable plain text, docx is a Word file with real headings, lists, tables and links, pdf is a paginated page with the title and last-updated date in the header. Default format md; default path is the document's slug plus the extension in the current directory (--out names a file, or a directory to put it in), and an existing file is replaced. Prints the path; --json shape: { ok, path, bytes, format }. To copy a page's text, `cockpit docs read` already does it.",
             "A document body is never accepted on the command line — --file (safest on Windows) or a pipe only, same discipline as `cockpit notes paste`.",
-            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
-            "A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
+            "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr. A refusal keeps Tower's own reason label — needs_rls_client, document_not_found_or_unreadable, document_not_writable, slug_taken, circular_parent, and so on.",
             "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
         ],
     ],
     [
         "msg",
         [
-            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|unread <channel> --from <message-id>|send <channel>|thread <id> --channel <channel>|show <message-id>] [flags]",
+            "Usage: cockpit msg [channels|create <name>|dm <email>|read <channel>|unread <channel> --from <message-id>|send <channel>|edit <message-id>|delete <message-id>|outcome <request-uuid>|thread <id> --channel <channel>|show <message-id>] [flags]",
             "",
             "Channels and messages, typed. <channel> is a channel id, or its name with or without a leading #.",
             "channels — every channel you are a member of (or, as a super_admin, every channel).",
@@ -88,7 +89,8 @@ export const TOWER_COMMAND_HELP = [
             "dm <email> — opens (or re-opens) the direct message with one person. Idempotent: the same address always resolves to the same channel, and you never have to name yourself.",
             "read <channel> [--limit <n>] [--thread <id>] [--mark-read] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead. The first page also says where the messages come from (for an imported Slack channel: how long ago the archive was checked, or that it is unknown) and where YOUR read line stands. Reading never moves the read line; --mark-read moves it to the newest message shown, and says plainly if that failed.",
             "unread <channel> --from <message-id> — marks that message and everything after it unread, so the web sidebar badge and the NEW MESSAGES line start there. Opening or reading a channel never clears unseen history.",
-            "send <channel> [--thread <id>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`.",
+            "send <channel> [--thread <id>] [--request-id <uuid>] — posts a message. The content is never accepted on the command line: pipe it in, e.g. `echo \"hello\" | cockpit msg send general`. Every send carries a request id (minted when you give none); retry a send whose answer was lost with the SAME --request-id and the same text and it posts once. The same id with different text is refused request_id_reused, not applied as an edit.",
+            "edit <message-id> [--expected-revision <n>] [--request-id <uuid>] — replaces your own message's text (piped in). With --expected-revision, an edit of a message that has moved on is refused revision_conflict and nothing is saved over it; the current revision is printed. A message you did not write, or one that was deleted, is refused by name. delete <message-id> [--expected-revision <n>] [--request-id <uuid>] — deletes by tombstone: the text is cleared and every surface reads \"This message was deleted\", but the row stays so its thread, replies and reply count survive. Search and unread counts ignore it. A repeat answers already_deleted. outcome <request-uuid> — your own write receipt for a send, edit or delete: committed, not_committed (with the reason) or unknown_check_again. Run it after a timeout before retrying.",
             "thread <id> --channel <channel> [--before <cursor>] [--limit <n>] — one thread's replies by the parent message's id.",
             "show <message-id> — exact message, thread root and bounded neighbors. read/thread --before takes the preceding nextCursor; repeat until hasMore is false.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
@@ -102,7 +104,7 @@ export const TOWER_COMMAND_HELP = [
             "Usage: cockpit issue [board|list|show <id> [<id>...]|create|update <id>|move <id> <state>|comment <id>|history <id>|versions <id>|restore <id> --version <n>|mutation-status <request-uuid>] [flags]",
             "",
             "Tower's issue tracker. <id> is a BLI-#### identifier (BLI-3654) or an issue's uuid — both work everywhere an issue is named.",
-            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] — the issues you may see, most recently updated first. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
+            "list [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--label <name>] [--q <text>] [--created-after|--created-before|--updated-after|--updated-before <utc instant|date>] [--sort updated_at|created_at] [--dir desc|asc] [--limit <n>] [--cursor <c>] [--all] — the issues you may see, most recently updated first. A page is 100 by default and at most 500. Filters run in the database BEFORE the page, so a label or title match deep in the set is found. --q is a case-insensitive title contains (% and _ are literal); *-after is inclusive, *-before is exclusive. --json adds next_cursor, has_more, coverage (complete|capped|failed_partial), requested, returned, unique: pass next_cursor back as --cursor with the same other flags. --all walks every page and streams ONE JSON OBJECT PER LINE (NDJSON; rows carry assignee_id, no names), then a final {\"type\":\"coverage\",...} line naming the coverage; an interrupted walk ends with coverage failed_partial, the reason and the resume cursor, and exits 1. Each row carries assignee_name/assignee_email alongside the bare assignee_id (BLI-10450, one extra `cockpit team members` call for the whole page, never per row), and a `size` label (S/M/L) alongside the raw `estimate` when it matches Tower's own scale (BLI-10575). --json shape: { issues: [{ id, identifier, title, state, priority, estimate, size, assignee_id, assignee_name, assignee_email, project_id, parent_id, updated_at }] }.",
             "board [--json] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <uuid>] [--label <name>] [--rows <state:n,...>] — the Tickets board, counts, coverage and top five cards per column, through GET /api/work/board. Also cockpit tickets board.",
             "show <id> [<id>...] — one or more issues: title, state, priority, size, assignee (name and email, not just its id), description, and every comment on each. Several ids read in one call — one bad id never loses the rest.",
             "  --json shape: one id answers { issue, comments }, unchanged from before BLI-10450 (plus `estimate`/`size`, BLI-10575). Several ids answer { issues: [{ ref, ok, issue, comments } | { ref, ok: false, error, detail }] }.",
@@ -112,7 +114,7 @@ export const TOWER_COMMAND_HELP = [
             "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
             "Writes accept --request-id <uuid> and --expected-revision <n>. Keep the UUID and identical fields across retries; JSON includes mutation receipt and mirror delivery separately.",
             "mutation-status <request-uuid> — check your own local commit and mirror delivery after a lost response; no receipt means unknown_check_again.",
-            "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
+            "history <id> [--limit <n>] [--cursor <c>] — every recorded state move and reassignment, oldest first; --json carries the same page fields as list.",
             "versions <id> [--limit <n>] — every saved description, newest first, each with its number, id, author, source and time (BLI-21300). --json shape: { versions: [{ id, version, markdown, author_id, source, restored_from_version, created_at }] }.",
             "restore <id> --version <n> [--request-id <uuid>] [--expected-revision <n>] — writes version <n>'s text back as a NEW version; nothing is rewritten, so the restore can itself be undone. A stale revision conflicts and changes nothing. --json shape: { issue, mutation }.",
             "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
@@ -151,7 +153,7 @@ export const TOWER_COMMAND_HELP = [
     [
         "cal",
         [
-            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find "<words>"|calendars|add-ical|create|duplicate <event id>|batch|undo [<change id>]|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [flags]',
+            'Usage: cockpit cal [event <id>|export <id>|today|week|conflicts|calendar-change <id> --color <hex-or-provider>|next|find "<words>"|calendars|add-ical|create|duplicate <event id>|batch|undo [<change id>]|rsvp <event id> --response <accepted|declined|tentative>|change <event id>|cancel <event id> --yes|share <id>|sync <id>|sync-status [<id>]|detach <id>|delete <event id> --yes] [flags]',
             "",
             "Every calendar you attached, in one place — plus any calendar a colleague marked shared.",
             "today [--offset 1] [--tz <zone>] — what is on today, in YOUR zone (this machine's, unless --tz says otherwise). --offset 1 is tomorrow, -1 yesterday.",
@@ -170,6 +172,8 @@ export const TOWER_COMMAND_HELP = [
             "      A work @buildlaunchiterate.ca calendar does not need this: connect Google in the browser and `cockpit cal calendars` will list them.",
             'create [--account <name>|--calendar <id>] --title "<what>" --at <iso> --until <iso> [--location "<where>"] [--attendee a@x,b@y] [--all-day] [--meet] — creates the event AT GOOGLE, then here. Attendees are invited by Google; --meet asks for a Google Meet room and prints its address (or says meet_not_available and keeps the event).',
             "      Only a Google calendar can be written to: an iCal secret address is a read address, and `write_not_supported_for_provider` says so by name.",
+            "rsvp <event id> --response accepted|declined|tentative [--comment \"<text>\"] [--scope instance|series] [--occurrence <iso>] [--account <name>] [--key <k>] — answers YOUR invitation; only your own guest entry changes and nobody else is emailed by Tower. Refuses with not_a_guest when you are not on the guest list.",
+            "change <event id> [--title ..] [--at <iso>] [--until <iso>] [--location ..] [--scope instance|following|series] [--occurrence <iso>] [--color 1-11|none] [--reminder <minutes[:popup|email]>|default]... [--visibility default|public|private|confidential] [--transparency opaque|transparent] — a recurring event REQUIRES --scope (instance and following also need --occurrence): instance = this event, following = this and following events (starts a NEW series), series = all events. --reminder repeats, at most 5; `default` alone means the calendar default. Refusals keep the door's reason (scope_required, occurrence_required, scope_not_supported, following_is_series, write_refused). cancel <event id> --yes [--scope instance|following|series] [--occurrence <iso>] [--account <name>] — same scope rules as change; `following` trims the series and prints the new end. create also takes --color, --reminder, --visibility and --transparency.",
             "share <id> --org-visible|--private — makes one of YOUR calendars readable by everyone at BLI, or private again. Sharing never lets anybody else change it.",
             "sync <id> [--full] — reads that calendar now instead of waiting for the cron. --full ignores the sync token / ETag and re-reads everything.",
             "sync-status [<id>] — every calendar's health, or one's: last successful sync, the last pass's own reason, how many events it carried, failures in the last 24h, and the lag between an event's own provider clock and when Tower stored it (ticket 10730).",
@@ -188,10 +192,10 @@ export const TOWER_COMMAND_HELP = [
     [
         "project",
         [
-            "Usage: cockpit project [list] [--archived] [--json]",
+            "Usage: cockpit project [list] [--archived] [--limit <n>] [--cursor <c>] [--json]",
             "",
             "The projects issues are filed under. Bare `cockpit project` lists them.",
-            "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+            "list [--archived] [--limit <n>] [--cursor <c>] — id, active/archived, name. --archived includes archived projects. A page is at most 500; when more exist the output (and --json: next_cursor, has_more, coverage, requested, returned, unique) carries the cursor to pass back as --cursor.",
             "There is no create/update/delete verb: `GET /api/work/projects` is the whole of Tower's project door today.",
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],

package/dist/commands/msg-write.js

@@ -0,0 +1,118 @@
+/**
+ * The message WRITE verbs of `cockpit msg` (BLI-21314): `edit`, `delete`, `outcome`, plus what `send`
+ * shares with them (the piped body, the one deleted sentence, the refusal that says how to check a write).
+ * Split out of `msg.ts` to keep it under the file-size ratchet. Same doors the browser calls.
+ */
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[msg cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 30_000;
+const CONTENT_MAX_CHARS = 8_000;
+/** The one sentence a deleted message reads as, on every surface. */
+export const DELETED_SENTENCE = "This message was deleted";
+export function messageText(message) {
+    return message.deleted_at ? `(${DELETED_SENTENCE})` : (message.content ?? "");
+}
+export async function readContent(io) {
+    if (isInteractiveStdin(io)) {
+        return {
+            ok: false,
+            reason: "nothing_piped",
+            detail: "Pipe the message in, e.g. `echo \"hello\" | cockpit msg send general`. A message never travels on the command line.",
+        };
+    }
+    try {
+        const text = await readPipedText(io.stdin, {
+            maxChars: CONTENT_MAX_CHARS,
+            overflowMessage: `A message is limited to ${CONTENT_MAX_CHARS} characters.`,
+        });
+        return { ok: true, text: text.trim() };
+    }
+    catch (error) {
+        return { ok: false, reason: "content_too_long", detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Says where the write stands, then fails with the door's own reason. A conflict names the current revision;
+ * an unknown result says how to resolve it by request id before retrying.
+ */
+export function refuseMsgWrite(door, answer, requestId, verb) {
+    const mutation = answer.body?.mutation;
+    writeLine(door.io.stderr, `${TAG} check the ${verb} with cockpit msg outcome ${requestId}; retry unchanged input with --request-id ${requestId}.`);
+    if (answer.reason === "revision_conflict") {
+        writeLine(door.io.stderr, `${TAG} conflict ${JSON.stringify({ request_id: requestId, current_revision: mutation?.current?.revision ?? mutation?.revision ?? null })}`);
+    }
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+/** `cockpit msg edit <message-id> [--expected-revision <n>] [--request-id <uuid>]` — the new text is piped in. */
+export async function editMessage(command, door) {
+    const content = await readContent(door.io);
+    if (!content.ok)
+        return failAgentDoor(door, TAG, content.reason, content.detail);
+    if (content.text === "")
+        return failAgentDoor(door, TAG, "invalid_body", "There was nothing to save. Nothing was changed.");
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/messages/${encodeURIComponent(command.targetId ?? "")}`,
+        method: "PATCH",
+        label: "msg edit",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            content: content.text,
+            request_id: requestId,
+            ...(command.expectedRevision === undefined ? {} : { expected_revision: command.expectedRevision }),
+        },
+    });
+    if (!answer.ok)
+        return refuseMsgWrite(door, answer, requestId, "edit");
+    const { message = null, mutation = null } = answer.body;
+    writeLine(door.io.stderr, `${TAG} edited ${JSON.stringify({ message_id: command.targetId, request_id: requestId, revision: mutation?.["revision"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, message, mutation });
+    writeLine(door.io.stdout, `Edited ${message?.id ?? command.targetId}, revision ${String(mutation?.["revision"] ?? message?.revision ?? "?")}.`);
+    return 0;
+}
+/** `cockpit msg delete <message-id> [--expected-revision <n>] [--request-id <uuid>]` — a tombstone: the thread stays, the text goes. */
+export async function deleteMessage(command, door) {
+    const requestId = command.requestId ?? randomUUID();
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/messages/${encodeURIComponent(command.targetId ?? "")}`,
+        method: "DELETE",
+        label: "msg delete",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            request_id: requestId,
+            ...(command.expectedRevision === undefined ? {} : { expected_revision: command.expectedRevision }),
+        },
+    });
+    if (!answer.ok)
+        return refuseMsgWrite(door, answer, requestId, "delete");
+    const { message = null, mutation = null } = answer.body;
+    writeLine(door.io.stderr, `${TAG} deleted ${JSON.stringify({ message_id: command.targetId, request_id: requestId, reason: mutation?.["reason"] ?? "ok" })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, message, mutation });
+    writeLine(door.io.stdout, `Deleted ${command.targetId} (${DELETED_SENTENCE.toLowerCase()}; its thread and replies stay).`);
+    return 0;
+}
+/** `cockpit msg outcome <request-uuid>` — your own write receipt. No receipt is `unknown_check_again`, never "nothing changed". */
+export async function messageOutcome(command, door) {
+    const answer = await askAgentDoor(door, {
+        path: `/api/msg/mutations/${encodeURIComponent(command.targetId ?? "")}`,
+        method: "GET",
+        label: "msg outcome",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const mutation = answer.body.mutation ?? {};
+    writeLine(door.io.stderr, `${TAG} outcome ${JSON.stringify({ request_id: command.targetId, outcome: mutation["outcome"] ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, mutation });
+    const outcome = String(mutation["outcome"] ?? "unknown_check_again");
+    writeLine(door.io.stdout, outcome === "unknown_check_again"
+        ? "Unknown: Tower has no receipt for that request yet. It may still be in flight; check again before retrying, and retry with the same --request-id."
+        : `${outcome}${mutation["reason"] ? ` (${String(mutation["reason"])})` : ""}${mutation["message_id"] ? `, message ${String(mutation["message_id"])}` : ""}.`);
+    return 0;
+}