spinuptui 1.1.2 → 1.2.0-alpha.1

package/src/lib/cliBeacon.ts

@@ -0,0 +1,290 @@
+// `spinuptui beacon …` and `spinuptui modules` — the CLI over lib/beacon.ts and
+// the module registry.
+//
+// Exit codes for `beacon send` are a contract callers branch on: 0 delivered;
+// 1 usage error or not configured (nothing was attempted, so a caller may fall
+// back to its own sender); 2 delivery failed after retries (Beacon tried — a
+// caller must not resend through another path, or a partial multi-part send
+// would be duplicated).
+
+import { readFileSync } from "node:fs"
+import { loadConfig, saveConfig, type BeaconStored } from "../config.ts"
+import { beaconFromConfig, beaconSend, maskChatId, maskToken, parseEnvFile, pickChannel, telegramGetMe, testMessage } from "./beacon.ts"
+import {
+  BOTFATHER_STEPS,
+  botLink,
+  channelExists,
+  discoverChat,
+  saveBeaconChannel,
+  sendConnectedMessage,
+  setupChannelName,
+  verifyBotToken,
+} from "./beaconSetup.ts"
+import { confirm, PromptCancelled, readLine } from "./prompt.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"])
+
+function parse(list: string[]): { positionals: string[]; flags: Map<string, string>; rest: string | null } {
+  const dash = list.indexOf("--")
+  const head = dash === -1 ? list : list.slice(0, dash)
+  const positionals: string[] = []
+  const flags = new Map<string, string>()
+  for (let i = 0; i < head.length; i++) {
+    const a = head[i]!
+    if (a.startsWith("-") && a !== "-") {
+      if (VALUE_FLAGS.has(a)) {
+        flags.set(a, head[i + 1] ?? "")
+        i++
+      } else flags.set(a, "")
+      continue
+    }
+    positionals.push(a)
+  }
+  return { positionals, flags, rest: dash === -1 ? null : list.slice(dash + 1).join(" ") }
+}
+
+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
+}
+
+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 remove <name>
+  spinuptui beacon test [--to <channel>] [--json]
+  spinuptui beacon status [--json]`
+
+function badValue(flags: Map<string, string>, name: string): boolean {
+  if (!flags.has(name)) return false
+  const v = flags.get(name)!
+  return !v || v.startsWith("-")
+}
+
+export async function runBeacon(argv: string[]): Promise<number> {
+  const { positionals, flags, rest } = parse(argv)
+  const json = flags.has("--json")
+  const sub = positionals[0]
+  for (const f of VALUE_FLAGS) if (badValue(flags, f)) return fail(json, "usage", `${f} needs a value.\n${USAGE}`)
+
+  if (sub === "setup") return setup(positionals.slice(1))
+  if (sub === "send") return send(positionals.slice(1), flags, rest, json)
+  if (sub === "test") return test(flags, json)
+  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)
+  return fail(json, "usage", USAGE)
+}
+
+async function send(pos: string[], flags: Map<string, string>, rest: string | null, json: boolean): Promise<number> {
+  // The message: everything after `--`, else the positionals, else stdin when it
+  // is `-` or absent and stdin isn't a terminal.
+  let text: string
+  if (rest !== null) text = rest
+  else if (pos.length > 0 && !(pos.length === 1 && pos[0] === "-")) text = pos.join(" ")
+  else if (pos[0] === "-" || !process.stdin.isTTY) text = await Bun.stdin.text()
+  else return fail(json, "usage", `No message: pass it as an argument or pipe it on stdin.\n${USAGE}`)
+  text = text.replace(/\s+$/, "")
+
+  const result = await beaconSend(beaconFromConfig(loadConfig()), text, {
+    to: flags.get("--to") ?? null,
+    silent: flags.has("--silent"),
+  })
+  if (json) console.log(JSON.stringify(result))
+  else if (!result.ok) {
+    console.error(result.message)
+    if (result.remedy) console.error(result.remedy)
+  }
+  if (result.ok) return 0
+  return result.reason === "delivery_failed" ? 2 : 1
+}
+
+async function test(flags: Map<string, string>, json: boolean): Promise<number> {
+  const result = await beaconSend(beaconFromConfig(loadConfig()), testMessage(), { to: flags.get("--to") ?? null })
+  if (json) console.log(JSON.stringify(result))
+  else if (result.ok) console.log(`Test message sent via ${result.channel}.`)
+  else {
+    console.error(result.message)
+    if (result.remedy) console.error(result.remedy)
+  }
+  if (result.ok) return 0
+  return result.reason === "delivery_failed" ? 2 : 1
+}
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/
+
+async function add(pos: string[], flags: Map<string, string>, json: boolean): Promise<number> {
+  const [type, name] = pos
+  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.`)
+
+  // Secrets come from a file or the environment, never argv (where `ps` shows them).
+  let source: Record<string, string | undefined> = process.env
+  const envFile = flags.get("--env-file")
+  if (envFile) {
+    try {
+      source = parseEnvFile(readFileSync(envFile, "utf8"))
+    } catch (err) {
+      return fail(json, "env_file_unreadable", `Couldn't read ${envFile}: ${(err as Error).message}`)
+    }
+  }
+  const botToken = source.TELEGRAM_BOT_TOKEN?.trim()
+  const chatId = source.TELEGRAM_CHAT_ID?.trim()
+  if (!botToken || !chatId) {
+    return fail(
+      json,
+      "missing_credentials",
+      `TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID must both be set ${envFile ? `in ${envFile}` : "in the environment"}.`,
+      "Put them in a KEY=VALUE file and pass --env-file <path>.",
+    )
+  }
+
+  // Credentials that can't deliver are never stored.
+  const me = await telegramGetMe(botToken)
+  if (!me.ok) {
+    if (json) console.log(JSON.stringify({ ok: false, reason: "token_rejected", message: `Telegram rejected the bot token: ${me.error}` }))
+    else console.error(`Telegram rejected the bot token: ${me.error}`)
+    return 2
+  }
+  const channel = { type: "telegram" as const, botToken, chatId }
+  if (!flags.has("--no-test")) {
+    const r = await sendConnectedMessage(name, channel)
+    if (!r.ok) {
+      if (json) console.log(JSON.stringify({ ...r, message: `Not saved. ${r.message}` }))
+      else console.error(`Not saved. ${r.message}`)
+      return 2
+    }
+  }
+
+  const previousDefault = loadConfig().beacon?.defaultChannel
+  const { isDefault } = await saveBeaconChannel(name, channel, flags.has("--default"))
+  const summary = {
+    ok: true,
+    channel: name,
+    bot: me.username ? `@${me.username}` : maskToken(botToken),
+    chat: maskChatId(chatId),
+    default: isDefault ? name : previousDefault,
+    tested: !flags.has("--no-test"),
+  }
+  if (json) console.log(JSON.stringify(summary))
+  else console.log(`Saved channel "${name}" (${summary.bot} → chat ${summary.chat})${isDefault ? ", now the default" : ""}.`)
+  return 0
+}
+
+// The guided path for someone without a bot yet. Interactive only: scripts and
+// provisioning use `add --env-file`.
+async function setup(pos: string[]): Promise<number> {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    return fail(false, "needs_terminal", "`beacon setup` is interactive and needs a terminal.", "For scripts, use `spinuptui beacon add telegram <name> --env-file <path>`.")
+  }
+  const name = pos[0] ?? setupChannelName()
+  if (!NAME_RE.test(name) || name === "env") return fail(false, "usage", `"${name}" can't be a channel name (lowercase letters, digits and dashes; "env" is reserved).`)
+  const say = (line = "") => process.stderr.write(line + "\n")
+  try {
+    say("Beacon setup: page yourself on Telegram.")
+    say()
+    if (channelExists(name) && !(await confirm(`A channel named "${name}" already exists. Replace it?`, false))) return 1
+
+    say("1. Create a bot (skip if you already have one):")
+    for (const step of BOTFATHER_STEPS) say(`   · ${step}`)
+    say()
+    let token = ""
+    let username = ""
+    for (let attempt = 0; ; attempt++) {
+      token = (await readLine("2. Paste the bot token (hidden): ", { hidden: true })).trim()
+      const me = await verifyBotToken(token)
+      if (me.ok) {
+        username = me.username ?? ""
+        say(`   ✓ Bot ${username ? `@${username}` : "found"}`)
+        break
+      }
+      say(`   ✗ ${me.error}`)
+      if (attempt >= 2) return 2
+    }
+    say()
+    for (;;) {
+      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)
+      if (!found.ok) {
+        say(`   ✗ ${found.message}`)
+        if (found.reason === "timeout" && (await confirm("   Keep waiting?", true))) continue
+        return found.reason === "cancelled" ? 1 : 2
+      }
+      say(`   ✓ Found: ${found.chat.label} (${found.chat.kind} chat)`)
+      if (!(await confirm("   Page this chat?", true))) continue
+      const channel = { type: "telegram" as const, botToken: token, chatId: found.chat.chatId }
+      const sent = await sendConnectedMessage(name, channel)
+      if (!sent.ok) {
+        say(`   ✗ Couldn't send the test message: ${sent.message}. Nothing was saved.`)
+        return 2
+      }
+      const { isDefault } = await saveBeaconChannel(name, channel, false)
+      say()
+      say(`✓ Saved channel "${name}"${isDefault ? " (the default)" : ""}. A test message is on its way to that chat.`)
+      say(`  Try it: spinuptui beacon send "hello from $(hostname)"`)
+      return 0
+    }
+  } catch (err) {
+    if (err instanceof PromptCancelled) {
+      say("Cancelled; nothing was saved.")
+      return 1
+    }
+    throw err
+  }
+}
+
+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.channels?.[name]) {
+    const resolved = pickChannel(beaconFromConfig(loadConfig()), name)
+    if (!("ok" in resolved) && resolved.env) {
+      return fail(json, "read_only", `"${name}" comes from SPINUPTUI_BEACON_* environment variables; unset them to remove it.`)
+    }
+    return fail(json, "unknown_channel", `No stored Beacon channel named "${name}".`)
+  }
+  const { [name]: _gone, ...channels } = stored.channels
+  const next: BeaconStored = { ...stored, channels }
+  if (next.defaultChannel === name) delete next.defaultChannel
+  await saveConfig({ beacon: next })
+  if (json) console.log(JSON.stringify({ ok: true, removed: name }))
+  else console.log(`Removed channel "${name}".`)
+  return 0
+}
+
+function printStatus(s: ModuleStatus & { name?: string }): void {
+  console.log(`${s.name ?? s.id}: ${s.state} — ${s.summary}`)
+  for (const c of s.checks) console.log(`  ${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`)
+  if (s.remedy) console.log(`  → ${s.remedy}`)
+}
+
+async function status(json: boolean): Promise<number> {
+  const s = await beaconModule.status()
+  if (json) console.log(JSON.stringify({ ok: true, ...s }))
+  else printStatus({ ...s, name: beaconModule.name })
+  return 0
+}
+
+export async function runModules(argv: string[]): Promise<number> {
+  const json = argv.includes("--json")
+  const statuses = await allModuleStatuses()
+  const upcoming = UPCOMING_MODULES.map(({ id, name, summary }) => ({ id, name, about: summary }))
+  if (json) console.log(JSON.stringify({ ok: true, modules: statuses, upcoming }))
+  else {
+    for (const s of statuses) printStatus(s)
+    console.log(`Coming soon: ${upcoming.map((u) => u.name).join(", ")}`)
+  }
+  return 0
+}

package/src/lib/prompt.ts

@@ -0,0 +1,47 @@
+// Minimal line prompts for interactive CLI subcommands (not the TUI). Prompts go
+// to stderr so stdout stays clean. `hidden` reads in raw mode and echoes a dot
+// per character, for secrets: they never appear on screen or in argv.
+
+export class PromptCancelled extends Error {}
+
+export function readLine(question: string, opts: { hidden?: boolean } = {}): Promise<string> {
+  const stdin = process.stdin
+  process.stderr.write(question)
+  return new Promise((resolve, reject) => {
+    let buf = ""
+    const raw = Boolean(stdin.isTTY)
+    if (raw) stdin.setRawMode(true)
+    stdin.resume()
+    const done = (err: Error | null) => {
+      stdin.off("data", onData)
+      if (raw) stdin.setRawMode(false)
+      stdin.pause()
+      process.stderr.write("\n")
+      if (err) reject(err)
+      else resolve(buf)
+    }
+    const onData = (chunk: Buffer) => {
+      for (const ch of chunk.toString("utf8")) {
+        if (ch === "\u0003" || ch === "\u0004") return done(new PromptCancelled("cancelled"))
+        if (ch === "\r" || ch === "\n") return done(null)
+        if (ch === "\u007f" || ch === "\b") {
+          if (buf.length) {
+            buf = buf.slice(0, -1)
+            if (raw) process.stderr.write("\b \b")
+          }
+          continue
+        }
+        if (ch < " ") continue
+        buf += ch
+        if (raw) process.stderr.write(opts.hidden ? "•" : ch)
+      }
+    }
+    stdin.on("data", onData)
+  })
+}
+
+export async function confirm(question: string, defaultYes: boolean): Promise<boolean> {
+  const answer = (await readLine(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase()
+  if (!answer) return defaultYes
+  return answer === "y" || answer === "yes"
+}

package/src/modules/beacon.ts

@@ -0,0 +1,51 @@
+// Beacon's module declaration: the first implementation of the contract.
+
+import { loadConfig } from "../config.ts"
+import { beaconFromConfig, lastSendLogEntry, maskChatId, maskToken } from "../lib/beacon.ts"
+import { moduleStateDir, type ModuleCheck, type ModuleDefinition, type ModuleStatus } from "./contract.ts"
+
+export const beaconModule: ModuleDefinition = {
+  id: "beacon",
+  name: "Beacon",
+  summary: "Tells you when something needs you: one pager for the fleet and every module.",
+  dependsOn: [],
+  configKey: "beacon",
+  stateDir: () => moduleStateDir("beacon"),
+  jobs: [],
+  async status(): Promise<ModuleStatus> {
+    const beacon = beaconFromConfig(loadConfig())
+    if (beacon.channels.length === 0) {
+      return {
+        id: "beacon",
+        state: "not_configured",
+        summary: "No channels configured",
+        checks: [],
+        remedy: "spinuptui beacon add telegram <name> --env-file <path>",
+      }
+    }
+    const checks: ModuleCheck[] = beacon.channels.map((c) => ({
+      name: `channel ${c.name}`,
+      ok: true,
+      detail: `telegram bot ${maskToken(c.channel.botToken)} → chat ${maskChatId(c.channel.chatId)}${c.env ? " (from environment)" : ""}${c.name === beacon.defaultChannel ? ", default" : ""}`,
+    }))
+    checks.push({
+      name: "default channel",
+      ok: beacon.defaultChannel !== null,
+      detail: beacon.defaultChannel ?? "none — senders must pass --to",
+    })
+    const last = lastSendLogEntry()
+    checks.push({
+      name: "last send",
+      ok: last?.ok ?? true,
+      detail: last ? `${last.ok ? "delivered" : `failed (${last.error})`} via ${last.channel} at ${last.at}` : "nothing sent yet",
+    })
+    const failing = checks.find((c) => !c.ok)
+    return {
+      id: "beacon",
+      state: failing ? "degraded" : "ok",
+      summary: failing ? `${failing.name}: ${failing.detail}` : `${beacon.channels.length} channel${beacon.channels.length === 1 ? "" : "s"}, default ${beacon.defaultChannel}`,
+      checks,
+      ...(failing ? { remedy: "spinuptui beacon test" } : {}),
+    }
+  },
+}

package/src/modules/contract.ts

@@ -0,0 +1,61 @@
+// The module contract (docs/2026-10-16_beacon-and-module-contract-spec.md).
+//
+// A module is a feature that keeps working after the TUI is closed. Each one
+// describes itself with a ModuleDefinition so `spinuptui modules`, the future
+// Modules screen and `station setup` are views over the same data rather than
+// knowing every module by hand.
+//
+// Rules the shape encodes:
+// - Config is a machine-level top-level key in config.json named after the
+//   module, written only by deliberate setup commands.
+// - Anything a module writes while running goes in its state directory, never
+//   config.json (whose writes are neither atomic nor locked).
+// - Recurring work is declared in `jobs` for Scheduler to run; a module never
+//   installs an OS scheduler unit of its own.
+// - status() is computed on demand, is cheap, and never sends anything.
+
+import { join } from "node:path"
+import { configDir } from "../config.ts"
+
+export type ModuleId = "beacon" | "scheduler" | "sentinel" | "samurai"
+
+export interface ScheduledJobDecl {
+  id: string // e.g. "sentinel.tick"
+  every?: string // e.g. "5m"
+  at?: string // e.g. "08:00"
+  // A spinuptui subcommand's arguments, never a path into a checkout.
+  command: string[]
+}
+
+export interface ModuleCheck {
+  name: string
+  ok: boolean
+  detail: string
+}
+
+export interface ModuleStatus {
+  id: ModuleId
+  state: "not_configured" | "ok" | "degraded"
+  summary: string
+  checks: ModuleCheck[]
+  remedy?: string
+}
+
+export interface ModuleDefinition {
+  id: ModuleId
+  name: string
+  // Outcome copy, shared with the landing page's module card.
+  summary: string
+  dependsOn: ModuleId[]
+  configKey: string
+  stateDir(): string
+  jobs: ScheduledJobDecl[]
+  status(): Promise<ModuleStatus>
+}
+
+export function moduleStateDir(id: ModuleId): string {
+  return join(configDir(), "modules", id)
+}
+
+// A module that hasn't shipped yet: just enough to draw its card.
+export type UpcomingModule = Pick<ModuleDefinition, "id" | "name" | "summary" | "dependsOn">

package/src/modules/index.ts

@@ -0,0 +1,34 @@
+// Every module SpinupTUI ships, in dependency order, plus the ones still to come
+// (shown as "coming soon" on the Modules screen and in `spinuptui modules`).
+
+import type { ModuleDefinition, UpcomingModule } from "./contract.ts"
+import { beaconModule } from "./beacon.ts"
+
+export const MODULES: ModuleDefinition[] = [beaconModule]
+
+// Outcome copy only — the same lines feed the landing page. An entry moves to
+// MODULES (and out of here) when the module ships.
+export const UPCOMING_MODULES: UpcomingModule[] = [
+  {
+    id: "scheduler",
+    name: "Scheduler",
+    summary: "Follow-ups that run themselves: the fix you shipped today gets checked tomorrow without you remembering.",
+    dependsOn: ["beacon"],
+  },
+  {
+    id: "sentinel",
+    name: "Sentinel",
+    summary: "Watches the fleet, works out what actually broke, and writes it up.",
+    dependsOn: ["beacon", "scheduler"],
+  },
+  {
+    id: "samurai",
+    name: "Samurai",
+    summary: "Defends your sites at the nginx layer, proactively and when Sentinel spots an attack, with your approval.",
+    dependsOn: ["beacon", "scheduler", "sentinel"],
+  },
+]
+
+export async function allModuleStatuses() {
+  return Promise.all(MODULES.map(async (m) => ({ name: m.name, about: m.summary, dependsOn: m.dependsOn, ...(await m.status()) })))
+}

package/src/ui/App.tsx

@@ -40,6 +40,8 @@ import { ProviderConnect } from "./views/ProviderConnect.tsx"
 import { DnsRecords } from "./views/DnsRecords.tsx"
 import { KumaSite } from "./views/KumaSite.tsx"
 import { Accounts } from "./views/Accounts.tsx"
+import { Modules } from "./views/Modules.tsx"
+import { BeaconSetup } from "./views/BeaconSetup.tsx"
 
 const MIN_SPLASH_MS = 1200
 
@@ -87,7 +89,8 @@ export function App() {
     store.dnsInventoryServer !== null ||
     store.connectZoneTarget !== null ||
     store.dnsRecordsTarget !== null ||
-    store.kumaSite !== null
+    store.kumaSite !== null ||
+    store.beaconSetupOpen
   useEffect(() => {
     store.setOverlayOpen(overlayActive)
   }, [overlayActive, store])
@@ -200,6 +203,9 @@ export function App() {
     // The site-monitoring (Uptime Kuma) overlay owns the keyboard while open.
     if (store.kumaSite) return
 
+    // Beacon's guided setup (Modules tab) owns the keyboard while open.
+    if (store.beaconSetupOpen) return
+
     // A (Shift+a): the Accounts overlay — the header advertises it from every tab.
     if (key.shift && key.name === "a") return setShowAccounts(true)
 
@@ -216,6 +222,8 @@ export function App() {
         return store.setRoute("search")
       case "5":
         return store.setRoute("events")
+      case "6":
+        return store.setRoute("modules")
       case "r":
         return void store.refresh()
       case "?":
@@ -255,6 +263,7 @@ export function App() {
         {store.route === "stacks" && <Stacks rows={contentRows} />}
         {store.route === "search" && <Search rows={contentRows} />}
         {store.route === "events" && <Events rows={contentRows} />}
+        {store.route === "modules" && <Modules rows={contentRows} />}
       </box>
       {showHelp && <HelpOverlay onClose={() => setShowHelp(false)} />}
       {showExplain && <ExplainOverlay route={store.route} />}
@@ -283,6 +292,7 @@ export function App() {
       {store.connectZoneTarget && <ProviderConnect />}
       {store.dnsRecordsTarget && <DnsRecords />}
       {store.kumaSite && <KumaSite />}
+      {store.beaconSetupOpen && <BeaconSetup />}
       {showAccounts && <Accounts onClose={() => setShowAccounts(false)} />}
       <ToastStack />
     </box>

package/src/ui/Explain.tsx

@@ -27,7 +27,7 @@ const GUIDES: Record<Route, Guide> = {
       ["Recent activity", "The latest deploys and operations"],
     ],
     actions: [
-      ["1–5", "Switch tabs"],
+      ["1–6", "Switch tabs"],
       ["r", "Refresh from the API"],
     ],
   },
@@ -91,10 +91,23 @@ const GUIDES: Record<Route, Guide> = {
     title: "Events",
     summary: "A live feed of deploys, reboots, and operations across your account.",
     actions: [
-      ["1–5", "Switch tabs"],
+      ["1–6", "Switch tabs"],
       ["r", "Refresh"],
     ],
   },
+  modules: {
+    title: "Modules",
+    summary: "Modules are the parts of SpinupTUI that keep working after you close it: paging you, running follow-ups, watching the fleet. Each card says what it does and whether it's set up on this machine.",
+    panes: [
+      ["Modules", "Every module, with its status here: ● set up · ○ not set up · coming soon"],
+      ["Detail", "What the selected module does, its health checks, and what to do next"],
+    ],
+    actions: [
+      ["⏎ / s", "Set up the selected module (Beacon: connect a Telegram bot)"],
+      ["t", "Send a test page through Beacon"],
+      ["1–6", "Switch tabs"],
+    ],
+  },
 }
 
 export function ExplainOverlay({ route }: { route: Route }) {

package/src/ui/Header.tsx

@@ -15,6 +15,7 @@ const TABS: { route: Route; key: string; label: string }[] = [
   { route: "stacks", key: "3", label: "Stacks" },
   { route: "search", key: "4", label: "Search" },
   { route: "events", key: "5", label: "Events" },
+  { route: "modules", key: "6", label: "Modules" },
 ]
 
 // A one-line "what is this view, and what can I do here" subtitle per tab —
@@ -26,6 +27,7 @@ const SUBTITLES: Record<Route, string> = {
   stacks: "Your fleet grouped by app type  ·  d identify an app (SSH)  ·  S find local copies on your disk",
   search: "Jump to any server or site by name  ·  Tab hands focus to the result's actions",
   events: "Recent deploys, reboots, and operations across your account",
+  modules: "What keeps working after you close SpinupTUI  ·  ⏎ set up the selected module",
 }
 
 // SpinupWP allows 60 API requests a minute. Show what's left of this minute so

package/src/ui/Help.tsx

@@ -15,7 +15,7 @@ type Section = { title: string; keys: [string, string][] }
 const GLOBAL: Section = {
   title: "Global",
   keys: [
-    ["1 … 5", "Switch tabs"],
+    ["1 … 6", "Switch tabs"],
     ["r", "Refresh from the API"],
     ["/", "Global search"],
     ["A", "Switch SpinupWP accounts"],

package/src/ui/store.tsx

@@ -60,7 +60,7 @@ import { planDbSync, runDbSync, isDbSyncInFlight, type DbSyncProgress, type Sync
 import { planLocalSetup, runLocalSetup, isLocalSetupInFlight, type LocalSetupProgress, type LocalSetupPlanResult } from "../lib/localSetup.ts"
 import { planMediaFallback, type MediaFallbackResult } from "../lib/mediaFallback.ts"
 
-export type Route = "dashboard" | "servers" | "stacks" | "search" | "events"
+export type Route = "dashboard" | "servers" | "stacks" | "search" | "events" | "modules"
 
 // Progress of a PHP-version upgrade, tracked in the store so it survives the
 // modal being closed. `status` mirrors the SpinupWP event status
@@ -742,6 +742,9 @@ interface StoreValue extends DataState {
   // Whether the local-copy discovery overlay is open.
   discoverOpen: boolean
   setDiscoverOpen: (v: boolean) => void
+  // Beacon's guided setup overlay, opened from the Modules tab.
+  beaconSetupOpen: boolean
+  setBeaconSetupOpen: (v: boolean) => void
   // Whether the "needs a local copy" (forgotten) report overlay is open, and an
   // optional stack filter (set from the selected Stacks group when opened).
   forgottenOpen: boolean
@@ -1110,6 +1113,7 @@ export function StoreProvider({ children }: { children: ReactNode }) {
   const [mediaFallbackSite, setMediaFallbackSite] = useState<Site | null>(null)
   const [localRoots, setLocalRoots] = useState<string[]>(() => [...cfgRef.current.localRoots])
   const [discoverOpen, setDiscoverOpen] = useState(false)
+  const [beaconSetupOpen, setBeaconSetupOpen] = useState(false)
   const [forgottenOpen, setForgottenOpen] = useState(false)
   const [forgottenStack, setForgottenStack] = useState<Stack | null>(null)
   const [linkReturnToForgotten, setLinkReturnToForgotten] = useState(false)
@@ -4528,6 +4532,8 @@ export function StoreProvider({ children }: { children: ReactNode }) {
     addLocalRoot,
     discoverOpen,
     setDiscoverOpen,
+    beaconSetupOpen,
+    setBeaconSetupOpen,
     forgottenOpen,
     setForgottenOpen,
     forgottenStack,