xtrm-tools 2.0.0

package/skills/using-TDD/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: tdd-workflow
+description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
+origin: ECC
+---
+
+# Test-Driven Development Workflow
+
+This skill ensures all code development follows TDD principles with comprehensive test coverage.
+
+## When to Activate
+
+- Writing new features or functionality
+- Fixing bugs or issues
+- Refactoring existing code
+- Adding API endpoints
+- Creating new components
+
+## Core Principles
+
+### 1. Tests BEFORE Code
+ALWAYS write tests first, then implement code to make tests pass.
+
+### 2. Coverage Requirements
+- Minimum 80% coverage (unit + integration + E2E)
+- All edge cases covered
+- Error scenarios tested
+- Boundary conditions verified
+
+### 3. Test Types
+
+#### Unit Tests
+- Individual functions and utilities
+- Component logic
+- Pure functions
+- Helpers and utilities
+
+#### Integration Tests
+- API endpoints
+- Database operations
+- Service interactions
+- External API calls
+
+#### E2E Tests (Playwright)
+- Critical user flows
+- Complete workflows
+- Browser automation
+- UI interactions
+
+## TDD Workflow Steps
+
+### Step 1: Write User Journeys
+```
+As a [role], I want to [action], so that [benefit]
+
+Example:
+As a user, I want to search for markets semantically,
+so that I can find relevant markets even without exact keywords.
+```
+
+### Step 2: Generate Test Cases
+For each user journey, create comprehensive test cases:
+
+```typescript
+describe('Semantic Search', () => {
+  it('returns relevant markets for query', async () => {
+    // Test implementation
+  })
+
+  it('handles empty query gracefully', async () => {
+    // Test edge case
+  })
+
+  it('falls back to substring search when Redis unavailable', async () => {
+    // Test fallback behavior
+  })
+
+  it('sorts results by similarity score', async () => {
+    // Test sorting logic
+  })
+})
+```
+
+### Step 3: Run Tests (They Should Fail)
+```bash
+npm test
+# Tests should fail - we haven't implemented yet
+```
+
+### Step 4: Implement Code
+Write minimal code to make tests pass:
+
+```typescript
+// Implementation guided by tests
+export async function searchMarkets(query: string) {
+  // Implementation here
+}
+```
+
+### Step 5: Run Tests Again
+```bash
+npm test
+# Tests should now pass
+```
+
+### Step 6: Refactor
+Improve code quality while keeping tests green:
+- Remove duplication
+- Improve naming
+- Optimize performance
+- Enhance readability
+
+### Step 7: Verify Coverage
+```bash
+npm run test:coverage
+# Verify 80%+ coverage achieved
+```
+
+## Testing Patterns
+
+### Unit Test Pattern (Jest/Vitest)
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button Component', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+### API Integration Test Pattern
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets', () => {
+  it('returns markets successfully', async () => {
+    const request = new NextRequest('http://localhost/api/markets')
+    const response = await GET(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(Array.isArray(data.data)).toBe(true)
+  })
+
+  it('validates query parameters', async () => {
+    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
+    const response = await GET(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('handles database errors gracefully', async () => {
+    // Mock database failure
+    const request = new NextRequest('http://localhost/api/markets')
+    // Test error handling
+  })
+})
+```
+
+### E2E Test Pattern (Playwright)
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and filter markets', async ({ page }) => {
+  // Navigate to markets page
+  await page.goto('/')
+  await page.click('a[href="/markets"]')
+
+  // Verify page loaded
+  await expect(page.locator('h1')).toContainText('Markets')
+
+  // Search for markets
+  await page.fill('input[placeholder="Search markets"]', 'election')
+
+  // Wait for debounce and results
+  await page.waitForTimeout(600)
+
+  // Verify search results displayed
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  // Verify results contain search term
+  const firstResult = results.first()
+  await expect(firstResult).toContainText('election', { ignoreCase: true })
+
+  // Filter by status
+  await page.click('button:has-text("Active")')
+
+  // Verify filtered results
+  await expect(results).toHaveCount(3)
+})
+
+test('user can create a new market', async ({ page }) => {
+  // Login first
+  await page.goto('/creator-dashboard')
+
+  // Fill market creation form
+  await page.fill('input[name="name"]', 'Test Market')
+  await page.fill('textarea[name="description"]', 'Test description')
+  await page.fill('input[name="endDate"]', '2025-12-31')
+
+  // Submit form
+  await page.click('button[type="submit"]')
+
+  // Verify success message
+  await expect(page.locator('text=Market created successfully')).toBeVisible()
+
+  // Verify redirect to market page
+  await expect(page).toHaveURL(/\/markets\/test-market/)
+})
+```
+
+## Test File Organization
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx          # Unit tests
+│   │   └── Button.stories.tsx       # Storybook
+│   └── MarketCard/
+│       ├── MarketCard.tsx
+│       └── MarketCard.test.tsx
+├── app/
+│   └── api/
+│       └── markets/
+│           ├── route.ts
+│           └── route.test.ts         # Integration tests
+└── e2e/
+    ├── markets.spec.ts               # E2E tests
+    ├── trading.spec.ts
+    └── auth.spec.ts
+```
+
+## Mocking External Services
+
+### Supabase Mock
+```typescript
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: [{ id: 1, name: 'Test Market' }],
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+```
+
+### Redis Mock
+```typescript
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-market', similarity_score: 0.95 }
+  ])),
+  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
+}))
+```
+
+### OpenAI Mock
+```typescript
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1) // Mock 1536-dim embedding
+  ))
+}))
+```
+
+## Test Coverage Verification
+
+### Run Coverage Report
+```bash
+npm run test:coverage
+```
+
+### Coverage Thresholds
+```json
+{
+  "jest": {
+    "coverageThresholds": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+## Common Testing Mistakes to Avoid
+
+### ❌ WRONG: Testing Implementation Details
+```typescript
+// Don't test internal state
+expect(component.state.count).toBe(5)
+```
+
+### ✅ CORRECT: Test User-Visible Behavior
+```typescript
+// Test what users see
+expect(screen.getByText('Count: 5')).toBeInTheDocument()
+```
+
+### ❌ WRONG: Brittle Selectors
+```typescript
+// Breaks easily
+await page.click('.css-class-xyz')
+```
+
+### ✅ CORRECT: Semantic Selectors
+```typescript
+// Resilient to changes
+await page.click('button:has-text("Submit")')
+await page.click('[data-testid="submit-button"]')
+```
+
+### ❌ WRONG: No Test Isolation
+```typescript
+// Tests depend on each other
+test('creates user', () => { /* ... */ })
+test('updates same user', () => { /* depends on previous test */ })
+```
+
+### ✅ CORRECT: Independent Tests
+```typescript
+// Each test sets up its own data
+test('creates user', () => {
+  const user = createTestUser()
+  // Test logic
+})
+
+test('updates user', () => {
+  const user = createTestUser()
+  // Update logic
+})
+```
+
+## Continuous Testing
+
+### Watch Mode During Development
+```bash
+npm test -- --watch
+# Tests run automatically on file changes
+```
+
+### Pre-Commit Hook
+```bash
+# Runs before every commit
+npm test && npm run lint
+```
+
+### CI/CD Integration
+```yaml
+# GitHub Actions
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Best Practices
+
+1. **Write Tests First** - Always TDD
+2. **One Assert Per Test** - Focus on single behavior
+3. **Descriptive Test Names** - Explain what's tested
+4. **Arrange-Act-Assert** - Clear test structure
+5. **Mock External Dependencies** - Isolate unit tests
+6. **Test Edge Cases** - Null, undefined, empty, large
+7. **Test Error Paths** - Not just happy paths
+8. **Keep Tests Fast** - Unit tests < 50ms each
+9. **Clean Up After Tests** - No side effects
+10. **Review Coverage Reports** - Identify gaps
+
+## Success Metrics
+
+- 80%+ code coverage achieved
+- All tests passing (green)
+- No skipped or disabled tests
+- Fast test execution (< 30s for unit tests)
+- E2E tests cover critical user flows
+- Tests catch bugs before production
+
+---
+
+**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

package/skills/using-serena-lsp/README.md

@@ -0,0 +1,8 @@
+# serena-lsp-workflow
+Master workflow combining Serena MCP semantic tools with LSP plugins.
+## Origin
+Provided by Serena MCP project.
+## Associated Hook
+- serena-workflow-reminder.sh
+## Documentation
+See Serena MCP documentation.

package/skills/using-serena-lsp/REFERENCE.md

@@ -0,0 +1,194 @@
+# Serena Tool Reference
+
+Detailed documentation for Serena MCP semantic tools.
+
+## Contents
+- [1. Exploration & Navigation](#1-exploration--navigation-tools)
+- [2. Editing Tools](#2-editing-tools)
+- [3. Memory Management](#3-memory-management-tools)
+- [4. Meta & Thinking](#4-meta--thinking-tools)
+
+---
+
+## 1. Exploration & Navigation Tools
+
+### `list_dir`
+List files and directories with optional recursion.
+```python
+mcp__serena__list_dir(
+    relative_path=".",  # or "src/analysis"
+    recursive=true,
+    skip_ignored_files=true
+)
+```
+
+### `find_file`
+Find files by name pattern (wildcards supported).
+```python
+mcp__serena__find_file(
+    file_mask="*volatility*.py",
+    relative_path="scripts"
+)
+```
+
+### `get_symbols_overview`
+Get high-level code structure (symbol tree) without reading the file body.
+```python
+mcp__serena__get_symbols_overview(
+    relative_path="scripts/core/analytics.py",
+    depth=1  # 0=top-level, 1=include children (methods)
+)
+```
+
+### `find_symbol`
+Locate specific symbols (functions, classes, methods) semantically.
+```python
+mcp__serena__find_symbol(
+    name_path_pattern="VolatilityCalculator/analyze_rv_trend",
+    relative_path="scripts/core/volatility_suite.py",
+    depth=1,
+    include_body=true,  # Set true only when needing source code
+    substring_matching=true,
+    include_kinds=[5, 6, 12]  # 5=Class, 6=Method, 12=Function
+)
+```
+
+**LSP Symbol Kinds Reference**:
+```
+1=file, 2=module, 3=namespace, 4=package, 5=class, 6=method,
+7=property, 8=field, 9=constructor, 10=enum, 11=interface,
+12=function, 13=variable, 14=constant, 15=string, 16=number,
+17=boolean, 18=array, 19=object, 20=key, 21=null,
+22=enum member, 23=struct, 24=event, 25=operator, 26=type parameter
+```
+
+### `find_referencing_symbols`
+Find all places that reference a symbol. Essential before editing.
+```python
+mcp__serena__find_referencing_symbols(
+    name_path="calculate_volatility",
+    relative_path="scripts/core/analytics.py"
+)
+```
+
+### `search_for_pattern`
+Flexible regex/substring search in code.
+```python
+mcp__serena__search_for_pattern(
+    substring_pattern="def.*volatility",  # Regex (DOTALL enabled)
+    relative_path="scripts/core",
+    restrict_search_to_code_files=true,
+    context_lines_before=2,
+    context_lines_after=2
+)
+```
+
+---
+
+## 2. Editing Tools
+
+### `replace_symbol_body`
+Replace entire symbol definition atomically.
+```python
+mcp__serena__replace_symbol_body(
+    name_path="get_db_engine",
+    relative_path="scripts/core/volatility_suite.py",
+    body="def get_db_engine(): ..."
+)
+```
+
+### `insert_after_symbol`
+Insert code after a symbol's definition ends.
+```python
+mcp__serena__insert_after_symbol(
+    name_path="VolatilityCalculator",
+    relative_path="scripts/core/analytics.py",
+    body="
+
+class RiskCalculator: ..."
+)
+```
+
+### `insert_before_symbol`
+Insert code before a symbol's definition starts (e.g., imports).
+```python
+mcp__serena__insert_before_symbol(
+    name_path="VolatilityCalculator",
+    relative_path="scripts/core/analytics.py",
+    body="from typing import Protocol
+
+"
+)
+```
+
+### `rename_symbol`
+Rename symbol across entire codebase using LSP.
+```python
+mcp__serena__rename_symbol(
+    name_path="calculate_volatility",
+    relative_path="scripts/core/analytics.py",
+    new_name="compute_volatility"
+)
+```
+
+---
+
+## 3. Memory Management Tools
+
+### `write_memory`
+Store project decisions, patterns, architecture notes.
+```python
+mcp__serena__write_memory(
+    memory_file_name="architecture_decision_auth",
+    content="# Auth Pattern
+..."
+)
+```
+
+### `read_memory`
+Retrieve stored project knowledge.
+```python
+mcp__serena__read_memory(memory_file_name="architecture_decision_auth")
+```
+
+### `list_memories`
+Discover available project knowledge.
+```python
+mcp__serena__list_memories()
+```
+
+### `edit_memory`
+Update existing memory files.
+```python
+mcp__serena__edit_memory(
+    memory_file_name="architecture_decision_auth",
+    mode="regex",
+    needle="Old",
+    repl="New"
+)
+```
+
+### `delete_memory`
+Remove obsolete memory files.
+```python
+mcp__serena__delete_memory(memory_file_name="deprecated_pattern")
+```
+
+---
+
+## 4. Meta & Thinking Tools
+
+### `check_onboarding_performed`
+Check if project onboarding was completed.
+
+### `onboarding`
+Get instructions for project onboarding.
+
+### `think_about_collected_information`
+Reflect after exploration/search operations.
+
+### `think_about_task_adherence`
+Verify you're still on track for the task.
+
+### `think_about_whether_you_are_done`
+Assess task completion.

package/skills/using-serena-lsp/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: using-serena-lsp
+description: Explores and edits code using semantic tools and LSP plugins. Use when reading code, understanding structure, finding symbols, or performing surgical edits to functions and classes.
+allowed-tools: mcp__serena__*, Read, Edit, Bash
+priority: high
+---
+
+# Using Serena LSP Workflow
+
+**Core Principle**: Use semantic, symbol-level access to understand and edit code without reading entire files. Combine with LSP plugins for real-time analysis.
+
+## Tools Reference
+
+**Full Tool Documentation**: See [REFERENCE.md](REFERENCE.md)
+
+| Tool | Purpose |
+|------|---------|
+| `get_symbols_overview` | **Start here.** See high-level structure of a file. |
+| `find_symbol` | Read specific functions/classes (set `include_body=true`). |
+| `find_referencing_symbols` | Find usages before editing. |
+| `replace_symbol_body` | Surgically replace a function/class. |
+| `insert_after_symbol` | Add new code after an existing symbol. |
+| `search_for_pattern` | Regex search when symbol names are unknown. |
+
+## Standard Workflows
+
+**🚨 MANDATORY FIRST STEP FOR ALL WORKFLOWS:**
+
+Before using ANY Serena semantic tools (`get_symbols_overview`, `find_symbol`, `replace_symbol_body`, etc.), you MUST activate the project:
+
+```javascript
+mcp__plugin_serena_serena__activate_project({ project: "/path/to/current/working/directory" })
+```
+
+**Why this is critical**: Without project activation, Serena cannot locate code symbols and will fail or loop indefinitely. This step establishes the working context for all symbolic operations.
+
+---
+
+### 1. Explore Code (The "Overview First" Pattern)
+
+Avoid reading full files >300 LOC.
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()`
+2.  **Understand Structure**: `get_symbols_overview(depth=1)`
+3.  **Drill Down**: `find_symbol(name_path="...", include_body=true)`
+4.  **Reflect**: `think_about_collected_information()`
+
+### 2. Surgical Editing
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
+2.  **Locate**: `find_symbol(include_body=true)` to get current code.
+3.  **Check Impact**: `find_referencing_symbols()` to find usages.
+4.  **Edit**: `replace_symbol_body(...)` to update.
+5.  **Verify**: Run tests or syntax checks (e.g., `python -m py_compile`).
+
+### 3. Adding Features
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
+2.  **Context**: `read_memory()` or `get_symbols_overview()` to understand patterns.
+3.  **Locate Anchor**: `find_symbol()` to find where to insert.
+4.  **Insert**: `insert_after_symbol(...)` to add new class/function.
+
+## File Size Guidelines
+
+| Lines of Code | Recommended Approach |
+|---------------|----------------------|
+| < 100 LOC | `Read` is acceptable. |
+| 100-300 LOC | `get_symbols_overview` → `find_symbol`. |
+| > 300 LOC | **Semantic only.** Do not read full file. |
+
+## Quick Tips
+
+*   **LSP Integration**: `Read()` on a Python file automatically triggers Pyright analysis. Use the feedback to fix type errors surgically.
+*   **Symbol Names**: Use `substring_matching=true` if you aren't sure of the exact name.
+*   **Safety**: Always find references before renaming or changing signatures.
+
+## ⚠️ Critical Constraints
+
+1. **NEVER skip project activation** - It must be the first Serena operation in any workflow
+2. **Use the current working directory** - Pass the actual project path, not a placeholder
+3. **Activate once per session** - After activation, all subsequent Serena tools will work correctly
+4. **Check activation status** - If Serena tools fail with "symbol not found" errors, you likely forgot to activate