feat: wire HuntingController/HuntingModule and enrich current-location with monster pool

Registers HuntingModule (POST /api/hunts) into the DI graph alongside its
new entities, and adds possibleMonsters (enabled LocationMonster pool,
weight-descending, empty when hunting is disabled) to
WorldService.getCurrentLocation. Also updates the pre-existing
DB-less app.e2e-spec.ts to override HuntingModule the same way the other
feature modules already are, since it now needs a real DataSource.

apps/api/src/app.module.ts

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { CharactersModule } from './characters/characters.module';
 import { DatabaseModule } from './database/database.module';
 import { HealthModule } from './health/health.module';
+import { HuntingModule } from './hunting/hunting.module';
 import { TravelModule } from './travel/travel.module';
 import { WorldModule } from './world/world.module';
 
@@ -12,6 +13,7 @@ import { WorldModule } from './world/world.module';
     CharactersModule,
     TravelModule,
     WorldModule,
+    HuntingModule,
   ],
 })
 export class AppModule {}

apps/api/src/hunting/hunting.controller.spec.ts

@@ -0,0 +1,50 @@
+import { INestApplication } from '@nestjs/common';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { configureApplication } from '../app.config';
+import { DEMO_CHARACTER_ID } from '../demo/demo-character.constants';
+import { HuntingController } from './hunting.controller';
+import { HuntingService } from './hunting.service';
+
+describe('HuntingController', () => {
+  let app: INestApplication<App>;
+  const startHunt = jest.fn();
+
+  beforeEach(async () => {
+    startHunt.mockReset();
+    const module = await Test.createTestingModule({
+      controllers: [HuntingController],
+      providers: [
+        {
+          provide: HuntingService,
+          useValue: { startHunt },
+        },
+      ],
+    }).compile();
+
+    app = module.createNestApplication<App>();
+    configureApplication(app);
+    await app.init();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('delegates to huntingService.startHunt with the demo character id and returns its result', async () => {
+    const huntResult = {
+      id: 'hunt-1',
+      location: { id: 'loc-1', key: 'burned-road', name: 'Verbrannte Strasse' },
+      encounters: [],
+    };
+    startHunt.mockResolvedValue(huntResult);
+
+    const response = await request(app.getHttpServer())
+      .post('/api/hunts')
+      .expect(201);
+
+    expect(startHunt).toHaveBeenCalledWith(DEMO_CHARACTER_ID);
+    expect(response.body).toEqual(huntResult);
+  });
+});

apps/api/src/hunting/hunting.controller.ts

@@ -0,0 +1,13 @@
+import { Controller, Post } from '@nestjs/common';
+import { DEMO_CHARACTER_ID } from '../demo/demo-character.constants';
+import { HuntResultDto, HuntingService } from './hunting.service';
+
+@Controller('hunts')
+export class HuntingController {
+  constructor(private readonly huntingService: HuntingService) {}
+
+  @Post()
+  startHunt(): Promise<HuntResultDto> {
+    return this.huntingService.startHunt(DEMO_CHARACTER_ID);
+  }
+}

apps/api/src/hunting/hunting.module.ts

@@ -0,0 +1,30 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { Character } from '../characters/entities/character.entity';
+import { LocationMonster } from '../monsters/entities/location-monster.entity';
+import { MonsterDefinition } from '../monsters/entities/monster-definition.entity';
+import { TravelModule } from '../travel/travel.module';
+import { Hunt } from './entities/hunt.entity';
+import { HuntEncounter } from './entities/hunt-encounter.entity';
+import { HuntingController } from './hunting.controller';
+import { HuntingService } from './hunting.service';
+import { RANDOM_SOURCE, systemRandomSource } from './random-source';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      MonsterDefinition,
+      LocationMonster,
+      Hunt,
+      HuntEncounter,
+      Character,
+    ]),
+    TravelModule,
+  ],
+  controllers: [HuntingController],
+  providers: [
+    HuntingService,
+    { provide: RANDOM_SOURCE, useValue: systemRandomSource },
+  ],
+})
+export class HuntingModule {}

apps/api/src/world/world.module.ts

@@ -1,6 +1,8 @@
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { Character } from '../characters/entities/character.entity';
+import { LocationMonster } from '../monsters/entities/location-monster.entity';
+import { MonsterDefinition } from '../monsters/entities/monster-definition.entity';
 import { TravelModule } from '../travel/travel.module';
 import { LocationConnection } from './entities/location-connection.entity';
 import { WorldController } from './world.controller';
@@ -8,7 +10,12 @@ import { WorldService } from './world.service';
 
 @Module({
   imports: [
-    TypeOrmModule.forFeature([Character, LocationConnection]),
+    TypeOrmModule.forFeature([
+      Character,
+      LocationConnection,
+      LocationMonster,
+      MonsterDefinition,
+    ]),
     TravelModule,
   ],
   controllers: [WorldController],

apps/api/src/world/world.service.spec.ts

@@ -5,6 +5,7 @@ import {
   BURNED_ROAD_ID,
   SOUTH_GATE_ID,
 } from '../database/seeds/vertical-slice.constants';
+import { LocationMonster } from '../monsters/entities/location-monster.entity';
 import { TravelService } from '../travel/travel.service';
 import { LocationConnection } from './entities/location-connection.entity';
 import { LocationDefinition } from './entities/location-definition.entity';
@@ -102,7 +103,16 @@ describe('WorldService', () => {
     const connections = {
       find: findConnections,
     } as unknown as Repository<LocationConnection>;
-    const service = new WorldService(travelService, characters, connections);
+    const findLocationMonsters = jest.fn();
+    const locationMonsters = {
+      find: findLocationMonsters,
+    } as unknown as Repository<LocationMonster>;
+    const service = new WorldService(
+      travelService,
+      characters,
+      connections,
+      locationMonsters,
+    );
 
     const result = await service.getCurrentLocation(CHARACTER_ID);
 
@@ -131,6 +141,7 @@ describe('WorldService', () => {
           danger: 'LOW',
         },
       ],
+      possibleMonsters: [],
     });
     expect(findCharacter).toHaveBeenCalledWith({
       where: { id: CHARACTER_ID },
@@ -140,6 +151,51 @@ describe('WorldService', () => {
       where: { fromLocationId: SOUTH_GATE_ID, enabled: true },
       relations: { toLocation: true },
     });
+    expect(findLocationMonsters).not.toHaveBeenCalled();
+  });
+
+  it('returns the enabled monster pool by name, ordered by weight descending, when hunting is enabled', async () => {
+    const location = burnedRoad();
+    const travelService = {
+      completeTravelIfDue: jest.fn().mockResolvedValue({ status: 'IDLE' }),
+    } as unknown as TravelService;
+    const characters = {
+      findOne: jest.fn().mockResolvedValue({
+        id: CHARACTER_ID,
+        currentLocationId: BURNED_ROAD_ID,
+        currentLocation: location,
+      }),
+    } as unknown as Repository<Character>;
+    const connections = {
+      find: jest.fn().mockResolvedValue([]),
+    } as unknown as Repository<LocationConnection>;
+    const findLocationMonsters = jest
+      .fn()
+      .mockResolvedValue([
+        { monster: { name: 'Aschenratte' } },
+        { monster: { name: 'Stra\u00dfenr\u00e4uber' } },
+      ]);
+    const locationMonsters = {
+      find: findLocationMonsters,
+    } as unknown as Repository<LocationMonster>;
+    const service = new WorldService(
+      travelService,
+      characters,
+      connections,
+      locationMonsters,
+    );
+
+    const result = await service.getCurrentLocation(CHARACTER_ID);
+
+    expect(result.possibleMonsters).toEqual([
+      'Aschenratte',
+      'Stra\u00dfenr\u00e4uber',
+    ]);
+    expect(findLocationMonsters).toHaveBeenCalledWith({
+      where: { locationId: BURNED_ROAD_ID, enabled: true },
+      relations: { monster: true },
+      order: { weight: 'DESC' },
+    });
   });
 
   it('reports a missing character after travel completion', async () => {
@@ -157,11 +213,21 @@ describe('WorldService', () => {
     const connections = {
       find: findConnections,
     } as unknown as Repository<LocationConnection>;
-    const service = new WorldService(travelService, characters, connections);
+    const findLocationMonsters = jest.fn();
+    const locationMonsters = {
+      find: findLocationMonsters,
+    } as unknown as Repository<LocationMonster>;
+    const service = new WorldService(
+      travelService,
+      characters,
+      connections,
+      locationMonsters,
+    );
 
     await expect(
       service.getCurrentLocation(CHARACTER_ID),
     ).rejects.toBeInstanceOf(NotFoundException);
     expect(findConnections).not.toHaveBeenCalled();
+    expect(findLocationMonsters).not.toHaveBeenCalled();
   });
 });

apps/api/src/world/world.service.ts

@@ -2,6 +2,7 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 import { Character } from '../characters/entities/character.entity';
+import { LocationMonster } from '../monsters/entities/location-monster.entity';
 import { TravelService } from '../travel/travel.service';
 import { LocationConnection } from './entities/location-connection.entity';
 
@@ -30,6 +31,7 @@ export interface CurrentLocationResponse {
   huntingEnabled: boolean;
   artworkPath: string;
   connections: CurrentLocationConnection[];
+  possibleMonsters: string[];
 }
 
 @Injectable()
@@ -40,6 +42,8 @@ export class WorldService {
     private readonly characters: Repository<Character>,
     @InjectRepository(LocationConnection)
     private readonly connections: Repository<LocationConnection>,
+    @InjectRepository(LocationMonster)
+    private readonly locationMonsters: Repository<LocationMonster>,
   ) {}
 
   async getCurrentLocation(
@@ -61,6 +65,10 @@ export class WorldService {
     });
     const location = character.currentLocation;
 
+    const possibleMonsters = location.huntingEnabled
+      ? await this.getPossibleMonsters(location.id)
+      : [];
+
     return {
       id: location.id,
       key: location.key,
@@ -84,9 +92,19 @@ export class WorldService {
           travelDurationSeconds: connection.travelDurationSeconds,
           danger: this.toDangerRating(connection.ambushChance),
         })),
+      possibleMonsters,
     };
   }
 
+  private async getPossibleMonsters(locationId: string): Promise<string[]> {
+    const pool = await this.locationMonsters.find({
+      where: { locationId, enabled: true },
+      relations: { monster: true },
+      order: { weight: 'DESC' },
+    });
+    return pool.map((entry) => entry.monster.name);
+  }
+
   private toDangerRating(ambushChance: string): 'LOW' | 'HIGH' {
     return Number(ambushChance) <= 0.05 ? 'LOW' : 'HIGH';
   }