.cursorrules

# CleanStack - TDD/BDD/DDD/Clean Architecture Rules

## Quick Reference

```bash
pnpm dev           # Dev server
pnpm test          # Run tests
pnpm check:all     # Full validation (lint, types, tests, duplication)
pnpm type-check    # TypeScript only
```

## Core Principles

### TDD Workflow (Mandatory)

```
1. Write Tests FIRST (Red)
   - Domain tests: src/domain/{name}/__tests__/
   - UseCase tests: src/application/use-cases/{domain}/__tests__/

2. Run tests → FAIL (expected)

3. Write Implementation (Green)
   - Minimal code to pass tests

4. Run tests → PASS

5. Refactor if needed
```

### BDD Test Format (Given/When/Then)

```typescript
describe("Context", () => {
  describe("Given [precondition]", () => {
    it("When [action], Then [expected outcome]", () => {
      // Given - Setup
      const input = { ... };

      // When - Action
      const result = await sut.execute(input);

      // Then - Assertions
      expect(result.isSuccess).toBe(true);
    });
  });
});
```

### Clean Architecture Layers

```
Domain (Core)     → Entities, VOs, Aggregates, Events (NO external deps)
    ↑
Application       → Use Cases, Ports (interfaces)
    ↑
Adapters          → Controllers, Repositories, Guards
    ↑
Infrastructure    → DB, DI config, External Services
```

**Rule:** Dependencies flow INWARD only. Never import outer layer in inner.

### DDD Patterns

| Pattern | Use For | Return Type |
|---------|---------|-------------|
| `Result<T>` | Operations that can fail | `Result.ok(value)` / `Result.fail(error)` |
| `Option<T>` | Nullable values | `Option.some(v)` / `Option.none()` |
| `ValueObject<T>` | Validated business values | Via `create()` → `Result<VO>` |
| `Aggregate<T>` | Entity with events | Via `create()` / `reconstitute()` |

## Code Templates

### Value Object

```typescript
import { Result, ValueObject } from "@packages/ddd-kit";
import { z } from "zod";

const schema = z.string().min(1).max(100);

export class {Name} extends ValueObject<string> {
  protected validate(value: string): Result<string> {
    const result = schema.safeParse(value);
    if (!result.success) {
      return Result.fail(result.error.errors[0].message);
    }
    return Result.ok(result.data);
  }
}
```

### Aggregate

```typescript
import { Aggregate, UUID } from "@packages/ddd-kit";
import { {Name}CreatedEvent } from "./events/{name}-created.event";

interface I{Name}Props {
  // properties
  createdAt: Date;
  updatedAt?: Date;
}

export class {Name} extends Aggregate<I{Name}Props> {
  get id(): {Name}Id {
    return {Name}Id.create(this._id);
  }

  static create(props: Omit<I{Name}Props, "createdAt">, id?: UUID): {Name} {
    const entity = new {Name}({ ...props, createdAt: new Date() }, id ?? new UUID());
    if (!id) entity.addEvent(new {Name}CreatedEvent(entity));
    return entity;
  }

  static reconstitute(props: I{Name}Props, id: UUID): {Name} {
    return new {Name}(props, id);
  }
}
```

### Use Case

```typescript
import { match, Result, type UseCase } from "@packages/ddd-kit";
import type { IEventDispatcher } from "@/application/ports/event-dispatcher.port";

export class {Name}UseCase implements UseCase<Input, Output> {
  constructor(
    private readonly repo: IRepository,
    private readonly eventDispatcher: IEventDispatcher,
  ) {}

  async execute(input: Input): Promise<Result<Output>> {
    // 1. Validate input - create VOs
    // 2. Check business rules
    // 3. Create/update domain entity
    // 4. Persist FIRST
    // 5. Dispatch events AFTER save
    // 6. Return DTO
  }
}
```

### Domain Event

```typescript
import { BaseDomainEvent } from "@packages/ddd-kit";

interface Payload {
  aggregateId: string;
}

export class {Name}Event extends BaseDomainEvent<Payload> {
  readonly eventType = "{aggregate}.{action}";

  constructor(aggregate: Aggregate) {
    super();
    this.aggregateId = aggregate.id.value;
    this.payload = { aggregateId: aggregate.id.value };
  }
}
```

## Testing Rules

### Test Location
- Domain: `src/domain/{name}/__tests__/`
- UseCases: `src/application/use-cases/{domain}/__tests__/`
- Adapters: `src/__TESTS__/adapters/`

### Test Categories
1. **Happy Path** - Valid input produces expected output
2. **Validation Errors** - Invalid input fails gracefully
3. **Business Rules** - Domain rules enforced
4. **Error Handling** - Repository/service failures handled
5. **Event Emission** - Events dispatched AFTER save

### Mocking Rules
- Mock at PORT/INTERFACE level only (Clean Architecture)
- Use `vi.fn()` for all mock functions
- Return `Result.ok/fail` for Result-returning methods
- Return `Option.some/none` for Option-returning methods

```typescript
const mockRepo: IRepository = {
  create: vi.fn(),
  findById: vi.fn(),
  // ...all BaseRepository methods
};
```

## Anti-Patterns (NEVER DO)

| Don't | Do Instead |
|-------|------------|
| `throw new Error()` in domain | `return Result.fail("message")` |
| `return null` | `return Option.none()` |
| Import React in domain | Keep domain pure |
| Logic in controllers | Logic in use cases |
| Tests AFTER code | Tests FIRST (TDD) |
| `any` types | `unknown` or proper types |
| Index barrels | Direct imports |

## Key Rules

1. **Domain = zero external imports** (only ddd-kit + Zod)
2. **Never throw** in Domain/Application → use `Result<T>`
3. **Never null** → use `Option<T>`
4. **VOs use Zod** for validation
5. **Events dispatch AFTER save** succeeds
6. **All deps injected** via DI
7. **No index.ts barrels** → import directly
8. **Only `get id()` getter** → use `entity.get('propName')` for others

## File Structure

```
apps/nextjs/src/
├── domain/{aggregate}/
│   ├── {aggregate}.aggregate.ts
│   ├── {aggregate}-id.ts
│   ├── __tests__/              # Domain tests
│   ├── value-objects/
│   └── events/
├── application/
│   ├── use-cases/{domain}/
│   │   ├── {name}.use-case.ts
│   │   └── __tests__/          # UseCase tests
│   ├── ports/                  # Interfaces
│   └── dto/
└── adapters/
    ├── repositories/
    ├── mappers/
    ├── guards/
    └── services/
```

## Before Coding Checklist

- [ ] Read CLAUDE.md for full patterns
- [ ] Write failing tests FIRST
- [ ] Use Result<T> for fallible operations
- [ ] Use Option<T> for nullable values
- [ ] Keep domain layer pure
- [ ] Dispatch events AFTER successful save