start-vibing 3.0.8 → 3.0.9

package/template/.claude/skills/playwright-testing/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: playwright-testing
+description: "ALWAYS invoke when creating or editing Playwright E2E tests. Do NOT write E2E tests without checking Page Object Model, fixture design, and multi-viewport patterns first."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Playwright Testing
+
+Architecture patterns for Playwright E2E tests: Page Objects, fixtures, assertions, and multi-viewport testing.
+
+## Playwright Config
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env['CI'],
+  retries: process.env['CI'] ? 2 : 0,
+  workers: process.env['CI'] ? 1 : undefined,
+  reporter: [['html'], ['list']],
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'Desktop', use: { ...devices['Desktop Chrome'] } },
+    { name: 'Tablet', use: { ...devices['iPad Mini'] } },
+    { name: 'Mobile', use: { ...devices['iPhone 14'] } },
+  ],
+  webServer: {
+    command: 'bun run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env['CI'],
+  },
+});
+```
+
+## Page Object Model
+
+```typescript
+// tests/e2e/pages/base.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  constructor(protected page: Page) {}
+
+  abstract readonly url: string;
+
+  async goto() {
+    await this.page.goto(this.url);
+  }
+
+  async waitForReady() {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  // Shared helpers
+  async getToast() {
+    return this.page.locator('[data-sonner-toast]');
+  }
+}
+```
+
+```typescript
+// tests/e2e/pages/login.page.ts
+export class LoginPage extends BasePage {
+  readonly url = '/login';
+
+  // Locators (prefer data-testid, role, text)
+  readonly emailInput = this.page.getByLabel('Email');
+  readonly passwordInput = this.page.getByLabel('Password');
+  readonly submitButton = this.page.getByRole('button', { name: 'Sign in' });
+  readonly errorMessage = this.page.getByRole('alert');
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}
+```
+
+### Component Page Objects
+
+```typescript
+// tests/e2e/pages/components/data-table.component.ts
+export class DataTableComponent {
+  constructor(private container: Locator) {}
+
+  get rows() { return this.container.getByRole('row'); }
+  get headers() { return this.container.getByRole('columnheader'); }
+
+  async sortBy(column: string) {
+    await this.container.getByRole('columnheader', { name: column }).click();
+  }
+
+  async getRowCount() {
+    return this.rows.count() - 1; // Minus header
+  }
+}
+```
+
+## Fixture Architecture
+
+```typescript
+// tests/e2e/fixtures/index.ts
+import { test as base } from '@playwright/test';
+import { LoginPage } from '../pages/login.page';
+import { DashboardPage } from '../pages/dashboard.page';
+
+// Worker fixture — shared across tests in same worker
+// Test fixture — fresh per test
+type TestFixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<TestFixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+  authenticatedPage: async ({ page }, use) => {
+    // Setup: login
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('Password123!');
+    await page.getByRole('button', { name: 'Sign in' }).click();
+    await page.waitForURL('/dashboard');
+    // Use the authenticated page
+    await use(page);
+    // Teardown: cleanup (automatic)
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+### Auto-fixtures (run before every test)
+
+```typescript
+export const test = base.extend<{ autoCleanup: void }>({
+  autoCleanup: [async ({ page }, use) => {
+    await use(); // Test runs here
+    // Cleanup after test
+    await page.evaluate(() => localStorage.clear());
+  }, { auto: true }],
+});
+```
+
+## Assertion Reference
+
+```typescript
+// Element assertions
+await expect(locator).toBeVisible();
+await expect(locator).toBeHidden();
+await expect(locator).toBeEnabled();
+await expect(locator).toBeDisabled();
+await expect(locator).toBeChecked();
+await expect(locator).toBeFocused();
+await expect(locator).toHaveText('Expected text');
+await expect(locator).toContainText('partial');
+await expect(locator).toHaveValue('expected');
+await expect(locator).toHaveAttribute('href', '/path');
+await expect(locator).toHaveClass(/active/);
+await expect(locator).toHaveCount(5);
+await expect(locator).toHaveCSS('color', 'rgb(0, 0, 0)');
+
+// Page assertions
+await expect(page).toHaveURL('/expected-path');
+await expect(page).toHaveURL(/\/users\/\d+/);
+await expect(page).toHaveTitle('Page Title');
+
+// Negation
+await expect(locator).not.toBeVisible();
+
+// Soft assertions (don't stop test)
+await expect.soft(locator).toHaveText('text');
+
+// Custom timeout
+await expect(locator).toBeVisible({ timeout: 10000 });
+
+// API response assertions
+const response = await page.request.get('/api/users');
+expect(response.ok()).toBeTruthy();
+expect(response.status()).toBe(200);
+```
+
+## Multi-Viewport Testing
+
+```typescript
+// tests/e2e/responsive/dashboard.spec.ts
+import { test, expect } from '../fixtures';
+
+const viewports = [
+  { name: 'Mobile', width: 375, height: 812 },
+  { name: 'Tablet', width: 768, height: 1024 },
+  { name: 'Desktop', width: 1280, height: 720 },
+];
+
+for (const viewport of viewports) {
+  test.describe(`Dashboard - ${viewport.name}`, () => {
+    test.use({ viewport: { width: viewport.width, height: viewport.height } });
+
+    test('navigation is appropriate', async ({ page }) => {
+      await page.goto('/dashboard');
+
+      if (viewport.width < 768) {
+        // Mobile: bottom nav or hamburger
+        await expect(page.getByTestId('mobile-nav')).toBeVisible();
+        await expect(page.getByTestId('sidebar')).toBeHidden();
+      } else if (viewport.width < 1280) {
+        // Tablet: collapsible sidebar
+        await expect(page.getByTestId('sidebar')).toBeVisible();
+      } else {
+        // Desktop: full sidebar
+        await expect(page.getByTestId('sidebar')).toBeVisible();
+        await expect(page.getByTestId('search-bar')).toBeVisible();
+      }
+    });
+  });
+}
+```
+
+## Selector Best Practices
+
+| Priority | Selector | Example |
+|----------|----------|---------|
+| 1 | `getByRole` | `getByRole('button', { name: 'Submit' })` |
+| 2 | `getByLabel` | `getByLabel('Email')` |
+| 3 | `getByText` | `getByText('Welcome')` |
+| 4 | `getByTestId` | `getByTestId('user-avatar')` |
+| 5 | CSS (last resort) | `locator('.card:first-child')` |
+
+## Critical Rules
+
+1. **Page Object Model** — Every page/component gets a POM class extending BasePage
+2. **Fixtures over beforeEach** — Use `test.extend` for reusable setup/teardown
+3. **3 viewports** — Test Mobile (375), Tablet (768), Desktop (1280+) separately
+4. **Role-based selectors** — Prefer `getByRole`/`getByLabel` over CSS selectors
+5. **No hardcoded waits** — Use `waitForURL`, `waitForLoadState`, `expect` auto-retry
+6. **Trace on failure** — `trace: 'on-first-retry'` for debugging
+7. **Parallel by default** — `fullyParallel: true` unless tests share state
+8. **Worker fixtures** — Share expensive setup (auth, DB) across tests in same worker

package/template/.claude/skills/skill-creator/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: skill-creator
+description: "ALWAYS invoke when creating, editing, or optimizing Claude Code skills. Do NOT create skills without following the interview, draft, test, iterate loop first."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Skill Creator
+
+Meta-skill for creating new skills and iteratively improving them.
+
+> Source: `anthropics/skills` (adapted for project conventions)
+
+## Creation Loop
+
+1. **Capture Intent** — What should this skill do? When should it trigger? What's the output format?
+2. **Interview & Research** — Ask about edge cases, input/output formats, dependencies
+3. **Write the SKILL.md** — See anatomy below
+4. **Test** — Create 2-3 realistic test prompts, run with/without skill
+5. **Evaluate** — Review outputs qualitatively and quantitatively
+6. **Iterate** — Improve based on feedback, repeat until satisfied
+7. **Optimize Description** — Generate trigger eval queries for better activation
+
+## Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description, allowed-tools)
+│   └── Markdown instructions
+└── Optional resources
+    ├── scripts/     — Executable code
+    ├── references/  — Docs loaded on demand
+    └── assets/      — Templates, icons
+```
+
+### Frontmatter (Project Convention)
+
+```yaml
+---
+name: my-skill
+description: "ALWAYS invoke when [trigger]. Do NOT [negation]."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+```
+
+**Description rules:**
+- Start with `ALWAYS invoke when...`
+- Include `Do NOT...` negation
+- Keep under 200 chars
+- Be slightly "pushy" — Claude tends to undertrigger skills
+
+### Writing Guide
+
+- Keep SKILL.md under 500 lines
+- Use imperative form in instructions
+- Explain **why** things are important (not heavy-handed MUSTs)
+- Include examples for complex patterns
+- Reference files from SKILL.md with guidance on when to read
+- For large reference files (>300 lines), include a table of contents
+
+## Testing Skills
+
+```json
+// evals/evals.json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's task prompt",
+      "expected_output": "Description of expected result",
+      "files": []
+    }
+  ]
+}
+```
+
+For each test case, run Claude with and without the skill, then compare outputs.
+
+## Description Optimization
+
+1. **Generate 20 eval queries** — Mix of should-trigger (8-10) and should-not-trigger (8-10)
+2. **Make queries realistic** — Include file paths, personal context, casual speech, typos
+3. **Focus negatives on near-misses** — Adjacent domains, ambiguous phrasing
+4. **Test triggering** — Run queries against the description
+5. **Iterate** — Improve description based on trigger accuracy
+
+## Validation
+
+After creating/modifying a skill:
+
+```bash
+bash .claude/scripts/validate-skills.sh
+```
+
+Checks: frontmatter, imperative pattern, negation, char budget < 16,000.
+
+## Critical Rules
+
+1. **Interview first** — Understand the user's intent before writing
+2. **Imperative description** — `ALWAYS invoke when... Do NOT...`
+3. **Under 200 chars** — Description must be concise
+4. **Test with real prompts** — Not abstract requests
+5. **Generalize from feedback** — Don't overfit to test cases
+6. **Explain the why** — Theory of mind over rigid MUSTs
+7. **Bundle repeated work** — If every test run writes the same helper, put it in scripts/

package/template/.claude/skills/test-infrastructure/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: test-infrastructure
+description: "ALWAYS invoke when setting up test configs, creating data factories, or writing integration tests. Do NOT configure Vitest or create test data without checking patterns first."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Test Infrastructure
+
+Patterns for Vitest configuration, data factories, integration tests, and test cleanup.
+
+## Data Factory Pattern
+
+```typescript
+// tests/factories/user.factory.ts
+import { ObjectId } from 'mongodb';
+
+let counter = 0;
+
+function nextId(): string {
+  return new ObjectId().toHexString();
+}
+
+function nextEmail(): string {
+  counter++;
+  return `user-${counter}-${Date.now()}@test.com`;
+}
+
+export function createUser(overrides: Partial<IUser> = {}): IUser {
+  return {
+    _id: nextId(),
+    email: nextEmail(),
+    name: `Test User ${counter}`,
+    password: 'HashedPassword123!',
+    role: 'user',
+    isActive: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+export function createUsers(count: number, overrides: Partial<IUser> = {}): IUser[] {
+  return Array.from({ length: count }, () => createUser(overrides));
+}
+```
+
+### Random Data Helpers (no faker dependency)
+
+```typescript
+// tests/helpers/random.ts
+export const random = {
+  string: (length = 10) =>
+    Math.random().toString(36).substring(2, 2 + length),
+  number: (min: number, max: number) =>
+    Math.floor(Math.random() * (max - min + 1)) + min,
+  boolean: () => Math.random() > 0.5,
+  date: (daysBack = 30) => {
+    const d = new Date();
+    d.setDate(d.getDate() - Math.floor(Math.random() * daysBack));
+    return d;
+  },
+  pick: <T>(arr: T[]): T => arr[Math.floor(Math.random() * arr.length)]!,
+  email: () => `test-${Date.now()}-${Math.random().toString(36).slice(2, 6)}@test.com`,
+};
+```
+
+## Vitest Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts', 'tests/**/*.spec.ts'],
+    exclude: ['tests/e2e/**'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+      include: ['src/**/*.ts', 'server/**/*.ts'],
+      exclude: ['**/*.d.ts', '**/*.test.ts'],
+      thresholds: { statements: 80, branches: 75, functions: 80, lines: 80 },
+    },
+    setupFiles: ['tests/setup.ts'],
+    testTimeout: 10000,
+  },
+  resolve: {
+    alias: {
+      '$types': path.resolve(__dirname, './types'),
+      '@common': path.resolve(__dirname, './common/index.ts'),
+      '@db': path.resolve(__dirname, './common/db'),
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});
+```
+
+### Setup File
+
+```typescript
+// tests/setup.ts
+import { beforeAll, afterAll, afterEach } from 'vitest';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import mongoose from 'mongoose';
+
+let mongod: MongoMemoryServer;
+
+beforeAll(async () => {
+  mongod = await MongoMemoryServer.create();
+  await mongoose.connect(mongod.getUri());
+});
+
+afterEach(async () => {
+  const collections = mongoose.connection.collections;
+  for (const key in collections) {
+    await collections[key]!.deleteMany({});
+  }
+});
+
+afterAll(async () => {
+  await mongoose.disconnect();
+  await mongod.stop();
+});
+```
+
+## Integration Test Patterns
+
+```typescript
+// tests/integration/user.service.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UserService } from '@/services/user.service';
+import { UserModel } from '@/models/user.model';
+import { createUser } from '../factories/user.factory';
+
+describe('UserService', () => {
+  let service: UserService;
+
+  beforeEach(() => {
+    service = new UserService();
+  });
+
+  describe('createUser', () => {
+    it('should create a user with hashed password', async () => {
+      const input = { email: 'new@test.com', password: 'Pass123!', name: 'Test' };
+      const user = await service.create(input);
+
+      expect(user.email).toBe('new@test.com');
+      expect(user.password).not.toBe('Pass123!'); // Hashed
+    });
+
+    it('should reject duplicate emails', async () => {
+      const existing = createUser({ email: 'dup@test.com' });
+      await UserModel.create(existing);
+
+      await expect(
+        service.create({ email: 'dup@test.com', password: 'Pass123!', name: 'Test' })
+      ).rejects.toThrow(/duplicate/i);
+    });
+  });
+
+  describe('findById', () => {
+    it('should return null for non-existent user', async () => {
+      const result = await service.findById('507f1f77bcf86cd799439011');
+      expect(result).toBeNull();
+    });
+  });
+});
+```
+
+### API Route Testing
+
+```typescript
+// tests/integration/api/users.test.ts
+import { describe, it, expect } from 'vitest';
+import { createUser } from '../../factories/user.factory';
+
+describe('POST /api/users', () => {
+  it('should validate required fields', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/users',
+      payload: {},
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json().errors).toBeDefined();
+  });
+
+  it('should create user with valid data', async () => {
+    const input = { email: 'new@test.com', password: 'Pass123!', name: 'Test' };
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/users',
+      payload: input,
+    });
+
+    expect(response.statusCode).toBe(201);
+    expect(response.json().email).toBe('new@test.com');
+    expect(response.json().password).toBeUndefined(); // Not exposed
+  });
+});
+```
+
+## Cleanup Strategy
+
+```typescript
+// Delete children before parents to avoid foreign key issues
+async function cleanupDatabase() {
+  const collections = ['orders', 'products', 'users', 'sessions'];
+  for (const name of collections) {
+    const collection = mongoose.connection.collection(name);
+    if (collection) await collection.deleteMany({});
+  }
+}
+
+// Per-test isolation with transaction rollback
+async function withTransaction<T>(fn: () => Promise<T>): Promise<T> {
+  const session = await mongoose.startSession();
+  session.startTransaction();
+  try {
+    const result = await fn();
+    await session.abortTransaction(); // Always rollback in tests
+    return result;
+  } finally {
+    session.endSession();
+  }
+}
+```
+
+## Critical Rules
+
+1. **ObjectId + counter** — Use real ObjectIds, counter for unique emails
+2. **No faker** — Use simple random helpers (no heavy dependency)
+3. **MongoMemoryServer** — In-memory DB for integration tests
+4. **Path aliases** — Mirror project aliases in vitest.config.ts
+5. **Children before parents** — Delete dependent collections first
+6. **afterEach cleanup** — Clear all collections between tests
+7. **Factory pattern** — `createUser(overrides)` for flexible test data
+8. **Separate E2E** — Exclude `tests/e2e/` from Vitest (Playwright handles those)