create-react-native-airborne 0.0.1

package/template/.agents/skills/convex-security-check/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: Convex Security Check
+description: Quick security audit checklist covering authentication, function exposure, argument validation, row-level access control, and environment variable handling
+version: 1.0.0
+author: Convex
+tags: [convex, security, authentication, authorization, checklist]
+---
+
+# Convex Security Check
+
+A quick security audit checklist for Convex applications covering authentication, function exposure, argument validation, row-level access control, and environment variable handling.
+
+## Documentation Sources
+
+Before implementing, do not assume; fetch the latest documentation:
+
+- Primary: https://docs.convex.dev/auth
+- Production Security: https://docs.convex.dev/production
+- Functions Auth: https://docs.convex.dev/auth/functions-auth
+- For broader context: https://docs.convex.dev/llms.txt
+
+## Instructions
+
+### Security Checklist
+
+Use this checklist to quickly audit your Convex application's security:
+
+#### 1. Authentication
+
+- [ ] Authentication provider configured (Clerk, Auth0, etc.)
+- [ ] All sensitive queries check `ctx.auth.getUserIdentity()`
+- [ ] Unauthenticated access explicitly allowed where intended
+- [ ] Session tokens properly validated
+
+#### 2. Function Exposure
+
+- [ ] Public functions (`query`, `mutation`, `action`) reviewed
+- [ ] Internal functions use `internalQuery`, `internalMutation`, `internalAction`
+- [ ] No sensitive operations exposed as public functions
+- [ ] HTTP actions validate origin/authentication
+
+#### 3. Argument Validation
+
+- [ ] All functions have explicit `args` validators
+- [ ] All functions have explicit `returns` validators
+- [ ] No `v.any()` used for sensitive data
+- [ ] ID validators use correct table names
+
+#### 4. Row-Level Access Control
+
+- [ ] Users can only access their own data
+- [ ] Admin functions check user roles
+- [ ] Shared resources have proper access checks
+- [ ] Deletion functions verify ownership
+
+#### 5. Environment Variables
+
+- [ ] API keys stored in environment variables
+- [ ] No secrets in code or schema
+- [ ] Different keys for dev/prod environments
+- [ ] Environment variables accessed only in actions
+
+### Authentication Check
+
+```typescript
+// convex/auth.ts
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+import { ConvexError } from "convex/values";
+
+// Helper to require authentication
+async function requireAuth(ctx: QueryCtx | MutationCtx) {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) {
+    throw new ConvexError("Authentication required");
+  }
+  return identity;
+}
+
+// Secure query pattern
+export const getMyProfile = query({
+  args: {},
+  returns: v.union(v.object({
+    _id: v.id("users"),
+    name: v.string(),
+    email: v.string(),
+  }), v.null()),
+  handler: async (ctx) => {
+    const identity = await requireAuth(ctx);
+    
+    return await ctx.db
+      .query("users")
+      .withIndex("by_tokenIdentifier", (q) => 
+        q.eq("tokenIdentifier", identity.tokenIdentifier)
+      )
+      .unique();
+  },
+});
+```
+
+### Function Exposure Check
+
+```typescript
+// PUBLIC - Exposed to clients (review carefully!)
+export const listPublicPosts = query({
+  args: {},
+  returns: v.array(v.object({ /* ... */ })),
+  handler: async (ctx) => {
+    // Anyone can call this - intentionally public
+    return await ctx.db
+      .query("posts")
+      .withIndex("by_public", (q) => q.eq("isPublic", true))
+      .collect();
+  },
+});
+
+// INTERNAL - Only callable from other Convex functions
+export const _updateUserCredits = internalMutation({
+  args: { userId: v.id("users"), amount: v.number() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // This cannot be called directly from clients
+    await ctx.db.patch(args.userId, {
+      credits: args.amount,
+    });
+    return null;
+  },
+});
+```
+
+### Argument Validation Check
+
+```typescript
+// GOOD: Strict validation
+export const createPost = mutation({
+  args: {
+    title: v.string(),
+    content: v.string(),
+    category: v.union(
+      v.literal("tech"),
+      v.literal("news"),
+      v.literal("other")
+    ),
+  },
+  returns: v.id("posts"),
+  handler: async (ctx, args) => {
+    const identity = await requireAuth(ctx);
+    return await ctx.db.insert("posts", {
+      ...args,
+      authorId: identity.tokenIdentifier,
+    });
+  },
+});
+
+// BAD: Weak validation
+export const createPostUnsafe = mutation({
+  args: {
+    data: v.any(), // DANGEROUS: Allows any data
+  },
+  returns: v.id("posts"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("posts", args.data);
+  },
+});
+```
+
+### Row-Level Access Control Check
+
+```typescript
+// Verify ownership before update
+export const updateTask = mutation({
+  args: {
+    taskId: v.id("tasks"),
+    title: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const identity = await requireAuth(ctx);
+    
+    const task = await ctx.db.get(args.taskId);
+    
+    // Check ownership
+    if (!task || task.userId !== identity.tokenIdentifier) {
+      throw new ConvexError("Not authorized to update this task");
+    }
+    
+    await ctx.db.patch(args.taskId, { title: args.title });
+    return null;
+  },
+});
+
+// Verify ownership before delete
+export const deleteTask = mutation({
+  args: { taskId: v.id("tasks") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const identity = await requireAuth(ctx);
+    
+    const task = await ctx.db.get(args.taskId);
+    
+    if (!task || task.userId !== identity.tokenIdentifier) {
+      throw new ConvexError("Not authorized to delete this task");
+    }
+    
+    await ctx.db.delete(args.taskId);
+    return null;
+  },
+});
+```
+
+### Environment Variables Check
+
+```typescript
+// convex/actions.ts
+"use node";
+
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+
+export const sendEmail = action({
+  args: {
+    to: v.string(),
+    subject: v.string(),
+    body: v.string(),
+  },
+  returns: v.object({ success: v.boolean() }),
+  handler: async (ctx, args) => {
+    // Access API key from environment
+    const apiKey = process.env.RESEND_API_KEY;
+    
+    if (!apiKey) {
+      throw new Error("RESEND_API_KEY not configured");
+    }
+    
+    const response = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        from: "noreply@example.com",
+        to: args.to,
+        subject: args.subject,
+        html: args.body,
+      }),
+    });
+    
+    return { success: response.ok };
+  },
+});
+```
+
+## Examples
+
+### Complete Security Pattern
+
+```typescript
+// convex/secure.ts
+import { query, mutation, internalMutation } from "./_generated/server";
+import { v } from "convex/values";
+import { ConvexError } from "convex/values";
+
+// Authentication helper
+async function getAuthenticatedUser(ctx: QueryCtx | MutationCtx) {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) {
+    throw new ConvexError({
+      code: "UNAUTHENTICATED",
+      message: "You must be logged in",
+    });
+  }
+  
+  const user = await ctx.db
+    .query("users")
+    .withIndex("by_tokenIdentifier", (q) => 
+      q.eq("tokenIdentifier", identity.tokenIdentifier)
+    )
+    .unique();
+    
+  if (!user) {
+    throw new ConvexError({
+      code: "USER_NOT_FOUND",
+      message: "User profile not found",
+    });
+  }
+  
+  return user;
+}
+
+// Check admin role
+async function requireAdmin(ctx: QueryCtx | MutationCtx) {
+  const user = await getAuthenticatedUser(ctx);
+  
+  if (user.role !== "admin") {
+    throw new ConvexError({
+      code: "FORBIDDEN",
+      message: "Admin access required",
+    });
+  }
+  
+  return user;
+}
+
+// Public: List own tasks
+export const listMyTasks = query({
+  args: {},
+  returns: v.array(v.object({
+    _id: v.id("tasks"),
+    title: v.string(),
+    completed: v.boolean(),
+  })),
+  handler: async (ctx) => {
+    const user = await getAuthenticatedUser(ctx);
+    
+    return await ctx.db
+      .query("tasks")
+      .withIndex("by_user", (q) => q.eq("userId", user._id))
+      .collect();
+  },
+});
+
+// Admin only: List all users
+export const listAllUsers = query({
+  args: {},
+  returns: v.array(v.object({
+    _id: v.id("users"),
+    name: v.string(),
+    role: v.string(),
+  })),
+  handler: async (ctx) => {
+    await requireAdmin(ctx);
+    
+    return await ctx.db.query("users").collect();
+  },
+});
+
+// Internal: Update user role (never exposed)
+export const _setUserRole = internalMutation({
+  args: {
+    userId: v.id("users"),
+    role: v.union(v.literal("user"), v.literal("admin")),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.userId, { role: args.role });
+    return null;
+  },
+});
+```
+
+## Best Practices
+
+- Never run `npx convex deploy` unless explicitly instructed
+- Never run any git commands unless explicitly instructed
+- Always verify user identity before returning sensitive data
+- Use internal functions for sensitive operations
+- Validate all arguments with strict validators
+- Check ownership before update/delete operations
+- Store API keys in environment variables
+- Review all public functions for security implications
+
+## Common Pitfalls
+
+1. **Missing authentication checks** - Always verify identity
+2. **Exposing internal operations** - Use internalMutation/Query
+3. **Trusting client-provided IDs** - Verify ownership
+4. **Using v.any() for arguments** - Use specific validators
+5. **Hardcoding secrets** - Use environment variables
+
+## References
+
+- Convex Documentation: https://docs.convex.dev/
+- Convex LLMs.txt: https://docs.convex.dev/llms.txt
+- Authentication: https://docs.convex.dev/auth
+- Production Security: https://docs.convex.dev/production
+- Functions Auth: https://docs.convex.dev/auth/functions-auth

package/template/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+name: "🧪 CI"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  validate:
+    name: "✅ Validate"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "🥟 Setup Bun"
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.4"
+
+      - name: "📦 Install dependencies"
+        run: bun install --workspaces
+
+      - name: "🔍 Lint"
+        run: |
+          cd client && bun run lint
+          cd ../server && bun run lint
+
+      - name: "🧠 Typecheck"
+        run: |
+          cd client && bun run typecheck
+          cd ../server && bun run typecheck
+
+      - name: "🧪 Test"
+        run: |
+          cd client && bun run test
+          cd ../server && bun run test
+
+  android-native-build:
+    name: "🤖 Android Native Build"
+    needs: validate
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "🥟 Setup Bun"
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.4"
+
+      - name: "☕ Setup Java"
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: "🤖 Setup Android SDK"
+        uses: android-actions/setup-android@v3
+
+      - name: "📦 Install dependencies"
+        run: bun install --workspaces
+
+      - name: "⚙️ Generate Android native project"
+        run: |
+          cd client
+          bunx expo prebuild --platform android --no-install
+
+      - name: "🏗️ Build Android (arm64-v8a)"
+        run: |
+          cd client/android
+          ./gradlew :app:assembleDebug --no-daemon -PreactNativeArchitectures=arm64-v8a
+
+  ios-native-build:
+    name: "🍎 iOS Native Build"
+    needs: validate
+    runs-on: macos-26
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "🥟 Setup Bun"
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.4"
+
+      - name: "📦 Install dependencies"
+        run: bun install --workspaces
+
+      - name: "⚙️ Generate iOS native project"
+        run: |
+          cd client
+          bunx expo prebuild --platform ios --no-install
+
+      - name: "🫘 Install CocoaPods dependencies"
+        run: |
+          cd client/ios
+          pod install
+
+      - name: "🏗️ Build iOS Simulator (arm64)"
+        run: |
+          set -euo pipefail
+          cd client
+
+          workspace="$(find ios -maxdepth 1 -name '*.xcworkspace' | head -n 1)"
+          if [[ -z "${workspace}" ]]; then
+            echo "No iOS workspace found under client/ios"
+            exit 1
+          fi
+
+          scheme="$(xcodebuild -list -workspace "${workspace}" | awk '/Schemes:/{getline; gsub(/^[[:space:]]+|[[:space:]]+$/, ""); print; exit}')"
+          if [[ -z "${scheme}" ]]; then
+            echo "No iOS scheme found for ${workspace}"
+            exit 1
+          fi
+
+          xcodebuild \
+            -workspace "${workspace}" \
+            -scheme "${scheme}" \
+            -configuration Debug \
+            -sdk iphonesimulator \
+            -destination 'generic/platform=iOS Simulator' \
+            ARCHS=arm64 \
+            CODE_SIGNING_ALLOWED=NO \
+            ONLY_ACTIVE_ARCH=YES \
+            build -quiet

package/template/.prettierignore

@@ -0,0 +1,8 @@
+node_modules
+bun.lock
+coverage
+client/.expo
+client/android
+client/ios
+server/convex/_generated
+tooling/create-react-native-airborne/template

package/template/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all"
+}

package/template/AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+This file is for engineers and coding agents working in this repository.
+
+## Purpose
+
+`react-native-airborne` is an opinionated Bun workspace starter for mobile apps:
+
+- Expo + Expo Router client
+- Expo Router Native Tabs (SDK 55)
+- Clerk auth
+- Uniwind styling (Tailwind v4)
+- Convex backend
+- Zustand + MMKV for local non-sensitive preferences
+- Expo notifications
+
+
+## Monorepo Structure
+
+- `client/`: Expo app (mobile only: iOS + Android)
+- `server/`: Convex functions, schema, tests
+- `uniwind/`: local integration docs used for setup decisions
+- `Justfile`: top-level task runner
+- `.github/workflows/ci.yml`: CI pipeline
+
+## Tooling Baseline
+
+- Package manager: Bun (`bun@1.3.4`)
+- Workspace management: Bun workspaces (root `package.json`)
+- Task runner: `just`
+- Formatting: Prettier (root `.prettierrc.json`)
+- Client lint: Expo ESLint config (flat config)
+- Server lint: strict ESLint 9 + `typescript-eslint` + `@convex-dev/eslint-plugin`
+- Tests: Vitest (client and server), plus `convex-test` on server
+
+## Essential Commands
+
+From repository root:
+
+- `just install`: install all workspace dependencies
+- `just dev`: run client and server together
+- `just dev-client`: run Expo only
+- `just dev-server`: run Convex only
+- `just prebuild`: generate native iOS/Android projects locally
+- `just ios`: run iOS app
+- `just android`: run Android app
+- `just fmt`: format client/server with Prettier
+- `just lint`: lint both workspaces
+- `just typecheck`: typecheck both workspaces
+- `just test`: run all tests
+- `just ci`: lint + typecheck + tests
+
+## Environment Variables
+
+### Client (`client/.env`)
+
+- `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` (required)
+- `EXPO_PUBLIC_CONVEX_URL` (required)
+- `EXPO_PUBLIC_EAS_PROJECT_ID` (optional; used for push token registration when needed)
+
+Validation is in `client/src/lib/env-schema.ts`.
+
+### Server (`server/.env`)
+
+- `CLERK_JWT_ISSUER_DOMAIN` (required in real environments)
+- `EXPO_PUSH_ENDPOINT` (optional, default Expo endpoint)
+- `EXPO_ACCESS_TOKEN` (optional)
+
+Validation is in `server/convex/env.ts`.
+
+## Auth Architecture (Clerk + Expo Router)
+
+- Root providers live in `client/app/_layout.tsx`:
+  - `ClerkProvider` with `tokenCache` from `@clerk/clerk-expo/token-cache` (secure storage)
+  - `ConvexProviderWithClerk`
+  - `SafeAreaProvider`
+- Route guards:
+  - `client/app/(auth)/_layout.tsx` redirects signed-in users to `/(app)`
+  - `client/app/(app)/_layout.tsx` redirects signed-out users to `/(auth)/sign-in`
+- App shell:
+  - `client/app/(app)/_layout.tsx` uses `NativeTabs` from `expo-router/unstable-native-tabs`
+  - tabs are explicitly registered for `index`, `push`, and `settings`
+- Auth screens are custom flows in:
+  - `client/app/(auth)/sign-in.tsx`
+  - `client/app/(auth)/sign-up.tsx`
+
+Important: never store auth/session tokens in MMKV.
+
+## Uniwind Integration Rules
+
+Uniwind integration is intentionally specific. Keep these rules:
+
+1. `client/global.css` must contain:
+   - `@import "tailwindcss";`
+   - `@import "uniwind";`
+2. Import `../global.css` in `client/app/_layout.tsx`.
+3. Keep Metro wrapped by `withUniwindConfig(...)` in `client/metro.config.js` with:
+   - `cssEntryFile: "./global.css"`
+   - `dtsFile: "./uniwind-types.d.ts"`
+4. For third-party components without `className` support (for example `SafeAreaView`), wrap with `withUniwind(...)`.
+5. Theming defaults to `system`; explicit `light`/`dark`/`system` is handled by preferences store + theme sync hook:
+   - `client/src/store/preferences-store.ts`
+   - `client/src/hooks/use-theme-sync.ts`
+
+## Client Data/State Notes
+
+- MMKV + Zustand is used for app preferences, not secrets.
+- Convex API imports in client use the alias path:
+  - `@convex/_generated/api`
+- Alias is configured in `client/tsconfig.json`.
+
+## Convex Backend Notes
+
+- Convex directory: `server/convex/`
+- Auth provider config: `server/convex/auth.config.ts`
+- Main starter functions:
+  - `users.bootstrap`
+  - `push.registerToken`
+  - `push.unregisterToken`
+  - `push.sendTestNotification`
+- Schema: `server/convex/schema.ts`
+- Regenerate generated types after Convex setup:
+  - `cd server && bun run codegen`
+
+## Prebuild Policy
+
+- `just prebuild` is supported for local native runs.
+- `client/ios` and `client/android` are intentionally gitignored.
+- Do not commit generated native folders in this starter.
+
+## Testing Expectations
+
+- Run `just ci` before handing off significant changes.
+- Server tests use `convex-test`; keep tests deterministic and isolated.
+- If changing auth/push flows, verify both happy path and obvious edge cases.
+
+## CI and Quality Gates
+
+CI (`.github/workflows/ci.yml`) runs:
+
+1. install (`bun install --workspaces`)
+2. validate (lint + typecheck + tests for client and server)
+3. native Android build on Linux (`arm64-v8a`)
+4. native iOS simulator build on `macos-26` (`arm64`)
+
+Keep local changes compatible with these checks.
+
+## Common Troubleshooting
+
+- Convex asks for missing env var on startup:
+  - set required variable in Convex dashboard deployment environment variables.
+- Clerk says user is already signed in on auth pages:
+  - ensure route guards are active and auth pages redirect signed-in users.
+  - if simulator state is stale, clear app data/reinstall app and retry.
+- Uniwind styles missing:
+  - verify `global.css` imports and `withUniwindConfig` metro wrapper.