npm - pgserve - Versions diffs - 2.2.0 → 2.2.2 - Mend

pgserve 2.2.0 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/CHANGELOG.md +58 -0
package/bin/pgserve-wrapper.cjs +1 -0
package/console/dist/app.js +121 -0
package/console/dist/index.html +13 -0
package/package.json +12 -6
package/scripts/postinstall.cjs +60 -0
package/scripts/test-bun-self-heal.sh +163 -0
package/scripts/test-npx.sh +60 -0
package/src/cli-install.cjs +14 -0
package/src/cli-ui.cjs +19 -2
package/src/upgrade/index.js +65 -0
package/src/upgrade/runner.js +23 -0
package/src/upgrade/steps/binary-cache-flush.js +67 -0
package/src/upgrade/steps/consumer-signal.js +40 -0
package/src/upgrade/steps/env-refresh.js +89 -0
package/src/upgrade/steps/health-validate.js +53 -0
package/src/upgrade/steps/plpgsql-resolve.js +66 -0
package/src/upgrade/steps/port-reconcile.js +52 -0
package/console/README.md +0 -131
package/console/api.js +0 -173
package/console/app.jsx +0 -483
package/console/components.jsx +0 -167
package/console/data.jsx +0 -350
package/console/index.html +0 -31
package/console/screens/databases.jsx +0 -5
package/console/screens/health.jsx +0 -5
package/console/screens/ingress.jsx +0 -5
package/console/screens/optimizer.jsx +0 -5
package/console/screens/rlm-sim.jsx +0 -5
package/console/screens/rlm-trace.jsx +0 -5
package/console/screens/security.jsx +0 -5
package/console/screens/settings.jsx +0 -611
package/console/screens/sql.jsx +0 -5
package/console/screens/sync.jsx +0 -5
package/console/screens/tables.jsx +0 -5
package/console/tweaks-panel.jsx +0 -425
/package/console/{colors_and_type.css → dist/colors_and_type.css} +0 -0
/package/console/{console.css → dist/console.css} +0 -0

package/console/dist/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="mdr" data-screen-label="autopg console">
+<head>
+<meta charset="utf-8" />
+<title>autopg · console</title>
+<link rel="stylesheet" href="colors_and_type.css" />
+<link rel="stylesheet" href="console.css?v=settings1" />
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="./app.js"></script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,11 +11,12 @@
   "files": [
     "bin/",
     "src/",
-    "console/",
+    "console/dist/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "SECURITY.md"
+    "SECURITY.md",
+    "scripts/"
   ],
   "scripts": {
     "bench": "bun tests/benchmarks/runner.js",
@@ -25,13 +26,16 @@
     "start": "bun bin/postgres-server.js",
     "build": "bun build --compile bin/postgres-server.js --outfile dist/pgserve",
     "build:all": "make build-all",
+    "console:build": "bun build console/src/main.jsx --target browser --minify --define 'process.env.NODE_ENV=\"production\"' --outfile console/dist/app.js && cp console/src/index.html console/dist/index.html && cp console/src/*.css console/dist/",
+    "console:dev": "bun build console/src/main.jsx --target browser --define 'process.env.NODE_ENV=\"development\"' --watch --outfile console/dist/app.js",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
     "deadcode": "knip",
     "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"
+    "prepublishOnly": "npm run console:build && npm run lint && npm run deadcode && npm run test:npx && npm run test:bun-self-heal",
+    "prepare": "husky",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
     "postgresql",
@@ -74,6 +78,8 @@
     ]
   },
   "dependencies": {
-    "bun": "^1.3.4"
+    "bun": "^1.3.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }

package/scripts/postinstall.cjs ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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/cli-ui.cjs CHANGED Viewed

@@ -142,8 +142,25 @@ function listenWithFallback(server, host, preferredPort) {
  * via npm the `files` allowlist preserves the layout.
  */
 function resolveConsoleRoot() {
-  // src/ → repo root → console/
-  return path.resolve(__dirname, '..', 'console');
+  // After autopg-console-dist (v2.2.2): the SPA ships pre-bundled in
+  // console/dist/ instead of as flat .jsx files at console/. Prefer dist/;
+  // fall back to console/src/ for repo-checkout dev mode (where dist/ is
+  // gitignored and only built on demand).
+  const consoleParent = path.resolve(__dirname, '..', 'console');
+  const distRoot = path.join(consoleParent, 'dist');
+  if (fs.existsSync(distRoot)) return distRoot;
+  const srcRoot = path.join(consoleParent, 'src');
+  if (fs.existsSync(srcRoot)) {
+    process.stderr.write(
+      'autopg ui: running unbuilt sources from console/src/ — run `bun run console:build` for production behavior\n',
+    );
+    return srcRoot;
+  }
+  throw new Error(
+    'console assets not found: expected console/dist/ (run `bun run console:build`) or console/src/ (repo checkout)',
+  );
 }
 /**

package/src/upgrade/index.js ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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}` };
+}