@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/expo/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

package/plugins/src/expo/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,
+        },
+      },
+    ],
+  },
+};
+```