pgserve 2.5.0 → 2.6.1

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
@@ -35,14 +157,32 @@ const path = require('node:path');
 const _adminJsonModuleP = import('./lib/admin-json.js');
 const _socketDirModuleP = import('./lib/socket-dir.js');
 const _runtimeJsonModuleP = import('./lib/runtime-json.js');
+const _blockedVersionsModuleP = import('./security/blocked-versions.js');
 
 async function loadCohortModules() {
-  const [adminJson, socketDirMod, runtimeJson] = await Promise.all([
+  const [adminJson, socketDirMod, runtimeJson, blockedVersions] = await Promise.all([
     _adminJsonModuleP,
     _socketDirModuleP,
     _runtimeJsonModuleP,
+    _blockedVersionsModuleP,
   ]);
-  return { adminJson, socketDirMod, runtimeJson };
+  return { adminJson, socketDirMod, runtimeJson, blockedVersions };
+}
+
+// pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 5.
+//
+// Resolves the running pgserve version from package.json so `assertNotBlocked`
+// can compare against the compile-time BLOCKED_VERSIONS list before any
+// install/update mutation. We intentionally use the package.json shipped
+// with this binary (`require.resolve` from inside cli-install.cjs) rather
+// than the version on the host filesystem — we want to refuse THIS binary
+// running, not a different binary that might happen to live next door.
+function getCurrentVersion() {
+  try {
+    return require('../package.json').version;
+  } catch (_e) {
+    return undefined;
+  }
 }
 
 // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
@@ -675,7 +815,32 @@ function cmdAuthDispatch(args) {
  * wrapper before this module is required (avoids re-resolving here).
  */
 async function cmdInstall(args, ctx) {
-  const { adminJson, socketDirMod } = await loadCohortModules();
+  // 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.
+  // Refuse to install if THIS binary's version appears in the compile-time
+  // blocklist. Runs first (before any host-touching work) so the operator
+  // sees a clear `EBLOCKEDVERSION:` diagnostic with the locked reason +
+  // remediation hint, exit code 4 (distinct from generic install failures).
+  const currentVersion = getCurrentVersion();
+  if (currentVersion) {
+    try {
+      blockedVersions.assertNotBlocked(currentVersion);
+    } catch (err) {
+      if (err.code === 'EBLOCKEDVERSION') {
+        process.stderr.write(`${err.message}\n`);
+        process.exit(4);
+      }
+      throw err;
+    }
+  }
 
   // pgserve singleton (v2.4): refuse to install if a different supervisor
   // (Tier B systemd-user / launchd) already owns the host. The cohort
@@ -696,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
@@ -1041,6 +1236,12 @@ function dispatch(subcommand, args, ctx) {
       // dispatcher. dispatch() returns a Promise here; the wrapper
       // already handles both numeric and Promise returns.
       return import('./commands/uninstall.js').then((mod) => mod.runUninstall());
+    case 'doctor':
+      // pgserve-singleton-no-proxy Group 3: read-only V1. Reports the
+      // active supervisor + postmaster reachability + admin.json /
+      // runtime.json health. --fix tiered modes deferred to a follow-up
+      // (SHARED-DESIGN §3.2).
+      return import('./commands/doctor.js').then((mod) => mod.runDoctor(args).then((code) => process.exit(code)));
     case 'status':
       return cmdStatus(args);
     case 'url':
@@ -1083,6 +1284,26 @@ function dispatch(subcommand, args, ctx) {
       // as `uninstall` so the ESM module isn't eagerly loaded.
       return import('./commands/verify.js').then((mod) => mod.runVerify(args));
     }
+    case 'trust':
+      // pgserve singleton (v2.4) — wish Group 3, second read-only verb.
+      // `pgserve trust add/list/remove` manages the user-extensible cosign
+      // trust store at ~/.pgserve/trust/identities.json. Pure node.
+      // The wrapper handles the numeric-exit-code case; matches the
+      // verify dispatch style so the wrapper, not the verb, owns
+      // process.exit.
+      return import('./commands/trust.js').then((mod) => mod.runTrust(args));
+    case 'gc':
+      // pgserve singleton (v2.4) — wish Group 3, verb 3. `pgserve gc`
+      // sweeps orphaned databases. Default mode is dry-run; --apply
+      // performs the actual DROP. Composes the orphan classifier +
+      // audit-log writer + psql shellout primitives.
+      return import('./commands/gc.js').then((mod) => mod.runGc(args));
+    case 'provision':
+      // pgserve singleton (v2.4) — wish Group 3, verb 4. Idempotent
+      // CREATE ROLE / DATABASE / GRANT + UPSERT pgserve_meta. Honest
+      // idempotency-driven serialization (see provision.js header for
+      // why no advisory lock). Pure node + psql shellout.
+      return import('./commands/provision.js').then((mod) => mod.runProvision(args));
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }
@@ -1091,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,