vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-data-connect/reference/native_sql.md

@@ -0,0 +1,170 @@
+# Native SQL Operations
+
+Always default to Native GraphQL. Use Native SQL **only** when you need
+database-specific features not available in GraphQL (e.g., PostGIS, Window
+Functions, Complex Aggregations, or specific DML CTEs).
+
+## Core Agent Constraints
+
+When generating Native SQL operations, you are bypassing GraphQL and talking
+directly to PostgreSQL. You **MUST** adhere to these strict constraints:
+
+1. **Operation Syntax Isolation:** Never mix Native SQL positional parameters
+   (`$1`) with standard GraphQL named variables (`$id`). The `sql:` argument
+   MUST be a hardcoded string literal block (`"""SELECT..."""`), not a GraphQL
+   variable.
+1. **Table & Column Mapping (Case Sensitivity):**
+   - **Default `snake_case` Conversion:** By default, SQL Connect converts
+     `PascalCase` types and `camelCase` fields to `snake_case` in the database.
+     - *Schema:* `type UserProfile { releaseYear: Int }` -> *Native SQL:*
+       `SELECT release_year FROM user_profile`
+   - **Explicit Overrides (Requires Double Quotes):** If the schema uses
+     `@table(name: "ExactName")` or `@col(name: "ExactCol")`, you **MUST wrap
+     the identifier in double quotes** if it contains capital letters (e.g.,
+     `SELECT * FROM "ExactName"`). Without quotes, Postgres folds it to
+     lowercase and fails validation.
+
+## Syntax rules & limitations
+
+Native SQL enforces strict parsing rules to ensure security and prevent SQL
+injection:
+
+- **String Literals Only:** The `sql` argument must be a hardcoded string
+  literal block (`"""SELECT..."""`) directly in the `.gql` file. It **cannot**
+  be a GraphQL variable.
+- **Validation:** Do **NOT** use DDL in any operations (modify the `schema.gql`
+  file instead for table/column changes). Furthermore, `query` operations cannot
+  contain DML and must start with `SELECT`, `TABLE`, or `WITH`.
+- **Parameters:** Use strict positional parameters (`$1`, `$2`) that match the
+  `params` array order. Named parameters (`$id`, `:name`) are **forbidden**.
+- **Comments:** Use block comments (`/* ... */`). Line comments (`--`) are
+  **forbidden** because they can truncate subsequent clauses during query
+  compilation. If you comment out a line containing a parameter (e.g.,
+  `/* WHERE id = $1 */`), you must also remove that parameter from the `params`
+  list, or it will fail with `unused parameter: $1`.
+- **Strings:** Extended string literals (`E'...'`) and dollar-quoted strings
+  (`$$...$$`) are supported.
+- **Context Maps (`_expr`):** Variables **cannot** be used inside `_expr`
+  fields; to ensure security, `_expr` must be a static string (e.g.,
+  `{_expr: "auth.uid"}`, not `{_expr: $uidVar}`).
+
+## Native SQL Root Fields
+
+Operations are executed using the permissions granted to the SQL Connect service
+account. You can alias the root field (e.g., `movies: _select`) to make the
+client response cleaner (`data.movies` instead of `data._select`).
+
+> **Note on `Any` Return Types:** Because Native SQL completely bypasses
+> GraphQL's strong typing, queries like `_select` and `_executeReturning` return
+> the generic `Any` scalar type. The generated client SDKs (TypeScript, Swift,
+> Kotlin, Dart) will type this as `any` (or equivalent). **AGENT INSTRUCTION**:
+> When you generate client-side code that consumes these operations, you MUST
+> manually cast or validate the shape of the data, as the typical type safety of
+> SQL Connect will not be present.
+
+Use these root fields in `query` or `mutation` operations:
+
+### Query Fields (Read-Only)
+
+- `_select`: Executes a SQL query returning zero or more rows. Returns `[Any]`.
+  ```graphql
+  query GetMovies($genre: String!) @auth(level: PUBLIC) {
+    movies: _select(
+      sql: "SELECT id, title FROM movie WHERE genre = $1",
+      params: [$genre]
+    )
+  }
+  ```
+- `_selectFirst`: Executes a SQL query expected to return zero or one row.
+  Returns `Any` or `null`.
+  ```graphql
+  query GetTotalReviews @auth(level: PUBLIC) {
+    stats: _selectFirst(
+      sql: "SELECT COUNT(*) as total_reviews FROM review"
+    ) # params can be omitted if empty
+  }
+  ```
+
+### Mutation Fields (DML)
+
+- `_execute`: Executes DML (`INSERT`, `UPDATE`, `DELETE`). Returns `Int` (number
+  of rows affected).
+  - *Note 1:* `RETURNING` clauses are ignored in the result.
+  - *Note 2:* Only `_execute` supports Data-Modifying Common Table Expressions
+    (e.g., `WITH new_row AS (INSERT...)`).
+  ```graphql
+  mutation UpdateRating($id: UUID!, $rating: Float!) @auth(level: USER) {
+    _execute(
+      sql: "UPDATE movie SET rating = $2 WHERE id = $1",
+      params: [$id, $rating]
+    )
+  }
+  ```
+- `_executeReturning`: Executes DML with a `RETURNING` clause. Returns `[Any]`.
+  Data-Modifying CTEs are **not** supported.
+  ```graphql
+  mutation DeleteUserReviews($uid: String!) @auth(level: USER) {
+    deletedReviews: _executeReturning(
+      sql: "DELETE FROM review WHERE user_id = $1 RETURNING id, rating",
+      params: [{_expr: "auth.uid"}]
+    )
+  }
+  ```
+- `_executeReturningFirst`: Executes DML with `RETURNING`, expecting zero or one
+  row. Returns `Any` or `null`. Data-Modifying CTEs are **not** supported.
+  ```graphql
+  mutation UpdateMyReview($movieId: UUID!, $text: String!) @auth(level: USER) {
+    updatedReview: _executeReturningFirst(
+      sql: """
+        UPDATE review SET text = $2 
+        WHERE movie_id = $1 AND user_id = $3 
+        RETURNING id, text
+      """,
+      params: [$movieId, $text, {_expr: "auth.uid"}]
+    )
+  }
+  ```
+
+### PostgreSQL Extensions
+
+Native SQL allows you to directly query and utilize PostgreSQL extensions, such
+as `PostGIS`, without needing to map complex geometry types into your GraphQL
+schema or alter your underlying tables (e.g., using JSON operators to extract
+values and pass them into `ST_MakePoint`).
+
+*Note: You must enable the extension on your underlying Cloud SQL instance by
+connecting as the `postgres` user and running
+`CREATE EXTENSION IF NOT EXISTS ...;`*
+
+*(See `examples.md` for a full `GetNearbyActiveRestaurants` implementation).*
+
+## ⚠️ Security: Stored Procedures & Dynamic SQL
+
+SQL Connect parameterizes inputs at the GraphQL boundary automatically. However,
+if your Native SQL calls **custom PL/pgSQL stored procedures**, you must
+manually prevent 2nd-order SQL injection:
+
+- **NEVER** concatenate user input into an `EXECUTE` string
+  (`EXECUTE 'UPDATE ' || table || ' SET x=' || val;`).
+- **DO** use the `USING` clause to bind data values safely.
+- **DO** use `format('%I')` for safe database identifier injection.
+- **DO** validate dynamic table/column names against a strict hardcoded
+  allowlist.
+
+**Secure PL/pgSQL Pattern:**
+
+```sql
+CREATE OR REPLACE PROCEDURE secure_update(target_table TEXT, new_value TEXT, row_id INT)
+LANGUAGE plpgsql AS $$
+BEGIN
+    -- 1. Strict Allowlist for Identifiers
+    IF target_table NOT IN ('orders', 'users', 'inventory') THEN
+        RAISE EXCEPTION 'Invalid table name';
+    END IF;
+
+    -- 2. format(%I) for Identifiers, USING for Data
+    EXECUTE format('UPDATE %I SET status = $1 WHERE id = $2', target_table)
+    USING new_value, row_id;
+END;
+$$;
+```

package/dist/global-skills/firebase-data-connect/reference/operations.md

@@ -0,0 +1,385 @@
+# Operations Reference
+
+## Contents
+
+- [Generated Fields](#generated-fields)
+- [Queries](#queries)
+- [Mutations](#mutations)
+- [Key Scalars](#key-scalars)
+- [Multi-Step Operations](#multi-step-operations)
+
+______________________________________________________________________
+
+## Generated Fields
+
+SQL Connect auto-generates fields for each `@table` type:
+
+| Generated Field                                                                         | Purpose             | Example                                          |
+| --------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------ |
+| `movie(id: UUID, key: Key, first: Row)`                                                 | Get single record   | `movie(id: $id)` or `movie(first: {where: ...})` |
+| `movies(where: ..., orderBy: ..., limit: ..., offset: ..., distinct: ..., having: ...)` | List/filter records | `movies(where: {...})`                           |
+| `movie_insert(data: ...)`                                                               | Create record       | Returns key                                      |
+| `movie_insertMany(data: [...])`                                                         | Bulk create         | Returns keys                                     |
+| `movie_update(id: ..., data: ...)`                                                      | Update by ID        | Returns key or null                              |
+| `movie_updateMany(where: ..., data: ...)`                                               | Bulk update         | Returns count                                    |
+| `movie_upsert(data: ...)`                                                               | Insert or update    | Returns key                                      |
+| `movie_delete(id: ...)`                                                                 | Delete by ID        | Returns key or null                              |
+| `movie_deleteMany(where: ...)`                                                          | Bulk delete         | Returns count                                    |
+
+### Relation Fields
+
+For a `Post` with `author: User!`:
+
+- `post.author` - Navigate to related User
+- `user.posts_on_author` - Reverse: all Posts by User
+
+For many-to-many via `MovieActor`:
+
+- `movie.actors_via_MovieActor` - Get all actors
+- `actor.movies_via_MovieActor` - Get all movies
+
+______________________________________________________________________
+
+## Referencing Generated GraphQL Schema
+
+**Do not guess** available queries or mutations. Review the generated schema
+files instead of trying to deduce them from the data model.
+
+1. **Location**: `.dataconnect/schema/main/` (relative to project root).
+1. **Action**: Scan this directory for generated files (`query.gql`,
+   `mutation.gql`, `relation.gql`, `input.gql`) to understand the exact shape of
+   the API and auto-generated types.
+1. **Validation**: Always run `firebase dataconnect:compile` to verify
+   operations against the full schema.
+
+______________________________________________________________________
+
+## Queries
+
+### Basic Query
+
+```graphql
+query GetMovie($id: UUID!) @auth(level: PUBLIC) {
+  movie(id: $id) {
+    id title genre releaseYear
+  }
+}
+```
+
+### List with Filtering
+
+```graphql
+query ListMovies($genre: String, $minRating: Int) @auth(level: PUBLIC) {
+  movies(
+    where: {
+      genre: { eq: $genre },
+      rating: { ge: $minRating }
+    },
+    orderBy: [{ releaseYear: DESC }, { title: ASC }],
+    limit: 20,
+    offset: 0
+  ) {
+    id title genre rating
+  }
+}
+```
+
+### Filter Operators
+
+| Operator     | Description             | Example                                     |
+| ------------ | ----------------------- | ------------------------------------------- |
+| `eq`         | Equals                  | `{ title: { eq: "Matrix" }}`                |
+| `ne`         | Not equals              | `{ status: { ne: "deleted" }}`              |
+| `gt`, `ge`   | Greater than (or equal) | `{ rating: { ge: 4 }}`                      |
+| `lt`, `le`   | Less than (or equal)    | `{ releaseYear: { lt: 2000 }}`              |
+| `in`         | In list                 | `{ genre: { in: ["Action", "Drama"] }}`     |
+| `nin`        | Not in list             | `{ status: { nin: ["deleted", "hidden"] }}` |
+| `isNull`     | Is null check           | `{ description: { isNull: true }}`          |
+| `contains`   | String contains         | `{ title: { contains: "war" }}`             |
+| `startsWith` | String starts with      | `{ title: { startsWith: "The" }}`           |
+| `endsWith`   | String ends with        | `{ email: { endsWith: "@gmail.com" }}`      |
+| `includes`   | Array includes          | `{ tags: { includes: "sci-fi" }}`           |
+
+### Expression Operators (Compare with Server Values)
+
+Use `_expr` suffix to compare with server-side values:
+
+```graphql
+query MyPosts @auth(level: USER) {
+  posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
+    id title
+  }
+}
+
+query RecentPosts @auth(level: PUBLIC) {
+  posts(where: { publishedAt: { lt_expr: "request.time" }}) {
+    id title
+  }
+}
+```
+
+### Logical Operators
+
+```graphql
+query ComplexFilter($genre: String, $minRating: Int) @auth(level: PUBLIC) {
+  movies(where: {
+    _or: [
+      { genre: { eq: $genre }},
+      { rating: { ge: $minRating }}
+    ],
+    _and: [
+      { releaseYear: { ge: 2000 }},
+      { status: { ne: "hidden" }}
+    ],
+    _not: { genre: { eq: "Horror" }}
+  }) { id title }
+}
+```
+
+### Relational Queries
+
+```graphql
+# Navigate relationships
+query MovieWithDetails($id: UUID!) @auth(level: PUBLIC) {
+  movie(id: $id) {
+    title
+    # One-to-one
+    metadata: movieMetadata_on_movie { director }
+    # One-to-many
+    reviews: reviews_on_movie { rating user { name }}
+    # Many-to-many
+    actors: actors_via_MovieActor { name }
+  }
+}
+
+# Filter by related data
+query MoviesByDirector($director: String!) @auth(level: PUBLIC) {
+  movies(where: {
+    movieMetadata_on_movie: { director: { eq: $director }}
+  }) { id title }
+}
+
+# Filter by null relationship (e.g., top-level categories with no parent)
+# Use the generated foreign key field (e.g., parentId)
+query TopLevelCategories @auth(level: PUBLIC) {
+  categories(where: { parentId: { eq: null } }) {
+    id
+    name
+  }
+}
+```
+
+### Aliases
+
+```graphql
+query CompareRatings($genre: String!) @auth(level: PUBLIC) {
+  highRated: movies(where: { genre: { eq: $genre }, rating: { ge: 8 }}) {
+    title rating
+  }
+  lowRated: movies(where: { genre: { eq: $genre }, rating: { lt: 5 }}) {
+    title rating
+  }
+}
+```
+
+______________________________________________________________________
+
+## Mutations
+
+### Create
+
+```graphql
+mutation CreateMovie($title: String!, $genre: String) @auth(level: USER) {
+  movie_insert(data: {
+    title: $title,
+    genre: $genre
+  })
+}
+```
+
+### Create with Server Values
+
+```graphql
+mutation CreatePost($title: String!, $content: String!) @auth(level: USER) {
+  post_insert(data: {
+    authorUid_expr: "auth.uid",         # Current user
+    id_expr: "uuidV4()",                 # Auto-generate UUID
+    createdAt_expr: "request.time",      # Server timestamp
+    title: $title,
+    content: $content
+  })
+}
+```
+
+### Update
+
+```graphql
+mutation UpdateMovie($id: UUID!, $title: String, $genre: String) @auth(level: USER) {
+  movie_update(
+    id: $id,
+    data: {
+      title: $title,
+      genre: $genre,
+      updatedAt_expr: "request.time"
+    }
+  )
+}
+```
+
+### Update Operators
+
+```graphql
+mutation IncrementViews($id: UUID!) @auth(level: PUBLIC) {
+  movie_update(id: $id, data: {
+    viewCount_update: { inc: 1 }
+  })
+}
+
+mutation AddTag($id: UUID!, $tag: String!) @auth(level: USER) {
+  movie_update(id: $id, data: {
+    tags_update: { add: [$tag] }  # add, remove, append, prepend
+  })
+}
+```
+
+| Operator  | Types                       | Description               |
+| --------- | --------------------------- | ------------------------- |
+| `inc`     | Int, Float, Date, Timestamp | Increment value           |
+| `dec`     | Int, Float, Date, Timestamp | Decrement value           |
+| `add`     | Lists                       | Add items if not present  |
+| `remove`  | Lists                       | Remove all matching items |
+| `append`  | Lists                       | Append to end             |
+| `prepend` | Lists                       | Prepend to start          |
+
+### Upsert
+
+```graphql
+mutation UpsertUser($email: String!, $name: String!) @auth(level: USER) {
+  user_upsert(data: {
+    uid_expr: "auth.uid",
+    email: $email,
+    name: $name
+  })
+}
+```
+
+### Delete
+
+```graphql
+mutation DeleteMovie($id: UUID!) @auth(level: USER) {
+  movie_delete(id: $id)
+}
+
+mutation DeleteOldDrafts @auth(level: USER) {
+  post_deleteMany(where: {
+    status: { eq: "draft" },
+    createdAt: { lt_time: { now: true, sub: { days: 30 }}}
+  })
+}
+```
+
+### Filtered Updates/Deletes (User-Owned)
+
+```graphql
+mutation UpdateMyPost($id: UUID!, $content: String!) @auth(level: USER) {
+  post_update(
+    first: { where: {
+      id: { eq: $id },
+      authorUid: { eq_expr: "auth.uid" }  # Only own posts
+    }},
+    data: { content: $content }
+  )
+}
+```
+
+______________________________________________________________________
+
+## Key Scalars
+
+Key scalars (`Movie_Key`, `User_Key`) are auto-generated types representing
+primary keys:
+
+```graphql
+# Using key scalar
+query GetMovie($key: Movie_Key!) @auth(level: PUBLIC) {
+  movie(key: $key) { title }
+}
+
+# Variable format
+# { "key": { "id": "uuid-here" } }
+
+# Composite key
+# { "key": { "movieId": "...", "userId": "..." } }
+```
+
+Key scalars are returned by mutations:
+
+```graphql
+mutation CreateAndFetch($title: String!) @auth(level: USER) {
+  key: movie_insert(data: { title: $title })
+  # Returns: { "key": { "id": "generated-uuid" } }
+}
+```
+
+______________________________________________________________________
+
+## Multi-Step Operations
+
+### @transaction
+
+Ensures atomicity - all steps succeed or all rollback:
+
+```graphql
+mutation CreateUserWithProfile($name: String!, $bio: String!) 
+  @auth(level: USER) 
+  @transaction {
+  # Step 1: Create user
+  user_insert(data: {
+    uid_expr: "auth.uid",
+    name: $name
+  })
+  # Step 2: Create profile (uses response from step 1)
+  userProfile_insert(data: {
+    userId_expr: "response.user_insert.uid",
+    bio: $bio
+  })
+}
+```
+
+### Using response Binding
+
+Access results from previous steps:
+
+```graphql
+mutation CreateTodoWithItem($listName: String!, $itemText: String!) 
+  @auth(level: USER) 
+  @transaction {
+  todoList_insert(data: {
+    id_expr: "uuidV4()",
+    name: $listName
+  })
+  todoItem_insert(data: {
+    listId_expr: "response.todoList_insert.id",  # From previous step
+    text: $itemText
+  })
+}
+```
+
+### Embedded Queries
+
+Run queries within mutations for validation:
+
+```graphql
+mutation AddToPublicList($listId: UUID!, $item: String!)
+  @auth(level: USER)
+  @transaction {
+  # Step 1: Verify list exists and is public
+  query @redact {
+    todoList(id: $listId) @check(expr: "this != null", message: "List not found") {
+      isPublic @check(expr: "this == true", message: "List is not public")
+    }
+  }
+  # Step 2: Add item
+  todoItem_insert(data: { listId: $listId, text: $item })
+}
+```