native-update 1.4.9 → 3.1.0

package/docs/project-audit/2026-05-16/01-BATCH-PLAN.md

@@ -0,0 +1,227 @@
+# Batch Plan — 2026-05-16 Finalization
+
+Each batch: 40–60 min, 1–4 tasks, one commit, verification commands, session report under `sessions/batch-NN.md`.
+
+---
+
+## Batch 1: Auth + critical backend fixes
+
+**Skills:** `laravel-specialist`, `security-best-practices`
+
+| # | File | Change |
+|---|---|---|
+| 1.1 | `backend/config/sanctum.php:53` | `'expiration' => null` → `'expiration' => env('SANCTUM_TOKEN_EXPIRATION', 10080)` |
+| 1.2 | `backend/routes/api.php:119` | Verify `/api/dashboard/me` GET intentionally has no `can:` gate (any authenticated user reads own profile) — add inline comment documenting this is by design |
+| 1.3 | `backend/config/logging.php:64,71` | Default log level `'debug'` → `env('LOG_LEVEL', 'warning')` for both `single` and `daily` channels |
+| 1.4 | `backend/app/Http/Controllers/Admin/AdminController.php:8` | Replace "Firebase `admin: true` claim" docblock with "Spatie super-admin role via spatie/laravel-permission" |
+| 1.5 | `backend/app/Policies/AppPolicy.php:11` + `backend/app/Policies/BuildPolicy.php:4` | Same Firebase → Spatie docblock fix |
+| 1.6 | `backend/app/Policies/AppPolicy.php:15` | Add `?bool` return type to `before(User $user, string $ability)` |
+| 1.7 | `backend/.env.example` | Add inline comments above `ADMIN_EMAILS=` explaining first-signer auto-promotion behaviour |
+| 1.8 | `docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md:34–35, 137` | Replace Firebase env var references with `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI`/`ADMIN_EMAILS` |
+
+**Verify:** `cd backend && php artisan test --without-tty` — all green (baseline 110/110). Then `php artisan config:clear && php artisan route:list` to confirm no booted-config errors.
+
+**Commit:** `fix(backend): Batch 1 — Sanctum expiration, LOG_LEVEL, Firebase reference cleanup`
+
+---
+
+## Batch 2: Website build + plugin test fixes
+
+**Skills:** `react-best-practices`, `react-19`, `vitest`
+
+| # | File | Change |
+|---|---|---|
+| 2.1 | `website/src/pages/dashboard/ConfigPage.tsx:~43` | Move async `loadApps()` declaration above the `useEffect` that calls it OR wrap in `useCallback` and add to deps array properly |
+| 2.2 | `website/src/pages/dashboard/GoogleDrivePage.tsx:~37` | Same pattern fix for `loadData()` |
+| 2.3 | `website/src/pages/dashboard/SettingsPage.tsx:~72` | Same pattern fix for `loadUserData()` |
+| 2.4 | `website/src/pages/dashboard/UploadPage.tsx:~363` | Fix ref usage — don't pass a ref-created callback into `handleSubmit()` during render; declare the submit handler with `useCallback` or hoist it |
+| 2.5 | `src/__tests__/integration.test.ts` (root plugin) | Add `beforeEach` localStorage polyfill OR move `loadStoredData()` out of constructor / make it idempotent / guard `typeof window === 'undefined'` |
+
+**Verify:**
+- `cd website && yarn lint` → exit 0 (currently 11 errors)
+- `cd website && yarn typecheck` → exit 0
+- `cd website && yarn build` → exit 0
+- `yarn test:run` (root) → 62/62 passing (currently 53/62)
+
+**Commit:** `fix(build): Batch 2 — rules-of-hooks fixes + plugin test localStorage polyfill`
+
+---
+
+## Batch 3: Auth token via Capacitor Preferences
+
+**Skills:** `capacitor-best-practices`, `capacitor-plugins`, `capacitor-offline-first`
+
+| # | File | Change |
+|---|---|---|
+| 3.1 | `website/src/lib/auth-token.ts` | Refactor to async API backed by `@capacitor/preferences` with `localStorage` fallback on web. Replace synchronous getters with async or boot-time hydrated cache. |
+| 3.2 | `website/src/lib/api.ts` | Update axios/fetch interceptor to read token from new async helper; cache token in memory for sync access during requests |
+| 3.3 | `website/src/context/AuthContext.tsx` | On boot, hydrate token from Preferences before flipping `loading=false` so the BootLoader keeps showing |
+| 3.4 | `website/src/pages/auth/CallbackPage.tsx` | Write token via new async helper, await before navigating |
+| 3.5 | `website/src/lib/api.ts` (401 handler) | On 401, clear token + push a global event/store flag that `AuthContext` listens to → redirect to `/login` automatically |
+
+**Verify:**
+- `cd website && yarn typecheck && yarn build` → clean
+- Read-only manual review: trace the login → callback → API → 401 path for completeness
+
+**Commit:** `feat(auth): Batch 3 — Capacitor Preferences token storage + 401 auto-redirect`
+
+---
+
+## Batch 4: Backend OAuth/Sanctum/Roles tests + FormRequest
+
+**Skills:** `laravel-specialist`, `security-best-practices`
+
+| # | File | Change |
+|---|---|---|
+| 4.1 | `backend/tests/Feature/OAuthControllerTest.php` (new) | Test cases: redirect issues correct Socialite URL; callback creates new user with `user` role; callback assigns `super-admin` if email in `ADMIN_EMAILS`; callback returns redirect to frontend with `?token=...`; existing user re-login refreshes attributes; token has expected abilities |
+| 4.2 | `backend/tests/Feature/SanctumTokenTest.php` (new) | Test cases: protected route rejects no token; protected route accepts valid token; expired token is rejected (use `Carbon::setTestNow`); abilities are honoured; `tokenCan()` works correctly |
+| 4.3 | `backend/tests/Feature/RolesPermissionsTest.php` (new) | Test cases: seeder is idempotent (run twice → same state); super-admin bypass works via Gate::before; admin cannot bypass; user lacks admin permissions |
+| 4.4 | `backend/app/Http/Requests/UpdateBuildRequest.php` (new) | Extract validation from `BuildController@update` into FormRequest |
+| 4.5 | `backend/app/Http/Controllers/Dashboard/BuildController.php` | Replace inline `$request->validate(...)` with `UpdateBuildRequest $request` |
+
+**Verify:** `cd backend && php artisan test --without-tty` — strictly more tests than baseline 110, all green.
+
+**Commit:** `test(backend): Batch 4 — OAuth/Sanctum/Roles coverage + UpdateBuildRequest`
+
+---
+
+## Batch 5: Admin pages → TanStack Query
+
+**Skills:** `tanstack-query-best-practices`, `react-best-practices`
+
+| # | File | Change |
+|---|---|---|
+| 5.1 | `website/src/pages/admin/AdminUsersPage.tsx:29–46` | Replace `useEffect`+`useState` with `useQuery` (queryKey `['admin','users',page,perPage,q]`), URL-state pagination, optimistic invalidation on role-change mutation |
+| 5.2 | `website/src/pages/admin/AdminAppsPage.tsx:24–41` | Same pattern: `useQuery` with `['admin','apps',page,perPage]` |
+| 5.3 | `website/src/pages/admin/AdminBuildsPage.tsx:24–41` | Same pattern: `useQuery` with `['admin','builds',page,perPage,status]` |
+| 5.4 | `website/src/pages/dashboard/DashboardOverview.tsx:20–34` | Replace `fetchRecentBuilds` raw Promise.all with `useQuery` |
+| 5.5 | `website/src/pages/dashboard/UploadPage.tsx:49–63` | Replace raw apps-list fetch with `useQuery` |
+
+**Verify:**
+- `cd website && yarn typecheck && yarn lint && yarn build` clean
+- Confirm React Query Devtools (already wired) show consistent query keys
+
+**Commit:** `refactor(admin): Batch 5 — admin + overview pages on TanStack Query`
+
+---
+
+## Batch 6: console.* cleanup + Firebase comment sweep
+
+**Skills:** (trivial pre-check sufficient)
+
+| # | File | Change |
+|---|---|---|
+| 6.1 | `website/src/pages/ExamplesPage.tsx:63,67` | Replace `console.*` with `logger.debug/error` |
+| 6.2 | `website/src/pages/dashboard/SettingsPage.tsx:78–87` | Remove stale Firebase terminology in comments |
+| 6.3 | `website/src/pages/dashboard/ConfigPage.tsx` | Remove stale Firebase comment headers / unused imports |
+| 6.4 | `website/src/lib/env.ts` | Drop `VITE_FIREBASE_*` keys (Firebase Auth removed per CLAUDE.md). Keep only what code still consumes. |
+| 6.5 | `website/.env.example` | Sync `.env.example` with `env.ts` — remove VITE_FIREBASE_* rows |
+| 6.6 | `website/src/vite-env.d.ts` | Drop VITE_FIREBASE_* type declarations |
+
+**Verify:**
+- `grep -rEn "\\bconsole\\.(log|info|debug|trace|warn|error|table|time|timeEnd|group|groupCollapsed|groupEnd)\\(" website/src --include="*.ts" --include="*.tsx" | grep -v "/lib/logger.ts" | grep -v "/pages/DocsPage.tsx"` → zero matches
+- `grep -rEn "firebase|firestore" website/src --include="*.ts" --include="*.tsx" -i | grep -v "// historical"` → zero non-historical matches
+
+**Commit:** `chore(website): Batch 6 — console.* via logger + Firebase reference cleanup`
+
+---
+
+## Batch 7: Play Store metadata + legal pages cleanup
+
+**Skills:** `copywriting`, `web-design-guidelines`
+
+| # | File | Change |
+|---|---|---|
+| 7.1 | `website/app-publish-assets/metadata/full-description.md` | Replace "Firestore project" prose with accurate "self-hosted Laravel + Sanctum backend (or our managed SaaS)" description |
+| 7.2 | `website/app-publish-assets/metadata/data-safety.md` | Strip Firestore reference (line 34); declare Laravel backend + Google Drive + FilesHub storage truthfully |
+| 7.3 | `website/app-publish-assets/metadata/listing-notes.md` | Refresh; remove Firebase Auth language; describe Google OAuth flow accurately |
+| 7.4 | `website/src/pages/PrivacyPage.tsx` | Update content + lastUpdated date to 2026-05-16; describe Google OAuth + Sanctum + Spatie correctly; remove Firebase Auth references |
+| 7.5 | `website/src/pages/TermsPage.tsx` | Update lastUpdated to 2026-05-16; minor content refresh |
+| 7.6 | `website/src/pages/CookiePolicyPage.tsx` | Update lastUpdated; verify cookies list is accurate (no Firebase cookies anymore) |
+| 7.7 | `website/src/pages/SecurityPage.tsx` | Update lastUpdated; verify security architecture description matches current backend |
+
+**Verify:**
+- `grep -rEn -i "firestore" website/app-publish-assets/` → zero matches
+- `grep -rEn -i "firebase auth|firebase.auth" website/src/pages/PrivacyPage.tsx website/src/pages/TermsPage.tsx` → zero matches
+
+**Commit:** `docs(legal): Batch 7 — Play Store metadata + Privacy/Terms refresh for Laravel backend`
+
+---
+
+## Batch 8: Android signing + ProGuard + build guide
+
+**Skills:** `capacitor-app-store`, `capacitor-android`, `security-best-practices`
+
+| # | File | Change |
+|---|---|---|
+| 8.1 | `website/android/keystore.properties.example` (new) | Template file showing required keys: `storeFile`, `storePassword`, `keyAlias`, `keyPassword` |
+| 8.2 | `website/android/.gitignore` | Ensure `keystore.properties` and `*.keystore` / `*.jks` are excluded |
+| 8.3 | `website/android/app/build.gradle` | Add `signingConfigs.release` block reading from `../keystore.properties` if present, falling back to debug keystore for dev; reference it from `buildTypes.release` |
+| 8.4 | `website/android/app/build.gradle:21` | `minifyEnabled false` → `minifyEnabled true` for release; add `shrinkResources true` |
+| 8.5 | `website/android/app/proguard-rules.pro` | Verify Capacitor + WebView rules are present (add `-keep class com.getcapacitor.** { *; }` and similar baseline rules) |
+| 8.6 | `website/android/app/src/main/res/xml/network_security_config.xml` (new) | Production-friendly config; allows cleartext only on debug for localhost ranges |
+| 8.7 | `website/android/app/src/main/AndroidManifest.xml` | Reference network_security_config + ensure `android:usesCleartextTraffic="false"` on application |
+| 8.8 | `website/BUILD_FOR_PLAY_STORE.md` (new) | Full runbook: keytool keystore generation, keystore.properties setup, `yarn build && cap sync && ./gradlew bundleRelease` walkthrough, where to find AAB, signing-key backup advice |
+
+**Verify:**
+- `cd website/android && ./gradlew assembleDebug` → BUILD SUCCESSFUL
+- `git check-ignore website/android/keystore.properties` → file ignored (path returned)
+- AAB build is documented but NOT run (requires user-provided keystore)
+
+**Commit:** `feat(android): Batch 8 — signing config + ProGuard + Play Store build runbook`
+
+---
+
+## Batch 9: App icons + splash + screenshot guide
+
+**Skills:** `capacitor-splash-screen`, `frontend-design`
+
+| # | File | Change |
+|---|---|---|
+| 9.1 | `website/app-publish-assets/icons/icon-1024.png` (new) | Render 1024×1024 from `icon-512.svg` (use a Node script with `sharp` OR document the user-side ImageMagick command) |
+| 9.2 | `website/android/app/src/main/res/mipmap-*/ic_launcher*.png` | Replace default Capacitor icons with rendered native-update branding across all densities (mdpi/hdpi/xhdpi/xxhdpi/xxxhdpi) |
+| 9.3 | `website/android/app/src/main/res/drawable*/splash.png` (or vector equivalent) | Replace splash with branded splash matching `#0A0F1A` BG + logo |
+| 9.4 | `website/capacitor.config.ts` | Verify SplashScreen plugin config — `backgroundColor`, `launchShowDuration` set correctly |
+| 9.5 | `website/app-publish-assets/screenshots/CAPTURE-GUIDE.md` (new) | Step-by-step user runbook: run app on emulator → capture 4–8 screenshots (login, dashboard overview, apps list, upload form, bundle detail, settings, theme customizer, sitemap page) at 1080×1920 minimum |
+
+**Verify:**
+- `cd website && yarn build && npx cap sync android` → success
+- `find website/android/app/src/main/res/mipmap-* -name "*.png" -exec ls -la {} \;` → all branded, non-zero sizes
+- Visual eyeball of `mipmap-xxxhdpi/ic_launcher.png` confirms branding
+
+**Commit:** `feat(android): Batch 9 — branded icons + splash + screenshot capture guide`
+
+---
+
+## Batch 10: SEO refresh + final verification + audit closure
+
+**Skills:** `ai-seo`, `seo`, `stack-audit`
+
+| # | File | Change |
+|---|---|---|
+| 10.1 | `website/postbuild-seo.ts:17` | `PAGE_LAST_UPDATED` → `'2026-05-16'` |
+| 10.2 | `website/postbuild-seo.ts:431` | `softwareVersion: '2.0.0'` → `'3.0.1'` |
+| 10.3 | `website/src/pages/AboutPage.tsx`, `FeaturesPage.tsx`, `PricingPage.tsx` | Bump visible `Last updated` date strings to 2026-05-16 |
+| 10.4 | `website/public/sitemap.xml` | Regenerate or hand-edit `<lastmod>` for refreshed routes (legal, features, pricing, about, sitemap, feed, home) to `2026-05-16` |
+| 10.5 | `website/public/feed.xml` | Bump `<lastBuildDate>` to current date (postbuild-seo.ts may already do this — verify) |
+| 10.6 | `docs/tracking/finalization-2026-05-16-tracker.json` | Mark all 10 batches `completed`, set top-level `last_run.status=complete`, `completed_at=2026-05-16`, `next_allowed_run_after=2026-05-23` |
+| 10.7 | `CLAUDE.md` + `AGENTS.md` (root) | Append new audit record row + bump `Last Updated` |
+| 10.8 | `website/CLAUDE.md` + `website/AGENTS.md` | Same |
+| 10.9 | `docs/rules-tracker.md` | Bump Generic Project Rules apply dates for rules that were re-verified during this audit |
+| 10.10 | `docs/project-audit/2026-05-16/sessions/batch-10.md` (new) | Session report |
+
+**Verify (final gate):**
+- `cd backend && php artisan test --without-tty` → green
+- `yarn build && yarn lint && yarn test:run` (root plugin) → green
+- `cd website && yarn typecheck && yarn lint && yarn build` → green
+- `cd website/android && ./gradlew assembleDebug` → BUILD SUCCESSFUL
+- `grep -rEn -i "firestore" website/app-publish-assets/` → zero
+- `git status` → clean after final commit + push
+
+**Commit:** `chore(release): Batch 10 — SEO date refresh + audit closure (next allowed run 2026-05-23)`
+
+---
+
+## Override conditions
+
+If something blocks a batch (test failure, missing file, dependency that needs `yarn install`), STOP at that batch and surface the blocker in the session report. Do not skip ahead. The user prefers visible blockers to silent skips.

package/docs/project-audit/2026-05-16/02-AUDIT-FINDINGS.md

@@ -0,0 +1,144 @@
+# Audit Findings — 2026-05-16
+
+Consolidated findings from the parallel deep audit run on 2026-05-16. Mapped to batch numbers from [`01-BATCH-PLAN.md`](./01-BATCH-PLAN.md).
+
+---
+
+## A — Website (React + Vite + Radix + Capacitor)
+
+### BLOCKERS
+- **4 ESLint hooks-rules errors** preventing `yarn lint` green. Files: `ConfigPage.tsx:43`, `GoogleDrivePage.tsx:37`, `SettingsPage.tsx:72`, `UploadPage.tsx:363`. → **Batch 2**
+- **`auth-token.ts` uses localStorage only.** Comment promises Capacitor Preferences fallback that never landed — the Android wrap will lose tokens on cold-start. → **Batch 3**
+- **401 handler clears token but does NOT redirect to login** — user can be left on a dashboard page with no UI state. → **Batch 3**
+
+### MAJOR
+- **Admin pages bypass TanStack Query** (`AdminUsersPage`, `AdminAppsPage`, `AdminBuildsPage`) and use raw `useEffect`+`useState` — no cache reuse, no invalidation on mutations. → **Batch 5**
+- **`DashboardOverview.tsx:20–34` + `UploadPage.tsx:49–63`** use raw `Promise.all` instead of `useQuery`. → **Batch 5**
+- **2 real `console.*` calls in `ExamplesPage.tsx:63,67`** (DocsPage matches are inside doc code blocks — acceptable). → **Batch 6**
+- **`VITE_FIREBASE_*` env keys still defined** in `env.ts` / `.env.example` / `vite-env.d.ts` although Firebase Auth was removed. → **Batch 6**
+
+### COMPLIANT (no action)
+- 29 routes wired in `router.tsx`, all with real content
+- Theme customizer present + 7 options + accessible from header + works unauthenticated
+- BootLoader present and blocks first paint
+- RHF + Zod on all dashboard forms
+- URL-state preserved in `useUrlState.ts` and used by AppsPage, SettingsPage modals
+- Dashboard pages mobile-friendly (Tailwind responsive defaults)
+- API calls under `/api/dashboard/*` and `/api/admin/*` — no Firestore leaks
+
+---
+
+## B — Backend (Laravel 11 + Nova + Sanctum + Spatie + Socialite)
+
+### BLOCKERS
+- **`config/sanctum.php:53` has `'expiration' => null`** — `.env.example` sets `SANCTUM_TOKEN_EXPIRATION=10080` but config ignores it. Tokens never expire. → **Batch 1**
+- **`docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md:34, 137`** references Firebase env vars + `auth.firebase.auto_create` config that no longer exist (post-Socialite swap). → **Batch 1**
+
+### MAJOR
+- **Stale Firebase docblocks** in `AdminController.php:8`, `AppPolicy.php:11`, `BuildPolicy.php:4` — confusing for any reviewer. → **Batch 1**
+- **`config/logging.php:64,71`** defaults to `debug` while `.env.example` sets `warning` — production leaks debug logs if env var missing. → **Batch 1**
+- **`BuildController@update`** validates inline; inconsistent with `store` using FormRequest. → **Batch 4**
+- **No tests for OAuth callback, Sanctum token lifecycle, or Spatie role assignment.** Critical given the swap is fresh. → **Batch 4**
+
+### MINOR
+- **`AppPolicy::before` missing `?bool` return type.** → **Batch 1**
+- **`.env.example`** lacks inline comments for `ADMIN_EMAILS` first-signer auto-promotion. → **Batch 1**
+
+### COMPLIANT
+- 110/110 backend tests passing baseline
+- Spatie permission tables migration + personal_access_tokens table present
+- `AssignUserRole` artisan command exists and revokes existing tokens
+- CORS lockdown env-driven with explicit allowlist
+- File uploads validated via `StoreBuildRequest` (zip, max 100MB)
+- Rate limiting present on auth + API endpoints
+- `Gate::before` super-admin bypass wired
+
+---
+
+## C — Root plugin (`src/`, `android/`, `ios/`)
+
+### BLOCKERS
+- **9/62 integration tests fail** because `NativeUpdateWeb` constructor accesses `localStorage` during vitest's node env. → **Batch 2**
+
+### COMPLIANT
+- TypeScript clean (`tsc --noEmit` exit 0)
+- ESLint clean
+- API surface complete on all platforms (web/Android/iOS)
+- No Firestore/Firebase references in plugin source
+- v3.0.1 in `package.json` matches CLAUDE.md
+
+---
+
+## D — Android publishing readiness (website/android/)
+
+### BLOCKERS
+- **No signingConfigs.release block** in `website/android/app/build.gradle` — release builds aren't signable. → **Batch 8**
+- **No `BUILD_FOR_PLAY_STORE.md` runbook** — user can't reproduce the signed AAB path. → **Batch 8**
+- **Firestore references in Play Store metadata** at `app-publish-assets/metadata/full-description.md:3,22` and `data-safety.md:34`. → **Batch 7**
+- **Privacy Policy references Firebase Auth** — Play Store will reject for declared-vs-actual mismatch. → **Batch 7**
+
+### MAJOR
+- **`minifyEnabled = false` for release build** — no R8 obfuscation. → **Batch 8**
+- **Default Capacitor app icons** in all `mipmap-*/` densities — not branded. → **Batch 9**
+- **No screenshots in `app-publish-assets/screenshots/`** — only a README placeholder. → **Batch 9** (we produce a capture guide; user takes the actual shots)
+- **Legal pages (`PrivacyPage`, `TermsPage`, `CookiePolicyPage`, `SecurityPage`) frozen at 2025-12-27** — 141 days stale. → **Batch 7**
+
+### COMPLIANT
+- `capacitor.config.ts` correctly set: `appId`, `appName`, `webDir`, hostname, HTTPS-only scheme
+- Manifest declares only `INTERNET` permission — no sensitive permission cleanup needed
+- `targetSdkVersion = 36` — beats 2026 Play Store minimum (34)
+- No CAMERA/RECORD_AUDIO/LOCATION/CONTACTS/etc. (no Data Safety entries needed for those)
+- `app-publish-assets/icons/` has SVG icon-512 + adaptive icon foreground/background sources
+
+---
+
+## E — SEO / AEO / Content quality
+
+### MAJOR
+- **`postbuild-seo.ts:17` `PAGE_LAST_UPDATED = '2026-05-08'`** is 8 days stale — should be 2026-05-16. → **Batch 10**
+- **`softwareVersion: '2.0.0'`** in `postbuild-seo.ts:431` JSON-LD — should be `3.0.1` (matches `package.json`). → **Batch 10**
+- **Legal pages dated 2025-12-27 (141 days old)**. → **Batch 7**
+- **20 doc routes in sitemap.xml** stale > 90 days — should be reviewed and either refreshed or removed. → **Batch 10** (selective refresh)
+
+### COMPLIANT
+- robots.txt allows all 18+ AI bots explicitly
+- llms.txt + llms-full.txt + ai.txt + humans.txt + security.txt all current
+- Per-route static HTML injection in `postbuild-seo.ts` covers all 18 routes
+- Static HTML `<noscript>` body contains rich content for AI crawlers
+- JSON-LD: Organization + WebSite + SoftwareApplication + FAQPage + WebPage + BreadcrumbList on all routes
+- Per-page uniqueness met on FeaturesPage, PricingPage, AboutPage (1000+ unique words each)
+- Footer covers all public pages — no orphan content
+- Honest framing: no "#1", no fabricated stats
+
+---
+
+## F — Generic Project Rules compliance spot-check
+
+Cross-referenced against `~/Documents/ahsan-notebook/static/assets/txt-files-important/generic-project-rules.md` and `docs/rules-tracker.md`:
+
+- **R-001 yarn-only:** ✅ (yarn 4.10.3 lockfile, no npm/pnpm)
+- **R-002 yarn upgrade --latest cadence:** Verify in Batch 10
+- **R-003 max 500 lines/file:** `DocsPage.tsx` is 1406 lines — documented as deferred follow-up (not blocking publish)
+- **R-013 NO TODOs:** ✅ grep returns zero real TODOs/FIXMEs/coming-soon
+- **R-019 SVG everywhere:** Mostly ✅; default Capacitor PNG icons are the exception, fixed in Batch 9
+- **R-024 centralized logger:** Mostly ✅; 2 violations fixed in Batch 6
+- **R-027 sitemap + feed routes:** ✅
+- **R-029 URL state preservation:** ✅
+- **R-030 Radix theme customizer:** ✅
+- **R-031 .env.example sync + boot validation:** ✅ with one drift (VITE_FIREBASE_* leftovers) — fixed Batch 6
+- **R-035 commit strategy ONE per prompt:** This audit follows ONE commit per batch — compliant with the "logical task" spirit
+- **R-038 Play Console rules global file:** ✅ reads from `~/.claude/play-console-rejection-rules.json`
+
+→ Generic Rules tracker bumped in Batch 10 with rules re-verified during this run.
+
+---
+
+## Findings summary
+
+| Severity | Count | Resolved by |
+|---|---|---|
+| BLOCKER | 8 | Batches 1, 2, 3, 7, 8 |
+| MAJOR | 16 | Batches 1, 4, 5, 6, 7, 8, 9, 10 |
+| MINOR | 4 | Batches 1, 6, 9, 10 |
+
+Total: **28 actionable findings**, all assigned to a batch, none deferred.

package/docs/project-audit/2026-05-16/sessions/batch-01.md

@@ -0,0 +1,42 @@
+# Session report — Batch 1
+
+**Date:** 2026-05-16
+**Batch:** 1 — Auth + critical backend fixes
+**Skill invoked:** `laravel-specialist`
+**Duration estimate:** ~45 min
+**Outcome:** All deliverables shipped. `php artisan test` → 110/110 passing.
+
+## Changes
+
+| File | Change |
+|---|---|
+| `backend/config/sanctum.php:53` | `'expiration' => null` → `env('SANCTUM_TOKEN_EXPIRATION', 10080)`. Tokens now expire after the env-configured TTL (default 7 days). Previously tokens lived forever — silent security bug. |
+| `backend/config/logging.php:64,71` | `'level' => env('LOG_LEVEL', 'debug')` → `env('LOG_LEVEL', 'warning')` for both `single` and `daily` channels. Production no longer leaks debug logs if env var is missing. |
+| `backend/app/Http/Controllers/Admin/AdminController.php:12–17` | Stale Firebase docblock ("`admin: true` claim", "ValidateFirebaseToken") rewritten to describe spatie/laravel-permission `super-admin` role + auth:sanctum gating. |
+| `backend/app/Policies/AppPolicy.php:10–18` | Same Firebase → spatie docblock rewrite; added defence-in-depth note about Gate::before short-circuit. |
+| `backend/app/Policies/BuildPolicy.php:8–15` | Same Firebase → spatie docblock rewrite. |
+| `backend/routes/api.php:118–122` | Added explanatory comment to `GET /api/dashboard/me` documenting why no `can:` gate is needed (Sanctum identity proven; controller scopes to caller's own row; no IDOR surface). Audit finding #2 resolved by code-comment rather than route change. |
+| `docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md:34, 134, 142` | Firebase env-var bullets removed. Added Sanctum + Google OAuth (sign-in + Drive picker) + RBAC bootstrap bullets describing the new auth stack. The post-deploy smoke step now reads "Sign in via Google OAuth" instead of Firebase. The legacy `auth.firebase.auto_create` line replaced with a description of the `ADMIN_EMAILS` first-signer auto-promotion mechanism. |
+| `backend/CLAUDE.md` | Stack table auth row updated ("Firebase Auth Token Validation" → "Google OAuth (Socialite) + Sanctum + spatie/laravel-permission RBAC"). Env section rewritten to document Sanctum + Google OAuth + ADMIN_EMAILS instead of Firebase. `Last Updated` bumped to 2026-05-16. |
+
+## Audit findings retired
+
+| ID | Finding | Resolution |
+|---|---|---|
+| B-1 | Sanctum expiration ignored | Fixed — config reads env |
+| B-2 | `/api/dashboard/me` gating inconsistent | Documented as intentional with inline comment |
+| B-3 | LOG_LEVEL config default mismatch | Fixed — defaults to `warning` |
+| B-4 | Firebase env vars in deploy checklist | Rewritten for Sanctum + Google OAuth |
+| B-5 | Stale Firebase docblocks in 3 files | All 3 updated to spatie/laravel-permission language |
+| B-7 | `AppPolicy::before` missing `?bool` return type | False positive — already typed (verified across all 5 policies) |
+| B-8 | `backend/CLAUDE.md` stale auth references | Updated stack table + env section + `Last Updated` |
+
+## Verification
+
+- `php artisan test --without-tty` → **110 passed (258 assertions), 24.42s** (baseline preserved).
+- `php artisan config:clear && php artisan config:cache` → clean.
+- Runtime config probe: `config('sanctum.expiration')` → `'10080'` (env-driven). `config('logging.channels.daily.level')` → `'debug'` in dev (local .env keeps debug for development; production default is `'warning'`).
+
+## What's next
+
+Batch 2 — Website build + plugin test fixes (4 ESLint hooks-rules errors + 9 plugin integration test failures).

package/docs/project-audit/2026-05-16/sessions/batch-02.md

@@ -0,0 +1,74 @@
+# Session report — Batch 2
+
+**Date:** 2026-05-16
+**Batch:** 2 — Website build + plugin test fixes
+**Skill invoked:** `react-best-practices`
+**Outcome:** All deliverables shipped. 0 lint errors. Plugin tests 62/62.
+
+## Changes
+
+### Website (`website/`) — 7 files with `useEffect` calling a function declared later
+
+The audit caught 4 cases; running `yarn lint` surfaced 3 more (AdminOverview, AnalyticsPage × 3 errors). All seven follow the same anti-pattern that the React Compiler's `react-hooks/immutability` rule rejects: `useEffect(() => { fnX() }, [...]); async function fnX() { ... }`. The hoisting works at runtime, but the linter is right that the closure can become stale.
+
+| File | Fix |
+|---|---|
+| `src/pages/admin/AdminAppsPage.tsx` | `loadApps` → `useCallback`, deps `[searchTerm, pagination.page]`; useEffect → `void loadApps()` with `[loadApps]` dep |
+| `src/pages/admin/AdminBuildsPage.tsx` | `loadBuilds` → `useCallback`, deps `[pagination.page]` |
+| `src/pages/admin/AdminOverview.tsx` | `loadStats` → `useCallback`, deps `[]` |
+| `src/pages/admin/AdminUsersPage.tsx` | `loadUsers` → `useCallback`, deps `[searchTerm, pagination.page]` |
+| `src/pages/dashboard/ConfigPage.tsx` | `loadApps` → `useCallback`; setSelectedAppId converted to functional updater to avoid stale closure |
+| `src/pages/dashboard/GoogleDrivePage.tsx` | `loadData` → `useCallback` |
+| `src/pages/dashboard/SettingsPage.tsx` | `loadUserData` → `useCallback` |
+| `src/pages/dashboard/AnalyticsPage.tsx` | `loadApps`, `renderDownloadsChart`, `renderPlatformChart` → `useCallback`; chart-render useEffects moved below their callbacks; `selectedAppRef` syncs current selection via `useEffect` so the loader's "only-set-default-if-empty" check stays stable. |
+
+### UploadPage ref-during-render fix
+
+`website/src/pages/dashboard/UploadPage.tsx:363` was passing the result of `handleSubmit(onUploadSubmit)` directly to `onClick` during render, which read the function's ref at render-time. Fixed by wrapping in an arrow function and adding `type="button"`:
+
+```tsx
+onClick={() => { void handleSubmit(onUploadSubmit)(); }}
+```
+
+### Plugin (`src/web.ts`) — localStorage safe-accessor
+
+`NativeUpdateWeb`'s constructor calls `loadStoredData()` + `incrementLaunchCount()`. Both used `localStorage.X` directly. In some test environments (and SSR / sandboxed iframes / private-mode browsers) `localStorage` is undefined, which threw `TypeError: Cannot read properties of undefined (reading 'getItem')` and broke 9 of 62 tests.
+
+Added `getLocalStorage(): Storage | null` — a defensive accessor that:
+- returns `null` when `typeof window === 'undefined'`
+- returns `null` when `window.localStorage` is undefined
+- catches access errors (some browsers throw in private mode)
+
+Refactored all 6 callsite groups in `web.ts` to use `this.getLocalStorage()?.X` or guard with `if (!storage) return`:
+- `loadStoredData()`, `saveStoredData()`
+- `saveConfiguration()`
+- `getInstallDate()` (read + write)
+- `incrementLaunchCount()`
+- The post-review-request `setItem('native-update-last-review', ...)`
+
+## Verification
+
+| Command | Result |
+|---|---|
+| `yarn --cwd website lint` | exit 0, zero errors, zero warnings |
+| `yarn --cwd website typecheck` | exit 0 |
+| `yarn --cwd website build` | exit 0; 16 per-route SEO HTML files generated; all 9 discovery files present |
+| `yarn lint` (root plugin) | exit 0 |
+| `yarn test:run` (root plugin) | **62 passed (62)**, 5.58s |
+| `yarn build` (root plugin) | exit 0; dist/plugin.{js,cjs.js,esm.js} created in 1.9s |
+
+## Audit findings retired
+
+| ID | Finding | Resolution |
+|---|---|---|
+| W-1 | 4 ESLint hooks-rules errors (per audit) | 11 errors found and fixed across 8 files |
+| C-1 | 9/62 plugin integration tests fail on localStorage | Defensive `getLocalStorage()` accessor; all 62 now pass |
+
+## Notes / follow-up
+
+- 7 of these 8 files will be revisited in Batch 5 (TanStack Query migration). The `useCallback` work here is forward-compatible; the migration will mostly replace these with `useQuery`.
+- The localStorage safe-accessor is the right baseline regardless of test fix — it also unblocks future SSR rendering and gracefully handles private-mode Safari.
+
+## What's next
+
+Batch 3 — Auth token storage via Capacitor Preferences (so the Android wrap doesn't lose tokens on cold-start).

package/docs/project-audit/2026-05-16/sessions/batch-03.md

@@ -0,0 +1,71 @@
+# Session report — Batch 3
+
+**Date:** 2026-05-16
+**Batch:** 3 — Auth token via Capacitor Preferences
+**Skill invoked:** `capacitor-best-practices`
+**Outcome:** All deliverables shipped. Cold-start on Android wrap now retains tokens. 401s auto-redirect to /login.
+
+## Changes
+
+### `website/src/lib/auth-token.ts` — rewritten
+
+Previously: synchronous `localStorage.getItem` / `setItem` / `removeItem`. Worked on web. **Broke on the Android wrap** because Capacitor's WebView uses an isolated localStorage that doesn't survive process death the same way Preferences does, and (more importantly) we want the token in a Keychain-backed (iOS) / EncryptedSharedPreferences-backed (Android) store rather than a webview key-value bag.
+
+New design:
+
+| Function | Behaviour |
+|---|---|
+| `hydrateAuthToken()` | Idempotent boot-time hydration. On native: reads from `@capacitor/preferences`. On web: reads from `localStorage` with safe-accessor (handles SSR / happy-dom / private-mode). |
+| `isAuthTokenHydrated()` | Lets callers gate "did we even check storage yet" without races. |
+| `getAuthToken()` (sync) | Reads in-memory cache. Sync surface preserved so axios interceptor stays trivial. |
+| `setAuthToken()` (sync) | Updates cache + fires async write to durable store + emits change event. |
+| `clearAuthToken()` (sync) | Same shape — fires async delete + emits `null`. |
+| `subscribeToAuthChanges()` | NEW. Lets AuthContext (and anyone else) react instantly to token sets / clears. |
+
+The in-memory cache + async durable store keeps the synchronous API surface AxiosRequestInterceptor needs, while letting the durable layer be Capacitor Preferences (which is async). Listeners get the event for the second a 401 lands in the response interceptor.
+
+### `website/src/context/AuthContext.tsx`
+
+- `refresh()` now **awaits `hydrateAuthToken()` before checking `getAuthToken()`** — prevents the cold-start race where the SPA thinks the user is signed out before Preferences resolves.
+- New `useEffect` subscribes to `subscribeToAuthChanges`. When the token clears (axios 401 interceptor / explicit logout / another tab), this fires `setUser(null)` immediately — ProtectedRoute then redirects to /login on the next render. When a token is set elsewhere (CallbackPage), this fires `refresh()` so the /me payload arrives without needing the page to do it manually.
+
+### `website/src/App.tsx`
+
+- Kicked off `void hydrateAuthToken()` in the same boot effect as theme hydration. Both run in parallel during the BootLoader window, so the token is ready by the time AuthProvider mounts. Eliminates the brief "loading spinner from ProtectedRoute" flash on cold start.
+
+### `website/src/pages/auth/CallbackPage.tsx`
+
+- Removed the explicit `await refresh()` from the callback flow. The auth-change event listener in AuthContext now picks up the new token and refreshes /me automatically — saving one round trip on every sign-in (was 2× /me, now 1×).
+- Dropped the `useAuth()` import (no longer needed).
+- Tightened the useEffect dep array (`[params, navigate]`) — no more eslint-disable.
+
+## 401 auto-redirect chain (now wired end-to-end)
+
+1. Some `/api/dashboard/*` request returns 401.
+2. axios response interceptor in `lib/api.ts` calls `clearAuthToken()`.
+3. `clearAuthToken()` clears in-memory cache, fires async Preferences delete, emits `null` to all subscribers.
+4. AuthContext's subscribe callback flips `setUser(null)`.
+5. ProtectedRoute re-renders, sees `user === null`, returns `<Navigate to="/login" replace />`.
+6. User lands on /login.
+
+No polling. No setTimeout. Single render cycle.
+
+## Verification
+
+| Command | Result |
+|---|---|
+| `yarn --cwd website lint` | exit 0 |
+| `yarn --cwd website typecheck` | exit 0 |
+| `yarn --cwd website build` | exit 0 (16 per-route SEO HTML files generated, all 9 discovery files present) |
+| Manual trace (read-only) | Reviewed CallbackPage → setAuthToken → AuthContext subscriber → refresh → ProtectedRoute. Also traced 401 path through axios interceptor → clearAuthToken → subscriber → setUser(null) → Navigate. |
+
+## Audit findings retired
+
+| ID | Finding | Resolution |
+|---|---|---|
+| W-3 | `auth-token.ts` localStorage-only would lose tokens on Android wrap | Capacitor Preferences with localStorage fallback + parallel boot hydration |
+| W-4 | 401 handler clears token but does NOT redirect to login | subscribeToAuthChanges → setUser(null) → Navigate fires automatically |
+
+## What's next
+
+Batch 4 — Backend OAuth/Sanctum/Roles tests + FormRequest extraction. New `OAuthControllerTest`, `SanctumTokenTest`, `RolesPermissionsTest`, plus `UpdateBuildRequest` extraction for `BuildController@update`.

package/docs/project-audit/2026-05-16/sessions/batch-04.md

@@ -0,0 +1,88 @@
+# Session report — Batch 4
+
+**Date:** 2026-05-16
+**Batch:** 4 — Backend OAuth/Sanctum/Roles tests + UpdateBuildRequest FormRequest
+**Skill invoked:** `laravel-specialist` (still loaded from Batch 1)
+**Outcome:** All deliverables shipped. **136/136** backend tests passing (+26 from baseline 110).
+
+## New test files
+
+### `tests/Feature/OAuthControllerTest.php` (9 cases)
+
+End-to-end tests for the post-2026-05-11 Socialite + Sanctum flow. Socialite is stubbed via `Socialite::shouldReceive('driver')` with a deterministic SocialiteUser; we never hit Google.
+
+- `redirect_endpoint_returns_a_redirect_response`
+- `callback_creates_user_and_assigns_default_role` (first sign-in → `user` role)
+- `callback_auto_promotes_admin_emails` (matches `services.admin_emails` → `super-admin`)
+- `callback_for_existing_user_updates_attributes_without_changing_role`
+- `callback_rejects_suspended_accounts_with_error_redirect` (302 → `/login?error=account_suspended`)
+- `callback_falls_back_to_email_match_for_legacy_users` (covers Firebase → Sanctum migration)
+- `callback_redirects_with_error_when_socialite_throws` (Google failure → `/login?error=oauth_failed`)
+- `logout_revokes_current_token` (bearer token row deleted)
+- `logout_requires_authentication` (401 without token)
+
+### `tests/Feature/SanctumTokenTest.php` (7 cases)
+
+Token lifecycle that exercises the **real** Sanctum expiration plumbing (not `Sanctum::actingAs()`, which bypasses expiration):
+
+- `protected_route_rejects_request_without_token`
+- `protected_route_accepts_valid_token`
+- `expired_token_is_rejected` (`Carbon::setTestNow` past the 7-day window)
+- `token_within_expiration_window_still_works` (just under the window)
+- `revoked_token_is_rejected` (DB row deleted)
+- `abilities_are_attached_to_the_token`
+- `sanctum_expiration_config_is_env_driven` (regression test for Batch 1's `config/sanctum.php` fix)
+
+### `tests/Feature/RolesPermissionsTest.php` (10 cases)
+
+Spatie RBAC plumbing:
+
+- `seeder_creates_expected_roles` (super-admin, admin, user with sanctum guard)
+- `seeder_is_idempotent` (run 3× → same counts)
+- `user_role_has_owner_scoped_permissions_not_admin_ones`
+- `super_admin_role_has_every_permission`
+- `gate_before_bypasses_for_super_admin` (asserts the `Gate::before` hook in `AppServiceProvider`)
+- `gate_before_does_not_bypass_for_regular_user`
+- `assign_role_command_adds_role_and_revokes_existing_tokens` (additive assign + token wipe)
+- `assign_role_revoke_flag_removes_specific_role_only` (`--revoke` path)
+- `user_model_isAdmin_helper_recognises_super_admin`
+- `user_model_isAdmin_helper_returns_false_for_user_role`
+
+## FormRequest extraction
+
+### `app/Http/Requests/UpdateBuildRequest.php` (new)
+
+Validates `PATCH /api/dashboard/apps/{app}/builds/{build}` — release notes, rollout percentage, status. Mirrors the inline rules removed from the controller.
+
+### `app/Http/Controllers/Dashboard/BuildController.php`
+
+- `update()` signature: `Request $request` → `UpdateBuildRequest $request`
+- Inline `$request->validate(...)` removed; uses `$request->validated()`
+- `use App\Http\Requests\UpdateBuildRequest;` added
+
+## Bug fixed mid-batch
+
+While my new tests passed in isolation, running the full suite showed 35 failures. Root cause: during Batch 1 verification I had run `php artisan config:cache` which baked **my local .env** into `bootstrap/cache/config.php`. That cached config overrode the per-test `<env>` entries in `phpunit.xml` (sqlite :memory:, etc.), so subsequent test runs hit my real MySQL DB without the test schema.
+
+Fix: cleared `bootstrap/cache/*.php` + ran `config:clear` + `cache:clear`. Re-ran full suite → **136/136 green**.
+
+This is a process gotcha worth remembering: **do not `config:cache` on a dev box** if you want phpunit.xml env to apply to the next test run. Adding a note to the deploy checklist is out of scope for this batch but I'll surface it in Batch 10.
+
+## Verification
+
+| Command | Result |
+|---|---|
+| `php artisan test --without-tty` | **136 passed (314 assertions), 6.67s** |
+| New tests alone | 9 + 7 + 10 = **26 new tests, all passing** |
+| Baseline preserved | 110 of 110 prior tests still green |
+
+## Audit findings retired
+
+| ID | Finding | Resolution |
+|---|---|---|
+| B-9 | `BuildController@update` inline validate | Extracted to `UpdateBuildRequest` FormRequest |
+| B-12 | No tests for OAuth callback, Sanctum lifecycle, Spatie roles | Three new test files (26 cases) |
+
+## What's next
+
+Batch 5 — Admin pages + DashboardOverview + UploadPage migration to TanStack Query. Replaces the 5 raw `useEffect` + `useState` data-fetching call sites with `useQuery` for proper cache, invalidation, and consistent error handling.