feat(web): rewrite frontend with Vite

.github/workflows/deploy.yml

@@ -32,8 +32,11 @@ jobs:
           filters: |
             backend:
               - 'backend/**'
+            # The rebuilt app in web/ is what ships. frontend/ is still in the
+            # tree for one release as a fallback but is no longer deployed, so
+            # a change to it must not trigger a build.
             frontend:
-              - 'frontend/**'
+              - 'web/**'
             nginx:
               - 'infra/nginx/**'
             meilisearch:
@@ -59,6 +62,74 @@ jobs:
               - 'infra/postgres/**'
               - 'infra/backup/**'
 
+      # Validate the exact source contract before publishing an image or static
+      # artifact. The dummy env supplies import-time Config values only; FastAPI
+      # lifespan is not started by the exporter.
+      - name: Install PostgreSQL build tools
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        run: sudo apt-get update && sudo apt-get install -y libpq-dev
+
+      - name: Set up Python for backend checks
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: backend/uv.lock
+
+      - name: Install backend dependencies
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Test backend
+        if: steps.changes.outputs.backend == 'true'
+        working-directory: backend
+        run: uv run --env-file ../infra/.env.example pytest
+
+      - name: Export OpenAPI contract
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        working-directory: backend
+        run: uv run python scripts/export_openapi.py --output "${{ runner.temp }}/openapi.json"
+
+      - name: Enable pnpm
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        run: corepack enable
+
+      - name: Set up Node.js for checks
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+
+      - name: Install web dependencies
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        working-directory: web
+        run: pnpm install --frozen-lockfile
+
+      - name: Check generated API types
+        if: steps.changes.outputs.backend == 'true' || steps.changes.outputs.frontend == 'true'
+        working-directory: web
+        env:
+          OPENAPI_URL: ${{ runner.temp }}/openapi.json
+        run: pnpm api:check
+
+      - name: Validate frontend
+        if: steps.changes.outputs.frontend == 'true'
+        working-directory: web
+        run: |
+          pnpm format:check
+          pnpm lint
+          pnpm test
+          pnpm build
+
       - name: Log in to Docker Hub
         uses: docker/login-action@v3
         with:
@@ -120,22 +191,9 @@ jobs:
           cache-to: type=gha,mode=max,scope=nuspace-backup
 
       # --- Frontend static export (Vite SPA) — built on the runner, not on the VM ---
-      - name: Set up Node.js for frontend build
-        if: steps.changes.outputs.frontend == 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: npm
-          cache-dependency-path: frontend/package-lock.json
-
-      - name: Build frontend static output
-        if: steps.changes.outputs.frontend == 'true'
-        working-directory: frontend
-        run: npm ci && npm run build
-
       - name: Pack frontend out/ for Ansible
         if: steps.changes.outputs.frontend == 'true'
-        run: tar czf "${{ runner.temp }}/frontend-static.tar.gz" -C frontend/out .
+        run: tar czf "${{ runner.temp }}/frontend-static.tar.gz" -C web/out .
 
       - name: Frontend tarball path for Ansible
         id: fe_artifact

.github/workflows/quality.yml

@@ -0,0 +1,107 @@
+name: Quality
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install PostgreSQL build tools
+        run: sudo apt-get update && sudo apt-get install -y libpq-dev
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: backend/uv.lock
+
+      - name: Install backend dependencies
+        working-directory: backend
+        run: uv sync --frozen
+
+      - name: Run backend tests
+        working-directory: backend
+        run: uv run --env-file ../infra/.env.example pytest
+
+      - name: Export OpenAPI
+        working-directory: backend
+        run: uv run python scripts/export_openapi.py --output "${{ runner.temp }}/openapi.json"
+
+      - name: Upload OpenAPI contract
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-contract
+          path: ${{ runner.temp }}/openapi.json
+
+  web:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Enable pnpm
+        run: corepack enable
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+
+      - name: Install web dependencies
+        working-directory: web
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        working-directory: web
+        run: pnpm format:check
+
+      - name: Lint web
+        working-directory: web
+        run: pnpm lint
+
+      - name: Test web
+        working-directory: web
+        run: pnpm test
+
+      - name: Build web
+        working-directory: web
+        run: pnpm build
+
+  contract:
+    needs: [backend, web]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download OpenAPI contract
+        uses: actions/download-artifact@v4
+        with:
+          name: openapi-contract
+          path: openapi
+
+      - name: Enable pnpm
+        run: corepack enable
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Check generated API types
+        working-directory: web
+        env:
+          OPENAPI_URL: ${{ github.workspace }}/openapi/openapi.json
+        run: pnpm api:check

AGENTS.md

@@ -4,7 +4,9 @@
 
 ```
 backend/       Python 3.12 / FastAPI app (package name: nuros)
-frontend/      React 19 / Vite 7 / TypeScript SPA
+web/           React 19 / Vite 8 / TypeScript SPA — the app that ships
+frontend/      The previous SPA. Kept one release as a fallback; not built,
+               not routed to, not deployed. Work in web/.
 infra/         Docker Compose, Nginx, monitoring, service configs
 terraform/     GCP infrastructure-as-code
 ansible/       Deployment playbooks (runs from CI, not locally)
@@ -39,15 +41,27 @@ uv run pytest                        # tests
 
 Pre-commit hooks run `ruff --fix` then `black` automatically.
 
-### Frontend (`frontend/`)
+### Frontend (`web/`)
+
+pnpm, not npm. The lockfile is `web/pnpm-lock.yaml` and CI installs with
+`--frozen-lockfile`, so a dependency added with npm will fail the build.
 
 ```sh
-npm ci && npm run build              # production build → out/
-npm run dev                          # dev server on :5173
-npm run test:url-validation          # run a single test file via tsx
+pnpm install                         # deps
+pnpm build                           # typecheck + production build → out/
+pnpm dev                             # dev server on :5173
+pnpm typecheck                       # tsc -b --noEmit
+pnpm lint                            # oxlint, including type-aware rules
+pnpm format                          # prettier, sorts Tailwind classes
+pnpm test                            # node --test over src/**/*.test.ts
+pnpm api:check                       # fail if src/api/schema.d.ts is stale
 ```
 
-TypeScript strict mode. `@` alias maps to `src/`.
+`out/`, not Vite's default `dist/` — the deployment path expects it (see
+`web/vite.config.ts`).
+
+TypeScript strict mode. `@` alias maps to `src/`. Read `web/README.md` before
+changing anything there; several of its conventions are load-bearing.
 
 ## Backend Architecture
 

ansible/roles/frontend/tasks/main.yml

@@ -1,10 +1,14 @@
 ---
 # Static files are built in GitHub Actions and shipped as a tarball on the controller.
 # `frontend_tarball_path` is set by CI when frontend paths changed; empty skips deploy.
+#
+# The path is web/out, not frontend/out: the app that ships is the rebuild in
+# web/. The frontend/ tree is still in the repository for one release, but
+# nothing unpacks into it and nginx no longer serves it.
 
 - name: Ensure frontend out directory exists with proper permissions
   ansible.builtin.file:
-    path: "/home/{{ ansible_user }}/nuspace/frontend/out"
+    path: "/home/{{ ansible_user }}/nuspace/web/out"
     state: directory
     owner: "{{ ansible_user }}"
     group: "{{ ansible_user }}"
@@ -14,23 +18,23 @@
 - name: Clear previous static export
   ansible.builtin.shell: |
     set -e
-    rm -rf /home/{{ ansible_user }}/nuspace/frontend/out/*
+    rm -rf /home/{{ ansible_user }}/nuspace/web/out/*
   args:
     executable: /bin/bash
   when: frontend_tarball_path | default('') | length > 0
 
 - name: Unpack frontend build from CI runner to VM
   ansible.builtin.unarchive:
     src: "{{ frontend_tarball_path }}"
-    dest: "/home/{{ ansible_user }}/nuspace/frontend/out"
+    dest: "/home/{{ ansible_user }}/nuspace/web/out"
     remote_src: false
     owner: "{{ ansible_user }}"
     group: "{{ ansible_user }}"
   when: frontend_tarball_path | default('') | length > 0
 
 - name: Verify out files were created
   ansible.builtin.stat:
-    path: "/home/{{ ansible_user }}/nuspace/frontend/out/index.html"
+    path: "/home/{{ ansible_user }}/nuspace/web/out/index.html"
   register: dist_check
   when: frontend_tarball_path | default('') | length > 0
 
@@ -43,7 +47,7 @@
 
 - name: Show frontend deploy success message
   ansible.builtin.debug:
-    msg: "Frontend static files from CI are deployed under frontend/out."
+    msg: "Frontend static files from CI are deployed under web/out."
   when: frontend_tarball_path | default('') | length > 0
 
 - name: Recreate nginx service to pick up new out files

backend/common/utils/meilisearch.py

@@ -2,6 +2,7 @@
 from typing import Type
 
 from backend.core.database.manager import AsyncDatabaseManager
+from fastapi import HTTPException
 from httpx import AsyncClient
 from sqlalchemy import select
 from sqlalchemy.orm import DeclarativeBase
@@ -81,6 +82,24 @@ async def get(
         payload["filter"] = filters
 
     response = await client.post(f"/indexes/{storage_name}/search", json=payload)
+
+    # An error response has no "hits", and every caller reads result["hits"]
+    # directly -- so without this the failure surfaces as an opaque
+    # `KeyError: 'hits'` and a 500 with no indication of what went wrong.
+    #
+    # This is not a rare edge: index setup deletes and recreates every index on
+    # startup, so there is a window after each deploy where searching an index
+    # that does not exist yet 500s.
+    if response.status_code >= 400:
+        body = response.json()
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                f"Search index '{storage_name}' is unavailable "
+                f"({body.get('code', response.status_code)})."
+            ),
+        )
+
     return response.json()
 
 

backend/core/configs/config.py

@@ -44,6 +44,15 @@ class Config(BaseSettings):
     GCP_SIGNING_SERVICE_ACCOUNT_KEY_JSON: str | None = None
     ORIGINS: List[str] = ["*"]
     MOCK_KEYCLOAK: bool  # always set True in local dev
+    # Your own registrar username, for testing the registrar sync locally.
+    #
+    # Mock users have no real NU email, so the username cannot be derived from
+    # the session the way it is in production. This used to be a colleague's
+    # username written into the source, which meant every developer's local sync
+    # attempt was a login attempt against that person's real registrar account --
+    # and enough wrong passwords locks them out. Set your own here, or leave it
+    # unset and the sync will simply fail to authenticate.
+    REGISTRAR_DEBUG_USERNAME: str | None = None
     USE_GCS_EMULATOR: bool  # keep True for local dev; For staging/prod .env will have it False
     GCS_EMULATOR_HOST: str
     INTEGRATION_SECRET: str