@bli-cockpit/cli 0.2.241 → 0.2.243

package/dist/commands/cal-remind.js

@@ -0,0 +1,176 @@
+/**
+ * `cockpit cal remind` - ONE tick of the laptop meeting reminder (BLI-21564, calendar slice 11).
+ *
+ * The OS scheduler runs this every minute (`com.bli.cockpit.remind` / `BLI Cockpit Remind`); there is no
+ * always-on process. Each tick is cheap and bounded:
+ *
+ * 1. Read the local cache `reminders.json` (collector state dir).
+ * 2. Handle every cached reminder whose time has come, BEFORE refreshing. A laptop that slept over the
+ *    boundary wakes with a stale cache, and this order is what lets the 5-minute grace decide `shown`
+ *    versus `missed` instead of the nudge silently vanishing.
+ * 3. Refresh from `/api/cal/reminders/due` at most every 5 minutes when reminders are on, every 15 when off.
+ *
+ * Handling one reminder: claim it (the server answers 409 `already_claimed` when another laptop won), then
+ * show it, then post the outcome. A claim after `start + 5 min` is recorded `missed` and shows nothing.
+ * Nothing here is silent: every branch writes one reason line to stderr (ids and counts, never a title).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { showNotification } from "../notifier.js";
+import { askAgentDoor, emitAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal remind]";
+const GRACE_MS = 5 * 60_000;
+const ENABLED_REFRESH_MS = 5 * 60_000;
+const DISABLED_REFRESH_MS = 15 * 60_000;
+const KEEP_AFTER_START_MS = 30 * 60_000;
+const REQUEST_TIMEOUT_MS = 20_000;
+export function cachePathFor(homeDir) {
+    return path.join(getCollectorRuntimePaths(homeDir).state_dir, "reminders.json");
+}
+function isReminder(value) {
+    const row = value;
+    return !!row && typeof row === "object" && typeof row.event_id === "string" && typeof row.occurrence_start === "string"
+        && Number.isFinite(Date.parse(row.occurrence_start)) && Number.isFinite(Date.parse(row.deliver_at))
+        && typeof row.lead_minutes === "number" && typeof row.title === "string";
+}
+export async function readReminderCache(cachePath, log = () => undefined) {
+    let text;
+    try {
+        text = await fs.readFile(cachePath, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            log(`${TAG} cache unreadable ${JSON.stringify({ reason: "read_failed", code: error.code ?? null })}`);
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!Number.isFinite(Date.parse(parsed.checked_at)) || typeof parsed.settings?.enabled !== "boolean" || !Array.isArray(parsed.reminders))
+            throw new Error("shape");
+        return { ...parsed, reminders: parsed.reminders.filter(isReminder) };
+    }
+    catch {
+        log(`${TAG} cache discarded ${JSON.stringify({ reason: "unparseable" })}`);
+        return null;
+    }
+}
+async function writeReminderCache(cachePath, cache) {
+    await fs.mkdir(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+    const temp = `${cachePath}.${process.pid}.tmp`;
+    await fs.writeFile(temp, JSON.stringify(cache), { mode: 0o600 });
+    await fs.rename(temp, cachePath);
+}
+function bannerText(reminder, now) {
+    const minutes = Math.round((Date.parse(reminder.occurrence_start) - now.getTime()) / 60_000);
+    if (minutes > 0)
+        return `${reminder.title} starts in ${minutes} min`;
+    return minutes === 0 ? `${reminder.title} starts now` : `${reminder.title} started ${-minutes} min ago`;
+}
+export async function remindTick(input) {
+    const log = input.log ?? ((line) => console.error(line));
+    const notify = input.notify ?? ((request) => showNotification(request));
+    const now = input.now;
+    const report = { refreshed: false, refresh_reason: "fresh_enough", enabled: false, due_handled: 0, shown: 0, missed: 0, permission_denied: 0, notifier_failed: 0, claimed_elsewhere: 0, retry_later: 0, cached: 0 };
+    let cache = await readReminderCache(input.cachePath, log);
+    // What this tick already handled, so a refresh that still lists it cannot nudge twice in one run.
+    const handled = new Set();
+    async function handleDue(current) {
+        const keep = [];
+        for (const reminder of current.reminders) {
+            const start = Date.parse(reminder.occurrence_start);
+            if (now.getTime() > start + KEEP_AFTER_START_MS) {
+                log(`${TAG} dropped ${JSON.stringify({ reason: "long_past", lead_minutes: reminder.lead_minutes })}`);
+                continue;
+            }
+            if (Date.parse(reminder.deliver_at) > now.getTime()) {
+                keep.push(reminder);
+                continue;
+            }
+            const handledKey = `${reminder.event_id}|${Date.parse(reminder.occurrence_start)}|${reminder.lead_minutes}`;
+            if (handled.has(handledKey))
+                continue;
+            handled.add(handledKey);
+            report.due_handled += 1;
+            const claim = await input.ask("POST", "/api/cal/reminders/claim", { event_id: reminder.event_id, occurrence_start: reminder.occurrence_start, lead_minutes: reminder.lead_minutes, device_label: input.deviceLabel ?? process.platform });
+            if (!claim.ok) {
+                if (claim.httpStatus === 409 && claim.reason === "already_claimed") {
+                    report.claimed_elsewhere += 1;
+                    log(`${TAG} skipped ${JSON.stringify({ reason: "already_claimed" })}`);
+                    continue;
+                }
+                if (claim.httpStatus === 409) {
+                    current.checked_at = new Date(0).toISOString();
+                    log(`${TAG} skipped ${JSON.stringify({ reason: claim.reason })}`);
+                    continue;
+                }
+                if (claim.httpStatus === 404) {
+                    log(`${TAG} dropped ${JSON.stringify({ reason: claim.reason })}`);
+                    continue;
+                }
+                report.retry_later += 1;
+                keep.push(reminder);
+                log(`${TAG} claim failed, will retry ${JSON.stringify({ reason: claim.reason, http_status: claim.httpStatus ?? null })}`);
+                continue;
+            }
+            let outcome;
+            if (now.getTime() > start + GRACE_MS) {
+                outcome = { outcome: "missed", reason: `late_${Math.round((now.getTime() - start) / 60_000)}m` };
+                report.missed += 1;
+            }
+            else {
+                outcome = await notify({ title: "TOWER", message: bannerText(reminder, now), sound: current.settings.sound });
+                report[outcome.outcome === "shown" ? "shown" : outcome.outcome] += 1;
+            }
+            const posted = await input.ask("POST", "/api/cal/reminders/outcome", { event_id: reminder.event_id, occurrence_start: reminder.occurrence_start, lead_minutes: reminder.lead_minutes, outcome: outcome.outcome, ...(outcome.reason ? { reason: outcome.reason } : {}) });
+            log(`${TAG} ${outcome.outcome} ${JSON.stringify({ reason: outcome.reason, lead_minutes: reminder.lead_minutes, outcome_recorded: posted.ok, ...(posted.ok ? {} : { record_error: posted.reason }) })}`);
+        }
+        current.reminders = keep;
+    }
+    if (cache)
+        await handleDue(cache);
+    const interval = cache?.settings.enabled ? ENABLED_REFRESH_MS : DISABLED_REFRESH_MS;
+    const age = cache ? now.getTime() - Date.parse(cache.checked_at) : Number.POSITIVE_INFINITY;
+    if (!cache || age >= interval || age < 0) {
+        report.refresh_reason = cache ? "interval_elapsed" : "no_cache";
+        const due = await input.ask("GET", "/api/cal/reminders/due?within_minutes=15");
+        if (due.ok) {
+            const body = due.body;
+            cache = { checked_at: now.toISOString(), settings: { enabled: body.settings?.enabled === true, lead_minutes: body.settings?.lead_minutes ?? 10, sound: body.settings?.sound !== false }, reminders: (body.reminders ?? []).filter(isReminder) };
+            report.refreshed = true;
+            await handleDue(cache);
+        }
+        else {
+            report.refresh_reason = `refresh_failed:${due.reason}`;
+            log(`${TAG} refresh failed ${JSON.stringify({ reason: due.reason, http_status: due.httpStatus ?? null, had_cache: cache !== null })}`);
+        }
+    }
+    if (cache) {
+        report.enabled = cache.settings.enabled;
+        report.cached = cache.reminders.length;
+        await writeReminderCache(input.cachePath, cache);
+    }
+    // An idle tick (nothing due, cache still fresh) stays out of the log: the job runs every minute. Anything that
+    // decided something, refreshed, or failed says so.
+    const idle = !report.refreshed && report.due_handled === 0 && report.refresh_reason === "fresh_enough";
+    if (!idle)
+        log(`${TAG} tick ${JSON.stringify(report)}`);
+    return report;
+}
+/** `cockpit cal remind [--json] [--quiet]`: one tick. An unpaired machine says so and exits 0, so the scheduler is not marked failing. */
+export async function runCalRemind(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("cal remind", command, io);
+    }
+    catch (error) {
+        writeLine(io.stderr, `${TAG} skipped ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail: error instanceof Error ? error.message : "no paired session" }));
+        return 0;
+    }
+    const ask = (method, requestPath, body) => askAgentDoor(door, { method, path: requestPath, label: `cal remind ${method}`, timeoutMs: REQUEST_TIMEOUT_MS, ...(body === undefined ? {} : { body }) });
+    const report = await remindTick({ ask, cachePath: cachePathFor(command.homeDir), now: new Date(), log: (line) => writeLine(io.stderr, line) });
+    return command.json ? emitAgentDoor(door, { ok: true, ...report }) : 0;
+}

package/dist/commands/cal-reminders.js

@@ -0,0 +1,33 @@
+/** `cockpit cal reminders [--on|--off] [--lead <min>] [--sound on|off]`, `cal snooze` and `cal dismiss` (BLI-21564): the same doors the web switch uses. */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const TIMEOUT_MS = 30000;
+export async function runCalReminders(command, door) {
+    const patch = command.reminderPatch;
+    const answer = await askAgentDoor(door, patch
+        ? { method: "PATCH", path: "/api/cal/reminders/settings", body: patch, label: "cal reminders", timeoutMs: TIMEOUT_MS }
+        : { method: "GET", path: "/api/cal/reminders/settings", label: "cal reminders", timeoutMs: TIMEOUT_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const settings = answer.body;
+    writeLine(door.io.stdout, `${patch ? "Reminders saved. " : ""}Laptop meeting reminders are ${settings.enabled ? "ON" : "OFF"}: ${settings.lead_minutes} min before, sound ${settings.sound ? "on" : "off"}${settings.saved ? "" : " (defaults, never saved)"}.`);
+    if (!settings.enabled)
+        writeLine(door.io.stdout, "Turn them on with: cockpit cal reminders --on");
+    return 0;
+}
+/** `cal snooze <event id> --occurrence <iso> --minutes 10` and `cal dismiss <event id> --occurrence <iso>`. */
+export async function runCalReminderChange(command, door) {
+    const snooze = command.action === "snooze";
+    const body = { event_id: command.subjectId, occurrence_start: command.occurrenceStart, ...(snooze ? { minutes: command.snoozeMinutes } : {}) };
+    const answer = await askAgentDoor(door, { method: "POST", path: `/api/cal/reminders/${snooze ? "snooze" : "dismiss"}`, body, label: `cal ${command.action}`, timeoutMs: TIMEOUT_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const done = answer.body;
+    writeLine(door.io.stdout, snooze ? `Snoozed until ${done.snoozed_until ?? "later"}.` : "Dismissed: no more reminders for this meeting.");
+    return 0;
+}

package/dist/commands/cal-suggest.js

@@ -0,0 +1,89 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { resolveLabel, readPipedBody } from "./cal-people.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
+const FAIL_TAG = "[cal cli]";
+const REQUEST_TIMEOUT_MS = 60000;
+const DEFAULT_WORDS = { duration_minutes: "30 minutes", hours: "09:00 to 17:00 in your zone", include_weekends: "weekends off" };
+function fitWords(slot) {
+    if (slot.fit === "all_free")
+        return "everyone free";
+    const parts = [];
+    if (slot.soft.length)
+        parts.push(`outside working hours for ${slot.soft.join(", ")}`);
+    if (slot.unconfirmed.length)
+        parts.push(`unknown, not shared with you: ${slot.unconfirmed.join(", ")}`);
+    if (slot.own_unconfirmed)
+        parts.push("your own calendars were not fully read");
+    return parts.join("; ");
+}
+/** `cal suggest` (BLI-21542): ranked common free slots, the same door the web "Find a time" form calls. */
+export async function runCalSuggest(command, door) {
+    let labels = command.peopleWith ?? [];
+    let from = command.from;
+    let to = command.to;
+    let tz = command.timeZone;
+    let account = command.accountName;
+    let duration = command.duration;
+    let hours = command.hoursRange;
+    let weekends = command.weekends;
+    let limit = command.limit;
+    if (!labels.length && !isInteractiveStdin(door.io)) {
+        const piped = await readPipedBody(door);
+        if (piped === null)
+            return failAgentDoor(door, FAIL_TAG, "invalid_body", "Pipe a JSON object like {\"with\":[\"vee@x.ca\"],\"from\":\"2026-10-19\",\"to\":\"2026-10-23\"}, or use --with.");
+        const listed = piped["with"] ?? piped["emails"];
+        labels = Array.isArray(listed) ? listed.filter((v) => typeof v === "string") : [];
+        from ??= typeof piped["from"] === "string" ? piped["from"] : undefined;
+        to ??= typeof piped["to"] === "string" ? piped["to"] : undefined;
+        tz ??= typeof piped["tz"] === "string" ? piped["tz"] : undefined;
+        account ??= typeof piped["account_id"] === "string" ? piped["account_id"] : undefined;
+        duration ??= typeof piped["duration_minutes"] === "number" ? piped["duration_minutes"] : undefined;
+        limit ??= typeof piped["limit"] === "number" ? piped["limit"] : undefined;
+        weekends ??= typeof piped["include_weekends"] === "boolean" ? piped["include_weekends"] : undefined;
+        const h = piped["hours"];
+        if (!hours && h && typeof h.start === "string" && typeof h.end === "string")
+            hours = { start: h.start, end: h.end };
+    }
+    if (!labels.length)
+        return failAgentDoor(door, FAIL_TAG, "invalid_body", "Name who to meet: --with vee@bluepearl.ca (repeat it), or a name as on the team list.");
+    if (!from || !to)
+        return failAgentDoor(door, FAIL_TAG, "invalid_body", "Give the window: --from 2026-10-19 --to 2026-10-23 (a date or an ISO instant).");
+    const emails = [];
+    for (const label of labels) {
+        const resolved = await resolveLabel(door, label);
+        if (!resolved.ok)
+            return resolved.code;
+        emails.push(resolved.email);
+    }
+    const body = {
+        emails: [...new Set(emails)], from, to, tz: tz ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+        ...(account ? { account_id: account } : {}), ...(duration === undefined ? {} : { duration_minutes: duration }),
+        ...(hours ? { hours } : {}), ...(weekends === undefined ? {} : { include_weekends: weekends }), ...(limit === undefined ? {} : { limit }),
+    };
+    const answer = await askAgentDoor(door, { method: "POST", path: "/api/cal/suggestions", body, label: "cal suggest", timeoutMs: REQUEST_TIMEOUT_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, FAIL_TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const result = answer.body;
+    const zone = result.window.time_zone;
+    const out = door.io.stdout;
+    if (!result.slots.length)
+        writeLine(out, "No common free slot in this window. Widen the dates or the hours.");
+    for (const slot of result.slots) {
+        const when = new Intl.DateTimeFormat("en-GB", { timeZone: zone, weekday: "short", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(slot.start));
+        const others = slot.local.map((l) => `${l.email} ${l.start_local.slice(11)} (${l.time_zone})`).join(" · ");
+        writeLine(out, `${when} ${zone} · ${fitWords(slot)}${others ? ` · ${others}` : ""}`);
+        writeLine(out, `  slot: ${slot.id}`);
+    }
+    for (const person of result.people)
+        if (person.status === "unknown")
+            writeLine(out, `${person.email}: unknown (${person.reason ?? "no answer"}). Never shown as free.`);
+    const c = result.coverage;
+    if (result.defaults_used.length)
+        writeLine(out, `Tower defaults used: ${result.defaults_used.map((d) => DEFAULT_WORDS[d] ?? d).join(", ")}`);
+    for (const note of c.notes)
+        writeLine(out, note);
+    writeLine(out, `${c.slots_returned} of ${c.slots_found} slots · ${c.answered} of ${c.requested} answered, ${c.unknown} unknown · ${c.own_calendars_checked} of your calendars checked${c.own_incomplete ? " (incomplete)" : ""} · times in ${zone} · as of ${c.as_of}`);
+    return 0;
+}

package/dist/commands/cal.js

@@ -20,11 +20,20 @@
  *   own zone from `Intl`, because a window computed server-side would be
  *   computed in UTC and "today" would end at 5pm in Vancouver.
  */
-import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
 import { runCalAddIcal, runCalDetach, runCalShare, runCalSync } from "./cal-calendars-write.js";
 import { runCalDetail } from "./cal-detail.js";
+import { runCalJoin } from "./cal-join.js";
+import { runCalContext } from "./cal-links.js";
+import { runCalRemind } from "./cal-remind.js";
+import { runCalReminderChange, runCalReminders } from "./cal-reminders.js";
 import { runCalOverlay } from "./cal-overlay.js";
 import { runCalViewSettings } from "./cal-view-settings.js";
+import { runCalPeople } from "./cal-people.js";
+import { runCalAvailabilityRevoke, runCalAvailabilityShare } from "./cal-availability-share.js";
+import { runCalBookingGuest, runCalBookingPage } from "./cal-booking.js";
+import { BOOKING_GUEST_ACTIONS } from "./local-args-tower-cal-booking.js";
+import { runCalSuggest } from "./cal-suggest.js";
 import { runCalDelete } from "./cal-delete.js";
 import { detailFields, runCalRsvp, scopeFields, writeScopeFacts } from "./cal-scope.js";
 import { runCalDirect } from "./cal-direct.js";
@@ -35,8 +44,28 @@ const TAG = "[cal cli]";
 const READ_DEADLINE_MS = 30_000;
 const WRITE_DEADLINE_MS = 60_000;
 export async function runCal(command, io) {
+    if (BOOKING_GUEST_ACTIONS.includes(command.action))
+        return runCalBookingGuest(command, io);
+    if (command.action === "remind")
+        return runCalRemind(command, io);
     const door = await openAgentDoor("cal", command, io);
     switch (command.action) {
+        case "join":
+            return runCalJoin(command, door);
+        case "links":
+        case "agenda": return runCalContext(command, door);
+        case "reminders":
+            return runCalReminders(command, door);
+        case "snooze":
+        case "dismiss":
+            return runCalReminderChange(command, door);
+        case "booking-page":
+            return runCalBookingPage(command, door);
+        case "booking-slots":
+        case "book":
+        case "booking-change":
+        case "booking-cancel":
+            return runCalBookingGuest(command, io);
         case "event":
         case "export":
             return runCalDetail(command, door);
@@ -50,6 +79,16 @@ export async function runCal(command, io) {
         case "view-settings":
         case "view-settings-change":
             return runCalViewSettings(command, door);
+        case "people":
+        case "availability":
+        case "overlays":
+            return runCalPeople(command, door);
+        case "suggest":
+            return runCalSuggest(command, door);
+        case "availability-share":
+            return runCalAvailabilityShare(command, door);
+        case "availability-revoke":
+            return runCalAvailabilityRevoke(command, door);
         case "today":
         case "week":
         case "next":
@@ -311,6 +350,7 @@ async function create(command, door) {
             ...(command.allDay ? { all_day: true } : {}),
             ...(command.attendees.length > 0 ? { attendees: command.attendees } : {}),
             ...(command.meet ? { meet: true } : {}),
+            ...(command.recheck ? { recheck_availability: true } : {}),
             ...detailFields(command),
             ...(command.idempotencyKey ? { idempotency_key: command.idempotencyKey } : {}),
             ...(command.reason ? { reason: command.reason } : {}),

package/dist/commands/cycle-args.js

@@ -0,0 +1,127 @@
+/**
+ * `cockpit ticket cycles [list|show|create|update|map]` argument parsing (BLI-21809, P12), plus the
+ * `--cycle <ref|none>` field of `ticket create|update`. `cycles` is an `issue` action; its flags are
+ * read here so `local-args-tower-work.ts` only names them, the way `template-args.ts` does.
+ *
+ * A cycle ref is a uuid or an exact, case-insensitive name; two cycles with one name are refused by the
+ * door (`cycle_ref_ambiguous`) with their ids, never guessed.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl } from "./local-arg-values.js";
+export const CYCLE_VALUE_FLAGS = ["--starts", "--ends", "--timezone", "--phase", "--cycle"];
+export const CYCLE_BOOLEAN_FLAGS = ["--close", "--reopen"];
+export const CYCLE_VERBS = ["list", "show", "create", "update", "map"];
+export const CYCLE_PHASES = ["upcoming", "active", "ended", "closed"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+function validDay(flag, value) {
+    if (value === undefined)
+        return undefined;
+    if (!DAY.test(value) || new Date(`${value}T12:00:00Z`).toISOString().slice(0, 10) !== value) {
+        throw new Error(`${flag} must be a calendar date as YYYY-MM-DD.`);
+    }
+    return value;
+}
+export function parseCycleArgs(values, rest) {
+    const first = rest[0];
+    const verb = (first === undefined ? "list" : first);
+    if (!CYCLE_VERBS.includes(verb))
+        throw new Error(`Unknown cycles command: ${first}. Try list, show, create, update or map.`);
+    const positional = rest.slice(first === undefined ? 0 : 1);
+    const needsRef = verb === "show" || verb === "update" || verb === "map";
+    if (needsRef && positional.length !== 1) {
+        throw new Error(`ticket cycles ${verb} takes exactly one ${verb === "map" ? "Linear cycle id" : "cycle id or name"}.`);
+    }
+    if (!needsRef && positional.length > 0)
+        throw new Error(`ticket cycles ${verb} does not take "${positional[0]}".`);
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    const writes = verb === "create" || verb === "update";
+    for (const flag of ["--name", "--description", "--starts", "--ends", "--timezone"]) {
+        if (given(flag) && !writes)
+            throw new Error(`${flag} belongs to \`cockpit ticket cycles create\` and \`update\`.`);
+    }
+    if (verb !== "update" && (given("--close") || given("--reopen") || given("--expected-updated-at"))) {
+        throw new Error("--close, --reopen and --expected-updated-at belong to `cockpit ticket cycles update`.");
+    }
+    if (verb !== "list" && (given("--phase") || given("--limit") || given("--cursor"))) {
+        throw new Error("--phase, --limit and --cursor belong to `cockpit ticket cycles list`.");
+    }
+    if (given("--cycle"))
+        throw new Error("--cycle belongs to `cockpit ticket create` and `update`.");
+    if (given("--request-id") && verb !== "create" && verb !== "update" && verb !== "map") {
+        throw new Error("--request-id belongs to `cockpit ticket cycles create`, `update` and `map`.");
+    }
+    if (given("--close") && given("--reopen"))
+        throw new Error("Give --close or --reopen, not both.");
+    const name = optionalNonEmpty(values.flags.get("--name"));
+    const startsOn = validDay("--starts", optionalNonEmpty(values.flags.get("--starts")));
+    const endsOn = validDay("--ends", optionalNonEmpty(values.flags.get("--ends")));
+    const timezone = optionalNonEmpty(values.flags.get("--timezone"));
+    const rawDescription = values.flags.get("--description");
+    if (verb === "create" && (!name || !startsOn || !endsOn)) {
+        throw new Error('ticket cycles create needs --name "<name>" --starts YYYY-MM-DD --ends YYYY-MM-DD.');
+    }
+    if (startsOn && endsOn && endsOn < startsOn)
+        throw new Error("--ends must not be before --starts.");
+    const phase = optionalNonEmpty(values.flags.get("--phase"));
+    if (phase && !CYCLE_PHASES.includes(phase))
+        throw new Error(`--phase must be one of: ${CYCLE_PHASES.join(", ")}.`);
+    const closing = given("--close") || given("--reopen");
+    const fieldGiven = name !== undefined || rawDescription !== undefined || startsOn !== undefined || endsOn !== undefined || timezone !== undefined;
+    if (verb === "update" && closing && fieldGiven)
+        throw new Error("--close and --reopen travel alone; change the fields in a separate update.");
+    if (verb === "update" && !closing && !fieldGiven) {
+        throw new Error("ticket cycles update needs a field to change: --name, --description, --starts, --ends, --timezone, --close or --reopen.");
+    }
+    const expectedUpdatedAt = optionalNonEmpty(values.flags.get("--expected-updated-at"));
+    if (expectedUpdatedAt && Number.isNaN(Date.parse(expectedUpdatedAt))) {
+        throw new Error("--expected-updated-at must be the updated_at timestamp you last read.");
+    }
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
+    const cursor = optionalNonEmpty(values.flags.get("--cursor"));
+    const cycles = {
+        verb,
+        ...(needsRef ? { ref: positional[0] } : {}),
+        ...(name ? { name } : {}),
+        ...(rawDescription === undefined ? {} : { description: verb === "update" && rawDescription.trim().toLowerCase() === "none" ? null : rawDescription }),
+        ...(startsOn ? { startsOn } : {}),
+        ...(endsOn ? { endsOn } : {}),
+        ...(timezone ? { timezone } : {}),
+        ...(phase ? { phase } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor ? { cursor } : {}),
+        ...(given("--close") ? { closed: true } : given("--reopen") ? { closed: false } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+    };
+    return {
+        kind: "issue",
+        action: "cycles",
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        ...(requestId ? { requestId } : {}),
+        json: values.booleans.has("--json"),
+        cycles,
+    };
+}
+/**
+ * `ticket create|update --cycle <name|id|none>`: `none` clears (update only). Any cycle-only flag on another
+ * ticket verb is refused here, so nothing is silently ignored.
+ */
+export function readCycleField(action, values) {
+    const stray = [...CYCLE_VALUE_FLAGS.filter((f) => f !== "--cycle"), ...CYCLE_BOOLEAN_FLAGS].find((f) => values.flags.has(f) || values.booleans.has(f));
+    if (stray)
+        throw new Error(`${stray} belongs to \`cockpit ticket cycles\`.`);
+    const cycle = optionalNonEmpty(values.flags.get("--cycle"));
+    if (cycle === undefined)
+        return {};
+    if (action !== "create" && action !== "update")
+        throw new Error("--cycle belongs to `cockpit ticket create` and `update`.");
+    if (cycle.toLowerCase() === "none") {
+        if (action === "create")
+            throw new Error("--cycle none clears a cycle on `cockpit ticket update`; leave --cycle off to create without one.");
+        return { cycle: null };
+    }
+    return { cycle };
+}

package/dist/commands/cycles.js

@@ -0,0 +1,117 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { BODY_MAX_CHARS, READ_DEADLINE_MS, WRITE_DEADLINE_MS } from "./issue-contracts.js";
+const TAG = "[ticket cycles cli]";
+const cycleLine = (c) => `${c.id}  ${c.name}  ${c.starts_on} to ${c.ends_on} (${c.timezone})  [${c.phase}${c.linear_cycle_id ? `, imported ${c.linear_cycle_id}` : ""}]`;
+/** Prints the door's refusal with its reason and message (an ambiguous name lists the ids). */
+function refuse(door, answer) {
+    const mutation = answer.body?.mutation;
+    return failAgentDoor(door, TAG, answer.reason, answer.detail, mutation ? { mutation } : {});
+}
+export async function runCycles(command, io, door) {
+    const c = command.cycles;
+    const ref = c.ref ? encodeURIComponent(c.ref) : "";
+    switch (c.verb) {
+        case "list": {
+            const query = new URLSearchParams();
+            if (c.phase)
+                query.set("phase", c.phase);
+            if (c.limit !== undefined)
+                query.set("limit", String(c.limit));
+            if (c.cursor)
+                query.set("cursor", c.cursor);
+            const answer = await askAgentDoor(door, {
+                path: `/api/work/cycles${query.size > 0 ? `?${query}` : ""}`, method: "GET", label: "ticket cycles list", timeoutMs: READ_DEADLINE_MS,
+            });
+            if (!answer.ok)
+                return refuse(door, answer);
+            const body = answer.body;
+            const cycles = body.cycles ?? [];
+            console.error(`${TAG} list done`, JSON.stringify({ returned: cycles.length, has_more: Boolean(body.has_more), phase: c.phase ?? "all" }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            if (cycles.length === 0)
+                writeLine(door.io.stdout, "No cycles here. Create one with `cockpit ticket cycles create --name <n> --starts <day> --ends <day>`.");
+            for (const row of cycles)
+                writeLine(door.io.stdout, cycleLine(row));
+            if (body.coverage)
+                writeLine(door.io.stdout, `\n${body.coverage}`);
+            if (body.has_more && body.next_cursor)
+                writeLine(door.io.stdout, `More cycles: --cursor ${body.next_cursor}`);
+            return 0;
+        }
+        case "show": {
+            const answer = await askAgentDoor(door, { path: `/api/work/cycles/${ref}`, method: "GET", label: "ticket cycles show", timeoutMs: READ_DEADLINE_MS });
+            if (!answer.ok)
+                return refuse(door, answer);
+            const body = answer.body;
+            console.error(`${TAG} show done`, JSON.stringify({ cycle_id: body.cycle.id, members: body.issues?.length ?? 0, phase: body.cycle.phase }));
+            if (door.json)
+                return emitAgentDoor(door, { ok: true, ...body });
+            writeLine(door.io.stdout, cycleLine(body.cycle));
+            if (body.cycle.description)
+                writeLine(door.io.stdout, `\n${body.cycle.description}`);
+            writeLine(door.io.stdout, `\nProgress: ${body.progress?.summary ?? "no progress summary"}`);
+            if (typeof body.imported_unassigned === "number") {
+                const n = body.imported_unassigned;
+                writeLine(door.io.stdout, n === 1 ? "1 imported ticket is not yet in this cycle." : `${n} imported tickets are not yet in this cycle.`);
+            }
+            for (const issue of body.issues ?? [])
+                writeLine(door.io.stdout, `${(issue.identifier ?? "").padEnd(9)}  ${(issue.state ?? "").padEnd(11)}  ${issue.title ?? ""}`);
+            if (body.coverage)
+                writeLine(door.io.stdout, `\n${body.coverage}`);
+            if (body.has_more && body.next_cursor)
+                writeLine(door.io.stdout, `More tickets: the --json answer carries next_cursor ${body.next_cursor}.`);
+            return 0;
+        }
+        case "map":
+            return write(command, door, { path: "/api/work/cycles/map", method: "POST", body: { ...(command.requestId ? { request_id: command.requestId } : {}), linear_cycle_id: c.ref } });
+        case "create":
+        case "update": {
+            const description = await readDescription(c.description, io);
+            if (!description.ok)
+                return failAgentDoor(door, TAG, "invalid_body", description.detail);
+            const payload = {
+                ...(command.requestId ? { request_id: command.requestId } : {}),
+                ...(c.verb === "update" && c.expectedUpdatedAt ? { expected_updated_at: c.expectedUpdatedAt } : {}),
+                ...(c.name === undefined ? {} : { name: c.name }),
+                ...(description.text === undefined ? {} : { description: description.text }),
+                ...(c.startsOn === undefined ? {} : { starts_on: c.startsOn }),
+                ...(c.endsOn === undefined ? {} : { ends_on: c.endsOn }),
+                ...(c.timezone === undefined ? {} : { timezone: c.timezone }),
+                ...(c.closed === undefined ? {} : { closed: c.closed }),
+            };
+            return write(command, door, c.verb === "create"
+                ? { path: "/api/work/cycles", method: "POST", body: payload }
+                : { path: `/api/work/cycles/${ref}`, method: "PATCH", body: payload });
+        }
+    }
+}
+/** `--description -` reads the text from stdin; anything else is the text itself. */
+async function readDescription(value, io) {
+    if (value !== "-")
+        return { ok: true, text: value };
+    if (isInteractiveStdin(io))
+        return { ok: false, detail: "--description - reads the text from stdin, and nothing is piped in." };
+    try {
+        return { ok: true, text: await readPipedText(io.stdin, { maxChars: BODY_MAX_CHARS, overflowMessage: `A cycle description is limited to ${BODY_MAX_CHARS} characters.` }) };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function write(command, door, req) {
+    const verb = command.cycles.verb;
+    const answer = await askAgentDoor(door, { ...req, label: `ticket cycles ${verb}`, timeoutMs: WRITE_DEADLINE_MS });
+    if (!answer.ok)
+        return refuse(door, answer);
+    const body = answer.body;
+    console.error(`${TAG} ${verb} done`, JSON.stringify({ cycle_id: body.cycle.id, phase: body.cycle.phase, already_mapped: Boolean(body.already_mapped) }));
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, ...body });
+    const label = verb === "create" ? "Created" : verb === "map" ? (body.already_mapped ? "Already mapped" : "Mapped") : command.cycles.closed === true ? "Closed" : command.cycles.closed === false ? "Reopened" : "Updated";
+    writeLine(door.io.stdout, `${label}: ${cycleLine(body.cycle)}`);
+    if (verb === "map")
+        writeLine(door.io.stdout, "Mapping links the cycles; no ticket was moved.");
+    return 0;
+}