@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/dotnet-patterns/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: dotnet-patterns
+description: Idiomatic C# and .NET patterns, conventions, dependency injection, async/await, and best practices for building robust, maintainable .NET applications.
+origin: ECC
+---
+
+# .NET Development Patterns
+
+Idiomatic C# and .NET patterns for building robust, performant, and maintainable applications.
+
+## When to Activate
+
+- Writing new C# code
+- Reviewing C# code
+- Refactoring existing .NET applications
+- Designing service architectures with ASP.NET Core
+
+## Core Principles
+
+### 1. Prefer Immutability
+
+Use records and init-only properties for data models. Mutability should be an explicit, justified choice.
+
+```csharp
+// Good: Immutable value object
+public sealed record Money(decimal Amount, string Currency);
+
+// Good: Immutable DTO with init setters
+public sealed class CreateOrderRequest
+{
+    public required string CustomerId { get; init; }
+    public required IReadOnlyList<OrderItem> Items { get; init; }
+}
+
+// Bad: Mutable model with public setters
+public class Order
+{
+    public string CustomerId { get; set; }
+    public List<OrderItem> Items { get; set; }
+}
+```
+
+### 2. Explicit Over Implicit
+
+Be clear about nullability, access modifiers, and intent.
+
+```csharp
+// Good: Explicit access modifiers and nullability
+public sealed class UserService
+{
+    private readonly IUserRepository _repository;
+    private readonly ILogger<UserService> _logger;
+
+    public UserService(IUserRepository repository, ILogger<UserService> logger)
+    {
+        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task<User?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
+    {
+        return await _repository.FindByIdAsync(id, cancellationToken);
+    }
+}
+```
+
+### 3. Depend on Abstractions
+
+Use interfaces for service boundaries. Register via DI container.
+
+```csharp
+// Good: Interface-based dependency
+public interface IOrderRepository
+{
+    Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    Task<IReadOnlyList<Order>> FindByCustomerAsync(string customerId, CancellationToken cancellationToken);
+    Task AddAsync(Order order, CancellationToken cancellationToken);
+}
+
+// Registration
+builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();
+```
+
+## Async/Await Patterns
+
+### Proper Async Usage
+
+```csharp
+// Good: Async all the way, with CancellationToken
+public async Task<OrderSummary> GetOrderSummaryAsync(
+    Guid orderId,
+    CancellationToken cancellationToken)
+{
+    var order = await _repository.FindByIdAsync(orderId, cancellationToken)
+        ?? throw new NotFoundException($"Order {orderId} not found");
+
+    var customer = await _customerService.GetAsync(order.CustomerId, cancellationToken);
+
+    return new OrderSummary(order, customer);
+}
+
+// Bad: Blocking on async
+public OrderSummary GetOrderSummary(Guid orderId)
+{
+    var order = _repository.FindByIdAsync(orderId, CancellationToken.None).Result; // Deadlock risk
+    return new OrderSummary(order);
+}
+```
+
+### Parallel Async Operations
+
+```csharp
+// Good: Concurrent independent operations
+public async Task<DashboardData> LoadDashboardAsync(CancellationToken cancellationToken)
+{
+    var ordersTask = _orderService.GetRecentAsync(cancellationToken);
+    var metricsTask = _metricsService.GetCurrentAsync(cancellationToken);
+    var alertsTask = _alertService.GetActiveAsync(cancellationToken);
+
+    await Task.WhenAll(ordersTask, metricsTask, alertsTask);
+
+    return new DashboardData(
+        Orders: await ordersTask,
+        Metrics: await metricsTask,
+        Alerts: await alertsTask);
+}
+```
+
+## Options Pattern
+
+Bind configuration sections to strongly-typed objects.
+
+```csharp
+public sealed class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public required string Host { get; init; }
+    public required int Port { get; init; }
+    public required string Username { get; init; }
+    public bool UseSsl { get; init; } = true;
+}
+
+// Registration
+builder.Services.Configure<SmtpOptions>(
+    builder.Configuration.GetSection(SmtpOptions.SectionName));
+
+// Usage via injection
+public class EmailService(IOptions<SmtpOptions> options)
+{
+    private readonly SmtpOptions _smtp = options.Value;
+}
+```
+
+## Result Pattern
+
+Return explicit success/failure instead of throwing for expected failures.
+
+```csharp
+public sealed record Result<T>
+{
+    public bool IsSuccess { get; }
+    public T? Value { get; }
+    public string? Error { get; }
+
+    private Result(T value) { IsSuccess = true; Value = value; }
+    private Result(string error) { IsSuccess = false; Error = error; }
+
+    public static Result<T> Success(T value) => new(value);
+    public static Result<T> Failure(string error) => new(error);
+}
+
+// Usage
+public async Task<Result<Order>> PlaceOrderAsync(CreateOrderRequest request)
+{
+    if (request.Items.Count == 0)
+        return Result<Order>.Failure("Order must contain at least one item");
+
+    var order = Order.Create(request);
+    await _repository.AddAsync(order, CancellationToken.None);
+    return Result<Order>.Success(order);
+}
+```
+
+## Repository Pattern with EF Core
+
+```csharp
+public sealed class SqlOrderRepository : IOrderRepository
+{
+    private readonly AppDbContext _db;
+
+    public SqlOrderRepository(AppDbContext db) => _db = db;
+
+    public async Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
+    {
+        return await _db.Orders
+            .Include(o => o.Items)
+            .AsNoTracking()
+            .FirstOrDefaultAsync(o => o.Id == id, cancellationToken);
+    }
+
+    public async Task<IReadOnlyList<Order>> FindByCustomerAsync(
+        string customerId,
+        CancellationToken cancellationToken)
+    {
+        return await _db.Orders
+            .Where(o => o.CustomerId == customerId)
+            .OrderByDescending(o => o.CreatedAt)
+            .AsNoTracking()
+            .ToListAsync(cancellationToken);
+    }
+
+    public async Task AddAsync(Order order, CancellationToken cancellationToken)
+    {
+        _db.Orders.Add(order);
+        await _db.SaveChangesAsync(cancellationToken);
+    }
+}
+```
+
+## Middleware and Pipeline
+
+```csharp
+// Custom middleware
+public sealed class RequestTimingMiddleware
+{
+    private readonly RequestDelegate _next;
+    private readonly ILogger<RequestTimingMiddleware> _logger;
+
+    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
+    {
+        _next = next;
+        _logger = logger;
+    }
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var stopwatch = Stopwatch.StartNew();
+        try
+        {
+            await _next(context);
+        }
+        finally
+        {
+            stopwatch.Stop();
+            _logger.LogInformation(
+                "Request {Method} {Path} completed in {ElapsedMs}ms with status {StatusCode}",
+                context.Request.Method,
+                context.Request.Path,
+                stopwatch.ElapsedMilliseconds,
+                context.Response.StatusCode);
+        }
+    }
+}
+```
+
+## Minimal API Patterns
+
+```csharp
+// Organized with route groups
+var orders = app.MapGroup("/api/orders")
+    .RequireAuthorization()
+    .WithTags("Orders");
+
+orders.MapGet("/{id:guid}", async (
+    Guid id,
+    IOrderRepository repository,
+    CancellationToken cancellationToken) =>
+{
+    var order = await repository.FindByIdAsync(id, cancellationToken);
+    return order is not null
+        ? TypedResults.Ok(order)
+        : TypedResults.NotFound();
+});
+
+orders.MapPost("/", async (
+    CreateOrderRequest request,
+    IOrderService service,
+    CancellationToken cancellationToken) =>
+{
+    var result = await service.PlaceOrderAsync(request, cancellationToken);
+    return result.IsSuccess
+        ? TypedResults.Created($"/api/orders/{result.Value!.Id}", result.Value)
+        : TypedResults.BadRequest(result.Error);
+});
+```
+
+## Guard Clauses
+
+```csharp
+// Good: Early returns with clear validation
+public async Task<ProcessResult> ProcessPaymentAsync(
+    PaymentRequest request,
+    CancellationToken cancellationToken)
+{
+    ArgumentNullException.ThrowIfNull(request);
+
+    if (request.Amount <= 0)
+        throw new ArgumentOutOfRangeException(nameof(request.Amount), "Amount must be positive");
+
+    if (string.IsNullOrWhiteSpace(request.Currency))
+        throw new ArgumentException("Currency is required", nameof(request.Currency));
+
+    // Happy path continues here without nesting
+    var gateway = _gatewayFactory.Create(request.Currency);
+    return await gateway.ChargeAsync(request, cancellationToken);
+}
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Fix |
+|---|---|
+| `async void` methods | Return `Task` (except event handlers) |
+| `.Result` or `.Wait()` | Use `await` |
+| `catch (Exception) { }` | Handle or rethrow with context |
+| `new Service()` in constructors | Use constructor injection |
+| `public` fields | Use properties with appropriate accessors |
+| `dynamic` in business logic | Use generics or explicit types |
+| Mutable `static` state | Use DI scoping or `ConcurrentDictionary` |
+| `string.Format` in loops | Use `StringBuilder` or interpolated string handlers |

package/.agent/skills/e2e-testing/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: e2e-testing
+description: Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies.
+origin: ECC
+---
+
+# E2E Testing Patterns
+
+Comprehensive Playwright patterns for building stable, fast, and maintainable E2E test suites.
+
+## Test File Organization
+
+```
+tests/
+├── e2e/
+│   ├── auth/
+│   │   ├── login.spec.ts
+│   │   ├── logout.spec.ts
+│   │   └── register.spec.ts
+│   ├── features/
+│   │   ├── browse.spec.ts
+│   │   ├── search.spec.ts
+│   │   └── create.spec.ts
+│   └── api/
+│       └── endpoints.spec.ts
+├── fixtures/
+│   ├── auth.ts
+│   └── data.ts
+└── playwright.config.ts
+```
+
+## Page Object Model (POM)
+
+```typescript
+import { Page, Locator } from '@playwright/test'
+
+export class ItemsPage {
+  readonly page: Page
+  readonly searchInput: Locator
+  readonly itemCards: Locator
+  readonly createButton: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.searchInput = page.locator('[data-testid="search-input"]')
+    this.itemCards = page.locator('[data-testid="item-card"]')
+    this.createButton = page.locator('[data-testid="create-btn"]')
+  }
+
+  async goto() {
+    await this.page.goto('/items')
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query)
+    await this.page.waitForResponse(resp => resp.url().includes('/api/search'))
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async getItemCount() {
+    return await this.itemCards.count()
+  }
+}
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ItemsPage } from '../../pages/ItemsPage'
+
+test.describe('Item Search', () => {
+  let itemsPage: ItemsPage
+
+  test.beforeEach(async ({ page }) => {
+    itemsPage = new ItemsPage(page)
+    await itemsPage.goto()
+  })
+
+  test('should search by keyword', async ({ page }) => {
+    await itemsPage.search('test')
+
+    const count = await itemsPage.getItemCount()
+    expect(count).toBeGreaterThan(0)
+
+    await expect(itemsPage.itemCards.first()).toContainText(/test/i)
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+  })
+
+  test('should handle no results', async ({ page }) => {
+    await itemsPage.search('xyznonexistent123')
+
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    expect(await itemsPage.getItemCount()).toBe(0)
+  })
+})
+```
+
+## Playwright Configuration
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['junit', { outputFile: 'playwright-results.xml' }],
+    ['json', { outputFile: 'playwright-results.json' }]
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+})
+```
+
+## Flaky Test Patterns
+
+### Quarantine
+
+```typescript
+test('flaky: complex search', async ({ page }) => {
+  test.fixme(true, 'Flaky - Issue #123')
+  // test code...
+})
+
+test('conditional skip', async ({ page }) => {
+  test.skip(process.env.CI, 'Flaky in CI - Issue #123')
+  // test code...
+})
+```
+
+### Identify Flakiness
+
+```bash
+npx playwright test tests/search.spec.ts --repeat-each=10
+npx playwright test tests/search.spec.ts --retries=3
+```
+
+### Common Causes & Fixes
+
+**Race conditions:**
+```typescript
+// Bad: assumes element is ready
+await page.click('[data-testid="button"]')
+
+// Good: auto-wait locator
+await page.locator('[data-testid="button"]').click()
+```
+
+**Network timing:**
+```typescript
+// Bad: arbitrary timeout
+await page.waitForTimeout(5000)
+
+// Good: wait for specific condition
+await page.waitForResponse(resp => resp.url().includes('/api/data'))
+```
+
+**Animation timing:**
+```typescript
+// Bad: click during animation
+await page.click('[data-testid="menu-item"]')
+
+// Good: wait for stability
+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
+await page.waitForLoadState('networkidle')
+await page.locator('[data-testid="menu-item"]').click()
+```
+
+## Artifact Management
+
+### Screenshots
+
+```typescript
+await page.screenshot({ path: 'artifacts/after-login.png' })
+await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
+await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })
+```
+
+### Traces
+
+```typescript
+await browser.startTracing(page, {
+  path: 'artifacts/trace.json',
+  screenshots: true,
+  snapshots: true,
+})
+// ... test actions ...
+await browser.stopTracing()
+```
+
+### Video
+
+```typescript
+// In playwright.config.ts
+use: {
+  video: 'retain-on-failure',
+  videosPath: 'artifacts/videos/'
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+        env:
+          BASE_URL: ${{ vars.STAGING_URL }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+## Test Report Template
+
+```markdown
+# E2E Test Report
+
+**Date:** YYYY-MM-DD HH:MM
+**Duration:** Xm Ys
+**Status:** PASSING / FAILING
+
+## Summary
+- Total: X | Passed: Y (Z%) | Failed: A | Flaky: B | Skipped: C
+
+## Failed Tests
+
+### test-name
+**File:** `tests/e2e/feature.spec.ts:45`
+**Error:** Expected element to be visible
+**Screenshot:** artifacts/failed.png
+**Recommended Fix:** [description]
+
+## Artifacts
+- HTML Report: playwright-report/index.html
+- Screenshots: artifacts/*.png
+- Videos: artifacts/videos/*.webm
+- Traces: artifacts/*.zip
+```
+
+## Wallet / Web3 Testing
+
+```typescript
+test('wallet connection', async ({ page, context }) => {
+  // Mock wallet provider
+  await context.addInitScript(() => {
+    window.ethereum = {
+      isMetaMask: true,
+      request: async ({ method }) => {
+        if (method === 'eth_requestAccounts')
+          return ['0x1234567890123456789012345678901234567890']
+        if (method === 'eth_chainId') return '0x1'
+      }
+    }
+  })
+
+  await page.goto('/')
+  await page.locator('[data-testid="connect-wallet"]').click()
+  await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
+})
+```
+
+## Financial / Critical Flow Testing
+
+```typescript
+test('trade execution', async ({ page }) => {
+  // Skip on production — real money
+  test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
+
+  await page.goto('/markets/test-market')
+  await page.locator('[data-testid="position-yes"]').click()
+  await page.locator('[data-testid="trade-amount"]').fill('1.0')
+
+  // Verify preview
+  const preview = page.locator('[data-testid="trade-preview"]')
+  await expect(preview).toContainText('1.0')
+
+  // Confirm and wait for blockchain
+  await page.locator('[data-testid="confirm-trade"]').click()
+  await page.waitForResponse(
+    resp => resp.url().includes('/api/trade') && resp.status() === 200,
+    { timeout: 30000 }
+  )
+
+  await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
+})
+```