feat: Migrate extralit-frontend from Vue 2 / Nuxt 2 to Vue 3 / Nuxt 4 + Vercel frontend CI/deploy

.github/actions/download-frontend-artifact/action.yml

@@ -0,0 +1,25 @@
+name: Download prebuilt frontend statics
+description: >-
+  Download the latest successful extralit-frontend.yml SPA build into
+  extralit-frontend/.output/public, so a server build can bake it into the wheel
+  (and the HF Space built FROM it) as the bundled fallback UI instead of running
+  npm. The SPA is env-agnostic (relative /api), so the same artifact works
+  regardless of where the server is deployed.
+
+inputs:
+  branch:
+    description: Branch whose latest successful frontend build to fetch (main or develop).
+    required: false
+    default: develop
+
+runs:
+  using: composite
+  steps:
+    - uses: dawidd6/action-download-artifact@v21
+      with:
+        workflow: extralit-frontend.yml
+        branch: ${{ inputs.branch }}
+        name: extralit-frontend
+        path: extralit-frontend/.output/public
+        workflow_conclusion: success
+        if_no_artifact_found: fail

.github/workflows/extralit-frontend.build-push-dev.yml

@@ -0,0 +1,148 @@
+name: Deploy PR preview HF Space
+
+# Builds a dev-tagged extralit-server image (pr-<n>) and dispatches the HF Space repo to
+# deploy an ephemeral Space at https://huggingface.co/spaces/extralit-dev/pr-<n>.
+#
+# Deliberately decoupled from extralit-server.yml so it does NOT run on every push:
+#   - auto:   only when a PR (touching the server or frontend) is marked "ready for review"
+#   - manual: workflow_dispatch with a PR number, to (re)deploy a preview on demand
+# main/develop deploys keep flowing through extralit-server.yml as before.
+
+on:
+  # Note: `ready_for_review` only fires on a draft→ready transition. A PR opened
+  # directly as non-draft does NOT auto-trigger — mark it ready, or use the manual
+  # workflow_dispatch below. This is intentional: previews never build on push.
+  pull_request:
+    types: [ready_for_review]
+    paths:
+      - "extralit-server/**"
+      - "extralit-frontend/**"
+      - ".github/workflows/extralit-frontend.build-push-dev.yml"
+      - ".github/workflows/extralit-server.build-docker-images.yml"
+
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to deploy to extralit-dev/pr-<n>"
+        required: true
+        type: string
+
+concurrency:
+  # One preview build per PR; cancel superseded runs.
+  group: pr-preview-${{ github.event.pull_request.number || inputs.pr_number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build `extralit-server` package (frontend baked in)
+    runs-on: ubuntu-latest
+    # Fork PRs don't receive secrets (Docker login / dispatch would fail), so skip them.
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.fork == false
+
+    defaults:
+      run:
+        shell: bash -l {0}
+        working-directory: extralit-server
+
+    steps:
+      - name: Checkout Code 🛎
+        uses: actions/checkout@v4
+        with:
+          # Auto path: default merge ref (refs/pull/<n>/merge). Manual path: resolve the PR's
+          # merge ref from pr_number so the build is self-contained — no need to run from the
+          # PR's head branch for the pr-<n> image/Space to reflect that PR's code.
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/pull/{0}/merge', inputs.pr_number) || github.ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86
+        with:
+          pyproject-file: "extralit-server/pyproject.toml"
+          enable-cache: true
+          cache-local-path: ~/.cache/uv
+          cache-dependency-glob: "extralit-server/uv.lock"
+
+      # No pytest here — preview-only path. The live frontend preview for this PR is published to
+      # Vercel by extralit-frontend.yml; the HF Space only needs a bundled fallback UI, so bake
+      # the prebuilt develop frontend artifact instead of rebuilding from source.
+      - name: Download prebuilt frontend statics
+        uses: ./.github/actions/download-frontend-artifact
+        with:
+          branch: develop
+
+      - name: Build package
+        run: |
+          set -euo pipefail
+          # Bake the compiled SPA into the wheel's static dir. Fail loudly if it's missing or
+          # empty, otherwise the server ships with no statics and 404s every route.
+          cp -r ../extralit-frontend/.output/public src/extralit_server/static
+          test -f src/extralit_server/static/index.html
+          uv build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: extralit-server
+          path: extralit-server/dist
+
+  build_docker_images:
+    name: Build docker images
+    needs:
+      - build
+    uses: ./.github/workflows/extralit-server.build-docker-images.yml
+    with:
+      is_release: false
+      publish_latest: false
+      # PR number on BOTH paths (manual input, or the PR number on the auto path). This forces
+      # IMAGE_TAG=pr-<n>, DISPATCH_BRANCH=<n>/merge, and crucially PUBLISH_LATEST=false so a
+      # preview never republishes the dev :latest tag from unreviewed PR code.
+      pr_number: ${{ inputs.pr_number || github.event.pull_request.number }}
+    secrets: inherit
+
+  # Opportunistic: this PR has its own ephemeral HF Space (extralit-dev/pr-<n>), so point the
+  # PR's Vercel preview at it instead of the shared develop backend. Vercel's native Git
+  # integration builds the preview; we just set a branch-scoped Preview env var (read by
+  # extralit-frontend/vercel.ts at build time) and redeploy the branch's latest preview so it
+  # takes effect now. Best-effort — never blocks the preview pipeline.
+  point-preview-at-pr-space:
+    name: Point Vercel preview at this PR's HF Space
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.fork == false
+    env:
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      GH_TOKEN: ${{ github.token }}
+      PR_NUMBER: ${{ inputs.pr_number || github.event.pull_request.number }}
+      HEAD_REF: ${{ github.head_ref }}
+    steps:
+      - name: Set branch-scoped preview backend + redeploy
+        continue-on-error: true
+        run: |
+          set -uo pipefail
+          if [[ -z "${VERCEL_TOKEN:-}" || -z "${VERCEL_PROJECT_ID:-}" ]]; then
+            echo "Vercel secrets not configured; skipping preview override."; exit 0
+          fi
+          # Resolve the PR head branch (manual dispatch only carries the PR number).
+          BRANCH="${HEAD_REF:-}"
+          if [[ -z "$BRANCH" ]]; then
+            BRANCH=$(gh pr view "$PR_NUMBER" --repo "${{ github.repository }}" --json headRefName -q .headRefName)
+          fi
+          SPACE_URL="https://extralit-dev-pr-${PR_NUMBER}.hf.space"
+          echo "Pointing preview for branch '$BRANCH' at $SPACE_URL"
+          npm install -g vercel@latest
+          # Durable: branch-scoped Preview env var so every build of this branch targets its Space.
+          # (Branch-scoped add is non-interactive with an explicit branch arg + --value + --yes.)
+          vercel env rm API_BASE_URL preview "$BRANCH" --token="$VERCEL_TOKEN" --yes 2>/dev/null || true
+          vercel env add API_BASE_URL preview "$BRANCH" --value "$SPACE_URL" --token="$VERCEL_TOKEN" --yes --force
+          # Immediate: redeploy the branch's latest preview so the new env applies now.
+          uid=$(curl -fsSL -H "Authorization: Bearer $VERCEL_TOKEN" \
+            "https://api.vercel.com/v6/deployments?projectId=${VERCEL_PROJECT_ID}&teamId=${VERCEL_ORG_ID}&target=preview&limit=30" 2>/dev/null \
+            | jq -r --arg b "$BRANCH" '[.deployments[] | select(.meta.githubCommitRef==$b)][0].uid // empty')
+          if [[ -n "${uid:-}" ]]; then
+            vercel redeploy "$uid" --token="$VERCEL_TOKEN" || echo "Redeploy failed (non-fatal); env applies on next build."
+          else
+            echo "No existing preview for '$BRANCH' yet; env applies on first/next build."
+          fi