@wdyy/skills 0.1.10 → 0.1.12

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

@@ -5,6 +5,9 @@ SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -
 SCRIPT_PATH="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
 CHECKSUM_TOOL=
 BUILD_LOCK=
+DEPLOY_ROOT=
+RELEASE_VERSION=
+OPERATION=
 
 fail() {
   echo "$*" >&2
@@ -12,7 +15,8 @@ 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 project root menu" >&2
   exit 2
 }
 
@@ -31,31 +35,29 @@ assert_port() {
 }
 
 reset_configuration() {
-  unset PROJECT_NAME SERVER_PROJECTS_ROOT PROJECT_HTTP_PORT DOCKER_BIND_IP
+  unset PROJECT_NAME 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_BASE_IMAGE BACKEND_BASE_IMAGE
   unset FRONTEND_DOCKERFILE BACKEND_DOCKERFILE DOCKERIGNORE_FILE
-  unset MIGRATIONS_SOURCE MIGRATION_RUNNER_SOURCE DEPLOY_CONFIG_DIR
-  unset COMPOSE_SOURCE NGINX_SOURCE
+  unset DEPLOY_CONFIG_DIR COMPOSE_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)
+    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|PROJECT_NAME|DOCKER_BIND_IP|\
+    FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE|FRONTEND_DOCKERFILE|BACKEND_DOCKERFILE|\
+    DOCKERIGNORE_FILE|DEPLOY_CONFIG_DIR|COMPOSE_SOURCE)
       return 0 ;;
     *) return 1 ;;
   esac
 }
 
-is_legacy_configuration_key() {
+is_removed_configuration_key() {
   case "$1" in
-    FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|BACKEND_LISTEN_HOST|*_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|*_HEALTH_URL|*_VERSION_URL)
       return 0 ;;
     *) return 1 ;;
   esac
@@ -63,16 +65,12 @@ is_legacy_configuration_key() {
 
 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
+  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_key
   local -a loaded_keys=()
   [[ -r "$file" ]] || fail "required root environment file is missing: $file"
   validate_env_permissions "$file"
@@ -80,60 +78,31 @@ load_dotenv() {
   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
+    [[ "$line" =~ ^([A-Za-z_][A-Za-z0-9_]*)=(.*)$ ]] || fail "invalid .env line; expected KEY=VALUE"
+    key="${BASH_REMATCH[1]}"; value="${BASH_REMATCH[2]}"
+    ! is_removed_configuration_key "$key" || fail "removed deployment configuration 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}"
+      first="${value:0:1}"; last="${value: -1}"
       if [[ "$first" == "'" || "$first" == '"' ]]; then
         [[ "$last" == "$first" ]] || fail "unclosed quoted .env value: $key"
         value="${value:1:${#value}-2}"
       fi
     fi
-    if is_deployment_key "$key"; then
-      printf -v "$key" '%s' "$value"
-      export "$key"
-    fi
+    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
-  [[ "$DATABASE_MIGRATION_MODE" == manual || "$DATABASE_MIGRATION_MODE" == none ]] ||
-    fail "DATABASE_MIGRATION_MODE must be manual or none"
+  local name
+  local -a required=(FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE)
+  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_]*$"
+  for name in DOCKER_BIND_IP FRONTEND_URL BACKEND_URL; do [[ "${!name}" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "$name contains unsafe characters"; done
+  assert_port FRONTEND_PORT "$FRONTEND_PORT"
+  assert_port BACKEND_PORT "$BACKEND_PORT"
+  [[ "$FRONTEND_PORT" != "$BACKEND_PORT" ]] || fail "FRONTEND_PORT and BACKEND_PORT must be different"
 }
 
 probe_host() {
@@ -153,708 +122,248 @@ endpoint_url() {
 
 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
+  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"
+  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
+  if [[ "$CHECKSUM_TOOL" == sha256sum ]]; then sha256sum "$1" | awk '{print $1}'; else shasum -a 256 "$1" | 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 validDate(text) { const y=Number(text.slice(0,4)),m=Number(text.slice(4,6)),d=Number(text.slice(6,8)),date=new Date(Date.UTC(y,m-1,d)); return date.getUTCFullYear()===y&&date.getUTCMonth()===m-1&&date.getUTCDate()===d; }
 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}`);
-}
+  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(),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 max=ledger.versions.filter(item=>item.startsWith(`${date}-`)).reduce((result,item)=>Math.max(result,Number(item.slice(-3))),0);if(max>=999)fail(`release sequence exhausted for ${date}`);return `${date}-${String(max+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(!/^\d{8}-\d{3}$/.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
-  )
+  (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"
+  local root="$1" line checksum relative actual
+  [[ -s "$root/manifest.sha256" ]] || fail "missing or empty manifest.sha256"
+  while IFS= read -r line; do
+    checksum="${line%%  *}"; relative="${line#*  }"
+    [[ "$checksum" =~ ^[0-9a-f]{64}$ && "$relative" != "$line" && "$relative" != /* && "$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"
+  done < "$root/manifest.sha256"
+  local actual_paths declared_paths
+  actual_paths="$(cd "$root"; find . -type f ! -name manifest.sha256 -print | sed 's|^./||' | LC_ALL=C sort)"
+  declared_paths="$(sed -n 's/^[0-9a-f]\{64\}  //p' "$root/manifest.sha256" | LC_ALL=C sort)"
+  [[ "$actual_paths" == "$declared_paths" ]] || fail "manifest coverage is incomplete"
 }
 
 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)
+  ! find "$root" -type l -print -quit | grep -q . || fail "symbolic links must not be packaged"
+  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 version directory: ${file#"$root"/}" ;; esac; done < <(find "$root" -type f -print)
 }
 
 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"
+  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
+  local output_root="$1" version="$2" version_root="$1/$2" compose="$1/$2/docker/docker-compose.yml"
   [[ -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"
+  [[ -f "$version_root/frontend-image.tar" && -f "$version_root/backend-image.tar" && -f "$compose" ]] || fail "dual image package is incomplete"
+  [[ "$(grep -Ec '^  (frontend|backend):$' "$compose")" == 2 ]] || fail "Compose must define frontend and backend only"
+  [[ "$(grep -Fc '../../logs:/app/logs' "$compose")" == 2 ]] || fail "both services must mount root logs"
+  ! grep -Eqi 'blue|green|nginx-upstream|PROJECT_HTTP_PORT' "$compose" || fail "blue-green or host Nginx configuration is forbidden"
+  [[ ! -e "$version_root/database" ]] || fail "release package must not contain database migration files"
+  reject_version_secrets "$version_root"; verify_manifest "$version_root"
 }
 
-release_build_lock() {
-  [[ -n "${BUILD_LOCK:-}" && -d "$BUILD_LOCK" ]] && rmdir "$BUILD_LOCK"
-}
+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=
+  local project_root="$SCRIPT_DIR" agents_file="$SCRIPT_DIR/AGENTS.md" today version raw_time build_time frontend_image backend_image
+  local frontend_dockerfile backend_dockerfile dockerignore_file deploy_config_dir compose_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
-
+  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
+  compose_source="$(resolve_project_path "$project_root" "${COMPOSE_SOURCE:-${deploy_config_dir#"$project_root"/}/docker-compose.yml}")"
+  for command in node pnpm docker install find sort cmp awk sed grep; 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"
+  [[ -f "$frontend_dockerfile" && -f "$backend_dockerfile" && -f "$compose_source" ]] || fail "Dockerfiles and deployment Compose 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"
-  frontend_image="${PROJECT_NAME}_frontend:$version"
-  backend_image="${PROJECT_NAME}_backend:$version"
-
+  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 build --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "RELEASE_VERSION=$version" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
+  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"
+  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"; 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}"
+  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.yml"; cmp -s "$compose_source" "$version_root/docker/docker-compose.yml" || fail "generated Compose 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
+  if [[ -e "$project_root/deploy" ]]; then old_deploy="$project_root/.deploy.previous.$$"; [[ ! -e "$old_deploy" ]] || fail "temporary deploy replacement path already exists"; mv "$project_root/deploy" "$old_deploy"; fi
+  if ! mv "$output_root" "$project_root/deploy"; then [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"; fail "failed to publish deploy directory"; fi
+  if ! mv "$agents_prepared" "$agents_file"; then rm -rf -- "$project_root/deploy"; [[ -n "$old_deploy" ]] && mv "$old_deploy" "$project_root/deploy"; fail "failed to write AGENTS.md release record"; fi
   [[ -n "$old_deploy" ]] && rm -rf -- "$old_deploy" && old_deploy=
-  rm -rf -- "$staging_parent"; staging_parent=
-  release_build_lock; BUILD_LOCK=
-  trap - EXIT
+  rm -rf -- "$staging_parent"; 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"
+  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
+  DEPLOY_ROOT="$SCRIPT_DIR"; load_dotenv "$DEPLOY_ROOT/.env"; validate_configuration; read_release_pointer
+  for command in docker curl tar find sort awk sed grep; do require_command "$command"; done
+  select_checksum_tool; mkdir -p "$DEPLOY_ROOT/logs"
 }
 
-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"
+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 version=%s operation=%s result=%s\n' "$timestamp" "${RELEASE_VERSION:-unknown}" "$OPERATION" "$result" >> "$DEPLOY_ROOT/logs/deploy.log"
 }
 
-read_active() {
-  ACTIVE_COLOR=; ACTIVE_VERSION=
-  if read_state_file "$ACTIVE_STATE"; then ACTIVE_COLOR="$STATE_COLOR"; ACTIVE_VERSION="$STATE_VERSION"; fi
+validate_uploaded_package() {
+  local root="$DEPLOY_ROOT/$RELEASE_VERSION"
+  [[ -f "$root/frontend-image.tar" && -f "$root/backend-image.tar" && -f "$root/docker/docker-compose.yml" ]] || fail "uploaded dual image package is incomplete"
+  [[ ! -e "$root/database" ]] || fail "release package must not contain database migration files"
+  reject_version_secrets "$root"; verify_manifest "$root"
+  tar -tf "$root/frontend-image.tar" >/dev/null || fail "invalid frontend image archive"
+  tar -tf "$root/backend-image.tar" >/dev/null || fail "invalid backend image archive"
 }
 
-read_previous() {
-  PREVIOUS_COLOR=; PREVIOUS_VERSION=
-  if read_state_file "$PREVIOUS_STATE"; then PREVIOUS_COLOR="$STATE_COLOR"; PREVIOUS_VERSION="$STATE_VERSION"; fi
+archive_has_tag() {
+  local archive="$1" tag="$2" manifest compact count
+  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 one expected tag: $tag"
 }
 
-write_state_candidate() {
-  local file="$1" color="$2" version="$3"
-  printf 'ACTIVE_COLOR=%s\nACTIVE_VERSION=%s\n' "$color" "$version" > "$file"
+image_names() { FRONTEND_IMAGE="${PROJECT_NAME}_frontend:$RELEASE_VERSION"; BACKEND_IMAGE="${PROJECT_NAME}_backend:$RELEASE_VERSION"; export FRONTEND_IMAGE BACKEND_IMAGE RELEASE_VERSION; }
+
+load_frontend_image() {
+  local archive="$DEPLOY_ROOT/$RELEASE_VERSION/frontend-image.tar"
+  archive_has_tag "$archive" "$FRONTEND_IMAGE"; docker load -i "$archive" >/dev/null
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$FRONTEND_IMAGE")" == "$RELEASE_VERSION" ]] || fail "frontend loaded image version mismatch"
 }
 
-compose_file_for() {
-  local version="$1"
-  assert_version "$version"
-  printf '%s/%s/docker/docker-compose.blue-green.yml\n' "$DEPLOY_ROOT" "$version"
+load_backend_image() {
+  local archive="$DEPLOY_ROOT/$RELEASE_VERSION/backend-image.tar"
+  archive_has_tag "$archive" "$BACKEND_IMAGE"; docker load -i "$archive" >/dev/null
+  [[ "$(docker image inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' "$BACKEND_IMAGE")" == "$RELEASE_VERSION" ]] || fail "backend loaded image version mismatch"
 }
 
-image_names_for() {
-  local version="$1"
-  assert_version "$version"
-  FRONTEND_IMAGE="${FRONTEND_IMAGE_REPOSITORY}:$version"
-  BACKEND_IMAGE="${BACKEND_IMAGE_REPOSITORY}:$version"
+compose() {
+  FRONTEND_IMAGE="$FRONTEND_IMAGE" BACKEND_IMAGE="$BACKEND_IMAGE" RELEASE_VERSION="$RELEASE_VERSION" docker compose --env-file "$DEPLOY_ROOT/.env" --project-name "$PROJECT_NAME" -f "$DEPLOY_ROOT/$RELEASE_VERSION/docker/docker-compose.yml" "$@"
 }
 
-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"
+verify_service() {
+  local service="$1" port health version_url actual
+  if [[ "$service" == frontend ]]; then port="$FRONTEND_PORT"; else port="$BACKEND_PORT"; fi
+  health="$(endpoint_url "$DOCKER_BIND_IP" "$port" /health)"; version_url="$(endpoint_url "$DOCKER_BIND_IP" "$port" /version)"
+  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$health" >/dev/null
+  actual="$(curl --fail --silent --show-error "$version_url")"
+  [[ "$actual" == "$RELEASE_VERSION" ]] || fail "$service version mismatch: expected $RELEASE_VERSION, got $actual"
 }
 
-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"
-  }
-  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
+run_or_replace() {
+  local target="$1"
+  validate_uploaded_package; image_names
+  case "$target" in
+    frontend) load_frontend_image; compose up -d --force-recreate --no-deps frontend; verify_service frontend ;;
+    backend) load_backend_image; compose up -d --force-recreate --no-deps backend; verify_service backend ;;
+    both) load_frontend_image; load_backend_image; compose up -d --force-recreate frontend backend; verify_service frontend; verify_service backend ;;
+    *) fail "invalid deployment target: $target" ;;
+  esac
+}
 
-  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
+stop_services() { image_names; compose stop frontend backend; }
 
-  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"
-  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" ]] || 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
+server_menu() {
+  local choice status
+  initialize_server_context
+  printf '%s\n' '1. 运行或替换前端' '2. 运行或替换后端' '3. 运行或替换前后端' '4. 停止'
+  IFS= read -r choice || fail "failed to read deployment menu selection"
+  case "$choice" in
+    1) OPERATION=run-or-replace-frontend ;;
+    2) OPERATION=run-or-replace-backend ;;
+    3) OPERATION=run-or-replace-both ;;
+    4) OPERATION=stop-both ;;
+    *) OPERATION=invalid-selection; record_operation failure; fail "invalid deployment menu selection: $choice" ;;
+  esac
+  trap 'status=$?; if [[ $status -eq 0 ]]; then record_operation success; else record_operation failure; fi' EXIT
+  case "$choice" in
+    1) run_or_replace frontend ;;
+    2) run_or_replace backend ;;
+    3) run_or_replace both ;;
+    4) stop_services ;;
+  esac
 }
 
-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
-}
-
-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_menu
+elif [[ "$#" -eq 1 && "$1" == build ]]; then build_release
+else usage
+fi