pgserve 2.3.0 → 2.4.0

package/config/logrotate.d/pgserve

@@ -0,0 +1,47 @@
+# pgserve singleton (v2.4) — logrotate config for the pm2 / systemd-user
+# / launchd-supervised postmaster.
+#
+# Postgres' stderr (where pgaudit's audit log lands when the .so is
+# present, and `log_statement=all` lands in the fallback path) is captured
+# by the supervisor and written to:
+#
+#   ~/.autopg/logs/autopg-server-out.log
+#   ~/.autopg/logs/autopg-server-error.log
+#
+# Symbolic ~/ resolves under each operator's HOME — logrotate runs the
+# rules per-user when invoked with `--state ~/.config/logrotate.state`
+# (see the autopg installer hint). The `su` directive is intentionally
+# absent: this config ships as a USER-context drop-in, not a system one.
+# System-wide rotation under a dedicated `autopg` UNIX user is delivered
+# by the separate `autopg-service-install-system` wish (out of scope for
+# v2.4).
+#
+# Copy or symlink to:   /etc/logrotate.d/pgserve  (system-wide)
+# Or use per-user:      ~/.config/logrotate.d/pgserve
+
+~/.autopg/logs/autopg-server-out.log
+~/.autopg/logs/autopg-server-error.log
+~/.pgserve/audit.log
+{
+    # Daily rotation keeps audit/forensic events queryable for ~2 weeks
+    # without burning disk on a long-running dev host.
+    daily
+    rotate 14
+    # Compress yesterday's log on tomorrow's rotation so today's log stays
+    # uncompressed for tail/grep.
+    compress
+    delaycompress
+    # Don't fail when a log file has not been created yet (e.g. fresh
+    # `autopg install` before the postmaster has emitted any output).
+    missingok
+    # Don't fail when a log file is empty.
+    notifempty
+    # Truncate-in-place so pm2 / systemd / launchd's open file handles
+    # keep writing to the rotated file. Avoids the "send SIGHUP and
+    # postgres re-opens" dance which we don't want to trigger from a
+    # supervisor-agnostic rule.
+    copytruncate
+    # File mode 0600: audit lines may include literal SQL (parameter
+    # values, error contexts) — operator-only on a multi-user host.
+    create 0600
+}

package/config/pgaudit.conf

@@ -0,0 +1,31 @@
+# pgserve singleton (v2.4) — pgaudit GUC defaults.
+#
+# Loaded by `src/postgres.js::_startPostgres` when the embedded postgres
+# bundle ships pgaudit.so. The postmaster passes these as `-c key=value`
+# pairs at boot; settings.json `_extra` overrides apply on top via the
+# normal curated < extra precedence.
+#
+# When pgaudit.so is NOT present in the bundle (the current state of the
+# `@embedded-postgres/<plat>-<arch>` packages), postgres.js falls back to
+# `log_statement=all`. The cohort sibling `autopg-distribution-cutover`
+# owns shipping the pgaudit binary; this file documents the GUCs that
+# light up the moment the .so lands.
+
+shared_preload_libraries = 'pgaudit'
+
+# `pgaudit.log = 'all'` is the audit-log breadth contract from the wish.
+# Operators who need a tighter classification (e.g. drop READ to cut log
+# volume on hot read paths) override via:
+#   ~/.autopg/settings.json -> postgres._extra.pgaudit.log = 'write,role,ddl'
+pgaudit.log = 'all'
+
+# Skip pg_catalog reads — they are constant per session and their
+# inclusion floods the audit log without forensic value.
+pgaudit.log_catalog = off
+
+# Audit lines emit on the postmaster's stderr, captured by the supervisor
+# (pm2 -> ~/.autopg/logs/autopg-server-error.log; systemd-user -> journal;
+# launchd -> launchd-managed plist log path). The legacy
+# ~/.pgserve/audit.log path stays rotated by `config/logrotate.d/pgserve`
+# so existing tooling parsing the file keeps working through the
+# migration window.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,6 +11,7 @@
   "files": [
     "bin/",
     "src/",
+    "config/",
     "console/dist/",
     "README.md",
     "CHANGELOG.md",
@@ -19,7 +20,6 @@
     "scripts/"
   ],
   "scripts": {
-    "bench": "bun tests/benchmarks/runner.js",
     "test": "bun test tests/**/*.test.js",
     "test:watch": "bun test --watch tests/**/*.test.js",
     "dev": "bun --watch bin/postgres-server.js",

package/scripts/test-npx.sh

@@ -1,10 +1,15 @@
 #!/bin/bash
 # Test that the package works with npx (simulates fresh user install)
-# This catches path resolution issues that static analysis can't detect
+# This catches path resolution issues that static analysis can't detect.
+#
+# v2.4 contract change (2026-05-08): `pgserve` (no args) now prints help and
+# exits cleanly. The long-running entry is `pgserve postmaster` (or its
+# `pgserve serve` alias). This test invokes the postmaster directly to verify
+# npx-installed bits boot a real PG.
 
 set -e
 
-echo "=== Testing npx compatibility ==="
+echo "=== Testing npx compatibility (v2.4 postmaster entry) ==="
 
 # Create temp directory
 TEST_DIR=$(mktemp -d)
@@ -29,22 +34,39 @@ 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 &
+# Verify the bare invocation prints v2.4 help and exits 0 (regression guard
+# for the breaking-cut: pre-v2.4 auto-started a server here).
+echo "Verifying bare 'npx pgserve' prints v2.4 help and exits cleanly..."
+HELP_OUT=$(npx pgserve 2>&1)
+if ! echo "$HELP_OUT" | grep -q "pgserve postmaster"; then
+  echo "✗ Bare 'npx pgserve' output does not match v2.4 help (missing 'pgserve postmaster')"
+  echo "Output:"
+  echo "$HELP_OUT"
+  echo "=== npx test FAILED ==="
+  exit 1
+fi
+echo "✓ Bare invocation prints v2.4 help"
+
+# Test that the postmaster entry starts (with timeout)
+DATA_DIR="$TEST_DIR/data"
+SOCKET_DIR="$TEST_DIR/sock"
+mkdir -p "$DATA_DIR" "$SOCKET_DIR"
+echo "Testing postmaster startup via npx (port 15432)..."
+timeout 30 npx pgserve postmaster --port 15432 --data "$DATA_DIR" --socket-dir "$SOCKET_DIR" > output.log 2>&1 &
 PID=$!
 
-# Wait for ready signal (Server started successfully!)
+# Wait for ready signal — bin/postgres-server.js logs
+# 'pgserve postmaster: ready (Unix socket + TCP)' once both transports are bound.
 for i in {1..60}; do
-  if grep -q "Server started successfully" output.log 2>/dev/null; then
-    echo "✓ Server started successfully via npx"
+  if grep -q "pgserve postmaster: ready" output.log 2>/dev/null; then
+    echo "✓ Postmaster 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"
+    echo "✗ Postmaster exited unexpectedly"
     cat output.log
     echo "=== npx test FAILED ==="
     exit 1
@@ -54,7 +76,7 @@ done
 
 # Timeout
 kill $PID 2>/dev/null || true
-echo "✗ Server did not start within timeout"
+echo "✗ Postmaster did not start within timeout"
 cat output.log
 echo "=== npx test FAILED ==="
 exit 1

package/src/cli-install.cjs

@@ -27,8 +27,37 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const PM2_PROCESS_NAME = 'pgserve';
-const DEFAULT_PORT = 8432;
+// 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
+// cannot synchronously `require()` ESM — so we cache the dynamic-import
+// promise once at module load and await it from async install paths.
+const _adminJsonModuleP = import('./lib/admin-json.js');
+const _socketDirModuleP = import('./lib/socket-dir.js');
+
+async function loadCohortModules() {
+  const [adminJson, socketDirMod] = await Promise.all([_adminJsonModuleP, _socketDirModuleP]);
+  return { adminJson, socketDirMod };
+}
+
+// pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
+//
+// The pm2 entry name moves from `pgserve` to `autopg-server` so the canonical
+// two-process layout matches the cohort design (`autopg-server` + `autopg-ui`).
+// Tier B operators install a systemd-user unit that ALSO claims the
+// `autopg-server` lifecycle role — `~/.autopg/admin.json` records which
+// supervisor owns the host and `pgserve install` refuses to register pm2 over
+// an existing Tier B record.
+//
+// Default postgres port moves from 8432 (the old bun-proxy listener) to 5432
+// (the postgres standard, since the postmaster now binds TCP directly).
+const PM2_PROCESS_NAME = 'autopg-server';
+// Legacy entry name (pre-v2.4). Self-healing migration in Group 6 will
+// `pm2 delete pgserve` after registering `autopg-server`; we surface the
+// constant here so cleanup tooling and tests can reference it without
+// hardcoding strings.
+const LEGACY_PM2_PROCESS_NAME = 'pgserve';
+const DEFAULT_PORT = 5432;
 
 // Console UI is auto-supervised under pm2 alongside the daemon since v2.2.3.
 // The bundled SPA (console/dist/) is served on this port; operator-facing
@@ -200,7 +229,7 @@ function getEffectiveSupervision() {
   }
 }
 
-function buildPm2StartArgs({ scriptPath, port, dataDir }) {
+function buildPm2StartArgs({ scriptPath, port, dataDir, socketDir }) {
   const logs = {
     out: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-out.log`),
     error: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-error.log`),
@@ -215,19 +244,11 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     'none',
     '--max-restarts',
     String(supervision.maxRestarts),
-    // NOTE: pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — passing
-    // it produces `error: unknown option --min-uptime` and aborts the
-    // install. The flag still works inside an ecosystem file, but per the
-    // canonical-pm2-supervision wish we keep `pgserve install` as a pure
-    // CLI flow (no extra files for operators to manage). The trade-off is
-    // that `--max-restarts` now counts every restart (rapid or not) rather
-    // than only sub-`min_uptime` ones; the budget of 50 above is sized
-    // accordingly.
+    // pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — passing it
+    // aborts the install. Restart budget (50) is sized to absorb a few
+    // long-uptime crashes without burning through.
     '--restart-delay',
     String(supervision.restartDelayMs),
-    // Exponential backoff between successive failures: starts at 100ms,
-    // doubles each crash, ramps to ~60s. Avoids hammering pm2 + the host
-    // when the underlying issue is persistent.
     '--exp-backoff-restart-delay',
     String(supervision.expBackoffRestartDelayMs),
     '--max-memory-restart',
@@ -241,28 +262,19 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     '--error',
     logs.error,
     '--',
-    // Foreground multi-tenant mode (`pgserve [options]`), NOT daemon mode.
-    //
-    // Daemon mode binds a unix control socket and requires libpq peers to
-    // authenticate via a fingerprint+token handshake (`pgserve daemon
-    // issue-token`). Downstream services that connect with a plain
-    // `postgres://` URL (omni, genie, anything that doesn't speak the
-    // fingerprint protocol) cannot reach a daemon-mode listener. We also
-    // observed live: `pgserve install` was passing `--port` to the daemon
-    // parser, which only accepts `--data | --ram | --log | --no-provision
-    // | --listen | --pgvector` — every install attempt crashed with
-    // `Unknown daemon option: --port` and pm2 burned its restart budget.
-    //
-    // Foreground mode (the default `pgserve [options]` invocation in
-    // postgres-server.js) accepts `--port`, auto-provisions databases on
-    // first connect, runs the cluster on multi-core hosts, and binds TCP
-    // on `127.0.0.1:<port>` with no auth dance — exactly what canonical
-    // pgserve consumers expect. Pass the same flags pgserve already
-    // documents in its own `pgserve --help` output.
+    // pgserve singleton (v2.4): pm2 supervises the postmaster directly via
+    // the `pgserve postmaster` subcommand — no router, no bun proxy, no
+    // daemon control socket. Postgres binds the canonical Unix socket
+    // under <socketDir> AND TCP <port> natively. Operators connect via
+    //   psql -h $XDG_RUNTIME_DIR/pgserve     (Unix socket, no -p)
+    //   psql -h 127.0.0.1 -p 5432            (canonical TCP)
+    'postmaster',
     '--port',
     String(port),
     '--data',
     dataDir,
+    '--socket-dir',
+    socketDir,
     '--log',
     'warn',
   ];
@@ -384,21 +396,9 @@ function cmdInstallUi(ctx, options = {}) {
   return 0;
 }
 
-function cmdUninstallUi() {
-  if (!pm2IsAvailable()) return 0;
-  // Always attempt the delete — `pm2 delete <name>` is idempotent and
-  // exits non-zero on a missing process, which is fine to swallow. This
-  // is more robust than a pre-existence check against `pm2 jlist`, which
-  // can lag the actual process state (or, in test stubs, return a
-  // partial registry).
-  const result = spawnSync('pm2', ['delete', UI_PM2_PROCESS_NAME], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  if (result.status === 0) {
-    ok(`UI uninstalled (pm2 process "${UI_PM2_PROCESS_NAME}" removed)`);
-  }
-  return 0;
-}
+// `cmdUninstall` + `cmdUninstallUi` migrated to `src/commands/uninstall.js`
+// as part of canonical-pgserve-pm2-supervision Group 1. The dispatch
+// `case 'uninstall'` above dynamically imports the new module.
 
 // ─── Admin password (Basic Auth for `autopg ui`) ─────────────────────────
 
@@ -429,12 +429,19 @@ function writeAdminFile({ password, rotated = false }) {
   const hash = hashAdminPassword(password, salt);
   const file = getAdminFilePath();
   const now = new Date().toISOString();
+  // pgserve singleton (v2.4): admin.json is shared with the supervisor
+  // record (`{ supervisor, socketDir, port, installedAt }`) written by
+  // `src/lib/admin-json.js`. Merge with any existing fields so the scrypt
+  // Basic-Auth scheme can never wipe the supervisor metadata (and vice
+  // versa).
+  const existing = readAdminFile() || {};
   const payload = {
+    ...existing,
     scheme: 'scrypt',
     params: SCRYPT_PARAMS,
     salt: salt.toString('base64'),
     hash: hash.toString('base64'),
-    createdAt: rotated ? readAdminFile()?.createdAt ?? now : now,
+    createdAt: rotated ? existing.createdAt ?? now : now,
     rotatedAt: rotated ? now : null,
   };
   ensureConfigDir();
@@ -487,9 +494,14 @@ function verifyAdminPassword(candidate) {
 
 function ensureAdminPassword({ rotate = false } = {}) {
   const existing = readAdminFile();
-  if (existing && !rotate) return null;
+  // pgserve singleton (v2.4): admin.json may exist with only supervisor
+  // fields (`{ supervisor, socketDir, port, installedAt }`) and no scrypt
+  // scheme yet. Treat "no scrypt scheme" as "no password" so the install
+  // path still mints one on first run.
+  const hasScryptScheme = !!(existing && existing.scheme === 'scrypt');
+  if (hasScryptScheme && !rotate) return null;
   const password = generateAdminPassword();
-  writeAdminFile({ password, rotated: !!existing });
+  writeAdminFile({ password, rotated: !!hasScryptScheme });
   return password;
 }
 
@@ -532,14 +544,41 @@ function cmdAuthDispatch(args) {
  * `scriptPath` is the path to `bin/postgres-server.js` resolved by the
  * wrapper before this module is required (avoids re-resolving here).
  */
-function cmdInstall(args, ctx) {
-  if (!pm2IsAvailable()) {
-    fail('pm2 not found in PATH. Install with: bun add -g pm2  (or npm i -g pm2)');
+async function cmdInstall(args, ctx) {
+  const { adminJson, socketDirMod } = await loadCohortModules();
+
+  // pgserve singleton (v2.4): refuse to install if a different supervisor
+  // (Tier B systemd-user / launchd) already owns the host. The cohort
+  // contract guarantees one and only one supervisor records itself in
+  // `~/.autopg/admin.json`. `pgserve install` is the Tier A (pm2) entry —
+  // it asserts that nothing else has already claimed the host before
+  // touching pm2.
+  const noPm2 = args.includes('--no-pm2');
+  const expectedSupervisor = noPm2 ? 'external' : 'pm2';
+  try {
+    adminJson.assertSupervisor(expectedSupervisor, { configDir: getConfigDir() });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  if (!noPm2 && !pm2IsAvailable()) {
+    fail('pm2 not found in PATH. Install with: bun add -g pm2  (or npm i -g pm2). Pass --no-pm2 for CI / Tier B-bound hosts.');
   }
 
   const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
   const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
 
+  // Set up the canonical socket directory before pm2 launches the
+  // postmaster. `ensureSocketDir` enforces mode 0700 and probes writability
+  // so failure surfaces here — not as a libpq bind error a few seconds
+  // into pm2 backoff.
+  const socketDir = parseSocketDir(args) ?? socketDirMod.resolveSocketDir();
+  try {
+    socketDirMod.ensureSocketDir(socketDir);
+  } catch (err) {
+    fail(err.message);
+  }
+
   const noUi = args.includes('--no-ui');
   const withUi = args.includes('--with-ui');
   const redeploy = args.includes('--redeploy');
@@ -559,6 +598,22 @@ function cmdInstall(args, ctx) {
     return 0;
   }
 
+  // --no-pm2: skip pm2 register entirely. Used by CI fixture provisioning
+  // (no sudo, no pm2 ambient state) and by Tier B-bound hosts that will
+  // immediately hand off to `autopg service install`. Still record the
+  // supervisor + canonical socket dir + port in admin.json so downstream
+  // tooling (pgserve doctor, omni install, genie install) can discover
+  // where to connect without an active pm2 entry.
+  if (noPm2) {
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    writeSupervisorRecord(adminJson, { supervisor: 'external', socketDir, port });
+    ok(`installed (--no-pm2): supervisor=external, socketDir=${socketDir}, port=${port}`);
+    ok(`url: postgres://localhost:${port}/postgres`);
+    note(`--no-pm2: pm2 register skipped. Start the postmaster manually with \`pgserve postmaster --port ${port} --data ${dataDir} --socket-dir ${socketDir}\` or hand off to systemd-user / launchd.`);
+    return 0;
+  }
+
   // --redeploy: full reset. Tear down both processes, then proceed with
   // a fresh install. Equivalent to `autopg uninstall && autopg install`
   // but in one verb.
@@ -581,6 +636,7 @@ function cmdInstall(args, ctx) {
     // don't tear down the live process. Operators wanting a port change
     // should `uninstall` then `install` (or pass --redeploy).
     writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    writeSupervisorRecord(adminJson, { supervisor: 'pm2', socketDir, port });
     if (!noUi) cmdInstallUi(ctx, { uiPort, uiHost });
     return 0;
   }
@@ -588,14 +644,15 @@ function cmdInstall(args, ctx) {
   ensureLogsDir();
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
 
-  const pm2Args = buildPm2StartArgs({ scriptPath: ctx.scriptPath, port, dataDir });
+  const pm2Args = buildPm2StartArgs({ scriptPath: ctx.scriptPath, port, dataDir, socketDir });
   const result = spawnSync('pm2', pm2Args, { stdio: 'inherit' });
   if (result.status !== 0) {
     fail(`pm2 start failed (exit ${result.status}). Logs: ${getLogsDir()}/${PM2_PROCESS_NAME}-error.log`);
   }
 
   writeConfig({ port, dataDir, registeredAt: new Date().toISOString() });
-  ok(`installed: pm2 process "${PM2_PROCESS_NAME}" on port ${port} (data: ${dataDir})`);
+  writeSupervisorRecord(adminJson, { supervisor: 'pm2', socketDir, port });
+  ok(`installed: pm2 process "${PM2_PROCESS_NAME}" on port ${port} (socket: ${socketDir}, data: ${dataDir})`);
   ok(`url: postgres://localhost:${port}/postgres`);
 
   if (noUi) {
@@ -620,29 +677,28 @@ function cmdInstall(args, ctx) {
 }
 
 /**
- * `pgserve uninstall`
- *
- * Removes pgserve from pm2. Leaves the data directory and config file
- * intact — operator can `rm -rf ~/.pgserve` after they're satisfied no
- * downstream service still depends on the data.
+ * Persist the supervisor record into `~/.autopg/admin.json`. Wraps
+ * `writeAdminJson` from the cohort-shared module so the install path can
+ * pin its own ISO timestamp + log a friendly diagnostic on the
+ * supervisor-lock refusal.
  */
-function cmdUninstall() {
-  // Delete the daemon first — it's the load-bearing process and the order
-  // of "what existed at uninstall start" is determined by the daemon's
-  // pm2 registry, not the UI's. UI cleanup follows; soft-fails if absent.
-  const existing = pm2GetProcess(PM2_PROCESS_NAME);
-  if (!existing) {
-    ok(`not registered under pm2 (nothing to uninstall)`);
-    cmdUninstallUi();
-    return 0;
-  }
-  const result = spawnSync('pm2', ['delete', PM2_PROCESS_NAME], { stdio: 'inherit' });
-  if (result.status !== 0) {
-    fail(`pm2 delete failed (exit ${result.status})`);
+function writeSupervisorRecord(adminJson, { supervisor, socketDir, port }) {
+  try {
+    adminJson.writeAdminJson(
+      {
+        supervisor,
+        socketDir,
+        port,
+        installedAt: new Date().toISOString(),
+      },
+      { configDir: getConfigDir() },
+    );
+  } catch (err) {
+    // The "Tier B already owns this host" error is the contract failure
+    // we surface to operators. Other errors (EACCES, ENOSPC, etc.) just
+    // pass through with their stock message.
+    fail(err.message);
   }
-  ok(`uninstalled (pm2 process removed; data dir preserved at ${getDataDir()})`);
-  cmdUninstallUi();
-  return 0;
 }
 
 /**
@@ -747,6 +803,14 @@ function parseDataDir(args) {
   return path.resolve(v);
 }
 
+function parseSocketDir(args) {
+  const i = args.indexOf('--socket-dir');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--socket-dir requires a value');
+  return path.resolve(v);
+}
+
 function parseUiPort(args) {
   const i = args.indexOf('--ui-port');
   if (i < 0) return null;
@@ -807,7 +871,13 @@ function dispatch(subcommand, args, ctx) {
     case 'install':
       return cmdInstall(args, ctx);
     case 'uninstall':
-      return cmdUninstall();
+      // canonical-pgserve-pm2-supervision Group 1: the uninstall surface
+      // moved to `src/commands/uninstall.js` so the cohort baseline (pm2
+      // teardown + admin.json supervisor clear + audit-log entry) lives
+      // alongside `src/lib/pm2-args.js` instead of inside this legacy
+      // 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 'status':
       return cmdStatus(args);
     case 'url':