@dv.nghiem/flowdeck 0.2.4 → 0.3.1

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

@@ -0,0 +1,104 @@
+# ddd-architecture
+
+## When to Activate
+When modeling complex business domains where deep understanding of the problem space, ubiquitous language, and bounded contexts are critical for long-term maintainability.
+
+## Steps
+1. **Establish the bounded context** - Identify the explicit boundary within which a single model (ubiquitous language) holds.
+2. **Build the domain model** - Create entities, value objects, aggregates, and domain events that reflect real business concepts.
+3. **Define aggregates** - Group related entities and value objects under a root aggregate that enforces invariants.
+4. **Identify domain events** - Capture meaningful business occurrences that other parts of the system may need to react to.
+5. **Create domain services** - Model operations that don't naturally belong to a single entity or value object.
+6. **Define repository interfaces** - Create ports for persisting and retrieving aggregates (implementation is infrastructure).
+7. **Implement application services** - Orchestrate the domain model, handle transactions, and coordinate multiple aggregates.
+8. **Establish anti-corruption layers** - Translate between external systems (legacy, third-party) and your domain model.
+
+## Examples
+```typescript
+// Value Object - Immutable concept with equality
+class Money {
+  constructor(
+    public readonly amount: number,
+    public readonly currency: Currency
+  ) {}
+
+  static of(amount: number, currency: Currency): Money {
+    return new Money(Math.round(amount * 100) / 100, currency)
+  }
+
+  add(other: Money): Money {
+    if (this.currency !== other.currency) {
+      throw new Error('Currency mismatch')
+    }
+    return Money.of(this.amount + other.amount, this.currency)
+  }
+}
+
+// Aggregate Root - Enforces invariants for the aggregate
+class Order extends AggregateRoot {
+  constructor(
+    private readonly id: OrderId,
+    private readonly customer: Customer,
+    private items: OrderItem[],
+    private status: OrderStatus
+  ) {
+    super()
+    this.validate()
+  }
+
+  private validate(): void {
+    if (this.items.length === 0) {
+      throw new DomainException('Order must have at least one item')
+    }
+  }
+
+  get total(): Money {
+    return this.items.reduce(
+      (sum, item) => sum.add(item.subtotal),
+      Money.of(0, Currency.USD)
+    )
+  }
+
+  // Business methods that enforce invariants
+  addItem(item: OrderItem): void {
+    if (this.status !== OrderStatus.DRAFT) {
+      throw new DomainException('Cannot add items to a non-draft order')
+    }
+    this.items.push(item)
+    this.addDomainEvent(new OrderItemAddedEvent(this.id, item))
+  }
+
+  submit(): void {
+    if (!this.canSubmit()) {
+      throw new DomainException('Order cannot be submitted')
+    }
+    this.status = OrderStatus.SUBMITTED
+    this.addDomainEvent(new OrderSubmittedEvent(this))
+  }
+
+  private canSubmit(): boolean {
+    return this.status === OrderStatus.DRAFT && this.items.length > 0
+  }
+}
+
+// Domain Event - Business facts that may trigger reactions
+class OrderSubmittedEvent extends DomainEvent {
+  constructor(public readonly order: Order) {
+    super('order.submitted', order.id)
+  }
+}
+
+// Repository Interface (Port) - Persistence abstraction
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>
+  findByCustomer(customerId: CustomerId): Promise<Order[]>
+  save(order: Order): Promise<void>
+}
+```
+
+## Related Skills
+- clean-architecture
+- hexagonal-architecture
+- layered-architecture
+- saga-architecture
+- backend-patterns

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

@@ -0,0 +1,304 @@
+---
+name: django-patterns
+description: Django patterns covering models, ORM queries, views, class-based views, middleware, URL routing, forms, and project structure. Activate when writing or reviewing Django code.
+origin: FlowDeck
+---
+
+# Django Patterns Skill
+
+Idiomatic Django for production systems. Covers models, views, ORM patterns, and project layout.
+
+## When to Activate
+
+Activate when:
+- Writing new Django apps or services
+- Reviewing Django code for correctness and idiom
+- Designing model relationships and ORM queries
+- Building views with class-based views or function-based views
+- Configuring URL routing and middleware
+
+## Project Structure
+
+### Standard Layout
+
+```text
+manage.py
+mysite/
+    __init__.py
+    settings.py
+    urls.py
+    wsgi.py
+myapp/
+    __init__.py
+    models.py
+    views.py
+    urls.py
+    admin.py
+    apps.py
+```
+
+### Decoupled Layout (Recommended)
+
+```text
+manage.py
+myapp/
+    __init__.py
+    models.py
+    views.py
+    urls.py
+mysite/
+    __init__.py
+    settings.py
+    urls.py
+    wsgi.py
+```
+
+Import apps as top-level modules without project prefix.
+
+## Models and ORM
+
+### Basic Model Definition
+
+```python
+from django.db import models
+
+class Reporter(models.Model):
+    full_name = models.CharField(max_length=70)
+
+    def __str__(self):
+        return self.full_name
+
+class Article(models.Model):
+    pub_date = models.DateField()
+    headline = models.CharField(max_length=200)
+    content = models.TextField()
+    reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
+
+    def __str__(self):
+        return self.headline
+```
+
+### Field Types and Options
+
+```python
+class Book(models.Model):
+    class Status(models.TextChoices):
+        DRAFT = 'draft', 'Draft'
+        PUBLISHED = 'published', 'Published'
+        ARCHIVED = 'archived', 'Archived'
+
+    title = models.CharField(max_length=200)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
+    isbn = models.CharField(max_length=13, unique=True)
+    published_date = models.DateField()
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    status = models.CharField(max_length=10, choices=Status.choices, default=Status.DRAFT)
+    tags = models.ManyToManyField('Tag', blank=True)
+
+    class Meta:
+        ordering = ['title']
+        indexes = [
+            models.Index(fields=['title', 'author']),
+            models.Index(fields=['published_date']),
+        ]
+```
+
+### QuerySet Operations
+
+```python
+# Create
+author = Author.objects.create(name="Jane Doe", email="jane@example.com")
+book = Book.objects.create(title="Django Mastery", author=author, isbn="9781234567890")
+
+# Read with filtering
+published_books = Book.objects.filter(status=Book.Status.PUBLISHED)
+expensive_books = Book.objects.filter(price__gte=30.00)
+
+# Complex queries with Q objects
+from django.db.models import Q, F, Count, Avg
+books = Book.objects.filter(
+    Q(title__icontains='django') | Q(author__name__icontains='django')
+).exclude(status=Book.Status.ARCHIVED)
+
+# Aggregations
+author_stats = Author.objects.annotate(
+    book_count=Count('books'),
+    avg_price=Avg('books__price')
+).filter(book_count__gt=0)
+
+# Update with F expressions
+Book.objects.filter(pk=1).update(price=F('price') * 1.1)
+
+# Select related (prevents N+1)
+books_with_authors = Book.objects.select_related('author').all()
+```
+
+## Views
+
+### Class-Based Views
+
+```python
+from django.http import HttpResponse
+from django.views import View
+from django.views.generic import ListView, DetailView, CreateView
+
+class MyView(View):
+    def get(self, request, *args, **kwargs):
+        return HttpResponse("Hello, World!")
+
+# URL routing
+from django.urls import path
+urlpatterns = [
+    path("about/", MyView.as_view()),
+]
+```
+
+### Generic Class-Based Views
+
+```python
+class ArticleListView(ListView):
+    model = Article
+    template_name = "articles/list.html"
+    context_object_name = "articles"
+
+    def get_queryset(self):
+        return Article.objects.filter(status='published').select_related('author')
+
+class ArticleDetailView(DetailView):
+    model = Article
+    template_name = "articles/detail.html"
+    context_object_name = "article"
+
+class ArticleCreateView(CreateView):
+    model = Article
+    fields = ['title', 'content', 'author', 'status']
+    template_name = "articles/form.html"
+    success_url = reverse_lazy('article-list')
+```
+
+### Function-Based Views
+
+```python
+from django.http import JsonResponse
+from django.shortcuts import get_object_or_404
+
+def article_detail(request, pk):
+    article = get_object_or_404(Article, pk=pk)
+    return JsonResponse({
+        'id': article.id,
+        'title': article.title,
+        'content': article.content,
+    })
+```
+
+## URL Routing
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    path("articles/", include("articles.urls")),
+    path("about/", AboutView.as_view(), name="about"),
+]
+
+# In articles/urls.py
+from django.urls import path
+from .views import ArticleListView, ArticleDetailView
+
+urlpatterns = [
+    path("", ArticleListView.as_view(), name="article-list"),
+    path("<int:pk>/", ArticleDetailView.as_view(), name="article-detail"),
+]
+```
+
+## Middleware
+
+### Function-Based Middleware
+
+```python
+def simple_middleware(get_response):
+    def middleware(request):
+        # Code executed before view
+        response = get_response(request)
+        # Code executed after view
+        return response
+    return middleware
+```
+
+### Adding to Settings
+
+```python
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',
+    'django.middleware.common.CommonMiddleware',
+    'myapp.middleware.simple_middleware',
+]
+```
+
+## Forms
+
+### Model Forms
+
+```python
+from django import forms
+from .models import Article
+
+class ArticleForm(forms.ModelForm):
+    class Meta:
+        model = Article
+        fields = ['title', 'content', 'author', 'status']
+
+    def clean_title(self):
+        title = self.cleaned_data['title']
+        if 'spam' in title.lower():
+            raise forms.ValidationError("No spam allowed")
+        return title
+```
+
+## Common Pitfalls
+
+### N+1 Query Problem
+
+```python
+# Bad: causes N+1 queries
+articles = Article.objects.all()
+for article in articles:
+    print(article.author.name)  # N additional queries
+
+# Good: use select_related or prefetch_related
+articles = Article.objects.select_related('author').all()
+for article in articles:
+    print(article.author.name)  # No additional queries
+```
+
+### Using Q Objects for Complex Queries
+
+```python
+from django.db.models import Q
+
+# OR conditions
+Book.objects.filter(Q(title__icontains='django') | Q(author__name__icontains='django'))
+
+# AND with exclusion
+Book.objects.filter(status='published').exclude(Q(title__icontains='old'))
+```
+
+### Bulk Operations
+
+```python
+# Create multiple objects efficiently
+Book.objects.bulk_create([
+    Book(title='Book 1', author=author),
+    Book(title='Book 2', author=author),
+])
+
+# Update multiple objects
+Book.objects.filter(status='archived').update(status='published')
+```
+
+## Related Skills
+
+- django-tdd
+- python-patterns
+- api-design

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