@codyswann/lisa 2.121.1 → 2.123.0

package/plugins/lisa-expo-copilot/skills/use-dom/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: use-dom
+description: Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally.
+version: 1.0.0
+license: MIT
+---
+
+## What are DOM Components?
+
+DOM components allow web code to run verbatim in a webview on native platforms while rendering as-is on web. This enables using web-only libraries like `recharts`, `react-syntax-highlighter`, or any React web library in your Expo app without modification.
+
+## When to Use DOM Components
+
+Use DOM components when you need:
+
+- **Web-only libraries** — Charts (recharts, chart.js), syntax highlighters, rich text editors, or any library that depends on DOM APIs
+- **Migrating web code** — Bring existing React web components to native without rewriting
+- **Complex HTML/CSS layouts** — When CSS features aren't available in React Native
+- **iframes or embeds** — Embedding external content that requires a browser context
+- **Canvas or WebGL** — Web graphics APIs not available natively
+
+## When NOT to Use DOM Components
+
+Avoid DOM components when:
+
+- **Native performance is critical** — Webviews add overhead
+- **Simple UI** — React Native components are more efficient for basic layouts
+- **Deep native integration** — Use local modules instead for native APIs
+- **Layout routes** — `_layout` files cannot be DOM components
+
+## Basic DOM Component
+
+Create a new file with the `'use dom';` directive at the top:
+
+```tsx
+// components/WebChart.tsx
+"use dom";
+
+export default function WebChart({
+  data,
+}: {
+  data: number[];
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div style={{ padding: 20 }}>
+      <h2>Chart Data</h2>
+      <ul>
+        {data.map((value, i) => (
+          <li key={i}>{value}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Rules for DOM Components
+
+1. **Must have `'use dom';` directive** at the top of the file
+2. **Single default export** — One React component per file
+3. **Own file** — Cannot be defined inline or combined with native components
+4. **Serializable props only** — Strings, numbers, booleans, arrays, plain objects
+5. **Include CSS in the component file** — DOM components run in isolated context
+
+## The `dom` Prop
+
+Every DOM component receives a special `dom` prop for webview configuration. Always type it in your props:
+
+```tsx
+"use dom";
+
+interface Props {
+  content: string;
+  dom: import("expo/dom").DOMProps;
+}
+
+export default function MyComponent({ content }: Props) {
+  return <div>{content}</div>;
+}
+```
+
+### Common `dom` Prop Options
+
+```tsx
+// Disable body scrolling
+<DOMComponent dom={{ scrollEnabled: false }} />
+
+// Flow under the notch (disable safe area insets)
+<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />
+
+// Control size manually
+<DOMComponent dom={{ style: { width: 300, height: 400 } }} />
+
+// Combine options
+<DOMComponent
+  dom={{
+    scrollEnabled: false,
+    contentInsetAdjustmentBehavior: "never",
+    style: { width: '100%', height: 500 }
+  }}
+/>
+```
+
+## Exposing Native Actions to the Webview
+
+Pass async functions as props to expose native functionality to the DOM component:
+
+```tsx
+// app/index.tsx (native)
+import { Alert } from "react-native";
+import DOMComponent from "@/components/dom-component";
+
+export default function Screen() {
+  return (
+    <DOMComponent
+      showAlert={async (message: string) => {
+        Alert.alert("From Web", message);
+      }}
+      saveData={async (data: { name: string; value: number }) => {
+        // Save to native storage, database, etc.
+        console.log("Saving:", data);
+        return { success: true };
+      }}
+    />
+  );
+}
+```
+
+```tsx
+// components/dom-component.tsx
+"use dom";
+
+interface Props {
+  showAlert: (message: string) => Promise<void>;
+  saveData: (data: {
+    name: string;
+    value: number;
+  }) => Promise<{ success: boolean }>;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function DOMComponent({ showAlert, saveData }: Props) {
+  const handleClick = async () => {
+    await showAlert("Hello from the webview!");
+    const result = await saveData({ name: "test", value: 42 });
+    console.log("Save result:", result);
+  };
+
+  return <button onClick={handleClick}>Trigger Native Action</button>;
+}
+```
+
+## Using Web Libraries
+
+DOM components can use any web library:
+
+```tsx
+// components/syntax-highlight.tsx
+"use dom";
+
+import SyntaxHighlighter from "react-syntax-highlighter";
+import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";
+
+interface Props {
+  code: string;
+  language: string;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function SyntaxHighlight({ code, language }: Props) {
+  return (
+    <SyntaxHighlighter language={language} style={docco}>
+      {code}
+    </SyntaxHighlighter>
+  );
+}
+```
+
+```tsx
+// components/chart.tsx
+"use dom";
+
+import {
+  LineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+} from "recharts";
+
+interface Props {
+  data: Array<{ name: string; value: number }>;
+  dom: import("expo/dom").DOMProps;
+}
+
+export default function Chart({ data }: Props) {
+  return (
+    <LineChart width={400} height={300} data={data}>
+      <CartesianGrid strokeDasharray="3 3" />
+      <XAxis dataKey="name" />
+      <YAxis />
+      <Tooltip />
+      <Line type="monotone" dataKey="value" stroke="#8884d8" />
+    </LineChart>
+  );
+}
+```
+
+## CSS in DOM Components
+
+CSS imports must be in the DOM component file since they run in isolated context:
+
+```tsx
+// components/styled-component.tsx
+"use dom";
+
+import "@/styles.css"; // CSS file in same directory
+
+export default function StyledComponent({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div className="container">
+      <h1 className="title">Styled Content</h1>
+    </div>
+  );
+}
+```
+
+Or use inline styles / CSS-in-JS:
+
+```tsx
+"use dom";
+
+const styles = {
+  container: {
+    padding: 20,
+    backgroundColor: "#f0f0f0",
+  },
+  title: {
+    fontSize: 24,
+    color: "#333",
+  },
+};
+
+export default function StyledComponent({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return (
+    <div style={styles.container}>
+      <h1 style={styles.title}>Styled Content</h1>
+    </div>
+  );
+}
+```
+
+## Expo Router in DOM Components
+
+The expo-router `<Link />` component and router API work inside DOM components:
+
+```tsx
+"use dom";
+
+import { Link, useRouter } from "expo-router";
+
+export default function Navigation({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  const router = useRouter();
+
+  return (
+    <nav>
+      <Link href="/about">About</Link>
+      <button onClick={() => router.push("/settings")}>Settings</button>
+    </nav>
+  );
+}
+```
+
+### Router APIs That Require Props
+
+These hooks don't work directly in DOM components because they need synchronous access to native routing state:
+
+- `useLocalSearchParams()`
+- `useGlobalSearchParams()`
+- `usePathname()`
+- `useSegments()`
+- `useRootNavigation()`
+- `useRootNavigationState()`
+
+**Solution:** Read these values in the native parent and pass as props:
+
+```tsx
+// app/[id].tsx (native)
+import { useLocalSearchParams, usePathname } from "expo-router";
+import DOMComponent from "@/components/dom-component";
+
+export default function Screen() {
+  const { id } = useLocalSearchParams();
+  const pathname = usePathname();
+
+  return <DOMComponent id={id as string} pathname={pathname} />;
+}
+```
+
+```tsx
+// components/dom-component.tsx
+"use dom";
+
+interface Props {
+  id: string;
+  pathname: string;
+  dom?: import("expo/dom").DOMProps;
+}
+
+export default function DOMComponent({ id, pathname }: Props) {
+  return (
+    <div>
+      <p>Current ID: {id}</p>
+      <p>Current Path: {pathname}</p>
+    </div>
+  );
+}
+```
+
+## Detecting DOM Environment
+
+Check if code is running in a DOM component:
+
+```tsx
+"use dom";
+
+import { IS_DOM } from "expo/dom";
+
+export default function Component({
+  dom,
+}: {
+  dom?: import("expo/dom").DOMProps;
+}) {
+  return <div>{IS_DOM ? "Running in DOM component" : "Running natively"}</div>;
+}
+```
+
+## Assets
+
+Prefer requiring assets instead of using the public directory:
+
+```tsx
+"use dom";
+
+// Good - bundled with the component
+const logo = require("../assets/logo.png");
+
+export default function Component({
+  dom,
+}: {
+  dom: import("expo/dom").DOMProps;
+}) {
+  return <img src={logo} alt="Logo" />;
+}
+```
+
+## Usage from Native Components
+
+Import and use DOM components like regular components:
+
+```tsx
+// app/index.tsx
+import { View, Text } from "react-native";
+import WebChart from "@/components/web-chart";
+import CodeBlock from "@/components/code-block";
+
+export default function HomeScreen() {
+  return (
+    <View style={{ flex: 1 }}>
+      <Text>Native content above</Text>
+
+      <WebChart data={[10, 20, 30, 40, 50]} dom={{ style: { height: 300 } }} />
+
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        dom={{ scrollEnabled: true }}
+      />
+
+      <Text>Native content below</Text>
+    </View>
+  );
+}
+```
+
+## Platform Behavior
+
+| Platform | Behavior                            |
+| -------- | ----------------------------------- |
+| iOS      | Rendered in WKWebView               |
+| Android  | Rendered in WebView                 |
+| Web      | Rendered as-is (no webview wrapper) |
+
+On web, the `dom` prop is ignored since no webview is needed.
+
+## Tips
+
+- DOM components hot reload during development
+- Keep DOM components focused — don't put entire screens in webviews
+- Use native components for navigation chrome, DOM components for specialized content
+- Test on all platforms — web rendering may differ slightly from native webviews
+- Large DOM components may impact performance — profile if needed
+- The webview has its own JavaScript context — cannot directly share state with native

package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "lisa-expo",
+  "version": "2.123.0",
+  "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "dependencies": [
+    "lisa-typescript"
+  ]
+}

package/plugins/lisa-expo-cursor/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "expo": {
+      "type": "http",
+      "url": "https://mcp.expo.dev/mcp"
+    }
+  }
+}

package/plugins/lisa-expo-cursor/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,57 @@
+# Third-Party Notices
+
+## Official Expo skills (vendored)
+
+The following skills under `skills/` are vendored verbatim from Expo's official
+plugin and are **not** Lisa-authored. Do not hand-edit them; re-vendor from
+upstream to update.
+
+- **Source:** https://github.com/expo/skills (`plugins/expo/skills/`)
+- **Upstream commit:** `510373b50956ef4dc84c20bb4c9cce70b618aa06`
+- **License:** MIT — Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)
+
+Vendored skills:
+
+```
+add-app-clip            expo-cicd-workflows     expo-ui-jetpack-compose
+building-native-ui      expo-deployment         expo-ui-swift-ui
+eas-update-insights     expo-dev-client         native-data-fetching
+expo-api-routes         expo-module             upgrading-expo
+expo-brownfield         expo-tailwind-setup     use-dom
+```
+
+These ship alongside Lisa's own opinionated Expo/React Native skills
+(`apollo-client`, `gluestack-nativewind`, `container-view-pattern`, etc.), which
+they complement rather than replace. Notably both `expo-tailwind-setup`
+(Tailwind v4 / NativeWind v5) and Lisa's `gluestack-nativewind` (Gluestack v3 /
+NativeWind v4) are kept intentionally; choose per project.
+
+The accompanying `expo` MCP server in `.mcp.json` points at Expo's official
+remote server (`https://mcp.expo.dev/mcp`), replacing the previously bundled
+third-party `expo-local-docs-mcp` stdio server.
+
+### MIT License
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2025-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/plugins/lisa-expo-cursor/agents/ops-specialist.md

@@ -0,0 +1,124 @@
+---
+name: ops-specialist
+description: Operations specialist agent for Expo + serverless backend projects. Runs the full stack locally, deploys frontend (EAS) and backend (Serverless), checks logs (local, browser, device, CloudWatch), monitors errors (Sentry), runs browser UAT via Playwright MCP tools, manages database migrations, and performs performance analysis. Self-contained with all operational knowledge.
+tools: Read, Grep, Glob, Bash
+skills:
+  - ops-run-local
+  - ops-deploy
+  - ops-check-logs
+  - ops-verify-health
+  - ops-browser-uat
+  - ops-db-ops
+  - ops-monitor-errors
+  - ops-performance
+---
+
+# Ops Specialist Agent
+
+You are an operations specialist for an Expo + serverless backend application. Your mission is to **run, monitor, deploy, debug, and UAT the application** across local and remote environments. You operate with full operational knowledge embedded in this prompt — you do not need to search for setup instructions.
+
+## Architecture Summary
+
+| Layer | Stack | Key Tech |
+|-------|-------|----------|
+| Frontend | Expo (React Native for Web, iOS, Android) | bun, Apollo Client, Expo Router |
+| Backend | NestJS (Serverless Framework on AWS Lambda) | TypeORM, PostgreSQL, Cognito, Redis, GraphQL |
+| Auth | AWS Cognito | Phone + OTP flow |
+| CI/CD | GitHub Actions | EAS Update (OTA), Serverless deploy |
+| Monitoring | Sentry | Frontend + Backend projects |
+
+## Repository Paths
+
+- **Frontend**: The current project directory (this repo). Use `.` or `$CLAUDE_PROJECT_DIR` in commands.
+- **Backend**: Resolved via the `BACKEND_DIR` environment variable. Defaults to `../backend-v2` (sibling directory convention).
+
+### Path Resolution
+
+All skills use `${BACKEND_DIR:-../backend-v2}` in bash commands. This means:
+- If `BACKEND_DIR` is set, use that path.
+- Otherwise, assume the backend repo is at `../backend-v2` relative to the frontend root.
+
+### Developer Setup
+
+Each developer sets their backend path in `.claude/settings.local.json` (gitignored):
+
+```json
+{
+  "env": {
+    "BACKEND_DIR": "/path/to/your/backend"
+  }
+}
+```
+
+If the backend is a sibling directory named `backend-v2`, no configuration is needed — the default works.
+
+## Project Discovery
+
+On first invocation, discover project-specific values by reading these files:
+
+| Value | Source File | How to Extract |
+|-------|------------|----------------|
+| Environment URLs | `.env.localhost`, `.env.development`, `.env.staging`, `.env.production` | `EXPO_PUBLIC_GRAPHQL_BASE_URL` for backend; frontend URLs from `e2e/constants.ts` |
+| Test credentials | `e2e/constants.ts` | `PHONE_NUMBER` and `OTP` exports |
+| UI selectors | `e2e/selectors.ts` | `selectors` object with all `data-testid` values |
+| Login flow | `e2e/fixtures/auth.fixture.ts` | `createAuthFixture` function with step-by-step login |
+| AWS profiles | Backend `package.json` | Scripts matching `aws:signin:*` pattern |
+| Lambda functions | Backend `package.json` | Scripts matching `logs:*` and `deploy:function:*` patterns |
+| Deploy commands | Backend `package.json` | Scripts matching `deploy:*` pattern |
+| Migration commands | Backend `package.json` | Scripts matching `migration:*` pattern |
+| Sentry config | Frontend `package.json` | `@sentry/react-native` dependency; org/project from `.sentryclirc` or Sentry DSN in `.env.*` |
+| Frontend scripts | Frontend `package.json` | All available `scripts` |
+
+## App Routes
+
+Discover routes from the `app/` directory (Expo Router file-based routing):
+
+| Route | Purpose |
+|-------|---------|
+| `/signin` | Login page |
+| `/confirm-code` | OTP entry |
+| `/` | Home screen |
+
+Read `app/` directory structure to discover all available routes.
+
+## Skills Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `ops-run-local` | Start, stop, restart, or check status of local dev environment |
+| `ops-deploy` | Deploy frontend (EAS) or backend (Serverless) to any environment |
+| `ops-check-logs` | View local, browser, device, or remote CloudWatch logs |
+| `ops-verify-health` | Health check all services across environments |
+| `ops-browser-uat` | Browser-based UAT via Playwright MCP tools |
+| `ops-db-ops` | Database migrations, reverts, schema generation, GraphQL codegen |
+| `ops-monitor-errors` | Monitor Sentry for unresolved errors |
+| `ops-performance` | Lighthouse audits, bundle analysis, k6 load tests |
+
+## Troubleshooting Quick Reference
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| `port 8081 already in use` | Previous Metro bundler running | `lsof -ti :8081 \| xargs kill -9` |
+| `port 3000 already in use` | Previous backend running | `lsof -ti :3000 \| xargs kill -9` |
+| `ExpiredTokenException` | AWS SSO session expired | Run `aws:signin:{env}` script from backend dir |
+| Metro bundler crash | Cache corruption | `bun start:local --clear` |
+| `ECONNREFUSED localhost:3000` | Backend not running | Start backend first, then frontend |
+| Migration fails | Missing AWS credentials | Run `aws:signin:{env}` script before migration |
+| EAS CLI not found | Not installed globally | `npm install -g eas-cli` |
+| `sls` not found | Serverless not installed | `cd $BACKEND_DIR && bun install` |
+| GraphQL schema mismatch | Stale generated types | Run `generate:types:{env}` script |
+| `BACKEND_DIR` not set | Missing env config | Set in `.claude/settings.local.json` or use default `../backend-v2` |
+
+## Rules
+
+- Always verify empirically — never assume something works because the code looks correct
+- Always discover project-specific values from source files before operations
+- Always check prerequisites (ports, AWS credentials, running services) before operations
+- Always resolve `$BACKEND_DIR` before running backend commands — verify the directory exists
+- Never deploy to production without explicit human confirmation
+- Never run destructive database operations without explicit human confirmation
+- Always use test credentials from `e2e/constants.ts` for browser automation
+- Always use the correct `--profile` and `--region` for AWS CLI commands (discover from backend scripts)
+- Always start backend before frontend for full-stack local development
+- Always take screenshots at verification points during browser UAT
+- Always report results in structured tables

package/plugins/lisa-expo-cursor/commands/e2e-coverage-gaps.md

@@ -0,0 +1,7 @@
+---
+description: "Explore gaps in the automated Playwright/e2e suite: inventory the app's routes and existing tests, find routes with no coverage or flows tested only on the happy path (missing error, permission, empty, loading, and edge cases), confirm each in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write. The optional ready flag (default true) controls build-ready vs backlog. For human usability issues, use exploratory-qa instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-expo:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-expo:exploratory-qa. $ARGUMENTS

package/plugins/lisa-expo-cursor/commands/exploratory-qa.md

@@ -0,0 +1,7 @@
+---
+description: "Run a first-time-user exploratory QA walkthrough: experience the app like a brand-new human user, clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent UX, awkward scroll behavior) across all breakpoints, and file each finding (bug or usability issue) as a tracked work item via lisa:tracker-write. The optional ready flag marks tickets build-ready (auto-picked-up by lisa:intake) or leaves them in the backlog for human triage (default). For gaps in the automated Playwright suite, use e2e-coverage-gaps instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-expo:exploratory-qa skill to experience the app like a brand-new first-time user — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand across all breakpoints — and file each finding (bugs, usability/clarity issues) as a tracked work item via lisa:tracker-write, build-ready or in triage per the ready flag (default: triage). For automated Playwright coverage gaps, use /lisa-expo:e2e-coverage-gaps. $ARGUMENTS