@devrouter/cli 0.0.28 → 0.0.30

package/README.md

@@ -113,6 +113,11 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 The current `devrouter repo devcontainer write` scaffold is intentionally narrow:
 Node + pnpm + Postgres. Other package managers stop with a JSON diagnostic
 instead of writing files that would need manual repair.
+The generated image extracts `devrouter-process` from the exact Devrouter
+package tarball without installing the CLI dependency tree. Its `post-start.sh`
+uses that helper for locked, owned, idempotent background startup. Application
+commands and environment setup remain repository-owned; route readiness remains
+part of `devrouter workspace ensure`.
 Use `devrouter repo devcontainer verify --json` for read-only PR evidence; add
 `--live --yes` only after the devcontainer is running and route probes should
 mutate local route state.

package/bin/devrouter-process

@@ -0,0 +1,274 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  devrouter-process ensure --name <name> --match <regex> [options] -- <command> [args...]
+
+Options:
+  --fingerprint <value>  Runtime identity. Defaults to command plus workspace identity.
+  --log <path>           Log file. Defaults to /tmp/devrouter-process-<name>.log.
+EOF
+}
+
+die() {
+  echo "[devrouter-process] $*" >&2
+  exit 1
+}
+
+require_value() {
+  [ "$#" -ge 2 ] || die "$1 requires a value."
+}
+
+[ "${1:-}" = "ensure" ] || {
+  usage >&2
+  exit 1
+}
+shift
+
+name=""
+process_match=""
+fingerprint=""
+log_file=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --name)
+      require_value "$@"
+      name="$2"
+      shift 2
+      ;;
+    --match)
+      require_value "$@"
+      process_match="$2"
+      shift 2
+      ;;
+    --fingerprint)
+      require_value "$@"
+      fingerprint="$2"
+      shift 2
+      ;;
+    --log)
+      require_value "$@"
+      log_file="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    *)
+      die "Unknown option: $1"
+      ;;
+  esac
+done
+
+[[ "$name" =~ ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ ]] || die "--name must be a safe identifier."
+[ -n "$process_match" ] || die "--match is required."
+[ "$#" -gt 0 ] || die "A command is required after --."
+[ -r "/proc/$$/environ" ] || die "Linux /proc process metadata is required."
+
+for tool in awk cksum flock grep pgrep ps setsid tr; do
+  command -v "$tool" >/dev/null 2>&1 || die "Required command is unavailable: $tool"
+done
+
+match_status=0
+pgrep -f -- "$process_match" >/dev/null 2>&1 || match_status=$?
+[ "$match_status" -le 1 ] || die "--match is not a valid process regular expression."
+
+if [ -z "$fingerprint" ]; then
+  fingerprint="$({
+    printf '%s\0' "$name" "${WORKSPACE:-}" "${DEVROUTER_WORKSPACE:-}"
+    printf '%s\0' "$@"
+  } | cksum | awk '{print $1 "-" $2}')"
+fi
+[[ "$fingerprint" =~ ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$ ]] || die "--fingerprint must be a safe identifier."
+
+state_dir="${DEVROUTER_PROCESS_STATE_DIR:-/tmp}"
+state_file="$state_dir/devrouter-process-$name.state"
+lock_file="$state_file.lock"
+log_file="${log_file:-/tmp/devrouter-process-$name.log}"
+lock_timeout="${DEVROUTER_PROCESS_LOCK_TIMEOUT_SECONDS:-30}"
+term_timeout="${DEVROUTER_PROCESS_TERM_TIMEOUT_SECONDS:-15}"
+kill_timeout="${DEVROUTER_PROCESS_KILL_TIMEOUT_SECONDS:-5}"
+
+process_alive() {
+  local pid="$1"
+  local state
+
+  kill -0 "$pid" 2>/dev/null || return 1
+  state="$(ps -o stat= -p "$pid" 2>/dev/null | tr -d ' ')"
+  [[ "$state" != Z* ]]
+}
+
+process_owned() {
+  local pid="$1"
+  local pgid="$2"
+  local expected_fingerprint="$3"
+  local actual_pgid
+
+  [ -r "/proc/$pid/environ" ] || return 1
+  actual_pgid="$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ')"
+  [ "$actual_pgid" = "$pgid" ] || return 1
+  [ "$pgid" = "$pid" ] || return 1
+  tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
+    grep -Fqx "DEVROUTER_PROCESS_NAME=$name" || return 1
+  tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
+    grep -Fqx "DEVROUTER_PROCESS_FINGERPRINT=$expected_fingerprint"
+}
+
+process_group_alive() {
+  local pgid="$1"
+
+  ps -eo pgid=,stat= | awk -v expected="$pgid" '
+    $1 == expected && $2 !~ /^Z/ { found = 1 }
+    END { exit(found ? 0 : 1) }
+  '
+}
+
+is_self_or_ancestor() {
+  local candidate="$1"
+  local current="$$"
+
+  while [[ "$current" =~ ^[1-9][0-9]*$ ]]; do
+    [ "$candidate" = "$current" ] && return 0
+    [ "$current" -le 1 ] && break
+    current="$(ps -o ppid= -p "$current" 2>/dev/null | tr -d ' ')"
+  done
+  return 1
+}
+
+is_helper_process() {
+  local candidate="$1"
+
+  [ -r "/proc/$candidate/cmdline" ] || return 1
+  tr '\0' '\n' <"/proc/$candidate/cmdline" 2>/dev/null | grep -Fqx "$0"
+}
+
+marked_process_exists() {
+  local environ
+  local pid
+
+  for environ in /proc/[1-9]*/environ; do
+    [ -r "$environ" ] || continue
+    pid="${environ#/proc/}"
+    pid="${pid%/environ}"
+    process_alive "$pid" || continue
+    is_self_or_ancestor "$pid" && continue
+    if tr '\0' '\n' <"$environ" 2>/dev/null | grep -Fqx "DEVROUTER_PROCESS_NAME=$name"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+matching_process_exists() {
+  local pid
+
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    [ -d "/proc/$pid" ] || continue
+    process_alive "$pid" || continue
+    is_self_or_ancestor "$pid" && continue
+    is_helper_process "$pid" && continue
+    return 0
+  done < <(pgrep -f -- "$process_match" 2>/dev/null || true)
+  return 1
+}
+
+unknown_process_exists() {
+  marked_process_exists || matching_process_exists
+}
+
+stop_process_group() {
+  local pid="$1"
+  local pgid="$2"
+  local attempt
+
+  kill -TERM -- "-$pgid" 2>/dev/null || true
+  for ((attempt = 1; attempt <= term_timeout; attempt += 1)); do
+    if ! process_group_alive "$pgid"; then
+      wait "$pid" 2>/dev/null || true
+      return 0
+    fi
+    sleep 1
+  done
+
+  kill -KILL -- "-$pgid" 2>/dev/null || true
+  for ((attempt = 1; attempt <= kill_timeout; attempt += 1)); do
+    if ! process_group_alive "$pgid"; then
+      wait "$pid" 2>/dev/null || true
+      return 0
+    fi
+    sleep 1
+  done
+
+  echo "[devrouter-process] Could not stop owned process group $pgid." >&2
+  return 1
+}
+
+mkdir -p "$state_dir" "$(dirname "$log_file")"
+exec 9>"$lock_file"
+flock -w "$lock_timeout" 9 || die "Timed out waiting for the '$name' process lock."
+
+pid=""
+pgid=""
+stored_fingerprint=""
+extra=""
+
+if [ -f "$state_file" ]; then
+  read -r pid pgid stored_fingerprint extra <"$state_file" || true
+  if [ -z "$stored_fingerprint" ] ||
+    ! [[ "$pid" =~ ^[1-9][0-9]*$ ]] ||
+    ! [[ "$pgid" =~ ^[1-9][0-9]*$ ]] ||
+    [ -n "$extra" ]; then
+    if unknown_process_exists; then
+      die "Invalid state while an unowned '$name' process is running; refusing to start or kill it."
+    fi
+    rm -f "$state_file"
+  elif process_alive "$pid"; then
+    process_owned "$pid" "$pgid" "$stored_fingerprint" ||
+      die "State points at an unowned '$name' process; refusing to kill it."
+    if [ "$stored_fingerprint" = "$fingerprint" ]; then
+      echo "[devrouter-process] '$name' already matches this runtime (PID $pid)."
+      exit 0
+    fi
+
+    echo "[devrouter-process] '$name' runtime changed; restarting owned process group $pgid."
+    stop_process_group "$pid" "$pgid"
+    rm -f "$state_file"
+  else
+    rm -f "$state_file"
+  fi
+fi
+
+unknown_process_exists &&
+  die "Found an unowned '$name' process; refusing to start a duplicate or kill it."
+
+echo "[devrouter-process] Starting '$name' (logs: $log_file)..."
+env DEVROUTER_PROCESS_NAME="$name" \
+  DEVROUTER_PROCESS_FINGERPRINT="$fingerprint" \
+  setsid "$@" 9>&- >"$log_file" 2>&1 </dev/null &
+pid=$!
+pgid="$pid"
+
+for attempt in {1..10}; do
+  if process_owned "$pid" "$pgid" "$fingerprint"; then
+    printf '%s %s %s\n' "$pid" "$pgid" "$fingerprint" >"$state_file.tmp.$BASHPID"
+    mv "$state_file.tmp.$BASHPID" "$state_file"
+    echo "[devrouter-process] '$name' started (PID $pid)."
+    exit 0
+  fi
+  if ! process_alive "$pid"; then
+    die "'$name' exited during startup; see $log_file."
+  fi
+  sleep 1
+done
+
+stop_process_group "$pid" "$pgid" || true
+die "Could not verify ownership of '$name'; stopped it."

package/dist/devrouter.js

@@ -1787,7 +1787,7 @@ function loadRepoConfig(repoPath) {
   const config = parseConfig(parsed ?? {}, configPath);
   const requiredVersion = config.devrouter?.version;
   if (requiredVersion && !hasWarnedVersionMismatch) {
-    const cliVersion = true ? "0.0.28" : "0.0.0-dev";
+    const cliVersion = true ? "0.0.30" : "0.0.0-dev";
     if (cliVersion !== "0.0.0-dev" && compareSemver(requiredVersion, cliVersion) > 0) {
       hasWarnedVersionMismatch = true;
       process.stderr.write(
@@ -4390,7 +4390,7 @@ async function buildDoctorReport(options = {}) {
       const config = runtimeConfig.config;
       loadedConfig = config;
       loadedWorkspace = runtimeConfig.workspace;
-      const cliVersion = true ? "0.0.28" : "0.0.0-dev";
+      const cliVersion = true ? "0.0.30" : "0.0.0-dev";
       const configVersion = config.devrouter?.version;
       if (configVersion && cliVersion !== "0.0.0-dev" && compareSemver(configVersion, cliVersion) > 0) {
         addCheck(checks, {
@@ -5984,27 +5984,39 @@ function majorVersion(value, fallback) {
 function devrouterVersion(value) {
   return value && /^\d+\.\d+\.\d+$/.test(value) ? value : DEFAULT_DEVROUTER_VERSION;
 }
-function inferDevScript(repo) {
+function escapeExtendedRegex(value) {
+  return value.replace(/[\\.^$|?*+()[\]{}]/g, "\\$&");
+}
+function inferDevProcess(repo) {
   const script = repo.scripts.find((entry) => entry.name === "dev") ?? repo.scripts.find((entry) => entry.name.endsWith(":dev"));
-  if (!script) {
-    return "pnpm dev";
-  }
-  return script.name === "dev" ? "pnpm dev" : `pnpm run -- ${shellSingleQuote(script.name)}`;
+  const scriptName = script?.name ?? "dev";
+  return {
+    command: scriptName === "dev" ? "pnpm dev" : `pnpm run -- ${shellSingleQuote(scriptName)}`,
+    match: `pnpm(\\.cjs)? .*${escapeExtendedRegex(scriptName)}`
+  };
 }
 function inferPort2(repo) {
   return repo.apps.find((app) => app.port)?.port ?? 3e3;
 }
-function renderDockerfile(nodeMajor, pnpmVersion) {
+function renderDockerfile(nodeMajor, pnpmVersion, version) {
   const pnpmPackageSpec = `pnpm@${pnpmVersion}`;
+  const devrouterPackageSpec = `@devrouter/cli@${version}`;
+  const devrouterTarball = `devrouter-cli-${version}.tgz`;
   return `# ${MANAGED_MARKER}
 FROM node:${nodeMajor}-bookworm-slim
 
 RUN apt-get update \\
-  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl \\
+  && apt-get install -y --no-install-recommends git ca-certificates curl procps openssl tar util-linux \\
   && rm -rf /var/lib/apt/lists/*
 
 RUN npm install -g ${shellSingleQuote(pnpmPackageSpec)}
 
+RUN npm pack --silent ${shellSingleQuote(devrouterPackageSpec)} \\
+  && tar -xzf ${shellSingleQuote(devrouterTarball)} --strip-components=2 \\
+    -C /usr/local/bin package/bin/devrouter-process \\
+  && chmod +x /usr/local/bin/devrouter-process \\
+  && rm ${shellSingleQuote(devrouterTarball)}
+
 WORKDIR /workspaces/app
 `;
 }
@@ -6140,7 +6152,7 @@ fi
 function shellSingleQuote(value) {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
-function renderPostStart(devCommand) {
+function renderPostStart(devProcess) {
   return `#!/usr/bin/env bash
 # ${MANAGED_MARKER}
 set -euo pipefail
@@ -6151,11 +6163,11 @@ set -a
 . .devcontainer/devcontainer.env
 set +a
 
-if pgrep -f ${shellSingleQuote(devCommand)} >/dev/null 2>&1; then
-  exit 0
-fi
-
-setsid bash -lc ${shellSingleQuote(devCommand)} >/tmp/devrouter-app.log 2>&1 </dev/null &
+devrouter-process ensure \\
+  --name app \\
+  --match ${shellSingleQuote(devProcess.match)} \\
+  --log /tmp/devrouter-app.log \\
+  -- bash -lc ${shellSingleQuote(devProcess.command)}
 `;
 }
 function renderDevrouter(projectName, port, version) {
@@ -6272,7 +6284,7 @@ function plannedFiles(repoPath, version) {
   const nodeMajor = majorVersion(repo.node?.version, "24");
   const pnpmVersion = repo.packageManager?.name === "pnpm" && repo.packageManager.version ? repo.packageManager.version : DEFAULT_PNPM_VERSION;
   const port = inferPort2(repo);
-  const devCommand = inferDevScript(repo);
+  const devProcess = inferDevProcess(repo);
   const issues = packageManagerIssues(repo);
   return {
     projectName,
@@ -6280,7 +6292,7 @@ function plannedFiles(repoPath, version) {
     files: [
       {
         relativePath: ".devcontainer/Dockerfile",
-        content: renderDockerfile(nodeMajor, pnpmVersion)
+        content: renderDockerfile(nodeMajor, pnpmVersion, version)
       },
       { relativePath: ".devcontainer/docker-compose.yml", content: renderCompose(projectName) },
       {
@@ -6304,7 +6316,7 @@ function plannedFiles(repoPath, version) {
       },
       {
         relativePath: ".devcontainer/post-start.sh",
-        content: renderPostStart(devCommand),
+        content: renderPostStart(devProcess),
         executable: true
       },
       { relativePath: ".devcontainer/README.md", content: renderReadme(projectName) },
@@ -8189,6 +8201,7 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
           await waitForContainerPreflight(repoPath, commonDir, workspace, upstreamHosts, 0);
         } catch {
           await recreateAndWait();
+          recreated = true;
         }
       }
       ensureRouterFiles();
@@ -8205,8 +8218,19 @@ async function workspaceEnsure(requestedRepoPath, options = {}) {
         }
       }
       startRouterStack();
-      replaceHostRoutesForRepo(repoPath, routeInputs(repoPath, workspace, apps));
-      await waitForHttpRoutes(apps, options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS);
+      const routes = routeInputs(repoPath, workspace, apps);
+      replaceHostRoutesForRepo(repoPath, routes);
+      try {
+        await waitForHttpRoutes(apps, options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS);
+      } catch (error) {
+        replaceHostRoutesForRepo(repoPath, []);
+        if (!hadExactDevpod || recreated) {
+          throw error;
+        }
+        await recreateAndWait();
+        replaceHostRoutesForRepo(repoPath, routes);
+        await waitForHttpRoutes(apps, options.httpTimeoutMs ?? DEFAULT_READINESS_TIMEOUT_MS);
+      }
       const urls = apps.map(
         (app) => app.protocol === "tcp" ? `${app.tcpProtocol}://${app.host}:${String(TCP_PROTOCOL_REGISTRY[app.tcpProtocol].port)}` : routeUrl3(app.host)
       );
@@ -8553,7 +8577,7 @@ var init_version = __esm({
 
 // src/cli.ts
 var import_commander = require("commander");
-var CLI_VERSION = true ? "0.0.28" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.0.30" : "0.0.0-dev";
 var VERSION_FLAGS = /* @__PURE__ */ new Set(["-V", "--version"]);
 function withErrorHandling(action2) {
   return async (...args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devrouter/cli",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Local dev routing CLI with shared Traefik reverse proxy",
   "author": "Roland Schlaefli",
   "homepage": "https://github.com/rschlaefli/devrouter#readme",
@@ -10,6 +10,7 @@
     "url": "https://github.com/rschlaefli/devrouter.git"
   },
   "files": [
+    "bin",
     "dist",
     "upgrade-prompts"
   ],
@@ -18,7 +19,8 @@
     "node": ">=24"
   },
   "bin": {
-    "devrouter": "dist/devrouter.js"
+    "devrouter": "dist/devrouter.js",
+    "devrouter-process": "bin/devrouter-process"
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -42,7 +44,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsx src/cli.ts",
-    "test": "vitest run",
+    "test": "vitest run && pnpm test:process",
+    "test:process": "bash scripts/test-devrouter-process.sh",
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "check:docs-policy": "./scripts/check-docs-policy.sh",

package/upgrade-prompts/0.0.29.md

@@ -0,0 +1,12 @@
+# Upgrade to devrouter 0.0.29
+
+## What changed
+
+`workspace ensure` now uses the one-total-recreate budget for HTTP readiness failures on existing exact workspaces. Routes are removed before recovery, verified after recreation, and removed again if the retry fails. No new CLI flags, config schema, or dependencies.
+
+## Steps
+
+1. Open `.devrouter.yml` and bump `devrouter.version` from `0.0.28` to `0.0.29`.
+2. Run `devrouter -V --repo <repo>` and confirm the reported version is `0.0.29`.
+3. From an existing linked worktree, run `devrouter workspace ensure .`.
+4. Report the route results.

package/upgrade-prompts/0.0.30.md

@@ -0,0 +1,13 @@
+# Upgrade to devrouter 0.0.30
+
+## What changed
+
+Devrouter now ships `devrouter-process ensure`, a Linux devcontainer helper for locked, fingerprinted, process-group-owned application startup. Generated devcontainers extract only this helper from the exact Devrouter package tarball instead of installing the CLI dependency tree or carrying their own PID, locking, and restart implementation. HTTP readiness and the single container-recreate budget remain in `devrouter workspace ensure`.
+
+## Steps
+
+1. Install `@devrouter/cli@0.0.30` on the host and bump `.devrouter.yml` to `devrouter.version: 0.0.30`.
+2. If the repository uses the managed scaffold, run `devrouter repo devcontainer write --dry-run --json`, review the plan, then run `devrouter repo devcontainer write --yes`.
+3. For a custom devcontainer, extract `bin/devrouter-process` from the exact package tarball into its image and replace repository-specific background-process lifecycle code with one `devrouter-process ensure` call. Keep only the application's command and environment setup in the repository.
+4. Rebuild or recreate the devcontainer so the helper is installed in the image.
+5. From a linked worktree, run `devrouter workspace ensure .` twice and confirm the second run reuses both the container and managed process.