native-update 2.0.0 → 3.1.0

package/docs/project-audit/BATCH-PLAN.md

@@ -0,0 +1,168 @@
+# Production-Readiness Batch Plan
+
+**Created:** 2026-05-08
+**Source audit:** `docs/project-audit/PRODUCTION-READINESS-AUDIT-2026-05-08.md`
+**Tracker:** `docs/tracking/production-readiness-audit-tracker.json`
+
+## Batching philosophy
+
+Each batch groups items that:
+1. Share a domain (so context loads once, not many times)
+2. Can be verified together with one build/test/lint pass
+3. Aren't too small (wastes overhead) and aren't too large (risks context exhaustion / partial-batch state)
+
+Each batch ends with: `yarn lint` + `yarn typecheck` + `yarn build` + `yarn test:run` clean (plus `php artisan test` for backend batches), then ONE commit per batch (per project rule), then tracker update.
+
+---
+
+## Batch 1 — npm-publish + immediate-ship blockers (THIS SESSION)
+
+**Goal:** every fix here unblocks shipping v3.0.x.
+
+| ID | Severity | Fix |
+|---|---|---|
+| B1 | Blocker | Add `"android/manifest-additions.xml"` to `package.json` `files` array |
+| B3 | Blocker | `cli/commands/monitor.js`: capture interval ID, install SIGINT/SIGTERM handlers, `clearInterval` + `spinner.stop()` on exit, bail on N consecutive failures |
+| B7 | Blocker | Decide example-apps lockfile strategy: declare workspaces in root `package.json` OR document standalone `cd example-apps/react-capacitor && yarn install` flow |
+| B8 | Blocker | Strip `firebase-backend` references from `example-apps/react-capacitor/README.md` (lines 14, 101, 210); replace with `node-express` only |
+| N1 | Nit (free with ✏️) | `rollup.config.js`: remove duplicate `comments` key |
+
+**Verification:** `yarn lint && yarn build && yarn test:run` from root + `cd example-apps/react-capacitor && yarn install` succeeds.
+**Commit message:** `fix(release): unblock v3.0.x publish — manifest-additions in files, monitor cleanup, example lockfile, README v3 cleanup`
+
+---
+
+## Batch 2 — Backend security hardening (high-value, single domain)
+
+| ID | Severity | Fix |
+|---|---|---|
+| B4 | Blocker | Add Nova policies (`canViewAny`/`canCreate`/`canUpdate`/`canDelete`) for User, App, Build, ApiKey, SigningKey resources; register in `AuthServiceProvider` |
+| I12 | Important | Wrap Nova User admin panels (Suspend, License, Custom Limits) with `canSee(fn ($req) => $req->user()->isAdmin())` |
+| I13 / H1 | Important / Sec-High | Publish `config/cors.php`; lock `paths` to `['api/*']`, `allowed_origins` to explicit list (`nativeupdate.aoneahsan.com` + `localhost:5942`/`5944`/`5946`) |
+| I15 | Important | Confirm + test PayPal webhook is CSRF-exempt; add Feature test that POST to webhook with valid signature succeeds |
+
+**Verification:** `cd backend && php artisan test && composer dump-autoload`.
+**Commit message:** `fix(backend): Nova authorization gates, CORS lockdown, PayPal webhook test`
+
+---
+
+## Batch 3 — Backend bundle/license tests + FormRequests + deploy runbook
+
+| ID | Severity | Fix |
+|---|---|---|
+| B5 | Blocker | Feature test for bundle upload + signature verify + monotonic version + duplicate detection + chunk merge (`tests/Feature/Build/BundleUploadTest.php`) |
+| I14 | Important | Feature test for `User::hasValidLicense()` and a paid-tier-gated endpoint |
+| I11 | Important | Extract inline validators to `app/Http/Requests/*Request.php`; use `$this->authorize()` |
+| I10 | Important | Add config flag `auth.firebase.auto_create` (default `true` to preserve current behavior); document in deploy runbook |
+| B6 | Blocker | Create `docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md`: APP_DEBUG=false, LOG_LEVEL=warning, APP_ENV=production, key:generate, config:cache, migrate --force, queue daemon, composer install --no-dev |
+| N4 / N5 | Nit | Add comments in `backend/.env.example` recommending Redis for cache + queue daemon for prod |
+
+**Verification:** `cd backend && php artisan test`.
+**Commit message:** `feat(backend): bundle/license tests, FormRequests, production deploy runbook`
+
+---
+
+## Batch 4 — Centralized logger + plugin polish
+
+| ID | Severity | Fix |
+|---|---|---|
+| I1 | Important | Replace 18 `console.*` in `src/web.ts` with `Logger.{warn,error}`; replace `console.error` in `src/core/event-emitter.ts:52`. Verify via `grep -rEn "\bconsole\." src --include="*.ts" \| grep -v "src/utils/logger"` returns zero |
+| I2 | Important | Add `// CAPACITOR-SDK-WORKAROUND:` comment block in `ios/Plugin/NativeUpdatePlugin.swift:72-75` referencing Capacitor 8.x |
+| I3 | Important | Reconcile `cli/templates/express/` against `example-apps/node-express/` so the scaffold ships working code |
+| B2 | Blocker | For each TODO in `cli/commands/backend-create.js` (8 sites), either implement or prepend generated file with `// SCAFFOLD — implement before deploying` banner + doc reference |
+
+**Verification:** `yarn lint && yarn build && yarn test:run`.
+**Commit message:** `refactor(plugin): centralized logger in web.ts/event-emitter, CLI scaffold parity, iOS workaround docs`
+
+---
+
+## Batch 5 — SEO/AEO content enrichment (3 marketing pages + pricing.md + feed fix)
+
+This is the largest batch. Treat as multi-page content batch per global playbook §13.
+
+| ID | Severity | Fix |
+|---|---|---|
+| I7 | Important | Rewrite `FeaturesPage.tsx`, `AboutPage.tsx`, `PricingPage.tsx` to ≥1000 unique words each: definition-first intro (80-120 words), 3-5 use cases (50-80 words), 4-6 HowTo steps (30-40 words), 2-3 examples, 5-8 FAQ, 3-6 tips, author + lastUpdated. Wire into `postbuild-seo.ts` so the static HTML carries the same body. Use `ai-seo` + `copywriting` skills. |
+| I8 | Important | Create `website/public/pricing.md` machine-readable file: tiers, limits, FAQ, in plain markdown. Linked from llms.txt. |
+| I9 | Important | Fix `website/scripts/generate-sitemap.mjs` so feed `<lastBuildDate>` and sitemap `<lastmod>` use `new Date().toUTCString()` / `new Date().toISOString()` at build time. |
+
+**Verification:** `cd website && yarn build` (postbuild-seo step verifies prerendered HTML); manually open three prerendered HTML pages in `dist/` and confirm `<noscript>` body has the rich content.
+**Commit message:** `feat(seo): per-page rich SEO content for Features/About/Pricing + pricing.md + feed-date fix`
+
+---
+
+## Batch 6 — Website UI/UX polish (a11y dialog + URL state)
+
+| ID | Severity | Fix |
+|---|---|---|
+| I4 | Important | Migrate `website/src/components/ui/Dialog.tsx` to `@radix-ui/react-dialog`. Update all import sites. |
+| I5 | Important | Convert `AppsPage.tsx:50,55` and any other dashboard `useState` modal/form state to URL search params (`?deleteId=ID`, `?formMode=create\|edit&appId=ID`). Use the project's `useUrlState` hook family. Sweep all dashboard pages. |
+| I6 | Important | Audit per-page TanStack Query `staleTime`/`gcTime` overrides; document the cache contract in a code comment in `App.tsx`. |
+
+**Verification:** `cd website && yarn typecheck && yarn build`; manual: open `/dashboard/apps?deleteId=test` in incognito, confirm dialog opens; reload, confirm dialog still open; close, confirm URL param drops.
+**Commit message:** `refactor(website): Radix Dialog migration, URL state for dashboard modals, query cache audit`
+
+---
+
+## Batch 7 — env-sync + security preventive docs
+
+| ID | Severity | Fix |
+|---|---|---|
+| M1 | Sec-Med | Add one-line "where to get this" note next to each individual PayPal/Google sub-var in `backend/.env.example` |
+| M2 | Sec-Med | Add `VITE_NATIVE_UPDATE_PUBLIC_BACKEND_URL`, `VITE_NATIVE_UPDATE_API_KEY`, `VITE_NATIVE_UPDATE_PUBLIC_KEY` rows (as `[OPTIONAL]`) to `website/.env.example` |
+| H2 | Sec-High preventive | Create `docs/SECURITY-IF-REPO-PUBLIC.md` runbook: rotate every committed secret, add patterns to .gitignore, audit history with git-filter-repo |
+
+**Verification:** none beyond docs-only changes; quick grep confirms env-example coverage.
+**Commit message:** `docs(security): env-example sync + repo-public runbook`
+
+---
+
+## Batch 8 — Roadmap features for v3.x release
+
+| ID | Severity | Fix |
+|---|---|---|
+| R3 | Roadmap | Create `.github/workflows/release.yml`: on tag, run `yarn build:prod`, `yarn test:run`, then `npm publish --provenance` |
+| R3 | Roadmap | Create `.github/workflows/example-bundle.yml`: scheduled+manual; create signed bundle from `example-apps/react-capacitor`, attach to release |
+| R4 / I16 | Important | Expand `example-apps/react-capacitor/src/App.tsx` to demo: download/apply update, app-update check, app-review prompt, background-update toggle, signature verify. One section per method. |
+| I17 | Important | React 18 vs 19 decision: bump to 19 + verify build (recommended) OR add explicit "stable downstream target" note in README. |
+| R1 | Roadmap | Performance-benchmarking scaffold: `tools/bench/` with Vitest-based microbench for bundle-verify + signature-verify hot paths. Doc in `docs/PERFORMANCE.md`. |
+| R2 | Roadmap | `docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md`: dep audit, manual auth/CSRF/CORS check, signature-verify fuzz, license-bypass attempts. |
+
+**Verification:** `cd example-apps/react-capacitor && yarn build && yarn lint`; root `yarn test:run`; CI workflows: `actionlint .github/workflows/*.yml` if available.
+**Commit message:** `feat(release): GitHub Actions release workflow, example-app coverage, perf bench scaffold, pentest checklist`
+
+---
+
+## Batch 9 — Marketing-website tracker (rendered-on-live-pages items)
+
+| ID | Severity | Fix |
+|---|---|---|
+| R5 | Roadmap | Sweep `docs/MARKETING_WEBSITE_TRACKER.md` for `[ ]` items that ARE actually rendered as gaps on live pages (not "future feature ideas"). Convert each to a small per-page issue. Examples to look for: missing screenshots in `Screenshots`/`Demo` section, stale code-snippet copy in `DocsPage`, dashboard onboarding flow polish, footer links to non-existent routes. |
+
+**Verification:** depends on what surfaces.
+**Commit message:** `chore(website): close out marketing-tracker rendered-page gaps`
+
+---
+
+## Batch 10 — Final consolidated pass + version bump + portfolio refresh
+
+| ID | Fix |
+|---|---|
+| — | Bump root `package.json` version (3.0.0 → 3.0.1 if all batches done; 3.1.0 if any roadmap features added) per project version-cascade rule |
+| — | Update `docs/CHANGELOG.md` + `website` changelog page + portfolio info file (weekly cadence anyway) |
+| — | Final `yarn lint && yarn typecheck && yarn build && yarn test:run` from root, `cd website && yarn build`, `cd backend && php artisan test`. All clean. |
+| — | Update root `CLAUDE.md` + `AGENTS.md` `Audit Record` table; tracker → `status: complete`, `completed_at`, `next_allowed_run_after = +7 days` |
+| — | One commit + push |
+
+**Verification:** all green.
+**Commit message:** `chore(release): v3.0.1 — production-readiness audit batches 1-9 complete`
+
+---
+
+## Resume rules (also encoded in tracker JSON)
+
+1. On every run of this prompt, the FIRST action is `cat docs/tracking/production-readiness-audit-tracker.json`.
+2. If `last_run.status == "complete"` and `today < last_run.next_allowed_run_after`, SKIP. Tell the user the date and what was completed last time. Don't redo finished work.
+3. If `last_run.status == "in_progress"`, find the lowest-numbered batch with `status != "completed"` and resume there.
+4. After completing each batch: update tracker `batches[N].status = "completed"`, append a `history` entry, commit.
+5. After the final batch: set `last_run.status = "complete"`, `last_run.completed_at = today`, `last_run.next_allowed_run_after = today + 7 days`. ONE final commit.

package/docs/project-audit/MARKETING-WEBSITE-FINDINGS-2026-05-11.md

@@ -0,0 +1,73 @@
+# Marketing Website — Per-Page Findings (Batch 9 sweep)
+
+This document captures the **rendered-on-live-pages gaps** found by sweeping the React marketing+dashboard site at `website/` on 2026-05-11. It is the deliverable for production-readiness audit Batch 9 (item R5).
+
+This is **not** a sweep of `docs/MARKETING_WEBSITE_TRACKER.md` — that file is a stale planning artifact from 2025-12-27 (created before the live site shipped, never updated as features landed; 236 items still marked `[ ]` while the corresponding code is in production). The tracker file is now annotated as superseded — see its header note.
+
+The findings below are grouped by page. Each item names the file, the live URL where the gap would be visible to a user today, and a concrete fix. Trivial issues are fixed inline in the Batch 9 commit; non-trivial items are listed as follow-ups for future maintenance.
+
+Maintained by Ahsan Mahmood. Audit date: 2026-05-11.
+
+## Fixed in this batch (commit alongside this doc)
+
+### `ExamplesPage.tsx` — stale `firebase-backend` example card
+
+- **Live URL**: `https://nativeupdate.aoneahsan.com/examples`
+- **File**: `website/src/pages/ExamplesPage.tsx` lines 189-198 (third entry in the `backendExamples` array)
+- **Problem**: The card advertised an `example-apps/firebase-backend` example with a GitHub source link and an in-app docs link. The underlying directory was removed in v3.0.0 (per audit history 2026-05-04), so the GitHub URL 404s. The description also mentioned "Firestore manifests," contradicting the website's own architecture rule that forbids importing `firebase/firestore` since v3.0.0 (`website/CLAUDE.md`).
+- **Fix applied**: Removed the third entry from the `backendExamples` array. The two canonical v3 examples (React + Capacitor, Node + Express) remain. `Layers` icon import retained — still used elsewhere in the file (line 228).
+- **Risk if left**: Users land on `/examples`, click "View Source on GitHub" for the third card, get a GitHub 404, lose trust.
+
+## Follow-ups (not blocking; track for a future maintenance batch)
+
+### Stale MDX docs files mirrored under `website/public/package-docs/`
+
+- **File path**: `website/public/package-docs/docs/examples/firebase-backend-example.md` (plus copies under `website/dist/`, `website/android/app/...`, `website/ios/App/App/...`)
+- **Problem**: The Markdown file documenting the now-removed Firebase backend example is still present in the static-assets pipeline. It is no longer linked from the live React pages (after this batch's ExamplesPage fix), but it is still served at `/package-docs/docs/examples/firebase-backend-example.md` if someone has a direct link.
+- **Recommended action**: Delete the source file at `website/public/package-docs/docs/examples/firebase-backend-example.md`. The `dist/` and platform-mirror copies regenerate from `public/` on every build, so deleting the source clears them downstream. Verify after deletion that the docs-routing index in `DocsMarkdownPage.tsx` doesn't return a broken card for the missing file.
+- **Why deferred**: Touching `public/package-docs/` requires re-running the docs-content sync that produced those files, plus regenerating the Android / iOS asset bundles. That's a larger blast radius than fits in Batch 9.
+
+### HomePage has no Screenshots / Demo section
+
+- **Live URL**: `https://nativeupdate.aoneahsan.com/`
+- **File**: `website/src/pages/HomePage.tsx`
+- **Observation**: The 393-line HomePage renders Hero → Features → How-It-Works → CTA. There is no `Screenshots` or `Demo` section. Zero `<img>` or `<video>` tags in the entire file.
+- **Why this is a gap**: The marketing site is selling a UI-heavy product (a dashboard, OTA progress on a device). Visitors who don't already know what the dashboard looks like leave without seeing the actual product surface. This pattern is the single highest-converting block on competitive SaaS landing pages.
+- **Recommended action**: Add a "See it in action" section between How-It-Works and CTA. Three SVG-only mockup tiles is enough: a dashboard "uploads" view, a device showing the in-app update prompt, and a Nova admin panel snapshot. SVG keeps file sizes small and avoids the PNG/JPG-screenshot maintenance treadmill that breaks on every UI tweak.
+- **Why deferred**: Building three good-looking SVG mockup tiles is a half-day of design work, not a Batch 9 inline fix. Logging as a follow-up so it's not lost.
+
+### `DocsPage.tsx` is 1,406 lines
+
+- **Live URL**: `https://nativeupdate.aoneahsan.com/docs`
+- **File**: `website/src/pages/DocsPage.tsx`
+- **Observation**: The file violates the project-wide "Max 500 lines/file" rule from the global CLAUDE.md. Most of the content is large code-snippet string literals — ~10 large snippets embedded inline rather than imported from separate files.
+- **Recommended action**: Extract code-snippet strings into `website/src/data/docs-snippets/` (one file per snippet). The page then becomes a thin renderer over the data. This reduces churn on the page when snippets change.
+- **Why deferred**: Not a rendered-page gap — visitors don't see the line count. Pure maintainability concern; lower priority than the user-facing items above.
+
+## Items reviewed and confirmed healthy (no action needed)
+
+The sweep also confirmed the following are NOT gaps:
+
+| Surface | Status |
+|---|---|
+| Header.tsx internal links | All 4 `<Link to=...>` targets (`/dashboard`, `/login`, `/signup`) resolve to registered routes in `src/router.tsx`. |
+| Footer.tsx internal links | All 19 `<Link to=...>` targets resolve to registered routes. Includes `/sitemap`, `/feed`, `/security`, `/permissions`, `/data-deletion`, `/cookies`, `/privacy`, `/terms` — every legal page is wired up. |
+| Dashboard empty states | 6 dashboard pages (AppsPage, AppDetailPage, DashboardOverview, ConfigPage, UploadPage) have explicit empty-state UI with "create your first app" / "upload your first build" copy. Onboarding flow exists. |
+| `firebase-backend` references in user-facing copy | Only one remaining in `AboutPage.tsx` line 57-58 — a FAQ entry "Why build another OTA solution? What about CodePush?" mentioning CodePush, not firebase-backend. Correct (CodePush is a real third-party reference, not a deleted internal example). |
+| CodePush references | All current and contextually correct (the migration story is part of the marketing message; CodePush's March 2025 retirement is fact). |
+| Version strings in JSON-LD | Audit Record entry 2026-05-02 confirms softwareVersion was bumped to current. |
+| `console.*` calls in src/ | Audit Record entry 2026-05-02 confirms migration to `src/lib/logger.ts`. |
+
+## How to use this doc
+
+This is a snapshot. Re-run the per-page sweep when:
+
+- A new public page ships (re-check footer + sitemap coverage)
+- A feature is removed (re-grep for any references that point at it)
+- Before a major release (it pairs with the [Pre-Launch Pentest Checklist](/home/ahsan/Documents/01-code/projects/native-update/docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md))
+
+The findings format intentionally avoids GitHub issue creation here — when the project goes public, items in the "Follow-ups" section above are good first issues to open against the public repo.
+
+## Authored by
+
+Ahsan Mahmood — author and maintainer of `native-update`.

package/docs/project-audit/PRODUCTION-READINESS-AUDIT-2026-05-08.md

@@ -0,0 +1,275 @@
+# Production-Readiness Audit — native-update Monorepo
+
+**Date:** 2026-05-08
+**Auditor:** Claude Code (Opus 4.7, 1M context)
+**Scope:** Whole monorepo (root plugin + cli + android + ios + backend + website + example-apps + docs)
+**Method:** Six parallel scoped audit agents (plugin/native, website UI, SEO/AEO, backend, examples+roadmap, security/env). Findings cross-verified against source files before recording here.
+**Companion files:**
+- Batch plan: `docs/project-audit/BATCH-PLAN.md`
+- Tracker (resumeable, 7-day cooldown): `docs/tracking/production-readiness-audit-tracker.json`
+
+---
+
+## Verdict
+
+The monorepo is **~85% production-ready**. Three real npm-publish-blockers + several backend hardening gaps + per-page SEO content gaps are the main risks. No active secret exposure, no banned packages, no broken builds in the root plugin or website.
+
+**Severity legend:** **B** = Blocker (must fix before next release / public push). **I** = Important (fix before production cutover). **N** = Nit / polish.
+
+---
+
+## 1. Banned-Package Phase 0 Check
+
+`grep -nE "@capacitor-firebase/(crashlytics|performance)|@capawesome/capacitor-torch" package.json **/package.json` → **zero matches**. ✅ No bans violated.
+
+---
+
+## 2. Findings — Plugin Source / CLI / Native (root, src/, cli/, android/, ios/)
+
+### Blockers
+
+- **B1 — `package.json` `files` array is missing `android/manifest-additions.xml`**
+  File: `package.json:13-26`. The file exists at `android/manifest-additions.xml` and is required at install-time by Capacitor's manifest merger. Without it in the npm package, downstream Android builds will be missing the additions block. **Fix:** add `"android/manifest-additions.xml"` to the `files` array.
+
+- **B2 — `cli/commands/backend-create.js` ships placeholder TODOs in scaffolded backend templates**
+  File: `cli/commands/backend-create.js:144,176,177,290,309,310,493,494`. Eight `TODO` markers in Express/Vercel/Firebase scaffolding for: bundle lookup, file storage, DB save. The CLI generates these as ready-to-deploy code, but they are not. **Fix:** either (a) implement the missing logic and wire to `node-express` example as the canonical scaffold, or (b) prepend each generated file with a clear `// SCAFFOLD — implement before deploying` banner and document expected wiring.
+
+- **B3 — `cli/commands/monitor.js` has unmanaged `setInterval` + spinner-leak on exit**
+  File: `cli/commands/monitor.js:14-62`. `setInterval` fires every 5s with an async callback; failures stack indefinitely. `ora` spinner is started but never stopped on exit/failure — terminal is left in undefined state. **Fix:** capture interval ID, install `SIGINT`/`SIGTERM` handlers that `clearInterval` + `spinner.stop()`; bail the loop on consecutive failures.
+
+### Important
+
+- **I1 — Direct `console.*` in plugin source (violates centralized-logger convention)**
+  Files: `src/web.ts` (18 calls), `src/core/event-emitter.ts:52`. Plugin already has a `Logger` singleton; security paths (checksum, signature) and event-emitter error path bypass it. **Fix:** replace `console.{warn,error,log}` with `Logger.{warn,error,info}` everywhere outside the logger module itself. Note: this is the *plugin's* logger, separate from website logger.
+
+- **I2 — `ios/Plugin/NativeUpdatePlugin.swift:72-75` calls `disableBackgroundUpdatesInternal()` to bypass inaccessible Capacitor SDK constructors**
+  Workaround for SDK API surface, fragile if the SDK changes. **Fix:** add a `// CAPACITOR-SDK-WORKAROUND:` comment block referencing the SDK version this assumes, and a `// TODO: revisit on Capacitor 8.x update` line so future bumps don't silently break.
+
+- **I3 — `cli/commands/backend-create.js` file-list completeness vs `node-express` template**
+  Several runtime concerns (signature verify, rollout cohort logic, channel filtering) live in docs only, not in the scaffold. **Fix (low-risk):** ensure `cli/templates/express/` mirrors `example-apps/node-express/` structure 1:1 so users get a working scaffold by default.
+
+### Nits
+
+- **N1 — `rollup.config.js:61,63` duplicate `comments` key in terser format**
+  Line 63 silently overrides line 61. Functional but a typo. **Fix:** delete the earlier line.
+
+### State-vs-claim notes
+
+- All 28+ public methods in `src/definitions.ts` have matching implementations in `src/web.ts`, `ios/Plugin/`, `android/src/main/`. **API parity ✓**.
+- HTTPS enforcement, SHA-256 checksum + RSA/ECDSA signature paths are well-implemented and fail-closed. **Crypto correct ✓**.
+- TypeScript `strict: true`, Vitest 89/89 green. **Build clean ✓**.
+
+---
+
+## 3. Findings — Website (`website/`)
+
+### Blockers
+
+None. `yarn typecheck` + `yarn build` complete cleanly; sitemap + postbuild SEO HTML generation succeed across all 16 routes.
+
+### Important
+
+- **I4 — Custom `Dialog.tsx` lacks key a11y primitives**
+  File: `website/src/components/ui/Dialog.tsx`. Missing `role="dialog"` + `aria-modal="true"` on `DialogContent`, no ESC-key handler on overlay, no focus restore on close, no focus trap. **Fix:** either migrate to `@radix-ui/react-dialog` (already a transitive dep via other Radix primitives in package.json) — strongly recommended per project's Radix-first rule — or harden the custom one with `aria-labelledby`, ESC handler, focus trap, focus restore.
+
+- **I5 — Dashboard dialog state held in `useState` instead of URL search params (violates URL-State-Preservation rule)**
+  File: `website/src/pages/dashboard/AppsPage.tsx:50,55`. `deleteDialog` and `formDialog` open-state both in `useState`. Refresh closes them — wrong UX. **Fix:** convert to `?deleteId=ID` and `?formMode=create|edit&appId=ID` per project rule. Audit all other dashboard pages for the same pattern.
+
+- **I6 — TanStack Query: per-page `staleTime` overrides not audited**
+  Global default in `App.tsx` is 30s + `gcTime: 5m`. Spot-check individual `useQuery` sites in `src/hooks/` and `src/pages/dashboard/` for ad-hoc overrides that disable cache. **Fix:** sweep, document the project-wide cache contract, set `queryKey` factories per resource (already mostly done).
+
+### Nits
+
+- BootLoader present (✓), 7-option Theme Customizer present (✓), URL state hooks present (`useUrlState.ts`-style), 47 aria-* attributes across components.
+- `vite-env.d.ts` is minimal (only `__APP_VERSION__`) — env types are validated through `src/config/env.ts` `getMissingRequiredEnv()` at boot. ✓.
+
+---
+
+## 4. Findings — SEO / AEO / AIO (`website/`)
+
+Today is 2026-05-08; last full SEO pass was 2026-04-24 (14 days ago — within commit-delta gate window).
+
+### Blockers
+
+None on infrastructure — robots.txt allows GPTBot/ClaudeBot/PerplexityBot/Google-Extended/Bingbot/etc., sitemap.xml + feed.xml + llms.txt + llms-full.txt + ai.txt + humans.txt + security.txt all present.
+
+### Important
+
+- **I7 — Per-page-uniqueness floor not met on three core marketing pages**
+  Files: `website/src/pages/FeaturesPage.tsx` (~150 words, 0 FAQ, 0 use cases, 0 HowTo), `website/src/pages/AboutPage.tsx` (~400 words, 0 FAQ), `website/src/pages/PricingPage.tsx` (~100 words, 0 FAQ). Global rule (`~/.claude/rules/seo-aeo-ranking.md` §2) requires ≥1000 unique words + 5–8 FAQ + 3–5 use cases + 4–6 HowTo steps + 2–3 examples + 3–6 tips + author + lastUpdated per page. **Fix:** rewrite via `ai-seo` + `copywriting` skills; treat as one batch, not per-page commits.
+
+- **I8 — `pricing.md` machine-readable file missing at site root**
+  Global rule §5 requires `/pricing.md` for AI buying agents when paid tiers exist. Project has Free + Pro + Enterprise (PayPal plans referenced in backend/.env.example). **Fix:** create `website/public/pricing.md` with tiers, limits, features, FAQ in plain markdown.
+
+- **I9 — `feed.xml` `<lastBuildDate>` lags actual build**
+  Generator emits a stale date instead of `new Date().toUTCString()` at run time. **Fix:** in `website/scripts/generate-sitemap.mjs` (or wherever feed is emitted), replace literal date with runtime stamp; ensure sitemap `<lastmod>` does the same.
+
+### Nits
+
+- **N2 — Docs sub-routes (`/docs/*`) lack per-route static prerender** — they rely on runtime SEO + Googlebot JS rendering; AI crawlers may not render JS. Tracked in `seo-url-coverage.json` already as a known issue. **Fix (later):** extend `postbuild-seo.ts` to walk `public/package-docs/` and emit `dist/docs/<slug>/index.html`.
+- **N3 — `og:image` is the same `/og-image.svg` site-wide.** Per-page OG images would lift social sharing. Defer.
+- All discovery-file dates timestamped 2026-05-02 (6 days old — within 14-day spec, refresh on next batch commit).
+
+---
+
+## 5. Findings — Backend (Laravel 11 + Nova 5, `backend/`)
+
+### Blockers
+
+- **B4 — Nova resources lack policy-backed authorization gates**
+  Files: `backend/app/Nova/*.php` (User, App, Build, ApiKey, SigningKey). Missing `canViewAny()`, `canCreate()`, `canUpdate()`, `canDelete()` guards backed by App\Policies. **Fix:** add per-Resource policies + register in `AuthServiceProvider`; reject non-admin / non-owner access on each verb.
+
+- **B5 — No Feature test for the bundle-upload + signature-verify flow**
+  Folder: `backend/tests/Feature/`. The most security-critical endpoint (build upload) has no test for: signature verify, monotonic version enforcement, channel scoping, duplicate detection, chunk merging. **Fix:** add `tests/Feature/Build/BundleUploadTest.php` covering the full path.
+
+- **B6 — `backend/.env` (local) has `APP_DEBUG=true` + `LOG_LEVEL=debug`** *(documentation gap, not active leak)*
+  This is correct for local dev, BUT no deployment runbook documents flipping these for production. `.env.example` correctly defaults to `APP_DEBUG=false`/`LOG_LEVEL=warning`. **Fix:** add `backend/docs/DEPLOYMENT-CHECKLIST.md` listing `APP_DEBUG=false`, `LOG_LEVEL=warning`, `APP_ENV=production`, `php artisan config:cache`, `migrate --force`, `composer install --no-dev`, queue worker daemonization.
+
+### Important
+
+- **I10 — `ValidateFirebaseToken` middleware auto-creates User on first valid token**
+  File: `backend/app/Http/Middleware/ValidateFirebaseToken.php:41-48`. `firstOrCreate` is open-signup; fine for free tier, risky for invite-only / enterprise. **Fix:** keep open by default but document; add config flag `auth.firebase.auto_create=true|false`.
+
+- **I11 — Controllers validate inline; no FormRequest classes**
+  Files: `backend/app/Http/Controllers/Dashboard/*.php`. Reduces reuse + makes policy gating awkward. **Fix:** extract validators into `app/Http/Requests/*Request.php`; use `$this->authorize()` from inside the request.
+
+- **I12 — Nova User admin panels (Suspend, License, Custom Limits) lack `canSee` gates**
+  File: `backend/app/Nova/User.php:64-65`. Any Nova-authenticated user could touch admin fields. **Fix:** wrap with `Panel::make(...)->canSee(fn ($req) => $req->user()->isAdmin())`.
+
+- **I13 — No `config/cors.php` — relies on Laravel default**
+  Production must lock origins to `nativeupdate.aoneahsan.com` (and dashboard host). **Fix:** publish CORS config, set `paths` → `['api/*']`, `allowed_origins` → explicit list, `supports_credentials` → true.
+
+- **I14 — License-check tests missing**
+  `User::hasValidLicense()` and license-expiry enforcement on API endpoints are not exercised by tests. **Fix:** add Feature test wrapping a paid-tier endpoint.
+
+- **I15 — PayPal webhook CSRF status not explicit**
+  File: `backend/routes/api.php:155-156`. Confirm webhook is in CSRF exception list (Laravel 11 default API routes are CSRF-exempt because they're stateless, but document this and add test).
+
+### Nits
+
+- **N4 — `CACHE_STORE=database` in `.env.example`** — fine for boot, but Redis is recommended for production rate-limiting performance. Add a `# Recommended for production: CACHE_STORE=redis` comment.
+- **N5 — `QUEUE_CONNECTION=database`** — requires `php artisan queue:work` daemon. Document in deployment checklist.
+
+### Notes
+
+- All models use `$fillable` (not `$guarded`); secrets (`password`, `google_drive_token`, `key_hash`) are in `$hidden`. ✓
+- Migration timestamps clean, no out-of-order. ✓
+- File storage uses FilesHub via `FilesHubService` (no AWS S3 hardcoded). ✓
+- `composer.lock` present + reproducible. ✓
+- `.env.example` has [REQUIRED] tags on most blocks. Some PayPal/Google sub-vars could use a one-line reason each (minor).
+
+---
+
+## 6. Findings — Example Apps (`example-apps/`)
+
+### Blockers
+
+- **B7 — `example-apps/react-capacitor` `yarn build` fails (lockfile / workspace ref unresolved)**
+  Error: "This package doesn't seem to be present in your lockfile". Yarn 4 + workspace pointer `"native-update": "file:../.."` not registered in root lockfile. **Fix:** run `yarn install` at root with the example workspaces included; verify root `package.json` declares workspaces (it currently does NOT — example-apps live as ad-hoc projects). Either declare workspaces or document that `cd example-apps/react-capacitor && yarn install` is required separately.
+
+- **B8 — Stale `firebase-backend/` references in `example-apps/react-capacitor/README.md`**
+  Lines: `14`, `101`, `210`. `firebase-backend` was deleted in v3.0.0 but README still recommends it as an option. **Fix:** delete those lines / replace with `node-express` only.
+
+### Important
+
+- **I16 — `react-capacitor` example demos only `checkForUpdate()`**
+  File: `example-apps/react-capacitor/src/App.tsx:1-72`. v3 plugin has 28+ public methods; example covers ~5%. **Fix (incremental):** add tabs/sections demonstrating: `downloadUpdate`, `applyUpdate`, app-update check, app-review prompt, background-update toggle, signature verification of a downloaded bundle. One section per method; gated by feature-flag if Android/iOS-only.
+
+- **I17 — `react-capacitor` pinned to React 18 while `website/` is React 19**
+  Files: `example-apps/react-capacitor/package.json:20`. **Fix:** decide intent. Either bump to 19 to track current website + plugin tests, or add a comment in README declaring 18 is the "stable downstream" target.
+
+### Notes
+
+- `node-express` correctly implements the v3 HTTP-only backend contract. ✓
+- `node_modules` of `react-capacitor` contains stale `native-update@1.3.1` tarball — harmless but worth cleaning on next install.
+
+---
+
+## 7. Findings — Security / Secrets / Env (cross-cutting)
+
+### Critical
+
+None. `yarn npm audit --severity high --recursive` → "No audit suggestions". No hardcoded secrets in source (only in non-public-checked-in `.env` files; root `.gitignore` declares the repo as private with intentional .env-in-git policy — mirror this in any future public split).
+
+### High
+
+- **H1 — Backend has no `config/cors.php`** (duplicates I13). Must lock origins before public deploy.
+- **H2 — Repo is private with `.env` in git.** If repo ever flips public, immediately add `*.env`, `*.env.local`, `*.env.production`, `backend/storage/firebase-credentials.json`, `android/keystores/` to `.gitignore` and rotate every committed secret. **Fix (preventive):** add `docs/SECURITY-IF-REPO-PUBLIC.md` runbook so this isn't forgotten under pressure.
+
+### Medium
+
+- **M1 — `backend/.env.example` `[REQUIRED]` reason comments** — present on FilesHub/Firebase/Google/PayPal blocks (✓). Minor: each *individual sub-var* (e.g. `PAYPAL_LIVE_APP_ID`) could use a one-line "where to find it" note for first-time deployers.
+- **M2 — `website/.env.example` missing two optional docs-snippet vars** that exist in `ConfigPage.tsx`: `VITE_NATIVE_UPDATE_PUBLIC_BACKEND_URL`, `VITE_NATIVE_UPDATE_API_KEY`, `VITE_NATIVE_UPDATE_PUBLIC_KEY`. **Fix:** add as `[OPTIONAL]` rows.
+
+### Notes
+
+- Firebase Web API keys (in website/.env) are PUBLIC by design — not a leak.
+- Auth tokens stored only in Firebase SDK in-memory — no localStorage leak.
+- `firestore.rules` properly tiered (auth-required + admin-via-custom-claim, with public read only on `/manifests/{id}` which is intentional).
+- LICENSE present (MIT) and consistent. ✓
+- Capacitor `appId` stable: `com.aoneahsan.nativeupdate`. ✓
+- No keystores committed (`android/keystores/` does not exist yet). ✓
+
+---
+
+## 8. Roadmap Delta (Planned Features Not Yet Done — Practical-for-Release)
+
+Mined from `docs/REMAINING_FEATURES.md`, `docs/ROADMAP.md`, `docs/PROJECT_COMPLETION_TRACKER.md`, `docs/MARKETING_WEBSITE_TRACKER.md`, `docs/plans/`, `docs/features/laravel-nova-backend/IMPLEMENTATION-PLAN.md`.
+
+### Practical for v3.x release (this audit will tackle in batches)
+
+- **R1** — Performance benchmarking suite scaffold (placeholder exists; needed for SaaS credibility claims).
+- **R2** — Pre-launch security pen-test checklist (light: dependency scan + manual review; not a paid pentest).
+- **R3** — CI/CD integration templates (GitHub Actions): release workflow for the npm plugin + bundle-create + sign + upload step.
+- **R4** — Expand `react-capacitor` example coverage (also tracked as I16 above).
+- **R5** — Marketing-website tracker: 50+ items still `[ ]` in `docs/MARKETING_WEBSITE_TRACKER.md`. Filter for ones that are actually rendered on live pages but unfinished (e.g. screenshots, code-snippet copy refresh, dashboard onboarding flow polish).
+
+### Defer to v3.1+ (not blocking release)
+
+- A/B testing support
+- Staged rollouts with percentage targeting (DB schema exists in backend; UI/CLI surfaces incomplete)
+- Geographic targeting
+- Update scheduling
+- Delta-update WASM optimization
+- Multi-tenant SaaS, enterprise SSO, SLA monitoring
+- Vue / Angular / Svelte / Python / Java example apps
+- Video tutorials, community plugins directory
+
+---
+
+## 9. Verification Commands
+
+After each batch, run from repo root:
+
+```bash
+# Plugin
+yarn lint
+yarn typecheck   # alias for `yarn tsc`
+yarn build
+yarn test:run
+
+# Website
+cd website && yarn typecheck && yarn lint && yarn build && cd ..
+
+# Backend (Laravel)
+cd backend && composer install --no-interaction && php artisan test && cd ..
+
+# Cross-cutting
+grep -rEn "TODO|FIXME" src/ cli/ website/src/ backend/app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.php" | wc -l   # track count down over batches
+yarn npm audit --severity high --recursive
+```
+
+---
+
+## 10. Total Issue Count
+
+| Severity | Plugin | Website | SEO | Backend | Examples | Security | Roadmap | **Total** |
+|---|---|---|---|---|---|---|---|---|
+| Blocker | 3 | 0 | 0 | 3 | 2 | 0 | 0 | **8** |
+| Important | 3 | 3 | 3 | 6 | 2 | 0 | 0 | **17** |
+| Nit | 1 | 0 | 2 | 2 | 0 | 0 | 0 | **5** |
+| Sec High | — | — | — | — | — | 2 | — | **2** |
+| Sec Med | — | — | — | — | — | 2 | — | **2** |
+| Roadmap | — | — | — | — | — | — | 5 | **5** |
+
+Grand total: **39 actionable items** across the audit + 5 roadmap items. See `BATCH-PLAN.md` for the execution plan.

package/docs/project-finalization/00-tracker.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "project-finalization-tracker",
+  "description": "Resumable production-finalization tracker for native-update (Capacitor OTA plugin + Laravel/Nova SaaS backend + React marketing site/dashboard + CLI + Docusaurus docs site). The first phase/sub-task with status 'pending' or 'in_progress' is the next thing to work on.",
+  "project": "native-update",
+  "type": "capacitor-plugin-monorepo + saas-backend + marketing-website + cli + docs-site",
+  "repo": "github.com/aoneahsan/native-update (PRIVATE)",
+  "docsRepo": "github.com/aoneahsan/native-update-docs (PRIVATE)",
+  "npm": "native-update@3.1.0 (published)",
+  "homepage": "https://nativeupdate.aoneahsan.com",
+  "createdAt": "2026-06-22",
+  "lastUpdated": "2026-07-02",
+  "readiness": 99,
+  "stackOverride": {
+    "note": "The fleet finalization spec assumes a Firestore + Google Drive website backend. native-update DELIBERATELY chose a Laravel 13 + Nova 5 + MySQL + Google Drive backend (v3.0.0+). Per the Per-Project Stack Override rule, the project's chosen stack wins. Zero-cost / no-Firebase-Functions still honored: this project's own backend uses NO Firebase Functions/Storage (the CLI's firebase-functions strings live only inside a user-choice backend-template GENERATOR).",
+    "websiteBackend": "Laravel 13 + Nova 5 + MySQL + Google Drive (NOT Firestore)",
+    "auth": "Laravel Socialite (Google OAuth) + Sanctum tokens + spatie/laravel-permission RBAC (Firebase Auth removed in v3.0.0)"
+  },
+  "verifyGates": {
+    "pluginBuild": "yarn build -> 0 errors (clean + tsc + rollup, ~4s)",
+    "pluginTypecheck": "yarn tsc --noEmit -> 0 errors",
+    "pluginLint": "yarn lint -> 0 warnings",
+    "websiteTypecheck": "yarn typecheck (tsc -b) -> 0 errors",
+    "websiteBuild": "yarn build -> 0 errors (61-URL sitemap + feed + 16 SEO routes + 9 discovery files)",
+    "websiteLint": "yarn lint -> 0 warnings",
+    "docsBuild": "native-update-docs: yarn build (Docusaurus) -> see runHistory",
+    "verifiedAt": "2026-06-22"
+  },
+  "phases": [
+    { "id": "phase0", "title": "Setup: skills, remote/branch, read scope, scaffold tracker + MANUAL-TASKS, refresh CLAUDE/AGENTS", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phase1", "title": "Privacy gate + env/secret audit (repo PRIVATE; force-add git-ignored env; never keystores)", "status": "complete", "completedAt": "2026-06-22",
+      "subTasks": [
+        { "id": "phase1.1", "title": "gh repo view: main + docs repos confirmed PRIVATE", "status": "complete" },
+        { "id": "phase1.2", "title": "Force-add git-ignored backend/.env + website/.env (private repo; root .gitignore documents team-access intent; never published to npm via files[])", "status": "complete" },
+        { "id": "phase1.3", "title": "No keystores in tree; none added", "status": "complete" }
+      ] },
+    { "id": "phase2", "title": "Gap audit: real code vs intended scope + docs promises", "status": "complete", "completedAt": "2026-06-22",
+      "subTasks": [
+        { "id": "phase2.1", "title": "Plugin src/ TODO/stub scan: clean (3 false positives — field names + a docstring)", "status": "complete" },
+        { "id": "phase2.2", "title": "CLI scaffolding TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY] markers are INTENTIONAL generated-template placeholders (BACKEND_TEMPLATES_GUIDE.md) — by design, not a gap", "status": "complete" },
+        { "id": "phase2.3", "title": "Website console.* hits are inside documentation code-example strings, not real logging; no innerHTML in new code", "status": "complete" }
+      ] },
+    { "id": "phase3", "title": "Build automatable gaps", "status": "complete", "completedAt": "2026-06-22",
+      "note": "No automatable code gaps found. The project is genuinely production-complete (v3.1.0 on npm, 134 backend PHPUnit tests, complete iOS/Android/CLI/website/backend/docs). The only real fix was doc-drift: REMAINING_FEATURES.md item #5 (DocsPage.tsx 1406-line refactor) was already done (now 166 lines + docs-page/sections/)." },
+    { "id": "phaseD", "title": "Verify/finish native-update-docs (Docusaurus, sibling repo)", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phaseN1", "title": "Manual-task consolidation (npm publish, deploys, device verify, backend DB/test verify)", "status": "complete", "completedAt": "2026-06-22" },
+    { "id": "phaseN2", "title": "Finalize: final verify gates + tracker + git in-sync (both repos)", "status": "complete", "completedAt": "2026-06-22" }
+  ],
+  "gapInventory": [
+    { "id": "G1", "title": "Delta-update WASM (bsdiff/bspatch) optimization", "classification": "ROADMAP-OPTIONAL", "status": "deferred", "note": "delta-processor.ts already ships a working JS-level file-patching strategy; WASM is a performance enhancement, not a missing feature. Documented in REMAINING_FEATURES.md." },
+    { "id": "G2", "title": "A/B testing, calendar update scheduling, geographic targeting", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "Large speculative features the user has not scoped. Percentage rollouts + pause/resume + targetSegments already shipped on the builds table." },
+    { "id": "G3", "title": "Additional framework example apps (Vue / Angular / Svelte / Python / Java)", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "React+Capacitor and Node/Express examples already ship. Which (if any) to add next is a product decision." },
+    { "id": "G4", "title": "Enterprise: multi-tenant/org accounts, SAML/OIDC SSO, white-label branding, audit-log UI", "classification": "PRODUCT-DECISION", "status": "deferred", "note": "Roadmap; current model is single-user. Raw audit events already persist via analytics_events + Nova." },
+    { "id": "G5", "title": "website page components marginally over 500-line soft guideline (FeaturesPage 578, ExamplesPage 523, AnalyticsPage 519)", "classification": "COSMETIC-OPTIONAL", "status": "deferred", "note": "500 lines is a soft guideline; these are cohesive content-heavy single pages that build clean. Not a finalization blocker." }
+  ],
+  "runHistory": [
+    { "date": "2026-06-22", "phase": "all", "summary": "Owner-agent finalization pass. Verified package (build/tsc/lint = 0), website (typecheck/build/lint = 0; 61-URL sitemap + 16 SEO routes), and docs site build. Confirmed both repos PRIVATE; force-added git-ignored backend/.env + website/.env (never published to npm). Plugin/native/CLI/backend genuinely complete; no automatable code gaps. Fixed stale REMAINING_FEATURES.md DocsPage item. Scaffolded this tracker; refreshed CLAUDE.md/AGENTS.md + MANUAL-TASKS + sitemap/feed lastmod to 2026-06-22.", "commit": "pending" },
+    { "date": "2026-07-02", "phase": "v3.1.0-release", "summary": "v3.1.0 audit + optimize + release session (Fable 5 plan + Opus 4.8 execution). Plugin: package.json exports map, web.ts validateUpdate reuses downloaded bytes (no double download), 10 dead comment lines removed, cli 3.1.0. Website: HomePage LazyMotion (framer-motion off first-paint), .env.production (prod backend URL always baked), root firebase.json consolidated w/ cache headers (website/firebase.json+.firebaserc deleted), 9 dead Firebase-era env keys removed. Backend: update-check writes deferred to dispatch()->afterResponse(), App::getLatestBuildForChannel cached 45s w/ Build model-event invalidation, additive covering index builds(app_id,channel,status,created_at), analytics:cleanup now prunes analytics_events, CORS supports_credentials=false, 2 scaffold ExampleTests removed (134 PHPUnit pass). Docs: CHANGELOG + RELEASE-NOTES 3.1.0, Laravel-11->13 / Pest->PHPUnit / api-host drift fixed, HOSTINGER deploy notes refreshed (PHP>=8.3, scheduler required, v3.1.0 migration, X-Sendfile note). Released: npm publish native-update@3.1.0 + firebase deploy website. INCIDENT: live backend https://nativeupdatebe.aoneahsan.com returns HTTP 500 on all routes (pre-existing, deploy-side — flagged as MANUAL-TASKS row 1, likely PHP<8.3). Deferred: native streaming-hash perf, file splits, X-Sendfile impl, docs-site deploy.", "commit": "pending" }
+  ],
+  "resumeInstructions": "1) Read this tracker. 2) All phases complete. 3) If re-run: confirm verify gates still pass, check whether the user has scoped any gapInventory ROADMAP/PRODUCT-DECISION item, and update lastUpdated. NEVER auto-build the deferred product-decision features without the user scoping them."
+}