@ranimontagna/agent-toolkit 0.1.7 → 0.1.10

package/skills/general/code-reviewer/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: code-reviewer
+description: Use when reviewing code, pull requests, security vulnerabilities, performance issues, correctness risks, maintainability problems, or pre-deployment quality.
+license: Apache-2.0
+metadata:
+  author: awesome-llm-apps
+  version: "2.0.0"
+---
+
+# Code Reviewer
+
+You are an expert code reviewer who identifies security vulnerabilities, performance issues, and code quality problems.
+
+## When to Apply
+
+Use this skill when:
+- Reviewing pull requests
+- Performing security audits
+- Checking code quality
+- Identifying performance bottlenecks
+- Ensuring best practices
+- Pre-deployment code review
+
+## How to Use This Skill
+
+This skill contains **detailed rules** in the `rules/` directory, organized by category and priority.
+
+### Quick Start
+
+1. **Review [AGENTS.md](AGENTS.md)** for a complete compilation of all rules with examples
+2. **Reference specific rules** from `rules/` directory for deep dives
+3. **Follow priority order**: Security → Performance → Correctness → Maintainability
+
+### Available Rules
+
+**Security (CRITICAL)**
+- [SQL Injection Prevention](rules/security-sql-injection.md)
+- [XSS Prevention](rules/security-xss-prevention.md)
+
+**Performance (HIGH)**
+- [Avoid N+1 Query Problem](rules/performance-n-plus-one.md)
+
+**Correctness (HIGH)**
+- [Proper Error Handling](rules/correctness-error-handling.md)
+
+**Maintainability (MEDIUM)**
+- [Use Meaningful Variable Names](rules/maintainability-naming.md)
+- [Add Type Hints](rules/maintainability-type-hints.md)
+
+## Review Process
+
+### 1. **Security First** (CRITICAL)
+Look for vulnerabilities that could lead to data breaches or unauthorized access:
+- SQL injection
+- XSS (Cross-Site Scripting)
+- Authentication/authorization bypasses
+- Hardcoded secrets
+- Insecure dependencies
+
+### 2. **Performance** (HIGH)
+Identify code that will cause slow performance at scale:
+- N+1 database queries
+- Missing indexes
+- Inefficient algorithms
+- Memory leaks
+- Unnecessary API calls
+
+### 3. **Correctness** (HIGH)
+Find bugs and edge cases:
+- Error handling gaps
+- Race conditions
+- Off-by-one errors
+- Null/undefined handling
+- Input validation
+
+### 4. **Maintainability** (MEDIUM)
+Improve code quality for long-term health:
+- Clear naming
+- Type safety
+- DRY principle
+- Single responsibility
+- Documentation
+
+### 5. **Testing**
+Verify adequate coverage:
+- Unit tests for new code
+- Edge case testing
+- Error path testing
+- Integration tests where needed
+
+## Review Output Format
+
+Structure your reviews as:
+
+```markdown
+This function retrieves user data but has critical security and reliability issues.
+
+## Critical Issues 🔴
+
+1. **SQL Injection Vulnerability** (Line 2)
+   - **Problem:** User input directly interpolated into SQL query
+   - **Impact:** Attackers can execute arbitrary SQL commands
+   - **Fix:** Use parameterized queries
+   ```python
+   query = "SELECT * FROM users WHERE id = ?"
+   result = db.execute(query, (user_id,))
+   ```
+
+## High Priority 🟠
+
+1. **No Error Handling** (Line 3-4)
+   - **Problem:** Assumes result always has data
+   - **Impact:** IndexError if user doesn't exist
+   - **Fix:** Check result before accessing
+   ```python
+   if not result:
+       return None
+   return result[0]
+   ```
+
+2. **Missing Type Hints** (Line 1)
+   - **Problem:** No type annotations
+   - **Impact:** Reduces code clarity and IDE support
+   - **Fix:** Add type hints
+   ```python
+   def get_user(user_id: int) -> Optional[Dict[str, Any]]:
+   ```
+
+## Recommendations
+- Add logging for debugging
+- Consider using an ORM to prevent SQL injection
+- Add input validation for user_id

package/skills/general/code-reviewer/rules/correctness-error-handling.md

@@ -0,0 +1,279 @@
+---
+title: Proper Error Handling
+impact: HIGH
+category: correctness
+tags: errors, exceptions, reliability
+---
+
+# Proper Error Handling
+
+Always handle errors explicitly. Don't use bare except clauses or ignore errors silently. Provide helpful error messages.
+
+## Why This Matters
+
+Proper error handling:
+- Prevents silent failures
+- Aids debugging with clear messages
+- Allows graceful degradation
+- Improves user experience
+- Enables error monitoring/alerting
+
+## ❌ Incorrect
+
+### Bare Except Clause
+```python
+# ❌ Catches everything, including KeyboardInterrupt, SystemExit
+try:
+    result = risky_operation()
+except:
+    pass  # Silent failure, no idea what went wrong
+```
+
+### Generic Exception Without Context
+```python
+# ❌ Too generic, loses error information
+try:
+    data = fetch_user(user_id)
+    process(data)
+    save_result()
+except Exception:
+    print("Error occurred")  # Which operation failed? Why?
+```
+
+### Ignoring Specific Errors
+```python
+# ❌ Ignoring errors entirely
+try:
+    config = json.loads(config_file.read())
+except json.JSONDecodeError:
+    pass  # App continues with undefined 'config'
+```
+
+## ✅ Correct
+
+### Catch Specific Exceptions
+```python
+# ✅ Handle specific errors appropriately
+try:
+    config = json.loads(config_file.read())
+except json.JSONDecodeError as e:
+    logger.error(f"Invalid JSON in config file: {e}")
+    # Provide sensible default
+    config = get_default_config()
+except FileNotFoundError:
+    logger.warning("Config file not found, using defaults")
+    config = get_default_config()
+```
+
+### Provide Context in Error Messages
+```python
+# ✅ Clear, actionable error messages
+def  get_user(user_id: int) -> User:
+    try:
+        response = requests.get(f"{API_URL}/users/{user_id}", timeout=5)
+        response.raise_for_status()
+        return User(**response.json())
+    except requests.Timeout:
+        raise ValueError(
+            f"Timeout fetching user {user_id} from {API_URL}. "
+            "Check network connection or increase timeout."
+        )
+    except requests.HTTPError as e:
+        if e.response.status_code == 404:
+            raise UserNotFoundError(f"User {user_id} does not exist")
+        raise ValueError(f"HTTP error fetching user {user_id}: {e}")
+    except json.JSONDecodeError:
+        raise ValueError(f"Invalid JSON response for user {user_id}")
+```
+
+### Re-raise with Context
+```python
+# ✅ Add context while preserving stack trace
+try:
+    process_batch(items)
+except ValidationError as e:
+    # Add context and re-raise
+    raise ValidationError(
+        f"Batch processing failed for {len(items)} items: {e}"
+    ) from e
+```
+
+## JavaScript/TypeScript
+
+### ❌ Catching Without Specificity
+```javascript
+// ❌ No error handling
+async function fetchUser(id) {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();  // What if fetch fails? What if not JSON?
+}
+
+// ❌ Generic catch
+try {
+  const user = await fetchUser(id);
+} catch (error) {
+  console.log('Error');  // Which error? From where?
+}
+```
+
+### ✅ Explicit Error Handling
+```typescript
+// ✅ Proper error handling with types
+class UserNotFoundError extends Error {
+  constructor(userId: string) {
+    super(`User ${userId} not found`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+async function fetchUser(id: string): Promise<User> {
+  let response: Response;
+  
+  try {
+    response = await fetch(`/api/users/${id}`, {
+      signal: AbortSignal.timeout(5000)
+    });
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'TimeoutError') {
+      throw new Error(`Timeout fetching user ${id}`);
+    }
+    throw new Error(`Network error fetching user ${id}: ${error}`);
+  }
+  
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new UserNotFoundError(id);
+    }
+    throw new Error(`HTTP ${response.status} fetching user ${id}`);
+  }
+  
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`Invalid JSON response for user ${id}`);
+  }
+}
+
+// Usage
+try {
+  const user = await fetchUser(userId);
+  displayUser(user);
+} catch (error) {
+  if (error instanceof UserNotFoundError) {
+    showNotFoundMessage();
+  } else {
+    logger.error('Failed to load user:', error);
+    showErrorMessage('Unable to load user. Please try again.');
+  }
+}
+```
+
+## Error Handling Patterns
+
+### Result Type (Rust-inspired)
+```typescript
+type Result<T, E = Error> = 
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(json: string): Result<Config> {
+  try {
+    const config = JSON.parse(json);
+    return { ok: true, value: config };
+  } catch (error) {
+    return { ok: false, error: new Error(`Invalid config: ${error}`) };
+  }
+}
+
+// Usage
+const result = parseConfig(configString);
+if (result.ok) {
+  useConfig(result.value);
+} else {
+  logger.error(result.error);
+  useDefaultConfig();
+}
+```
+
+### Custom Error Classes
+```python
+class DatabaseError(Exception):
+    """Base class for database errors."""
+    pass
+
+class ConnectionError(DatabaseError):
+    """Database connection failed."""
+    pass
+
+class QueryError(DatabaseError):
+    """Query execution failed."""
+    def __init__(self, query: str, original_error: Exception):
+        self.query = query
+        self.original_error = original_error
+        super().__init__(f"Query failed: {query[:100]}... Error: {original_error}")
+
+# Usage
+try:
+    db.execute(query)
+except psycopg2.OperationalError as e:
+    raise ConnectionError(f"Cannot connect to database: {e}") from e
+except psycopg2.Error as e:
+    raise QueryError(query, e) from e
+```
+
+## Logging Errors
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+try:
+    result = complex_operation()
+except ValueError as e:
+    logger.error(
+        "Operation failed",
+        exc_info=True,  # Include stack trace
+        extra={
+            'user_id': user_id,
+            'operation': 'complex_operation',
+            'input_data': sanitized_data
+        }
+    )
+    raise
+```
+
+## Best Practices
+
+- [ ] **Catch specific exceptions** (not bare `except` or generic `Exception`)
+- [ ] **Provide context** in error messages (what failed, why, how to fix)
+- [ ] **Log errors** with relevant details
+- [ ] **Don't silently ignore errors**
+- [ ] **Use custom exception classes** for domain errors
+- [ ] **Include stack traces** in logs (but not user-facing messages)
+- [ ] **Handle errors at appropriate level** (don't catch too early)
+- [ ] **Clean up resources** (use context managers/try-finally)
+
+## Monitoring & Alerting
+
+```python
+# Integration with error tracking
+import sentry_sdk
+
+try:
+    process_payment(order)
+except PaymentError as e:
+    sentry_sdk.capture_exception(e)
+    sentry_sdk.set_context("order", {
+        "order_id": order.id,
+        "amount": order.total,
+        "user_id": order.user_id
+    })
+    raise
+```
+
+## References
+
+- [Python Exception Handling Best Practices](https://docs.python.org/3/tutorial/errors.html)
+- [Error Handling in JavaScript](https://javascript.info/try-catch)
+- [Sentry Error Monitoring](https://sentry.io/)

package/skills/general/code-reviewer/rules/maintainability-naming.md

@@ -0,0 +1,149 @@
+---
+title: Use Meaningful Variable Names
+impact: MEDIUM
+category: maintainability
+tags: naming, readability, code-quality
+---
+
+# Use Meaningful Variable Names
+
+Choose descriptive, intention-revealing names. Avoid single letters (except loop counters), abbreviations, and generic names.
+
+## Why This Matters
+
+Code is read 10x more than it's written. Clear names:
+- Make code self-documenting
+- Reduce cognitive load
+- Prevent bugs from misunderstanding
+- Enable easier refactoring
+
+## ❌ Incorrect
+
+```python
+# ❌ Cryptic, meaningless
+def calc(x, y, z):
+    tmp = x * y
+    res = tmp + z
+    return res
+
+# ❌ Too generic
+data = fetch_data()
+result = process(data)
+output = format(result)
+
+# ❌ Confusing abbreviations
+usr_nm = input()
+acc_bal = get_bal(usr_nm)
+```
+
+## ✅ Correct
+
+```python
+# ✅ Clear, descriptive
+def calculate_total_price(item_price: float, quantity: int, tax_rate: float) -> float:
+    """Calculate total price including tax."""
+    subtotal = item_price * quantity
+    total_with_tax = subtotal + (subtotal * tax_rate)
+    return total_with_tax
+
+# ✅ Intention-revealing
+customer_orders = fetch_customer_orders(customer_id)
+validated_orders = validate_orders(customer_orders)
+order_confirmation_email = format_confirmation_email(validated_orders)
+
+# ✅ Full words
+username = input("Enter username: ")
+account_balance = get_account_balance(username)
+```
+
+## Naming Conventions by Language
+
+### Python (PEP 8)
+```python
+# Variables & functions: snake_case
+user_count = 10
+def calculate_average(): pass
+
+# Classes: PascalCase
+class UserAccount: pass
+
+# Constants: UPPER_SNAKE_CASE
+MAX_RETRY_ATTEMPTS = 3
+```
+
+### JavaScript/TypeScript
+```javascript
+// Variables & functions: camelCase
+const userCount = 10;
+function calculateAverage() {}
+
+// Classes: PascalCase
+class UserAccount {}
+
+// Constants: UPPER_SNAKE_CASE or camelCase
+const MAX_RETRY_ATTEMPTS = 3;
+const maxRetryAttempts = 3;  // Also acceptable
+```
+
+### Booleans
+```python
+# Use is_, has_, can_ prefixes
+is_active = True
+has_permission = check_permission()
+can_edit = user.role == "admin"
+
+# Not: active, permission, editable
+```
+
+## Context Matters
+
+### Loop Variables
+```python
+# ❌ Generic in complex loop
+for i in users:
+    for j in i.orders:
+        process(j)
+
+# ✅ Descriptive
+for user in users:
+    for order in user.orders:
+        process_order(order)
+
+# ✅ Single letter OK for simple index
+for i in range(10):
+    print(i)
+```
+
+### Scope-Appropriate Names
+```python
+# Short scope: concise OK
+def validate(email):
+    # 'email' is clear in this small function
+    return '@' in email and '.' in email
+
+# Long scope: more descriptive
+class UserAuthenticationService:
+    def __init__(self):
+        # Longer, clearer for class-level
+        self.failed_login_attempts = {}
+        self.account_lockout_duration_seconds = 300
+```
+
+## Avoid Ambiguity
+
+```python
+# ❌ Ambiguous
+def get_data(id):
+    return data[id]
+
+# What data? What ID?
+
+# ✅ Specific
+def get_user_by_id(user_id: int) -> User:
+    return users_cache[user_id]
+```
+
+## References
+
+- [PEP 8 - Python Naming Conventions](https://peps.python.org/pep-0008/#naming-conventions)
+- [Clean Code by Robert Martin](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)

package/skills/general/code-reviewer/rules/maintainability-type-hints.md

@@ -0,0 +1,93 @@
+---
+title: Add Type Hints
+impact: MEDIUM
+category: maintainability
+tags: types, python, typescript, type-safety
+---
+
+# Add Type Hints
+
+Use type annotations to make code self-documenting and catch errors early.
+
+## Why This Matters
+
+Type hints provide:
+- **Static analysis** - catch bugs before runtime
+- **Better IDE support** - autocomplete, refactoring
+- **Documentation** - types explain intent
+- **Confidence** - easier refactoring
+
+##❌ Incorrect
+
+```python
+# ❌ No type hints
+def get_user(id):
+    return users.get(id)
+
+def process_order(order, discount):
+    if discount:
+        return order['total'] * (1 - discount)
+    return order['total']
+```
+
+## ✅ Correct
+
+```python
+# ✅ Full type hints
+from typing import Optional, Dict, Any
+
+def get_user(id: int) -> Optional[Dict[str, Any]]:
+    """Fetch user by ID.
+    
+    Args:
+        id: User ID
+        
+    Returns:
+        User dict or None if not found
+    """
+    return users.get(id)
+
+def process_order(order: Dict[str, Any], discount: Optional[float] = None) -> float:
+    """Calculate order total with optional discount.
+    
+    Args:
+        order: Order dictionary with 'total' key
+        discount: Discount rate (0.0-1.0), e.g. 0.1 for 10% off
+        
+    Returns:
+        Final price after discount
+    """
+    if discount:
+        return order['total'] * (1 - discount)
+    return order['total']
+```
+
+## TypeScript
+
+```typescript
+// ✅ Explicit types
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function getUser(id: number): User | null {
+  return users.get(id) ?? null;
+}
+
+function processOrder(
+  order: { total: number },
+  discount?: number
+): number {
+  if (discount) {
+    return order.total * (1 - discount);
+  }
+  return order.total;
+}
+```
+
+## References
+
+- [Python Type Hints](https://docs.python.org/3/library/typing.html)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)