spinuptui 1.3.0-alpha.1 → 1.3.0-alpha.3

package/CHANGELOG.md

@@ -11,6 +11,34 @@ 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.
+
+### Added
+- **Scheduler: follow-ups that run themselves.** Queue a job for later (`spinuptui scheduler add verify-410s --kind spinuptui --when "2026-10-21 08:00" --expires 2026-10-28 --created-by "…" -- incidents example.com`) and this machine runs it at that time, writes a report, and sends you the result through Beacon. Jobs can be a SpinupTUI command, a shell script, or a prompt for an agent CLI (Claude Code or Codex, read-only by default). They can be one-offs or recurring (`every 30m`, `weekdays 08:00`, `mon,thu 08:00`), and every job carries an expiry date so a forgotten one stops on its own. Jobs and reports live in `~/SpinupTUI/scheduler/`, a visible folder of your own. Make `~/SpinupTUI/` a git repository and Scheduler pulls it before each run and commits and pushes the reports, so you can queue a job from any machine with a commit. Only one machine runs a repository's jobs: the first station to tick it claims it, so a second machine with a dispatcher can't run them twice. `scheduler source claim` and `release` move them between machines. A job can say what happens when the station reaches it late (`--late run`, `skip`, or a grace window like `2h`). A skipped job is paged, not dropped silently. `scheduler list`, `show`, `run`, `cancel` and `validate` round it out. See [docs/scheduler.md](docs/scheduler.md).
+- **`spinuptui scheduler install --plan|--apply`** sets up the one LaunchAgent everything runs on: a tick at login and every five minutes, with the PATH a bare launchd environment lacks written into it. `--apply` doesn't report success until a tick has actually run under launchd. `uninstall` removes it and keeps your jobs and reports. Scheduler shows up live on the Modules tab (`6`), where `⏎` shows the same plan and installs it on confirm, and in `spinuptui modules`, which reports how long ago the last tick ran. Modules will declare their own recurring work for Scheduler to run, so a station needs only this one unit. The design is in [docs/2026-10-20_scheduler-spec.md](docs/2026-10-20_scheduler-spec.md).
+
+### Changed
+- **Headless commands start about three times faster.** `beacon send`, `incidents`, `ssh-exec`, `scheduler` and the rest no longer load the dashboard's renderer before looking at their arguments, which matters for something started every five minutes.
+
 ## [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.
@@ -1506,7 +1534,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.3.0-alpha.1...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
 [1.2.0-alpha.1]: https://github.com/mwender/spinupwp-tui/compare/v1.1.2...v1.2.0-alpha.1

package/README.md

@@ -82,6 +82,13 @@
   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)
+  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/`; `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
@@ -310,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 →
@@ -375,8 +383,10 @@ 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) |
+| `⏎` / `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.1",
+  "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

@@ -109,6 +109,12 @@ export interface AppConfig {
   // 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
+  // Scheduler's sources and installed dispatcher (lib/scheduler*.ts,
+  // docs/2026-10-20_scheduler-spec.md). Machine-level: a station runs one clock.
+  scheduler: SchedulerStored | null
+  // Where modules put the user's work (Scheduler's jobs and reports…); null =
+  // the default, ~/SpinupTUI. SPINUPTUI_HOME overrides. See modules/contract.ts.
+  homeDir: string | null
 }
 
 export interface BeaconTelegramChannel {
@@ -126,6 +132,21 @@ export interface BeaconStored {
   channels?: Record<string, BeaconChannel>
 }
 
+export interface SchedulerStored {
+  // Named job sources beyond the built-in `local` one: directories holding
+  // jobs/ and runs/, pulled and pushed when they are git repositories.
+  sources?: Record<string, { path: string }>
+  defaultSource?: string
+  // Git sources this machine only queues to: it never claims or runs them
+  // (set by `scheduler source release`, cleared by `claim`).
+  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 {
   id: number
   databaseProviderId?: number
@@ -224,6 +245,8 @@ export interface StoredConfig {
   kumaMonitors?: Record<string, KumaMonitorRef>
   lastSeenVersion?: string
   beacon?: BeaconStored
+  scheduler?: SchedulerStored
+  homeDir?: string
 }
 
 // ---- Accounts (profiles) -------------------------------------------------------
@@ -510,6 +533,8 @@ export function loadConfig(): AppConfig {
     kumaMonitors: stored.kumaMonitors ?? {},
     lastSeenVersion: stored.lastSeenVersion?.trim() || null,
     beacon: stored.beacon ?? null,
+    scheduler: stored.scheduler ?? null,
+    homeDir: stored.homeDir?.trim() || null,
   }
 }
 

package/src/index.tsx

@@ -1,22 +1,15 @@
 #!/usr/bin/env bun
-// Entry point. Handles a few non-interactive CLI subcommands, then boots the
-// OpenTUI renderer and mounts either the first-run onboarding wizard (no token
-// yet) or the main app wrapped in the data store.
+// Entry point. Handles the non-interactive CLI subcommands, then hands off to
+// the dashboard (ui/main.tsx).
 
 // First, before any config read or spawn: keep a site checkout's .env from
 // leaking into child processes (see the module).
 import "./lib/cwdDotenv.ts"
-import { useCallback, useMemo, useState } from "react"
-import { createCliRenderer } from "@opentui/core"
-import { createRoot } from "@opentui/react"
+// Nothing UI-related is imported statically: headless commands (the Scheduler
+// tick every 5 minutes, beacon send, incidents…) never load the renderer or
+// React. The dashboard is a dynamic import at the bottom.
 import pkg from "../package.json" with { type: "json" }
-import { hasToken, configPath, loadConfig, pinActiveProfile, setActiveProfile, listProfiles } from "./config.ts"
-import { StoreProvider } from "./ui/store.tsx"
-import { App } from "./ui/App.tsx"
-import { AccountsContext, type AccountsApi } from "./ui/accounts.tsx"
-import { resetWpCoreJobs } from "./ui/wpCoreJobs.tsx"
-import { Onboarding } from "./ui/Onboarding.tsx"
-import { isDevMode } from "./dev/devMode.ts"
+import { configPath, loadConfig, listProfiles } from "./config.ts"
 import { SpinupWPClient } from "./api/client.ts"
 import { resolveSshAccess } from "./lib/cliSsh.ts"
 import { resolveIncidents } from "./lib/cliIncidents.ts"
@@ -25,6 +18,7 @@ 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"
+import { runScheduler } from "./lib/cliScheduler.ts"
 
 const args = process.argv.slice(2)
 const positionals = args.filter((a) => !a.startsWith("-"))
@@ -113,6 +107,15 @@ Usage:
                        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 scheduler add <id> --kind spinuptui|script|agent --when <time> | --every <schedule>
+                       --expires <date> --created-by <who> -- <body>
+                       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
@@ -313,31 +316,16 @@ 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"
+if (command === "home") {
+  const { runHome } = await import("./lib/cliHome.ts")
+  process.exit(await runHome(args.slice(args.indexOf("home") + 1)))
+}
 
-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>
-  )
+if (command === "scheduler") {
+  process.exit(await runScheduler(args.slice(args.indexOf("scheduler") + 1)))
 }
 
-const renderer = await createCliRenderer()
-createRoot(renderer).render(<Root />)
+// `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 { startDashboard } = await import("./ui/main.tsx")
+await startDashboard({ forceLogin: command === "login" })

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
+}