pgserve 2.3.0 → 2.5.0

package/src/cosign/verify-binary.js

@@ -0,0 +1,277 @@
+/**
+ * Cosign keyless OIDC binary verifier.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Per Decision P5 (locked), we shell out to the `cosign` CLI rather than
+ * vendoring sigstore-rs. Verification model:
+ *
+ *   - Each binary distributed by an automagik release ships with a
+ *     paired Sigstore bundle file at `<binary>.bundle` (modern keyless
+ *     OIDC attestation, JSON-encoded).
+ *   - We invoke `cosign verify-blob --bundle <bundle>
+ *     --certificate-identity-regexp <re> --certificate-oidc-issuer <iss>
+ *     <binary>` — once per entry in the trust list.
+ *   - First entry that exits 0 wins. We return its identity + tier.
+ *   - If every entry fails, we surface the most-specific cosign diagnostic
+ *     (the last exit) so the operator knows which trust root we tried.
+ *
+ * Resolution of the cosign executable:
+ *   1. Caller-supplied `cosignBin` (used by tests + `--cosign-bin` flag)
+ *   2. `cosign` on `$PATH`
+ *   3. Cached static binary at `~/.pgserve/bin/cosign`
+ *   4. Download official static binary from sigstore release (offline by
+ *      default — only triggered when `allowFetch: true` is passed)
+ *
+ * Returns a tagged union:
+ *   { ok: true,  identity, tier, sha256, cosignBin, bundle }
+ *   { ok: false, reason, detail?, identityChain? }
+ */
+
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { TRUSTED_IDENTITIES } from './trust-list.js';
+
+export const COSIGN_TIER = 'cosign_signed';
+export const COSIGN_BIN_DIR = path.join(os.homedir(), '.pgserve', 'bin');
+export const COSIGN_BIN_FILE = path.join(COSIGN_BIN_DIR, process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+
+const COSIGN_RELEASE_VERSION = 'v2.2.4';
+const COSIGN_RELEASE_BASE = `https://github.com/sigstore/cosign/releases/download/${COSIGN_RELEASE_VERSION}`;
+
+/**
+ * Compute sha256 of a file. Returns lowercase hex.
+ */
+export function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  const buf = fs.readFileSync(filePath);
+  hash.update(buf);
+  return hash.digest('hex');
+}
+
+/**
+ * Resolve the sidecar bundle path for a given binary path. Convention:
+ * `<binary>.bundle`. Operators that publish detached `.sig` + `.cert` can
+ * regenerate a bundle with `cosign sign-blob --bundle <path>.bundle`; we
+ * intentionally only support the bundle form to keep the surface narrow.
+ */
+export function resolveBundlePath(binaryPath) {
+  return `${binaryPath}.bundle`;
+}
+
+/**
+ * Resolve which `cosign` executable to use. Returns a string path or null
+ * if no cosign is available and `allowFetch: false`.
+ *
+ * PATH probing is implemented in-process (rather than shelling out to
+ * `which` / `where`) so the resolver works inside test harnesses that
+ * scrub PATH down to a single stub directory.
+ */
+export function resolveCosignBin({ cosignBin, allowFetch = false } = {}) {
+  if (cosignBin && fs.existsSync(cosignBin)) return cosignBin;
+
+  const fromPath = lookupOnPath(process.platform === 'win32' ? 'cosign.exe' : 'cosign');
+  if (fromPath) return fromPath;
+
+  // Cached static binary.
+  if (fs.existsSync(COSIGN_BIN_FILE)) return COSIGN_BIN_FILE;
+
+  if (!allowFetch) return null;
+
+  try {
+    return fetchCosignBin();
+  } catch {
+    return null;
+  }
+}
+
+function lookupOnPath(name) {
+  const PATH = process.env.PATH || '';
+  if (!PATH) return null;
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const dirs = PATH.split(sep).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, name);
+    try {
+      const stat = fs.statSync(candidate);
+      if (stat.isFile()) {
+        // On POSIX, ensure it's executable; on Windows, file existence is enough.
+        if (process.platform === 'win32') return candidate;
+        if ((stat.mode & 0o111) !== 0) return candidate;
+      }
+    } catch {
+      // missing or stat error — try next dir
+    }
+  }
+  return null;
+}
+
+/**
+ * Download the official cosign static binary into `~/.pgserve/bin/cosign`.
+ * Synchronous — used by `pgserve verify` when no cosign is on PATH and the
+ * operator opts into the fetch (see Decision P5: "if cosign not on PATH,
+ * pgserve install shells out to a downloader to fetch the official static
+ * binary into ~/.pgserve/bin/cosign").
+ *
+ * Network-dependent. Throws on failure. Tests stub via `cosignBin` instead
+ * of this code path.
+ */
+export function fetchCosignBin({
+  releaseBase = COSIGN_RELEASE_BASE,
+  targetFile = COSIGN_BIN_FILE,
+  targetDir = COSIGN_BIN_DIR,
+} = {}) {
+  fs.mkdirSync(targetDir, { recursive: true, mode: 0o755 });
+  const assetName = pickCosignAssetName();
+  const url = `${releaseBase}/${assetName}`;
+  const tmp = `${targetFile}.tmp.${process.pid}`;
+  downloadToFileSync(url, tmp);
+  fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, targetFile);
+  return targetFile;
+}
+
+function pickCosignAssetName() {
+  const arch = process.arch === 'x64' ? 'amd64' : process.arch === 'arm64' ? 'arm64' : process.arch;
+  if (process.platform === 'darwin') return `cosign-darwin-${arch}`;
+  if (process.platform === 'win32') return `cosign-windows-${arch}.exe`;
+  return `cosign-linux-${arch}`;
+}
+
+function downloadToFileSync(url, destPath) {
+  // Node has no built-in synchronous HTTP. We fall back to spawning curl
+  // since this only runs once per host (cached afterward) and curl is
+  // ubiquitous on the supported platforms.
+  const curl = spawnSync('curl', ['-fsSL', '-o', destPath, url], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (curl.status === 0) return;
+  // Fallback: try wget.
+  const wget = spawnSync('wget', ['-qO', destPath, url], { stdio: ['ignore', 'pipe', 'pipe'] });
+  if (wget.status === 0) return;
+  throw new Error(
+    `cosign-verify: failed to download cosign from ${url} (curl exit ${curl.status}, wget exit ${wget?.status ?? 'n/a'})`,
+  );
+}
+
+/**
+ * Verify a binary with cosign.
+ *
+ * @param {string} binaryPath
+ * @param {object} [options]
+ * @param {string} [options.cosignBin]   override cosign executable
+ * @param {string} [options.bundlePath]  override bundle sidecar path
+ * @param {Array}  [options.trustList]   override hardcoded TRUSTED_IDENTITIES
+ * @param {boolean}[options.allowFetch]  allow fetching the cosign binary if missing
+ * @returns {{ ok: true, identity, tier, sha256, cosignBin, bundle, identityChain }
+ *         | { ok: false, reason, detail?, identityChain? }}
+ */
+export function verifyBinary(binaryPath, options = {}) {
+  if (typeof binaryPath !== 'string' || binaryPath.length === 0) {
+    return { ok: false, reason: 'invalid-args', detail: 'binaryPath required' };
+  }
+  if (!fs.existsSync(binaryPath)) {
+    return { ok: false, reason: 'binary-missing', detail: binaryPath };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(binaryPath);
+  } catch (err) {
+    return { ok: false, reason: 'binary-unreadable', detail: err.message };
+  }
+  if (!stat.isFile()) {
+    return { ok: false, reason: 'binary-not-a-file', detail: binaryPath };
+  }
+
+  const bundlePath = options.bundlePath || resolveBundlePath(binaryPath);
+  if (!fs.existsSync(bundlePath)) {
+    return {
+      ok: false,
+      reason: 'bundle-missing',
+      detail: `expected sigstore bundle at ${bundlePath} (run \`cosign sign-blob --bundle ${bundlePath} ${binaryPath}\` to attest)`,
+    };
+  }
+
+  const trustList = options.trustList || TRUSTED_IDENTITIES;
+  if (!Array.isArray(trustList) || trustList.length === 0) {
+    return { ok: false, reason: 'empty-trust-list' };
+  }
+
+  const cosignBin = resolveCosignBin({
+    cosignBin: options.cosignBin,
+    allowFetch: options.allowFetch === true,
+  });
+  if (!cosignBin) {
+    return {
+      ok: false,
+      reason: 'cosign-missing',
+      detail:
+        'no `cosign` binary on $PATH or in ~/.pgserve/bin/cosign — install cosign or rerun with --allow-fetch',
+    };
+  }
+
+  const sha256 = sha256File(binaryPath);
+  const identityChain = [];
+  let lastFailure = null;
+
+  for (const identity of trustList) {
+    if (!identity || !identity.id || !identity.issuer || !identity.identityRegexp) {
+      identityChain.push({ id: identity?.id || '<malformed>', status: 'skipped' });
+      continue;
+    }
+    const result = invokeCosign({
+      cosignBin,
+      bundlePath,
+      binaryPath,
+      identity,
+    });
+    if (result.ok) {
+      identityChain.push({ id: identity.id, status: 'matched' });
+      return {
+        ok: true,
+        identity: identity.id,
+        publisher: identity.publisher,
+        tier: COSIGN_TIER,
+        sha256,
+        cosignBin,
+        bundle: bundlePath,
+        identityChain,
+      };
+    }
+    identityChain.push({ id: identity.id, status: 'rejected', exitCode: result.exitCode });
+    lastFailure = result;
+  }
+
+  return {
+    ok: false,
+    reason: 'no-trust-match',
+    detail: lastFailure?.stderr || 'cosign rejected the binary against every trust root',
+    identityChain,
+  };
+}
+
+function invokeCosign({ cosignBin, bundlePath, binaryPath, identity }) {
+  const args = [
+    'verify-blob',
+    '--bundle', bundlePath,
+    '--certificate-identity-regexp', identity.identityRegexp,
+    '--certificate-oidc-issuer', identity.issuer,
+    binaryPath,
+  ];
+  const proc = spawnSync(cosignBin, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (proc.status === 0) {
+    return { ok: true, stdout: proc.stdout || '' };
+  }
+  return {
+    ok: false,
+    exitCode: typeof proc.status === 'number' ? proc.status : -1,
+    stderr: (proc.stderr || proc.stdout || '').trim().slice(0, 4096),
+  };
+}

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;
+}