spinuptui 0.19.0

package/src/dev/mockClient.ts

@@ -0,0 +1,214 @@
+// In-memory stand-in for SpinupWPClient, used when SPINUP_DEV_MODE is on (see
+// devMode.ts). Backed by the fixture fleet in fixtures.ts; writes mutate this
+// module's own copy of the data and never touch the network. Event polling
+// simulates a couple of "running" ticks before settling "deployed" so the same
+// spinners/toasts a real write shows are visible in a demo.
+//
+// Every write here always succeeds — Dev Mode is for showing the UI's happy path,
+// not for testing SpinupWP's error handling (the real client covers that).
+
+import type {
+  CreateServerPayload,
+  CreateSitePayload,
+  Event,
+  ProviderMetadata,
+  Server,
+  Site,
+} from "../api/types.ts"
+import type { ServerService, SpinupWPClientLike } from "../api/client.ts"
+import { freshFixtures } from "./fixtures.ts"
+
+const EVENT_POLLS_BEFORE_DONE = 2 // ~2 poll intervals of visible "in progress" state
+
+function nextIdAfter(items: { id: number }[], floor: number): number {
+  return Math.max(floor, ...items.map((i) => i.id)) + 1
+}
+
+function fakeProviderMetadata(): ProviderMetadata {
+  return {
+    regions: {
+      "North America": [
+        { slug: "nyc3", name: "New York 3", available: true, continent: "North America", sizes: ["s-1vcpu-2gb", "s-2vcpu-4gb"] },
+      ],
+    },
+    sizes: [
+      { slug: "s-1vcpu-2gb", type: "standard", memory: 2048, vcpus: 1, disk: 50, priceMonthly: 12, available: true },
+      { slug: "s-2vcpu-4gb", type: "standard", memory: 4096, vcpus: 2, disk: 80, priceMonthly: 24, available: true },
+    ],
+  }
+}
+
+export function createMockClient(): SpinupWPClientLike {
+  const { servers, sites, events } = freshFixtures()
+  let nextServerId = nextIdAfter(servers, 200)
+  let nextSiteId = nextIdAfter(sites, 2000)
+  let nextEventId = nextIdAfter(events, 9100)
+  const eventPolls = new Map<number, number>()
+
+  function pushEvent(name: string, serverId: number | null, output: string): number {
+    const id = nextEventId++
+    const now = new Date().toISOString()
+    events.unshift({ id, initiated_by: "dev-mode", server_id: serverId, name, status: "running", output, created_at: now, started_at: now, finished_at: null })
+    return id
+  }
+
+  return {
+    async validateToken() {
+      return { ok: true }
+    },
+
+    async listServers() {
+      return servers.map((s) => ({ ...s }))
+    },
+
+    async getServer(id) {
+      const found = servers.find((s) => s.id === id)
+      if (!found) throw new Error(`dev mode: no such server ${id}`)
+      return { ...found }
+    },
+
+    async providerMetadata() {
+      return fakeProviderMetadata()
+    },
+
+    async createServer(payload: CreateServerPayload) {
+      const id = nextServerId++
+      const server: Server = {
+        id,
+        name: payload.hostname,
+        provider_name: payload.server_provider.name ?? "digitalocean",
+        ubuntu_version: "24.04",
+        ip_address: `203.0.113.${(id % 200) + 20}`,
+        ssh_port: 22,
+        timezone: payload.timezone ?? "UTC",
+        region: payload.server_provider.region,
+        size: payload.server_provider.size,
+        disk_space: { total: 80 * 1024 * 1024 * 1024, available: 78 * 1024 * 1024 * 1024, used: 2 * 1024 * 1024 * 1024, updated_at: new Date().toISOString() },
+        database: null,
+        connection_status: "connected",
+        reboot_required: false,
+        upgrade_required: false,
+        created_at: new Date().toISOString(),
+        status: "active",
+      }
+      servers.push(server)
+      const event_id = pushEvent("server.provisioned", id, `Server ${payload.hostname} provisioned`)
+      return { event_id }
+    },
+
+    async listSites(serverId) {
+      const rows = serverId ? sites.filter((s) => s.server_id === serverId) : sites
+      return rows.map((s) => ({ ...s }))
+    },
+
+    async getSite(id) {
+      const found = sites.find((s) => s.id === id)
+      if (!found) throw new Error(`dev mode: no such site ${id}`)
+      return { ...found }
+    },
+
+    async createSite(payload: CreateSitePayload) {
+      const id = nextSiteId++
+      const site: Site = {
+        id,
+        server_id: payload.server_id,
+        domain: payload.domain,
+        site_user: payload.site_user,
+        php_version: payload.php_version ?? "8.3",
+        public_folder: payload.public_folder ?? "/",
+        is_wordpress: payload.installation_method !== "blank",
+        page_cache: { enabled: payload.page_cache?.enabled ?? false },
+        https: { enabled: false },
+        database: payload.database ? { id, user_id: id, table_prefix: payload.database.table_prefix ?? "wp_" } : null,
+        git: payload.git ? { repo: payload.git.repo, branch: payload.git.branch ?? "main", deploy_script: payload.deploy_script ?? null, push_enabled: payload.git.push_to_deploy ?? false, deployment_url: null } : null,
+        wp_core_update: false,
+        wp_theme_updates: 0,
+        wp_plugin_updates: 0,
+        created_at: new Date().toISOString(),
+        status: "active",
+      }
+      sites.push(site)
+      const event_id = pushEvent("site.created", payload.server_id, `Site ${payload.domain} created`)
+      return { event_id }
+    },
+
+    async enableHttps(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.https = { enabled: true }
+      const event_id = pushEvent("site.https.enabled", site?.server_id ?? null, `HTTPS enabled for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async disableHttps(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.https = { enabled: false }
+      const event_id = pushEvent("site.https.disabled", site?.server_id ?? null, `HTTPS disabled for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async purgePageCache(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      const event_id = pushEvent("site.cache.purged", site?.server_id ?? null, `Page cache purged for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async purgeObjectCache(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      const event_id = pushEvent("site.object_cache.purged", site?.server_id ?? null, `Object cache purged for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async listSiteDomains(siteId) {
+      const site = sites.find((s) => s.id === siteId)
+      return (site?.additional_domains ?? []).map((d) => ({ ...d }))
+    },
+
+    async addSiteDomain(siteId, payload) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) {
+        site.additional_domains = site.additional_domains ?? []
+        const domId = 9000 + sites.reduce((n, x) => n + (x.additional_domains?.length ?? 0), 0)
+        site.additional_domains.push({ id: domId, domain: payload.domain, redirect: { enabled: payload.redirect?.enabled ?? false, type: payload.redirect?.type ?? 301, destination: payload.redirect?.destination ?? site.domain }, created_at: new Date().toISOString() })
+      }
+      const event_id = pushEvent("site.domains.updated", site?.server_id ?? null, `Updating domains for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async listEvents(maxPages) {
+      const limit = (maxPages ?? 3) * 100
+      return events.slice(0, limit).map((e) => ({ ...e }))
+    },
+
+    async getEvent(id) {
+      const found = events.find((e) => e.id === id)
+      if (!found) throw new Error(`dev mode: no such event ${id}`)
+      const polls = (eventPolls.get(id) ?? 0) + 1
+      eventPolls.set(id, polls)
+      if (polls >= EVENT_POLLS_BEFORE_DONE && found.status === "running") {
+        found.status = "deployed"
+        found.finished_at = new Date().toISOString()
+      }
+      return { ...found }
+    },
+
+    async upgradeSitePhp(siteId, phpVersion) {
+      const site = sites.find((s) => s.id === siteId)
+      if (site) site.php_version = phpVersion
+      const event_id = pushEvent("site.php_version.updated", site?.server_id ?? null, `PHP updated to ${phpVersion} for ${site?.domain ?? siteId}`)
+      return { event_id }
+    },
+
+    async rebootServer(serverId) {
+      const server = servers.find((s) => s.id === serverId)
+      if (server) server.reboot_required = false
+      const event_id = pushEvent("server.rebooted", serverId, `Server ${server?.name ?? serverId} rebooted`)
+      return { event_id }
+    },
+
+    async restartService(serverId, service: ServerService) {
+      const server = servers.find((s) => s.id === serverId)
+      const event_id = pushEvent(`server.service.${service}.restarted`, serverId, `${service} restarted on ${server?.name ?? serverId}`)
+      return { event_id }
+    },
+  }
+}

package/src/index.tsx

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+// Entry point. Handles a few non-interactive CLI subcommands, then boots the
+// OpenTUI renderer and mounts either the first-run onboarding wizard (no token
+// yet) or the main app wrapped in the data store.
+
+import { useState } from "react"
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import pkg from "../package.json" with { type: "json" }
+import { hasToken, configPath, loadConfig } from "./config.ts"
+import { StoreProvider } from "./ui/store.tsx"
+import { App } from "./ui/App.tsx"
+import { Onboarding } from "./ui/Onboarding.tsx"
+import { isDevMode } from "./dev/devMode.ts"
+
+const args = process.argv.slice(2)
+const command = args.find((a) => !a.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
+
+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 --version  Print the version
+  spinuptui --help     Show this help
+
+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.
+
+Config file: ${configPath()}
+Token source: ${cfg.tokenSource}`)
+  process.exit(0)
+}
+
+if (args.includes("-v") || args.includes("--version") || command === "version") {
+  console.log(pkg.version)
+  process.exit(0)
+}
+
+if (command === "where") {
+  const cfg = loadConfig()
+  console.log(`config: ${configPath()}`)
+  console.log(`token source: ${cfg.tokenSource}`)
+  process.exit(0)
+}
+
+// `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"
+
+function Root() {
+  const [configured, setConfigured] = useState(isDevMode() ? true : forceLogin ? false : hasToken())
+  if (!configured) {
+    return <Onboarding onComplete={() => setConfigured(true)} />
+  }
+  return (
+    <StoreProvider>
+      <App />
+    </StoreProvider>
+  )
+}
+
+const renderer = await createCliRenderer()
+createRoot(renderer).render(<Root />)

package/src/lib/appUpdate.ts

@@ -0,0 +1,206 @@
+// "Update available" check: compare the running version to the latest GitHub
+// release, so a `✨ vX.Y.Z` hint can nudge users — either to update in-app (`u`
+// in the Help/About overlay, see runSelfUpdate below) or with a manual `git pull`.
+//
+// Polling model: checked once per launch, backed by a disk cache with a 6h TTL —
+// so frequent open/close cycles reuse the cached result instead of hitting GitHub
+// each time (releases are infrequent; the unauthenticated API allows 60 req/hr).
+// Never throws and degrades gracefully offline.
+
+import { join, sep } from "node:path"
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"
+import { configDir } from "../config.ts"
+import { REPO_SLUG } from "../version.ts"
+
+const CACHE_VERSION = 1
+const TTL_MS = 6 * 60 * 60 * 1000 // 6 hours
+const FETCH_TIMEOUT_MS = 5000
+
+export interface UpdateInfo {
+  current: string // running version
+  latest: string // latest released version (no leading "v")
+  url: string // release page
+  updateAvailable: boolean
+}
+
+interface CacheFile {
+  version: number
+  checkedAt: number // epoch ms
+  latest: string | null
+  url: string | null
+}
+
+function cachePath(): string {
+  return join(configDir(), "update-check.json")
+}
+
+// Parse "v1.2.3" / "1.2.3" → [1,2,3]; null when it doesn't look like a version.
+function parseVersion(s: string): [number, number, number] | null {
+  const m = s.trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)\.(\d+)/)
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+}
+
+// Strictly-newer comparison (latest > current). Unparseable → false (never nag).
+function isNewer(latest: string, current: string): boolean {
+  const a = parseVersion(latest)
+  const b = parseVersion(current)
+  if (!a || !b) return false
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i]
+  }
+  return false
+}
+
+function readCache(): CacheFile | null {
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath(), "utf8")) as CacheFile
+    return parsed?.version === CACHE_VERSION ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function writeCache(latest: string | null, url: string | null): void {
+  try {
+    mkdirSync(configDir(), { recursive: true })
+    const file: CacheFile = { version: CACHE_VERSION, checkedAt: Date.now(), latest, url }
+    writeFileSync(cachePath(), JSON.stringify(file))
+  } catch {
+    /* best-effort; a failed cache write just means we re-check next launch */
+  }
+}
+
+function deriveInfo(current: string, latest: string | null, url: string | null): UpdateInfo | null {
+  if (!latest) return null
+  return { current, latest, url: url ?? `https://github.com/${REPO_SLUG}/releases`, updateAvailable: isNewer(latest, current) }
+}
+
+// Synchronous read of whatever we last cached — used to show a hint instantly on
+// launch without waiting on the network. Returns null when nothing is cached.
+export function cachedUpdateInfo(current: string): UpdateInfo | null {
+  const c = readCache()
+  return c ? deriveInfo(current, c.latest, c.url) : null
+}
+
+// Hit GitHub for the latest release; null on any failure (offline, rate limit, no
+// releases yet). Times out so it can't hang the launch.
+async function fetchLatestRelease(): Promise<{ latest: string; url: string } | null> {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const res = await fetch(`https://api.github.com/repos/${REPO_SLUG}/releases/latest`, {
+      headers: {
+        "User-Agent": "spinup-tui",
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      signal: ctrl.signal,
+    })
+    if (!res.ok) return null
+    const json = (await res.json()) as { tag_name?: string; html_url?: string }
+    const tag = json.tag_name?.replace(/^v/i, "")
+    if (!tag) return null
+    return { latest: tag, url: json.html_url ?? `https://github.com/${REPO_SLUG}/releases` }
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// The launch-time check: returns the freshest info we can, hitting GitHub only
+// when the cache is stale (older than the TTL). Falls back to a stale cache if
+// the network fails. Returns null only when we have nothing at all.
+export async function refreshUpdateInfo(current: string): Promise<UpdateInfo | null> {
+  const cache = readCache()
+  if (cache && Date.now() - cache.checkedAt < TTL_MS) {
+    return deriveInfo(current, cache.latest, cache.url)
+  }
+  const fetched = await fetchLatestRelease()
+  if (fetched) {
+    writeCache(fetched.latest, fetched.url)
+    return deriveInfo(current, fetched.latest, fetched.url)
+  }
+  // Network failed — keep whatever we had so the hint doesn't flicker off.
+  return cache ? deriveInfo(current, cache.latest, cache.url) : null
+}
+
+// ---- In-app updater (`u` in the Help/About overlay) ------------------------
+
+// How this copy of the app was installed, which decides the update path shown
+// in Help/About: a package-manager install (bun/npm global) lives under a
+// node_modules dir and updates via `bun update -g spinuptui`; anything else is
+// treated as a git checkout and updates via `git pull` (runSelfUpdate).
+export type InstallChannel = "git" | "package"
+
+export function installChannel(): InstallChannel {
+  return import.meta.dir.includes(`${sep}node_modules${sep}`) ? "package" : "git"
+}
+
+// The one-liner Help shows for a package install (also used by runSelfUpdate's
+// "not a checkout" message so every path names the same command).
+export const PACKAGE_UPDATE_CMD = "bun update -g spinuptui"
+
+// The real checkout directory, resolved through Bun's module system rather
+// than process.cwd() — `spinuptui` is typically a global symlink invoked from
+// wherever the user happens to be, so cwd is meaningless here. import.meta.dir
+// follows the symlink to this file's REAL location (verified: it does not
+// resolve to the symlink's own path or the invoking shell's cwd).
+function checkoutRoot(): string {
+  return join(import.meta.dir, "..", "..")
+}
+
+async function git(cwd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["git", "-C", cwd, ...args], { stdout: "pipe", stderr: "pipe", stdin: "ignore" })
+  const [stdout, stderr, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited])
+  return { code, stdout: stdout.trim(), stderr: stderr.trim() }
+}
+
+export interface SelfUpdateResult {
+  ok: boolean
+  message: string
+  // package.json / bun.lock changed — the running code on disk now needs
+  // `bun install` before it'll actually run.
+  needsInstall: boolean
+}
+
+// `git pull --ff-only` in the checkout, with the safety rails a self-updater
+// needs: refuse on a dirty tree (this is the user's own dev checkout, not an
+// opaque install dir — never silently overwrite their uncommitted work), and
+// never attempt a merge/rebase that could produce conflicts (--ff-only). Can't
+// hot-reload the already-running process — the result always says "on disk",
+// never implies the update is live without a restart.
+// `cwd` defaults to the real checkout; overridable so this is testable against
+// a disposable sandbox without ever touching the real repo's git state.
+export async function runSelfUpdate(cwd: string = checkoutRoot()): Promise<SelfUpdateResult> {
+  try {
+    const isRepo = await git(cwd, ["rev-parse", "--is-inside-work-tree"])
+    if (isRepo.code !== 0 || isRepo.stdout !== "true") {
+      return { ok: false, message: `This install isn't a git checkout — update with \`${PACKAGE_UPDATE_CMD}\`.`, needsInstall: false }
+    }
+    const status = await git(cwd, ["status", "--porcelain"])
+    if (status.stdout.length > 0) {
+      return { ok: false, message: "Your checkout has uncommitted changes — commit or stash them, then try again.", needsInstall: false }
+    }
+    const before = await git(cwd, ["rev-parse", "HEAD"])
+    const pull = await git(cwd, ["pull", "--ff-only"])
+    if (pull.code !== 0) {
+      return { ok: false, message: pull.stderr || pull.stdout || "git pull failed.", needsInstall: false }
+    }
+    const after = await git(cwd, ["rev-parse", "HEAD"])
+    if (before.stdout && before.stdout === after.stdout) {
+      return { ok: true, message: "Already up to date.", needsInstall: false }
+    }
+    const diff = await git(cwd, ["diff", "--name-only", before.stdout, after.stdout])
+    const needsInstall = /(^|\/)(package\.json|bun\.lock)$/m.test(diff.stdout)
+    return {
+      ok: true,
+      needsInstall,
+      message: needsInstall
+        ? "Updated on disk — run `bun install`, then press q and restart spinuptui."
+        : "Updated on disk — press q and restart spinuptui.",
+    }
+  } catch (err) {
+    return { ok: false, message: `Update failed: ${(err as Error).message}`, needsInstall: false }
+  }
+}

package/src/lib/awsSigV4.ts

@@ -0,0 +1,133 @@
+// Hand-rolled AWS Signature Version 4 — no `aws` CLI, no SDK. We only issue a
+// handful of calls: read-only GETs (STS GetCallerIdentity, Route 53
+// ListHostedZonesByName / ListResourceRecordSets) and one write POST (Route 53
+// ChangeResourceRecordSets, for editing a record's TTL). The full SigV4 algorithm
+// for a signed request — empty body for GETs, hashed XML body for the POST — is
+// all we need, which keeps the app dependency-light (node:crypto + fetch only).
+//
+// Reference: docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html
+// signGetV4 is verified against AWS's published "get-vanilla" test vector.
+
+import { createHash, createHmac } from "node:crypto"
+
+export interface AwsCreds {
+  accessKeyId: string
+  secretAccessKey: string
+  region?: string // defaults to us-east-1 (Route 53 + STS are global, signed in us-east-1)
+  sessionToken?: string
+}
+
+function sha256hex(data: string): string {
+  return createHash("sha256").update(data, "utf8").digest("hex")
+}
+function hmac(key: string | Buffer, data: string): Buffer {
+  return createHmac("sha256", key).update(data, "utf8").digest()
+}
+
+// AWS URI-encoding (RFC 3986): encodeURIComponent plus the four chars it leaves.
+function enc(s: string): string {
+  return encodeURIComponent(s).replace(/[!*'()]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase())
+}
+
+export interface SignOptions {
+  creds: AwsCreds
+  service: string
+  host: string
+  method?: string // defaults to GET
+  path: string // already in canonical form (we only use simple ASCII paths)
+  query?: Record<string, string>
+  body?: string // request body (empty string for GET)
+  contentType?: string // sent (unsigned) when a body is present
+  amzDate?: string // override for testing; defaults to now in ISO8601 basic (YYYYMMDDTHHMMSSZ)
+}
+
+// Produce the headers + URL for a signed request. Pure (no I/O) so it can be unit
+// tested against AWS's reference vectors. Only host + x-amz-date (+ the session
+// token when present) are signed; Content-Type, when sent, rides along unsigned —
+// SigV4 permits unsigned headers, and this keeps the signed set (and thus the GET
+// path) identical to the verified reference implementation.
+export function signV4(opts: SignOptions): { url: string; headers: Record<string, string> } {
+  const { creds, service, host, path } = opts
+  const method = opts.method ?? "GET"
+  const body = opts.body ?? ""
+  const region = creds.region || "us-east-1"
+  const query = opts.query ?? {}
+  const amzDate = opts.amzDate ?? new Date().toISOString().replace(/[:-]|\.\d{3}/g, "")
+  const dateStamp = amzDate.slice(0, 8)
+
+  const canonicalQuery = Object.keys(query)
+    .sort()
+    .map((k) => `${enc(k)}=${enc(query[k])}`)
+    .join("&")
+
+  // Signed headers (lowercase names, sorted). host + x-amz-date, plus the session
+  // token header when present.
+  const hdrs: Record<string, string> = { host, "x-amz-date": amzDate }
+  if (creds.sessionToken) hdrs["x-amz-security-token"] = creds.sessionToken
+  const names = Object.keys(hdrs).sort()
+  const canonicalHeaders = names.map((n) => `${n}:${hdrs[n].trim()}\n`).join("")
+  const signedHeaders = names.join(";")
+
+  const payloadHash = sha256hex(body)
+  const canonicalRequest = [method, path, canonicalQuery, canonicalHeaders, signedHeaders, payloadHash].join("\n")
+
+  const scope = `${dateStamp}/${region}/${service}/aws4_request`
+  const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256hex(canonicalRequest)].join("\n")
+
+  const kDate = hmac("AWS4" + creds.secretAccessKey, dateStamp)
+  const kRegion = hmac(kDate, region)
+  const kService = hmac(kRegion, service)
+  const kSigning = hmac(kService, "aws4_request")
+  const signature = createHmac("sha256", kSigning).update(stringToSign, "utf8").digest("hex")
+
+  const authorization = `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`
+
+  // host is implied by the URL (fetch sets it); send the rest.
+  const headers: Record<string, string> = { "x-amz-date": amzDate, Authorization: authorization }
+  if (creds.sessionToken) headers["x-amz-security-token"] = creds.sessionToken
+  if (body && opts.contentType) headers["Content-Type"] = opts.contentType
+
+  const url = `https://${host}${path}${canonicalQuery ? "?" + canonicalQuery : ""}`
+  return { url, headers }
+}
+
+// Back-compat name for the GET-only signer (verified against AWS's reference
+// vector). Delegates to signV4 — the signed set is unchanged, so its output is
+// byte-identical to the original implementation.
+export function signGetV4(opts: {
+  creds: AwsCreds
+  service: string
+  host: string
+  path: string
+  query?: Record<string, string>
+  amzDate?: string
+}): { url: string; headers: Record<string, string> } {
+  return signV4({ ...opts, method: "GET" })
+}
+
+// Sign and perform a GET. Returns the HTTP status + raw body text.
+export async function awsGet(
+  creds: AwsCreds,
+  service: string,
+  host: string,
+  path: string,
+  query: Record<string, string> = {},
+): Promise<{ status: number; body: string }> {
+  const { url, headers } = signV4({ creds, service, host, path, query, method: "GET" })
+  const res = await fetch(url, { method: "GET", headers })
+  return { status: res.status, body: await res.text() }
+}
+
+// Sign and perform a POST with a body. Returns the HTTP status + raw body text.
+export async function awsPost(
+  creds: AwsCreds,
+  service: string,
+  host: string,
+  path: string,
+  body: string,
+  contentType = "application/xml",
+): Promise<{ status: number; body: string }> {
+  const { url, headers } = signV4({ creds, service, host, path, body, contentType, method: "POST" })
+  const res = await fetch(url, { method: "POST", headers, body })
+  return { status: res.status, body: await res.text() }
+}