@codyswann/lisa 2.121.1 → 2.123.0

package/plugins/lisa-expo-cursor/skills/expo-deployment/references/workflows.md

@@ -0,0 +1,200 @@
+# EAS Workflows
+
+Automate builds, submissions, and deployments with EAS Workflows.
+
+## Web Deployment
+
+Deploy web apps on push to main:
+
+`.eas/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+# https://docs.expo.dev/eas/workflows/syntax/#deploy
+jobs:
+  deploy_web:
+    type: deploy
+    params:
+      prod: true
+```
+
+## PR Previews
+
+### Web PR Previews
+
+```yaml
+name: Web PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  preview:
+    type: deploy
+    params:
+      prod: false
+```
+
+### Native PR Previews with EAS Updates
+
+Deploy OTA updates for pull requests:
+
+```yaml
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  publish:
+    type: update
+    params:
+      branch: "pr-${{ github.event.pull_request.number }}"
+      message: "PR #${{ github.event.pull_request.number }}"
+```
+
+## Production Release
+
+Complete release workflow for both platforms:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build-ios:
+    type: build
+    params:
+      platform: ios
+      profile: production
+
+  build-android:
+    type: build
+    params:
+      platform: android
+      profile: production
+
+  submit-ios:
+    type: submit
+    needs: [build-ios]
+    params:
+      platform: ios
+      profile: production
+
+  submit-android:
+    type: submit
+    needs: [build-android]
+    params:
+      platform: android
+      profile: production
+```
+
+## Build on Push
+
+Trigger builds when pushing to specific branches:
+
+```yaml
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+      - release/*
+
+jobs:
+  build:
+    type: build
+    params:
+      platform: all
+      profile: production
+```
+
+## Conditional Jobs
+
+Run jobs based on conditions:
+
+```yaml
+name: Conditional Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  check-changes:
+    type: run
+    params:
+      command: |
+        if git diff --name-only HEAD~1 | grep -q "^src/"; then
+          echo "has_changes=true" >> $GITHUB_OUTPUT
+        fi
+
+  build:
+    type: build
+    needs: [check-changes]
+    if: needs.check-changes.outputs.has_changes == 'true'
+    params:
+      platform: all
+      profile: production
+```
+
+## Workflow Syntax Reference
+
+### Triggers
+
+```yaml
+on:
+  push:
+    branches: [main, develop]
+    tags: ['v*']
+  pull_request:
+    types: [opened, synchronize, reopened]
+  schedule:
+    - cron: '0 0 * * *'  # Daily at midnight
+  workflow_dispatch:  # Manual trigger
+```
+
+### Job Types
+
+| Type | Purpose |
+|------|---------|
+| `build` | Create app builds |
+| `submit` | Submit to app stores |
+| `update` | Publish OTA updates |
+| `deploy` | Deploy web apps |
+| `run` | Execute custom commands |
+
+### Job Dependencies
+
+```yaml
+jobs:
+  first:
+    type: build
+    params:
+      platform: ios
+
+  second:
+    type: submit
+    needs: [first]  # Runs after 'first' completes
+    params:
+      platform: ios
+```
+
+## Tips
+
+- Use `workflow_dispatch` for manual production releases
+- Combine PR previews with GitHub status checks
+- Use tags for versioned releases
+- Keep sensitive values in EAS Secrets, not workflow files

package/plugins/lisa-expo-cursor/skills/expo-dev-client/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: expo-dev-client
+description: Build and distribute Expo development clients locally or via TestFlight
+version: 1.0.0
+license: MIT
+---
+
+Use EAS Build to create development clients for testing native code changes on physical devices. Use this for creating custom Expo Go clients for testing branches of your app.
+
+## Important: When Development Clients Are Needed
+
+**Only create development clients when your app requires custom native code.** Most apps work fine in Expo Go.
+
+You need a dev client ONLY when using:
+- Local Expo modules (custom native code)
+- Apple targets (widgets, app clips, extensions)
+- Third-party native modules not in Expo Go
+
+**Try Expo Go first** with `npx expo start`. If everything works, you don't need a dev client.
+
+## EAS Configuration
+
+Ensure `eas.json` has a development profile:
+
+```json
+{
+  "cli": {
+    "version": ">= 16.0.1",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "production": {
+      "autoIncrement": true
+    },
+    "development": {
+      "autoIncrement": true,
+      "developmentClient": true
+    }
+  },
+  "submit": {
+    "production": {},
+    "development": {}
+  }
+}
+```
+
+Key settings:
+- `developmentClient: true` - Bundles expo-dev-client for development builds
+- `autoIncrement: true` - Automatically increments build numbers
+- `appVersionSource: "remote"` - Uses EAS as the source of truth for version numbers
+
+## Building for TestFlight
+
+Build iOS dev client and submit to TestFlight in one command:
+
+```bash
+eas build -p ios --profile development --submit
+```
+
+This will:
+1. Build the development client in the cloud
+2. Automatically submit to App Store Connect
+3. Send you an email when the build is ready in TestFlight
+
+After receiving the TestFlight email:
+1. Download the build from TestFlight on your device
+2. Launch the app to see the expo-dev-client UI
+3. Connect to your local Metro bundler or scan a QR code
+
+## Building Locally
+
+Build a development client on your machine:
+
+```bash
+# iOS (requires Xcode)
+eas build -p ios --profile development --local
+
+# Android
+eas build -p android --profile development --local
+```
+
+Local builds output:
+- iOS: `.ipa` file
+- Android: `.apk` or `.aab` file
+
+## Installing Local Builds
+
+Install iOS build on simulator:
+
+```bash
+# Find the .app in the .tar.gz output
+tar -xzf build-*.tar.gz
+xcrun simctl install booted ./path/to/App.app
+```
+
+Install iOS build on device (requires signing):
+
+```bash
+# Use Xcode Devices window or ideviceinstaller
+ideviceinstaller -i build.ipa
+```
+
+Install Android build:
+
+```bash
+adb install build.apk
+```
+
+## Building for Specific Platform
+
+```bash
+# iOS only
+eas build -p ios --profile development
+
+# Android only
+eas build -p android --profile development
+
+# Both platforms
+eas build --profile development
+```
+
+## Checking Build Status
+
+```bash
+# List recent builds
+eas build:list
+
+# View build details
+eas build:view
+```
+
+## Using the Dev Client
+
+Once installed, the dev client provides:
+- **Development server connection** - Enter your Metro bundler URL or scan QR
+- **Build information** - View native build details
+- **Launcher UI** - Switch between development servers
+
+Connect to local development:
+
+```bash
+# Start Metro bundler
+npx expo start --dev-client
+
+# Scan QR code with dev client or enter URL manually
+```
+
+## Troubleshooting
+
+**Build fails with signing errors:**
+```bash
+eas credentials
+```
+
+**Clear build cache:**
+```bash
+eas build -p ios --profile development --clear-cache
+```
+
+**Check EAS CLI version:**
+```bash
+eas --version
+eas update
+```

package/plugins/lisa-expo-cursor/skills/expo-env-config/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: expo-env-config
+description: This skill should be used when creating, modifying, or accessing environment variables in this Expo/React Native codebase. It enforces type-safe, validated environment configuration using Zod schemas. Use this skill when adding new environment variables, setting up env validation, or writing code that reads from process.env.
+---
+
+# Expo Environment Configuration
+
+## Overview
+
+This skill enforces type-safe, validated environment variable management for Expo/React Native using Zod schemas. Environment variables are validated at build time and provide full TypeScript inference, regardless of their source (`.env` files, EAS Build secrets, CI/CD pipelines, or command-line exports).
+
+## Why This Pattern?
+
+Unlike NestJS's `@nestjs/config`, Expo has no official type-safe env solution. The Zod validation pattern provides:
+
+1. **Type safety** - Full TypeScript inference via `z.infer<typeof schema>`
+2. **Build-time validation** - Fails fast with clear error messages before deployment
+3. **Source agnostic** - Works with `.env`, EAS secrets, CI variables
+4. **Testing support** - Easy mocking via module aliases
+
+## Core Pattern
+
+### Environment Schema (`src/lib/env.ts`)
+
+```typescript
+import { z } from "zod";
+
+/**
+ * Environment variable schema with Zod validation.
+ * Variables are validated at module load time.
+ */
+const envSchema = z.object({
+  // Required variables
+  EXPO_PUBLIC_API_URL: z.string().url(),
+  EXPO_PUBLIC_APP_ENV: z.enum(["development", "staging", "production"]),
+
+  // Optional variables with defaults
+  EXPO_PUBLIC_SENTRY_DSN: z.string().optional(),
+  EXPO_PUBLIC_FEATURE_FLAG: z
+    .string()
+    .transform(v => v === "true")
+    .default("false"),
+});
+
+/**
+ * Validated environment configuration.
+ * Throws at module load if validation fails.
+ */
+export const env = envSchema.parse(process.env);
+
+/**
+ * Type-safe environment configuration.
+ */
+export type Env = z.infer<typeof envSchema>;
+```
+
+### Usage in Components/Hooks
+
+```typescript
+import { env } from "@/lib/env";
+
+// Full autocomplete and type safety
+const apiUrl = env.EXPO_PUBLIC_API_URL; // string
+const isDev = env.EXPO_PUBLIC_APP_ENV === "development"; // boolean
+```
+
+## Build-Time Validation (`app.config.ts`)
+
+For variables needed during the build process, validate in `app.config.ts`:
+
+```javascript
+// app.config.ts
+const { z } = require("zod");
+
+const buildEnvSchema = z.object({
+  EXPO_PUBLIC_API_URL: z.string().url(),
+  EXPO_PUBLIC_APP_ENV: z.enum(["development", "staging", "production"]),
+  // Build-only secrets (not exposed to client)
+  SENTRY_AUTH_TOKEN: z.string().optional(),
+});
+
+// Throws during `eas build` if invalid
+const env = buildEnvSchema.parse(process.env);
+
+module.exports = {
+  name: "MyApp",
+  slug: "my-app",
+  extra: {
+    apiUrl: env.EXPO_PUBLIC_API_URL,
+    appEnv: env.EXPO_PUBLIC_APP_ENV,
+  },
+};
+```
+
+## Variable Sources
+
+Environment variables arrive in `process.env` from multiple sources:
+
+| Source | When Available | How Set |
+|--------|----------------|---------|
+| `.env.local` | Local dev | Expo CLI auto-loads |
+| `.env.development` | Local dev | Copied to `.env.local` via npm script |
+| `eas.json` env | EAS Build | `build.production.env` section |
+| EAS Secrets | EAS Build | `eas secret:create` |
+| CI Variables | CI builds | GitHub Actions / GitLab CI settings |
+
+The Zod pattern validates `process.env` directly - it doesn't care how variables got there.
+
+## Testing Pattern
+
+### Jest Setup (`jest.setup.local.ts`)
+
+```typescript
+// Mock the env module for all tests
+jest.mock("@/lib/env", () => ({
+  env: {
+    EXPO_PUBLIC_API_URL: "https://test.example.com",
+    EXPO_PUBLIC_APP_ENV: "development",
+    EXPO_PUBLIC_SENTRY_DSN: undefined,
+    EXPO_PUBLIC_FEATURE_FLAG: false,
+  },
+}));
+```
+
+### Override in Specific Tests
+
+```typescript
+import { env } from "@/lib/env";
+
+jest.mock("@/lib/env");
+
+describe("ProductionFeature", () => {
+  beforeEach(() => {
+    (env as jest.Mocked<typeof env>).EXPO_PUBLIC_APP_ENV = "production";
+  });
+
+  it("should behave differently in production", () => {
+    // Test production-specific behavior
+  });
+});
+```
+
+## ESLint Enforcement
+
+This pattern is enforced by ESLint's `no-restricted-syntax` rule in `eslint.config.mjs`:
+
+```javascript
+"no-restricted-syntax": [
+  "error",
+  {
+    selector: "MemberExpression[object.name='process'][property.name='env']",
+    message: "Direct process.env access is forbidden. Import { env } from '@/lib/env' instead.",
+  },
+],
+```
+
+**Exceptions** (files allowed to use `process.env`):
+- `lib/env.ts` - The env validation module itself
+- `app.config.ts` - Expo build config
+- `codegen.ts` - GraphQL codegen config
+- `playwright.config.ts` - E2E test config
+- `lighthouserc.js` - Lighthouse CI config
+
+## Core Rules
+
+### 1. Always Prefix with EXPO_PUBLIC_
+
+Variables without this prefix are not available in client code:
+
+```typescript
+// CORRECT - available in client
+EXPO_PUBLIC_API_URL=https://api.example.com
+
+// INCORRECT - only available at build time
+API_URL=https://api.example.com
+```
+
+### 2. Never Access process.env Directly
+
+Always use the validated `env` object:
+
+```typescript
+// CORRECT - type-safe, validated
+import { env } from "@/lib/env";
+const url = env.EXPO_PUBLIC_API_URL;
+
+// INCORRECT - untyped, unvalidated
+const url = process.env.EXPO_PUBLIC_API_URL;
+```
+
+### 3. Validate Early, Fail Fast
+
+Validation happens at module load. If a required variable is missing, the app fails immediately with a clear error rather than at runtime.
+
+### 4. Use Transforms for Non-String Types
+
+Environment variables are always strings. Use Zod transforms:
+
+```typescript
+const envSchema = z.object({
+  // Boolean from string
+  EXPO_PUBLIC_DEBUG: z
+    .string()
+    .transform(v => v === "true")
+    .default("false"),
+
+  // Number from string
+  EXPO_PUBLIC_TIMEOUT_MS: z
+    .string()
+    .transform(v => parseInt(v, 10))
+    .default("5000"),
+
+  // Array from comma-separated string
+  EXPO_PUBLIC_ALLOWED_HOSTS: z
+    .string()
+    .transform(v => v.split(",").map(s => s.trim()))
+    .default(""),
+});
+```
+
+### 5. Separate Client vs Build-Only Variables
+
+Keep sensitive build-time variables out of the client schema:
+
+```typescript
+// Client variables (embedded in JS bundle)
+const clientSchema = z.object({
+  EXPO_PUBLIC_API_URL: z.string().url(),
+});
+
+// Build-only variables (NOT in bundle)
+const buildSchema = z.object({
+  SENTRY_AUTH_TOKEN: z.string(),
+  EAS_PROJECT_ID: z.string(),
+});
+```
+
+## File Organization
+
+```
+src/
+  lib/
+    env.ts              # Main env schema and exports
+app.config.ts           # Build-time validation (if needed)
+.env.localhost          # Local development (git-ignored)
+.env.development        # Development environment
+.env.staging            # Staging environment
+.env.production         # Production environment
+```
+
+## Detailed Reference
+
+For comprehensive patterns, transforms, and testing examples:
+
+- **[references/validation-patterns.md](references/validation-patterns.md)** - Advanced Zod schemas, transforms, and refinements
+
+## Anti-Patterns to Avoid
+
+### Never use process.env directly in components
+
+```typescript
+// WRONG - untyped, could be undefined
+const Component = () => {
+  const url = process.env.EXPO_PUBLIC_API_URL;
+  // url is string | undefined, no validation
+};
+
+// CORRECT - validated and typed
+import { env } from "@/lib/env";
+const Component = () => {
+  const url = env.EXPO_PUBLIC_API_URL;
+  // url is string, guaranteed to be valid URL
+};
+```
+
+### Never skip validation for "simple" variables
+
+```typescript
+// WRONG - skipping validation
+export const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
+
+// CORRECT - always validate
+const envSchema = z.object({
+  EXPO_PUBLIC_API_URL: z.string().url().default("http://localhost:3000"),
+});
+export const { EXPO_PUBLIC_API_URL: API_URL } = envSchema.parse(process.env);
+```
+
+### Never store secrets in EXPO_PUBLIC_ variables
+
+```typescript
+// WRONG - secrets exposed in client bundle
+EXPO_PUBLIC_API_SECRET=super-secret-key
+
+// CORRECT - secrets only at build time, passed securely
+SENTRY_AUTH_TOKEN=secret  # Build-only, not in bundle
+```
+
+## Validation Checklist
+
+When adding or modifying environment variables:
+
+- [ ] Variable is prefixed with `EXPO_PUBLIC_` (if needed in client code)
+- [ ] Variable is added to the Zod schema in `src/lib/env.ts`
+- [ ] Appropriate Zod type/transform is used (url, enum, boolean transform, etc.)
+- [ ] Default value provided for optional variables
+- [ ] Jest mock updated in `jest.setup.local.ts`
+- [ ] Variable documented in `.env.example` or `.env.development`
+- [ ] Sensitive values use EAS Secrets, not `.env` files