fix(deploy): stage worktree build and short .next cutover

Build install/test/migrate in a detached worktree while the live site keeps serving, then swap .next and node_modules during a brief stop. Drops nuclear rm -rf src and rolls back .next.prev on cutover failure.

Co-authored-by: Cursor <[email protected]>

.gitea/workflows/deploy.yaml

@@ -236,58 +236,65 @@ jobs:
 
           echo "--- Deploying ---"
 
+          LIVE="/var/www/atom-nexst"
+          STAGE=""
+          CUTOVER_STARTED=0
+
           error_handler() {
             echo "!!! DEPLOYMENT FAILED on line $1 !!!" >&2
+            # Roll back the build artifact if cutover already moved .next into place.
+            if [ "${CUTOVER_STARTED}" = "1" ] && [ -d "${LIVE}/.next.prev" ]; then
+              echo "Rolling back .next to previous artifact..." >&2
+              rm -rf "${LIVE}/.next" || true
+              mv "${LIVE}/.next.prev" "${LIVE}/.next" || true
+            fi
+            if [ -n "${STAGE}" ] && [ -d "${STAGE}" ]; then
+              git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
+            fi
             sudo systemctl start atom-nexst.service || true
             exit 1
           }
           trap 'error_handler $LINENO' ERR
 
           docker image prune -f
-          cd /var/www/atom-nexst/
 
           DEPLOY_USER="$(id -un)"
           DEPLOY_GROUP="$(id -gn)"
-          sudo chown -R "${DEPLOY_USER}:${DEPLOY_GROUP}" /var/www/atom-nexst/
-          git config --global --add safe.directory /var/www/atom-nexst
-          git remote set-url origin /docker/gitea/gitea/git/repositories/remco/epicnext-cms.git/
+          sudo chown -R "${DEPLOY_USER}:${DEPLOY_GROUP}" "${LIVE}"
+          git config --global --add safe.directory "${LIVE}"
+          git -C "${LIVE}" remote set-url origin /docker/gitea/gitea/git/repositories/remco/epicnext-cms.git/
 
           echo "Fetching origin/main..."
-          git fetch origin --prune
+          git -C "${LIVE}" fetch origin --prune
 
           echo "Clearing sticky git index bits (if any)..."
-          STICKY_LIST="$(git ls-files -v | awk '/^[a-zS]/ {print substr($0,3)}' || true)"
+          STICKY_LIST="$(git -C "${LIVE}" ls-files -v | awk '/^[a-zS]/ {print substr($0,3)}' || true)"
           if [ -n "${STICKY_LIST}" ]; then
             echo "${STICKY_LIST}" | while IFS= read -r f; do
               [ -n "$f" ] || continue
-              git update-index --no-skip-worktree --no-assume-unchanged -- "$f" 2>/dev/null || true
+              git -C "${LIVE}" update-index --no-skip-worktree --no-assume-unchanged -- "$f" 2>/dev/null || true
             done
           fi
 
-          echo "Hard reset to origin/main..."
-          git reset --hard origin/main
-
-          echo "Nuclear-replacing src/ from HEAD..."
-          rm -rf src
-          git checkout -f HEAD -- src
-          git clean -fd -e .env -e .env.local -e .env.production -e .env*.local
-
-          if ! git diff --exit-code HEAD -- src >/dev/null; then
-            echo "ERROR: src/ still differs from HEAD after nuclear checkout:" >&2
-            git diff --stat HEAD -- src >&2 || true
-            exit 1
-          fi
-          echo "Verified src/ matches HEAD"
-
-          rm -f tsconfig.tsbuildinfo .tsbuildinfo
-          find . -maxdepth 3 -name '*.tsbuildinfo' -delete 2>/dev/null || true
-          rm -rf .output dist .next/types .next/dev
-
-          export APP_VERSION="$(git rev-parse --short HEAD)"
+          export APP_VERSION="$(git -C "${LIVE}" rev-parse --short origin/main)"
           export NEXT_PUBLIC_APP_VERSION="${APP_VERSION}"
           echo "APP_VERSION=${APP_VERSION}"
 
+          STAGE="/var/tmp/atom-nexst-stage-${APP_VERSION}"
+          echo "Preparing stage worktree at ${STAGE} (live site stays up)..."
+          git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
+          git -C "${LIVE}" worktree add --detach "${STAGE}" origin/main
+
+          # Production env stays on the live tree; stage only needs a symlink for build/migrate.
+          ln -sfn "${LIVE}/.env" "${STAGE}/.env"
+
+          cd "${STAGE}"
+          rm -f tsconfig.tsbuildinfo .tsbuildinfo
+          find . -maxdepth 3 -name '*.tsbuildinfo' -delete 2>/dev/null || true
+          rm -rf .output dist .next .next/types .next/dev
+
           pnpm install --frozen-lockfile
+          # Additive migrations while the old build still serves traffic.
           pnpm db:migrate
           pnpm prisma:generate
           pnpm typecheck
@@ -296,11 +303,48 @@ jobs:
           # Do not set SKIP_ENV_VALIDATION here — that flag is for tests/tooling only.
           pnpm build
 
-          sudo chown -R www-data:www-data /var/www/atom-nexst/
+          if [ ! -d "${STAGE}/.next" ]; then
+            echo "ERROR: stage build produced no .next/" >&2
+            exit 1
+          fi
 
-          echo "Hard resetting systemd service..."
+          echo "Cutover: stop service, sync code, swap .next artifact..."
+          CUTOVER_STARTED=1
           sudo systemctl stop atom-nexst.service || true
           pkill -f 'next-server' || true
+
+          cd "${LIVE}"
+          echo "Hard reset live tree to origin/main (no nuclear src wipe)..."
+          git reset --hard origin/main
+          # Keep env, uploads, and deps we are about to replace from stage.
+          git clean -fd \
+            -e .env -e .env.local -e .env.production -e .env*.local \
+            -e storage -e public/cache -e node_modules -e .next -e .next.prev
+
+          if ! git diff --exit-code HEAD -- src >/dev/null; then
+            echo "ERROR: live src/ still differs from HEAD after reset:" >&2
+            git diff --stat HEAD -- src >&2 || true
+            exit 1
+          fi
+          echo "Verified live src/ matches HEAD"
+
+          # Atomic-ish artifact swap: keep previous .next until the new one is in place.
+          rm -rf .next.prev
+          if [ -d .next ]; then
+            mv .next .next.prev
+          fi
+          mv "${STAGE}/.next" .next
+
+          # Use the exact node_modules the stage build resolved against.
+          rm -rf node_modules
+          mv "${STAGE}/node_modules" node_modules
+
+          # Prisma client is gitignored — regenerate into live src/generated.
+          pnpm prisma:generate
+
+          sudo chown -R www-data:www-data "${LIVE}"
+
+          echo "Starting systemd service..."
           sudo systemctl start atom-nexst.service
 
           sleep 2
@@ -329,4 +373,9 @@ jobs:
             exit 1
           fi
 
+          echo "Cleaning stage worktree and previous .next..."
+          rm -rf "${LIVE}/.next.prev"
+          git -C "${LIVE}" worktree remove --force "${STAGE}" 2>/dev/null || rm -rf "${STAGE}" || true
+          STAGE=""
+
           echo "--- Deployed successfully ---"