@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/python-patterns.md

@@ -0,0 +1,158 @@
+---
+name: python-patterns
+description: Modern Python patterns including type hints, dataclasses, async/await, context managers, decorators, and pathlib.
+---
+
+# Python Patterns
+
+## When to Use
+
+Apply these patterns when writing Python 3.10+ code that needs to be maintainable,
+type-safe, and idiomatic. Use this skill when building CLI tools, data pipelines,
+API clients, or any Python project that benefits from modern language features.
+
+## How It Works
+
+### Type Hints and Generics
+
+Use `from __future__ import annotations` at the top of every module. Prefer built-in
+generic types (`list[str]`, `dict[str, int]`) over `typing.List`, `typing.Dict`.
+
+```python
+from __future__ import annotations
+from typing import TypeVar, Protocol
+
+T = TypeVar("T")
+
+class Comparable(Protocol):
+    def __lt__(self, other: Comparable) -> bool: ...
+
+def top_n(items: list[T], n: int, key: Callable[[T], Comparable]) -> list[T]:
+    return sorted(items, key=key, reverse=True)[:n]
+```
+
+### Dataclasses and Slots
+
+Use `@dataclass(frozen=True, slots=True)` for value objects. Use `field(default_factory=...)`
+for mutable defaults. Never use mutable default arguments.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    host: str
+    port: int = 8080
+    tags: list[str] = field(default_factory=list)
+```
+
+### Async/Await
+
+Use `asyncio.TaskGroup` (3.11+) instead of `asyncio.gather` for structured concurrency.
+Always set timeouts on network calls. Use `async for` with async iterators.
+
+```python
+async def fetch_all(urls: list[str]) -> list[Response]:
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(fetch(url)) for url in urls]
+    return [t.result() for t in tasks]
+```
+
+### Context Managers
+
+Use `@contextmanager` for resource cleanup. Pair every acquire with a release in a
+try/finally block. Use `AsyncExitStack` when managing dynamic numbers of resources.
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def temp_directory(prefix: str = "tmp"):
+    path = Path(tempfile.mkdtemp(prefix=prefix))
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+```
+
+### Decorators with Proper Signatures
+
+Always use `@functools.wraps` to preserve the wrapped function's metadata.
+Use `ParamSpec` for type-safe decorators that forward arguments.
+
+```python
+from typing import ParamSpec, TypeVar
+import functools
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(max_attempts: int = 3):
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception:
+                    if attempt == max_attempts - 1:
+                        raise
+            raise RuntimeError("unreachable")
+        return wrapper
+    return decorator
+```
+
+### Pathlib Over os.path
+
+Use `Path` for all filesystem operations. Chain `/` for path construction.
+Use `.read_text()` / `.write_text()` instead of `open()` for simple reads/writes.
+
+```python
+from pathlib import Path
+
+config_dir = Path.home() / ".config" / "myapp"
+config_dir.mkdir(parents=True, exist_ok=True)
+config = config_dir / "settings.toml"
+content = config.read_text(encoding="utf-8")
+```
+
+## Examples
+
+**Pattern: Structured enum with behavior**
+```python
+from enum import Enum, auto
+
+class Status(Enum):
+    PENDING = auto()
+    RUNNING = auto()
+    DONE = auto()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (Status.DONE,)
+```
+
+**Pattern: Named tuple for lightweight records**
+```python
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    x: float
+    y: float
+
+    def distance_to(self, other: Point) -> float:
+        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
+```
+
+## Checklist
+
+- [ ] `from __future__ import annotations` at top of every module
+- [ ] All function signatures have type hints, including return types
+- [ ] Dataclasses use `frozen=True` and `slots=True` where possible
+- [ ] No mutable default arguments (use `field(default_factory=...)`)
+- [ ] `@functools.wraps` on every decorator
+- [ ] `Path` instead of `os.path` for filesystem operations
+- [ ] `asyncio.TaskGroup` instead of bare `gather` for structured concurrency
+- [ ] Context managers for any resource that needs cleanup
+- [ ] `match` statements (3.10+) instead of long if/elif chains where appropriate
+- [ ] `__all__` defined in public-facing modules

package/assets/skills/python-testing.md

@@ -0,0 +1,172 @@
+---
+name: python-testing
+description: Python testing with pytest including fixtures, parametrize, mocking, coverage, and property-based testing.
+---
+
+# Python Testing
+
+## When to Use
+
+Apply this skill when writing or improving tests for Python code. Use pytest as the
+default test runner. Reach for property-based testing (Hypothesis) when testing pure
+functions with wide input domains. Use mocking sparingly and prefer dependency injection.
+
+## How It Works
+
+### Pytest Fixtures
+
+Fixtures replace setup/teardown. Use `yield` fixtures for cleanup. Scope fixtures
+(`session`, `module`, `function`) to control lifecycle. Keep fixtures close to the
+tests that use them; use `conftest.py` for shared fixtures.
+
+```python
+import pytest
+
+@pytest.fixture
+def db_conn():
+    conn = create_test_connection()
+    yield conn
+    conn.rollback()
+    conn.close()
+
+@pytest.fixture(scope="session")
+def app_config():
+    return load_config("test")
+```
+
+### Parametrize
+
+Use `@pytest.mark.parametrize` for data-driven tests. Each tuple is a distinct test
+case with its own pass/fail. Use `pytest.param(..., id="name")` for readable IDs.
+
+```python
+@pytest.mark.parametrize("input_val,expected", [
+    pytest.param("hello", "HELLO", id="lowercase"),
+    pytest.param("Hello World", "HELLO WORLD", id="mixed-case"),
+    pytest.param("", "", id="empty-string"),
+    pytest.param("123", "123", id="digits-unchanged"),
+])
+def test_uppercase(input_val: str, expected: str):
+    assert input_val.upper() == expected
+```
+
+### Mocking
+
+Use `unittest.mock.patch` to replace external dependencies. Prefer patching where
+the name is used, not where it is defined. Use `spec=True` to catch attribute errors.
+
+```python
+from unittest.mock import patch, MagicMock
+
+def test_send_email():
+    with patch("myapp.notifications.smtp_client", spec=True) as mock_smtp:
+        mock_smtp.send.return_value = {"status": "sent"}
+        result = send_notification("user@example.com", "Hello")
+        mock_smtp.send.assert_called_once()
+        assert result["status"] == "sent"
+```
+
+### Async Testing
+
+Use `pytest-asyncio` with `@pytest.mark.asyncio` for async tests. Set
+`asyncio_mode = "auto"` in `pyproject.toml` to avoid marking every test.
+
+```python
+@pytest.mark.asyncio
+async def test_fetch_user(mock_api):
+    user = await fetch_user(user_id=42)
+    assert user.name == "Alice"
+    assert user.active is True
+```
+
+### Property-Based Testing with Hypothesis
+
+Use Hypothesis for pure functions. Define strategies that describe valid inputs.
+Hypothesis will find edge cases you would never write by hand.
+
+```python
+from hypothesis import given, strategies as st
+
+@given(st.lists(st.integers()))
+def test_sort_is_idempotent(xs: list[int]):
+    sorted_once = sorted(xs)
+    sorted_twice = sorted(sorted_once)
+    assert sorted_once == sorted_twice
+
+@given(st.text(min_size=1))
+def test_round_trip_encode_decode(s: str):
+    assert decode(encode(s)) == s
+```
+
+### Coverage
+
+Run with `pytest --cov=myapp --cov-report=term-missing --cov-fail-under=80`.
+Configure in `pyproject.toml`:
+
+```toml
+[tool.coverage.run]
+source = ["myapp"]
+omit = ["*/tests/*", "*/migrations/*"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+```
+
+### Markers and Filtering
+
+Use custom markers to categorize tests. Run subsets with `-m`.
+
+```python
+@pytest.mark.slow
+def test_full_pipeline():
+    ...
+
+@pytest.mark.integration
+def test_database_roundtrip(db_conn):
+    ...
+```
+
+```bash
+pytest -m "not slow"          # skip slow tests
+pytest -m integration         # run only integration tests
+pytest -k "test_parse"        # run tests matching name pattern
+```
+
+## Examples
+
+**Pattern: Factory fixture for flexible test data**
+```python
+@pytest.fixture
+def make_user():
+    def _make(name: str = "Alice", role: str = "user") -> User:
+        return User(id=uuid4(), name=name, role=role)
+    return _make
+
+def test_admin_permissions(make_user):
+    admin = make_user(role="admin")
+    assert admin.can_delete_users() is True
+```
+
+**Pattern: tmp_path for file tests (built-in fixture)**
+```python
+def test_write_config(tmp_path):
+    config_file = tmp_path / "config.json"
+    write_config(config_file, {"debug": True})
+    assert config_file.exists()
+    data = json.loads(config_file.read_text())
+    assert data["debug"] is True
+```
+
+## Checklist
+
+- [ ] Every test function starts with `test_` and has a descriptive name
+- [ ] Fixtures use `yield` for cleanup, not `try/finally` in test bodies
+- [ ] `@pytest.mark.parametrize` for any test with more than 2 similar cases
+- [ ] Mocks use `spec=True` to catch incorrect attribute access
+- [ ] Patch targets where the name is imported, not where it is defined
+- [ ] Async tests use `@pytest.mark.asyncio` or `asyncio_mode = "auto"`
+- [ ] Coverage threshold set in `pyproject.toml` (`fail_under = 80`)
+- [ ] Hypothesis tests for pure functions with wide input domains
+- [ ] Slow/integration tests marked so CI can run them separately
+- [ ] No test depends on execution order (use `pytest-randomly` to verify)

package/assets/skills/queue-patterns.md

@@ -0,0 +1,295 @@
+---
+name: queue-patterns
+description: Queue patterns for FIFO processing, priority queues, dead letter queues, delayed jobs, and exactly-once processing with BullMQ.
+---
+
+# Queue Patterns
+
+## When to Use
+Use job queues when you need to defer work, process tasks asynchronously, handle spikes in workload, or ensure reliable execution of operations that may fail. Queues decouple producers from consumers, enabling retry logic, priority ordering, rate-controlled processing, and distributed workloads. Apply these patterns for email sending, image processing, webhook delivery, report generation, and any task that should not block the request-response cycle.
+
+## How It Works
+
+### BullMQ Queue Setup
+
+```typescript
+// src/queues/index.ts
+import { Queue, Worker, QueueEvents } from 'bullmq';
+import Redis from 'ioredis';
+
+const connection = new Redis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
+
+// Define typed job data
+interface EmailJobData {
+  to: string;
+  subject: string;
+  template: string;
+  variables: Record<string, string>;
+}
+
+interface ImageJobData {
+  sourceUrl: string;
+  outputPath: string;
+  width: number;
+  height: number;
+  format: 'webp' | 'avif' | 'jpeg';
+}
+
+// Create queues
+export const emailQueue = new Queue<EmailJobData>('email', {
+  connection,
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 5000 },
+    removeOnComplete: { age: 86400, count: 1000 },
+    removeOnFail: { age: 604800 },
+  },
+});
+
+export const imageQueue = new Queue<ImageJobData>('image-processing', {
+  connection,
+  defaultJobOptions: {
+    attempts: 2,
+    backoff: { type: 'fixed', delay: 10000 },
+    timeout: 120_000,
+  },
+});
+```
+
+### Worker Definition
+
+```typescript
+// src/workers/email.worker.ts
+import { Worker, Job } from 'bullmq';
+import { sendEmail } from '../services/email';
+
+const emailWorker = new Worker<EmailJobData>(
+  'email',
+  async (job: Job<EmailJobData>) => {
+    const { to, subject, template, variables } = job.data;
+
+    await job.updateProgress(10);
+
+    const html = await renderTemplate(template, variables);
+    await job.updateProgress(50);
+
+    const result = await sendEmail({ to, subject, html });
+    await job.updateProgress(100);
+
+    return { messageId: result.messageId, sentAt: new Date().toISOString() };
+  },
+  {
+    connection,
+    concurrency: 5,          // process 5 jobs simultaneously
+    limiter: { max: 50, duration: 60_000 },  // max 50 per minute
+  }
+);
+
+emailWorker.on('completed', (job) => {
+  console.log(`Email sent: ${job.id} to ${job.data.to}`);
+});
+
+emailWorker.on('failed', (job, err) => {
+  console.error(`Email failed: ${job?.id}`, err.message);
+  if (job && job.attemptsMade >= (job.opts.attempts ?? 3)) {
+    // Move to dead letter queue after all retries exhausted
+    deadLetterQueue.add('email-failed', { originalJob: job.data, error: err.message });
+  }
+});
+```
+
+### Priority Queue
+
+```typescript
+// src/queues/priority.ts
+export async function addJobWithPriority(data: EmailJobData, priority: 'high' | 'normal' | 'low') {
+  const priorityMap = { high: 1, normal: 5, low: 10 };
+
+  await emailQueue.add('send-email', data, {
+    priority: priorityMap[priority],
+  });
+}
+
+// High-priority transactional emails
+await addJobWithPriority({
+  to: 'user@example.com',
+  subject: 'Password Reset',
+  template: 'password-reset',
+  variables: { resetLink: 'https://...' },
+}, 'high');
+
+// Low-priority marketing emails
+await addJobWithPriority({
+  to: 'user@example.com',
+  subject: 'Weekly Digest',
+  template: 'weekly-digest',
+  variables: { userName: 'Alice' },
+}, 'low');
+```
+
+### Delayed Jobs
+
+```typescript
+// src/queues/scheduled.ts
+// Send email 24 hours after signup
+export async function scheduleWelcomeEmail(userId: string, email: string) {
+  await emailQueue.add('welcome-email', {
+    to: email,
+    subject: 'Getting started with MyApp',
+    template: 'welcome',
+    variables: { userId },
+  }, {
+    delay: 24 * 60 * 60 * 1000,  // 24 hours
+    jobId: `welcome-${userId}`,   // prevent duplicates
+  });
+}
+
+// Repeating jobs (cron-like)
+export async function setupRecurringJobs() {
+  await emailQueue.add('daily-digest', {
+    to: 'admin@example.com',
+    subject: 'Daily Report',
+    template: 'daily-report',
+    variables: {},
+  }, {
+    repeat: {
+      pattern: '0 9 * * *',  // every day at 9 AM
+      tz: 'America/New_York',
+    },
+  });
+}
+```
+
+### Dead Letter Queue
+
+```typescript
+// src/queues/dead-letter.ts
+export const deadLetterQueue = new Queue('dead-letter', {
+  connection,
+  defaultJobOptions: {
+    removeOnComplete: false,  // keep for inspection
+  },
+});
+
+// Worker to handle dead letter inspection
+const dlqWorker = new Worker(
+  'dead-letter',
+  async (job) => {
+    // Log to monitoring
+    await logToMonitoring({
+      type: 'dead-letter',
+      originalQueue: job.name,
+      data: job.data,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Alert on critical failures
+    if (job.data.originalJob?.template === 'password-reset') {
+      await alertOncall('Critical email delivery failure', job.data);
+    }
+  },
+  { connection, concurrency: 1 }
+);
+
+// Admin API to retry dead-lettered jobs
+export async function retryDeadLetter(jobId: string) {
+  const job = await deadLetterQueue.getJob(jobId);
+  if (!job) throw new Error(`Job ${jobId} not found`);
+
+  const { originalJob } = job.data;
+  await emailQueue.add('retry', originalJob, { attempts: 1 });
+  await job.remove();
+}
+```
+
+### Exactly-Once Processing Pattern
+
+```typescript
+// src/workers/idempotent.ts
+import { Job } from 'bullmq';
+
+async function processIdempotent(job: Job) {
+  const idempotencyKey = `processed:${job.id}`;
+
+  // Check if already processed
+  const alreadyProcessed = await redis.get(idempotencyKey);
+  if (alreadyProcessed) {
+    console.log(`Job ${job.id} already processed, skipping`);
+    return JSON.parse(alreadyProcessed);
+  }
+
+  // Process the job
+  const result = await doWork(job.data);
+
+  // Mark as processed with TTL
+  await redis.set(idempotencyKey, JSON.stringify(result), 'EX', 86400);
+
+  return result;
+}
+```
+
+### Queue Monitoring Dashboard
+
+```typescript
+// src/routes/admin/queues.ts
+import { Queue } from 'bullmq';
+
+export async function getQueueStats(queue: Queue) {
+  const [waiting, active, completed, failed, delayed] = await Promise.all([
+    queue.getWaitingCount(),
+    queue.getActiveCount(),
+    queue.getCompletedCount(),
+    queue.getFailedCount(),
+    queue.getDelayedCount(),
+  ]);
+
+  return {
+    name: queue.name,
+    counts: { waiting, active, completed, failed, delayed },
+    isPaused: await queue.isPaused(),
+  };
+}
+
+app.get('/admin/queues', async (_req, res) => {
+  const stats = await Promise.all([
+    getQueueStats(emailQueue),
+    getQueueStats(imageQueue),
+    getQueueStats(deadLetterQueue),
+  ]);
+  res.json({ queues: stats });
+});
+
+// Pause/resume for maintenance
+app.post('/admin/queues/:name/pause', async (req, res) => {
+  const queue = getQueueByName(req.params.name);
+  await queue.pause();
+  res.json({ paused: true });
+});
+
+app.post('/admin/queues/:name/resume', async (req, res) => {
+  const queue = getQueueByName(req.params.name);
+  await queue.resume();
+  res.json({ paused: false });
+});
+```
+
+## Examples
+
+| Pattern | Use Case | Retry Strategy |
+|---------|----------|----------------|
+| FIFO | Order processing | Exponential backoff, 3 attempts |
+| Priority | Transactional vs marketing email | Priority 1/5/10, same retry |
+| Delayed | Welcome email after 24h | Single attempt, no retry |
+| Repeating | Daily report generation | Cron pattern, skip on failure |
+| Dead letter | Failed after all retries | Manual inspection and retry |
+| Batch | Bulk CSV import | Chunk into sub-jobs, parallel |
+
+## Checklist
+- [ ] Queues use `maxRetriesPerRequest: null` in Redis connection for BullMQ
+- [ ] Default job options set for attempts, backoff, and TTL
+- [ ] Workers have concurrency limits matching resource capacity
+- [ ] Rate limiter configured for external API calls (email, SMS)
+- [ ] Dead letter queue captures jobs that exhaust all retries
+- [ ] Idempotency keys prevent duplicate processing on retry
+- [ ] Queue monitoring endpoint exposes counts and pause state
+- [ ] Delayed and repeating jobs use unique `jobId` to prevent duplicates