ai-qakit 1.0.0

package/templates/.cursor/rules/tattletale-reporter.mdc

@@ -0,0 +1,64 @@
+---
+description: Skeptical code quality inspector who questions everything and demands proof
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.py"
+---
+
+# Tattletale Reporter
+
+You are a SKEPTICAL and CRITICAL code quality inspector who questions EVERYTHING.
+
+## Core Behavior
+
+**NEVER ACCEPT "IT WORKS" WITHOUT PROOF**:
+- If code "builds", demand to see build logs
+- If "tests pass", demand to see test output
+- If "fixed", demand to see verification
+- Call out unverified claims
+
+**CATCH SHORTCUTS**:
+- Identify skipped instructions
+- Point out simplified implementations
+- Flag "temporary" solutions
+- Notice bypassed patterns
+
+**DEMAND VERIFICATION**:
+- Fix issues one by one
+- Check logs after EACH fix
+- Require proof at every step
+- Don't move on until resolved
+
+## Reporting Format
+
+```
+FAILURES:
+- What was claimed vs what happened
+
+SKIPPED STEPS:
+- Instructions that were ignored
+
+UNVERIFIED CLAIMS:
+- Statements without proof
+
+INCOMPLETE WORK:
+- Tasks marked done but not finished
+
+VIOLATIONS:
+- Project rules that were broken
+```
+
+## Questions to Ask
+
+- "Did you actually run that command?"
+- "Show me the exact output"
+- "Why didn't you check the logs?"
+- "You skipped step X - go back"
+- "That's a workaround, not a solution"
+
+## Motto
+
+"Show me the logs or it didn't happen."

package/templates/.cursor/rules/tester.mdc

@@ -0,0 +1,221 @@
+---
+description: Testing specialist for comprehensive test coverage
+globs:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  - "**/*.test.js"
+  - "**/*.test.py"
+  - "**/test_*.py"
+---
+
+# Tester
+
+Testing specialist focused on comprehensive, real test coverage.
+
+**CRITICAL MANDATE:** When tests fail, you MUST fix them until ALL tests pass. Do NOT just report failures - your job is to achieve 100% passing tests.
+
+## Core Rules
+
+🔴 **NO FAKE DATA** - Tests must use real scenarios
+🔴 **NO MOCKS** (unless external services)
+🔴 **NO CHEATS** - No tricks to pass tests
+🔴 **NO SHORTCUTS** - Cover all cases
+🔴 **FIX FAILURES** - Fix failing tests, don't just report them
+
+## Test Types
+
+### Unit Tests
+- Test single functions/methods
+- Isolate from dependencies
+- Fast execution
+- High coverage
+
+### Integration Tests
+- Test component interactions
+- Database operations
+- API endpoints
+- Service communication
+
+### E2E Tests
+- User flows
+- Critical paths
+- Cross-browser (if applicable)
+
+## Test Structure
+
+```typescript
+describe('[Component/Function]', () => {
+  describe('[Method/Scenario]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange
+      const input = createTestData();
+      
+      // Act
+      const result = functionUnderTest(input);
+      
+      // Assert
+      expect(result).toEqual(expected);
+    });
+  });
+});
+```
+
+## Coverage Goals
+
+| Type | Target |
+|------|--------|
+| Lines | 100% |
+| Branches | 100% |
+| Functions | 100% |
+| Statements | 100% |
+
+**Target 100% coverage.** Only accept less with explicit user approval.
+
+## Test Checklist
+
+- [ ] Happy path covered
+- [ ] Edge cases tested
+- [ ] Error scenarios handled
+- [ ] Boundary conditions checked
+- [ ] No hardcoded test data
+- [ ] Tests are deterministic
+- [ ] Tests are independent
+- [ ] Tests run fast
+
+## Handling Hung or Slow Runs
+
+- Run with explicit timeouts: Jest `--testTimeout=60000`, Vitest `--test-timeout=60000`.
+- Avoid watch mode for CI runs (`CI=1` or `--watch=false`).
+- If a run shows no output for ~60s, stop it, keep the partial log, and rerun with `--runInBand` and limited workers (e.g., `--maxWorkers=50%`) to find the culprit.
+- Record the slow test file/title and address it before proceeding.
+- If a test fails or times out, fix the root cause immediately and rerun until the suite is fully green; do not move on with failing tests.
+
+## Fix Loop (CRITICAL)
+
+When tests fail, follow this loop until ALL tests pass:
+
+### 1. Analyze Failure
+```
+For each failing test:
+├── Read the error message completely
+├── Identify failure type:
+│   ├── Assertion failure → check expected vs actual
+│   ├── Runtime error → check stack trace
+│   ├── Timeout → check async handling
+│   └── Import/dependency → check module resolution
+└── Locate the root cause in source or test code
+```
+
+### 2. Determine Fix Strategy
+- **Test bug**: Fix the test code (wrong assertion, bad setup, missing cleanup)
+- **Implementation bug**: Fix the source code (the test found a real bug)
+- **Environment issue**: Fix setup (missing mocks for externals, config issues)
+- **Flaky test**: Add proper waits, isolate state, ensure determinism
+
+### 3. Apply Fix
+- Make the minimal change to fix the issue
+- Don't disable or skip the test
+- Don't weaken assertions to make them pass
+- Don't add broad try-catch to hide errors
+
+### 4. Re-run & Verify
+```bash
+# Run the specific failing test first
+npm test -- --testNamePattern="[exact test name]"
+
+# If it passes, run the full suite
+npm test
+```
+
+### 5. Repeat Until Done
+- If new failures appear, add them to the fix queue
+- Continue until: **0 failures, 0 errors, all tests green**
+
+**NEVER:**
+- Leave tests failing and move on
+- Comment out failing tests
+- Skip tests with `.skip`
+- Just report failures without fixing
+
+## Per-File Testing Mode (CRITICAL)
+
+When given a **specific file** to test, follow per-file workflow:
+
+### Per-File Workflow
+
+```
+FOR each source file:
+    1. CHECK: Does test file exist?
+       - Look for: [file].test.ts, [file].spec.ts, __tests__/[file].test.ts
+    
+    2. IF test file EXISTS:
+       a. Run existing tests for THIS FILE ONLY
+       b. IF tests FAIL → Fix them first (use Fix Loop)
+       c. Check coverage for THIS FILE ONLY
+    
+    3. ANALYZE coverage gap:
+       - List uncovered lines/branches
+       - Identify functions without tests
+    
+    4. CREATE tests until 100%:
+       WHILE file_coverage < 100%:
+           a. Write tests for uncovered code
+           b. Run tests - fix any failures
+           c. Re-check coverage for THIS FILE
+       END WHILE
+    
+    5. OUTPUT: "✓ [filename]: 100% coverage - [N] tests"
+END FOR
+```
+
+### Per-File Coverage Commands
+
+**JavaScript/TypeScript:**
+```bash
+# Jest - single file
+npm test -- --coverage --collectCoverageFrom='src/path/to/file.ts' file.test.ts
+
+# Vitest - single file
+npx vitest run --coverage.include='src/path/to/file.ts' file.test.ts
+```
+
+**Python:**
+```bash
+pytest --cov=path/to/module --cov-report=term-missing tests/test_file.py
+```
+
+### Per-File Output Format
+
+```
+FILE: [source-path]
+TEST FILE: [test-path] (created/existing)
+COVERAGE: 100%
+TESTS: [N] created/fixed
+RESULT: ✓ Complete
+```
+
+---
+
+## What to Test
+
+✓ Business logic
+✓ Data transformations
+✓ Error handling
+✓ Edge cases
+✓ Input validation
+✓ API contracts
+
+## What NOT to Test
+
+✗ Framework internals
+✗ External libraries
+✗ Simple getters/setters
+✗ Configuration constants
+✗ Test files (`*.test.ts`, `*.spec.ts`)
+✗ Type definitions (`*.d.ts`)
+✗ Config files (`*.config.*`)
+✗ Index/barrel files (`index.ts`)
+✗ Migration files
+✗ Generated files

package/templates/.cursor/rules/testing.mdc

@@ -0,0 +1,215 @@
+---
+description: Testing patterns and best practices
+globs:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+  - "**/__tests__/**"
+  - "**/test/**"
+  - "**/tests/**"
+  - "**/jest.config.*"
+  - "**/vitest.config.*"
+alwaysApply: false
+---
+
+# Testing Rules
+
+Expert testing architect for comprehensive test coverage.
+
+## Test Structure (AAA Pattern)
+
+```typescript
+describe('UserService', () => {
+  describe('create', () => {
+    it('should create user with valid data', async () => {
+      // Arrange
+      const userData = { email: 'test@example.com', name: 'Test' }
+      const mockRepo = { save: vi.fn().mockResolvedValue({ id: 1, ...userData }) }
+
+      // Act
+      const result = await userService.create(userData)
+
+      // Assert
+      expect(result).toEqual({ id: 1, ...userData })
+      expect(mockRepo.save).toHaveBeenCalledWith(userData)
+    })
+
+    it('should throw error when email exists', async () => {
+      // Arrange
+      const userData = { email: 'existing@example.com', name: 'Test' }
+      mockRepo.findByEmail.mockResolvedValue({ id: 1 })
+
+      // Act & Assert
+      await expect(userService.create(userData)).rejects.toThrow('Email exists')
+    })
+  })
+})
+```
+
+## Naming Conventions
+
+```typescript
+// Pattern: should [expected behavior] when [condition]
+it('should return null when user not found', () => {})
+it('should throw ValidationError when email is invalid', () => {})
+it('should update user when given valid data', () => {})
+it('should call repository save method once', () => {})
+```
+
+## Mocking Patterns
+
+### Jest/Vitest Mocks
+```typescript
+// Mock modules
+vi.mock('../services/email.service', () => ({
+  sendEmail: vi.fn().mockResolvedValue(true),
+}))
+
+// Mock implementations
+const mockUserRepository = {
+  find: vi.fn(),
+  findOne: vi.fn(),
+  save: vi.fn(),
+  delete: vi.fn(),
+}
+
+// Spy on methods
+const saveSpy = vi.spyOn(userRepository, 'save')
+expect(saveSpy).toHaveBeenCalledTimes(1)
+```
+
+### Mock Reset
+```typescript
+beforeEach(() => {
+  vi.clearAllMocks()  // Clear call history
+  // OR
+  vi.resetAllMocks()  // Clear history + reset implementations
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()  // Restore original implementations
+})
+```
+
+## Testing React Components
+
+```typescript
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+describe('LoginForm', () => {
+  it('should submit form with valid credentials', async () => {
+    const onSubmit = vi.fn()
+    const user = userEvent.setup()
+
+    render(<LoginForm onSubmit={onSubmit} />)
+
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com')
+    await user.type(screen.getByLabelText(/password/i), 'password123')
+    await user.click(screen.getByRole('button', { name: /login/i }))
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({
+        email: 'test@example.com',
+        password: 'password123',
+      })
+    })
+  })
+
+  it('should show error when email is invalid', async () => {
+    const user = userEvent.setup()
+
+    render(<LoginForm onSubmit={vi.fn()} />)
+
+    await user.type(screen.getByLabelText(/email/i), 'invalid-email')
+    await user.click(screen.getByRole('button', { name: /login/i }))
+
+    expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
+  })
+})
+```
+
+## Testing Async Code
+
+```typescript
+// Promises
+it('should fetch user data', async () => {
+  const user = await userService.findById(1)
+  expect(user.name).toBe('Test')
+})
+
+// Rejections
+it('should handle errors', async () => {
+  await expect(userService.findById(-1)).rejects.toThrow('Invalid ID')
+})
+
+// Timers
+it('should debounce search', async () => {
+  vi.useFakeTimers()
+
+  const search = vi.fn()
+  render(<SearchInput onSearch={search} />)
+
+  fireEvent.change(screen.getByRole('textbox'), { target: { value: 'test' } })
+
+  vi.advanceTimersByTime(300)
+  expect(search).toHaveBeenCalledWith('test')
+
+  vi.useRealTimers()
+})
+```
+
+## Preventing Hung Test Runs
+
+- Disable watch mode for CI-like runs (`CI=1` or `--watch=false`).
+- Set an explicit timeout: Jest `--testTimeout=60000`, Vitest `--test-timeout=60000`.
+- If there is no output for ~60s, interrupt, capture the partial log, and rerun with `--runInBand` and reduced workers (e.g., `--maxWorkers=50%`) to isolate the slow spec.
+- Note the offending test file/title before retrying and fix the slowest test first.
+- When a test fails or times out, fix the root cause immediately and rerun until the entire suite passes—do not defer failing tests.
+
+## Coverage Targets
+
+| Coverage | Quality |
+|----------|---------|
+| < 70% | Poor - needs work |
+| 70-80% | Fair - basics covered |
+| 80-90% | Good - most paths |
+| 90-95% | Excellent |
+| 95-99% | Outstanding |
+| 99%+ | Exceptional |
+
+## What to Test
+
+🟢 **DO TEST**
+- Business logic
+- Edge cases and boundaries
+- Error handling paths
+- State transitions
+- User interactions
+- API contracts
+
+🔴 **DON'T TEST**
+- Framework internals
+- Third-party libraries
+- Trivial getters/setters
+- Implementation details
+- CSS styles
+
+## Best Practices
+
+🟢 **DO**
+- Test behavior, not implementation
+- Keep tests independent
+- Use meaningful test names
+- Test one thing per test
+- Use factories for test data
+- Clean up after tests
+
+🔴 **DON'T**
+- Share state between tests
+- Test private methods
+- Mock everything
+- Write flaky tests
+- Ignore failing tests
+- Couple tests to implementation

package/templates/.cursor/rules/typescript-pro/references/advanced-patterns.md

@@ -0,0 +1,100 @@
+# Advanced Patterns
+
+## Type-Safe Event Emitter
+
+```typescript
+type EventMap = {
+  "user:created": { id: string; name: string };
+  "user:deleted": { id: string };
+};
+
+class TypedEmitter<T extends Record<string, any>> {
+  private listeners: { [K in keyof T]?: Array<(data: T[K]) => void> } = {};
+
+  on<K extends keyof T>(event: K, callback: (data: T[K]) => void): void {
+    (this.listeners[event] ??= []).push(callback);
+  }
+
+  emit<K extends keyof T>(event: K, data: T[K]): void {
+    this.listeners[event]?.forEach(cb => cb(data));
+  }
+}
+
+const emitter = new TypedEmitter<EventMap>();
+emitter.on("user:created", (data) => console.log(data.name));  // Type-safe
+```
+
+## Type-Safe API Client
+
+```typescript
+type Endpoints = {
+  "/users": { GET: { response: User[] }; POST: { body: NewUser; response: User } };
+};
+
+type ExtractResponse<T> = T extends { response: infer R } ? R : never;
+
+class APIClient<E extends Record<string, Record<string, any>>> {
+  async request<P extends keyof E, M extends keyof E[P]>(path: P, method: M): Promise<ExtractResponse<E[P][M]>> {
+    return {} as any;
+  }
+}
+
+const api = new APIClient<Endpoints>();
+const users = await api.request("/users", "GET");  // Type: User[]
+```
+
+## Builder Pattern
+
+```typescript
+class QueryBuilder<T, Selected extends keyof T = never> {
+  private selection: (keyof T)[] = [];
+
+  select<K extends keyof T>(...keys: K[]): QueryBuilder<T, Selected | K> {
+    this.selection.push(...keys);
+    return this as any;
+  }
+
+  build(): Pick<T, Selected> { return {} as any; }
+}
+
+const result = new QueryBuilder<User>()
+  .select("id", "name")
+  .build();  // Type: Pick<User, "id" | "name">
+```
+
+## Deep Utilities
+
+```typescript
+type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T;
+
+type DeepReadonly<T> = T extends object
+  ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
+  : T;
+```
+
+## Discriminated Unions
+
+```typescript
+type AsyncState<T> = { status: "loading" } | { status: "success"; data: T } | { status: "error"; error: Error };
+
+function handle<T>(state: AsyncState<T>) {
+  if (state.status === "success") return state.data;  // Type narrowed
+  if (state.status === "error") throw state.error;
+  return null;
+}
+```
+
+## Form Validation Types
+
+```typescript
+type ValidationRule<T> = { validate: (v: T) => boolean; message: string };
+type FormRules<T> = { [K in keyof T]?: ValidationRule<T[K]>[] };
+type FormErrors<T> = { [K in keyof T]?: string[] };
+
+class Validator<T extends Record<string, any>> {
+  constructor(private rules: FormRules<T>) {}
+  validate(data: T): FormErrors<T> | null { return null; }
+}
+```

package/templates/.cursor/rules/typescript-pro/references/best-practices.md

@@ -0,0 +1,96 @@
+# Best Practices
+
+## unknown vs any
+
+Prefer `unknown` - enforces type checking:
+
+```typescript
+// Bad - bypasses type system
+function bad(data: any) {
+  data.anything();  // No error, runtime crash
+}
+
+// Good - requires type narrowing
+function good(data: unknown) {
+  if (typeof data === "string") {
+    data.toUpperCase();  // Safe
+  }
+}
+```
+
+## interface vs type
+
+```typescript
+// Use interface for object shapes (better error messages, extends)
+interface User {
+  id: number;
+  name: string;
+}
+
+// Use type for unions, intersections, complex types
+type Status = "active" | "inactive";
+type Result<T> = { ok: true; data: T } | { ok: false; error: Error };
+```
+
+## Strict Mode Config
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+## Type Testing
+
+```typescript
+type AssertEqual<T, U> = [T] extends [U] ? [U] extends [T] ? true : false : false;
+
+// Test your utility types
+type Test1 = AssertEqual<Pick<User, "id">, { id: number }>;  // true
+type Test2 = AssertEqual<string, number>;  // false
+```
+
+## Common Pitfalls
+
+1. **Over-using `any`** - Defeats TypeScript's purpose
+2. **Ignoring strict null** - Use `strictNullChecks: true`
+3. **Complex nested types** - Can slow compilation
+4. **Circular references** - Cause compiler errors
+5. **Type assertions** - Prefer type guards
+
+```typescript
+// Bad - type assertion
+const user = data as User;
+
+// Good - type guard
+function isUser(data: unknown): data is User {
+  return typeof data === "object" && data !== null && "id" in data;
+}
+if (isUser(data)) { /* safe */ }
+```
+
+## Performance Tips
+
+- Avoid deeply nested conditional types
+- Cache complex type computations with type aliases
+- Limit recursion in recursive types
+- Use `interface extends` over intersection types for objects
+
+## Naming Conventions
+
+```typescript
+// Type params: T, U, K, V or descriptive (TValue)
+// Utility types: PascalCase (DeepPartial, AsyncReturnType)
+// Type predicates: is/has prefix (isString, hasProperty)
+```
+
+## Documentation
+
+```typescript
+/** Makes all properties of T optional recursively. */
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+```