@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/code-python/SKILL.md

@@ -0,0 +1,424 @@
+---
+name: code-python
+description: Python 3.10+ expertise covering type hints, async patterns, dataclasses, and modern Python best practices
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [python, django-app, flask-api, fastapi, pandas]
+---
+
+# Python
+
+Expert knowledge of modern Python (3.10+), type hints, async/await patterns, dataclasses, packaging, virtual environments, and popular frameworks.
+
+## Patterns
+
+### Pythonic Patterns
+
+```python
+# List comprehensions
+squares = [x**2 for x in range(10)]
+evens = [x for x in numbers if x % 2 == 0]
+
+# Dictionary comprehensions
+word_lengths = {word: len(word) for word in words}
+
+# Generator expressions (memory efficient)
+sum_of_squares = sum(x**2 for x in range(1000000))
+
+# Context managers
+with open('file.txt', 'r') as f:
+    data = f.read()
+
+# Custom context manager
+from contextlib import contextmanager
+
+@contextmanager
+def database_connection():
+    conn = connect()
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+# Unpacking
+first, *middle, last = [1, 2, 3, 4, 5]
+head, *tail = items
+
+# Dictionary unpacking
+merged = {**defaults, **options}
+
+# Walrus operator (3.8+)
+if (n := len(data)) > 10:
+    print(f"Large dataset: {n} items")
+
+# Match statement (3.10+)
+match status:
+    case 'active':
+        activate()
+    case 'inactive':
+        deactivate()
+    case _:
+        unknown()
+```
+
+### Dataclasses
+
+```python
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+@dataclass
+class User:
+    id: str
+    name: str
+    email: str
+    age: int = 0
+    tags: List[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.age < 0:
+            raise ValueError("Age must be positive")
+
+@dataclass(frozen=True)  # Immutable
+class Point:
+    x: float
+    y: float
+
+@dataclass(order=True)  # Adds comparison methods
+class Priority:
+    level: int
+    name: str
+```
+
+### Decorators
+
+```python
+from functools import wraps
+import time
+
+# Function decorator
+def timer(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        result = func(*args, **kwargs)
+        print(f"{func.__name__} took {time.time() - start:.2f}s")
+        return result
+    return wrapper
+
+# Decorator with arguments
+def retry(times=3):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            for i in range(times):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    if i == times - 1:
+                        raise
+        return wrapper
+    return decorator
+
+# Class decorator
+@dataclass
+class Config:
+    host: str
+    port: int
+```
+
+### Async Patterns
+
+```python
+import asyncio
+from typing import List
+
+# Basic async function
+async def fetch_data(url: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.json()
+
+# Parallel execution
+async def fetch_all(urls: List[str]) -> List[dict]:
+    tasks = [fetch_data(url) for url in urls]
+    return await asyncio.gather(*tasks)
+
+# With error handling
+async def safe_fetch(url: str) -> dict | None:
+    try:
+        return await fetch_data(url)
+    except Exception as e:
+        print(f"Error fetching {url}: {e}")
+        return None
+
+# Async context manager
+class AsyncDatabase:
+    async def __aenter__(self):
+        self.conn = await connect()
+        return self.conn
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.conn.close()
+
+# Async iterator
+class AsyncRange:
+    def __init__(self, n):
+        self.n = n
+        self.i = 0
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if self.i >= self.n:
+            raise StopAsyncIteration
+        self.i += 1
+        await asyncio.sleep(0.1)
+        return self.i
+
+# Usage
+async for i in AsyncRange(10):
+    print(i)
+```
+
+## Type Hints Best Practices
+
+### Basic Types
+
+```python
+from typing import List, Dict, Set, Tuple, Optional, Union, Any, Callable
+
+# Function annotations
+def greet(name: str, age: int) -> str:
+    return f"Hello {name}, age {age}"
+
+# Collections
+def process_items(items: List[str]) -> Dict[str, int]:
+    return {item: len(item) for item in items}
+
+# Optional
+def find_user(id: str) -> Optional[User]:
+    return users.get(id)
+
+# Union types (3.10+ can use |)
+def parse_input(value: str | int) -> int:
+    return int(value)
+
+# Callable
+def apply(func: Callable[[int], int], value: int) -> int:
+    return func(value)
+
+# Any (avoid when possible)
+def legacy_function(data: Any) -> Any:
+    return process(data)
+```
+
+### Advanced Types
+
+```python
+from typing import TypeVar, Generic, Protocol, TypedDict
+
+# Generic types
+T = TypeVar('T')
+
+class Stack(Generic[T]):
+    def __init__(self):
+        self._items: List[T] = []
+
+    def push(self, item: T) -> None:
+        self._items.append(item)
+
+    def pop(self) -> T:
+        return self._items.pop()
+
+# Protocol (structural typing)
+class Drawable(Protocol):
+    def draw(self) -> None: ...
+
+def render(obj: Drawable) -> None:
+    obj.draw()
+
+# TypedDict
+class UserDict(TypedDict):
+    id: str
+    name: str
+    email: str
+
+# NewType (semantic typing)
+from typing import NewType
+UserId = NewType('UserId', str)
+
+def get_user(user_id: UserId) -> User: ...
+```
+
+### Pydantic for Runtime Validation
+
+```python
+from pydantic import BaseModel, EmailStr, validator, Field
+
+class User(BaseModel):
+    id: str
+    name: str = Field(..., min_length=1, max_length=100)
+    email: EmailStr
+    age: int = Field(..., ge=0, le=120)
+
+    @validator('name')
+    def name_must_not_be_empty(cls, v):
+        if not v.strip():
+            raise ValueError('Name cannot be empty')
+        return v.strip()
+
+    class Config:
+        frozen = True  # Immutable
+
+# Validation
+user = User(id='123', name='John', email='john@example.com', age=30)
+```
+
+## Common Pitfalls
+
+### 1. Mutable Default Arguments
+
+```python
+# BAD
+def add_item(item, items=[]):
+    items.append(item)
+    return items
+
+# GOOD
+def add_item(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+```
+
+### 2. Late Binding Closures
+
+```python
+# BAD
+functions = [lambda: i for i in range(5)]
+# All return 4
+
+# GOOD
+functions = [lambda i=i: i for i in range(5)]
+```
+
+### 3. Exception Handling
+
+```python
+# BAD
+try:
+    risky_operation()
+except:  # Catches everything including KeyboardInterrupt
+    pass
+
+# GOOD
+try:
+    risky_operation()
+except ValueError as e:
+    handle_error(e)
+except (TypeError, KeyError) as e:
+    handle_multiple(e)
+finally:
+    cleanup()
+```
+
+### 4. String Concatenation
+
+```python
+# BAD - Slow for many strings
+result = ""
+for s in strings:
+    result += s
+
+# GOOD
+result = "".join(strings)
+result = f"{var1} {var2} {var3}"  # f-strings
+```
+
+### 5. Dict/List Comprehension Side Effects
+
+```python
+# BAD - Side effects in comprehension
+[process_and_save(item) for item in items]
+
+# GOOD
+for item in items:
+    process_and_save(item)
+```
+
+## Packaging & Virtual Environments
+
+### Project Structure
+
+```
+project/
+├── src/
+│   └── mypackage/
+│       ├── __init__.py
+│       └── main.py
+├── tests/
+├── pyproject.toml
+├── requirements.txt
+└── README.md
+```
+
+### Virtual Environments
+
+```bash
+# Create venv
+python -m venv venv
+
+# Activate
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Freeze dependencies
+pip freeze > requirements.txt
+
+# Using poetry (modern alternative)
+poetry init
+poetry add requests
+poetry install
+```
+
+### pyproject.toml
+
+```toml
+[project]
+name = "mypackage"
+version = "1.0.0"
+dependencies = [
+    "requests>=2.28.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+]
+```
+
+## Best Practices
+
+1. Use type hints for all public APIs
+2. Follow PEP 8 style guide (use `black` formatter)
+3. Prefer composition over inheritance
+4. Use dataclasses for data structures
+5. Validate external data with Pydantic
+6. Use async/await for I/O-bound operations
+7. Write docstrings (Google or NumPy style)
+8. Use context managers for resources
+9. Avoid mutable default arguments
+10. Use virtual environments for all projects
+11. Pin dependencies in requirements.txt
+12. Use `pathlib` instead of `os.path`

package/.merlin-core/skills/general/code-style/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: code-style
+description: Concrete code style rubric with naming conventions, structural rules, and readability constraints. Injected into developer context for consistent output.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: []
+  file_triggers:
+    ["*.js", "*.ts", "*.jsx", "*.tsx", "*.py", "*.go", "*.rs", "*.java"]
+  tool_reminders:
+    [
+      Functions must be <30 LOC,
+      max 3 nesting levels,
+      max 3 positional params,
+      No magic numbers — extract to named constants,
+      Guard clauses mandatory — early returns,
+      error cases first,
+    ]
+---
+
+# Code Style Rubric
+
+Concrete, enforceable coding rules for consistent, readable output. These rules apply to ALL languages unless a language-specific skill overrides them.
+
+## Naming Conventions
+
+- **Variables/functions:** camelCase (JS/TS), snake_case (Python), follow project convention
+- **Classes/types:** PascalCase universally
+- **Constants:** UPPER_SNAKE_CASE for true compile-time constants; camelCase for runtime
+- **Booleans:** Prefix with is/has/can/should (e.g., `isActive`, `hasPermission`)
+- **Event handlers:** Prefix with on/handle (e.g., `onClick`, `handleSubmit`)
+- **Private members:** Use language convention (`_`, `#`, `private` keyword)
+- **File names:** Match the primary export (`UserService.ts` exports `UserService`)
+
+## Structural Rules
+
+### Guard Clauses (Mandatory)
+
+- Use early returns instead of nested if/else
+- Handle error cases first, happy path last
+- Maximum nesting depth: 3 levels (refactor if deeper)
+
+### Function Length
+
+- Target: under 30 lines per function
+- If > 50 lines, extract helper functions
+- Single responsibility: one function does one thing
+
+### File Length
+
+- Target: under 300 lines per file
+- If > 500 lines, split by responsibility
+
+### Parameter Count
+
+- Maximum 3 positional parameters; use an options object for more
+- Destructure options objects in the function signature
+
+## Readability Rules
+
+- **No magic numbers/strings** — Extract to named constants
+- **No commented-out code** — Delete it; git has history
+- **No acronyms** without first explaining them in a comment
+- **Prefer explicit over clever** — Readable code > short code
+- **One statement per line** — No chained assignments
+- **Blank lines** — Separate logical blocks within functions
+
+## Error Handling
+
+- **Always catch specific errors**, never bare catch
+- **Include context** in error messages (what operation, what input)
+- **Fail fast** — Validate inputs at function boundaries
+- **Never swallow errors silently** — At minimum, log them
+
+## Resiliency Patterns
+
+- **No empty catch blocks** — At minimum log with context; prefer specific error handling
+- **Retry with backoff** — Never retry in a tight loop; use exponential backoff with jitter
+- **Circuit breaker on external calls** — After N failures, stop calling and degrade gracefully
+- **Timeouts on all external calls** — Network, database, API — every external call needs a timeout
+- **Graceful degradation** — When a dependency fails, the system continues with reduced functionality, not a crash
+- **Idempotent operations** — Retries must not create duplicate side effects
+- **Race condition awareness** — Document shared state; prefer immutable data and message passing
+- **Transactional boundaries** — Multi-step mutations use transactions; partial completion is handled
+
+## Import Organization
+
+- Group imports: stdlib/builtin > external packages > internal modules > relative
+- Alphabetize within each group
+- No unused imports
+
+## Comments
+
+- **Why, not what** — Explain reasoning, not mechanics
+- **Update comments when code changes** — Stale comments are worse than none
+- **TODO format:** `// TODO(agent-id): description — date`