spinuptui 1.3.0-alpha.2 → 1.3.0-alpha.3

package/CHANGELOG.md

@@ -11,6 +11,23 @@ version; such changes are called out here.
 
 ## [Unreleased]
 
+## [1.3.0-alpha.3] - 2026-10-27
+
+A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew are on 1.2.1.
+
+### Added
+- **Station heartbeat: find out when the station itself stops.** If the machine running Scheduler is off, the installed `spinuptui` is broken, or its LaunchAgent is gone, nothing on that machine can page you. Now every dispatcher tick pings an Uptime Kuma push monitor that you run somewhere else (a small VPS is easiest), and when the pings stop, Kuma alerts you through its own notifications. If SpinupTUI has your Kuma login (from site monitoring), `spinuptui scheduler heartbeat setup --plan|--apply` creates the monitor for you; otherwise make a push monitor by hand and run `spinuptui scheduler heartbeat set '<push URL>'`. Both ping once before saving. In the app, `h` on the Modules tab's Scheduler card walks through the same setup and later shows the last ping, sends a test ping, or removes it. The ping reports **down** when the station is running but can't page you, because Beacon isn't set up or its last page failed, so a broken pager reaches you too. `scheduler status` and the Modules tab show the last ping. See [docs/scheduler.md](docs/scheduler.md#know-when-the-station-itself-stops).
+- **Your SpinupTUI folder explains itself, and can be shared across machines in one step.** `~/SpinupTUI/`, where Scheduler keeps your jobs and reports, now gets a `README.md` when it's created, covering what each part is, which parts are yours to edit, and how to move or share it. `spinuptui home` shows where it is and whether it's shared. `spinuptui home sync --plan|--apply` shares it through a private git repository: it creates one on GitHub (`--github <name>`, using the GitHub CLI) or pushes to an empty one you made (`--remote <url>`). Then you can queue jobs from any machine and read the reports anywhere. On a second machine, `--clone <url>` sets up the same folder. It won't share a folder inside iCloud, Dropbox or another sync service, push to a repository that already has commits, or use a public GitHub repository. The Modules tab shows where jobs and reports land, and `f` on Scheduler walks through the same steps. Queuing a job now prints the full path of the job file and where its reports will go.
+
+### Fixed
+- **Scheduler no longer reports a problem on every tick before you've queued anything locally.** `~/SpinupTUI/scheduler/` is created on first use, so its absence is normal; `scheduler status` used to list "source local … does not exist" as a problem from the last tick.
+
+## [1.2.1] - 2026-10-27
+
+### Fixed
+- **WordPress versions no longer go stale.** The version shown for a site was read once, when the site was first identified, and never again, so sites updated outside SpinupTUI (auto-updates, wp-admin, deploys) kept showing the old version, and `r` didn't help. Versions older than a day are now re-checked in the background when the site list loads, one site at a time per server, stopping at a server's first failure so unattended SSH can't trip fail2ban. A reading that couldn't be refreshed shows its age in the Stacks list, and the Details pane always says when it was taken.
+- **`w` opens the site or server you picked, not the SpinupWP dashboard.** Deep links need the account slug, which SpinupWP's API doesn't provide and first-run setup never asked for, so unless you had added `accountSlug` to `config.json` by hand, `w` quietly fell back to the dashboard. Now `w` asks for the slug the first time it needs it (pasting any dashboard URL works), saves it to the current account and opens the right page. First-run setup also asks for it, as an optional step after the token.
+
 ## [1.3.0-alpha.2] - 2026-10-26
 
 A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew stay on 1.2.0.
@@ -1517,7 +1534,9 @@ Initial tagged release.
 ### Notes
 - Read-only release: works with a SpinupWP **Read Only** API token.
 
-[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.2...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.3...HEAD
+[1.3.0-alpha.3]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.2...v1.3.0-alpha.3
+[1.2.1]: https://github.com/mwender/spinupwp-tui/compare/v1.2.0...v1.2.1
 [1.3.0-alpha.2]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.1...v1.3.0-alpha.2
 [1.3.0-alpha.1]: https://github.com/mwender/spinupwp-tui/compare/v1.2.0...v1.3.0-alpha.1
 [1.2.0]: https://github.com/mwender/spinupwp-tui/compare/v1.1.2...v1.2.0

package/README.md

@@ -84,9 +84,11 @@
   bot connection for you. → [docs/beacon.md](docs/beacon.md)
   Then **Scheduler**: follow-ups that run themselves. Queue "check this
   tomorrow at 8" from any session, and the result arrives through Beacon. Jobs
-  and reports live in `~/SpinupTUI/scheduler/`; make that folder a git
-  repository to queue from any machine. One LaunchAgent ticks every
-  5 minutes and is the clock the other modules run on. → [docs/scheduler.md](docs/scheduler.md)
+  and reports live in `~/SpinupTUI/scheduler/`; `spinuptui home sync` (or `f`)
+  shares that folder through a private git repository so you can queue from
+  any machine. One LaunchAgent ticks every 5 minutes and is the clock the other
+  modules run on, and a station heartbeat (`h`) pings your Uptime Kuma each
+  tick, so a station that stops is noticed from elsewhere. → [docs/scheduler.md](docs/scheduler.md)
 - **Non-interactive CLI subcommands for external tooling** — `spinuptui ssh <domain>`
   resolves a domain to a live SSH target with a live connectivity probe;
   `spinuptui ssh-exec <domain> -- <command>` runs a command over SSH, but only
@@ -315,8 +317,9 @@ These can be set in `config.json` or via an environment variable:
 - **`accountSlug`** / `SPINUPWP_ACCOUNT_SLUG` — your SpinupWP account/team slug
   (the first path segment in a SpinupWP URL, e.g. `acme-agency` in
   `https://spinupwp.app/acme-agency/servers/12345`). The API
-  doesn't expose it, so set it to enable the `w` deep links into the web app.
-  Without it, `w` opens the SpinupWP dashboard root.
+  doesn't expose it, so it's needed for the `w` deep links into the web app.
+  You don't have to set it by hand: first-run setup asks for it (optional), and
+  `w` asks the first time it's needed, then saves it to the current account.
 - **`sshUser`** / `SPINUPWP_SSH_USER` — override the SSH user for the health view
   and stack probes (see "Server health" below).
 - **`localSync`** / `SPINUPWP_LOCAL_SYNC` — opt-in for the **Pull production →
@@ -382,6 +385,8 @@ These can be set in `config.json` or via an environment variable:
 | `A` | Accounts — switch, add, rename, or remove SpinupWP accounts (from anywhere) |
 | `⏎` / `s` | Set up the selected module — Beacon opens its guided Telegram setup, Scheduler its install plan (Modules tab) |
 | `t` | Send a test page through Beacon (Modules tab, once Beacon is set up) |
+| `f` | Your SpinupTUI folder: where jobs and reports live, and sharing it across machines (Modules tab, Scheduler) |
+| `h` | Station heartbeat: set up the Uptime Kuma push monitor, see the last ping, test or remove it (Modules tab, Scheduler) |
 | `r` | Refresh data from the API |
 | `i` | Explain the current screen (what each pane and key does) |
 | `?` | Toggle the help overlay |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spinuptui",
-  "version": "1.3.0-alpha.2",
+  "version": "1.3.0-alpha.3",
   "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -142,6 +142,9 @@ export interface SchedulerStored {
   queueOnly?: string[]
   // Written by `scheduler install --apply`, cleared by uninstall.
   dispatcher?: { label: string; unitPath: string; bin: string; installedAt: string }
+  // The station heartbeat: an Uptime Kuma push monitor, pinged at the end of
+  // every dispatcher tick (lib/heartbeat.ts). Set by `scheduler heartbeat set`.
+  heartbeat?: { url: string; setAt: string }
 }
 
 export interface ServerProviderRef {

package/src/index.tsx

@@ -112,6 +112,10 @@ Usage:
                        Queue a follow-up for this station to run later and report
                        on through Beacon (\`spinuptui scheduler\` for the rest)
   spinuptui scheduler list | status | install --plan|--apply
+  spinuptui home       Where the SpinupTUI folder (your jobs and reports) is
+  spinuptui home sync --plan|--apply --github <name> | --remote <url> | --clone <url>
+                       Share that folder across machines through a private git
+                       repository, or set it up from one on a second machine
   spinuptui modules    List SpinupTUI's modules and their status (--json)
   spinuptui --version  Print the version
   spinuptui --help     Show this help
@@ -312,6 +316,11 @@ if (command === "modules") {
   process.exit(await runModules(args.slice(1)))
 }
 
+if (command === "home") {
+  const { runHome } = await import("./lib/cliHome.ts")
+  process.exit(await runHome(args.slice(args.indexOf("home") + 1)))
+}
+
 if (command === "scheduler") {
   process.exit(await runScheduler(args.slice(args.indexOf("scheduler") + 1)))
 }

package/src/lib/cliHome.ts

@@ -0,0 +1,107 @@
+// `spinuptui home`: where the SpinupTUI folder is and whether it's shared, and
+// `home sync`, which shares it across machines (lib/home.ts). Headless like the
+// module commands: --json prints one object on stdout.
+
+import { applySync, describeShare, ensureHome, homeStatus, planSync, tilde, type SyncOptions } from "./home.ts"
+
+const USAGE = `Usage:
+  spinuptui home [--json]          where the SpinupTUI folder is, and whether it's shared
+  spinuptui home sync --plan | --apply [--json]
+        --github <name>            create a private GitHub repository for it (needs gh)
+        --remote <url>             or push it to an empty private repository you made
+        --clone <url>              on another machine: set the same folder up here
+
+The SpinupTUI folder (~/SpinupTUI) holds your Scheduler jobs and reports and,
+later, other modules' work. Shared through a private git repository, you can
+queue jobs from any machine and read the reports anywhere.`
+
+const VALUE_FLAGS = new Set(["--github", "--remote", "--clone"])
+
+function fail(json: boolean, reason: string, message: string, remedy?: string): number {
+  if (json) console.log(JSON.stringify({ ok: false, reason, message, ...(remedy ? { remedy } : {}) }))
+  else {
+    console.error(message)
+    if (remedy) console.error(remedy)
+  }
+  return 1
+}
+
+export async function runHome(argv: string[]): Promise<number> {
+  const flags = new Map<string, string>()
+  const pos: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!
+    if (VALUE_FLAGS.has(a)) flags.set(a, argv[++i] ?? "")
+    else if (a.startsWith("-")) flags.set(a, "")
+    else pos.push(a)
+  }
+  const json = flags.has("--json")
+  if (flags.has("--help") || flags.has("-h")) {
+    console.log(USAGE)
+    return 0
+  }
+  if (pos.length === 0) return status(json)
+  if (pos[0] === "sync") return sync(flags, json)
+  return fail(json, "usage", USAGE)
+}
+
+async function status(json: boolean): Promise<number> {
+  const s = await homeStatus()
+  if (json) {
+    console.log(JSON.stringify({ ok: true, ...s }))
+    return 0
+  }
+  console.log(`SpinupTUI folder: ${tilde(s.path)}${s.exists ? "" : " (created the first time a module writes to it)"}`)
+  console.log(`  ${s.git && s.remote ? "✓" : "·"} ${describeShare(s)}`)
+  if (s.station) console.log(`  · its jobs run on ${s.station === s.thisMachine ? "this machine" : s.station}`)
+  if (s.syncedBy) console.log(`  ✗ inside ${s.syncedBy}: ${s.git ? "two programs syncing the same .git can corrupt it. Move it (homeDir in config.json)." : "fine on its own, but move it before sharing it with git."}`)
+  if (!s.git && !s.insideRepo) console.log(`\nTo queue jobs from other machines: spinuptui home sync --plan`)
+  return 0
+}
+
+async function sync(flags: Map<string, string>, json: boolean): Promise<number> {
+  const apply = flags.has("--apply")
+  if (apply === flags.has("--plan")) return fail(json, "usage", "Pass --plan to see what would happen, or --apply to do it.\n\n" + USAGE)
+  const opts: SyncOptions = {}
+  for (const [flag, key] of [
+    ["--github", "github"],
+    ["--remote", "remote"],
+    ["--clone", "clone"],
+  ] as const) {
+    if (!flags.has(flag)) continue
+    if (!flags.get(flag)) return fail(json, "usage", `${flag} needs a value.`)
+    opts[key] = flags.get(flag)
+  }
+  const plan = await planSync(opts)
+  if (plan.blockers.length) {
+    const b = plan.blockers[0]!
+    if (json) console.log(JSON.stringify({ ok: false, reason: b.reason, message: b.message, ...(b.remedy ? { remedy: b.remedy } : {}), blockers: plan.blockers }))
+    else for (const x of plan.blockers) fail(false, x.reason, x.message, x.remedy)
+    return 1
+  }
+  const steps = plan.steps.map((s) => s.label)
+  if (!apply) {
+    if (json) console.log(JSON.stringify({ ok: true, applied: false, mode: plan.mode, home: plan.home, steps, notes: plan.notes }))
+    else if (!steps.length) console.log(`${tilde(plan.home)} is already shared and up to date. Nothing to do.`)
+    else {
+      console.log(`Plan for ${tilde(plan.home)}:`)
+      steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`))
+      for (const n of plan.notes) console.log(`\n${n}`)
+      console.log(`\nRun with --apply to do it.`)
+    }
+    return 0
+  }
+  const r = await applySync(plan)
+  if (json) console.log(JSON.stringify({ ok: r.ok, applied: true, mode: plan.mode, home: plan.home, done: r.done, ...(r.failed ? { failed: r.failed } : {}) }))
+  else {
+    for (const d of r.done) console.log(`✓ ${d}`)
+    if (r.failed) console.error(`✗ ${r.failed.step}: ${r.failed.message}\nSteps above it are done; fix this and run it again, and it picks up where it stopped.`)
+    else if (steps.length) {
+      // A clone brings the other machine's README; make sure there is one.
+      ensureHome()
+      const s = await homeStatus()
+      console.log(`\n${tilde(s.path)} is ${describeShare(s)}.`)
+    } else console.log(`${tilde(plan.home)} is already shared and up to date. Nothing to do.`)
+  }
+  return r.ok ? 0 : 1
+}

package/src/lib/cliScheduler.ts

@@ -3,7 +3,7 @@
 // result object on stdout, progress goes to stderr, failures use the
 // { ok: false, reason, message, remedy? } shape and exit 1.
 
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { existsSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import { join, relative, resolve } from "node:path"
 import { loadConfig, saveConfig } from "../config.ts"
 import { schedulerModule } from "../modules/scheduler.ts"
@@ -21,12 +21,16 @@ import {
   loadState,
   LOCAL_SOURCE,
   parseJobText,
+  readLastTick,
   renderJob,
+  runsDir,
   validateJob,
   type Source,
 } from "./schedulerJobs.ts"
 import { applyInstall, applyUninstall, binHasScheduler, NO_SCHEDULER, planInstall, planUninstall } from "./schedulerInstall.ts"
 import { tick } from "./schedulerTick.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"
 
 const VALUE_FLAGS = new Set([
@@ -80,6 +84,9 @@ const USAGE = `Usage:
   spinuptui scheduler source release <name>   stop running it here; another station takes it
   spinuptui scheduler tick [--here]
   spinuptui scheduler install | uninstall --plan | --apply [--bin <path>]
+  spinuptui scheduler heartbeat [setup --plan|--apply [--notify <name>] | set '<kuma-push-url>' | test | remove]
+                          ping an Uptime Kuma push monitor on another machine every
+                          tick, so a station that stops (or can't page) is noticed
 
 Schedules: --every 30m | 6h | "daily 08:00" | "weekdays 08:00" | "mon,thu 08:00" (station local time).
 Add options: --workdir <dir> --timeout <min> --notify beacon|none --to <channel>
@@ -161,6 +168,8 @@ export async function runScheduler(argv: string[]): Promise<number> {
       return doTick(p, json)
     case "install":
       return install(p, json)
+    case "heartbeat":
+      return heartbeat(p.positionals.slice(1), p.flags, json)
     case "uninstall":
       return uninstall(p, json)
   }
@@ -295,7 +304,7 @@ async function add(pos: string[], p: Parsed, json: boolean): Promise<number> {
   const problems = validateJob(parsed.header, parsed.body, `${id}.md`)
   if (problems.length) return fail(json, "invalid_job", `Not added: ${problems.join("; ")}`)
 
-  mkdirSync(jobsDir(s), { recursive: true })
+  prepareWorkDir(jobsDir(s))
   writeFileSync(`${path}.tmp`, text)
   renameSync(`${path}.tmp`, path)
   let pushed: boolean | null = null
@@ -308,7 +317,7 @@ async function add(pos: string[], p: Parsed, json: boolean): Promise<number> {
   }
   const result = { ok: true, source: s.name, id, path, pushed }
   if (json) console.log(JSON.stringify(result))
-  else console.log(`Queued ${s.name}/jobs/${id}.md${pushed ? " and pushed it" : ""}. The station runs it within 5 minutes of it falling due.`)
+  else console.log(`Queued ${tilde(path)}${pushed ? " and pushed it" : ""}. The station runs it within 5 minutes of it falling due; reports go in ${tilde(join(runsDir(s), id))}/.`)
   return 0
 }
 
@@ -532,3 +541,90 @@ async function uninstall(p: Parsed, json: boolean): Promise<number> {
   else console.log(`Removed ${plan.label}. Jobs and reports are still in place; \`install --apply\` brings the dispatcher back.`)
   return 0
 }
+
+// ---- the station heartbeat ------------------------------------------------------
+
+async function heartbeat(pos: string[], flags: Map<string, string>, json: boolean): Promise<number> {
+  const [action, arg] = pos
+  const cfg = loadConfig()
+  const stored = cfg.scheduler ?? {}
+  const current = stored.heartbeat
+  const host = stationName()
+  if (!action) {
+    const last = readLastTick()?.heartbeat ?? null
+    if (json) console.log(JSON.stringify({ ok: true, set: !!current, ...(current ? { host: new URL(current.url).host, setAt: current.setAt } : {}), last }))
+    else if (!current) {
+      console.log("No heartbeat set. Nothing outside this machine notices if it stops ticking.")
+      if (cfg.uptimeKuma) console.log(`Set it up in your Uptime Kuma (${cfg.uptimeKuma.url}): spinuptui scheduler heartbeat setup --plan`)
+      else {
+        console.log("Make a Push monitor in Uptime Kuma (on another machine; heartbeat interval 900s), then:")
+        console.log("  spinuptui scheduler heartbeat set '<its push URL>'")
+      }
+    } else {
+      console.log(`Heartbeat: pings ${new URL(current.url).host} at the end of every dispatcher tick (set ${current.setAt.slice(0, 10)}).`)
+      console.log(last ? `Last ping: ${last.ok ? "accepted" : `failed (${last.error})`}, status ${last.status}.` : "No dispatcher tick has pinged it yet.")
+      const pager = pagerProblem(cfg)
+      if (pager) console.log(`Pings say "down" right now: ${pager}.`)
+    }
+    return 0
+  }
+  if (action === "setup") return heartbeatSetup(flags, json)
+  if (action === "set") {
+    if (!arg) return fail(json, "usage", "Usage: spinuptui scheduler heartbeat set '<kuma-push-url>'")
+    const r = await connectHeartbeat(arg, host)
+    if (!r.ok) return fail(json, "ping_failed", r.message, r.remedy ? `${r.remedy} Quote the URL: it contains ? and &.` : undefined)
+    return heartbeatSaved(json, "set", r.status)
+  }
+  if (action === "test") {
+    if (!current) return fail(json, "not_set", "No heartbeat set to test.")
+    const t = tickHeartbeat(0, [], pagerProblem(cfg))
+    const r = await sendHeartbeat(current.url, t.status, `${host}: test ping (${t.msg})`)
+    if (!r.ok) return fail(json, "ping_failed", `Kuma didn't take the ping: ${r.error}`, "Check that the monitor is active and that this machine can reach Kuma.")
+    if (json) console.log(JSON.stringify({ ok: true, action, status: t.status }))
+    else console.log(`Kuma took the ping (status ${t.status}).${t.status === "down" ? ` It says "down" because ${pagerProblem(cfg)}.` : ""}`)
+    return 0
+  }
+  if (action === "remove") {
+    if (!current) return fail(json, "not_set", "No heartbeat set.")
+    await removeHeartbeat()
+    if (json) console.log(JSON.stringify({ ok: true, removed: true }))
+    else console.log("Removed. Pause or delete the monitor in Kuma too, or it will report this station as down.")
+    return 0
+  }
+  return fail(json, "usage", "Usage: spinuptui scheduler heartbeat [setup --plan|--apply | set '<kuma-push-url>' | test | remove]")
+}
+
+function heartbeatSaved(json: boolean, action: string, status: "up" | "down", extra: Record<string, unknown> = {}, lead = "Saved. Kuma took the ping"): number {
+  const dispatcher = !!loadConfig().scheduler?.dispatcher
+  if (json) console.log(JSON.stringify({ ok: true, action, status, dispatcher, ...extra }))
+  else {
+    console.log(`${lead} (status ${status}).`)
+    if (status === "down") console.log(`It says "down" because ${pagerProblem()}. Fix that and the next tick reports "up".`)
+    console.log(dispatcher ? "Every dispatcher tick pings it from now on." : "This machine has no dispatcher yet, so nothing pings it until you install one: spinuptui scheduler install --plan")
+  }
+  return 0
+}
+
+async function heartbeatSetup(flags: Map<string, string>, json: boolean): Promise<number> {
+  const apply = flags.has("--apply")
+  if (apply === flags.has("--plan")) return fail(json, "usage", "Pass --plan to see what would be created in Kuma, or --apply to create it.")
+  const host = stationName()
+  const loaded = await loadStationPlan(host, flags.get("--notify") || undefined)
+  if (!loaded.ok) return fail(json, "kuma_failed", loaded.message, loaded.remedy)
+  const plan = loaded.plan
+  if (!plan.existing && plan.needChoice) return fail(json, "choose_notification", plan.needChoice, "e.g. spinuptui scheduler heartbeat setup --plan --notify \"<name>\"")
+  const { steps, notes } = stationPlanText(plan)
+  if (!apply) {
+    if (json) console.log(JSON.stringify({ ok: true, applied: false, kuma: plan.kumaUrl, monitor: plan.name, existing: plan.existing?.id ?? null, notifications: plan.chosen.map((n) => n.name), steps, notes }))
+    else {
+      console.log("Plan:")
+      steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`))
+      for (const n of notes) console.log(`\n${n}`)
+      console.log("\nRun with --apply to do it.")
+    }
+    return 0
+  }
+  const r = await applyStationPlan(plan, host)
+  if (!r.ok) return fail(json, "setup_failed", r.message, r.remedy)
+  return heartbeatSaved(json, "setup", r.status, { monitorId: r.monitorId, created: r.created !== null }, `${r.created ? `Created "${plan.name}" (#${r.created}) and` : `Reused "${plan.name}" and`} sent the first ping`)
+}

package/src/lib/heartbeat.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test"
+import type { AppConfig } from "../config.ts"
+import { chooseNotifications, pagerProblem, parsePushUrl, pingUrl, sendHeartbeat, stationMonitorPayload, tickHeartbeat } from "./heartbeat.ts"
+
+const PUSH = "https://kuma.example.com/api/push/AbC123?status=up&msg=OK&ping="
+
+describe("push URLs", () => {
+  test("accepts Kuma's push URL with or without its query", () => {
+    expect(parsePushUrl(PUSH)?.toString()).toBe("https://kuma.example.com/api/push/AbC123")
+    expect(parsePushUrl("https://kuma.example.com/api/push/AbC123")).not.toBeNull()
+    expect(parsePushUrl("https://kuma.example.com/dashboard/12")).toBeNull()
+    expect(parsePushUrl("ftp://kuma.example.com/api/push/x")).toBeNull()
+    expect(parsePushUrl("not a url")).toBeNull()
+  })
+
+  test("each ping sets status, msg and ping", () => {
+    const u = new URL(pingUrl(PUSH, "down", "pager broken", 1234.6))
+    expect(u.searchParams.get("status")).toBe("down")
+    expect(u.searchParams.get("msg")).toBe("pager broken")
+    expect(u.searchParams.get("ping")).toBe("1235")
+  })
+})
+
+describe("what a tick reports", () => {
+  test("up, with what ran and the first problem", () => {
+    expect(tickHeartbeat(0, [], null)).toEqual({ status: "up", msg: "tick ok, nothing due" })
+    expect(tickHeartbeat(2, ["git push failed"], null)).toEqual({ status: "up", msg: "tick ok, 2 jobs ran; 1 problem: git push failed" })
+  })
+
+  test("down when the pager is broken", () => {
+    expect(tickHeartbeat(1, [], "Beacon's last page failed (HTTP 401)").status).toBe("down")
+  })
+
+  test("pagerProblem: no channel, or the last page failed", () => {
+    const none = { beacon: null } as unknown as AppConfig
+    const one = { beacon: { defaultChannel: "pager", channels: { pager: { type: "telegram", botToken: "t", chatId: "1" } } } } as unknown as AppConfig
+    const entry = (ok: boolean) => ({ at: "", channel: "pager", ok, parts: 1, chars: 1, preview: "", ...(ok ? {} : { error: "HTTP 401" }) })
+    expect(pagerProblem(none, null)).toMatch(/isn't set up/)
+    expect(pagerProblem(one, null)).toBeNull()
+    expect(pagerProblem(one, entry(true))).toBeNull()
+    expect(pagerProblem(one, entry(false))).toMatch(/HTTP 401/)
+  })
+})
+
+describe("sendHeartbeat against a fake Kuma", () => {
+  test("ok, Kuma's refusal, and an unreachable host", async () => {
+    const seen: URL[] = []
+    const server = Bun.serve({
+      port: 0,
+      fetch(req) {
+        const u = new URL(req.url)
+        seen.push(u)
+        return Response.json(u.pathname.endsWith("/good") ? { ok: true } : { ok: false, msg: "Monitor not found or not active." })
+      },
+    })
+    try {
+      const base = `http://127.0.0.1:${server.port}/api/push`
+      expect(await sendHeartbeat(`${base}/good`, "up", "tick ok", 10)).toEqual({ ok: true, status: "up", msg: "tick ok" })
+      expect(seen[0]!.searchParams.get("status")).toBe("up")
+      const bad = await sendHeartbeat(`${base}/gone`, "up", "tick ok")
+      expect(bad.ok).toBe(false)
+      expect(bad.error).toBe("Monitor not found or not active.")
+    } finally {
+      server.stop(true)
+    }
+    expect((await sendHeartbeat("http://127.0.0.1:1/api/push/x", "up", "m")).ok).toBe(false)
+  })
+})
+
+describe("station monitor setup", () => {
+  const n = (id: number, name: string, isDefault = false) => ({ id, name, active: true, isDefault })
+
+  test("who it alerts", () => {
+    expect(chooseNotifications([n(1, "Pager")]).chosen.map((x) => x.id)).toEqual([1])
+    expect(chooseNotifications([n(1, "Email"), n(2, "Telegram", true)]).chosen.map((x) => x.id)).toEqual([2])
+    expect(chooseNotifications([n(1, "Email"), n(2, "Telegram")]).needChoice).toMatch(/--notify/)
+    expect(chooseNotifications([n(1, "Email"), n(2, "Telegram")], "telegram").chosen.map((x) => x.id)).toEqual([2])
+    expect(chooseNotifications([n(1, "Email")], "2").needChoice).toMatch(/No active Kuma notification/)
+    expect(chooseNotifications([]).needChoice).toMatch(/no active notifications/)
+  })
+
+  test("a push monitor that waits three ticks", () => {
+    const p = stationMonitorPayload("SpinupTUI station: x", "tok")
+    expect(p).toMatchObject({ type: "push", pushToken: "tok", interval: 900, maxretries: 0 })
+  })
+})