diff --git a/README.md b/README.md index 6e973dd..1d72de5 100644 --- a/README.md +++ b/README.md @@ -130,3 +130,4 @@ Current baseline note: after common-platform workspace alignment, `pnpm install - [`docs/ROADMAP.md`](docs/ROADMAP.md) — Master execution tracker - [`docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md) — Active production-readiness checklist - [`docs/PLATFORM_SMOKE_CHECKS.md`](docs/PLATFORM_SMOKE_CHECKS.md) — Shared platform and NoteLett smoke commands +- [`docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`](docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md) — Expo build notes and iOS/Android smoke checklist diff --git a/docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md b/docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md new file mode 100644 index 0000000..8a49496 --- /dev/null +++ b/docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md @@ -0,0 +1,148 @@ +# NoteLett Mobile Production Build And Smoke Checklist + +Date: May 5, 2026 +Surface: Expo mobile app in `mobile/` + +## Scope + +This runbook covers the release-readiness checks for the NoteLett Expo companion app. It is intentionally focused on the current React Native/Expo path, not a native Swift/Kotlin track. + +## Product Identity + +The canonical product identity is `shared/product.json`. + +| Field | Value | +| --- | --- | +| Expo name | `NoteLett` | +| Expo slug | `notelett` | +| URL scheme | `notelett` | +| iOS bundle identifier | `com.bytelyst.notelett` | +| Android package | `com.notelett.app` | +| Platform product id | `notelett` | + +Verify before a production build: + +```bash +node -e "const app=require('./mobile/app.json').expo; const product=require('./shared/product.json'); console.log({name: app.name, slug: app.slug, scheme: app.scheme, ios: app.ios.bundleIdentifier, android: app.android.package, productId: product.productId})" +``` + +## Required Services + +Production-like smoke checks require these services to be reachable from the simulator/device: + +| Service | Default local URL | Purpose | +| --- | --- | --- | +| NoteLett backend | `http://localhost:4016/api` | Notes, workspaces, intake, prompts, reviews | +| platform-service | `http://localhost:4003/api` | Auth, flags, kill switch, telemetry, diagnostics, blob | +| extraction-service | `http://localhost:4005` | URL/task extraction behind backend flows | + +For physical devices, replace `localhost` with the host machine IP or a tunnel URL that the device can reach. + +## Build Environment + +Set mobile public API URLs before building or launching a production-like app: + +```bash +export EXPO_PUBLIC_NOTES_API_URL="https://api.notelett.app/api" +export EXPO_PUBLIC_PLATFORM_SERVICE_URL="https://platform.bytelyst.com/api" +``` + +Local simulator/device smoke can use LAN URLs: + +```bash +export EXPO_PUBLIC_NOTES_API_URL="http://:4016/api" +export EXPO_PUBLIC_PLATFORM_SERVICE_URL="http://:4003/api" +``` + +Do not put secrets in `EXPO_PUBLIC_*` variables. They are bundled into the app. + +## Pre-Build Verification + +From the repo root: + +```bash +zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm install --frozen-lockfile' +zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/mobile run typecheck' +zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/mobile run test' +``` + +If lint is part of the release gate, run it and compare against the known P0.5/P8.1 lint baseline: + +```bash +zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/mobile run lint' +``` + +## Local Production-Like Launch + +Start shared services and the NoteLett backend first. For an isolated product-backend check: + +```bash +DB_PROVIDER=memory JWT_SECRET=dev-secret-do-not-use-in-prod pnpm --filter @notelett/backend run dev +``` + +Then launch the mobile app: + +```bash +zsh -lc 'source ~/.zshrc; export GITEA_NPM_TOKEN; pnpm --filter @notelett/mobile run start' +``` + +Open the app in an iOS simulator, Android emulator, Expo Go, or a development build. For physical devices, confirm the `EXPO_PUBLIC_*` URLs are not `localhost`. + +## Production Build Notes + +The repo does not currently include an `eas.json`, so EAS build profiles must be added before CI-driven store builds. Until that lands, treat EAS as an operator step: + +```bash +cd mobile +eas build --platform ios --profile production +eas build --platform android --profile production +``` + +Before running those commands: + +- Confirm Apple/Google signing credentials are configured in EAS. +- Confirm `EXPO_PUBLIC_NOTES_API_URL` and `EXPO_PUBLIC_PLATFORM_SERVICE_URL` are set through EAS environment variables or the selected build profile. +- Confirm `mobile/app.json` still has the production bundle identifiers listed above. +- Confirm privacy and permission copy matches any native modules enabled for the build. + +## iOS Simulator Or Device Smoke + +Run this checklist on a production-like iOS build or simulator launch: + +- Open app cold and confirm the kill-switch gate does not appear when platform-service reports enabled. +- Register a new account or sign in with a test platform-service account. +- Force close and reopen; confirm auth state persists and stores hydrate only after auth bootstrap. +- Toggle airplane mode before launch; confirm cached auth does not force logout and note list remains usable from local state where available. +- Create a text note in Capture, then confirm it appears on Home and opens in note detail. +- Edit the note title/body and confirm the update persists after reopening detail. +- Switch workspaces on Home and Capture; confirm filters/save target update. +- Submit URL intake from Capture or share intent; confirm queued state appears, success navigates to note detail, and failures show an error instead of spinning forever. +- Run a Smart Action prompt from note detail; confirm success renders result and failure shows the prompt error state. +- Approve and reject one inbox item with a review note. +- Open Settings and submit feedback through the shared feedback client. +- Background the app and return; confirm queued notes flush when online and telemetry flush does not crash. +- Trigger or simulate broadcast/survey responses if available from platform-service. +- Sign out and confirm protected tabs route back through auth. + +## Android Emulator Or Device Smoke + +Run the same workflow on Android, plus: + +- Confirm the Android package is `com.notelett.app`. +- Confirm back navigation from auth, note detail, prompt result, and intake does not leave a blank route. +- Confirm text inputs are not obscured by the keyboard in auth, capture, note detail, inbox review note, settings feedback, and intake screens. +- Confirm Dynamic Type/accessibility font scaling keeps button text readable and unclipped. +- Confirm physical-device builds use LAN/tunnel URLs, not `localhost`. + +## Result Recording + +Record smoke results with: + +- build identifier or simulator/device name +- backend/platform/extraction URLs used +- account tested +- pass/fail for each checklist item +- links to logs, screenshots, or crash reports for failures +- commit hash under test + +P10 production gate should attach or summarize this record before release. diff --git a/docs/roadmaps/04_MOBILE_ROADMAP.md b/docs/roadmaps/04_MOBILE_ROADMAP.md index 33c469d..47c6c92 100644 --- a/docs/roadmaps/04_MOBILE_ROADMAP.md +++ b/docs/roadmaps/04_MOBILE_ROADMAP.md @@ -41,7 +41,7 @@ Stack: React Native + Expo + TypeScript # Phase M4 — Hardening -- [ ] Smoke tests +- [x] Smoke tests documented in [`../MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`](../MOBILE_PRODUCTION_BUILD_AND_SMOKE.md) - [x] Error-state polish - [x] Build/compile verification - [x] Token compliance review @@ -83,6 +83,7 @@ Stack: React Native + Expo + TypeScript - Mobile now uses token-backed placeholder and border colors instead of raw hardcoded fallbacks. - Expo now boots locally, and `tsconfig.json` was aligned to extend `expo/tsconfig.base`. - Mobile core Expo package versions were aligned to the SDK 55 expectations surfaced during runtime startup. +- Expo production build notes and iOS/Android simulator/device smoke checklist now live in `docs/MOBILE_PRODUCTION_BUILD_AND_SMOKE.md`. - Mobile currently uses provisional product config, but the core quick-capture and note retrieval/edit slice is now wired to the product backend. - Quick capture now persists notes through the product backend instead of saving local-only drafts (`5995b6c`). - Quick capture now exposes live workspace selection directly on the capture screen (`8e57799`).