feat: v2.5.0 T3 — Vercel deployment (entry + vercel.json + workflow + docs) (#328)

* feat: add Vercel deployment target (Node runtime + Turso)

Adds first-class Vercel support: server/entry-vercel.ts using hono/vercel
handler, deploy/vercel/vercel.json with nodejs22.x function config and SPA
rewrites, build:vercel npm script producing api/entry-vercel.js + dist/,
deploy-vercel GitHub Actions workflow (8-step: secrets check, tag resolve,
checkout, install, migrate, build, link, deploy), and docs/deploy/vercel.md
documenting secrets, quick-start, local dev, and pricing notes.

Edge runtime is explicitly not used — @aws-sdk/client-s3 requires Node APIs.

Agent-Profile: https://agent-kanban.dev/agents/a6bb038c4226a87f

* fix: auto-generate BETTER_AUTH_SECRET on first Vercel deploy

Remove BETTER_AUTH_SECRET from the required secrets check. Add a
dedicated step that detects whether the secret already exists in the
Vercel project env via `vercel env ls production`, then either upserts
the user-supplied GitHub secret, auto-generates one with openssl on
first deploy, or skips if already present. Auto-generation case appends
a backup warning to GITHUB_STEP_SUMMARY. Docs move BETTER_AUTH_SECRET
to Optional Secrets with a note about the auto-gen behaviour.

Matches the existing CF Workers deploy.yml pattern (step 8 contract).

Agent-Profile: https://agent-kanban.dev/agents/a6bb038c4226a87f

---------

Co-authored-by: Bob <aibob@mails.agent-kanban.dev>

.github/workflows/deploy-vercel.yml

@@ -0,0 +1,133 @@
+name: Deploy to Vercel
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release tag to deploy (e.g. v2.5.0). Leave empty for latest.'
+        required: false
+
+# Prevent overlapping deployments.
+concurrency:
+  group: deploy-vercel
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    # Only run on forks — upstream repo uses Cloudflare Workers Builds.
+    if: github.repository != 'saltbo/zpan'
+    steps:
+      - name: Check required secrets
+        env:
+          HAS_TOKEN: ${{ secrets.VERCEL_TOKEN != '' }}
+          HAS_ORG: ${{ secrets.VERCEL_ORG_ID != '' }}
+          HAS_PROJECT: ${{ secrets.VERCEL_PROJECT_ID != '' }}
+          HAS_TURSO_URL: ${{ secrets.TURSO_DATABASE_URL != '' }}
+        run: |
+          missing=()
+          [ "$HAS_TOKEN" != "true" ] && missing+=(VERCEL_TOKEN)
+          [ "$HAS_ORG" != "true" ] && missing+=(VERCEL_ORG_ID)
+          [ "$HAS_PROJECT" != "true" ] && missing+=(VERCEL_PROJECT_ID)
+          [ "$HAS_TURSO_URL" != "true" ] && missing+=(TURSO_DATABASE_URL)
+          if [ ${#missing[@]} -gt 0 ]; then
+            echo "::error::Missing required secrets: ${missing[*]}. Go to Settings → Secrets and variables → Actions."
+            exit 1
+          fi
+
+      - name: Resolve release tag
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          if [ -n "$INPUT_VERSION" ]; then
+            TAG="$INPUT_VERSION"
+          else
+            TAG=$(gh api repos/saltbo/zpan/releases/latest --jq '.tag_name')
+          fi
+          if [ -z "$TAG" ]; then
+            echo "::error::No release found in saltbo/zpan"
+            exit 1
+          fi
+          echo "version=$TAG" >> "$GITHUB_OUTPUT"
+          echo "### 🚀 Deploying $TAG to Vercel" >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/checkout@v6
+        with:
+          repository: saltbo/zpan
+          ref: ${{ steps.release.outputs.version }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run migrations (Turso)
+        env:
+          TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
+          TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
+        run: npm run db:migrate
+
+      - name: Build
+        run: npm run build:vercel
+
+      - name: Link or create Vercel project
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+        run: |
+          cp deploy/vercel/vercel.json vercel.json
+          npx vercel link --yes \
+            --token "$VERCEL_TOKEN" \
+            --scope "$VERCEL_ORG_ID"
+
+      - name: Ensure BETTER_AUTH_SECRET (first deploy only)
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          USER_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
+        run: |
+          EXISTS=$(npx vercel env ls production --token "$VERCEL_TOKEN" 2>/dev/null | grep -c "^BETTER_AUTH_SECRET" || true)
+          if [ -n "$USER_SECRET" ]; then
+            # User supplied their own secret — persist it (upsert).
+            echo "$USER_SECRET" | npx vercel env add BETTER_AUTH_SECRET production --token "$VERCEL_TOKEN" --force
+            echo "Set BETTER_AUTH_SECRET from GitHub secret."
+          elif [ "$EXISTS" -eq 0 ]; then
+            # First deploy and no user secret — auto-generate and persist.
+            SECRET=$(openssl rand -base64 32)
+            echo "$SECRET" | npx vercel env add BETTER_AUTH_SECRET production --token "$VERCEL_TOKEN"
+            echo "auto_generated=true" >> "$GITHUB_OUTPUT"
+            echo "Auto-generated BETTER_AUTH_SECRET and stored in Vercel project env."
+          else
+            echo "BETTER_AUTH_SECRET already set in Vercel project env, skipping."
+          fi
+        id: auth_secret
+
+      - name: Deploy to Vercel
+        id: deploy
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+          TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
+          TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
+          BETTER_AUTH_URL: ${{ secrets.BETTER_AUTH_URL }}
+          TRUSTED_ORIGINS: ${{ secrets.TRUSTED_ORIGINS }}
+        run: |
+          DEPLOY_URL=$(npx vercel deploy --prod --token "$VERCEL_TOKEN" \
+            --env TURSO_DATABASE_URL="$TURSO_DATABASE_URL" \
+            --env TURSO_AUTH_TOKEN="$TURSO_AUTH_TOKEN" \
+            --env BETTER_AUTH_URL="$BETTER_AUTH_URL" \
+            --env TRUSTED_ORIGINS="$TRUSTED_ORIGINS")
+          echo "url=$DEPLOY_URL" >> "$GITHUB_OUTPUT"
+          echo "**Deployed to:** $DEPLOY_URL" >> "$GITHUB_STEP_SUMMARY"
+          if [ "${{ steps.auth_secret.outputs.auto_generated }}" = "true" ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "> ⚠️ **BETTER_AUTH_SECRET was auto-generated** and stored in your Vercel project env. Back it up from the Vercel dashboard before rotating." >> "$GITHUB_STEP_SUMMARY"
+          fi