pgserve 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 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

package/bin/pgserve-wrapper.cjs

@@ -40,6 +40,7 @@ const __installSubcommands = new Set([
   // 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',
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -15,7 +15,8 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "SECURITY.md"
+    "SECURITY.md",
+    "scripts/"
   ],
   "scripts": {
     "bench": "bun tests/benchmarks/runner.js",
@@ -31,7 +32,8 @@
     "test:npx": "scripts/test-npx.sh",
     "test:bun-self-heal": "scripts/test-bun-self-heal.sh",
     "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx && npm run test:bun-self-heal",
-    "prepare": "husky"
+    "prepare": "husky",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
     "postgresql",

package/scripts/postinstall.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * autopg postinstall — auto-runs `autopg upgrade` on detected upgrade.
+ *
+ * Behavior:
+ *   - Fresh install (no ~/.autopg/data/) → exit 0 silently (no upgrade needed)
+ *   - Upgrade install (data dir exists) → invoke `autopg upgrade --quiet`
+ *   - Soft-fail: any error logs warning, exits 0 (never breaks `bun install`)
+ *   - Skip override: AUTOPG_SKIP_POSTINSTALL=1 → exit 0 immediately
+ *
+ * The escape hatch for forced re-runs is `autopg upgrade` (manual).
+ *
+ * See: .genie/wishes/autopg-upgrade-command/WISH.md
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function getAutopgRoot() {
+  return process.env.AUTOPG_CONFIG_DIR || process.env.PGSERVE_CONFIG_DIR || `${process.env.HOME}/.autopg`;
+}
+
+function main() {
+  if (process.env.AUTOPG_SKIP_POSTINSTALL === '1') {
+    return;
+  }
+  const dataDir = path.join(getAutopgRoot(), 'data');
+  if (!fs.existsSync(dataDir)) {
+    // Fresh install — nothing to upgrade
+    return;
+  }
+  // Locate own CLI entry — script is run from the package dir at install time
+  const cliEntry = path.join(__dirname, '..', 'bin', 'pgserve-wrapper.cjs');
+  if (!fs.existsSync(cliEntry)) {
+    process.stderr.write(`[autopg-postinstall] wrapper not found at ${cliEntry}, skipping\n`);
+    return;
+  }
+  const result = spawnSync(process.execPath, [cliEntry, 'upgrade', '--quiet'], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+    timeout: 60_000,
+  });
+  if (result.error) {
+    process.stderr.write(`[autopg-postinstall] WARNING: upgrade invocation failed: ${result.error.message}\n`);
+    process.stderr.write('[autopg-postinstall] Run `autopg upgrade` manually to retry.\n');
+    return;
+  }
+  if (result.status !== 0) {
+    process.stderr.write(`[autopg-postinstall] WARNING: \`autopg upgrade\` exited ${result.status}\n`);
+    process.stderr.write('[autopg-postinstall] Run `autopg upgrade` manually to investigate.\n');
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[autopg-postinstall] WARNING: unexpected error: ${err.message}\n`);
+}
+
+process.exit(0);

package/scripts/test-bun-self-heal.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Regression test for https://github.com/namastexlabs/pgserve/issues/22
+#
+# When pgserve is installed via `bun install`, the nested `bun` npm package's
+# postinstall can be skipped, leaving @oven/bun-<platform>/bin/bun empty.
+# The bun stub then refuses to run with "Bun's postinstall script was not run".
+# pgserve-wrapper.cjs must detect this and self-heal via `node install.js`.
+#
+# This test stages a synthetic broken install tree, runs the wrapper, and
+# asserts that it recovers and spawns postgres-server.
+
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+WRAPPER="$REPO_ROOT/bin/pgserve-wrapper.cjs"
+
+if [ ! -f "$WRAPPER" ]; then
+  echo "✗ wrapper not found: $WRAPPER"
+  exit 1
+fi
+
+# Use a real bun binary as the "recovered" payload so the healthy-path
+# assertion is meaningful. Falls back to any bun on PATH.
+REAL_BUN="${BUN_BIN:-$(command -v bun || true)}"
+if [ -z "$REAL_BUN" ] || [ ! -x "$REAL_BUN" ]; then
+  echo "✗ bun runtime not found on PATH (set BUN_BIN to override)"
+  exit 1
+fi
+
+FIXTURE=$(mktemp -d)
+trap "rm -rf $FIXTURE" EXIT
+
+mkdir -p "$FIXTURE/node_modules/bun/bin"
+mkdir -p "$FIXTURE/node_modules/@oven/bun-linux-x64/bin"   # empty, simulating the bug
+mkdir -p "$FIXTURE/node_modules/.bin"
+mkdir -p "$FIXTURE/node_modules/pgserve/bin"
+
+cp "$WRAPPER" "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs"
+
+# Stub postgres-server so we can detect a successful spawn without needing
+# postgres binaries in the fixture.
+cat > "$FIXTURE/node_modules/pgserve/bin/postgres-server.js" <<'EOF'
+console.log("postgres-server-spawned");
+process.exit(0);
+EOF
+
+# Fake bun install.js: copies the real bun into the expected @oven location,
+# mirroring what the real postinstall does.
+cat > "$FIXTURE/node_modules/bun/install.js" <<EOF
+const fs = require('fs');
+const path = require('path');
+const dst = path.resolve(__dirname, '..', '@oven', 'bun-linux-x64', 'bin', 'bun');
+fs.mkdirSync(path.dirname(dst), { recursive: true });
+fs.copyFileSync('$REAL_BUN', dst);
+fs.chmodSync(dst, 0o755);
+console.log('[test] install.js populated', dst);
+EOF
+echo '{"name":"bun","version":"1.3.12"}' > "$FIXTURE/node_modules/bun/package.json"
+
+# Broken bun stub: prints the postinstall error unless the @oven binary exists.
+cat > "$FIXTURE/node_modules/bun/bin/bun" <<'EOF'
+#!/bin/sh
+SELF=$(readlink -f "$0")
+TARGET="$(dirname "$SELF")/../../@oven/bun-linux-x64/bin/bun"
+if [ ! -x "$TARGET" ]; then
+  echo "Error: Bun's postinstall script was not run." >&2
+  echo "" >&2
+  echo "To fix this, run the postinstall script manually:" >&2
+  echo "  cd node_modules/bun && node install.js" >&2
+  exit 1
+fi
+exec "$TARGET" "$@"
+EOF
+chmod +x "$FIXTURE/node_modules/bun/bin/bun"
+
+ln -s ../bun/bin/bun "$FIXTURE/node_modules/.bin/bun"
+
+echo "=== Testing self-heal on broken install ==="
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1)
+EXIT=$?
+
+if [ $EXIT -ne 0 ]; then
+  echo "✗ wrapper exited non-zero: $EXIT"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "attempting self-heal"; then
+  echo "✗ wrapper did not attempt self-heal"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "bun runtime recovered"; then
+  echo "✗ wrapper did not report recovery"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned after self-heal"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ self-heal path: wrapper detected, repaired, and spawned postgres-server"
+
+echo ""
+echo "=== Testing healthy path is unaffected ==="
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1)
+EXIT=$?
+
+if [ $EXIT -ne 0 ]; then
+  echo "✗ wrapper exited non-zero on healthy path: $EXIT"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if echo "$OUTPUT" | grep -q "self-heal\|recovered"; then
+  echo "✗ wrapper logged self-heal messages on a healthy install"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned on healthy path"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ healthy path: wrapper was silent and spawned postgres-server directly"
+
+echo ""
+echo "=== Testing non-postinstall errors surface raw ==="
+# Replace stub with one that emits an unrelated error.
+cat > "$FIXTURE/node_modules/bun/bin/bun" <<'EOF'
+#!/bin/sh
+echo "Error: GLIBC_2.99 not found (libc mismatch)" >&2
+exit 127
+EOF
+chmod +x "$FIXTURE/node_modules/bun/bin/bun"
+
+# Clear the @oven healed binary so the stub is what runs.
+rm -f "$FIXTURE/node_modules/@oven/bun-linux-x64/bin/bun"
+
+OUTPUT=$(node "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs" 2>&1 || true)
+
+if echo "$OUTPUT" | grep -q "self-heal"; then
+  echo "✗ wrapper tried self-heal for a non-postinstall error"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+if ! echo "$OUTPUT" | grep -q "GLIBC_2.99"; then
+  echo "✗ wrapper did not surface the real error message"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ unrelated-error path: wrapper surfaced the raw error without self-heal"
+
+echo ""
+echo "=== bun self-heal test PASSED ==="

package/scripts/test-npx.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Test that the package works with npx (simulates fresh user install)
+# This catches path resolution issues that static analysis can't detect
+
+set -e
+
+echo "=== Testing npx compatibility ==="
+
+# Create temp directory
+TEST_DIR=$(mktemp -d)
+trap "rm -rf $TEST_DIR" EXIT
+
+# Pack the current package
+echo "Packing package..."
+PACK_OUTPUT=$(npm pack --pack-destination "$TEST_DIR" 2>&1)
+PACK_FILE=$(echo "$PACK_OUTPUT" | grep -E '\.tgz$' | tail -1)
+
+# If npm pack fails, exit with an error
+if [ -z "$PACK_FILE" ] || [ ! -f "$TEST_DIR/$PACK_FILE" ]; then
+  echo "✗ Failed to pack package with npm"
+  echo "Pack output: $PACK_OUTPUT"
+  exit 1
+fi
+echo "Packed: $PACK_FILE"
+
+# Install in isolated environment using npm
+echo "Installing in isolated environment..."
+cd "$TEST_DIR"
+echo '{"name":"test-npx-install","private":true}' > package.json
+npm install "./$PACK_FILE" > /dev/null 2>&1
+
+# Test that it starts (with timeout)
+echo "Testing server startup via npx..."
+timeout 30 npx pgserve --no-cluster --port 15432 > output.log 2>&1 &
+PID=$!
+
+# Wait for ready signal (Server started successfully!)
+for i in {1..60}; do
+  if grep -q "Server started successfully" output.log 2>/dev/null; then
+    echo "✓ Server started successfully via npx"
+    kill $PID 2>/dev/null || true
+    wait $PID 2>/dev/null || true
+    echo "=== npx test PASSED ==="
+    exit 0
+  fi
+  if ! kill -0 $PID 2>/dev/null; then
+    echo "✗ Server exited unexpectedly"
+    cat output.log
+    echo "=== npx test FAILED ==="
+    exit 1
+  fi
+  sleep 0.5
+done
+
+# Timeout
+kill $PID 2>/dev/null || true
+echo "✗ Server did not start within timeout"
+cat output.log
+echo "=== npx test FAILED ==="
+exit 1

package/src/cli-install.cjs

@@ -483,6 +483,20 @@ function dispatch(subcommand, args, ctx) {
       return cmdUrl();
     case 'port':
       return cmdPort();
+    case 'upgrade': {
+      const opts = {
+        quiet: args.includes('--quiet'),
+        dryRun: args.includes('--dry-run'),
+        skipSteps: (() => {
+          const idx = args.indexOf('--skip-steps');
+          if (idx === -1) return [];
+          return (args[idx + 1] || '').split(',').filter(Boolean);
+        })(),
+      };
+      return import(require('node:path').join(__dirname, 'upgrade', 'index.js'))
+        .then((mod) => mod.upgrade(opts))
+        .then((r) => process.exit(r.ok ? 0 : 1));
+    }
     case 'config': {
       const cfg = require('./cli-config.cjs');
       const [sub, ...rest] = args;

package/src/upgrade/index.js

@@ -0,0 +1,65 @@
+/**
+ * autopg upgrade — idempotent migration orchestrator.
+ *
+ * Runs 6 steps in order, each safe to re-run any number of times:
+ *   1. port-reconcile    — ensure pgserve listens on canonical port (8432)
+ *   2. binary-cache-flush — verify binary version matches PINNED_PG_VERSION
+ *   3. plpgsql-resolve   — DROP+CREATE plpgsql per DB to refresh .so path
+ *   4. env-refresh       — regenerate ~/.autopg/<app>.env URLs
+ *   5. consumer-signal   — touch ~/.autopg/state/upgrade.signal
+ *   6. health-validate   — pg_isready + per-DB plpgsql smoke test
+ *
+ * Patches the upgrade-path hole left by autopg-v22 partial roll-out.
+ * See: .genie/wishes/autopg-upgrade-command/WISH.md
+ */
+
+import { runStep } from './runner.js';
+import * as portReconcile from './steps/port-reconcile.js';
+import * as binaryCacheFlush from './steps/binary-cache-flush.js';
+import * as plpgsqlResolve from './steps/plpgsql-resolve.js';
+import * as envRefresh from './steps/env-refresh.js';
+import * as consumerSignal from './steps/consumer-signal.js';
+import * as healthValidate from './steps/health-validate.js';
+
+export const STEPS = [
+  { name: 'port-reconcile', impl: portReconcile },
+  { name: 'binary-cache-flush', impl: binaryCacheFlush },
+  { name: 'plpgsql-resolve', impl: plpgsqlResolve },
+  { name: 'env-refresh', impl: envRefresh },
+  { name: 'consumer-signal', impl: consumerSignal },
+  { name: 'health-validate', impl: healthValidate },
+];
+
+export async function upgrade(options = {}) {
+  const { quiet = false, dryRun = false, skipSteps = [] } = options;
+  const log = (msg) => { if (!quiet) process.stderr.write(`${msg}\n`); };
+  const warn = (msg) => process.stderr.write(`${msg}\n`);
+
+  log(`autopg upgrade starting (dryRun=${dryRun}, quiet=${quiet})`);
+
+  const results = [];
+  for (const step of STEPS) {
+    if (skipSteps.includes(step.name)) {
+      log(`[${step.name}] SKIP (excluded by --skip-steps)`);
+      results.push({ name: step.name, status: 'SKIP', detail: 'excluded' });
+      continue;
+    }
+    try {
+      const result = await runStep(step.name, step.impl, { dryRun, log, warn });
+      results.push(result);
+    } catch (err) {
+      warn(`[${step.name}] FAIL: ${err.message}`);
+      results.push({ name: step.name, status: 'FAIL', detail: err.message });
+    }
+  }
+
+  const failed = results.filter((r) => r.status === 'FAIL');
+  const summary = `autopg upgrade complete: ${results.length - failed.length}/${results.length} steps OK`;
+  log(summary);
+  if (failed.length > 0) {
+    warn(`Failed steps: ${failed.map((r) => r.name).join(', ')}`);
+    warn('Re-run `autopg upgrade` after addressing the above.');
+    return { ok: false, results, summary };
+  }
+  return { ok: true, results, summary };
+}

package/src/upgrade/runner.js

@@ -0,0 +1,23 @@
+/**
+ * Step runner — wraps each step with consistent logging + error capture.
+ *
+ * A step module exports `{ name, plan(ctx), execute(ctx) }`:
+ *   - plan(ctx)    → string describing what would happen (dry-run output)
+ *   - execute(ctx) → { status: 'OK'|'SKIP'|'FAIL', detail: string }
+ */
+
+export async function runStep(name, stepImpl, { dryRun, log, warn }) {
+  if (typeof stepImpl.plan !== 'function' || typeof stepImpl.execute !== 'function') {
+    throw new Error(`step ${name} missing plan() or execute()`);
+  }
+  if (dryRun) {
+    const planned = await stepImpl.plan({ log, warn });
+    log(`[${name}] DRY-RUN: ${planned}`);
+    return { name, status: 'DRY-RUN', detail: planned };
+  }
+  const result = await stepImpl.execute({ log, warn });
+  const status = result.status || 'OK';
+  const detail = result.detail || '';
+  log(`[${name}] ${status}: ${detail}`);
+  return { name, status, detail };
+}

package/src/upgrade/steps/binary-cache-flush.js

@@ -0,0 +1,67 @@
+/**
+ * Step 2 — Binary cache flush against PINNED_PG_VERSION.
+ * Re-downloads if version marker missing or mismatch. Idempotent.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const name = 'binary-cache-flush';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getAutopgRoot() {
+  return process.env.AUTOPG_CONFIG_DIR || process.env.PGSERVE_CONFIG_DIR || `${process.env.HOME}/.autopg`;
+}
+
+function getBinaryCacheDir() {
+  return path.join(getAutopgRoot(), 'bin', `${process.platform}-${process.arch}`);
+}
+
+function getPinnedVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf8'));
+    if (pkg.autopg && pkg.autopg.pinnedPgVersion) return pkg.autopg.pinnedPgVersion;
+  } catch { /* fall through */ }
+  return process.env.AUTOPG_PINNED_PG_VERSION || '18.3';
+}
+
+function readVersionMarker(cacheDir) {
+  try { return fs.readFileSync(path.join(cacheDir, '.version'), 'utf8').trim(); } catch { return null; }
+}
+
+export async function plan() {
+  const cacheDir = getBinaryCacheDir();
+  const pinned = getPinnedVersion();
+  const marker = readVersionMarker(cacheDir);
+  if (!fs.existsSync(path.join(cacheDir, 'bin', 'postgres'))) {
+    return `binary missing at ${cacheDir} — would trigger download for PG ${pinned}`;
+  }
+  if (marker !== pinned) return `version drift (cached=${marker || 'unknown'}, pinned=${pinned}) — would re-download`;
+  return `binary present and matches pinned ${pinned}, no action needed`;
+}
+
+export async function execute({ log, warn }) {
+  const cacheDir = getBinaryCacheDir();
+  const pinned = getPinnedVersion();
+  const marker = readVersionMarker(cacheDir);
+  const binaryExists = fs.existsSync(path.join(cacheDir, 'bin', 'postgres'));
+
+  if (binaryExists && marker === pinned) return { status: 'SKIP', detail: `binary OK (PG ${pinned})` };
+
+  let downloadFn;
+  try {
+    const postgres = await import('../../postgres.js');
+    downloadFn = postgres.ensureBinary || postgres.downloadBinary || postgres.installBinary;
+  } catch { /* postgres module not loadable here */ }
+
+  if (!downloadFn) {
+    warn(`binary needs refresh (pinned=${pinned}, cached=${marker || 'missing'}) but autopg postgres module not exposing download API`);
+    warn(`operator action: rerun \`bun install -g @automagik/autopg@latest\``);
+    return { status: 'FAIL', detail: 'binary refresh needs autopg npm reinstall' };
+  }
+  log(`re-downloading PG ${pinned} into ${cacheDir}`);
+  await downloadFn({ version: pinned, targetDir: cacheDir });
+  fs.writeFileSync(path.join(cacheDir, '.version'), pinned, { mode: 0o644 });
+  return { status: 'OK', detail: `binary refreshed to PG ${pinned}` };
+}

package/src/upgrade/steps/consumer-signal.js

@@ -0,0 +1,40 @@
+/**
+ * Step 5 — Consumer reconnect signal. Touches ~/.autopg/state/upgrade.signal
+ * with epoch + autopg version. Consumers (omni-api, genie-serve) opt-in via fs.watch.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const name = 'consumer-signal';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function getAutopgRoot() {
+  return process.env.AUTOPG_CONFIG_DIR || process.env.PGSERVE_CONFIG_DIR || `${process.env.HOME}/.autopg`;
+}
+
+function getAutopgVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch { return 'unknown'; }
+}
+
+export async function plan() {
+  return `would write upgrade signal at ${path.join(getAutopgRoot(), 'state', 'upgrade.signal')}`;
+}
+
+export async function execute() {
+  const signalDir = path.join(getAutopgRoot(), 'state');
+  fs.mkdirSync(signalDir, { recursive: true });
+  const payload = {
+    timestamp: new Date().toISOString(),
+    epoch_ms: Date.now(),
+    autopg_version: getAutopgVersion(),
+    canonical_port: 8432,
+  };
+  const signalPath = path.join(signalDir, 'upgrade.signal');
+  fs.writeFileSync(signalPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o644 });
+  return { status: 'OK', detail: `signal written at ${signalPath}` };
+}

package/src/upgrade/steps/env-refresh.js

@@ -0,0 +1,89 @@
+/**
+ * Step 4 — App env file refresh. Regenerates ~/.autopg/<name>.env with
+ * canonical port. Verifies SCRAM cred works; warns if rotation needed.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export const name = 'env-refresh';
+const CANONICAL_PORT = 8432;
+
+function getAutopgRoot() {
+  return process.env.AUTOPG_CONFIG_DIR || process.env.PGSERVE_CONFIG_DIR || `${process.env.HOME}/.autopg`;
+}
+
+function listAppEnvFiles() {
+  const root = getAutopgRoot();
+  if (!fs.existsSync(root)) return [];
+  return fs.readdirSync(root)
+    .filter((f) => f.endsWith('.env') && !f.startsWith('.'))
+    .map((f) => path.join(root, f));
+}
+
+function parseEnv(content) {
+  const out = {};
+  for (const line of content.split('\n')) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) out[m[1]] = m[2].replace(/^"(.*)"$/, '$1');
+  }
+  return out;
+}
+
+function buildUrl({ user, password, port, db }) {
+  const enc = (s) => encodeURIComponent(s);
+  return `postgresql://${enc(user)}:${enc(password)}@127.0.0.1:${port}/${db}`;
+}
+
+function tryConnect(url) {
+  try {
+    execSync(`psql ${JSON.stringify(url)} -At -c "SELECT 1"`, { stdio: 'pipe', env: process.env });
+    return true;
+  } catch { return false; }
+}
+
+export async function plan() {
+  const files = listAppEnvFiles();
+  if (files.length === 0) return 'no app .env files found in autopg root';
+  return `would verify+rewrite ${files.length} env file(s): ${files.map((f) => path.basename(f)).join(', ')}`;
+}
+
+export async function execute({ warn }) {
+  const files = listAppEnvFiles();
+  if (files.length === 0) return { status: 'SKIP', detail: 'no .env files' };
+
+  let updated = 0, valid = 0;
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, 'utf8');
+      const env = parseEnv(content);
+      const url = env.DATABASE_URL || env.PG_URL || env.POSTGRES_URL;
+      if (!url) {
+        warn(`[env-refresh] ${path.basename(file)}: no DATABASE_URL key`);
+        continue;
+      }
+      const parsed = new URL(url);
+      const newUrl = buildUrl({
+        user: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password),
+        port: CANONICAL_PORT,
+        db: parsed.pathname.replace(/^\//, ''),
+      });
+
+      if (tryConnect(newUrl)) {
+        valid++;
+        if (newUrl !== url) {
+          const newContent = content.replace(/^(DATABASE_URL|PG_URL|POSTGRES_URL)=.*/m, `$1=${newUrl}`);
+          fs.writeFileSync(file, newContent, { mode: 0o600 });
+          updated++;
+        }
+      } else {
+        warn(`[env-refresh] ${path.basename(file)}: SCRAM cred fails — rotate via \`autopg rotate <app>\``);
+      }
+    } catch (err) {
+      warn(`[env-refresh] ${path.basename(file)} failed: ${err.message}`);
+    }
+  }
+  return { status: 'OK', detail: `validated ${valid}/${files.length}, rewrote ${updated}` };
+}

package/src/upgrade/steps/health-validate.js

@@ -0,0 +1,53 @@
+/**
+ * Step 6 — Health validation. pg_isready + per-DB plpgsql smoke test.
+ */
+
+import { execSync } from 'node:child_process';
+
+export const name = 'health-validate';
+const CANONICAL_PORT = 8432;
+const SYSTEM_DBS = new Set(['template0', 'template1']);
+
+function pgIsReady() {
+  try { execSync(`pg_isready -h 127.0.0.1 -p ${CANONICAL_PORT}`, { stdio: 'pipe' }); return true; }
+  catch { return false; }
+}
+
+function listAllDbs() {
+  const env = { ...process.env, PGPASSWORD: process.env.PGPASSWORD || 'postgres' };
+  const out = execSync(
+    `psql -h 127.0.0.1 -p ${CANONICAL_PORT} -U postgres -At -c "SELECT datname FROM pg_database WHERE NOT datistemplate"`,
+    { env, stdio: ['ignore', 'pipe', 'pipe'] },
+  ).toString().trim();
+  return out ? out.split('\n').filter(Boolean) : [];
+}
+
+function plpgsqlSmoke(db) {
+  try {
+    const env = { ...process.env, PGPASSWORD: process.env.PGPASSWORD || 'postgres' };
+    execSync(
+      `psql -h 127.0.0.1 -p ${CANONICAL_PORT} -U postgres -d ${db} -At -c "DO \\$\\$ BEGIN RAISE NOTICE 'ok'; END; \\$\\$"`,
+      { env, stdio: 'pipe' },
+    );
+    return true;
+  } catch { return false; }
+}
+
+export async function plan() {
+  return `would check pg_isready on :${CANONICAL_PORT} + plpgsql smoke test in each user DB`;
+}
+
+export async function execute({ warn }) {
+  if (!pgIsReady()) return { status: 'FAIL', detail: `pg_isready failed on port ${CANONICAL_PORT}` };
+  let dbs;
+  try { dbs = listAllDbs(); } catch (err) { return { status: 'FAIL', detail: `cannot list DBs: ${err.message}` }; }
+
+  let pass = 0, fail = 0;
+  for (const db of dbs) {
+    if (SYSTEM_DBS.has(db)) continue;
+    if (plpgsqlSmoke(db)) pass++;
+    else { fail++; warn(`[health-validate] plpgsql smoke FAIL in ${db}`); }
+  }
+  if (fail > 0) return { status: 'FAIL', detail: `${pass}/${pass + fail} DBs healthy; ${fail} failure(s)` };
+  return { status: 'OK', detail: `pg_isready OK, plpgsql healthy in ${pass}/${pass} DBs` };
+}

package/src/upgrade/steps/plpgsql-resolve.js

@@ -0,0 +1,66 @@
+/**
+ * Step 3 — plpgsql extension re-resolve.
+ * DROP+CREATE plpgsql per user DB to refresh `.so` path against current $libdir.
+ * Skips DBs with user-owned plpgsql functions (CASCADE would drop them).
+ */
+
+import { execSync } from 'node:child_process';
+
+export const name = 'plpgsql-resolve';
+const CANONICAL_PORT = 8432;
+const SYSTEM_DBS = new Set(['postgres', 'template0', 'template1']);
+
+function pgQuery({ db, sql, captureStdout = false }) {
+  const env = { ...process.env, PGPASSWORD: process.env.PGPASSWORD || 'postgres' };
+  const cmd = `psql -h 127.0.0.1 -p ${CANONICAL_PORT} -U postgres -d ${db} -At -c ${JSON.stringify(sql)}`;
+  return captureStdout
+    ? execSync(cmd, { env, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
+    : execSync(cmd, { env, stdio: 'pipe' });
+}
+
+function listUserDbs() {
+  const out = pgQuery({
+    db: 'postgres',
+    sql: "SELECT datname FROM pg_database WHERE NOT datistemplate AND datname != 'postgres' ORDER BY datname",
+    captureStdout: true,
+  });
+  return out ? out.split('\n').filter(Boolean) : [];
+}
+
+function hasUserOwnedPlpgsqlFunctions(db) {
+  const out = pgQuery({
+    db,
+    sql: "SELECT count(*) FROM pg_proc p JOIN pg_language l ON p.prolang = l.oid WHERE l.lanname = 'plpgsql' AND p.proowner != 10",
+    captureStdout: true,
+  });
+  return parseInt(out, 10) > 0;
+}
+
+export async function plan() {
+  let dbs;
+  try { dbs = listUserDbs(); } catch (err) { return `cannot enumerate DBs: ${err.message}`; }
+  return `would DROP+CREATE plpgsql in ${dbs.length} user DB(s): ${dbs.join(', ')}`;
+}
+
+export async function execute({ warn }) {
+  let dbs;
+  try { dbs = listUserDbs(); } catch (err) { return { status: 'FAIL', detail: `cannot enumerate DBs: ${err.message}` }; }
+  if (dbs.length === 0) return { status: 'SKIP', detail: 'no user DBs to refresh' };
+
+  let refreshed = 0, skipped = 0;
+  for (const db of dbs) {
+    if (SYSTEM_DBS.has(db)) { skipped++; continue; }
+    try {
+      if (hasUserOwnedPlpgsqlFunctions(db)) {
+        warn(`[plpgsql-resolve] skip ${db}: user-owned plpgsql functions present (DROP CASCADE would lose them)`);
+        skipped++; continue;
+      }
+      pgQuery({ db, sql: 'DROP EXTENSION IF EXISTS plpgsql CASCADE; CREATE EXTENSION plpgsql' });
+      refreshed++;
+    } catch (err) {
+      warn(`[plpgsql-resolve] ${db} failed: ${err.message}`);
+      skipped++;
+    }
+  }
+  return { status: 'OK', detail: `refreshed ${refreshed} DB(s), skipped ${skipped}` };
+}

package/src/upgrade/steps/port-reconcile.js

@@ -0,0 +1,52 @@
+/**
+ * Step 1 — Port reconciliation. Ensures pgserve listens on canonical 8432.
+ * If running on a different port, stop and relaunch on 8432. Idempotent.
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const name = 'port-reconcile';
+const CANONICAL_PORT = 8432;
+
+function readPostmasterPid(dataDir) {
+  try {
+    const content = fs.readFileSync(path.join(dataDir, 'postmaster.pid'), 'utf8');
+    const lines = content.trim().split('\n');
+    return { pid: parseInt(lines[0], 10), port: parseInt(lines[3], 10) };
+  } catch {
+    return null;
+  }
+}
+
+function getDataDir() {
+  return process.env.PGSERVE_DATA || `${process.env.HOME}/.pgserve/data`;
+}
+
+export async function plan() {
+  const info = readPostmasterPid(getDataDir());
+  if (!info) return 'no running pgserve detected — nothing to reconcile';
+  if (info.port === CANONICAL_PORT) return `already on port ${CANONICAL_PORT}, no action needed`;
+  return `would stop pgserve PID ${info.pid} (port ${info.port}) and relaunch on ${CANONICAL_PORT}`;
+}
+
+export async function execute({ log, warn }) {
+  const info = readPostmasterPid(getDataDir());
+  if (!info) return { status: 'SKIP', detail: 'no running pgserve' };
+  if (info.port === CANONICAL_PORT) return { status: 'SKIP', detail: `already on ${CANONICAL_PORT}` };
+
+  log(`stopping pgserve PID ${info.pid} (port ${info.port})`);
+  try {
+    execSync(`pm2 restart pgserve --update-env -- --port ${CANONICAL_PORT}`, { stdio: 'pipe' });
+    return { status: 'OK', detail: `pm2 restart pgserve on port ${CANONICAL_PORT}` };
+  } catch (pm2Err) {
+    warn(`pm2 restart failed (${pm2Err.message}) — falling back to direct pg_ctl`);
+    try {
+      execSync(`pg_ctl -D ${getDataDir()} -m fast stop`, { stdio: 'pipe' });
+      return { status: 'OK', detail: `stopped pgserve; relaunch via pm2 or autopg install` };
+    } catch (ctlErr) {
+      throw new Error(`port reconcile failed: pm2 (${pm2Err.message}) and pg_ctl (${ctlErr.message})`);
+    }
+  }
+}