@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/skills/django-tdd/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: django-tdd
+description: Test-driven development patterns for Django covering pytest, Django TestCase, factory_boy, test client, and best practices for testing Django applications.
+origin: FlowDeck
+---
+
+# Django TDD Skill
+
+Test-driven development workflow for Django applications. Covers pytest fixtures, Django TestCase, factory_boy, and testing patterns.
+
+## When to Activate
+
+Activate when:
+- Writing new Django features using TDD workflow
+- Adding tests to existing Django applications
+- Debugging test failures in Django projects
+- Setting up testing infrastructure for Django apps
+
+## TDD Workflow
+
+1. Write a failing test (RED)
+2. Run the test - it should fail
+3. Write minimal implementation (GREEN)
+4. Run tests - they should pass
+5. Refactor (IMPROVE)
+6. Verify coverage
+
+## Test Setup
+
+### Using pytest with Django
+
+```python
+# conftest.py
+import pytest
+import django
+from django.conf import settings
+
+@pytest.fixture(scope="session")
+def django_db_setup():
+    settings.DATABASES["default"] = {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": ":memory:",
+    }
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()
+```
+
+### Django TestCase
+
+```python
+from django.test import TestCase, Client
+from django.urls import reverse
+from django.contrib.auth import get_user_model
+from .models import Article, Author
+
+User = get_user_model()
+
+class ArticleViewTest(TestCase):
+    def setUp(self):
+        self.client = Client()
+        self.user = User.objects.create_user(
+            email='test@example.com',
+            password='testpass123'
+        )
+        self.author = Author.objects.create(name='Author', email='a@test.com')
+        self.article = Article.objects.create(
+            title='Test',
+            content='Content',
+            author=self.author,
+            status='published'
+        )
+```
+
+## Testing Views
+
+### List View Tests
+
+```python
+def test_article_list_view(self):
+    response = self.client.get(reverse('article-list'))
+    self.assertEqual(response.status_code, 200)
+    self.assertContains(response, 'Test')
+    self.assertTemplateUsed(response, 'articles/list.html')
+    self.assertEqual(len(response.context['articles']), 1)
+```
+
+### Detail View Tests
+
+```python
+def test_article_detail_view(self):
+    response = self.client.get(
+        reverse('article-detail', kwargs={'pk': self.article.pk})
+    )
+    self.assertEqual(response.status_code, 200)
+    self.assertContains(response, self.article.title)
+
+def test_article_detail_not_found(self):
+    response = self.client.get(
+        reverse('article-detail', kwargs={'pk': 9999})
+    )
+    self.assertEqual(response.status_code, 404)
+```
+
+### Authentication Tests
+
+```python
+def test_create_article_requires_login(self):
+    response = self.client.get(reverse('article-create'))
+    self.assertRedirects(response, '/accounts/login/?next=/articles/create/')
+
+def test_create_article_authenticated(self):
+    self.client.login(email='test@example.com', password='testpass123')
+    response = self.client.post(reverse('article-create'), {
+        'title': 'New Article',
+        'content': 'New content',
+        'status': 'draft',
+    })
+    self.assertEqual(response.status_code, 302)
+    self.assertTrue(Article.objects.filter(title='New Article').exists())
+```
+
+### JSON API Tests
+
+```python
+def test_json_response(self):
+    response = self.client.get(
+        reverse('api-articles'),
+        content_type='application/json'
+    )
+    self.assertEqual(response.status_code, 200)
+    data = response.json()
+    self.assertIn('articles', data)
+```
+
+## Testing Models
+
+```python
+def test_article_creation(self):
+    article = Article.objects.create(
+        title='Test Article',
+        content='Test content',
+        author=self.author,
+        status='draft'
+    )
+    self.assertEqual(article.title, 'Test Article')
+    self.assertEqual(article.status, 'draft')
+    self.assertEqual(str(article), 'Test Article')
+
+def test_article_ordering(self):
+    Article.objects.create(title='Second', author=self.author)
+    Article.objects.create(title='First', author=self.author)
+    articles = list(Article.objects.all())
+    self.assertEqual(articles[0].title, 'First')
+```
+
+## Factory Boy Fixtures
+
+### Defining Factories
+
+```python
+# factories.py
+import factory
+from factory.django import DjangoModelFactory
+from .models import Author, Article
+
+class AuthorFactory(DjangoModelFactory):
+    class Meta:
+        model = Author
+
+    name = factory.Sequence(lambda n: f"Author {n}")
+    email = factory.LazyAttribute(lambda obj: f"{obj.name.replace(' ', '')}@example.com")
+
+class ArticleFactory(DjangoModelFactory):
+    class Meta:
+        model = Article
+
+    title = factory.Sequence(lambda n: f"Article {n}")
+    content = "Test content"
+    author = factory.SubFactory(AuthorFactory)
+    status = 'draft'
+```
+
+### Using Factories in Tests
+
+```python
+from .factories import AuthorFactory, ArticleFactory
+
+def test_article_with_factory(self):
+    author = AuthorFactory(name="Jane Doe")
+    article = ArticleFactory(title="Test", author=author)
+    assert article.author.name == "Jane Doe"
+    assert article.title == "Test"
+```
+
+## Pytest Fixtures
+
+### Basic Fixture
+
+```python
+import pytest
+
+@pytest.fixture
+def sample_data():
+    return {"name": "test", "value": 42}
+
+def test_sample_data(sample_data):
+    assert sample_data["name"] == "test"
+    assert sample_data["value"] == 42
+```
+
+### Fixture with Teardown
+
+```python
+import tempfile
+import os
+
+@pytest.fixture
+def temp_file():
+    fd, path = tempfile.mkstemp()
+    os.write(fd, b"test content")
+    os.close(fd)
+    yield path
+    os.unlink(path)
+
+def test_temp_file(temp_file):
+    assert os.path.exists(temp_file)
+    with open(temp_file) as f:
+        assert f.read() == "test content"
+```
+
+### Parametrized Fixtures
+
+```python
+@pytest.fixture(params=["mysql", "postgresql", "sqlite"])
+def database_type(request):
+    return request.param
+
+def test_database_type(database_type):
+    assert database_type in ["mysql", "postgresql", "sqlite"]
+```
+
+## Common Patterns
+
+### Testing Forms
+
+```python
+def test_form_valid(self):
+    form_data = {
+        'title': 'New Article',
+        'content': 'Content',
+        'author': self.author.pk,
+        'status': 'draft',
+    }
+    form = ArticleForm(data=form_data)
+    self.assertTrue(form.is_valid())
+
+def test_form_invalid(self):
+    form_data = {'title': '', 'content': 'Content'}
+    form = ArticleForm(data=form_data)
+    self.assertFalse(form.is_valid())
+    self.assertIn('title', form.errors)
+```
+
+### Testing Middleware
+
+```python
+def test_middleware_process_request(self):
+    response = self.client.get('/articles/')
+    self.assertEqual(response.status_code, 200)
+    # Check middleware added expected headers or behavior
+```
+
+### Testing Signals
+
+```python
+def test_signal_on_save(self):
+    article = ArticleFactory()
+    # Verify signal handlers executed (e.g., notifications sent)
+```
+
+## Coverage Verification
+
+```bash
+# Run with coverage
+pytest --cov=myapp --cov-report=html
+
+# Minimum 80% coverage required
+```
+
+## Related Skills
+
+- django-patterns
+- python-patterns
+- tdd-workflow

package/src/skills/event-driven-architecture/SKILL.md

@@ -0,0 +1,152 @@
+# Event-Driven Architecture
+
+## When to Activate
+
+Activate when:
+- Designing or implementing message-based communication between services
+- Building systems that require asynchronous processing
+- Decoupling producers from consumers in distributed systems
+- Implementing event sourcing or audit trails
+- Setting up webhooks, message queues, or pub/sub patterns
+
+## Steps
+
+### 1. Identify Event Boundaries
+
+Define what constitutes an "event" in your system:
+- Events are **facts** about something that happened (past tense: `OrderPlaced`, `PaymentProcessed`)
+- Commands are **requests** for an action (present tense: `PlaceOrder`, `ProcessPayment`)
+- Events should be **immutable** once emitted
+
+### 2. Choose the Right Messaging Pattern
+
+| Pattern | Use Case | Examples |
+|---------|----------|----------|
+| Pub/Sub | One-to-many notification | Notifications, audit logs |
+| Message Queue | Point-to-point processing | Order processing, email sending |
+| Event Streaming | Durable, replayable event log | Event sourcing, analytics |
+| Webhooks | External system integration | HTTP callbacks |
+
+### 3. Design Event Schema
+
+```typescript
+interface Event<T> {
+  id: string;           // Unique event identifier (UUID)
+  type: string;         // Event type (e.g., "ORDER_PLACED")
+  version: string;      // Schema version for evolution
+  timestamp: string;    // ISO 8601 timestamp
+  source: string;       // Origin service name
+  data: T;             // Event payload
+  metadata?: Record<string, unknown>;  // Optional tracing/correlation
+}
+```
+
+### 4. Handle Eventual Consistency
+
+- Design consumers to be **idempotent** (safe to process twice)
+- Use **correlation IDs** to track event chains
+- Implement **dead letter queues** for failed processing
+- Set **retry policies** with exponential backoff
+
+### 5. Ensure Durability
+
+- Use persistent message storage (not in-memory)
+- Acknowledge messages only after successful processing
+- Implement **at-least-once** delivery semantics
+
+## Examples
+
+### TypeScript Event Emitter
+
+```typescript
+interface OrderEvent {
+  orderId: string;
+  customerId: string;
+  total: number;
+  items: OrderItem[];
+}
+
+class OrderEventPublisher {
+  private emitter: EventEmitter;
+
+  async publishOrderPlaced(event: OrderEvent): Promise<void> {
+    const message: Event<OrderEvent> = {
+      id: crypto.randomUUID(),
+      type: 'ORDER_PLACED',
+      version: '1.0',
+      timestamp: new Date().toISOString(),
+      source: 'order-service',
+      data: event,
+      metadata: {
+        correlationId: event.orderId,
+        partitionKey: event.customerId
+      }
+    };
+
+    await this.messageBroker.publish('orders.placed', message);
+  }
+}
+```
+
+### Message Consumer with Retry
+
+```typescript
+class OrderEventConsumer {
+  async handleOrderPlaced(event: Event<OrderEvent>): Promise<void> {
+    try {
+      // Idempotent processing
+      const existingOrder = await this.orderRepo.findById(event.data.orderId);
+      if (existingOrder) {
+        logger.info('Order already processed, skipping', { orderId: event.data.orderId });
+        return;
+      }
+
+      await this.orderService.processOrder(event.data);
+      await this.messageBroker.ack(event.id);
+    } catch (error) {
+      if (error instanceof TransientError) {
+        // Requeue with delay for retry
+        await this.messageBroker.requeue(event.id, { delay: 5000 });
+      } else {
+        // Send to dead letter queue
+        await this.messageBroker.sendToDlq(event, error);
+      }
+    }
+  }
+}
+```
+
+### Event Schema Registry
+
+```typescript
+// contracts/order-events.ts
+export const OrderPlacedEventSchema = {
+  type: 'object',
+  required: ['orderId', 'customerId', 'total', 'items'],
+  properties: {
+    orderId: { type: 'string', format: 'uuid' },
+    customerId: { type: 'string', format: 'uuid' },
+    total: { type: 'number', minimum: 0 },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['productId', 'quantity', 'price'],
+        properties: {
+          productId: { type: 'string' },
+          quantity: { type: 'number', minimum: 1 },
+          price: { type: 'number', minimum: 0 }
+        }
+      }
+    }
+  }
+};
+```
+
+## Related Skills
+
+- api-design
+- backend-patterns
+- cqrs
+- event-sourcing
+- message-queues

package/src/skills/frontend-pattern/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: frontend-pattern
+description: Frontend development patterns — component composition, state management, URL-as-state, data fetching, and animation best practices for React/TypeScript web applications
+origin: FlowDeck
+---
+
+# Frontend Pattern Skill
+
+Implements maintainable, performant frontend patterns using React and TypeScript.
+
+## When to Activate
+
+Activate when:
+- Building new UI components
+- Setting up state management
+- Implementing data fetching
+- Adding animations or transitions
+- Structuring a new feature module
+
+## Component Patterns
+
+### Compound Components
+
+Use compound components when related UI shares state and interaction semantics:
+
+```tsx
+<Tabs defaultValue="overview">
+  <Tabs.List>
+    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="overview">...</Tabs.Content>
+  <Tabs.Content value="settings">...</Tabs.Content>
+</Tabs>
+```
+
+- Parent owns state via `useState` or context
+- Children consume via context — no prop drilling
+- Keeps keyboard handling, ARIA, and focus logic in the headless layer
+
+### Container / Presentational Split
+
+```tsx
+// Container — owns data loading and side effects
+function UserProfileContainer({ userId }: { userId: string }) {
+  const { data, isLoading } = useUser(userId);
+  if (isLoading) return <Skeleton />;
+  return <UserProfileView user={data} />;
+}
+
+// Presentational — receives props, renders UI
+function UserProfileView({ user }: { user: User }) {
+  return (
+    <div>
+      <Avatar src={user.avatar} />
+      <h1>{user.name}</h1>
+    </div>
+  );
+}
+```
+
+## State Management
+
+| Concern | Tooling |
+|---------|---------|
+| Server state | TanStack Query, SWR, tRPC |
+| Client state | Zustand, Jotai, signals |
+| URL state | search params, route segments |
+| Form state | React Hook Form or equivalent |
+
+**Do not duplicate server state into client stores.** Derive values instead of storing redundant computed state.
+
+## URL As State
+
+Persist shareable, bookmarkable state in the URL:
+
+```tsx
+// Good: filters, sort, pagination in URL
+const [searchParams, setSearchParams] = useSearchParams();
+const filter = searchParams.get('filter') ?? 'all';
+
+// Usage
+<button onClick={() => setSearchParams({ filter: 'active' })}>
+  Active
+</button>
+```
+
+## Data Fetching Patterns
+
+### Stale-While-Revalidate
+
+Return cached data immediately, revalidate in background:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['users', userId],
+  queryFn: () => fetchUser(userId),
+  staleTime: 5 * 60 * 1000, // 5 minutes
+});
+```
+
+### Optimistic Updates
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newData) => {
+    await queryClient.cancelQueries({ queryKey: ['user', newData.id] });
+    const previous = queryClient.getQueryData(['user', newData.id]);
+    queryClient.setQueryData(['user', newData.id], newData);
+    return { previous };
+  },
+  onError: (err, newData, context) => {
+    queryClient.setQueryData(['user', newData.id], context.previous);
+  },
+});
+```
+
+## CSS Custom Properties
+
+Define design tokens as CSS variables — do not hardcode values:
+
+```css
+:root {
+  --color-surface: oklch(98% 0 0);
+  --color-text: oklch(18% 0 0);
+  --color-accent: oklch(68% 0.21 250);
+
+  --text-base: clamp(1rem, 0.92rem + 0.4vw, 1.125rem);
+  --space-section: clamp(4rem, 3rem + 5vw, 10rem);
+
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+## Animation Guidelines
+
+Use compositor-friendly properties only:
+
+```
+✅ transform, opacity, clip-path, filter
+❌ width, height, top, left, margin, padding, border, font-size
+```
+
+```tsx
+// Good
+const style = { opacity: isVisible ? 1 : 0, transform: `translateY(${isVisible ? 0 : 20}px)` };
+
+// Bad
+const style = { height: isVisible ? 'auto' : 0 };
+```
+
+## Related Skills
+
+- [code-review](code-review) — Review frontend code for quality
+- [security-scan](security-scan) — Check for XSS and injection vulnerabilities
+- [test-coverage](test-coverage) — Ensure UI component tests exist

package/src/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,80 @@
+# hexagonal-architecture
+
+## When to Activate
+When building applications that must remain flexible to changing external systems (databases, APIs, UI frameworks) and need to support multiple entry points (ports) for the same business logic.
+
+## Steps
+1. **Identify the core domain** - Isolate the pure business logic that makes no references to infrastructure.
+2. **Define inbound ports** - Create interfaces (ports) for primary/ driving actors (UI, API controllers) that trigger application logic.
+3. **Define outbound ports** - Create interfaces (ports) for secondary/ driven actors (databases, external services) that the domain calls.
+4. **Implement primary adapters** - Create adapters for inbound traffic (REST controllers, GraphQL resolvers, CLI commands).
+5. **Implement secondary adapters** - Create adapters for outbound traffic (Postgres repositories, Redis caches, email gateways).
+6. **Ensure domain has no external dependencies** - The domain layer should compile and run with no imports from adapters.
+7. **Wire via dependency injection** - Connect adapters to ports at application startup.
+
+## Examples
+```typescript
+// Domain Core - Pure business logic, no infrastructure dependencies
+class Transfer {
+  constructor(
+    public readonly fromAccountId: string,
+    public readonly toAccountId: string,
+    public readonly amount: number
+  ) {}
+
+  execute(accounts: Map<string, Account>): TransferResult {
+    const from = accounts.get(this.fromAccountId)
+    const to = accounts.get(this.toAccountId)
+
+    if (!from || !to) {
+      return TransferResult.failed('Account not found')
+    }
+
+    if (!from.canDebit(this.amount)) {
+      return TransferResult.failed('Insufficient funds')
+    }
+
+    from.debit(this.amount)
+    to.credit(this.amount)
+
+    return TransferResult.success()
+  }
+}
+
+// Inbound Port (Primary Port) - Interface for driving operations
+interface TransferUseCase {
+  execute(transfer: Transfer): TransferResult
+}
+
+// Outbound Port (Secondary Port) - Interface for driven operations
+interface AccountRepository {
+  findById(id: string): Promise<Account | null>
+  save(account: Account): Promise<void>
+}
+
+interface EventBus {
+  publish(event: DomainEvent): Promise<void>
+}
+
+// Primary Adapter - REST API
+class TransferController implements TransferUseCase {
+  constructor(private readonly accounts: AccountRepository) {}
+
+  async execute(transfer: Transfer): Promise<TransferResult> {
+    const allAccounts = await this.accounts.findById(transfer.fromAccountId)
+    // ... handle via injected port
+  }
+}
+
+// Secondary Adapter - PostgreSQL implementation
+class PostgresAccountRepository implements AccountRepository {
+  constructor(private readonly db: Database) {}
+  // ... implementation
+}
+```
+
+## Related Skills
+- clean-architecture
+- layered-architecture
+- ddd-architecture
+- backend-patterns