@wdyy/skills 0.1.6 → 0.1.8

package/.well-known/skills/wdyy-deployment-standard/templates/deploy.sh.template

@@ -3,6 +3,8 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
 SCRIPT_PATH="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
+CHECKSUM_TOOL=
+BUILD_LOCK=
 
 fail() {
   echo "$*" >&2
@@ -10,10 +12,14 @@ fail() {
 }
 
 usage() {
-  echo "usage: ./deploy.sh build|start|stop|restart|status|rollback <version>" >&2
+  echo "usage: ./deploy.sh build|start|replace|restart|stop|remove|status|rollback <version>" >&2
   exit 2
 }
 
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
 assert_version() {
   [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || fail "version must match YYYYMMDD-NNN"
 }
@@ -24,27 +30,129 @@ assert_port() {
   (( value >= 1 && value <= 65535 )) || fail "$name must be between 1 and 65535"
 }
 
-require_command() {
-  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+reset_configuration() {
+  unset PROJECT_NAME SERVER_PROJECTS_ROOT PROJECT_HTTP_PORT DOCKER_BIND_IP
+  unset FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT
+  unset FRONTEND_BLUE_PORT FRONTEND_GREEN_PORT BACKEND_BLUE_PORT BACKEND_GREEN_PORT
+  unset FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE DATABASE_MIGRATION_MODE
+  unset FRONTEND_DOCKERFILE BACKEND_DOCKERFILE DOCKERIGNORE_FILE
+  unset MIGRATIONS_SOURCE MIGRATION_RUNNER_SOURCE DEPLOY_CONFIG_DIR
+  unset COMPOSE_SOURCE NGINX_SOURCE
+}
+
+is_deployment_key() {
+  case "$1" in
+    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|\
+    PROJECT_NAME|SERVER_PROJECTS_ROOT|PROJECT_HTTP_PORT|DOCKER_BIND_IP|\
+    FRONTEND_BLUE_PORT|FRONTEND_GREEN_PORT|BACKEND_BLUE_PORT|BACKEND_GREEN_PORT|\
+    FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE|DATABASE_MIGRATION_MODE|\
+    FRONTEND_DOCKERFILE|BACKEND_DOCKERFILE|DOCKERIGNORE_FILE|MIGRATIONS_SOURCE|MIGRATION_RUNNER_SOURCE|\
+    DEPLOY_CONFIG_DIR|COMPOSE_SOURCE|NGINX_SOURCE)
+      return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+is_legacy_configuration_key() {
+  case "$1" in
+    FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|*_HEALTH_URL|*_VERSION_URL)
+      return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+validate_env_permissions() {
+  local file="$1" mode
+  if stat -c '%a' "$file" >/dev/null 2>&1; then
+    mode="$(stat -c '%a' "$file")"
+  else
+    mode="$(stat -f '%Lp' "$file")"
+  fi
+  [[ "$mode" == 400 || "$mode" == 600 ]] || fail "root .env permissions must be 400 or 600; got $mode"
+}
+
+load_dotenv() {
+  local file="$1" raw line key value first last
+  local -a loaded_keys=()
+  [[ -r "$file" ]] || fail "required root environment file is missing: $file"
+  validate_env_permissions "$file"
+  reset_configuration
+  while IFS= read -r raw || [[ -n "$raw" ]]; do
+    line="${raw%$'\r'}"
+    [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+    [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*)$ ]] ||
+      fail "invalid .env line; expected KEY=VALUE"
+    key="${BASH_REMATCH[1]}"
+    value="${BASH_REMATCH[2]}"
+    [[ "$key" != LOG_DIR && "$key" != HOST_LOG_DIR ]] || fail "root .env must not configure log directories"
+    ! is_legacy_configuration_key "$key" || fail "legacy duplicate environment key is forbidden: $key"
+    for loaded_key in "${loaded_keys[@]:-}"; do
+      [[ "$loaded_key" != "$key" ]] || fail "duplicate .env key: $key"
+    done
+    loaded_keys+=("$key")
+    if [[ ${#value} -ge 2 ]]; then
+      first="${value:0:1}"
+      last="${value: -1}"
+      if [[ "$first" == "'" || "$first" == '"' ]]; then
+        [[ "$last" == "$first" ]] || fail "unclosed quoted .env value: $key"
+        value="${value:1:${#value}-2}"
+      fi
+    fi
+    if is_deployment_key "$key"; then
+      printf -v "$key" '%s' "$value"
+      export "$key"
+    fi
+  done < "$file"
 }
 
-load_env_if_present() {
-  local file="$1"
-  if [[ -f "$file" ]]; then
-    set -a
-    # shellcheck disable=SC1090
-    source "$file"
-    set +a
-  fi
+validate_configuration() {
+  local name port seen=" "
+  local -a required=(
+    FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT
+    PROJECT_NAME SERVER_PROJECTS_ROOT PROJECT_HTTP_PORT DOCKER_BIND_IP
+    FRONTEND_BLUE_PORT FRONTEND_GREEN_PORT BACKEND_BLUE_PORT BACKEND_GREEN_PORT
+    FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE DATABASE_MIGRATION_MODE
+  )
+  for name in "${required[@]}"; do
+    [[ -n "${!name:-}" ]] || fail "$name is required in root .env"
+  done
+  [[ "$PROJECT_NAME" =~ ^[a-z][a-z0-9_]*$ ]] ||
+    fail "PROJECT_NAME must match ^[a-z][a-z0-9_]*$"
+  [[ "$SERVER_PROJECTS_ROOT" = /* && "$SERVER_PROJECTS_ROOT" != */ ]] ||
+    fail "SERVER_PROJECTS_ROOT must be an absolute path without a trailing slash"
+  [[ "$DOCKER_BIND_IP" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "DOCKER_BIND_IP contains unsafe characters"
+  [[ "$FRONTEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "FRONTEND_URL contains unsafe characters"
+  [[ "$BACKEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "BACKEND_URL contains unsafe characters"
+  for name in PROJECT_HTTP_PORT FRONTEND_PORT BACKEND_PORT \
+    FRONTEND_BLUE_PORT FRONTEND_GREEN_PORT BACKEND_BLUE_PORT BACKEND_GREEN_PORT; do
+    assert_port "$name" "${!name}"
+  done
+  for name in PROJECT_HTTP_PORT FRONTEND_BLUE_PORT FRONTEND_GREEN_PORT BACKEND_BLUE_PORT BACKEND_GREEN_PORT; do
+    port="${!name}"
+    [[ "$seen" != *" $port "* ]] || fail "host ports must be unique; duplicate value: $port"
+    seen+="$port "
+  done
+  [[ "$FRONTEND_BASE_IMAGE" =~ @sha256:[0-9a-f]{64}$ ]] ||
+    fail "FRONTEND_BASE_IMAGE must be pinned by sha256 digest"
+  [[ "$BACKEND_BASE_IMAGE" =~ @sha256:[0-9a-f]{64}$ ]] ||
+    fail "BACKEND_BASE_IMAGE must be pinned by sha256 digest"
+  [[ "$DATABASE_MIGRATION_MODE" == manual || "$DATABASE_MIGRATION_MODE" == none ]] ||
+    fail "DATABASE_MIGRATION_MODE must be manual or none"
 }
 
-load_required_env() {
-  local file="$1"
-  [[ -r "$file" ]] || fail "required production environment file is missing: $file"
-  set -a
-  # shellcheck disable=SC1090
-  source "$file"
-  set +a
+probe_host() {
+  case "$1" in
+    0.0.0.0) printf '127.0.0.1\n' ;;
+    ::) printf '[::1]\n' ;;
+    *:*) printf '[%s]\n' "$1" ;;
+    *) printf '%s\n' "$1" ;;
+  esac
+}
+
+endpoint_url() {
+  local host
+  host="$(probe_host "$1")"
+  printf 'http://%s:%s%s\n' "$host" "$2" "$3"
 }
 
 resolve_project_path() {
@@ -86,95 +194,62 @@ const separator = '|---|---|';
 const versionPattern = /^(\d{4})(\d{2})(\d{2})-(\d{3})$/;
 const rowPattern = /^\| (\d{8}-\d{3}) \| (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}) \|$/;
 
-function fail(message) {
-  throw new Error(message);
-}
-
-function validCalendarDate(dateText) {
-  const year = Number(dateText.slice(0, 4));
-  const month = Number(dateText.slice(4, 6));
-  const day = Number(dateText.slice(6, 8));
-  const value = new Date(Date.UTC(year, month - 1, day));
-  return value.getUTCFullYear() === year
-    && value.getUTCMonth() === month - 1
-    && value.getUTCDate() === day;
+function fail(message) { throw new Error(message); }
+function validDate(text) {
+  const year = Number(text.slice(0, 4));
+  const month = Number(text.slice(4, 6));
+  const day = Number(text.slice(6, 8));
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
 }
-
-function inspectLedger(text) {
+function inspect(text) {
   const lines = text.replace(/\r\n/g, '\n').split('\n');
-  const headings = [];
-  for (let index = 0; index < lines.length; index += 1) {
-    if (lines[index] === heading) headings.push(index);
-  }
+  const headings = lines.flatMap((line, index) => line === heading ? [index] : []);
   if (headings.length > 1) fail('AGENTS.md contains multiple release record sections');
-  if (headings.length === 0) return { lines, headingIndex: -1, endIndex: lines.length, versions: [] };
-
+  if (!headings.length) return { lines, headingIndex: -1, endIndex: lines.length, versions: [] };
   const headingIndex = headings[0];
   let endIndex = lines.length;
   for (let index = headingIndex + 1; index < lines.length; index += 1) {
-    if (/^## /.test(lines[index])) {
-      endIndex = index;
-      break;
-    }
+    if (/^## /.test(lines[index])) { endIndex = index; break; }
   }
-
   const section = lines.slice(headingIndex + 1, endIndex);
   while (section[0] === '') section.shift();
-  while (section[section.length - 1] === '') section.pop();
-  if (section[0] !== header || section[1] !== separator) {
-    fail('AGENTS.md release record table must contain only version and build time columns');
-  }
-
-  const versions = [];
+  while (section.at(-1) === '') section.pop();
+  if (section[0] !== header || section[1] !== separator) fail('AGENTS.md release record table is invalid');
   const unique = new Set();
+  const versions = [];
   for (const row of section.slice(2)) {
     const match = row.match(rowPattern);
-    if (!match) fail(`invalid AGENTS.md release record row: ${row}`);
-    const versionMatch = match[1].match(versionPattern);
-    if (!versionMatch || !validCalendarDate(match[1].slice(0, 8))) {
-      fail(`invalid release version: ${match[1]}`);
-    }
-    const sequence = Number(versionMatch[4]);
-    if (sequence < 1 || sequence > 999) fail(`invalid release sequence: ${match[1]}`);
+    if (!match || !validDate(match[1].slice(0, 8))) fail(`invalid AGENTS.md release record row: ${row}`);
     if (unique.has(match[1])) fail(`duplicate release version: ${match[1]}`);
     unique.add(match[1]);
     versions.push(match[1]);
   }
   return { lines, headingIndex, endIndex, versions };
 }
-
-function nextVersion(ledger, currentDate) {
-  if (!/^\d{8}$/.test(currentDate) || !validCalendarDate(currentDate)) {
-    fail(`invalid current release date: ${currentDate}`);
-  }
-  let maximum = 0;
-  for (const version of ledger.versions) {
-    if (version.startsWith(`${currentDate}-`)) {
-      maximum = Math.max(maximum, Number(version.slice(-3)));
-    }
-  }
-  if (maximum >= 999) fail(`release sequence exhausted for ${currentDate}`);
-  return `${currentDate}-${String(maximum + 1).padStart(3, '0')}`;
+function nextVersion(ledger, date) {
+  if (!/^\d{8}$/.test(date) || !validDate(date)) fail(`invalid current release date: ${date}`);
+  const maximum = ledger.versions
+    .filter((item) => item.startsWith(`${date}-`))
+    .reduce((max, item) => Math.max(max, Number(item.slice(-3))), 0);
+  if (maximum >= 999) fail(`release sequence exhausted for ${date}`);
+  return `${date}-${String(maximum + 1).padStart(3, '0')}`;
 }
 
 const original = fs.readFileSync(agentsPath, 'utf8');
-const ledger = inspectLedger(original);
-
+const ledger = inspect(original);
 if (mode === 'next') {
   process.stdout.write(`${nextVersion(ledger, value)}\n`);
 } else if (mode === 'prepare') {
-  const versionMatch = value.match(versionPattern);
-  if (!versionMatch || !validCalendarDate(value.slice(0, 8))) fail(`invalid release version: ${value}`);
-  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}$/.test(timestamp)) {
-    fail(`invalid release build time: ${timestamp}`);
-  }
+  if (!versionPattern.test(value) || !validDate(value.slice(0, 8))) fail(`invalid release version: ${value}`);
+  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}$/.test(timestamp)) fail('invalid build time');
   const expected = nextVersion(ledger, value.slice(0, 8));
   if (value !== expected) fail(`release ledger changed: expected ${expected}, got ${value}`);
   const row = `| ${value} | ${timestamp} |`;
   let updated;
   if (ledger.headingIndex === -1) {
-    const separatorText = original.length === 0 ? '' : original.endsWith('\n') ? '\n' : '\n\n';
-    updated = `${original}${separatorText}${heading}\n\n${header}\n${separator}\n${row}\n`;
+    const gap = original.length === 0 ? '' : original.endsWith('\n') ? '\n' : '\n\n';
+    updated = `${original}${gap}${heading}\n\n${header}\n${separator}\n${row}\n`;
   } else {
     const lines = [...ledger.lines];
     let insertAt = ledger.endIndex;
@@ -182,8 +257,7 @@ if (mode === 'next') {
     lines.splice(insertAt, 0, row);
     updated = lines.join('\n');
   }
-  const modeBits = fs.statSync(agentsPath).mode;
-  fs.writeFileSync(outputPath, updated, { mode: modeBits });
+  fs.writeFileSync(outputPath, updated, { mode: fs.statSync(agentsPath).mode });
 } else {
   fail(`unknown release ledger mode: ${mode}`);
 }
@@ -194,7 +268,6 @@ create_manifest() {
   local version_root="$1" file relative checksum
   (
     cd "$version_root"
-    : > manifest.sha256
     find . -type f ! -name manifest.sha256 -print | LC_ALL=C sort |
       while IFS= read -r file; do
         relative="${file#./}"
@@ -205,45 +278,26 @@ create_manifest() {
 }
 
 verify_manifest() {
-  local version_root="$1"
-  local manifest="$version_root/manifest.sha256"
-  local actual_paths declared_paths result line checksum relative actual
+  local version_root="$1" manifest="$1/manifest.sha256"
+  local actual_paths declared_paths result=0 line checksum relative actual
   [[ -s "$manifest" ]] || fail "missing or empty manifest.sha256"
   actual_paths="$(mktemp)"
   declared_paths="$(mktemp)"
-  result=0
-
   if (
     cd "$version_root"
-    find . -type f ! -name manifest.sha256 -print |
-      sed 's|^\./||' |
-      LC_ALL=C sort > "$actual_paths"
+    find . -type f ! -name manifest.sha256 -print | sed 's|^\./||' | LC_ALL=C sort > "$actual_paths"
     while IFS= read -r line; do
       checksum="${line%%  *}"
       relative="${line#*  }"
-      if [[ ! "$checksum" =~ ^[0-9a-f]{64}$ || "$relative" == "$line" || "$relative" == /* || "$relative" == ../* || "$relative" == *"/../"* ]]; then
-        echo "invalid manifest entry: $line" >&2
-        result=1
-        continue
-      fi
+      [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$relative" != ../* && "$relative" != *"/../"* ]] || exit 11
       printf '%s\n' "$relative" >> "$declared_paths"
-      [[ -f "$relative" ]] || {
-        echo "manifest file is missing: $relative" >&2
-        result=1
-        continue
-      }
+      [[ -f "$relative" && ! -L "$relative" ]] || exit 12
       actual="$(checksum_value "$relative")"
-      if [[ "$actual" != "$checksum" ]]; then
-        echo "checksum mismatch: $relative" >&2
-        result=1
-      fi
+      [[ "$actual" == "$checksum" ]] || exit 13
     done < manifest.sha256
     LC_ALL=C sort -o "$declared_paths" "$declared_paths"
-    if ! cmp -s "$actual_paths" "$declared_paths"; then
-      echo "manifest does not cover the complete release package" >&2
-      result=1
-    fi
-    exit "$result"
+    [[ "$(uniq -d "$declared_paths" | wc -l | tr -d ' ')" == 0 ]] || exit 14
+    cmp -s "$actual_paths" "$declared_paths"
   ); then
     result=0
   else
@@ -253,144 +307,140 @@ verify_manifest() {
   [[ "$result" -eq 0 ]] || fail "release manifest validation failed"
 }
 
-reject_secret_files() {
+reject_version_secrets() {
   local root="$1" file base
-  if find "$root" -type l -print -quit | grep -q .; then
-    fail "symbolic links must not be packaged"
-  fi
+  if find "$root" -type l -print -quit | grep -q .; then fail "symbolic links must not be packaged"; fi
   while IFS= read -r file; do
     base="${file##*/}"
     case "$base" in
       .env|.env.*|*.pem|*.key|id_rsa|id_ed25519|credentials|credentials.*)
-        fail "production secret file must not be packaged: ${file#"$root"/}"
-        ;;
+        fail "secret file must not enter the version directory: ${file#"$root"/}" ;;
     esac
   done < <(find "$root" -type f -print)
 }
 
 validate_dockerignore() {
-  local file="$1" pattern
+  local file="$1" pattern line
   [[ -f "$file" ]] || fail "required Docker ignore file is missing: $file"
-  for pattern in \
-    '.env' \
-    '.env.*' \
-    '*.pem' \
-    '*.key' \
-    'id_rsa' \
-    'id_ed25519' \
-    'credentials' \
-    'credentials.*' \
-    'deploy/' \
-    'logs/' \
-    '.git/' \
-    'node_modules/' \
-    'venv/' \
-    '.pnpm-store/'; do
+  for pattern in '.env' '.env.*' '*.pem' '*.key' id_rsa id_ed25519 credentials 'credentials.*' \
+    'deploy/' 'logs/' '.git/' 'node_modules/' 'venv/' '.pnpm-store/' '.deploy-build.lock/' '.deploy-build.*'; do
     grep -Fxq "$pattern" "$file" || fail "Docker ignore file is missing required pattern: $pattern"
   done
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" != !* || "$line" == '!.env.example' ]] || fail "Docker ignore file contains forbidden reverse include: $line"
+  done < "$file"
 }
 
 validate_local_package() {
-  local output_root="$1" version="$2"
-  local version_root="$output_root/$version"
+  local output_root="$1" version="$2" version_root="$1/$2"
+  local expected_count
   [[ -x "$output_root/deploy.sh" ]] || fail "generated deploy.sh is missing or not executable"
-  [[ "$(cat "$output_root/release.env")" == "RELEASE_VERSION=$version" ]] ||
-    fail "release.env does not point to the generated version"
-  [[ -f "$version_root/frontend.tar.gz" ]] || fail "missing frontend.tar.gz"
-  [[ -f "$version_root/backend-image.tar" ]] || fail "missing backend-image.tar"
-  [[ -d "$version_root/database/migrations" ]] || fail "missing database/migrations"
-  [[ -x "$version_root/scripts/apply-migrations.sh" ]] || fail "missing executable migration runner"
-  [[ -f "$version_root/docker/docker-compose.blue-green.yml" ]] || fail "missing blue-green compose file"
-  [[ -f "$version_root/nginx/site.conf" ]] || fail "missing Nginx site configuration"
-  grep -Fq '../../logs:/app/logs' "$version_root/docker/docker-compose.blue-green.yml" ||
-    fail "compose does not mount deployment-root logs"
-  grep -Fq '__DEPLOY_ROOT__' "$version_root/nginx/site.conf" ||
-    fail "Nginx configuration does not contain the deployment-root placeholder"
-  grep -Fq '__BACKEND_PROXY_URL__' "$version_root/nginx/site.conf" ||
-    fail "Nginx configuration does not contain the backend proxy URL placeholder"
-  reject_secret_files "$output_root"
+  cmp -s "$SCRIPT_PATH" "$output_root/deploy.sh" || fail "generated deploy.sh differs from its source"
+  cmp -s "$SCRIPT_DIR/.env" "$output_root/.env" || fail "generated root .env differs from project .env"
+  [[ "$(cat "$output_root/release.env")" == "RELEASE_VERSION=$version" ]] || fail "invalid release.env"
+  [[ -f "$version_root/frontend-image.tar" && -f "$version_root/backend-image.tar" ]] || fail "dual image archives are required"
+  [[ -f "$version_root/docker/docker-compose.blue-green.yml" ]] || fail "missing compose file"
+  [[ -f "$version_root/nginx/site.conf" ]] || fail "missing Nginx site template"
+  [[ "$(grep -Fc '../../logs:/app/logs' "$version_root/docker/docker-compose.blue-green.yml")" == 4 ]] || fail "all four services must mount root logs"
+  grep -Fq 'frontend-blue:' "$version_root/docker/docker-compose.blue-green.yml" || fail "missing frontend-blue"
+  grep -Fq 'backend-blue:' "$version_root/docker/docker-compose.blue-green.yml" || fail "missing backend-blue"
+  grep -Fq 'frontend-green:' "$version_root/docker/docker-compose.blue-green.yml" || fail "missing frontend-green"
+  grep -Fq 'backend-green:' "$version_root/docker/docker-compose.blue-green.yml" || fail "missing backend-green"
+  grep -Fq '__PROJECT_HTTP_PORT__' "$version_root/nginx/site.conf" || fail "missing project port placeholder"
+  if [[ "$DATABASE_MIGRATION_MODE" == manual ]]; then
+    [[ -d "$version_root/database/migrations" && -x "$version_root/database/apply-migrations.sh" ]] || fail "manual database package is incomplete"
+  else
+    [[ ! -e "$version_root/database" ]] || fail "none database mode must not package database files"
+  fi
+  expected_count=4
+  [[ "$DATABASE_MIGRATION_MODE" == manual ]] && expected_count=6
+  [[ "$(find "$version_root" -type f ! -name manifest.sha256 | wc -l | tr -d ' ')" -ge "$expected_count" ]] || fail "release package is incomplete"
+  reject_version_secrets "$version_root"
   verify_manifest "$version_root"
 }
 
-build_release() {
-  local project_root="$SCRIPT_DIR" agents_file="$SCRIPT_DIR/AGENTS.md"
-  local today version build_time raw_time image staging_parent output_root version_root agents_prepared
-  local frontend_dist backend_dockerfile migrations_source migration_runner_source
-  local deploy_config_dir compose_source nginx_source dockerignore_file
+acquire_build_lock() {
+  BUILD_LOCK="$SCRIPT_DIR/.deploy-build.lock"
+  mkdir "$BUILD_LOCK" 2>/dev/null || fail "another build is active or stale lock exists: $BUILD_LOCK"
+}
 
-  [[ -r "$agents_file" && -w "$agents_file" ]] || fail "project AGENTS.md must exist and be readable and writable"
-  load_env_if_present "$project_root/.env"
-  : "${PROJECT_NAME:?PROJECT_NAME is required in the environment or project .env}"
-  : "${BACKEND_CONTAINER_PORT:?BACKEND_CONTAINER_PORT is required in the environment or project .env}"
-  assert_port BACKEND_CONTAINER_PORT "$BACKEND_CONTAINER_PORT"
+release_build_lock() {
+  [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]] && rmdir "$BUILD_LOCK"
+}
 
-  frontend_dist="$(resolve_project_path "$project_root" "${FRONTEND_DIST_DIR:-src/frontend/dist}")"
+build_release() {
+  local project_root="$SCRIPT_DIR" agents_file="$SCRIPT_DIR/AGENTS.md"
+  local today version raw_time build_time frontend_image backend_image
+  local frontend_dockerfile backend_dockerfile dockerignore_file deploy_config_dir compose_source nginx_source
+  local migrations_source migration_runner_source staging_parent output_root version_root agents_prepared old_deploy
+
+  acquire_build_lock
+  staging_parent=
+  agents_prepared=
+  old_deploy=
+  trap 'rm -rf -- "${staging_parent:-}" "${old_deploy:-}"; rm -f -- "${agents_prepared:-}"; release_build_lock' EXIT
+  [[ -r "$agents_file" && -w "$agents_file" ]] || fail "project AGENTS.md must be readable and writable"
+  load_dotenv "$project_root/.env"
+  validate_configuration
+
+  frontend_dockerfile="$(resolve_project_path "$project_root" "${FRONTEND_DOCKERFILE:-src/frontend/Dockerfile}")"
   backend_dockerfile="$(resolve_project_path "$project_root" "${BACKEND_DOCKERFILE:-src/backend/Dockerfile}")"
   dockerignore_file="$(resolve_project_path "$project_root" "${DOCKERIGNORE_FILE:-.dockerignore}")"
+  deploy_config_dir="$(resolve_project_path "$project_root" "${DEPLOY_CONFIG_DIR:-scripts/deployment}")"
+  compose_source="$(resolve_project_path "$project_root" "${COMPOSE_SOURCE:-${deploy_config_dir#"$project_root"/}/docker-compose.blue-green.yml}")"
+  nginx_source="$(resolve_project_path "$project_root" "${NGINX_SOURCE:-${deploy_config_dir#"$project_root"/}/nginx-site.conf}")"
   migrations_source="$(resolve_project_path "$project_root" "${MIGRATIONS_SOURCE:-database/migrations}")"
   migration_runner_source="$(resolve_project_path "$project_root" "${MIGRATION_RUNNER_SOURCE:-scripts/apply-migrations.sh}")"
-  deploy_config_dir="$(resolve_project_path "$project_root" "${DEPLOY_CONFIG_DIR:-scripts/deployment}")"
-  compose_source="$(resolve_project_path "$project_root" "${COMPOSE_SOURCE:-${deploy_config_dir#$project_root/}/docker-compose.blue-green.yml}")"
-  nginx_source="$(resolve_project_path "$project_root" "${NGINX_SOURCE:-${deploy_config_dir#$project_root/}/nginx-site.conf}")"
-  BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
 
-  for command in node pnpm docker tar install find sort cmp awk sed grep; do
-    require_command "$command"
-  done
+  for command in node pnpm docker tar install find sort cmp awk sed grep uniq; do require_command "$command"; done
   select_checksum_tool
-  [[ -f "$backend_dockerfile" ]] || fail "backend Dockerfile not found: $backend_dockerfile"
+  [[ -f "$frontend_dockerfile" && -f "$backend_dockerfile" ]] || fail "frontend and backend Dockerfiles are required"
+  [[ -f "$compose_source" && -f "$nginx_source" ]] || fail "deployment Compose and Nginx sources are required"
   validate_dockerignore "$dockerignore_file"
-  [[ -d "$migrations_source" ]] || fail "migration directory not found: $migrations_source"
-  [[ -x "$migration_runner_source" ]] || fail "migration runner is missing or not executable: $migration_runner_source"
-  [[ -f "$compose_source" ]] || fail "compose source not found: $compose_source"
-  [[ -f "$nginx_source" ]] || fail "Nginx source not found: $nginx_source"
+  if [[ "$DATABASE_MIGRATION_MODE" == manual ]]; then
+    [[ -d "$migrations_source" ]] || fail "manual migration directory is missing: $migrations_source"
+    [[ -x "$migration_runner_source" ]] || fail "manual migration runner is missing or not executable"
+  fi
 
   today="$(date +%Y%m%d)"
   version="$(release_ledger next "$agents_file" "$today")"
   assert_version "$version"
-  image="$BACKEND_IMAGE_PREFIX:$version"
-
-  echo "release gate: pnpm test"
-  pnpm test
-  echo "release gate: pnpm lint"
-  pnpm lint
-  echo "release gate: pnpm typecheck"
-  pnpm typecheck
-  echo "release gate: pnpm build"
-  RELEASE_VERSION="$version" VITE_RELEASE_BASE="/releases/$version/" pnpm build
-
-  [[ -f "$frontend_dist/index.html" ]] || fail "frontend build missing index.html: $frontend_dist"
-  grep -Fq "/releases/$version/" "$frontend_dist/index.html" ||
-    fail "frontend assets are not built with /releases/$version/"
-
-  echo "release gate: docker build"
-  docker build \
-    --build-arg "RELEASE_VERSION=$version" \
-    --build-arg "BACKEND_CONTAINER_PORT=$BACKEND_CONTAINER_PORT" \
-    --tag "$image" \
-    --file "$backend_dockerfile" \
-    "$project_root"
-  docker image inspect "$image" >/dev/null
+  frontend_image="${PROJECT_NAME}_frontend:$version"
+  backend_image="${PROJECT_NAME}_backend:$version"
+
+  echo "release gate: pnpm test"; pnpm test
+  echo "release gate: pnpm lint"; pnpm lint
+  echo "release gate: pnpm typecheck"; pnpm typecheck
+  echo "release gate: pnpm build"; RELEASE_VERSION="$version" pnpm build
+
+  echo "release gate: frontend docker build"
+  docker build --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "RELEASE_VERSION=$version" \
+    --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
+  echo "release gate: backend docker build"
+  docker build --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "RELEASE_VERSION=$version" \
+    --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$frontend_image")" == "$version" ]] || fail "frontend image version label mismatch"
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$backend_image")" == "$version" ]] || fail "backend image version label mismatch"
 
   staging_parent="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"
   output_root="$staging_parent/deploy"
   version_root="$output_root/$version"
   agents_prepared="$project_root/.AGENTS.md.release.$$.tmp"
-  trap 'rm -rf -- "${staging_parent:-}"; rm -f -- "${agents_prepared:-}"' EXIT
-
-  mkdir -p \
-    "$version_root/database" \
-    "$version_root/scripts" \
-    "$version_root/docker" \
-    "$version_root/nginx"
+  mkdir -p "$version_root/docker" "$version_root/nginx"
   install -m 0755 "$SCRIPT_PATH" "$output_root/deploy.sh"
+  install -m 0600 "$project_root/.env" "$output_root/.env"
   printf 'RELEASE_VERSION=%s\n' "$version" > "$output_root/release.env"
-  tar -czf "$version_root/frontend.tar.gz" -C "$frontend_dist" .
-  docker save -o "$version_root/backend-image.tar" "$image"
-  cp -R "$migrations_source" "$version_root/database/migrations"
-  install -m 0755 "$migration_runner_source" "$version_root/scripts/apply-migrations.sh"
+  docker save -o "$version_root/frontend-image.tar" "$frontend_image"
+  docker save -o "$version_root/backend-image.tar" "$backend_image"
   install -m 0644 "$compose_source" "$version_root/docker/docker-compose.blue-green.yml"
   install -m 0644 "$nginx_source" "$version_root/nginx/site.conf"
+  cmp -s "$compose_source" "$version_root/docker/docker-compose.blue-green.yml" || fail "generated Compose is not deterministic"
+  cmp -s "$nginx_source" "$version_root/nginx/site.conf" || fail "generated Nginx config is not deterministic"
+  if [[ "$DATABASE_MIGRATION_MODE" == manual ]]; then
+    mkdir -p "$version_root/database"
+    cp -R "$migrations_source" "$version_root/database/migrations"
+    install -m 0755 "$migration_runner_source" "$version_root/database/apply-migrations.sh"
+  fi
   create_manifest "$version_root"
   validate_local_package "$output_root" "$version"
 
@@ -398,23 +448,32 @@ build_release() {
   build_time="${raw_time%?????}${raw_time: -5:3}:${raw_time: -2}"
   release_ledger prepare "$agents_file" "$version" "$build_time" "$agents_prepared"
 
-  [[ "$project_root/deploy" == "$SCRIPT_DIR/deploy" ]] || fail "refusing to replace an unexpected deploy directory"
-  rm -rf -- "$project_root/deploy"
-  mv "$output_root" "$project_root/deploy"
+  if [[ -e "$project_root/deploy" ]]; then
+    old_deploy="$project_root/.deploy.previous.$$"
+    [[ ! -e "$old_deploy" ]] || fail "temporary deploy replacement path already exists"
+    mv "$project_root/deploy" "$old_deploy"
+  fi
+  if ! mv "$output_root" "$project_root/deploy"; then
+    [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"
+    fail "failed to publish deploy directory"
+  fi
   if ! mv "$agents_prepared" "$agents_file"; then
     rm -rf -- "$project_root/deploy"
+    [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"
     fail "failed to write AGENTS.md release record"
   fi
-
+  [[ -n "$old_deploy" ]] && rm -rf -- "$old_deploy" && old_deploy=
+  rm -rf -- "$staging_parent"; staging_parent=
+  release_build_lock; BUILD_LOCK=
   trap - EXIT
-  rm -rf -- "$staging_parent"
   echo "release package created: deploy/$version"
+  [[ "$DATABASE_MIGRATION_MODE" == manual ]] && echo "database migration was not executed; run the packaged script manually after approval"
+  return 0
 }
 
 read_release_pointer() {
   local file="$DEPLOY_ROOT/release.env" line
-  [[ -f "$file" ]] || fail "missing release.env"
-  [[ "$(wc -l < "$file" | tr -d ' ')" == 1 ]] || fail "release.env must contain exactly one line"
+  [[ -f "$file" && "$(wc -l < "$file" | tr -d ' ')" == 1 ]] || fail "release.env must contain exactly one line"
   line="$(cat "$file")"
   [[ "$line" =~ ^RELEASE_VERSION=([0-9]{8}-[0-9]{3})$ ]] || fail "invalid release.env"
   RELEASE_VERSION="${BASH_REMATCH[1]}"
@@ -422,56 +481,53 @@ read_release_pointer() {
 }
 
 initialize_server_context() {
+  local expected_root
   DEPLOY_ROOT="$SCRIPT_DIR"
-  load_required_env "$DEPLOY_ROOT/.env.production"
-  : "${PROJECT_NAME:?PROJECT_NAME is required in .env.production}"
-  : "${DATABASE_URL:?DATABASE_URL is required in .env.production}"
-  : "${BACKEND_BIND_IP:?BACKEND_BIND_IP is required in .env.production}"
-  : "${BACKEND_LISTEN_HOST:?BACKEND_LISTEN_HOST is required in .env.production}"
-  : "${BACKEND_CONTAINER_PORT:?BACKEND_CONTAINER_PORT is required in .env.production}"
-  : "${BACKEND_CONTAINER_HEALTH_URL:?BACKEND_CONTAINER_HEALTH_URL is required in .env.production}"
-  : "${BLUE_PORT:?BLUE_PORT is required in .env.production}"
-  : "${GREEN_PORT:?GREEN_PORT is required in .env.production}"
-  : "${BLUE_HEALTH_URL:?BLUE_HEALTH_URL is required in .env.production}"
-  : "${GREEN_HEALTH_URL:?GREEN_HEALTH_URL is required in .env.production}"
-  : "${BLUE_VERSION_URL:?BLUE_VERSION_URL is required in .env.production}"
-  : "${GREEN_VERSION_URL:?GREEN_VERSION_URL is required in .env.production}"
-  : "${BLUE_UPSTREAM:?BLUE_UPSTREAM is required in .env.production}"
-  : "${GREEN_UPSTREAM:?GREEN_UPSTREAM is required in .env.production}"
-  : "${BACKEND_PROXY_URL:?BACKEND_PROXY_URL is required in .env.production}"
-  if [[ ! "$BACKEND_PROXY_URL" =~ ^https?://([A-Za-z_][A-Za-z0-9_]*)$ ]]; then
-    fail "BACKEND_PROXY_URL must be an http(s) URL containing only a valid Nginx upstream name"
-  fi
-  BACKEND_UPSTREAM_NAME="${BASH_REMATCH[1]}"
-  BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
-  assert_port BACKEND_CONTAINER_PORT "$BACKEND_CONTAINER_PORT"
-  assert_port BLUE_PORT "$BLUE_PORT"
-  assert_port GREEN_PORT "$GREEN_PORT"
+  load_dotenv "$DEPLOY_ROOT/.env"
+  validate_configuration
+  [[ -d "$SERVER_PROJECTS_ROOT" ]] || fail "SERVER_PROJECTS_ROOT does not exist: $SERVER_PROJECTS_ROOT"
+  expected_root="$(cd "$SERVER_PROJECTS_ROOT" >/dev/null 2>&1 && pwd -P)/$PROJECT_NAME"
+  [[ "$DEPLOY_ROOT" == "$expected_root" ]] || fail "server deploy root must be exactly $expected_root; got $DEPLOY_ROOT"
   STATE_DIR="$DEPLOY_ROOT/state"
   ACTIVE_STATE="$STATE_DIR/active.env"
   PREVIOUS_STATE="$STATE_DIR/previous.env"
-  RELEASES_DIR="$DEPLOY_ROOT/releases"
-  UPSTREAM_FILE="$DEPLOY_ROOT/nginx/backend-active.conf"
-  NGINX_SITE_FILE="$DEPLOY_ROOT/nginx/site.conf"
-  for command in docker curl nginx psql tar find sort cmp awk sed grep; do
-    require_command "$command"
-  done
+  NGINX_DIR="$DEPLOY_ROOT/nginx"
+  NGINX_SITE_FILE="$NGINX_DIR/site.conf"
+  UPSTREAM_FILE="$NGINX_DIR/active-upstreams.conf"
+  FRONTEND_UPSTREAM_NAME="${PROJECT_NAME}_frontend_active"
+  BACKEND_UPSTREAM_NAME="${PROJECT_NAME}_backend_active"
+  FRONTEND_IMAGE_REPOSITORY="${PROJECT_NAME}_frontend"
+  BACKEND_IMAGE_REPOSITORY="${PROJECT_NAME}_backend"
+  for command in docker curl nginx tar find sort cmp awk sed grep uniq flock; do require_command "$command"; done
   select_checksum_tool
 }
 
+read_state_file() {
+  local file="$1" line key value color= version= count=0
+  [[ -f "$file" ]] || return 1
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" =~ ^(ACTIVE_COLOR|ACTIVE_VERSION)=([A-Za-z0-9_-]+)$ ]] || fail "invalid state file: $file"
+    key="${BASH_REMATCH[1]}"; value="${BASH_REMATCH[2]}"; count=$((count + 1))
+    if [[ "$key" == ACTIVE_COLOR ]]; then [[ -z "$color" ]] || fail "duplicate state color"; color="$value"; else [[ -z "$version" ]] || fail "duplicate state version"; version="$value"; fi
+  done < "$file"
+  [[ "$count" -eq 2 && ( "$color" == blue || "$color" == green ) ]] || fail "incomplete state file: $file"
+  assert_version "$version"
+  STATE_COLOR="$color"; STATE_VERSION="$version"
+}
+
 read_active() {
-  ACTIVE_COLOR=green
-  ACTIVE_VERSION=
-  if [[ -f "$ACTIVE_STATE" ]]; then
-    # shellcheck disable=SC1090
-    source "$ACTIVE_STATE"
-    [[ "$ACTIVE_COLOR" == blue || "$ACTIVE_COLOR" == green ]] || fail "invalid active color state"
-    assert_version "$ACTIVE_VERSION"
-  fi
+  ACTIVE_COLOR=; ACTIVE_VERSION=
+  if read_state_file "$ACTIVE_STATE"; then ACTIVE_COLOR="$STATE_COLOR"; ACTIVE_VERSION="$STATE_VERSION"; fi
 }
 
-upstream_for() {
-  [[ "$1" == blue ]] && printf '%s' "$BLUE_UPSTREAM" || printf '%s' "$GREEN_UPSTREAM"
+read_previous() {
+  PREVIOUS_COLOR=; PREVIOUS_VERSION=
+  if read_state_file "$PREVIOUS_STATE"; then PREVIOUS_COLOR="$STATE_COLOR"; PREVIOUS_VERSION="$STATE_VERSION"; fi
+}
+
+write_state_candidate() {
+  local file="$1" color="$2" version="$3"
+  printf 'ACTIVE_COLOR=%s\nACTIVE_VERSION=%s\n' "$color" "$version" > "$file"
 }
 
 compose_file_for() {
@@ -480,203 +536,329 @@ compose_file_for() {
   printf '%s/%s/docker/docker-compose.blue-green.yml\n' "$DEPLOY_ROOT" "$version"
 }
 
-render_nginx_site() {
-  local source="$1" escaped_root escaped_proxy_url
-  grep -Fq '__DEPLOY_ROOT__' "$source" || fail "Nginx package is missing __DEPLOY_ROOT__ placeholder"
-  grep -Fq '__BACKEND_PROXY_URL__' "$source" ||
-    fail "Nginx package is missing __BACKEND_PROXY_URL__ placeholder"
-  escaped_root="${DEPLOY_ROOT//\\/\\\\}"
-  escaped_root="${escaped_root//&/\\&}"
-  escaped_root="${escaped_root//|/\\|}"
-  escaped_proxy_url="${BACKEND_PROXY_URL//\\/\\\\}"
-  escaped_proxy_url="${escaped_proxy_url//&/\\&}"
-  escaped_proxy_url="${escaped_proxy_url//|/\\|}"
-  mkdir -p "$DEPLOY_ROOT/nginx"
-  sed \
-    -e "s|__DEPLOY_ROOT__|$escaped_root|g" \
-    -e "s|__BACKEND_PROXY_URL__|$escaped_proxy_url|g" \
-    "$source" > "$NGINX_SITE_FILE.new"
-  mv "$NGINX_SITE_FILE.new" "$NGINX_SITE_FILE"
-}
-
-switch_traffic() {
-  local color="$1" version="$2" upstream backup
-  upstream="$(upstream_for "$color")"
-  backup="$UPSTREAM_FILE.previous"
-  printf 'upstream %s {\n  server %s;\n  keepalive 32;\n}\n' \
-    "$BACKEND_UPSTREAM_NAME" "$upstream" > "$UPSTREAM_FILE.new"
-  [[ -f "$UPSTREAM_FILE" ]] && cp "$UPSTREAM_FILE" "$backup"
-  mv -f "$UPSTREAM_FILE.new" "$UPSTREAM_FILE"
-  if ! nginx -t || ! nginx -s reload; then
-    if [[ -f "$backup" ]]; then
-      mv -f "$backup" "$UPSTREAM_FILE"
-      nginx -t
-      nginx -s reload
-    fi
-    echo "failed to switch Nginx upstream" >&2
-    return 1
+image_names_for() {
+  local version="$1"
+  assert_version "$version"
+  FRONTEND_IMAGE="${FRONTEND_IMAGE_REPOSITORY}:$version"
+  BACKEND_IMAGE="${BACKEND_IMAGE_REPOSITORY}:$version"
+}
+
+validate_uploaded_package() {
+  local package_root="$1"
+  [[ -f "$package_root/frontend-image.tar" && -f "$package_root/backend-image.tar" ]] || fail "dual image archives are missing"
+  [[ -f "$package_root/docker/docker-compose.blue-green.yml" && -f "$package_root/nginx/site.conf" ]] || fail "release configuration is incomplete"
+  if [[ "$DATABASE_MIGRATION_MODE" == manual ]]; then
+    [[ -d "$package_root/database/migrations" && -x "$package_root/database/apply-migrations.sh" ]] || fail "manual database package is incomplete"
+  else
+    [[ ! -e "$package_root/database" ]] || fail "none database mode must not contain database files"
   fi
-  rm -f "$backup"
-  ln -sfn "releases/$version" "$DEPLOY_ROOT/current.new"
-  mv -Tf "$DEPLOY_ROOT/current.new" "$DEPLOY_ROOT/current"
+  reject_version_secrets "$package_root"
+  verify_manifest "$package_root"
+  tar -tf "$package_root/frontend-image.tar" >/dev/null || fail "invalid frontend image archive"
+  tar -tf "$package_root/backend-image.tar" >/dev/null || fail "invalid backend image archive"
+}
+
+archive_has_tag() {
+  local archive="$1" tag="$2" manifest compact repo_tag_count
+  manifest="$(tar -xOf "$archive" manifest.json 2>/dev/null)" || fail "image archive is missing manifest.json: $archive"
+  compact="$(tr -d '[:space:]' <<< "$manifest")"
+  repo_tag_count="$(grep -o '"RepoTags"' <<< "$compact" | wc -l | tr -d ' ')"
+  [[ "$repo_tag_count" == 1 && "$compact" == *"\"RepoTags\":[\"$tag\"]"* ]] ||
+    fail "image archive must contain exactly one expected tag: $tag"
+}
+
+load_release_images() {
+  local version="$1" package_root="$DEPLOY_ROOT/$1"
+  image_names_for "$version"
+  archive_has_tag "$package_root/frontend-image.tar" "$FRONTEND_IMAGE"
+  archive_has_tag "$package_root/backend-image.tar" "$BACKEND_IMAGE"
+  docker load -i "$package_root/frontend-image.tar" >/dev/null
+  docker load -i "$package_root/backend-image.tar" >/dev/null
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$FRONTEND_IMAGE")" == "$version" ]] || fail "frontend loaded image version mismatch"
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$BACKEND_IMAGE")" == "$version" ]] || fail "backend loaded image version mismatch"
 }
 
-verify_backend() {
-  local color="$1" version="$2" health_url version_url actual
+compose_for() {
+  local version="$1"; shift
+  local compose_file
+  image_names_for "$version"
+  compose_file="$(compose_file_for "$version")"
+  [[ -f "$compose_file" ]] || fail "compose file is missing for version $version"
+  FRONTEND_IMAGE="$FRONTEND_IMAGE" BACKEND_IMAGE="$BACKEND_IMAGE" \
+    docker compose --env-file "$DEPLOY_ROOT/.env" --project-name "$PROJECT_NAME" -f "$compose_file" "$@"
+}
+
+up_pair() {
+  local color="$1" version="$2"
+  compose_for "$version" up -d --force-recreate "frontend-$color" "backend-$color"
+}
+
+verify_pair() {
+  local color="$1" version="$2" frontend_health frontend_version backend_health backend_version frontend_actual backend_actual
   if [[ "$color" == blue ]]; then
-    health_url="$BLUE_HEALTH_URL"
-    version_url="$BLUE_VERSION_URL"
+    frontend_health="$(endpoint_url "$DOCKER_BIND_IP" "$FRONTEND_BLUE_PORT" /health)"; frontend_version="$(endpoint_url "$DOCKER_BIND_IP" "$FRONTEND_BLUE_PORT" /version)"
+    backend_health="$(endpoint_url "$DOCKER_BIND_IP" "$BACKEND_BLUE_PORT" /health)"; backend_version="$(endpoint_url "$DOCKER_BIND_IP" "$BACKEND_BLUE_PORT" /version)"
   else
-    health_url="$GREEN_HEALTH_URL"
-    version_url="$GREEN_VERSION_URL"
+    frontend_health="$(endpoint_url "$DOCKER_BIND_IP" "$FRONTEND_GREEN_PORT" /health)"; frontend_version="$(endpoint_url "$DOCKER_BIND_IP" "$FRONTEND_GREEN_PORT" /version)"
+    backend_health="$(endpoint_url "$DOCKER_BIND_IP" "$BACKEND_GREEN_PORT" /health)"; backend_version="$(endpoint_url "$DOCKER_BIND_IP" "$BACKEND_GREEN_PORT" /version)"
   fi
-  HEALTH_URL="$health_url"
-  VERSION_URL="$version_url"
-  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$HEALTH_URL"
-  actual="$(curl --fail --silent --show-error "$VERSION_URL")"
-  [[ "$actual" == "$version" ]] || fail "backend version mismatch: expected $version, got $actual"
+  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$frontend_health" >/dev/null
+  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$backend_health" >/dev/null
+  frontend_actual="$(curl --fail --silent --show-error "$frontend_version")"
+  backend_actual="$(curl --fail --silent --show-error "$backend_version")"
+  [[ "$frontend_actual" == "$version" ]] || fail "frontend version mismatch: expected $version, got $frontend_actual"
+  [[ "$backend_actual" == "$version" ]] || fail "backend version mismatch: expected $version, got $backend_actual"
+}
+
+render_site_candidate() {
+  local source="$1" output="$2" escaped_root
+  for placeholder in __PROJECT_NAME__ __PROJECT_HTTP_PORT__ __DOCKER_HOST_PORTS__ __DEPLOY_ROOT__ __FRONTEND_UPSTREAM_NAME__ __BACKEND_UPSTREAM_NAME__; do
+    grep -Fq "$placeholder" "$source" || fail "Nginx template is missing $placeholder"
+  done
+  escaped_root="${DEPLOY_ROOT//\\/\\\\}"; escaped_root="${escaped_root//&/\\&}"; escaped_root="${escaped_root//|/\\|}"
+  sed -e "s|__PROJECT_NAME__|$PROJECT_NAME|g" -e "s|__PROJECT_HTTP_PORT__|$PROJECT_HTTP_PORT|g" \
+    -e "s|__DOCKER_HOST_PORTS__|$FRONTEND_BLUE_PORT,$FRONTEND_GREEN_PORT,$BACKEND_BLUE_PORT,$BACKEND_GREEN_PORT|g" \
+    -e "s|__DEPLOY_ROOT__|$escaped_root|g" -e "s|__FRONTEND_UPSTREAM_NAME__|$FRONTEND_UPSTREAM_NAME|g" \
+    -e "s|__BACKEND_UPSTREAM_NAME__|$BACKEND_UPSTREAM_NAME|g" "$source" > "$output"
+}
+
+write_upstream_candidate() {
+  local color="$1" output="$2" frontend_port backend_port
+  if [[ "$color" == blue ]]; then frontend_port="$FRONTEND_BLUE_PORT"; backend_port="$BACKEND_BLUE_PORT"; else frontend_port="$FRONTEND_GREEN_PORT"; backend_port="$BACKEND_GREEN_PORT"; fi
+  printf 'upstream %s {\n  server %s:%s;\n  keepalive 32;\n}\n\nupstream %s {\n  server %s:%s;\n  keepalive 32;\n}\n' \
+    "$FRONTEND_UPSTREAM_NAME" "$DOCKER_BIND_IP" "$frontend_port" \
+    "$BACKEND_UPSTREAM_NAME" "$DOCKER_BIND_IP" "$backend_port" > "$output"
+}
+
+assert_project_ports_isolated() {
+  local site site_physical expanded total_listeners own_listener marker port own_upstream_listener
+  local docker_ports compose_project published_ports
+  shopt -s nullglob
+  for site in "$SERVER_PROJECTS_ROOT"/*/nginx/site.conf; do
+    site_physical="$(cd "$(dirname "$site")" >/dev/null 2>&1 && pwd -P)/$(basename "$site")"
+    [[ "$site_physical" == "$NGINX_SITE_FILE" ]] && continue
+    if grep -Eq "^# wdyy-port: ${PROJECT_HTTP_PORT}$|^[[:space:]]*listen[[:space:]]+${PROJECT_HTTP_PORT}[[:space:]]*;" "$site"; then
+      shopt -u nullglob
+      fail "PROJECT_HTTP_PORT is already used by another project: $site"
+    fi
+    marker="$(sed -n 's/^# wdyy-docker-ports: //p' "$site")"
+    [[ "$marker" =~ ^[0-9]+,[0-9]+,[0-9]+,[0-9]+$ ]] || {
+      shopt -u nullglob
+      fail "cannot prove Docker host port isolation for project site: $site"
+    }
+    marker=" ${marker//,/ } "
+    for port in $FRONTEND_BLUE_PORT $FRONTEND_GREEN_PORT $BACKEND_BLUE_PORT $BACKEND_GREEN_PORT; do
+      [[ "$marker" != *" $port "* ]] || {
+        shopt -u nullglob
+        fail "Docker host port $port is already reserved by another project: $site"
+      }
+    done
+  done
+  shopt -u nullglob
+  docker_ports="$(docker ps --format '{{.Label "com.docker.compose.project"}}|{{.Ports}}')" ||
+    fail "unable to inspect running Docker port bindings"
+  while IFS='|' read -r compose_project published_ports; do
+    [[ -n "$published_ports" && "$compose_project" != "$PROJECT_NAME" ]] || continue
+    for port in $FRONTEND_BLUE_PORT $FRONTEND_GREEN_PORT $BACKEND_BLUE_PORT $BACKEND_GREEN_PORT; do
+      if grep -Eq "(^|[[:space:],])([^,[:space:]]*:)?${port}->" <<< "$published_ports"; then
+        fail "Docker host port $port is already published by another container"
+      fi
+    done
+  done <<< "$docker_ports"
+  expanded="$(nginx -T 2>&1)" || fail "current global Nginx configuration is invalid"
+  total_listeners="$(grep -Ec "^[[:space:]]*listen[[:space:]]+${PROJECT_HTTP_PORT}[[:space:]]*;" <<< "$expanded" || true)"
+  if grep -Fq "# wdyy-project: $PROJECT_NAME" <<< "$expanded"; then own_listener=1; fi
+  (( total_listeners <= own_listener )) || fail "PROJECT_HTTP_PORT is already used outside this project in expanded Nginx configuration"
+  for port in $FRONTEND_BLUE_PORT $FRONTEND_GREEN_PORT $BACKEND_BLUE_PORT $BACKEND_GREEN_PORT; do
+    total_listeners="$(grep -Ec "^[[:space:]]*server[[:space:]]+[^;[:space:]]+:${port}[[:space:]]*;|proxy_pass[[:space:]]+https?://[^;[:space:]]+:${port}([/;]|$)" <<< "$expanded" || true)"
+    own_upstream_listener=0
+    if grep -Eq "upstream[[:space:]]+(${FRONTEND_UPSTREAM_NAME}|${BACKEND_UPSTREAM_NAME})" <<< "$expanded" &&
+      [[ -f "$UPSTREAM_FILE" ]] && grep -Eq ":${port}[[:space:]]*;" "$UPSTREAM_FILE"; then
+      own_upstream_listener=1
+    fi
+    (( total_listeners <= own_upstream_listener )) || fail "Docker host port $port is already used outside this project in expanded Nginx configuration"
+  done
 }
 
-validate_uploaded_package() {
-  local package_root="$1"
-  select_checksum_tool
-  [[ -f "$package_root/frontend.tar.gz" ]] || fail "missing frontend.tar.gz"
-  [[ -f "$package_root/backend-image.tar" ]] || fail "missing backend-image.tar"
-  [[ -d "$package_root/database/migrations" ]] || fail "missing database/migrations"
-  [[ -x "$package_root/scripts/apply-migrations.sh" ]] || fail "missing executable migration runner"
-  [[ -f "$package_root/docker/docker-compose.blue-green.yml" ]] || fail "missing blue-green compose file"
-  [[ -f "$package_root/nginx/site.conf" ]] || fail "missing Nginx site configuration"
-  reject_secret_files "$package_root"
-  verify_manifest "$package_root"
-  if tar -tzf "$package_root/frontend.tar.gz" | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
-    fail "frontend archive contains an unsafe path"
+restore_file() {
+  local backup="$1" target="$2"
+  if [[ -f "$backup" ]]; then cp -p "$backup" "$target"; else rm -f -- "$target"; fi
+}
+
+commit_traffic_and_state() {
+  local site_candidate="$1" upstream_candidate="$2" active_candidate="$3" previous_candidate="${4:-}" expected_version="$5"
+  local transaction expanded public_health public_version_url public_version rollback_failed=0
+  mkdir -p "$NGINX_DIR" "$STATE_DIR"
+  transaction="$(mktemp -d "$DEPLOY_ROOT/.nginx-switch.XXXXXX")"
+  [[ -f "$NGINX_SITE_FILE" ]] && cp -p "$NGINX_SITE_FILE" "$transaction/site.old"
+  [[ -f "$UPSTREAM_FILE" ]] && cp -p "$UPSTREAM_FILE" "$transaction/upstreams.old"
+  [[ -f "$ACTIVE_STATE" ]] && cp -p "$ACTIVE_STATE" "$transaction/active.old"
+  [[ -f "$PREVIOUS_STATE" ]] && cp -p "$PREVIOUS_STATE" "$transaction/previous.old"
+
+  exec 9>/tmp/wdyy-nginx-deploy.lock
+  flock -x 9
+  assert_project_ports_isolated
+  install -m 0644 "$site_candidate" "$NGINX_SITE_FILE"
+  install -m 0644 "$upstream_candidate" "$UPSTREAM_FILE"
+  if ! nginx -t; then
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    rm -rf -- "$transaction"
+    fail "Nginx candidate validation failed; project configuration restored"
+  fi
+  expanded="$(nginx -T 2>&1)" || {
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    rm -rf -- "$transaction"
+    fail "unable to inspect expanded Nginx configuration"
+  }
+  grep -Fq "# wdyy-project: $PROJECT_NAME" <<< "$expanded" || {
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    rm -rf -- "$transaction"
+    fail "shared Nginx does not include this project's site.conf"
+  }
+  if ! nginx -s reload; then
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    nginx -t && nginx -s reload || rollback_failed=1
+    rm -rf -- "$transaction"
+    [[ "$rollback_failed" -eq 0 ]] || fail "Nginx reload failed and old project configuration could not be restored"
+    fail "Nginx reload failed; old project configuration restored"
+  fi
+
+  public_health="$(endpoint_url "$DOCKER_BIND_IP" "$PROJECT_HTTP_PORT" /health)"
+  public_version_url="$(endpoint_url "$DOCKER_BIND_IP" "$PROJECT_HTTP_PORT" /api/version)"
+  if ! curl --fail --silent --show-error --retry 6 --retry-delay 1 --retry-connrefused "$public_health" >/dev/null ||
+    ! public_version="$(curl --fail --silent --show-error "$public_version_url")" ||
+    [[ "$public_version" != "$expected_version" ]]; then
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    nginx -t && nginx -s reload || rollback_failed=1
+    rm -rf -- "$transaction"
+    [[ "$rollback_failed" -eq 0 ]] || fail "public endpoint verification failed and old project traffic could not be restored"
+    fail "public endpoint verification failed; old project traffic restored"
+  fi
+
+  if ! install -m 0644 "$active_candidate" "$ACTIVE_STATE" || { [[ -n "$previous_candidate" ]] && ! install -m 0644 "$previous_candidate" "$PREVIOUS_STATE"; }; then
+    restore_file "$transaction/site.old" "$NGINX_SITE_FILE"
+    restore_file "$transaction/upstreams.old" "$UPSTREAM_FILE"
+    restore_file "$transaction/active.old" "$ACTIVE_STATE"
+    restore_file "$transaction/previous.old" "$PREVIOUS_STATE"
+    nginx -t && nginx -s reload || rollback_failed=1
+    rm -rf -- "$transaction"
+    [[ "$rollback_failed" -eq 0 ]] || fail "state commit failed and old traffic could not be restored"
+    fail "state commit failed; old project traffic and state restored"
   fi
+  [[ -n "$previous_candidate" ]] || rm -f -- "$PREVIOUS_STATE"
+  rm -rf -- "$transaction"
+  flock -u 9
+  exec 9>&-
 }
 
-start_release() {
-  local package_root release_dir target_color image compose_file
-  initialize_server_context
+deploy_release() {
+  local mode="$1" package_root target_color work site_candidate upstream_candidate active_candidate previous_candidate=
   read_release_pointer
   package_root="$DEPLOY_ROOT/$RELEASE_VERSION"
   validate_uploaded_package "$package_root"
-  mkdir -p "$STATE_DIR" "$RELEASES_DIR" "$DEPLOY_ROOT/logs" "$DEPLOY_ROOT/nginx"
-  render_nginx_site "$package_root/nginx/site.conf"
-
-  release_dir="$RELEASES_DIR/$RELEASE_VERSION"
-  rm -rf -- "$release_dir"
-  mkdir -p "$release_dir"
-  tar -xzf "$package_root/frontend.tar.gz" -C "$release_dir"
-  [[ -f "$release_dir/index.html" ]] || fail "frontend release missing index.html"
-  grep -Fq "/releases/$RELEASE_VERSION/" "$release_dir/index.html" ||
-    fail "frontend assets are not built with the versioned release URL"
-
-  docker load -i "$package_root/backend-image.tar"
-  image="$BACKEND_IMAGE_PREFIX:$RELEASE_VERSION"
-  docker image inspect "$image" >/dev/null
-  MIGRATIONS_DIR="$package_root/database/migrations" \
-    DATABASE_URL="$DATABASE_URL" \
-    "$package_root/scripts/apply-migrations.sh"
-
   read_active
-  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
-  compose_file="$(compose_file_for "$RELEASE_VERSION")"
-  if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
-      up -d --force-recreate backend-blue
+  if [[ "$mode" == start ]]; then
+    [[ -z "$ACTIVE_VERSION" ]] || fail "an active deployment already exists; use replace"
+    target_color=blue
   else
-    BACKEND_GREEN_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
-      up -d --force-recreate backend-green
+    [[ -n "$ACTIVE_VERSION" ]] || fail "no active deployment exists; use start"
+    [[ "$RELEASE_VERSION" != "$ACTIVE_VERSION" ]] || fail "replace version must differ from active version"
+    target_color=$([[ "$ACTIVE_COLOR" == blue ]] && printf green || printf blue)
   fi
-  verify_backend "$target_color" "$RELEASE_VERSION"
-  [[ -f "$ACTIVE_STATE" ]] && cp "$ACTIVE_STATE" "$PREVIOUS_STATE"
-  switch_traffic "$target_color" "$RELEASE_VERSION"
-  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$RELEASE_VERSION" > "$ACTIVE_STATE"
+  mkdir -p "$STATE_DIR" "$NGINX_DIR" "$DEPLOY_ROOT/logs"
+  assert_project_ports_isolated
+  load_release_images "$RELEASE_VERSION"
+  up_pair "$target_color" "$RELEASE_VERSION"
+  verify_pair "$target_color" "$RELEASE_VERSION"
+
+  work="$(mktemp -d "$DEPLOY_ROOT/.traffic-candidate.XXXXXX")"
+  site_candidate="$work/site.conf"; upstream_candidate="$work/upstreams.conf"; active_candidate="$work/active.env"
+  render_site_candidate "$package_root/nginx/site.conf" "$site_candidate"
+  write_upstream_candidate "$target_color" "$upstream_candidate"
+  write_state_candidate "$active_candidate" "$target_color" "$RELEASE_VERSION"
+  if [[ -n "$ACTIVE_VERSION" ]]; then
+    previous_candidate="$work/previous.env"
+    write_state_candidate "$previous_candidate" "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  fi
+  trap 'rm -rf -- "${work:-}"' EXIT
+  commit_traffic_and_state "$site_candidate" "$upstream_candidate" "$active_candidate" "$previous_candidate" "$RELEASE_VERSION"
+  rm -rf -- "$work"
+  trap - EXIT
+  echo "active release: $RELEASE_VERSION ($target_color)"
+  [[ "$DATABASE_MIGRATION_MODE" == manual ]] && echo "database migration was not executed; execute $package_root/database/apply-migrations.sh manually after approval"
+  return 0
 }
 
 restart_current() {
-  local target_color image compose_file
   read_active
-  [[ -n "$ACTIVE_VERSION" ]] || fail "no active version"
-  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
-  image="$BACKEND_IMAGE_PREFIX:$ACTIVE_VERSION"
-  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
-  [[ -f "$compose_file" ]] || fail "active version compose file is missing: $compose_file"
-  if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
-      up -d --force-recreate backend-blue
-  else
-    BACKEND_GREEN_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
-      up -d --force-recreate backend-green
-  fi
-  verify_backend "$target_color" "$ACTIVE_VERSION"
-  switch_traffic "$target_color" "$ACTIVE_VERSION"
-  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$ACTIVE_VERSION" > "$ACTIVE_STATE"
+  [[ -n "$ACTIVE_VERSION" ]] || fail "no active deployment"
+  validate_uploaded_package "$DEPLOY_ROOT/$ACTIVE_VERSION"
+  load_release_images "$ACTIVE_VERSION"
+  up_pair "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  verify_pair "$ACTIVE_COLOR" "$ACTIVE_VERSION"
 }
 
 stop_current() {
-  local compose_file
   read_active
-  [[ -n "$ACTIVE_VERSION" ]] || fail "no active version"
-  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
-  docker compose --project-name "$PROJECT_NAME" -f "$compose_file" down
+  [[ -n "$ACTIVE_VERSION" ]] || fail "no active deployment"
+  compose_for "$ACTIVE_VERSION" stop "frontend-$ACTIVE_COLOR" "backend-$ACTIVE_COLOR"
 }
 
 status_current() {
-  local compose_file
-  read_active
-  printf 'color=%s\nversion=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION"
-  [[ -n "$ACTIVE_VERSION" ]] || return 0
-  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
-  docker compose --project-name "$PROJECT_NAME" -f "$compose_file" ps
+  read_active; read_previous
+  printf 'active_color=%s\nactive_version=%s\nprevious_color=%s\nprevious_version=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION" "$PREVIOUS_COLOR" "$PREVIOUS_VERSION"
+  if [[ -n "$ACTIVE_VERSION" ]]; then
+    compose_for "$ACTIVE_VERSION" ps
+  fi
+}
+
+remove_project_docker() {
+  local value container_output network_output image_output
+  local -a container_ids=() network_ids=() image_references=()
+  container_output="$(docker ps -aq --filter "label=com.docker.compose.project=$PROJECT_NAME")"
+  while IFS= read -r value; do [[ -n "$value" ]] && container_ids+=("$value"); done <<< "$container_output"
+  ((${#container_ids[@]} == 0)) || docker rm -f "${container_ids[@]}"
+  network_output="$(docker network ls -q --filter "label=com.docker.compose.project=$PROJECT_NAME")"
+  while IFS= read -r value; do [[ -n "$value" ]] && network_ids+=("$value"); done <<< "$network_output"
+  ((${#network_ids[@]} == 0)) || docker network rm "${network_ids[@]}"
+  image_output="$(docker image ls --format '{{.Repository}}:{{.Tag}}' | awk -F: -v frontend="$FRONTEND_IMAGE_REPOSITORY" -v backend="$BACKEND_IMAGE_REPOSITORY" '($1 == frontend || $1 == backend) && $2 != "<none>" { print $0 }' | LC_ALL=C sort -u)"
+  while IFS= read -r value; do [[ -n "$value" ]] && image_references+=("$value"); done <<< "$image_output"
+  ((${#image_references[@]} == 0)) || docker image rm -f "${image_references[@]}"
+  echo "removed only Docker resources for project: $PROJECT_NAME"
 }
 
 rollback_version() {
-  local version="$1"
-  assert_version "$version"
-  [[ -f "$PREVIOUS_STATE" ]] || fail "no previous deployment"
-  # shellcheck disable=SC1090
-  source "$PREVIOUS_STATE"
-  [[ "$ACTIVE_COLOR" == blue || "$ACTIVE_COLOR" == green ]] || fail "invalid previous color state"
-  assert_version "$ACTIVE_VERSION"
-  [[ "$ACTIVE_VERSION" == "$version" ]] || fail "rollback target is not the retained previous version"
-  [[ -d "$RELEASES_DIR/$ACTIVE_VERSION" ]] || fail "previous frontend release is missing"
-  verify_backend "$ACTIVE_COLOR" "$ACTIVE_VERSION"
-  switch_traffic "$ACTIVE_COLOR" "$ACTIVE_VERSION"
-  cp "$ACTIVE_STATE" "$PREVIOUS_STATE.tmp"
-  cp "$PREVIOUS_STATE" "$ACTIVE_STATE"
-  mv "$PREVIOUS_STATE.tmp" "$PREVIOUS_STATE"
+  local requested="$1" work site_candidate upstream_candidate active_candidate previous_candidate
+  assert_version "$requested"
+  read_active; read_previous
+  [[ -n "$ACTIVE_VERSION" && -n "$PREVIOUS_VERSION" ]] || fail "active and previous deployment states are required"
+  [[ "$requested" == "$PREVIOUS_VERSION" ]] || fail "rollback target must equal previous version $PREVIOUS_VERSION"
+  verify_pair "$PREVIOUS_COLOR" "$PREVIOUS_VERSION"
+  work="$(mktemp -d "$DEPLOY_ROOT/.rollback-candidate.XXXXXX")"
+  site_candidate="$work/site.conf"; upstream_candidate="$work/upstreams.conf"; active_candidate="$work/active.env"; previous_candidate="$work/previous.env"
+  render_site_candidate "$DEPLOY_ROOT/$PREVIOUS_VERSION/nginx/site.conf" "$site_candidate"
+  write_upstream_candidate "$PREVIOUS_COLOR" "$upstream_candidate"
+  write_state_candidate "$active_candidate" "$PREVIOUS_COLOR" "$PREVIOUS_VERSION"
+  write_state_candidate "$previous_candidate" "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  trap 'rm -rf -- "${work:-}"' EXIT
+  commit_traffic_and_state "$site_candidate" "$upstream_candidate" "$active_candidate" "$previous_candidate" "$PREVIOUS_VERSION"
+  rm -rf -- "$work"
+  trap - EXIT
 }
 
 case "${1:-}" in
-  build)
-    [[ "$#" -eq 1 ]] || usage
-    build_release
-    ;;
-  start)
-    [[ "$#" -eq 1 ]] || usage
-    start_release
-    ;;
-  stop)
-    [[ "$#" -eq 1 ]] || usage
-    initialize_server_context
-    stop_current
-    ;;
-  restart)
-    [[ "$#" -eq 1 ]] || usage
-    initialize_server_context
-    restart_current
-    ;;
-  status)
-    [[ "$#" -eq 1 ]] || usage
-    initialize_server_context
-    status_current
-    ;;
-  rollback)
-    [[ "$#" -eq 2 ]] || usage
-    initialize_server_context
-    rollback_version "$2"
-    ;;
-  *)
-    usage
-    ;;
+  build) [[ "$#" -eq 1 ]] || usage; build_release ;;
+  start) [[ "$#" -eq 1 ]] || usage; initialize_server_context; deploy_release start ;;
+  replace) [[ "$#" -eq 1 ]] || usage; initialize_server_context; deploy_release replace ;;
+  restart) [[ "$#" -eq 1 ]] || usage; initialize_server_context; restart_current ;;
+  stop) [[ "$#" -eq 1 ]] || usage; initialize_server_context; stop_current ;;
+  remove) [[ "$#" -eq 1 ]] || usage; initialize_server_context; remove_project_docker ;;
+  status) [[ "$#" -eq 1 ]] || usage; initialize_server_context; status_current ;;
+  rollback) [[ "$#" -eq 2 ]] || usage; initialize_server_context; rollback_version "$2" ;;
+  *) usage ;;
 esac