rollbridge 0.1.1 → 0.1.4

package/src/daemon.js

@@ -10,7 +10,7 @@ import ReleaseGroup from "./release-group.js"
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{releaseId?: string, releasePath: string, revision?: string}} DeployArgs
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
- * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, proxy: {host: string, port: number | undefined}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
+ * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
  */
 
 export default class RollbridgeDaemon {
@@ -74,6 +74,10 @@ export default class RollbridgeDaemon {
         resolve(undefined)
       })
     })
+
+    if (this.config.control.mode !== undefined) {
+      await fs.chmod(this.config.control.path, this.config.control.mode)
+    }
   }
 
   /** @returns {Promise<void>} Removes a stale Unix socket before binding, or fails clearly when a daemon is alive. */
@@ -282,9 +286,7 @@ export default class RollbridgeDaemon {
     await this.replaceSingletons(release)
 
     if (previousRelease) {
-      previousRelease.drainAndStop(this.config.proxy.drainTimeoutMs).catch((error) => {
-        this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: previousRelease.releaseId})
-      })
+      void this.drainAndPrune(previousRelease)
     }
 
     return {
@@ -362,6 +364,7 @@ export default class RollbridgeDaemon {
         cwd: nextDefinition.cwd,
         env: nextDefinition.env,
         logger: nextDefinition.logger,
+        outputLines: nextDefinition.outputLines,
         restartDelayMs: nextDefinition.restartDelayMs,
         shouldRestart: nextDefinition.shouldRestart,
         stopTimeoutMs: nextDefinition.stopTimeoutMs
@@ -402,6 +405,31 @@ export default class RollbridgeDaemon {
     if (release === this.activeRelease) this.activeRelease = undefined
 
     await release.stop()
+    this.pruneStoppedReleases()
+  }
+
+  /**
+   * Drains and stops a retired release in the background, then prunes stopped releases.
+   * @param {ReleaseGroup} release - Release to drain and stop.
+   * @returns {Promise<void>} Resolves once drained, stopped, and pruned.
+   */
+  async drainAndPrune(release) {
+    try {
+      await release.drainAndStop(this.config.proxy.drainTimeoutMs)
+    } catch (error) {
+      this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: release.releaseId})
+    } finally {
+      this.pruneStoppedReleases()
+    }
+  }
+
+  /** @returns {void} Removes stopped releases beyond the retention policy. */
+  pruneStoppedReleases() {
+    const statuses = [...this.releases.values()].map((release) => release.status())
+
+    for (const releaseId of releasesToPrune(statuses, this.config.releaseRetention, Date.now())) {
+      this.releases.delete(releaseId)
+    }
   }
 
   /** @returns {Promise<void>} Stops proxy, control socket, and child processes. */
@@ -441,7 +469,8 @@ export default class RollbridgeDaemon {
       control: {...this.config.control},
       proxy: {
         host: this.config.proxy.host,
-        port: this.proxyPort ?? this.config.proxy.port
+        port: this.proxyPort ?? this.config.proxy.port,
+        upstreamHost: this.config.proxy.upstreamHost
       },
       releases: [...this.releases.values()].map((release) => release.status()),
       services: [...this.services.entries()].map(([id, processInstance]) => ({
@@ -480,6 +509,37 @@ function requiredString(value, key) {
   return value
 }
 
+/**
+ * @typedef {{releaseId: string, state: string, stoppedAt: string | undefined}} PrunableRelease
+ */
+
+/**
+ * Selects stopped releases to prune by the retention policy, keeping the most recent.
+ * @param {PrunableRelease[]} releases - Status of all tracked releases, in deploy order (oldest first).
+ * @param {import("./config.js").ReleaseRetentionConfig} policy - Retention policy.
+ * @param {number} now - Current epoch milliseconds.
+ * @returns {string[]} Release ids to remove.
+ */
+export function releasesToPrune(releases, policy, now) {
+  const stopped = releases
+    .filter((release) => release.state === "stopped")
+    .map((release, index) => ({deployOrder: index, releaseId: release.releaseId, stoppedAtMs: release.stoppedAt ? Date.parse(release.stoppedAt) : 0}))
+    // Most recent first; ties (same stoppedAt millisecond) prefer the later-deployed release.
+    .sort((first, second) => second.stoppedAtMs - first.stoppedAtMs || second.deployOrder - first.deployOrder)
+
+  /** @type {string[]} */
+  const remove = []
+
+  stopped.forEach((release, index) => {
+    const beyondKeep = index >= policy.keep
+    const tooOld = policy.maxAgeMs > 0 && release.stoppedAtMs > 0 && now - release.stoppedAtMs > policy.maxAgeMs
+
+    if (beyondKeep || tooOld) remove.push(release.releaseId)
+  })
+
+  return remove
+}
+
 /**
  * @typedef {{alive: boolean, application?: string, activeReleaseId?: string | null}} ControlSocketInspection
  */
@@ -507,7 +567,7 @@ function controlSocketBusyMessage(socketPath, inspection) {
  * @param {number} [timeoutMs] - How long to wait for a status response before treating the socket as busy.
  * @returns {Promise<ControlSocketInspection>} Whether the socket is live and, when it is Rollbridge, its identity.
  */
-async function inspectControlSocket(socketPath, timeoutMs = 1000) {
+export async function inspectControlSocket(socketPath, timeoutMs = 1000) {
   return await new Promise((resolve, reject) => {
     const socket = net.createConnection(socketPath)
     let buffer = ""

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

@@ -8,8 +8,8 @@ import {spawn} from "node:child_process"
  * @typedef {"starting" | "running" | "stopping" | "stopped" | "failed"} ManagedProcessState
  * @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, 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, 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, restarts: number, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
 export default class ManagedProcess extends EventEmitter {
@@ -20,11 +20,12 @@ export default class ManagedProcess extends EventEmitter {
    * @param {Record<string, string | undefined>} args.env - Environment.
    * @param {string} args.id - Process id.
    * @param {(message: string, data?: Record<string, JsonValue>) => void} args.logger - Logger callback.
+   * @param {number} args.outputLines - Recent stdout/stderr lines to retain and report.
    * @param {number} args.restartDelayMs - Restart delay.
    * @param {() => boolean} args.shouldRestart - Restart policy callback.
    * @param {number} args.stopTimeoutMs - Stop timeout.
    */
-  constructor({command, cwd, env, id, logger, restartDelayMs, shouldRestart, stopTimeoutMs}) {
+  constructor({command, cwd, env, id, logger, outputLines, restartDelayMs, shouldRestart, stopTimeoutMs}) {
     super()
 
     this.command = command
@@ -32,11 +33,14 @@ export default class ManagedProcess extends EventEmitter {
     this.env = env
     this.id = id
     this.logger = logger
+    this.outputLines = outputLines
     this.restartDelayMs = restartDelayMs
     this.shouldRestart = shouldRestart
     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
@@ -75,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)
@@ -100,6 +105,7 @@ export default class ManagedProcess extends EventEmitter {
     this.cwd = definition.cwd
     this.env = definition.env
     this.logger = definition.logger
+    this.outputLines = definition.outputLines
     this.restartDelayMs = definition.restartDelayMs
     this.shouldRestart = definition.shouldRestart
     this.stopTimeoutMs = definition.stopTimeoutMs
@@ -116,8 +122,8 @@ export default class ManagedProcess extends EventEmitter {
 
       this.logs.push({at: new Date().toISOString(), line, stream})
 
-      if (this.logs.length > 200) {
-        this.logs.splice(0, this.logs.length - 200)
+      if (this.logs.length > this.outputLines) {
+        this.logs.splice(0, this.logs.length - this.outputLines)
       }
     }
   }
@@ -142,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})
         })
@@ -224,9 +231,12 @@ export default class ManagedProcess extends EventEmitter {
       exitCode: this.exitCode,
       exitSignal: this.exitSignal,
       id: this.id,
-      logs: this.logs.slice(-20),
+      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
       })
@@ -141,6 +169,7 @@ export default class ReleaseGroup extends EventEmitter {
       env: processEnv,
       id: processConfig.id,
       logger: (message, data = {}) => this.logger(message, {processId: processConfig.id, releaseId: this.releaseId, ...data}),
+      outputLines: processConfig.outputLines,
       restartDelayMs: processConfig.restartDelayMs,
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
       stopTimeoutMs: processConfig.gracefulStopMs
@@ -179,12 +208,14 @@ export default class ReleaseGroup extends EventEmitter {
   contextForProcess(processConfig) {
     return {
       application: this.config.application,
+      env: {...process.env},
       port: this.ports[processConfig.id],
       ports: this.ports,
       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,
@@ -209,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,139 @@ 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",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run worker", id: "worker", outputLines: 5, policy: "companion"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.processes[0].outputLines, 50)
+  assert.equal(config.processes[1].outputLines, 5)
+})
+
+test("validateConfig rejects a non-positive-integer outputLines with a fix", () => {
+  const {issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", outputLines: 0, policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const issue = issues.find((candidate) => candidate.message === "processes[0].outputLines must be a positive integer")
+
+  assert.ok(issue, `expected an outputLines issue in ${JSON.stringify(issues.map((candidate) => candidate.message))}`)
+  assert.match(issue.fix, /positive integer/)
+})
+
+test("validateConfig parses control.mode, defaults it to unset, and rejects invalid modes", () => {
+  /**
+   * @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 parsed = validateControl({mode: "660", path: "/tmp/demo.sock"})
+
+  assert.deepEqual(parsed.issues, [])
+  assert.equal(parsed.config.control.mode, 0o660)
+
+  // Minimal octal strings are accepted, matching the numeric boundary (e.g. 0).
+  const minimal = validateControl({mode: "0", path: "/tmp/demo.sock"})
+
+  assert.deepEqual(minimal.issues, [])
+  assert.equal(minimal.config.control.mode, 0)
+
+  assert.equal(validateControl({path: "/tmp/demo.sock"}).config.control.mode, undefined)
+
+  const invalid = validateControl({mode: "abc", path: "/tmp/demo.sock"})
+
+  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({
@@ -116,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.