vibe-and-thrive 1.0.0

package/.claude/commands/add-tests.md

@@ -0,0 +1,240 @@
+# Add Tests
+
+Add tests to existing code to improve coverage and confidence.
+
+## Instructions
+
+When asked to add tests:
+
+### Step 1: Analyze the Code
+
+1. Read the code to understand what it does
+2. Identify the public interface (what should be tested)
+3. Find edge cases and error conditions
+4. Check existing test patterns in the project
+
+### Step 2: Determine Test Type
+
+| Code Type | Test Type | Framework |
+|-----------|-----------|-----------|
+| Utility functions | Unit tests | Jest, pytest |
+| React components | Component tests | React Testing Library |
+| API endpoints | Integration tests | supertest, pytest |
+| User flows | E2E tests | Playwright, Cypress |
+| Hooks | Hook tests | @testing-library/react-hooks |
+
+### Step 3: Identify Test Cases
+
+For each function/component, consider:
+
+**Happy Path**
+- Normal inputs produce expected outputs
+- Main use case works correctly
+
+**Edge Cases**
+- Empty inputs
+- Null/undefined values
+- Boundary values (0, -1, max)
+- Single item vs multiple items
+
+**Error Cases**
+- Invalid inputs
+- Network failures
+- Permission errors
+- Timeout scenarios
+
+**State Transitions**
+- Before/after state changes
+- Loading → success → idle
+- Loading → error → retry
+
+### Step 4: Write Tests
+
+Use this structure for each test:
+
+```typescript
+test('descriptive name of what is being tested', () => {
+  // Arrange: Set up test data and conditions
+  const input = createTestInput();
+
+  // Act: Perform the action being tested
+  const result = functionUnderTest(input);
+
+  // Assert: Verify the expected outcome
+  expect(result).toEqual(expectedOutput);
+});
+```
+
+### Step 5: Document Test Purpose
+
+Use the SCENARIO/EXPECTED/FAILURE pattern:
+
+```typescript
+test('user can submit form with valid data', () => {
+  /**
+   * SCENARIO: User fills out all required fields correctly
+   * EXPECTED: Form submits successfully, success message shown
+   * FAILURE: Form doesn't submit, or error message shown
+   */
+});
+```
+
+## Output Format
+
+```markdown
+## Tests for: [filename]
+
+### Test File Location
+`[path/to/test/file.test.ts]`
+
+### Test Cases
+
+1. **Happy Path**: [description]
+2. **Edge Case**: [description]
+3. **Error Case**: [description]
+
+### Generated Tests
+
+```typescript
+[complete test file]
+```
+
+### Coverage Summary
+- Functions tested: X/Y
+- Edge cases covered: [list]
+- Not covered (intentionally): [list with reasons]
+
+### Running the Tests
+```bash
+[command to run tests]
+```
+```
+
+## Test Patterns
+
+### Unit Test (Function)
+```typescript
+describe('calculateTotal', () => {
+  it('returns sum of item prices', () => {
+    const items = [{ price: 10 }, { price: 20 }];
+    expect(calculateTotal(items)).toBe(30);
+  });
+
+  it('returns 0 for empty array', () => {
+    expect(calculateTotal([])).toBe(0);
+  });
+
+  it('handles single item', () => {
+    expect(calculateTotal([{ price: 15 }])).toBe(15);
+  });
+});
+```
+
+### Component Test (React)
+```typescript
+describe('LoginForm', () => {
+  it('submits with valid credentials', async () => {
+    const onSubmit = vi.fn();
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await userEvent.type(screen.getByLabelText(/password/i), 'password123');
+    await userEvent.click(screen.getByRole('button', { name: /login/i }));
+
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'test@example.com',
+      password: 'password123',
+    });
+  });
+
+  it('shows error for invalid email', async () => {
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    await userEvent.type(screen.getByLabelText(/email/i), 'invalid');
+    await userEvent.click(screen.getByRole('button', { name: /login/i }));
+
+    expect(screen.getByText(/valid email/i)).toBeInTheDocument();
+  });
+});
+```
+
+### API Test (Integration)
+```python
+def test_create_user_success(client, db):
+    """
+    SCENARIO: POST /api/users with valid data
+    EXPECTED: 201 Created, user in database
+    """
+    response = client.post('/api/users', json={
+        'email': 'test@example.com',
+        'name': 'Test User',
+    })
+
+    assert response.status_code == 201
+    assert User.objects.filter(email='test@example.com').exists()
+
+
+def test_create_user_duplicate_email(client, db, existing_user):
+    """
+    SCENARIO: POST /api/users with existing email
+    EXPECTED: 400 Bad Request, error message
+    """
+    response = client.post('/api/users', json={
+        'email': existing_user.email,
+        'name': 'Another User',
+    })
+
+    assert response.status_code == 400
+    assert 'already exists' in response.json()['error']
+```
+
+### E2E Test (Playwright)
+```typescript
+test('user can complete checkout', async ({ page }) => {
+  /**
+   * SCENARIO: User adds item to cart and completes checkout
+   * EXPECTED: Order confirmation page shown
+   * FAILURE: Stuck on checkout, error message, or wrong page
+   */
+
+  // Add item to cart
+  await page.goto('/products/1');
+  await page.click('button:has-text("Add to Cart")');
+
+  // Go to checkout
+  await page.click('a:has-text("Checkout")');
+
+  // Fill shipping info
+  await page.fill('[name="address"]', '123 Main St');
+  await page.fill('[name="city"]', 'Anytown');
+
+  // Complete order
+  await page.click('button:has-text("Place Order")');
+
+  // Verify success
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+```
+
+## Test Modes
+
+### Quick Tests
+Add basic happy path tests:
+> "Add basic tests for this function"
+
+### Comprehensive Tests
+Full coverage with edge cases:
+> "Add comprehensive tests for UserService"
+
+### Specific Scenario
+Test a specific case:
+> "Add a test for when the API returns a 404"
+
+## Tips
+
+- **Test behavior, not implementation**
+- **One assertion per test** (when possible)
+- **Use descriptive test names**
+- **Don't test framework code** (React, Django, etc.)
+- **Mock external dependencies**
+- **Keep tests fast**

package/.claude/commands/e2e-scaffold.md

@@ -0,0 +1,212 @@
+# E2E Test Scaffold
+
+Generate a Playwright E2E test file structure for a new feature.
+
+## Instructions
+
+Before generating the scaffold, **discover the project's testing setup**:
+
+### Step 1: Discovery Phase
+
+Check for existing patterns in this order:
+
+1. **Playwright config**: Look for `playwright.config.ts` or `playwright.config.js`
+   - Note the `testDir` setting
+   - Check for `baseURL` configuration
+   - Look for any custom fixtures or global setup
+
+2. **Test directory structure**: Search for existing E2E tests
+   - Common locations: `e2e/`, `tests/`, `tests/e2e/`, `__tests__/e2e/`
+   - Note the file naming pattern (`.spec.ts`, `.test.ts`, etc.)
+
+3. **Existing helpers**: Look for helper files
+   - `e2e/helpers.ts`, `tests/helpers.ts`, `tests/utils.ts`
+   - Note API call patterns, auth setup, common utilities
+
+4. **Auth patterns**: Search for how tests handle authentication
+   - Session-based with cookies
+   - JWT tokens
+   - OAuth flows
+   - No auth needed
+
+5. **API patterns**: Check the tech stack
+   - REST endpoints
+   - GraphQL queries
+   - tRPC calls
+
+### Step 2: Ask User
+
+If patterns are unclear, ask:
+- "What feature are you building tests for?"
+- "Does this feature require authentication?"
+- "What API endpoints will the feature use?"
+
+### Step 3: Generate Scaffold
+
+Create a test file with this structure:
+
+```typescript
+import { test, expect, Page } from '@playwright/test';
+
+// Configuration - adapt to project's pattern
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const API_BASE_URL = process.env.API_BASE_URL || 'http://localhost:8000';
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * [Add helper functions for API calls, auth setup, etc.]
+ *
+ * Example API helper pattern:
+ * async function createResourceViaAPI(page: Page): Promise<{ id: number }> {
+ *   const result = await page.evaluate(async (apiBase) => {
+ *     const response = await fetch(`${apiBase}/api/v1/resources/`, {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       credentials: 'include',
+ *     });
+ *     return response.json();
+ *   }, API_BASE_URL);
+ *   return result;
+ * }
+ */
+
+// ============================================================================
+// TEST SUITE: [Feature Name]
+// ============================================================================
+
+test.describe('[Feature Name]', () => {
+
+  test.beforeEach(async ({ page }) => {
+    // Setup: navigate to the feature, log in if needed
+    await page.goto(BASE_URL);
+  });
+
+  test.afterEach(async ({ page }, testInfo) => {
+    // Capture screenshot on failure for debugging
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const screenshotPath = `e2e-${testInfo.title.replace(/\s+/g, '-')}-failure.png`;
+      await page.screenshot({ path: screenshotPath });
+      console.log(`Screenshot saved: ${screenshotPath}`);
+    }
+  });
+
+  // --------------------------------------------------------------------------
+  // Happy Path Tests
+  // --------------------------------------------------------------------------
+
+  test('user can [primary action]', async ({ page }) => {
+    /**
+     * SCENARIO: As a [user type], when I [action],
+     *           I should [expected outcome]
+     * EXPECTED: [Specific success criteria]
+     * FAILURE: [What would indicate failure]
+     */
+
+    // Arrange: Set up test data
+
+    // Act: Perform user actions
+
+    // Assert: Verify expected outcome
+    // Use the critical assertion pattern:
+    // const isSuccess = await page.locator('[data-testid="success"]').isVisible();
+    // if (!isSuccess) {
+    //   console.error('FAIL: Success indicator not visible');
+    //   await page.screenshot({ path: 'e2e-test-name-debug.png' });
+    // }
+    // expect(isSuccess).toBeTruthy();
+  });
+
+  // --------------------------------------------------------------------------
+  // Edge Cases
+  // --------------------------------------------------------------------------
+
+  test('handles [edge case scenario]', async ({ page }) => {
+    /**
+     * SCENARIO: As a [user type], when [edge case condition],
+     *           I should [expected behavior]
+     * EXPECTED: [Specific handling criteria]
+     * FAILURE: [What would indicate improper handling]
+     */
+  });
+
+  // --------------------------------------------------------------------------
+  // Error Handling
+  // --------------------------------------------------------------------------
+
+  test('shows error when [error condition]', async ({ page }) => {
+    /**
+     * SCENARIO: As a [user type], when [error condition occurs],
+     *           I should see an appropriate error message
+     * EXPECTED: Error message displayed, user can recover
+     * FAILURE: Silent failure, crash, or unclear error
+     */
+  });
+
+});
+```
+
+### Step 4: Adapt to Project
+
+Based on discovery, customize the scaffold:
+
+**If project uses session auth with CSRF:**
+```typescript
+async function apiCallWithAuth(page: Page, endpoint: string, method: string, body?: object) {
+  return await page.evaluate(async ({ apiBase, endpoint, method, body }) => {
+    const csrfToken = document.cookie.split('; ')
+      .find(row => row.startsWith('csrftoken='))?.split('=')[1];
+    const response = await fetch(`${apiBase}${endpoint}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRFToken': csrfToken || ''
+      },
+      credentials: 'include',
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    return response.json();
+  }, { apiBase: API_BASE_URL, endpoint, method, body });
+}
+```
+
+**If project uses JWT:**
+```typescript
+async function apiCallWithJWT(page: Page, endpoint: string, method: string, body?: object) {
+  return await page.evaluate(async ({ apiBase, endpoint, method, body }) => {
+    const token = localStorage.getItem('authToken');
+    const response = await fetch(`${apiBase}${endpoint}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    return response.json();
+  }, { apiBase: API_BASE_URL, endpoint, method, body });
+}
+```
+
+**If project has existing helpers, import them:**
+```typescript
+import { loginAsTestUser, createTestData, cleanupTestData } from './helpers';
+```
+
+### Step 5: Output
+
+Provide:
+1. The scaffold file at the appropriate location
+2. Summary of discovered patterns used
+3. List of placeholder TODOs for the user to complete
+4. Suggestion to run `npx playwright test --ui` to verify setup
+
+## Notes
+
+- Always use the SCENARIO/EXPECTED/FAILURE documentation pattern
+- Include screenshot capture on failure
+- Use flexible locators: `page.getByRole()` with `.or()` for fallbacks
+- Keep tests independent - each test should set up its own data
+- Use `test.describe()` to group related tests

package/.claude/commands/explain.md

@@ -0,0 +1,110 @@
+# Explain Code
+
+Explain what code does, line by line, so you can understand and learn from it.
+
+## Instructions
+
+When the user asks you to explain code:
+
+### Step 1: Identify the Code
+
+If the user provides a file path, read that file. If they paste code directly, use that.
+
+If no code is specified, ask:
+> "What code would you like me to explain? Please provide a file path or paste the code."
+
+### Step 2: Provide Overview
+
+Start with a high-level summary:
+- What is the purpose of this code?
+- What problem does it solve?
+- How does it fit into the larger application?
+
+### Step 3: Walk Through Line by Line
+
+For each significant section, explain:
+- **What** it does (literally)
+- **Why** it's needed (purpose)
+- **How** it works (mechanism)
+
+Use this format:
+
+```
+Lines X-Y: [Brief description]
+- This code [what it does]
+- It's needed because [why]
+- It works by [how]
+```
+
+### Step 4: Highlight Key Concepts
+
+Point out important patterns and concepts:
+- Design patterns used
+- Language features that might be unfamiliar
+- Best practices demonstrated
+- Potential gotchas or edge cases
+
+### Step 5: Summarize
+
+End with:
+- Key takeaways
+- What the user should understand now
+- Suggestions for further learning if applicable
+
+## Example Output
+
+```
+## Overview
+
+This is a React custom hook that manages authentication state. It handles
+login, logout, and automatic token refresh.
+
+## Line-by-Line Explanation
+
+### Lines 1-5: Imports
+```typescript
+import { useState, useEffect, useCallback } from 'react';
+import { authApi } from '@/services/api';
+import { User } from '@/types';
+```
+- Imports React hooks for state management and side effects
+- Imports the auth API service for making authentication requests
+- Imports the User type for type safety
+
+### Lines 7-15: Hook Definition and State
+```typescript
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+```
+- Creates a custom hook that can be used in any component
+- `user` state holds the current user (or null if logged out)
+- `loading` state tracks whether we're still checking auth status
+- Starting with `loading: true` prevents flash of unauthenticated content
+
+### Lines 17-30: Auto-refresh Effect
+[... continue explanation ...]
+
+## Key Concepts
+
+1. **Custom Hooks**: Reusable logic extracted from components
+2. **Optimistic Updates**: UI updates before server confirms
+3. **Token Refresh**: Automatic re-authentication before expiry
+
+## Takeaways
+
+- This hook centralizes all auth logic in one place
+- Components just need to call `useAuth()` to access auth state
+- The refresh logic runs automatically in the background
+```
+
+## Tips for Users
+
+Ask me to explain:
+- "Explain this function" (paste code)
+- "Explain src/hooks/useAuth.ts"
+- "Explain lines 50-100 of api.ts"
+- "What does this regex do?"
+- "Why is this pattern used here?"
+
+I'll adjust the depth based on what you ask. For simple code, I'll be brief. For complex code, I'll be thorough.