pgserve 2.6.0 → 2.6.1

package/bin/pgserve-wrapper.cjs

@@ -95,6 +95,35 @@ if (__subcommand === 'serve') {
   process.argv[2] = 'postmaster';
 }
 
+// B4 (v2.6.1): unknown-verb guard. Prior behavior fell through to the
+// bun probe + postgres-server.js which prints help and exits 0 on any
+// argv shape it didn't understand — that masked typos as silent
+// successes (`pgserve doctorr` → exits 0 with help banner; the operator
+// thinks doctor ran). Now we emit a clear `unknown verb` error and
+// exit EX_USAGE (64 per sysexits.h).
+//
+// Allowed shapes that MUST still flow through:
+//   - empty argv (no subcommand) → top-level help via postgres-server.js
+//   - flags starting with `-` (e.g. `--help`, `--version`) → top-level
+//     handlers in postgres-server.js
+//   - `postmaster` (canonical long-running entry) + `serve` (alias,
+//     already rewritten above)
+//   - allowlisted install-subcommands (already dispatched above; if
+//     control reaches here with one in __subcommand it means the
+//     dispatch path returned without exiting — keep the fallthrough).
+if (
+  __subcommand &&
+  !__subcommand.startsWith('-') &&
+  __subcommand !== 'postmaster' &&
+  __subcommand !== 'serve' &&
+  !__installSubcommands.has(__subcommand)
+) {
+  process.stderr.write(
+    `pgserve: unknown verb "${__subcommand}". Run \`pgserve --help\` for the supported verb list.\n`,
+  );
+  process.exit(64); // EX_USAGE per sysexits.h
+}
+
 // Detect platform
 const isWindows = process.platform === 'win32';
 const bunBin = isWindows ? 'bun.exe' : 'bun';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/src/cli-install.cjs

@@ -24,9 +24,131 @@
 const { spawnSync, execFileSync } = require('node:child_process');
 const crypto = require('node:crypto');
 const fs = require('node:fs');
+const net = require('node:net');
 const os = require('node:os');
 const path = require('node:path');
 
+// pgserve v2.6.1 — `pgserve install --help` should print usage + exit 0,
+// not run the install (B2 HIGH from QA-RECIPE-B2.md). Single source of
+// truth for the help text so the autopg + pgserve bin invocations show
+// the same surface (Decision #7 of finalize wish).
+const INSTALL_USAGE = `Usage:
+  pgserve install [options]
+  autopg install [options]
+
+Register pgserve under pm2 (Tier A supervisor) with hardened defaults.
+
+Options:
+  --port <N>            TCP port for postgres (default: 5432)
+  --data <path>         Data directory (default: ~/.autopg/data)
+  --socket-dir <path>   Unix socket directory (default: $XDG_RUNTIME_DIR/pgserve)
+  --ui-port <N>         Port for the autopg UI process (default: 8433)
+  --ui-host <host>      Bind host for the UI (default: 127.0.0.1)
+  --no-ui               Skip the autopg-ui pm2 process (headless / CI)
+  --no-pm2              Skip pm2 registration entirely (Tier B / external supervisor)
+  --help, -h            Show this help and exit
+
+Idempotent: re-running with the same args is a no-op when the existing
+admin.json + pm2 state already matches.
+
+See \`pgserve --help\` for the full verb list.
+`;
+
+function printInstallUsage(stream = process.stdout) {
+  stream.write(INSTALL_USAGE);
+}
+
+// pgserve v2.6.1 — `pgserve install` on a host where the chosen port is
+// already in use must fail BEFORE pm2 / admin.json / data-dir side
+// effects (B3 HIGH from QA-RECIPE-B3.md). Pre-flight bind-test on the
+// canonical loopback the postmaster will use; on EADDRINUSE we fail
+// fast with an operator-readable hint pointing at `--port`.
+//
+// Synchronous wrapper around net.createServer().listen() — uses
+// child_process.spawnSync via a self-bind-then-close so the install
+// flow stays synchronous. Returns null on success; throws an Error
+// with `code='EADDRINUSE'` on collision.
+async function assertPortAvailable(port, host = '127.0.0.1') {
+  // Test-only escape hatch. Production never sets this env var. Used by
+  // tests that assert on `port: 5432` literal output where the host
+  // running the test happens to have 5432 bound (dev workstations
+  // running a real pgserve). The port-pre-flight contract itself is
+  // covered end-to-end by the B3-collision test which intentionally
+  // does NOT set this env var so the pre-flight fires.
+  if (process.env.PGSERVE_TEST_SKIP_PORT_PREFLIGHT === '1') return null;
+
+  // Layer 1: connect-probe BOTH IPv4 (127.0.0.1) and IPv6 (::1).
+  // Postgres binds both loopback families on startup; any listener on
+  // either is an EADDRINUSE for the postmaster. A pure listen()-bind
+  // probe can miss this when the conflicting service was started with
+  // SO_REUSEADDR or only-one-family, so connect() is the primary check.
+  // If connect() succeeds → something is listening → port is busy.
+  for (const probeHost of [host, '::1']) {
+    const busy = await probePortListening(port, probeHost);
+    if (busy) {
+      const e = new Error(
+        `pgserve install: port ${port} is already in use on ${probeHost} (something is listening).\n` +
+        `Specify a different port with \`pgserve install --port <free>\`,\n` +
+        `or stop the process bound to ${port} first and retry.`,
+      );
+      e.code = 'EADDRINUSE';
+      throw e;
+    }
+  }
+
+  // Layer 2: bind-probe to confirm we ourselves can bind without
+  // SO_REUSEADDR conflicts. Catches the case where another process
+  // bound the same port with SO_REUSEADDR but isn't currently listening
+  // (rare but possible for transitional services).
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        const e = new Error(
+          `pgserve install: port ${port} is already in use on ${host} (EADDRINUSE).\n` +
+          `Specify a different port with \`pgserve install --port <free>\`,\n` +
+          `or stop the process bound to ${port} first and retry.`,
+        );
+        e.code = 'EADDRINUSE';
+        reject(e);
+        return;
+      }
+      // Non-EADDRINUSE errors (e.g. EACCES on privileged ports) — fail
+      // closed with the underlying message; no install side effects yet.
+      reject(err);
+    });
+    server.once('listening', () => {
+      server.close(() => resolve(null));
+    });
+    server.listen(port, host);
+  });
+}
+
+// Promise that resolves true when something is accepting connections at
+// host:port (port is busy), false on ECONNREFUSED (port is free), and
+// rejects on any other error so callers can fail closed.
+function probePortListening(port, host, timeoutMs = 500) {
+  return new Promise((resolve, reject) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (value, err) => {
+      if (settled) return;
+      settled = true;
+      try { socket.destroy(); } catch { /* best-effort */ }
+      if (err) reject(err); else resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false)); // treat slow/no-response as free
+    socket.once('error', (err) => {
+      if (err.code === 'ECONNREFUSED') return finish(false);
+      if (err.code === 'EHOSTUNREACH' || err.code === 'EADDRNOTAVAIL') return finish(false); // IPv6 not configured, etc.
+      finish(false, err);
+    });
+    socket.connect(port, host);
+  });
+}
+
 // pgserve singleton (v2.4): the cohort-shared admin-json + socket-dir
 // helpers live in `src/lib/*.js` as ESM modules (project convention: new
 // modules ship as .js / ESM). cli-install.cjs runs under node — which
@@ -693,6 +815,13 @@ function cmdAuthDispatch(args) {
  * wrapper before this module is required (avoids re-resolving here).
  */
 async function cmdInstall(args, ctx) {
+  // B2 (v2.6.1): `--help` / `-h` MUST short-circuit before any side
+  // effects (no pm2 spawn, no admin.json write, no data-dir create).
+  if (args.includes('--help') || args.includes('-h')) {
+    printInstallUsage();
+    process.exit(0);
+  }
+
   const { adminJson, socketDirMod, blockedVersions } = await loadCohortModules();
 
   // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 5.
@@ -732,6 +861,36 @@ async function cmdInstall(args, ctx) {
   }
 
   const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
+
+  // B3 (v2.6.1): pre-flight bind-test the chosen port BEFORE creating
+  // pm2 entries / admin.json / data dir. Without this, an operator on
+  // a host where 5432 is already occupied gets pm2 reporting `online`
+  // while the postmaster crashes silently — divergence between
+  // supervisor state and data-plane state. Fail fast with a clear hint.
+  try {
+    await assertPortAvailable(port);
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      process.stderr.write(`${err.message}\n`);
+      // Belt-and-suspenders for the QA loop-2/2 finding: in QA's test
+      // environment, the synchronous `process.exit(1)` path was
+      // observed to NOT terminate the process before the install
+      // function continued + resolved the wrapper's promise with
+      // undefined, which the wrapper then mapped to `process.exit(0)`.
+      // Three guarantees here:
+      //   1. process.exitCode = 1  → default exit code becomes 1 even
+      //      if explicit exit is somehow trapped/delayed
+      //   2. process.exit(1)       → force termination (preferred path)
+      //   3. throw err             → if exit is delayed, the async
+      //      function rejects, wrapper's rejection handler does its
+      //      own process.exit(1), guaranteeing non-zero exit
+      process.exitCode = 1;
+      process.exit(1);
+      throw err;
+    }
+    throw err;
+  }
+
   const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
 
   // Set up the canonical socket directory before pm2 launches the
@@ -1153,6 +1312,11 @@ function dispatch(subcommand, args, ctx) {
 module.exports = {
   // Public API for the wrapper.
   dispatch,
+  // B2 + B3: surfaced so unit tests can drive helpers without the
+  // full install side-effect chain.
+  printInstallUsage,
+  assertPortAvailable,
+  INSTALL_USAGE,
   // Auth surface used by cli-ui.cjs.
   verifyAdminPassword,
   getAdminFilePath,