@bli-cockpit/cli 0.2.241 → 0.2.243

package/dist/commands/autostart-heal.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { appendFile } from "node:fs/promises";
-import { AUTOSTART_LABEL, autostartStatus, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
+import { AUTOSTART_LABEL, autostartStatus, REMIND_AUTOSTART_LABEL, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
 import { isAutostartOptedOut } from "../autostart-opt-out.js";
+import { writeDarwinRemindPlist } from "../autostart-remind.js";
 import { redactedHealthDetail } from "../health-detail.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -110,6 +111,33 @@ async function writeAndVerifyRegistration(command, exec, platform, roots, before
             detail: redactedHealthDetail(reregistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
         };
     }
+    // BLI-21564: the reminder job is healed with the sync agent, by the same two steps.
+    let remindPlist;
+    try {
+        remindPlist = await writeDarwinRemindPlist({
+            homeDir: command.homeDir,
+            repoRoot: roots[0],
+            repoRoots: roots,
+            dashboardUrl: command.dashboardUrl,
+            exec,
+            platform,
+        });
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            reason: "remind_plist_write_failed",
+            detail: redactedHealthDetail(error instanceof Error ? error.message : String(error)).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    const remindRegistered = await reregisterDarwinAgent({ exec, plistPath: remindPlist.plist_path, label: REMIND_AUTOSTART_LABEL });
+    if (!remindRegistered.ok) {
+        return {
+            status: "fail",
+            reason: `remind_${remindRegistered.reason}`,
+            detail: redactedHealthDetail(remindRegistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
+        };
+    }
     return verifyRegistration(command, exec, platform, roots, beforeStatus, written.node_path_reason);
 }
 async function verifyRegistration(command, exec, platform, roots, beforeStatus, nodePathReason) {
@@ -124,6 +152,13 @@ async function verifyRegistration(command, exec, platform, roots, beforeStatus,
         exec,
         platform,
     });
+    if (after.status === "loaded" && after.remind && after.remind.status !== "loaded") {
+        return {
+            status: "fail",
+            reason: "remind_reregistered_but_still_broken",
+            detail: redactedHealthDetail(after.remind.message ?? after.remind.status).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
     if (after.status !== "loaded") {
         return {
             status: "fail",

package/dist/commands/brain.js

@@ -62,7 +62,7 @@ export async function runBrain(command, io) {
     if (!answer.ok)
         return failAgentDoor(door, TAG, answer.reason, answer.detail);
     const body = answer.body;
-    writeLine(io.stderr, `${TAG} status read ${JSON.stringify({ projects: body.projects.length, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end })}`);
+    writeLine(io.stderr, `${TAG} status read ${JSON.stringify({ projects: body.projects.length, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end, shown: body.projects.map((p) => ({ project: p.project, listed: p.incidents?.length ?? 0, ...p.incidents_coverage })) })}`);
     if (command.json)
         return emitAgentDoor(door, body);
     writeLine(io.stdout, body.text);

package/dist/commands/cal-agenda.js

@@ -0,0 +1,44 @@
+/**
+ * `cockpit cal agenda [--from <d> --to <d>] [--tz <IANA>]` (BLI-21588): events plus tickets due in the window.
+ * `DUE` lines are all-day date markers, not meetings: they never block time. Coverage of both reads is printed.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const dateIn = (instant, zone) => new Intl.DateTimeFormat("en-CA", { timeZone: zone }).format(new Date(instant));
+const clock = (instant, zone) => new Intl.DateTimeFormat("en-GB", { timeZone: zone, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(instant));
+/** Lines grouped by day: events by time, then `DUE` markers. */
+export function agendaLines(body) {
+    const zone = body.window.time_zone;
+    const days = new Map();
+    const add = (day, line) => { days.set(day, [...(days.get(day) ?? []), line]); };
+    for (const event of body.events) {
+        const when = event.all_day ? "all day" : `${clock(event.starts_at, zone)}-${clock(event.ends_at, zone)}`;
+        add(event.all_day ? event.starts_at.slice(0, 10) : dateIn(event.starts_at, zone), `  ${when.padEnd(11)}  ${event.title}`);
+    }
+    for (const due of body.due)
+        add(due.date, `  DUE          ${due.identifier} ${due.title} (${due.state})`);
+    const lines = [];
+    for (const day of [...days.keys()].sort())
+        lines.push(day, ...days.get(day));
+    const c = body.coverage;
+    if (lines.length === 0)
+        lines.push("Nothing on the calendar or due in this window.");
+    lines.push("", `${body.events.length} event(s) from ${c.events.calendars} calendar(s)${c.events.truncated ? " (more than fitted)" : ""}; ${c.due.unique} ticket(s) due (${c.due.returned} of ${c.due.requested} requested rows read${c.due.complete ? ", complete" : `, INCOMPLETE: ${c.due.reason}`}).`);
+    return lines;
+}
+export async function runCalAgenda(command, door) {
+    const query = new URLSearchParams({ tz: command.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone });
+    if (command.from)
+        query.set("from", command.from);
+    if (command.to)
+        query.set("to", command.to);
+    const answer = await askAgentDoor(door, { method: "GET", path: `/api/cal/agenda?${query}`, label: "cal agenda", timeoutMs: 30000 });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    for (const line of agendaLines(answer.body))
+        writeLine(door.io.stdout, line);
+    return 0;
+}

package/dist/commands/cal-availability-share.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { readPipedBody } from "./cal-people.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
+const FAIL_TAG = "[cal cli]";
+const REQUEST_TIMEOUT_MS = 60000;
+const DOOR = "/api/cal/availability-shares";
+const shareLine = (s) => `${s.id}  ${s.status}  ${s.label ?? "(no label)"}  ${s.duration_minutes} min ${s.time_zone}  opens ${s.open_count}  expires ${s.expires_at}${s.single_use ? "  single-use" : ""}`;
+/** `cal availability-share` (BLI-21548): free time as text, a revocable link, a list, or a change. The same doors the web box calls. */
+export async function runCalAvailabilityShare(command, door) {
+    const out = door.io.stdout;
+    if (command.shareMode === "list") {
+        const answer = await askAgentDoor(door, { method: "GET", path: DOOR, label: "cal availability-share --list", 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 { shares } = answer.body;
+        if (!shares.length)
+            writeLine(out, "No availability links yet.");
+        for (const share of shares)
+            writeLine(out, shareLine(share));
+        return 0;
+    }
+    if (command.shareMode === "change") {
+        const body = {
+            ...(command.shareExpires ? { expires_at: command.shareExpires } : {}), ...(command.shareLabel ? { label: command.shareLabel } : {}),
+            ...(command.location ? { location: command.location } : {}), ...(command.meet ? { conference: "google_meet" } : {}),
+        };
+        if (!Object.keys(body).length)
+            return failAgentDoor(door, FAIL_TAG, "invalid_body", "Change at least one of --expires, --label, --location or --meet.");
+        const answer = await askAgentDoor(door, { method: "PATCH", path: `${DOOR}/${encodeURIComponent(command.shareId ?? "")}`, body, label: "cal availability-share --id", timeoutMs: REQUEST_TIMEOUT_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, FAIL_TAG, answer.reason, answer.detail);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        writeLine(out, `Changed: ${shareLine(answer.body.share)}`);
+        return 0;
+    }
+    let ranges = (command.shareRanges ?? []).map((range) => ({ start: range.split("/")[0].trim(), end: range.split("/")[1].trim() }));
+    const piped = {};
+    if (!ranges.length && !isInteractiveStdin(door.io)) {
+        const body = await readPipedBody(door);
+        if (body === null)
+            return failAgentDoor(door, FAIL_TAG, "invalid_body", "Pipe a JSON object like {\"ranges\":[{\"start\":\"2026-10-20T10:00\",\"end\":\"2026-10-20T17:00\"}]}, or use --range <start>/<end>.");
+        Object.assign(piped, body);
+        if (Array.isArray(body["ranges"]))
+            ranges = body["ranges"].filter((r) => Boolean(r) && typeof r.start === "string" && typeof r.end === "string");
+    }
+    if (!ranges.length)
+        return failAgentDoor(door, FAIL_TAG, "invalid_body", "Give at least one --range <start>/<end>, like 2026-10-20T10:00/2026-10-20T17:00.");
+    const link = command.shareMode === "link" || piped["mode"] === "link";
+    const pick = (flag, key, type) => flag ?? (typeof piped[key] === type ? piped[key] : undefined);
+    const duration = pick(command.duration, "duration_minutes", "number");
+    const expires = pick(command.shareExpires, "expires_at", "string");
+    const location = pick(command.location, "location", "string");
+    const label = pick(command.shareLabel, "label", "string");
+    const conference = command.meet ? "google_meet" : pick(undefined, "conference", "string");
+    const body = {
+        mode: link ? "link" : "text", ranges, time_zone: command.timeZone ?? pick(undefined, "time_zone", "string") ?? pick(undefined, "tz", "string") ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+        ...(duration === undefined ? {} : { duration_minutes: duration }), ...(expires ? { expires_at: expires } : {}), ...(location ? { location } : {}), ...(conference ? { conference } : {}),
+        ...(command.singleUse || piped["single_use"] === true ? { single_use: true } : {}),
+        ...(command.allowConflicts ? { avoid_conflicts: false } : typeof piped["avoid_conflicts"] === "boolean" ? { avoid_conflicts: piped["avoid_conflicts"] } : {}),
+        ...(label ? { label } : {}),
+        ...(link ? { request_key: command.idempotencyKey ?? (typeof piped["request_key"] === "string" ? piped["request_key"] : randomUUID()) } : {}),
+    };
+    const answer = await askAgentDoor(door, { method: "POST", path: DOOR, body, label: "cal availability-share", 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;
+    writeLine(out, result.text);
+    if (link) {
+        if (result.token)
+            writeLine(out, `\nLink (shown once, ${result.token_rotated ? "new token for your repeat request" : "copy it now"}): ${result.url}\nId: ${result.share.id}  expires ${result.share.expires_at}${result.share.single_use ? "  single-use (enforced when booking arrives)" : ""}`);
+        else
+            writeLine(out, `\nNo new link: ${result.reason === "link_revoked" ? "that one was revoked" : "that link was already opened, so its token is not shown again"}. Id: ${result.share.id}`);
+    }
+    else
+        writeLine(out, "\nCopy the text above; nothing was saved or sent.");
+    if (result.coverage.own_incomplete)
+        writeLine(out, "Your own calendars were not fully read, so these times are not confirmed free.");
+    if (result.defaults_used.length)
+        writeLine(out, `Tower defaults used: ${result.defaults_used.map((d) => (d === "duration_minutes" ? "30 minutes" : "skip your busy time")).join(", ")}`);
+    return 0;
+}
+/** `cal availability-revoke <id>`: turn a link off. */
+export async function runCalAvailabilityRevoke(command, door) {
+    const answer = await askAgentDoor(door, { method: "DELETE", path: `${DOOR}/${encodeURIComponent(command.subjectId ?? "")}`, label: "cal availability-revoke", timeoutMs: REQUEST_TIMEOUT_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, FAIL_TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    writeLine(door.io.stdout, `Revoked: ${shareLine(answer.body.share)}`);
+    return 0;
+}

package/dist/commands/cal-booking.js

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { readPipedBody } from "./cal-people.js";
+import { isInteractiveStdin, writeLine } from "./cli-io.js";
+import { parseWeekly } from "./local-args-tower-cal-booking.js";
+import { DEFAULT_DASHBOARD_URL } from "../local-state-config.js";
+const FAIL_TAG = "[cal cli]";
+const REQUEST_TIMEOUT_MS = 60000;
+const PAGES = "/api/cal/booking-pages";
+const pageLine = (p) => `${p.id}  ${p.status}  ${p.title}  ${p.duration_minutes} min ${p.time_zone}  next ${p.window_days} days  ${p.mode === "single_use" ? "single-use" : "reusable"}`;
+/** Flags into the page body. Names match the door's body; a flag the person did not give is left out. */
+function pageBody(command, piped) {
+    const weekly = (command.bookingWeekly ?? []).flatMap((raw) => parseWeekly(raw) ?? []);
+    const flags = {
+        ...(command.title ? { title: command.title } : {}), ...(command.timeZone ? { time_zone: command.timeZone } : {}),
+        ...(weekly.length ? { weekly_ranges: weekly } : {}), ...(command.duration === undefined ? {} : { duration_minutes: command.duration }),
+        ...(command.bufferBefore === undefined ? {} : { buffer_before_minutes: command.bufferBefore }), ...(command.bufferAfter === undefined ? {} : { buffer_after_minutes: command.bufferAfter }),
+        ...(command.minNotice === undefined ? {} : { min_notice_minutes: command.minNotice }), ...(command.windowDays === undefined ? {} : { window_days: command.windowDays }),
+        ...(command.meet ? { conference: "google_meet" } : {}), ...(command.location ? { location: command.location } : {}),
+        ...(command.singleUse ? { mode: "single_use" } : {}), ...(command.calendarId ? { calendar_id: command.calendarId } : {}), ...(command.accountName ? { account_name: command.accountName } : {}),
+    };
+    return { ...piped, ...flags };
+}
+/** `cal booking-page` (BLI-21556): create, list, edit, rotate, close or reopen a public booking page. The same doors the web page calls. */
+export async function runCalBookingPage(command, door) {
+    const out = door.io.stdout;
+    if (command.bookingMode === "list") {
+        const answer = await askAgentDoor(door, { method: "GET", path: PAGES, label: "cal booking-page --list", 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 { pages } = answer.body;
+        if (!pages.length)
+            writeLine(out, "No booking pages yet.");
+        for (const page of pages) {
+            writeLine(out, pageLine(page));
+            for (const r of page.upcoming ?? [])
+                writeLine(out, `    ${r.slot_start}  ${r.guest_name}  ${r.status}`);
+        }
+        return 0;
+    }
+    let piped = {};
+    if (!isInteractiveStdin(door.io) && !command.bookingWeekly?.length && command.bookingMode === "create") {
+        const body = await readPipedBody(door);
+        if (body === null)
+            return failAgentDoor(door, FAIL_TAG, "invalid_body", "Pipe a JSON object like {\"title\":\"Office hours\",\"time_zone\":\"America/Toronto\",\"weekly_ranges\":[{\"weekday\":1,\"start\":\"09:00\",\"end\":\"12:00\"}]}, or use --title and --weekly.");
+        piped = body;
+    }
+    const body = pageBody(command, piped);
+    const change = command.bookingMode === "change";
+    if (change) {
+        if (command.rotate)
+            body["rotate_link"] = true;
+        if (command.bookingClosed !== undefined)
+            body["closed"] = command.bookingClosed;
+        delete body["calendar_id"];
+        delete body["account_name"];
+        const answer = await askAgentDoor(door, { method: "PATCH", path: `${PAGES}/${encodeURIComponent(command.bookingId ?? "")}`, body, label: "cal booking-page --id", timeoutMs: REQUEST_TIMEOUT_MS });
+        return printPage(answer, door, "Changed");
+    }
+    if (!body["title"] || !body["weekly_ranges"])
+        return failAgentDoor(door, FAIL_TAG, "invalid_body", "A booking page needs --title \"<name>\" and at least one --weekly <day>/<HH:MM>-<HH:MM>, like mon/09:00-12:00.");
+    body["time_zone"] ??= Intl.DateTimeFormat().resolvedOptions().timeZone;
+    body["request_key"] = command.idempotencyKey ?? (typeof piped["request_key"] === "string" ? piped["request_key"] : randomUUID());
+    return printPage(await askAgentDoor(door, { method: "POST", path: PAGES, body, label: "cal booking-page", timeoutMs: REQUEST_TIMEOUT_MS }), door, "Created");
+}
+function printPage(answer, door, verb) {
+    if (!answer.ok)
+        return failAgentDoor(door, FAIL_TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const result = answer.body;
+    writeLine(door.io.stdout, `${verb}: ${pageLine(result.page)}`);
+    if (result.token)
+        writeLine(door.io.stdout, `Link (shown once, ${result.token_rotated ? "new token" : "copy it now"}): ${result.url}`);
+    else if (result.reason)
+        writeLine(door.io.stdout, `No new link: ${result.reason === "link_revoked" ? "that page was turned off" : "that page was already opened, so its token is not shown again"}.`);
+    return 0;
+}
+/** A pasted link or a bare token -> the token and the Tower it belongs to. */
+export function readBookingTarget(raw, dashboardUrl) {
+    const text = raw.trim();
+    if (/^https?:\/\//i.test(text)) {
+        const url = new URL(text);
+        const parts = url.pathname.split("/").filter(Boolean);
+        const at = parts.findIndex((part) => part === "booking" || part === "booking-reservations");
+        return { token: parts[at >= 0 ? at + 1 : parts.length - 1] ?? "", dashboardUrl: url.origin };
+    }
+    return { token: text, dashboardUrl: dashboardUrl ?? DEFAULT_DASHBOARD_URL };
+}
+const when = (r) => `${r.start} to ${r.end}`;
+/** The guest verbs. They need no paired session: the link or token in the path is the credential. */
+export async function runCalBookingGuest(command, io) {
+    const target = readBookingTarget(command.subjectId ?? "", command.dashboardUrl);
+    const door = { dashboardUrl: target.dashboardUrl, deviceToken: "", io, json: command.json, homeDir: command.homeDir };
+    const token = encodeURIComponent(target.token);
+    const out = io.stdout;
+    const fail = (a) => failAgentDoor(door, FAIL_TAG, a.reason, a.detail);
+    if (command.action === "booking-slots") {
+        const answer = await askAgentDoor(door, { method: "GET", path: `/api/cal/booking/${token}/slots`, label: "cal booking-slots", timeoutMs: REQUEST_TIMEOUT_MS });
+        if (!answer.ok)
+            return fail(answer);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        const page = answer.body;
+        writeLine(out, `${page.title}: ${page.duration_minutes} minutes, times in ${page.time_zone}${page.location ? `, ${page.location}` : page.conference === "google_meet" ? ", Google Meet" : ""}`);
+        if (!page.slots.length)
+            writeLine(out, "No times are open right now.");
+        for (const slot of page.slots)
+            writeLine(out, when(slot));
+        if (page.coverage.own_incomplete)
+            writeLine(out, "The host's calendar could not be fully read, so a time may turn out to be taken.");
+        return 0;
+    }
+    if (command.action === "book") {
+        const body = { start: command.bookingStart, guest_name: command.name, guest_email: command.guestEmail, ...(command.guestNote ? { note: command.guestNote } : {}), request_key: command.idempotencyKey ?? randomUUID() };
+        const answer = await askAgentDoor(door, { method: "POST", path: `/api/cal/booking/${token}/reservations`, body, label: "cal book", timeoutMs: REQUEST_TIMEOUT_MS });
+        if (!answer.ok)
+            return fail(answer);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        const result = answer.body;
+        writeLine(out, `Booked: ${result.reservation.title}, ${when(result.reservation)} (${result.reservation.time_zone}). An invitation is on its way.`);
+        writeLine(out, result.manage_url ? `Keep this link to change or cancel (shown once, stops working when the meeting starts): ${result.manage_url}` : "Your booking link could not be shown again. Ask the host if you need to change it.");
+        return 0;
+    }
+    if (command.action === "booking-change") {
+        const body = { start: command.bookingStart, request_key: command.idempotencyKey ?? randomUUID() };
+        const answer = await askAgentDoor(door, { method: "PATCH", path: `/api/cal/booking-reservations/${token}`, body, label: "cal booking-change", timeoutMs: REQUEST_TIMEOUT_MS });
+        if (!answer.ok)
+            return fail(answer);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        const result = answer.body;
+        writeLine(out, `Moved to ${when(result.reservation)} (${result.reservation.time_zone}). The old link no longer works. New link (shown once): ${result.manage_url}`);
+        return 0;
+    }
+    const answer = await askAgentDoor(door, { method: "DELETE", path: `/api/cal/booking-reservations/${token}`, label: "cal booking-cancel", timeoutMs: REQUEST_TIMEOUT_MS });
+    if (!answer.ok)
+        return fail(answer);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const result = answer.body;
+    writeLine(out, `Cancelled: ${result.reservation.title}, ${when(result.reservation)}.${result.changed_outside_tower ? " The host's calendar had already dropped the event." : ""}`);
+    return 0;
+}

package/dist/commands/cal-join.js

@@ -0,0 +1,62 @@
+/**
+ * `cockpit cal join [--event <id> --occurrence <iso>] [--print]` (BLI-21564): open the meeting link.
+ *
+ * With no event it picks the meeting running now or starting within 15 minutes from `/api/cal/next` (which already
+ * drops cancelled and declined meetings). The link must be an `https:` address with no credentials - the same test
+ * as the web Join button (`calendarHttpsLink`) - and a missing or unsafe link is refused by name, never opened.
+ * `--print` only prints it. Opening is best effort (`browser-open.ts`); the link is printed either way.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { openInBrowser } from "./browser-open.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+export const JOIN_LOOKAHEAD_MS = 15 * 60_000;
+/** The same rule as `calendarHttpsLink` on the dashboard: https only, no user or password. */
+export function httpsJoinLink(value) {
+    try {
+        const url = new URL(value ?? "");
+        return url.protocol === "https:" && !url.username && !url.password ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Running now, or starting within 15 minutes; the first one with a link wins, else the first one (to be refused by name). */
+export function pickJoinCandidate(events, now) {
+    const near = events.filter(event => !event.all_day && event.status !== "cancelled"
+        && Date.parse(event.starts_at) <= now + JOIN_LOOKAHEAD_MS && Date.parse(event.ends_at) > now);
+    return near.find(event => httpsJoinLink(event.meeting_url) !== null) ?? near[0] ?? null;
+}
+export async function runCalJoin(command, door, now = Date.now) {
+    const zone = command.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+    let meeting;
+    if (command.remindEvent) {
+        const query = new URLSearchParams({ tz: zone, occurrence_start: command.occurrenceStart ?? "" });
+        const answer = await askAgentDoor(door, { method: "GET", path: `/api/cal/events/${encodeURIComponent(command.remindEvent)}?${query}`, label: "cal join", timeoutMs: 30000 });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        meeting = answer.body.event;
+    }
+    else {
+        const answer = await askAgentDoor(door, { method: "GET", path: `/api/cal/next?${new URLSearchParams({ tz: zone, hours: "2" })}`, label: "cal join", timeoutMs: 30000 });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        meeting = pickJoinCandidate(answer.body.events ?? [], now());
+        if (!meeting)
+            return failAgentDoor(door, TAG, "nothing_to_join", "No meeting is running or starts in the next 15 minutes.");
+    }
+    if (!meeting.meeting_url)
+        return failAgentDoor(door, TAG, "no_join_link", `"${meeting.title}" has no join link on its calendar entry.`, { event_id: meeting.event_id });
+    const link = httpsJoinLink(meeting.meeting_url);
+    if (!link)
+        return failAgentDoor(door, TAG, "link_not_https", `"${meeting.title}" has a join link that is not a plain https address, so it was not opened.`, { event_id: meeting.event_id });
+    const opened = command.printOnly ? null : openInBrowser(link);
+    console.error(`${TAG} join`, JSON.stringify({ event_id: meeting.event_id, kind: meeting.meeting_kind, print_only: command.printOnly === true, open: opened ? opened.reason : "not_attempted" }));
+    if (door.json) {
+        return emitAgentDoor(door, { ok: true, event_id: meeting.event_id, title: meeting.title, starts_at: meeting.starts_at, join_url: link, join_kind: meeting.meeting_kind, opened: opened?.ok === true, open_reason: opened ? opened.reason : "print_only" });
+    }
+    writeLine(door.io.stdout, link);
+    if (opened && !opened.ok)
+        writeLine(door.io.stderr, opened.detail);
+    return 0;
+}

package/dist/commands/cal-links.js

@@ -0,0 +1,68 @@
+/**
+ * `cockpit cal links <event id> [--occurrence <iso>] [--add doc:<id>|note:<id> [--series]] [--remove <link id>]`
+ * (BLI-21588): the same doors the web event panel uses. A link is yours alone and gives nobody any access; a target you
+ * can no longer open prints as unavailable with no title.
+ */
+import { runCalAgenda } from "./cal-agenda.js";
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[cal cli]";
+const TIMEOUT_MS = 30000;
+/** One line: the link id, the kind, the title (or "unavailable"), where it opens, and a note's recording facts. */
+export function linkLine(row) {
+    const id = row.link_id ? `${row.link_id}  ` : "";
+    const scope = row.scope === "series" ? "series  " : "";
+    if (row.state === "unavailable")
+        return `${id}${scope}${row.kind.toUpperCase().padEnd(4)}  unavailable (${row.id}): you can no longer open it`;
+    const facts = row.kind === "note" ? `  [${row.status}; ${row.recordings} recording(s), ${row.alternates} alternate, ${row.missed} missed]` : "";
+    return `${id}${scope}${row.kind.toUpperCase().padEnd(4)}  ${row.title}  ${row.href}${facts}`;
+}
+export async function runCalLinks(command, door) {
+    const base = `/api/cal/events/${encodeURIComponent(command.subjectId)}/links`;
+    if (command.linkRemove) {
+        const answer = await askAgentDoor(door, { method: "DELETE", path: `${base}/${encodeURIComponent(command.linkRemove)}`, label: "cal links", timeoutMs: TIMEOUT_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        writeLine(door.io.stdout, `Removed link ${command.linkRemove}. The history keeps it.`);
+        return 0;
+    }
+    if (command.linkAdd) {
+        const body = {
+            target_kind: command.linkAdd.kind, target_id: command.linkAdd.id,
+            scope: command.linkSeries ? "series" : "occurrence",
+            ...(command.linkSeries ? {} : { occurrence_start: command.occurrenceStart }),
+        };
+        const answer = await askAgentDoor(door, { method: "POST", path: base, body, label: "cal links", timeoutMs: TIMEOUT_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        if (door.json)
+            return emitAgentDoor(door, answer.body);
+        writeLine(door.io.stdout, `Linked: ${linkLine(answer.body.link)}`);
+        return 0;
+    }
+    const query = new URLSearchParams();
+    if (command.occurrenceStart)
+        query.set("occurrence_start", command.occurrenceStart);
+    const answer = await askAgentDoor(door, { method: "GET", path: `${base}?${query}`, label: "cal links", timeoutMs: TIMEOUT_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    if (door.json)
+        return emitAgentDoor(door, answer.body);
+    const list = answer.body;
+    if (list.links.length === 0)
+        writeLine(door.io.stdout, "No links on this event yet. Add one with: cockpit cal links <event id> --add doc:<id> --occurrence <iso>");
+    for (const row of list.links)
+        writeLine(door.io.stdout, linkLine(row));
+    for (const suggestion of list.suggestions) {
+        writeLine(door.io.stdout, `Suggested (${suggestion.reason}): ${linkLine(suggestion.target)}  -> attach with --add note:${suggestion.target.id}`);
+    }
+    if (list.suggestions_read === false)
+        writeLine(door.io.stdout, "Suggestions could not be read just now.");
+    return 0;
+}
+/** `links` and `agenda` share one routing line in `cal.ts`, which is at its size ceiling. */
+export function runCalContext(command, door) {
+    return command.action === "agenda" ? runCalAgenda(command, door) : runCalLinks(command, door);
+}

package/dist/commands/cal-people.js

@@ -0,0 +1,136 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor } from "./agent-door.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const FAIL_TAG = "[cal cli]";
+const REQUEST_TIMEOUT_MS = 30000;
+/** `cal people`, `cal availability` and `cal overlays` (BLI-21522): the same doors the browser's People box uses. */
+export async function runCalPeople(command, door) {
+    if (command.action === "people")
+        return people(command, door);
+    if (command.action === "availability")
+        return availability(command, door);
+    return overlays(command, door);
+}
+async function search(door, label) {
+    const answer = await askAgentDoor(door, { method: "GET", path: `/api/cal/people?q=${encodeURIComponent(label)}`, label: "cal people", timeoutMs: REQUEST_TIMEOUT_MS });
+    if (!answer.ok)
+        return { ok: false, code: failAgentDoor(door, FAIL_TAG, answer.reason, answer.detail) };
+    return { ok: true, people: answer.body.people ?? [] };
+}
+async function people(command, door) {
+    const found = await search(door, command.query ?? "");
+    if (!found.ok)
+        return found.code;
+    if (door.json)
+        return emitAgentDoor(door, { query: command.query, people: found.people });
+    if (!found.people.length)
+        writeLine(door.io.stdout, `Nobody on the team list is exactly "${command.query}". Names must match exactly; an email address works too.`);
+    for (const person of found.people)
+        writeLine(door.io.stdout, `${person.display_name} <${person.email}>${person.kind === "email" ? " (not on the team list)" : ""}`);
+    return 0;
+}
+/** One label to one exact address, or a named failure. Ambiguity is never guessed. */
+export async function resolveLabel(door, label) {
+    const found = await search(door, label);
+    if (!found.ok)
+        return found;
+    if (found.people.length === 1)
+        return { ok: true, email: found.people[0].email };
+    const detail = found.people.length === 0
+        ? `Nobody on the team list is exactly "${label}". Use their full name as listed, or an email address.`
+        : `"${label}" fits more than one person (${found.people.map((p) => p.email).join(", ")}). Use an email address.`;
+    return { ok: false, code: failAgentDoor(door, FAIL_TAG, found.people.length === 0 ? "unknown_person" : "ambiguous_person", detail) };
+}
+export async function readPipedBody(door) {
+    try {
+        const parsed = JSON.parse(await readPipedText(door.io.stdin, { maxChars: 20000, overflowMessage: "The request is too large." }));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function availability(command, door) {
+    let labels = command.peopleWith ?? [];
+    let from = command.from;
+    let to = command.to;
+    let tz = command.timeZone;
+    let account = command.accountName;
+    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;
+    }
+    if (!labels.length)
+        return failAgentDoor(door, FAIL_TAG, "invalid_body", "Name who to check: --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 } : {}) };
+    const answer = await askAgentDoor(door, { method: "POST", path: "/api/cal/availability", body, label: "cal availability", 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 time = (iso) => new Intl.DateTimeFormat("en-GB", { timeZone: zone, weekday: "short", day: "numeric", month: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(iso));
+    for (const person of result.people) {
+        if (person.status === "unknown")
+            writeLine(door.io.stdout, `${person.email}: unknown (${person.reason ?? "no answer"}). Not shown as free.`);
+        else if (!person.busy.length)
+            writeLine(door.io.stdout, `${person.email}: no busy time in this window`);
+        else {
+            writeLine(door.io.stdout, `${person.email}: busy`);
+            for (const block of person.busy)
+                writeLine(door.io.stdout, `  ${time(block.start)} to ${time(block.end)}`);
+        }
+    }
+    const c = result.coverage;
+    writeLine(door.io.stdout, `${c.answered} of ${c.requested} answered, ${c.unknown} unknown · times in ${zone} · as of ${c.as_of}`);
+    return 0;
+}
+async function overlays(command, door) {
+    let answer;
+    if (command.pinLabel || command.removeEmail) {
+        let body;
+        if (command.pinLabel) {
+            const found = await search(door, command.pinLabel);
+            if (!found.ok)
+                return found.code;
+            if (found.people.length !== 1) {
+                return failAgentDoor(door, FAIL_TAG, found.people.length ? "ambiguous_person" : "unknown_person", found.people.length ? `"${command.pinLabel}" fits more than one person (${found.people.map((p) => p.email).join(", ")}). Pin by email address.` : `Nobody on the team list is exactly "${command.pinLabel}". Pin by email address.`);
+            }
+            const person = found.people[0];
+            body = { pin: { email: person.email, person_id: person.person_id, label: person.display_name } };
+        }
+        else
+            body = { remove: command.removeEmail };
+        answer = await askAgentDoor(door, { method: "PATCH", path: "/api/cal/overlays", body, label: "cal overlays", timeoutMs: REQUEST_TIMEOUT_MS });
+    }
+    else {
+        answer = await askAgentDoor(door, { method: "GET", path: "/api/cal/overlays", label: "cal overlays", 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;
+    if (result.changed)
+        writeLine(door.io.stdout, `Overlay ${result.changed}.`);
+    writeLine(door.io.stdout, `${result.overlays.length} of ${result.max} people pinned on your calendar`);
+    for (const pin of result.overlays)
+        writeLine(door.io.stdout, `  ${pin.label ?? pin.email} <${pin.email}>`);
+    return 0;
+}