@bli-cockpit/cli 0.2.67 → 0.2.69

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

@@ -0,0 +1,165 @@
+/**
+ * `cockpit cal` argument parsing (BLI-3709) — the calendar surface's half of
+ * `local-args-tower.ts`, a sibling of `local-args-tower-mail.ts` for the same
+ * reason that file is one: a calendar has its own vocabulary (a window, a
+ * zone, a series, a secret address) and folding it into another family's
+ * parser would stretch that family's doc comment past the truth.
+ *
+ * ONE SECRET NEVER TRAVELS ON ARGV, and it is refused here rather than at the
+ * door: **the secret iCal address**. `cockpit cal add-ical` reads it from
+ * STDIN, always, and there is no `--url` flag to forget about. That address is
+ * a permanent, unauthenticated, read-anything-on-that-calendar credential;
+ * argv is world-readable on a shared machine (`ps`), lands in shell history,
+ * and is captured by this very product's own session harvester. Same rule as
+ * `mail add-imap`, same reasoning, and the same reason neither has an MCP
+ * twin.
+ *
+ * THE ZONE IS ALWAYS SENT. Every read verb passes `--tz` (or the machine's own
+ * zone, read from `Intl`) to the door, because a window computed on the server
+ * would be computed in UTC — "today" would end at 5pm in Vancouver.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
+const CAL_ACTIONS = new Set([
+    "today",
+    "week",
+    "next",
+    "find",
+    "calendars",
+    "add-ical",
+    "create",
+    "share",
+    "detach",
+    "sync",
+]);
+/** Every verb that names ONE calendar first. */
+const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["sync", "detach", "share"]);
+export function parseCalArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [
+            "--home",
+            "--dashboard-url",
+            "--calendar",
+            "--tz",
+            "--offset",
+            "--hours",
+            "--from",
+            "--to",
+            "--limit",
+            "--all",
+            "--name",
+            "--title",
+            "--at",
+            "--until",
+            "--location",
+            "--attendee",
+            "--all-day",
+            "--org-visible",
+            "--private",
+            "--full",
+            "--json",
+        ],
+        valueFlags: [
+            "--home",
+            "--dashboard-url",
+            "--calendar",
+            "--tz",
+            "--offset",
+            "--hours",
+            "--from",
+            "--to",
+            "--limit",
+            "--name",
+            "--title",
+            "--at",
+            "--until",
+            "--location",
+            "--attendee",
+        ],
+    });
+    const first = values.positionals[0];
+    const action = (first === undefined ? "today" : first);
+    if (!CAL_ACTIONS.has(action)) {
+        throw new Error(`Unknown cal command: ${first}. Try today, week, next, find, calendars, add-ical, create, share, detach, or sync.`);
+    }
+    const rest = values.positionals.slice(first === undefined ? 0 : 1);
+    let subject;
+    let query;
+    if (CAL_ACTIONS_NEEDING_A_SUBJECT.has(action)) {
+        subject = optionalNonEmpty(rest[0]);
+        if (!subject)
+            throw new Error(`cal ${action} needs a calendar id — take one from \`cockpit cal calendars\`.`);
+        if (rest.length > 1)
+            throw new Error(`cal ${action} takes one id, not ${rest.length}.`);
+    }
+    else if (action === "find") {
+        query = optionalNonEmpty(rest.join(" "));
+        if (!query)
+            throw new Error('cal find needs words: cockpit cal find "standup".');
+    }
+    else if (rest.length > 0) {
+        throw new Error(`cal ${action} does not take "${rest[0]}".`);
+    }
+    const title = optionalNonEmpty(values.flags.get("--title"));
+    const startsAt = optionalNonEmpty(values.flags.get("--at"));
+    const endsAt = optionalNonEmpty(values.flags.get("--until"));
+    if (action === "create") {
+        if (!optionalNonEmpty(values.flags.get("--calendar"))) {
+            throw new Error("cal create needs --calendar <id>: with several calendars attached, which one this goes on is yours to say. `cockpit cal calendars` lists them.");
+        }
+        if (!title)
+            throw new Error('cal create needs --title "<what it is>".');
+        if (!startsAt)
+            throw new Error("cal create needs --at <when it starts> (an ISO instant, or a date with --all-day).");
+        if (!endsAt)
+            throw new Error("cal create needs --until <when it ends>.");
+    }
+    if (action === "share" && !values.booleans.has("--org-visible") && !values.booleans.has("--private")) {
+        throw new Error("cal share needs --org-visible (every member may read it) or --private (only you). Sharing is a decision, not a default.");
+    }
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const offsetRaw = optionalNonEmpty(values.flags.get("--offset"));
+    const offset = offsetRaw === undefined ? undefined : Number.parseInt(offsetRaw, 10);
+    if (offset !== undefined && !Number.isFinite(offset)) {
+        throw new Error("--offset takes a whole number of days (today/next) or weeks (week).");
+    }
+    return {
+        kind: "cal",
+        action,
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(subject ? { subjectId: subject } : {}),
+        ...(query ? { query } : {}),
+        calendarId: optionalNonEmpty(values.flags.get("--calendar")),
+        // An absent `--tz` means "this machine's zone", resolved at run time in
+        // `commands/cal.ts` rather than here, so the parser stays pure.
+        timeZone: optionalNonEmpty(values.flags.get("--tz")),
+        ...(offset === undefined ? {} : { offset }),
+        ...(optionalPositiveInteger(values.flags.get("--hours"), "--hours") === undefined
+            ? {}
+            : { hours: optionalPositiveInteger(values.flags.get("--hours"), "--hours") }),
+        from: optionalNonEmpty(values.flags.get("--from")),
+        to: optionalNonEmpty(values.flags.get("--to")),
+        ...(limit === undefined ? {} : { limit }),
+        includeDeselected: values.booleans.has("--all"),
+        name: optionalNonEmpty(values.flags.get("--name")),
+        title,
+        startsAt,
+        endsAt,
+        location: optionalNonEmpty(values.flags.get("--location")),
+        attendees: splitAddresses(values.flags.get("--attendee")),
+        allDay: values.booleans.has("--all-day"),
+        orgVisible: values.booleans.has("--org-visible"),
+        makePrivate: values.booleans.has("--private"),
+        full: values.booleans.has("--full"),
+        json: values.booleans.has("--json"),
+    };
+}
+/** `a@x.com,b@y.com` → two attendees. Exact, never fuzzy; empties dropped. */
+function splitAddresses(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value !== "");
+}

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

@@ -21,6 +21,7 @@
  *   local-args-tower-work.ts    issue, project     — the issue tracker
  *                                                      (BLI-3716)
  *   local-args-tower-mail.ts    mail               — the mailboxes (BLI-3708)
+ *   local-args-tower-cal.ts     cal                — the calendars (BLI-3709)
  *   local-args-tower-search.ts   search            — one bar over all five
  *                                                      corpora (BLI-3728)
  *
@@ -32,4 +33,5 @@ export { SCOUT_MIN_PREFIX_LENGTH, parseScoutArgs, parseOpsArgs, SLACK_WORKSPACE_
 export { parseDocsArgs, parseMsgArgs, } from "./local-args-tower-docs-msg.js";
 export { ISSUE_STATES, parseIssueArgs, parseProjectArgs, } from "./local-args-tower-work.js";
 export { SEARCH_KINDS, parseSearchArgs } from "./local-args-tower-search.js";
-export { parseMailArgs } from "./local-args-tower-mail.js";
+export { parseMailArgs } from "./local-args-tower-mail.js";
+export { parseCalArgs } from "./local-args-tower-cal.js";

package/dist/commands/local-args.js

@@ -16,7 +16,7 @@
  * verbatim, no logic change.
  */
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseScoutArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -105,6 +105,8 @@ export function parseLocalArgs(argv) {
             return parseIssueArgs(argv.slice(1));
         case "mail":
             return parseMailArgs(argv.slice(1));
+        case "cal":
+            return parseCalArgs(argv.slice(1));
         case "project":
             return parseProjectArgs(argv.slice(1));
         case "search":

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

@@ -0,0 +1,163 @@
+/**
+ * The long-form `cockpit <command> --help` text for the TOWER surfaces —
+ * documents, messages, issues, projects, mail, calendar and search (BLI-3709).
+ *
+ * Split out of `local-help-commands.ts` when that file crossed the 700-line
+ * readability ceiling, and split along the same seam the ARGUMENT parsers
+ * already use (`local-args-tower*.ts`): the collector's own commands — onboard,
+ * sync, backfill, autostart, clean — change for one set of reasons, and the
+ * Tower nouns a person reads and writes through change for another.
+ *
+ * Every string moved verbatim. Help output is what an intern pastes back when
+ * something breaks, so it is a user-visible contract like any other.
+ */
+/** One entry per Tower noun, in the order `cockpit --help` lists them. */
+export const TOWER_COMMAND_HELP = [
+    [
+        "docs",
+        [
+            "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
+            "",
+            "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
+            "list [--parent <id>|root] [--query <text>] [--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).",
+            "  --parent <id> lists the documents filed directly under that document; --parent root lists the top of the tree.",
+            "  --query <text> keeps the documents whose title OR body contains that text, matched case-insensitively in the database — never fuzzy, and the body still never comes back.",
+            "  --limit <n> caps the rows (1-1000). Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
+            "tree — the same documents nested under their parent, for a sidebar-shaped view.",
+            "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
+            "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
+            "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
+            "  --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.",
+            "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.",
+            "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>|send <channel>|thread <id> --channel <channel>] [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).",
+            "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
+            "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>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
+            "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`.",
+            "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
+            "--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, channel_not_found_or_unreadable, content_too_long, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "issue",
+        [
+            "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [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.",
+            "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
+            "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
+            "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
+            "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
+            "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
+            "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
+            "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
+            "--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, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "mail",
+        [
+            "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
+            "",
+            "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
+            "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
+            "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
+            "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+            "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
+            "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
+            "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
+            "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
+            "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
+            "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
+            "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
+            "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
+            "detach <account> — removes the mailbox, its stored mail and its credential.",
+            "--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, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "cal",
+        [
+            'Usage: cockpit cal [today|week|next|find "<words>"|calendars|add-ical|create|share <id>|sync <id>|detach <id>] [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.",
+            "week [--offset 1] — Monday to Sunday. The week starts on Monday here.",
+            "next [--hours 12] — what is coming, from RIGHT NOW rather than from midnight. Defaults to the next 72 hours, so a Friday evening still answers.",
+            'find "<words>" — full text over titles, locations and descriptions. A repeating event is answered with the NEXT time it happens, not its first one in 2024.',
+            "calendars — every calendar, its provider (google_oauth or ical_url), whether it is shared, and when it last synced. The ids other verbs take are on the last line.",
+            "add-ical [--name \"<what to call it>\"] — attaches a personal calendar by its SECRET iCal ADDRESS, read from stdin. There is no flag for it:",
+            '      macOS:      printf "%s" "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"',
+            '      PowerShell: "https://calendar.google.com/calendar/ical/…/basic.ics" | cockpit cal add-ical --name "Personal"',
+            "      Find it at calendar.google.com -> the calendar's Settings -> \"Secret address in iCal format\". Anybody who has that link can read the calendar, which is why it never goes on a command line.",
+            "      A work @buildlaunchiterate.ca calendar does not need this: connect Google in the browser and `cockpit cal calendars` will list them.",
+            'create --calendar <id> --title "<what>" --at <iso> --until <iso> [--location "<where>"] [--attendee a@x,b@y] [--all-day] — creates the event AT GOOGLE, then here. Attendees are invited by Google.',
+            "      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.",
+            "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.",
+            "detach <id> — removes the calendar and its stored events from Tower. The calendar itself is untouched at Google.",
+            "--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, calendar_not_found_or_unreadable, calendar_not_yours, ical_url_invalid, google_oauth_not_configured, write_not_supported_for_provider, and so on.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+    [
+        "project",
+        [
+            "Usage: cockpit project [list] [--archived] [--json]",
+            "",
+            "The projects issues are filed under. Bare `cockpit project` lists them.",
+            "list [--archived] — id, active/archived, name. --archived includes archived projects.",
+            "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.",
+        ],
+    ],
+    [
+        "search",
+        [
+            'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
+            "",
+            "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
+            "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
+            "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
+            "",
+            "The words are positional and do not need quoting unless they contain shell metacharacters:",
+            '`cockpit search storage ceiling` and `cockpit search "storage ceiling"` are the same search.',
+            "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
+            "websearch parser, which shrugs at anything a person can type instead of raising.",
+            "",
+            "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
+            "--limit caps the number of results (default 20, maximum 50).",
+            "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
+            "",
+            "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
+            "own database session, so a document or a channel you cannot open is not in the list.",
+            "",
+            "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
+            "those are different facts and folding them together would let a broken search read as silence.",
+            "A memory result has no page to open; the text printed under it is the whole record.",
+            "",
+            "A refusal keeps Tower's own reason label — needs_rls_client, query_too_short, query_too_long,",
+            "unknown_kind, read_failed.",
+            "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
+        ],
+    ],
+];

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

@@ -1,6 +1,11 @@
 /**
  * The long-form `cockpit <command> --help` text — one entry per command.
  *
+ * The collector's OWN commands live here; the Tower nouns (docs, msg, issue,
+ * project, mail, cal, search) live in `local-help-commands-tower.ts`, split off
+ * by BLI-3709 when this file crossed the same ceiling — along the seam
+ * `local-args-tower*.ts` already draws.
+ *
  * Split out of `local-help.ts` (BLI-3728) when that file crossed the 700-line
  * readability ceiling. The split is by RESPONSIBILITY, not by size: this file
  * is the per-command manual, `local-help.ts` is the command NAME registry plus
@@ -13,8 +18,12 @@
  */
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { localCommandHelp } from "./local-help.js";
+import { TOWER_COMMAND_HELP } from "./local-help-commands-tower.js";
 export function localSubcommandHelp(command) {
     const helpByCommand = new Map([
+        // BLI-3709: the Tower nouns live next door, split along the same seam the
+        // argument parsers already use — see `local-help-commands-tower.ts`.
+        ...TOWER_COMMAND_HELP,
         [
             "onboard",
             [
@@ -544,127 +553,6 @@ export function localSubcommandHelp(command) {
                 "right now.",
             ],
         ],
-        [
-            "docs",
-            [
-                "Usage: cockpit docs [list|tree|read <id|slug>|create|update <id>] [flags]",
-                "",
-                "The Tower document library, typed. Bare `cockpit docs` lists every document you may read.",
-                "list [--parent <id>|root] [--query <text>] [--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).",
-                "  --parent <id> lists the documents filed directly under that document; --parent root lists the top of the tree.",
-                "  --query <text> keeps the documents whose title OR body contains that text, matched case-insensitively in the database — never fuzzy, and the body still never comes back.",
-                "  --limit <n> caps the rows (1-1000). Narrow with these before reading: `cockpit docs list --query onboarding --json` then `cockpit docs read <slug>`.",
-                "tree — the same documents nested under their parent, for a sidebar-shaped view.",
-                "read <id|slug> — one document's title, slug, visibility, and its body. This is the ONLY verb that returns a body.",
-                "create --title \"<title>\" [--parent <id>] [--visibility org|private] [--file <path>|--body-stdin] — the body comes from --file, or stdin (`cat body.md | cockpit docs create --title \"...\"`); neither means an empty body, matching the browser's own default.",
-                "update <id|slug> [--title \"<t>\"] [--visibility org|private] [--parent <id>|--clear-parent] [--file <path>|--body-stdin] [--allow-empty] — only the fields you pass change; a `--parent` change IS a move, there is no separate move verb.",
-                "  --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.",
-                "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.",
-                "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>|send <channel>|thread <id> --channel <channel>] [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).",
-                "create <name> [--private] [--members a@x.test,b@y.test] [--description \"<text>\"] — makes a channel and prints its id. A leading # is fine; --private means membership decides who may read it, and --members names who joins at birth BY EMAIL. An address Tower does not carry refuses the whole create — no half-built channel.",
-                "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>] — the channel's most recent top-level messages, oldest first; --thread <id> reads one thread's replies instead.",
-                "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`.",
-                "thread <id> --channel <channel> — one thread's replies by the parent message's id.",
-                "--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, channel_not_found_or_unreadable, content_too_long, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "issue",
-            [
-                "Usage: cockpit issue [list|show <id>|create|update <id>|move <id> <state>|comment <id>|history <id>] [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.",
-                "show <id> — one issue: title, state, priority, assignee, description, and every comment on it.",
-                "create --title \"<title>\" [--project <name|id>] [--priority 0-4] [--assignee me|<uuid>] [--parent <id>] [--file <path>] — the DESCRIPTION comes from --file or stdin (`cat plan.md | cockpit issue create --title \"...\"`); neither means no description.",
-                "update <id> [--title \"<t>\"] [--priority 0-4] [--assignee me|<uuid>] [--project <name|id>] [--parent <id>] [--file <path>|--body-stdin] — only the fields you pass change. State does NOT move here; use move.",
-                "move <id> <state> — moves an issue and records the move. States: backlog, todo, in_progress, in_review, done, canceled.",
-                "comment <id> — posts a comment. The body is never taken on the command line: `echo \"shipped\" | cockpit issue comment BLI-3654`.",
-                "history <id> [--limit <n>] — every recorded state move and reassignment, oldest first.",
-                "A project may be named instead of id'd; the name is matched exactly (case-insensitively) against `cockpit project list`.",
-                "--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, issue_not_found_or_unreadable, issue_not_writable, invalid_state, comment_too_long, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "mail",
-            [
-                "Usage: cockpit mail [accounts|add-imap|inbox|read <thread>|search \"<words>\"|send|attachment <id>|sync <account>|detach <account>] [flags]",
-                "",
-                "Every mailbox you attached, in one place. One person, several addresses — nothing here has a \"current\" mailbox.",
-                "accounts — every mailbox, its provider (gmail_oauth or imap), its health and when it last synced. The ids other verbs take are on the last line.",
-                "add-imap --address <you@gmail.com> [--name \"<display name>\"] — attaches a personal Google account over IMAP + SMTP. The APP PASSWORD is read from stdin and there is no flag for it:",
-                "      macOS:      printf \"%s\" \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
-                "      PowerShell: \"abcd efgh ijkl mnop\" | cockpit mail add-imap --address you@gmail.com",
-                "      Make one at myaccount.google.com/apppasswords (2-Step Verification has to be on). A work @buildlaunchiterate.ca address connects in the browser instead.",
-                "inbox [--account <id>] [--unread] [--label <l>] [--limit <n>] [--before <iso>] — everything across every mailbox, newest first. * is unread, @ has an attachment.",
-                "read <thread> — one conversation with its bodies. Thread ids come from `cockpit mail inbox --json`.",
-                "search \"<words>\" [--account <id>] [--limit <n>] — full text over subject and body. Quotes and OR work the way they do in a search box.",
-                "send --account <id> --to <a[,b]> [--cc <c>] --subject \"<s>\" [--reply-to <message id>] [--file <path>] — the BODY comes from --file or stdin. --account is required: which address this goes out from is yours to say.",
-                "attachment <id> --out <path> — downloads one attachment to a file. Attachments are pointers until you ask; nothing is stored in Tower.",
-                "sync <account> — reads that mailbox now instead of waiting for the cron. Prints what landed, or the reason it did not.",
-                "detach <account> — removes the mailbox, its stored mail and its credential.",
-                "--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, account_not_found_or_unreadable, account_not_active, google_oauth_not_configured, credential_unavailable, and so on.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
-        [
-            "project",
-            [
-                "Usage: cockpit project [list] [--archived] [--json]",
-                "",
-                "The projects issues are filed under. Bare `cockpit project` lists them.",
-                "list [--archived] — id, active/archived, name. --archived includes archived projects.",
-                "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.",
-            ],
-        ],
-        [
-            "search",
-            [
-                'Usage: cockpit search "<words>" [--kind doc,msg,issue,note,memory] [--limit <n>] [--json]',
-                "",
-                "One bar over five corpora: documents, messages, issues, meeting notes and memory.",
-                "It presses the SAME door the browser's search bar presses (GET /api/search), so what you",
-                "read here is the same row, the same ranking and the same snippet a person sees in Tower.",
-                "",
-                "The words are positional and do not need quoting unless they contain shell metacharacters:",
-                '`cockpit search storage ceiling` and `cockpit search "storage ceiling"` are the same search.',
-                "Quoted phrases and -word work inside the query itself — the query goes to Postgres's",
-                "websearch parser, which shrugs at anything a person can type instead of raising.",
-                "",
-                "--kind narrows to one or more corpora, comma separated. Omit it and all five are searched.",
-                "--limit caps the number of results (default 20, maximum 50).",
-                "--json writes the door's whole answer to stdout, hits, per-kind counts, failures and all.",
-                "",
-                "Every result is scoped by what YOU may read: four of the five corpora are searched on your",
-                "own database session, so a document or a channel you cannot open is not in the list.",
-                "",
-                "A corpus that could not ANSWER gets its own line, separately from \"nothing matched\" —",
-                "those are different facts and folding them together would let a broken search read as silence.",
-                "A memory result has no page to open; the text printed under it is the whole record.",
-                "",
-                "A refusal keeps Tower's own reason label — needs_rls_client, query_too_short, query_too_long,",
-                "unknown_kind, read_failed.",
-                "The command uses the existing paired device identity. Run `cockpit login` first if this machine is not paired.",
-            ],
-        ],
         [
             "release",
             [

package/dist/commands/local-help.js

@@ -46,6 +46,7 @@ export const rootCommandNames = new Set([
     "msg",
     "issue",
     "mail",
+    "cal",
     "project",
     "search",
     "release",
@@ -91,6 +92,7 @@ export function localCommandHelp(command) {
         "  cockpit msg [channels|create <name>|dm <email>|read <channel>|send <channel>|thread <id> --channel <channel>] [--private] [--members a@x,b@y] [--description <text>] [--thread <id>] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit issue [list|show <BLI-id>|create --title <t>|update <BLI-id>|move <BLI-id> <state>|comment <BLI-id>|history <BLI-id>] [--state <s>] [--assignee me|unassigned|<uuid>] [--project <name|id>] [--limit <n>] [--priority 0-4] [--parent <BLI-id>] [--file <path>|--body-stdin] [--dashboard-url <url>] [--json]",
         "  cockpit mail [accounts|add-imap --address <a>|inbox|read <thread>|search \"<words>\"|send --account <id> --to <a> --subject <s>|attachment <id> --out <path>|sync <account>|detach <account>] [--account <id>] [--limit <n>] [--unread] [--label <l>] [--file <path>] [--dashboard-url <url>] [--json]",
+        "  cockpit cal [today|week|next|find \"<words>\"|calendars|add-ical|create --calendar <id> --title <t> --at <iso> --until <iso>|share <id> --org-visible|--private|sync <id> [--full]|detach <id>] [--tz <zone>] [--offset <n>] [--hours <n>] [--from <d> --to <d>] [--calendar <id>] [--limit <n>] [--all] [--dashboard-url <url>] [--json]",
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         "  cockpit search \"<words>\" [--kind doc,msg,issue,note,memory] [--limit <n>] [--dashboard-url <url>] [--json]",
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",

package/dist/commands/local.js

@@ -35,6 +35,7 @@ import { runClean } from "./clean.js";
 import { runDocs } from "./docs.js";
 import { runMsg } from "./msg.js";
 import { runIssue } from "./issue.js";
+import { runCal } from "./cal.js";
 import { runMail } from "./mail.js";
 import { runProject } from "./project.js";
 import { runSearch } from "./search.js";
@@ -143,6 +144,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runMsg(command, io);
             case "issue":
                 return await runIssue(command, io);
+            case "cal":
+                return runCal(command, io);
             case "mail":
                 return await runMail(command, io);
             case "project":

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.67");
+    writeLine(io?.stdout ?? process.stdout, "0.2.69");
     return 0;
   }