feat: implements defender

package.json

@@ -6,19 +6,23 @@
         "build": "node esbuild.config.mjs",
         "push": "npm run build && ts-node publish.ts",
         "format": "prettier --check --ignore-path .gitignore .",
-        "format:fix": "prettier --write --ignore-path .gitignore ."
+        "format:fix": "prettier --write --ignore-path .gitignore .",
+        "test": "jest"
     },
     "dependencies": {
         "@trivago/prettier-plugin-sort-imports": "^6.0.2",
         "@types/screeps": "^3.3.8",
         "dotenv": "^17.4.2",
         "esbuild": "^0.28.0",
+        "jest": "^30.3.0",
         "prettier": "^3.8.3",
+        "ts-jest": "^29.4.9",
         "ts-node": "^10.9.2",
         "typescript": "^6.0.3",
         "zod": "^4.3.6"
     },
     "devDependencies": {
+        "@types/jest": "^30.0.0",
         "@types/node": "^25.6.0"
     },
     "prettier": {
@@ -36,5 +40,24 @@
             "jsx",
             "decorators-legacy"
         ]
+    },
+    "jest": {
+        "testEnvironment": "node",
+        "transform": {
+            "^.+\\.(ts|tsx)$": ["ts-jest", { "tsconfig": "tsconfig.test.json" }]
+        },
+        "moduleNameMapper": {
+            "\\.(png|jpg|jpeg|gif|webp|svg|ico)$": "<rootDir>/tests/setup/__mocks__/fileMock.js",
+            "^@/(.*)$": "<rootDir>/src/$1",
+            "^~/(.*)$": "<rootDir>/$1"
+        },
+        "moduleFileExtensions": [
+            "ts",
+            "tsx",
+            "js"
+        ],
+        "testMatch": [
+            "**/?(*.)+(spec|test).[jt]s?(x)"
+        ]
     }
 }

src/CreepRunner.ts

@@ -1,5 +1,5 @@
-import { CreepRole, CreepRoles } from 'types/creeps';
+import { CreepRole, CreepRoles } from '@/types/creeps';
-import { getRoomCreeps } from 'utils/funcs/getRoomCreeps';
+import { getRoomCreeps } from '@/utils/funcs/getRoomCreeps';
 
 class CreepRunner {
     public static run(room: Room, state: GameState): GameState {

src/RequisitionsManager.ts

@@ -1,8 +1,8 @@
-import { CreepRequisition, CreepRole, CreepRoles } from 'types/creeps';
+import { CreepRequisition, CreepRole, CreepRoles } from '@/types/creeps';
-import { DEFAULT_GAME_CONFIG } from 'types/gameConfig';
+import { DEFAULT_GAME_CONFIG } from '@/types/gameConfig';
-import { get_role_cost } from 'utils/funcs/getRoleCost';
+import { get_role_cost } from '@/utils/funcs/getRoleCost';
-import { getRoomCreeps } from 'utils/funcs/getRoomCreeps';
+import { getRoomCreeps } from '@/utils/funcs/getRoomCreeps';
-import { sortCreepRolesByPriority } from 'utils/funcs/sortCreepRolesByPriority';
+import { sortCreepRolesByPriority } from '@/utils/funcs/sortCreepRolesByPriority';
 
 class RequisitionsManager {
     public static validateState(room: Room, state: GameState): GameState {

src/RoomInspector.ts

@@ -1,33 +1,27 @@
-import { checkPositionWalkable } from 'utils/funcs/checkPosition';
+import { checkPositionWalkable } from '@/utils/funcs/checkPosition';
 import {
     createSourcePositionMatrix,
     forEachMatrixSpot,
     getPositionWithDelta,
     PositionSpotStatus,
     setSpotStatus,
-} from 'utils/positions';
+} from '@/utils/positions';
 
 class RoomInspector {
     public static inspectState(room: Room, state: GameState): GameState {
-        if (!this.stateWasInitialized(state)) {
+        if (!state.sourcesStates) {
-            state = this.initializeState(room, state);
+            this.initializeState(room, state);
         }
         return state;
     }
 
-    private static stateWasInitialized(state: GameState): boolean {
+    private static initializeState(room: Room, state: GameState): void {
-        return !!state.sourcesStates;
-    }
-
-    private static initializeState(room: Room, state: GameState): GameState {
         state.sourcesStates = {};
         state.maxHarvesters = 0;
 
         for (const source of room.find(FIND_SOURCES)) {
             this.configureSourceState(source, state);
         }
-
-        return state;
     }
 
     private static configureSourceState(

src/RoomRunner.ts

@@ -1,6 +1,6 @@
-import CreepRunner from 'CreepRunner';
+import CreepRunner from '@/CreepRunner';
-import RequisitionsManager from 'RequisitionsManager';
+import RequisitionsManager from '@/RequisitionsManager';
-import RoomInspector from 'RoomInspector';
+import RoomInspector from '@/RoomInspector';
 
 class RoomRunner {
     public static run(room: Room, state: GameState): GameState {

src/global.d.ts

@@ -0,0 +1,48 @@
+import { CreepDestination } from '@/types/creeps';
+import { PositionMatrix } from '@/utils/positions';
+
+declare global {
+    /*
+    Example types, expand on these or remove them and add your own.
+    Note: Values, properties defined here do no fully *exist* by this type definiton alone.
+          You must also give them an implemention if you would like to use them. (ex. actually setting a `role` property in a Creeps memory)
+
+    Types added in this `global` block are in an ambient, global context. This is needed because `main.ts` is a module file (uses import or export).
+    Interfaces matching on name from @types/screeps will be merged. This is how you can extend the 'built-in' interfaces from @types/screeps.
+  */
+    interface SourceState {
+        id: string;
+        spots: PositionMatrix;
+        pos: RoomPosition;
+    }
+
+    interface GameState {
+        sourcesStates: { [sourceId: string]: SourceState };
+        maxHarvesters: number; // Maximum number of harvesters allowed in the game
+    }
+
+    // Memory extension samples
+    interface Memory {
+        uuid: number;
+        log: any;
+        roomStateRegistry: { [name: string]: GameState };
+    }
+
+    interface CreepMemory {
+        role: string;
+        room: string;
+        spawnId: string;
+        working: boolean;
+        destination?: CreepDestination;
+        previousDestination?: CreepDestination;
+    }
+
+    // Syntax for adding proprties to `global` (ex "global.log")
+    namespace NodeJS {
+        interface Global {
+            log: any;
+        }
+    }
+}
+
+export {};

src/main.ts

@@ -1,50 +1,4 @@
-import RoomRunner from 'RoomRunner';
+import RoomRunner from '@/RoomRunner';
-import { CreepDestination } from 'types/creeps';
-import { PositionMatrix } from 'utils/positions';
-
-declare global {
-    /*
-    Example types, expand on these or remove them and add your own.
-    Note: Values, properties defined here do no fully *exist* by this type definiton alone.
-          You must also give them an implemention if you would like to use them. (ex. actually setting a `role` property in a Creeps memory)
-
-    Types added in this `global` block are in an ambient, global context. This is needed because `main.ts` is a module file (uses import or export).
-    Interfaces matching on name from @types/screeps will be merged. This is how you can extend the 'built-in' interfaces from @types/screeps.
-  */
-    interface SourceState {
-        id: string;
-        spots: PositionMatrix;
-        pos: RoomPosition;
-    }
-
-    interface GameState {
-        sourcesStates: { [sourceId: string]: SourceState };
-        maxHarvesters: number; // Maximum number of harvesters allowed in the game
-    }
-
-    // Memory extension samples
-    interface Memory {
-        uuid: number;
-        log: any;
-        roomStateRegistry: { [name: string]: GameState };
-    }
-
-    interface CreepMemory {
-        role: string;
-        room: string;
-        spawnId: string;
-        working: boolean;
-        destination?: CreepDestination;
-        previousDestination?: CreepDestination;
-    }
-
-    // Syntax for adding proprties to `global` (ex "global.log")
-    namespace NodeJS {
-        interface Global {
-            log: any;
-        }
-    }
-}
 
 export const loop = () => {
     Memory.roomStateRegistry = Memory.roomStateRegistry || {};

src/roleHandlers/BaseHandler.interface.ts

@@ -1,12 +0,0 @@
-export abstract class RoleHandler {
-    public static destroy(_creepMemory: CreepMemory, _state: GameState): void {
-        // Default implementation does nothing
-        // Subclasses should override this method
-    }
-
-    public static run(_creep: Creep, state: GameState): GameState {
-        // Default implementation returns state unchanged
-        // Subclasses should override this method
-        return state;
-    }
-}

src/roleHandlers/base.handler.ts

@@ -0,0 +1,9 @@
+export abstract class RoleHandler {
+    public static destroy(_creepMemory: CreepMemory, _state: GameState): void {
+        throw Error('not implemented');
+    }
+
+    public static run(_creep: Creep, _state: GameState): GameState {
+        throw Error('not implemented');
+    }
+}

src/roleHandlers/harvester.handler.ts

@@ -1,12 +1,12 @@
-import { RoleHandler } from './BaseHandler.interface';
+import { RoleHandler } from './base.handler';
-import { SourceDestination } from 'types/creeps';
+import { SourceDestination } from '@/types/creeps';
-import { getSourceById, getSpawnById } from 'utils/funcs/getById';
+import { getSourceById, getSpawnById } from '@/utils/funcs/getById';
 import {
     getNextEmptySpot,
     getPositionWithDelta,
     PositionSpotStatus,
     setSpotStatus,
-} from 'utils/positions';
+} from '@/utils/positions';
 
 class HarvesterHandler extends RoleHandler {
     public static destroy(creepMemory: CreepMemory, state: GameState): void {

src/roleHandlers/index.ts

@@ -1,4 +1,4 @@
-import { RoleHandler } from './BaseHandler.interface';
+import { RoleHandler } from './base.handler';
 import HarvesterHandler from './harvester.handler';
 import UpgraderHandler from './upgrader.handler';
 

src/roleHandlers/upgrader.handler.ts

@@ -1,12 +1,12 @@
-import { RoleHandler } from './BaseHandler.interface';
+import { RoleHandler } from './base.handler';
-import { SourceDestination } from 'types/creeps';
+import { SourceDestination } from '@/types/creeps';
-import { getControllerById, getSourceById } from 'utils/funcs/getById';
+import { getControllerById, getSourceById } from '@/utils/funcs/getById';
 import {
     getNextEmptySpot,
+    getPositionWithDelta,
     PositionSpotStatus,
     setSpotStatus,
-    getPositionWithDelta,
+} from '@/utils/positions';
-} from 'utils/positions';
 
 class UpgraderHandler extends RoleHandler {
     public static destroy(creepMemory: CreepMemory, state: GameState): void {

src/types/creeps.ts

@@ -1,5 +1,5 @@
-import { HarvesterHandler, RoleHandler, UpgraderHandler } from 'roleHandlers';
+import { HarvesterHandler, RoleHandler, UpgraderHandler } from '@/roleHandlers';
-import { PositionDelta } from 'utils/positions';
+import { PositionDelta } from '@/utils/positions';
 
 export type RoleDefinition = {
     name: string;
@@ -27,6 +27,9 @@ export const CreepRoles = {
         handler: HarvesterHandler,
         priority: 3,
     },
+    defender: {
+        name: 'defender',
+    }
 } satisfies Record<string, RoleDefinition>;
 
 export type CreepRole = keyof typeof CreepRoles;

src/utils/funcs/getRoleCost.ts

@@ -1,4 +1,4 @@
-import { RoleDefinition } from 'types/creeps';
+import { RoleDefinition } from '@/types/creeps';
 
 export const get_role_cost = (role: RoleDefinition) => {
     return role.body.reduce((cost, part) => {

src/utils/funcs/sortCreepRolesByPriority.ts

@@ -3,7 +3,7 @@ import {
     CreepRole,
     CreepRoles,
     RoleDefinition,
-} from 'types/creeps';
+} from '@/types/creeps';
 
 export const sortCreepRolesByPriority = (
     requisition: CreepRequisition

tests/__mocks__/screeps.ts

@@ -0,0 +1,35 @@
+/**
+ * Minimal Screeps global mocks used across tests.
+ */
+
+// Constants
+(global as any).RESOURCE_ENERGY = 'energy';
+(global as any).ERR_NOT_IN_RANGE = -9;
+(global as any).OK = 0;
+(global as any).WORK = 'work';
+(global as any).CARRY = 'carry';
+(global as any).MOVE = 'move';
+
+// RoomPosition constructor mock
+(global as any).RoomPosition = class RoomPosition {
+    x: number;
+    y: number;
+    roomName: string;
+
+    constructor(x: number, y: number, roomName: string) {
+        this.x = x;
+        this.y = y;
+        this.roomName = roomName;
+    }
+
+    getRangeTo(_target: any): number {
+        return 0;
+    }
+};
+
+// Game mock
+(global as any).Game = {
+    getObjectById: jest.fn(),
+};
+
+export {};

tests/roleHandlers/harvester.handler.test.ts

@@ -0,0 +1,421 @@
+import HarvesterHandler from '@/roleHandlers/harvester.handler';
+import * as getById from '@/utils/funcs/getById';
+import {
+    PositionSpotStatus,
+    createSourcePositionMatrix,
+} from '@/utils/positions';
+import '~/tests/__mocks__/screeps';
+
+describe('HarvesterHandler', () => {
+    type FixtureOptions = {
+        memory?: Partial<CreepMemory>;
+        storeUsed?: number;
+        storeCapacity?: number;
+        stateOverrides?: Partial<GameState>;
+        sourceId?: string;
+        spawnId?: string;
+    };
+
+    const createFixture = ({
+        memory = {},
+        storeUsed = 0,
+        storeCapacity = 50,
+        stateOverrides = {},
+        sourceId = 'src1',
+        spawnId = 'spawn1',
+    }: FixtureOptions = {}) => {
+        const state = {
+            sourcesStates: {
+                [sourceId]: {
+                    spots: createSourcePositionMatrix(
+                        PositionSpotStatus.EMPTY as any
+                    ),
+                },
+            },
+            ...stateOverrides,
+        } as unknown as GameState;
+
+        const source = {
+            id: sourceId,
+            pos: new (global as any).RoomPosition(5, 5, 'W1N1'),
+        } as unknown as Source;
+
+        const spawn = { id: spawnId } as unknown as StructureSpawn;
+
+        const creep = {
+            name: 'Creep1',
+            memory: {
+                role: 'harvester',
+                spawnId,
+                ...memory,
+            } as CreepMemory,
+            store: {
+                getFreeCapacity: (_res: string) => storeCapacity - storeUsed,
+                getUsedCapacity: (_res: string) => storeUsed,
+            },
+            pos: new (global as any).RoomPosition(0, 0, 'W1N1'),
+            room: {},
+            harvest: jest.fn().mockReturnValue((global as any).OK),
+            moveTo: jest.fn().mockReturnValue((global as any).OK),
+            transfer: jest.fn().mockReturnValue((global as any).OK),
+        } as unknown as Creep;
+
+        return {
+            state,
+            source,
+            spawn,
+            creep,
+            memory: creep.memory,
+            mockSource: (value: Source | null = source) =>
+                jest.spyOn(getById, 'getSourceById').mockReturnValue(value),
+            mockSpawn: (value: StructureSpawn | null = spawn) =>
+                jest.spyOn(getById, 'getSpawnById').mockReturnValue(value),
+        };
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    describe('destroy', () => {
+        it('releases the source spot from destination and clears it', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            state.sourcesStates['src1'].spots[0] = PositionSpotStatus.OCCUPIED;
+
+            HarvesterHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[0]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.destination).toBeUndefined();
+        });
+
+        it('releases the source spot from previousDestination and clears it', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 2,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[2] = PositionSpotStatus.OCCUPIED;
+
+            HarvesterHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[2]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.previousDestination).toBeUndefined();
+        });
+
+        it('releases both destination and previousDestination source spots when both are set', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 2,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[0] = PositionSpotStatus.OCCUPIED;
+            state.sourcesStates['src1'].spots[2] = PositionSpotStatus.OCCUPIED;
+
+            HarvesterHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[0]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(state.sourcesStates['src1'].spots[2]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.destination).toBeUndefined();
+            expect(memory.previousDestination).toBeUndefined();
+        });
+
+        it('does nothing when destination is not a source', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'spawn', id: 'spawn1' },
+                },
+            });
+
+            HarvesterHandler.destroy(memory, state);
+
+            expect(
+                state.sourcesStates['src1'].spots.every(
+                    (s: PositionSpotStatus) =>
+                        s === PositionSpotStatus.EMPTY ||
+                        s === PositionSpotStatus.CENTER
+                )
+            ).toBe(true);
+        });
+
+        it('does nothing when memory has no destination', () => {
+            const { state, memory } = createFixture();
+
+            expect(() => HarvesterHandler.destroy(memory, state)).not.toThrow();
+        });
+
+        it('does not throw when destination source ID is missing from state', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: {
+                        type: 'source',
+                        id: 'nonexistent',
+                        sourceSpot: 0,
+                    },
+                },
+            });
+
+            expect(() => HarvesterHandler.destroy(memory, state)).not.toThrow();
+            expect(memory.destination).toBeUndefined();
+        });
+    });
+
+    describe('validateCreepMemory (via run)', () => {
+        it('releases previousDestination source spot and deletes it', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 1,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[1] = PositionSpotStatus.OCCUPIED;
+            mockSource(null);
+
+            HarvesterHandler.run(creep, state);
+
+            expect(state.sourcesStates['src1'].spots[1]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(creep.memory.previousDestination).toBeUndefined();
+        });
+
+        it('transitions from source to spawn destination when energy is full', () => {
+            const { state, creep, mockSource, mockSpawn } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                    spawnId: 'spawn1',
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+            });
+            mockSource();
+            mockSpawn();
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.memory.destination?.type).toBe('spawn');
+            expect(creep.memory.previousDestination?.type).toBe('source');
+        });
+
+        it('clears spawn destination when energy is empty', () => {
+            const { state, creep, mockSpawn, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'spawn', id: 'spawn1' },
+                },
+                storeUsed: 0,
+                storeCapacity: 50,
+            });
+            mockSpawn();
+            // Explicitly return null so onFindNewSource finds nothing
+            mockSource(null);
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.memory.destination).toBeUndefined();
+        });
+    });
+
+    describe('onFindNewSource', () => {
+        it('assigns the first available source spot to the creep', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource();
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.memory.destination?.type).toBe('source');
+            expect((creep.memory.destination as any).id).toBe('src1');
+        });
+
+        it('does not assign a source when all spots are occupied', () => {
+            const { state, creep, mockSource } = createFixture();
+            state.sourcesStates['src1'].spots = state.sourcesStates[
+                'src1'
+            ].spots.map((s: PositionSpotStatus) =>
+                s === PositionSpotStatus.CENTER ? s : PositionSpotStatus.OCCUPIED
+            ) as any;
+            mockSource();
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.memory.destination).toBeUndefined();
+        });
+
+        it('marks the assigned source spot as OCCUPIED in state', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource();
+
+            HarvesterHandler.run(creep, state);
+
+            const spotIndex = (creep.memory.destination as any)?.sourceSpot;
+            expect(spotIndex).toBeDefined();
+            expect(state.sourcesStates['src1'].spots[spotIndex]).toBe(
+                PositionSpotStatus.OCCUPIED
+            );
+        });
+    });
+
+    describe('onSourceDestination', () => {
+        it('harvests when in range', () => {
+            const { state, source, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue((global as any).OK);
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.harvest).toHaveBeenCalledWith(source);
+            expect(creep.moveTo).not.toHaveBeenCalled();
+        });
+
+        it('moves to source when not in range', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalled();
+        });
+
+        it('moves to the computed spot position (not source pos) when not in range', () => {
+            const { state, source, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalledWith(
+                // spot 0 → delta (-1,-1) from source pos (5,5) → (4,4)
+                expect.objectContaining({ x: 4, y: 4, roomName: 'W1N1' }),
+                expect.objectContaining({ reusePath: 10 })
+            );
+        });
+
+        it('logs and returns when source is not found', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: {
+                        type: 'source',
+                        id: 'unknown',
+                        sourceSpot: 0,
+                    },
+                },
+            });
+            mockSource(null);
+
+            expect(() => HarvesterHandler.run(creep, state)).not.toThrow();
+            expect(creep.harvest).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('onSpawnDestination', () => {
+        it('transfers energy when in range', () => {
+            const { state, spawn, creep, mockSpawn } = createFixture({
+                memory: {
+                    destination: { type: 'spawn', id: 'spawn1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+            });
+            mockSpawn();
+            (creep.transfer as jest.Mock).mockReturnValue((global as any).OK);
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.transfer).toHaveBeenCalledWith(
+                spawn,
+                (global as any).RESOURCE_ENERGY
+            );
+            expect(creep.moveTo).not.toHaveBeenCalled();
+        });
+
+        it('moves to spawn when not in range', () => {
+            const { state, spawn, creep, mockSpawn } = createFixture({
+                memory: {
+                    destination: { type: 'spawn', id: 'spawn1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+            });
+            mockSpawn();
+            (creep.transfer as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            HarvesterHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalledWith(
+                spawn,
+                expect.any(Object)
+            );
+        });
+
+        it('logs and returns when spawn is not found', () => {
+            const { state, creep, mockSpawn } = createFixture({
+                memory: {
+                    destination: { type: 'spawn', id: 'spawn1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+            });
+            mockSpawn(null);
+
+            expect(() => HarvesterHandler.run(creep, state)).not.toThrow();
+            expect(creep.transfer).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('run', () => {
+        it('returns the state object', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource(null);
+
+            const result = HarvesterHandler.run(creep, state);
+
+            expect(result).toBe(state);
+        });
+    });
+});

tests/roleHandlers/upgrader.handler.test.ts

@@ -0,0 +1,460 @@
+import UpgraderHandler from '@/roleHandlers/upgrader.handler';
+import * as getById from '@/utils/funcs/getById';
+import {
+    PositionSpotStatus,
+    createSourcePositionMatrix,
+} from '@/utils/positions';
+import '~/tests/__mocks__/screeps';
+
+describe('UpgraderHandler', () => {
+    type FixtureOptions = {
+        memory?: Partial<CreepMemory>;
+        storeUsed?: number;
+        storeCapacity?: number;
+        stateOverrides?: Partial<GameState>;
+        sourceId?: string;
+        controllerId?: string;
+        controllerInRoom?: StructureController | null;
+    };
+
+    const createFixture = ({
+        memory = {},
+        storeUsed = 0,
+        storeCapacity = 50,
+        stateOverrides = {},
+        sourceId = 'src1',
+        controllerId = 'ctrl1',
+        controllerInRoom = null,
+    }: FixtureOptions = {}) => {
+        const state = {
+            sourcesStates: {
+                [sourceId]: {
+                    spots: createSourcePositionMatrix(
+                        PositionSpotStatus.EMPTY as any
+                    ),
+                },
+            },
+            ...stateOverrides,
+        } as unknown as GameState;
+
+        const source = {
+            id: sourceId,
+            pos: new (global as any).RoomPosition(5, 5, 'W1N1'),
+        } as unknown as Source;
+
+        const controller = { id: controllerId } as StructureController;
+
+        const creep = {
+            name: 'Creep1',
+            memory: {
+                role: 'upgrader',
+                spawnId: 'spawn1',
+                ...memory,
+            } as CreepMemory,
+            store: {
+                getFreeCapacity: (_res: string) => storeCapacity - storeUsed,
+                getUsedCapacity: (_res: string) => storeUsed,
+            },
+            pos: new (global as any).RoomPosition(0, 0, 'W1N1'),
+            room: {
+                controller: controllerInRoom,
+            },
+            harvest: jest.fn().mockReturnValue((global as any).OK),
+            moveTo: jest.fn().mockReturnValue((global as any).OK),
+            upgradeController: jest.fn().mockReturnValue((global as any).OK),
+        } as unknown as Creep;
+
+        return {
+            state,
+            source,
+            controller,
+            creep,
+            memory: creep.memory,
+            mockSource: (value: Source | null = source) =>
+                jest.spyOn(getById, 'getSourceById').mockReturnValue(value),
+            mockController: (value: StructureController | null = controller) =>
+                jest
+                    .spyOn(getById, 'getControllerById')
+                    .mockReturnValue(value),
+        };
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    describe('destroy', () => {
+        it('releases the source spot from destination and clears it', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            state.sourcesStates['src1'].spots[0] = PositionSpotStatus.OCCUPIED;
+
+            UpgraderHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[0]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.destination).toBeUndefined();
+        });
+
+        it('releases the source spot from previousDestination and clears it', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 3,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[3] = PositionSpotStatus.OCCUPIED;
+
+            UpgraderHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[3]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.previousDestination).toBeUndefined();
+        });
+
+        it('releases both destination and previousDestination source spots when both are set', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 3,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[0] = PositionSpotStatus.OCCUPIED;
+            state.sourcesStates['src1'].spots[3] = PositionSpotStatus.OCCUPIED;
+
+            UpgraderHandler.destroy(memory, state);
+
+            expect(state.sourcesStates['src1'].spots[0]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(state.sourcesStates['src1'].spots[3]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(memory.destination).toBeUndefined();
+            expect(memory.previousDestination).toBeUndefined();
+        });
+
+        it('does nothing when destination is not a source', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: { type: 'controller', id: 'ctrl1' },
+                },
+            });
+
+            UpgraderHandler.destroy(memory, state);
+
+            expect(
+                state.sourcesStates['src1'].spots.every(
+                    (s: PositionSpotStatus) =>
+                        s === PositionSpotStatus.EMPTY ||
+                        s === PositionSpotStatus.CENTER
+                )
+            ).toBe(true);
+        });
+
+        it('does nothing when memory has no destination', () => {
+            const { state, memory } = createFixture();
+
+            expect(() => UpgraderHandler.destroy(memory, state)).not.toThrow();
+        });
+
+        it('does not throw when destination source ID is missing from state', () => {
+            const { state, memory } = createFixture({
+                memory: {
+                    destination: {
+                        type: 'source',
+                        id: 'nonexistent',
+                        sourceSpot: 0,
+                    },
+                },
+            });
+
+            expect(() => UpgraderHandler.destroy(memory, state)).not.toThrow();
+            expect(memory.destination).toBeUndefined();
+        });
+    });
+
+    describe('validateCreepMemory (via run)', () => {
+        it('releases previousDestination source spot and deletes it', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    previousDestination: {
+                        type: 'source',
+                        id: 'src1',
+                        sourceSpot: 1,
+                    },
+                },
+            });
+            state.sourcesStates['src1'].spots[1] = PositionSpotStatus.OCCUPIED;
+            mockSource(null);
+
+            UpgraderHandler.run(creep, state);
+
+            expect(state.sourcesStates['src1'].spots[1]).toBe(
+                PositionSpotStatus.EMPTY
+            );
+            expect(creep.memory.previousDestination).toBeUndefined();
+        });
+
+        it('transitions from source to controller destination when energy is full', () => {
+            const { state, controller, creep, mockController } =
+                createFixture({
+                    memory: {
+                        destination: {
+                            type: 'source',
+                            id: 'src1',
+                            sourceSpot: 0,
+                        },
+                    },
+                    storeUsed: 50,
+                    storeCapacity: 50,
+                    controllerInRoom: { id: 'ctrl1' } as StructureController,
+                });
+            // getSourceById is not called in this path — only getControllerById is needed
+            mockController(controller);
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.memory.destination?.type).toBe('controller');
+            expect(creep.memory.previousDestination?.type).toBe('source');
+        });
+
+        it('clears controller destination when energy is empty', () => {
+            const { state, controller, creep, mockController } = createFixture({
+                memory: {
+                    destination: { type: 'controller', id: 'ctrl1' },
+                },
+                storeUsed: 0,
+                storeCapacity: 50,
+                controllerInRoom: { id: 'ctrl1' } as StructureController,
+            });
+            mockController(controller);
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.memory.destination).toBeUndefined();
+        });
+
+        it('clears destination and logs when room has no controller during source->controller transition', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+                controllerInRoom: null,
+            });
+            state.sourcesStates['src1'].spots = state.sourcesStates[
+                'src1'
+            ].spots.map((s: PositionSpotStatus) =>
+                s === PositionSpotStatus.CENTER ? s : PositionSpotStatus.OCCUPIED
+            ) as any;
+            mockSource();
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.memory.destination).toBeUndefined();
+            // previousDestination is set to the old source before checking room.controller,
+            // so the source spot can be released on the next tick
+            expect(creep.memory.previousDestination).toEqual({
+                type: 'source',
+                id: 'src1',
+                sourceSpot: 0,
+            });
+        });
+    });
+
+    describe('onFindNewSource', () => {
+        it('assigns the first available source spot to the creep', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource();
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.memory.destination?.type).toBe('source');
+            expect((creep.memory.destination as any).id).toBe('src1');
+        });
+
+        it('does not assign a source when all spots are occupied', () => {
+            const { state, creep, mockSource } = createFixture();
+            state.sourcesStates['src1'].spots = state.sourcesStates[
+                'src1'
+            ].spots.map((s: PositionSpotStatus) =>
+                s === PositionSpotStatus.CENTER ? s : PositionSpotStatus.OCCUPIED
+            ) as any;
+            mockSource();
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.memory.destination).toBeUndefined();
+        });
+
+        it('marks the assigned source spot as OCCUPIED in state', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource();
+
+            UpgraderHandler.run(creep, state);
+
+            const spotIndex = (creep.memory.destination as any)?.sourceSpot;
+            expect(spotIndex).toBeDefined();
+            expect(state.sourcesStates['src1'].spots[spotIndex]).toBe(
+                PositionSpotStatus.OCCUPIED
+            );
+        });
+    });
+
+    describe('onSourceDestination', () => {
+        it('harvests when in range', () => {
+            const { state, source, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue((global as any).OK);
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.harvest).toHaveBeenCalledWith(source);
+            expect(creep.moveTo).not.toHaveBeenCalled();
+        });
+
+        it('moves to source when not in range', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalled();
+        });
+
+        it('moves to the computed spot position (not source pos) when not in range', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: { type: 'source', id: 'src1', sourceSpot: 0 },
+                },
+            });
+            mockSource();
+            (creep.harvest as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalledWith(
+                // spot 0 → delta (-1,-1) from source pos (5,5) → (4,4)
+                expect.objectContaining({ x: 4, y: 4, roomName: 'W1N1' }),
+                expect.objectContaining({ reusePath: 10 })
+            );
+        });
+
+        it('logs and returns when source is not found', () => {
+            const { state, creep, mockSource } = createFixture({
+                memory: {
+                    destination: {
+                        type: 'source',
+                        id: 'unknown',
+                        sourceSpot: 0,
+                    },
+                },
+            });
+            mockSource(null);
+
+            expect(() => UpgraderHandler.run(creep, state)).not.toThrow();
+            expect(creep.harvest).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('onControllerDestination', () => {
+        it('upgrades controller when in range', () => {
+            const { state, controller, creep, mockController } = createFixture({
+                memory: {
+                    destination: { type: 'controller', id: 'ctrl1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+                controllerInRoom: { id: 'ctrl1' } as StructureController,
+            });
+            mockController(controller);
+            (creep.upgradeController as jest.Mock).mockReturnValue(
+                (global as any).OK
+            );
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.upgradeController).toHaveBeenCalledWith(controller);
+            expect(creep.moveTo).not.toHaveBeenCalled();
+        });
+
+        it('moves to controller when not in range', () => {
+            const { state, controller, creep, mockController } = createFixture({
+                memory: {
+                    destination: { type: 'controller', id: 'ctrl1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+                controllerInRoom: { id: 'ctrl1' } as StructureController,
+            });
+            mockController(controller);
+            (creep.upgradeController as jest.Mock).mockReturnValue(
+                (global as any).ERR_NOT_IN_RANGE
+            );
+
+            UpgraderHandler.run(creep, state);
+
+            expect(creep.moveTo).toHaveBeenCalledWith(
+                controller,
+                expect.any(Object)
+            );
+        });
+
+        it('logs and returns when controller is not found by ID', () => {
+            const { state, creep, mockController } = createFixture({
+                memory: {
+                    destination: { type: 'controller', id: 'ctrl1' },
+                },
+                storeUsed: 50,
+                storeCapacity: 50,
+            });
+            mockController(null);
+
+            expect(() => UpgraderHandler.run(creep, state)).not.toThrow();
+            expect(creep.upgradeController).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('run', () => {
+        it('returns the state object', () => {
+            const { state, creep, mockSource } = createFixture();
+            mockSource(null);
+
+            const result = UpgraderHandler.run(creep, state);
+
+            expect(result).toBe(state);
+        });
+    });
+});

tsconfig.json

@@ -5,8 +5,7 @@
         "module": "commonjs",
         "moduleResolution": "node",
         "outDir": "dist",
-        "rootDir": "src",
+        "baseUrl": ".",
-        "baseUrl": "src",
         "strict": true,
         "noImplicitReturns": true,
         "noUnusedLocals": true,
@@ -16,8 +15,13 @@
         "sourceMap": true,
         "experimentalDecorators": true,
         "allowSyntheticDefaultImports": true,
-        "types": ["node", "screeps"]
+        "types": ["node", "screeps", "jest"],
+        "paths": {
+            "@/*": ["./src/*"],
+            "~/*": ["./*"]
+        },
+        "typeRoots": ["node_modules/@types", "src"]
     },
-    "include": ["src/*.ts", "src/**/*.ts"],
+    "include": ["src/global.d.ts", "src/*.ts", "src/**/*.ts"],
     "exclude": ["node_modules", "dist"]
 }

tsconfig.test.json

@@ -1,6 +1,13 @@
 {
     "extends": "./tsconfig.json",
     "compilerOptions": {
-        "module": "CommonJs"
+        "noUnusedLocals": false,
-    }
+        "noUnusedParameters": false
+    },
+    "include": [
+        "src/global.d.ts",
+        "src/**/*.ts",
+        "tests/**/*.ts"
+    ]
 }
+