@musashishao/agent-kit 1.8.2 → 1.9.0

package/.agent/skills/firebase/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: firebase
+description: "Firebase gives you a complete backend in minutes - auth, database, storage, functions, hosting. Covers Security Rules, Firestore patterns, Auth flows, and cost optimization."
+version: "1.0.0"
+source: "antigravity-awesome-skills (adapted)"
+---
+
+# 🔥 Firebase
+
+You're a developer who has shipped dozens of Firebase projects. You've seen the "easy" path lead to security breaches, runaway costs, and impossible migrations. You know Firebase is powerful, but you also know its sharp edges.
+
+**Key insight**: Firebase is optimized for read-heavy, denormalized data. If you design Firestore like SQL, you'll have a bad time.
+
+---
+
+## When to Use This Skill
+
+- Rapid prototyping with full backend
+- Real-time applications (chat, collaboration)
+- Mobile/web apps needing auth + database
+- Serverless functions with Cloud Functions
+- Static hosting with global CDN
+
+---
+
+## Capabilities
+
+- `firebase-auth`
+- `firestore`
+- `firebase-realtime-database`
+- `firebase-cloud-functions`
+- `firebase-storage`
+- `firebase-hosting`
+- `firebase-security-rules`
+- `firebase-emulators`
+
+---
+
+## 1. Modular SDK Setup
+
+```javascript
+// lib/firebase.js
+import { initializeApp } from 'firebase/app';
+import { getAuth, connectAuthEmulator } from 'firebase/auth';
+import { getFirestore, connectFirestoreEmulator } from 'firebase/firestore';
+
+const firebaseConfig = {
+  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID
+};
+
+const app = initializeApp(firebaseConfig);
+export const auth = getAuth(app);
+export const db = getFirestore(app);
+
+// Connect to emulators in development
+if (process.env.NODE_ENV === 'development') {
+  connectAuthEmulator(auth, 'http://localhost:9099');
+  connectFirestoreEmulator(db, 'localhost', 8080);
+}
+```
+
+---
+
+## 2. Authentication Patterns
+
+### Email/Password Auth
+
+```javascript
+import { 
+  createUserWithEmailAndPassword,
+  signInWithEmailAndPassword,
+  signOut,
+  onAuthStateChanged
+} from 'firebase/auth';
+import { auth } from './firebase';
+
+// Sign up
+export async function signUp(email, password) {
+  const userCredential = await createUserWithEmailAndPassword(auth, email, password);
+  return userCredential.user;
+}
+
+// Sign in
+export async function signIn(email, password) {
+  const userCredential = await signInWithEmailAndPassword(auth, email, password);
+  return userCredential.user;
+}
+
+// Auth state listener
+export function subscribeToAuth(callback) {
+  return onAuthStateChanged(auth, (user) => {
+    callback(user);
+  });
+}
+```
+
+### OAuth Provider
+
+```javascript
+import { GoogleAuthProvider, signInWithPopup } from 'firebase/auth';
+
+export async function signInWithGoogle() {
+  const provider = new GoogleAuthProvider();
+  provider.addScope('email');
+  provider.addScope('profile');
+  
+  const result = await signInWithPopup(auth, provider);
+  
+  // Access token for Google APIs
+  const credential = GoogleAuthProvider.credentialFromResult(result);
+  const token = credential.accessToken;
+  
+  return result.user;
+}
+```
+
+---
+
+## 3. Firestore Patterns
+
+### Data Modeling for Queries
+
+```javascript
+// Design around your query patterns!
+// Example: Messages in a chat room
+
+// DON'T: Nest deeply
+// /chats/{chatId}/messages/{messageId}/reactions/{reactionId}
+
+// DO: Flatten for query flexibility
+// /messages (with chatId field for filtering)
+
+// Collection structure
+const messageRef = {
+  id: 'msg123',
+  chatId: 'chat456',
+  userId: 'user789',
+  text: 'Hello world',
+  createdAt: serverTimestamp(),
+  // Denormalize for display without extra reads
+  userName: 'John Doe',
+  userAvatar: 'https://...'
+};
+```
+
+### Real-time Subscription
+
+```javascript
+import { 
+  collection, 
+  query, 
+  where, 
+  orderBy, 
+  limit,
+  onSnapshot 
+} from 'firebase/firestore';
+
+export function subscribeToMessages(chatId, callback) {
+  const q = query(
+    collection(db, 'messages'),
+    where('chatId', '==', chatId),
+    orderBy('createdAt', 'desc'),
+    limit(50)
+  );
+  
+  return onSnapshot(q, (snapshot) => {
+    const messages = snapshot.docs.map(doc => ({
+      id: doc.id,
+      ...doc.data()
+    }));
+    callback(messages);
+  }, (error) => {
+    console.error('Subscription error:', error);
+  });
+}
+```
+
+### Batch Writes
+
+```javascript
+import { writeBatch, doc, serverTimestamp } from 'firebase/firestore';
+
+export async function createOrderWithItems(order, items) {
+  const batch = writeBatch(db);
+  
+  // Create order
+  const orderRef = doc(collection(db, 'orders'));
+  batch.set(orderRef, {
+    ...order,
+    createdAt: serverTimestamp()
+  });
+  
+  // Create items
+  items.forEach(item => {
+    const itemRef = doc(collection(db, 'orderItems'));
+    batch.set(itemRef, {
+      ...item,
+      orderId: orderRef.id
+    });
+  });
+  
+  // Update inventory
+  items.forEach(item => {
+    const productRef = doc(db, 'products', item.productId);
+    batch.update(productRef, {
+      inventory: increment(-item.quantity)
+    });
+  });
+  
+  await batch.commit();
+  return orderRef.id;
+}
+```
+
+---
+
+## 4. Security Rules
+
+```javascript
+// firestore.rules
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    
+    // Helper functions
+    function isSignedIn() {
+      return request.auth != null;
+    }
+    
+    function isOwner(userId) {
+      return request.auth.uid == userId;
+    }
+    
+    function isAdmin() {
+      return request.auth.token.admin == true;
+    }
+    
+    // Users collection
+    match /users/{userId} {
+      // Anyone signed in can read
+      allow read: if isSignedIn();
+      
+      // Only owner can write their own doc
+      allow write: if isOwner(userId);
+    }
+    
+    // Messages collection
+    match /messages/{messageId} {
+      // Read if member of the chat
+      allow read: if isSignedIn() && 
+        exists(/databases/$(database)/documents/chatMembers/$(request.auth.uid + '_' + resource.data.chatId));
+      
+      // Create with valid data
+      allow create: if isSignedIn() &&
+        request.resource.data.userId == request.auth.uid &&
+        request.resource.data.text is string &&
+        request.resource.data.text.size() <= 1000;
+      
+      // Only owner can update/delete
+      allow update, delete: if isOwner(resource.data.userId);
+    }
+    
+    // Admin-only collection
+    match /admin/{document=**} {
+      allow read, write: if isAdmin();
+    }
+  }
+}
+```
+
+---
+
+## 5. Cloud Functions
+
+```javascript
+// functions/index.js
+const functions = require('firebase-functions');
+const admin = require('firebase-admin');
+
+admin.initializeApp();
+const db = admin.firestore();
+
+// HTTP function
+exports.createUser = functions.https.onCall(async (data, context) => {
+  // Verify auth
+  if (!context.auth) {
+    throw new functions.https.HttpsError('unauthenticated', 'Must be signed in');
+  }
+  
+  // Create user document
+  await db.collection('users').doc(context.auth.uid).set({
+    name: data.name,
+    email: context.auth.token.email,
+    createdAt: admin.firestore.FieldValue.serverTimestamp()
+  });
+  
+  return { success: true };
+});
+
+// Firestore trigger
+exports.onUserCreate = functions.firestore
+  .document('users/{userId}')
+  .onCreate(async (snap, context) => {
+    const user = snap.data();
+    
+    // Send welcome email
+    await sendWelcomeEmail(user.email);
+    
+    // Initialize user settings
+    await db.collection('settings').doc(context.params.userId).set({
+      notifications: true,
+      theme: 'light'
+    });
+  });
+```
+
+---
+
+## 6. Anti-Patterns
+
+### ❌ No Security Rules
+
+```javascript
+// WRONG: Open database
+rules_version = '2';
+service cloud.firestore {
+  match /{document=**} {
+    allow read, write: if true; // ANYONE CAN READ/WRITE!
+  }
+}
+
+// CORRECT: Lock down by default
+match /{document=**} {
+  allow read, write: if false;
+}
+// Then allow specific access
+```
+
+### ❌ Listener on Large Collections
+
+```javascript
+// WRONG: Subscribe to ALL users
+const unsubscribe = onSnapshot(collection(db, 'users'), (snapshot) => {
+  // 1 million docs = $1000+ in reads!
+});
+
+// CORRECT: Always use query limits
+const q = query(
+  collection(db, 'users'),
+  where('active', '==', true),
+  limit(50)
+);
+```
+
+### ❌ Client-Side Admin Operations
+
+```javascript
+// WRONG: Delete in client
+await deleteDoc(doc(db, 'users', userId)); // Relies on client-side rules!
+
+// CORRECT: Use Cloud Function for sensitive ops
+const deleteUser = httpsCallable(functions, 'deleteUser');
+await deleteUser({ userId });
+```
+
+---
+
+## Related Skills
+
+- `nextjs-supabase-auth` - Supabase alternative
+- `api-patterns` - API design
+- `database-design` - Data modeling