@codyswann/lisa 2.121.1 → 2.122.0

package/plugins/lisa-expo-cursor/skills/expo-env-config/references/validation-patterns.md

@@ -0,0 +1,417 @@
+# Environment Validation Patterns
+
+Advanced Zod patterns for environment variable validation in Expo/React Native.
+
+## Complete Schema Example
+
+```typescript
+import { z } from "zod";
+
+/**
+ * Transforms a string "true"/"false" to boolean.
+ */
+const booleanString = z
+  .string()
+  .transform(v => v.toLowerCase() === "true")
+  .default("false");
+
+/**
+ * Transforms a string to number with validation.
+ */
+const numberString = (defaultValue: number) =>
+  z
+    .string()
+    .transform(v => {
+      const parsed = parseInt(v, 10);
+      if (isNaN(parsed)) {
+        throw new Error(`Invalid number: ${v}`);
+      }
+      return parsed;
+    })
+    .default(String(defaultValue));
+
+/**
+ * Transforms comma-separated string to array.
+ */
+const arrayString = z
+  .string()
+  .transform(v => (v ? v.split(",").map(s => s.trim()) : []))
+  .default("");
+
+/**
+ * Complete environment schema.
+ */
+const envSchema = z.object({
+  // Required strings
+  EXPO_PUBLIC_API_URL: z.string().url(),
+  EXPO_PUBLIC_APP_ENV: z.enum(["development", "staging", "production"]),
+
+  // Optional strings
+  EXPO_PUBLIC_SENTRY_DSN: z.string().url().optional(),
+  EXPO_PUBLIC_ANALYTICS_ID: z.string().optional(),
+
+  // Booleans (from string)
+  EXPO_PUBLIC_DEBUG_MODE: booleanString,
+  EXPO_PUBLIC_FEATURE_NEW_UI: booleanString,
+
+  // Numbers (from string)
+  EXPO_PUBLIC_API_TIMEOUT_MS: numberString(5000),
+  EXPO_PUBLIC_MAX_RETRIES: numberString(3),
+
+  // Arrays (from comma-separated string)
+  EXPO_PUBLIC_ALLOWED_ORIGINS: arrayString,
+
+  // Conditional/derived
+  EXPO_PUBLIC_LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+export const env = envSchema.parse(process.env);
+export type Env = z.infer<typeof envSchema>;
+```
+
+## Common Transforms
+
+### Boolean from String
+
+```typescript
+// Handles "true", "TRUE", "True", etc.
+const booleanEnv = z
+  .string()
+  .transform(v => v.toLowerCase() === "true")
+  .default("false");
+
+// Usage
+EXPO_PUBLIC_FEATURE_FLAG: booleanEnv,
+```
+
+### Number from String
+
+```typescript
+// With validation
+const numberEnv = z.string().transform((v, ctx) => {
+  const parsed = parseInt(v, 10);
+  if (isNaN(parsed)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Must be a valid number",
+    });
+    return z.NEVER;
+  }
+  return parsed;
+});
+
+// With default
+const numberWithDefault = (def: number) =>
+  z
+    .string()
+    .optional()
+    .transform(v => (v ? parseInt(v, 10) : def));
+```
+
+### Array from Comma-Separated String
+
+```typescript
+const arrayEnv = z
+  .string()
+  .transform(v =>
+    v
+      .split(",")
+      .map(s => s.trim())
+      .filter(Boolean)
+  )
+  .default("");
+
+// Example: "host1.com, host2.com" -> ["host1.com", "host2.com"]
+```
+
+### URL with Protocol Validation
+
+```typescript
+const httpUrl = z.string().url().refine(
+  url => url.startsWith("https://") || url.startsWith("http://"),
+  { message: "Must be an HTTP(S) URL" }
+);
+
+// HTTPS only in production
+const secureUrl = z.string().url().refine(
+  url => {
+    if (process.env.EXPO_PUBLIC_APP_ENV === "production") {
+      return url.startsWith("https://");
+    }
+    return true;
+  },
+  { message: "Production URLs must use HTTPS" }
+);
+```
+
+## Environment-Specific Defaults
+
+```typescript
+const getDefaultApiUrl = () => {
+  switch (process.env.EXPO_PUBLIC_APP_ENV) {
+    case "production":
+      return "https://api.example.com";
+    case "staging":
+      return "https://staging-api.example.com";
+    default:
+      return "http://localhost:3000";
+  }
+};
+
+const envSchema = z.object({
+  EXPO_PUBLIC_API_URL: z.string().url().default(getDefaultApiUrl()),
+});
+```
+
+## Refinements and Cross-Field Validation
+
+```typescript
+const envSchema = z
+  .object({
+    EXPO_PUBLIC_APP_ENV: z.enum(["development", "staging", "production"]),
+    EXPO_PUBLIC_DEBUG_MODE: booleanString,
+    EXPO_PUBLIC_SENTRY_DSN: z.string().url().optional(),
+  })
+  .refine(
+    data => {
+      // Sentry DSN required in production
+      if (data.EXPO_PUBLIC_APP_ENV === "production") {
+        return !!data.EXPO_PUBLIC_SENTRY_DSN;
+      }
+      return true;
+    },
+    {
+      message: "EXPO_PUBLIC_SENTRY_DSN is required in production",
+      path: ["EXPO_PUBLIC_SENTRY_DSN"],
+    }
+  )
+  .refine(
+    data => {
+      // Debug mode forbidden in production
+      if (data.EXPO_PUBLIC_APP_ENV === "production") {
+        return !data.EXPO_PUBLIC_DEBUG_MODE;
+      }
+      return true;
+    },
+    {
+      message: "Debug mode cannot be enabled in production",
+      path: ["EXPO_PUBLIC_DEBUG_MODE"],
+    }
+  );
+```
+
+## Error Handling
+
+### Custom Error Messages
+
+```typescript
+const envSchema = z.object({
+  EXPO_PUBLIC_API_URL: z
+    .string({
+      required_error: "API URL is required. Set EXPO_PUBLIC_API_URL in your .env file.",
+    })
+    .url({
+      message: "API URL must be a valid URL (e.g., https://api.example.com)",
+    }),
+});
+```
+
+### Graceful Error Formatting
+
+```typescript
+const parseEnv = () => {
+  const result = envSchema.safeParse(process.env);
+
+  if (!result.success) {
+    const formatted = result.error.issues
+      .map(issue => `  - ${issue.path.join(".")}: ${issue.message}`)
+      .join("\n");
+
+    throw new Error(`Environment validation failed:\n${formatted}`);
+  }
+
+  return result.data;
+};
+
+export const env = parseEnv();
+```
+
+## Testing Patterns
+
+### Complete Mock Setup
+
+```typescript
+// jest.setup.local.ts
+const mockEnv = {
+  EXPO_PUBLIC_API_URL: "https://test.example.com",
+  EXPO_PUBLIC_APP_ENV: "development" as const,
+  EXPO_PUBLIC_DEBUG_MODE: false,
+  EXPO_PUBLIC_FEATURE_NEW_UI: true,
+  EXPO_PUBLIC_API_TIMEOUT_MS: 5000,
+  EXPO_PUBLIC_MAX_RETRIES: 3,
+  EXPO_PUBLIC_ALLOWED_ORIGINS: ["localhost"],
+  EXPO_PUBLIC_LOG_LEVEL: "info" as const,
+  EXPO_PUBLIC_SENTRY_DSN: undefined,
+  EXPO_PUBLIC_ANALYTICS_ID: undefined,
+};
+
+jest.mock("@/lib/env", () => ({
+  env: mockEnv,
+}));
+```
+
+### Override for Specific Tests
+
+```typescript
+// In test file
+import { env } from "@/lib/env";
+
+jest.mock("@/lib/env");
+
+const mockEnv = env as jest.Mocked<typeof env>;
+
+describe("Feature with production behavior", () => {
+  beforeEach(() => {
+    mockEnv.EXPO_PUBLIC_APP_ENV = "production";
+    mockEnv.EXPO_PUBLIC_DEBUG_MODE = false;
+  });
+
+  afterEach(() => {
+    mockEnv.EXPO_PUBLIC_APP_ENV = "development";
+  });
+
+  it("should disable debug features in production", () => {
+    // Test production-specific behavior
+  });
+});
+```
+
+### Testing Validation Itself
+
+```typescript
+// env.test.ts
+describe("Environment Schema Validation", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it("should throw for missing required variables", () => {
+    delete process.env.EXPO_PUBLIC_API_URL;
+
+    expect(() => {
+      require("@/lib/env");
+    }).toThrow(/EXPO_PUBLIC_API_URL/);
+  });
+
+  it("should throw for invalid URL format", () => {
+    process.env.EXPO_PUBLIC_API_URL = "not-a-url";
+
+    expect(() => {
+      require("@/lib/env");
+    }).toThrow(/url/i);
+  });
+
+  it("should use defaults for optional variables", () => {
+    process.env.EXPO_PUBLIC_API_URL = "https://api.example.com";
+    process.env.EXPO_PUBLIC_APP_ENV = "development";
+
+    const { env } = require("@/lib/env");
+
+    expect(env.EXPO_PUBLIC_DEBUG_MODE).toBe(false);
+    expect(env.EXPO_PUBLIC_API_TIMEOUT_MS).toBe(5000);
+  });
+});
+```
+
+## EAS Build Integration
+
+### eas.json Configuration
+
+```json
+{
+  "build": {
+    "development": {
+      "env": {
+        "EXPO_PUBLIC_APP_ENV": "development",
+        "EXPO_PUBLIC_API_URL": "https://dev-api.example.com"
+      }
+    },
+    "staging": {
+      "env": {
+        "EXPO_PUBLIC_APP_ENV": "staging",
+        "EXPO_PUBLIC_API_URL": "https://staging-api.example.com"
+      }
+    },
+    "production": {
+      "env": {
+        "EXPO_PUBLIC_APP_ENV": "production",
+        "EXPO_PUBLIC_API_URL": "https://api.example.com"
+      }
+    }
+  }
+}
+```
+
+### EAS Secrets for Sensitive Values
+
+```bash
+# Set secrets via CLI (not in eas.json)
+eas secret:create --name SENTRY_AUTH_TOKEN --value "your-token"
+eas secret:create --name GOOGLE_SERVICES_JSON --type file --value ./google-services.json
+```
+
+## app.config.ts Build-Time Validation
+
+```javascript
+// app.config.ts
+const { z } = require("zod");
+
+// Validate at build time
+const buildSchema = z.object({
+  EXPO_PUBLIC_API_URL: z.string().url(),
+  EXPO_PUBLIC_APP_ENV: z.enum(["development", "staging", "production"]),
+  // Build-only (not exposed to client)
+  SENTRY_AUTH_TOKEN: z.string().optional(),
+  EAS_PROJECT_ID: z.string().optional(),
+});
+
+const result = buildSchema.safeParse(process.env);
+
+if (!result.success) {
+  console.error("Build environment validation failed:");
+  result.error.issues.forEach(issue => {
+    console.error(`  - ${issue.path.join(".")}: ${issue.message}`);
+  });
+  throw new Error("Invalid build environment");
+}
+
+const env = result.data;
+
+module.exports = {
+  name: "MyApp",
+  slug: "my-app",
+  version: "1.0.0",
+  extra: {
+    eas: {
+      projectId: env.EAS_PROJECT_ID,
+    },
+  },
+  hooks: {
+    postPublish: [
+      {
+        file: "sentry-expo/upload-sourcemaps",
+        config: {
+          authToken: env.SENTRY_AUTH_TOKEN,
+        },
+      },
+    ],
+  },
+};
+```

package/plugins/lisa-expo-cursor/skills/expo-module/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: expo-module
+description: Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo.
+version: 1.0.0
+license: MIT
+---
+
+# Writing Expo Modules
+
+Complete reference for building native modules and views using the Expo Modules API. Covers Swift (iOS), Kotlin (Android), and TypeScript.
+
+## When to Use
+
+- Creating a new Expo native module or native view
+- Adding native functionality (camera, sensors, system APIs) to an Expo app
+- Wrapping platform SDKs for React Native consumption
+- Building config plugins that modify native project files
+- Adding Android, Apple, or web support to an existing Expo module
+- Editing `expo-module.config.json`, config plugins, or lifecycle hooks
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  create-expo-module.md      Scaffolding and add-platform-support workflow, defaults, and quirks
+  native-module.md           Module definition DSL: Name, Function, AsyncFunction, Property, Constant, Events, type system, shared objects
+  native-view.md             Native view components: View, Prop, EventDispatcher, view lifecycle, ref-based functions
+  lifecycle.md               Lifecycle hooks: module, iOS app/AppDelegate, Android activity/application listeners
+  config-plugin.md           Config plugins: modifying Info.plist, AndroidManifest.xml, reading values in native code
+  module-config.md           expo-module.config.json fields, file placement, and autolinking behavior
+```
+
+## Quick Start
+
+Prefer `create-expo-module` over manually creating native module files and directories. In practice, the best path is usually to create the scaffold first and then build on top of it. The scaffold sets up the expected layout, `expo-module.config.json`, podspec or Gradle files, TypeScript bindings, and the standalone example app flow.
+
+If an existing Expo module only needs another platform, use `create-expo-module add-platform-support` instead of manually copying native directories.
+
+See [references/create-expo-module.md](references/create-expo-module.md) before scaffolding or extending a module. It covers:
+
+- local vs standalone modules
+- `--platform`, `--features`, `--barrel`, `--package-manager`, and non-interactive mode
+- `expo.autolinking.nativeModulesDir`
+- `add-platform-support` behavior and quirks
+
+## Recommended Workflow
+
+1. Choose the scaffold type first:
+   - **Local module** for one app
+   - **Standalone module** for reuse, monorepos, or publishing
+2. Determine native `expo-module` features that you will need.
+   - Based on the user's instructions determine which feature scaffolding will be useful.
+   - Available features: `Constant`, `Function`, `AsyncFunction`, `Event`, `View`, `ViewEvent`, `SharedObject`
+3. Scaffold deliberately:
+   - pass an explicit slug or path
+   - choose `--platform` intentionally instead of relying on defaults
+   - use `--features` to choose code samples which you will modify in the next step to match the real implementation.
+4. Replace generated example code with the real implementation.
+5. If you add a new platform later, prefer `add-platform-support` over manual file copying.
+
+## Practical Scaffolding Rules
+
+- Feature examples are **opt-in**. A newly scaffolded module may be minimal if no features were selected.
+- `ViewEvent` implies `View`.
+- Local modules do **not** generate an `index.ts` barrel by default. Use `--barrel` only if you want one.
+- In non-interactive local scaffolding, pass the positional slug or path explicitly. `--name` changes the native class name, not the folder name.
+- Local modules live in `expo.autolinking.nativeModulesDir` when configured, otherwise in `modules/`.
+- Standalone modules have their own package metadata, scripts, and usually an example app. Local modules use the host app's tooling instead.
+
+## Core File Shapes
+
+The Swift and Kotlin DSL share the same structure. Swift is usually the clearest primary example; consult the references for feature-specific details.
+
+## Module Structure Reference
+
+The Swift and Kotlin DSL share the same structure. Both platforms are shown here for reference — in other reference files, Swift is shown as the primary language unless the Kotlin pattern meaningfully differs.
+
+**Swift (iOS):**
+
+```swift
+import ExpoModulesCore
+
+public class MyModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("MyModule")
+
+    Function("hello") { (name: String) -> String in
+      return "Hello \(name)!"
+    }
+  }
+}
+```
+
+**Kotlin (Android):**
+
+```kotlin
+package expo.modules.mymodule
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class MyModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("MyModule")
+
+    Function("hello") { name: String ->
+      "Hello $name!"
+    }
+  }
+}
+```
+
+**TypeScript:**
+
+```typescript
+import { requireNativeModule } from "expo";
+
+const MyModule = requireNativeModule("MyModule");
+
+export function hello(name: string): string {
+  return MyModule.hello(name);
+}
+```
+
+### expo-module.config.json
+
+```json
+{
+  "platforms": ["android", "apple"],
+  "apple": {
+    "modules": ["MyModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.mymodule.MyModule"]
+  }
+}
+```
+
+Note: iOS uses just the class name; Android uses the fully-qualified class name (package + class). See `references/module-config.md` for all fields.

package/plugins/lisa-expo-cursor/skills/expo-module/references/config-plugin.md

@@ -0,0 +1,90 @@
+# Config Plugins Reference
+
+Config plugins customize native Android and iOS projects generated with `npx expo prebuild`. They are synchronous functions that accept an `ExpoConfig` and return a modified version.
+
+## Plugin Structure
+
+```
+my-module/
+  plugin/
+    tsconfig.json
+    src/
+      index.ts
+  app.plugin.js         # Entry: module.exports = require('./plugin/build');
+```
+
+## Writing a Plugin
+
+Plugin functions follow the `with` prefix naming convention.
+
+```typescript
+import {
+  ConfigPlugin,
+  withInfoPlist,
+  withAndroidManifest,
+  AndroidConfig,
+} from "expo/config-plugins";
+
+const withMyConfig: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
+  // iOS: modify Info.plist
+  config = withInfoPlist(config, (config) => {
+    config.modResults["MY_API_KEY"] = apiKey;
+    return config;
+  });
+
+  // Android: modify AndroidManifest.xml
+  config = withAndroidManifest(config, (config) => {
+    const mainApp =
+      AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
+    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
+      mainApp,
+      "MY_API_KEY",
+      apiKey
+    );
+    return config;
+  });
+
+  return config;
+};
+
+export default withMyConfig;
+```
+
+## Using in app.json
+
+```json
+{
+  "expo": {
+    "plugins": [["my-module", { "apiKey": "secret_key" }]]
+  }
+}
+```
+
+## Reading Config Values in Native Code
+
+**Swift:**
+
+```swift
+Function("getApiKey") {
+  return Bundle.main.object(forInfoDictionaryKey: "MY_API_KEY") as? String
+}
+```
+
+**Kotlin:**
+
+```kotlin
+Function("getApiKey") {
+  val appInfo = appContext?.reactContext?.packageManager?.getApplicationInfo(
+    appContext?.reactContext?.packageName.toString(),
+    PackageManager.GET_META_DATA
+  )
+  return@Function appInfo?.metaData?.getString("MY_API_KEY")
+}
+```
+
+## Key Rules
+
+- Plugins must be synchronous; return values must be serializable (except `mods`)
+- `Mods` are async functions invoked during the prebuild "syncing" phase
+- Use `npm run build plugin` to compile TypeScript plugins
+- Test with `npx expo prebuild --clean`