rollbridge 0.1.4 → 0.1.6

package/src/cli.js

@@ -7,7 +7,8 @@ import {spawn} from "node:child_process"
 import {Command} from "commander"
 import RollbridgeDaemon from "./daemon.js"
 import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
-import {runEnvironmentChecks} from "./doctor.js"
+import {runEnvironmentChecks, runReleaseChecks} from "./doctor.js"
+import {recoverOrphans} from "./recover.js"
 import {sendControlCommand} from "./control-client.js"
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 10000
@@ -82,6 +83,25 @@ export async function runCli(argv) {
       console.log(JSON.stringify(response, null, 2))
     })
 
+  program
+    .command("rollback")
+    .description("Roll back to a previous release: re-start it, health-check it, and switch traffic.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--release-id <id>", "Release id to roll back to (defaults to the most recently retired release)")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {
+          command: "rollback",
+          releaseId: options.releaseId
+        },
+        path: config.control.path
+      })
+
+      console.log(JSON.stringify(response, null, 2))
+    })
+
   program
     .command("ensure-daemon")
     .description("Start the daemon if the control socket is not already accepting commands.")
@@ -136,6 +156,33 @@ export async function runCli(argv) {
       console.log(JSON.stringify(response, null, 2))
     })
 
+  program
+    .command("restart")
+    .description("Restart running non-proxied processes (by id, by policy, or all).")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--process <id>", "Restart only the process with this id")
+    .option("--policy <policy>", "Restart only processes with this policy (companion, singleton, or service)")
+    .action(async (options) => {
+      if (options.policy !== undefined && !["companion", "service", "singleton"].includes(options.policy)) {
+        console.error("--policy must be one of: companion, singleton, service.")
+        process.exitCode = 1
+        return
+      }
+
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {
+          command: "restart",
+          policy: options.policy,
+          processId: options.process
+        },
+        path: config.control.path
+      })
+
+      console.log(JSON.stringify(response, null, 2))
+    })
+
   program
     .command("shutdown")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
@@ -201,6 +248,9 @@ export async function runCli(argv) {
     .command("doctor")
     .description("Check the environment before starting the daemon: config, control socket, and proxy port.")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--release-path <path>", "Also pre-flight a prepared release: render its templates and check the release and working directories")
+    .option("--release-id <id>", "Release id used when rendering templates (defaults to --revision or the release path basename)")
+    .option("--revision <sha>", "Revision used when rendering templates (defaults to --release-id)")
     .option("--json", "Output machine-readable JSON")
     .action(async (options) => {
       let configPath
@@ -225,6 +275,10 @@ export async function runCli(argv) {
       } else {
         checks.push({detail: `valid: ${config.processes.length} ${config.processes.length === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}`, name: "config", ok: true})
         checks.push(...await runEnvironmentChecks(config))
+
+        if (options.releasePath) {
+          checks.push(...await runReleaseChecks(config, {releaseId: options.releaseId, releasePath: options.releasePath, revision: options.revision}))
+        }
       }
 
       const failed = checks.filter((check) => !check.ok).length
@@ -268,9 +322,271 @@ export async function runCli(argv) {
       console.log(formatLogSources(sources, options.process))
     })
 
+  program
+    .command("events")
+    .description("Print recent structured daemon events (deploys, switches, stops, crashes, restarts, failures).")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--limit <count>", "Show only the most recent <count> events")
+    .option("--json", "Output machine-readable JSON")
+    .action(async (options) => {
+      let limit
+
+      if (options.limit !== undefined) {
+        limit = Number(options.limit)
+
+        if (!Number.isInteger(limit) || limit < 1) {
+          console.error("--limit must be a positive integer.")
+          process.exitCode = 1
+          return
+        }
+      }
+
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {command: "events", limit},
+        path: config.control.path
+      })
+      const events = /** @type {import("./event-log.js").DaemonEvent[]} */ (response.events ?? [])
+
+      if (options.json) {
+        console.log(JSON.stringify(events, null, 2))
+        return
+      }
+
+      console.log(formatEvents(events))
+    })
+
+  program
+    .command("recover")
+    .description("Stop orphaned processes left by a crashed daemon (reads statePath; lists them unless --force).")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--force", "Stop the orphaned processes; without it, recover only lists them")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const result = await recoverOrphans({config, force: Boolean(options.force)})
+
+      if ("error" in result) {
+        console.error(result.error)
+        process.exitCode = 1
+        return
+      }
+
+      if (result.remaining.length > 0) {
+        console.error(formatRecoverResult(result))
+        process.exitCode = 1
+        return
+      }
+
+      console.log(formatRecoverResult(result))
+    })
+
+  program
+    .command("completion")
+    .description("Print a shell completion script. Enable with: source <(rollbridge completion <shell>)")
+    .argument("<shell>", "Shell to generate completion for (bash or zsh)")
+    .action((shell) => {
+      if (shell !== "bash" && shell !== "zsh") {
+        console.error(`Unsupported shell "${shell}". Supported shells: bash, zsh.`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log(generateCompletionScript(program, shell))
+    })
+
   await program.parseAsync(argv)
 }
 
+/**
+ * @typedef {import("./recover.js").OrphanProcess} OrphanProcess
+ */
+
+/**
+ * Formats the result of a recover run (the report case, not the error case).
+ * @param {{cleared: boolean, forced: boolean, orphans: OrphanProcess[], remaining: OrphanProcess[]}} result - Recover report.
+ * @returns {string} Human-readable summary.
+ */
+export function formatRecoverResult(result) {
+  if (result.orphans.length === 0) {
+    return result.forced ? "No orphaned processes found; cleared the state file." : "No orphaned processes found."
+  }
+
+  if (!result.forced) {
+    return [
+      `Found ${orphanCountLabel(result.orphans.length)} (run with --force to stop):`,
+      ...listOrphans(result.orphans),
+      "Review the list first — a recycled pid could be an unrelated process."
+    ].join("\n")
+  }
+
+  const remainingPids = new Set(result.remaining.map((orphan) => orphan.pid))
+  const stopped = result.orphans.filter((orphan) => !remainingPids.has(orphan.pid))
+  const lines = []
+
+  if (stopped.length > 0) lines.push(`Stopped ${orphanCountLabel(stopped.length)}:`, ...listOrphans(stopped))
+
+  if (result.remaining.length > 0) {
+    lines.push(
+      `Could not stop ${orphanCountLabel(result.remaining.length)} — still running (check permissions/ownership):`,
+      ...listOrphans(result.remaining),
+      "Left the state file in place so you can investigate and re-run recover."
+    )
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * @param {number} count - Number of orphaned processes.
+ * @returns {string} A pluralized label such as "1 orphaned process" or "3 orphaned processes".
+ */
+function orphanCountLabel(count) {
+  return `${count} orphaned process${count === 1 ? "" : "es"}`
+}
+
+/**
+ * @param {OrphanProcess[]} orphans - Orphans to render.
+ * @returns {string[]} One indented line per orphan.
+ */
+function listOrphans(orphans) {
+  return orphans.map((orphan) => `  ${orphan.id} (pid ${orphan.pid}${orphan.releaseId ? `, release ${orphan.releaseId}` : ""})`)
+}
+
+/**
+ * @typedef {{name: string, options: string[], valueOptions: string[]}} CompletionCommand
+ */
+
+/**
+ * Builds a shell completion script by introspecting the CLI's commands and options,
+ * so completions never drift from the actual command surface.
+ * @param {import("commander").Command} program - Configured CLI program.
+ * @param {"bash" | "zsh"} shell - Target shell.
+ * @returns {string} A sourceable completion script.
+ */
+export function generateCompletionScript(program, shell) {
+  const commands = describeCommands(program)
+
+  return shell === "zsh" ? zshCompletionScript(commands) : bashCompletionScript(commands)
+}
+
+/**
+ * @param {import("commander").Command} program - Configured CLI program.
+ * @returns {CompletionCommand[]} Each command's name, long option flags, and value-taking option flags.
+ */
+function describeCommands(program) {
+  return program.commands.map((command) => {
+    /** @type {string[]} */
+    const options = []
+    /** @type {string[]} */
+    const valueOptions = []
+
+    for (const option of command.options) {
+      if (!option.long) continue
+
+      options.push(option.long)
+      if (option.required || option.optional) valueOptions.push(option.long)
+    }
+
+    return {name: command.name(), options, valueOptions}
+  })
+}
+
+/**
+ * @param {CompletionCommand[]} commands - Command descriptors.
+ * @returns {string} A bash completion script.
+ */
+function bashCompletionScript(commands) {
+  const names = commands.map((command) => command.name).join(" ")
+  const branches = commands
+    .map((command) => `    ${command.name})\n      opts="${command.options.join(" ")}"\n      values="${command.valueOptions.join(" ")}"\n      ;;`)
+    .join("\n")
+
+  return `# rollbridge bash completion
+# Enable with: source <(rollbridge completion bash)
+_rollbridge() {
+  local cur prev cmd opts values i
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  cmd=""
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    case "\${COMP_WORDS[i]}" in
+      -*) ;;
+      *) cmd="\${COMP_WORDS[i]}"; break ;;
+    esac
+  done
+
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${names}" -- "$cur") )
+    return
+  fi
+
+  opts=""
+  values=""
+  case "$cmd" in
+${branches}
+  esac
+
+  if [[ -n "$values" && " $values " == *" $prev "* ]]; then
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return
+  fi
+
+  COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+}
+complete -F _rollbridge rollbridge
+`
+}
+
+/**
+ * @param {CompletionCommand[]} commands - Command descriptors.
+ * @returns {string} A zsh completion script.
+ */
+function zshCompletionScript(commands) {
+  const names = commands.map((command) => command.name).join(" ")
+  const branches = commands
+    .map((command) => `    ${command.name}) compadd -- ${command.options.join(" ")} ;;`)
+    .join("\n")
+
+  return `#compdef rollbridge
+# rollbridge zsh completion
+# Enable with: source <(rollbridge completion zsh)
+_rollbridge() {
+  local -a commands
+  commands=(${names})
+
+  if (( CURRENT == 2 )); then
+    compadd -- $commands
+    return
+  fi
+
+  case "\${words[2]}" in
+${branches}
+  esac
+}
+compdef _rollbridge rollbridge
+`
+}
+
+/**
+ * Formats structured daemon events as human-readable lines.
+ * @param {import("./event-log.js").DaemonEvent[]} events - Recent events, oldest first.
+ * @returns {string} One line per event, or a placeholder when empty.
+ */
+export function formatEvents(events) {
+  if (events.length === 0) return "No events recorded yet."
+
+  return events
+    .map((event) => {
+      const data = Object.keys(event.data).length > 0 ? ` ${JSON.stringify(event.data)}` : ""
+
+      return `${event.at}  ${event.message}${data}`
+    })
+    .join("\n")
+}
+
 /**
  * @typedef {{id: string, logs: import("./managed-process.js").ManagedProcessLog[], source: string}} LogSource
  */

package/src/config.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import fs from "node:fs/promises"
+import os from "node:os"
 import path from "node:path"
 import {pathToFileURL} from "node:url"
 
@@ -9,11 +10,14 @@ import {pathToFileURL} from "node:url"
  * @typedef {{from: number, to: number}} PortRange
  * @typedef {{path: string, startDelayMs: number, timeoutMs: number, intervalMs: number}} HealthConfig
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
- * @typedef {{mode?: number, path: string}} ControlConfig
+ * @typedef {{backoffFactor: number, maxDelayMs: number, maxRestarts: number | undefined, windowMs: number}} RestartConfig
+ * @typedef {{checkIntervalMs: number, limitBytes: number, warnBytes: number}} MemoryConfig
+ * @typedef {{drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, stopCommand?: string}} LifecycleConfig
+ * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
+ * @typedef {{group?: number | string, mode?: number, owner?: number | string, path: string}} ControlConfig
  * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
  * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
- * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig}} RollbridgeConfig
+ * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -124,15 +128,18 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   const processesSource = arrayAt(source.processes, "processes", issues)
   const proxy = normalizeProxy(proxySource, issues)
   const control = {
+    group: normalizeControlPrincipal(controlSource.group, "control.group", issues),
     mode: normalizeSocketMode(controlSource.mode, "control.mode", issues),
+    owner: normalizeControlPrincipal(controlSource.owner, "control.owner", issues),
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
   const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
+  const statePath = source.statePath === undefined || source.statePath === null ? undefined : normalizeString(source.statePath, "statePath", issues)
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, processes, proxy, releaseRetention}, issues}
+  return {config: {application, control, processes, proxy, releaseRetention, statePath}, issues}
 }
 
 /**
@@ -175,7 +182,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restartDelayMs: 1000}
+    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
   }
 
   const source = value
@@ -187,13 +194,170 @@ function normalizeProcess(value, index, proxy, issues) {
     gracefulStopMs: normalizeNumber(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, issues, {default: proxy.forceStopTimeoutMs}),
     health: normalizeHealth(source.health, `processes[${index}].health`, proxy, issues),
     id: normalizeString(source.id, `processes[${index}].id`, issues),
+    lifecycle: normalizeLifecycle(source.lifecycle, `processes[${index}].lifecycle`, issues),
+    memory: normalizeMemory(source.memory, `processes[${index}].memory`, issues),
+    nonBlockingDrain: normalizeBoolean(source.nonBlockingDrain, `processes[${index}].nonBlockingDrain`, issues, false),
     outputLines: normalizeOutputLines(source.outputLines, `processes[${index}].outputLines`, issues),
     policy: normalizePolicy(source.policy, `processes[${index}].policy`, issues),
     port: normalizePortRange(source.port, `processes[${index}].port`, issues),
-    restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000})
+    replicas: normalizeReplicas(source.replicas, `processes[${index}].replicas`, issues),
+    restart: normalizeRestart(source.restart, `processes[${index}].restart`, issues),
+    restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000}),
+    stopSignal: normalizeStopSignal(source.stopSignal, `processes[${index}].stopSignal`, issues)
   }
 }
 
+/**
+ * @returns {RestartConfig} Default restart policy: unlimited restarts with a constant delay.
+ */
+function defaultRestartConfig() {
+  return {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}
+}
+
+/**
+ * @param {JsonValue} value - Raw restart policy.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {RestartConfig} Normalized restart policy.
+ */
+function normalizeRestart(value, key, issues) {
+  if (value === undefined || value === null) return defaultRestartConfig()
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with maxRestarts, windowMs, backoffFactor, and maxDelayMs.`, message: `${key} must be an object`})
+
+    return defaultRestartConfig()
+  }
+
+  const windowMs = normalizeNumber(value.windowMs, `${key}.windowMs`, issues, {default: 0})
+  const maxDelayMs = normalizeNumber(value.maxDelayMs, `${key}.maxDelayMs`, issues, {default: 0})
+
+  return {
+    backoffFactor: normalizeBackoffFactor(value.backoffFactor, `${key}.backoffFactor`, issues),
+    maxDelayMs: nonNegativeOrDefault(maxDelayMs, `${key}.maxDelayMs`, issues, 0, false),
+    maxRestarts: normalizeMaxRestarts(value.maxRestarts, `${key}.maxRestarts`, issues),
+    windowMs: nonNegativeOrDefault(windowMs, `${key}.windowMs`, issues, 0, false)
+  }
+}
+
+/**
+ * @param {JsonValue} value - Raw maximum restart count.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | undefined} Restart cap, or undefined for unlimited restarts.
+ */
+function normalizeMaxRestarts(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    issues.push({fix: `Set ${key} to a non-negative integer (0 disables automatic restarts), or omit it for unlimited restarts.`, message: `${key} must be a non-negative integer`})
+
+    return undefined
+  }
+
+  return value
+}
+
+/**
+ * @param {JsonValue} value - Raw backoff factor.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Backoff multiplier (>= 1; 1 keeps a constant delay).
+ */
+function normalizeBackoffFactor(value, key, issues) {
+  const factor = normalizeNumber(value, key, issues, {default: 1})
+
+  if (factor < 1) {
+    issues.push({fix: `Set ${key} to a number >= 1 (1 keeps a constant delay; 2 doubles the delay each restart).`, message: `${key} must be a number greater than or equal to 1`})
+
+    return 1
+  }
+
+  return factor
+}
+
+/**
+ * @param {JsonValue} value - Raw memory supervision config.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {MemoryConfig | undefined} Normalized memory config, or undefined when monitoring is off.
+ */
+function normalizeMemory(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with limitBytes (and optionally warnBytes, checkIntervalMs), or omit it to disable memory supervision.`, message: `${key} must be an object`})
+
+    return undefined
+  }
+
+  const limitBytes = normalizeNumber(value.limitBytes, `${key}.limitBytes`, issues, {default: 0})
+  const warnBytes = normalizeNumber(value.warnBytes, `${key}.warnBytes`, issues, {default: 0})
+  const checkIntervalMs = normalizeNumber(value.checkIntervalMs, `${key}.checkIntervalMs`, issues, {default: 5000})
+
+  if (!Number.isInteger(limitBytes) || limitBytes <= 0) {
+    issues.push({fix: `Set ${key}.limitBytes to a positive integer number of bytes, e.g. 536870912 (512 MiB).`, message: `${key}.limitBytes must be a positive integer`})
+  }
+
+  if (!Number.isInteger(warnBytes) || warnBytes < 0) {
+    issues.push({fix: `Set ${key}.warnBytes to a non-negative integer number of bytes below limitBytes, e.g. 402653184 (384 MiB).`, message: `${key}.warnBytes must be a non-negative integer`})
+  }
+
+  if (checkIntervalMs <= 0) {
+    issues.push({fix: `Set ${key}.checkIntervalMs to a positive number of milliseconds, e.g. 5000.`, message: `${key}.checkIntervalMs must be a positive number`})
+  }
+
+  return {checkIntervalMs, limitBytes, warnBytes}
+}
+
+/**
+ * @param {JsonValue} value - Raw lifecycle config.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {LifecycleConfig} Normalized lifecycle hooks (no commands and a 0 drain by default).
+ */
+function normalizeLifecycle(value, key, issues) {
+  if (value === undefined || value === null) return {drainTimeoutMs: 0}
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with optional quietCommand, drainCommand, stopCommand, and drainTimeoutMs.`, message: `${key} must be an object`})
+
+    return {drainTimeoutMs: 0}
+  }
+
+  const drainTimeoutMs = normalizeNumber(value.drainTimeoutMs, `${key}.drainTimeoutMs`, issues, {default: 0})
+  /** @type {LifecycleConfig} */
+  const lifecycle = {drainTimeoutMs: nonNegativeOrDefault(drainTimeoutMs, `${key}.drainTimeoutMs`, issues, 0, false)}
+
+  if (value.quietCommand !== undefined) lifecycle.quietCommand = normalizeString(value.quietCommand, `${key}.quietCommand`, issues)
+  if (value.drainCommand !== undefined) lifecycle.drainCommand = normalizeString(value.drainCommand, `${key}.drainCommand`, issues)
+  if (value.stopCommand !== undefined) lifecycle.stopCommand = normalizeString(value.stopCommand, `${key}.stopCommand`, issues)
+
+  if (lifecycle.drainCommand !== undefined && lifecycle.drainTimeoutMs <= 0) {
+    issues.push({fix: `Set ${key}.drainTimeoutMs to a positive number to bound ${key}.drainCommand; with 0 the drain step is skipped and the command never runs.`, message: `${key}.drainCommand requires a positive ${key}.drainTimeoutMs`})
+  }
+
+  return lifecycle
+}
+
+/**
+ * @param {JsonValue} value - Raw stop signal.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {string} The graceful-stop signal name (default "SIGTERM").
+ */
+function normalizeStopSignal(value, key, issues) {
+  if (value === undefined || value === null) return "SIGTERM"
+
+  if (typeof value === "string" && Object.prototype.hasOwnProperty.call(os.constants.signals, value)) {
+    return value
+  }
+
+  issues.push({fix: `Set ${key} to a signal name such as "SIGTERM", "SIGINT", or "SIGQUIT".`, message: `${key} must be a valid signal name`})
+
+  return "SIGTERM"
+}
+
 /**
  * @param {JsonValue} value - Raw output retention value.
  * @param {string} key - Config key.
@@ -212,6 +376,40 @@ function normalizeOutputLines(value, key, issues) {
   return outputLines
 }
 
+/**
+ * @param {JsonValue} value - Raw replica count.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Number of replicas to run (default 1).
+ */
+function normalizeReplicas(value, key, issues) {
+  const replicas = normalizeNumber(value, key, issues, {default: 1})
+
+  if (!Number.isInteger(replicas) || replicas < 1) {
+    issues.push({fix: `Set ${key} to a positive integer number of replicas, e.g. 1 or 4.`, message: `${key} must be a positive integer`})
+
+    return 1
+  }
+
+  return replicas
+}
+
+/**
+ * @param {JsonValue} value - Raw boolean value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @param {boolean} fallback - Default when unset.
+ * @returns {boolean} The boolean value, or the fallback when unset/invalid.
+ */
+function normalizeBoolean(value, key, issues, fallback) {
+  if (value === undefined || value === null) return fallback
+  if (typeof value === "boolean") return value
+
+  issues.push({fix: `Set ${key} to true or false.`, message: `${key} must be a boolean`})
+
+  return fallback
+}
+
 /**
  * @param {Record<string, JsonValue>} source - Raw release retention config.
  * @param {ConfigIssue[]} issues - Issue collector.
@@ -268,6 +466,26 @@ function normalizeSocketMode(value, key, issues) {
   return undefined
 }
 
+/**
+ * @param {JsonValue} value - Raw owner/group value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | string | undefined} A numeric id, a name (resolved at bind time), or undefined when unset.
+ */
+function normalizeControlPrincipal(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value) && value >= 0) return value
+  } else if (typeof value === "string" && value.length > 0) {
+    return value
+  }
+
+  issues.push({fix: `Set ${key} to a non-negative integer id or a user/group name, e.g. "deploy".`, message: `${key} must be a non-negative integer id or a name`})
+
+  return undefined
+}
+
 /**
  * Validates cross-process rules: unique ids, exactly one proxied process, and proxied ports.
  * @param {ProcessConfig[]} processes - Normalized processes.
@@ -285,6 +503,22 @@ function validateProcessSet(processes, issues) {
     }
 
     seenIds.add(processConfig.id)
+
+    if (processConfig.id.includes("#")) {
+      issues.push({fix: `Remove "#" from the process id "${processConfig.id}"; it is reserved for replica instance ids (e.g. "${processConfig.id.replace(/#/g, "")}#0").`, message: `Process id "${processConfig.id}" must not contain "#"`})
+    }
+
+    if (processConfig.replicas > 1 && (processConfig.policy !== "companion" || processConfig.port)) {
+      issues.push({fix: `Run replicas (${processConfig.replicas}) only on a companion process without a port; "${processConfig.id}" is ${processConfig.policy}${processConfig.port ? " with a port" : ""}.`, message: `Process "${processConfig.id}" can only set replicas > 1 on a companion process without a port`})
+    }
+
+    if (processConfig.nonBlockingDrain && processConfig.policy !== "companion") {
+      issues.push({fix: `Set nonBlockingDrain only on a companion process; "${processConfig.id}" is ${processConfig.policy}.`, message: `Process "${processConfig.id}" can only set nonBlockingDrain on a companion process`})
+    }
+
+    if (processConfig.lifecycle.stopCommand && processConfig.stopSignal !== "SIGTERM") {
+      issues.push({fix: `Drop the custom stopSignal "${processConfig.stopSignal}" or lifecycle.stopCommand from "${processConfig.id}": with a stopCommand set, Rollbridge runs it to stop the process instead of sending stopSignal, so the signal is never used.`, message: `Process "${processConfig.id}" sets both lifecycle.stopCommand and a custom stopSignal, but stopCommand replaces stopSignal`})
+    }
   }
 
   const proxiedProcesses = processes.filter((processConfig) => processConfig.policy === "proxied")