spinuptui 1.2.0 → 1.3.0-alpha.1

package/CHANGELOG.md

@@ -11,11 +11,27 @@ version; such changes are called out here.
 
 ## [Unreleased]
 
+## [1.3.0-alpha.1] - 2026-10-21
+
+A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew stay on 1.2.0. It continues `1.2.0-alpha.1` under a new number, because stable 1.2.0 shipped without the modules: it has Beacon and the Modules tab (see [1.2.0-alpha.1]) plus everything in [1.2.0]. The stable 1.3.0 will roll these notes up with the next modules.
+
 ## [1.2.0] - 2026-10-21
 
 ### Added
 - **Take a server's sites offline, and bring them back.** For a vulnerability you can't patch yet: `spinuptui offline <server>… --yes` (or **Take all sites offline** in the `a` menu) disables every site on the server through SpinupWP, so nginx stops answering for them and no request reaches PHP. Files, databases and certificates are untouched. `spinuptui online <server>… --yes` re-enables exactly the sites it took down, never one disabled for another reason, and a re-run finishes anything that failed. Without `--yes` both print the plan. One site at a time works too: `O` on a site, or `--site <domain>` on either command; the confirmation says how many other sites on its server stay up, since PHP is shared. Uptime Kuma monitors for those sites sit in a maintenance window until they're back, and offline servers are flagged `⏻ off` in the Servers list and on the Overview. See [docs/taking-sites-offline.md](docs/taking-sites-offline.md).
 
+## [1.2.0-alpha.1] - 2026-10-17
+
+A pre-release, published on npm's `next` tag (`bun add -g spinuptui@next --no-cache`). `@latest` and Homebrew stay on 1.1.2. The modules' stable release is 1.3.0, which will roll these notes up with the next modules; 1.2.0 shipped without them.
+
+### Added
+- **Beacon: `spinuptui beacon send` pages you on Telegram.** One command any script, cron job or agent can use instead of its own `curl` to the Telegram API. Messages go out as plain text with link previews off; anything over Telegram's 4096-character limit is split into numbered parts instead of being rejected; sends are retried (honoring Telegram's rate-limit hints) and logged. Exit codes tell a caller what happened: `0` delivered, `1` not configured (nothing attempted), `2` delivery failed. No Telegram bot yet? `spinuptui beacon setup` walks you through making one with @BotFather, checks the token, and finds your chat by itself once you message the bot. No digging for a chat ID. It saves nothing until a test message has arrived. Scripts can use `spinuptui beacon add telegram <name> --env-file <path>` instead. `beacon test`, `beacon status` and `beacon remove` round it out. See [docs/beacon.md](docs/beacon.md).
+- **A Modules tab (`6`).** Everything SpinupTUI can keep doing after you close it, with its status on this machine and set up from the same place: select Beacon and press `⏎` for the guided Telegram setup, or `t` for a test page. Modules still on the way (Scheduler, Sentinel, Samurai) are listed as coming soon.
+- **`spinuptui modules`** lists SpinupTUI's modules (the features that keep working after the TUI is closed) and their status. Beacon is the first; the module contract is in [docs/2026-10-16_beacon-and-module-contract-spec.md](docs/2026-10-16_beacon-and-module-contract-spec.md).
+
+### Fixed
+- **The update hint understands pre-releases.** Someone running a pre-release (say `1.2.0-alpha.1`) is now told when the matching stable release ships; before, the two counted as the same version.
+
 ## [1.1.2] - 2026-10-15
 
 ### Fixed
@@ -1490,8 +1506,10 @@ Initial tagged release.
 ### Notes
 - Read-only release: works with a SpinupWP **Read Only** API token.
 
-[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v1.3.0-alpha.1...HEAD
+[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
+[1.2.0-alpha.1]: https://github.com/mwender/spinupwp-tui/compare/v1.1.2...v1.2.0-alpha.1
 [1.1.2]: https://github.com/mwender/spinupwp-tui/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/mwender/spinupwp-tui/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/mwender/spinupwp-tui/compare/v1.0.0...v1.1.0

package/README.md

@@ -77,6 +77,11 @@
   register/recalibrate/remove it — plus a cache/outage doctor and alert
   wiring. → [docs/site-monitoring.md](docs/site-monitoring.md) ·
   [docs/uptime-kuma.md](docs/uptime-kuma.md)
+- **Modules** (`6`, pre-release: `bun add -g spinuptui@next --no-cache`) — the parts of SpinupTUI that keep working after you close it,
+  each set up from the same screen. First up, **Beacon**: `spinuptui beacon send`
+  pages you on Telegram from any cron job, watcher or agent, with retries, long
+  messages split instead of dropped, and a send log. A guided setup creates the
+  bot connection for you. → [docs/beacon.md](docs/beacon.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
@@ -334,7 +339,7 @@ These can be set in `config.json` or via an environment variable:
 
 | Key | Action |
 | --- | --- |
-| `1`…`5` | Switch tabs: Dashboard · Servers · Stacks · Search · Events |
+| `1`…`6` | Switch tabs: Dashboard · Servers · Stacks · Search · Events · Modules |
 | `↑`/`↓` or `j`/`k` | Move selection |
 | `Enter` / `→` | Drill in (server → its sites) |
 | `←` / `Esc` | Go back / collapse |
@@ -370,6 +375,8 @@ These can be set in `config.json` or via an environment variable:
 | `w` | Open the selected server/site in the SpinupWP web app |
 | `/` | Jump to global search |
 | `A` | Accounts — switch, add, rename, or remove SpinupWP accounts (from anywhere) |
+| `⏎` / `s` | Set up the selected module — Beacon opens its guided Telegram setup (Modules tab) |
+| `t` | Send a test page through Beacon (Modules tab, once Beacon is set up) |
 | `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.2.0",
+  "version": "1.3.0-alpha.1",
   "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -103,6 +103,27 @@ export interface AppConfig {
   // running version with no notes shown — nothing meaningful to announce). A
   // mismatch against the running version is what triggers the overlay.
   lastSeenVersion: string | null
+  // Beacon's notification channels (see lib/beacon.ts and
+  // docs/2026-10-16_beacon-and-module-contract-spec.md). Machine-level like the
+  // Kuma login: one operator's pager serves every account. Holds bot tokens, so
+  // it relies on the file's 600 mode. The env channel (SPINUPTUI_BEACON_*) is
+  // resolved in lib/beacon.ts, not here, so this is only what's stored.
+  beacon: BeaconStored | null
+}
+
+export interface BeaconTelegramChannel {
+  type: "telegram"
+  botToken: string
+  chatId: string
+}
+
+// A union so later transports (Slack, ntfy, a client-facing Basecamp channel)
+// are additive.
+export type BeaconChannel = BeaconTelegramChannel
+
+export interface BeaconStored {
+  defaultChannel?: string
+  channels?: Record<string, BeaconChannel>
 }
 
 export interface ServerProviderRef {
@@ -202,6 +223,7 @@ export interface StoredConfig {
   uptimeKuma?: UptimeKumaConn
   kumaMonitors?: Record<string, KumaMonitorRef>
   lastSeenVersion?: string
+  beacon?: BeaconStored
 }
 
 // ---- Accounts (profiles) -------------------------------------------------------
@@ -487,6 +509,7 @@ export function loadConfig(): AppConfig {
     })(),
     kumaMonitors: stored.kumaMonitors ?? {},
     lastSeenVersion: stored.lastSeenVersion?.trim() || null,
+    beacon: stored.beacon ?? null,
   }
 }
 

package/src/index.tsx

@@ -23,6 +23,7 @@ import { resolveIncidents } from "./lib/cliIncidents.ts"
 import { resolveSiblings } from "./lib/cliSiblings.ts"
 import { execSshCommand } from "./lib/sshExec.ts"
 import { runPullFiles, runPullDb } from "./lib/cliPull.ts"
+import { runBeacon, runModules } from "./lib/cliBeacon.ts"
 import { runOffline, runOnline } from "./lib/cliOffline.ts"
 
 const args = process.argv.slice(2)
@@ -102,6 +103,17 @@ Usage:
   spinuptui online <server>… | --all | --site <domain> --yes
                        Bring back exactly the sites \`offline\` took down.
                        Servers are matched by exact name, IP or id.
+  spinuptui beacon setup  Guided Telegram setup: make a bot, find your chat,
+                       send a test (interactive; also in the app's Modules tab, 6)
+  spinuptui beacon send [--to <channel>] [--silent] [<message> | -]
+                       Page yourself through Beacon (Telegram). Reads the
+                       message from stdin when it's \`-\` or absent. Exit 0 sent,
+                       1 not configured / usage, 2 delivery failed.
+  spinuptui beacon add telegram <name> --env-file <path> [--default]
+                       Add a channel from a file holding TELEGRAM_BOT_TOKEN and
+                       TELEGRAM_CHAT_ID; sends a test message before saving.
+  spinuptui beacon test | status | remove <name>
+  spinuptui modules    List SpinupTUI's modules and their status (--json)
   spinuptui --version  Print the version
   spinuptui --help     Show this help
 
@@ -293,6 +305,14 @@ if (command === "online") {
   process.exit(await runOnline(args.slice(args.indexOf("online") + 1)))
 }
 
+if (command === "beacon") {
+  process.exit(await runBeacon(args.slice(args.indexOf("beacon") + 1)))
+}
+
+if (command === "modules") {
+  process.exit(await runModules(args.slice(1)))
+}
+
 // `spinuptui login` forces the onboarding wizard even when a token already exists,
 // so the token can be (re)saved to the config file for global use.
 const forceLogin = command === "login"

package/src/lib/appUpdate.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test"
+import { isNewer } from "./appUpdate.ts"
+
+test("plain versions", () => {
+  expect(isNewer("1.2.0", "1.1.2")).toBe(true)
+  expect(isNewer("1.1.2", "1.2.0")).toBe(false)
+  expect(isNewer("1.10.0", "1.9.9")).toBe(true)
+  expect(isNewer("1.2.0", "1.2.0")).toBe(false)
+})
+
+test("a release outranks its pre-releases", () => {
+  expect(isNewer("1.2.0", "1.2.0-alpha.1")).toBe(true)
+  expect(isNewer("1.2.0-alpha.1", "1.2.0")).toBe(false)
+  expect(isNewer("1.2.0-alpha.1", "1.1.2")).toBe(true)
+})
+
+test("pre-release ordering", () => {
+  expect(isNewer("1.2.0-alpha.2", "1.2.0-alpha.1")).toBe(true)
+  expect(isNewer("1.2.0-alpha.10", "1.2.0-alpha.9")).toBe(true)
+  expect(isNewer("1.2.0-beta.1", "1.2.0-alpha.5")).toBe(true)
+  expect(isNewer("1.2.0-alpha.1", "1.2.0-alpha")).toBe(true)
+})
+
+test("unparseable never nags", () => {
+  expect(isNewer("garbage", "1.0.0")).toBe(false)
+})

package/src/lib/appUpdate.ts

@@ -35,21 +35,47 @@ function cachePath(): string {
   return join(configDir(), "update-check.json")
 }
 
-// Parse "v1.2.3" / "1.2.3" → [1,2,3]; null when it doesn't look like a version.
-function parseVersion(s: string): [number, number, number] | null {
-  const m = s.trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)\.(\d+)/)
-  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+// Parse "v1.2.3" / "1.2.3" / "1.2.3-alpha.1" → numbers + pre-release tag; null
+// when it doesn't look like a version.
+function parseVersion(s: string): { nums: [number, number, number]; pre: string | null } | null {
+  const m = s.trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/)
+  return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null
+}
+
+// SemVer pre-release precedence: dot-separated identifiers compared left to
+// right, numeric ones numerically and below alphanumeric ones; a shorter set of
+// otherwise-equal identifiers sorts first.
+function comparePre(a: string, b: string): number {
+  const x = a.split(".")
+  const y = b.split(".")
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    if (x[i] === undefined) return -1
+    if (y[i] === undefined) return 1
+    const nx = /^\d+$/.test(x[i]!)
+    const ny = /^\d+$/.test(y[i]!)
+    if (nx && ny) {
+      const d = Number(x[i]) - Number(y[i])
+      if (d) return d
+    } else if (nx !== ny) return nx ? -1 : 1
+    else if (x[i] !== y[i]) return x[i]! < y[i]! ? -1 : 1
+  }
+  return 0
 }
 
 // Strictly-newer comparison (latest > current). Unparseable → false (never nag).
-function isNewer(latest: string, current: string): boolean {
+// A release outranks its own pre-releases, so someone on 1.2.0-alpha.1 is told
+// when 1.2.0 ships.
+export function isNewer(latest: string, current: string): boolean {
   const a = parseVersion(latest)
   const b = parseVersion(current)
   if (!a || !b) return false
   for (let i = 0; i < 3; i++) {
-    if (a[i] !== b[i]) return a[i] > b[i]
+    if (a.nums[i] !== b.nums[i]) return a.nums[i]! > b.nums[i]!
   }
-  return false
+  if (a.pre === b.pre) return false
+  if (a.pre === null) return true
+  if (b.pre === null) return false
+  return comparePre(a.pre, b.pre) > 0
 }
 
 function readCache(): CacheFile | null {

package/src/lib/beacon.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test"
+import { beaconSend, MAX_PARTS, maskToken, parseEnvFile, resolveBeacon, splitMessage, TELEGRAM_LIMIT, type ResolvedBeacon } from "./beacon.ts"
+
+const pager: ResolvedBeacon = {
+  channels: [{ name: "pager", channel: { type: "telegram", botToken: "123:SECRET", chatId: "-1001" }, env: false }],
+  defaultChannel: "pager",
+}
+
+function fakeFetch(responses: Array<{ status: number; body: unknown } | Error>) {
+  const calls: Array<{ url: string; params: URLSearchParams }> = []
+  const impl = async (url: string, init?: RequestInit) => {
+    calls.push({ url, params: init?.body as URLSearchParams })
+    const next = responses.shift() ?? { status: 200, body: { ok: true, result: {} } }
+    if (next instanceof Error) throw next
+    return new Response(JSON.stringify(next.body), { status: next.status })
+  }
+  return { impl, calls }
+}
+
+const noWait = async () => {}
+
+describe("resolveBeacon", () => {
+  test("a lone stored channel is the default", () => {
+    const r = resolveBeacon({ channels: { pager: { type: "telegram", botToken: "1:a", chatId: "2" } } }, {})
+    expect(r.defaultChannel).toBe("pager")
+  })
+
+  test("env channel is added and becomes default unless one is chosen", () => {
+    const env = { SPINUPTUI_BEACON_TELEGRAM_TOKEN: "9:z", SPINUPTUI_BEACON_TELEGRAM_CHAT_ID: "5" }
+    const stored = { channels: { pager: { type: "telegram" as const, botToken: "1:a", chatId: "2" } } }
+    expect(resolveBeacon(stored, env).defaultChannel).toBe("env")
+    expect(resolveBeacon({ ...stored, defaultChannel: "pager" }, env).defaultChannel).toBe("pager")
+    expect(resolveBeacon(stored, env).channels.find((c) => c.name === "env")?.env).toBe(true)
+  })
+
+  test("two stored channels and no choice means no default", () => {
+    const ch = { type: "telegram" as const, botToken: "1:a", chatId: "2" }
+    expect(resolveBeacon({ channels: { a: ch, b: ch } }, {}).defaultChannel).toBeNull()
+  })
+})
+
+describe("splitMessage", () => {
+  test("short text is untouched", () => {
+    expect(splitMessage("hello")).toEqual(["hello"])
+  })
+
+  test("long text splits on lines, numbered, each under the limit", () => {
+    const text = Array.from({ length: 300 }, (_, i) => `line ${i} ${"x".repeat(40)}`).join("\n")
+    const parts = splitMessage(text)
+    expect(parts.length).toBeGreaterThan(1)
+    parts.forEach((p, i) => {
+      expect(p.length).toBeLessThanOrEqual(TELEGRAM_LIMIT)
+      expect(p.startsWith(`(${i + 1}/${parts.length}) `)).toBe(true)
+    })
+    // Nothing lost or reordered.
+    expect(parts.map((p) => p.replace(/^\(\d+\/\d+\) /, "")).join("\n")).toBe(text)
+  })
+
+  test("a single huge line is hard-split", () => {
+    const parts = splitMessage("y".repeat(9000))
+    expect(parts.length).toBe(3)
+    parts.forEach((p) => expect(p.length).toBeLessThanOrEqual(TELEGRAM_LIMIT))
+  })
+
+  test("beyond the part cap the last part is truncated with a marker", () => {
+    const parts = splitMessage("z".repeat(4000 * 8))
+    expect(parts.length).toBe(MAX_PARTS)
+    expect(parts[MAX_PARTS - 1]).toContain("[truncated:")
+    parts.forEach((p) => expect(p.length).toBeLessThanOrEqual(TELEGRAM_LIMIT))
+  })
+})
+
+describe("parseEnvFile", () => {
+  test("handles export, quotes and comments", () => {
+    const env = parseEnvFile(`# creds\nexport TELEGRAM_BOT_TOKEN="1:abc"\nTELEGRAM_CHAT_ID='-100' \nOTHER=x # note\n`)
+    expect(env).toEqual({ TELEGRAM_BOT_TOKEN: "1:abc", TELEGRAM_CHAT_ID: "-100", OTHER: "x" })
+  })
+})
+
+test("maskToken keeps only the bot id", () => {
+  expect(maskToken("123456:AAE-secret")).toBe("123456:…")
+})
+
+describe("beaconSend", () => {
+  test("sends plain text with previews off", async () => {
+    const f = fakeFetch([])
+    const r = await beaconSend(pager, "site down", { fetchImpl: f.impl, wait: noWait, log: false })
+    expect(r).toEqual({ ok: true, channel: "pager", parts: 1, chars: 9 })
+    expect(f.calls[0]!.params.get("disable_web_page_preview")).toBe("true")
+    expect(f.calls[0]!.params.has("parse_mode")).toBe(false)
+    expect(f.calls[0]!.params.has("disable_notification")).toBe(false)
+  })
+
+  test("--silent sets disable_notification", async () => {
+    const f = fakeFetch([])
+    await beaconSend(pager, "digest", { silent: true, fetchImpl: f.impl, wait: noWait, log: false })
+    expect(f.calls[0]!.params.get("disable_notification")).toBe("true")
+  })
+
+  test("retries a 429 and a network error, then succeeds", async () => {
+    const f = fakeFetch([{ status: 429, body: { ok: false, parameters: { retry_after: 1 } } }, new Error("socket hang up")])
+    const r = await beaconSend(pager, "x", { fetchImpl: f.impl, wait: noWait, log: false })
+    expect(r.ok).toBe(true)
+    expect(f.calls.length).toBe(3)
+  })
+
+  test("a 400 is not retried and is a delivery failure", async () => {
+    const f = fakeFetch([{ status: 400, body: { ok: false, description: "Bad Request: chat not found" } }])
+    const r = await beaconSend(pager, "x", { fetchImpl: f.impl, wait: noWait, log: false })
+    expect(f.calls.length).toBe(1)
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.reason).toBe("delivery_failed")
+      expect(r.message).toContain("chat not found")
+    }
+  })
+
+  test("network errors never leak the token", async () => {
+    const f = fakeFetch([new Error("fail https://api.telegram.org/bot123:SECRET/sendMessage"), new Error("x"), new Error("x")])
+    const r = await beaconSend(pager, "x", { fetchImpl: f.impl, wait: noWait, log: false })
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.message).not.toContain("SECRET")
+  })
+
+  test("not configured and empty messages attempt nothing", async () => {
+    const f = fakeFetch([])
+    const none = await beaconSend({ channels: [], defaultChannel: null }, "x", { fetchImpl: f.impl, log: false })
+    const empty = await beaconSend(pager, "   ", { fetchImpl: f.impl, log: false })
+    expect(!none.ok && none.reason).toBe("not_configured")
+    expect(!empty.ok && empty.reason).toBe("empty_message")
+    expect(f.calls.length).toBe(0)
+  })
+
+  test("a multi-part send stops at the first failed part", async () => {
+    const f = fakeFetch([{ status: 200, body: { ok: true } }, { status: 403, body: { ok: false, description: "Forbidden" } }])
+    const r = await beaconSend(pager, "q".repeat(9000), { fetchImpl: f.impl, wait: noWait, log: false })
+    expect(!r.ok && r.partsSent).toBe(1)
+    expect(f.calls.length).toBe(2)
+  })
+})