rollbridge 0.1.2 → 0.1.4

package/src/doctor.js

@@ -0,0 +1,114 @@
+// @ts-check
+
+import {constants as fsConstants} from "node:fs"
+import fs from "node:fs/promises"
+import net from "node:net"
+import path from "node:path"
+import {inspectControlSocket} from "./daemon.js"
+
+/**
+ * @typedef {{detail: string, name: string, ok: boolean}} DoctorCheck
+ */
+
+/**
+ * Runs pre-flight environment checks for a validated config: control socket
+ * reachability, control-socket directory writability, and proxy port availability.
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck[]>} One check per probed aspect.
+ */
+export async function runEnvironmentChecks(config) {
+  /** @type {DoctorCheck[]} */
+  const checks = []
+  const socketInspection = await inspectControlSocketSafely(config.control.path)
+
+  checks.push(controlSocketCheck(config, socketInspection))
+  checks.push(await controlSocketDirectoryCheck(config))
+  checks.push(await proxyPortCheck(config))
+
+  return checks
+}
+
+/**
+ * @param {string} socketPath - Control socket path.
+ * @returns {Promise<{alive: boolean, application?: string} | {error: string}>} Probe result, or the probe error.
+ */
+async function inspectControlSocketSafely(socketPath) {
+  try {
+    return await inspectControlSocket(socketPath)
+  } catch (error) {
+    return {error: error instanceof Error ? error.message : String(error)}
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @param {{alive: boolean, application?: string} | {error: string}} inspection - Control socket probe result.
+ * @returns {DoctorCheck} Control socket reachability check.
+ */
+function controlSocketCheck(config, inspection) {
+  const socketPath = config.control.path
+
+  if ("error" in inspection) {
+    return {detail: `could not probe ${socketPath}: ${inspection.error}`, name: "control socket", ok: false}
+  }
+
+  if (!inspection.alive) {
+    return {detail: `no daemon running; ${socketPath} is free to bind`, name: "control socket", ok: true}
+  }
+
+  if (inspection.application === undefined) {
+    return {detail: `another process is already listening on ${socketPath}; the daemon would fail to bind it`, name: "control socket", ok: false}
+  }
+
+  return {detail: `a Rollbridge daemon for "${inspection.application}" is already running on ${socketPath}; stop it before starting another`, name: "control socket", ok: false}
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck>} Whether the control socket's directory is writable.
+ */
+async function controlSocketDirectoryCheck(config) {
+  const directory = path.dirname(path.resolve(config.control.path))
+
+  try {
+    // Creating a Unix socket needs both write and search (execute) permission on the directory.
+    await fs.access(directory, fsConstants.W_OK | fsConstants.X_OK)
+
+    return {detail: `${directory} is writable`, name: "control socket directory", ok: true}
+  } catch {
+    return {detail: `${directory} is missing or not writable`, name: "control socket directory", ok: false}
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck>} Whether the proxy port can be bound.
+ */
+async function proxyPortCheck(config) {
+  const address = `${config.proxy.host}:${config.proxy.port}`
+  const bind = await canBindPort(config.proxy.host, config.proxy.port)
+
+  if (bind.ok) {
+    return {detail: `${address} is available`, name: "proxy port", ok: true}
+  }
+
+  return {detail: `${address} is unavailable (${bind.code})`, name: "proxy port", ok: false}
+}
+
+/**
+ * @param {string} host - Bind host.
+ * @param {number} port - Candidate port.
+ * @returns {Promise<{ok: true} | {code: string, ok: false}>} Whether the port can be bound.
+ */
+async function canBindPort(host, port) {
+  return await new Promise((resolve) => {
+    const server = net.createServer()
+
+    server.once("error", (error) => {
+      const code = error && typeof error === "object" && "code" in error ? String(error.code) : "EUNKNOWN"
+
+      resolve({code, ok: false})
+    })
+    server.listen(port, host, () => server.close(() => resolve({ok: true})))
+  })
+}

package/src/health.js

@@ -9,6 +9,10 @@
  * @returns {Promise<void>} Resolves when healthy.
  */
 export async function waitForHealth({health, host, port}) {
+  if (health.startDelayMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, health.startDelayMs))
+  }
+
   const deadline = Date.now() + health.timeoutMs
   const url = `http://${host}:${port}${health.path}`
   let lastError = "no attempts"

package/src/managed-process.js

@@ -9,7 +9,7 @@ import {spawn} from "node:child_process"
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
  * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, outputLines: number, restartDelayMs: number, shouldRestart: () => boolean, stopTimeoutMs: number}} ManagedProcessDefinition
- * @typedef {{command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, logs: ManagedProcessLog[], pid: number | undefined, state: ManagedProcessState}} ManagedProcessStatus
+ * @typedef {{command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, logs: ManagedProcessLog[], pid: number | undefined, restarts: number, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
 export default class ManagedProcess extends EventEmitter {
@@ -39,6 +39,8 @@ export default class ManagedProcess extends EventEmitter {
     this.stopTimeoutMs = stopTimeoutMs
     this.state = /** @type {ManagedProcessState} */ ("stopped")
     this.logs = /** @type {ManagedProcessLog[]} */ ([])
+    this.restarts = 0
+    this.startedAtMs = /** @type {number | undefined} */ (undefined)
     this.intentionalStop = false
     this.restartTimer = undefined
     this.child = undefined
@@ -77,6 +79,7 @@ export default class ManagedProcess extends EventEmitter {
 
       child.once("spawn", () => {
         this.state = "running"
+        this.startedAtMs = Date.now()
         this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null})
         this.emit("started")
         resolve(undefined)
@@ -145,6 +148,7 @@ export default class ManagedProcess extends EventEmitter {
     if (!wasIntentional && this.shouldRestart()) {
       this.restartTimer = setTimeout(() => {
         this.restartTimer = undefined
+        this.restarts += 1
         this.start().catch((error) => {
           this.logger("process restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
         })
@@ -229,7 +233,10 @@ export default class ManagedProcess extends EventEmitter {
       id: this.id,
       logs: this.logs.slice(-this.outputLines),
       pid: this.pid,
-      state: this.state
+      restarts: this.restarts,
+      startedAt: this.startedAtMs === undefined ? undefined : new Date(this.startedAtMs).toISOString(),
+      state: this.state,
+      uptimeMs: this.state === "running" && this.startedAtMs !== undefined ? Date.now() - this.startedAtMs : undefined
     }
   }
 }

package/src/release-group.js

@@ -67,18 +67,46 @@ export default class ReleaseGroup extends EventEmitter {
         if (processConfig.policy === "proxied" && processConfig.port && processConfig.health) {
           await waitForHealth({
             health: processConfig.health,
-            host: this.config.proxy.host,
+            host: this.config.proxy.upstreamHost,
             port: this.ports[processConfig.id]
           })
         }
       }
     } catch (error) {
       this.state = "failed"
+      this.logStartupFailure(error instanceof Error ? error : String(error))
       await this.stop()
       throw error
     }
   }
 
+  /**
+   * Logs process diagnostics before failed startup cleanup stops and removes the release processes.
+   * @param {Error | string} error - Startup failure.
+   * @returns {void}
+   */
+  logStartupFailure(error) {
+    this.logger("release startup failed", {
+      error: error instanceof Error ? error.message : error,
+      releaseId: this.releaseId
+    })
+
+    for (const processInstance of this.processes.values()) {
+      const status = processInstance.status()
+
+      this.logger("release startup process status", {
+        command: status.command,
+        exitCode: status.exitCode ?? null,
+        exitSignal: status.exitSignal ?? null,
+        logs: status.logs,
+        pid: status.pid ?? null,
+        processId: status.id,
+        releaseId: this.releaseId,
+        state: status.state
+      })
+    }
+  }
+
   /**
    * Starts companions before the proxied process so release-local dependencies are available before health checks.
    * @returns {import("./config.js").ProcessConfig[]} Ordered process configs.
@@ -112,7 +140,7 @@ export default class ReleaseGroup extends EventEmitter {
       }
 
       this.ports[processConfig.id] = await findAvailablePort({
-        host: this.config.proxy.host,
+        host: this.config.proxy.upstreamHost,
         range: processConfig.port,
         usedPorts
       })
@@ -186,7 +214,8 @@ export default class ReleaseGroup extends EventEmitter {
       processId: processConfig.id,
       proxy: {
         host: this.config.proxy.host,
-        port: this.config.proxy.port
+        port: this.config.proxy.port,
+        upstreamHost: this.config.proxy.upstreamHost
       },
       releaseId: this.releaseId,
       releasePath: this.releasePath,
@@ -211,7 +240,7 @@ export default class ReleaseGroup extends EventEmitter {
 
     return {
       process: processInstance,
-      target: `http://${this.config.proxy.host}:${port}`
+      target: `http://${this.config.proxy.upstreamHost}:${port}`
     }
   }
 

package/test/config-validation.test.js

@@ -55,6 +55,21 @@ test("validateConfig returns a normalized config and no issues for a valid confi
   assert.equal(config.proxy.port, 8182)
 })
 
+test("validateConfig defaults wildcard proxy upstreams to loopback", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", health: {path: "/ping"}, id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "0.0.0.0", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.proxy.host, "0.0.0.0")
+  assert.equal(config.proxy.upstreamHost, "127.0.0.1")
+})
+
 test("validateConfig defaults outputLines and accepts a positive override", () => {
   const {config, issues} = validateConfig({
     application: "demo",
@@ -117,6 +132,62 @@ 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 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.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateHealth = (health) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", health, id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const defaulted = validateHealth({path: "/ping"})
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.equal(defaulted.config.processes[0].health?.startDelayMs, 0)
+
+  const custom = validateHealth({path: "/ping", startDelayMs: 2000})
+
+  assert.deepEqual(custom.issues, [])
+  assert.equal(custom.config.processes[0].health?.startDelayMs, 2000)
+
+  const negative = validateHealth({path: "/ping", startDelayMs: -1})
+
+  assert.ok(negative.issues.some((issue) => issue.message === "processes[0].health.startDelayMs must be a non-negative number"))
+})
+
+test("validateConfig defaults releaseRetention, accepts overrides, and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} releaseRetention - Retention config under test, or undefined.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateRetention = (releaseRetention) => 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},
+    releaseRetention
+  })
+
+  const defaulted = validateRetention(undefined)
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.deepEqual(defaulted.config.releaseRetention, {keep: 10, maxAgeMs: 0})
+
+  const custom = validateRetention({keep: 3, maxAgeMs: 60000})
+
+  assert.deepEqual(custom.issues, [])
+  assert.deepEqual(custom.config.releaseRetention, {keep: 3, maxAgeMs: 60000})
+
+  const invalid = validateRetention({keep: -1, maxAgeMs: -5})
+
+  assert.ok(invalid.issues.some((issue) => issue.message === "releaseRetention.keep must be a non-negative integer"))
+  assert.ok(invalid.issues.some((issue) => issue.message === "releaseRetention.maxAgeMs must be a non-negative number"))
+})
+
 test("normalizeConfig throws an aggregated error listing every issue", () => {
   assert.throws(
     () => normalizeConfig({
@@ -178,6 +249,40 @@ test("validate CLI command accepts a valid config without setting a failure exit
   }
 })
 
+test("validate --json emits a machine-readable result", async () => {
+  const validPath = await writeConfig({
+    application: "demo",
+    control: {path: "/tmp/rollbridge-json-valid.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+  const invalidPath = await writeConfig({
+    application: "demo",
+    processes: [{command: "run web", id: "web", policy: "proxied"}],
+    proxy: {port: 8182}
+  })
+
+  try {
+    const valid = JSON.parse((await captureCli(["node", "rollbridge", "validate", "--json", "-c", validPath])).output)
+
+    assert.equal(valid.valid, true)
+    assert.deepEqual(valid.issues, [])
+    assert.equal(valid.config.processes, 1)
+    assert.notEqual(process.exitCode, 1)
+
+    const invalid = JSON.parse((await captureCli(["node", "rollbridge", "validate", "--json", "-c", invalidPath])).output)
+
+    assert.equal(invalid.valid, false)
+    assert.equal(invalid.config, null)
+    assert.ok(invalid.issues.some((/** @type {{message: string}} */ issue) => /must define a port range/.test(issue.message)))
+    assert.equal(process.exitCode, 1)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(path.dirname(validPath), {force: true, recursive: true})
+    await fs.rm(path.dirname(invalidPath), {force: true, recursive: true})
+  }
+})
+
 /**
  * @param {Record<string, import("../src/json.js").JsonValue>} config - Raw config object.
  * @returns {Promise<string>} Path to the written config module.

package/test/doctor.test.js

@@ -0,0 +1,228 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import fs from "node:fs/promises"
+import net from "node:net"
+import os from "node:os"
+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 {runCli} from "../src/cli.js"
+
+/**
+ * @param {object} args - Options.
+ * @param {string} args.controlPath - Control socket path.
+ * @param {number} args.proxyPort - Proxy port.
+ * @returns {import("../src/config.js").RollbridgeConfig} Normalized config.
+ */
+function buildConfig({controlPath, proxyPort}) {
+  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}
+  })
+}
+
+/**
+ * @returns {Promise<number>} A port that was free when probed.
+ */
+async function freePort() {
+  return await new Promise((resolve) => {
+    const server = net.createServer()
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+      const port = address && typeof address === "object" ? address.port : 0
+
+      server.close(() => resolve(port))
+    })
+  })
+}
+
+/**
+ * @returns {Promise<{port: number, server: import("node:net").Server}>} An occupied port and its server.
+ */
+async function occupyPort() {
+  const server = net.createServer()
+  const port = await new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+
+      resolve(address && typeof address === "object" ? address.port : 0)
+    })
+  })
+
+  return {port, server}
+}
+
+/**
+ * @param {DoctorCheck[]} checks - Checks.
+ * @param {string} name - Check name.
+ * @returns {DoctorCheck} The matching check.
+ * @typedef {import("../src/doctor.js").DoctorCheck} DoctorCheck
+ */
+function checkNamed(checks, name) {
+  const check = checks.find((candidate) => candidate.name === name)
+
+  assert.ok(check, `expected a "${name}" check`)
+
+  return check
+}
+
+test("runEnvironmentChecks passes when no daemon runs, the port is free, and the directory is writable", 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.equal(checkNamed(checks, "control socket").ok, true)
+    assert.equal(checkNamed(checks, "control socket directory").ok, true)
+    assert.equal(checkNamed(checks, "proxy port").ok, true)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks reports an unavailable proxy port", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const {port, server} = await occupyPort()
+
+  try {
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: port}))
+    const proxyCheck = checkNamed(checks, "proxy port")
+
+    assert.equal(proxyCheck.ok, false)
+    assert.match(proxyCheck.detail, /unavailable/)
+  } finally {
+    await new Promise((resolve) => server.close(() => resolve(undefined)))
+    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")
+
+  assert.equal(directoryCheck.ok, false)
+  assert.match(directoryCheck.detail, /missing or not writable/)
+})
+
+test("runEnvironmentChecks fails when a Rollbridge daemon already holds the socket and port", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const config = buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort()})
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    const checks = await runEnvironmentChecks(config)
+    const socketCheck = checkNamed(checks, "control socket")
+
+    // A daemon already running means `rollbridge daemon` would fail to bind, so doctor must fail too.
+    assert.equal(socketCheck.ok, false)
+    assert.match(socketCheck.detail, /a Rollbridge daemon for "doctor-test" is already running/)
+    assert.equal(checkNamed(checks, "proxy port").ok, false)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+/**
+ * Runs the CLI while capturing console output.
+ * @param {string[]} argv - Process argv.
+ * @returns {Promise<string>} Captured stdout and stderr lines.
+ */
+async function captureCli(argv) {
+  const originalLog = console.log
+  const originalError = console.error
+  /** @type {string[]} */
+  const lines = []
+  const collect = (/** @type {string[]} */ ...args) => { lines.push(args.map((arg) => String(arg)).join(" ")) }
+
+  console.log = collect
+  console.error = collect
+
+  try {
+    await runCli(argv)
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+
+  return lines.join("\n")
+}
+
+test("doctor CLI passes for a valid, bindable config", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const rawConfig = {
+    application: "doctor-cli-test",
+    control: {path: path.join(root, "rollbridge.sock")},
+    processes: [{command: "run web", 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 output = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js")])
+
+    assert.match(output, /All checks passed\./)
+    assert.notEqual(process.exitCode, 1)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("doctor CLI fails and exits non-zero for an invalid config", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  await fs.writeFile(path.join(root, "rollbridge.js"), "module.exports = {application: \"x\", proxy: {port: 8182}, processes: []}\n")
+
+  try {
+    const output = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js")])
+
+    assert.equal(process.exitCode, 1)
+    assert.match(output, /✗ config:/)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("doctor --json emits structured checks", async () => {
+  const okRoot = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const okConfig = {
+    application: "doctor-json-test",
+    control: {path: path.join(okRoot, "rollbridge.sock")},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: await freePort()}
+  }
+
+  await fs.writeFile(path.join(okRoot, "rollbridge.js"), `module.exports = ${JSON.stringify(okConfig)}\n`)
+
+  const badRoot = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  await fs.writeFile(path.join(badRoot, "rollbridge.js"), "module.exports = {application: \"x\", proxy: {port: 8182}, processes: []}\n")
+
+  try {
+    const passing = JSON.parse(await captureCli(["node", "rollbridge", "doctor", "--json", "-c", path.join(okRoot, "rollbridge.js")]))
+
+    assert.equal(passing.ok, true)
+    assert.ok(passing.checks.some((/** @type {{name: string, ok: boolean}} */ check) => check.name === "proxy port" && check.ok === true))
+    assert.notEqual(process.exitCode, 1)
+
+    const failing = JSON.parse(await captureCli(["node", "rollbridge", "doctor", "--json", "-c", path.join(badRoot, "rollbridge.js")]))
+
+    assert.equal(failing.ok, false)
+    assert.ok(failing.checks.some((/** @type {{name: string, ok: boolean}} */ check) => check.name === "config" && check.ok === false))
+    assert.equal(process.exitCode, 1)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(okRoot, {force: true, recursive: true})
+    await fs.rm(badRoot, {force: true, recursive: true})
+  }
+})

package/test/fixtures/crasher.js

@@ -0,0 +1,2 @@
+// Exits non-zero shortly after starting, to exercise auto-restart behavior.
+setTimeout(() => process.exit(1), 40)

package/test/health.test.js

@@ -0,0 +1,63 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import http from "node:http"
+import test from "node:test"
+import {waitForHealth} from "../src/health.js"
+
+/**
+ * Starts a health server that records when it first receives a probe.
+ * @returns {Promise<{firstProbeDelay: () => number, port: number, close: () => Promise<void>}>} Server handle.
+ */
+async function startHealthServer() {
+  const start = Date.now()
+  let firstProbeAt = 0
+  const server = http.createServer((request, response) => {
+    if (firstProbeAt === 0) firstProbeAt = Date.now()
+
+    response.writeHead(200, {"Content-Type": "text/plain"})
+    response.end("ok")
+  })
+
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve(undefined)))
+
+  const address = server.address()
+
+  return {
+    close: () => new Promise((resolve) => server.close(() => resolve(undefined))),
+    firstProbeDelay: () => firstProbeAt - start,
+    port: address && typeof address === "object" ? address.port : 0
+  }
+}
+
+test("waitForHealth delays the first probe by startDelayMs", async () => {
+  const server = await startHealthServer()
+
+  try {
+    await waitForHealth({
+      health: {intervalMs: 25, path: "/ping", startDelayMs: 200, timeoutMs: 2000},
+      host: "127.0.0.1",
+      port: server.port
+    })
+
+    assert.ok(server.firstProbeDelay() >= 180, `expected first probe to be delayed ~200ms, was ${server.firstProbeDelay()}ms`)
+  } finally {
+    await server.close()
+  }
+})
+
+test("waitForHealth probes immediately when startDelayMs is 0", async () => {
+  const server = await startHealthServer()
+
+  try {
+    await waitForHealth({
+      health: {intervalMs: 25, path: "/ping", startDelayMs: 0, timeoutMs: 2000},
+      host: "127.0.0.1",
+      port: server.port
+    })
+
+    assert.ok(server.firstProbeDelay() < 150, `expected an immediate first probe, was ${server.firstProbeDelay()}ms`)
+  } finally {
+    await server.close()
+  }
+})