pgserve 2.1.2 → 2.2.0

package/src/cli-config.cjs

@@ -0,0 +1,310 @@
+/**
+ * `autopg config` subcommand router (also reachable via `pgserve config`).
+ *
+ * Surface:
+ *   autopg config list                    - print every leaf as key|value|source
+ *   autopg config get <key>               - print the resolved value (machine-friendly)
+ *   autopg config set <key> <value>       - validate + atomic write, round-trips through get
+ *   autopg config edit                    - open $EDITOR on settings.json
+ *   autopg config path                    - print absolute path to settings.json
+ *   autopg config init [--force]          - write schema defaults; refuses to clobber
+ *
+ * Exit codes:
+ *   0 - success
+ *   1 - unknown subcommand / IO error / EDITOR not set / settings file unreadable
+ *   2 - validation error (stable shape: `error: <field> — <CODE>: <detail>`)
+ *
+ * The CLI is single-process and skips the etag round-trip — each `set` is its
+ * own transaction. Concurrency control is the UI helper's responsibility.
+ */
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+
+const { loadEffectiveConfig, getSettingsPath } = require('./settings-loader.cjs');
+const {
+  setLeaf,
+  initSettings,
+  ensureConfigDir,
+} = require('./settings-writer.cjs');
+const {
+  ValidationError,
+  validateSetting,
+  resolveKey,
+} = require('./settings-validator.cjs');
+const { SCHEMA, flattenSchema } = require('./settings-schema.cjs');
+
+const EXIT_OK = 0;
+const EXIT_UNKNOWN = 1;
+const EXIT_VALIDATION = 2;
+
+function emitError(field, code, detail) {
+  process.stderr.write(`error: ${field} — ${code}: ${detail}\n`);
+}
+
+function emitErrorFromValidation(err) {
+  emitError(err.field ?? '_root', err.code ?? 'INVALID', err.detail ?? err.message);
+}
+
+/**
+ * Resolve the current value of `key` from the merged effective config tree.
+ * Supports curated leaves (`section.field`) and `_extra` entries
+ * (`postgres._extra.<gucName>`). Returns `{ value }` or `null` when missing.
+ */
+function readValue(tree, key) {
+  if (key.startsWith('postgres._extra.')) {
+    const guc = key.slice('postgres._extra.'.length);
+    const map = tree?.postgres?._extra;
+    if (map && Object.prototype.hasOwnProperty.call(map, guc)) {
+      return { value: map[guc] };
+    }
+    return null;
+  }
+  const [section, field] = key.split('.');
+  if (!section || !field) return null;
+  const node = tree?.[section];
+  if (!node || !Object.prototype.hasOwnProperty.call(node, field)) return null;
+  return { value: node[field] };
+}
+
+/**
+ * Serialize a leaf value for human consumption. Objects (the `_extra` map
+ * descriptor) round-trip through JSON; primitives stringify directly.
+ * `null` / `undefined` render as the empty string so `autopg config get`
+ * stays scriptable.
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+/**
+ * Assemble the full set of keys to display in `config list`. Curated
+ * leaves come from the schema; `_extra` entries are expanded from the
+ * effective tree so user-added GUCs surface.
+ */
+function enumerateKeys(tree) {
+  const out = [];
+  for (const [section, fields] of Object.entries(SCHEMA)) {
+    for (const field of Object.keys(fields)) {
+      out.push(`${section}.${field}`);
+    }
+  }
+  const extras = tree?.postgres?._extra;
+  if (extras && typeof extras === 'object') {
+    for (const guc of Object.keys(extras)) {
+      out.push(`postgres._extra.${guc}`);
+    }
+  }
+  return out;
+}
+
+function pad(s, n) {
+  s = String(s);
+  if (s.length >= n) return s;
+  return s + ' '.repeat(n - s.length);
+}
+
+function cmdList() {
+  const { settings, sources } = loadEffectiveConfig();
+  const keys = enumerateKeys(settings);
+
+  // Source for `_extra` entries inherits the parent map's source. The
+  // loader doesn't break the map per-entry because env precedence
+  // applies wholesale, so we surface each row's source as the parent.
+  const rows = keys.map((key) => {
+    const valueResolved = readValue(settings, key);
+    const value = valueResolved ? formatValue(valueResolved.value) : '';
+    let source;
+    if (key.startsWith('postgres._extra.')) {
+      source = sources['postgres._extra'] || 'default';
+    } else {
+      source = sources[key] || 'default';
+    }
+    return { key, value, source };
+  });
+
+  const widths = {
+    key: Math.max(3, ...rows.map((r) => r.key.length)),
+    value: Math.max(5, ...rows.map((r) => r.value.length)),
+    source: Math.max(6, ...rows.map((r) => r.source.length)),
+  };
+
+  process.stdout.write(
+    `${pad('KEY', widths.key)}  ${pad('VALUE', widths.value)}  ${pad('SOURCE', widths.source)}\n`,
+  );
+  for (const row of rows) {
+    process.stdout.write(
+      `${pad(row.key, widths.key)}  ${pad(row.value, widths.value)}  ${pad(row.source, widths.source)}\n`,
+    );
+  }
+  return EXIT_OK;
+}
+
+function cmdGet(args) {
+  const key = args[0];
+  if (!key) {
+    emitError('_args', 'INVALID_KEY', 'config get requires a key');
+    return EXIT_VALIDATION;
+  }
+  // Validate key shape early so typos surface as INVALID_KEY rather than
+  // an empty value print.
+  try {
+    resolveKey(key);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      emitErrorFromValidation(err);
+      return EXIT_VALIDATION;
+    }
+    throw err;
+  }
+
+  const { settings } = loadEffectiveConfig();
+  const resolved = readValue(settings, key);
+  if (!resolved) {
+    process.stdout.write('\n');
+    return EXIT_OK;
+  }
+  process.stdout.write(`${formatValue(resolved.value)}\n`);
+  return EXIT_OK;
+}
+
+function cmdSet(args) {
+  if (args.length < 2) {
+    emitError('_args', 'INVALID_KEY', 'config set requires <key> <value>');
+    return EXIT_VALIDATION;
+  }
+  const [key, ...rest] = args;
+  // Allow values that contain spaces by joining the remainder. Operators
+  // can still quote the value as a single argv slot; this is the safe
+  // fallback.
+  const value = rest.join(' ');
+
+  try {
+    setLeaf(key, value);
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      emitErrorFromValidation(err);
+      return EXIT_VALIDATION;
+    }
+    throw err;
+  }
+  return EXIT_OK;
+}
+
+function cmdPath() {
+  process.stdout.write(`${getSettingsPath()}\n`);
+  return EXIT_OK;
+}
+
+function cmdInit(args) {
+  const force = args.includes('--force');
+  ensureConfigDir();
+  try {
+    initSettings({ force });
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      emitError(
+        getSettingsPath(),
+        'EEXIST',
+        'settings.json already exists; pass --force to overwrite',
+      );
+      return EXIT_VALIDATION;
+    }
+    if (err instanceof ValidationError) {
+      emitErrorFromValidation(err);
+      return EXIT_VALIDATION;
+    }
+    throw err;
+  }
+  process.stdout.write(`autopg: wrote defaults to ${getSettingsPath()}\n`);
+  return EXIT_OK;
+}
+
+/**
+ * `autopg config edit` — open the configured editor on `settings.json`,
+ * creating the file with defaults if it doesn't exist yet (so the
+ * operator gets a useful template instead of an empty buffer).
+ *
+ * Editor resolution: $VISUAL, $EDITOR, then `vi` (POSIX) / `notepad` (Windows).
+ */
+function cmdEdit() {
+  const settingsPath = getSettingsPath();
+  if (!fs.existsSync(settingsPath)) {
+    ensureConfigDir();
+    initSettings({});
+  }
+
+  const editor =
+    process.env.VISUAL ||
+    process.env.EDITOR ||
+    (process.platform === 'win32' ? 'notepad' : 'vi');
+
+  // Editors are interactive — inherit stdio so the operator gets the TUI.
+  const result = spawnSync(editor, [settingsPath], { stdio: 'inherit' });
+  if (result.error) {
+    emitError(
+      'editor',
+      'EEDITOR',
+      `failed to launch editor "${editor}": ${result.error.message}`,
+    );
+    return EXIT_UNKNOWN;
+  }
+  return result.status ?? EXIT_OK;
+}
+
+/**
+ * Subcommand dispatch. Returns the exit code; the parent dispatcher
+ * uses the return value as `process.exit(code)` directly.
+ */
+function dispatch(subcommand, args = []) {
+  switch (subcommand) {
+    case 'list':
+      return cmdList();
+    case 'get':
+      return cmdGet(args);
+    case 'set':
+      return cmdSet(args);
+    case 'path':
+      return cmdPath();
+    case 'init':
+      return cmdInit(args);
+    case 'edit':
+      return cmdEdit();
+    case undefined:
+    case '': {
+      // Bare `autopg config` → list (mirrors `git config --list` ergonomics).
+      return cmdList();
+    }
+    default:
+      emitError(subcommand, 'INVALID_KEY', `unknown config subcommand "${subcommand}"`);
+      process.stderr.write(
+        'usage: autopg config <list|get|set|edit|path|init> [args]\n',
+      );
+      return EXIT_UNKNOWN;
+  }
+}
+
+module.exports = {
+  dispatch,
+  EXIT_OK,
+  EXIT_UNKNOWN,
+  EXIT_VALIDATION,
+  // Test surface
+  _internals: {
+    cmdList,
+    cmdGet,
+    cmdSet,
+    cmdPath,
+    cmdInit,
+    cmdEdit,
+    enumerateKeys,
+    formatValue,
+    readValue,
+    flattenSchema,
+    validateSetting,
+  },
+};

package/src/cli-install.cjs

@@ -77,8 +77,22 @@ const HARDENED_DEFAULTS = {
   logDateFormat: 'YYYY-MM-DD HH:mm:ss.SSS',
 };
 
+/**
+ * Resolve the config directory. AUTOPG_CONFIG_DIR (the new var) wins,
+ * PGSERVE_CONFIG_DIR (the legacy var) is honored as a fall-through, and
+ * `~/.autopg/` is the new default. The legacy default `~/.pgserve/` is
+ * NOT consulted here — `settings-migrate.js` handles the one-shot copy.
+ *
+ * Soft-rename rule: AUTOPG_<X> beats PGSERVE_<X>. When only the legacy
+ * env is set we still honor it but the loader emits a one-time
+ * deprecation log via logger.warn (see settings-loader.js).
+ */
 function getConfigDir() {
-  return process.env.PGSERVE_CONFIG_DIR || path.join(os.homedir(), '.pgserve');
+  return (
+    process.env.AUTOPG_CONFIG_DIR ||
+    process.env.PGSERVE_CONFIG_DIR ||
+    path.join(os.homedir(), '.autopg')
+  );
 }
 
 function getConfigPath() {
@@ -139,11 +153,40 @@ function pm2IsAvailable() {
   }
 }
 
+/**
+ * Resolve the effective supervision config — start from HARDENED_DEFAULTS,
+ * overlay any values found in `~/.autopg/settings.json` `supervision`
+ * section. Failures fall through to defaults silently so `pgserve install`
+ * still works on a fresh machine before `autopg config init` has run.
+ *
+ * Precedence: defaults < settings.json < env (env wins via loadEffectiveConfig).
+ */
+function getEffectiveSupervision() {
+  try {
+    const { loadEffectiveConfig } = require('./settings-loader.cjs');
+    const { settings } = loadEffectiveConfig();
+    const sup = settings?.supervision || {};
+    return {
+      maxRestarts: sup.maxRestarts ?? HARDENED_DEFAULTS.maxRestarts,
+      minUptimeMs: sup.minUptimeMs ?? HARDENED_DEFAULTS.minUptimeMs,
+      restartDelayMs: sup.restartDelayMs ?? HARDENED_DEFAULTS.restartDelayMs,
+      expBackoffRestartDelayMs: sup.expBackoffRestartDelayMs ?? HARDENED_DEFAULTS.expBackoffRestartDelayMs,
+      expBackoffMaxMs: sup.expBackoffMaxMs ?? HARDENED_DEFAULTS.expBackoffMaxMs,
+      maxMemory: sup.maxMemory ?? HARDENED_DEFAULTS.maxMemory,
+      killTimeoutMs: sup.killTimeoutMs ?? HARDENED_DEFAULTS.killTimeoutMs,
+      logDateFormat: sup.logDateFormat ?? HARDENED_DEFAULTS.logDateFormat,
+    };
+  } catch {
+    return { ...HARDENED_DEFAULTS };
+  }
+}
+
 function buildPm2StartArgs({ scriptPath, port, dataDir }) {
   const logs = {
     out: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-out.log`),
     error: path.join(getLogsDir(), `${PM2_PROCESS_NAME}-error.log`),
   };
+  const supervision = getEffectiveSupervision();
   return [
     'start',
     scriptPath,
@@ -152,7 +195,7 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     '--interpreter',
     'none',
     '--max-restarts',
-    String(HARDENED_DEFAULTS.maxRestarts),
+    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
@@ -162,18 +205,18 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     // than only sub-`min_uptime` ones; the budget of 50 above is sized
     // accordingly.
     '--restart-delay',
-    String(HARDENED_DEFAULTS.restartDelayMs),
+    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(HARDENED_DEFAULTS.expBackoffRestartDelayMs),
+    String(supervision.expBackoffRestartDelayMs),
     '--max-memory-restart',
-    HARDENED_DEFAULTS.maxMemory,
+    supervision.maxMemory,
     '--kill-timeout',
-    String(HARDENED_DEFAULTS.killTimeoutMs),
+    String(supervision.killTimeoutMs),
     '--log-date-format',
-    HARDENED_DEFAULTS.logDateFormat,
+    supervision.logDateFormat,
     '--output',
     logs.out,
     '--error',
@@ -393,12 +436,42 @@ function parseDataDir(args) {
 }
 
 /**
- * Entry point invoked by the wrapper. Returns the exit code. Throws on
- * unknown subcommand so the wrapper's normal flow can take over (the
- * router treats any non-recognized subcommand as "pass through to the
- * postgres-server.js dispatcher").
+ * One-shot migration check from `~/.pgserve/` → `~/.autopg/`. Runs once
+ * per process at the top of dispatch() so every CLI entry point gets
+ * the cutover. Fully best-effort: any failure is swallowed (we never
+ * want migration to block an `autopg status` invocation).
+ */
+let _migrationChecked = false;
+function ensureMigrationOnce() {
+  if (_migrationChecked) return;
+  _migrationChecked = true;
+  try {
+    const { migrateIfNeeded } = require('./settings-migrate.cjs');
+    const result = migrateIfNeeded();
+    if (result.migrated) {
+      process.stderr.write(
+        `autopg: migrated ${result.legacy} → ${result.fresh} (one-time)\n`,
+      );
+    }
+  } catch {
+    // Swallow — operator can re-run migration manually if needed.
+  }
+}
+
+/**
+ * Entry point invoked by the wrapper. Returns the exit code (or a Promise
+ * for async subcommands such as `ui`). Throws on unknown subcommand so
+ * the wrapper's normal flow can take over (the router treats any
+ * non-recognized subcommand as "pass through to the postgres-server.js
+ * dispatcher").
+ *
+ * `ctx.scriptPath` is the path to `bin/postgres-server.js` (used by
+ * install for the pm2 entry point). For `restart` and `ui` we need the
+ * wrapper script path instead — `ctx.wrapperPath`. The wrapper provides
+ * both before calling dispatch.
  */
 function dispatch(subcommand, args, ctx) {
+  ensureMigrationOnce();
   switch (subcommand) {
     case 'install':
       return cmdInstall(args, ctx);
@@ -410,6 +483,19 @@ function dispatch(subcommand, args, ctx) {
       return cmdUrl();
     case 'port':
       return cmdPort();
+    case 'config': {
+      const cfg = require('./cli-config.cjs');
+      const [sub, ...rest] = args;
+      return cfg.dispatch(sub, rest);
+    }
+    case 'restart': {
+      const restart = require('./cli-restart.cjs');
+      return restart.dispatch(args, { scriptPath: ctx.wrapperPath });
+    }
+    case 'ui': {
+      const ui = require('./cli-ui.cjs');
+      return ui.dispatch(args, { scriptPath: ctx.wrapperPath });
+    }
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }
@@ -430,6 +516,7 @@ module.exports = {
     readConfig,
     writeConfig,
     buildPm2StartArgs,
+    getEffectiveSupervision,
     parsePort,
     parseDataDir,
   },

package/src/cli-restart.cjs

@@ -0,0 +1,228 @@
+/**
+ * `autopg restart` (also reachable via `pgserve restart`).
+ *
+ * Behavior:
+ *   - If pm2 is supervising the `pgserve` process → `pm2 restart pgserve`.
+ *     This is the production path: pm2 owns the lifecycle, sending it a
+ *     restart bumps the supervised counter and respects the hardened
+ *     defaults registered at install time.
+ *   - Otherwise → read the daemon's pidfile, SIGTERM, wait for exit, then
+ *     respawn via `bin/pgserve-wrapper.cjs daemon`. Detached so the
+ *     respawn outlives this CLI process.
+ *
+ * Exit codes:
+ *   0 - restart issued (pm2 path) or respawn started (local path)
+ *   1 - pm2 restart failed, or respawn could not start, or the daemon
+ *       didn't honor SIGTERM within the timeout
+ *
+ * Why pm2 wins when present: a supervised process restarted via the local
+ * SIGTERM path would race pm2's own restart loop and double-fire (pm2
+ * relaunches as soon as it sees the exit, then we relaunch again). The
+ * pm2 jlist probe is the authoritative gate.
+ */
+
+'use strict';
+
+const { spawnSync, spawn, execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PM2_PROCESS_NAME = 'pgserve';
+const SIGTERM_TIMEOUT_MS = 10_000;
+const POLL_INTERVAL_MS = 100;
+
+/**
+ * Mirror of `resolvePidLockPath` from src/daemon.js (ESM). Inlined here
+ * because cli-restart.cjs is CJS and we don't want to pull in dynamic
+ * import for a 3-line path resolver. The two MUST stay in sync.
+ */
+function resolveControlSocketDir() {
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  const base = xdg && xdg.length > 0 ? xdg : '/tmp';
+  return path.join(base, 'pgserve');
+}
+
+function resolvePidLockPath() {
+  return path.join(resolveControlSocketDir(), 'pgserve.pid');
+}
+
+/**
+ * `pm2 jlist` probe. Returns the registered process object or null.
+ * Mirrors cli-install's helper but runs without the install ctx —
+ * we don't need anything other than the process name.
+ */
+function pm2GetProcess(name = PM2_PROCESS_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;
+  }
+}
+
+function pm2IsAvailable() {
+  try {
+    execFileSync('pm2', ['--version'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPid(pidPath) {
+  if (!fs.existsSync(pidPath)) return null;
+  try {
+    const raw = fs.readFileSync(pidPath, 'utf8').trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Synchronously wait until the pidfile is gone (the daemon's graceful
+ * shutdown path removes it). We don't also require !isAlive because the
+ * pid may briefly be a zombie until the parent reaps it — the pidfile
+ * being absent is the daemon's "I'm clean" signal, matching the existing
+ * `pgserve daemon stop` flow in src/daemon.js.
+ */
+function waitForExit(pid, pidPath, timeoutMs = SIGTERM_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!fs.existsSync(pidPath)) return true;
+    sleepBlocking(POLL_INTERVAL_MS);
+  }
+  return false;
+}
+
+function sleepBlocking(ms) {
+  // Atomics.wait is a portable blocking sleep — node 16+ supports it on
+  // a SharedArrayBuffer-backed Int32Array. No Bun dependency.
+  try {
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    Atomics.wait(ia, 0, 0, ms);
+  } catch {
+    // Fall back to a busy spin on platforms that don't allow Atomics.wait
+    // on the main thread (rare). Acceptable here — only invoked at most
+    // once per ~100ms inside a CLI command.
+    const end = Date.now() + ms;
+    while (Date.now() < end) { /* spin */ }
+  }
+}
+
+function fail(message) {
+  process.stderr.write(`autopg: ${message}\n`);
+  return 1;
+}
+
+function ok(message) {
+  process.stdout.write(`autopg: ${message}\n`);
+  return 0;
+}
+
+/**
+ * Pm2-supervised path. `pm2 restart pgserve` is the canonical operator
+ * action — pm2 increments its own restart counter and respects all the
+ * hardening flags registered at install time.
+ */
+function restartViaPm2() {
+  const result = spawnSync('pm2', ['restart', PM2_PROCESS_NAME], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+  });
+  if (result.status !== 0) {
+    return fail(`pm2 restart failed (exit ${result.status})`);
+  }
+  return ok(`restarted via pm2 (process "${PM2_PROCESS_NAME}")`);
+}
+
+/**
+ * Local-respawn path. Reads the daemon pidfile, SIGTERMs, waits, then
+ * respawns the daemon detached so it survives this CLI process exiting.
+ *
+ * `scriptPath` is the path to bin/pgserve-wrapper.cjs (resolved by the
+ * dispatcher's ctx so the test surface can inject a stub binary).
+ */
+function restartLocally({ scriptPath, env = process.env } = {}) {
+  const pidPath = resolvePidLockPath();
+  const pid = readPid(pidPath);
+
+  if (pid && isAlive(pid)) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch (err) {
+      return fail(`failed to signal pid ${pid}: ${err.message}`);
+    }
+    if (!waitForExit(pid, pidPath)) {
+      return fail(`pid ${pid} did not exit within ${SIGTERM_TIMEOUT_MS}ms`);
+    }
+  }
+
+  if (!scriptPath || !fs.existsSync(scriptPath)) {
+    return fail(`cannot respawn: wrapper script not found at ${scriptPath}`);
+  }
+
+  // Spawn detached so the daemon outlives this CLI.
+  const child = spawn(process.execPath, [scriptPath, 'daemon'], {
+    detached: true,
+    stdio: 'ignore',
+    env,
+  });
+  child.unref();
+
+  return ok(`respawned daemon (pid ${child.pid})`);
+}
+
+/**
+ * Entry point. `ctx.scriptPath` is the path to `bin/pgserve-wrapper.cjs`
+ * (so the local respawn can re-enter the wrapper to start the daemon).
+ *
+ * `ctx.pm2IsAvailable` and `ctx.pm2GetProcess` are dependency-injection
+ * hooks for tests — production callers omit them and the module-level
+ * helpers (which shell out to the real `pm2` binary) are used.
+ */
+function dispatch(_args = [], ctx = {}) {
+  const isAvailable = ctx.pm2IsAvailable || pm2IsAvailable;
+  const getProcess = ctx.pm2GetProcess || pm2GetProcess;
+  const restartFn = ctx.restartViaPm2 || restartViaPm2;
+  if (isAvailable() && getProcess(PM2_PROCESS_NAME)) {
+    return restartFn();
+  }
+  return restartLocally({ scriptPath: ctx.scriptPath });
+}
+
+module.exports = {
+  dispatch,
+  // Test surface
+  _internals: {
+    pm2GetProcess,
+    pm2IsAvailable,
+    readPid,
+    isAlive,
+    waitForExit,
+    resolvePidLockPath,
+    restartViaPm2,
+    restartLocally,
+    PM2_PROCESS_NAME,
+    SIGTERM_TIMEOUT_MS,
+  },
+};