Nuxt 4 SPA migration: Laravel becomes API-only

.dockerignore

@@ -1,4 +1,7 @@
-node_modules
+# Docker only applies a bare directory name at the top level, so `node_modules`
+# alone never excluded client/node_modules (~466MB) — it was uploaded to the
+# builder on every deploy, CI included. Use ** for anything nested.
+**/node_modules
 vendor
 .git
 .env*
@@ -14,4 +17,25 @@ tests/Browser/screenshots
 tests/Browser/console
 *.log
 .DS_Store
-Thumbs.db
+Thumbs.db
+
+# Local-only clutter. These never exist in a CI checkout, but a manual
+# `flyctl deploy` from a working tree uploads them: together they took the
+# build context to 8.1GB / 358k files and made the deploy time out.
+.worktrees/
+.claude/
+.idea/
+.vscode/
+
+# Test/report output. All untracked, so a CI checkout never has them, but a
+# local deploy would ship ~253MB of screenshots and reports.
+playwright-report/
+parity-shots/
+test-results/
+/uploads/
+
+# Root-level database dumps (e.g. restarters-anonymised.sql, ~662MB).
+# Anchored to the root on purpose: database/data_updates/*.sql is tracked and
+# must stay in the image.
+/*.sql
+/*.sql.gz

.github/workflows/pr-preview.yml

@@ -3,7 +3,7 @@
 # Deploy:  label a PR with 'preview' (or re-push while labeled, or run this
 #          workflow manually with a PR number). Every deploy waits for
 #          approval via the 'preview' GitHub Environment — approvers should
-#          glance at the PR's diff to .github/workflows/, fly.pr.toml,
+#          glance at the PR's diff to .github/workflows/, fly.preview.toml,
 #          Dockerfile.fly and docker/*.sh before approving, since the deploy
 #          runs the PR's own code.
 # Cleanup: a 6-hourly sweep destroys apps whose PR is closed or no longer
@@ -116,7 +116,7 @@ jobs:
       - name: Overlay preview infra files from develop if still missing
         run: |
           git fetch origin develop --depth=1
-          for f in fly.pr.toml docker/preview-startup.sh; do
+          for f in fly.preview.toml docker/preview-startup.sh; do
             if [ ! -f "$f" ]; then
               echo "Branch lacks $f - taking it from develop"
               git show origin/develop:"$f" > "$f"
@@ -153,7 +153,7 @@ jobs:
           else
             flyctl apps create "$APP" --org "$FLY_ORG"
             # Shared read-only credentials (Tigris RO, Drive RO, gate password...)
-            # Strip comments/blank lines so the fly.pr-secrets.example.env
+            # Strip comments/blank lines so the fly.preview-secrets.example.env
             # template can be filled in and pasted as-is.
             echo "$FLY_PREVIEW_SECRETS" | grep -vE '^\s*(#|$)' \
               | flyctl secrets import --app "$APP" --stage
@@ -171,8 +171,14 @@ jobs:
           PR="${{ steps.pr.outputs.number }}"
           # Shown on the cookie-gate login page so testers know which PR this is.
           flyctl secrets set PREVIEW_PR_TITLE="$PR_TITLE" --app "$APP" --stage
-          sed "s/__PR_NUMBER__/$PR/g" fly.pr.toml > fly.pr.generated.toml
-          flyctl deploy --config fly.pr.generated.toml --app "$APP" \
+          # fly.preview.toml is shared with the develop deploy in
+          # .circleci/config.yml; keep the two substitution lists in step.
+          sed -e "s|__APP_NAME__|$APP|g" \
+              -e "s|__APP_TITLE__|Restarters PR #$PR|g" \
+              -e "s|__BASE_URL__|https://$APP.fly.dev|g" \
+              -e "s|__SENTRY_ENV__|preview|g" \
+              fly.preview.toml > fly.preview.generated.toml
+          flyctl deploy --config fly.preview.generated.toml --app "$APP" \
             --remote-only --ha=false
           # --ha=false has a history of not reliably keeping one machine.
           flyctl scale count 1 --app "$APP" --yes

.gitignore

@@ -32,9 +32,29 @@ restarters-anonymised.sql
 /.claude/settings.local.json
 /public/build/
 /storage/api-docs/api-docs.json
+/storage/app/tus
+/storage/app/tus-cache
 /.phpunit.result.cache
 /playwright-report/
 /events.csv
 /public/repair-data*.csv
 /uploads/*.jpg
 .mcp.json
+
+# Local ralph session log (not for commit)
+.claude-session.md
+# PHPUnit coverage artifact
+/tests/clover.xml
+
+# Visual parity capture output (task parity:capture) - screenshots, never committed
+parity-shots/
+
+# Canvas share-image backgrounds (224MB, 267 files). These live in the Laravel
+# app at public/images/stats and must NOT be duplicated into the client bundle.
+# The client reaches them through an /api/* endpoint so CORS applies and the
+# canvas stays untainted - see the stats-share composable.
+client/public/images/stats/
+parity-fixtures.json
+
+# Generated from fly.preview.toml by CI (and by hand for manual deploys)
+fly.*.generated.toml

.php_cs.cache

@@ -0,0 +1 @@
+{"php":"8.4.21","version":"2.19.1","indent":"    ","lineEnding":"\n","rules":{"array_syntax":{"syntax":"short"},"binary_operator_spaces":{"default":"single_space","operators":{"=>":null}},"blank_line_after_namespace":true,"blank_line_after_opening_tag":true,"blank_line_before_statement":{"statements":["return"]},"braces":true,"cast_spaces":true,"class_attributes_separation":{"elements":["method"]},"class_definition":true,"concat_space":{"spacing":"none"},"declare_equal_normalize":true,"elseif":true,"encoding":true,"full_opening_tag":true,"fully_qualified_strict_types":true,"function_declaration":true,"function_typehint_space":true,"heredoc_to_nowdoc":true,"include":true,"increment_style":{"style":"post"},"indentation_type":true,"linebreak_after_opening_tag":true,"line_ending":true,"lowercase_cast":true,"lowercase_constants":true,"lowercase_keywords":true,"lowercase_static_reference":true,"magic_method_casing":true,"magic_constant_casing":true,"method_argument_space":true,"native_function_casing":true,"no_alias_functions":true,"no_extra_blank_lines":{"tokens":["extra","throw","use","use_trait"]},"no_blank_lines_after_class_opening":true,"no_blank_lines_after_phpdoc":true,"no_closing_tag":true,"no_empty_phpdoc":true,"no_empty_statement":true,"no_leading_import_slash":true,"no_leading_namespace_whitespace":true,"no_mixed_echo_print":{"use":"echo"},"no_multiline_whitespace_around_double_arrow":true,"multiline_whitespace_before_semicolons":{"strategy":"no_multi_line"},"no_short_bool_cast":true,"no_singleline_whitespace_before_semicolons":true,"no_spaces_after_function_name":true,"no_spaces_around_offset":true,"no_spaces_inside_parenthesis":true,"no_trailing_comma_in_list_call":true,"no_trailing_comma_in_singleline_array":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"no_unneeded_control_parentheses":true,"no_unreachable_default_argument_value":true,"no_useless_return":true,"no_whitespace_before_comma_in_array":true,"no_whitespace_in_blank_line":true,"normalize_index_brace":true,"not_operator_with_successor_space":true,"object_operator_without_whitespace":true,"ordered_imports":{"sortAlgorithm":"alpha"},"phpdoc_indent":true,"phpdoc_inline_tag":true,"phpdoc_no_access":true,"phpdoc_no_package":true,"phpdoc_no_useless_inheritdoc":true,"phpdoc_scalar":true,"phpdoc_single_line_var_spacing":true,"phpdoc_summary":true,"phpdoc_to_comment":true,"phpdoc_trim":true,"phpdoc_types":true,"phpdoc_var_without_name":true,"psr4":true,"self_accessor":true,"short_scalar_cast":true,"single_blank_line_at_eof":true,"single_blank_line_before_namespace":true,"single_class_element_per_statement":true,"single_import_per_statement":true,"single_line_after_imports":true,"single_line_comment_style":{"comment_types":["hash"]},"single_quote":true,"space_after_semicolon":true,"standardize_not_equals":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"ternary_operator_spaces":true,"trailing_comma_in_multiline_array":true,"trim_array_spaces":true,"unary_operator_spaces":true,"visibility_required":{"elements":["method","property"]},"whitespace_after_comma_in_array":true},"hashes":{"app\/Http\/Controllers\/API\/StatsShareImageController.php":653998297,"tests\/Feature\/Devices\/APIv2StatsShareImageTest.php":3643096653,"routes\/api.php":180907154}}

CLAUDE.md

@@ -25,9 +25,9 @@ task docker:run:artisan -- migrate         # Run artisan command
 task docker:shell                          # Open shell in container
 
 # Testing
-task docker:test:phpunit      # Run PHP tests
-task docker:test:jest         # Run JS tests
-task docker:test:playwright   # Run e2e tests
+task docker:test:phpunit             # Run PHP tests
+task docker:test:vitest              # Run client (Nuxt) unit tests
+task docker:test:playwright:client   # Run client e2e tests
 
 # Vite dev server (HMR)
 task docker:vite:start        # Start Vite in background
@@ -74,11 +74,9 @@ task docker:shell        # Open shell in container
 task docker:run:artisan -- migrate  # Run artisan commands
 task docker:run:bash -- "command"   # Run bash commands
 
-# Run Vite for HMR (hot module replacement)
-task docker:run:bash -- "npm run dev"
-
 # The application will be available at:
-# - Restarters: http://localhost:8001 (Admin: jane@bloggs.net / passw0rd)
+# - Frontend (Nuxt SPA, restarters_client): http://localhost:8004 (Admin: jane@bloggs.net / passw0rd)
+# - Laravel API: http://localhost:8001
 # - phpMyAdmin: http://localhost:8002 (Host: restarters_db, User: root, Pass: s3cr3t)
 # - Mailhog: http://localhost:8025
 # - Discourse: http://localhost:8003
@@ -89,11 +87,13 @@ task docker:run:bash -- "npm run dev"
 # Install PHP dependencies
 composer install
 
-# Install and build frontend assets
-npm install
-npm run dev          # Development build
-npm run watch        # Watch for changes
-npm run production   # Production build
+# Frontend (Nuxt SPA) — the restarters_client container runs the dev server;
+# for local tooling outside Docker:
+cd client && npm install && npm run dev
+
+# Widget/wiki assets still built by Laravel-side Vite (rarely needed):
+npm install --legacy-peer-deps
+npm run build
 
 # Laravel commands
 php artisan migrate            # Run database migrations
@@ -121,11 +121,11 @@ export DB_TEST_HOST=restarters_db
 # Run specific test method
 ./vendor/bin/phpunit --filter testMethodName
 
-# Run JavaScript tests
-npm run jest
+# Run client unit tests (from client/)
+cd client && npx vitest run
 
-# Run Playwright end-to-end tests
-npm test
+# Run client Playwright end-to-end tests
+task docker:test:playwright:client
 ```
 
 ### Code Quality
@@ -168,11 +168,14 @@ npm test
 - JSON columns for flexible network_data storage
 
 ### Frontend Stack
-- **Vue 2** components for interactive features
-- **Laravel Mix** for asset compilation
-- **Bootstrap 4** for styling
-- **SCSS** for styles in `resources/sass/`
-- Multiple build targets: main app, global styles, wiki styles
+- **Nuxt 4 SPA in `client/`** — Vue 3, Pinia, bootstrap-vue-next (Bootstrap 5),
+  @nuxtjs/i18n, Vitest; talks to Laravel exclusively via `/api/v2`
+- Laravel serves no user-facing pages (see `tests/Feature/ApiOnlyRouteSurfaceTest.php`
+  for the pinned web-route surface): only the embeddable stats widgets and the
+  MediaWiki skin assets are still built here (Vite, `resources/global` +
+  `resources/wiki`, jQuery/Bootstrap 4 only)
+- Client translations are exported from `lang/*.php` via
+  `php artisan translations:export-client` (checked in CI)
 
 ### Permission System
 - Role-based permissions via custom `app/Role.php` and `app/Permissions.php`

Dockerfile.fly

@@ -17,8 +17,9 @@
 # Install composer
 COPY --from=composer/composer:2-bin /composer /usr/bin/composer
 
-# Install Node 18
-RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+# Install Node 22 (Nuxt 4 / nuxi require Node >=22; matches client/Dockerfile
+# node:22 and CI cimg/node:22.16. Vite 4 root build is Node-22-compatible too.)
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y nodejs \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 
@@ -53,6 +54,19 @@
 RUN php artisan lang:js --no-lib resources/js/translations.js 2>/dev/null || true
 RUN npm run production && rm -f public/hot
 
+# Build the Nuxt SPA (the separate app in client/). `nuxt build` emits a
+# standalone Nitro Node server at client/.output that bundles its own runtime
+# deps, so production serves the SPA origin via
+# `node client/.output/server/index.mjs` (see docker/supervisord-fly.conf).
+# apiBase is runtime-overridable (NUXT_PUBLIC_API_BASE), so no API URL is baked
+# in here. Drop client/node_modules afterwards — .output is self-contained, and
+# this keeps the final-stage `COPY /build` from dragging the dev install in.
+WORKDIR /build/client
+RUN npm ci --legacy-peer-deps
+RUN npm run build
+RUN rm -rf node_modules
+WORKDIR /build
+
 # Generate swagger docs (non-fatal if it fails)
 RUN php artisan l5-swagger:generate 2>/dev/null || true
 
@@ -77,6 +91,7 @@
     util-linux \
     default-mysql-client \
     rclone \
+    curl ca-certificates gnupg \
     libpng-dev libjpeg62-turbo-dev libfreetype6-dev libzip-dev libicu-dev libxml2-dev \
     && if [ "$STARTUP_SCRIPT" != "startup.sh" ]; then apt-get install -y --no-install-recommends default-mysql-server; fi \
     && docker-php-ext-configure gd --with-freetype --with-jpeg \
@@ -86,6 +101,13 @@
 # Install xmlrpc
 RUN pecl install channel://pecl.php.net/xmlrpc-1.0.0RC3 && docker-php-ext-enable xmlrpc
 
+# Node 22 (runtime only) — runs the Nuxt Nitro server that serves the SPA origin
+# (client/.output, started by supervisord). The .output targets Node >=22, same
+# as the builder. This image only needs the node binary to run it.
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean && rm -rf /var/lib/apt/lists/*
+
 # Configure PHP-FPM to use unix socket.
 # The base image ships docker.conf (formerly zz-docker.conf) with:
 #   listen = 9000      — overrides www.conf (last-file-wins in glob)