codecruise 0.1.0

package/config/agents/stack/shared-ts/rules/zod.md

@@ -0,0 +1,427 @@
+# Zod Schema Patterns
+
+Runtime validation with type inference.
+
+---
+
+## Schema Basics
+
+### ZOD-001: Define base schemas
+
+```typescript
+import { z } from 'zod';
+
+// Primitives
+const stringSchema = z.string();
+const numberSchema = z.number();
+const booleanSchema = z.boolean();
+const dateSchema = z.date();
+
+// With constraints
+const emailSchema = z.string().email();
+const positiveSchema = z.number().positive();
+const nonEmptySchema = z.string().min(1);
+
+// Optional and nullable
+const optionalSchema = z.string().optional(); // string | undefined
+const nullableSchema = z.string().nullable(); // string | null
+const nullishSchema = z.string().nullish(); // string | null | undefined
+```
+
+### ZOD-002: Use coercion for form data
+
+```typescript
+// Coerce strings to proper types
+const formSchema = z.object({
+  age: z.coerce.number().int().min(0).max(150),
+  birthDate: z.coerce.date(),
+  isActive: z.coerce.boolean(),
+  price: z.coerce.number().positive(),
+});
+
+// Handles: "25" -> 25, "true" -> true, "2024-01-01" -> Date
+const data = formSchema.parse({
+  age: '25',
+  birthDate: '2024-01-01',
+  isActive: 'true',
+  price: '99.99',
+});
+```
+
+---
+
+## Object Schemas
+
+### ZOD-003: Compose object schemas
+
+```typescript
+// Base schema
+const baseEntitySchema = z.object({
+  id: z.string().cuid(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+
+// Extended schema
+const userSchema = baseEntitySchema.extend({
+  email: z.string().email().toLowerCase(),
+  name: z.string().min(2).max(100),
+  role: z.enum(['USER', 'ADMIN']),
+});
+
+// Merge schemas
+const fullUserSchema = userSchema.merge(
+  z.object({
+    profile: z.object({
+      bio: z.string().optional(),
+      avatar: z.string().url().optional(),
+    }),
+  })
+);
+```
+
+### ZOD-004: Create input/output schemas
+
+```typescript
+// Full entity (from database)
+const userSchema = z.object({
+  id: z.string().cuid(),
+  email: z.string().email(),
+  password: z.string(),
+  name: z.string(),
+  createdAt: z.date(),
+});
+
+// Create input (no id, no timestamps)
+const createUserSchema = userSchema.omit({
+  id: true,
+  createdAt: true,
+});
+
+// Update input (all optional except id)
+const updateUserSchema = userSchema
+  .partial()
+  .required({ id: true });
+
+// Public output (no password)
+const publicUserSchema = userSchema.omit({
+  password: true,
+});
+
+// Types
+type User = z.infer<typeof userSchema>;
+type CreateUser = z.infer<typeof createUserSchema>;
+type UpdateUser = z.infer<typeof updateUserSchema>;
+type PublicUser = z.infer<typeof publicUserSchema>;
+```
+
+---
+
+## Transforms
+
+### ZOD-005: Normalize input with transforms
+
+```typescript
+const userInputSchema = z.object({
+  // Normalize email
+  email: z
+    .string()
+    .email()
+    .toLowerCase()
+    .trim(),
+
+  // Normalize whitespace in name
+  name: z
+    .string()
+    .trim()
+    .transform(s => s.replace(/\s+/g, ' ')),
+
+  // Extract digits from phone
+  phone: z
+    .string()
+    .optional()
+    .transform(s => s?.replace(/\D/g, '')),
+
+  // Parse tags from comma-separated string
+  tags: z
+    .string()
+    .transform(s => s.split(',').map(t => t.trim()).filter(Boolean)),
+});
+```
+
+### ZOD-006: Transform to domain types
+
+```typescript
+// Transform to branded types
+const userIdSchema = z.string().cuid().transform(id => id as UserId);
+
+// Transform to class instance
+const dateRangeSchema = z
+  .object({
+    start: z.coerce.date(),
+    end: z.coerce.date(),
+  })
+  .transform(({ start, end }) => new DateRange(start, end));
+
+// Transform with validation
+const positiveIntSchema = z
+  .number()
+  .transform((n, ctx) => {
+    const int = Math.floor(n);
+    if (int <= 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Must be positive integer',
+      });
+      return z.NEVER;
+    }
+    return int;
+  });
+```
+
+---
+
+## Refinements
+
+### ZOD-007: Add custom validation
+
+```typescript
+// Single field refinement
+const passwordSchema = z
+  .string()
+  .min(8)
+  .refine(
+    (password) => /[A-Z]/.test(password),
+    { message: 'Must contain uppercase letter' }
+  )
+  .refine(
+    (password) => /[0-9]/.test(password),
+    { message: 'Must contain number' }
+  );
+
+// Object-level refinement
+const dateRangeSchema = z
+  .object({
+    startDate: z.coerce.date(),
+    endDate: z.coerce.date(),
+  })
+  .refine(
+    (data) => data.endDate > data.startDate,
+    {
+      message: 'End date must be after start date',
+      path: ['endDate'],
+    }
+  );
+```
+
+### ZOD-008: Use superRefine for complex validation
+
+```typescript
+const registrationSchema = z
+  .object({
+    password: z.string().min(8),
+    confirmPassword: z.string(),
+    email: z.string().email(),
+  })
+  .superRefine((data, ctx) => {
+    if (data.password !== data.confirmPassword) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Passwords must match',
+        path: ['confirmPassword'],
+      });
+    }
+
+    if (data.password.toLowerCase().includes(data.email.split('@')[0])) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Password cannot contain email',
+        path: ['password'],
+      });
+    }
+  });
+```
+
+---
+
+## Unions & Discriminated Unions
+
+### ZOD-009: Use discriminated unions
+
+```typescript
+// Event types
+const eventSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('USER_CREATED'),
+    userId: z.string(),
+    email: z.string().email(),
+  }),
+  z.object({
+    type: z.literal('USER_UPDATED'),
+    userId: z.string(),
+    changes: z.record(z.unknown()),
+  }),
+  z.object({
+    type: z.literal('USER_DELETED'),
+    userId: z.string(),
+    deletedAt: z.date(),
+  }),
+]);
+
+type Event = z.infer<typeof eventSchema>;
+// Properly typed discriminated union
+```
+
+### ZOD-010: Handle multiple valid shapes
+
+```typescript
+// Config that can be string or object
+const configSchema = z.union([
+  z.string(), // Simple string value
+  z.object({
+    value: z.string(),
+    options: z.object({
+      required: z.boolean().default(false),
+      maxLength: z.number().optional(),
+    }),
+  }),
+]);
+
+// Normalize to object
+const normalizedConfigSchema = configSchema.transform((config) => {
+  if (typeof config === 'string') {
+    return { value: config, options: { required: false } };
+  }
+  return config;
+});
+```
+
+---
+
+## Error Handling
+
+### ZOD-011: Format errors for API responses
+
+```typescript
+import { ZodError, ZodIssue } from 'zod';
+
+interface FieldError {
+  field: string;
+  message: string;
+  code: string;
+}
+
+function formatZodError(error: ZodError): FieldError[] {
+  return error.issues.map((issue: ZodIssue) => ({
+    field: issue.path.join('.'),
+    message: issue.message,
+    code: issue.code,
+  }));
+}
+
+// Usage
+try {
+  userSchema.parse(input);
+} catch (e) {
+  if (e instanceof ZodError) {
+    return {
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Invalid input',
+        details: formatZodError(e),
+      },
+    };
+  }
+  throw e;
+}
+```
+
+### ZOD-012: Use safeParse for non-throwing validation
+
+```typescript
+// safeParse returns Result-like object
+const result = userSchema.safeParse(input);
+
+if (result.success) {
+  const user = result.data; // Typed as User
+  await saveUser(user);
+} else {
+  const errors = formatZodError(result.error);
+  return { error: { code: 'VALIDATION_ERROR', details: errors } };
+}
+
+// Async validation
+const asyncResult = await asyncSchema.safeParseAsync(input);
+```
+
+---
+
+## Integration Patterns
+
+### ZOD-013: Convert to JSON Schema (Fastify/OpenAPI)
+
+```typescript
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const userSchema = z.object({
+  id: z.string().cuid(),
+  email: z.string().email(),
+  name: z.string().min(2),
+});
+
+// For Fastify route schema
+const routeSchema = {
+  body: zodToJsonSchema(createUserSchema),
+  response: {
+    200: zodToJsonSchema(userSchema),
+    400: zodToJsonSchema(errorSchema),
+  },
+};
+```
+
+### ZOD-014: Environment validation
+
+```typescript
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+// Validate at startup
+export const env = envSchema.parse(process.env);
+
+// Type-safe access
+console.log(env.PORT); // number
+console.log(env.NODE_ENV); // 'development' | 'test' | 'production'
+```
+
+### ZOD-015: Form validation (React Hook Form)
+
+```typescript
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+
+const formSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'At least 8 characters'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+function LoginForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+    resolver: zodResolver(formSchema),
+  });
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+    </form>
+  );
+}
+```

package/config/agents/tester.md

@@ -0,0 +1,79 @@
+---
+name: tester
+description: Write and run tests. Use for testing features or validating implementations.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: haiku
+---
+
+# Tester Agent
+
+Write integration and e2e tests. Verify implementations.
+
+## Test Types
+
+| Type | Purpose | Speed | When |
+|------|---------|-------|------|
+| Unit | Individual functions | Fast | Business logic |
+| Integration | Component interactions, APIs, DB | Medium | API endpoints, services |
+| E2E | Complete user flows | Slow | Critical paths only |
+
+## Principles
+
+1. **Deterministic** — Same input → same result (no timing deps)
+2. **Independent** — No order dependency between tests
+3. **Focused** — One behavior per test
+4. **Readable** — Test name describes scenario
+
+## Test Structure
+
+```
+describe: Feature or component
+  describe: Scenario or condition
+    it: should + expected behavior
+```
+
+**Pattern**: Arrange → Act → Assert
+
+## Coverage Priority
+
+1. **Happy path** — Main success scenario
+2. **Error cases** — Validation, network, auth failures
+3. **Edge cases** — Empty, null, boundary values
+4. **Security cases** — Auth bypass, injection
+
+## Mocking Decisions
+
+| Dependency | Mock? | Why |
+|------------|-------|-----|
+| External APIs | Yes | Unreliable, slow, costs |
+| Time/Date | Yes | Determinism |
+| Database | Integration: No, Unit: Yes | Reality vs speed |
+| File system | Usually Yes | Speed |
+| Internal modules | No | Test real behavior |
+
+## Anti-Patterns to Avoid
+
+- ❌ Testing implementation details (test behavior, not internals)
+- ❌ Flaky tests (timing-dependent, order-dependent)
+- ❌ Over-mocking (testing mocks, not code)
+- ❌ Duplicate coverage
+- ❌ Testing third-party code
+
+## Quality Checklist
+
+- [ ] Tests cover acceptance criteria
+- [ ] Tests are meaningful (not just coverage)
+- [ ] Edge cases considered
+- [ ] Error cases tested
+- [ ] No flaky tests
+- [ ] Factories for test data (not inline objects)
+- [ ] Mocks only for external deps
+
+## Output
+
+```
+✓ Tests: {path}
+  ✓ should {case 1}
+  ✓ should {case 2}
+Coverage: X% (if available)
+```