rollbridge 0.1.5 → 0.1.6

package/test/config-validation.test.js

@@ -126,6 +126,175 @@ test("validateConfig defaults the restart policy, accepts overrides, and rejects
   assert.ok(validateRestart({maxRestarts: 1.5}).issues.some((issue) => issue.message === "processes[0].restart.maxRestarts must be a non-negative integer"))
 })
 
+test("validateConfig defaults lifecycle, accepts hooks, and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} lifecycle - Lifecycle config under test, or undefined.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateLifecycle = (lifecycle) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", lifecycle, policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  // Omitted → no commands, zero drain.
+  assert.deepEqual(validateLifecycle(undefined).config.processes[0].lifecycle, {drainTimeoutMs: 0})
+
+  const custom = validateLifecycle({drainTimeoutMs: 30000, quietCommand: "kill -TSTP $ROLLBRIDGE_PID", stopCommand: "kill -TERM $ROLLBRIDGE_PID"})
+
+  assert.deepEqual(custom.issues, [])
+  assert.equal(custom.config.processes[0].lifecycle.quietCommand, "kill -TSTP $ROLLBRIDGE_PID")
+  assert.equal(custom.config.processes[0].lifecycle.stopCommand, "kill -TERM $ROLLBRIDGE_PID")
+  assert.equal(custom.config.processes[0].lifecycle.drainTimeoutMs, 30000)
+
+  const invalid = validateLifecycle({drainTimeoutMs: -1, quietCommand: 5})
+  const messages = invalid.issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("processes[0].lifecycle.drainTimeoutMs must be a non-negative number"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].lifecycle.quietCommand must be a string"), JSON.stringify(messages))
+
+  // drainCommand needs a positive drainTimeoutMs to bound it; otherwise the drain step is skipped.
+  assert.ok(validateLifecycle({drainCommand: "drain"}).issues
+    .some((issue) => issue.message === "processes[0].lifecycle.drainCommand requires a positive processes[0].lifecycle.drainTimeoutMs"))
+  assert.deepEqual(validateLifecycle({drainCommand: "drain", drainTimeoutMs: 1000}).issues, [])
+
+  // A stopCommand replaces stopSignal, so a stopCommand alongside the default SIGTERM is fine.
+  assert.deepEqual(validateLifecycle({stopCommand: "kill -TERM $ROLLBRIDGE_PID"}).issues, [])
+})
+
+test("validateConfig rejects a custom stopSignal alongside a stopCommand that would ignore it", () => {
+  /**
+   * @param {Record<string, import("../src/json.js").JsonValue>} overrides - Extra fields merged onto the worker process.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateWorker = (overrides) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}, {command: "run worker", id: "worker", policy: "companion", ...overrides}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  // A custom stopSignal with a stopCommand is contradictory: stopCommand runs instead of the signal.
+  assert.ok(validateWorker({lifecycle: {stopCommand: "kill -TERM $ROLLBRIDGE_PID"}, stopSignal: "SIGINT"}).issues
+    .some((issue) => /sets both lifecycle.stopCommand and a custom stopSignal/.test(issue.message)),
+  "a custom stopSignal next to a stopCommand must be rejected")
+
+  // stopSignal alone (no stopCommand) is fine — the signal is what stops the worker.
+  assert.deepEqual(validateWorker({stopSignal: "SIGINT"}).issues, [])
+
+  // stopCommand alone (default SIGTERM) is fine — nothing custom is silently dropped.
+  assert.deepEqual(validateWorker({lifecycle: {stopCommand: "kill -TERM $ROLLBRIDGE_PID"}}).issues, [])
+
+  // An explicit default stopSignal next to a stopCommand is not flagged (SIGTERM is the default).
+  assert.deepEqual(validateWorker({lifecycle: {stopCommand: "kill -TERM $ROLLBRIDGE_PID"}, stopSignal: "SIGTERM"}).issues, [])
+})
+
+test("validateConfig defaults replicas, accepts companion replicas, and rejects bad placements", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} worker - Second (worker) process definition.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateWorker = (worker) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}, worker],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.equal(validateWorker({command: "run worker", id: "worker", policy: "companion"}).config.processes[1].replicas, 1)
+
+  const replicated = validateWorker({command: "run worker", id: "worker", policy: "companion", replicas: 4})
+
+  assert.deepEqual(replicated.issues, [])
+  assert.equal(replicated.config.processes[1].replicas, 4)
+
+  // replicas > 1 on a companion with a port is rejected.
+  assert.ok(validateWorker({command: "run worker", id: "worker", policy: "companion", port: {from: 19000, to: 19099}, replicas: 2}).issues
+    .some((issue) => /can only set replicas > 1 on a companion process without a port/.test(issue.message)))
+
+  // replicas > 1 on a non-companion policy is rejected.
+  assert.ok(validateWorker({command: "run broker", id: "broker", policy: "service", replicas: 2}).issues
+    .some((issue) => /can only set replicas > 1 on a companion/.test(issue.message)))
+
+  // Non-positive replicas is rejected.
+  assert.ok(validateWorker({command: "run worker", id: "worker", policy: "companion", replicas: 0}).issues
+    .some((issue) => issue.message === "processes[1].replicas must be a positive integer"))
+
+  // A "#" in a process id (reserved for replica instance ids) is rejected.
+  assert.ok(validateWorker({command: "run worker", id: "work#er", policy: "companion"}).issues
+    .some((issue) => /must not contain "#"/.test(issue.message)))
+
+  // nonBlockingDrain defaults to false, is accepted on a companion, and rejected elsewhere.
+  assert.equal(validateWorker({command: "run worker", id: "worker", policy: "companion"}).config.processes[1].nonBlockingDrain, false)
+
+  const draining = validateWorker({command: "run worker", id: "worker", nonBlockingDrain: true, policy: "companion"})
+
+  assert.deepEqual(draining.issues, [])
+  assert.equal(draining.config.processes[1].nonBlockingDrain, true)
+
+  assert.ok(validateWorker({command: "run b", id: "broker", nonBlockingDrain: true, policy: "service"}).issues
+    .some((issue) => /can only set nonBlockingDrain on a companion/.test(issue.message)))
+})
+
+test("validateConfig defaults stopSignal, accepts valid signals, and rejects unknown ones", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} stopSignal - Stop signal under test, or undefined to omit it.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateStopSignal = (stopSignal) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}, stopSignal}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.equal(validateStopSignal(undefined).config.processes[0].stopSignal, "SIGTERM")
+
+  const custom = validateStopSignal("SIGINT")
+
+  assert.deepEqual(custom.issues, [])
+  assert.equal(custom.config.processes[0].stopSignal, "SIGINT")
+
+  const invalid = validateStopSignal("SIGBOGUS")
+
+  assert.ok(invalid.issues.some((issue) => issue.message === "processes[0].stopSignal must be a valid signal name"), JSON.stringify(invalid.issues.map((issue) => issue.message)))
+})
+
+test("validateConfig normalizes memory supervision and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} memory - Memory config under test, or undefined to omit it.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateMemory = (memory) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", memory, policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  // Omitted → monitoring off.
+  assert.equal(validateMemory(undefined).config.processes[0].memory, undefined)
+
+  const custom = validateMemory({checkIntervalMs: 2000, limitBytes: 1048576, warnBytes: 524288})
+
+  assert.deepEqual(custom.issues, [])
+  assert.deepEqual(custom.config.processes[0].memory, {checkIntervalMs: 2000, limitBytes: 1048576, warnBytes: 524288})
+
+  // Defaults checkIntervalMs and warnBytes when only limitBytes is given.
+  const defaulted = validateMemory({limitBytes: 1048576})
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.deepEqual(defaulted.config.processes[0].memory, {checkIntervalMs: 5000, limitBytes: 1048576, warnBytes: 0})
+
+  const invalid = validateMemory({checkIntervalMs: 0, limitBytes: 0, warnBytes: -1})
+  const messages = invalid.issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("processes[0].memory.limitBytes must be a positive integer"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].memory.warnBytes must be a non-negative integer"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].memory.checkIntervalMs must be a positive number"), JSON.stringify(messages))
+})
+
 test("validateConfig rejects a non-positive-integer outputLines with a fix", () => {
   const {issues} = validateConfig({
     application: "demo",
@@ -172,6 +341,41 @@ test("validateConfig parses control.mode, defaults it to unset, and rejects inva
   assert.ok(invalid.issues.some((issue) => issue.message === "control.mode must be an octal file mode between 0 and 0o777"))
 })
 
+test("validateConfig accepts control owner/group as ids or names and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} control - Control config under test.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateControl = (control) => validateConfig({
+    application: "demo",
+    control,
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const numeric = validateControl({group: 1000, owner: 1000, path: "/tmp/demo.sock"})
+
+  assert.deepEqual(numeric.issues, [])
+  assert.equal(numeric.config.control.owner, 1000)
+  assert.equal(numeric.config.control.group, 1000)
+
+  const named = validateControl({group: "deploy", owner: "deploy", path: "/tmp/demo.sock"})
+
+  assert.deepEqual(named.issues, [])
+  assert.equal(named.config.control.owner, "deploy")
+  assert.equal(named.config.control.group, "deploy")
+
+  // Unset by default.
+  assert.equal(validateControl({path: "/tmp/demo.sock"}).config.control.owner, undefined)
+  assert.equal(validateControl({path: "/tmp/demo.sock"}).config.control.group, undefined)
+
+  const invalid = validateControl({group: -1, owner: true, path: "/tmp/demo.sock"})
+  const messages = invalid.issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("control.owner must be a non-negative integer id or a name"), JSON.stringify(messages))
+  assert.ok(messages.includes("control.group must be a non-negative integer id or a name"), JSON.stringify(messages))
+})
+
 test("validateConfig defaults health.startDelayMs to 0, accepts an override, and rejects negatives", () => {
   /**
    * @param {import("../src/json.js").JsonValue} health - Health config under test, or undefined to omit it.
@@ -228,6 +432,29 @@ test("validateConfig defaults releaseRetention, accepts overrides, and rejects b
   assert.ok(invalid.issues.some((issue) => issue.message === "releaseRetention.maxAgeMs must be a non-negative number"))
 })
 
+test("validateConfig leaves statePath unset by default, accepts a string, and rejects non-strings", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} statePath - statePath under test, or undefined.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateStatePath = (statePath) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182},
+    statePath
+  })
+
+  assert.equal(validateStatePath(undefined).config.statePath, undefined)
+
+  const set = validateStatePath("/var/lib/rollbridge/demo.state.json")
+
+  assert.deepEqual(set.issues, [])
+  assert.equal(set.config.statePath, "/var/lib/rollbridge/demo.state.json")
+
+  assert.ok(validateStatePath(123).issues.some((issue) => issue.message === "statePath must be a string"))
+})
+
 test("normalizeConfig throws an aggregated error listing every issue", () => {
   assert.throws(
     () => normalizeConfig({

package/test/doctor.test.js

@@ -1,6 +1,8 @@
 // @ts-check
 
 import assert from "node:assert/strict"
+import {spawn} from "node:child_process"
+import {once} from "node:events"
 import fs from "node:fs/promises"
 import net from "node:net"
 import os from "node:os"
@@ -8,21 +10,24 @@ import path from "node:path"
 import test from "node:test"
 import RollbridgeDaemon from "../src/daemon.js"
 import {normalizeConfig} from "../src/config.js"
-import {runEnvironmentChecks} from "../src/doctor.js"
+import {runEnvironmentChecks, runReleaseChecks} from "../src/doctor.js"
+import {writeState} from "../src/state-store.js"
 import {runCli} from "../src/cli.js"
 
 /**
  * @param {object} args - Options.
  * @param {string} args.controlPath - Control socket path.
  * @param {number} args.proxyPort - Proxy port.
+ * @param {string} [args.statePath] - State file path.
  * @returns {import("../src/config.js").RollbridgeConfig} Normalized config.
  */
-function buildConfig({controlPath, proxyPort}) {
+function buildConfig({controlPath, proxyPort, statePath}) {
   return normalizeConfig({
     application: "doctor-test",
     control: {path: controlPath},
     processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
-    proxy: {host: "127.0.0.1", port: proxyPort}
+    proxy: {host: "127.0.0.1", port: proxyPort},
+    ...(statePath ? {statePath} : {})
   })
 }
 
@@ -102,6 +107,79 @@ test("runEnvironmentChecks reports an unavailable proxy port", async () => {
   }
 })
 
+test("runEnvironmentChecks checks the state path directory and reports no orphans when none exist", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  try {
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort(), statePath: path.join(root, "state.json")}))
+
+    assert.equal(checkNamed(checks, "state path directory").ok, true)
+    assert.equal(checkNamed(checks, "orphaned processes").ok, true)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks omits state checks when no statePath is configured", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  try {
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort()}))
+
+    assert.ok(!checks.some((check) => check.name === "state path directory"))
+    assert.ok(!checks.some((check) => check.name === "orphaned processes"))
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks does not flag orphans while a daemon is running", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const statePath = path.join(root, "state.json")
+  const config = buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort(), statePath})
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    const checks = await runEnvironmentChecks(config)
+    const orphanCheck = checkNamed(checks, "orphaned processes")
+
+    // A running daemon's persisted pids are its own managed processes, not orphans.
+    assert.equal(orphanCheck.ok, true)
+    assert.match(orphanCheck.detail, /a daemon is running/)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks reports orphaned processes left in the state file", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const statePath = path.join(root, "state.json")
+  const leftover = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore"})
+
+  await once(leftover, "spawn")
+
+  try {
+    await writeState(statePath, {
+      activeReleaseId: "v1",
+      releases: [{processes: [{id: "worker", pid: leftover.pid}], releaseId: "v1"}],
+      services: [],
+      singletons: []
+    })
+
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort(), statePath}))
+    const orphanCheck = checkNamed(checks, "orphaned processes")
+
+    assert.equal(orphanCheck.ok, false)
+    assert.match(orphanCheck.detail, new RegExp(`worker \\(pid ${leftover.pid}\\)`))
+  } finally {
+    leftover.kill("SIGKILL")
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("runEnvironmentChecks reports a missing control socket directory", async () => {
   const checks = await runEnvironmentChecks(buildConfig({controlPath: "/rollbridge-doctor-missing-dir/rollbridge.sock", proxyPort: await freePort()}))
   const directoryCheck = checkNamed(checks, "control socket directory")
@@ -131,6 +209,91 @@ test("runEnvironmentChecks fails when a Rollbridge daemon already holds the sock
   }
 })
 
+/**
+ * @param {object} args - Options.
+ * @param {string} args.root - Temp root directory (holds the control socket).
+ * @param {import("../src/json.js").JsonValue[]} args.processes - Process definitions to validate.
+ * @returns {import("../src/config.js").RollbridgeConfig} Normalized config.
+ */
+function releaseConfig({processes, root}) {
+  return normalizeConfig({
+    application: "doctor-release-test",
+    control: {path: path.join(root, "rollbridge.sock")},
+    processes,
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+}
+
+test("runReleaseChecks passes for an existing release with resolvable templates", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const releasePath = path.join(root, "release")
+
+  await fs.mkdir(path.join(releasePath, "backend"), {recursive: true})
+
+  try {
+    const config = releaseConfig({processes: [{command: "run web --port {{port}} --release {{releaseId}}", cwd: "{{releasePath}}/backend", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}], root})
+    const checks = await runReleaseChecks(config, {releasePath})
+
+    assert.equal(checkNamed(checks, "release path").ok, true)
+    assert.equal(checkNamed(checks, "process templates").ok, true)
+    assert.equal(checkNamed(checks, "process working directories").ok, true)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runReleaseChecks flags a command that references an undefined template variable", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const releasePath = path.join(root, "release")
+
+  await fs.mkdir(releasePath, {recursive: true})
+
+  try {
+    const config = releaseConfig({processes: [{command: "run web --secret {{missingVar}}", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}], root})
+    const templates = checkNamed(await runReleaseChecks(config, {releasePath}), "process templates")
+
+    assert.equal(templates.ok, false)
+    assert.match(templates.detail, /web:.*missingVar/)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runReleaseChecks reports a missing process working directory", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const releasePath = path.join(root, "release")
+
+  // The release directory exists, but the process's rendered cwd subdirectory does not.
+  await fs.mkdir(releasePath, {recursive: true})
+
+  try {
+    const config = releaseConfig({processes: [{command: "run web", cwd: "{{releasePath}}/backend", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}], root})
+    const checks = await runReleaseChecks(config, {releasePath})
+
+    assert.equal(checkNamed(checks, "release path").ok, true)
+
+    const directories = checkNamed(checks, "process working directories")
+
+    assert.equal(directories.ok, false)
+    assert.match(directories.detail, /web .*backend/)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runReleaseChecks reports a missing release path", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  try {
+    const config = releaseConfig({processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}], root})
+    const checks = await runReleaseChecks(config, {releasePath: path.join(root, "does-not-exist")})
+
+    assert.equal(checkNamed(checks, "release path").ok, false)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 /**
  * Runs the CLI while capturing console output.
  * @param {string[]} argv - Process argv.
@@ -226,3 +389,42 @@ test("doctor --json emits structured checks", async () => {
     await fs.rm(badRoot, {force: true, recursive: true})
   }
 })
+
+test("doctor --release-path adds release checks, passing or failing on the working directory", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const releasePath = path.join(root, "release")
+
+  await fs.mkdir(path.join(releasePath, "backend"), {recursive: true})
+
+  const rawConfig = {
+    application: "doctor-release-cli",
+    control: {path: path.join(root, "rollbridge.sock")},
+    processes: [{command: "run web --port {{port}}", cwd: "{{releasePath}}/backend", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: await freePort()}
+  }
+
+  await fs.writeFile(path.join(root, "rollbridge.js"), `module.exports = ${JSON.stringify(rawConfig)}\n`)
+
+  try {
+    const passing = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js"), "--release-path", releasePath])
+
+    assert.match(passing, /✓ release path:/)
+    assert.match(passing, /✓ process templates:/)
+    assert.match(passing, /✓ process working directories:/)
+    assert.match(passing, /All checks passed\./)
+    assert.notEqual(process.exitCode, 1)
+
+    // A release without the rendered backend directory fails the working-directories check.
+    const emptyRelease = path.join(root, "empty-release")
+
+    await fs.mkdir(emptyRelease, {recursive: true})
+
+    const failing = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js"), "--release-path", emptyRelease])
+
+    assert.match(failing, /✗ process working directories:/)
+    assert.equal(process.exitCode, 1)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})

package/test/event-log.test.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import test from "node:test"
+import EventLog from "../src/event-log.js"
+
+test("records events with a timestamp, message, and data", () => {
+  const log = new EventLog(10)
+
+  log.record("traffic switched", {releaseId: "v1"})
+
+  const [event] = log.recent()
+
+  assert.equal(event.message, "traffic switched")
+  assert.deepEqual(event.data, {releaseId: "v1"})
+  assert.match(event.at, /^\d{4}-\d{2}-\d{2}T.*Z$/)
+})
+
+test("drops the oldest events once the limit is exceeded", () => {
+  const log = new EventLog(3)
+
+  for (let index = 0; index < 5; index += 1) log.record("tick", {index})
+
+  const events = log.recent()
+
+  assert.equal(events.length, 3)
+  assert.deepEqual(events.map((event) => event.data.index), [2, 3, 4])
+})
+
+test("recent(limit) returns only the most recent events, oldest first", () => {
+  const log = new EventLog(10)
+
+  for (let index = 0; index < 5; index += 1) log.record("tick", {index})
+
+  assert.deepEqual(log.recent(2).map((event) => event.data.index), [3, 4])
+})
+
+test("recent returns every event when the limit is omitted or not a positive number", () => {
+  const log = new EventLog(10)
+
+  for (let index = 0; index < 3; index += 1) log.record("tick", {index})
+
+  assert.equal(log.recent().length, 3)
+  assert.equal(log.recent(0).length, 3)
+  assert.equal(log.recent(99).length, 3)
+})

package/test/fixtures/memory-hog.js

@@ -0,0 +1,19 @@
+// Allocates and fills memory above a configured size, then stays alive, to exercise
+// memory supervision. ROLLBRIDGE_HOG_BYTES controls how much resident memory to hold.
+
+const targetBytes = Number(process.env.ROLLBRIDGE_HOG_BYTES || 200 * 1024 * 1024)
+const chunkBytes = 16 * 1024 * 1024
+const buffers = []
+let allocated = 0
+
+while (allocated < targetBytes) {
+  const size = Math.min(chunkBytes, targetBytes - allocated)
+
+  // Fill so the pages are resident (counted in RSS), not lazily reserved.
+  buffers.push(Buffer.alloc(size, 1))
+  allocated += size
+}
+
+// Keep the buffers referenced and the process alive.
+globalThis.__rollbridgeHog = buffers
+setInterval(() => {}, 1000)