spinuptui 1.2.0 → 1.3.0-alpha.2

package/src/modules/index.ts

@@ -0,0 +1,29 @@
+// 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"
+import { schedulerModule } from "./scheduler.ts"
+
+export const MODULES: ModuleDefinition[] = [beaconModule, schedulerModule]
+
+// 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: "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/modules/scheduler.ts

@@ -0,0 +1,146 @@
+// Scheduler's module declaration: the station's clock. Its status is the
+// one-question answer to "is the station alive?" — how long ago the dispatcher
+// last ticked.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { tryLock } from "../lib/flock.ts"
+import { loadConfig } from "../config.ts"
+import { beaconFromConfig } from "../lib/beacon.ts"
+import { nextRunText, parseWhen } from "../lib/schedule.ts"
+import { listSources, loadJobs, loadState, readLastTick, type Source } from "../lib/schedulerJobs.ts"
+import { readClaim, stationName } from "../lib/schedulerGit.ts"
+import { moduleStateDir, moduleWorkDir, type ModuleCheck, type ModuleDefinition, type ModuleStatus } from "./contract.ts"
+
+// Three missed ticks.
+export const TICK_STALE_MS = 15 * 60_000
+const RECENT_FAILURE_MS = 24 * 60 * 60_000
+
+function claimText(s: Source): string {
+  const holder = readClaim(s)
+  if (s.queueOnly) return holder ? `run by ${holder}; released here, this machine only queues` : "released here; this machine only queues"
+  if (!holder) return "unclaimed: the next dispatcher tick here claims it"
+  return holder === stationName() ? "run by this station" : `run by ${holder}; this machine only queues`
+}
+
+function tickRunning(): boolean {
+  try {
+    const lock = tryLock(join(moduleStateDir("scheduler"), "tick.lock"))
+    if (!lock) return true
+    lock.release()
+  } catch {
+    // No lock support: assume nothing is running.
+  }
+  return false
+}
+
+function age(ms: number): string {
+  const m = Math.round(ms / 60_000)
+  if (m < 1) return "just now"
+  if (m < 120) return `${m} min ago`
+  const h = Math.round(m / 60)
+  return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`
+}
+
+export const schedulerModule: ModuleDefinition = {
+  id: "scheduler",
+  name: "Scheduler",
+  summary: "Follow-ups that run themselves: the fix you shipped today gets checked tomorrow without you remembering.",
+  dependsOn: ["beacon"],
+  configKey: "scheduler",
+  stateDir: () => moduleStateDir("scheduler"),
+  workDir: () => moduleWorkDir("scheduler"),
+  jobs: [],
+  async status(): Promise<ModuleStatus> {
+    const cfg = loadConfig()
+    const d = cfg.scheduler?.dispatcher
+    const checks: ModuleCheck[] = []
+    const installed = !!d && existsSync(d.unitPath)
+    checks.push({
+      name: "dispatcher",
+      ok: installed,
+      detail: installed ? `${d!.label}, every 5 min` : d ? `unit file missing (${d.unitPath})` : "not installed",
+    })
+    const last = readLastTick()
+    const lastAge = last ? Date.now() - Date.parse(last.at) : null
+    const fresh = lastAge !== null && lastAge < TICK_STALE_MS
+    // A tick still holding its lock is alive: a long agent job can take 30
+    // minutes, and the station isn't dead while it runs.
+    const running = !fresh && tickRunning()
+    checks.push({
+      name: "last tick",
+      ok: !installed || fresh || running,
+      detail:
+        (last ? `${age(lastAge!)} (${last.via})${last.errors.length ? `, ${last.errors.length} problem${last.errors.length === 1 ? "" : "s"}: ${last.errors[0]}` : ""}` : "never") +
+        (running ? "; a tick is running now" : ""),
+    })
+    const now = new Date()
+    let active = 0
+    const failed: string[] = []
+    for (const s of listSources(cfg)) {
+      const exists = existsSync(s.path)
+      // The local folder appears on first use, so its absence is normal.
+      if (s.name !== "local" || exists) checks.push({ name: `source ${s.name}`, ok: exists, detail: exists ? `${s.path}${s.git ? ` (git, ${claimText(s)})` : ""}` : `${s.path} does not exist` })
+      if (!exists) continue
+      for (const j of loadJobs(s)) {
+        if (j.problems.length) {
+          failed.push(`${s.name}/${j.name} invalid`)
+          continue
+        }
+        const st = loadState(s, j.header.id!)
+        let next = "?"
+        try {
+          next = nextRunText(j.header, st, now)
+        } catch {
+          // validateJob already accepted it; leave "?".
+        }
+        if (next !== "expired" && next !== "done") active++
+        // A failure was paged when it happened; it stays news for a day, not
+        // until the job expires.
+        const recent = st.last_run ? now.getTime() - parseWhen(st.last_run).getTime() < RECENT_FAILURE_MS : st.last_status === "auth"
+        if (st.last_status && st.last_status !== "ok" && next !== "expired" && recent) failed.push(`${s.name}/${j.header.id} ${st.last_status}`)
+      }
+    }
+    checks.push({ name: "jobs", ok: failed.length === 0, detail: `${active} active${failed.length ? `; not ok in the last day: ${failed.slice(0, 3).join(", ")}` : ""}` })
+    const beacon = beaconFromConfig(cfg)
+    checks.push({ name: "digests", ok: beacon.channels.length > 0, detail: beacon.channels.length ? `via Beacon (${beacon.defaultChannel ?? "no default"})` : "Beacon isn't set up, so runs aren't reported" })
+
+    if (!installed && !d) {
+      return {
+        id: "scheduler",
+        state: "not_configured",
+        summary: "Dispatcher not installed",
+        checks,
+        remedy: "spinuptui scheduler install --plan",
+      }
+    }
+    const failing = checks.find((c) => !c.ok)
+    return {
+      id: "scheduler",
+      state: failing ? "degraded" : "ok",
+      summary: failing ? `${failing.name}: ${failing.detail}` : `ticking (${checks[1]!.detail.split(" (")[0]}), ${active} active job${active === 1 ? "" : "s"}`,
+      checks,
+      ...(failing ? { remedy: failing.name === "dispatcher" || failing.name === "last tick" ? "spinuptui scheduler install --apply" : "spinuptui scheduler list" } : {}),
+    }
+  },
+}
+
+// The next few follow-ups due, soonest first, for the Modules screen.
+export function upcomingRuns(limit = 5): { source: string; id: string; next: string }[] {
+  const now = new Date()
+  const out: { source: string; id: string; next: string }[] = []
+  for (const s of listSources(loadConfig())) {
+    if (!existsSync(s.path)) continue
+    for (const j of loadJobs(s)) {
+      if (j.problems.length) continue
+      try {
+        const next = nextRunText(j.header, loadState(s, j.header.id!), now)
+        if (next !== "expired" && next !== "done") out.push({ source: s.name, id: j.header.id!, next })
+      } catch {
+        // Skip a job whose schedule can't be read.
+      }
+    }
+  }
+  // Fixed times sort before "every N min", which has no single next time.
+  return out.sort((a, b) => (a.next.startsWith("every") ? 1 : 0) - (b.next.startsWith("every") ? 1 : 0) || a.next.localeCompare(b.next)).slice(0, limit)
+}

package/src/ui/App.tsx

@@ -41,6 +41,9 @@ 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"
+import { SchedulerInstall } from "./views/SchedulerInstall.tsx"
 
 const MIN_SPLASH_MS = 1200
 
@@ -89,7 +92,9 @@ export function App() {
     store.dnsInventoryServer !== null ||
     store.connectZoneTarget !== null ||
     store.dnsRecordsTarget !== null ||
-    store.kumaSite !== null
+    store.kumaSite !== null ||
+    store.beaconSetupOpen ||
+    store.schedulerInstallOpen
   useEffect(() => {
     store.setOverlayOpen(overlayActive)
   }, [overlayActive, store])
@@ -205,6 +210,10 @@ 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
+    if (store.schedulerInstallOpen) return
+
     // A (Shift+a): the Accounts overlay — the header advertises it from every tab.
     if (key.shift && key.name === "a") return setShowAccounts(true)
 
@@ -221,6 +230,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 "?":
@@ -260,6 +271,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} />}
@@ -289,6 +301,8 @@ export function App() {
       {store.connectZoneTarget && <ProviderConnect />}
       {store.dnsRecordsTarget && <DnsRecords />}
       {store.kumaSite && <KumaSite />}
+      {store.beaconSetupOpen && <BeaconSetup />}
+      {store.schedulerInstallOpen && <SchedulerInstall />}
       {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/main.tsx

@@ -0,0 +1,42 @@
+// The dashboard: boots the OpenTUI renderer and mounts either the first-run
+// onboarding wizard (no token yet) or the main app wrapped in the data store.
+// Loaded by src/index.tsx with a dynamic import, only once no headless command
+// has claimed the arguments.
+
+import { useCallback, useMemo, useState } from "react"
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import { hasToken, pinActiveProfile, setActiveProfile } from "../config.ts"
+import { StoreProvider } from "./store.tsx"
+import { App } from "./App.tsx"
+import { AccountsContext, type AccountsApi } from "./accounts.tsx"
+import { resetWpCoreJobs } from "./wpCoreJobs.tsx"
+import { Onboarding } from "./Onboarding.tsx"
+import { isDevMode } from "../dev/devMode.ts"
+
+export async function startDashboard({ forceLogin }: { forceLogin: boolean }): Promise<void> {
+  function Root() {
+    const [configured, setConfigured] = useState(isDevMode() ? true : forceLogin ? false : hasToken())
+    // The store is keyed by account: switching remounts it (see ui/accounts.tsx).
+    const [account, setAccount] = useState(() => pinActiveProfile())
+    const switchAccount = useCallback(async (id: string) => {
+      await setActiveProfile(id)
+      resetWpCoreJobs()
+      setAccount(id)
+    }, [])
+    const accounts = useMemo<AccountsApi>(() => ({ switchAccount }), [switchAccount])
+    if (!configured) {
+      return <Onboarding onComplete={() => setConfigured(true)} />
+    }
+    return (
+      <AccountsContext.Provider value={accounts}>
+        <StoreProvider key={account}>
+          <App />
+        </StoreProvider>
+      </AccountsContext.Provider>
+    )
+  }
+
+  const renderer = await createCliRenderer()
+  createRoot(renderer).render(<Root />)
+}

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
@@ -745,6 +745,12 @@ 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
+  // Scheduler's install plan + confirm overlay, opened from the Modules tab.
+  schedulerInstallOpen: boolean
+  setSchedulerInstallOpen: (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
@@ -1114,6 +1120,8 @@ 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 [schedulerInstallOpen, setSchedulerInstallOpen] = useState(false)
   const [forgottenOpen, setForgottenOpen] = useState(false)
   const [forgottenStack, setForgottenStack] = useState<Stack | null>(null)
   const [linkReturnToForgotten, setLinkReturnToForgotten] = useState(false)
@@ -4534,6 +4542,10 @@ export function StoreProvider({ children }: { children: ReactNode }) {
     addLocalRoot,
     discoverOpen,
     setDiscoverOpen,
+    beaconSetupOpen,
+    setBeaconSetupOpen,
+    schedulerInstallOpen,
+    setSchedulerInstallOpen,
     forgottenOpen,
     setForgottenOpen,
     forgottenStack,

package/src/ui/views/BeaconSetup.tsx

@@ -0,0 +1,268 @@
+// Beacon setup overlay, opened with ⏎ on Beacon in the Modules tab. The same
+// guided flow as `spinuptui beacon setup` (lib/beaconSetup.ts): paste a bot
+// token, message the bot so Beacon can find the chat, then a test page — and
+// only then is anything saved.
+
+import { useEffect, useRef, useState } from "react"
+import { useKeyboard } from "@opentui/react"
+import { theme } from "../../lib/theme.ts"
+import { Panel, Centered, Spinner, SecretInput } from "../components.tsx"
+import { StatusBar } from "../StatusBar.tsx"
+import { useStore } from "../store.tsx"
+import { openUrl } from "../../lib/open.ts"
+import {
+  BOTFATHER_STEPS,
+  BOTFATHER_URL,
+  botLink,
+  channelExists,
+  discoverChat,
+  saveBeaconChannel,
+  sendConnectedMessage,
+  setupChannelName,
+  verifyBotToken,
+  type FoundChat,
+} from "../../lib/beaconSetup.ts"
+
+type Phase = "token" | "verifying" | "waiting" | "found" | "saving" | "done" | "error"
+
+const WIDTH = 70
+
+export function BeaconSetup() {
+  const { setBeaconSetupOpen, setInputMode } = useStore()
+  const [name] = useState(setupChannelName)
+  const [replacing] = useState(() => channelExists(name))
+  const [phase, setPhase] = useState<Phase>("token")
+  const [token, setToken] = useState("")
+  const [username, setUsername] = useState("")
+  const [chat, setChat] = useState<FoundChat | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [retryFrom, setRetryFrom] = useState<Phase>("token")
+  const abort = useRef<AbortController | null>(null)
+
+  useEffect(() => {
+    setInputMode(phase === "token")
+    return () => setInputMode(false)
+  }, [phase, setInputMode])
+
+  // Stop any long-poll when the overlay goes away.
+  useEffect(() => () => abort.current?.abort(), [])
+
+  const close = () => {
+    abort.current?.abort()
+    setInputMode(false)
+    setBeaconSetupOpen(false)
+  }
+
+  const fail = (message: string, from: Phase) => {
+    setError(message)
+    setRetryFrom(from)
+    setPhase("error")
+  }
+
+  const listen = (tok: string) => {
+    abort.current?.abort()
+    const ctrl = new AbortController()
+    abort.current = ctrl
+    setChat(null)
+    setPhase("waiting")
+    void discoverChat(tok, { signal: ctrl.signal }).then((r) => {
+      if (ctrl.signal.aborted) return
+      if (r.ok) {
+        setChat(r.chat)
+        setPhase("found")
+      } else fail(r.message, "waiting")
+    })
+  }
+
+  const submitToken = () => {
+    const tok = token.trim()
+    if (!tok) return
+    setPhase("verifying")
+    void verifyBotToken(tok).then((me) => {
+      if (!me.ok) return fail(me.error ?? "Telegram rejected the token.", "token")
+      setUsername(me.username ?? "")
+      listen(tok)
+    })
+  }
+
+  const save = () => {
+    if (!chat) return
+    const channel = { type: "telegram" as const, botToken: token.trim(), chatId: chat.chatId }
+    setPhase("saving")
+    void sendConnectedMessage(name, channel).then(async (r) => {
+      if (!r.ok) return fail(`Couldn't send the test message: ${r.message}. Nothing was saved.`, "found")
+      await saveBeaconChannel(name, channel, false)
+      setToken("") // don't keep the secret in component state once it's saved
+      setPhase("done")
+    })
+  }
+
+  useKeyboard((key) => {
+    const k = key.name ?? ""
+    if (k === "escape") return close()
+    if (phase === "token") return // SecretInput owns typing; Enter submits
+    if (phase === "waiting") {
+      if (k === "o" && username) return openUrl(botLink(username))
+      return
+    }
+    if (phase === "found") {
+      if (k === "return") return save()
+      if (k === "r") return listen(token.trim())
+      return
+    }
+    if (phase === "error") {
+      if (k === "r") {
+        setError(null)
+        if (retryFrom === "waiting") return listen(token.trim())
+        if (retryFrom === "found" && chat) return setPhase("found")
+        setToken("") // a rejected token is replaced, not edited
+        return setPhase("token")
+      }
+      if (k === "q") return close()
+      return
+    }
+    if (phase === "done" && (k === "return" || k === "q")) return close()
+  })
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        height: "100%",
+        flexDirection: "column",
+        backgroundColor: theme.bg,
+        zIndex: 200,
+      }}
+    >
+      <box style={{ flexDirection: "row", height: 1, backgroundColor: theme.bgAlt, paddingLeft: 1, paddingRight: 1 }}>
+        <text content="Beacon  " fg={theme.brand} style={{ flexShrink: 0 }} />
+        <text content="connect a Telegram pager" fg={theme.text} wrapMode="none" style={{ flexShrink: 1 }} />
+        <box style={{ flexGrow: 1 }} />
+        <text content={`channel “${name}”`} fg={theme.textFaint} style={{ flexShrink: 0 }} />
+      </box>
+      <Centered>{body()}</Centered>
+      <StatusBar hints={hints()} showGlobal={false} />
+    </box>
+  )
+
+  function body() {
+    if (phase === "token") {
+      return (
+        <Panel title=" 1 · Your bot " active>
+          <box style={{ flexDirection: "column", width: WIDTH, paddingTop: 1, paddingBottom: 1 }}>
+            <text content="Beacon pages you through your own Telegram bot. Making one is free:" fg={theme.textDim} />
+            <box style={{ height: 1 }} />
+            {BOTFATHER_STEPS.map((s, i) => (
+              <text key={i} content={`  ${i + 1}. ${s}`} fg={theme.text} />
+            ))}
+            <box style={{ height: 1 }} />
+            <text content="Then paste the token here (it's hidden as you type):" fg={theme.textDim} />
+            <SecretInput focused value={token} placeholder="123456789:AAE…" onChange={setToken} onSubmit={submitToken} width={WIDTH - 2} />
+            {replacing && (
+              <>
+                <box style={{ height: 1 }} />
+                <text content={`⚠ This replaces the existing “${name}” channel once the new one is tested.`} fg={theme.warn} />
+              </>
+            )}
+            <box style={{ height: 1 }} />
+            <text content={`⏎ continue · Esc cancel · BotFather: ${BOTFATHER_URL}`} fg={theme.textFaint} wrapMode="none" />
+          </box>
+        </Panel>
+      )
+    }
+
+    if (phase === "verifying" || phase === "saving") {
+      return (
+        <box style={{ flexDirection: "row" }}>
+          <Spinner />
+          <text content={phase === "verifying" ? "  Checking the token with Telegram…" : "  Sending a test message…"} fg={theme.textDim} />
+        </box>
+      )
+    }
+
+    if (phase === "waiting") {
+      return (
+        <Panel title=" 2 · Say hello to your bot " active>
+          <box style={{ flexDirection: "column", width: WIDTH, paddingTop: 1, paddingBottom: 1 }}>
+            <box style={{ flexDirection: "row" }}>
+              <text content="✓ Bot " fg={theme.good} wrapMode="none" />
+              <text content={username ? `@${username}` : "found"} fg={theme.accent} wrapMode="none" />
+            </box>
+            <box style={{ height: 1 }} />
+            <text content="Now open Telegram and send your bot any message, so Beacon knows which" fg={theme.text} />
+            <text content="chat to page." fg={theme.text} />
+            {username && <text content={`  ${botLink(username)}   (press o to open it)`} fg={theme.accent} wrapMode="none" />}
+            <box style={{ height: 1 }} />
+            <text content="To page a group instead, add the bot to the group and send /start there." fg={theme.textFaint} />
+            <box style={{ height: 1 }} />
+            <box style={{ flexDirection: "row" }}>
+              <Spinner />
+              <text content="  Waiting for your message (up to 5 minutes)…" fg={theme.textDim} />
+            </box>
+          </box>
+        </Panel>
+      )
+    }
+
+    if (phase === "found" && chat) {
+      return (
+        <Panel title=" 3 · Confirm the chat " active>
+          <box style={{ flexDirection: "column", width: WIDTH, paddingTop: 1, paddingBottom: 1 }}>
+            <box style={{ flexDirection: "row" }}>
+              <text content="✓ Message received from " fg={theme.good} wrapMode="none" />
+              <text content={chat.label} fg={theme.accent} wrapMode="none" style={{ flexShrink: 1 }} />
+            </box>
+            <text content={`  a ${chat.kind} chat`} fg={theme.textFaint} />
+            <box style={{ height: 1 }} />
+            <text content="Beacon will page this chat. Press ⏎ to send a test message and save." fg={theme.text} />
+            <text content="Wrong chat? Press r, then message the bot from the right one." fg={theme.textDim} />
+          </box>
+        </Panel>
+      )
+    }
+
+    if (phase === "done") {
+      return (
+        <Panel title=" Beacon connected " active>
+          <box style={{ flexDirection: "column", width: WIDTH, paddingTop: 1, paddingBottom: 1 }}>
+            <text content={`● Channel “${name}” is set up, and a test message is on its way.`} fg={theme.good} />
+            <box style={{ height: 1 }} />
+            <text content="Anything on this machine can page you now:" fg={theme.textDim} />
+            <text content={`  spinuptui beacon send "web1 is down"`} fg={theme.accent} wrapMode="none" />
+            <text content={`  some-report | spinuptui beacon send --silent`} fg={theme.accent} wrapMode="none" />
+            <box style={{ height: 1 }} />
+            <text content="⏎ done" fg={theme.textFaint} />
+          </box>
+        </Panel>
+      )
+    }
+
+    return (
+      <Panel title=" Not connected yet " active>
+        <box style={{ flexDirection: "column", width: WIDTH, paddingTop: 1, paddingBottom: 1 }}>
+          <text content={`✕ ${error ?? "Something went wrong."}`} fg={theme.bad} />
+          <box style={{ height: 1 }} />
+          <text content="Nothing was saved. r — try again · Esc — close" fg={theme.textDim} />
+        </box>
+      </Panel>
+    )
+  }
+
+  function hints() {
+    if (phase === "token") return [{ key: "⏎", label: "continue" }, { key: "esc", label: "cancel" }]
+    if (phase === "waiting")
+      return [...(username ? [{ key: "o", label: "open the bot" }] : []), { key: "esc", label: "cancel" }]
+    if (phase === "found")
+      return [
+        { key: "⏎", label: "test & save" },
+        { key: "r", label: "different chat" },
+        { key: "esc", label: "cancel" },
+      ]
+    if (phase === "error") return [{ key: "r", label: "try again" }, { key: "esc", label: "close" }]
+    if (phase === "done") return [{ key: "⏎", label: "done" }]
+    return [{ key: "esc", label: "cancel" }]
+  }
+}