run-dmcp 0.1.0

package/dist/tools/__tests__/timers.test.js

@@ -0,0 +1,426 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
+import { getDatabase } from '../../db/connection.js';
+import { createGame } from '../game.js';
+import { createResource, getResource, getResourceHistory, deleteResource } from '../resource.js';
+import { createTimer, getTimer, listTimers, tickTimer, resetTimer, modifyTimerState } from '../timers.js';
+describe('timer tools', () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    describe('tickTimer baseline (no consequence)', () => {
+        it('returns null for an unknown timer', () => {
+            expect(tickTimer('does-not-exist')).toBeNull();
+        });
+        it('counts a countdown timer down by the tick amount', () => {
+            const timer = createTimer({ gameId, name: 'fuse', timerType: 'countdown', currentValue: 5 });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.timer.currentValue).toBe(4);
+            expect(result?.previousValue).toBe(5);
+        });
+        it('counts a stopwatch timer up by the tick amount', () => {
+            const timer = createTimer({ gameId, name: 'ritual', timerType: 'stopwatch', direction: 'up', maxValue: 10 });
+            const result = tickTimer(timer.id, 3);
+            expect(result?.timer.currentValue).toBe(3);
+        });
+        it('flags justTriggered the first time a countdown reaches its triggerAt', () => {
+            const timer = createTimer({ gameId, name: 'fuse', timerType: 'countdown', currentValue: 1, triggerAt: 0 });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.justTriggered).toBe(true);
+            expect(result?.timer.triggered).toBe(true);
+        });
+        it('does not flag justTriggered again on a subsequent tick after already triggered', () => {
+            const timer = createTimer({ gameId, name: 'fuse', timerType: 'countdown', currentValue: 1, triggerAt: 0 });
+            tickTimer(timer.id, 1);
+            const second = tickTimer(timer.id, 1);
+            expect(second?.justTriggered).toBe(false);
+        });
+    });
+    describe('createTimer consequence persistence (opt-in field)', () => {
+        it('defaults consequence to null when not provided', () => {
+            const timer = createTimer({ gameId, name: 'fuse', timerType: 'countdown', currentValue: 3 });
+            expect(timer.consequence).toBeNull();
+        });
+        it('persists and round-trips a provided consequence through createTimer', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 10 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 3,
+                consequence: { resourceId: resource.id, delta: -5 },
+            });
+            expect(timer.consequence).toEqual({ resourceId: resource.id, delta: -5 });
+        });
+        it('round-trips through getTimer', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 10 });
+            const created = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 3,
+                consequence: { resourceId: resource.id, delta: -5 },
+            });
+            expect(getTimer(created.id)?.consequence).toEqual({ resourceId: resource.id, delta: -5 });
+        });
+        it('round-trips through listTimers', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 10 });
+            createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 3,
+                consequence: { resourceId: resource.id, delta: -5 },
+            });
+            const [listed] = listTimers(gameId);
+            expect(listed.consequence).toEqual({ resourceId: resource.id, delta: -5 });
+        });
+    });
+    describe('consequences applied by tickTimer -- no LLM in the loop', () => {
+        it('applies the consequence the moment the timer crosses its triggerAt', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -30 },
+            });
+            // Nothing reads justTriggered or acts on it -- tickTimer alone must
+            // be enough for the resource to change.
+            tickTimer(timer.id, 1);
+            expect(getResource(resource.id)?.value).toBe(70);
+        });
+        it('applies a positive delta consequence', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 10 });
+            const timer = createTimer({
+                gameId,
+                name: 'ritual completes',
+                timerType: 'stopwatch',
+                direction: 'up',
+                maxValue: 3,
+                triggerAt: 3,
+                consequence: { resourceId: resource.id, delta: 25 },
+            });
+            tickTimer(timer.id, 3);
+            expect(getResource(resource.id)?.value).toBe(35);
+        });
+        it('clamps the consequence delta the same way any other delta update is clamped', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'population', value: 5, minValue: 0 });
+            const timer = createTimer({
+                gameId,
+                name: 'plague',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -100 },
+            });
+            tickTimer(timer.id, 1);
+            expect(getResource(resource.id)?.value).toBe(0);
+        });
+        it('records a resource_history row whose reason references the triggering timer', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            tickTimer(timer.id, 1);
+            const history = getResourceHistory(resource.id);
+            expect(history).toHaveLength(1);
+            expect(history[0]).toMatchObject({ previousValue: 100, newValue: 90, delta: -10 });
+            expect(history[0].reason).toContain('fuse');
+        });
+        it('reports consequenceApplied=true on the TickResult when the consequence lands', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.consequenceApplied).toBe(true);
+        });
+        it('reports consequenceApplied=false when a tick does not cross the trigger', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 5,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.consequenceApplied).toBe(false);
+            expect(getResource(resource.id)?.value).toBe(100);
+        });
+        it('reports consequenceApplied=false when justTriggered fires but no consequence is declared', () => {
+            const timer = createTimer({ gameId, name: 'fuse', timerType: 'countdown', currentValue: 1, triggerAt: 0 });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.justTriggered).toBe(true);
+            expect(result?.consequenceApplied).toBe(false);
+        });
+        it('leaves timers with no declared consequence behaving exactly as before (opt-in)', () => {
+            const timer = createTimer({ gameId, name: 'plain fuse', timerType: 'countdown', currentValue: 1, triggerAt: 0 });
+            const result = tickTimer(timer.id, 1);
+            expect(result?.timer.currentValue).toBe(0);
+            expect(result?.timer.triggered).toBe(true);
+        });
+    });
+    describe('exactly-once guarantees', () => {
+        it('does not re-apply the consequence on a later tick after the timer already triggered', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 2,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            tickTimer(timer.id, 1); // 2 -> 1, not yet triggered
+            tickTimer(timer.id, 1); // 1 -> 0, triggers, applies once
+            tickTimer(timer.id, 1); // already triggered, stays at 0 (floor), must not re-apply
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+        it('applies exactly once even when a single tick amount jumps straight past the trigger boundary', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 10,
+                triggerAt: 5,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = tickTimer(timer.id, 8); // 10 -> 2, jumps past triggerAt=5 in one tick
+            expect(result?.justTriggered).toBe(true);
+            expect(getResource(resource.id)?.value).toBe(90);
+            tickTimer(timer.id, 1); // further ticks must not re-apply
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+        it('applies a consequence when the new value lands exactly on triggerAt (boundary, countdown)', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 5,
+                triggerAt: 3,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = tickTimer(timer.id, 2); // 5 -> 3, exactly on triggerAt
+            expect(result?.justTriggered).toBe(true);
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+        it('applies a consequence when the new value lands exactly on triggerAt (boundary, stopwatch)', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'ritual',
+                timerType: 'stopwatch',
+                direction: 'up',
+                maxValue: 6,
+                triggerAt: 6,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = tickTimer(timer.id, 6);
+            expect(result?.justTriggered).toBe(true);
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+        it('re-fires the consequence after an explicit reset and a subsequent re-trigger', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            tickTimer(timer.id, 1); // triggers, -10
+            expect(getResource(resource.id)?.value).toBe(90);
+            resetTimer(timer.id); // explicit reset clears the triggered flag
+            tickTimer(timer.id, 1); // fires again -- this is a deliberate re-arm, not a double-fire of the same event
+            expect(getResource(resource.id)?.value).toBe(80);
+        });
+        it('resetTimer itself never applies a consequence, even though it clears the triggered flag', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            tickTimer(timer.id, 1);
+            expect(getResource(resource.id)?.value).toBe(90);
+            resetTimer(timer.id);
+            expect(getResource(resource.id)?.value).toBe(90); // unchanged by reset alone
+        });
+        it('modifyTimerState({mode: "reset"}) does not apply a consequence', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            tickTimer(timer.id, 1);
+            modifyTimerState(timer.id, { mode: 'reset' });
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+        it('modifyTimerState({mode: "tick"}) applies the consequence exactly like tickTimer', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const result = modifyTimerState(timer.id, { mode: 'tick', amount: 1 });
+            expect(result?.consequenceApplied).toBe(true);
+            expect(getResource(resource.id)?.value).toBe(90);
+        });
+    });
+    describe('a consequence that itself fails', () => {
+        it('throws when the target resource never existed, and does not tick the timer at all', () => {
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: 'does-not-exist', delta: -10 },
+            });
+            expect(() => tickTimer(timer.id, 1)).toThrow();
+            const reloaded = getTimer(timer.id);
+            expect(reloaded?.currentValue).toBe(1);
+            expect(reloaded?.triggered).toBe(false);
+        });
+        it('throws when the target resource was deleted after the timer was created', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            deleteResource(resource.id);
+            expect(() => tickTimer(timer.id, 1)).toThrow();
+            const reloaded = getTimer(timer.id);
+            expect(reloaded?.currentValue).toBe(1);
+            expect(reloaded?.triggered).toBe(false);
+        });
+        it('rolls back the value and triggered-flag change together with the consequence on a mid-transaction failure', () => {
+            const resource = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: resource.id, delta: -10 },
+            });
+            const db = getDatabase();
+            db.exec(`
+        CREATE TRIGGER fail_resource_history_insert_timer
+        BEFORE INSERT ON resource_history
+        BEGIN
+          SELECT RAISE(ABORT, 'simulated failure');
+        END;
+      `);
+            expect(() => tickTimer(timer.id, 1)).toThrow();
+            expect(getResource(resource.id)?.value).toBe(100);
+            expect(getResourceHistory(resource.id)).toHaveLength(0);
+            const reloaded = getTimer(timer.id);
+            expect(reloaded?.currentValue).toBe(1);
+            expect(reloaded?.triggered).toBe(false);
+        });
+        it('permits ticking again after fixing the underlying resource problem', () => {
+            const timer = createTimer({
+                gameId,
+                name: 'fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: 'does-not-exist', delta: -10 },
+            });
+            expect(() => tickTimer(timer.id, 1)).toThrow();
+            // Retrying with the same broken consequence keeps failing safely --
+            // it never silently "succeeds" by skipping the consequence.
+            expect(() => tickTimer(timer.id, 1)).toThrow();
+            const reloaded = getTimer(timer.id);
+            expect(reloaded?.currentValue).toBe(1);
+            expect(reloaded?.triggered).toBe(false);
+        });
+    });
+    describe('interleaving with unrelated timers', () => {
+        it('applies consequences independently across multiple timers sharing no state', () => {
+            const grain = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
+            const treasury = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 100 });
+            const fuseA = createTimer({
+                gameId,
+                name: 'fuse A',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: grain.id, delta: -10 },
+            });
+            const fuseB = createTimer({
+                gameId,
+                name: 'fuse B',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: treasury.id, delta: -25 },
+            });
+            tickTimer(fuseA.id, 1);
+            tickTimer(fuseB.id, 1);
+            expect(getResource(grain.id)?.value).toBe(90);
+            expect(getResource(treasury.id)?.value).toBe(75);
+        });
+        it('one timer failing to apply its consequence does not affect an unrelated timer ticked afterward', () => {
+            const treasury = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 100 });
+            const brokenFuse = createTimer({
+                gameId,
+                name: 'broken fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: 'does-not-exist', delta: -10 },
+            });
+            const healthyFuse = createTimer({
+                gameId,
+                name: 'healthy fuse',
+                timerType: 'countdown',
+                currentValue: 1,
+                triggerAt: 0,
+                consequence: { resourceId: treasury.id, delta: -25 },
+            });
+            expect(() => tickTimer(brokenFuse.id, 1)).toThrow();
+            tickTimer(healthyFuse.id, 1);
+            expect(getResource(treasury.id)?.value).toBe(75);
+        });
+    });
+});

package/dist/tools/__tests__/world.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/world.test.js

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
+import { getDatabase } from '../../db/connection.js';
+import { createGame } from '../game.js';
+import { connectLocations, createLocation, getLocation } from '../world.js';
+describe('connectLocations', () => {
+    let gameId;
+    beforeEach(() => {
+        createTestDb();
+        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
+    });
+    afterEach(() => {
+        destroyTestDb();
+    });
+    it('adds a one-way exit when bidirectional is false', () => {
+        const a = createLocation({ gameId, name: 'Field', description: 'An open field' });
+        const b = createLocation({ gameId, name: 'Barn', description: 'A wooden barn' });
+        const result = connectLocations({
+            fromLocationId: a.id,
+            toLocationId: b.id,
+            fromDirection: 'north',
+            toDirection: 'south',
+            bidirectional: false,
+        });
+        expect(result?.success).toBe(true);
+        expect(result?.reverseExitCreated).toBeNull();
+        expect(getLocation(a.id)?.properties.exits).toHaveLength(1);
+        expect(getLocation(b.id)?.properties.exits).toHaveLength(0);
+    });
+    it('adds exits to both locations when bidirectional', () => {
+        const a = createLocation({ gameId, name: 'Field', description: 'An open field' });
+        const b = createLocation({ gameId, name: 'Barn', description: 'A wooden barn' });
+        connectLocations({
+            fromLocationId: a.id,
+            toLocationId: b.id,
+            fromDirection: 'north',
+            toDirection: 'south',
+        });
+        expect(getLocation(a.id)?.properties.exits).toHaveLength(1);
+        expect(getLocation(b.id)?.properties.exits).toHaveLength(1);
+    });
+    it('leaves NO partial write when the second (reverse-exit) update fails mid-operation', () => {
+        const a = createLocation({ gameId, name: 'Field', description: 'An open field' });
+        const b = createLocation({ gameId, name: 'Barn', description: 'A wooden barn' });
+        // Fault injection: make the UPDATE against location `b` (the second
+        // write connectLocations performs) fail, simulating a mid-operation
+        // failure such as a disk error or constraint violation. If the two
+        // writes aren't wrapped in a real transaction, location `a` will have
+        // already been updated by the time this trigger fires.
+        const db = getDatabase();
+        db.exec(`
+      CREATE TRIGGER fail_second_update
+      BEFORE UPDATE ON locations
+      WHEN NEW.id = '${b.id}'
+      BEGIN
+        SELECT RAISE(ABORT, 'simulated failure');
+      END;
+    `);
+        expect(() => connectLocations({
+            fromLocationId: a.id,
+            toLocationId: b.id,
+            fromDirection: 'north',
+            toDirection: 'south',
+        })).toThrow();
+        // Neither location should show any exit -- the forward-exit write to
+        // `a` must have been rolled back along with the failed write to `b`.
+        expect(getLocation(a.id)?.properties.exits).toHaveLength(0);
+        expect(getLocation(b.id)?.properties.exits).toHaveLength(0);
+    });
+});

package/dist/tools/ability.d.ts

@@ -0,0 +1,48 @@
+import type { Ability } from "../types/index.js";
+export declare function createAbility(params: {
+    gameId: string;
+    ownerType: "template" | "character";
+    ownerId?: string;
+    name: string;
+    description?: string;
+    category?: string;
+    cost?: Record<string, number>;
+    cooldown?: number;
+    effects?: string[];
+    requirements?: Record<string, number>;
+    tags?: string[];
+}): Ability;
+export declare function getAbility(id: string): Ability | null;
+export declare function updateAbility(id: string, updates: {
+    name?: string;
+    description?: string;
+    category?: string | null;
+    cost?: Record<string, number>;
+    cooldown?: number | null;
+    effects?: string[];
+    requirements?: Record<string, number>;
+    tags?: string[];
+}): Ability | null;
+export declare function deleteAbility(id: string): boolean;
+export declare function listAbilities(gameId: string, filter?: {
+    ownerType?: "template" | "character";
+    ownerId?: string;
+    category?: string;
+}): Ability[];
+export declare function learnAbility(templateId: string, characterId: string): Ability | null;
+export interface UseAbilityResult {
+    success: boolean;
+    ability: Ability;
+    reason?: string;
+    costsPaid?: Record<string, number>;
+}
+export declare function useAbility(abilityId: string, _characterId: string): UseAbilityResult;
+export declare function tickCooldowns(gameId: string, amount?: number): Ability[];
+export interface RequirementCheck {
+    meetsRequirements: boolean;
+    missing: Record<string, {
+        required: number;
+        actual: number;
+    }>;
+}
+export declare function checkRequirements(abilityId: string, characterId: string): RequirementCheck | null;