vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-firestore/references/enterprise/flutter_setup.md

@@ -0,0 +1,180 @@
+# Cloud Firestore in Flutter
+
+This guide covers basic CRUD operations, type-safe data modeling, and real-time
+streams when using Cloud Firestore in a Flutter application via the
+`cloud_firestore` package.
+
+## 1. Setup
+
+Ensure you have added the required dependency:
+
+```bash
+flutter pub add cloud_firestore
+```
+
+Also, ensure FlutterFire is configured properly for your target platforms.
+
+______________________________________________________________________
+
+## 2. Best Practices: Type-Safe Models
+
+Instead of passing raw `Map<String, dynamic>` maps throughout your UI layer,
+define a domain model class with `fromFirestore` and `toFirestore` converters to
+maintain type safety.
+
+```dart
+import 'package:cloud_firestore/cloud_firestore.dart';
+
+class Item {
+  final String id;
+  final String name;
+  final String ownerId;
+  final DateTime createdAt;
+
+  Item({
+    required this.id,
+    required this.name,
+    required this.ownerId,
+    required this.createdAt,
+  });
+
+  factory Item.fromFirestore(DocumentSnapshot doc) {
+    final data = doc.data() as Map<String, dynamic>? ?? {};
+    return Item(
+      id: doc.id,
+      name: data['name'] as String? ?? '',
+      ownerId: data['ownerId'] as String? ?? '',
+      createdAt: data['createdAt'] is Timestamp 
+          ? (data['createdAt'] as Timestamp).toDate() 
+          : DateTime.now(),
+    );
+  }
+
+  Map<String, dynamic> toFirestore() {
+    return {
+      'name': name,
+      'ownerId': ownerId,
+      'createdAt': Timestamp.fromDate(createdAt),
+    };
+  }
+}
+```
+
+______________________________________________________________________
+
+## 3. The Service Layer
+
+Encapsulate all database interactions within a dedicated service class to keep
+your UI code clean and testable.
+
+### Initialization & References
+
+```dart
+class ItemService {
+  // For Enterprise Native Mode, you often need to specify a non-default database ID:
+  final FirebaseFirestore _db = FirebaseFirestore.instanceFor(
+    app: Firebase.app(),
+    databaseId: 'my-database-id',
+  );
+
+  // Define your collection reference
+  CollectionReference get _itemsRef => _db.collection('items');
+
+  // 1. Create Data
+  Future<void> createItem(Item item) async {
+    try {
+      await _itemsRef.add(item.toFirestore());
+    } catch (e) {
+      print("Error creating document: $e");
+    }
+  }
+
+  // 2. Read Data (One-Time Fetch)
+  Future<List<Item>> fetchItems(String ownerId) async {
+    try {
+      final querySnapshot = await _itemsRef
+          .where('ownerId', isEqualTo: ownerId)
+          .orderBy('createdAt', descending: true)
+          .get();
+
+      return querySnapshot.docs.map((doc) => Item.fromFirestore(doc)).toList();
+    } catch (e) {
+      print("Error fetching documents: $e");
+      return [];
+    }
+  }
+
+  // 3. Read Data (Real-Time Stream)
+  Stream<List<Item>> streamItems(String ownerId) {
+    return _itemsRef
+        .where('ownerId', isEqualTo: ownerId)
+        .snapshots()
+        .map((snapshot) {
+          // If a custom composite index is missing during prototyping, apply sorting client-side:
+          final items = snapshot.docs.map((doc) => Item.fromFirestore(doc)).toList();
+          items.sort((a, b) => b.createdAt.compareTo(a.createdAt));
+          return items;
+        });
+  }
+
+  // 4. Update Data
+  Future<void> updateItemName(String id, String newName) async {
+    try {
+      await _itemsRef.doc(id).update({'name': newName});
+    } catch (e) {
+      print("Error updating document: $e");
+    }
+  }
+
+  // 5. Delete Data
+  Future<void> deleteItem(String id) async {
+    try {
+      await _itemsRef.doc(id).delete();
+    } catch (e) {
+      print("Error deleting document: $e");
+    }
+  }
+}
+```
+
+______________________________________________________________________
+
+## 4. Listening to Streams in the UI (`StreamBuilder`)
+
+Use Flutter's `StreamBuilder` to rebuild the interface reactively whenever data
+changes in your database collection.
+
+```dart
+StreamBuilder<List<Item>>(
+  stream: itemService.streamItems(currentUser.uid),
+  builder: (context, snapshot) {
+    if (snapshot.hasError) {
+      return const Center(child: Text('Failed to load data'));
+    }
+
+    if (snapshot.connectionState == ConnectionState.waiting) {
+      return const Center(child: CircularProgressIndicator());
+    }
+
+    final items = snapshot.data ?? [];
+
+    if (items.isEmpty) {
+      return const Center(child: Text('No items found.'));
+    }
+
+    return ListView.builder(
+      itemCount: items.length,
+      itemBuilder: (context, index) {
+        final item = items[index];
+        return ListTile(
+          title: Text(item.name),
+          trailing: IconButton(
+            icon: const Icon(Icons.delete),
+            onPressed: () => itemService.deleteItem(item.id),
+          ),
+        );
+      },
+    );
+  },
+);
+```

package/dist/global-skills/firebase-firestore/references/enterprise/indexes.md

@@ -0,0 +1,135 @@
+# Firestore Indexes Reference
+
+Indexes helps to improve query performance. Firestore Enterprise edition does
+not create any indexes by default. By default, Firestore Enterprise performs a
+full collection scan to find documents that match a query, which can be slow and
+expensive for large collections. To avoid this, you can create indexes to
+optimize your queries.
+
+## Index Structure
+
+An index consists of the following:
+
+- a collection ID.
+- a list of fields in the given collection.
+- an order, either ascending or descending, for each field.
+
+### Index Ordering
+
+The order and sort direction of each field uniquely defines the index. For
+example, the following indexes are two distinct indexes and not interchangeable:
+
+- Field name `name` (ascending) and `population` (descending)
+- Field name `name` (descending) and `population` (ascending)
+
+### Index Density
+
+Dense indexes: By default, Firestore indexes store data from all documents in a
+collection. An index entry will be added for a document regardless of whether
+the document contains any of the fields specified in the index. Non-existent
+fields are treated as having a NULL value when generating index entries.
+
+Sparse indexes: To change this behavior, you can define the index as a sparse
+index. A sparse index indexes only the documents in the collection that contain
+a value (including null) for at least one of the indexed fields. A sparse index
+reduces storage costs and can improve performance.
+
+### Unique Indexes
+
+You can use unique index option to enforce unique values for the indexed fields.
+For indexes on multiple fields, each combination of values must be unique across
+the index. The database rejects any update and insert operations that attempt to
+create index entries with duplicate values.
+
+## Query Support Examples
+
+| Query Type                                                 | Index Required                       |
+| :--------------------------------------------------------- | :----------------------------------- |
+| **Simple Equality**<br>\`where("a",                        | Single-Field Index on field `a`      |
+| : "==", 1)\` : :                                           |                                      |
+| **Simple Range/Sort**<br>\`where("a",                      | Single-Field Index on field `a`      |
+| : ">", 1).orderBy("a")\` : :                               |                                      |
+| **Multiple Equality**<br>\`where("a",                      | Single-Field Index on field `a` and  |
+| : "==", 1).where("b", "==", 2)`       :`b\` :              |                                      |
+| \*\*Equality +                                             | **Composite Index** on field `a` and |
+| : Range/Sort\*\*<br>`where("a", "==",    : `b\` :          |                                      |
+| : 1).where("b", ">", 2)\` : :                              |                                      |
+| **Multiple Ranges**<br>\`where("a",                        | **Composite Index** on field `a` and |
+| : ">", 1).where("b", ">", 2)`         :`b\` :              |                                      |
+| \*\*Array Contains +                                       | **Composite Index** on field `tags`  |
+| : Equality\*\*<br>`where("tags",         : and `active\` : |                                      |
+| : "array-contains", : :                                    |                                      |
+| : "news").where("active", "==", true)\` : :                |                                      |
+
+If no indexes is present, Firestore Enterprise will perform a full collection
+scan to find documents that match a query.
+
+## Management
+
+### Config files
+
+Your indexes should be defined in `firestore.indexes.json` (pointed to by
+`firebase.json`).
+
+Define a dense index:
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "cities",
+      "queryScope": "COLLECTION",
+      "density": "DENSE",
+      "fields": [
+        { "fieldPath": "country", "order": "ASCENDING" },
+        { "fieldPath": "population", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+Define a sparse-any index:
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "cities",
+      "queryScope": "COLLECTION",
+      "density": "SPARSE_ANY",
+      "fields": [
+        { "fieldPath": "country", "order": "ASCENDING" },
+        { "fieldPath": "population", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+Define a unique index:
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "cities",
+      "queryScope": "COLLECTION",
+      "density": "SPARSE_ANY",
+      "unique": true,
+      "fields": [
+        { "fieldPath": "country", "order": "ASCENDING" },
+        { "fieldPath": "population", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+### CLI Commands
+
+Deploy indexes only:
+`bash npx firebase-tools@latest -y deploy --only firestore:indexes`

package/dist/global-skills/firebase-firestore/references/enterprise/ios_setup.md

@@ -0,0 +1,189 @@
+# Firestore Enterprise Native Mode on iOS
+
+This guide walks you through using the Cloud Firestore SDK in your iOS app using
+Swift.
+
+# ⛔️ CRITICAL RULE: NO FirebaseFirestoreSwift ⛔️
+
+UNDER NO CIRCUMSTANCES should you import, link against, or configure a project
+to use `FirebaseFirestoreSwift`.
+
+As of Firebase SDK v11+, all Swift-specific features (including `@DocumentID`,
+`@ServerTimestamp`, and `Codable` support) have been fully merged into the main
+`FirebaseFirestore` module.
+
+- NEVER add `.external(name: "FirebaseFirestoreSwift")` or similar to SPM or
+  Xcode configurations.
+- NEVER write `import FirebaseFirestoreSwift` in any Swift file.
+- ONLY use `import FirebaseFirestore`.
+
+This is a zero-tolerance constraint. Using `FirebaseFirestoreSwift` is
+fundamentally incorrect and unacceptable.
+
+# ⛔️ CRITICAL RULE: NO INLINE INITIALIZATION ⛔️
+
+NEVER write `let db = Firestore.firestore()` or `Firestore.firestore(database:)`
+as an inline class or struct property if there is ANY chance the object is
+instantiated before `FirebaseApp.configure()` executes in the app root.
+
+- **FATAL CRASH:**
+  `@Observable class DataManager { let db = Firestore.firestore() }` initialized
+  as a `@State` in the App root.
+- **SAFE PATTERN:** Initialize `Firestore.firestore()` lazily
+  (`lazy var db = Firestore.firestore()`) OR explicitly initialize the manager
+  *after* `FirebaseApp.configure()` finishes.
+
+## 1. Import and Initialize
+
+Ensure you have installed the `FirebaseFirestore` SDK. Use the
+`xcode-project-setup` skill to automate adding the SPM dependency to the Xcode
+project.
+
+```swift
+import FirebaseFirestore
+```
+
+Initialize an instance of Cloud Firestore. **CRITICAL**: Enterprise databases
+require a custom database ID and cannot use the `(default)` instance.
+
+```swift
+// Replace "your-enterprise-database-id" with your actual database ID
+let db = Firestore.firestore(database: "your-enterprise-database-id")
+```
+
+## 2. Type-Safe Data Models (Codable)
+
+To leverage modern Swift data modeling, define your data as `Codable` structs.
+The main `FirebaseFirestore` module automatically supports mapping these types.
+
+```swift
+struct User: Codable {
+    @DocumentID var id: String?
+    var firstName: String
+    var lastName: String
+    var born: Int
+}
+```
+
+## 3. Basic CRUD Operations
+
+The operations are identical to standard Firestore, but ensure you use the `db`
+instance initialized with your Enterprise database ID.
+
+### Writing Data (Modern Concurrency & Codable)
+
+```swift
+let user = User(firstName: "Ada", lastName: "Lovelace", born: 1815)
+
+do {
+    // Add a new document with a generated ID using Codable
+    let ref = try db.collection("users").addDocument(from: user)
+    print("Document added with ID: \(ref.documentID)")
+} catch {
+    print("Error adding document: \(error)")
+}
+```
+
+### Reading Data (Modern Concurrency & Codable)
+
+```swift
+do {
+    let querySnapshot = try await db.collection("users").getDocuments()
+    
+    // Map documents to the User struct automatically
+    let users = querySnapshot.documents.compactMap { document in
+        try? document.data(as: User.self)
+    }
+    
+    for user in users {
+        print("Found user: \(user.firstName) \(user.lastName)")
+    }
+} catch {
+    print("Error getting documents: \(error)")
+}
+```
+
+## 4. Pipeline Queries
+
+Firestore Enterprise supports Pipeline operations for complex queries.
+
+### Initialization
+
+```swift
+let pipeline = db.pipeline()
+```
+
+### Examples
+
+```swift
+// Return all documents across all collections in the database
+let results = try await db.pipeline().database().execute()
+
+// Filtered query
+let results = try await db.pipeline()
+    .collection("cities")
+    .where(Field("name").equal(Constant("Toronto")))
+    .execute()
+
+// Compound query
+let results = try await db.pipeline()
+    .collection("books")
+    .where(Field("rating").equal(5) && Field("published").lessThan(1900))
+    .execute()
+```
+
+## 5. Realtime Listeners in SwiftUI (Lifecycle Best Practices)
+
+When implementing Firestore realtime listeners (`addSnapshotListener`) within a
+SwiftUI application, you **MUST** tie the listener lifecycle to the view's
+identity using `.task(id:)`, NOT `.onDisappear`.
+
+### ⛔️ UNSAFE PATTERN (.onDisappear)
+
+Presenting a `.sheet` or `.fullScreenCover` can trigger the underlying view's
+`onDisappear` method. If you stop your listener here, the feed will stop
+updating while the sheet is open, and won't resume when it's dismissed.
+
+### ✅ SAFE PATTERN (.task with deinit)
+
+Because `addSnapshotListener` is a synchronous call, placing it inside a `.task`
+means the task completes immediately. This breaks SwiftUI's automatic
+cancellation mechanism.
+
+To safely manage traditional Firebase listeners in SwiftUI, you must use
+**`deinit`** to handle memory cleanup when the view is destroyed, and
+**`.task(id:)`** to handle data identity changes while the view is active.
+
+```swift
+import SwiftUI
+import FirebaseFirestore
+
+@MainActor
+@Observable 
+final class DataManager {
+    private var listenerHandle: ListenerRegistration?
+    var data: [String] = []
+    
+    func startListening(for userId: String) {
+        // 1. Clean up any existing listener to prevent duplicates if the ID changes
+        stopListening()
+        
+        // 2. Start the regular listener and capture the handle
+        // Note: Using the global default instance here, make sure to use your enterprise instance if applicable
+        // For enterprise, you might need to pass the db instance or use a shared manager.
+        listenerHandle = Firestore.firestore(database: "your-enterprise-database-id").collection("users").document(userId).addSnapshotListener { snapshot, error in
+            // Handle updates
+        }
+    }
+    
+    func stopListening() {
+        listenerHandle?.remove()
+        listenerHandle = nil
+    }
+    
+    // 3. Guarantee cleanup when the View is destroyed and this object is deallocated
+    isolated deinit {
+        stopListening()
+    }
+}
+```

package/dist/global-skills/firebase-firestore/references/enterprise/provisioning.md

@@ -0,0 +1,118 @@
+# Provisioning Firestore Enterprise Native Mode
+
+## Manual Initialization
+
+Initialize the following firebase configuration files manually. Do not use
+`npx -y firebase-tools@latest init`, as it expects interactive inputs.
+
+1. **Create a Firestore Enterprise Database**: Create a Firestore Enterprise
+   database using the Firebase CLI.
+1. **Create `firebase.json`**: This file contains database configuration for the
+   Firebase CLI.
+1. **Create `firestore.rules`**: This file contains your security rules.
+1. **Create `firestore.indexes.json`**: This file contains your index
+   definitions.
+
+### 1. Create a Firestore Enterprise Database
+
+If the user needs to create a new database, ask the user what location to use.
+Run `npx -y firebase-tools@latest firestore:locations` to get the list of
+options. Suggest colocating with other resources if applicable.
+
+Use the following command to create a Firestore Enterprise database:
+
+```bash
+firebase firestore:databases:create my-database-id \
+  --location="<selected-location>" \
+  --edition="enterprise" \
+  --firestore-data-access="ENABLED" \
+  --mongodb-compatible-data-access="DISABLED"
+```
+
+This will create an enterprise database in the selected location with native
+mode enabled. A database id is required to create an enterprise database and the
+database id must not be `(default)`. To enable realtime-updates feature, use
+`--realtime-updates` flag.
+
+```bash
+firebase firestore:databases:create my-database-id \
+  --location="<selected-location>" \
+  --edition="enterprise" \
+  --firestore-data-access="ENABLED" \
+  --mongodb-compatible-data-access="DISABLED" \
+  --realtime-updates="ENABLED"
+```
+
+### 2. Create `firebase.json`
+
+Create a file named `firebase.json` in your project root with the following
+content (edit `database` and `location` to match the ones you created above). If
+this file already exists, instead append to the existing JSON:
+
+```json
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json",
+    "edition": "enterprise",
+    "database": "my-database-id",
+    "location": "<selected-location>"
+  }
+}
+```
+
+### 2. Create `firestore.rules`
+
+Create a file named `firestore.rules`. A good starting point (locking down the
+database) is:
+
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /{document=**} {
+      allow read, write: if false;
+    }
+  }
+}
+```
+
+*See [security_rules.md](security_rules.md) for how to write actual rules.*
+
+### 3. Create `firestore.indexes.json`
+
+Create a file named `firestore.indexes.json` with an empty configuration to
+start:
+
+```json
+{
+  "indexes": [],
+  "fieldOverrides": []
+}
+```
+
+*See [indexes.md](indexes.md) for how to configure indexes.*
+
+## Deploy rules and indexes
+
+```bash
+# To deploy all rules and indexes
+firebase deploy --only firestore
+
+# To deploy just rules
+firebase deploy --only firestore:rules
+
+# To deploy just indexes
+firebase deploy --only firestore:indexes
+```
+
+## Local Emulation
+
+To run Firestore locally for development and testing:
+
+```bash
+firebase emulators:start --only firestore
+```
+
+This starts the Firestore emulator, typically on port 8080. You can interact
+with it using the Emulator UI (usually at http://localhost:4000/firestore).