spinuptui 0.19.0

package/bin/spinuptui.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+// Published-package entry shim. The app must run under Bun — OpenTUI loads
+// native code via Bun's FFI — so when a Node-based global install ignores the
+// shebang, fail with instructions instead of exploding inside the renderer.
+if (!process.versions?.bun) {
+  console.error(
+    "SpinupTUI runs on Bun (its terminal renderer uses Bun-native FFI).\n" +
+      "Install Bun: https://bun.sh\n" +
+      "Then reinstall with:  bun install -g spinuptui",
+  )
+  process.exit(1)
+}
+await import("../src/index.tsx")

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "spinuptui",
+  "version": "0.19.0",
+  "description": "SpinupTUI — a terminal dashboard for browsing, monitoring, and managing your SpinupWP servers and sites.",
+  "type": "module",
+  "bin": {
+    "spinuptui": "bin/spinuptui.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mwender/spinupwp-tui.git"
+  },
+  "homepage": "https://github.com/mwender/spinupwp-tui#readme",
+  "bugs": {
+    "url": "https://github.com/mwender/spinupwp-tui/issues"
+  },
+  "scripts": {
+    "dev": "bun run src/index.tsx",
+    "start": "bun run src/index.tsx",
+    "typecheck": "tsc --noEmit",
+    "link-global": "bun link",
+    "unlink-global": "bun unlink",
+    "build:binary": "bun build src/index.tsx --compile --outfile spinuptui"
+  },
+  "keywords": [
+    "spinupwp",
+    "tui",
+    "terminal-ui",
+    "opentui",
+    "wordpress",
+    "devops",
+    "dashboard"
+  ],
+  "author": "Michael Wender",
+  "license": "MIT",
+  "dependencies": {
+    "@opentui-ui/toast": "^0.0.5",
+    "@opentui/core": "^0.4.1",
+    "@opentui/react": "^0.4.1",
+    "react": "^19.0.0",
+    "socket.io-client": "^4.8.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,354 @@
+// Thin typed wrapper around the SpinupWP REST API using fetch + Bearer auth.
+// Reads (GET) work with any token. The handful of write methods (e.g.
+// upgradeSitePhp) need a Read/Write-scoped token; since the API exposes no
+// token-scope endpoint, a write that comes back 403 is treated as "token is
+// read-only" (see mutate()).
+
+import type {
+  ApiList,
+  ApiSingle,
+  Server,
+  Site,
+  Event,
+  ProviderMetadata,
+  CreateServerPayload,
+  CreateSitePayload,
+  AdditionalDomain,
+  AddDomainPayload,
+} from "./types.ts"
+
+// The restartable services SpinupWP exposes (POST /servers/{id}/services/{svc}/restart).
+export type ServerService = "nginx" | "php" | "mysql" | "redis"
+
+export class ApiError extends Error {
+  status: number
+  body?: string
+  constructor(message: string, status: number, body?: string) {
+    super(message)
+    this.name = "ApiError"
+    this.status = status
+    this.body = body
+  }
+}
+
+export interface ClientOptions {
+  token: string
+  baseUrl: string
+}
+
+// The public surface the store (and Onboarding) actually calls. Extracted so a fake
+// implementation (see src/dev/mockClient.ts, used by SPINUP_DEV_MODE) can stand in for
+// SpinupWPClient wherever it's consumed, without either side depending on the other.
+export interface SpinupWPClientLike {
+  validateToken(): Promise<{ ok: true } | { ok: false; reason: string }>
+  listServers(): Promise<Server[]>
+  getServer(id: number): Promise<Server>
+  providerMetadata(provider: string): Promise<ProviderMetadata>
+  createServer(payload: CreateServerPayload): Promise<{ event_id: number }>
+  listSites(serverId?: number): Promise<Site[]>
+  getSite(id: number): Promise<Site>
+  createSite(payload: CreateSitePayload): Promise<{ event_id: number }>
+  enableHttps(siteId: number): Promise<{ event_id: number }>
+  disableHttps(siteId: number): Promise<{ event_id: number } | undefined>
+  purgePageCache(siteId: number): Promise<{ event_id: number }>
+  purgeObjectCache(siteId: number): Promise<{ event_id: number }>
+  listSiteDomains(siteId: number): Promise<AdditionalDomain[]>
+  addSiteDomain(siteId: number, payload: AddDomainPayload): Promise<{ event_id: number }>
+  listEvents(maxPages?: number): Promise<Event[]>
+  getEvent(id: number): Promise<Event>
+  upgradeSitePhp(siteId: number, phpVersion: string): Promise<{ event_id: number }>
+  rebootServer(serverId: number): Promise<{ event_id: number }>
+  restartService(serverId: number, service: ServerService): Promise<{ event_id: number }>
+}
+
+const MAX_PAGES = 100 // hard safety cap when auto-paginating
+
+// ---- Rate-limit awareness -------------------------------------------------
+// SpinupWP sends X-RateLimit-Remaining on every response (Laravel throttle,
+// 1-minute windows). All traffic funnels through fetchWithRateLimit below:
+// PROACTIVE pacing — when the window is nearly spent, spread the remaining
+// requests across what's left of it instead of slamming into the wall — plus
+// REACTIVE Retry-After backoff on 429 (safe to retry: a 429 was rejected before
+// any processing). Module-level so every client instance shares one budget.
+// Born from the 2026-07-02 prod clone retry, where three concurrent site workers'
+// event polling burned the window and made SUCCESSFUL operations look failed.
+let rlRemaining = Infinity
+let rlResetAt = 0
+const RL_LOW_WATER = 8 // start pacing when fewer than this many requests remain
+const RL_MAX_RETRIES = 3
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+function rlUpdate(headers: Headers): void {
+  const rem = Number(headers.get("x-ratelimit-remaining"))
+  if (Number.isFinite(rem)) rlRemaining = rem
+  // No reset header outside 429s — assume the standard 1-minute window rolls over.
+  if (rlResetAt < Date.now()) rlResetAt = Date.now() + 60_000
+}
+
+async function rlGate(): Promise<void> {
+  if (rlRemaining > RL_LOW_WATER) return
+  const windowLeft = Math.max(0, rlResetAt - Date.now())
+  const delay = rlRemaining <= 1 ? windowLeft : Math.ceil(windowLeft / Math.max(1, rlRemaining))
+  if (delay > 0) await sleep(delay + Math.random() * 300)
+}
+
+export class SpinupWPClient implements SpinupWPClientLike {
+  private token: string
+  private baseUrl: string
+
+  constructor(opts: ClientOptions) {
+    this.token = opts.token
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "")
+  }
+
+  // Gate → fetch → learn from headers; on 429 wait out Retry-After (default 20s)
+  // and retry a few times before surfacing it. Network errors become ApiError(0).
+  private async fetchWithRateLimit(url: string, init: RequestInit): Promise<Response> {
+    for (let attempt = 0; ; attempt++) {
+      await rlGate()
+      let res: Response
+      try {
+        res = await fetch(url, init)
+      } catch (err) {
+        throw new ApiError(`Network error reaching the SpinupWP API: ${(err as Error).message}`, 0)
+      }
+      rlUpdate(res.headers)
+      if (res.status === 429 && attempt < RL_MAX_RETRIES) {
+        const ra = Number(res.headers.get("retry-after"))
+        const waitMs = (Number.isFinite(ra) && ra > 0 ? ra : 20) * 1000
+        rlRemaining = 0
+        rlResetAt = Date.now() + waitMs
+        await sleep(waitMs + Math.random() * 500)
+        continue
+      }
+      return res
+    }
+  }
+
+  private async request<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T> {
+    const url = new URL(this.baseUrl + path)
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null) url.searchParams.set(k, String(v))
+      }
+    }
+
+    const res = await this.fetchWithRateLimit(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Accept: "application/json",
+        "User-Agent": "spinupwp-tui",
+      },
+    })
+
+    if (res.status === 401) {
+      throw new ApiError("Unauthorized — your access token was rejected (401).", 401)
+    }
+    if (res.status === 403) {
+      throw new ApiError("Forbidden — this token lacks permission for that resource (403).", 403)
+    }
+    if (res.status === 429) {
+      throw new ApiError("Rate limited by the SpinupWP API (429). Try again shortly.", 429)
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => "")
+      throw new ApiError(`SpinupWP API error (HTTP ${res.status}).`, res.status, body)
+    }
+
+    return (await res.json()) as T
+  }
+
+  // Write request (POST/PUT/PATCH/DELETE) with a JSON body. A 403 here almost
+  // always means the token lacks Read/Write scope — there's no scope endpoint to
+  // check up front, so we detect it by attempting the write and translating the
+  // 403 into an actionable message. All other statuses mirror request().
+  private async mutate<T>(path: string, method: string, body?: unknown): Promise<T> {
+    const url = this.baseUrl + path
+    const res = await this.fetchWithRateLimit(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "spinupwp-tui",
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+
+    if (res.status === 401) {
+      throw new ApiError("Unauthorized — your access token was rejected (401).", 401)
+    }
+    if (res.status === 403) {
+      throw new ApiError(
+        "Your token is read-only — this action needs a Read/Write token. Run `spinuptui login` to set one.",
+        403,
+      )
+    }
+    if (res.status === 429) {
+      throw new ApiError("Rate limited by the SpinupWP API (429). Try again shortly.", 429)
+    }
+    if (!res.ok) {
+      const errBody = await res.text().catch(() => "")
+      throw new ApiError(`SpinupWP API error (HTTP ${res.status}).`, res.status, errBody)
+    }
+
+    // Some write endpoints (e.g. PHP upgrade) return a bare body, others 204.
+    if (res.status === 204) return undefined as T
+    return (await res.json().catch(() => undefined)) as T
+  }
+
+  // Fetch a single page of a list resource.
+  private listPage<T>(path: string, page: number, params?: Record<string, string | number | undefined>) {
+    return this.request<ApiList<T>>(path, { page, limit: 100, ...params })
+  }
+
+  // Follow pagination until exhausted, aggregating all items.
+  private async listAll<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T[]> {
+    const all: T[] = []
+    let page = 1
+    while (page <= MAX_PAGES) {
+      const res = await this.listPage<T>(path, page, params)
+      all.push(...res.data)
+      if (!res.pagination?.next) break
+      page += 1
+    }
+    return all
+  }
+
+  // ---- Token validation -------------------------------------------------
+
+  // Lightweight call used by onboarding to verify a token works.
+  async validateToken(): Promise<{ ok: true } | { ok: false; reason: string }> {
+    try {
+      await this.request<ApiList<Server>>("/servers", { limit: 1 })
+      return { ok: true }
+    } catch (err) {
+      if (err instanceof ApiError) return { ok: false, reason: err.message }
+      return { ok: false, reason: (err as Error).message }
+    }
+  }
+
+  // ---- Servers ----------------------------------------------------------
+
+  listServers(): Promise<Server[]> {
+    return this.listAll<Server>("/servers")
+  }
+
+  async getServer(id: number): Promise<Server> {
+    const res = await this.request<ApiSingle<Server>>(`/servers/${id}`)
+    return res.data
+  }
+
+  // The catalog of sizes + regions (with pricing) a provider offers. Provider is
+  // a key the API recognizes: digitalocean | vultr | linode | hetzner. The
+  // endpoint may or may not be data-wrapped, so normalize defensively.
+  async providerMetadata(provider: string): Promise<ProviderMetadata> {
+    const raw = await this.request<Record<string, unknown>>(`/providers/${provider}/metadata`)
+    const data = raw && typeof raw === "object" && "data" in raw ? (raw.data as Record<string, unknown>) : raw
+    return data as unknown as ProviderMetadata
+  }
+
+  // Provision a managed server. Async on SpinupWP's side: returns an event_id to
+  // poll via getEvent() (provisioning averages ~10 min). Needs a Read/Write token.
+  createServer(payload: CreateServerPayload): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>("/servers", "POST", payload)
+  }
+
+  // ---- Sites ------------------------------------------------------------
+
+  listSites(serverId?: number): Promise<Site[]> {
+    return this.listAll<Site>("/sites", serverId ? { server_id: serverId } : undefined)
+  }
+
+  async getSite(id: number): Promise<Site> {
+    const res = await this.request<ApiSingle<Site>>(`/sites/${id}`)
+    return res.data
+  }
+
+  // Create a site. Async on SpinupWP's side: returns an event_id to poll via
+  // getEvent(). Needs a Read/Write token. HTTPS is enabled separately — see
+  // enableHttps().
+  createSite(payload: CreateSitePayload): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>("/sites", "POST", payload)
+  }
+
+  // Additional domains on a site (the extra hostnames nginx answers for). The
+  // clone wizard re-creates the source's set on the dest — a fresh site only
+  // serves its primary domain otherwise.
+  async listSiteDomains(siteId: number): Promise<AdditionalDomain[]> {
+    return this.listAll<AdditionalDomain>(`/sites/${siteId}/domains`)
+  }
+
+  // Add an additional domain to a site. Async (nginx reconfig) → returns an
+  // event_id to poll. Needs a Read/Write token.
+  addSiteDomain(siteId: number, payload: AddDomainPayload): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/domains`, "POST", payload)
+  }
+
+  // Enable HTTPS on a site. `type: "webroot"` requests a Let's Encrypt cert (the
+  // domain must already resolve to the server for LE to issue, so this runs after
+  // the DNS A record has propagated). Async → returns an event_id to poll. Needs a
+  // Read/Write token.
+  enableHttps(siteId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/https`, "POST", { type: "webroot" })
+  }
+
+  // Disable HTTPS on a site (removes the certificate). May return an event_id to
+  // poll, or settle synchronously (204 → undefined) — the store handles both.
+  // Needs a Read/Write token.
+  disableHttps(siteId: number): Promise<{ event_id: number } | undefined> {
+    return this.mutate<{ event_id: number } | undefined>(`/sites/${siteId}/https`, "DELETE")
+  }
+
+  // Purge a site's page cache / WordPress object cache. There's no enable/disable
+  // for either on an existing site (only at site-creation time) — purge is the
+  // only available write. Async → returns an event_id to poll. Needs a Read/Write
+  // token.
+  purgePageCache(siteId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/page-cache/purge`, "POST")
+  }
+  purgeObjectCache(siteId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/object-cache/purge`, "POST")
+  }
+
+  // ---- Events -----------------------------------------------------------
+
+  // Events can be numerous; cap to the most recent few pages for the feed.
+  async listEvents(maxPages = 3): Promise<Event[]> {
+    const all: Event[] = []
+    let page = 1
+    while (page <= maxPages) {
+      const res = await this.listPage<Event>("/events", page)
+      all.push(...res.data)
+      if (!res.pagination?.next) break
+      page += 1
+    }
+    return all
+  }
+
+  // Fetch a single event by id — used to track an async write to completion.
+  async getEvent(id: number): Promise<Event> {
+    const res = await this.request<ApiSingle<Event>>(`/events/${id}`)
+    return res.data
+  }
+
+  // ---- Writes -----------------------------------------------------------
+
+  // Change a site's PHP version. Async on SpinupWP's side: returns an event_id
+  // to poll via getEvent(). SpinupWP installs the version on the server first if
+  // it isn't already present. Needs a Read/Write token (see mutate()).
+  upgradeSitePhp(siteId: number, phpVersion: string): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/sites/${siteId}/php`, "PUT", { php_version: phpVersion })
+  }
+
+  // Reboot a server. Async → returns an event_id to poll via getEvent().
+  rebootServer(serverId: number): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/servers/${serverId}/reboot`, "POST")
+  }
+
+  // Restart a single service on a server (nginx / php / mysql / redis). Async →
+  // returns an event_id to poll via getEvent().
+  restartService(serverId: number, service: ServerService): Promise<{ event_id: number }> {
+    return this.mutate<{ event_id: number }>(`/servers/${serverId}/services/${service}/restart`, "POST")
+  }
+}

package/src/api/types.ts

@@ -0,0 +1,206 @@
+// Type definitions for the SpinupWP REST API (v1).
+// Kept intentionally permissive — the API may add fields over time, and we only
+// depend on the subset we render. See https://api.spinupwp.com/ for the full spec.
+
+export interface Pagination {
+  previous: string | null
+  next: string | null
+  per_page: number
+  count: number
+}
+
+export interface ApiList<T> {
+  data: T[]
+  pagination: Pagination
+}
+
+export interface ApiSingle<T> {
+  data: T
+}
+
+export interface DiskSpace {
+  total: number
+  available: number
+  used: number
+  updated_at: string | null
+}
+
+export interface ServerDatabase {
+  server: string | null
+  host: string | null
+  port: number | null
+}
+
+export type ConnectionStatus = "connected" | "disconnected" | "connecting" | string
+
+export interface Server {
+  id: number
+  name: string
+  provider_name: string | null
+  ubuntu_version: string | null
+  ip_address: string | null
+  ssh_port: number | null
+  timezone: string | null
+  region: string | null
+  size: string | null
+  disk_space: DiskSpace | null
+  database: ServerDatabase | null
+  ssh_publickey?: string | null
+  git_publickey?: string | null
+  connection_status: ConnectionStatus
+  reboot_required: boolean
+  upgrade_required: boolean
+  install_notes?: string | null
+  created_at: string
+  status: string
+}
+
+export interface AdditionalDomain {
+  id: number
+  domain: string
+  redirect?: {
+    enabled: boolean
+    type: number
+    destination: string
+  }
+  created_at: string
+}
+
+export interface Site {
+  id: number
+  server_id: number
+  domain: string
+  additional_domains?: AdditionalDomain[]
+  site_user: string | null
+  php_version: string | null
+  public_folder: string | null
+  is_wordpress: boolean
+  page_cache?: { enabled: boolean }
+  https?: { enabled: boolean }
+  nginx?: Record<string, unknown>
+  database?: {
+    id: number | null
+    user_id: number | null
+    table_prefix: string | null
+  } | null
+  backups?: {
+    files: boolean
+    database: boolean
+    retention_period?: number | null
+    next_run_time?: string | null
+    storage_provider?: { id: number; region: string; bucket: string } | null
+  } | null
+  wp_core_update?: boolean
+  wp_theme_updates?: number
+  wp_plugin_updates?: number
+  git?: {
+    repo: string | null
+    branch: string | null
+    deploy_script?: string | null
+    push_enabled?: boolean
+    deployment_url?: string | null
+  } | null
+  basic_auth?: { enabled: boolean; username?: string | null } | null
+  subdomain?: { enabled: boolean; url: string | null } | null
+  created_at: string
+  status: string
+}
+
+// Server-provider metadata (GET /providers/{provider}/metadata) — the catalog of
+// sizes and regions a provider offers, including pricing. Used to show "match
+// source" specs + a monthly cost before creating a server.
+export interface ProviderSize {
+  slug: string
+  type?: string
+  memory: number // MB
+  vcpus: number
+  disk: number // GB
+  transfer?: number
+  priceMonthly: number
+  backupPriceMonthly?: number
+  available?: boolean
+  processor?: string
+}
+
+export interface ProviderRegion {
+  slug: string
+  name: string
+  available?: boolean
+  continent?: string
+  sizes: string[] // size slugs offered in this region
+}
+
+export interface ProviderMetadata {
+  regions: Record<string, ProviderRegion[]> // grouped by continent name
+  sizes: ProviderSize[]
+}
+
+// Request body for POST /servers (provision a managed server). The API uses
+// bracketed form keys (server_provider[id], …) which map to these nested objects.
+export interface CreateServerPayload {
+  server_provider: {
+    id?: number // an existing provider connection (from SpinupWP Account Settings)
+    name?: string // or provider name + token to use an unsaved provider
+    api_token?: string
+    region: string
+    size: string
+    enable_backups?: boolean
+  }
+  hostname: string
+  timezone?: string
+  database?: { root_password?: string }
+  database_provider?: { id: number }
+  post_provision_script?: string
+}
+
+// POST /sites. HTTPS is NOT a creation field — it's enabled afterward via
+// POST /sites/{id}/https (see SpinupWPClient.enableHttps). For a vanity/placeholder
+// site we use installation_method "blank" (empty docroot we drop an index.php into).
+// POST /sites/{id}/domains — add an additional domain (async, returns event_id).
+// redirect.type: 301/302/307/308 (defaults 301); redirect.destination defaults to
+// the site's primary domain.
+export interface AddDomainPayload {
+  domain: string
+  redirect?: { enabled?: boolean; type?: number; destination?: string }
+}
+
+export interface CreateSitePayload {
+  server_id: number
+  domain: string
+  site_user: string
+  installation_method: "wp" | "wp_subdirectory" | "wp_subdomain" | "git" | "blank"
+  php_version?: string // defaults to 8.3 server-side
+  public_folder?: string // defaults to "/"
+  database?: { name?: string; username?: string; password?: string; table_prefix?: string }
+  page_cache?: { enabled?: boolean }
+  // installation_method "git" (Bedrock): SpinupWP clones `git.repo` at create time.
+  // We always send a UNIQUE per-site keypair via `deploy_key_enabled` + `deploy_key`
+  // (SpinupWP installs it as the site's git identity) — the server-wide git_publickey
+  // can only be attached to ONE GitHub repo account-wide, so it can never cover a
+  // second repo on the same server (verified 2026-07-06). The public half must be a
+  // read-only deploy key on the repo before create or the clone fails. `deploy_script`
+  // is TOP-LEVEL (a nested git.deploy_script is silently ignored); the write key is
+  // `push_to_deploy` (the read shape echoes it back as git.push_enabled). See the
+  // site-creation findings doc.
+  deploy_script?: string
+  git?: {
+    repo: string
+    branch?: string
+    push_to_deploy?: boolean
+    always_run_deploy_script?: boolean
+    deploy_key_enabled?: boolean
+    deploy_key?: { privatekey: string; publickey: string }
+  }
+}
+
+export interface Event {
+  id: number
+  initiated_by: string | null
+  server_id: number | null
+  name: string
+  status: string
+  output: string | null
+  created_at: string
+  started_at: string | null
+  finished_at: string | null
+}