@wdyy/skills 0.1.11 → 0.1.13

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

@@ -3,8 +3,11 @@ 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=
+STAGING_ROOT=
+DEPLOY_ROOT=
+OPERATION=
+CHECKSUM_TOOL=
 
 fail() {
   echo "$*" >&2
@@ -12,7 +15,10 @@ fail() {
 }
 
 usage() {
-  echo "usage: ./deploy.sh build|start|replace|restart|stop|remove|status|rollback <version>" >&2
+  echo "usage: ./deploy.sh build   # local project root" >&2
+  echo "       ./deploy.sh         # server: deploy the complete stack" >&2
+  echo "       ./deploy.sh stop    # server: stop the complete stack" >&2
+  echo "       ./deploy.sh status  # server: inspect stack status" >&2
   exit 2
 }
 
@@ -20,8 +26,17 @@ 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"
+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 "required SHA-256 command not found"
+  fi
+}
+
+checksum_value() {
+  if [[ "$CHECKSUM_TOOL" == sha256sum ]]; then sha256sum "$1" | awk '{print $1}'
+  else shasum -a 256 "$1" | awk '{print $1}'
+  fi
 }
 
 assert_port() {
@@ -30,65 +45,51 @@ assert_port() {
   (( value >= 1 && value <= 65535 )) || fail "$name must be between 1 and 65535"
 }
 
+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"
+}
+
 reset_configuration() {
-  unset PROJECT_NAME 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
-  unset FRONTEND_DOCKERFILE BACKEND_DOCKERFILE DOCKERIGNORE_FILE
-  unset DEPLOY_CONFIG_DIR
-  unset COMPOSE_SOURCE NGINX_SOURCE
+  unset DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA
+  unset PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
 }
 
-is_deployment_key() {
+is_configuration_key() {
   case "$1" in
-    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|\
-    PROJECT_NAME|PROJECT_HTTP_PORT|DOCKER_BIND_IP|\
-    FRONTEND_BLUE_PORT|FRONTEND_GREEN_PORT|BACKEND_BLUE_PORT|BACKEND_GREEN_PORT|\
-    FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE|\
-    FRONTEND_DOCKERFILE|BACKEND_DOCKERFILE|DOCKERIGNORE_FILE|\
-    DEPLOY_CONFIG_DIR|COMPOSE_SOURCE|NGINX_SOURCE)
+    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|DB_URL|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|DB_SCHEMA|PROJECT_NAME|DOCKER_BIND_IP|FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE)
       return 0 ;;
     *) return 1 ;;
   esac
 }
 
-is_legacy_configuration_key() {
+is_removed_key() {
   case "$1" in
-    FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|DATABASE_MIGRATION_MODE|MIGRATIONS_SOURCE|MIGRATION_RUNNER_SOURCE|*_HEALTH_URL|*_VERSION_URL)
+    PROJECT_HTTP_PORT|FRONTEND_BLUE_PORT|FRONTEND_GREEN_PORT|BACKEND_BLUE_PORT|BACKEND_GREEN_PORT|SERVER_PROJECTS_ROOT|NGINX_SOURCE|LOG_DIR|HOST_LOG_DIR|FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|DATABASE_MIGRATION_MODE|MIGRATIONS_SOURCE|MIGRATION_RUNNER_SOURCE|RELEASE_VERSION|*_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 file="$1" raw line key value first last loaded
   local -a loaded_keys=()
-  [[ -r "$file" ]] || fail "required root environment file is missing: $file"
+  [[ -r "$file" && -f "$file" && ! -L "$file" ]] || fail "required root environment file is missing or unsafe: $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"
+    [[ "$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
+    ! is_removed_key "$key" || fail "removed deployment configuration is forbidden: $key"
+    [[ "$value" != *'$('* && "$value" != *'`'* ]] || fail "executable syntax is forbidden in .env: $key"
+    for loaded in "${loaded_keys[@]:-}"; do [[ "$loaded" != "$key" ]] || fail "duplicate .env key: $key"; done
     loaded_keys+=("$key")
     if [[ ${#value} -ge 2 ]]; then
       first="${value:0:1}"
@@ -98,224 +99,33 @@ load_dotenv() {
         value="${value:1:${#value}-2}"
       fi
     fi
-    if is_deployment_key "$key"; then
-      printf -v "$key" '%s' "$value"
-      export "$key"
-    fi
+    if is_configuration_key "$key"; then printf -v "$key" '%s' "$value"; fi
   done < "$file"
 }
 
 validate_configuration() {
-  local name port seen=" "
-  local -a required=(
-    FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT
-    PROJECT_NAME PROJECT_HTTP_PORT DOCKER_BIND_IP
-    FRONTEND_BLUE_PORT FRONTEND_GREEN_PORT BACKEND_BLUE_PORT BACKEND_GREEN_PORT
-    FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
-  )
-  for name in "${required[@]}"; do
-    [[ -n "${!name:-}" ]] || fail "$name is required in root .env"
+  local key value
+  for key in FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE; do
+    value="${!key:-}"
+    [[ -n "$value" ]] || fail "required configuration is missing: $key"
   done
-  [[ "$PROJECT_NAME" =~ ^[a-z][a-z0-9_]*$ ]] ||
-    fail "PROJECT_NAME must match ^[a-z][a-z0-9_]*$"
-  [[ "$DOCKER_BIND_IP" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "DOCKER_BIND_IP contains unsafe characters"
+  [[ "$PROJECT_NAME" =~ ^[a-z][a-z0-9_]*$ ]] || fail "PROJECT_NAME must match ^[a-z][a-z0-9_]*$"
   [[ "$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
-}
-
-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)
+  [[ "$DOCKER_BIND_IP" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "DOCKER_BIND_IP contains unsafe characters"
+  [[ "$DB_URL" =~ ^[A-Za-z0-9._:/?@\&=%-]+$ ]] || fail "DB_URL contains unsafe characters"
+  [[ "$FRONTEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "FRONTEND_BASE_IMAGE is not a valid image reference"
+  [[ "$BACKEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "BACKEND_BASE_IMAGE is not a valid image reference"
+  assert_port FRONTEND_PORT "$FRONTEND_PORT"
+  assert_port BACKEND_PORT "$BACKEND_PORT"
+  assert_port DB_PORT "$DB_PORT"
+  [[ "$FRONTEND_PORT" != "$BACKEND_PORT" ]] || fail "FRONTEND_PORT and BACKEND_PORT must differ"
 }
 
 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
+  [[ -f "$file" && ! -L "$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
@@ -323,441 +133,191 @@ validate_dockerignore() {
   done < "$file"
 }
 
-validate_local_package() {
-  local output_root="$1" version="$2" version_root="$1/$2"
-  [[ -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"
-  [[ ! -e "$version_root/database" ]] || fail "release package must not contain database migration files"
-  [[ "$(find "$version_root" -type f ! -name manifest.sha256 | wc -l | tr -d ' ')" -ge 4 ]] || fail "release package is incomplete"
-  reject_version_secrets "$version_root"
-  verify_manifest "$version_root"
+create_manifest() {
+  local root="$1" file checksum
+  : > "$root/manifest.sha256"
+  for file in .env backend-image.tar deploy.sh docker-compose.yml frontend-image.tar; do
+    checksum="$(checksum_value "$root/$file")"
+    printf '%s  %s\n' "$checksum" "$file" >> "$root/manifest.sha256"
+  done
+}
+
+verify_manifest() {
+  local root="$1" line checksum relative actual count=0
+  [[ -s "$root/manifest.sha256" && ! -L "$root/manifest.sha256" ]] || fail "missing or unsafe manifest.sha256"
+  while IFS= read -r line; do
+    checksum="${line%%  *}"
+    relative="${line#*  }"
+    [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$relative" != *'/'* ]] || fail "invalid manifest entry"
+    [[ -f "$root/$relative" && ! -L "$root/$relative" ]] || fail "manifest path is missing: $relative"
+    actual="$(checksum_value "$root/$relative")"
+    [[ "$actual" == "$checksum" ]] || fail "checksum mismatch: $relative"
+    count=$((count + 1))
+  done < "$root/manifest.sha256"
+  [[ "$count" == 5 ]] || fail "manifest must contain exactly five entries"
+  [[ "$(sed -n 's/^[0-9a-f]\{64\}  //p' "$root/manifest.sha256" | LC_ALL=C sort | tr '\n' '|')" == '.env|backend-image.tar|deploy.sh|docker-compose.yml|frontend-image.tar|' ]] || fail "manifest coverage is incomplete"
+}
+
+validate_package_layout() {
+  local root="$1" entry name
+  for name in .env backend-image.tar deploy.sh docker-compose.yml frontend-image.tar manifest.sha256; do
+    [[ -f "$root/$name" && ! -L "$root/$name" ]] || fail "required package file is missing or unsafe: $name"
+  done
+  while IFS= read -r entry; do
+    name="${entry##*/}"
+    case "$name" in
+      .env|backend-image.tar|deploy.sh|docker-compose.yml|frontend-image.tar|manifest.sha256) ;;
+      logs) [[ -d "$entry" && ! -L "$entry" ]] || fail "logs must be a regular directory" ;;
+      *) fail "unexpected package entry: $name" ;;
+    esac
+  done < <(find "$root" -mindepth 1 -maxdepth 1 -print | LC_ALL=C sort)
+}
+
+archive_has_tag() {
+  local archive="$1" tag="$2" manifest compact count
+  [[ -f "$archive" && ! -L "$archive" ]] || fail "image archive is missing: $archive"
+  manifest="$(tar -xOf "$archive" manifest.json 2>/dev/null)" || fail "image archive is missing manifest.json: $archive"
+  compact="$(tr -d '[:space:]' <<< "$manifest")"
+  count="$(grep -o '"RepoTags"' <<< "$compact" | wc -l | tr -d ' ')"
+  [[ "$count" == 1 && "$compact" == *"\"RepoTags\":[\"$tag\"]"* ]] || fail "image archive must contain exactly the expected tag: $tag"
 }
 
 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"
+  mkdir "$BUILD_LOCK" 2>/dev/null || fail "another build is active or a stale lock exists: $BUILD_LOCK"
 }
 
-release_build_lock() {
-  [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]] && rmdir "$BUILD_LOCK"
+cleanup_build() {
+  local status=$?
+  if [[ -n "${STAGING_ROOT:-}" && -d "$STAGING_ROOT" ]]; then rm -rf -- "$STAGING_ROOT"; fi
+  if [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]]; then rmdir "$BUILD_LOCK" 2>/dev/null || true; fi
+  return "$status"
 }
 
-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 staging_parent output_root version_root agents_prepared old_deploy
+ensure_deploy_output_scope() {
+  local deploy_dir="$1" archive_name="$2" entry
+  mkdir -p "$deploy_dir"
+  [[ -d "$deploy_dir" && ! -L "$deploy_dir" ]] || fail "deploy output must be a regular directory"
+  while IFS= read -r entry; do
+    [[ "${entry##*/}" == "$archive_name" && -f "$entry" && ! -L "$entry" ]] || fail "deploy directory contains unexpected entry: ${entry##*/}"
+  done < <(find "$deploy_dir" -mindepth 1 -maxdepth 1 -print)
+}
 
-  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"
+build_release() {
+  local project_root="$SCRIPT_DIR" frontend_dockerfile backend_dockerfile compose_source dockerignore_file
+  local frontend_image backend_image package_root deploy_dir archive_name candidate
+  for command in docker tar install find sort grep sed awk mktemp; do require_command "$command"; done
+  select_checksum_tool
   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}")"
-
-  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"
+  frontend_dockerfile="$project_root/src/frontend/Dockerfile"
+  backend_dockerfile="$project_root/src/backend/Dockerfile"
+  compose_source="$project_root/scripts/deployment/docker-compose.yml"
+  dockerignore_file="$project_root/.dockerignore"
+  for file in "$frontend_dockerfile" "$backend_dockerfile" "$compose_source"; do
+    [[ -f "$file" && ! -L "$file" ]] || fail "required generated deployment file is missing: ${file#"$project_root"/}"
+  done
   validate_dockerignore "$dockerignore_file"
-
-  today="$(date +%Y%m%d)"
-  version="$(release_ledger next "$agents_file" "$today")"
-  assert_version "$version"
-  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"
-  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=
+  docker image inspect "$FRONTEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local frontend base image is missing: $FRONTEND_BASE_IMAGE"
+  docker image inspect "$BACKEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local backend base image is missing: $BACKEND_BASE_IMAGE"
+  frontend_image="${PROJECT_NAME}_frontend:latest"
+  backend_image="${PROJECT_NAME}_backend:latest"
+  acquire_build_lock
+  trap cleanup_build EXIT
+  docker build --pull=false --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
+  docker build --pull=false --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
+  docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "frontend image build did not create $frontend_image"
+  docker image inspect "$backend_image" >/dev/null 2>&1 || fail "backend image build did not create $backend_image"
+  STAGING_ROOT="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"
+  package_root="$STAGING_ROOT/package"
+  mkdir -p "$package_root"
+  install -m 0600 "$project_root/.env" "$package_root/.env"
+  install -m 0755 "$SCRIPT_PATH" "$package_root/deploy.sh"
+  install -m 0644 "$compose_source" "$package_root/docker-compose.yml"
+  docker save -o "$package_root/frontend-image.tar" "$frontend_image"
+  docker save -o "$package_root/backend-image.tar" "$backend_image"
+  archive_has_tag "$package_root/frontend-image.tar" "$frontend_image"
+  archive_has_tag "$package_root/backend-image.tar" "$backend_image"
+  create_manifest "$package_root"
+  validate_package_layout "$package_root"
+  verify_manifest "$package_root"
+  deploy_dir="$project_root/deploy"
+  archive_name="${PROJECT_NAME}-docker.tar.gz"
+  ensure_deploy_output_scope "$deploy_dir" "$archive_name"
+  candidate="$STAGING_ROOT/$archive_name"
+  tar -czf "$candidate" -C "$package_root" .
+  tar -tzf "$candidate" >/dev/null || fail "generated delivery archive is invalid"
+  mv -f "$candidate" "$deploy_dir/$archive_name"
+  rm -rf -- "$STAGING_ROOT"
+  STAGING_ROOT=
+  rmdir "$BUILD_LOCK"
+  BUILD_LOCK=
   trap - EXIT
-  echo "release package created: deploy/$version"
-  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"
+  echo "delivery archive created: deploy/$archive_name"
 }
 
 initialize_server_context() {
   DEPLOY_ROOT="$SCRIPT_DIR"
+  for command in docker tar find sort grep sed awk; do require_command "$command"; done
+  select_checksum_tool
   load_dotenv "$DEPLOY_ROOT/.env"
   validate_configuration
-  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
+  [[ -f "$DEPLOY_ROOT/docker-compose.yml" && ! -L "$DEPLOY_ROOT/docker-compose.yml" ]] || fail "docker-compose.yml is missing"
+  mkdir -p "$DEPLOY_ROOT/logs"
 }
 
-write_state_candidate() {
-  local file="$1" color="$2" version="$3"
-  printf 'ACTIVE_COLOR=%s\nACTIVE_VERSION=%s\n' "$color" "$version" > "$file"
+compose() {
+  docker compose --env-file "$DEPLOY_ROOT/.env" --project-name "$PROJECT_NAME" -f "$DEPLOY_ROOT/docker-compose.yml" "$@"
 }
 
-compose_file_for() {
-  local version="$1"
-  assert_version "$version"
-  printf '%s/%s/docker/docker-compose.blue-green.yml\n' "$DEPLOY_ROOT" "$version"
+record_operation() {
+  local result="$1" timestamp
+  [[ -n "$DEPLOY_ROOT" && -d "$DEPLOY_ROOT/logs" && -n "$OPERATION" ]] || return 0
+  timestamp="$(date '+%Y-%m-%d %H:%M:%S %z')"
+  printf '%s operation=%s result=%s\n' "$timestamp" "$OPERATION" "$result" >> "$DEPLOY_ROOT/logs/deploy.log"
 }
 
-image_names_for() {
-  local version="$1"
-  assert_version "$version"
-  FRONTEND_IMAGE="${FRONTEND_IMAGE_REPOSITORY}:$version"
-  BACKEND_IMAGE="${BACKEND_IMAGE_REPOSITORY}:$version"
+deploy_stack() {
+  local frontend_image="${PROJECT_NAME}_frontend:latest" backend_image="${PROJECT_NAME}_backend:latest"
+  validate_package_layout "$DEPLOY_ROOT"
+  verify_manifest "$DEPLOY_ROOT"
+  archive_has_tag "$DEPLOY_ROOT/frontend-image.tar" "$frontend_image"
+  archive_has_tag "$DEPLOY_ROOT/backend-image.tar" "$backend_image"
+  docker load -i "$DEPLOY_ROOT/frontend-image.tar" >/dev/null
+  docker load -i "$DEPLOY_ROOT/backend-image.tar" >/dev/null
+  docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "loaded frontend image is missing: $frontend_image"
+  docker image inspect "$backend_image" >/dev/null 2>&1 || fail "loaded backend image is missing: $backend_image"
+  compose up -d --force-recreate --no-build --pull never --wait frontend backend
 }
 
-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"
-  [[ ! -e "$package_root/database" ]] || fail "release package must not contain database migration files"
-  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__ __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|__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"
-}
-
-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 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
-  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
-  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
-  if [[ "$mode" == start ]]; then
-    [[ -z "$ACTIVE_VERSION" ]] || fail "an active deployment already exists; use replace"
-    target_color=blue
-  else
-    [[ -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
-  mkdir -p "$STATE_DIR" "$NGINX_DIR" "$DEPLOY_ROOT/logs"
-  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"
+run_logged_operation() {
+  local operation="$1"
+  shift
+  OPERATION="$operation"
+  trap 'status=$?; if [[ $status -eq 0 ]]; then record_operation success; else record_operation failure; fi' EXIT
+  "$@"
   trap - EXIT
-  echo "active release: $RELEASE_VERSION ($target_color)"
-  return 0
+  record_operation success
 }
 
-restart_current() {
-  read_active
-  [[ -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"
+server_deploy() {
+  initialize_server_context
+  run_logged_operation deploy deploy_stack
 }
 
-stop_current() {
-  read_active
-  [[ -n "$ACTIVE_VERSION" ]] || fail "no active deployment"
-  compose_for "$ACTIVE_VERSION" stop "frontend-$ACTIVE_COLOR" "backend-$ACTIVE_COLOR"
+server_stop() {
+  initialize_server_context
+  run_logged_operation stop compose stop frontend backend
 }
 
-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
-}
-
-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 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
+server_status() {
+  initialize_server_context
+  compose ps frontend backend
 }
 
-case "${1:-}" in
-  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
+if [[ "$#" -eq 0 ]]; then server_deploy
+elif [[ "$#" -eq 1 && "$1" == build ]]; then build_release
+elif [[ "$#" -eq 1 && "$1" == stop ]]; then server_stop
+elif [[ "$#" -eq 1 && "$1" == status ]]; then server_status
+else usage
+fi