@wdyy/skills 0.1.5 → 0.1.7

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

@@ -1,171 +1,864 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-: "${PROJECT_NAME:?PROJECT_NAME is required}"
-: "${DATABASE_URL:?DATABASE_URL is required}"
-
-DEPLOY_ROOT="${DEPLOY_ROOT:-/srv/$PROJECT_NAME}"
-COMPOSE_FILE="${COMPOSE_FILE:-$DEPLOY_ROOT/deploy/docker/docker-compose.blue-green.yml}"
-UPSTREAM_FILE="${UPSTREAM_FILE:-$DEPLOY_ROOT/deploy/nginx/backend-active.conf}"
-MIGRATION_RUNNER="${MIGRATION_RUNNER:-$DEPLOY_ROOT/scripts/apply-migrations.sh}"
-BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
-BLUE_PORT="${BLUE_PORT:-3001}"
-GREEN_PORT="${GREEN_PORT:-3002}"
-STATE_DIR="$DEPLOY_ROOT/state"
-ACTIVE_STATE="$STATE_DIR/active.env"
-PREVIOUS_STATE="$STATE_DIR/previous.env"
-INCOMING_DIR="$DEPLOY_ROOT/incoming"
-RELEASES_DIR="$DEPLOY_ROOT/releases"
-
-mkdir -p "$STATE_DIR" "$RELEASES_DIR"
+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
+  exit 1
+}
+
+usage() {
+  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}$ ]] || {
-    echo "version must match YYYYMMDD-NNN" >&2
-    exit 2
-  }
+  [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || fail "version must match YYYYMMDD-NNN"
 }
 
-read_active() {
-  ACTIVE_COLOR=green
-  ACTIVE_VERSION=
-  if [[ -f "$ACTIVE_STATE" ]]; then
-    # shellcheck disable=SC1090
-    source "$ACTIVE_STATE"
-  fi
-}
-
-port_for() {
-  [[ "$1" == blue ]] && printf '%s' "$BLUE_PORT" || printf '%s' "$GREEN_PORT"
-}
-
-switch_traffic() {
-  local color="$1" version="$2" port backup
-  port="$(port_for "$color")"
-  backup="$UPSTREAM_FILE.previous"
-  printf 'upstream backend_active {\n  server 127.0.0.1:%s;\n  keepalive 32;\n}\n' "$port" > "$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
+assert_port() {
+  local name="$1" value="$2"
+  [[ "$value" =~ ^[0-9]+$ ]] || fail "$name must be a numeric port"
+  (( value >= 1 && value <= 65535 )) || fail "$name must be between 1 and 65535"
+}
+
+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
-    echo "failed to switch Nginx upstream" >&2
-    return 1
-  fi
-  rm -f "$backup"
-  ln -sfn "releases/$version" "$DEPLOY_ROOT/current.new"
-  mv -Tf "$DEPLOY_ROOT/current.new" "$DEPLOY_ROOT/current"
-}
-
-verify_backend() {
-  local color="$1" version="$2" port health_url version_url actual
-  port="$(port_for "$color")"
-  health_url="http://127.0.0.1:$port/health"
-  version_url="http://127.0.0.1:$port/version"
-  HEALTH_URL="$health_url"
-  VERSION_URL="$version_url"
-  curl --fail --silent --show-error --retry 12 --retry-delay 2 "$HEALTH_URL"
-  actual="$(curl --fail --silent --show-error "$VERSION_URL")"
-  [[ "$actual" == "$version" ]] || {
-    echo "backend version mismatch: expected $version, got $actual" >&2
-    exit 1
+    if is_deployment_key "$key"; then
+      printf -v "$key" '%s' "$value"
+      export "$key"
+    fi
+  done < "$file"
+}
+
+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"
+}
+
+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() {
+  local project_root="$1" candidate="$2"
+  if [[ "$candidate" = /* ]]; then
+    printf '%s\n' "$candidate"
+  else
+    printf '%s/%s\n' "$project_root" "$candidate"
+  fi
+}
+
+select_checksum_tool() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    CHECKSUM_TOOL=sha256sum
+  elif command -v shasum >/dev/null 2>&1; then
+    CHECKSUM_TOOL=shasum
+  else
+    fail "sha256sum or shasum is required"
+  fi
+}
+
+checksum_value() {
+  local file="$1"
+  if [[ "$CHECKSUM_TOOL" == sha256sum ]]; then
+    sha256sum "$file" | awk '{print $1}'
+  else
+    shasum -a 256 "$file" | awk '{print $1}'
+  fi
+}
+
+release_ledger() {
+  node --input-type=module - "$@" <<'NODE'
+import fs from 'node:fs';
+
+const [mode, agentsPath, value, timestamp, outputPath] = process.argv.slice(2);
+const heading = '## 发布记录';
+const header = '| 版本号 | 构建时间 |';
+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 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 inspect(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  const headings = lines.flatMap((line, index) => line === heading ? [index] : []);
+  if (headings.length > 1) fail('AGENTS.md contains multiple release record sections');
+  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; }
+  }
+  const section = lines.slice(headingIndex + 1, endIndex);
+  while (section[0] === '') section.shift();
+  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 || !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, 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 = inspect(original);
+if (mode === 'next') {
+  process.stdout.write(`${nextVersion(ledger, value)}\n`);
+} else if (mode === 'prepare') {
+  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 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;
+    while (insertAt > ledger.headingIndex + 1 && lines[insertAt - 1] === '') insertAt -= 1;
+    lines.splice(insertAt, 0, row);
+    updated = lines.join('\n');
   }
+  fs.writeFileSync(outputPath, updated, { mode: fs.statSync(agentsPath).mode });
+} else {
+  fail(`unknown release ledger mode: ${mode}`);
+}
+NODE
+}
+
+create_manifest() {
+  local version_root="$1" file relative checksum
+  (
+    cd "$version_root"
+    find . -type f ! -name manifest.sha256 -print | LC_ALL=C sort |
+      while IFS= read -r file; do
+        relative="${file#./}"
+        checksum="$(checksum_value "$file")"
+        printf '%s  %s\n' "$checksum" "$relative"
+      done > manifest.sha256
+  )
+}
+
+verify_manifest() {
+  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)"
+  if (
+    cd "$version_root"
+    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#*  }"
+      [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$relative" != ../* && "$relative" != *"/../"* ]] || exit 11
+      printf '%s\n' "$relative" >> "$declared_paths"
+      [[ -f "$relative" && ! -L "$relative" ]] || exit 12
+      actual="$(checksum_value "$relative")"
+      [[ "$actual" == "$checksum" ]] || exit 13
+    done < manifest.sha256
+    LC_ALL=C sort -o "$declared_paths" "$declared_paths"
+    [[ "$(uniq -d "$declared_paths" | wc -l | tr -d ' ')" == 0 ]] || exit 14
+    cmp -s "$actual_paths" "$declared_paths"
+  ); then
+    result=0
+  else
+    result=$?
+  fi
+  rm -f -- "$actual_paths" "$declared_paths"
+  [[ "$result" -eq 0 ]] || fail "release manifest validation failed"
+}
+
+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
+  while IFS= read -r file; do
+    base="${file##*/}"
+    case "$base" in
+      .env|.env.*|*.pem|*.key|id_rsa|id_ed25519|credentials|credentials.*)
+        fail "secret file must not enter the version directory: ${file#"$root"/}" ;;
+    esac
+  done < <(find "$root" -type f -print)
 }
 
-start_version() {
-  local version="$1" source_dir release_dir target_color image
+validate_dockerignore() {
+  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/' '.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" version_root="$1/$2"
+  local expected_count
+  [[ -x "$output_root/deploy.sh" ]] || fail "generated deploy.sh is missing or not executable"
+  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"
+}
+
+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"
+}
+
+release_build_lock() {
+  [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]] && rmdir "$BUILD_LOCK"
+}
+
+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}")"
+
+  for command in node pnpm docker tar install find sort cmp awk sed grep uniq; do require_command "$command"; done
+  select_checksum_tool
+  [[ -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"
+  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"
-  source_dir="$INCOMING_DIR/$version"
-  release_dir="$RELEASES_DIR/$version"
-  [[ -f "$source_dir/frontend.tar.gz" ]] || { echo "missing frontend.tar.gz" >&2; exit 1; }
-  [[ -f "$source_dir/backend-image.tar" ]] || { echo "missing backend-image.tar" >&2; exit 1; }
-  [[ -d "$source_dir/database/migrations" ]] || { echo "missing database/migrations" >&2; exit 1; }
-
-  rm -rf "$release_dir"
-  mkdir -p "$release_dir"
-  if tar -tzf "$source_dir/frontend.tar.gz" | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
-    echo "frontend archive contains an unsafe path" >&2
-    exit 1
-  fi
-  tar -xzf "$source_dir/frontend.tar.gz" -C "$release_dir"
-  [[ -f "$release_dir/index.html" ]] || { echo "frontend release missing index.html" >&2; exit 1; }
-  grep -q "/releases/$version/" "$release_dir/index.html" || {
-    echo "frontend assets are not built with the versioned release URL" >&2
-    exit 1
+  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"
+  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"
+  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"
+
+  raw_time="$(date '+%Y-%m-%d %H:%M:%S %z')"
+  build_time="${raw_time%?????}${raw_time: -5:3}:${raw_time: -2}"
+  release_ledger prepare "$agents_file" "$version" "$build_time" "$agents_prepared"
+
+  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
+  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" && "$(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]}"
+  assert_version "$RELEASE_VERSION"
+}
+
+initialize_server_context() {
+  local expected_root
+  DEPLOY_ROOT="$SCRIPT_DIR"
+  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"
+  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=; ACTIVE_VERSION=
+  if read_state_file "$ACTIVE_STATE"; then ACTIVE_COLOR="$STATE_COLOR"; ACTIVE_VERSION="$STATE_VERSION"; fi
+}
+
+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() {
+  local version="$1"
+  assert_version "$version"
+  printf '%s/%s/docker/docker-compose.blue-green.yml\n' "$DEPLOY_ROOT" "$version"
+}
+
+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
+  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"
+}
+
+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
+    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
+    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
+  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
+}
+
+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"
   }
-  docker load -i "$source_dir/backend-image.tar"
-  image="$BACKEND_IMAGE_PREFIX:$version"
-  docker image inspect "$image" >/dev/null
-  MIGRATIONS_DIR="$source_dir/database/migrations" "$MIGRATION_RUNNER"
+  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>&-
+}
 
+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"
   read_active
-  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
-  if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose -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 -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" "$version"
-  [[ -f "$ACTIVE_STATE" ]] && cp "$ACTIVE_STATE" "$PREVIOUS_STATE"
-  switch_traffic "$target_color" "$version"
-  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$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() {
   read_active
-  [[ -n "$ACTIVE_VERSION" ]] || { echo "no active version" >&2; exit 1; }
-  local target_color image
-  target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
-  image="$BACKEND_IMAGE_PREFIX:$ACTIVE_VERSION"
-  if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-blue
-  else
-    BACKEND_GREEN_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-green
+  [[ -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() {
+  read_active
+  [[ -n "$ACTIVE_VERSION" ]] || fail "no active deployment"
+  compose_for "$ACTIVE_VERSION" stop "frontend-$ACTIVE_COLOR" "backend-$ACTIVE_COLOR"
+}
+
+status_current() {
+  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
-  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"
+}
+
+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" ]] || { echo "no previous deployment" >&2; exit 1; }
-  # shellcheck disable=SC1090
-  source "$PREVIOUS_STATE"
-  [[ "$ACTIVE_VERSION" == "$version" ]] || { echo "rollback target is not the retained previous version" >&2; exit 1; }
-  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
-  start)
-    version="$2"
-    start_version "$version"
-    ;;
-  stop)
-    docker compose -f "$COMPOSE_FILE" down
-    ;;
-  restart)
-    restart_current
-    ;;
-  status)
-    read_active
-    printf 'color=%s\nversion=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION"
-    docker compose -f "$COMPOSE_FILE" ps
-    ;;
-  rollback)
-    version="$2"
-    rollback_version "$version"
-    ;;
-  *)
-    echo "usage: ./deploy.sh start <version>|stop|restart|status|rollback <version>" >&2
-    exit 2
-    ;;
+  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