@wdyy/skills 0.1.4 → 0.1.6

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

@@ -1,29 +1,462 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-: "${PROJECT_NAME:?PROJECT_NAME is required}"
-: "${DATABASE_URL:?DATABASE_URL is required}"
-
-DEPLOY_ROOT="${DEPLOY_ROOT:-/srv/$PROJECT_NAME}"
-COMPOSE_FILE="${COMPOSE_FILE:-$DEPLOY_ROOT/deploy/docker/docker-compose.blue-green.yml}"
-UPSTREAM_FILE="${UPSTREAM_FILE:-$DEPLOY_ROOT/deploy/nginx/backend-active.conf}"
-MIGRATION_RUNNER="${MIGRATION_RUNNER:-$DEPLOY_ROOT/scripts/apply-migrations.sh}"
-BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
-BLUE_PORT="${BLUE_PORT:-3001}"
-GREEN_PORT="${GREEN_PORT:-3002}"
-STATE_DIR="$DEPLOY_ROOT/state"
-ACTIVE_STATE="$STATE_DIR/active.env"
-PREVIOUS_STATE="$STATE_DIR/previous.env"
-INCOMING_DIR="$DEPLOY_ROOT/incoming"
-RELEASES_DIR="$DEPLOY_ROOT/releases"
-
-mkdir -p "$STATE_DIR" "$RELEASES_DIR"
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
+SCRIPT_PATH="$SCRIPT_DIR/$(basename -- "${BASH_SOURCE[0]}")"
+
+fail() {
+  echo "$*" >&2
+  exit 1
+}
+
+usage() {
+  echo "usage: ./deploy.sh build|start|stop|restart|status|rollback <version>" >&2
+  exit 2
+}
 
 assert_version() {
-  [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || {
-    echo "version must match YYYYMMDD-NNN" >&2
-    exit 2
+  [[ "${1:-}" =~ ^[0-9]{8}-[0-9]{3}$ ]] || fail "version must match YYYYMMDD-NNN"
+}
+
+assert_port() {
+  local name="$1" value="$2"
+  [[ "$value" =~ ^[0-9]+$ ]] || fail "$name must be a numeric port"
+  (( value >= 1 && value <= 65535 )) || fail "$name must be between 1 and 65535"
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
+load_env_if_present() {
+  local file="$1"
+  if [[ -f "$file" ]]; then
+    set -a
+    # shellcheck disable=SC1090
+    source "$file"
+    set +a
+  fi
+}
+
+load_required_env() {
+  local file="$1"
+  [[ -r "$file" ]] || fail "required production environment file is missing: $file"
+  set -a
+  # shellcheck disable=SC1090
+  source "$file"
+  set +a
+}
+
+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 validCalendarDate(dateText) {
+  const year = Number(dateText.slice(0, 4));
+  const month = Number(dateText.slice(4, 6));
+  const day = Number(dateText.slice(6, 8));
+  const value = new Date(Date.UTC(year, month - 1, day));
+  return value.getUTCFullYear() === year
+    && value.getUTCMonth() === month - 1
+    && value.getUTCDate() === day;
+}
+
+function inspectLedger(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  const headings = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index] === heading) headings.push(index);
+  }
+  if (headings.length > 1) fail('AGENTS.md contains multiple release record sections');
+  if (headings.length === 0) 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[section.length - 1] === '') section.pop();
+  if (section[0] !== header || section[1] !== separator) {
+    fail('AGENTS.md release record table must contain only version and build time columns');
+  }
+
+  const versions = [];
+  const unique = new Set();
+  for (const row of section.slice(2)) {
+    const match = row.match(rowPattern);
+    if (!match) fail(`invalid AGENTS.md release record row: ${row}`);
+    const versionMatch = match[1].match(versionPattern);
+    if (!versionMatch || !validCalendarDate(match[1].slice(0, 8))) {
+      fail(`invalid release version: ${match[1]}`);
+    }
+    const sequence = Number(versionMatch[4]);
+    if (sequence < 1 || sequence > 999) fail(`invalid release sequence: ${match[1]}`);
+    if (unique.has(match[1])) fail(`duplicate release version: ${match[1]}`);
+    unique.add(match[1]);
+    versions.push(match[1]);
+  }
+  return { lines, headingIndex, endIndex, versions };
+}
+
+function nextVersion(ledger, currentDate) {
+  if (!/^\d{8}$/.test(currentDate) || !validCalendarDate(currentDate)) {
+    fail(`invalid current release date: ${currentDate}`);
+  }
+  let maximum = 0;
+  for (const version of ledger.versions) {
+    if (version.startsWith(`${currentDate}-`)) {
+      maximum = Math.max(maximum, Number(version.slice(-3)));
+    }
+  }
+  if (maximum >= 999) fail(`release sequence exhausted for ${currentDate}`);
+  return `${currentDate}-${String(maximum + 1).padStart(3, '0')}`;
+}
+
+const original = fs.readFileSync(agentsPath, 'utf8');
+const ledger = inspectLedger(original);
+
+if (mode === 'next') {
+  process.stdout.write(`${nextVersion(ledger, value)}\n`);
+} else if (mode === 'prepare') {
+  const versionMatch = value.match(versionPattern);
+  if (!versionMatch || !validCalendarDate(value.slice(0, 8))) fail(`invalid release version: ${value}`);
+  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{2}:\d{2}$/.test(timestamp)) {
+    fail(`invalid release build time: ${timestamp}`);
+  }
+  const expected = nextVersion(ledger, value.slice(0, 8));
+  if (value !== expected) fail(`release ledger changed: expected ${expected}, got ${value}`);
+  const row = `| ${value} | ${timestamp} |`;
+  let updated;
+  if (ledger.headingIndex === -1) {
+    const separatorText = original.length === 0 ? '' : original.endsWith('\n') ? '\n' : '\n\n';
+    updated = `${original}${separatorText}${heading}\n\n${header}\n${separator}\n${row}\n`;
+  } 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');
   }
+  const modeBits = fs.statSync(agentsPath).mode;
+  fs.writeFileSync(outputPath, updated, { mode: modeBits });
+} else {
+  fail(`unknown release ledger mode: ${mode}`);
+}
+NODE
+}
+
+create_manifest() {
+  local version_root="$1" file relative checksum
+  (
+    cd "$version_root"
+    : > manifest.sha256
+    find . -type f ! -name manifest.sha256 -print | LC_ALL=C sort |
+      while IFS= read -r file; do
+        relative="${file#./}"
+        checksum="$(checksum_value "$file")"
+        printf '%s  %s\n' "$checksum" "$relative"
+      done > manifest.sha256
+  )
+}
+
+verify_manifest() {
+  local version_root="$1"
+  local manifest="$version_root/manifest.sha256"
+  local actual_paths declared_paths result line checksum relative actual
+  [[ -s "$manifest" ]] || fail "missing or empty manifest.sha256"
+  actual_paths="$(mktemp)"
+  declared_paths="$(mktemp)"
+  result=0
+
+  if (
+    cd "$version_root"
+    find . -type f ! -name manifest.sha256 -print |
+      sed 's|^\./||' |
+      LC_ALL=C sort > "$actual_paths"
+    while IFS= read -r line; do
+      checksum="${line%%  *}"
+      relative="${line#*  }"
+      if [[ ! "$checksum" =~ ^[0-9a-f]{64}$ || "$relative" == "$line" || "$relative" == /* || "$relative" == ../* || "$relative" == *"/../"* ]]; then
+        echo "invalid manifest entry: $line" >&2
+        result=1
+        continue
+      fi
+      printf '%s\n' "$relative" >> "$declared_paths"
+      [[ -f "$relative" ]] || {
+        echo "manifest file is missing: $relative" >&2
+        result=1
+        continue
+      }
+      actual="$(checksum_value "$relative")"
+      if [[ "$actual" != "$checksum" ]]; then
+        echo "checksum mismatch: $relative" >&2
+        result=1
+      fi
+    done < manifest.sha256
+    LC_ALL=C sort -o "$declared_paths" "$declared_paths"
+    if ! cmp -s "$actual_paths" "$declared_paths"; then
+      echo "manifest does not cover the complete release package" >&2
+      result=1
+    fi
+    exit "$result"
+  ); then
+    result=0
+  else
+    result=$?
+  fi
+  rm -f -- "$actual_paths" "$declared_paths"
+  [[ "$result" -eq 0 ]] || fail "release manifest validation failed"
+}
+
+reject_secret_files() {
+  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 "production secret file must not be packaged: ${file#"$root"/}"
+        ;;
+    esac
+  done < <(find "$root" -type f -print)
+}
+
+validate_dockerignore() {
+  local file="$1" pattern
+  [[ -f "$file" ]] || fail "required Docker ignore file is missing: $file"
+  for pattern in \
+    '.env' \
+    '.env.*' \
+    '*.pem' \
+    '*.key' \
+    'id_rsa' \
+    'id_ed25519' \
+    'credentials' \
+    'credentials.*' \
+    'deploy/' \
+    'logs/' \
+    '.git/' \
+    'node_modules/' \
+    'venv/' \
+    '.pnpm-store/'; do
+    grep -Fxq "$pattern" "$file" || fail "Docker ignore file is missing required pattern: $pattern"
+  done
+}
+
+validate_local_package() {
+  local output_root="$1" version="$2"
+  local version_root="$output_root/$version"
+  [[ -x "$output_root/deploy.sh" ]] || fail "generated deploy.sh is missing or not executable"
+  [[ "$(cat "$output_root/release.env")" == "RELEASE_VERSION=$version" ]] ||
+    fail "release.env does not point to the generated version"
+  [[ -f "$version_root/frontend.tar.gz" ]] || fail "missing frontend.tar.gz"
+  [[ -f "$version_root/backend-image.tar" ]] || fail "missing backend-image.tar"
+  [[ -d "$version_root/database/migrations" ]] || fail "missing database/migrations"
+  [[ -x "$version_root/scripts/apply-migrations.sh" ]] || fail "missing executable migration runner"
+  [[ -f "$version_root/docker/docker-compose.blue-green.yml" ]] || fail "missing blue-green compose file"
+  [[ -f "$version_root/nginx/site.conf" ]] || fail "missing Nginx site configuration"
+  grep -Fq '../../logs:/app/logs' "$version_root/docker/docker-compose.blue-green.yml" ||
+    fail "compose does not mount deployment-root logs"
+  grep -Fq '__DEPLOY_ROOT__' "$version_root/nginx/site.conf" ||
+    fail "Nginx configuration does not contain the deployment-root placeholder"
+  grep -Fq '__BACKEND_PROXY_URL__' "$version_root/nginx/site.conf" ||
+    fail "Nginx configuration does not contain the backend proxy URL placeholder"
+  reject_secret_files "$output_root"
+  verify_manifest "$version_root"
+}
+
+build_release() {
+  local project_root="$SCRIPT_DIR" agents_file="$SCRIPT_DIR/AGENTS.md"
+  local today version build_time raw_time image staging_parent output_root version_root agents_prepared
+  local frontend_dist backend_dockerfile migrations_source migration_runner_source
+  local deploy_config_dir compose_source nginx_source dockerignore_file
+
+  [[ -r "$agents_file" && -w "$agents_file" ]] || fail "project AGENTS.md must exist and be readable and writable"
+  load_env_if_present "$project_root/.env"
+  : "${PROJECT_NAME:?PROJECT_NAME is required in the environment or project .env}"
+  : "${BACKEND_CONTAINER_PORT:?BACKEND_CONTAINER_PORT is required in the environment or project .env}"
+  assert_port BACKEND_CONTAINER_PORT "$BACKEND_CONTAINER_PORT"
+
+  frontend_dist="$(resolve_project_path "$project_root" "${FRONTEND_DIST_DIR:-src/frontend/dist}")"
+  backend_dockerfile="$(resolve_project_path "$project_root" "${BACKEND_DOCKERFILE:-src/backend/Dockerfile}")"
+  dockerignore_file="$(resolve_project_path "$project_root" "${DOCKERIGNORE_FILE:-.dockerignore}")"
+  migrations_source="$(resolve_project_path "$project_root" "${MIGRATIONS_SOURCE:-database/migrations}")"
+  migration_runner_source="$(resolve_project_path "$project_root" "${MIGRATION_RUNNER_SOURCE:-scripts/apply-migrations.sh}")"
+  deploy_config_dir="$(resolve_project_path "$project_root" "${DEPLOY_CONFIG_DIR:-scripts/deployment}")"
+  compose_source="$(resolve_project_path "$project_root" "${COMPOSE_SOURCE:-${deploy_config_dir#$project_root/}/docker-compose.blue-green.yml}")"
+  nginx_source="$(resolve_project_path "$project_root" "${NGINX_SOURCE:-${deploy_config_dir#$project_root/}/nginx-site.conf}")"
+  BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
+
+  for command in node pnpm docker tar install find sort cmp awk sed grep; do
+    require_command "$command"
+  done
+  select_checksum_tool
+  [[ -f "$backend_dockerfile" ]] || fail "backend Dockerfile not found: $backend_dockerfile"
+  validate_dockerignore "$dockerignore_file"
+  [[ -d "$migrations_source" ]] || fail "migration directory not found: $migrations_source"
+  [[ -x "$migration_runner_source" ]] || fail "migration runner is missing or not executable: $migration_runner_source"
+  [[ -f "$compose_source" ]] || fail "compose source not found: $compose_source"
+  [[ -f "$nginx_source" ]] || fail "Nginx source not found: $nginx_source"
+
+  today="$(date +%Y%m%d)"
+  version="$(release_ledger next "$agents_file" "$today")"
+  assert_version "$version"
+  image="$BACKEND_IMAGE_PREFIX:$version"
+
+  echo "release gate: pnpm test"
+  pnpm test
+  echo "release gate: pnpm lint"
+  pnpm lint
+  echo "release gate: pnpm typecheck"
+  pnpm typecheck
+  echo "release gate: pnpm build"
+  RELEASE_VERSION="$version" VITE_RELEASE_BASE="/releases/$version/" pnpm build
+
+  [[ -f "$frontend_dist/index.html" ]] || fail "frontend build missing index.html: $frontend_dist"
+  grep -Fq "/releases/$version/" "$frontend_dist/index.html" ||
+    fail "frontend assets are not built with /releases/$version/"
+
+  echo "release gate: docker build"
+  docker build \
+    --build-arg "RELEASE_VERSION=$version" \
+    --build-arg "BACKEND_CONTAINER_PORT=$BACKEND_CONTAINER_PORT" \
+    --tag "$image" \
+    --file "$backend_dockerfile" \
+    "$project_root"
+  docker image inspect "$image" >/dev/null
+
+  staging_parent="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"
+  output_root="$staging_parent/deploy"
+  version_root="$output_root/$version"
+  agents_prepared="$project_root/.AGENTS.md.release.$$.tmp"
+  trap 'rm -rf -- "${staging_parent:-}"; rm -f -- "${agents_prepared:-}"' EXIT
+
+  mkdir -p \
+    "$version_root/database" \
+    "$version_root/scripts" \
+    "$version_root/docker" \
+    "$version_root/nginx"
+  install -m 0755 "$SCRIPT_PATH" "$output_root/deploy.sh"
+  printf 'RELEASE_VERSION=%s\n' "$version" > "$output_root/release.env"
+  tar -czf "$version_root/frontend.tar.gz" -C "$frontend_dist" .
+  docker save -o "$version_root/backend-image.tar" "$image"
+  cp -R "$migrations_source" "$version_root/database/migrations"
+  install -m 0755 "$migration_runner_source" "$version_root/scripts/apply-migrations.sh"
+  install -m 0644 "$compose_source" "$version_root/docker/docker-compose.blue-green.yml"
+  install -m 0644 "$nginx_source" "$version_root/nginx/site.conf"
+  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"
+
+  [[ "$project_root/deploy" == "$SCRIPT_DIR/deploy" ]] || fail "refusing to replace an unexpected deploy directory"
+  rm -rf -- "$project_root/deploy"
+  mv "$output_root" "$project_root/deploy"
+  if ! mv "$agents_prepared" "$agents_file"; then
+    rm -rf -- "$project_root/deploy"
+    fail "failed to write AGENTS.md release record"
+  fi
+
+  trap - EXIT
+  rm -rf -- "$staging_parent"
+  echo "release package created: deploy/$version"
+}
+
+read_release_pointer() {
+  local file="$DEPLOY_ROOT/release.env" line
+  [[ -f "$file" ]] || fail "missing release.env"
+  [[ "$(wc -l < "$file" | tr -d ' ')" == 1 ]] || fail "release.env must contain exactly one line"
+  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() {
+  DEPLOY_ROOT="$SCRIPT_DIR"
+  load_required_env "$DEPLOY_ROOT/.env.production"
+  : "${PROJECT_NAME:?PROJECT_NAME is required in .env.production}"
+  : "${DATABASE_URL:?DATABASE_URL is required in .env.production}"
+  : "${BACKEND_BIND_IP:?BACKEND_BIND_IP is required in .env.production}"
+  : "${BACKEND_LISTEN_HOST:?BACKEND_LISTEN_HOST is required in .env.production}"
+  : "${BACKEND_CONTAINER_PORT:?BACKEND_CONTAINER_PORT is required in .env.production}"
+  : "${BACKEND_CONTAINER_HEALTH_URL:?BACKEND_CONTAINER_HEALTH_URL is required in .env.production}"
+  : "${BLUE_PORT:?BLUE_PORT is required in .env.production}"
+  : "${GREEN_PORT:?GREEN_PORT is required in .env.production}"
+  : "${BLUE_HEALTH_URL:?BLUE_HEALTH_URL is required in .env.production}"
+  : "${GREEN_HEALTH_URL:?GREEN_HEALTH_URL is required in .env.production}"
+  : "${BLUE_VERSION_URL:?BLUE_VERSION_URL is required in .env.production}"
+  : "${GREEN_VERSION_URL:?GREEN_VERSION_URL is required in .env.production}"
+  : "${BLUE_UPSTREAM:?BLUE_UPSTREAM is required in .env.production}"
+  : "${GREEN_UPSTREAM:?GREEN_UPSTREAM is required in .env.production}"
+  : "${BACKEND_PROXY_URL:?BACKEND_PROXY_URL is required in .env.production}"
+  if [[ ! "$BACKEND_PROXY_URL" =~ ^https?://([A-Za-z_][A-Za-z0-9_]*)$ ]]; then
+    fail "BACKEND_PROXY_URL must be an http(s) URL containing only a valid Nginx upstream name"
+  fi
+  BACKEND_UPSTREAM_NAME="${BASH_REMATCH[1]}"
+  BACKEND_IMAGE_PREFIX="${BACKEND_IMAGE_PREFIX:-$PROJECT_NAME-backend}"
+  assert_port BACKEND_CONTAINER_PORT "$BACKEND_CONTAINER_PORT"
+  assert_port BLUE_PORT "$BLUE_PORT"
+  assert_port GREEN_PORT "$GREEN_PORT"
+  STATE_DIR="$DEPLOY_ROOT/state"
+  ACTIVE_STATE="$STATE_DIR/active.env"
+  PREVIOUS_STATE="$STATE_DIR/previous.env"
+  RELEASES_DIR="$DEPLOY_ROOT/releases"
+  UPSTREAM_FILE="$DEPLOY_ROOT/nginx/backend-active.conf"
+  NGINX_SITE_FILE="$DEPLOY_ROOT/nginx/site.conf"
+  for command in docker curl nginx psql tar find sort cmp awk sed grep; do
+    require_command "$command"
+  done
+  select_checksum_tool
 }
 
 read_active() {
@@ -32,18 +465,46 @@ read_active() {
   if [[ -f "$ACTIVE_STATE" ]]; then
     # shellcheck disable=SC1090
     source "$ACTIVE_STATE"
+    [[ "$ACTIVE_COLOR" == blue || "$ACTIVE_COLOR" == green ]] || fail "invalid active color state"
+    assert_version "$ACTIVE_VERSION"
   fi
 }
 
-port_for() {
-  [[ "$1" == blue ]] && printf '%s' "$BLUE_PORT" || printf '%s' "$GREEN_PORT"
+upstream_for() {
+  [[ "$1" == blue ]] && printf '%s' "$BLUE_UPSTREAM" || printf '%s' "$GREEN_UPSTREAM"
+}
+
+compose_file_for() {
+  local version="$1"
+  assert_version "$version"
+  printf '%s/%s/docker/docker-compose.blue-green.yml\n' "$DEPLOY_ROOT" "$version"
+}
+
+render_nginx_site() {
+  local source="$1" escaped_root escaped_proxy_url
+  grep -Fq '__DEPLOY_ROOT__' "$source" || fail "Nginx package is missing __DEPLOY_ROOT__ placeholder"
+  grep -Fq '__BACKEND_PROXY_URL__' "$source" ||
+    fail "Nginx package is missing __BACKEND_PROXY_URL__ placeholder"
+  escaped_root="${DEPLOY_ROOT//\\/\\\\}"
+  escaped_root="${escaped_root//&/\\&}"
+  escaped_root="${escaped_root//|/\\|}"
+  escaped_proxy_url="${BACKEND_PROXY_URL//\\/\\\\}"
+  escaped_proxy_url="${escaped_proxy_url//&/\\&}"
+  escaped_proxy_url="${escaped_proxy_url//|/\\|}"
+  mkdir -p "$DEPLOY_ROOT/nginx"
+  sed \
+    -e "s|__DEPLOY_ROOT__|$escaped_root|g" \
+    -e "s|__BACKEND_PROXY_URL__|$escaped_proxy_url|g" \
+    "$source" > "$NGINX_SITE_FILE.new"
+  mv "$NGINX_SITE_FILE.new" "$NGINX_SITE_FILE"
 }
 
 switch_traffic() {
-  local color="$1" version="$2" port backup
-  port="$(port_for "$color")"
+  local color="$1" version="$2" upstream backup
+  upstream="$(upstream_for "$color")"
   backup="$UPSTREAM_FILE.previous"
-  printf 'upstream backend_active {\n  server 127.0.0.1:%s;\n  keepalive 32;\n}\n' "$port" > "$UPSTREAM_FILE.new"
+  printf 'upstream %s {\n  server %s;\n  keepalive 32;\n}\n' \
+    "$BACKEND_UPSTREAM_NAME" "$upstream" > "$UPSTREAM_FILE.new"
   [[ -f "$UPSTREAM_FILE" ]] && cp "$UPSTREAM_FILE" "$backup"
   mv -f "$UPSTREAM_FILE.new" "$UPSTREAM_FILE"
   if ! nginx -t || ! nginx -s reload; then
@@ -61,82 +522,124 @@ switch_traffic() {
 }
 
 verify_backend() {
-  local color="$1" version="$2" port health_url version_url actual
-  port="$(port_for "$color")"
-  health_url="http://127.0.0.1:$port/health"
-  version_url="http://127.0.0.1:$port/version"
+  local color="$1" version="$2" health_url version_url actual
+  if [[ "$color" == blue ]]; then
+    health_url="$BLUE_HEALTH_URL"
+    version_url="$BLUE_VERSION_URL"
+  else
+    health_url="$GREEN_HEALTH_URL"
+    version_url="$GREEN_VERSION_URL"
+  fi
   HEALTH_URL="$health_url"
   VERSION_URL="$version_url"
-  curl --fail --silent --show-error --retry 12 --retry-delay 2 "$HEALTH_URL"
+  curl --fail --silent --show-error --retry 12 --retry-delay 2 --retry-connrefused "$HEALTH_URL"
   actual="$(curl --fail --silent --show-error "$VERSION_URL")"
-  [[ "$actual" == "$version" ]] || {
-    echo "backend version mismatch: expected $version, got $actual" >&2
-    exit 1
-  }
+  [[ "$actual" == "$version" ]] || fail "backend version mismatch: expected $version, got $actual"
 }
 
-start_version() {
-  local version="$1" source_dir release_dir target_color image
-  assert_version "$version"
-  source_dir="$INCOMING_DIR/$version"
-  release_dir="$RELEASES_DIR/$version"
-  [[ -f "$source_dir/frontend.tar.gz" ]] || { echo "missing frontend.tar.gz" >&2; exit 1; }
-  [[ -f "$source_dir/backend-image.tar" ]] || { echo "missing backend-image.tar" >&2; exit 1; }
-  [[ -d "$source_dir/database/migrations" ]] || { echo "missing database/migrations" >&2; exit 1; }
+validate_uploaded_package() {
+  local package_root="$1"
+  select_checksum_tool
+  [[ -f "$package_root/frontend.tar.gz" ]] || fail "missing frontend.tar.gz"
+  [[ -f "$package_root/backend-image.tar" ]] || fail "missing backend-image.tar"
+  [[ -d "$package_root/database/migrations" ]] || fail "missing database/migrations"
+  [[ -x "$package_root/scripts/apply-migrations.sh" ]] || fail "missing executable migration runner"
+  [[ -f "$package_root/docker/docker-compose.blue-green.yml" ]] || fail "missing blue-green compose file"
+  [[ -f "$package_root/nginx/site.conf" ]] || fail "missing Nginx site configuration"
+  reject_secret_files "$package_root"
+  verify_manifest "$package_root"
+  if tar -tzf "$package_root/frontend.tar.gz" | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
+    fail "frontend archive contains an unsafe path"
+  fi
+}
 
-  rm -rf "$release_dir"
+start_release() {
+  local package_root release_dir target_color image compose_file
+  initialize_server_context
+  read_release_pointer
+  package_root="$DEPLOY_ROOT/$RELEASE_VERSION"
+  validate_uploaded_package "$package_root"
+  mkdir -p "$STATE_DIR" "$RELEASES_DIR" "$DEPLOY_ROOT/logs" "$DEPLOY_ROOT/nginx"
+  render_nginx_site "$package_root/nginx/site.conf"
+
+  release_dir="$RELEASES_DIR/$RELEASE_VERSION"
+  rm -rf -- "$release_dir"
   mkdir -p "$release_dir"
-  if tar -tzf "$source_dir/frontend.tar.gz" | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
-    echo "frontend archive contains an unsafe path" >&2
-    exit 1
-  fi
-  tar -xzf "$source_dir/frontend.tar.gz" -C "$release_dir"
-  [[ -f "$release_dir/index.html" ]] || { echo "frontend release missing index.html" >&2; exit 1; }
-  grep -q "/releases/$version/" "$release_dir/index.html" || {
-    echo "frontend assets are not built with the versioned release URL" >&2
-    exit 1
-  }
-  docker load -i "$source_dir/backend-image.tar"
-  image="$BACKEND_IMAGE_PREFIX:$version"
+  tar -xzf "$package_root/frontend.tar.gz" -C "$release_dir"
+  [[ -f "$release_dir/index.html" ]] || fail "frontend release missing index.html"
+  grep -Fq "/releases/$RELEASE_VERSION/" "$release_dir/index.html" ||
+    fail "frontend assets are not built with the versioned release URL"
+
+  docker load -i "$package_root/backend-image.tar"
+  image="$BACKEND_IMAGE_PREFIX:$RELEASE_VERSION"
   docker image inspect "$image" >/dev/null
-  MIGRATIONS_DIR="$source_dir/database/migrations" "$MIGRATION_RUNNER"
+  MIGRATIONS_DIR="$package_root/database/migrations" \
+    DATABASE_URL="$DATABASE_URL" \
+    "$package_root/scripts/apply-migrations.sh"
 
   read_active
   target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
+  compose_file="$(compose_file_for "$RELEASE_VERSION")"
   if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-blue
+    BACKEND_BLUE_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
+      up -d --force-recreate backend-blue
   else
-    BACKEND_GREEN_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-green
+    BACKEND_GREEN_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
+      up -d --force-recreate backend-green
   fi
-  verify_backend "$target_color" "$version"
+  verify_backend "$target_color" "$RELEASE_VERSION"
   [[ -f "$ACTIVE_STATE" ]] && cp "$ACTIVE_STATE" "$PREVIOUS_STATE"
-  switch_traffic "$target_color" "$version"
-  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$version" > "$ACTIVE_STATE"
+  switch_traffic "$target_color" "$RELEASE_VERSION"
+  printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$RELEASE_VERSION" > "$ACTIVE_STATE"
 }
 
 restart_current() {
+  local target_color image compose_file
   read_active
-  [[ -n "$ACTIVE_VERSION" ]] || { echo "no active version" >&2; exit 1; }
-  local target_color image
+  [[ -n "$ACTIVE_VERSION" ]] || fail "no active version"
   target_color=$([[ "$ACTIVE_COLOR" == blue ]] && echo green || echo blue)
   image="$BACKEND_IMAGE_PREFIX:$ACTIVE_VERSION"
+  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
+  [[ -f "$compose_file" ]] || fail "active version compose file is missing: $compose_file"
   if [[ "$target_color" == blue ]]; then
-    BACKEND_BLUE_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-blue
+    BACKEND_BLUE_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
+      up -d --force-recreate backend-blue
   else
-    BACKEND_GREEN_IMAGE="$image" docker compose -f "$COMPOSE_FILE" up -d --force-recreate backend-green
+    BACKEND_GREEN_IMAGE="$image" docker compose --project-name "$PROJECT_NAME" -f "$compose_file" \
+      up -d --force-recreate backend-green
   fi
   verify_backend "$target_color" "$ACTIVE_VERSION"
   switch_traffic "$target_color" "$ACTIVE_VERSION"
   printf 'ACTIVE_COLOR=%q\nACTIVE_VERSION=%q\n' "$target_color" "$ACTIVE_VERSION" > "$ACTIVE_STATE"
 }
 
+stop_current() {
+  local compose_file
+  read_active
+  [[ -n "$ACTIVE_VERSION" ]] || fail "no active version"
+  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
+  docker compose --project-name "$PROJECT_NAME" -f "$compose_file" down
+}
+
+status_current() {
+  local compose_file
+  read_active
+  printf 'color=%s\nversion=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION"
+  [[ -n "$ACTIVE_VERSION" ]] || return 0
+  compose_file="$(compose_file_for "$ACTIVE_VERSION")"
+  docker compose --project-name "$PROJECT_NAME" -f "$compose_file" ps
+}
+
 rollback_version() {
   local version="$1"
   assert_version "$version"
-  [[ -f "$PREVIOUS_STATE" ]] || { echo "no previous deployment" >&2; exit 1; }
+  [[ -f "$PREVIOUS_STATE" ]] || fail "no previous deployment"
   # shellcheck disable=SC1090
   source "$PREVIOUS_STATE"
-  [[ "$ACTIVE_VERSION" == "$version" ]] || { echo "rollback target is not the retained previous version" >&2; exit 1; }
+  [[ "$ACTIVE_COLOR" == blue || "$ACTIVE_COLOR" == green ]] || fail "invalid previous color state"
+  assert_version "$ACTIVE_VERSION"
+  [[ "$ACTIVE_VERSION" == "$version" ]] || fail "rollback target is not the retained previous version"
+  [[ -d "$RELEASES_DIR/$ACTIVE_VERSION" ]] || fail "previous frontend release is missing"
   verify_backend "$ACTIVE_COLOR" "$ACTIVE_VERSION"
   switch_traffic "$ACTIVE_COLOR" "$ACTIVE_VERSION"
   cp "$ACTIVE_STATE" "$PREVIOUS_STATE.tmp"
@@ -145,27 +648,35 @@ rollback_version() {
 }
 
 case "${1:-}" in
+  build)
+    [[ "$#" -eq 1 ]] || usage
+    build_release
+    ;;
   start)
-    version="$2"
-    start_version "$version"
+    [[ "$#" -eq 1 ]] || usage
+    start_release
     ;;
   stop)
-    docker compose -f "$COMPOSE_FILE" down
+    [[ "$#" -eq 1 ]] || usage
+    initialize_server_context
+    stop_current
     ;;
   restart)
+    [[ "$#" -eq 1 ]] || usage
+    initialize_server_context
     restart_current
     ;;
   status)
-    read_active
-    printf 'color=%s\nversion=%s\n' "$ACTIVE_COLOR" "$ACTIVE_VERSION"
-    docker compose -f "$COMPOSE_FILE" ps
+    [[ "$#" -eq 1 ]] || usage
+    initialize_server_context
+    status_current
     ;;
   rollback)
-    version="$2"
-    rollback_version "$version"
+    [[ "$#" -eq 2 ]] || usage
+    initialize_server_context
+    rollback_version "$2"
     ;;
   *)
-    echo "usage: ./deploy.sh start <version>|stop|restart|status|rollback <version>" >&2
-    exit 2
+    usage
     ;;
 esac