spinuptui 1.3.0-alpha.3 → 1.3.0-alpha.5

package/src/lib/beaconListenInstall.ts

@@ -0,0 +1,251 @@
+// Installing Beacon's listener: a resident LaunchAgent (KeepAlive) running
+// `spinuptui beacon listen`, so macOS restarts it if it dies. It's the station's
+// one unit besides Scheduler's dispatcher; it does no scheduled work, it only
+// waits for the operator. Scheduler's tick runs `beacon listener check` (a
+// Beacon module job) and pages when the listener stops answering.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { loadConfig, saveConfig } from "../config.ts"
+import { beaconFromConfig, beaconSend, pickChannel } from "./beacon.ts"
+import { buttonMarkup, channelProblem, listenerDir, listenerLogPath, readListenerState } from "./beaconListen.ts"
+import { helpIncludes, launchctl, resolveRunner } from "./schedulerInstall.ts"
+import type { BeaconButton } from "../modules/contract.ts"
+
+export const DEFAULT_LISTENER_LABEL = "com.spinuptui.beacon-listener"
+// Three missed polls, with room for a restart.
+export const LISTENER_STALE_MS = 5 * 60_000
+// A poll that keeps failing this long (Telegram unreachable, another reader of
+// the bot) counts as down too; one blip doesn't.
+export const LISTENER_FAILING_MS = 10 * 60_000
+
+// Set while Beacon setup has the listener stopped, so the alive check doesn't
+// page about a pause the operator asked for.
+const pausedPath = () => join(listenerDir(), "listener.paused")
+const PAUSE_MAX_MS = 30 * 60_000
+
+export function listenerLabel(): string {
+  return process.env.SPINUPTUI_LISTENER_LABEL?.trim() || DEFAULT_LISTENER_LABEL
+}
+
+const domain = () => `gui/${process.getuid?.() ?? 501}`
+const xml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+export function renderListenerPlist(p: { label: string; programArguments: string[]; env: Record<string, string>; logPath: string }): string {
+  const args = p.programArguments.map((a) => `    <string>${xml(a)}</string>`).join("\n")
+  const env = Object.entries(p.env)
+    .map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`)
+    .join("\n")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  SpinupTUI Beacon's listener: \`spinuptui beacon listen\`, kept running so the
+  pager can answer you (/jobs and button taps). Written by
+  \`spinuptui beacon listener install --apply\`; remove it with
+  \`spinuptui beacon listener uninstall --apply\` rather than by hand.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(p.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>30</integer>
+  <key>StandardOutPath</key><string>${xml(p.logPath)}</string>
+  <key>StandardErrorPath</key><string>${xml(p.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+</dict>
+</plist>
+`
+}
+
+export interface ListenerPlan {
+  label: string
+  unitPath: string
+  bin: string
+  channel: string
+  programArguments: string[]
+  env: Record<string, string>
+  unitText: string
+  commands: string[]
+  notes: string[]
+}
+
+export type ListenerPlanResult = ({ ok: true } & ListenerPlan) | { ok: false; reason: string; message: string; remedy?: string }
+
+export function planListenerInstall(opts: { bin?: string | null; to?: string | null } = {}): ListenerPlanResult {
+  if (process.platform !== "darwin") {
+    return { ok: false, reason: "unsupported_platform", message: "The listener installs as a macOS LaunchAgent; Linux isn't supported yet." }
+  }
+  const picked = pickChannel(beaconFromConfig(loadConfig()), opts.to)
+  if ("ok" in picked) return { ok: false, reason: picked.reason, message: picked.message, remedy: picked.remedy ?? "Set up Beacon first: spinuptui beacon setup" }
+  if (picked.env) {
+    return {
+      ok: false,
+      reason: "env_channel",
+      message: "The default channel comes from SPINUPTUI_BEACON_* in this shell, which the LaunchAgent won't have.",
+      remedy: "Save the channel with `spinuptui beacon setup` (or `beacon add`) and install again.",
+    }
+  }
+  const problem = channelProblem(picked.channel)
+  if (problem) return { ok: false, reason: "group_chat", message: problem, remedy: "Point a channel at your private chat with the bot (spinuptui beacon setup), then install with --to <that channel>." }
+  const runner = resolveRunner(opts)
+  if (!runner.ok) return runner
+  const label = listenerLabel()
+  const programArguments = [...runner.prefix, "beacon", "listen", "--to", picked.name]
+  const env = { ...runner.env, SPINUPTUI_BEACON_LISTENER: "1" }
+  const unitPath = join(homedir(), "Library/LaunchAgents", `${label}.plist`)
+  const notes = [
+    `It answers only your private chat with the bot on channel "${picked.name}", and ignores everyone else.`,
+    "It long-polls Telegram (about one request a minute when idle) and restarts itself after you upgrade SpinupTUI.",
+    "Scheduler's tick checks it's alive and pages you if it isn't, so install Scheduler too.",
+  ]
+  if (runner.checkout) notes.push(`--bin points into a checkout (${runner.checkout}); fine for testing, never for a station.`)
+  return {
+    ok: true,
+    label,
+    unitPath,
+    bin: runner.bin,
+    channel: picked.name,
+    programArguments,
+    env,
+    unitText: renderListenerPlist({ label, programArguments, env, logPath: join(listenerDir(), "launchd.log") }),
+    commands: [`launchctl bootout ${domain()}/${label}  (if loaded)`, `launchctl bootstrap ${domain()} ${unitPath}`, "wait for the listener to start (up to 60 s)", "send a message saying it's listening"],
+    notes,
+  }
+}
+
+export type ListenerApplyResult =
+  | { ok: true; label: string; unitPath: string; channel: string; startedAt: string; notes: string[] }
+  | { ok: false; reason: string; message: string; remedy?: string; unitPath?: string }
+
+// Asked through --help, as for Scheduler's dispatcher: a release without the
+// listener treats `beacon listen` as an unknown subcommand.
+export function binHasListener(plan: Pick<ListenerPlan, "programArguments" | "env">): Promise<boolean> {
+  return helpIncludes(plan.programArguments.slice(0, -4), plan.env.PATH ?? "", "spinuptui beacon listen")
+}
+
+export const NO_LISTENER = {
+  ok: false as const,
+  reason: "spinuptui_too_old",
+  message: "The `spinuptui` the LaunchAgent would run doesn't have Beacon's listener yet.",
+  remedy: "Install a release that has it first: bun add -g spinuptui@next --no-cache",
+}
+
+export async function applyListenerInstall(plan: ListenerPlan, onStage: (s: string) => void = () => {}): Promise<ListenerApplyResult> {
+  onStage("checking that this spinuptui has the listener")
+  if (!(await binHasListener(plan))) return NO_LISTENER
+  mkdirSync(dirname(plan.unitPath), { recursive: true })
+  mkdirSync(listenerDir(), { recursive: true })
+  onStage(`writing ${plan.unitPath}`)
+  writeFileSync(plan.unitPath, plan.unitText, { mode: 0o644 })
+  await launchctl("bootout", `${domain()}/${plan.label}`)
+  const since = Date.now()
+  onStage("loading it with launchctl")
+  const boot = await launchctl("bootstrap", domain(), plan.unitPath)
+  if (boot.code !== 0) return { ok: false, reason: "launchctl_failed", message: `launchctl bootstrap failed: ${boot.out}`, unitPath: plan.unitPath }
+  const beacon = loadConfig().beacon ?? {}
+  await saveConfig({ beacon: { ...beacon, listener: { label: plan.label, unitPath: plan.unitPath, bin: plan.bin, channel: plan.channel, installedAt: new Date().toISOString() } } })
+
+  onStage("waiting for the listener to start")
+  for (let waited = 0; waited < 60_000; waited += 1000) {
+    const st = readListenerState()
+    if (st.startedAt && Date.parse(st.startedAt) >= since) {
+      const sent = await beaconSend(beaconFromConfig(loadConfig()), "Beacon is listening on this station. Send /help to see what it answers, or /jobs for the scheduled jobs.", { to: plan.channel })
+      const notes = sent.ok ? plan.notes : [...plan.notes, `It's running, but the hello message failed: ${sent.message}`]
+      return { ok: true, label: plan.label, unitPath: plan.unitPath, channel: plan.channel, startedAt: st.startedAt, notes }
+    }
+    await Bun.sleep(1000)
+  }
+  return {
+    ok: false,
+    reason: "not_started",
+    message: "The listener is installed, but it didn't start within 60 seconds.",
+    remedy: `Check ${join(listenerDir(), "launchd.log")} and \`launchctl print ${domain()}/${plan.label}\`.`,
+    unitPath: plan.unitPath,
+  }
+}
+
+export interface ListenerUninstallPlan {
+  label: string
+  unitPath: string
+  installed: boolean
+  commands: string[]
+}
+
+export function planListenerUninstall(): ListenerUninstallPlan {
+  const l = loadConfig().beacon?.listener
+  const label = l?.label ?? listenerLabel()
+  const unitPath = l?.unitPath ?? join(homedir(), "Library/LaunchAgents", `${label}.plist`)
+  return {
+    label,
+    unitPath,
+    installed: !!l || existsSync(unitPath),
+    commands: [`launchctl bootout ${domain()}/${label}`, `delete ${unitPath}`, "clear beacon.listener in config.json (channels are kept)"],
+  }
+}
+
+export async function applyListenerUninstall(plan: ListenerUninstallPlan): Promise<{ ok: true; removed: string }> {
+  if (process.platform === "darwin") await launchctl("bootout", `${domain()}/${plan.label}`)
+  if (existsSync(plan.unitPath)) unlinkSync(plan.unitPath)
+  const b = loadConfig().beacon
+  if (b?.listener) {
+    const { listener: _gone, ...rest } = b
+    await saveConfig({ beacon: rest })
+  }
+  return { ok: true, removed: plan.unitPath }
+}
+
+export function listenerInstalled(): boolean {
+  const l = loadConfig().beacon?.listener
+  return !!l && existsSync(l.unitPath)
+}
+
+// Is the installed listener answering? null when none is installed.
+// Inline buttons for a page. Only the listener can receive a tap, so with none
+// installed a page goes out without them.
+export function pageMarkup(buttons: BeaconButton[][]): string | undefined {
+  return listenerInstalled() ? buttonMarkup(buttons) : undefined
+}
+
+export function listenerHealth(now = Date.now()): { ok: boolean; detail: string } | null {
+  if (!listenerInstalled()) return null
+  try {
+    const at = Date.parse(readFileSync(pausedPath(), "utf8").trim())
+    if (now - at < PAUSE_MAX_MS) return { ok: true, detail: `paused by Beacon setup since ${new Date(at).toISOString()}` }
+  } catch {
+    // Not paused.
+  }
+  const st = readListenerState()
+  // A listener that just started has a first poll still out (up to 50 seconds),
+  // so its start counts as a sign of life too.
+  const last = Math.max(...[st.lastPollAt, st.startedAt].map((t) => (t ? Date.parse(t) : 0)))
+  if (now - last > LISTENER_STALE_MS) {
+    return { ok: false, detail: `hasn't polled Telegram since ${st.lastPollAt ?? "it was installed"}; see ${listenerLogPath()}` }
+  }
+  if (st.failingSince && now - Date.parse(st.failingSince) > LISTENER_FAILING_MS) {
+    return { ok: false, detail: `polls failing since ${st.failingSince}: ${st.lastError ?? "unknown error"}` }
+  }
+  return { ok: true, detail: `listening on ${st.channel ?? "?"} (pid ${st.pid ?? "?"}, ${st.version ?? "?"}), ${st.lastPollAt ? `last poll ${st.lastPollAt}` : `started ${st.startedAt}`}` }
+}
+
+// Telegram hands a bot's updates to one reader at a time, so Beacon setup's chat
+// discovery stops the listener while it waits and starts it again after.
+export async function pauseListener(): Promise<() => Promise<void>> {
+  const l = loadConfig().beacon?.listener
+  if (process.platform !== "darwin" || !l || !existsSync(l.unitPath)) return async () => {}
+  mkdirSync(listenerDir(), { recursive: true })
+  writeFileSync(pausedPath(), new Date().toISOString() + "\n")
+  await launchctl("bootout", `${domain()}/${l.label}`)
+  return async () => {
+    await launchctl("bootstrap", domain(), l.unitPath)
+    rmSync(pausedPath(), { force: true })
+  }
+}

package/src/lib/cliBeacon.ts

@@ -20,12 +20,25 @@ import {
   setupChannelName,
   verifyBotToken,
 } from "./beaconSetup.ts"
+import { boardLogin } from "./beaconBoard.ts"
 import { confirm, PromptCancelled, readLine } from "./prompt.ts"
+import { listen, routesFrom } from "./beaconListen.ts"
+import {
+  applyListenerInstall,
+  applyListenerUninstall,
+  binHasListener,
+  listenerHealth,
+  NO_LISTENER,
+  pauseListener,
+  planListenerInstall,
+  planListenerUninstall,
+} from "./beaconListenInstall.ts"
+import { MODULES } from "../modules/index.ts"
 import { beaconModule } from "../modules/beacon.ts"
 import { allModuleStatuses, UPCOMING_MODULES } from "../modules/index.ts"
 import type { ModuleStatus } from "../modules/contract.ts"
 
-const VALUE_FLAGS = new Set(["--to", "--env-file"])
+const VALUE_FLAGS = new Set(["--to", "--env-file", "--bin", "--project", "--mention"])
 
 function parse(list: string[]): { positionals: string[]; flags: Map<string, string>; rest: string | null } {
   const dash = list.indexOf("--")
@@ -59,9 +72,14 @@ const USAGE = `Usage:
   spinuptui beacon setup [<name>]   (guided, in a terminal)
   spinuptui beacon send [--to <channel>] [--silent] [--json] [<message> | -]
   spinuptui beacon add telegram <name> [--env-file <path>] [--default] [--no-test]
+  spinuptui beacon add basecamp <name> --project <id> [--mention "<person>"]
+                          a team message board: the \`basecamp\` CLI must be logged in
   spinuptui beacon remove <name>
   spinuptui beacon test [--to <channel>] [--json]
-  spinuptui beacon status [--json]`
+  spinuptui beacon status [--json]
+  spinuptui beacon listen [--to <channel>]   answer the operator: /jobs, button taps (foreground)
+  spinuptui beacon listener install | uninstall --plan | --apply [--to <channel>] [--bin <path>]
+  spinuptui beacon listener status | check   is it running? (check exits 1 when it isn't)`
 
 function badValue(flags: Map<string, string>, name: string): boolean {
   if (!flags.has(name)) return false
@@ -81,6 +99,8 @@ export async function runBeacon(argv: string[]): Promise<number> {
   if (sub === "add") return add(positionals.slice(1), flags, json)
   if (sub === "remove") return remove(positionals.slice(1), json)
   if (sub === "status") return status(json)
+  if (sub === "listen") return listenCmd(flags)
+  if (sub === "listener") return listener(positionals.slice(1), flags, json)
   return fail(json, "usage", USAGE)
 }
 
@@ -121,8 +141,22 @@ async function test(flags: Map<string, string>, json: boolean): Promise<number>
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/
 
+async function addBoard(name: string, flags: Map<string, string>, json: boolean): Promise<number> {
+  const projectId = flags.get("--project") ?? ""
+  if (!/^\d+$/.test(projectId)) return fail(json, "usage", `--project needs the Basecamp project's numeric id.\n${USAGE}`)
+  const login = await boardLogin()
+  if (!login.ok) return fail(json, "basecamp_login", `Can't reach Basecamp: ${login.detail}.`)
+  const mention = flags.get("--mention")
+  const stored: BeaconStored = loadConfig().beacon ?? {}
+  await saveConfig({ beacon: { ...stored, boards: { ...(stored.boards ?? {}), [name]: { type: "basecamp", projectId, audience: "team", ...(mention ? { mention } : {}) } } } })
+  if (json) console.log(JSON.stringify({ ok: true, board: name, projectId }))
+  else console.log(`Added team board "${name}" (Basecamp project ${projectId}), posting as ${login.detail}.`)
+  return 0
+}
+
 async function add(pos: string[], flags: Map<string, string>, json: boolean): Promise<number> {
   const [type, name] = pos
+  if (type === "basecamp" && name && NAME_RE.test(name)) return addBoard(name, flags, json)
   if (type !== "telegram" || !name) return fail(json, "usage", USAGE)
   if (!NAME_RE.test(name)) return fail(json, "usage", `Channel names are lowercase letters, digits and dashes (got "${name}").`)
   if (name === "env") return fail(json, "usage", `"env" is reserved for the channel defined by SPINUPTUI_BEACON_* environment variables.`)
@@ -215,7 +249,9 @@ async function setup(pos: string[]): Promise<number> {
       say(`3. In Telegram, send any message to ${username ? `@${username} (${botLink(username)})` : "your bot"}.`)
       say("   To page a group instead, add the bot to the group and send /start there.")
       say("   Waiting up to 5 minutes… (Ctrl-C to cancel)")
-      const found = await discoverChat(token)
+      // Telegram gives a bot's messages to one reader: stop the listener meanwhile.
+      const resume = await pauseListener()
+      const found = await discoverChat(token).finally(resume)
       if (!found.ok) {
         say(`   ✗ ${found.message}`)
         if (found.reason === "timeout" && (await confirm("   Keep waiting?", true))) continue
@@ -248,6 +284,13 @@ async function remove(pos: string[], json: boolean): Promise<number> {
   const name = pos[0]
   if (!name) return fail(json, "usage", USAGE)
   const stored: BeaconStored = loadConfig().beacon ?? {}
+  if (stored.boards?.[name]) {
+    const { [name]: _board, ...boards } = stored.boards
+    await saveConfig({ beacon: { ...stored, boards } })
+    if (json) console.log(JSON.stringify({ ok: true, removed: name }))
+    else console.log(`Removed board "${name}".`)
+    return 0
+  }
   if (!stored.channels?.[name]) {
     const resolved = pickChannel(beaconFromConfig(loadConfig()), name)
     if (!("ok" in resolved) && resolved.env) {
@@ -288,3 +331,72 @@ export async function runModules(argv: string[]): Promise<number> {
   }
   return 0
 }
+
+// ---- the listener ----------------------------------------------------------------
+
+async function listenCmd(flags: Map<string, string>): Promise<number> {
+  const picked = pickChannel(beaconFromConfig(loadConfig()), flags.get("--to") ?? null)
+  if ("ok" in picked) return fail(false, picked.reason, picked.message, picked.remedy)
+  const ctrl = new AbortController()
+  for (const sig of ["SIGTERM", "SIGINT"] as const) process.on(sig, () => ctrl.abort())
+  if (process.env.SPINUPTUI_BEACON_LISTENER !== "1") process.stderr.write(`Listening on "${picked.name}" for /commands and button taps (Ctrl-C to stop)…\n`)
+  const r = await listen({ channel: picked.channel, channelName: picked.name, routes: routesFrom(MODULES), signal: ctrl.signal })
+  if (!r.ok) return fail(false, r.reason, r.message)
+  return 0
+}
+
+async function listener(pos: string[], flags: Map<string, string>, json: boolean): Promise<number> {
+  const sub = pos[0]
+  if (sub === "status" || sub === "check") {
+    const h = listenerHealth()
+    if (json) console.log(JSON.stringify({ ok: h?.ok ?? true, installed: h !== null, ...(h ? { detail: h.detail } : {}) }))
+    else if (!h) console.log("Beacon's listener isn't installed on this machine.")
+    else console.log(`${h.ok ? "✓" : "✗"} Beacon's listener ${h.detail}`)
+    if (sub === "check" && h && !h.ok && !json) console.log("Reinstall it with `spinuptui beacon listener install --apply`, or from the Modules tab.")
+    return sub === "check" && h && !h.ok ? 1 : 0
+  }
+  const apply = flags.has("--apply")
+  if ((sub !== "install" && sub !== "uninstall") || apply === flags.has("--plan")) {
+    return fail(json, "usage", "Usage: spinuptui beacon listener install | uninstall --plan | --apply, or listener status | check")
+  }
+  if (sub === "uninstall") {
+    const plan = planListenerUninstall()
+    if (!apply) {
+      if (json) console.log(JSON.stringify({ ok: true, ...plan }))
+      else {
+        if (!plan.installed) console.log("Beacon's listener isn't installed; nothing to remove.")
+        for (const c of plan.commands) console.log(`  · ${c}`)
+      }
+      return 0
+    }
+    const r = await applyListenerUninstall(plan)
+    if (json) console.log(JSON.stringify(r))
+    else console.log(`Removed ${plan.label}. The pager still sends; it just won't answer.`)
+    return 0
+  }
+  const plan = planListenerInstall({ bin: flags.get("--bin") ?? null, to: flags.get("--to") ?? null })
+  if (!plan.ok) return fail(json, plan.reason, plan.message, plan.remedy)
+  // Refuse at --plan too, so a plan that can't work is never shown as one.
+  if (!(await binHasListener(plan))) return fail(json, NO_LISTENER.reason, NO_LISTENER.message, NO_LISTENER.remedy)
+  if (!apply) {
+    if (json) console.log(JSON.stringify(plan))
+    else {
+      console.log(`Would install Beacon's listener (${plan.label}), kept running by launchd:\n`)
+      console.log(`  ${plan.programArguments.join(" ")}\n`)
+      console.log(`Unit: ${plan.unitPath}\n`)
+      console.log("Steps:")
+      for (const c of plan.commands) console.log(`  · ${c}`)
+      for (const n of plan.notes) console.log(`Note: ${n}`)
+      console.log(`\nRun with --apply to install it.`)
+    }
+    return 0
+  }
+  const r = await applyListenerInstall(plan, (line) => process.stderr.write(`→ ${line}\n`))
+  if (!r.ok) return fail(json, r.reason, r.message, r.remedy)
+  if (json) console.log(JSON.stringify(r))
+  else {
+    console.log(`Installed ${r.label}; it's listening on "${r.channel}". Send /jobs to the bot to try it.`)
+    for (const n of r.notes) console.log(`Note: ${n}`)
+  }
+  return 0
+}

package/src/lib/cliIncidents.ts

@@ -18,10 +18,14 @@ export interface IncidentEvent {
   status: IncidentStatus
   time: string
   message: string
+  monitorId: number
 }
 
 export type IncidentsResult =
-  | { ok: true; windowHours: number; events: IncidentEvent[] }
+  // failedMonitors: monitors whose history couldn't be read this time, so a
+  // caller doesn't mistake their silence for "no events". kumaAlerted: with
+  // `wiring`, the monitors Kuma itself sends a notification for.
+  | { ok: true; windowHours: number; events: IncidentEvent[]; failedMonitors: string[]; kumaAlerted?: number[] }
   | { ok: false; reason: "kuma_not_configured" | "no_monitors_registered" | "kuma_error"; message: string }
 
 const STATUS_LABEL: Record<number, IncidentStatus> = { 0: "down", 1: "up", 2: "pending", 3: "maintenance" }
@@ -50,7 +54,7 @@ interface Target {
 
 export async function resolveIncidents(
   cfg: AppConfig,
-  opts: { domain?: string; hours: number },
+  opts: { domain?: string; hours: number; wiring?: boolean },
 ): Promise<IncidentsResult> {
   if (!cfg.uptimeKuma) {
     return {
@@ -83,11 +87,13 @@ export async function resolveIncidents(
 
   try {
     const { result } = await withKuma(cfg.uptimeKuma, async (kuma) => {
+      const failedMonitors: string[] = []
       const perTarget = await Promise.all(
         targets.map(async (t) => {
           try {
             return { t, beats: await kuma.getMonitorBeats(t.id, opts.hours) }
           } catch {
+            failedMonitors.push(`${t.domain} ${t.kind}`)
             return { t, beats: [] as KumaBeat[] }
           }
         }),
@@ -115,17 +121,18 @@ export async function resolveIncidents(
           const looksLikeDomainList = domainList.every((d) => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)+$/.test(d))
           if (t.kind === "fatal" && status === "down" && looksLikeDomainList) {
             for (const domain of domainList) {
-              events.push({ domain, kind: t.kind, status, time: b.time, message })
+              events.push({ domain, kind: t.kind, status, time: b.time, message, monitorId: t.id })
             }
             continue
           }
-          events.push({ domain: t.domain, kind: t.kind, status, time: b.time, message })
+          events.push({ domain: t.domain, kind: t.kind, status, time: b.time, message, monitorId: t.id })
         }
       }
       events.sort((a, b) => a.time.localeCompare(b.time))
-      return events
+      const kumaAlerted = opts.wiring ? (await kuma.getMonitors()).filter((m) => Object.keys((m.notificationIDList as object | null) ?? {}).length > 0).map((m) => m.id) : undefined
+      return { events, failedMonitors, kumaAlerted }
     })
-    return { ok: true, windowHours: opts.hours, events: result }
+    return { ok: true, windowHours: opts.hours, ...result }
   } catch (err) {
     const message = err instanceof KumaError ? err.message : `Unexpected error: ${(err as Error).message}`
     return { ok: false, reason: "kuma_error", message }

package/src/lib/cliScheduler.ts

@@ -7,7 +7,7 @@ import { existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSy
 import { join, relative, resolve } from "node:path"
 import { loadConfig, saveConfig } from "../config.ts"
 import { schedulerModule } from "../modules/scheduler.ts"
-import { fmt, nextRunText } from "./schedule.ts"
+import { fmt, nextRunText, parseDate } from "./schedule.ts"
 import {
   defaultSourceName,
   expandHome,
@@ -29,6 +29,7 @@ import {
 } from "./schedulerJobs.ts"
 import { applyInstall, applyUninstall, binHasScheduler, NO_SCHEDULER, planInstall, planUninstall } from "./schedulerInstall.ts"
 import { tick } from "./schedulerTick.ts"
+import { extendJob, PERIOD_RE } from "./schedulerExtend.ts"
 import { prepareWorkDir, tilde } from "./home.ts"
 import { applyStationPlan, connectHeartbeat, loadStationPlan, pagerProblem, removeHeartbeat, sendHeartbeat, stationPlanText, tickHeartbeat } from "./heartbeat.ts"
 import { git, gitPull, readClaim, removeClaim, stationName, writeClaim } from "./schedulerGit.ts"
@@ -53,6 +54,7 @@ const VALUE_FLAGS = new Set([
   "--prompt-file",
   "--bin",
   "--late",
+  "--by",
 ])
 
 // Header keys `add` writes from flags, in file order.
@@ -76,6 +78,9 @@ const USAGE = `Usage:
   spinuptui scheduler add <id> --kind ${KINDS.join("|")} (--when "YYYY-MM-DD HH:MM" | --when now | --every <schedule>)
                           --expires YYYY-MM-DD --created-by <who> [--source <name>] [options]
                           [--body-file <path> | -- <body>]   (else stdin)
+  spinuptui scheduler extend <id> (--expires YYYY-MM-DD | --by 30d|2w|6m|1y) [--source <name>]
+                          move its expiry later; --by counts from the current expiry
+                          (or from today, if it has already expired)
   spinuptui scheduler cancel <id> [--source <name>]
   spinuptui scheduler run <id> [--source <name>]     run it now, on this machine
   spinuptui scheduler validate [--source <name>]
@@ -156,6 +161,8 @@ export async function runScheduler(argv: string[]): Promise<number> {
       return show(pos, p)
     case "add":
       return add(pos, p, json)
+    case "extend":
+      return extend(pos, p, json)
     case "cancel":
       return cancel(pos, p, json)
     case "run":
@@ -321,6 +328,28 @@ async function add(pos: string[], p: Parsed, json: boolean): Promise<number> {
   return 0
 }
 
+async function extend(pos: string[], p: Parsed, json: boolean): Promise<number> {
+  const id = pos[0]
+  const date = p.flags.get("--expires")
+  const by = p.flags.get("--by")
+  if (!id || !!date === !!by) return fail(json, "usage", `Give a job id and exactly one of --expires or --by.\n${USAGE}`)
+  if (by && !PERIOD_RE.test(by.toLowerCase())) return fail(json, "usage", `--by takes a period like 30d, 2w, 6m or 1y, got "${by}".`)
+  if (date) {
+    try {
+      parseDate(date)
+    } catch (err) {
+      return fail(json, "usage", (err as Error).message.replace(/^expires:/, "--expires"))
+    }
+  }
+  const s = sourceOrFail(p, json)
+  if (typeof s === "number") return s
+  const r = await extendJob(s, id, { date, by }, { push: !p.flags.has("--no-push") })
+  if (!r.ok) return fail(json, r.reason, r.message, r.remedy)
+  if (json) console.log(JSON.stringify(r))
+  else console.log(`Extended ${s.name}/${id}: expires ${r.to} (was ${r.from})${r.pushed ? ", pushed" : ""}.`)
+  return 0
+}
+
 async function cancel(pos: string[], p: Parsed, json: boolean): Promise<number> {
   const id = pos[0]
   if (!id) return fail(json, "usage", USAGE)