erne-universal 0.1.0

package/rules/bare-rn/testing.md

@@ -0,0 +1,78 @@
+---
+description: Testing patterns for bare React Native projects
+globs: "**/*.test.{ts,tsx}"
+alwaysApply: false
+---
+
+# Bare React Native Testing
+
+## Native Unit Tests
+Run native tests alongside JS tests for full coverage:
+
+### iOS (XCTest)
+```swift
+// ios/MyAppTests/MyModuleTests.swift
+import XCTest
+@testable import MyApp
+
+class MyModuleTests: XCTestCase {
+    func testDataProcessing() {
+        let module = MyModule()
+        let result = module.processData("input")
+        XCTAssertEqual(result, "expected_output")
+    }
+}
+```
+
+### Android (JUnit)
+```kotlin
+// android/app/src/test/java/com/myapp/MyModuleTest.kt
+import org.junit.Test
+import org.junit.Assert.*
+
+class MyModuleTest {
+    @Test
+    fun testDataProcessing() {
+        val module = MyModule()
+        val result = module.processData("input")
+        assertEquals("expected_output", result)
+    }
+}
+```
+
+## E2E with Detox (Bare Setup)
+- Configure Detox directly in project (no EAS Build needed)
+- Build test binaries locally: `detox build --configuration ios.sim.debug`
+- Run: `detox test --configuration ios.sim.debug`
+
+```js
+// .detoxrc.js
+module.exports = {
+  testRunner: { args: { config: 'e2e/jest.config.js' } },
+  apps: {
+    'ios.debug': {
+      type: 'ios.app',
+      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/MyApp.app',
+      build: 'xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build',
+    },
+    'android.debug': {
+      type: 'android.apk',
+      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
+      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
+    },
+  },
+  devices: {
+    simulator: { type: 'ios.simulator', device: { type: 'iPhone 16' } },
+    emulator: { type: 'android.emulator', device: { avdName: 'Pixel_7' } },
+  },
+  configurations: {
+    'ios.sim.debug': { device: 'simulator', app: 'ios.debug' },
+    'android.emu.debug': { device: 'emulator', app: 'android.debug' },
+  },
+};
+```
+
+## Integration Testing
+- Test native module bridges with integration tests
+- Verify Turbo Module codegen output matches specs
+- Test platform-specific behavior on both iOS and Android

package/rules/common/coding-style.md

@@ -0,0 +1,50 @@
+---
+description: TypeScript and React Native coding style conventions — enforced for all project types
+globs: "**/*.{ts,tsx,js,jsx}"
+alwaysApply: false
+---
+
+# Coding Style
+
+## TypeScript
+- Enable `strict` mode in tsconfig.json
+- No `any` types — use `unknown` + type guards or proper generics
+- Use type inference where possible; annotate function signatures explicitly
+- Prefer `interface` for object shapes, `type` for unions/intersections
+- Use `as const` for literal types instead of enums
+
+## Components
+- Functional components only — no class components
+- Named exports only — no default exports
+- One component per file (colocated helpers are fine)
+- Props interface named `[Component]Props` (e.g., `ButtonProps`)
+- Destructure props in function signature
+
+```tsx
+// GOOD
+export function UserCard({ name, avatar }: UserCardProps) { ... }
+
+// BAD
+export default class UserCard extends Component { ... }
+```
+
+## File Naming
+- Components: `PascalCase.tsx` (e.g., `UserCard.tsx`)
+- Hooks: `camelCase.ts` prefixed with `use` (e.g., `useAuth.ts`)
+- Utils/helpers: `camelCase.ts` (e.g., `formatDate.ts`)
+- Types: `camelCase.ts` or colocated in component file
+- Tests: `[name].test.ts(x)` adjacent to source
+- Platform-specific: `[name].ios.tsx` / `[name].android.tsx`
+
+## Imports
+- Use path aliases (`@/` maps to `src/`)
+- No barrel files (`index.ts` re-exports) — import directly
+- Group imports: react → react-native → expo → third-party → local
+- Use `import type` for type-only imports
+
+## General
+- Max line length: 100 characters (Prettier enforced)
+- Trailing commas in multiline structures
+- Single quotes for strings
+- Semicolons required
+- No `var` — use `const` by default, `let` when reassignment needed

package/rules/common/development-workflow.md

@@ -0,0 +1,55 @@
+---
+description: Development environment and workflow conventions
+globs: ""
+alwaysApply: true
+---
+
+# Development Workflow
+
+## Development Client
+- Use `expo-dev-client` instead of Expo Go for projects with native modules
+- Expo Go is fine for pure JS/TS projects without custom native code
+- Create development builds: `eas build --profile development`
+
+## Build Profiles
+
+| Profile | Use Case | Command |
+|---------|----------|---------|
+| development | Local testing with dev tools | `eas build --profile development` |
+| preview | QA testing, stakeholder review | `eas build --profile preview` |
+| production | App Store / Play Store release | `eas build --profile production` |
+
+## Environment Management
+- `.env.development`, `.env.preview`, `.env.production`
+- Use `expo-constants` to access env vars at runtime
+- Never commit `.env` files (add to `.gitignore`)
+- Use EAS Secrets for CI/CD environment variables
+
+## Local Development
+```bash
+# Start Metro bundler
+npx expo start
+
+# Run on specific platform
+npx expo run:ios
+npx expo run:android
+
+# Clear cache when things break
+npx expo start --clear
+
+# Regenerate native projects
+npx expo prebuild --clean
+```
+
+## Debugging
+- Use React Native DevTools (built-in with Expo SDK 50+)
+- Console.log for quick debugging (remove before commit)
+- React DevTools for component inspection
+- Flipper/React Native Debugger for network and performance
+- `LogBox.ignoreLogs()` only for known harmless warnings
+
+## CI/CD
+- EAS Build for cloud builds
+- EAS Submit for store submissions
+- EAS Update for OTA updates (non-native changes)
+- GitHub Actions for lint/test/typecheck on PRs

package/rules/common/git-workflow.md

@@ -0,0 +1,40 @@
+---
+description: Git workflow and commit conventions
+globs: ""
+alwaysApply: true
+---
+
+# Git Workflow
+
+## Commit Messages
+Follow Conventional Commits:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`
+
+Examples:
+- `feat(auth): add biometric login support`
+- `fix(navigation): prevent double-tap on tab bar`
+- `perf(list): switch FlatList to FlashList for feed`
+
+## Branch Naming
+- Feature: `feat/short-description`
+- Fix: `fix/issue-number-description`
+- Chore: `chore/description`
+
+## PR Guidelines
+- Keep PRs under 400 lines when possible
+- One logical change per PR
+- Include screenshots/recordings for UI changes
+- Update tests for changed behavior
+- Run full test suite before requesting review
+
+## Hooks Integration
+The `pre-commit-lint.js` hook runs ESLint + Prettier on staged files before commit.

package/rules/common/navigation.md

@@ -0,0 +1,56 @@
+---
+description: Expo Router navigation conventions and patterns
+globs: "app/**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Navigation
+
+## Expo Router File Conventions
+- File-based routing in `app/` directory
+- `_layout.tsx` for layout definitions (Stack, Tabs, Drawer)
+- `[param].tsx` for dynamic routes
+- `[...catchAll].tsx` for catch-all routes
+- `+not-found.tsx` for 404 handling
+- `(group)` parentheses for layout groups (no URL impact)
+
+```
+app/
+  _layout.tsx          # Root layout (Stack)
+  index.tsx            # / (home)
+  (tabs)/
+    _layout.tsx        # Tab layout
+    home.tsx           # /home tab
+    profile.tsx        # /profile tab
+  (auth)/
+    _layout.tsx        # Auth stack (no tabs)
+    login.tsx          # /login
+    register.tsx       # /register
+  settings/
+    _layout.tsx        # Settings stack
+    index.tsx          # /settings
+    [section].tsx      # /settings/notifications
+```
+
+## Typed Routes
+- Use `href` with type-safe route paths
+- Define route params with `useLocalSearchParams<{ id: string }>()`
+- Use `router.push()` / `router.replace()` / `router.back()`
+- Prefer `<Link>` component for declarative navigation
+
+## Deep Linking
+- Define scheme in `app.json` (`expo.scheme`)
+- Map deep links to file routes
+- Validate incoming URLs before navigating
+- Test deep links: `npx uri-scheme open [url] --ios/--android`
+
+## Modal Patterns
+- Use `presentation: 'modal'` in layout options
+- Full-screen modals: separate route in layout group
+- Bottom sheets: `@gorhom/bottom-sheet` (not navigation)
+
+## Best Practices
+- Keep navigation state minimal (pass IDs, not full objects)
+- Prefetch data for likely next screens
+- Use `initialRouteName` for proper back navigation
+- Handle "not found" routes gracefully

package/rules/common/patterns.md

@@ -0,0 +1,59 @@
+---
+description: React Native architectural patterns and best practices
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Patterns
+
+## State Management
+- **Client state**: Zustand (simple) or Jotai (atomic) — NOT Redux for new projects
+- **Server state**: TanStack Query (React Query) — handles caching, refetching, optimistic updates
+- **Form state**: React Hook Form or controlled components (small forms)
+- Avoid prop drilling beyond 2 levels — use Zustand store or composition
+
+```tsx
+// GOOD: Zustand store
+const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  logout: () => set({ user: null }),
+}));
+
+// BAD: Deep prop drilling
+<App user={user}>
+  <Layout user={user}>
+    <Header user={user}>
+      <Avatar user={user} />
+```
+
+## Component Patterns
+- **Compound components** for complex UI (Header + Body + Footer)
+- **Custom hooks** for shared logic (extract `useAuth`, `useTheme`)
+- **Colocation**: keep feature files together
+
+```
+features/
+  auth/
+    LoginScreen.tsx
+    useAuth.ts
+    auth.store.ts
+    auth.test.tsx
+```
+
+- **Render props / children** for flexible containers
+- **forwardRef** for imperative handles (scroll, focus)
+
+## Data Fetching
+- TanStack Query for all API calls
+- Define query keys as constants (`['users', userId]`)
+- Use `queryClient.prefetchQuery` for anticipated navigation
+- Optimistic updates for user-initiated mutations
+- Error boundaries per screen (not global)
+
+## Error Handling
+- Error boundaries at screen level (catch rendering crashes)
+- Try/catch at API call level (handle network errors)
+- Graceful degradation (offline placeholder, retry button)
+- Report errors to monitoring (Sentry/Crashlytics)
+- Never swallow errors silently

package/rules/common/performance.md

@@ -0,0 +1,55 @@
+---
+description: React Native performance optimization rules
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# Performance
+
+## Rendering
+- Use `React.memo` on components rendered in lists or receiving stable props
+- Wrap callbacks with `useCallback` when passed to memoized children
+- Use `useMemo` for expensive computations (sorting, filtering large arrays)
+- Never define functions or objects inline in JSX within loops/lists
+
+```tsx
+// GOOD
+const renderItem = useCallback(({ item }: { item: User }) => (
+  <UserRow user={item} onPress={handlePress} />
+), [handlePress]);
+
+// BAD — creates new object every render
+<FlatList renderItem={({ item }) => <UserRow user={item} />} />
+```
+
+## Lists
+- `FlatList` or `FlashList` for lists > 20 items (never ScrollView)
+- Set `keyExtractor` with stable, unique keys
+- Use `getItemLayout` when item heights are fixed
+- Configure `windowSize`, `maxToRenderPerBatch`, `initialNumToRender`
+- `removeClippedSubviews={true}` for long lists on Android
+
+## Images
+- Use `expo-image` (not `<Image>` or react-native-fast-image)
+- Set explicit `width` and `height` (avoid layout shifts)
+- Use `contentFit="cover"` and `placeholder` for loading states
+- Optimize source images (WebP, appropriate resolution)
+- Use `cachePolicy="memory-disk"` for frequently accessed images
+
+## Bundle Size
+- Import specific modules, not entire packages (`lodash/get` not `lodash`)
+- Use `React.lazy` + `Suspense` for code splitting heavy screens
+- Analyze bundle with `npx react-native-bundle-visualizer`
+- Target < 5MB JS bundle for production
+
+## Animations
+- Use `react-native-reanimated` for all animations (not Animated API)
+- Run animations on UI thread via worklets
+- Never read shared values from JS thread in hot paths
+- Use `useAnimatedStyle` instead of inline animated styles
+
+## Startup
+- Use Hermes engine (enabled by default in Expo SDK 50+)
+- Inline requires for heavy modules (`require('heavy-lib')` inside function)
+- Minimize `useEffect` chains on app startup
+- Defer non-critical initialization with `InteractionManager.runAfterInteractions`

package/rules/common/security.md

@@ -0,0 +1,64 @@
+---
+description: Mobile security rules for React Native applications
+globs: "**/*.{ts,tsx,js,jsx}"
+alwaysApply: false
+---
+
+# Security
+
+## Secrets Management
+- NEVER hardcode API keys, tokens, or secrets in JS code
+- Use `expo-secure-store` for sensitive data (NOT AsyncStorage)
+- Environment variables via `.env` files (excluded from git)
+- Build-time secrets via EAS Secrets (for CI/CD)
+- Runtime secrets via secure backend API
+
+```tsx
+// GOOD
+import * as SecureStore from 'expo-secure-store';
+const token = await SecureStore.getItemAsync('auth_token');
+
+// BAD
+const API_KEY = 'sk-1234567890abcdef';
+await AsyncStorage.setItem('auth_token', token);
+```
+
+## Deep Linking
+- Validate ALL incoming deep link URLs before navigation
+- Whitelist allowed hosts and paths
+- Never pass deep link params directly to sensitive operations
+- Sanitize query parameters
+
+```tsx
+// GOOD
+function handleDeepLink(url: string) {
+  const parsed = Linking.parse(url);
+  if (ALLOWED_HOSTS.includes(parsed.hostname)) {
+    router.push(parsed.path);
+  }
+}
+```
+
+## Network Security
+- HTTPS only — no HTTP requests
+- Certificate pinning for critical API endpoints
+- Timeout all network requests (15s default)
+- Handle network errors gracefully (offline mode)
+
+## WebView
+- Always set `originWhitelist` (never `['*']` in production)
+- Disable JavaScript if not needed
+- Never load untrusted URLs
+- Use `onShouldStartLoadWithRequest` to filter navigation
+
+## Input Validation
+- Sanitize all user input before display (XSS prevention)
+- Validate form data on client AND server
+- Use parameterized queries (never string concatenation for queries)
+- Limit input lengths to prevent abuse
+
+## Data Storage
+- Sensitive data: `expo-secure-store` (Keychain/Keystore)
+- Non-sensitive preferences: `AsyncStorage` or `expo-file-system`
+- Never store PII in logs or crash reports
+- Clear sensitive data on logout

package/rules/common/state-management.md

@@ -0,0 +1,86 @@
+---
+description: State management guidelines — Zustand for client, TanStack Query for server
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# State Management
+
+## Architecture
+
+| State Type | Tool | When |
+|-----------|------|------|
+| **Client state** | Zustand | UI state, user preferences, app mode |
+| **Server state** | TanStack Query | API data, caching, pagination, optimistic updates |
+| **Form state** | React Hook Form | Complex forms with validation |
+| **Ephemeral state** | useState | Component-local, non-shared |
+| **Derived state** | useMemo | Computed from other state |
+
+## Zustand Patterns
+
+```tsx
+// Store definition — one store per domain
+interface AuthStore {
+  user: User | null;
+  token: string | null;
+  setUser: (user: User) => void;
+  logout: () => void;
+}
+
+const useAuthStore = create<AuthStore>((set) => ({
+  user: null,
+  token: null,
+  setUser: (user) => set({ user }),
+  logout: () => set({ user: null, token: null }),
+}));
+
+// Usage — select only what you need
+const userName = useAuthStore((s) => s.user?.name);
+```
+
+## TanStack Query Patterns
+
+```tsx
+// Query keys as constants
+export const userKeys = {
+  all: ['users'] as const,
+  detail: (id: string) => ['users', id] as const,
+  lists: () => ['users', 'list'] as const,
+};
+
+// Query hook
+function useUser(id: string) {
+  return useQuery({
+    queryKey: userKeys.detail(id),
+    queryFn: () => api.getUser(id),
+    staleTime: 5 * 60 * 1000,
+  });
+}
+
+// Mutation with optimistic update
+function useUpdateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: api.updateUser,
+    onMutate: async (updated) => {
+      await queryClient.cancelQueries({ queryKey: userKeys.detail(updated.id) });
+      const previous = queryClient.getQueryData(userKeys.detail(updated.id));
+      queryClient.setQueryData(userKeys.detail(updated.id), updated);
+      return { previous };
+    },
+    onError: (err, vars, context) => {
+      queryClient.setQueryData(userKeys.detail(vars.id), context?.previous);
+    },
+    onSettled: (data, err, vars) => {
+      queryClient.invalidateQueries({ queryKey: userKeys.detail(vars.id) });
+    },
+  });
+}
+```
+
+## Rules
+- Context API only for truly global, rarely-changing values (theme, locale)
+- No prop drilling beyond 2 component levels
+- Keep stores small and domain-focused
+- Never store derived data — compute with `useMemo` or selectors
+- Persist critical state with `zustand/middleware` persist

package/rules/common/testing.md

@@ -0,0 +1,61 @@
+---
+description: Testing standards for React Native projects
+globs: "**/*.test.{ts,tsx}"
+alwaysApply: false
+---
+
+# Testing
+
+## Stack
+- **Unit/Component**: Jest + React Native Testing Library (RNTL)
+- **E2E**: Detox (with EAS Build for Expo projects)
+- **Coverage**: Jest built-in, target 80% lines, 70% branches
+
+## Principles
+- Test behavior, not implementation
+- Query by role, text, or label — avoid testID unless necessary
+- One logical assertion per test
+- Mock at boundaries (API, native modules), not internals
+- No snapshot tests as primary strategy (smoke checks only)
+
+## Component Tests
+```tsx
+// GOOD: Tests behavior
+test('disables submit when form is invalid', () => {
+  render(<LoginForm />);
+  const button = screen.getByRole('button', { name: 'Submit' });
+  expect(button).toBeDisabled();
+});
+
+// BAD: Tests implementation
+test('sets isValid state to false', () => {
+  const { result } = renderHook(() => useForm());
+  expect(result.current.isValid).toBe(false);
+});
+```
+
+## Mocking
+```tsx
+// Mock native module
+jest.mock('expo-secure-store', () => ({
+  getItemAsync: jest.fn().mockResolvedValue('token'),
+  setItemAsync: jest.fn(),
+}));
+
+// Mock navigation
+jest.mock('expo-router', () => ({
+  useRouter: () => ({ push: jest.fn(), back: jest.fn() }),
+  useLocalSearchParams: () => ({}),
+}));
+
+// Mock API — use MSW or manual mock
+const server = setupServer(
+  rest.get('/api/users', (req, res, ctx) => res(ctx.json([]))),
+);
+```
+
+## File Organization
+- Tests adjacent to source: `UserCard.test.tsx` next to `UserCard.tsx`
+- Or in `__tests__/` directory at feature level
+- Shared test utilities in `tests/helpers/`
+- E2E tests in `e2e/` directory at project root

package/rules/expo/coding-style.md

@@ -0,0 +1,54 @@
+---
+description: Expo managed workflow coding conventions
+globs: "**/*.{ts,tsx,js,jsx}"
+alwaysApply: false
+---
+
+# Expo Coding Style
+
+## SDK Module Preference
+- Always prefer Expo SDK modules over community alternatives
+- `expo-image` over `react-native-fast-image`
+- `expo-file-system` over `react-native-fs`
+- `expo-camera` over `react-native-camera`
+- `expo-notifications` over `react-native-push-notification`
+- `expo-secure-store` over `react-native-keychain`
+
+```tsx
+// GOOD — Expo SDK module
+import * as FileSystem from 'expo-file-system';
+const content = await FileSystem.readAsStringAsync(uri);
+
+// BAD — community alternative in Expo project
+import RNFS from 'react-native-fs';
+const content = await RNFS.readFile(path);
+```
+
+## Config Plugins Over Manual Native Edits
+- NEVER modify `ios/` or `android/` directories directly in managed workflow
+- Use config plugins for native configuration
+- Run `npx expo prebuild --clean` to regenerate native projects
+- Add native config in `app.config.ts` with plugins array
+
+```ts
+// app.config.ts
+export default ({ config }) => ({
+  ...config,
+  plugins: [
+    ['expo-camera', { cameraPermission: 'Allow camera for scanning' }],
+    ['expo-location', { locationAlwaysAndWhenInUsePermission: 'Allow location' }],
+    './plugins/custom-splash.js',
+  ],
+});
+```
+
+## Expo Router Conventions
+- Use file-based routing exclusively (no manual route registration)
+- Layout files (`_layout.tsx`) define navigation structure
+- Use typed routes for navigation
+- Group routes with parentheses for logical organization
+
+## Module Resolution
+- Use `expo-modules-core` for creating native modules
+- Prefer `expo-constants` for accessing build-time configuration
+- Use `expo-updates` API for checking/fetching OTA updates