pgserve 1.1.9 → 1.1.10

package/.genie/AGENTS.md

@@ -5,6 +5,8 @@ description: Global agents (orchestration, QA, analysis, maintenance)
 github_url: https://github.com/namastexlabs/automagik-genie/tree/main/.genie
 ---
 
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 # Base Genie Agents
 
 **Global agents available across all collectives.**

package/.genie/code/AGENTS.md

@@ -11,6 +11,8 @@ forge:
   OPENCODE: {}
 ---
 
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 ## Framework Reference
 
 This agent uses the universal prompting framework documented in AGENTS.md §Prompting Standards Framework:

package/AGENTS.md

@@ -1,3 +1,5 @@
+> **Shared rules in `~/.claude/rules/agent-bible.md`. Read it.**
+
 # Genie Agent Framework
 
 ## Core Identity

package/bin/pgserve-wrapper.cjs

@@ -53,8 +53,113 @@ if (!bunPath) {
   process.exit(1);
 }
 
+// Pre-flight health check: verify bun can actually execute.
+//
+// When pgserve is installed via `bun install` (as a global or transitive dep),
+// the nested `bun` npm package's postinstall can be skipped, leaving
+// `@oven/bun-<platform>/bin/bun` empty. The bun stub at `node_modules/bun/bin/bun`
+// then exits instantly with:
+//   Error: Bun's postinstall script was not run.
+//
+// pglite-server.js's TCP readiness poll can't distinguish this from a slow
+// startup, so users see a confusing 30s timeout. Detect the specific error
+// here, attempt the documented self-heal once (`node install.js`), and retry.
+// If self-heal also fails, surface the real error instead of hanging later.
+ensureBunHealthy(bunPath);
+
 const scriptPath = path.join(__dirname, 'pglite-server.js');
 
+/**
+ * Verify the selected bun binary can execute. If it fails with the known
+ * "postinstall script was not run" signature, attempt a one-shot repair via
+ * the bun npm package's install.js. Throws (with a useful message) rather
+ * than letting pglite-server.js hang on the TCP readiness poll for 30s.
+ */
+function ensureBunHealthy(bunExe) {
+  const probe = probeBun(bunExe);
+  if (probe.ok) return;
+
+  // Only attempt self-heal for the specific postinstall-not-run failure.
+  // Any other failure (corrupt binary, unsupported glibc, etc.) is surfaced
+  // as-is rather than silently papered over.
+  if (!isPostinstallMissingError(probe.output)) {
+    console.error('Error: bun runtime at', bunExe, 'failed to execute:');
+    console.error(probe.output || '(no output)');
+    process.exit(1);
+  }
+
+  const installJs = findBunInstallJs(bunExe);
+  if (!installJs) {
+    console.error('Error: bun runtime at', bunExe, 'is missing its platform binary,');
+    console.error('and the recovery script (node_modules/bun/install.js) could not be located.');
+    console.error('');
+    console.error('Try reinstalling pgserve, or run the fix manually:');
+    console.error('  cd <node_modules>/bun && node install.js');
+    process.exit(1);
+  }
+
+  console.error('[pgserve] bun runtime missing platform binary; attempting self-heal...');
+  try {
+    execSync(`node ${JSON.stringify(installJs)}`, { stdio: 'inherit' });
+  } catch {
+    // fall through to second probe
+  }
+
+  const second = probeBun(bunExe);
+  if (second.ok) {
+    console.error('[pgserve] bun runtime recovered.');
+    return;
+  }
+
+  console.error('Error: bun runtime still broken after self-heal attempt.');
+  console.error(second.output || '(no output)');
+  console.error('');
+  console.error('Manual fix:');
+  console.error(`  cd ${path.dirname(path.dirname(installJs))}/bun && node install.js`);
+  console.error('');
+  console.error('Upstream bug: https://github.com/namastexlabs/pgserve/issues/22');
+  process.exit(1);
+}
+
+function probeBun(bunExe) {
+  try {
+    const out = execSync(`${JSON.stringify(bunExe)} --version`, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 10000,
+      encoding: 'utf8'
+    });
+    return { ok: true, output: out };
+  } catch (err) {
+    const output = [err.stderr, err.stdout, err.message]
+      .filter(Boolean).map(String).join('\n');
+    return { ok: false, output };
+  }
+}
+
+function isPostinstallMissingError(output) {
+  return typeof output === 'string' &&
+    /Bun's postinstall script was not run/i.test(output);
+}
+
+function findBunInstallJs(bunExe) {
+  // Walk up from the bun binary toward a `bun` package dir containing install.js.
+  // Matches the wrapper's own location list - bun is always nested under a
+  // `bun` package directory (or its `bin/` subdir).
+  let cursor = path.dirname(path.resolve(bunExe));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(cursor, 'install.js');
+    if (fs.existsSync(candidate) && fs.existsSync(path.join(cursor, 'package.json'))) {
+      return candidate;
+    }
+    const nested = path.join(cursor, 'bun', 'install.js');
+    if (fs.existsSync(nested)) return nested;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
 // Platform-specific spawning strategy:
 // - Windows: Use pipes for explicit handle control (prevents EBUSY errors)
 // - Unix: Use inherit for simplicity (works fine)

package/knip.json

@@ -3,7 +3,7 @@
   "entry": ["src/index.js", "bin/pglite-server.js", "bin/pgserve-wrapper.cjs"],
   "project": ["src/**/*.js", "bin/**/*.js", "bin/**/*.cjs"],
   "ignore": ["tests/**", "helpers/**", "scripts/**"],
-  "ignoreBinaries": ["scripts/test-npx.sh", "make"],
+  "ignoreBinaries": ["scripts/test-npx.sh", "scripts/test-bun-self-heal.sh", "make"],
   "ignoreDependencies": ["bun"],
   "ignoreExportsUsedInFile": true
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -19,7 +19,8 @@
     "lint:fix": "eslint src/ bin/ --fix",
     "deadcode": "knip",
     "test:npx": "scripts/test-npx.sh",
-    "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx",
+    "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"
   },
   "keywords": [

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 pglite-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 pglite-server so we can detect a successful spawn without needing
+# postgres binaries in the fixture.
+cat > "$FIXTURE/node_modules/pgserve/bin/pglite-server.js" <<'EOF'
+console.log("pglite-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 "pglite-server-spawned"; then
+  echo "✗ pglite-server was not spawned after self-heal"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ self-heal path: wrapper detected, repaired, and spawned pglite-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 "pglite-server-spawned"; then
+  echo "✗ pglite-server was not spawned on healthy path"
+  echo "$OUTPUT"
+  exit 1
+fi
+
+echo "✓ healthy path: wrapper was silent and spawned pglite-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 ==="