@intentsolutionsio/jeremy-firestore 2.0.0

package/skills/firestore-operations-manager/references/examples.md

@@ -0,0 +1,211 @@
+# Firestore Operations Manager: Examples
+
+## Example 1: Fix a Missing Composite Index
+
+Query fails with `FAILED_PRECONDITION: The query requires an index`.
+
+```typescript
+// This query needs a composite index on (status ASC, createdAt DESC)
+const snapshot = await db.collection("orders")
+  .where("status", "==", "pending")
+  .orderBy("createdAt", "desc")
+  .limit(50).get();
+```
+
+The error message includes a Firebase Console URL to auto-create the index. Or add manually to `firestore.indexes.json`:
+
+```json
+{
+  "indexes": [{
+    "collectionGroup": "orders", "queryScope": "COLLECTION",
+    "fields": [
+      { "fieldPath": "status", "order": "ASCENDING" },
+      { "fieldPath": "createdAt", "order": "DESCENDING" }
+    ]
+  }],
+  "fieldOverrides": []
+}
+```
+
+Deploy: `firebase deploy --only firestore:indexes` then check status with `firebase firestore:indexes` (wait for READY).
+
+**Prevention**: Any `where()` + `orderBy()` on different fields requires a composite index. Single-field queries do not.
+
+---
+
+## Example 2: Batch Migrate 100k Documents with Checkpoints
+
+Add a `status` field (default: `"active"`) to all documents in the `users` collection.
+
+```typescript
+import * as admin from "firebase-admin";
+admin.initializeApp();
+const db = admin.firestore();
+
+const MIGRATION_ID = "add-status-field-2026-03";
+const BATCH_SIZE = 500;
+
+interface Checkpoint { lastDocId: string; processed: number; skipped: number; status: string; }
+
+async function getCheckpoint(): Promise<Checkpoint | null> {
+  const doc = await db.collection("_migrations").doc(MIGRATION_ID).get();
+  return doc.exists ? (doc.data() as Checkpoint) : null;
+}
+
+async function saveCheckpoint(cp: Checkpoint): Promise<void> {
+  await db.collection("_migrations").doc(MIGRATION_ID).set({
+    ...cp, updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+  });
+}
+
+async function migrate() {
+  let checkpoint = await getCheckpoint();
+  let processed = checkpoint?.processed || 0;
+  let skipped = checkpoint?.skipped || 0;
+
+  while (true) {
+    let query = db.collection("users").orderBy("__name__").limit(BATCH_SIZE);
+    if (checkpoint?.lastDocId) {
+      const lastDoc = await db.collection("users").doc(checkpoint.lastDocId).get();
+      if (lastDoc.exists) query = query.startAfter(lastDoc);
+    }
+
+    const snapshot = await query.get();
+    if (snapshot.empty) break;
+
+    const batch = db.batch();
+    let batchCount = 0;
+    for (const doc of snapshot.docs) {
+      if (doc.data().status !== undefined) { skipped++; continue; } // Idempotent
+      batch.update(doc.ref, { status: "active" });
+      batchCount++;
+    }
+    if (batchCount > 0) await batch.commit();
+    processed += batchCount;
+
+    const lastDoc = snapshot.docs[snapshot.docs.length - 1];
+    checkpoint = { lastDocId: lastDoc.id, processed, skipped, status: "in_progress" };
+    await saveCheckpoint(checkpoint);
+    console.log(`Processed: ${processed}, Skipped: ${skipped}`);
+  }
+
+  await saveCheckpoint({ lastDocId: checkpoint?.lastDocId || "", processed, skipped, status: "completed" });
+  console.log(`Done. Processed: ${processed}, Skipped: ${skipped}`);
+}
+migrate().catch(console.error);
+```
+
+Run against emulator first: `FIRESTORE_EMULATOR_HOST=localhost:8080 npx ts-node migrate.ts`
+
+Cost estimate: 100k reads ($0.06) + 100k writes ($0.18) = ~$0.24.
+
+---
+
+## Example 3: Security Rules for Multi-Tenant App
+
+Data model: `tenants/{tenantId}`, `tenants/{tenantId}/members/{userId}`, `tenants/{tenantId}/projects/{projId}`.
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function isAuth() { return request.auth != null; }
+    function isMember(tenantId) {
+      return isAuth() && exists(/databases/$(database)/documents/tenants/$(tenantId)/members/$(request.auth.uid));
+    }
+    function isTenantAdmin(tenantId) {
+      return isMember(tenantId) &&
+        get(/databases/$(database)/documents/tenants/$(tenantId)/members/$(request.auth.uid)).data.role == 'admin';
+    }
+
+    match /tenants/{tenantId} {
+      allow read: if isMember(tenantId);
+      allow update: if isTenantAdmin(tenantId);
+      allow create, delete: if false; // Admin SDK only
+    }
+    match /tenants/{tenantId}/members/{userId} {
+      allow read: if isMember(tenantId);
+      allow write: if isTenantAdmin(tenantId);
+    }
+    match /tenants/{tenantId}/projects/{projId} {
+      allow read: if isMember(tenantId);
+      allow create: if isMember(tenantId) && request.resource.data.createdBy == request.auth.uid;
+      allow update: if isMember(tenantId) && resource.data.createdBy == request.auth.uid;
+      allow delete: if isTenantAdmin(tenantId);
+    }
+  }
+}
+```
+
+Emulator test:
+
+```typescript
+const testEnv = await initializeTestEnvironment({
+  projectId: "demo-test", firestore: { rules: readFileSync("firestore.rules", "utf8") },
+});
+await testEnv.withSecurityRulesDisabled(async (ctx) => {
+  await ctx.firestore().doc("tenants/acme").set({ name: "Acme" });
+  await ctx.firestore().doc("tenants/acme/members/alice").set({ role: "admin" });
+  await ctx.firestore().doc("tenants/acme/members/bob").set({ role: "member" });
+});
+
+const alice = testEnv.authenticatedContext("alice");
+await assertSucceeds(alice.firestore().doc("tenants/acme").update({ name: "Acme Inc" }));
+const bob = testEnv.authenticatedContext("bob");
+await assertFails(bob.firestore().doc("tenants/acme").update({ name: "Bob Corp" }));
+const eve = testEnv.authenticatedContext("eve");
+await assertFails(eve.firestore().doc("tenants/acme").get()); // Not a member
+```
+
+---
+
+## Example 4: Cursor-Based Pagination
+
+Fetch products by category, 20 per page, with stable ordering.
+
+```typescript
+interface PaginationCursor { lastPrice: number; lastDocId: string; }
+
+async function getProductPage(category: string, pageSize = 20, cursor?: PaginationCursor) {
+  let query = db.collection("products")
+    .where("category", "==", category)
+    .orderBy("price", "asc")
+    .orderBy("__name__", "asc")  // Tiebreaker for stable pagination
+    .limit(pageSize + 1);        // One extra to detect next page
+
+  if (cursor) query = query.startAfter(cursor.lastPrice, cursor.lastDocId);
+
+  const snapshot = await query.get();
+  const hasNextPage = snapshot.docs.length > pageSize;
+  const docs = snapshot.docs.slice(0, pageSize);
+
+  return {
+    items: docs.map((doc) => ({ id: doc.id, ...doc.data() })),
+    nextCursor: hasNextPage
+      ? { lastPrice: docs[docs.length - 1].data().price, lastDocId: docs[docs.length - 1].id }
+      : null,
+    hasNextPage,
+  };
+}
+
+// Usage
+const page1 = await getProductPage("electronics");
+if (page1.nextCursor) {
+  const page2 = await getProductPage("electronics", 20, page1.nextCursor);
+}
+```
+
+Required composite index in `firestore.indexes.json`:
+
+```json
+{ "collectionGroup": "products", "queryScope": "COLLECTION",
+  "fields": [
+    { "fieldPath": "category", "order": "ASCENDING" },
+    { "fieldPath": "price", "order": "ASCENDING" }
+  ]}
+```
+
+`__name__` is automatically included as a tiebreaker -- no explicit index entry needed.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/firestore-operations-manager/references/implementation.md

@@ -0,0 +1,214 @@
+# Firestore Operations Manager: Implementation Guide
+
+## Firestore Data Model Patterns
+
+### Subcollections vs Root Collections
+
+| Pattern | When to Use | Trade-off |
+|---------|-------------|-----------|
+| Root collection (`/orders`) | Query across all documents regardless of parent | Must store parent IDs as fields; no automatic scoping |
+| Subcollection (`/users/{uid}/orders`) | Data naturally owned by a parent; security rules scope by parent | Cannot query across all users' orders without collection group query |
+| Collection group query | Cross-parent queries on subcollections | Must create collection group index; same rules apply to all subcollections with that name |
+
+### Denormalization
+
+Firestore has no joins. Duplicate data where read patterns require it:
+
+```typescript
+// Store user name directly on order (avoids extra read)
+await db.collection("orders").add({
+  userId: "alice123", userName: "Alice Smith",
+  items: [...], total: 49.99,
+  createdAt: admin.firestore.FieldValue.serverTimestamp(),
+});
+
+// When name changes, batch-update all denormalized copies
+async function updateUserName(userId: string, newName: string) {
+  const orders = await db.collection("orders").where("userId", "==", userId).get();
+  const BATCH_SIZE = 500;
+  for (let i = 0; i < orders.docs.length; i += BATCH_SIZE) {
+    const batch = db.batch();
+    orders.docs.slice(i, i + BATCH_SIZE).forEach((doc) => batch.update(doc.ref, { userName: newName }));
+    await batch.commit();
+  }
+}
+```
+
+## Batch Write Mechanics
+
+### The 500-Operation Limit
+
+Each `WriteBatch.commit()` accepts max 500 operations (`set`, `update`, `delete`). Exceeding throws `INVALID_ARGUMENT`.
+
+### Reusable Chunked Batch Writer
+
+```typescript
+async function batchWrite<T>(
+  items: T[],
+  writeFn: (batch: admin.firestore.WriteBatch, item: T) => void,
+  options: { batchSize?: number; onProgress?: (done: number, total: number) => void } = {}
+) {
+  const { batchSize = 500, onProgress } = options;
+  let processed = 0;
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = db.batch();
+    items.slice(i, i + batchSize).forEach((item) => writeFn(batch, item));
+    await batch.commit();
+    processed += Math.min(batchSize, items.length - i);
+    onProgress?.(processed, items.length);
+  }
+  return { processed };
+}
+```
+
+### Retry Logic
+
+```typescript
+async function commitWithRetry(batch: admin.firestore.WriteBatch, maxRetries = 3): Promise<void> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try { await batch.commit(); return; }
+    catch (err: any) {
+      if (attempt === maxRetries) throw err;
+      if (err.code === 10 /* ABORTED */ || err.code === 14 /* UNAVAILABLE */) {
+        await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000 + Math.random() * 500));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+```
+
+## Composite Index Design
+
+### When Indexes Are Required
+
+| Query Pattern | Index Needed? |
+|---------------|---------------|
+| Single `where('field', '==', value)` | No (auto-indexed) |
+| Single `where('field', '>', value)` | No (auto-indexed) |
+| `where('a', '==', v1).where('b', '==', v2)` | Yes (composite) |
+| `where('a', '==', v).orderBy('b')` | Yes (unless a == b) |
+| `where('a', '>', v).orderBy('a')` | No (same field) |
+| `where('a', '>', v).orderBy('b')` | Yes (a must be first orderBy) |
+| `where('a', 'array-contains', v).orderBy('b')` | Yes (composite) |
+
+### Index File Format
+
+```json
+{ "indexes": [
+  { "collectionGroup": "products", "queryScope": "COLLECTION",
+    "fields": [{ "fieldPath": "category", "order": "ASCENDING" }, { "fieldPath": "price", "order": "ASCENDING" }] },
+  { "collectionGroup": "orders", "queryScope": "COLLECTION",
+    "fields": [{ "fieldPath": "userId", "order": "ASCENDING" }, { "fieldPath": "createdAt", "order": "DESCENDING" }] }
+], "fieldOverrides": [] }
+```
+
+Deploy: `firebase deploy --only firestore:indexes`. Large collections (>1M docs) can take hours. Deploy indexes before query code.
+
+## Security Rules Testing Workflow
+
+```bash
+npm install -D @firebase/rules-unit-testing firebase-admin
+```
+
+```typescript
+import { initializeTestEnvironment, assertSucceeds, assertFails, RulesTestEnvironment } from "@firebase/rules-unit-testing";
+import { readFileSync } from "fs";
+
+let testEnv: RulesTestEnvironment;
+beforeAll(async () => {
+  testEnv = await initializeTestEnvironment({
+    projectId: "demo-test", firestore: { rules: readFileSync("firestore.rules", "utf8") },
+  });
+});
+afterAll(() => testEnv.cleanup());
+afterEach(() => testEnv.clearFirestore());
+
+test("owner can read own profile", async () => {
+  await testEnv.withSecurityRulesDisabled(async (ctx) => {
+    await ctx.firestore().doc("users/alice").set({ name: "Alice", role: "user" });
+  });
+  await assertSucceeds(testEnv.authenticatedContext("alice").firestore().doc("users/alice").get());
+});
+
+test("unauthenticated cannot read profiles", async () => {
+  await assertFails(testEnv.unauthenticatedContext().firestore().doc("users/alice").get());
+});
+```
+
+Run: `firebase emulators:exec --only firestore "npx jest tests/firestore.rules.test.ts"`
+
+## Migration Strategies
+
+### Backfill (Add New Field)
+
+Firestore cannot query for missing fields. Query all, skip docs that already have the field:
+
+```typescript
+for (const doc of snapshot.docs) {
+  if (doc.data().status !== undefined) { skipped++; continue; }
+  batch.update(doc.ref, { status: "active" });
+}
+```
+
+### Transform (Modify Existing Field)
+
+```typescript
+const TRANSFORMS: Record<string, string> = {
+  "free": "free_tier", "Free": "free_tier", "premium": "premium_tier", "enterprise": "enterprise_tier",
+};
+for (const doc of snapshot.docs) {
+  const newType = TRANSFORMS[doc.data().type];
+  if (!newType || doc.data().type === newType) { skipped++; continue; }
+  batch.update(doc.ref, { type: newType });
+}
+```
+
+### Collection Move
+
+```typescript
+async function moveCollection(source: string, target: string) {
+  let lastDoc: admin.firestore.DocumentSnapshot | null = null;
+  while (true) {
+    let query = db.collection(source).orderBy("__name__").limit(500);
+    if (lastDoc) query = query.startAfter(lastDoc);
+    const snapshot = await query.get();
+    if (snapshot.empty) break;
+    const batch = db.batch();
+    for (const doc of snapshot.docs) {
+      batch.set(db.collection(target).doc(doc.id), doc.data());
+      batch.delete(doc.ref);
+    }
+    await batch.commit();
+    lastDoc = snapshot.docs[snapshot.docs.length - 1];
+  }
+}
+```
+
+**Warning**: Not atomic across batches. Run reconciliation after failures.
+
+## Emulator Setup
+
+```json
+{ "emulators": { "firestore": { "port": 8080 }, "auth": { "port": 9099 }, "ui": { "enabled": true, "port": 4000 } } }
+```
+
+Connect Admin SDK:
+
+```typescript
+process.env.FIRESTORE_EMULATOR_HOST = "localhost:8080";
+process.env.FIREBASE_AUTH_EMULATOR_HOST = "localhost:9099";
+admin.initializeApp({ projectId: "demo-test" });
+```
+
+Persist data between restarts:
+
+```bash
+firebase emulators:start --export-on-exit=./emulator-data --import=./emulator-data
+```
+
+Add `emulator-data/` to `.gitignore`.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/firestore-operations-manager/scripts/setup-firestore.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# setup-firestore.sh - Setup Firestore for Firebase/GCP project
+
+set -euo pipefail
+
+PROJECT_ID="${1:-${GCP_PROJECT_ID:-}}"
+
+if [[ -z "$PROJECT_ID" ]]; then
+    echo "Usage: $0 <PROJECT_ID>"
+    echo "Setup Firestore database with security rules"
+    exit 1
+fi
+
+echo "Setting up Firestore"
+echo "Project: $PROJECT_ID"
+echo ""
+
+# Enable Firestore API
+echo "Enabling Firestore API..."
+gcloud services enable firestore.googleapis.com --project="$PROJECT_ID"
+
+# Create Firestore database (Native mode)
+echo "Creating Firestore database..."
+gcloud firestore databases create \
+    --location=us-central1 \
+    --project="$PROJECT_ID" || echo "Database may already exist"
+
+# Create security rules file
+cat > firestore.rules <<'EOF'
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // User documents
+    match /users/{userId} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+
+    // Public documents
+    match /public/{document=**} {
+      allow read: if true;
+      allow write: if request.auth != null;
+    }
+
+    // A2A agent communication
+    function isServiceAccount() {
+      return request.auth.token.email.matches('.*@.*\\.iam\\.gserviceaccount\\.com$');
+    }
+
+    match /agent_sessions/{sessionId} {
+      allow read, write: if isServiceAccount();
+    }
+
+    match /agent_memory/{agentId}/{document=**} {
+      allow read, write: if isServiceAccount();
+    }
+  }
+}
+EOF
+
+echo "✓ Security rules created: firestore.rules"
+echo ""
+echo "Deploy security rules with:"
+echo "  firebase deploy --only firestore:rules"