pgserve 2.3.0 → 2.4.0

package/src/commands/uninstall.js

@@ -0,0 +1,241 @@
+/**
+ * `autopg uninstall` — Tier A teardown of the rootless pm2 supervisor.
+ *
+ * Group 1 of the canonical-pgserve-pm2-supervision wish. Idempotent.
+ *
+ * Removes:
+ *   - pm2 entry `autopg-server` (the postmaster, registered by `autopg install`)
+ *   - pm2 entry `autopg-ui`     (the console SPA, registered by `autopg install`)
+ *   - the supervisor record in `~/.autopg/admin.json` (the four supervisor
+ *     fields managed by `src/lib/admin-json.js` — preserves the scrypt
+ *     Basic-Auth scheme so a re-install can keep the same admin password).
+ *
+ * Preserves:
+ *   - the data directory under `~/.autopg/data/`
+ *   - `~/.autopg/config.json`
+ *   - `admin.json` auth fields (scheme/salt/hash/createdAt/rotatedAt/...)
+ *
+ * Writes one JSONL audit-log entry to `<configDir>/audit.log`.
+ *
+ * Idempotent contract: running uninstall twice in a row is a no-op on the
+ * second call. After uninstall, a subsequent `autopg install` succeeds
+ * without a Tier-B-refusal false positive — `assertSupervisor` treats a
+ * missing supervisor field as "host is free to install".
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  ADMIN_FILE_MODE,
+  getAdminFilePath,
+  readAdminJson,
+} from '../lib/admin-json.js';
+
+export const TIER_A_PM2_PROCESSES = Object.freeze(['autopg-server', 'autopg-ui']);
+export const SUPERVISOR_FIELDS = Object.freeze([
+  'supervisor',
+  'socketDir',
+  'port',
+  'installedAt',
+]);
+
+function getConfigDir() {
+  return (
+    process.env.AUTOPG_CONFIG_DIR
+    || process.env.PGSERVE_CONFIG_DIR
+    || path.join(os.homedir(), '.autopg')
+  );
+}
+
+function pm2IsAvailable() {
+  try {
+    execFileSync('pm2', ['--version'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function pm2GetProcess(name) {
+  try {
+    const out = execFileSync('pm2', ['jlist'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const list = JSON.parse(out);
+    return list.find((p) => p && p.name === name) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Always-attempt pm2 delete. `pm2 delete <missing>` exits non-zero but the
+ * call is idempotent server-side, so any non-zero exit is treated as
+ * "already absent" rather than a hard failure. We snapshot pm2 jlist
+ * BEFORE the delete to report whether the entry actually existed.
+ */
+function tearDownPm2(name) {
+  if (!pm2IsAvailable()) {
+    return { name, removed: false, status: 'pm2-missing' };
+  }
+  const before = pm2GetProcess(name);
+  const res = spawnSync('pm2', ['delete', name], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 10_000,
+  });
+  if (res.status === 0) {
+    return {
+      name,
+      removed: !!before,
+      status: before ? 'removed' : 'already-absent',
+    };
+  }
+  return {
+    name,
+    removed: false,
+    status: 'already-absent',
+    exitCode: res.status,
+  };
+}
+
+/**
+ * Atomically clear the supervisor fields from admin.json. Preserves all
+ * other fields (notably the scrypt Basic-Auth scheme written by
+ * `cli-install.cjs`'s `writeAdminFile`). Removes the file entirely if
+ * clearing leaves an empty object.
+ *
+ * Returns { changed, file, hadSupervisor }.
+ */
+function clearSupervisorRecord(configDir) {
+  const file = getAdminFilePath(configDir);
+  const existing = readAdminJson({ configDir });
+  if (!existing) {
+    return { changed: false, file, hadSupervisor: false };
+  }
+  const hadSupervisor = SUPERVISOR_FIELDS.some((k) => k in existing);
+  if (!hadSupervisor) {
+    return { changed: false, file, hadSupervisor: false };
+  }
+  const cleared = { ...existing };
+  for (const field of SUPERVISOR_FIELDS) {
+    delete cleared[field];
+  }
+  if (Object.keys(cleared).length === 0) {
+    try {
+      fs.unlinkSync(file);
+    } catch (err) {
+      if (err && err.code !== 'ENOENT') throw err;
+    }
+    return { changed: true, file, hadSupervisor: true };
+  }
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(cleared, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: ADMIN_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, ADMIN_FILE_MODE);
+  return { changed: true, file, hadSupervisor: true };
+}
+
+function appendAuditLog(configDir, payload) {
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+  const file = path.join(configDir, 'audit.log');
+  const record = {
+    ts: new Date().toISOString(),
+    event: 'autopg_uninstall',
+    ...payload,
+  };
+  fs.appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+
+function emit(level, msg, silent) {
+  if (silent) return;
+  const stream = level === 'err' ? process.stderr : process.stdout;
+  stream.write(`autopg: ${msg}\n`);
+}
+
+/**
+ * Run the uninstall flow. Returns a numeric exit code.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.configDir] — override the autopg config dir (used
+ *   by tests; production code should leave this undefined and let env vars
+ *   resolve).
+ * @param {boolean} [opts.silent] — suppress stdout/stderr writes.
+ */
+export function runUninstall(opts = {}) {
+  const configDir = opts.configDir || getConfigDir();
+  const silent = opts.silent === true;
+
+  const pm2Available = pm2IsAvailable();
+  if (!pm2Available) {
+    emit(
+      'err',
+      'pm2 not found in PATH; skipping pm2 teardown (admin.json supervisor record will still be cleared).',
+      silent,
+    );
+  }
+
+  const pm2Results = TIER_A_PM2_PROCESSES.map((name) => tearDownPm2(name));
+
+  let supervisorClear;
+  try {
+    supervisorClear = clearSupervisorRecord(configDir);
+  } catch (err) {
+    emit('err', `failed to clear supervisor record in admin.json: ${err.message}`, silent);
+    return 1;
+  }
+
+  try {
+    appendAuditLog(configDir, {
+      pm2Available,
+      pm2: pm2Results,
+      supervisorRecord: {
+        changed: supervisorClear.changed,
+        hadSupervisor: supervisorClear.hadSupervisor,
+        file: supervisorClear.file,
+      },
+    });
+  } catch {
+    // Audit must never break uninstall.
+  }
+
+  const removed = pm2Results.filter((r) => r.removed).map((r) => r.name);
+  const absent = pm2Results.filter((r) => r.status === 'already-absent').map((r) => r.name);
+
+  if (removed.length === 0 && !supervisorClear.changed) {
+    emit(
+      'out',
+      `not registered under pm2 (${TIER_A_PM2_PROCESSES.join(', ')}); nothing to uninstall`,
+      silent,
+    );
+    return 0;
+  }
+
+  if (removed.length > 0) {
+    emit(
+      'out',
+      `uninstalled pm2 entries: ${removed.join(', ')} (data dir preserved at ${path.join(configDir, 'data')})`,
+      silent,
+    );
+  }
+  if (absent.length > 0 && removed.length > 0) {
+    emit('out', `(already absent: ${absent.join(', ')})`, silent);
+  }
+  if (supervisorClear.changed) {
+    emit('out', `cleared supervisor record from ${supervisorClear.file}`, silent);
+  } else if (removed.length > 0) {
+    emit('out', `no supervisor record to clear in ${supervisorClear.file}`, silent);
+  }
+  return 0;
+}

package/src/index.js

@@ -1,49 +1,16 @@
 /**
- * pgserve - Embedded PostgreSQL Server
+ * pgserve — Embedded PostgreSQL Server (singleton, v2.4+)
  *
- * True concurrent connections, zero config, auto-provision databases.
- * Uses embedded-postgres (real PostgreSQL binaries).
+ * Public surface after the `pgserve-singleton-no-proxy` Group 2 deletion:
+ * the bun proxy data plane, daemon control socket, libpq protocol
+ * rewriting, and SO_PEERCRED handshake are gone. Operators interact with
+ * pgserve through the CLI (`bin/pgserve-wrapper.cjs`), the postmaster
+ * subcommand (`bin/postgres-server.js postmaster`), and the cohort-shared
+ * helpers under `src/lib/`.
+ *
+ * `PostgresManager` is exported for tests and integrators that want to
+ * embed a postgres instance programmatically — it is the same class the
+ * postmaster subcommand instantiates.
  */
 
-// Main exports
-export { MultiTenantRouter, startMultiTenantServer } from './router.js';
 export { PostgresManager } from './postgres.js';
-export { SyncManager } from './sync.js';
-export { RestoreManager } from './restore.js';
-export { Dashboard } from './dashboard.js';
-export { StatsCollector } from './stats-collector.js';
-export { StatsDashboard } from './stats-dashboard.js';
-export {
-  PgserveDaemon,
-  startDaemon,
-  stopDaemon,
-  resolveControlSocketDir,
-  resolveControlSocketPath,
-  resolvePidLockPath,
-  resolveLibpqCompatPath,
-  acquirePidLock,
-  isProcessAlive,
-} from './daemon.js';
-export {
-  buildDaemonArgs,
-  daemonClientOptions,
-  ensureDaemon,
-  probeDaemon,
-  resolveBundledCliBin,
-} from './sdk.js';
-export {
-  derivePackageFingerprint,
-  deriveScriptFingerprint,
-  fingerprintFromCred,
-  findNearestPackageJson,
-  readPackageName,
-  readPersistFlag,
-} from './fingerprint.js';
-export {
-  hashToken,
-  mintToken,
-  parseTcpAuth,
-} from './tokens.js';
-
-// Default export
-export { startMultiTenantServer as default } from './router.js';

package/src/lib/admin-json.js

@@ -0,0 +1,202 @@
+/**
+ * `~/.autopg/admin.json` reader, atomic writer, and supervisor-assertion.
+ *
+ * Cohort-shared module — co-owned with `canonical-pgserve-pm2-supervision`
+ * Group 1. Schema for the supervisor record:
+ *
+ *     {
+ *       supervisor: "pm2" | "systemd-user" | "launchd" | "external",
+ *       socketDir:  "<absolute path>",
+ *       port:       <integer>,
+ *       installedAt: "<ISO 8601 timestamp>"
+ *     }
+ *
+ * The file is shared with the Basic-Auth scrypt password record used by the
+ * autopg console UI (`scheme`/`salt`/`hash`/...). This module merges with
+ * any pre-existing fields it does not own — `writeAdminJson` is additive,
+ * never destructive — so both tenants coexist on the same file.
+ *
+ * Hard contract — refuses to downgrade supervision authority:
+ *   - If the existing file records `systemd-user` or `launchd`, refuses to
+ *     write `pm2` or `external`. Operators must `autopg service uninstall`
+ *     first to migrate Tier B → Tier A.
+ *   - `assertSupervisor(expected)` throws when the actual supervisor differs
+ *     so callers fail fast with a structured remediation hint.
+ *
+ * Atomic semantics: write to `<file>.tmp.<pid>`, fsync, then
+ * `fs.renameSync` to the target. mode 0600 enforced via `fs.chmodSync`
+ * after write.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const ADMIN_FILE_NAME = 'admin.json';
+export const ADMIN_FILE_MODE = 0o600;
+
+export const SUPERVISOR_VALUES = Object.freeze([
+  'pm2',
+  'systemd-user',
+  'launchd',
+  'external',
+]);
+
+/** Supervisors that own the postmaster lifecycle via an OS service unit. */
+const TIER_B_SUPERVISORS = new Set(['systemd-user', 'launchd']);
+
+/**
+ * Resolve the autopg config directory.
+ *
+ * Honors `AUTOPG_CONFIG_DIR` (current var) first, then `PGSERVE_CONFIG_DIR`
+ * (legacy soft-rename), then `$HOME/.autopg`. Mirrors the precedence in
+ * `src/cli-install.cjs` and `src/settings-loader.cjs`.
+ */
+export function getDefaultConfigDir() {
+  return (
+    process.env.AUTOPG_CONFIG_DIR
+    || process.env.PGSERVE_CONFIG_DIR
+    || path.join(os.homedir(), '.autopg')
+  );
+}
+
+export function getAdminFilePath(configDir = getDefaultConfigDir()) {
+  return path.join(configDir, ADMIN_FILE_NAME);
+}
+
+function ensureConfigDir(configDir) {
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Read the admin.json record. Returns the parsed object on success, `null`
+ * when the file is missing or unreadable. Never throws — callers treat
+ * "missing" and "broken" identically.
+ */
+export function readAdminJson({ configDir = getDefaultConfigDir() } = {}) {
+  const file = getAdminFilePath(configDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function validateSupervisorRecord(record) {
+  if (!isPlainObject(record)) {
+    throw new TypeError('admin-json: record must be an object');
+  }
+  if (!SUPERVISOR_VALUES.includes(record.supervisor)) {
+    throw new TypeError(
+      `admin-json: invalid supervisor "${record.supervisor}". `
+      + `Expected one of: ${SUPERVISOR_VALUES.join(', ')}`,
+    );
+  }
+  if (typeof record.socketDir !== 'string' || record.socketDir.length === 0) {
+    throw new TypeError('admin-json: socketDir must be a non-empty string');
+  }
+  if (!Number.isInteger(record.port) || record.port < 1 || record.port > 65535) {
+    throw new TypeError(`admin-json: port must be an integer in [1, 65535]; got ${record.port}`);
+  }
+  if (typeof record.installedAt !== 'string' || record.installedAt.length === 0) {
+    throw new TypeError('admin-json: installedAt must be a non-empty ISO 8601 string');
+  }
+}
+
+/**
+ * Atomic merge-write of the supervisor record.
+ *
+ * Reads any existing admin.json, layers the supplied supervisor fields on
+ * top (preserving unrelated fields like the scrypt Basic-Auth scheme), and
+ * writes the result via tmp+rename with mode 0600.
+ *
+ * Refuses with a structured error when the existing record names a Tier B
+ * supervisor (`systemd-user` / `launchd`) and the incoming record would
+ * downgrade authority. Use `autopg service uninstall` to migrate Tier B →
+ * Tier A explicitly.
+ */
+export function writeAdminJson(record, { configDir = getDefaultConfigDir() } = {}) {
+  validateSupervisorRecord(record);
+
+  ensureConfigDir(configDir);
+  const file = getAdminFilePath(configDir);
+  const existing = readAdminJson({ configDir }) ?? {};
+
+  if (
+    TIER_B_SUPERVISORS.has(existing.supervisor)
+    && existing.supervisor !== record.supervisor
+  ) {
+    const err = new Error(
+      `pgserve: refusing to overwrite admin.json — existing supervisor is `
+      + `"${existing.supervisor}" (Tier B); cannot register "${record.supervisor}". `
+      + `Run \`autopg service uninstall\` first to migrate to Tier A.`,
+    );
+    err.code = 'EADMINSUPERVISORLOCK';
+    err.existingSupervisor = existing.supervisor;
+    err.requestedSupervisor = record.supervisor;
+    throw err;
+  }
+
+  const merged = {
+    ...existing,
+    supervisor: record.supervisor,
+    socketDir: record.socketDir,
+    port: record.port,
+    installedAt: record.installedAt,
+  };
+
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(merged, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: ADMIN_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, ADMIN_FILE_MODE);
+
+  return merged;
+}
+
+/**
+ * Throw when the on-disk supervisor differs from `expected`. Returns the
+ * record on match. Used by callers that must refuse to operate when the
+ * host has already been claimed by a different supervisor — e.g.
+ * `pgserve install` (Tier A) refusing to run on a Tier B host.
+ *
+ * Missing file is NOT an error here — there's nothing to assert against.
+ * The caller should treat "no record" as "free to install".
+ */
+export function assertSupervisor(expected, { configDir = getDefaultConfigDir() } = {}) {
+  if (!SUPERVISOR_VALUES.includes(expected)) {
+    throw new TypeError(
+      `admin-json: invalid expected supervisor "${expected}". `
+      + `Expected one of: ${SUPERVISOR_VALUES.join(', ')}`,
+    );
+  }
+  const existing = readAdminJson({ configDir });
+  if (!existing || !existing.supervisor) return null;
+  if (existing.supervisor !== expected) {
+    const err = new Error(
+      `pgserve: admin.json supervisor mismatch — expected "${expected}", `
+      + `found "${existing.supervisor}". `
+      + `${TIER_B_SUPERVISORS.has(existing.supervisor)
+          ? 'Run `autopg service uninstall` to migrate to Tier A.'
+          : 'Run `pgserve uninstall` to clear the existing record.'}`,
+    );
+    err.code = 'EADMINSUPERVISORMISMATCH';
+    err.expected = expected;
+    err.actual = existing.supervisor;
+    throw err;
+  }
+  return existing;
+}

package/src/lib/pm2-args.js

@@ -0,0 +1,119 @@
+/**
+ * Cohort-shared pm2 launch builder for the canonical-pgserve-pm2-supervision
+ * wish (Group 1).
+ *
+ * Exports:
+ *   PM2_HARDENED_DEFAULTS — baseline hardening values pinned in the wish
+ *   SERVICE_MEMORY_LIMITS — per-service maxMemoryRestart map
+ *   buildPm2StartArgs(serviceName, opts) — factory returning the argv passed
+ *     to `pm2 ...`
+ *
+ * Per Decision 3 of the wish, the constants stay duplicated across
+ * `autopg`, `genie`, and `omni` rather than introducing a shared package —
+ * the values are pinned here and copied verbatim into the genie + omni
+ * installers.
+ *
+ * Note on the autopg daemon (`autopg-server`): its own pm2 args are still
+ * built inside `src/cli-install.cjs` with a higher restart budget and a
+ * larger memory ceiling, because postgres specifics demand more headroom
+ * (see PR #57 review notes). The values exported here are the cohort
+ * baseline used by the companion `autopg-ui` process and by the cross-repo
+ * services (`genie-serve`, `omni-api`, `omni-nats`).
+ */
+
+import path from 'node:path';
+
+export const PM2_HARDENED_DEFAULTS = Object.freeze({
+  maxRestarts: 10,
+  restartDelayMs: 5000,
+  killTimeoutMs: 20000,
+  logDateFormat: 'YYYY-MM-DD HH:mm:ss.SSS',
+  // pm2 launches both genie and omni binaries via `#!/usr/bin/env bun`
+  // shebangs. `--interpreter bun` triggers pm2's ESM/require crash on
+  // top-level await; shebang resolution side-steps the issue.
+  // Empirically validated 2026-04-30 (Decision 4 of the wish).
+  interpreter: 'none',
+});
+
+export const SERVICE_MEMORY_LIMITS = Object.freeze({
+  'autopg-server': '2G',
+  'autopg-ui': '256M',
+  'genie-serve': '2G',
+  'omni-api': '2G',
+  'omni-nats': '1G',
+});
+
+export const DEFAULT_MAX_MEMORY = '2G';
+
+const VALID_SERVICE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+/**
+ * Resolve the maxMemoryRestart string for a service. Honors caller override
+ * first, then SERVICE_MEMORY_LIMITS, then DEFAULT_MAX_MEMORY.
+ */
+export function resolveMaxMemory(serviceName, override) {
+  if (override) return override;
+  return SERVICE_MEMORY_LIMITS[serviceName] || DEFAULT_MAX_MEMORY;
+}
+
+/**
+ * Build the argv to register a long-lived service under pm2.
+ *
+ * @param {string} serviceName — pm2 process name (also used in default log
+ *   filenames). Must match `^[A-Za-z][A-Za-z0-9_-]{0,63}$`.
+ * @param {object} opts
+ * @param {string} opts.scriptPath — script pm2 invokes
+ * @param {string} opts.logsDir — directory for `<name>-out.log` /
+ *   `<name>-error.log`
+ * @param {string[]} [opts.scriptArgs] — args passed after `--` to the script
+ * @param {string} [opts.maxMemoryRestart] — override the per-service default
+ *   (e.g. `4G` on big-iron hosts)
+ * @param {object} [opts.overrides] — override individual hardening values
+ *   (`maxRestarts`, `restartDelayMs`, `killTimeoutMs`, `logDateFormat`,
+ *   `interpreter`)
+ * @returns {string[]} args to pass to `pm2`
+ */
+export function buildPm2StartArgs(serviceName, opts) {
+  if (typeof serviceName !== 'string' || !VALID_SERVICE_NAME.test(serviceName)) {
+    throw new TypeError(
+      `pm2-args: serviceName must match /^[A-Za-z][A-Za-z0-9_-]{0,63}$/; got ${JSON.stringify(serviceName)}`,
+    );
+  }
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('pm2-args: opts is required');
+  }
+  if (typeof opts.scriptPath !== 'string' || opts.scriptPath.length === 0) {
+    throw new TypeError('pm2-args: opts.scriptPath must be a non-empty string');
+  }
+  if (typeof opts.logsDir !== 'string' || opts.logsDir.length === 0) {
+    throw new TypeError('pm2-args: opts.logsDir must be a non-empty string');
+  }
+
+  const overrides = opts.overrides || {};
+  const maxRestarts = overrides.maxRestarts ?? PM2_HARDENED_DEFAULTS.maxRestarts;
+  const restartDelayMs = overrides.restartDelayMs ?? PM2_HARDENED_DEFAULTS.restartDelayMs;
+  const killTimeoutMs = overrides.killTimeoutMs ?? PM2_HARDENED_DEFAULTS.killTimeoutMs;
+  const logDateFormat = overrides.logDateFormat ?? PM2_HARDENED_DEFAULTS.logDateFormat;
+  const interpreter = overrides.interpreter ?? PM2_HARDENED_DEFAULTS.interpreter;
+  const maxMemoryRestart = resolveMaxMemory(serviceName, opts.maxMemoryRestart);
+
+  const argv = [
+    'start',
+    opts.scriptPath,
+    '--name', serviceName,
+    '--interpreter', interpreter,
+    '--max-restarts', String(maxRestarts),
+    '--restart-delay', String(restartDelayMs),
+    '--max-memory-restart', maxMemoryRestart,
+    '--kill-timeout', String(killTimeoutMs),
+    '--log-date-format', logDateFormat,
+    '--output', path.join(opts.logsDir, `${serviceName}-out.log`),
+    '--error', path.join(opts.logsDir, `${serviceName}-error.log`),
+  ];
+
+  const scriptArgs = Array.isArray(opts.scriptArgs) ? opts.scriptArgs : [];
+  if (scriptArgs.length > 0) {
+    argv.push('--', ...scriptArgs);
+  }
+  return argv;
+}

package/src/lib/socket-dir.js

@@ -0,0 +1,69 @@
+/**
+ * Canonical pgserve socket-dir resolver.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
+ *
+ * Postgres backend listens on a Unix socket inside this directory plus TCP
+ * 5432. The directory is also where `pgserve` records its `.s.PGSQL.<port>`
+ * socket file so off-the-shelf libpq clients connecting via
+ * `psql -h <socketDir>` (no `-p`) succeed against the systemd / freedesktop
+ * convention path. CI runners and minimal containers without
+ * `$XDG_RUNTIME_DIR` get `/tmp/pgserve` as the documented fallback.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const SOCKET_DIR_NAME = 'pgserve';
+export const SOCKET_DIR_MODE = 0o700;
+
+/**
+ * Resolve the canonical socket directory.
+ *
+ * Preferred: `$XDG_RUNTIME_DIR/pgserve` (systemd / freedesktop convention).
+ * Fallback: `/tmp/pgserve` (CI runners and minimal containers without XDG).
+ *
+ * Pure function — does not touch the filesystem. Use `ensureSocketDir()`
+ * to create the directory with the correct permissions.
+ */
+export function resolveSocketDir() {
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  const base = xdg && xdg.length > 0 ? xdg : '/tmp';
+  return path.join(base, SOCKET_DIR_NAME);
+}
+
+/**
+ * Ensure the socket directory exists with mode 0700 and is writable.
+ *
+ * Returns the resolved path. Throws if the directory exists but is not a
+ * directory, or if creation fails for any reason other than EEXIST.
+ *
+ * The mode is enforced via fs.chmodSync after creation — `mkdirSync(mode)`
+ * is honored only when the directory does not already exist.
+ */
+export function ensureSocketDir(dir = resolveSocketDir()) {
+  fs.mkdirSync(dir, { recursive: true, mode: SOCKET_DIR_MODE });
+  fs.chmodSync(dir, SOCKET_DIR_MODE);
+
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) {
+    throw new Error(
+      `pgserve: socket dir path exists but is not a directory: ${dir}`,
+    );
+  }
+
+  // Validate writability by touching a sentinel file. Avoids surfacing the
+  // real-world failure ("postgres can't bind socket") at the postmaster
+  // boot step where the diagnostic is much harder to trace.
+  const probe = path.join(dir, `.writable-${process.pid}-${Date.now()}`);
+  try {
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+  } catch (err) {
+    throw new Error(
+      `pgserve: socket dir not writable (${dir}): ${err.message}`,
+    );
+  }
+
+  return dir;
+}