create-react-native-airborne 0.0.1

package/README.md

@@ -0,0 +1,24 @@
+# create-react-native-airborne
+
+Create projects from the React Native Airborne template.
+
+## Usage
+
+```bash
+bun create react-native-airborne my-app
+```
+
+## Flags
+
+- `--skip-install`: skip `bun install --workspaces`
+- `--no-git`: skip `git init`
+
+## Development
+
+From repo root:
+
+```bash
+cd tooling/create-react-native-airborne && bun run sync-template
+```
+
+This refreshes `template/` from the current root starter files.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "create-react-native-airborne",
+  "version": "0.0.1",
+  "description": "Scaffold a react-native-airborne starter project",
+  "type": "module",
+  "bin": {
+    "create-react-native-airborne": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "template"
+  ],
+  "scripts": {
+    "sync-template": "bun ./scripts/sync-template.ts",
+    "prepare": "bun run sync-template",
+    "prepack": "bun run sync-template"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.4"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { mkdir, readdir, readFile, writeFile, copyFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((arg) => arg.startsWith("--")));
+const projectNameArg = args.find((arg) => !arg.startsWith("--"));
+
+if (!projectNameArg) {
+  console.error("Usage: bun create react-native-airborne <project-name> [--skip-install] [--no-git]");
+  process.exit(1);
+}
+
+const projectName = projectNameArg.trim();
+const projectSlug = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+const targetDir = path.resolve(process.cwd(), projectName);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templateDir = path.resolve(__dirname, "../template");
+
+async function exists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyDirectory(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function replaceTokens(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const filePath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await replaceTokens(filePath);
+      continue;
+    }
+
+    if (!/\.(json|md|ts|tsx|js|css|yml|yaml|env|toml|txt)$/.test(entry.name)) {
+      continue;
+    }
+
+    const content = await readFile(filePath, "utf8");
+    const updated = content
+      .replaceAll("__APP_NAME__", projectName)
+      .replaceAll("__APP_SLUG__", projectSlug)
+      .replaceAll("__APP_BUNDLE_ID__", `com.${projectSlug.replace(/-/g, "")}.app`);
+
+    if (updated !== content) {
+      await writeFile(filePath, updated, "utf8");
+    }
+  }
+}
+
+if (await exists(targetDir)) {
+  const contents = await readdir(targetDir);
+  if (contents.length > 0) {
+    console.error(`Target directory is not empty: ${targetDir}`);
+    process.exit(1);
+  }
+}
+
+await copyDirectory(templateDir, targetDir);
+await replaceTokens(targetDir);
+
+if (!flags.has("--skip-install")) {
+  const install = spawnSync("bun", ["install", "--workspaces"], {
+    cwd: targetDir,
+    stdio: "inherit",
+  });
+
+  if (install.status !== 0) {
+    process.exit(install.status ?? 1);
+  }
+}
+
+if (!flags.has("--no-git")) {
+  spawnSync("git", ["init"], { cwd: targetDir, stdio: "inherit" });
+}
+
+console.log(`\nCreated ${projectName} at ${targetDir}`);
+console.log("\nNext steps:");
+console.log(`  cd ${projectName}`);
+console.log("  cp client/.env.example client/.env");
+console.log("  cp server/.env.example server/.env");
+console.log("  just dev");

package/template/.agents/skills/convex-best-practices/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: Convex Best Practices
+description: Guidelines for building production-ready Convex apps covering function organization, query patterns, validation, TypeScript usage, error handling, and the Zen of Convex design philosophy
+version: 1.0.0
+author: Convex
+tags: [convex, best-practices, typescript, production, error-handling]
+---
+
+# Convex Best Practices
+
+Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.
+
+## Documentation Sources
+
+Before implementing, do not assume; fetch the latest documentation:
+
+- Primary: https://docs.convex.dev/understanding/best-practices/
+- Error Handling: https://docs.convex.dev/functions/error-handling
+- Write Conflicts: https://docs.convex.dev/error#1
+- For broader context: https://docs.convex.dev/llms.txt
+
+## Instructions
+
+### The Zen of Convex
+
+1. **Convex manages the hard parts** - Let Convex handle caching, real-time sync, and consistency
+2. **Functions are the API** - Design your functions as your application's interface
+3. **Schema is truth** - Define your data model explicitly in schema.ts
+4. **TypeScript everywhere** - Leverage end-to-end type safety
+5. **Queries are reactive** - Think in terms of subscriptions, not requests
+
+### Function Organization
+
+Organize your Convex functions by domain:
+
+```typescript
+// convex/users.ts - User-related functions
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const get = query({
+  args: { userId: v.id("users") },
+  returns: v.union(v.object({
+    _id: v.id("users"),
+    _creationTime: v.number(),
+    name: v.string(),
+    email: v.string(),
+  }), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.userId);
+  },
+});
+```
+
+### Argument and Return Validation
+
+Always define validators for arguments AND return types:
+
+```typescript
+export const createTask = mutation({
+  args: {
+    title: v.string(),
+    description: v.optional(v.string()),
+    priority: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
+  },
+  returns: v.id("tasks"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("tasks", {
+      title: args.title,
+      description: args.description,
+      priority: args.priority,
+      completed: false,
+      createdAt: Date.now(),
+    });
+  },
+});
+```
+
+### Query Patterns
+
+Use indexes instead of filters for efficient queries:
+
+```typescript
+// Schema with index
+export default defineSchema({
+  tasks: defineTable({
+    userId: v.id("users"),
+    status: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_user", ["userId"])
+    .index("by_user_and_status", ["userId", "status"]),
+});
+
+// Query using index
+export const getTasksByUser = query({
+  args: { userId: v.id("users") },
+  returns: v.array(v.object({
+    _id: v.id("tasks"),
+    _creationTime: v.number(),
+    userId: v.id("users"),
+    status: v.string(),
+    createdAt: v.number(),
+  })),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("tasks")
+      .withIndex("by_user", (q) => q.eq("userId", args.userId))
+      .order("desc")
+      .collect();
+  },
+});
+```
+
+### Error Handling
+
+Use ConvexError for user-facing errors:
+
+```typescript
+import { ConvexError } from "convex/values";
+
+export const updateTask = mutation({
+  args: {
+    taskId: v.id("tasks"),
+    title: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const task = await ctx.db.get(args.taskId);
+    
+    if (!task) {
+      throw new ConvexError({
+        code: "NOT_FOUND",
+        message: "Task not found",
+      });
+    }
+    
+    await ctx.db.patch(args.taskId, { title: args.title });
+    return null;
+  },
+});
+```
+
+### Avoiding Write Conflicts (Optimistic Concurrency Control)
+
+Convex uses OCC. Follow these patterns to minimize conflicts:
+
+```typescript
+// GOOD: Make mutations idempotent
+export const completeTask = mutation({
+  args: { taskId: v.id("tasks") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const task = await ctx.db.get(args.taskId);
+    
+    // Early return if already complete (idempotent)
+    if (!task || task.status === "completed") {
+      return null;
+    }
+    
+    await ctx.db.patch(args.taskId, {
+      status: "completed",
+      completedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+// GOOD: Patch directly without reading first when possible
+export const updateNote = mutation({
+  args: { id: v.id("notes"), content: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // Patch directly - ctx.db.patch throws if document doesn't exist
+    await ctx.db.patch(args.id, { content: args.content });
+    return null;
+  },
+});
+
+// GOOD: Use Promise.all for parallel independent updates
+export const reorderItems = mutation({
+  args: { itemIds: v.array(v.id("items")) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const updates = args.itemIds.map((id, index) =>
+      ctx.db.patch(id, { order: index })
+    );
+    await Promise.all(updates);
+    return null;
+  },
+});
+```
+
+### TypeScript Best Practices
+
+```typescript
+import { Id, Doc } from "./_generated/dataModel";
+
+// Use Id type for document references
+type UserId = Id<"users">;
+
+// Use Doc type for full documents
+type User = Doc<"users">;
+
+// Define Record types properly
+const userScores: Record<Id<"users">, number> = {};
+```
+
+### Internal vs Public Functions
+
+```typescript
+// Public function - exposed to clients
+export const getUser = query({
+  args: { userId: v.id("users") },
+  returns: v.union(v.null(), v.object({ /* ... */ })),
+  handler: async (ctx, args) => {
+    // ...
+  },
+});
+
+// Internal function - only callable from other Convex functions
+export const _updateUserStats = internalMutation({
+  args: { userId: v.id("users") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // ...
+  },
+});
+```
+
+## Examples
+
+### Complete CRUD Pattern
+
+```typescript
+// convex/tasks.ts
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+import { ConvexError } from "convex/values";
+
+const taskValidator = v.object({
+  _id: v.id("tasks"),
+  _creationTime: v.number(),
+  title: v.string(),
+  completed: v.boolean(),
+  userId: v.id("users"),
+});
+
+export const list = query({
+  args: { userId: v.id("users") },
+  returns: v.array(taskValidator),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("tasks")
+      .withIndex("by_user", (q) => q.eq("userId", args.userId))
+      .collect();
+  },
+});
+
+export const create = mutation({
+  args: {
+    title: v.string(),
+    userId: v.id("users"),
+  },
+  returns: v.id("tasks"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("tasks", {
+      title: args.title,
+      completed: false,
+      userId: args.userId,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    taskId: v.id("tasks"),
+    title: v.optional(v.string()),
+    completed: v.optional(v.boolean()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const { taskId, ...updates } = args;
+    
+    // Remove undefined values
+    const cleanUpdates = Object.fromEntries(
+      Object.entries(updates).filter(([_, v]) => v !== undefined)
+    );
+    
+    if (Object.keys(cleanUpdates).length > 0) {
+      await ctx.db.patch(taskId, cleanUpdates);
+    }
+    return null;
+  },
+});
+
+export const remove = mutation({
+  args: { taskId: v.id("tasks") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.taskId);
+    return null;
+  },
+});
+```
+
+## Best Practices
+
+- Never run `npx convex deploy` unless explicitly instructed
+- Never run any git commands unless explicitly instructed
+- Always define return validators for functions
+- Use indexes for all queries that filter data
+- Make mutations idempotent to handle retries gracefully
+- Use ConvexError for user-facing error messages
+- Organize functions by domain (users.ts, tasks.ts, etc.)
+- Use internal functions for sensitive operations
+- Leverage TypeScript's Id and Doc types
+
+## Common Pitfalls
+
+1. **Using filter instead of withIndex** - Always define indexes and use withIndex
+2. **Missing return validators** - Always specify the returns field
+3. **Non-idempotent mutations** - Check current state before updating
+4. **Reading before patching unnecessarily** - Patch directly when possible
+5. **Not handling null returns** - Document IDs might not exist
+
+## References
+
+- Convex Documentation: https://docs.convex.dev/
+- Convex LLMs.txt: https://docs.convex.dev/llms.txt
+- Best Practices: https://docs.convex.dev/understanding/best-practices/
+- Error Handling: https://docs.convex.dev/functions/error-handling
+- Write Conflicts: https://docs.convex.dev/error#1