@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/django-patterns.md

@@ -0,0 +1,182 @@
+---
+name: django-patterns
+description: Django patterns for models, views, serializers, middleware, signals, custom managers, and admin customization.
+---
+
+# Django Patterns
+
+## When to Use
+
+Apply these patterns when building Django 4.2+ applications. Use this skill for
+structuring models with custom managers, writing class-based views, building DRF
+serializers, wiring signals correctly, and customizing the admin interface.
+
+## How It Works
+
+### Models with Custom Managers and QuerySets
+
+Define a custom QuerySet, then create a manager from it. This lets you chain custom
+filters naturally. Always add `Meta.ordering` and `__str__`.
+
+```python
+class ArticleQuerySet(models.QuerySet):
+    def published(self):
+        return self.filter(status="published", pub_date__lte=timezone.now())
+
+    def by_author(self, user):
+        return self.filter(author=user)
+
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    status = models.CharField(max_length=20, choices=STATUS_CHOICES, db_index=True)
+    pub_date = models.DateTimeField(null=True, blank=True)
+    author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
+
+    objects = ArticleQuerySet.as_manager()
+
+    class Meta:
+        ordering = ["-pub_date"]
+        indexes = [models.Index(fields=["status", "pub_date"])]
+
+    def __str__(self):
+        return self.title
+```
+
+### Views: Fat Models, Thin Views
+
+Keep business logic in model methods or service functions. Views handle HTTP
+concerns only: parsing requests, calling services, returning responses.
+
+```python
+# services.py
+def publish_article(article: Article, user: User) -> Article:
+    if not user.has_perm("articles.publish"):
+        raise PermissionDenied("Cannot publish")
+    article.status = "published"
+    article.pub_date = timezone.now()
+    article.save(update_fields=["status", "pub_date"])
+    return article
+
+# views.py
+class ArticlePublishView(LoginRequiredMixin, View):
+    def post(self, request, pk):
+        article = get_object_or_404(Article, pk=pk)
+        publish_article(article, request.user)
+        return redirect("article-detail", pk=pk)
+```
+
+### DRF Serializers
+
+Use `ModelSerializer` for CRUD. Override `validate_<field>` for field-level
+validation. Use `SerializerMethodField` for computed fields. Nest read serializers;
+accept IDs for writes.
+
+```python
+class ArticleSerializer(serializers.ModelSerializer):
+    author_name = serializers.SerializerMethodField()
+    word_count = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Article
+        fields = ["id", "title", "status", "pub_date", "author", "author_name", "word_count"]
+        read_only_fields = ["pub_date"]
+
+    def get_author_name(self, obj):
+        return obj.author.get_full_name()
+
+    def get_word_count(self, obj):
+        return len(obj.body.split())
+
+    def validate_title(self, value):
+        if len(value) < 5:
+            raise serializers.ValidationError("Title must be at least 5 characters")
+        return value
+```
+
+### Middleware
+
+Middleware processes every request/response. Keep it fast. Use `__init__` for
+one-time setup and `__call__` for per-request logic.
+
+```python
+class RequestTimingMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        start = time.monotonic()
+        response = self.get_response(request)
+        duration_ms = (time.monotonic() - start) * 1000
+        response["X-Request-Duration-Ms"] = f"{duration_ms:.1f}"
+        return response
+```
+
+### Signals: Use Sparingly
+
+Signals create implicit coupling. Prefer explicit service calls. When you do use
+signals, connect them in `AppConfig.ready()` and keep handlers idempotent.
+
+```python
+# apps.py
+class ArticlesConfig(AppConfig):
+    name = "articles"
+    def ready(self):
+        from . import signals  # noqa: F401
+
+# signals.py
+from django.db.models.signals import post_save
+from django.dispatch import receiver
+
+@receiver(post_save, sender=Article)
+def notify_subscribers(sender, instance, created, **kwargs):
+    if created and instance.status == "published":
+        enqueue_notification_task(instance.pk)
+```
+
+### Admin Customization
+
+Use `list_display`, `list_filter`, `search_fields` for usability. Add custom
+actions for bulk operations. Use `readonly_fields` for computed displays.
+
+```python
+@admin.register(Article)
+class ArticleAdmin(admin.ModelAdmin):
+    list_display = ["title", "author", "status", "pub_date"]
+    list_filter = ["status", "pub_date"]
+    search_fields = ["title", "body"]
+    raw_id_fields = ["author"]
+    actions = ["mark_published"]
+
+    @admin.action(description="Mark selected as published")
+    def mark_published(self, request, queryset):
+        queryset.update(status="published", pub_date=timezone.now())
+```
+
+## Examples
+
+**Pattern: select_related / prefetch_related to avoid N+1**
+```python
+articles = Article.objects.published().select_related("author").prefetch_related("tags")
+```
+
+**Pattern: Database constraint at the model level**
+```python
+class Meta:
+    constraints = [
+        models.UniqueConstraint(fields=["author", "slug"], name="unique_author_slug"),
+        models.CheckConstraint(check=models.Q(price__gte=0), name="price_non_negative"),
+    ]
+```
+
+## Checklist
+
+- [ ] Every model has `__str__`, `Meta.ordering`, and relevant indexes
+- [ ] Custom QuerySet methods chained via `.as_manager()`
+- [ ] Business logic in service functions, not views
+- [ ] `select_related` / `prefetch_related` for related lookups (no N+1 queries)
+- [ ] Serializers validate at field and object level
+- [ ] Signals connected in `AppConfig.ready()`, kept idempotent
+- [ ] Middleware is fast and stateless
+- [ ] Admin uses `list_display`, `list_filter`, `search_fields`
+- [ ] Database constraints (`UniqueConstraint`, `CheckConstraint`) enforce integrity
+- [ ] `update_fields` passed to `.save()` when only specific columns change

package/assets/skills/docker-patterns.md

@@ -0,0 +1,235 @@
+---
+name: docker-patterns
+description: Build efficient Docker images with multi-stage builds, layer caching, health checks, and Compose orchestration.
+---
+
+# Docker Patterns
+
+## When to Use
+
+Use these patterns when containerizing any application for development, CI, or
+production. A poorly written Dockerfile wastes minutes per build, ships hundreds
+of megabytes of unnecessary files, and creates security vulnerabilities.
+
+## How It Works
+
+### 1. Multi-Stage Builds
+
+Separate build dependencies from the runtime image. Final image contains only
+what's needed to run.
+
+```dockerfile
+# Stage 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+COPY tsconfig.json ./
+COPY src/ src/
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+RUN addgroup -g 1001 appuser && adduser -u 1001 -G appuser -s /bin/sh -D appuser
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json /app/package-lock.json ./
+RUN npm ci --ignore-scripts --omit=dev && npm cache clean --force
+
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+Result: builder stage has TypeScript, dev dependencies, source. Runner stage has
+only compiled JS and production deps. Image shrinks from ~800MB to ~150MB.
+
+### 2. Layer Caching
+
+Docker caches each layer. Order instructions from least-changing to most-changing.
+
+```dockerfile
+# Good order — dependencies change less often than source code
+COPY package.json package-lock.json ./    # Layer 1: cached unless deps change
+RUN npm ci                                # Layer 2: cached with Layer 1
+COPY src/ src/                            # Layer 3: busted on every code change
+RUN npm run build                         # Layer 4: busted with Layer 3
+```
+
+```dockerfile
+# Bad order — every code change reinstalls dependencies
+COPY . .                                  # Always busted
+RUN npm ci && npm run build               # Always reinstalls
+```
+
+### 3. .dockerignore
+
+Exclude files that bloat context and leak secrets.
+
+```
+node_modules
+.git
+.env*
+*.md
+coverage
+.next
+dist
+```
+
+### 4. Health Checks
+
+Let orchestrators know when your app is actually ready to serve traffic.
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+```
+
+The health endpoint should verify critical dependencies:
+
+```typescript
+app.get('/health', async (req, res) => {
+  try {
+    await db.$queryRaw`SELECT 1`;
+    res.json({ status: 'ok', db: 'connected' });
+  } catch {
+    res.status(503).json({ status: 'unhealthy', db: 'disconnected' });
+  }
+});
+```
+
+### 5. Docker Compose for Development
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build:
+      context: .
+      target: builder          # use the builder stage for dev
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./src:/app/src         # hot reload
+      - /app/node_modules      # prevent host overwrite
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app
+      - REDIS_URL=redis://cache:6379
+    depends_on:
+      db:
+        condition: service_healthy
+    command: npm run dev
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_PASSWORD: postgres
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  cache:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  pgdata:
+```
+
+### 6. Secrets Management
+
+Never bake secrets into images. Use build-time secrets or runtime injection.
+
+```dockerfile
+# Build-time secret (Docker BuildKit)
+RUN --mount=type=secret,id=npm_token \
+    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
+```
+
+```bash
+docker build --secret id=npm_token,src=.npm_token .
+```
+
+Runtime: pass via environment variables or mounted secret files.
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    environment:
+      - DATABASE_URL  # inherits from host env
+    secrets:
+      - api_key
+
+secrets:
+  api_key:
+    file: ./secrets/api_key.txt
+```
+
+### 7. Volume Patterns
+
+```yaml
+volumes:
+  # Named volume — persists across restarts
+  pgdata:
+    driver: local
+
+  # Bind mount — sync host files into container
+  # Good for dev, bad for production
+  ./src:/app/src
+
+  # Anonymous volume — prevent host from overwriting container dirs
+  /app/node_modules
+```
+
+### 8. Production Best Practices
+
+```dockerfile
+# Pin exact versions, not :latest
+FROM node:20.11.1-alpine3.19
+
+# Run as non-root
+USER 1001
+
+# Set memory limits
+ENV NODE_OPTIONS="--max-old-space-size=256"
+
+# Use tini as PID 1 for proper signal handling
+RUN apk add --no-cache tini
+ENTRYPOINT ["/sbin/tini", "--"]
+CMD ["node", "dist/index.js"]
+```
+
+## Examples
+
+| Goal | Pattern |
+|------|---------|
+| Small image | Multi-stage build, Alpine base |
+| Fast rebuilds | Layer caching, .dockerignore |
+| Reliable orchestration | Health checks with dependency verification |
+| Local development | Compose with bind mounts and hot reload |
+| Secret protection | BuildKit secrets, never `ENV` or `ARG` for secrets |
+
+## Checklist
+
+- [ ] Dockerfile uses multi-stage build — final image has no build tools
+- [ ] Base image is pinned to a specific version, not `:latest`
+- [ ] `.dockerignore` excludes `node_modules`, `.git`, `.env*`, and build artifacts
+- [ ] COPY order puts `package*.json` before source code for layer caching
+- [ ] `HEALTHCHECK` instruction is present with reasonable intervals
+- [ ] Application runs as a non-root user
+- [ ] No secrets in the image — use BuildKit secrets or runtime env vars
+- [ ] `tini` or equivalent handles PID 1 for proper signal forwarding
+- [ ] Compose `depends_on` uses `condition: service_healthy`
+- [ ] Production image is < 200MB (verify with `docker images`)

package/assets/skills/e2e-testing.md

@@ -0,0 +1,287 @@
+---
+name: e2e-testing
+description: E2E testing patterns with Playwright including page objects, fixtures, network mocking, visual comparisons, and CI integration.
+---
+
+# E2E Testing Patterns
+
+## When to Use
+Write end-to-end tests for critical user journeys: authentication, checkout, onboarding, data-entry workflows, and any path where a failure means lost revenue or broken trust. Use Playwright for cross-browser coverage (Chromium, Firefox, WebKit), built-in auto-waiting, and powerful network interception. Reserve E2E for high-value flows and use unit/integration tests for everything else.
+
+## How It Works
+
+### Playwright Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { open: 'never' }],
+    ['junit', { outputFile: 'results/e2e.xml' }],
+  ],
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+  },
+  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'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+### Page Object Model
+
+```typescript
+// e2e/pages/login.page.ts
+import { Page, Locator, expect } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorAlert: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Sign in' });
+    this.errorAlert = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+
+  async expectError(message: string) {
+    await expect(this.errorAlert).toContainText(message);
+  }
+
+  async expectRedirectTo(path: string) {
+    await expect(this.page).toHaveURL(new RegExp(path));
+  }
+}
+```
+
+```typescript
+// e2e/pages/dashboard.page.ts
+import { Page, Locator, expect } from '@playwright/test';
+
+export class DashboardPage {
+  readonly page: Page;
+  readonly heading: Locator;
+  readonly userMenu: Locator;
+  readonly navLinks: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.heading = page.getByRole('heading', { level: 1 });
+    this.userMenu = page.getByTestId('user-menu');
+    this.navLinks = page.getByRole('navigation').getByRole('link');
+  }
+
+  async expectLoaded() {
+    await expect(this.heading).toBeVisible();
+  }
+
+  async logout() {
+    await this.userMenu.click();
+    await this.page.getByRole('menuitem', { name: 'Logout' }).click();
+  }
+}
+```
+
+### Custom Fixtures
+
+```typescript
+// e2e/fixtures.ts
+import { test as base, expect } from '@playwright/test';
+import { LoginPage } from './pages/login.page';
+import { DashboardPage } from './pages/dashboard.page';
+
+type Fixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+  authenticatedPage: async ({ browser }, use) => {
+    const context = await browser.newContext({
+      storageState: 'e2e/.auth/user.json',
+    });
+    const page = await context.newPage();
+    await use(page);
+    await context.close();
+  },
+});
+
+export { expect };
+```
+
+### Authentication Setup
+
+```typescript
+// e2e/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill('TestPassword123');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page).toHaveURL('/dashboard');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'e2e/.auth/user.json' });
+});
+```
+
+### Network Mocking
+
+```typescript
+// e2e/tests/dashboard.spec.ts
+import { test, expect } from '../fixtures';
+
+test.describe('Dashboard', () => {
+  test('displays analytics data', async ({ page }) => {
+    // Mock the API response
+    await page.route('**/api/analytics*', (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          visitors: 1234,
+          pageViews: 5678,
+          bounceRate: 0.42,
+        }),
+      })
+    );
+
+    await page.goto('/dashboard');
+    await expect(page.getByText('1,234')).toBeVisible();
+    await expect(page.getByText('5,678')).toBeVisible();
+  });
+
+  test('handles API failure gracefully', async ({ page }) => {
+    await page.route('**/api/analytics*', (route) =>
+      route.fulfill({ status: 500 })
+    );
+
+    await page.goto('/dashboard');
+    await expect(page.getByText('Failed to load analytics')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+  });
+
+  test('waits for network idle', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/analytics*');
+    await page.goto('/dashboard');
+    const response = await responsePromise;
+    expect(response.status()).toBe(200);
+  });
+});
+```
+
+### Visual Comparisons
+
+```typescript
+// e2e/tests/visual.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('homepage visual regression', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png', {
+    maxDiffPixelRatio: 0.01,
+    fullPage: true,
+  });
+});
+
+test('component visual states', async ({ page }) => {
+  await page.goto('/storybook/iframe.html?id=button--primary');
+  await expect(page.locator('#storybook-root')).toHaveScreenshot('button-primary.png');
+
+  // Hover state
+  await page.locator('button').hover();
+  await expect(page.locator('#storybook-root')).toHaveScreenshot('button-primary-hover.png');
+});
+```
+
+### CI Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+```
+
+## Examples
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Page Object | Duplicate locators across tests | Centralized selectors and actions |
+| Custom fixture | Repeated setup per test | Shared auth, page objects via fixture |
+| Storage state | Re-login per test is slow | Save/restore auth cookies |
+| `page.route()` | Tests depend on live API | Mock API for deterministic data |
+| `toHaveScreenshot()` | Visual bugs missed in review | Pixel-diff screenshots in CI |
+
+## Checklist
+- [ ] Tests use Page Object Model for reusable selectors and actions
+- [ ] Custom fixtures provide page objects and authenticated contexts
+- [ ] Auth state saved to file and reused across tests (not re-login per test)
+- [ ] Network requests mocked for deterministic test data
+- [ ] Locators use accessible roles (`getByRole`, `getByLabel`) not CSS selectors
+- [ ] Visual regression screenshots baselined and checked on PR
+- [ ] CI configured with retries, trace-on-failure, and artifact upload
+- [ ] Tests run across at least Chromium, Firefox, and one mobile viewport