spinuptui 0.21.1 → 0.22.0

package/CHANGELOG.md

@@ -11,6 +11,99 @@ versions; such changes are called out here.
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-07-13
+
+### Added
+- **`spinuptui ssh-exec <domain> -- <command>`** — resolves the domain's SSH
+  target (same as `spinuptui ssh`) and runs `<command>` on it, but only if
+  it's read-only: anything matching a write/restart/destructive pattern
+  (plugin/theme changes, DB writes, service restarts, redirecting output to
+  a real file, package installs, etc.) is denied before it ever reaches the
+  server. Built for external tooling that needs to run diagnostic commands
+  unattended — any agent configured to touch a server only through this
+  command inherits the read-only guarantee without building its own guard.
+  Prints structured JSON (`stdout`/`stderr`/`exitCode` on success,
+  `reason:"command_denied"` on refusal) and logs every attempt — allowed,
+  denied, or unresolved — to `<config dir>/logs/ssh-exec-audit.jsonl`.
+- **Refreshing a vanity page's HTML is now discoverable from where you'd look
+  for it.** A shared, grouped, key-chipped action list (`siteGroups()`) now
+  shows every per-site action — including `R` (refresh vanity page) for the
+  one site per server whose domain is the server's own hostname — in Search's
+  Actions pane and, on the Servers tab, in the bottom **Control strip**
+  (below). Previously `R` only lived inside the `m` monitoring overlay.
+- **The Servers tab's bottom "Local" drawer is now a full-width Control
+  strip.** With a site selected it shows Site Control (Open/Remote/Local/
+  Vanity/Server); with a server selected (no site drilled into) it now shows
+  real **Server Control** (Clone/Access/Manage/Open) instead of a generic
+  placeholder. Each group's items flow and wrap across the full terminal
+  width instead of stacking one per line, so even a long group like Remote
+  fits in 1 line — each group's label sits in its own left column (pinned to
+  the top if its items wrap), and item labels are terser now that they don't
+  need to repeat their group's name (e.g. "In browser" under OPEN, not "Open
+  site in browser"). The Sites list also dropped its per-row status badges
+  (linked/keys/HTTPS/cache/backup/updates) — that info is already shown in
+  the Details pane for the selected site — to give the domain name more room;
+  Servers/Sites/Details are back to a simple 3-pane row.
+
+### Changed
+- **Servers and Search footers no longer duplicate the action list.** Both
+  views' key hints for a selected site are now nav-only (`select` / `back`);
+  the full, always-in-sync action list lives in the Control strip (or
+  Search's Actions pane). Also fixed a stale Search hint (`⏎ open site`) that was
+  shown even for a selected server row, where Enter is a no-op.
+
+## [0.21.2] - 2026-07-10
+
+### Fixed
+- **Onboarding's API token link was a 404.** `https://spinupwp.app/account/api/`
+  no longer resolves, and the correct URL is account-specific (a company slug
+  we can't know before the user has a token) — replaced with generic
+  "Settings → API Tokens" navigation instructions in onboarding and the README.
+- **Bedrock detection now works at any nesting depth, everywhere it matters.**
+  A Bedrock install whose project root isn't directly under the site's files
+  root (e.g. moved into its own subdirectory) could go undetected — the
+  plugins/themes view (`p`) reported "no WordPress core found" even though the
+  site worked fine and SpinupWP itself knew it was WordPress. Detection now
+  anchors on the site's configured Public Folder (falling back to a bounded
+  search only when that's unset) instead of a fixed, shallow search depth:
+  - `p` (plugins/themes) finds core correctly.
+  - `d` (identify app) correctly labels it "Bedrock" again, not just generic
+    WordPress.
+  - The clone wizard's Bedrock pull no longer hardcodes `web/`. It detects the
+    real project root independently on both source and destination — they're
+    not assumed to match, since the destination's layout comes from the git
+    repo's own committed content, not the source's on-disk state. A cheap
+    pre-flight check also catches a source whose files don't match its own
+    configured Public Folder *before* a destination site gets created for a
+    clone that can't succeed; the pull chain's own detection step is the
+    real, authoritative check either way.
+  - The Stacks tab's default (pre-probe) "Bedrock" label also recognizes a
+    webroot like `site/web`, not just an exact `web`.
+- **A first-time local Bedrock pull now explains itself.** "Pull production →
+  local" (`p` in Search) backs up the local database before overwriting it —
+  on a fresh Bedrock checkout with no `vendor/` yet, that step failed with
+  wp-cli's generic "not a WordPress install" error. The message now adds
+  "Run `composer install` in your local checkout first" when that's the
+  likely cause.
+- **Clone-wizard error messages no longer get cut off at a fixed, often-too-
+  short length.** The site roster, Git-access deploy-key list, and DNS
+  cutover roster all truncated error text to a small fixed character count
+  regardless of how much space was actually available. Errors now fill
+  whatever room the row has, so a full-sentence error like the Bedrock
+  layout mismatch above is far more likely to be readable inline instead of
+  needing a drill-down for basic context.
+
+### Notes
+- Nested Bedrock layouts (where the project root isn't directly under the
+  site's files root) are now correctly detected in the plugins/themes view,
+  app identification, and the clone wizard's size estimate — all live-
+  tested. A standard (non-nested) Bedrock clone through the rewritten pull
+  chain was also live-tested end to end, including a real DNS cutover. The
+  clone wizard's pull for a *nested* Bedrock site detects a source/repo
+  mismatch and refuses cleanly before creating anything, but the success
+  path — a genuinely nested repo cloning through to completion — hasn't
+  been live-validated yet. If you hit this, we'd welcome a report.
+
 ## [0.21.1] - 2026-07-10
 
 ### Fixed
@@ -1073,7 +1166,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.21.1...HEAD
+[Unreleased]: https://github.com/mwender/spinupwp-tui/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/mwender/spinupwp-tui/compare/v0.21.2...v0.22.0
+[0.21.2]: https://github.com/mwender/spinupwp-tui/compare/v0.21.1...v0.21.2
 [0.21.1]: https://github.com/mwender/spinupwp-tui/compare/v0.21.0...v0.21.1
 [0.21.0]: https://github.com/mwender/spinupwp-tui/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/mwender/spinupwp-tui/compare/v0.20.0...v0.20.1

package/README.md

@@ -29,8 +29,10 @@
 
 - **Fleet dashboard** — connection status, disk usage, pending reboots/upgrades,
   WP update counts, EOL Ubuntu flags, and a recent-activity feed for every server.
-- **Server & site browser** — a three-pane navigator with an at-a-glance status
-  column (SSH keys, HTTPS, cache, backups, linked copy, pending updates).
+- **Server & site browser** — a three-pane navigator (servers → sites →
+  details) with a full-width Control strip below showing every action for
+  whatever's selected — Site Control or Server Control, grouped and always
+  visible, no hidden key combos.
 - **Stack detection & fleet composition** — classifies every site as Standard WP,
   Bedrock, or Non-WP, with a PHP-version breakdown and an on-demand SSH probe for
   precise identification. → [docs/stack-detection.md](docs/stack-detection.md)
@@ -74,10 +76,13 @@
   [docs/uptime-kuma.md](docs/uptime-kuma.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 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)
+  `spinuptui ssh-exec <domain> -- <command>` runs a command over SSH, but only
+  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)
 - **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
@@ -96,10 +101,9 @@
   ```sh
   curl -fsSL https://bun.sh/install | bash
   ```
-- A SpinupWP API token — create one at
-  [spinupwp.app/account/api](https://spinupwp.app/account/api/). **Read Only**
-  scope is enough to browse; use **Read/Write** if you want to upgrade a site's
-  PHP version.
+- A SpinupWP API token — create one in your SpinupWP dashboard under
+  **Settings → API Tokens**. **Read Only** scope is enough to browse; use
+  **Read/Write** if you want to upgrade a site's PHP version.
 
 ## Install & run
 
@@ -167,6 +171,17 @@ spinuptui ssh <domain>  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
+                     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
+                     restarts, file redirection to a real path, etc.) is
+                     denied instead of run. Prints JSON: on success,
+                     {ok:true, exitCode, stdout, stderr, ...}; on denial,
+                     {ok:false, reason:"command_denied", message}. Every
+                     attempt (allowed, denied, or unresolved) is appended to
+                     <config dir>/logs/ssh-exec-audit.jsonl. Quote <command>
+                     as one shell argument if it needs pipes or redirects.
 spinuptui incidents <domain> | --all [--hours N]  Print Uptime Kuma down/up
                      incidents as JSON, scoped to sites SpinupTUI manages
                      monitoring for (config.json's kumaMonitors) — --all
@@ -249,6 +264,7 @@ These can be set in `config.json` or via an environment variable:
 | `H` | Enable / disable HTTPS on a site (Servers / Stacks / Search; needs a Read/Write token) |
 | `P` | Purge a site's page cache + object cache (Servers / Stacks / Search; needs a Read/Write token) |
 | `m` / `M` | Site/server monitoring — a two-pane browser of this site's Uptime Kuma monitors (`M` is an alias, since lowercase `m` is taken in Search/Stacks). Inside: `↑`/`↓` selects a monitor, `a` registers/recalibrates/repairs it (Front page and Cache bypass open a check-window picker), `x` removes Front page or Cache bypass, `o` opens the selected monitor in Kuma, `d` runs the site doctor, `n` shows/edits alert wiring, and vanity sites add `R`/`r` for page refresh/secret rotation (Servers / Stacks / Search) |
+| `R` | Refresh a vanity page's HTML to the currently bundled version — no need to open `m` first. Shown under Vanity in the Servers tab's Control strip and Search's Actions list, for the one site per server whose domain is the server's own hostname |
 | `a` | Server actions: reboot / restart a service (Servers / Search; needs a Read/Write token) |
 | `c` | Create a new server (Servers tab; needs a Read/Write token) |
 | `V` | Add a vanity site at the server's own hostname — DNS + site + HTTPS + SSH-key handoff (Servers tab; offered when no hostname site exists; needs a Read/Write token) |

package/package.json

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

package/src/index.tsx

@@ -15,6 +15,7 @@ import { isDevMode } from "./dev/devMode.ts"
 import { SpinupWPClient } from "./api/client.ts"
 import { resolveSshAccess } from "./lib/cliSsh.ts"
 import { resolveIncidents } from "./lib/cliIncidents.ts"
+import { execSshCommand } from "./lib/sshExec.ts"
 
 const args = process.argv.slice(2)
 const positionals = args.filter((a) => !a.startsWith("-"))
@@ -29,6 +30,8 @@ Usage:
   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 incidents <domain> | --all [--hours N]  Print Uptime Kuma
                        down/up incidents for a site or the whole fleet (JSON)
   spinuptui --version  Print the version
@@ -68,6 +71,23 @@ if (command === "ssh") {
   process.exit(result.ok ? 0 : 1)
 }
 
+if (command === "ssh-exec") {
+  const dashIdx = args.indexOf("--")
+  const domain = positionals[1]
+  const remoteCmd = dashIdx !== -1 ? args.slice(dashIdx + 1).join(" ") : ""
+  if (!domain || dashIdx === -1 || !remoteCmd.trim()) {
+    console.error(
+      JSON.stringify({ ok: false, reason: "usage", message: "Usage: spinuptui ssh-exec <domain> -- <command>" }),
+    )
+    process.exit(1)
+  }
+  const cfg = loadConfig()
+  const client = new SpinupWPClient(cfg)
+  const result = await execSshCommand(domain, remoteCmd, client, cfg)
+  console.log(JSON.stringify(result))
+  process.exit(result.ok ? 0 : 1)
+}
+
 if (command === "incidents") {
   const rest = args.slice(1)
   const hoursIdx = rest.indexOf("--hours")

package/src/lib/cliSsh.ts

@@ -40,13 +40,32 @@ export type SshAccessResult =
 const GRANT_KEY_REMEDY =
   "Run `spinuptui`, select this site in the Browser view, and press K to grant this device's key (sudo must be connected on the server first — press S)."
 
-export async function resolveSshAccess(
+// Resolved SSH connection details for a domain, without having tested them.
+export interface SshTargetInfo {
+  domain: string
+  primaryDomain: string
+  sshTarget: string
+  port: number | null
+  server: string
+}
+
+export type SshTargetResolution =
+  | { ok: true; info: SshTargetInfo }
+  | { ok: false; result: SshAccessResult & { ok: false } }
+
+// Domain -> site -> server -> SSH target/port, with no live connectivity check.
+// Split out of resolveSshAccess so callers that are about to run a real command
+// (which is itself a connectivity test) don't pay for a redundant probe first.
+export async function resolveSshTargetInfo(
   domain: string,
   client: SpinupWPClientLike,
   cfg: AppConfig,
-): Promise<SshAccessResult> {
+): Promise<SshTargetResolution> {
   if (!cfg.token) {
-    return { ok: false, domain, reason: "no_token", message: "No API token configured. Run `spinuptui login`." }
+    return {
+      ok: false,
+      result: { ok: false, domain, reason: "no_token", message: "No API token configured. Run `spinuptui login`." },
+    }
   }
 
   let site
@@ -59,9 +78,12 @@ export async function resolveSshAccess(
     if (matches.length === 0) {
       return {
         ok: false,
-        domain,
-        reason: "site_not_found",
-        message: `No site matching "${domain}" found in this SpinupWP account.`,
+        result: {
+          ok: false,
+          domain,
+          reason: "site_not_found",
+          message: `No site matching "${domain}" found in this SpinupWP account.`,
+        },
       }
     }
     if (matches.length > 1) {
@@ -73,10 +95,13 @@ export async function resolveSshAccess(
       )
       return {
         ok: false,
-        domain,
-        reason: "multiple_matches",
-        message: `"${domain}" matches ${matches.length} sites in this account — cannot pick one automatically.`,
-        candidates,
+        result: {
+          ok: false,
+          domain,
+          reason: "multiple_matches",
+          message: `"${domain}" matches ${matches.length} sites in this account — cannot pick one automatically.`,
+          candidates,
+        },
       }
     }
     site = matches[0]
@@ -85,27 +110,48 @@ export async function resolveSshAccess(
     if (err instanceof ApiError && err.status === 401) {
       return {
         ok: false,
-        domain,
-        reason: "token_rejected",
-        message: "Saved API token was rejected (401) — it may be expired or revoked.",
-        remedy: "Run `spinuptui login` to save a fresh token.",
+        result: {
+          ok: false,
+          domain,
+          reason: "token_rejected",
+          message: "Saved API token was rejected (401) — it may be expired or revoked.",
+          remedy: "Run `spinuptui login` to save a fresh token.",
+        },
       }
     }
     const message = err instanceof ApiError ? err.message : `Unexpected error: ${(err as Error).message}`
-    return { ok: false, domain, reason: "api_error", message }
+    return { ok: false, result: { ok: false, domain, reason: "api_error", message } }
   }
 
   if (!server.ip_address) {
     return {
       ok: false,
-      domain,
-      reason: "server_has_no_ip",
-      message: `Server "${server.name}" has no IP address on file.`,
+      result: {
+        ok: false,
+        domain,
+        reason: "server_has_no_ip",
+        message: `Server "${server.name}" has no IP address on file.`,
+      },
     }
   }
 
   const target = resolveSiteSshTarget(site, server, cfg.sshUser)
   const port = server.ssh_port && server.ssh_port !== 22 ? server.ssh_port : null
+
+  return {
+    ok: true,
+    info: { domain, primaryDomain: site.domain, sshTarget: target, port, server: server.name },
+  }
+}
+
+export async function resolveSshAccess(
+  domain: string,
+  client: SpinupWPClientLike,
+  cfg: AppConfig,
+): Promise<SshAccessResult> {
+  const resolution = await resolveSshTargetInfo(domain, client, cfg)
+  if (!resolution.ok) return resolution.result
+  const { primaryDomain, sshTarget: target, port, server: serverName } = resolution.info
   const portOpt = port ? ["-p", String(port)] : []
 
   let proc: ReturnType<typeof Bun.spawn>
@@ -132,7 +178,7 @@ export async function resolveSshAccess(
   const stderr = await new Response(proc.stderr as ReadableStream<Uint8Array>).text()
 
   if (exitCode === 0) {
-    return { ok: true, domain, primaryDomain: site.domain, sshTarget: target, port, server: server.name }
+    return { ok: true, domain, primaryDomain, sshTarget: target, port, server: serverName }
   }
 
   if (/permission denied/i.test(stderr)) {

package/src/lib/dbSync.ts

@@ -15,7 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs"
 import { join, dirname } from "node:path"
 import type { Server, Site } from "../api/types.ts"
-import { expandPath, findProjectRoot, type LocalLink } from "./local.ts"
+import { expandPath, findProjectRoot, resolveLocalLink, type LocalKind, type LocalLink } from "./local.ts"
 import { remoteDocRoot, backupBaseName, SSH_OPTS, sshPort, scpPort, runProcess, meaningfulError } from "./dbBackup.ts"
 
 // Read a KEY=value from a dotenv file, tolerating surrounding quotes. null if absent.
@@ -99,6 +99,7 @@ export interface DbSyncPlan {
   localHost: string // bare local host (hook env)
   hookPath: string | null // bin/sync.d/post-import.sh, if present
   prefixWarning: string | null // set when remote/local table prefixes differ
+  localKind: LocalKind // for a tailored hint if local wp-cli can't find an install (e.g. fresh Bedrock checkout)
 }
 
 export type SyncPlanResult = { ok: true; plan: DbSyncPlan } | { ok: false; error: string }
@@ -161,6 +162,7 @@ export function planDbSync(
         ? join(localRoot, "bin", "sync.d", "post-import.sh")
         : null,
       prefixWarning,
+      localKind: resolveLocalLink(link).kind,
     },
   }
 }
@@ -209,7 +211,15 @@ export async function runDbSync(plan: DbSyncPlan, domain: string, onProgress: (p
   }
   const localSql = plan.localBackupPath.replace(/\.gz$/, "")
   const lb = await wp(`wp db export "${localSql}" >/dev/null && gzip -f "${localSql}"`, 300_000)
-  if (lb.code !== 0) return stageFail("Local DB backup failed", lb.stderr, "couldn't export the local database.", "local-backup")
+  if (lb.code !== 0) {
+    // wp-cli's own "not a WordPress install" error is a common first-pull snag on a
+    // fresh checkout — a Bedrock project needs `composer install` to build vendor/ +
+    // web/wp before wp-cli (or wp-cli.yml) can find anything there at all. Appended
+    // after meaningfulError's own pick (not passed as its fallback), since that's
+    // only used when stderr has NO meaningful line — not the case here.
+    const hint = plan.localKind === "bedrock" && /does not seem to be a WordPress install/i.test(lb.stderr) ? " Run `composer install` in your local checkout first." : ""
+    return fail(`Local DB backup failed — ${meaningfulError(lb.stderr, "couldn't export the local database.")}${hint}`, "local-backup")
+  }
 
   // 2) Export prod + download the gzip (same remote pipeline as the backup).
   onProgress({ stage: "export", domain })

package/src/lib/probe.ts

@@ -17,6 +17,7 @@
 // view's SSH usage.
 
 import type { Server, Site } from "../api/types.ts"
+import { detectWpDirScript } from "./serverClone.ts"
 import { theme } from "./theme.ts"
 
 export type ProbeKind = "wordpress" | "bedrock" | "whmcs" | "laravel" | "static" | "unknown"
@@ -76,12 +77,21 @@ function safePublicFolder(pf: string | null): string {
   return pf
 }
 
-function buildRemoteScript(publicFolder: string | null): string {
+function buildRemoteScript(domain: string, publicFolder: string | null): string {
   const pf = safePublicFolder(publicFolder)
+  const root = `/sites/${domain}/files`
   return [
+    // detectWpDirScript anchors on the configured public folder (falling back to a
+    // bounded find), so Bedrock's project root — one level above wherever its core
+    // actually lives — is found at any nesting depth, not just when composer.json
+    // sits directly in the files root. $D/$W from this are shadowed below by the
+    // probe's own "webroot per public_folder" variables, which the rest of this
+    // script (WHMCS/index/WP-version checks) intentionally keeps using as-is.
+    detectWpDirScript(root, publicFolder ?? undefined),
+    `BEDROCKROOT="$B"`,
     'F="$HOME/files"',
     `W="$HOME/files${pf}"`,
-    'echo ===BEDROCK; grep -q "roots/bedrock" "$F/composer.json" 2>/dev/null && echo yes || echo no',
+    'echo ===BEDROCK; [ -n "$BEDROCKROOT" ] && echo yes || echo no',
     'echo ===APPLICATION; test -f "$F/config/application.php" && echo yes || echo no',
     'echo ===ARTISAN; test -f "$F/artisan" && echo yes || echo no',
     'echo ===WHMCSCONF; test -f "$W/configuration.php" && echo yes || echo no',
@@ -103,7 +113,7 @@ export async function probeSite(
 
   let proc: ReturnType<typeof Bun.spawn>
   try {
-    proc = Bun.spawn(["ssh", ...SSH_OPTS, target, buildRemoteScript(site.public_folder)], {
+    proc = Bun.spawn(["ssh", ...SSH_OPTS, target, buildRemoteScript(site.domain, site.public_folder)], {
       stdout: "pipe",
       stderr: "pipe",
       stdin: "ignore",