@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/terraform-patterns.md

@@ -0,0 +1,270 @@
+---
+name: terraform-patterns
+description: Terraform and IaC patterns for modules, state management, workspaces, drift detection, and import.
+---
+
+# Terraform / IaC Patterns
+
+## When to Use
+
+Apply these patterns when managing cloud infrastructure with Terraform 1.5+. Use
+this skill for structuring reusable modules, managing state safely, isolating
+environments with workspaces, detecting configuration drift, and importing
+existing resources under Terraform management.
+
+## How It Works
+
+### Module Structure
+
+Create reusable modules with clear inputs, outputs, and documentation. A module
+should represent one logical unit (VPC, ECS service, RDS instance).
+
+```
+modules/
+  vpc/
+    main.tf          # resources
+    variables.tf     # input variables
+    outputs.tf       # output values
+    versions.tf      # required providers and versions
+    README.md        # usage documentation
+  ecs-service/
+    main.tf
+    variables.tf
+    outputs.tf
+    iam.tf           # IAM roles/policies for this module
+    versions.tf
+```
+
+```hcl
+# modules/vpc/variables.tf
+variable "name" {
+  type        = string
+  description = "Name prefix for all VPC resources"
+}
+
+variable "cidr" {
+  type        = string
+  description = "CIDR block for the VPC"
+  default     = "10.0.0.0/16"
+
+  validation {
+    condition     = can(cidrhost(var.cidr, 0))
+    error_message = "Must be a valid CIDR block."
+  }
+}
+
+variable "availability_zones" {
+  type        = list(string)
+  description = "List of AZs to deploy subnets into"
+}
+
+# modules/vpc/outputs.tf
+output "vpc_id" {
+  value       = aws_vpc.main.id
+  description = "ID of the created VPC"
+}
+
+output "private_subnet_ids" {
+  value       = aws_subnet.private[*].id
+  description = "IDs of private subnets"
+}
+```
+
+### Root Module Composition
+
+The root module wires together child modules and passes configuration. Keep
+resource definitions in modules; the root should be mostly module calls.
+
+```hcl
+# environments/production/main.tf
+module "vpc" {
+  source             = "../../modules/vpc"
+  name               = "prod"
+  cidr               = "10.0.0.0/16"
+  availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]
+}
+
+module "database" {
+  source            = "../../modules/rds"
+  name              = "prod-db"
+  vpc_id            = module.vpc.vpc_id
+  subnet_ids        = module.vpc.private_subnet_ids
+  instance_class    = "db.r6g.large"
+  allocated_storage = 100
+  multi_az          = true
+}
+
+module "api" {
+  source       = "../../modules/ecs-service"
+  name         = "api"
+  vpc_id       = module.vpc.vpc_id
+  subnet_ids   = module.vpc.private_subnet_ids
+  image        = "${var.ecr_repo}:${var.image_tag}"
+  cpu          = 512
+  memory       = 1024
+  desired_count = 3
+
+  environment = {
+    DATABASE_URL = module.database.connection_string
+    NODE_ENV     = "production"
+  }
+}
+```
+
+### State Management
+
+Remote state prevents conflicts. Use S3 + DynamoDB for locking. Never store
+state locally in production. Separate state per environment.
+
+```hcl
+# environments/production/backend.tf
+terraform {
+  backend "s3" {
+    bucket         = "mycompany-terraform-state"
+    key            = "production/terraform.tfstate"
+    region         = "us-east-1"
+    dynamodb_table = "terraform-locks"
+    encrypt        = true
+  }
+}
+```
+
+```hcl
+# State locking table (create once, outside Terraform)
+resource "aws_dynamodb_table" "terraform_locks" {
+  name         = "terraform-locks"
+  billing_mode = "PAY_PER_REQUEST"
+  hash_key     = "LockID"
+
+  attribute {
+    name = "LockID"
+    type = "S"
+  }
+}
+```
+
+### Workspaces vs. Directory Structure
+
+Use **directory-per-environment** for significantly different configs. Use
+**workspaces** only when environments share identical structure and differ
+only in variable values.
+
+```
+# Directory approach (recommended for most teams)
+environments/
+  production/
+    main.tf
+    terraform.tfvars
+    backend.tf
+  staging/
+    main.tf
+    terraform.tfvars
+    backend.tf
+
+# Workspace approach (same structure, different values)
+terraform workspace select production
+terraform apply -var-file="production.tfvars"
+```
+
+### Drift Detection
+
+Run `terraform plan` on a schedule (CI/CD) to detect manual changes. Alert on
+any planned changes when none are expected.
+
+```yaml
+# .github/workflows/drift-detection.yml
+name: Terraform Drift Detection
+on:
+  schedule:
+    - cron: '0 8 * * 1-5'  # weekday mornings
+
+jobs:
+  detect-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+      - run: terraform init
+        working-directory: environments/production
+      - run: terraform plan -detailed-exitcode -out=plan.tfplan
+        working-directory: environments/production
+        id: plan
+        continue-on-error: true
+      - if: steps.plan.outcome == 'failure'
+        run: |
+          echo "Drift detected in production!"
+          # Send alert to Slack/PagerDuty
+```
+
+### Import Existing Resources
+
+Use `import` blocks (Terraform 1.5+) to bring existing resources under management
+without destroying and recreating them.
+
+```hcl
+# Import an existing S3 bucket
+import {
+  to = aws_s3_bucket.existing_logs
+  id = "my-existing-log-bucket"
+}
+
+resource "aws_s3_bucket" "existing_logs" {
+  bucket = "my-existing-log-bucket"
+  # Configuration matching the existing resource
+}
+```
+
+```bash
+# Generate config for imported resources
+terraform plan -generate-config-out=generated.tf
+```
+
+### Variable Validation and Locals
+
+Use `validation` blocks on variables. Use `locals` for computed values to
+keep resource blocks clean.
+
+```hcl
+variable "environment" {
+  type = string
+  validation {
+    condition     = contains(["dev", "staging", "production"], var.environment)
+    error_message = "Environment must be dev, staging, or production."
+  }
+}
+
+locals {
+  common_tags = {
+    Environment = var.environment
+    ManagedBy   = "terraform"
+    Project     = var.project_name
+  }
+  name_prefix = "${var.project_name}-${var.environment}"
+}
+```
+
+## Examples
+
+**Pattern: Conditional resource creation**
+```hcl
+resource "aws_cloudwatch_metric_alarm" "cpu" {
+  count               = var.enable_alarms ? 1 : 0
+  alarm_name          = "${local.name_prefix}-cpu-high"
+  comparison_operator = "GreaterThanThreshold"
+  threshold           = 80
+  # ...
+}
+```
+
+## Checklist
+
+- [ ] One logical unit per module (VPC, service, database)
+- [ ] All variables have `type`, `description`, and `validation` where applicable
+- [ ] All outputs have `description`
+- [ ] Remote state with S3 + DynamoDB locking, encrypted at rest
+- [ ] Separate state files per environment
+- [ ] `terraform fmt` and `terraform validate` in CI
+- [ ] Drift detection runs on a schedule, alerts on unexpected changes
+- [ ] `import` blocks for existing resources (Terraform 1.5+)
+- [ ] `locals` for computed values and common tags
+- [ ] Provider versions pinned with `~>` in `versions.tf`

package/assets/skills/testing-react.md

@@ -0,0 +1,240 @@
+---
+name: testing-react
+description: React Testing Library patterns including render, screen queries, userEvent, async testing, and custom hooks testing.
+---
+
+# React Testing Library Patterns
+
+## When to Use
+Use React Testing Library when testing React components from the user's perspective. These patterns focus on testing behavior rather than implementation details, querying by accessible roles and text rather than CSS selectors or component internals. Apply these patterns for unit tests of individual components, integration tests of connected components, and tests of custom hooks.
+
+## How It Works
+
+### Basic Component Rendering
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Badge } from '../src/components/Badge';
+
+describe('Badge', () => {
+  it('renders the label text', () => {
+    render(<Badge label="New" variant="info" />);
+
+    expect(screen.getByText('New')).toBeInTheDocument();
+  });
+
+  it('applies the correct variant class', () => {
+    render(<Badge label="Error" variant="danger" />);
+
+    const badge = screen.getByText('Error');
+    expect(badge).toHaveClass('badge-danger');
+  });
+
+  it('renders nothing when label is empty', () => {
+    const { container } = render(<Badge label="" variant="info" />);
+    expect(container.firstChild).toBeNull();
+  });
+});
+```
+
+### User Interactions with userEvent
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LoginForm } from '../src/components/LoginForm';
+
+describe('LoginForm', () => {
+  it('submits with email and password', async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText('Email'), 'alice@example.com');
+    await user.type(screen.getByLabelText('Password'), 'secret123');
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'alice@example.com',
+      password: 'secret123',
+    });
+  });
+
+  it('disables submit when fields are empty', async () => {
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    const submitButton = screen.getByRole('button', { name: /sign in/i });
+    expect(submitButton).toBeDisabled();
+  });
+
+  it('shows validation error for invalid email', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    await user.type(screen.getByLabelText('Email'), 'not-an-email');
+    await user.tab();
+
+    expect(screen.getByText('Please enter a valid email')).toBeInTheDocument();
+  });
+});
+```
+
+### Async Testing with waitFor and findBy
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { UserList } from '../src/components/UserList';
+import * as api from '../src/api';
+
+vi.mock('../src/api');
+
+describe('UserList', () => {
+  it('displays users after loading', async () => {
+    vi.mocked(api.fetchUsers).mockResolvedValueOnce([
+      { id: '1', name: 'Alice' },
+      { id: '2', name: 'Bob' },
+    ]);
+
+    render(<UserList />);
+
+    expect(screen.getByText('Loading...')).toBeInTheDocument();
+
+    const alice = await screen.findByText('Alice');
+    expect(alice).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+    expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
+  });
+
+  it('shows error message on fetch failure', async () => {
+    vi.mocked(api.fetchUsers).mockRejectedValueOnce(new Error('Server error'));
+
+    render(<UserList />);
+
+    await waitFor(() => {
+      expect(screen.getByRole('alert')).toHaveTextContent('Failed to load users');
+    });
+  });
+});
+```
+
+### Testing Custom Hooks
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useDebounce } from '../src/hooks/useDebounce';
+
+describe('useDebounce', () => {
+  it('returns debounced value after delay', async () => {
+    vi.useFakeTimers();
+
+    const { result, rerender } = renderHook(
+      ({ value }) => useDebounce(value, 500),
+      { initialProps: { value: 'hello' } },
+    );
+
+    expect(result.current).toBe('hello');
+
+    rerender({ value: 'hello world' });
+    expect(result.current).toBe('hello');
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(result.current).toBe('hello world');
+    vi.useRealTimers();
+  });
+});
+```
+
+### Testing with Providers (Router, Theme, Store)
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { ThemeProvider } from '../src/context/ThemeContext';
+import { Navbar } from '../src/components/Navbar';
+
+function renderWithProviders(ui: React.ReactElement, { route = '/' } = {}) {
+  return render(
+    <MemoryRouter initialEntries={[route]}>
+      <ThemeProvider defaultTheme="light">
+        {ui}
+      </ThemeProvider>
+    </MemoryRouter>,
+  );
+}
+
+describe('Navbar', () => {
+  it('highlights the active link', () => {
+    renderWithProviders(<Navbar />, { route: '/settings' });
+
+    const settingsLink = screen.getByRole('link', { name: /settings/i });
+    expect(settingsLink).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('renders all navigation items', () => {
+    renderWithProviders(<Navbar />);
+
+    expect(screen.getByRole('link', { name: /dashboard/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /projects/i })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: /settings/i })).toBeInTheDocument();
+  });
+});
+```
+
+### Accessibility Queries Priority
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SearchBar } from '../src/components/SearchBar';
+
+describe('SearchBar accessibility', () => {
+  it('uses accessible queries in priority order', () => {
+    render(<SearchBar placeholder="Search projects..." />);
+
+    // 1. getByRole - best, matches ARIA roles
+    screen.getByRole('searchbox');
+
+    // 2. getByLabelText - for form fields
+    screen.getByLabelText('Search');
+
+    // 3. getByPlaceholderText - when no label exists
+    screen.getByPlaceholderText('Search projects...');
+
+    // 4. getByText - for non-interactive elements
+    screen.getByText('Search');
+
+    // 5. getByTestId - last resort
+    screen.getByTestId('search-bar');
+  });
+});
+```
+
+## Examples
+
+| Query | When to Use | Example |
+|-------|------------|---------|
+| `getByRole` | Buttons, links, headings, form controls | `getByRole('button', { name: /save/i })` |
+| `getByLabelText` | Form inputs with associated labels | `getByLabelText('Email address')` |
+| `getByText` | Static text content | `getByText(/no results found/i)` |
+| `findByText` | Elements that appear asynchronously | `await findByText('Loaded!')` |
+| `queryByText` | Asserting an element does NOT exist | `expect(queryByText('Error')).toBeNull()` |
+| `getAllByRole` | Multiple matching elements | `getAllByRole('listitem')` |
+
+## Checklist
+- [ ] Use `userEvent.setup()` instead of `fireEvent` for realistic interactions
+- [ ] Prefer `getByRole` and `getByLabelText` over `getByTestId`
+- [ ] Use `findBy*` (async) for elements that appear after loading or state changes
+- [ ] Use `queryBy*` only when asserting an element is absent
+- [ ] Wrap state updates in `act()` only when not already handled by RTL utilities
+- [ ] Provide wrapper components (router, theme, store) via a shared `renderWithProviders` helper
+- [ ] Never test internal state or implementation details (no `component.state` access)
+- [ ] Run with `jsdom` or `happy-dom` environment configured in vitest.config.ts