opencode-skills-collection 4.1.15 → 4.1.17

package/bundled-skills/azure-cosmos-py/references/query-patterns.md

@@ -0,0 +1,395 @@
+# Query Patterns Reference
+
+Advanced query patterns for Azure Cosmos DB NoSQL API.
+
+## Parameterized Queries
+
+Always use parameters to prevent injection and enable query plan caching:
+
+```python
+# GOOD: Parameterized query
+query = "SELECT * FROM c WHERE c.category = @category AND c.price < @max_price"
+items = container.query_items(
+    query=query,
+    parameters=[
+        {"name": "@category", "value": "electronics"},
+        {"name": "@max_price", "value": 500}
+    ],
+    partition_key="electronics"
+)
+
+# BAD: String interpolation (injection risk, no caching)
+category = "electronics"
+query = f"SELECT * FROM c WHERE c.category = '{category}'"  # Never do this!
+```
+
+## Query Optimization
+
+### Single Partition vs Cross-Partition
+
+```python
+# EFFICIENT: Single partition query (always preferred)
+items = container.query_items(
+    query="SELECT * FROM c WHERE c.status = 'active'",
+    partition_key="tenant-123"
+)
+
+# EXPENSIVE: Cross-partition query (use sparingly)
+items = container.query_items(
+    query="SELECT * FROM c WHERE c.status = 'active'",
+    enable_cross_partition_query=True  # Fans out to all partitions
+)
+```
+
+### Point Reads vs Queries
+
+```python
+# MOST EFFICIENT: Point read (1 RU for 1KB document)
+item = container.read_item(
+    item="doc-123",
+    partition_key="tenant-abc"
+)
+
+# LESS EFFICIENT: Query for single document (higher RU)
+items = list(container.query_items(
+    query="SELECT * FROM c WHERE c.id = @id",
+    parameters=[{"name": "@id", "value": "doc-123"}],
+    partition_key="tenant-abc"
+))
+item = items[0] if items else None
+```
+
+### Projection for Efficiency
+
+```python
+# GOOD: Select only needed fields (less RU, less bandwidth)
+query = "SELECT c.id, c.name, c.price FROM c WHERE c.category = @category"
+items = container.query_items(
+    query=query,
+    parameters=[{"name": "@category", "value": "electronics"}],
+    partition_key="electronics"
+)
+
+# EXPENSIVE: Select all fields when you only need a few
+query = "SELECT * FROM c WHERE c.category = @category"
+```
+
+## Pagination
+
+### Continuation Token Pagination
+
+```python
+def paginated_query(
+    container,
+    query: str,
+    partition_key: str,
+    page_size: int = 100,
+    parameters: list | None = None
+):
+    """Paginate through query results using continuation tokens."""
+    continuation_token = None
+    page_number = 0
+
+    while True:
+        # Create query iterable with pagination
+        query_iterable = container.query_items(
+            query=query,
+            parameters=parameters or [],
+            partition_key=partition_key,
+            max_item_count=page_size,
+            continuation_token=continuation_token
+        )
+
+        # Get page of results
+        page = list(query_iterable.by_page().__next__())
+        page_number += 1
+
+        print(f"Page {page_number}: {len(page)} items")
+        yield page
+
+        # Get continuation token for next page
+        continuation_token = query_iterable.continuation_token
+        if not continuation_token:
+            break
+
+# Usage
+for page in paginated_query(
+    container,
+    query="SELECT * FROM c WHERE c.status = 'active'",
+    partition_key="tenant-123",
+    page_size=50
+):
+    process_page(page)
+```
+
+### Offset-Limit Pagination (Not Recommended for Large Datasets)
+
+```python
+# Works but inefficient for large offsets (still reads skipped items)
+query = "SELECT * FROM c ORDER BY c.created_at DESC OFFSET @offset LIMIT @limit"
+items = container.query_items(
+    query=query,
+    parameters=[
+        {"name": "@offset", "value": 100},
+        {"name": "@limit", "value": 10}
+    ],
+    partition_key="tenant-123"
+)
+```
+
+## Aggregations
+
+### COUNT, SUM, AVG, MIN, MAX
+
+```python
+# Count items in partition
+query = "SELECT VALUE COUNT(1) FROM c WHERE c.status = 'active'"
+result = list(container.query_items(
+    query=query,
+    partition_key="tenant-123"
+))
+count = result[0]  # Returns integer directly with VALUE
+
+# Sum with grouping
+query = """
+SELECT c.category, SUM(c.quantity) as total_quantity, AVG(c.price) as avg_price
+FROM c
+WHERE c.order_date >= @start_date
+GROUP BY c.category
+"""
+results = container.query_items(
+    query=query,
+    parameters=[{"name": "@start_date", "value": "2025-01-01"}],
+    partition_key="tenant-123"
+)
+
+for result in results:
+    print(f"{result['category']}: {result['total_quantity']} items, ${result['avg_price']:.2f} avg")
+```
+
+### Aggregate Functions Reference
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `COUNT(expr)` | Count non-null values | `COUNT(c.id)` |
+| `COUNT(1)` | Count all documents | `COUNT(1)` |
+| `SUM(expr)` | Sum numeric values | `SUM(c.quantity)` |
+| `AVG(expr)` | Average of numeric values | `AVG(c.price)` |
+| `MIN(expr)` | Minimum value | `MIN(c.created_at)` |
+| `MAX(expr)` | Maximum value | `MAX(c.price)` |
+
+## Advanced Query Patterns
+
+### Array Operations
+
+```python
+# Check if array contains value
+query = "SELECT * FROM c WHERE ARRAY_CONTAINS(c.tags, 'urgent')"
+
+# Check if array contains object with property
+query = """
+SELECT * FROM c
+WHERE ARRAY_CONTAINS(c.items, {'product_id': @product_id}, true)
+"""
+
+# Flatten array with JOIN
+query = """
+SELECT c.id, c.order_id, item.product_name, item.quantity
+FROM c
+JOIN item IN c.items
+WHERE item.quantity > @min_quantity
+"""
+
+# Array length
+query = "SELECT * FROM c WHERE ARRAY_LENGTH(c.tags) > 3"
+```
+
+### String Functions
+
+```python
+# Case-insensitive search (expensive - no index)
+query = "SELECT * FROM c WHERE LOWER(c.name) = LOWER(@search_name)"
+
+# Contains (prefix search uses index, contains doesn't)
+query = "SELECT * FROM c WHERE STARTSWITH(c.name, @prefix)"  # Uses index
+query = "SELECT * FROM c WHERE CONTAINS(c.name, @substring)"  # Full scan
+
+# String manipulation
+query = """
+SELECT
+    c.id,
+    CONCAT(c.first_name, ' ', c.last_name) as full_name,
+    LENGTH(c.description) as desc_length
+FROM c
+"""
+```
+
+### Subqueries
+
+```python
+# EXISTS subquery
+query = """
+SELECT * FROM c
+WHERE EXISTS(
+    SELECT VALUE item FROM item IN c.items WHERE item.status = 'pending'
+)
+"""
+
+# Scalar subquery
+query = """
+SELECT
+    c.id,
+    c.name,
+    (SELECT VALUE COUNT(1) FROM item IN c.items) as item_count
+FROM c
+"""
+```
+
+### Ordering and Distinct
+
+```python
+# Order by (requires composite index for multiple fields)
+query = "SELECT * FROM c ORDER BY c.created_at DESC, c.priority ASC"
+
+# Distinct values
+query = "SELECT DISTINCT VALUE c.category FROM c"
+
+# Top N
+query = "SELECT TOP 10 * FROM c ORDER BY c.score DESC"
+```
+
+## Transactions (Transactional Batch)
+
+Execute multiple operations atomically within a single partition:
+
+```python
+from azure.cosmos import TransactionalBatch
+
+def transfer_funds(container, from_account_id: str, to_account_id: str, amount: float, partition_key: str):
+    """Transfer funds between accounts atomically."""
+
+    # Read current balances
+    from_account = container.read_item(item=from_account_id, partition_key=partition_key)
+    to_account = container.read_item(item=to_account_id, partition_key=partition_key)
+
+    if from_account["balance"] < amount:
+        raise ValueError("Insufficient funds")
+
+    # Update balances
+    from_account["balance"] -= amount
+    to_account["balance"] += amount
+
+    # Execute as transaction
+    batch = TransactionalBatch(partition_key=partition_key)
+    batch.replace_item(item=from_account_id, body=from_account)
+    batch.replace_item(item=to_account_id, body=to_account)
+
+    results = container.execute_transactional_batch(batch=batch)
+
+    # Check results
+    for result in results:
+        if result["statusCode"] >= 400:
+            raise Exception(f"Transaction failed: {result}")
+
+    return results
+```
+
+### Batch Operations
+
+```python
+from azure.cosmos import TransactionalBatch
+
+def batch_create_items(container, items: list[dict], partition_key: str):
+    """Create multiple items in a single batch (max 100 operations)."""
+    batch = TransactionalBatch(partition_key=partition_key)
+
+    for item in items[:100]:  # Max 100 operations per batch
+        batch.create_item(body=item)
+
+    results = container.execute_transactional_batch(batch=batch)
+
+    successful = sum(1 for r in results if r["statusCode"] < 400)
+    print(f"Created {successful}/{len(items)} items")
+
+    return results
+
+# Usage
+items = [
+    {"id": f"item-{i}", "pk": "batch-test", "value": i}
+    for i in range(50)
+]
+batch_create_items(container, items, partition_key="batch-test")
+```
+
+## Change Feed
+
+Process changes to documents in order:
+
+```python
+def process_change_feed(container, partition_key: str | None = None):
+    """Process change feed for a container."""
+
+    # Start from beginning
+    change_feed = container.query_items_change_feed(
+        partition_key=partition_key,  # None for all partitions
+        start_time="Beginning"
+    )
+
+    for change in change_feed:
+        print(f"Changed document: {change['id']}")
+        # Process the change
+        process_document(change)
+
+    # Get continuation token for next run
+    continuation = change_feed.continuation_token
+    return continuation
+
+def process_change_feed_incremental(container, continuation_token: str):
+    """Resume change feed from continuation token."""
+    change_feed = container.query_items_change_feed(
+        continuation_token=continuation_token
+    )
+
+    for change in change_feed:
+        process_document(change)
+
+    return change_feed.continuation_token
+```
+
+## Query Best Practices
+
+| Practice | Recommendation |
+|----------|----------------|
+| Always use partition key | Avoid cross-partition queries when possible |
+| Use parameters | Enable query plan caching, prevent injection |
+| Project only needed fields | Reduces RU cost and bandwidth |
+| Use point reads | For single document by ID, use `read_item` not query |
+| Index strategy | Create composite indexes for ORDER BY on multiple fields |
+| Pagination | Use continuation tokens for large result sets |
+| Aggregations | Prefer single-partition aggregations |
+| Avoid OFFSET | Use continuation tokens instead for large datasets |
+
+## RU Estimation
+
+```python
+def estimate_query_cost(container, query: str, partition_key: str, parameters: list | None = None):
+    """Execute query and return RU cost."""
+
+    query_iterable = container.query_items(
+        query=query,
+        parameters=parameters or [],
+        partition_key=partition_key,
+        populate_query_metrics=True
+    )
+
+    items = list(query_iterable)
+
+    # Get request charge from response headers
+    request_charge = query_iterable.get_response_headers().get("x-ms-request-charge", 0)
+
+    print(f"Query returned {len(items)} items")
+    print(f"Total RU cost: {request_charge}")
+    print(f"RU per item: {float(request_charge) / len(items) if items else 0:.2f}")
+
+    return items, float(request_charge)
+```

package/bundled-skills/azure-cosmos-rust/SKILL.md

@@ -10,32 +10,34 @@ date_added: '2026-02-27'
 
 Client library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.
 
+The examples below require a reviewed compatible crate set and replacement of every resource placeholder. Do not use production data for demonstration writes.
+
 ## Installation
 
 ```sh
-cargo add azure_data_cosmos azure_identity
+cargo add azure_data_cosmos@=0.37.1 azure_identity@=1.0.0 azure_core@=1.1.0
 ```
 
 ## Environment Variables
 
 ```bash
-COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
-COSMOS_DATABASE=mydb
-COSMOS_CONTAINER=mycontainer
+export COSMOS_ENDPOINT="https://<account>.documents.azure.com:443/"
+export COSMOS_DATABASE="mydb"
+export COSMOS_CONTAINER="mycontainer"
 ```
 
 ## Authentication
 
 ```rust
 use azure_identity::DeveloperToolsCredential;
-use azure_data_cosmos::CosmosClient;
+use azure_data_cosmos::{AccountEndpoint, AccountReference, CosmosClient, RoutingStrategy};
 
 let credential = DeveloperToolsCredential::new(None)?;
-let client = CosmosClient::new(
-    "https://<account>.documents.azure.com:443/",
-    credential.clone(),
-    None,
-)?;
+let endpoint: AccountEndpoint = "https://<account>.documents.azure.com/".parse()?;
+let account = AccountReference::with_credential(endpoint, credential.clone());
+let client = CosmosClient::builder()
+    .build(account, RoutingStrategy::ProximityTo("East US".into()))
+    .await?;
 ```
 
 ## Client Hierarchy
@@ -52,7 +54,7 @@ let client = CosmosClient::new(
 
 ```rust
 let database = client.database_client("myDatabase");
-let container = database.container_client("myContainer");
+let container = database.container_client("myContainer", None).await?;
 ```
 
 ### Create Item
@@ -73,7 +75,7 @@ let item = Item {
     value: "hello".into(),
 };
 
-container.create_item("partition1", item, None).await?;
+container.create_item("partition1", "1", item, None).await?;
 ```
 
 ### Read Item
@@ -95,13 +97,14 @@ container.replace_item("partition1", "1", item, None).await?;
 ### Patch Item
 
 ```rust
-use azure_data_cosmos::models::PatchDocument;
-
-let patch = PatchDocument::default()
-    .with_add("/newField", "newValue")?
-    .with_remove("/oldField")?;
-
-container.patch_item("partition1", "1", patch, None).await?;
+// Explicit preview opt-in: cargo add azure_data_cosmos@=0.37.1 --features preview_patch
+use azure_data_cosmos::models::{PatchInstructions, PatchOperation};
+
+let patch = PatchInstructions::from(vec![
+    PatchOperation::set("/value", serde_json::json!("newValue")),
+]);
+let patched: Item = container.patch_item("partition1", "1", patch, None)
+    .await?.into_model()?;
 ```
 
 ### Delete Item
@@ -110,12 +113,14 @@ container.patch_item("partition1", "1", patch, None).await?;
 container.delete_item("partition1", "1", None).await?;
 ```
 
+The reviewed current API uses an async builder/container initialization and a separate explicit item ID. Preview PATCH is not a production-ready guarantee; review its selected strategy, conflict/retry behavior and request-unit cost. [Official crate reference](https://docs.rs/azure_data_cosmos/0.37.1/azure_data_cosmos/).
+
 ## Key Auth (Optional)
 
 Enable key-based authentication with feature flag:
 
 ```sh
-cargo add azure_data_cosmos --features key_auth
+cargo add azure_data_cosmos@=0.37.1 --features key_auth
 ```
 
 ## Best Practices
@@ -126,6 +131,8 @@ cargo add azure_data_cosmos --features key_auth
 4. **Use Entra ID auth** — prefer `DeveloperToolsCredential` over key auth
 5. **Reuse client instances** — clients are thread-safe and reusable
 
+The reviewed example set uses `azure_data_cosmos 0.37.1` and compatible Azure core/credential crates. Record and commit Cargo.lock; source/API review is not a compiler or live-service test.
+
 ## Reference Links
 
 | Resource | Link |
@@ -135,9 +142,10 @@ cargo add azure_data_cosmos --features key_auth
 | crates.io | https://crates.io/crates/azure_data_cosmos |
 
 ## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+Use when a Rust application needs Cosmos DB NoSQL item CRUD, partition-key point reads, container access or explicitly opted-in preview patching.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
+- Examples are fragments inside async application code, with compatible pinned Azure crates and the required Tokio/Serde/Futures dependencies; verify the selected version’s API before use. They were reviewed against official source/reference, not compiled or run against a cloud account here.
+- Use an authorized tenant, resource and identity with least privilege. Writes, overwrites, deletes, backup retrieval and account changes require the corresponding scope; cleanup may remove only explicitly identified disposable resources. Bound requests, retries and downloaded bytes, and do not log payloads, credentials or secret values.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
 - Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/azure-eventhub-py/SKILL.md

@@ -5,6 +5,13 @@ risk: critical
 source: community
 date_added: '2026-02-27'
 ---
+## Bundled upstream support
+
+Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.
+
+## Restored helper safety
+
+`scripts/setup_consumer.py` authenticates to the configured Event Hub. `send` publishes event data; `receive` prints event bodies and properties and can write or advance a Blob checkpoint. Confirm the exact namespace, hub, payload/count, starting position, data handling, and checkpoint destination before live use.
 
 # Azure Event Hubs SDK for Python
 

package/bundled-skills/azure-eventhub-py/UPSTREAM-LICENSE.txt

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/bundled-skills/azure-eventhub-py/UPSTREAM-NOTICE.md

@@ -0,0 +1,15 @@
+# Upstream helpers for azure-eventhub-py
+
+The files listed below were recovered from [microsoft/skills](https://github.com/microsoft/skills) at commit `fc164ba1d7a0c10377dbcc1c9ac07253b9329fdb`. The repository ID is `1135891523`.
+
+They retain the upstream **MIT** license reproduced in [UPSTREAM-LICENSE.txt](UPSTREAM-LICENSE.txt). This notice applies to the listed support files; it does not replace the license metadata of other catalog files. Preserve the upstream license and this attribution when redistributing them.
+
+License wording is unchanged; text-only trailing whitespace and EOF blank lines are normalized. Original license: https://github.com/microsoft/skills/blob/fc164ba1d7a0c10377dbcc1c9ac07253b9329fdb/LICENSE
+
+| Local file | Original upstream path | Original Git blob SHA | Import changes |
+| --- | --- | --- | --- |
+| `references/checkpointing.md` | `.github/plugins/azure-sdk-python/skills/azure-eventhub-py/references/checkpointing.md` | `39fabba6e3aefa0531b5e208cf85dcd3c24208a2` | text-only trailing whitespace and EOF blank lines normalized |
+| `references/partitions.md` | `.github/plugins/azure-sdk-python/skills/azure-eventhub-py/references/partitions.md` | `1e64c82d620bae578c124253f81407b7f82aed25` | text-only trailing whitespace and EOF blank lines normalized |
+| `scripts/setup_consumer.py` | `.github/plugins/azure-sdk-python/skills/azure-eventhub-py/scripts/setup_consumer.py` | `73b925deb18c3b6da0760b3225cc8e3ea69db1e7` | text-only trailing whitespace normalized |
+
+`scripts/setup_consumer.py` authenticates to the configured Event Hub. `send` publishes event data; `receive` prints event bodies and properties and, when configured, writes/advances a Blob checkpoint. Confirm the exact namespace, hub, payload/count, starting position, data handling, and checkpoint destination before live use. No cloud calls were made during restoration.