@codyswann/lisa 2.121.1 → 2.122.0

package/plugins/lisa-expo-agy/skills/native-data-fetching/references/expo-router-loaders.md

@@ -0,0 +1,344 @@
+# Expo Router Data Loaders
+
+Route-level data loading for web apps using Expo SDK 55+. Loaders are async functions exported from route files that load data before the route renders, following the Remix/React Router loader model.
+
+**Dual execution model:**
+
+- **Initial page load (SSR):** The loader runs server-side. Its return value is serialized as JSON and embedded in the HTML response.
+- **Client-side navigation:** The browser fetches the loader data from the server via HTTP. The route renders once the data arrives.
+
+You write one function and the framework manages when and how it executes.
+
+## Configuration
+
+**Requirements:** Expo SDK 55+, web output mode (`npx expo serve` or `npx expo export --platform web`) set in `app.json` or `app.config.js`.
+
+**Server rendering:**
+
+```json
+{
+  "expo": {
+    "web": {
+      "output": "server"
+    },
+    "plugins": [
+      ["expo-router", {
+        "unstable_useServerDataLoaders": true,
+        "unstable_useServerRendering": true
+      }]
+    ]
+  }
+}
+```
+
+**Static/SSG:**
+
+```json
+{
+  "expo": {
+    "web": {
+      "output": "static"
+    },
+    "plugins": [
+      ["expo-router", {
+        "unstable_useServerDataLoaders": true
+      }]
+    ]
+  }
+}
+```
+
+| | `"server"` | `"static"` |
+|---|-----------|------------|
+| `unstable_useServerDataLoaders` | Required | Required |
+| `unstable_useServerRendering` | Required | Not required |
+| Loader runs on | Live server (every request) | Build time (static generation) |
+| `request` object | Full access (headers, cookies) | Not available |
+| Hosting | Node.js server (EAS Hosting) | Any static host (Netlify, Vercel, S3) |
+
+## Imports
+
+Loaders use two packages:
+
+- **`expo-router`** — `useLoaderData` hook
+- **`expo-server`** — `LoaderFunction` type, `StatusError`, `setResponseHeaders`. Always available (dependency of `expo-router`), no install needed.
+
+## Basic Loader
+
+For loaders without params, a plain async function works:
+
+```tsx
+// app/posts/index.tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { ActivityIndicator, View, Text } from "react-native";
+
+export async function loader() {
+  const response = await fetch("https://api.example.com/posts");
+  const posts = await response.json();
+  return { posts };
+}
+
+function PostList() {
+  const { posts } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      {posts.map((post) => (
+        <Text key={post.id}>{post.title}</Text>
+      ))}
+    </View>
+  );
+}
+
+export default function Posts() {
+  return (
+    <Suspense fallback={<ActivityIndicator size="large" />}>
+      <PostList />
+    </Suspense>
+  );
+}
+```
+
+`useLoaderData` is typed via `typeof loader` — the generic parameter infers the return type.
+
+## Dynamic Routes
+
+For loaders with params, use the `LoaderFunction<T>` type from `expo-server`. The first argument is the request (an immutable `Request`-like object, or `undefined` in static mode). The second is `params` (`Record<string, string | string[]>`), which contains **path parameters only**. Access individual params with a cast like `params.id as string`. For query parameters, use `new URL(request.url).searchParams`:
+
+```tsx
+// app/posts/[id].tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { StatusError, type LoaderFunction } from "expo-server";
+import { ActivityIndicator, View, Text } from "react-native";
+
+type Post = {
+  id: number;
+  title: string;
+  body: string;
+};
+
+export const loader: LoaderFunction<{ post: Post }> = async (
+  request,
+  params,
+) => {
+  const id = params.id as string;
+  const response = await fetch(`https://api.example.com/posts/${id}`);
+
+  if (!response.ok) {
+    throw new StatusError(404, `Post ${id} not found`);
+  }
+
+  const post: Post = await response.json();
+  return { post };
+};
+
+function PostContent() {
+  const { post } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      <Text>{post.title}</Text>
+      <Text>{post.body}</Text>
+    </View>
+  );
+}
+
+export default function PostDetail() {
+  return (
+    <Suspense fallback={<ActivityIndicator size="large" />}>
+      <PostContent />
+    </Suspense>
+  );
+}
+```
+
+Catch-all routes access `params.slug` the same way:
+
+```tsx
+// app/docs/[...slug].tsx
+import { type LoaderFunction } from "expo-server";
+
+type Doc = { title: string; content: string };
+
+export const loader: LoaderFunction<{ doc: Doc }> = async (request, params) => {
+  const slug = params.slug as string[];
+  const path = slug.join("/");
+  const doc = await fetchDoc(path);
+  return { doc };
+};
+```
+
+Query parameters are available via the `request` object (server output mode only):
+
+```tsx
+// app/search.tsx
+import { type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{ results: any[]; query: string }> = async (request) => {
+  if (!request) {
+    return { results: [], query: "" };
+  }
+  // Assuming request.url is `/search?q=expo&page=2`
+  const url = new URL(request.url);
+  const query = url.searchParams.get("q") ?? "";
+  const page = Number(url.searchParams.get("page") ?? "1");
+
+  const results = await fetchSearchResults(query, page);
+  return { results, query };
+};
+```
+
+## Server-Side Secrets & Request Access
+
+Loaders run on the server, so you can access secrets and server-only resources directly:
+
+```tsx
+// app/dashboard.tsx
+import { type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{ balance: any; isAuthenticated: boolean }> = async (
+  request,
+  params,
+) => {
+  const data = await fetch("https://api.stripe.com/v1/balance", {
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+    },
+  });
+
+  const sessionToken = request?.headers.get("cookie")?.match(/session=([^;]+)/)?.[1];
+
+  const balance = await data.json();
+  return { balance, isAuthenticated: !!sessionToken };
+};
+```
+
+The `request` object is available in server output mode. In static output mode, `request` is always `undefined`.
+
+## Response Utilities
+
+### Setting Response Headers
+
+```tsx
+// app/products.tsx
+import { setResponseHeaders } from "expo-server";
+
+export async function loader() {
+  setResponseHeaders({
+    "Cache-Control": "public, max-age=300",
+  });
+
+  const products = await fetchProducts();
+  return { products };
+}
+```
+
+### Throwing HTTP Errors
+
+```tsx
+// app/products/[id].tsx
+import { StatusError, type LoaderFunction } from "expo-server";
+
+export const loader: LoaderFunction<{ product: Product }> = async (request, params) => {
+  const id = params.id as string;
+  const product = await fetchProduct(id);
+
+  if (!product) {
+    throw new StatusError(404, "Product not found");
+  }
+
+  return { product };
+};
+```
+
+## Suspense & Error Boundaries
+
+### Loading States with Suspense
+
+`useLoaderData()` suspends during client-side navigation. Push it into a child component and wrap with `<Suspense>`:
+
+```tsx
+// app/posts/index.tsx
+import { Suspense } from "react";
+import { useLoaderData } from "expo-router";
+import { ActivityIndicator, View, Text } from "react-native";
+
+export async function loader() {
+  const response = await fetch("https://api.example.com/posts");
+  return { posts: await response.json() };
+}
+
+function PostList() {
+  const { posts } = useLoaderData<typeof loader>();
+
+  return (
+    <View>
+      {posts.map((post) => (
+        <Text key={post.id}>{post.title}</Text>
+      ))}
+    </View>
+  );
+}
+
+export default function Posts() {
+  return (
+    <Suspense
+      fallback={
+        <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+          <ActivityIndicator size="large" />
+        </View>
+      }
+    >
+      <PostList />
+    </Suspense>
+  );
+}
+```
+
+The `<Suspense>` boundary must be above the component calling `useLoaderData()`. On initial page load the data is already in the HTML, suspension only occurs during client-side navigation.
+
+### Error Boundaries
+
+```tsx
+// app/posts/[id].tsx
+export function ErrorBoundary({ error }: { error: Error }) {
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <Text>Error: {error.message}</Text>
+    </View>
+  );
+}
+```
+
+When a loader throws (including `StatusError`), the nearest `ErrorBoundary` catches it.
+
+## Static vs Server Rendering
+
+| | Server (`"server"`) | Static (`"static"`) |
+|---|---|---|
+| **When loader runs** | Every request (live) | At build time (`npx expo export`) |
+| **Data freshness** | Fresh on initial server request | Stale until next build |
+| **`request` object** | Full access | Not available |
+| **Hosting** | Node.js server (EAS Hosting) | Any static host |
+| **Use case** | Personalized/dynamic content | Marketing pages, blogs, docs |
+
+**Choose server** when data changes frequently or content is personalized (cookies, auth, headers).
+
+**Choose static** when content is the same for all users and changes infrequently.
+
+## Best Practices
+
+- Loaders are web-only; use client-side fetching (React Query, fetch) for native
+- Loaders cannot be used in `_layout` files — only in route files
+- Use `LoaderFunction<T>` from `expo-server` to type loaders that use params
+- The request object is immutable — use optional chaining (`request?.headers`) as it may be `undefined` in static mode
+- Return only JSON-serializable values (no `Date`, `Map`, `Set`, class instances, functions)
+- Use non-prefixed `process.env` vars for secrets in loaders, not `EXPO_PUBLIC_` (which is embedded in the client bundle)
+- Use `StatusError` from `expo-server` for HTTP error responses
+- Use `setResponseHeaders` from `expo-server` to set headers
+- Export `ErrorBoundary` from route files to handle loader failures gracefully
+- Validate and sanitize user input (params, query strings) before using in database queries or API calls
+- Handle errors gracefully with try/catch; log server-side for debugging
+- Loader data is currently cached for the session. This is a known limitation that will be lifted in a future release

package/plugins/lisa-expo-agy/skills/ops-browser-uat/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ops-browser-uat
+description: Browser-based user acceptance testing via Playwright MCP tools. Logs into the application, navigates through features, and captures visual proof with screenshots.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Browser UAT
+
+Perform browser-based user acceptance testing using Playwright MCP tools.
+
+**Argument**: `$ARGUMENTS` — scenario and environment (e.g., `smoke-test dev`, `login staging`, `player-detail dev`, `custom production /path`)
+
+## Prerequisites
+
+1. **Load Playwright MCP tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser` and load all browser tools.
+2. **Verify target environment is up** — curl check the frontend URL before launching the browser.
+3. **For localhost** — ensure the frontend is running on port 8081.
+
+## Discovery
+
+Before running any scenario, read these project files to discover configuration:
+
+1. **`e2e/constants.ts`** — environment URLs, test credentials (phone, OTP), timeouts, viewports
+2. **`e2e/selectors.ts`** — all `data-testid` values organized by feature area
+3. **`e2e/fixtures/auth.fixture.ts`** — exact login/logout flow to replicate via MCP tools
+4. **`playwright.config.ts`** — video/trace recording config, test directory
+
+## Authentication Procedure
+
+Replicate the login flow from `e2e/fixtures/auth.fixture.ts` using Playwright MCP tools. Read the file to get the exact steps, which typically follow this pattern:
+
+### Login
+
+1. `browser_navigate` to `{BASE_URL}/signin`
+2. `browser_snapshot` to discover page elements
+3. `browser_fill_form` — fill the phone input (discover placeholder text from auth fixture)
+4. Wait for form validation debounce (typically 500ms)
+5. `browser_click` — click the "Next" button
+6. `browser_wait_for` — wait for URL to contain `confirm-code` (timeout from constants)
+7. `browser_snapshot` to discover OTP input
+8. `browser_fill_form` — fill the OTP input (discover testid from selectors, value from constants)
+9. `browser_wait_for` — wait for URL to NOT contain `confirm-code`
+10. `browser_take_screenshot` — capture login proof
+
+### Dismiss Error Overlay
+
+Expo's development error overlay may appear. Dismiss it:
+
+1. `browser_evaluate` with script:
+   ```javascript
+   document.getElementById('error-overlay')?.remove();
+   document.querySelectorAll('[id*="error"]').forEach(el => el.remove());
+   ```
+2. `browser_press_key` — press "Escape" as backup
+
+### Check if Logged In
+
+```javascript
+// browser_evaluate
+localStorage.getItem("@authData") !== null
+```
+
+### Logout
+
+Discover the menu button and sign-out flow from `e2e/selectors.ts` and `e2e/fixtures/auth.fixture.ts`:
+
+1. `browser_click` — menu button element (discover testid from selectors)
+2. `browser_click` — element with text "Sign Out"
+3. `browser_wait_for` — URL contains `signin`
+
+## Selector Reference
+
+Read `e2e/selectors.ts` to get the complete `data-testid` reference for the project. The selectors object is organized by feature area (auth, nav, home sections, player detail, etc.).
+
+Use `[data-testid="{TESTID}"]` to target elements in Playwright MCP tools.
+
+## Built-in UAT Scenarios
+
+### 1. smoke-test
+
+Full app walkthrough. Read `e2e/selectors.ts` to identify which sections and elements to verify:
+
+1. **Login** (auth procedure above)
+2. **Home screen** — verify key sections exist using selectors from the project
+3. **Feature pages** — navigate to 2-3 key routes and verify content loads
+4. **Logout** → verify redirect to signin
+5. Screenshot at each step
+
+### 2. login
+
+Just the login flow with screenshot proof.
+
+### 3. home-screen
+
+Login → verify all home screen sections have data. Screenshot each section.
+
+### 4. custom
+
+Login → navigate to user-specified URL → interact as instructed → screenshot.
+
+## Proof Recording
+
+At each verification point:
+
+1. `browser_take_screenshot` — visual proof of current state
+2. `browser_console_messages` — check for JavaScript errors
+3. `browser_network_requests` — monitor for failed API calls (4xx, 5xx)
+
+## Output Format
+
+Report UAT results as a table:
+
+| Step | Action | Status | Notes |
+|------|--------|--------|-------|
+| 1 | Navigate to /signin | PASS | Page loaded in 1.2s |
+| 2 | Enter phone number | PASS | Input accepted |
+| 3 | Click Next | PASS | Navigated to /confirm-code |
+| 4 | Enter OTP | PASS | OTP accepted |
+| 5 | Verify home screen | PASS | All sections present |
+| 6 | Logout | PASS | Redirected to /signin |
+
+Include total PASS/FAIL count and any JS errors or failed network requests observed.

package/plugins/lisa-expo-agy/skills/ops-check-logs/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: ops-check-logs
+description: Check application logs from local processes, browser console, React Native device logs, or remote AWS CloudWatch. Supports log tailing, filtering, and error searching across all platforms.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Check Logs
+
+View and search logs across all platforms and environments.
+
+**Argument**: `$ARGUMENTS` — target and optional filter (e.g., `dev errors`, `staging api`, `local`, `browser`, `device ios`, `production {function}`)
+
+## Path Convention
+
+- **Frontend**: Current project directory (`.`)
+- **Backend**: `${BACKEND_DIR:-../backend-v2}` — set `BACKEND_DIR` in `.claude/settings.local.json` if your backend is elsewhere
+
+## Discovery
+
+1. Read backend `package.json` to discover `logs:*`, `logs:watch:*`, and `aws:signin:*` scripts
+2. Extract function names from `logs:{env}` scripts (typically set via `FUNCTION_NAME` env var)
+3. Read `.env.{environment}` to find Sentry DSN for error correlation
+
+## Local Process Logs
+
+Local services run in foreground processes. Their logs are captured in the terminal where they were started.
+
+- **Frontend**: stdout from `bun start:local` or `bun start:dev` (Metro bundler)
+- **Backend**: stdout from `IS_OFFLINE=true bun run start:local` (Serverless Offline)
+
+If services were started via the `ops-run-local` skill with `run_in_background`, check the background task output file.
+
+## Browser Console Logs (Expo Web)
+
+For inspecting JavaScript errors, warnings, and `console.log` output in the browser at runtime.
+
+### Via Playwright MCP Tools (automated)
+
+Use when you need to capture browser logs programmatically during UAT or debugging.
+
+1. **Load Playwright tools** — use the current runtime's tool-discovery mechanism to search for `playwright browser`.
+
+2. **Navigate to the app**:
+   - `browser_navigate` to the target URL (discover from `e2e/constants.ts` or `.env.*` files)
+
+3. **Capture console messages**:
+   - `browser_console_messages` — returns all `console.log`, `console.warn`, `console.error` output
+
+4. **Check for failed network requests**:
+   - `browser_network_requests` — shows all HTTP requests including 4xx/5xx failures
+
+5. **Run custom JS to inspect state**:
+   - `browser_evaluate` with script: `JSON.stringify(performance.getEntriesByType('resource').filter(r => r.duration > 1000).map(r => ({name: r.name, duration: r.duration})))`
+
+### Via Browser DevTools (manual)
+
+When a developer is debugging interactively:
+
+1. Open the app in Chrome (`http://localhost:8081`)
+2. Open Chrome DevTools: `Cmd+Option+I` (macOS) or `F12`
+3. **Console tab** — JS errors, warnings, and log output
+4. **Network tab** — failed API requests (filter by `4xx` or `5xx`)
+5. **Performance tab** — runtime performance profiling
+
+## React Native Device Logs
+
+For inspecting logs on iOS and Android devices/simulators when running the native app.
+
+### React Native DevTools (primary — press `j`)
+
+The modern debugging tool for Expo apps (React Native 0.76+):
+
+1. Start the app: `bun start:local` or `bun start:dev`
+2. Press `j` in the Metro terminal to open React Native DevTools
+3. Available tabs:
+   - **Console** — interactive JS console connected to the app
+   - **Sources** — set breakpoints, step through code
+   - **Network** — inspect fetch requests and media loads
+   - **Memory** — heap snapshots and memory profiling
+
+### Expo Developer Menu (press `m`)
+
+Press `m` in the Metro terminal to open the Developer Menu on the connected device:
+- Toggle performance monitor (RAM, JS heap, Views, FPS)
+- Toggle element inspector
+- Open JS debugger
+- Reload app
+
+### iOS Logs
+
+```bash
+# Via Expo CLI (logs appear in Metro terminal automatically)
+# Just run the app — console.log output streams to the terminal
+
+# Via Xcode Console (native-level logs)
+# Open Xcode > Devices and Simulators (Shift+Cmd+2) > Open Console
+
+# Via macOS Console app (simulator logs)
+# Open Console.app > filter by process name
+```
+
+### Android Logs
+
+```bash
+# Via Expo CLI (logs appear in Metro terminal automatically)
+# Just run the app — console.log output streams to the terminal
+
+# Via adb logcat (native-level logs, verbose)
+adb logcat *:E  # Errors only
+adb logcat -s ReactNativeJS  # React Native JS logs only
+adb logcat -s ReactNativeJS:V *:S  # JS logs verbose, suppress everything else
+
+# Via Android Studio Logcat
+# Open Android Studio > View > Tool Windows > Logcat
+# Filter by package name or "ReactNativeJS"
+```
+
+### Production Crash Logs (Device)
+
+For production crash investigation on native platforms:
+- **iOS**: Xcode Crashes Organizer (TestFlight/App Store builds)
+- **Android**: Google Play Console > Crashes section
+- **Both**: Sentry captures JS-level crashes — use `ops-monitor-errors` skill
+
+## Remote Logs (CloudWatch via Serverless Framework)
+
+Discover available log scripts from the backend `package.json` (matching `logs:*` and `logs:watch:*`).
+
+### Prerequisites
+
+```bash
+cd "${BACKEND_DIR:-../backend-v2}"
+bun run aws:signin:{env}
+```
+
+### View Recent Logs
+
+```bash
+cd "${BACKEND_DIR:-../backend-v2}"
+FUNCTION_NAME={fn} bun run logs:{env}
+```
+
+### Tail Logs (follow mode)
+
+```bash
+cd "${BACKEND_DIR:-../backend-v2}"
+FUNCTION_NAME={fn} bun run logs:watch:{env}
+```
+
+## Remote Logs (AWS CLI — Advanced Filtering)
+
+For more advanced filtering, use the AWS CLI directly. Discover the AWS profile from backend `package.json` `aws:signin:*` scripts.
+
+### Discover Log Groups
+
+```bash
+aws logs describe-log-groups \
+  --profile {aws-profile} \
+  --region us-east-1 \
+  --query 'logGroups[].logGroupName' \
+  --output text | tr '\t' '\n'
+```
+
+### Filter for Errors (last 30 minutes)
+
+```bash
+aws logs filter-log-events \
+  --profile {aws-profile} \
+  --region us-east-1 \
+  --log-group-name "{log-group}" \
+  --start-time $(date -v-30M +%s000) \
+  --filter-pattern "ERROR" \
+  --query 'events[].message' \
+  --output text
+```
+
+### Tail Live Logs
+
+```bash
+aws logs tail "{log-group}" \
+  --profile {aws-profile} \
+  --region us-east-1 \
+  --follow \
+  --since 10m
+```
+
+## EAS Build Logs
+
+For frontend build issues:
+
+```bash
+# List recent builds
+eas build:list --limit 5
+
+# View specific build details
+eas build:view {build-id}
+```
+
+## Output Format
+
+Report log findings as:
+
+| Source | Timestamp | Level | Context | Message |
+|--------|-----------|-------|---------|---------|
+| CloudWatch | 2024-01-15T10:30:00Z | ERROR | api | Connection timeout to RDS |
+| Browser | — | ERROR | console | TypeError: Cannot read property 'name' |
+| Device | — | WARN | ReactNativeJS | VirtualizedList: missing keys |
+
+Include a summary of findings: total errors, warnings, and any patterns observed.