vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-data-connect/templates.md

@@ -0,0 +1,318 @@
+# Templates
+
+Ready-to-use templates for common Firebase SQL Connect patterns.
+
+______________________________________________________________________
+
+## Basic CRUD Schema
+
+```graphql
+# schema.gql
+type Item @table {
+  id: UUID! @default(expr: "uuidV4()")
+  name: String!
+  description: String
+  createdAt: Timestamp! @default(expr: "request.time")
+  updatedAt: Timestamp! @default(expr: "request.time")
+}
+```
+
+```graphql
+# queries.gql
+query ListItems @auth(level: PUBLIC) {
+  items(orderBy: [{ createdAt: DESC }]) {
+    id name description createdAt
+  }
+}
+
+query GetItem($id: UUID!) @auth(level: PUBLIC) {
+  item(id: $id) { id name description createdAt updatedAt }
+}
+```
+
+```graphql
+# mutations.gql
+mutation CreateItem($name: String!, $description: String) @auth(level: USER) {
+  item_insert(data: { name: $name, description: $description })
+}
+
+mutation UpdateItem($id: UUID!, $name: String, $description: String) @auth(level: USER) {
+  item_update(id: $id, data: {
+    name: $name,
+    description: $description,
+    updatedAt_expr: "request.time"
+  })
+}
+
+mutation DeleteItem($id: UUID!) @auth(level: USER) {
+  item_delete(id: $id)
+}
+```
+
+______________________________________________________________________
+
+## User-Owned Resources
+
+```graphql
+# schema.gql
+type User @table(key: "uid") {
+  uid: String! @default(expr: "auth.uid")
+  email: String! @unique
+  displayName: String
+}
+
+type Note @table {
+  id: UUID! @default(expr: "uuidV4()")
+  owner: User!
+  title: String!
+  content: String
+  createdAt: Timestamp! @default(expr: "request.time")
+}
+```
+
+```graphql
+# queries.gql
+query MyNotes @auth(level: USER) {
+  notes(
+    where: { owner: { uid: { eq_expr: "auth.uid" }}},
+    orderBy: [{ createdAt: DESC }]
+  ) { id title content createdAt }
+}
+
+query GetMyNote($id: UUID!) @auth(level: USER) {
+  note(
+    first: { where: {
+      id: { eq: $id },
+      owner: { uid: { eq_expr: "auth.uid" }}
+    }}
+  ) { id title content }
+}
+```
+
+```graphql
+# mutations.gql
+mutation CreateNote($title: String!, $content: String) @auth(level: USER) {
+  note_insert(data: {
+    owner: { uid_expr: "auth.uid" },
+    title: $title,
+    content: $content
+  })
+}
+
+mutation UpdateNote($id: UUID!, $title: String, $content: String) @auth(level: USER) {
+  note_update(
+    first: { where: { id: { eq: $id }, owner: { uid: { eq_expr: "auth.uid" }}}},
+    data: { title: $title, content: $content }
+  )
+}
+
+mutation DeleteNote($id: UUID!) @auth(level: USER) {
+  note_delete(
+    first: { where: { id: { eq: $id }, owner: { uid: { eq_expr: "auth.uid" }}}}
+  )
+}
+```
+
+______________________________________________________________________
+
+## Many-to-Many Relationship
+
+```graphql
+# schema.gql
+type Tag @table {
+  id: UUID! @default(expr: "uuidV4()")
+  name: String! @unique
+}
+
+type Article @table {
+  id: UUID! @default(expr: "uuidV4()")
+  title: String!
+  content: String!
+}
+
+type ArticleTag @table(key: ["article", "tag"]) {
+  article: Article!
+  tag: Tag!
+}
+```
+
+```graphql
+# queries.gql
+query ArticlesByTag($tagName: String!) @auth(level: PUBLIC) {
+  articles(where: {
+    articleTags_on_article: { tag: { name: { eq: $tagName }}}
+  }) {
+    id title
+    tags: tags_via_ArticleTag { name }
+  }
+}
+
+query ArticleWithTags($id: UUID!) @auth(level: PUBLIC) {
+  article(id: $id) {
+    id title content
+    tags: tags_via_ArticleTag { id name }
+  }
+}
+```
+
+```graphql
+# mutations.gql
+mutation AddTagToArticle($articleId: UUID!, $tagId: UUID!) @auth(level: USER) {
+  articleTag_insert(data: {
+    article: { id: $articleId },
+    tag: { id: $tagId }
+  })
+}
+
+mutation RemoveTagFromArticle($articleId: UUID!, $tagId: UUID!) @auth(level: USER) {
+  articleTag_delete(key: { articleId: $articleId, tagId: $tagId })
+}
+```
+
+______________________________________________________________________
+
+## dataconnect.yaml Template
+
+```yaml
+specVersion: "v1"
+serviceId: "my-service"
+location: "us-central1"
+schema:
+  source: "./schema"
+  datasource:
+    postgresql:
+      database: "fdcdb"
+      cloudSql:
+        instanceId: "my-instance"
+connectorDirs: ["./connector"]
+```
+
+______________________________________________________________________
+
+## connector.yaml Template
+
+```yaml
+connectorId: "default"
+generate:
+  javascriptSdk:
+    outputDir: "../web/src/lib/dataconnect"
+    package: "@myapp/dataconnect"
+  kotlinSdk:
+    outputDir: "../android/app/src/main/kotlin/com/myapp/dataconnect"
+    package: "com.myapp.dataconnect"
+  swiftSdk:
+    outputDir: "../ios/MyApp/DataConnect"
+  dartSdk:
+    outputDir: "../flutter/lib/dataconnect"
+    package: myapp_dataconnect
+```
+
+______________________________________________________________________
+
+## Firebase Init Commands
+
+```bash
+# Initialize SQL Connect in project
+npx -y firebase-tools@latest init dataconnect
+
+# Initialize with specific project
+npx -y firebase-tools@latest use <project-id>
+npx -y firebase-tools@latest init dataconnect
+
+# Start emulator for development
+npx -y firebase-tools@latest emulators:start --only dataconnect
+
+# Generate SDKs
+npx -y firebase-tools@latest dataconnect:sdk:generate
+
+# Deploy to production
+npx -y firebase-tools@latest deploy --only dataconnect
+```
+
+______________________________________________________________________
+
+## SDK Initialization (Web)
+
+```typescript
+// lib/firebase.ts
+import { initializeApp } from 'firebase/app';
+import { getAuth } from 'firebase/auth';
+import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
+import { connectorConfig } from '@myapp/dataconnect';
+
+const firebaseConfig = {
+  apiKey: "...",
+  authDomain: "...",
+  projectId: "...",
+};
+
+export const app = initializeApp(firebaseConfig);
+export const auth = getAuth(app);
+export const dataConnect = getDataConnect(app, connectorConfig);
+
+// Connect to emulator in development
+if (import.meta.env.DEV) {
+  connectDataConnectEmulator(dataConnect, 'localhost', 9399);
+}
+```
+
+```typescript
+// Example usage
+import { listItems, createItem } from '@myapp/dataconnect';
+
+// List items
+const { data } = await listItems();
+console.log(data.items);
+
+// Create item (requires auth)
+await createItem({ name: 'New Item', description: 'Description' });
+```
+
+______________________________________________________________________
+
+## Realtime Query Templates
+
+### Time-Based Polling
+
+```graphql
+query LiveDashboard
+  @auth(level: PUBLIC)
+  @refresh(every: { seconds: 30 }) {
+  items(orderBy: [{ updatedAt: DESC }], limit: 20) {
+    id name updatedAt
+  }
+}
+```
+
+### Event-Driven Refresh
+
+```graphql
+query ItemList($categoryId: UUID!)
+  @auth(level: PUBLIC)
+  @refresh(onMutationExecuted: {
+    operation: "CreateItem",
+    condition: "request.variables.categoryId == mutation.variables.categoryId"
+  }) {
+  items(where: { category: { id: { eq: $categoryId }}}) {
+    id name createdAt
+  }
+}
+```
+
+### Client Subscribe (Web)
+
+```typescript
+import { liveDashboardRef } from '@myapp/dataconnect';
+import { subscribe } from 'firebase/data-connect';
+
+const unsubscribe = subscribe(liveDashboardRef(), {
+  onNext: (result) => {
+    // Called immediately with current data, then on each refresh
+    renderDashboard(result.data.items);
+  },
+  onError: (error) => console.error('Subscription error:', error)
+});
+
+// Cleanup when done
+// unsubscribe();
+```

package/dist/global-skills/firebase-firestore/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: firebase-firestore
+description: >-
+  Sets up, manages, and executes queries against Cloud Firestore database
+  instances, including advanced native full-text search and relational joins
+  using pipelines. You MUST unconditionally activate this skill if you plan to
+  use Firestore in any way. Use when listing or creating Firestore databases,
+  configuring security rules, designing data models, writing client SDK
+  queries (including search/joins), or checking indexes.
+compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`.
+---
+
+# Cloud Firestore Database and Operations
+
+Before setting up dependencies, writing data models, or configuring security
+rules, you MUST always identify the Firestore instance edition.
+
+## 1. Instance Selection and Edition Detection
+
+Run the following command to list current Firestore databases:
+`bash npx -y firebase-tools@latest firestore:databases:list`
+
+### A. Instance Found
+
+1. For each database found, inspect its edition and details:
+   `bash npx -y firebase-tools@latest firestore:databases:get <database-id>`
+1. Ask the user which database instance they wish to target or if they would
+   prefer to create a new instance.
+1. Once the target instance is established:
+   - If the **`edition`** is `STANDARD`, follow the guides under
+     `references/standard/`.
+   - If the **`edition`** is `ENTERPRISE` or native mode, follow the guides
+     under `references/enterprise/`.
+
+### B. No Instance Found (or New Requested)
+
+If no databases exist or the user requests a new one, default to provisioning an
+**Enterprise** edition database and 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.
+
+Once the location is determined, create the database:
+`bash npx -y firebase-tools@latest firestore:databases:create <database-id> --edition="enterprise" --location="<selected-location>"`
+
+Proceed with using the guides under `references/enterprise/`.
+
+______________________________________________________________________
+
+## 2. Specialized Guides
+
+Based on the identified or created instance edition, open and read the
+corresponding reference guides:
+
+### Standard Edition (`references/standard/`)
+
+- **Provisioning**: Read [provisioning.md](references/standard/provisioning.md)
+- **Security Rules**: Read
+  [security_rules.md](references/standard/security_rules.md)
+- **SDK Usage**: Read [web_sdk_usage.md](references/standard/web_sdk_usage.md),
+  [android_sdk_usage.md](references/standard/android_sdk_usage.md),
+  [ios_setup.md](references/standard/ios_setup.md), or
+  [flutter_setup.md](references/standard/flutter_setup.md)
+- **Indexes**: Read [indexes.md](references/standard/indexes.md)
+
+### Enterprise Edition / Native Mode (`references/enterprise/`)
+
+- **Provisioning**: Read
+  [provisioning.md](references/enterprise/provisioning.md)
+
+- **Data Model**: Read [data_model.md](references/enterprise/data_model.md)
+
+- **Security Rules**: Read
+  [security_rules.md](references/enterprise/security_rules.md)
+
+- **SDK Usage**:
+
+  > [!CRITICAL] **Mandatory Reference Reading** Before writing or modifying any
+  > application code for Firestore Enterprise Edition, you **MUST** read at
+  > least one of the relevant reference documents below for the target
+  > platform/language to understand specific architectural requirements and
+  > pipeline initialization patterns.
+
+  Read [web_sdk_usage.md](references/enterprise/web_sdk_usage.md),
+  [python_sdk_usage.md](references/enterprise/python_sdk_usage.md),
+  [android_sdk_usage.md](references/enterprise/android_sdk_usage.md),
+  [ios_setup.md](references/enterprise/ios_setup.md), or
+  [flutter_setup.md](references/enterprise/flutter_setup.md)
+
+- **Indexes**: Read [indexes.md](references/enterprise/indexes.md)

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

@@ -0,0 +1,230 @@
+# Android SDK Usage (Enterprise Native Mode)
+
+This guide covers the Firestore Android SDK (Kotlin) setup and usage patterns
+optimized for Firestore Enterprise edition in Native mode.
+
+______________________________________________________________________
+
+## 1. Initialization
+
+### Add Dependencies
+
+In your module-level `build.gradle.kts` (usually `app/build.gradle.kts`), add
+the Firebase Kotlin Bill of Materials (BoM) and the dependency for Cloud
+Firestore:
+
+> [!IMPORTANT] **[AGENT] RESOLVING THE RESOLVED SDK VERSION DETERMINISTICALLY**
+> Never guess or hardcode a memorized out-of-date SDK version. Before adding
+> dependencies, you MUST query the latest available versions directly from the
+> Google Maven Repository:
+>
+> ```bash
+> # Find the latest Firebase BoM version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-bom/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+>
+> # Find the latest firebase-firestore version
+> curl -s https://dl.google.com/dl/android/maven2/com/google/firebase/firebase-firestore/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
+> ```
+>
+> If the dependency is already declared, fetch the exact resolved version
+> currently active in the workspace's build graph:
+>
+> ```bash
+> ./gradlew -q :app:dependencyInsight --dependency firebase-firestore --configuration releaseRuntimeClasspath
+> ```
+
+```kotlin
+dependencies {
+    // [AGENT] Fetch the latest resolved version using the Gradle command above
+    implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
+
+    // Add the dependency for the Cloud Firestore library
+    // When using the BoM, you don't specify versions in Firebase library dependencies
+    implementation("com.google.firebase:firebase-firestore")
+}
+```
+
+### Initialize Firestore
+
+Initialize the `FirebaseFirestore` instance in your ComponentActivity (Jetpack
+Compose) or standard Activity/Fragment:
+
+```kotlin
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import com.google.firebase.Firebase
+import com.google.firebase.firestore.FirebaseFirestore
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Initialize the Firestore instance
+        val db = FirebaseFirestore.getInstance("<database-name>")
+        
+        setContent {
+            MaterialTheme {
+                Text("Firestore initialized!")
+            }
+        }
+    }
+}
+```
+
+______________________________________________________________________
+
+## 2. Decision Framework: Mandatory Pipeline Architecture
+
+> [!CRITICAL] **MANDATORY PIPELINE ARCHITECTURE (ZERO TOLERANCE)** You are
+> strictly forbidden from using standard collection queries (e.g.,
+> `db.collection(...).where(...)` or client-side mapping loops) as the primary
+> implementation for relational joins, aggregations, or search algorithms.
+>
+> Server-side execution via pipelines is the superior, non-negotiable core
+> architecture for Enterprise instances.
+
+### Strict Rules & Accountability
+
+1. **Mandatory Execution Engine**: Every repository lookup requiring related
+   data mapping, textual relevance scoring, or multi-document counting MUST be
+   authored natively using the server-side `db.pipeline()` API.
+1. **Required Proof of Use**: In your task execution summaries, you MUST
+   explicitly highlight the exact pipeline stages (`.define()`, `.addFields()`,
+   `.search()`, `.aggregate()`) integrated into your primary data layer return
+   paths. Failure to implement pipelines natively constitutes an immediate
+   violation of instructions.
+1. **Check API References**:
+   - **Locate**: Locate the standard Maven sources JAR (`-sources.jar`)
+     corresponding to the resolved `firebase-firestore` dependency version
+     inside your local Gradle or Maven dependency cache.
+   - **Extract Once**: Extract the documentation files `pipeline.docs.txt` and
+     `expressions.docs.txt` from the root directory of that `-sources.jar`
+     archive into a temporary workspace scratch directory of your choice.
+   - **Read & Reference**:
+     - **Read** the extracted `pipeline.docs.txt` once fully to understand core
+       pipeline structure and stage capabilities.
+     - **Reference** the extracted `expressions.docs.txt` on-demand for specific
+       function overloads and parameters.
+
+______________________________________________________________________
+
+## 3. Pipeline Examples
+
+### Relational Joins Pattern
+
+When querying related data (e.g., articles and their author profiles), perform
+the join at the database level via pipeline stages instead of executing multiple
+sequential lookups on the client-side.
+
+- Use `.define()` to bind parameters or document properties as variables.
+- Use `.addFields()` and a nested subquery with a matching filter.
+- Use `.toScalarExpression()` to convert a nested pipeline subquery to a single
+  field value.
+- Assign variable and field aliases using `.alias(...)` (note: while the Web SDK
+  uses `.as()`, the Kotlin SDK uses `.alias()` to avoid keyword conflicts with
+  Kotlin's `as` operator).
+
+```kotlin
+import com.google.firebase.firestore.pipeline.Expression.field
+import com.google.firebase.firestore.pipeline.Expression.variable
+
+// Fetch articles and join the associated author Profile side-by-side
+val articlesWithAuthProfile = db.pipeline().collection("articles")
+    .define(field("authorUid").alias("author_id"))
+    .addFields(
+        db.pipeline().collection("users")
+            .where(field("__name__").documentId().equalTo(variable("author_id")))
+            .select(field("displayName"), field("avatarUrl"), field("handle"))
+            .toScalarExpression()
+            .alias("author")
+    )
+```
+
+### Full-Text Search
+
+Leverage the database-native `.search()` stage within your pipelines to run
+high-performance text query matches on the database level.
+
+```kotlin
+import com.google.firebase.firestore.pipeline.Expression.documentMatches
+import com.google.firebase.firestore.pipeline.Expression.score
+
+// Execute full-text search inside a pipeline, sorted by relevance score descending
+val searchPipeline = db.pipeline()
+    .collection("articles")
+    .search(
+        query = documentMatches("machine learning"),
+        sort = score().descending()
+    )
+    .limit(5)
+```
+
+______________________________________________________________________
+
+## 4. Real-Time Listener & Document Operations
+
+When real-time data sync or transaction-based document mutations are strictly
+required by application specifications, write clean operations as shown in this
+comprehensive example.
+
+```kotlin
+import android.util.Log
+import com.google.firebase.Firebase
+import com.google.firebase.firestore.DocumentChange
+import com.google.firebase.firestore.firestore
+
+val db = Firebase.firestore
+// 1. Add a new document to a collection
+val taskData = hashMapOf(
+    "title" to "Refactor Android SDK Usage Guide",
+    "status" to "pending"
+)
+
+db.collection("tasks")
+    .add(taskData)
+    .addOnSuccessListener { documentReference ->
+        val taskId = documentReference.id
+        Log.d("Firestore", "Document added with ID: $taskId")
+
+        // 2. Update specific fields of an existing document without replacing it
+        db.collection("tasks").document(taskId)
+            .update("priority", "high")
+            .addOnSuccessListener {
+                Log.d("Firestore", "Document successfully updated!")
+            }
+            .addOnFailureListener { e ->
+                Log.w("Firestore", "Error updating document", e)
+            }
+    }
+    .addOnFailureListener { e ->
+        Log.w("Firestore", "Error adding document", e)
+    }
+
+// 3. Establish a real-time listener on a collection query
+db.collection("tasks")
+    .whereEqualTo("status", "pending")
+    .addSnapshotListener { snapshot, error ->
+        if (error != null) {
+            Log.w("Firestore", "Listen failed.", error)
+            return@addSnapshotListener
+        }
+
+        snapshot?.documentChanges?.forEach { change ->
+            val docId = change.document.id
+            val docData = change.document.data
+            when (change.type) {
+                DocumentChange.Type.ADDED -> {
+                    Log.d("Firestore", "Added Task: $docId => $docData")
+                }
+                DocumentChange.Type.MODIFIED -> {
+                    Log.d("Firestore", "Updated Task: $docId => $docData")
+                }
+                DocumentChange.Type.REMOVED -> {
+                    Log.d("Firestore", "Removed Task: $docId => $docData")
+                }
+            }
+        }
+    }
+```

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

@@ -0,0 +1,66 @@
+# Firestore Data Model Reference
+
+Firestore is a NoSQL, document-oriented database. Unlike a SQL database, there
+are no tables or rows. Instead, you store data in **documents**, which are
+organized into **collections**.
+
+## Document Data Model
+
+Data in Firestore is organized into documents, collections, and subcollections.
+
+### Documents
+
+A **document** is a lightweight record that contains fields, which map to
+values. Each document is identified by a name. A document can contain complex
+nested objects in addition to basic data types like strings, numbers, and
+booleans. Documents are limited to a maximum size of 1 MiB.
+
+Example document (e.g., in a `users` collection):
+`json { "first": "Ada", "last": "Lovelace", "born": 1815 }`
+
+### Collections
+
+Documents live in **collections**, which are containers for your documents. For
+example, you could have a `users` collection to contain your various users, each
+represented by a document. * Collections can only contain documents. They cannot
+directly contain raw fields with values, and they cannot contain other
+collections. * Documents within a collection can contain different fields. * You
+don't need to "create" or "delete" collections explicitly. After you create the
+first document in a collection, the collection exists. If you delete all of the
+documents in a collection, the collection no longer exists.
+
+### Subcollections
+
+Documents can contain subcollections natively. A subcollection is a collection
+associated with a specific document. For example, a user document in the `users`
+collection could have a `messages` subcollection containing message documents
+exclusively for that user. This creates a powerful hierarchical data structure.
+
+Data path example: `users/user1/messages/message1`
+
+## Collection Group Support
+
+A **collection group** consists of all collections with the same ID. By default,
+queries retrieve results from a single collection in your database. Use a
+collection group query to retrieve documents from a collection group instead of
+from a single collection.
+
+### Use Cases
+
+Collection group queries are useful when you want to query across multiple
+subcollections that share the same organizational structure.
+
+For example, imagine an app with a `landmarks` collection where each landmark
+has a `reviews` subcollection. If you want to find all 5-star reviews across
+*all* landmarks, it would involve checking many separate `reviews`
+subcollections. With a collection group, you can perform a single query against
+the `reviews` collection group.
+
+### Examples
+
+**Standard Query** (Single Collection): Find all 5-star reviews for a specific
+landmark.
+`javascript db.collection('landmarks/golden_gate_bridge/reviews').where('rating', '==', 5)`
+
+**Collection Group Query**: Find all 5-star reviews across *all* landmarks.
+`javascript db.collectionGroup('reviews').where('rating', '==', 5)`