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

package/src/lib/stackCache.ts

@@ -5,7 +5,8 @@
 //   - set()   is called after a successful `d` probe; it upserts the entry and
 //             writes the whole file back immediately (write-through), so a probe
 //             survives even if the TUI is killed with q / Ctrl+C.
-// Probing itself is always on-demand and per-site — this cache exists to avoid
+// Probing is on-demand and per-site, with one exception: a WP version older than
+// VERSION_MAX_AGE_MS is re-probed in the background. This cache exists to avoid
 // repeating the slow SSH round-trips across launches, not to save RAM. It's a
 // deliberately small, reusable pattern for other expensive derived data later.
 
@@ -21,6 +22,10 @@ export interface CachedProbe {
   result: ProbeResult
   detectedAt: number // epoch ms
   signature: string // invalidation key (see siteSignature)
+  // Last automatic re-check of an old version (epoch ms), kept even when it
+  // failed, so the once-per-window limit holds across launches. A successful
+  // probe replaces the whole entry, which clears it.
+  recheckedAt?: number
 }
 
 interface CacheFile {
@@ -32,6 +37,25 @@ export function stackCachePath(dir = profileDataDir()): string {
   return join(dir, "stack-cache.json")
 }
 
+// A WordPress version is a fact about the server that changes without us: auto-
+// updates, wp-admin and deploys all move it, and none of them touch the site's
+// shape below. So a reading that carries a version is re-checked once it's older
+// than this (in the background, when the site list loads), and its age is shown.
+export const VERSION_MAX_AGE_MS = 24 * 60 * 60 * 1000
+
+// True when the entry carries a WP version read longer ago than the max age.
+// Identities without a version (WHMCS, Laravel, static) don't drift this way.
+export function isVersionOld(entry: CachedProbe | undefined, now = Date.now()): boolean {
+  return entry?.result.version != null && now - entry.detectedAt > VERSION_MAX_AGE_MS
+}
+
+// True when an old version is due an automatic re-check: none was attempted in
+// the current window. Unattended SSH that fails must not repeat on every launch.
+export function isRecheckDue(entry: CachedProbe | undefined, now = Date.now()): boolean {
+  if (!entry || !isVersionOld(entry, now)) return false
+  return entry.recheckedAt == null || now - entry.recheckedAt > VERSION_MAX_AGE_MS
+}
+
 // A cached probe is considered stale when the site's relevant shape changes.
 // Keying on is_wordpress + public_folder catches the cases that would alter the
 // probe's target paths or expected result.
@@ -83,6 +107,16 @@ export class StackCache {
     await this.persist()
   }
 
+  // Record an automatic re-check attempt on existing entries, in one write.
+  async noteRecheck(siteIds: number[]): Promise<void> {
+    const now = Date.now()
+    for (const id of siteIds) {
+      const e = this.entries.get(id)
+      if (e) this.entries.set(id, { ...e, recheckedAt: now })
+    }
+    await this.persist()
+  }
+
   // A copy of all entries (for rendering aggregates without exposing the map).
   snapshot(): Map<number, CachedProbe> {
     return new Map(this.entries)

package/src/modules/beacon.ts

@@ -2,7 +2,7 @@
 
 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"
+import { moduleStateDir, moduleWorkDir, type ModuleCheck, type ModuleDefinition, type ModuleStatus } from "./contract.ts"
 
 export const beaconModule: ModuleDefinition = {
   id: "beacon",
@@ -11,6 +11,7 @@ export const beaconModule: ModuleDefinition = {
   dependsOn: [],
   configKey: "beacon",
   stateDir: () => moduleStateDir("beacon"),
+  workDir: () => moduleWorkDir("beacon"),
   jobs: [],
   async status(): Promise<ModuleStatus> {
     const beacon = beaconFromConfig(loadConfig())

package/src/modules/contract.ts

@@ -10,12 +10,16 @@
 //   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).
+// - The user's work (jobs, reports, write-ups — anything a person reads, keeps
+//   or shares) goes in its work directory, ~/SpinupTUI/<id>/, not next to the
+//   tokens in the hidden config directory.
 // - 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 { homedir } from "node:os"
 import { join } from "node:path"
-import { configDir } from "../config.ts"
+import { configDir, loadConfig } from "../config.ts"
 
 export type ModuleId = "beacon" | "scheduler" | "sentinel" | "samurai"
 
@@ -48,7 +52,10 @@ export interface ModuleDefinition {
   summary: string
   dependsOn: ModuleId[]
   configKey: string
+  // Machine state: locks, logs, high-water marks.
   stateDir(): string
+  // The user's work. Created on first use, never at install.
+  workDir(): string
   jobs: ScheduledJobDecl[]
   status(): Promise<ModuleStatus>
 }
@@ -57,5 +64,19 @@ export function moduleStateDir(id: ModuleId): string {
   return join(configDir(), "modules", id)
 }
 
+const expandHome = (p: string) => (p === "~" ? homedir() : p.startsWith("~/") ? join(homedir(), p.slice(2)) : p)
+
+// ~/SpinupTUI by default: visible and easy to back up or turn into a git
+// repository. Deliberately not ~/Documents, which iCloud may sync (a second
+// syncer writing inside a .git corrupts it).
+export function spinuptuiHome(): string {
+  const p = process.env.SPINUPTUI_HOME?.trim() || loadConfig().homeDir || join(homedir(), "SpinupTUI")
+  return expandHome(p)
+}
+
+export function moduleWorkDir(id: ModuleId): string {
+  return join(spinuptuiHome(), 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

@@ -3,18 +3,13 @@
 
 import type { ModuleDefinition, UpcomingModule } from "./contract.ts"
 import { beaconModule } from "./beacon.ts"
+import { schedulerModule } from "./scheduler.ts"
 
-export const MODULES: ModuleDefinition[] = [beaconModule]
+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: "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",

package/src/modules/scheduler.ts

@@ -0,0 +1,159 @@
+// 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" })
+    const hb = cfg.scheduler?.heartbeat
+    const lastHb = last?.heartbeat
+    checks.push({
+      name: "heartbeat",
+      ok: !hb || !lastHb || lastHb.ok,
+      detail: !hb
+        ? "not set: nothing outside this machine notices if it stops (spinuptui scheduler heartbeat set <kuma-push-url>)"
+        : !lastHb
+          ? `${new URL(hb.url).host}: first ping on the next dispatcher tick`
+          : lastHb.ok
+            ? `pinging ${new URL(hb.url).host} every tick (last: ${lastHb.status})`
+            : `last ping to ${new URL(hb.url).host} failed: ${lastHb.error}`,
+    })
+
+    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

@@ -19,6 +19,7 @@ import { SiteUpdate } from "./views/SiteUpdate.tsx"
 import { BulkWpUpdate } from "./views/BulkWpUpdate.tsx"
 import { HttpsToggle } from "./views/HttpsToggle.tsx"
 import { PurgeCache } from "./views/PurgeCache.tsx"
+import { AccountSlugPrompt } from "./views/AccountSlugPrompt.tsx"
 import { SiteOffline } from "./views/SiteOffline.tsx"
 import { ReleaseNotes } from "./views/ReleaseNotes.tsx"
 import { GrantKey } from "./views/GrantKey.tsx"
@@ -43,6 +44,9 @@ 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"
+import { HomeSync } from "./views/HomeSync.tsx"
+import { HeartbeatSetup } from "./views/HeartbeatSetup.tsx"
 
 const MIN_SPLASH_MS = 1200
 
@@ -92,7 +96,11 @@ export function App() {
     store.connectZoneTarget !== null ||
     store.dnsRecordsTarget !== null ||
     store.kumaSite !== null ||
-    store.beaconSetupOpen
+    store.beaconSetupOpen ||
+    store.schedulerInstallOpen ||
+    store.homeSyncOpen ||
+    store.heartbeatSetupOpen ||
+    store.slugPrompt !== null
   useEffect(() => {
     store.setOverlayOpen(overlayActive)
   }, [overlayActive, store])
@@ -130,6 +138,9 @@ export function App() {
     // The Accounts overlay owns the keyboard while open.
     if (showAccounts) return
 
+    // The account-slug prompt (from `w`) owns the keyboard while open.
+    if (store.slugPrompt) return
+
     // The release-notes overlay owns the keyboard while open (any key dismisses).
     if (store.releaseNotesInfo) return
 
@@ -210,6 +221,9 @@ export function App() {
 
     // Beacon's guided setup (Modules tab) owns the keyboard while open.
     if (store.beaconSetupOpen) return
+    if (store.schedulerInstallOpen) return
+    if (store.homeSyncOpen) return
+    if (store.heartbeatSetupOpen) return
 
     // A (Shift+a): the Accounts overlay — the header advertises it from every tab.
     if (key.shift && key.name === "a") return setShowAccounts(true)
@@ -299,7 +313,11 @@ export function App() {
       {store.dnsRecordsTarget && <DnsRecords />}
       {store.kumaSite && <KumaSite />}
       {store.beaconSetupOpen && <BeaconSetup />}
+      {store.schedulerInstallOpen && <SchedulerInstall />}
+      {store.homeSyncOpen && <HomeSync />}
+      {store.heartbeatSetupOpen && <HeartbeatSetup />}
       {showAccounts && <Accounts onClose={() => setShowAccounts(false)} />}
+      {store.slugPrompt && <AccountSlugPrompt />}
       <ToastStack />
     </box>
   )

package/src/ui/Details.tsx

@@ -180,7 +180,13 @@ export function SiteDetail({ site, serverName }: { site: Site; serverName: strin
       <Field label="Stack" value={stack} valueColor={stackColor(stack)} />
       <Field
         label="Detected"
-        value={probing ? "identifying…" : probe ? probe.result.label + (isProbeStale(site) ? " (stale)" : "") : "not identified · d"}
+        value={
+          probing
+            ? "identifying…"
+            : probe
+              ? `${probe.result.label}${isProbeStale(site) ? " (stale)" : ""} · ${timeAgo(new Date(probe.detectedAt).toISOString())}`
+              : "not identified · d"
+        }
         valueColor={probing ? theme.textDim : probe ? probeKindColor(probe.result.kind) : theme.textFaint}
       />
       <Field label="Type" value={isWordPress ? "WordPress" : "Generic"} valueColor={isWordPress ? theme.brand : theme.textDim} />

package/src/ui/Onboarding.tsx

@@ -2,20 +2,25 @@
 //
 // Shown when no token is found in the environment or config file. Collects an
 // API token, validates it against the live API, persists it to ~/.config, then
-// hands control back to the app.
+// asks (optionally) for the account slug that `w` deep links need — the API
+// can't tell us — and hands control back to the app.
 
 import { useState } from "react"
 import { theme } from "../lib/theme.ts"
 import { Spinner, SecretInput } from "./components.tsx"
 import { SpinupWPClient } from "../api/client.ts"
 import { DEFAULT_BASE_URL, saveConfig, configPath } from "../config.ts"
+import { parseAccountSlug } from "../lib/spinupweb.ts"
 
-type Phase = "input" | "validating" | "error"
+type Phase = "input" | "validating" | "error" | "slug"
+
+const INPUT_STYLE = { backgroundColor: theme.bgAlt, focusedBackgroundColor: theme.bgAlt, textColor: theme.text }
 
 export function Onboarding({ onComplete }: { onComplete: () => void }) {
   const [value, setValue] = useState("")
   const [phase, setPhase] = useState<Phase>("input")
   const [error, setError] = useState<string | null>(null)
+  const [slug, setSlug] = useState("")
 
   async function submit(token: string) {
     const trimmed = token.trim()
@@ -26,13 +31,76 @@ export function Onboarding({ onComplete }: { onComplete: () => void }) {
     const result = await client.validateToken()
     if (result.ok) {
       await saveConfig({ token: trimmed, baseUrl: DEFAULT_BASE_URL })
-      onComplete()
+      setPhase("slug")
     } else {
       setError(result.reason)
       setPhase("error")
     }
   }
 
+  // Optional: empty skips (an existing slug, e.g. on `spinuptui login`, is kept).
+  async function submitSlug() {
+    if (!slug.trim()) return onComplete()
+    const parsed = parseAccountSlug(slug)
+    if (!parsed) {
+      setError("That doesn't look like a slug — paste the part after spinupwp.app/, or the whole URL.")
+      return
+    }
+    await saveConfig({ accountSlug: parsed })
+    onComplete()
+  }
+
+  if (phase === "slug") {
+    return (
+      <box
+        style={{
+          width: "100%",
+          height: "100%",
+          flexDirection: "column",
+          justifyContent: "center",
+          alignItems: "center",
+          backgroundColor: theme.bg,
+        }}
+      >
+        <ascii-font text="SPINUPTUI" font="block" color={[theme.brand, theme.accent]} />
+        <box style={{ height: 1 }} />
+        <box
+          title=" Almost done "
+          titleColor={theme.brand}
+          border
+          borderColor={theme.border}
+          style={{ flexDirection: "column", width: 70, paddingLeft: 2, paddingRight: 2, paddingTop: 1, paddingBottom: 1 }}
+        >
+          <text content="✓ Token works." fg={theme.good} />
+          <box style={{ height: 1 }} />
+          <text content="One more (optional): your SpinupWP account slug, the part" fg={theme.text} wrapMode="none" />
+          <text content="after spinupwp.app/ in your dashboard's address. With it, w" fg={theme.text} wrapMode="none" />
+          <text content="opens a site or server straight in SpinupWP." fg={theme.text} wrapMode="none" />
+          <text content="Pasting any dashboard URL works too." fg={theme.textDim} wrapMode="none" />
+          <box style={{ height: 1 }} />
+          <text content="Account slug" fg={theme.accent} />
+          <input
+            focused
+            value={slug}
+            placeholder="acme-agency"
+            onInput={(v: string) => {
+              setSlug(v)
+              setError(null)
+            }}
+            onSubmit={() => void submitSlug()}
+            style={INPUT_STYLE}
+          />
+          <box style={{ height: 1 }} />
+          {error ? (
+            <text content={"✕ " + error} fg={theme.bad} wrapMode="none" />
+          ) : (
+            <text content="Press Enter to finish. Leave it empty to skip; w will ask later." fg={theme.textFaint} wrapMode="none" />
+          )}
+        </box>
+      </box>
+    )
+  }
+
   return (
     <box
       style={{

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