run-dmcp 0.1.0

package/dist/tools/constraint.js

@@ -0,0 +1,269 @@
+import { v4 as uuidv4 } from "uuid";
+import { getDatabase } from "../db/connection.js";
+import { validateGameExists } from "./game.js";
+import { getResource } from "./resource.js";
+/**
+ * Declarative, opt-in, server-enforced invariants on `resources` rows.
+ *
+ * A resource with no declared constraint behaves exactly as it always has --
+ * out-of-bounds writes are silently clamped by clampValue() in resource.ts.
+ * Declaring a constraint here changes that contract for that one resource
+ * (or set of resources, for 'conserved') only.
+ *
+ * SCOPE NOTE: this layer covers the `resources` table only. Three other
+ * numeric write paths bypass it entirely and are NOT covered:
+ *   - factions.resources (JSON blob; see modifyFactionResource/setFactionResource
+ *     in src/tools/faction.ts -- no bounds, no history, silently deletes an
+ *     entry when it hits <= 0)
+ *   - characters.attributes (arbitrary numeric JSON, unvalidated)
+ *   - relationships.value (its own separate system)
+ * A game author who needs a server-enforced invariant on a quantity must
+ * model that quantity as a `resources` row, not one of the above.
+ *
+ * 'conserved' is fully enforced: a resource that is a member of a declared
+ * 'conserved' constraint can no longer be written directly through
+ * update_resource_value (see checkResourceConstraints() below) -- it must go
+ * through transferResourceValue() in resource.ts, which moves value between
+ * exactly two members of the same set atomically. See the comment on
+ * transferResourceValue() for why an explicit transfer, rather than a
+ * balanced multi-resource write, was chosen.
+ */
+/** Absolute tolerance for floating-point sum comparisons on 'conserved'
+ * constraints. IEEE 754 doubles cannot represent values like 0.1 exactly,
+ * so repeated addition/subtraction across many transfers can drift by a
+ * few ULPs. This is large enough to absorb that drift over realistic
+ * transfer volumes while still catching an actual logic bug (which would
+ * typically desync the sum by a whole `amount`, not a fraction of one). */
+export const CONSERVED_SUM_EPSILON = 1e-6;
+export class ConstraintViolationError extends Error {
+    constraintKind;
+    resourceId;
+    constructor(constraintKind, resourceId, message) {
+        super(message);
+        this.constraintKind = constraintKind;
+        this.resourceId = resourceId;
+        this.name = "ConstraintViolationError";
+    }
+}
+function memberIdsFor(constraintId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT resource_id FROM resource_constraint_members WHERE constraint_id = ? ORDER BY rowid`)
+        .all(constraintId);
+    return rows.map((r) => r.resource_id);
+}
+function rowToConstraint(row) {
+    return {
+        id: row.id,
+        gameId: row.game_id,
+        kind: row.kind,
+        resourceIds: memberIdsFor(row.id),
+        direction: row.direction,
+        total: row.total,
+        createdAt: row.created_at,
+    };
+}
+function insertConstraint(gameId, kind, resourceIds, direction, total) {
+    const db = getDatabase();
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO resource_constraints (id, game_id, kind, direction, total, created_at) VALUES (?, ?, ?, ?, ?, ?)`).run(id, gameId, kind, direction, total, now);
+    const memberStmt = db.prepare(`INSERT INTO resource_constraint_members (constraint_id, resource_id) VALUES (?, ?)`);
+    for (const resourceId of resourceIds) {
+        memberStmt.run(id, resourceId);
+    }
+    return {
+        id,
+        gameId,
+        kind,
+        resourceIds,
+        direction,
+        total,
+        createdAt: now,
+    };
+}
+/**
+ * Declare a 'bounded' constraint: the resource's value must stay within its
+ * existing minValue/maxValue (set via create_resource/update_resource).
+ * Once declared, out-of-bounds writes through updateResourceValue() are
+ * REJECTED instead of silently clamped -- see checkResourceConstraints().
+ */
+export function declareBoundedConstraint(params) {
+    validateGameExists(params.gameId);
+    const resource = getResource(params.resourceId);
+    if (!resource) {
+        throw new Error(`Resource '${params.resourceId}' not found.`);
+    }
+    if (resource.minValue === null && resource.maxValue === null) {
+        throw new Error(`Resource '${params.resourceId}' has neither minValue nor maxValue set. ` +
+            `A 'bounded' constraint enforces those bounds by rejecting instead of clamping -- ` +
+            `set at least one bound with update_resource before declaring this constraint.`);
+    }
+    if (getConstraintsForResource(params.resourceId).some((c) => c.kind === "bounded")) {
+        throw new Error(`Resource '${params.resourceId}' already has a 'bounded' constraint.`);
+    }
+    return insertConstraint(params.gameId, "bounded", [params.resourceId], null, null);
+}
+/**
+ * Declare a 'monotonic' constraint: the resource's value may only move in
+ * the given direction. 'increasing' means it may never decrease;
+ * 'decreasing' means it may never increase. Holding steady is always
+ * allowed.
+ */
+export function declareMonotonicConstraint(params) {
+    validateGameExists(params.gameId);
+    const resource = getResource(params.resourceId);
+    if (!resource) {
+        throw new Error(`Resource '${params.resourceId}' not found.`);
+    }
+    if (getConstraintsForResource(params.resourceId).some((c) => c.kind === "monotonic")) {
+        throw new Error(`Resource '${params.resourceId}' already has a 'monotonic' constraint.`);
+    }
+    return insertConstraint(params.gameId, "monotonic", [params.resourceId], params.direction, null);
+}
+/**
+ * Register a 'conserved' constraint: a set of resources that must always
+ * sum to a fixed total.
+ *
+ * Validation performed here, all rejecting rather than silently coercing:
+ *   - at least two distinct resources
+ *   - every resourceId must exist
+ *   - `total` must be a finite number
+ *   - no resource may already belong to another 'conserved' constraint --
+ *     a resource can be a member of at most one conserved set at a time, so
+ *     that transferResourceValue() (resource.ts) never has to guess which
+ *     set a transfer touching that resource is supposed to preserve
+ *   - the members' CURRENT values must already sum to `total`. This
+ *     constraint records an existing invariant, it does not establish one --
+ *     if the values don't already sum to `total`, that's almost always a
+ *     caller mistake (wrong total, forgot a member), and silently rewriting
+ *     resource values to make it true would hide that mistake.
+ *
+ * A resource may still separately hold a 'bounded' and/or 'monotonic'
+ * constraint alongside 'conserved' -- those are orthogonal and both remain
+ * enforced during transfers (see transferResourceValue()).
+ */
+export function declareConservedConstraint(params) {
+    validateGameExists(params.gameId);
+    const uniqueIds = Array.from(new Set(params.resourceIds));
+    if (uniqueIds.length < 2) {
+        throw new Error("A 'conserved' constraint requires at least two distinct resources.");
+    }
+    if (!Number.isFinite(params.total)) {
+        throw new Error(`'total' must be a finite number for a 'conserved' constraint; got ${params.total}.`);
+    }
+    let sum = 0;
+    for (const resourceId of uniqueIds) {
+        const resource = getResource(resourceId);
+        if (!resource) {
+            throw new Error(`Resource '${resourceId}' not found.`);
+        }
+        if (getConstraintsForResource(resourceId).some((c) => c.kind === "conserved")) {
+            throw new Error(`Resource '${resourceId}' already belongs to a 'conserved' constraint. A resource may only be a ` +
+                `member of one 'conserved' set at a time -- remove the existing constraint first (remove_resource_constraint) ` +
+                `if you need to redefine the set it belongs to.`);
+        }
+        sum += resource.value;
+    }
+    if (Math.abs(sum - params.total) > CONSERVED_SUM_EPSILON) {
+        throw new Error(`Cannot declare a 'conserved' constraint with total ${params.total}: the current values of ` +
+            `[${uniqueIds.join(", ")}] sum to ${sum}, not ${params.total}. Adjust the resources' values (via ` +
+            `update_resource_value, before declaring the constraint) or the declared total so they already match -- ` +
+            `declaring this constraint does not rewrite resource values to make a mismatched total true.`);
+    }
+    return insertConstraint(params.gameId, "conserved", uniqueIds, null, params.total);
+}
+/** List constraints for a game, optionally filtered to ones governing a given resource. */
+export function listConstraints(gameId, resourceId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT * FROM resource_constraints WHERE game_id = ? ORDER BY created_at`)
+        .all(gameId);
+    const constraints = rows.map(rowToConstraint);
+    if (resourceId === undefined)
+        return constraints;
+    return constraints.filter((c) => c.resourceIds.includes(resourceId));
+}
+/** All constraints (of any kind) that govern the given resource. */
+export function getConstraintsForResource(resourceId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT rc.* FROM resource_constraints rc
+       JOIN resource_constraint_members rcm ON rcm.constraint_id = rc.id
+       WHERE rcm.resource_id = ?
+       ORDER BY rc.created_at`)
+        .all(resourceId);
+    return rows.map(rowToConstraint);
+}
+/** Remove a constraint by id. Returns true if a row was deleted. */
+export function removeConstraint(id) {
+    const db = getDatabase();
+    const result = db.prepare(`DELETE FROM resource_constraints WHERE id = ?`).run(id);
+    return result.changes > 0;
+}
+/**
+ * Check whether an intended value change for a single resource would
+ * violate any 'bounded' or 'monotonic' constraint declared on it. Throws
+ * ConstraintViolationError on violation; returns void otherwise. Shared by
+ * checkResourceConstraints() (the single-resource write path) and
+ * transferResourceValue() (resource.ts; the two-resource conserved-transfer
+ * path) -- both paths must respect 'bounded'/'monotonic' the same way.
+ * Deliberately does not look at 'conserved' constraints; callers decide
+ * separately what to do about those (see checkResourceConstraints() below
+ * and transferResourceValue()).
+ */
+export function checkBoundedAndMonotonicConstraints(resourceId, previousValue, intendedValue, bounds) {
+    const constraints = getConstraintsForResource(resourceId);
+    for (const constraint of constraints) {
+        if (constraint.kind === "monotonic") {
+            if (constraint.direction === "increasing" && intendedValue < previousValue) {
+                throw new ConstraintViolationError("monotonic", resourceId, `Resource '${resourceId}' is constrained to never decrease; rejected change from ${previousValue} to ${intendedValue}.`);
+            }
+            if (constraint.direction === "decreasing" && intendedValue > previousValue) {
+                throw new ConstraintViolationError("monotonic", resourceId, `Resource '${resourceId}' is constrained to never increase; rejected change from ${previousValue} to ${intendedValue}.`);
+            }
+        }
+        if (constraint.kind === "bounded") {
+            if (bounds.minValue !== null && intendedValue < bounds.minValue) {
+                throw new ConstraintViolationError("bounded", resourceId, `Resource '${resourceId}' is bounded-constrained (min ${bounds.minValue}); rejected value ${intendedValue} instead of clamping.`);
+            }
+            if (bounds.maxValue !== null && intendedValue > bounds.maxValue) {
+                throw new ConstraintViolationError("bounded", resourceId, `Resource '${resourceId}' is bounded-constrained (max ${bounds.maxValue}); rejected value ${intendedValue} instead of clamping.`);
+            }
+        }
+        // constraint.kind === "conserved": handled by callers, not here.
+    }
+}
+/**
+ * Check whether an intended value change for a single resource would
+ * violate any constraint declared on it. Throws ConstraintViolationError on
+ * violation; returns void otherwise. Called from updateResourceValue() in
+ * resource.ts before the row is written.
+ *
+ * 'conserved' is handled specially here: ANY direct single-resource write to
+ * a conserved member is rejected, unconditionally, regardless of whether the
+ * particular delta would happen to preserve the total. The server cannot
+ * know where update_resource_value's counterpart delta should come from --
+ * writing one member without atomically adjusting another would silently
+ * break the set's invariant, which is exactly the failure this constraint
+ * exists to prevent. Use transfer_resource_value (transferResourceValue() in
+ * resource.ts) instead, which moves value between two members of the same
+ * set atomically.
+ */
+export function checkResourceConstraints(resourceId, previousValue, intendedValue, bounds) {
+    const constraints = getConstraintsForResource(resourceId);
+    checkBoundedAndMonotonicConstraints(resourceId, previousValue, intendedValue, bounds);
+    const conserved = constraints.find((c) => c.kind === "conserved");
+    if (conserved) {
+        throw new ConstraintViolationError("conserved", resourceId, `Resource '${resourceId}' is a member of a 'conserved' constraint (id '${conserved.id}', total ${conserved.total}) ` +
+            `and cannot be written directly via update_resource_value -- a single-resource write is ambiguous about where ` +
+            `the counterpart delta should come from, and could silently break the set's total. Use transfer_resource_value ` +
+            `to move value between two members of this set atomically instead.`);
+    }
+}
+/** All conserved constraints (of kind 'conserved') governing a resource,
+ * i.e. zero or one (declareConservedConstraint() rejects overlapping
+ * conserved membership, so a resource can belong to at most one). */
+export function getConservedConstraintFor(resourceId) {
+    return getConstraintsForResource(resourceId).find((c) => c.kind === "conserved") ?? null;
+}

package/dist/tools/dice.d.ts

@@ -0,0 +1,23 @@
+import type { DiceRoll, CheckResult } from "../types/index.js";
+export declare function roll(expression: string): DiceRoll;
+export declare function check(params: {
+    gameId: string;
+    characterId: string;
+    skill?: string;
+    attribute?: string;
+    difficulty: number;
+    bonusModifier?: number;
+}): CheckResult;
+export declare function contest(params: {
+    gameId: string;
+    attackerId: string;
+    defenderId: string;
+    attackerSkill?: string;
+    defenderSkill?: string;
+    attackerAttribute?: string;
+    defenderAttribute?: string;
+}): {
+    attackerResult: CheckResult;
+    defenderResult: CheckResult;
+    winner: "attacker" | "defender" | "tie";
+};

package/dist/tools/dice.js

@@ -0,0 +1,111 @@
+import { getRules } from "./rules.js";
+import { getCharacter } from "./character.js";
+// Maximum limits to prevent DoS attacks
+const MAX_DICE_COUNT = 100;
+const MAX_DICE_SIDES = 1000;
+// Parse and roll dice expressions like "2d6+3", "1d20-2", "3d8"
+export function roll(expression) {
+    const regex = /^(\d+)?d(\d+)([+-]\d+)?$/i;
+    const match = expression.replace(/\s/g, "").match(regex);
+    if (!match) {
+        throw new Error(`Invalid dice expression: ${expression}. Expected format: NdX+M (e.g., 2d6+3)`);
+    }
+    const count = match[1] ? parseInt(match[1], 10) : 1;
+    const sides = parseInt(match[2], 10);
+    const modifier = match[3] ? parseInt(match[3], 10) : 0;
+    // Validate bounds to prevent DoS
+    if (count < 1 || count > MAX_DICE_COUNT) {
+        throw new Error(`Dice count must be between 1 and ${MAX_DICE_COUNT}, got: ${count}`);
+    }
+    if (sides < 1 || sides > MAX_DICE_SIDES) {
+        throw new Error(`Dice sides must be between 1 and ${MAX_DICE_SIDES}, got: ${sides}`);
+    }
+    const rolls = [];
+    for (let i = 0; i < count; i++) {
+        rolls.push(Math.floor(Math.random() * sides) + 1);
+    }
+    const total = rolls.reduce((sum, r) => sum + r, 0) + modifier;
+    return {
+        expression,
+        rolls,
+        modifier,
+        total,
+    };
+}
+// Perform a skill/ability check using game rules
+export function check(params) {
+    const rules = getRules(params.gameId);
+    if (!rules) {
+        throw new Error(`No rules set for game ${params.gameId}`);
+    }
+    const character = getCharacter(params.characterId);
+    if (!character) {
+        throw new Error(`Character ${params.characterId} not found`);
+    }
+    // Calculate modifier from character stats
+    let modifier = params.bonusModifier || 0;
+    if (params.skill && character.skills[params.skill] !== undefined) {
+        modifier += character.skills[params.skill];
+    }
+    if (params.attribute && character.attributes[params.attribute] !== undefined) {
+        // Common formula: (attribute - 10) / 2, but we'll just add the raw value
+        // The DM agent should configure how modifiers work in the rules
+        modifier += Math.floor((character.attributes[params.attribute] - 10) / 2);
+    }
+    // Roll the base dice
+    const diceRoll = roll(rules.checkMechanics.baseDice);
+    const total = diceRoll.total + modifier;
+    // Determine success
+    const success = total >= params.difficulty;
+    const criticalSuccess = rules.checkMechanics.criticalSuccess !== undefined &&
+        diceRoll.rolls[0] >= rules.checkMechanics.criticalSuccess;
+    const criticalFailure = rules.checkMechanics.criticalFailure !== undefined &&
+        diceRoll.rolls[0] <= rules.checkMechanics.criticalFailure;
+    return {
+        roll: diceRoll,
+        modifier,
+        total,
+        difficulty: params.difficulty,
+        success: criticalFailure ? false : criticalSuccess ? true : success,
+        criticalSuccess,
+        criticalFailure,
+        margin: total - params.difficulty,
+    };
+}
+// Opposed check between two characters
+export function contest(params) {
+    const rules = getRules(params.gameId);
+    if (!rules) {
+        throw new Error(`No rules set for game ${params.gameId}`);
+    }
+    // Both roll against difficulty 0, we compare totals
+    const attackerResult = check({
+        gameId: params.gameId,
+        characterId: params.attackerId,
+        skill: params.attackerSkill,
+        attribute: params.attackerAttribute,
+        difficulty: 0,
+    });
+    const defenderResult = check({
+        gameId: params.gameId,
+        characterId: params.defenderId,
+        skill: params.defenderSkill,
+        attribute: params.defenderAttribute,
+        difficulty: 0,
+    });
+    let winner;
+    if (attackerResult.total > defenderResult.total) {
+        winner = "attacker";
+    }
+    else if (defenderResult.total > attackerResult.total) {
+        winner = "defender";
+    }
+    else {
+        winner = "tie";
+    }
+    return {
+        attackerResult,
+        defenderResult,
+        winner,
+    };
+}

package/dist/tools/display.d.ts

@@ -0,0 +1,120 @@
+export type BorderRadiusStyle = "sharp" | "rounded" | "soft";
+export type CardStyle = "clean" | "grungy" | "tech" | "parchment" | "metallic" | "wooden";
+export interface DisplayConfig {
+    bgColor: string;
+    bgSecondary: string;
+    bgElevated: string;
+    textColor: string;
+    textMuted: string;
+    accentColor: string;
+    accentHover: string;
+    borderColor: string;
+    successColor: string;
+    warningColor: string;
+    dangerColor: string;
+    codeBackground: string;
+    codeText: string;
+    borderRadius: BorderRadiusStyle;
+    cardStyle: CardStyle;
+    fontDisplay: string;
+    fontBody: string;
+    fontMono: string;
+    showHealthBars: boolean;
+    showConditionTags: boolean;
+    showImages: boolean;
+    appTitle: string;
+}
+export declare const themePresets: Record<string, Partial<DisplayConfig>>;
+/**
+ * Get the current display configuration
+ */
+export declare function getDisplayConfig(): DisplayConfig;
+/**
+ * Set the display configuration (full or partial update)
+ */
+export declare function setDisplayConfig(config: Partial<DisplayConfig>): DisplayConfig;
+/**
+ * Reset display configuration to defaults
+ */
+export declare function resetDisplayConfig(): DisplayConfig;
+/**
+ * Apply a preset theme
+ */
+export declare function applyThemePreset(presetName: string): DisplayConfig | null;
+/**
+ * List available theme presets
+ */
+export declare function listThemePresets(): Array<{
+    name: string;
+    preview: Partial<DisplayConfig>;
+}>;
+/**
+ * Set specific display options (convenience function)
+ */
+export declare function setDisplayOptions(options: {
+    showHealthBars?: boolean;
+    showConditionTags?: boolean;
+    showImages?: boolean;
+}): DisplayConfig;
+/**
+ * Set theme colors (convenience function)
+ */
+export declare function setThemeColors(colors: {
+    bgColor?: string;
+    bgSecondary?: string;
+    bgElevated?: string;
+    textColor?: string;
+    textMuted?: string;
+    accentColor?: string;
+    accentHover?: string;
+    borderColor?: string;
+    successColor?: string;
+    warningColor?: string;
+    dangerColor?: string;
+    codeBackground?: string;
+    codeText?: string;
+}): DisplayConfig;
+/**
+ * Set the app title
+ */
+export declare function setAppTitle(title: string): DisplayConfig;
+/**
+ * Set fonts (Google Fonts names)
+ */
+export declare function setFonts(fonts: {
+    fontDisplay?: string;
+    fontBody?: string;
+    fontMono?: string;
+}): DisplayConfig;
+/**
+ * Set visual style options
+ */
+export declare function setVisualStyle(style: {
+    borderRadius?: BorderRadiusStyle;
+    cardStyle?: CardStyle;
+}): DisplayConfig;
+/**
+ * Get display configuration for a specific game
+ * Falls back to global config if no game theme exists
+ */
+export declare function getGameDisplayConfig(gameId: string): DisplayConfig;
+/**
+ * Set display configuration for a specific game
+ */
+export declare function setGameDisplayConfig(gameId: string, config: Partial<DisplayConfig>): DisplayConfig;
+/**
+ * Apply a preset theme to a specific game
+ */
+export declare function applyGameThemePreset(gameId: string, presetName: string): DisplayConfig | null;
+/**
+ * Reset game theme (removes game-specific config, falls back to global)
+ */
+export declare function resetGameTheme(gameId: string): void;
+/**
+ * Check if a game has a custom theme
+ */
+export declare function hasGameTheme(gameId: string): boolean;
+/**
+ * Infer and apply theme based on game genre/setting
+ */
+export declare function inferAndApplyTheme(gameId: string, genre: string, setting?: string): DisplayConfig;