pgserve 2.1.3 → 2.2.1

package/CHANGELOG.md

@@ -1,9 +1,105 @@
+## v2.2.x — Transparent Upgrade
+
+**Added:** `autopg upgrade` CLI verb — idempotent migration runner that reconciles port back to canonical 8432, flushes the binary cache against the pinned PG version, re-resolves the plpgsql `.so` path per database, refreshes `~/.autopg/<app>.env` files, signals consumers, and validates final health.
+
+**Added:** npm `postinstall` hook (`scripts/postinstall.cjs`) auto-runs `autopg upgrade --quiet` when an existing `~/.autopg/data/` is detected on `bun install`. Soft-fails so package install never breaks; manual `autopg upgrade` remains the explicit escape hatch.
+
+**Contract:** Users upgrading from pgserve@2.1.3 to autopg@2.2.x get transparent migration via the postinstall hook. Manual `autopg upgrade` remains as the explicit escape hatch for forced re-runs. Patches the upgrade-path hole left by autopg-v22 partial roll-out (binary moved to `~/.autopg/`, default port silently shifted to 9432, plpgsql extensions referenced stale `$libdir`).
+
+**Override:** Set `AUTOPG_SKIP_POSTINSTALL=1` to bypass the hook (CI / containers / install-only flows).
+
 # Changelog
 
 All notable changes to `pgserve` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased — autopg console settings
+
+### Added
+
+- **Soft rename to `autopg`.** The npm package stays `pgserve` (no
+  `npm deprecate`); the package now also ships an `autopg` bin that
+  routes through the same dispatcher. Use either name interchangeably:
+  `autopg config list` and `pgserve config list` are byte-equivalent.
+  pm2 process name stays `pgserve` so existing supervised installs
+  upgrade cleanly with no migration step.
+- **`~/.autopg/settings.json` (schema version 1).** Six sections —
+  `server`, `runtime`, `sync`, `supervision`, `postgres`, `ui` —
+  with a curated set of 15 PostgreSQL GUCs plus a `postgres._extra`
+  raw passthrough map. Every write is atomic (`tmp + rename`),
+  chmod 0600, and tagged with a sha256 etag for optimistic
+  concurrency control on the UI helper. Override the directory with
+  `AUTOPG_CONFIG_DIR`. See [`docs/settings-schema.md`](./docs/settings-schema.md)
+  for the full key reference.
+- **`autopg config (list / get / set / edit / path / init)`** — manage
+  settings from the shell. `list` prints a `KEY VALUE SOURCE` table
+  showing where each leaf was resolved from (default / file / env).
+  `set` validates with a stable error format (`error: <field> — <CODE>:
+  <detail>`, exit code 2). Seven error codes: `INVALID_KEY`,
+  `INVALID_GUC_NAME`, `INVALID_GUC_VALUE`, `INVALID_TYPE`,
+  `OUT_OF_RANGE`, `READONLY`, `ETAG_MISMATCH`.
+- **`autopg restart`** — pm2-aware. If the `pgserve` process appears
+  in `pm2 jlist`, calls `pm2 restart pgserve` (single-fire, respects
+  the hardened defaults registered at install time). Otherwise reads
+  the pidfile, sends SIGTERM, waits, and respawns the daemon
+  detached.
+- **`autopg ui [--port N] [--no-open]`** — boots a local web console
+  on 127.0.0.1 (default port walk: 8433–8533). Single-user dev tool,
+  no auth, no TLS. Mounts four endpoints: `GET /api/settings` (returns
+  `{ settings, sources, etag }`), `PUT /api/settings` (requires
+  `If-Match`, returns 409 on stale etag), `POST /api/restart`,
+  `GET /api/status`. All handlers shell out to the CLI — the daemon
+  stays untouched, so the console works even with no daemon running.
+- **Console scaffolding (`console/`).** React + Babel via CDN, no
+  build step. All 11 routes are registered; the **Settings** screen
+  is the first stateful one and renders the full 6-section schema
+  with type-aware controls, inline validation, an `OVERRIDDEN BY ENV`
+  chip on env-overridden rows, and an etag-mismatch reload banner.
+  The remaining 10 screens (Databases, Tables, SQL, Optimizer,
+  Security, Ingress, Health, Sync, RLM-trace, RLM-sim) render
+  `[ coming soon ]` placeholders — Health ships next.
+- **Daemon now reads from settings.** `cluster.js` calls
+  `loadEffectiveConfig()` (env > file > defaults). `postgres.js`
+  emits `-c key=value` for every entry in `settings.postgres` and
+  `settings.postgres._extra`, with name regex (`^[a-z][a-z0-9_]*$`)
+  and scalar value validation enforced at boot — invalid GUCs are
+  dropped with a `logger.warn` so a typo in `_extra` doesn't crash
+  the daemon. Hardcoded `max_connections=1000` and the WAL
+  replication block (`wal_level=logical`,
+  `max_replication_slots=10`, `max_wal_senders=10`,
+  `wal_keep_size=512MB`) are now schema defaults — overridable
+  per-install via `autopg config set`.
+- **`AUTOPG_*` env vars** as the new primary form. `PGSERVE_*` is
+  still honored at the daemon (one-time deprecation log per process
+  when `PGSERVE_*` is the only one set); `AUTOPG_*` wins on
+  conflict.
+
+### Migrated
+
+- **`~/.pgserve/` → `~/.autopg/` (one-shot, idempotent).** On first
+  run, if `~/.pgserve/` exists and `~/.autopg/` does not, the contents
+  are copied (preserving mtimes). A `MIGRATED-FROM-PGSERVE.md` marker
+  is dropped in the old directory so subsequent runs skip the copy
+  cleanly. If both directories exist, neither is touched and
+  `~/.autopg/` wins. No automatic merge.
+
+### Notes for operators
+
+- pm2 process name stays `pgserve`. Running `autopg install` on a
+  host that already has the legacy install is a no-op — pm2 sees the
+  same process name. Re-issue `pm2 save` if you want pm2 to persist
+  any settings changes through reboots.
+- Local dev loop:
+  ```bash
+  bun install && npm link && autopg install && autopg ui
+  ```
+  Then edit `postgres.shared_buffers` in the UI, click Save & Restart,
+  and `psql -c "SHOW shared_buffers;"` reflects the new value.
+- The npm package name is **not changing** — keep installing with
+  `npm install pgserve` (or `npx pgserve`); both `autopg` and
+  `pgserve` bins ship in the same tarball.
+
 ## 2.0.8
 
 ### Changed

package/README.md

@@ -37,6 +37,14 @@ psql postgresql://localhost:8432/myapp
 
 > Note: v2 default is the Unix socket — see [Daemon mode](#daemon-mode). The TCP form above is the v1 compat path.
 
+> **Naming.** The npm package stays `pgserve`. The CLI now also ships as
+> `autopg` — both bins route to the same dispatcher. Use `autopg` for the
+> new console (`autopg ui`) and configuration surface (`autopg config`,
+> `autopg restart`); `pgserve <subcommand>` keeps working as a forever
+> alias. Settings live at `~/.autopg/settings.json` and are migrated
+> from `~/.pgserve/` automatically on first run. See
+> [Console](#console-autopg-ui) and [Configuration](#configuration).
+
 <br>
 
 ## Features
@@ -120,9 +128,25 @@ pgserve-windows-x64.exe --data C:\pgserve-data
 
 ## CLI Reference
 
+`autopg` and `pgserve` are interchangeable — every subcommand routes
+through the same dispatcher. Use whichever you prefer; new examples in
+this README and in `console/` use `autopg`.
+
 ```
-pgserve [options]
+autopg [options]                       # foreground server (alias: pgserve)
+autopg daemon                          # long-lived background daemon
+autopg install [--port N] [--data P]   # register pgserve under pm2
+autopg uninstall                       # remove from pm2 (data dir kept)
+autopg status                          # pm2 + on-disk config snapshot
+autopg url | autopg port               # canonical connection string / port
+autopg config <list|get|set|edit|path|init>   # manage ~/.autopg/settings.json
+autopg restart                         # pm2-aware: pm2 restart pgserve, else SIGTERM+respawn
+autopg ui [--port N] [--no-open]       # local web console on 127.0.0.1
+```
+
+Foreground options accepted by `autopg` / `pgserve` (no subcommand):
 
+```
 Options:
   --port <number>       PostgreSQL port (default: 8432)
   --data <path>         Data directory for persistence (default: in-memory)
@@ -351,6 +375,86 @@ agent state), not just for convenience.
 
 <br>
 
+## Console (`autopg ui`)
+
+A local web console for inspecting and editing the running cluster.
+Runs in-process via `node:http`, binds 127.0.0.1 only, single-user dev
+tool — no auth, no TLS, never expose it.
+
+```bash
+autopg ui                  # walk 8433–8533 picking the first free port
+autopg ui --port 8500      # bind exactly 8500
+autopg ui --no-open        # skip browser launch (CI / headless)
+```
+
+The first stateful screen — **Settings** — is functional today: it
+renders the 6-section schema (server / runtime / sync / supervision /
+postgres / ui), validates inline, and round-trips through
+`~/.autopg/settings.json` with optimistic concurrency (sha256 etag +
+`If-Match`). The other 10 screens (Databases, Tables, SQL, Optimizer,
+Security, Ingress, Health, Sync, RLM-trace, RLM-sim) are scaffolded
+as `[ coming soon ]` placeholders — Health ships next.
+
+The UI shells out to the CLI for every mutation (`autopg config set`
+under PUT, `autopg restart` under POST). The daemon stays untouched
+— no HTTP API, no signal-based reload — so the console works even
+when no daemon is running.
+
+See [`console/README.md`](./console/README.md) for the local dev loop
+and design-system source.
+
+<br>
+
+## Configuration
+
+The CLI is the source of truth. Settings live at
+`~/.autopg/settings.json` (override the directory with
+`AUTOPG_CONFIG_DIR`; the legacy `PGSERVE_CONFIG_DIR` is still honored
+and falls back to `~/.pgserve/`). Every write is atomic, chmod 0600,
+and tagged with a sha256 etag for optimistic concurrency on the UI
+helper's PUT path.
+
+Schema sections (one per `~/.autopg/settings.json` top-level key):
+
+| Section | Purpose |
+|---------|---------|
+| `server` | Router port/host, backend socket, superuser credentials |
+| `runtime` | Log level, auto-provision, pgvector, data dir |
+| `sync` | WAL-based logical replication toggle |
+| `supervision` | pm2 hardening defaults (memory, restart, kill timeout) |
+| `postgres` | 15 curated GUCs (`shared_buffers`, `wal_level`, …) + `_extra` raw passthrough |
+| `ui` | Console theme / phosphor / density / CRT toggle |
+
+```bash
+autopg config init                              # write defaults
+autopg config list                              # KEY VALUE SOURCE table
+autopg config get postgres.shared_buffers       # machine-friendly value
+autopg config set postgres.shared_buffers 256MB # validates + atomic write
+autopg config edit                              # opens $EDITOR on settings.json
+autopg config path                              # absolute path (honors AUTOPG_CONFIG_DIR)
+```
+
+**Precedence:** `default < file < env`. `AUTOPG_*` env vars beat
+`PGSERVE_*` (the legacy form is still honored with a one-time
+deprecation log per process, so existing operators keep working).
+The console shows a yellow `OVERRIDDEN BY ENV` chip on rows whose
+env var is currently set.
+
+**GUC passthrough:** `postgres._extra` is a free-form `{ gucName: scalar }`
+map for any PostgreSQL setting outside the curated 15. Names must match
+`^[a-z][a-z0-9_]*$`; values must be string / number / boolean (no
+newlines, no leading `-`). Both layers are revalidated at boot, so a
+typo logs a `logger.warn` and is dropped — postgres still starts.
+
+**One-shot migration:** on first run, if `~/.pgserve/` exists and
+`~/.autopg/` does not, the contents are copied (preserving mtimes)
+and a `MIGRATED-FROM-PGSERVE.md` marker is dropped in the old dir.
+Idempotent — second run is a no-op.
+
+Full schema reference: [`docs/settings-schema.md`](./docs/settings-schema.md).
+
+<br>
+
 ## Compat TCP via `--listen`
 
 TCP is **off by default** in v2. Bring it back only when you need it

package/bin/autopg-wrapper.cjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * autopg wrapper — primary CLI bin name post soft-rename.
+ *
+ * autopg and pgserve route through the same dispatcher. The package
+ * stays published as `pgserve` on npm; this wrapper is the new
+ * preferred command, with `pgserve` retained as a forever alias.
+ *
+ * Implementation: delegate to pgserve-wrapper.cjs so dispatch logic
+ * stays single-sourced. argv[0]/argv[1] preservation is what matters
+ * for the inner module — node already wires argv correctly when
+ * require()'d at module load time, and the wrapper inspects
+ * process.argv directly.
+ */
+
+require('./pgserve-wrapper.cjs');

package/bin/pgserve-wrapper.cjs

@@ -29,14 +29,40 @@ const fs = require('fs');
 // sees the original `daemon` token.
 // ────────────────────────────────────────────────────────────────────────
 const __subcommand = process.argv[2];
-const __installSubcommands = new Set(['install', 'uninstall', 'status', 'url', 'port']);
+const __installSubcommands = new Set([
+  'install',
+  'uninstall',
+  'status',
+  'url',
+  'port',
+  // autopg-console-settings (Group 2): config / restart / ui are pure node
+  // wrappers that read/write `~/.autopg/settings.json` (and shell out to
+  // pm2 for restart). They don't need bun, so route them BEFORE the bun
+  // probe — same rationale as the wave-1 install commands.
+  'config',
+  'upgrade',
+  'restart',
+  'ui',
+]);
 if (__subcommand && __installSubcommands.has(__subcommand)) {
   const cli = require(path.join(__dirname, '..', 'src', 'cli-install.cjs'));
-  process.exit(
-    cli.dispatch(__subcommand, process.argv.slice(3), {
-      scriptPath: path.join(__dirname, 'postgres-server.js'),
-    }),
-  );
+  const result = cli.dispatch(__subcommand, process.argv.slice(3), {
+    scriptPath: path.join(__dirname, 'postgres-server.js'),
+    wrapperPath: __filename,
+  });
+  // `ui` returns a Promise that never resolves (the server parks on
+  // signals). Other subcommands return a number directly. Handle both.
+  if (result && typeof result.then === 'function') {
+    result.then(
+      (code) => process.exit(typeof code === 'number' ? code : 0),
+      (err) => {
+        process.stderr.write(`pgserve: ${err?.message ?? err}\n`);
+        process.exit(1);
+      },
+    );
+    return;
+  }
+  process.exit(typeof result === 'number' ? result : 0);
 }
 if (__subcommand === 'serve') {
   // Alias `serve` → `daemon` so the wish's canonical command name maps

package/bin/postgres-server.js

@@ -12,6 +12,7 @@ import path from 'path';
 import os from 'os';
 import { startMultiTenantServer } from '../src/index.js';
 import { startClusterServer } from '../src/cluster.js';
+import { loadEffectiveConfig as loadAutopgConfig } from '../src/settings-loader.cjs';
 import {
   PgserveDaemon,
   stopDaemon,
@@ -387,8 +388,60 @@ FEATURES:
 `);
 }
 
+/**
+ * Pull daemon options from ~/.autopg/settings.json (with env overlay).
+ * Returns a partial options patch — only keys that are present in the
+ * settings file or env override the hardcoded defaults. CLI flags layer
+ * on top of this in parseArgs().
+ *
+ * Failures (missing file, bad JSON) fall through to defaults silently —
+ * the daemon must remain runnable on a brand-new install before
+ * `autopg config init` has been called.
+ */
+function loadSettingsOverlay() {
+  try {
+    const cpuCount = os.cpus().length;
+    const isWindows = os.platform() === 'win32';
+    const { settings } = loadAutopgConfig();
+    const s = settings.server || {};
+    const r = settings.runtime || {};
+    const sy = settings.sync || {};
+    const pg = settings.postgres || {};
+    const overlay = {};
+    if (typeof s.port === 'number') overlay.port = s.port;
+    if (typeof s.host === 'string' && s.host) overlay.host = s.host;
+    if (typeof r.dataDir === 'string' && r.dataDir) overlay.dataDir = r.dataDir;
+    if (typeof r.ramMode === 'boolean') overlay.useRam = r.ramMode;
+    if (typeof r.logLevel === 'string' && r.logLevel) overlay.logLevel = r.logLevel;
+    if (typeof r.autoProvision === 'boolean') overlay.autoProvision = r.autoProvision;
+    if (typeof r.cluster === 'string') {
+      overlay.cluster = r.cluster === 'auto'
+        ? (cpuCount > 1 && !isWindows)
+        : r.cluster === 'on';
+    }
+    if (typeof r.workers === 'number' && r.workers > 0) overlay.workers = r.workers;
+    if (typeof r.statsDashboard === 'boolean') overlay.showStats = r.statsDashboard;
+    if (typeof r.enablePgvector === 'boolean') overlay.enablePgvector = r.enablePgvector;
+    if (sy.enabled && typeof sy.url === 'string' && sy.url) overlay.syncTo = sy.url;
+    if (sy.enabled && typeof sy.databases === 'string' && sy.databases) overlay.syncDatabases = sy.databases;
+    // pgserve-side connection cap mirrors the postgres GUC unless the user
+    // has explicitly diverged via CLI flag (handled in parseArgs).
+    if (typeof pg.max_connections === 'number') overlay.maxConnections = pg.max_connections;
+    return overlay;
+  } catch {
+    // First run, no settings.json yet, or file parse error. Hardcoded
+    // defaults still produce a working daemon — nothing to do here.
+    return {};
+  }
+}
+
 /**
  * Parse command line arguments
+ *
+ * Precedence (lowest → highest):
+ *   1. hardcoded defaults
+ *   2. ~/.autopg/settings.json (with env overlay via loadEffectiveConfig)
+ *   3. CLI flags  ← explicit user intent always wins
  */
 function parseArgs() {
   // Auto-enable cluster mode on multi-core systems for best performance
@@ -412,6 +465,9 @@ function parseArgs() {
     enablePgvector: false // Auto-enable pgvector extension on new databases
   };
 
+  // Layer settings.json + env on top of defaults. CLI flags below win.
+  Object.assign(options, loadSettingsOverlay());
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 

package/console/README.md

@@ -0,0 +1,131 @@
+# `console/` — autopg console
+
+Local web console served by `autopg ui`. React + Babel via CDN, no build
+step. Single-user dev tool — binds 127.0.0.1 only, no auth, no TLS.
+
+## Run
+
+```bash
+autopg ui                 # walks 8433–8533 picking the first free port
+autopg ui --port 8500     # bind exactly 8500 or fail
+autopg ui --no-open       # skip browser launch (CI / headless)
+```
+
+`pgserve ui …` is a forever alias of the same command.
+
+The server boots in-process via `node:http` and serves this directory as
+its document root. Four helper endpoints are mounted alongside the static
+assets — every mutation shells out to the CLI rather than calling the
+daemon directly, so the console works with or without a running daemon.
+
+| Endpoint | Backed by |
+|----------|-----------|
+| `GET /api/settings` | `loadEffectiveConfig()` → `{ settings, sources, etag }` |
+| `PUT /api/settings` | `writeSettings(body, { ifMatch })` (409 on stale `If-Match`) |
+| `POST /api/restart` | `cli-restart.cjs` (pm2-aware) |
+| `GET /api/status`   | shells out to `autopg status --json` |
+
+## Layout
+
+```
+console/
+├── README.md                   # this file
+├── index.html                  # entry — pinned React + Babel CDN scripts
+├── app.jsx                     # shell + sidebar router (11 routes)
+├── api.js                      # fetch wrapper, holds latest etag, surfaces ETAG_MISMATCH
+├── components.jsx              # shared widgets (Seg, Toggle, Field, …)
+├── data.jsx                    # demo data fixtures (used by placeholder screens)
+├── tweaks-panel.jsx            # theme/phosphor/density/CRT toggles (persists to settings.ui)
+├── colors_and_type.css         # design tokens
+├── console.css                 # layout + screen styles
+└── screens/
+    ├── settings.jsx            # ✅ functional — 6-section schema editor
+    ├── databases.jsx           # [ coming soon ]
+    ├── tables.jsx              # [ coming soon ]
+    ├── sql.jsx                 # [ coming soon ]
+    ├── optimizer.jsx           # [ coming soon ]
+    ├── security.jsx            # [ coming soon ]
+    ├── ingress.jsx             # [ coming soon ]
+    ├── health.jsx              # [ coming soon ] — next wish
+    ├── sync.jsx                # [ coming soon ]
+    ├── rlm-trace.jsx           # [ coming soon ]
+    └── rlm-sim.jsx             # [ coming soon ]
+```
+
+## Screen rollout
+
+| Screen | Status | Notes |
+|--------|--------|-------|
+| Settings | ✅ functional | 6 sections, type-aware controls, raw GUC passthrough, etag concurrency, env-override chip |
+| Health | 🟡 next | Live cluster health metrics — next wish |
+| Databases | ⚪ placeholder | List + create + drop |
+| Tables | ⚪ placeholder | Per-DB table inspector |
+| SQL | ⚪ placeholder | Ad-hoc query runner |
+| Optimizer | ⚪ placeholder | Plan inspector / GUC tuner suggestions |
+| Security | ⚪ placeholder | Roles, RLS, audit log |
+| Ingress | ⚪ placeholder | Listener / TLS / token surface |
+| Sync | ⚪ placeholder | Replication-slot status |
+| RLM-trace | ⚪ placeholder | RLM agent trace viewer (depends on rlmx) |
+| RLM-sim | ⚪ placeholder | RLM scenario simulator (depends on rlmx) |
+
+## Local dev loop
+
+The console is shipped as static files — no build, no bundler. Edit the
+`.jsx` files in place; refresh the browser tab to pick up the change
+(Babel transpiles in the browser at load time). The CDN scripts are
+pinned with SRI integrity hashes — bumping React or Babel requires
+re-pinning the matching `integrity="sha384-…"` attribute in
+[`index.html`](./index.html).
+
+```bash
+autopg ui --no-open --port 8500 &
+open http://127.0.0.1:8500
+# … edit screens/settings.jsx, refresh browser …
+kill %1
+```
+
+The Settings screen reads live state from `~/.autopg/settings.json`
+through the helper endpoints, so changes survive reload and round-trip
+through `autopg config get` from another shell.
+
+### Concurrency model
+
+`api.js` stores the etag returned by every successful GET and sends it
+back as `If-Match` on the next PUT. If a parallel `autopg config set` (or
+another browser tab) drifts the file, the PUT comes back as
+`409 ETAG_MISMATCH` with a fresh `currentEtag`. The Settings screen
+catches this and shows a "settings changed, reload?" banner instead of
+overwriting the operator's other changes.
+
+### Env-override chip
+
+`GET /api/settings` returns a `sources` map (one entry per leaf:
+`'default' | 'file' | 'env:<NAME>'`). Rows whose source starts with
+`env:` render a yellow `OVERRIDDEN BY ENV` chip — Save still writes the
+file, but `loadEffectiveConfig()` will keep returning the env value
+until the env var is unset or the daemon is restarted with a clean
+environment.
+
+## Design system
+
+The console UI is derived from the `pgserve-console` design kit at
+`namastex-design-system/ui_kits/pgserve-console`. The CSS files
+(`colors_and_type.css`, `console.css`) and the shared widgets
+(`components.jsx`, `tweaks-panel.jsx`) are copied verbatim — the
+soft rename only touches the topbar identity (`pgserve` → `autopg`)
+and the Settings screen, which was rewritten to match the
+6-section schema documented in
+[`docs/settings-schema.md`](../docs/settings-schema.md).
+
+## What's deliberately not here
+
+- **No build step.** Pre-bundling is a future optimization. The CDN +
+  Babel-in-browser path is intentional for v1 — zero infrastructure.
+- **No daemon HTTP API.** The CLI is the source of truth; every UI
+  mutation shells out. This means the UI works ahead of `autopg
+  install` (you can configure before the daemon ever runs) and
+  cannot leak privileges through a long-lived listening socket.
+- **No multi-user / multi-machine access.** 127.0.0.1 only, by
+  design.
+- **No telemetry, no analytics.** Static page + four endpoints, all
+  local.

package/console/api.js

@@ -0,0 +1,173 @@
+/* autopg console · API client.
+ *
+ * Wraps the four helper endpoints exposed by `autopg ui`:
+ *   GET  /api/settings   →  { settings, sources, etag, path }
+ *   PUT  /api/settings   →  { ok, etag } | { error: { code, message, field? } }
+ *   POST /api/restart    →  { ok } | { error }
+ *   GET  /api/status     →  whatever `pgserve status --json` returns
+ *
+ * The latest etag from a successful GET is cached on the module so PUTs can
+ * send `If-Match` without the caller threading it through manually. PUT
+ * replies update the cached etag too so successive saves chain cleanly.
+ *
+ * Errors from the server come back as `{ error: { code, message, field? } }`.
+ * The wrapper raises a structured `ApiError` (with `.code`, `.field`,
+ * `.message`, `.status`, `.currentEtag?`) so screens can branch on the code
+ * without parsing strings. ETAG_MISMATCH is surfaced as a normal rejection
+ * with `error.code === 'ETAG_MISMATCH'` plus `error.currentEtag` so the
+ * Settings screen can show a "settings changed, reload?" banner.
+ */
+(function (root) {
+  'use strict';
+
+  const STATE = { etag: null };
+
+  class ApiError extends Error {
+    constructor({ code, message, field, status, currentEtag }) {
+      super(message || code || 'api error');
+      this.name = 'ApiError';
+      this.code = code || 'UNKNOWN';
+      if (field) this.field = field;
+      if (typeof status === 'number') this.status = status;
+      if (currentEtag) this.currentEtag = currentEtag;
+    }
+  }
+
+  async function parseJson(res) {
+    const text = await res.text();
+    if (!text) return {};
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { _raw: text };
+    }
+  }
+
+  async function getSettings() {
+    const res = await fetch('/api/settings', {
+      method: 'GET',
+      headers: { accept: 'application/json' },
+      cache: 'no-store',
+    });
+    const body = await parseJson(res);
+    if (!res.ok) {
+      throw new ApiError({
+        code: body?.error?.code,
+        message: body?.error?.message,
+        field: body?.error?.field,
+        status: res.status,
+      });
+    }
+    if (body && body.etag) STATE.etag = body.etag;
+    return body;
+  }
+
+  async function putSettings(patch, { ifMatch } = {}) {
+    const etag = ifMatch ?? STATE.etag;
+    if (!etag) {
+      throw new ApiError({
+        code: 'PRECONDITION_REQUIRED',
+        message: 'no etag cached — call getSettings() before putSettings()',
+        status: 428,
+      });
+    }
+    const res = await fetch('/api/settings', {
+      method: 'PUT',
+      headers: {
+        'content-type': 'application/json',
+        'if-match': etag,
+        accept: 'application/json',
+      },
+      body: JSON.stringify(patch ?? {}),
+    });
+    const body = await parseJson(res);
+    if (res.status === 409) {
+      // Update the cached etag so the next reload has the latest.
+      if (body && body.currentEtag) STATE.etag = body.currentEtag;
+      throw new ApiError({
+        code: body?.error?.code || 'ETAG_MISMATCH',
+        message: body?.error?.message || 'settings changed on disk',
+        status: 409,
+        currentEtag: body?.currentEtag,
+      });
+    }
+    if (!res.ok) {
+      throw new ApiError({
+        code: body?.error?.code,
+        message: body?.error?.message,
+        field: body?.error?.field,
+        status: res.status,
+      });
+    }
+    if (body && body.etag) STATE.etag = body.etag;
+    return body;
+  }
+
+  async function restart() {
+    const res = await fetch('/api/restart', {
+      method: 'POST',
+      headers: { accept: 'application/json' },
+    });
+    const body = await parseJson(res);
+    if (!res.ok) {
+      throw new ApiError({
+        code: body?.error?.code,
+        message: body?.error?.message,
+        status: res.status,
+      });
+    }
+    return body;
+  }
+
+  async function getStatus() {
+    const res = await fetch('/api/status', {
+      method: 'GET',
+      headers: { accept: 'application/json' },
+      cache: 'no-store',
+    });
+    const body = await parseJson(res);
+    if (!res.ok) {
+      throw new ApiError({
+        code: body?.error?.code,
+        message: body?.error?.message,
+        status: res.status,
+      });
+    }
+    return body;
+  }
+
+  // Live pgserve stats — connections + databases. Always returns a body
+  // (status 200) even when the daemon is unreachable; check `body.ok`.
+  // Safe to poll from the topbar without try/catch error handling.
+  async function getStats() {
+    try {
+      const res = await fetch('/api/stats', {
+        method: 'GET',
+        headers: { accept: 'application/json' },
+        cache: 'no-store',
+      });
+      return await parseJson(res);
+    } catch (err) {
+      return { ok: false, reason: 'fetch-failed', message: err.message };
+    }
+  }
+
+  function getCachedEtag() {
+    return STATE.etag;
+  }
+
+  function setCachedEtag(etag) {
+    STATE.etag = etag || null;
+  }
+
+  root.AutopgApi = {
+    getSettings,
+    putSettings,
+    restart,
+    getStatus,
+    getStats,
+    getCachedEtag,
+    setCachedEtag,
+    ApiError,
+  };
+})(typeof window !== 'undefined' ? window : globalThis);