agent-skill-kit 3.9.135

package/.agent/skills/nodejs-pro/rules/testing-strategy.md

@@ -0,0 +1,266 @@
+---
+name: testing-strategy
+description: Node.js testing with Vitest and node:test — unit/integration/E2E patterns, mocking, and CI integration
+title: "Test the right things: critical paths, edge cases, error handling. Don't test framework code."
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: testing, strategy
+---
+
+# Testing Strategy
+
+> Test the right things: critical paths, edge cases, error handling. **Don't test framework code.**
+
+---
+
+## Test Tool Selection
+
+| Tool | Best For | Speed | Setup |
+|------|---------|-------|-------|
+| **Vitest** | Vite/React projects, modern DX | Fastest | Zero-config with Vite |
+| **node:test** | Zero-dependency, built-in | Fast | No install needed |
+| **Jest** | Legacy projects | Slower | Extra config for ESM |
+
+**Default recommendation:** Vitest for app projects. `node:test` for libraries / zero-dep projects.
+
+---
+
+## What to Test (Priorities)
+
+| Priority | Test | Why |
+|----------|------|-----|
+| 1 | **Critical paths** | Auth, payments, core business logic |
+| 2 | **Edge cases** | Empty inputs, boundaries, nulls |
+| 3 | **Error handling** | What happens when things fail? |
+| 4 | **Integration points** | API endpoints, database queries |
+| ❌ | Framework code | Express/Fastify already tested |
+| ❌ | Trivial getters/setters | No logic to test |
+| ❌ | Third-party libraries | They have their own tests |
+
+---
+
+## Unit Test Examples
+
+### Vitest
+
+```typescript
+// user.service.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { UserService } from './user.service'
+
+describe('UserService', () => {
+  let service: UserService
+  let mockRepo: { findById: ReturnType<typeof vi.fn>; create: ReturnType<typeof vi.fn> }
+
+  beforeEach(() => {
+    mockRepo = {
+      findById: vi.fn(),
+      create: vi.fn(),
+    }
+    service = new UserService(mockRepo as any)
+  })
+
+  it('returns user when found', async () => {
+    const user = { id: '1', name: 'Alice', email: 'alice@test.com' }
+    mockRepo.findById.mockResolvedValue(user)
+
+    const result = await service.getUser('1')
+
+    expect(result).toEqual(user)
+    expect(mockRepo.findById).toHaveBeenCalledWith('1')
+  })
+
+  it('throws NotFoundError when user missing', async () => {
+    mockRepo.findById.mockResolvedValue(null)
+
+    await expect(service.getUser('999'))
+      .rejects.toThrow('User not found')
+  })
+})
+```
+
+### node:test (Zero Dependencies)
+
+```typescript
+// user.service.test.ts
+import { describe, it, mock, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { UserService } from './user.service.js'
+
+describe('UserService', () => {
+  let service: UserService
+  let mockRepo: { findById: Function; create: Function }
+
+  beforeEach(() => {
+    mockRepo = {
+      findById: mock.fn(() => Promise.resolve(null)),
+      create: mock.fn(() => Promise.resolve({ id: '1' })),
+    }
+    service = new UserService(mockRepo as any)
+  })
+
+  it('returns user when found', async () => {
+    const user = { id: '1', name: 'Alice' }
+    mockRepo.findById = mock.fn(() => Promise.resolve(user))
+    service = new UserService(mockRepo as any)
+
+    const result = await service.getUser('1')
+    assert.deepEqual(result, user)
+  })
+
+  it('throws when user not found', async () => {
+    await assert.rejects(
+      () => service.getUser('999'),
+      { message: 'User not found' }
+    )
+  })
+})
+```
+
+---
+
+## Integration Test (API Endpoint)
+
+```typescript
+// Fastify + Vitest
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { buildApp } from '../app'
+
+describe('POST /users', () => {
+  let app: FastifyInstance
+
+  beforeAll(async () => {
+    app = await buildApp({ testing: true })
+  })
+
+  afterAll(async () => {
+    await app.close()
+  })
+
+  it('creates user with valid data', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/users',
+      payload: { email: 'test@test.com', name: 'Test User' },
+    })
+
+    expect(response.statusCode).toBe(201)
+    expect(response.json()).toMatchObject({
+      email: 'test@test.com',
+      name: 'Test User',
+    })
+  })
+
+  it('returns 422 for invalid email', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/users',
+      payload: { email: 'not-an-email', name: 'Test' },
+    })
+
+    expect(response.statusCode).toBe(422)
+    expect(response.json().error).toBe('VALIDATION_ERROR')
+  })
+})
+```
+
+---
+
+## Mocking Patterns
+
+```typescript
+// Mock external services (Vitest)
+vi.mock('./external-api', () => ({
+  fetchFromAPI: vi.fn().mockResolvedValue({ data: 'mocked' }),
+}))
+
+// Mock environment variables
+vi.stubEnv('DATABASE_URL', 'postgres://test:test@localhost/test')
+
+// Mock timers
+vi.useFakeTimers()
+vi.advanceTimersByTime(5000)
+vi.useRealTimers()
+
+// Spy on function calls
+const spy = vi.spyOn(logger, 'error')
+await performAction()
+expect(spy).toHaveBeenCalledWith(expect.objectContaining({ error: true }))
+```
+
+---
+
+## Test Structure
+
+```
+src/
+├── services/
+│   ├── user.service.ts
+│   └── user.service.test.ts      # Co-located unit tests
+├── controllers/
+│   ├── user.controller.ts
+│   └── user.controller.test.ts
+└── __tests__/                     # Integration tests
+    ├── api/
+    │   └── users.test.ts
+    └── setup.ts                   # Test database, fixtures
+```
+
+---
+
+## Running Tests
+
+```bash
+# Vitest
+npx vitest              # Watch mode
+npx vitest run           # Single run (CI)
+npx vitest run --coverage  # With coverage
+
+# node:test
+node --test src/**/*.test.ts       # Run all tests
+node --test --watch                # Watch mode (Node.js 22+)
+node --test --experimental-test-coverage  # Coverage
+```
+
+---
+
+## CI Integration
+
+```yaml
+# GitHub Actions
+- name: Test
+  run: npx vitest run --coverage --reporter=junit
+  env:
+    DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
+
+- name: Upload Coverage
+  uses: codecov/codecov-action@v4
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Test implementation details | Test behavior and outcomes |
+| Mock everything | Mock only external boundaries |
+| Test framework internals | Test your business logic |
+| Skip error path tests | Test both happy and error paths |
+| Use `any` for mock types | Type mocks properly |
+| Rely on test order | Each test is independent |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [architecture-patterns.md](architecture-patterns.md) | Layer testing strategy |
+| [error-handling.md](error-handling.md) | Testing error paths |
+| [validation-security.md](validation-security.md) | Testing validation schemas |
+| [async-patterns.md](async-patterns.md) | Testing async code |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/nodejs-pro/rules/validation-security.md

@@ -0,0 +1,205 @@
+---
+name: validation-security
+description: Input validation with Zod, security middleware, rate limiting, CORS, secrets management, and security checklist
+title: "Validation & Security"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: validation, security
+---
+
+# Validation & Security
+
+> Validate at boundary. Trust nothing. **Every input is hostile until proven otherwise.**
+
+---
+
+## Validation Library Selection
+
+| Library | Best For | Bundle | TypeScript |
+|---------|----------|--------|-----------|
+| **Zod** | TypeScript-first, type inference | 13KB | Native inference |
+| **Valibot** | Smallest bundle (tree-shakeable) | 1KB | Native inference |
+| **ArkType** | Performance-critical validation | 25KB | Native inference |
+| **Yup** | React forms (existing usage) | 40KB | @types needed |
+
+**Default recommendation:** Zod (best DX + ecosystem). Valibot if bundle size critical.
+
+---
+
+## Zod Validation Examples
+
+### Request Schema
+
+```typescript
+import { z } from 'zod'
+
+// Define schema
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  age: z.number().int().min(13).max(150).optional(),
+  role: z.enum(['user', 'admin']).default('user'),
+})
+
+// Infer TypeScript type from schema
+type CreateUser = z.infer<typeof CreateUserSchema>
+// { email: string; name: string; age?: number; role: 'user' | 'admin' }
+```
+
+### Fastify Validation Middleware
+
+```typescript
+import { ZodSchema, ZodError } from 'zod'
+
+function validate<T>(schema: ZodSchema<T>) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      request.body = schema.parse(request.body)
+    } catch (err) {
+      if (err instanceof ZodError) {
+        reply.code(422).send({
+          error: 'VALIDATION_ERROR',
+          details: err.errors.map(e => ({
+            path: e.path.join('.'),
+            message: e.message,
+          }))
+        })
+      }
+    }
+  }
+}
+
+app.post('/users', { preHandler: validate(CreateUserSchema) }, async (request) => {
+  return userService.create(request.body) // Already validated + typed
+})
+```
+
+### Hono Validation Middleware
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+
+app.post('/users',
+  zValidator('json', CreateUserSchema),
+  async (c) => {
+    const data = c.req.valid('json') // Typed as CreateUser
+    return c.json(await userService.create(data), 201)
+  }
+)
+```
+
+### Environment Validation (startup)
+
+```typescript
+// env.ts — Validate ALL env vars at startup, fail fast
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  REDIS_URL: z.string().url().optional(),
+})
+
+export const env = EnvSchema.parse(process.env)
+// If any env var is missing/invalid → crash immediately at startup
+```
+
+---
+
+## Security Middleware Stack
+
+### Fastify
+
+```typescript
+import fastifyHelmet from '@fastify/helmet'
+import fastifyRateLimit from '@fastify/rate-limit'
+import fastifyCors from '@fastify/cors'
+
+// Security headers
+await app.register(fastifyHelmet)
+
+// Rate limiting
+await app.register(fastifyRateLimit, {
+  max: 100,            // 100 requests
+  timeWindow: '1 minute',
+  keyGenerator: (req) => req.ip,
+})
+
+// CORS
+await app.register(fastifyCors, {
+  origin: env.CORS_ORIGINS?.split(',') || false,
+  credentials: true,
+})
+```
+
+### Hono
+
+```typescript
+import { cors } from 'hono/cors'
+import { secureHeaders } from 'hono/secure-headers'
+import { rateLimiter } from 'hono-rate-limiter'
+
+app.use('*', secureHeaders())
+app.use('*', cors({ origin: env.CORS_ORIGINS?.split(',') || [] }))
+app.use('*', rateLimiter({ windowMs: 60_000, limit: 100 }))
+```
+
+---
+
+## Security Checklist
+
+| Category | Check | Implementation |
+|----------|-------|---------------|
+| **Input** | All inputs validated | Zod/Valibot at boundary |
+| **SQL** | Parameterized queries | Drizzle/Prisma (never string concat) |
+| **Auth** | Password hashing | `argon2` (preferred) or `bcrypt` |
+| **Auth** | JWT verification | Verify signature + expiry + issuer |
+| **Network** | Rate limiting | `@fastify/rate-limit` or equivalent |
+| **Headers** | Security headers | Helmet.js or `hono/secure-headers` |
+| **Transport** | HTTPS everywhere | TLS termination at load balancer |
+| **CORS** | Properly configured | Explicit origins, not `*` in production |
+| **Secrets** | Environment variables | Never hardcode, validate at startup |
+| **Deps** | Dependency audit | `npm audit` in CI, Renovate/Dependabot |
+| **Code** | No `eval()`/`Function()` | Never in production |
+| **Logging** | No secrets in logs | Redact tokens, passwords, keys |
+
+---
+
+## Common Vulnerabilities
+
+| Vulnerability | Prevention |
+|--------------|-----------|
+| **SQL Injection** | Use ORM (Drizzle/Prisma). Never `db.query(\`SELECT * WHERE id = ${id}\`)` |
+| **XSS** | React auto-escapes. Never `dangerouslySetInnerHTML` with user input |
+| **CSRF** | SameSite cookies + CSRF token for non-API forms |
+| **Path Traversal** | Validate file paths: `path.resolve()` + check prefix |
+| **Mass Assignment** | Validate with schema, pick only allowed fields |
+| **Prototype Pollution** | Use `Object.create(null)` for lookup maps, validate JSON |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Validate inside business logic | Validate at route boundary |
+| `CORS: origin: '*'` in production | Explicit allowed origins |
+| Store JWT secret in code | Environment variable, validate at startup |
+| `bcrypt` with low rounds | `argon2` or `bcrypt` with rounds ≥ 12 |
+| Trust `Content-Type` header | Parse and validate body explicitly |
+| Log full request bodies | Redact sensitive fields |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [error-handling.md](error-handling.md) | Validation error responses |
+| [framework-selection.md](framework-selection.md) | Framework-specific validation |
+| [architecture-patterns.md](architecture-patterns.md) | Where validation sits in layers |
+| [testing-strategy.md](testing-strategy.md) | Testing validation schemas |
+
+---
+
+⚡ PikaKit v3.9.134