spinuptui 0.24.4 → 0.26.0

package/CHANGELOG.md

@@ -11,6 +11,115 @@ versions; such changes are called out here.
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-08-26
+
+### Added
+- **Clone a site's full local working copy from production** — `L` on a site
+  with no local copy yet now opens a choose screen: `e` is the existing manual
+  "enter a path" form, and the new `c` runs a guided clone. It pulls the code
+  down (a `git clone` for git-deployed sites, an `rsync` over SSH for everything
+  else), runs `composer install` when the checkout turns out to be
+  Bedrock/Radicle, links the result exactly as the manual form would, and then
+  hands off to the existing DB sync (`p`) and production-media (`m`) flows
+  unchanged — three already-reviewed screens chained by keypresses rather than
+  one new mega-flow. The local database and webserver config are never touched.
+  - The rsync pull always takes the site's whole files root (so a `public/`-style
+    layout brings `wp-config.php` down from one level above the webroot), and the
+    real webroot is **detected** on the server rather than trusting
+    `public_folder`.
+  - `wp-content/uploads` is excluded — production media is served through the
+    media-fallback mu-plugin (`m`) instead of copied.
+  - `object-cache.php` and `advanced-cache.php` are excluded outright: SpinupWP's
+    Redis drop-in doesn't no-op when Redis is unreachable, it 500s on a cache
+    miss, so copying them down fatals the local site.
+  - The done screen flags that the copied `wp-config.php` is **production's**,
+    credentials included, on the file-pull path. Nothing local can reach the
+    production database through them (its `DB_HOST` is localhost), but local
+    wp-cli authenticates as the production DB user, so the DB pull offered on
+    the same screen is denied until they're pointed at a local database. A
+    Bedrock/Radicle clone gets the mirror-image note: `.env` holds its database
+    credentials and isn't in the repo, so a fresh checkout has none.
+- **`spinuptui pull files` and `spinuptui pull db`** — the local-working-copy
+  setup and DB sync, driven non-interactively from the command line, on the
+  same engines the TUI's guided flow uses. `pull files <domain> [path]` clones a
+  site's code down and links it; `pull db <domain> --yes` imports production's
+  database into that copy. Built for an agentic workflow ("pull site X down for
+  local dev") as much as for a person: progress goes to stderr, and stdout
+  carries the machine contract — with `--json`, a single result object, exit
+  code mirroring `ok`, and failures carrying both a stable `reason` code and a
+  `remedy` naming the exact command that fixes it.
+  - **`pull db` is gated twice**, since it overwrites the local database:
+    `"localSync": true` in the config (the same opt-in the TUI enforces) *and*
+    `--yes` on the invocation. Both are checked before any network call, so a
+    typo'd domain in a script bounces off the gate rather than off a lookup.
+  - **`pull files` never re-syncs over an existing copy** — a site that's
+    already linked is refused with its current path, rather than clobbering
+    local work.
+  - **`pull files` warns that the copied `wp-config.php` is production's**, and
+    a `pull db` that's denied by local MySQL says why. The rsync path brings
+    down the site's real `wp-config.php`, credentials and all — harmless (their
+    `DB_HOST` is localhost, so nothing local can reach production's database
+    through them) but it means local wp-cli authenticates as the *production*
+    DB user, and `pull db` fails on its very first step until they're pointed
+    at a local database.
+  - **`--server <name>` picks one site when a domain exists on more than one
+    server**, and the ambiguity itself now lists what matched (in both output
+    modes) instead of only saying there was more than one.
+  - **A Bedrock/Radicle clone is flagged for its missing `.env`** — that's where
+    its database credentials live and it's deliberately not in the repo, so
+    `pull db` would otherwise die on `mysqldump: unknown variable 'pass='`.
+    It's now caught up front, by name.
+  - The path argument is optional only when exactly one `localRoots` entry is
+    configured. With several, it's required: which root a site belongs in isn't
+    knowable from here, and guessing would file a standard-WP site under
+    Bedrock.
+- **`--server <name>` on `ssh` and `ssh-exec` too**, not just the `pull`
+  commands. A domain that exists on more than one server — a clone-wizard
+  destination, a staging twin — could previously be reported as ambiguous by
+  these commands but never resolved, leaving it simply unreachable from the
+  CLI. The ambiguity now also lists the candidates and names the flag that
+  picks one, everywhere it's raised.
+
+### Changed
+- **Search now shows a full-width Site/Server Control drawer**, matching the
+  Servers tab, instead of swapping the right-hand panel between Details and
+  Actions. The Details pane stays put while you browse, and the drawer below
+  always reflects the currently selected result — reusing the exact same
+  control-list component the Servers tab uses, so the two views can't drift
+  out of sync again.
+
+### Fixed
+- **`K` (Grant SSH key) and `V` (create/resume vanity site) now work on server
+  results in Search**, not just site results. Both were already advertised in
+  the legend but silently did nothing on a server before this — `K` falls back
+  to the server's first key-eligible site as the anchor, matching the Servers
+  tab's behavior.
+- **A failed local-database backup no longer leaves a fake backup behind.** The
+  DB pull (`p`, and the same engine everywhere else) starts by dumping the
+  local database as a safety net; `wp db export` creates its output file before
+  it knows the dump will succeed, and the follow-up `gzip` never runs when it
+  doesn't — leaving a bare `.sql` in `sql/`, named exactly like a real backup.
+  Empty when the failure is instant (bad credentials), **partial** when the
+  dump dies midway, which is the case that matters: it reads as a safety net
+  and isn't one. Nothing was lost by removing it — the pull aborts at that step,
+  before the local database is touched at all.
+
+## [0.25.0] - 2026-08-12
+
+### Added
+- **Server actions now surfaces a pending SpinupWP platform upgrade**, not just
+  a silent badge. The overlay (`a`) shows a banner explaining the API only
+  exposes it as a flag with no actionable detail, and `w` jumps straight to the
+  server's page in the SpinupWP web app to run it.
+- **App version on the splash screen**, shown below the tagline while the first
+  batch of data loads.
+
+### Fixed
+- **The reboot-pending detail line now shows the real reason when the SSH probe
+  fails**, instead of a generic "couldn't read detail over SSH" message — e.g.
+  an SSH auth failure now shows the actual error. Both this and the new upgrade
+  banner wrap across lines instead of overflowing the panel on longer text.
+
 ## [0.24.4] - 2026-08-06
 
 ### Fixed
@@ -1299,7 +1408,9 @@ Initial tagged release.
 ### Notes
 - Read-only release: works with a SpinupWP **Read Only** API token.
 
-[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v0.24.4...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v0.26.0...HEAD
+[0.26.0]: https://github.com/mwender/spinupwp-tui/compare/v0.25.0...v0.26.0
+[0.25.0]: https://github.com/mwender/spinupwp-tui/compare/v0.24.4...v0.25.0
 [0.24.4]: https://github.com/mwender/spinupwp-tui/compare/v0.24.3...v0.24.4
 [0.24.3]: https://github.com/mwender/spinupwp-tui/compare/v0.24.2...v0.24.3
 [0.24.2]: https://github.com/mwender/spinupwp-tui/compare/v0.24.1...v0.24.2

package/README.md

@@ -44,8 +44,9 @@
 - **Installed plugins & themes** (`e`) — real `wp plugin`/`theme list` over SSH,
   with per-item version and update status. → [docs/plugins-themes.md](docs/plugins-themes.md)
 - **Open in browser** (`o`) / **SSH into a site** (`s`) — one-key shortcuts.
-- **Link local working copies** (`L`) — link a site to its local checkout, with
-  auto-discovery and git-drift indicators. → [docs/local-working-copies.md](docs/local-working-copies.md)
+- **Local working copies** (`L`) — link a site to its local checkout, or clone
+  one from production (`c`) when you don't have it yet; with auto-discovery and
+  git-drift indicators. → [docs/local-working-copies.md](docs/local-working-copies.md)
 - **DNS migration lens** (`n` / `N`) — see and edit a site's hosting records,
   repoint it to another server. → [docs/dns-access-editing.md](docs/dns-access-editing.md)
 - **Database backup & sync** (`d` / `p`, Servers / Search tabs) — download or
@@ -80,9 +81,12 @@
   if it's read-only — anything that looks like a write/restart/destructive
   action is denied rather than run, so any agent using it inherits that
   guarantee without building its own guard; `spinuptui incidents <domain>` /
-  `--all` surfaces Uptime Kuma's down/up history as JSON. Built so another
-  agent/script can go from just a domain to "what's wrong and how do I get
-  in" with no manual lookup. → [CLI subcommands](#cli-subcommands)
+  `--all` surfaces Uptime Kuma's down/up history as JSON; `spinuptui pull files
+  <domain> [path]` and `spinuptui pull db <domain> --yes` set up a local working
+  copy from production without opening the TUI at all — the same engines the
+  guided flow drives. Built so another agent/script can go from just a domain to
+  "what's wrong and how do I get in", or to a working local copy, with no manual
+  lookup. → [CLI subcommands](#cli-subcommands)
 - **Completion toasts** — a non-focus-stealing toast when a background write
   (PHP upgrade, reboot, DNS resolve, …) finishes.
 - **Release notes** — an in-app "what's new" after every update, sourced
@@ -169,11 +173,13 @@ to the version in the header (and in the `?` About panel).
 spinuptui            Launch the dashboard
 spinuptui login      Set or update your saved API token
 spinuptui where      Show the config path and which source the token came from
-spinuptui ssh <domain>  Print SSH access info for a site as JSON (resolves the
+spinuptui ssh <domain> [--server <name>]  Print SSH access info for a site
+                     as JSON (resolves the
                      site's server, builds its SSH target, and runs a live
                      connectivity probe — for external tooling, e.g. an
                      incident-diagnostics agent handed only a domain)
-spinuptui ssh-exec <domain> -- <command>  Resolve the domain's SSH target and
+spinuptui ssh-exec <domain> [--server <name>] -- <command>  Resolve the
+                     domain's SSH target and
                      run <command> on it, but only if the command is
                      read-only — anything matching a write/restart/destructive
                      pattern (plugin/theme changes, DB writes, service
@@ -189,10 +195,57 @@ spinuptui incidents <domain> | --all [--hours N]  Print Uptime Kuma down/up
                      monitoring for (config.json's kumaMonitors) — --all
                      sweeps every such site in one Kuma connection, --hours
                      sets the lookback window (default 24)
+spinuptui pull files <domain> [path] [--url <local url>] [--server <name>]
+                     [--json]
+                     Set up a new local working copy of a site: `git clone` for
+                     git-deployed sites, `rsync` over SSH otherwise (excluding
+                     uploads and the caching drop-ins), `composer install` for
+                     Bedrock/Radicle, then link it. Read-only on production.
+                     Refuses a path that exists and isn't empty, and refuses a
+                     site that already has a local copy rather than re-syncing
+                     over your work. With exactly one `localRoots` entry
+                     configured the path is optional (defaults to
+                     `<that root>/<domain>`); with several, it's required,
+                     since which root a site belongs in isn't knowable. Note
+                     the rsync path copies the site's real `wp-config.php` —
+                     production credentials and all — so point its DB settings
+                     at your local database before `pull db` (the command says
+                     so on success, and again if the import is denied). A
+                     Bedrock/Radicle clone lands without its `.env` — which is
+                     where its DB credentials live and is deliberately not in
+                     the repo — and says so the same way. `--server <name>`
+                     picks one site when a domain exists on more than one
+                     server; the ambiguity message lists the candidates.
+spinuptui pull db <domain> [--url <local url>] [--server <name>] --yes [--json]
+                     Import production's database into the already-linked local
+                     copy, rewriting production URLs to the local URL, after
+                     dumping the current local database as a backup. This
+                     **overwrites your local database**, so it's gated twice:
+                     `"localSync": true` must be set in the config (or
+                     `SPINUPWP_LOCAL_SYNC=1`) *and* `--yes` passed on the
+                     invocation. Both are checked before any network call.
+                     `--url` doubles as "set the local URL, then sync".
 spinuptui --version  Print the version
 spinuptui --help     Show help
 ```
 
+`--server <name>` works on every domain-addressed subcommand (`ssh`,
+`ssh-exec`, `pull files`, `pull db`). A domain can legitimately exist on more
+than one server — a clone-wizard destination, a staging twin — and without it
+those commands could only report the ambiguity, not resolve it. It matches the
+full server name or its first label (`web1` for `web1.example.com`), and the
+ambiguity message lists the candidates to pick from.
+
+Both `pull` commands write human-readable progress to **stderr** and their
+result to **stdout** — with `--json`, a single result object (`{ok:true, …}` or
+`{ok:false, reason, message, remedy}`), and the exit code mirrors `ok`. That
+keeps stdout parseable for an agent while a person watching a ten-minute rsync
+can still see it isn't hung. Failures carry a machine-readable `reason`
+(`site_not_found`, `multiple_matches`, `already_linked`, `dest_not_empty`,
+`ambiguous_dest`, `not_linked`, `missing_env`, `local_sync_disabled`,
+`not_confirmed`, …) and, where there's a
+clear next step, a `remedy` naming the exact command to run.
+
 ## Configuration
 
 The token is resolved in this order (first match wins):
@@ -256,7 +309,7 @@ These can be set in `config.json` or via an environment variable:
 | `d` | Download a production DB backup into the linked copy (Servers / Search; WordPress + linked) |
 | `p` | Pull the production DB into the linked copy — overwrites local; opt-in via `localSync` (Servers / Search) |
 | `m` | Production media fallback: serve missing-locally images from production (Servers / Search; WordPress + linked) |
-| `L` | Link / edit a site's local working copy |
+| `L` | Link / edit a site's local working copy — on an unlinked site, `e` enters a path by hand and `c` clones one from production |
 | `t` / `v` | Open the linked copy in a terminal / its local URL in your browser |
 | `n` | DNS migration view for a site — its records + TTLs (`⏎` edits a TTL; `p` repoints the record; `a` shows the whole server) |
 | `N` | DNS migration view for the whole server |
@@ -320,8 +373,10 @@ Full details: [docs/php-upgrade.md](docs/php-upgrade.md).
 ## Server actions
 
 `a` on a server reboots it or restarts a service (Nginx/PHP-FPM/MySQL/Redis),
-and shows *why* a reboot is pending (the actual OS packages, read over SSH).
-Needs a Read/Write token. Full details: [docs/server-actions.md](docs/server-actions.md).
+shows *why* a reboot is pending (the actual OS packages, read over SSH), and for
+a pending SpinupWP platform upgrade — which the API can't act on — offers `w` to
+jump straight to it in the SpinupWP web app. Needs a Read/Write token. Full
+details: [docs/server-actions.md](docs/server-actions.md).
 
 ## Site monitoring
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spinuptui",
-  "version": "0.24.4",
+  "version": "0.26.0",
   "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
   "type": "module",
   "bin": {

package/src/index.tsx

@@ -16,11 +16,44 @@ import { SpinupWPClient } from "./api/client.ts"
 import { resolveSshAccess } from "./lib/cliSsh.ts"
 import { resolveIncidents } from "./lib/cliIncidents.ts"
 import { execSshCommand } from "./lib/sshExec.ts"
+import { runPullFiles, runPullDb } from "./lib/cliPull.ts"
 
 const args = process.argv.slice(2)
 const positionals = args.filter((a) => !a.startsWith("-"))
 const command = positionals[0]
 
+// Flags that take a following value. Listed so that value can be skipped when
+// collecting positionals — otherwise `--server web1 <domain>` reads "web1" as
+// the domain, and a URL (which doesn't look like a flag) reads as a path.
+const VALUE_FLAGS = new Set(["--url", "--server"])
+
+function parseFlags(list: string[]): { positionals: string[]; flags: Map<string, string> } {
+  const out: string[] = []
+  const flags = new Map<string, string>()
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i]!
+    if (a.startsWith("-")) {
+      if (VALUE_FLAGS.has(a)) {
+        flags.set(a, list[i + 1] ?? "")
+        i++
+      } else {
+        flags.set(a, "")
+      }
+      continue
+    }
+    out.push(a)
+  }
+  return { positionals: out, flags }
+}
+
+// A value-taking flag with nothing usable after it is a mistake worth naming,
+// not a silently-empty value.
+function badFlagValue(flags: Map<string, string>, name: string): boolean {
+  if (!flags.has(name)) return false
+  const v = flags.get(name)!
+  return !v || v.startsWith("-")
+}
+
 if (args.includes("-h") || args.includes("--help") || command === "help") {
   const cfg = loadConfig()
   console.log(`SpinupTUI v${pkg.version} — terminal dashboard for your SpinupWP account
@@ -29,14 +62,31 @@ Usage:
   spinuptui            Launch the dashboard
   spinuptui login      Set or update your saved API token
   spinuptui where      Print the config file path and token source
-  spinuptui ssh <domain>  Print SSH access info for a site (JSON)
-  spinuptui ssh-exec <domain> -- <command>  Run a read-only command over SSH
-                       (JSON); denies anything that looks like a remote write
+  spinuptui ssh <domain> [--server <name>]  Print SSH access info for a site
+                       (JSON)
+  spinuptui ssh-exec <domain> [--server <name>] -- <command>  Run a read-only
+                       command over SSH (JSON); denies anything that looks
+                       like a remote write
   spinuptui incidents <domain> | --all [--hours N]  Print Uptime Kuma
                        down/up incidents for a site or the whole fleet (JSON)
+  spinuptui pull files <domain> [path] [--url <local url>] [--server <name>]
+                       Clone a site's code to a new local working copy and link
+                       it. Read-only on production; refuses a non-empty path.
+                       With exactly one localRoots entry configured, the path
+                       defaults to <that root>/<domain>.
+  spinuptui pull db <domain> [--url <local url>] [--server <name>] --yes
+                       Import production's database into the linked local copy,
+                       rewriting URLs. OVERWRITES your local database: needs
+                       both --yes and "localSync": true in the config.
   spinuptui --version  Print the version
   spinuptui --help     Show this help
 
+--server picks one site when a domain exists on more than one server (the
+ambiguity message lists them); it works on ssh, ssh-exec and both pull
+commands. Add --json to either pull command for a single
+machine-readable result object on stdout; progress always goes to stderr, so a
+long pull never looks hung.
+
 Token resolution: SPINUPWP_ACCESS_TOKEN (env / .env) first, then the config
 file. Run \`spinuptui login\` once to save a token so \`spinuptui\` works from
 anywhere.
@@ -59,31 +109,43 @@ if (command === "where") {
 }
 
 if (command === "ssh") {
-  const domain = positionals[1]
-  if (!domain) {
-    console.error(JSON.stringify({ ok: false, reason: "usage", message: "Usage: spinuptui ssh <domain>" }))
+  const parsed = parseFlags(args.slice(1))
+  const domain = parsed.positionals[0]
+  const server = parsed.flags.get("--server") ?? null
+  if (!domain || badFlagValue(parsed.flags, "--server")) {
+    console.error(
+      JSON.stringify({ ok: false, reason: "usage", message: "Usage: spinuptui ssh <domain> [--server <name>]" }),
+    )
     process.exit(1)
   }
   const cfg = loadConfig()
   const client = new SpinupWPClient(cfg)
-  const result = await resolveSshAccess(domain, client, cfg)
+  const result = await resolveSshAccess(domain, client, cfg, { server })
   console.log(JSON.stringify(result))
   process.exit(result.ok ? 0 : 1)
 }
 
 if (command === "ssh-exec") {
   const dashIdx = args.indexOf("--")
-  const domain = positionals[1]
+  // Only the arguments BEFORE `--` are ours; everything after is the remote
+  // command, which may legitimately contain things that look like our flags.
+  const parsed = parseFlags(dashIdx === -1 ? args.slice(1) : args.slice(1, dashIdx))
+  const domain = parsed.positionals[0]
+  const server = parsed.flags.get("--server") ?? null
   const remoteCmd = dashIdx !== -1 ? args.slice(dashIdx + 1).join(" ") : ""
-  if (!domain || dashIdx === -1 || !remoteCmd.trim()) {
+  if (!domain || dashIdx === -1 || !remoteCmd.trim() || badFlagValue(parsed.flags, "--server")) {
     console.error(
-      JSON.stringify({ ok: false, reason: "usage", message: "Usage: spinuptui ssh-exec <domain> -- <command>" }),
+      JSON.stringify({
+        ok: false,
+        reason: "usage",
+        message: "Usage: spinuptui ssh-exec <domain> [--server <name>] -- <command>",
+      }),
     )
     process.exit(1)
   }
   const cfg = loadConfig()
   const client = new SpinupWPClient(cfg)
-  const result = await execSshCommand(domain, remoteCmd, client, cfg)
+  const result = await execSshCommand(domain, remoteCmd, client, cfg, { server })
   console.log(JSON.stringify(result))
   process.exit(result.ok ? 0 : 1)
 }
@@ -111,6 +173,64 @@ if (command === "incidents") {
   process.exit(result.ok ? 0 : 1)
 }
 
+if (command === "pull") {
+  const { positionals: pos, flags } = parseFlags(args.slice(1))
+  const json = flags.has("--json")
+  const yes = flags.has("--yes")
+  const url = flags.get("--url") ?? null
+  const server = flags.get("--server") ?? null
+  const sub = pos[0]
+  const domain = pos[1]
+  const destPath = pos[2] ?? null
+
+  const usage = (message: string) => {
+    console.error(JSON.stringify({ ok: false, reason: "usage", message }))
+    process.exit(1)
+  }
+
+  if (sub !== "files" && sub !== "db") {
+    usage("Usage: spinuptui pull files <domain> [path] [--url <local url>] | spinuptui pull db <domain> [--url <local url>] --yes")
+  }
+  if (!domain) usage(`Usage: spinuptui pull ${sub} <domain>`)
+  if (badFlagValue(flags, "--url")) usage("--url needs a value, e.g. --url https://example.test")
+  if (badFlagValue(flags, "--server")) usage("--server needs a value, e.g. --server web1.example.com")
+  if (sub === "db" && destPath) usage("`pull db` imports into the already-linked copy and takes no path. Use --url to set the local URL.")
+
+  const cfg = loadConfig()
+  const client = new SpinupWPClient(cfg)
+  // Progress is a human channel on stderr in both modes: it keeps a long rsync
+  // from looking hung, and leaves stdout as the machine contract.
+  const onStage = (line: string) => process.stderr.write(`\u2192 ${line}\n`)
+
+  const result =
+    sub === "files"
+      ? await runPullFiles(domain!, { path: destPath, url, server }, client, cfg, onStage)
+      : await runPullDb(domain!, { url, yes, server }, client, cfg, onStage)
+
+  if (json) {
+    console.log(JSON.stringify(result))
+  } else if (result.ok) {
+    if (result.command === "pull files") {
+      const built = result.ranComposer ? ", composer install ran" : ""
+      console.log(`Pulled ${result.primaryDomain} to ${result.path} (${result.method}${built}) and linked it.`)
+      console.log(
+        result.localUrl
+          ? `Next: spinuptui pull db ${result.primaryDomain} --yes`
+          : `Next: spinuptui pull db ${result.primaryDomain} --url <local url> --yes`,
+      )
+    } else {
+      console.log(`Imported production's database for ${result.primaryDomain} into ${result.path}.`)
+      console.log(`Local database backed up first to ${result.localBackupPath}`)
+    }
+    for (const warning of result.warnings ?? []) console.error(`Warning: ${warning}`)
+  } else {
+    console.error(result.message)
+    for (const c of result.candidates ?? []) console.error(`  · ${c.server} (site ${c.siteId})`)
+    if (result.remedy) console.error(result.remedy)
+  }
+  process.exit(result.ok ? 0 : 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"