wherdr 1.3.1 → 1.3.2

package/bin/lib/core.mjs

@@ -17,6 +17,18 @@ export function homebrewInstall(file) {
   return /[\\/]Cellar[\\/]wherdr[\\/]/.test(file)
 }
 
+// How this copy of wherdr was installed (shared/updates.ts InstallMode), from
+// the path of its bin/wherdr.mjs: the Homebrew Cellar; the copy the Herdr
+// plugin keeps in <wherdr dir>/app; `npm i -g` (<prefix>/lib/node_modules/wherdr,
+// never a temporary npx folder); otherwise a temporary package (npx, bunx, pnpm dlx).
+export function installKind(bin, dir) {
+  if (homebrewInstall(bin)) return 'brew'
+  const root = path.resolve(bin, '..', '..')
+  if (root === path.join(dir, 'app')) return 'plugin'
+  if (/[\\/]lib[\\/]node_modules[\\/]wherdr$/.test(root) && !/[\\/]_npx[\\/]/.test(root)) return 'npm-global'
+  return 'npm'
+}
+
 export const COMMANDS = ['run', 'start', 'stop', 'restart', 'status', 'logs', 'open', 'phone', 'panel', 'service', 'doctor', 'help', 'version']
 const VALUE_OPTIONS = { '--port': 'port', '--host': 'host', '--data-dir': 'dataDir', '--session': 'session', '--lines': 'lines', '-n': 'lines' }
 const FLAGS = { '-h': 'help', '--help': 'help', '-v': 'version', '--version': 'version', '-f': 'follow', '--follow': 'follow' }
@@ -98,8 +110,11 @@ export function serverEnv(opts, env, home = os.homedir(), bin = BIN) {
   out.NODE_ENV = 'production'
   // Open WebSockets do not hold Ctrl+C for 30 s; clients reconnect on their own.
   out.NITRO_SHUTDOWN_TIMEOUT ??= '1500'
-  // Update command offered in the app (shared/updates.ts).
-  out.WHERDR_INSTALL = homebrewInstall(bin) ? 'brew' : 'npm'
+  // Update command, or one-tap update, offered in the app (shared/updates.ts):
+  // the package to replace and the folder of its state and log (server/utils/selfupdate.ts).
+  out.WHERDR_INSTALL = installKind(bin, dir)
+  out.WHERDR_ROOT = path.resolve(bin, '..', '..')
+  out.WHERDR_DIR = dir
   // Nitro reads NITRO_PORT / NITRO_HOST before PORT / HOST.
   delete out.NITRO_PORT
   delete out.NITRO_HOST

package/bin/lib/tailnet.d.mts

@@ -1,13 +1,18 @@
 // Types of tailnet.mjs, for the server (server/utils/phone.ts).
-export interface PhoneAddress { url: string, served: boolean, httpsPort: string }
+// funnel: also published on the Internet by `tailscale funnel` (never adopted).
+export interface PhoneAddress { url: string, served: boolean, httpsPort: string, funnel?: boolean }
 export interface Tailnet {
   installed: boolean
-  bin?: string
+  bin?: string | null
+  // Tailscale's socket, when the state was read there (no CLI: Docker).
+  socket?: string | null
   name?: string | null
   connected?: boolean
   https?: boolean
   phone?: PhoneAddress | null
   taken?: boolean
+  // Addresses published for wherdr's port; null when they could not be read.
+  served?: string[] | null
 }
 export type Reach = 'ok' | 'host' | 'other' | 'unreachable'
 export type ReachCause = 'dns' | 'refused' | 'timeout' | 'cert' | 'tls' | 'network'
@@ -15,18 +20,22 @@ export interface Probe { reach: Reach, cause?: ReachCause, status?: number }
 export type ServeErrorCode = 'operator' | 'https' | 'offline'
 
 export const LINKS: { download: string, https: string, operator: string }
+export const TAILSCALED_SOCKET: string
+export function tailscaledSocket(env?: Record<string, string | undefined>, exists?: (p: string) => boolean): string | null
 export function tailscaleBin(env?: Record<string, string | undefined>, exists?: (p: string) => boolean): string | null
 export function tailnetStatus(statusJson: string): { name: string | null, connected: boolean, https: boolean }
 export function phoneAddress(name: string | null, port: string | number, serveJson: string): PhoneAddress | null
+export function servedAddresses(name: string | null, port: string | number, serveJson: string): string[] | null
 export function servedPorts(serveJson: string): string[]
 export function publishCommand(port: string | number, httpsPort?: string | number): string
 export function publishArgs(port: string | number): string[]
 export function unpublishArgs(httpsPort: string): string[]
 export function tailnetUrl(text: unknown): string | null
 export function serveError(output: string): { code: ServeErrorCode, link: string } | null
-export function inspect(port: string | number, bin?: string | null): Promise<Tailnet>
+export function inspect(port: string | number, bin?: string | null, socket?: string | null): Promise<Tailnet>
 export function tailnetDomain(resolvConf: string): string | null
 export function reachable(url: string, timeoutMs?: number): Promise<Reach>
+export function healthReach(status: number, text: string): 'ok' | 'host' | null
 export function probe(url: string, timeoutMs?: number): Promise<Probe>
 export function failureCause(err: unknown): ReachCause
 export function runTailscale(bin: string, args: string[], timeoutMs?: number): Promise<{ code: number, output: string }>

package/bin/lib/tailnet.mjs

@@ -7,6 +7,7 @@
 import { execFile } from 'node:child_process'
 import dns from 'node:dns'
 import { existsSync } from 'node:fs'
+import http from 'node:http'
 import https from 'node:https'
 import path from 'node:path'
 import { promisify } from 'node:util'
@@ -26,6 +27,32 @@ export function tailscaleBin(env = process.env, exists = existsSync) {
   return dirs.find(p => exists(p)) || null
 }
 
+// Tailscale's own socket on Linux. Its local API answers the same JSON as the
+// CLI: a Docker container has no `tailscale` command, but docker-compose.yml
+// mounts this folder, so wherdr reads the state there. Anyone may read; the
+// API also accepts changes from Tailscale's operator, but wherdr only ever
+// sends GET requests to it (localApi below).
+export const TAILSCALED_SOCKET = '/var/run/tailscale/tailscaled.sock'
+export function tailscaledSocket(env = process.env, exists = existsSync) {
+  const file = env.WHERDR_TAILSCALED_SOCKET || TAILSCALED_SOCKET
+  return exists(file) ? file : null
+}
+
+// GET on Tailscale's local API → the body, '' on any failure.
+function localApi(socketPath, route, timeoutMs = 4000) {
+  const { promise, resolve } = Promise.withResolvers()
+  const req = http.get({ socketPath, path: `/localapi/v0/${route}`, headers: { host: 'local-tailscaled.sock' }, timeout: timeoutMs }, (res) => {
+    let text = ''
+    res.setEncoding('utf8')
+    res.on('data', (c) => { if (text.length < 1 << 20) text += c })
+    res.on('end', () => resolve(res.statusCode === 200 ? text : ''))
+    res.on('error', () => resolve(''))
+  })
+  req.on('timeout', () => req.destroy())
+  req.on('error', () => resolve(''))
+  return promise
+}
+
 // `tailscale status --json` → { name, connected, https }: this machine's
 // tailnet name (machine.tailnet.ts.net) or null, whether Tailscale is up,
 // and whether the tailnet issues HTTPS certificates.
@@ -40,22 +67,51 @@ export function tailnetStatus(statusJson) {
   }
 }
 
+// The HTTPS entries of a serve configuration that proxy to wherdr's local
+// port on this machine's own name: [{ hostPort, httpsPort, funnel }], or null
+// when the configuration could not be read (Tailscale stopped, not JSON).
+// Background entries (`--bg`) and those of a `tailscale serve` still running
+// in a terminal (Foreground) both count. `funnel`: also open to the Internet.
+function wherdrEntries(name, port, serveJson) {
+  let config = null
+  try { config = JSON.parse(serveJson) } catch {}
+  if (!name || !config || typeof config !== 'object' || Array.isArray(config)) return null
+  const target = new RegExp(`^(https?://)?(127\\.0\\.0\\.1|localhost):${port}/?$`)
+  const out = []
+  for (const part of [config, ...Object.values(config.Foreground || {})]) {
+    for (const [hostPort, entry] of Object.entries(part?.Web || {})) {
+      const colon = hostPort.lastIndexOf(':')
+      if (hostPort.slice(0, colon).toLowerCase() !== name.toLowerCase()) continue
+      if (!Object.values(entry?.Handlers || {}).some(h => target.test(h?.Proxy || ''))) continue
+      out.push({ hostPort, httpsPort: hostPort.slice(colon + 1), funnel: Boolean(part.AllowFunnel?.[hostPort]) })
+    }
+  }
+  return out
+}
+
+const addressOf = (name, httpsPort) => `https://${name}${httpsPort === '443' ? '' : `:${httpsPort}`}/`
+
 // Phone address: the `tailscale serve` entry whose proxy targets wherdr's
 // local port (served on any HTTPS port), else the address publishing would
 // give (same port) with served: false. Null without a tailnet name.
 export function phoneAddress(name, port, serveJson) {
   if (!name) return null
-  let web = {}
-  try { web = JSON.parse(serveJson || '{}')?.Web || {} } catch {}
-  const target = new RegExp(`^(https?://)?(127\\.0\\.0\\.1|localhost):${port}/?$`)
-  for (const [hostPort, entry] of Object.entries(web)) {
-    if (!Object.values(entry?.Handlers || {}).some(h => target.test(h?.Proxy || ''))) continue
-    const servedPort = hostPort.slice(hostPort.lastIndexOf(':') + 1)
-    return { url: `https://${name}${servedPort === '443' ? '' : `:${servedPort}`}/`, served: true, httpsPort: servedPort }
-  }
+  const entries = wherdrEntries(name, port, serveJson) || []
+  const hit = entries.find(e => !e.funnel) || entries[0]
+  if (hit) return { url: addressOf(name, hit.httpsPort), served: true, httpsPort: hit.httpsPort, ...(hit.funnel ? { funnel: true } : {}) }
   return { url: `https://${name}:${port}/`, served: false, httpsPort: String(port) }
 }
 
+// The addresses wherdr adopts by itself (server/utils/phone.ts): what
+// `tailscale serve` publishes for its port on this machine's name, read from
+// Tailscale, which only the owner of the machine configures. null: unknown
+// (nothing is changed then); []: nothing is published. An address that
+// `tailscale funnel` also opens to the Internet is never adopted.
+export function servedAddresses(name, port, serveJson) {
+  const entries = wherdrEntries(name, port, serveJson)
+  return entries && entries.filter(e => !e.funnel).map(e => addressOf(name, e.httpsPort))
+}
+
 // HTTPS ports already published by `tailscale serve` (for anything).
 export function servedPorts(serveJson) {
   try {
@@ -92,16 +148,18 @@ export function serveError(output) {
   return null
 }
 
-// Tailscale's state for wherdr's port: { installed, bin, connected, https, name, phone, taken }.
-export async function inspect(port, bin = tailscaleBin()) {
-  if (!bin) return { installed: false }
+// Tailscale's state for wherdr's port: { installed, bin, socket, connected,
+// https, name, phone, taken, served }. Read with the CLI, or without one
+// (Docker) from Tailscale's socket.
+export async function inspect(port, bin = tailscaleBin(), socket = bin ? null : tailscaledSocket()) {
+  if (!bin && !socket) return { installed: false }
   const run = args => exec(bin, args, { encoding: 'utf8', timeout: 8000 }).then(r => r.stdout, () => '')
-  const status = tailnetStatus(await run(['status', '--json']))
-  const serve = status.name ? await run(['serve', 'status', '--json']) : ''
+  const status = tailnetStatus(bin ? await run(['status', '--json']) : await localApi(socket, 'status?peers=false'))
+  const serve = !status.name ? '' : bin ? await run(['serve', 'status', '--json']) : await localApi(socket, 'serve-config')
   const phone = phoneAddress(status.name, port, serve)
   // Publishing on wherdr's port would replace whatever else is served there.
   const taken = Boolean(phone && !phone.served && servedPorts(serve).includes(String(port)))
-  return { installed: true, bin, ...status, phone, taken }
+  return { installed: true, bin, socket, ...status, phone, taken, served: servedAddresses(status.name, port, serve) }
 }
 
 // The tailnet's DNS suffix (tailnet.ts.net) from /etc/resolv.conf's search
@@ -152,29 +210,49 @@ export function failureCause(err) {
   return 'network'
 }
 
-// reachable() with the details: { reach, cause?, status? }: `cause` when
-// unreachable (failureCause), `status` the HTTP code when something answered.
-export function probe(url, timeoutMs = 8000) {
+// GET of `route` on the address → { status, text }, or { cause } when it failed.
+function fetchText(url, route, timeoutMs) {
   const { promise, resolve } = Promise.withResolvers()
   let u
-  try { u = new URL('manifest.webmanifest', url) } catch { return Promise.resolve({ reach: 'unreachable', cause: 'network' }) }
+  try { u = new URL(route, url) } catch { return Promise.resolve({ cause: 'network' }) }
   // Accept JSON: a refused host then answers { code: 'host' }, not the HTML page.
   const req = https.get(u, { lookup, timeout: timeoutMs, headers: { accept: 'application/json' } }, (res) => {
     let text = ''
     res.setEncoding('utf8')
     res.on('data', (c) => { if (text.length < 65536) text += c })
-    res.on('end', () => {
-      const status = res.statusCode || 0
-      if (status >= 200 && status < 300) resolve({ reach: text.includes('wherdr') ? 'ok' : 'other', status })
-      else resolve({ reach: status === 403 && /"code"\s*:\s*"host"/.test(text) ? 'host' : 'other', status })
-    })
-    res.on('error', e => resolve({ reach: 'unreachable', cause: failureCause(e) }))
+    res.on('end', () => resolve({ status: res.statusCode || 0, text }))
+    res.on('error', e => resolve({ cause: failureCause(e) }))
   })
   req.on('timeout', () => req.destroy(new Error('timeout')))
-  req.on('error', e => resolve({ reach: 'unreachable', cause: failureCause(e) }))
+  req.on('error', e => resolve({ cause: failureCause(e) }))
   return promise
 }
 
+// What an answer of /api/health means: 'ok' (wherdr, and it accepts this
+// address), 'host' (wherdr's host check refused it), or null: not a wherdr
+// that has this route (versions up to 1.3.1, or another program).
+export function healthReach(status, text) {
+  if (status >= 200 && status < 300 && /"name"\s*:\s*"wherdr"/.test(text)) return 'ok'
+  if (status === 403 && /"code"\s*:\s*"host"/.test(text)) return 'host'
+  return null
+}
+
+// reachable() with the details: { reach, cause?, status? }: `cause` when
+// unreachable (failureCause), `status` the HTTP code when something answered.
+// /api/health is asked first: it goes through wherdr's host check, which the
+// static manifest does not (it answers for any host name). The manifest only
+// recognizes an older wherdr without that route.
+export async function probe(url, timeoutMs = 8000) {
+  const health = await fetchText(url, 'api/health', timeoutMs)
+  if (health.cause) return { reach: 'unreachable', cause: health.cause }
+  const reach = healthReach(health.status, health.text)
+  if (reach) return { reach, status: health.status }
+  const manifest = await fetchText(url, 'manifest.webmanifest', timeoutMs)
+  if (manifest.cause) return { reach: 'unreachable', cause: manifest.cause }
+  const ok = manifest.status >= 200 && manifest.status < 300 && manifest.text.includes('wherdr')
+  return { reach: ok ? 'ok' : 'other', status: ok ? manifest.status : health.status }
+}
+
 // Runs `tailscale <args>` without a terminal → { code, output }. On a tailnet
 // without HTTPS, `tailscale serve` prints a link and waits: the timeout ends it.
 export function runTailscale(bin, args, timeoutMs = 30_000) {

package/bin/lib/updater.mjs

@@ -0,0 +1,267 @@
+// One-tap update (Update button of the app, server/utils/selfupdate.ts): runs
+// detached from the server it replaces, so it outlives the restart. Installs
+// the new version, restarts wherdr, waits for /api/health to report the new
+// version, and goes back to the previous one when it does not. Progress goes
+// to <wherdr dir>/update.json (read by the server for the app) and
+// <wherdr dir>/update.log.
+//
+//   node updater.mjs <plan.json>
+//
+// The server copies this file out of the package before running it (npm and
+// Homebrew replace the package folder): it imports Node built-ins only.
+import { spawn } from 'node:child_process'
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Plan (written by the server):
+//   kind      plugin | npm-global | brew
+//   from, to  installed and target versions
+//   root      package folder of the running wherdr (holds bin/ and .output/)
+//   dir       wherdr folder (~/wherdr): state, log, pid file
+//   runtime   node (or bun) running the server
+//   serverPid pid of the server to replace
+//   port, host  where it answers
+//   registry  npm registry (npm_config_registry, default registry.npmjs.org)
+//   healthMs  how long the new version has to answer (default 60 s)
+
+export const HEALTH_MS = 60_000
+
+const healthHost = host => !host || host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host.includes(':') ? `[${host}]` : host
+export const healthUrl = plan => `http://${healthHost(plan.host)}:${plan.port}/api/health`
+
+// --------------------------------------------------------------- drivers
+// What each install mode does to install, put in place and go back. `io.run`
+// throws on a non-zero exit (the message ends with the command's output).
+
+function pluginDriver(plan, io) {
+  const staged = `${plan.root}.new`
+  const previous = `${plan.root}.prev`
+  return {
+    // The npm package of the target version, unpacked next to the running copy.
+    async install() {
+      const tgz = path.join(plan.dir, 'update', `wherdr-${plan.to}.tgz`)
+      await io.download(`${plan.registry.replace(/\/$/, '')}/wherdr/-/wherdr-${plan.to}.tgz`, tgz)
+      io.rm(staged)
+      io.mkdir(staged)
+      await io.run('tar', ['-xzf', tgz, '-C', staged, '--strip-components=1'])
+      io.rm(tgz)
+      if (!io.exists(path.join(staged, '.output', 'server', 'index.mjs'))) throw new Error(`wherdr ${plan.to}: the package has no built server`)
+      // The panel's QR code package (the plugin install copies it the same way).
+      const qr = path.join(plan.root, 'node_modules', 'qrcode-terminal')
+      if (io.exists(qr)) io.copy(qr, path.join(staged, 'node_modules', 'qrcode-terminal'))
+    },
+    // Server stopped: the previous copy is kept as <root>.prev.
+    async activate() {
+      io.rm(previous)
+      io.rename(plan.root, previous)
+      io.rename(staged, plan.root)
+    },
+    async rollback() {
+      if (!io.exists(previous)) throw new Error(`no previous copy to go back to (${previous})`)
+      io.rm(plan.root)
+      io.rename(previous, plan.root)
+    },
+    start: () => cliStart(plan, io),
+  }
+}
+
+function npmDriver(plan, io) {
+  const local = path.join(path.dirname(plan.runtime), 'npm')
+  const npm = io.exists(local) ? local : 'npm'
+  const install = version => io.run(npm, ['install', '--global', `wherdr@${version}`, '--no-audit', '--no-fund'])
+  return {
+    install: () => install(plan.to),
+    async activate() {},
+    rollback: () => install(plan.from),
+    start: () => cliStart(plan, io),
+  }
+}
+
+// <prefix>/Cellar/wherdr/<version>/libexec/lib/node_modules/wherdr (the
+// formula's npm install) → <prefix> and the keg <prefix>/Cellar/wherdr/<version>.
+function brewDriver(plan, io) {
+  const m = /^(.*)[\\/]Cellar[\\/]wherdr[\\/][^\\/]+/.exec(plan.root)
+  if (!m) throw new Error(`not a Homebrew keg: ${plan.root}`)
+  const keg = m[0]
+  const prefix = m[1]
+  const brew = path.join(prefix, 'bin', 'brew')
+  const opt = path.join(prefix, 'opt', 'wherdr')
+  // The old keg stays in the Cellar for the way back.
+  const env = { HOMEBREW_NO_INSTALL_CLEANUP: '1', HOMEBREW_NO_ENV_HINTS: '1' }
+  const optVersion = () => path.basename(io.realpath(opt))
+  return {
+    async install() {
+      await io.run(brew, ['upgrade', 'wherdr'], env)
+      const now = optVersion()
+      if (now !== plan.to && !now.startsWith(`${plan.to}_`)) throw new Error(`Homebrew installed ${now}, not ${plan.to}: its formula may not offer ${plan.to} yet`)
+    },
+    async activate() {},
+    // `brew link` (and opt/, which brew services runs) follows the newest keg:
+    // the keg that does not start is removed, then the previous one is linked.
+    // Homebrew then sees the previous version installed, and the update offered again.
+    async rollback() {
+      if (!io.exists(keg)) throw new Error(`the previous Homebrew version (${keg}) was removed: reinstall it with brew install wherdr`)
+      const failed = io.realpath(opt)
+      await io.run(brew, ['unlink', 'wherdr'], env)
+      if (failed !== keg && path.dirname(failed) === path.dirname(keg)) io.rm(failed)
+      await io.run(brew, ['link', '--overwrite', 'wherdr'], env)
+    },
+    start: () => io.run(brew, ['services', 'restart', 'wherdr'], env),
+  }
+}
+
+// `wherdr start` of the package now in place: the pid file, or the login service.
+function cliStart(plan, io) {
+  return io.run(plan.runtime, [path.join(plan.root, 'bin', 'wherdr.mjs'), 'start'])
+}
+
+export function driverFor(plan, io) {
+  if (plan.kind === 'plugin') return pluginDriver(plan, io)
+  if (plan.kind === 'npm-global') return npmDriver(plan, io)
+  if (plan.kind === 'brew') return brewDriver(plan, io)
+  throw new Error(`no one-tap update for ${plan.kind}`)
+}
+
+// ---------------------------------------------------------- state machine
+// installing → restarting → checking → done; a failed install leaves the old
+// server running (failed); a new version that does not start or answer goes
+// back: rolling-back → rolled-back (or failed when the old one does not come back).
+export async function runUpdate(plan, io) {
+  const d = driverFor(plan, io)
+  const healthMs = plan.healthMs ?? HEALTH_MS
+  io.log(`update ${plan.from} → ${plan.to} (${plan.kind}, ${plan.root})`)
+  io.state('installing')
+  try { await d.install() } catch (e) {
+    io.log(`install failed: ${e.message}`)
+    io.state('failed', `The update could not be installed: ${e.message}. Still on ${plan.from}.`)
+    return 'failed'
+  }
+  io.state('restarting')
+  let reason = ''
+  try {
+    await io.stopServer()
+    await d.activate()
+    await d.start()
+    io.state('checking')
+    if (await io.healthy(plan.to, healthMs)) {
+      io.log(`wherdr ${plan.to} answers: done`)
+      io.state('done')
+      return 'done'
+    }
+    reason = `wherdr ${plan.to} did not answer within ${Math.round(healthMs / 1000)} s`
+  } catch (e) { reason = e.message }
+  io.log(`${reason}: going back to ${plan.from}`)
+  io.state('rolling-back', reason)
+  try {
+    await io.stopServer()
+    await d.rollback()
+    await d.start()
+    if (await io.healthy(plan.from, healthMs)) {
+      io.log(`wherdr ${plan.from} answers again: rolled back`)
+      io.state('rolled-back', `wherdr ${plan.to} did not start (${reason}). Rolled back to ${plan.from}.`)
+      return 'rolled-back'
+    }
+    throw new Error(`wherdr ${plan.from} did not answer either`)
+  } catch (e) {
+    io.log(`rollback failed: ${e.message}`)
+    io.state('failed', `wherdr ${plan.to} did not start (${reason}), and going back to ${plan.from} failed: ${e.message}. See ${path.join(plan.dir, 'update.log')}.`)
+    return 'failed'
+  }
+}
+
+// ------------------------------------------------------------- real I/O
+const sleep = ms => new Promise(r => setTimeout(r, ms))
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+export function realIo(plan, now = Date.now) {
+  const stateFile = path.join(plan.dir, 'update.json')
+  const logFile = path.join(plan.dir, 'update.log')
+  const startedAt = now()
+  const log = (line) => { try { appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`) } catch {} }
+  // The commands see the runtime first on the PATH (npm's `#!/usr/bin/env node`).
+  const PATH = `${path.dirname(plan.runtime)}${path.delimiter}${process.env.PATH || ''}`
+  return {
+    log,
+    state(state, message) {
+      const job = { state, from: plan.from, to: plan.to, mode: plan.kind, startedAt, updatedAt: now(), ...(message ? { message } : {}) }
+      writeFileSync(`${stateFile}.tmp`, `${JSON.stringify(job)}\n`)
+      renameSync(`${stateFile}.tmp`, stateFile)
+    },
+    run(cmd, args, env = {}) {
+      log(`$ ${[cmd, ...args].join(' ')}`)
+      const { promise, resolve, reject } = Promise.withResolvers()
+      const child = spawn(cmd, args, { cwd: plan.dir, env: { ...process.env, PATH, ...env }, stdio: ['ignore', 'pipe', 'pipe'] })
+      let out = ''
+      const keep = (b) => { out = (out + b).slice(-4000); try { appendFileSync(logFile, b) } catch {} }
+      child.stdout.on('data', keep)
+      child.stderr.on('data', keep)
+      child.on('error', e => reject(new Error(`${path.basename(cmd)}: ${e.message}`)))
+      child.on('close', (code) => {
+        if (code === 0) return resolve(out)
+        // The lines that say what went wrong (`wherdr: …`, `Error: …`), not a stack trace.
+        const lines = out.split('\n').map(l => l.trim()).filter(Boolean)
+        const why = lines.filter(l => /^(wherdr: |error\b|\w*Error: )/i.test(l)).slice(0, 2)
+        const tail = (why.length ? why : lines.slice(-1)).join(' / ')
+        reject(new Error(`${path.basename(cmd)} ${args[0]} exited with ${code}${tail ? `: ${tail}` : ''}`))
+      })
+      return promise
+    },
+    async download(url, file) {
+      log(`GET ${url}`)
+      const res = await fetch(url, { signal: AbortSignal.timeout(180_000) })
+      if (!res.ok) throw new Error(`${url} answered ${res.status}`)
+      mkdirSync(path.dirname(file), { recursive: true })
+      writeFileSync(file, Buffer.from(await res.arrayBuffer()))
+    },
+    // The server being replaced, then whatever `wherdr start` left (pid file).
+    async stopServer() {
+      const pids = [plan.serverPid]
+      try { pids.push(Number(readFileSync(path.join(plan.dir, 'wherdr.pid'), 'utf8').trim())) } catch {}
+      for (const pid of new Set(pids.filter(p => p && p !== process.pid && alive(p)))) {
+        log(`stopping pid ${pid}`)
+        try { process.kill(pid, 'SIGTERM') } catch {}
+        for (let i = 0; i < 40 && alive(pid); i++) await sleep(250)
+        if (alive(pid)) try { process.kill(pid, 'SIGKILL') } catch {}
+      }
+      rmSync(path.join(plan.dir, 'wherdr.pid'), { force: true })
+    },
+    async healthy(version, ms) {
+      const until = now() + ms
+      const get = async (url) => {
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000) })
+        return { status: res.status, body: res.ok ? await res.json().catch(() => null) : null }
+      }
+      while (now() < until) {
+        try {
+          const health = await get(healthUrl(plan))
+          if (health.body?.version === version) return true
+          // Versions up to 1.3.1 have no /api/health: their version is in
+          // /api/update (unless the app is locked).
+          if (health.body?.version === undefined && (await get(healthUrl(plan).replace(/health$/, 'update'))).body?.current === version) return true
+        } catch {}
+        await sleep(1000)
+      }
+      return false
+    },
+    exists: p => existsSync(p),
+    rm: p => rmSync(p, { recursive: true, force: true }),
+    mkdir: p => mkdirSync(p, { recursive: true }),
+    rename: (a, b) => renameSync(a, b),
+    copy: (a, b) => cpSync(a, b, { recursive: true }),
+    realpath: p => realpathSync(p),
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const plan = JSON.parse(readFileSync(process.argv[2], 'utf8'))
+  const io = realIo(plan)
+  runUpdate(plan, io).then(r => process.exit(r === 'done' ? 0 : 1), (e) => {
+    io.log(`updater crashed: ${e?.stack || e}`)
+    try { io.state('failed', `The updater crashed: ${e?.message || e}`) } catch {}
+    process.exit(1)
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wherdr",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "license": "MIT",
   "type": "module",
   "description": "Unofficial mobile web client (PWA) to drive the coding agents running in Herdr",
@@ -33,6 +33,7 @@
   "scripts": {
     "dev": "nuxt dev",
     "build": "nuxt build",
+    "build:demo": "VITE_WHERDR_DEMO=1 nuxt generate",
     "start": "HOST=${HOST:-127.0.0.1} PORT=${PORT:-7683} node .output/server/index.mjs",
     "typecheck": "nuxt typecheck",
     "test": "vitest run",

package/.output/public/_nuxt/BpQH8Ho1.js

@@ -1 +0,0 @@
-var e=Object.defineProperty,t=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports),n=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n||e(r,Symbol.toStringTag,{value:`Module`}),r};export{n,t};