run-dmcp 0.2.0 → 0.4.0

package/dist/timeline/schema.js

@@ -53,6 +53,8 @@ export function initializeTimelineSchema() {
     // all (absence is the absence of a fact, never a fact of absence -- hard
     // rule 3). No ON DELETE CASCADE and no FK to `games`: deleting a game
     // deletes its live rows, but the timeline of that game survives.
+    // DECISION(#21): a property to be declared irreversible needs its own fact key.
+    //
     // `irreversible` is a per-fact flag, not a per-entity or per-value one --
     // so any property a future consumer wants to declare irreversible has to
     // live under its own fact key; you cannot flag half a blob.

package/dist/tools/audio.js

@@ -2,6 +2,7 @@ import { v4 as uuidv4 } from "uuid";
 import { getDatabase, getDataDir, withTransaction } from "../db/connection.js";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, rmSync, } from "fs";
 import { dirname, join, extname } from "path";
+import { mediaDirPath, mediaFilePath, mediaPathWithin } from "../utils/media-path.js";
 import { getCharacter } from "./character.js";
 import { getLocation } from "./world.js";
 import { getFaction } from "./faction.js";
@@ -128,10 +129,11 @@ export async function storeAudio(params) {
     else {
         throw new Error("Either url or filePath must be provided");
     }
-    // Build file path
+    // Build file path. Every segment below arrives from the caller, so the
+    // composition goes through the media-path choke point, which rejects
+    // anything that would land outside the audio directory.
     const ext = getExtension(mimeType);
-    const relativePath = join(params.gameId, `${params.entityType}s`, params.entityId, `${id}.${ext}`);
-    const fullPath = join(getAudioDir(), relativePath);
+    const { relativePath, fullPath } = mediaFilePath(getAudioDir(), [params.gameId, `${params.entityType}s`, params.entityId], `${id}.${ext}`);
     // Ensure directory exists and write file
     ensureDir(dirname(fullPath));
     writeFileSync(fullPath, audioBuffer);
@@ -192,7 +194,7 @@ export function getAudioFilePath(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     return fullPath;
@@ -201,7 +203,7 @@ export function getAudioData(audioId) {
     const audio = getAudio(audioId);
     if (!audio)
         return null;
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (!existsSync(fullPath))
         return null;
     const buffer = readFileSync(fullPath);
@@ -264,7 +266,7 @@ export function getCharacterVoiceReferences(gameId, characterId) {
     const audioDir = getAudioDir();
     const filePaths = voiceRefs
         .map((ref) => {
-        const fullPath = join(audioDir, ref.filePath);
+        const fullPath = mediaPathWithin(audioDir, ref.filePath);
         return existsSync(fullPath) ? fullPath : null;
     })
         .filter((p) => p !== null);
@@ -283,7 +285,7 @@ export function deleteAudio(audioId) {
     if (!audio)
         return false;
     // Delete file
-    const fullPath = join(getAudioDir(), audio.filePath);
+    const fullPath = mediaPathWithin(getAudioDir(), audio.filePath);
     if (existsSync(fullPath)) {
         unlinkSync(fullPath);
     }
@@ -339,8 +341,10 @@ export function updateAudioMetadata(audioId, updates) {
 // Cleanup helper - delete all audio for a game
 export function deleteGameAudio(gameId) {
     const db = getDatabase();
-    // Delete files
-    const gameDir = join(getAudioDir(), gameId);
+    // Delete files. mediaDirPath rejects before the rmSync below, which is
+    // recursive and forced: an unchecked `..` here would take the whole data
+    // directory with it.
+    const gameDir = mediaDirPath(getAudioDir(), [gameId]);
     if (existsSync(gameDir)) {
         rmSync(gameDir, { recursive: true, force: true });
     }

package/dist/tools/game.js

@@ -1,6 +1,10 @@
 import { v4 as uuidv4 } from "uuid";
 import { getDatabase } from "../db/connection.js";
 import { safeJsonParse } from "../utils/json.js";
+import { createLogger } from "../utils/logger.js";
+import { deleteGameAudio } from "./audio.js";
+import { deleteGameImages } from "./images.js";
+const log = createLogger("game");
 /**
  * Validates that a game exists and returns it, or throws an error if not found.
  * Use this in create operations to prevent orphaned records.
@@ -119,7 +123,35 @@ export function deleteGame(id) {
     const db = getDatabase();
     const stmt = db.prepare(`DELETE FROM games WHERE id = ?`);
     const result = stmt.run(id);
-    return result.changes > 0;
+    if (result.changes === 0)
+        return false;
+    // The stored_audio / stored_images rows went with the game by foreign key
+    // cascade, so nothing is left that knows the files on disk exist. Cleanup
+    // therefore runs here, after the delete has committed.
+    //
+    // A cleanup failure degrades to a log rather than an exception: the row is
+    // already gone and throwing cannot un-delete it, so it would trade a stale
+    // directory for a failed tool call and lose both. Each cleanup is attempted
+    // separately, so one failing does not skip the other.
+    try {
+        deleteGameAudio(id);
+    }
+    catch (error) {
+        log.error("Failed to remove stored audio for a deleted game; files remain on disk", {
+            gameId: id,
+            error: error.message,
+        });
+    }
+    try {
+        deleteGameImages(id);
+    }
+    catch (error) {
+        log.error("Failed to remove stored images for a deleted game; files remain on disk", {
+            gameId: id,
+            error: error.message,
+        });
+    }
+    return true;
 }
 export function updateGameLocation(gameId, locationId) {
     const db = getDatabase();

package/dist/tools/images.js

@@ -3,6 +3,7 @@ import { getDatabase, getDataDir, withTransaction } from "../db/connection.js";
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, rmSync, } from "fs";
 import { dirname, join } from "path";
 import sharp from "sharp";
+import { mediaDirPath, mediaFilePath, mediaPathWithin } from "../utils/media-path.js";
 import { getCharacter } from "./character.js";
 import { getLocation } from "./world.js";
 import { getItem } from "./inventory.js";
@@ -122,10 +123,11 @@ export async function storeImage(params) {
     catch {
         // If sharp can't parse it, proceed without dimensions
     }
-    // Build file path
+    // Build file path. Every segment below arrives from the caller, so the
+    // composition goes through the media-path choke point, which rejects
+    // anything that would land outside the images directory.
     const ext = getExtension(mimeType);
-    const relativePath = join(params.gameId, `${params.entityType}s`, params.entityId, `${id}.${ext}`);
-    const fullPath = join(getImagesDir(), relativePath);
+    const { relativePath, fullPath } = mediaFilePath(getImagesDir(), [params.gameId, `${params.entityType}s`, params.entityId], `${id}.${ext}`);
     // Ensure directory exists and write file
     ensureDir(dirname(fullPath));
     writeFileSync(fullPath, imageBuffer);
@@ -177,7 +179,7 @@ export async function getImageData(imageId, options) {
     const image = getImage(imageId);
     if (!image)
         return null;
-    const fullPath = join(getImagesDir(), image.filePath);
+    const fullPath = mediaPathWithin(getImagesDir(), image.filePath);
     if (!existsSync(fullPath))
         return null;
     const originalBuffer = readFileSync(fullPath);
@@ -335,7 +337,7 @@ export function deleteImage(imageId) {
     if (!image)
         return false;
     // Delete file
-    const fullPath = join(getImagesDir(), image.filePath);
+    const fullPath = mediaPathWithin(getImagesDir(), image.filePath);
     if (existsSync(fullPath)) {
         unlinkSync(fullPath);
     }
@@ -380,10 +382,13 @@ export function updateImageMetadata(imageId, updates) {
         validateEntityExists(newEntityId, newEntityType);
         // If entity changed, move the file
         if (newEntityId !== current.entityId || newEntityType !== current.entityType) {
-            const oldFullPath = join(getImagesDir(), current.filePath);
+            const oldFullPath = mediaPathWithin(getImagesDir(), current.filePath);
             const ext = current.filePath.split(".").pop() || "png";
-            newFilePath = join(current.gameId, `${newEntityType}s`, newEntityId, `${imageId}.${ext}`);
-            const newFullPath = join(getImagesDir(), newFilePath);
+            // The move recomposes the path from a caller-supplied entity id and
+            // type, so it goes through the same choke point as the original write.
+            const moved = mediaFilePath(getImagesDir(), [current.gameId, `${newEntityType}s`, newEntityId], `${imageId}.${ext}`);
+            newFilePath = moved.relativePath;
+            const newFullPath = moved.fullPath;
             // Ensure new directory exists
             ensureDir(dirname(newFullPath));
             // Move the file
@@ -411,8 +416,10 @@ export function updateImageMetadata(imageId, updates) {
 // Cleanup helper - delete all images for a game
 export function deleteGameImages(gameId) {
     const db = getDatabase();
-    // Delete files
-    const sessionDir = join(getImagesDir(), gameId);
+    // Delete files. mediaDirPath rejects before the rmSync below, which is
+    // recursive and forced: an unchecked `..` here would take the whole data
+    // directory with it.
+    const sessionDir = mediaDirPath(getImagesDir(), [gameId]);
     if (existsSync(sessionDir)) {
         rmSync(sessionDir, { recursive: true, force: true });
     }

package/dist/tools/resource.d.ts

@@ -1,7 +1,7 @@
 import type { Resource, ResourceChange } from "../types/index.js";
 export declare function createResource(params: {
     gameId: string;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     ownerId?: string;
     name: string;
     description?: string;
@@ -20,7 +20,7 @@ export declare function updateResource(id: string, updates: {
 }): Resource | null;
 export declare function deleteResource(id: string): boolean;
 export declare function listResources(gameId: string, filter?: {
-    ownerType?: "game" | "character";
+    ownerType?: "game" | "character" | "faction" | "location";
     ownerId?: string;
     category?: string;
 }): Resource[];

package/dist/tools/time.js

@@ -133,9 +133,24 @@ export function advanceTime(gameId, duration) {
     const consequenceFailures = [];
     for (const row of events) {
         const triggerTime = safeJsonParse(row.trigger_time, { year: 1, month: 1, day: 1, hour: 0, minute: 0 });
-        // Check if event should trigger (trigger time is between previous and new time)
-        if (compareDateTime(triggerTime, previousTime, calendarConfig) >= 0 &&
-            compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
+        // Due if the trigger time has been reached -- deliberately NOT also gated
+        // on `triggerTime >= previousTime`.
+        //
+        // That lower bound looks like the right window ("did we cross it on THIS
+        // call?") and quietly broke the retry the catch block below promises. When
+        // a consequence throws, the transaction rolls back and the row stays
+        // pending, exactly as intended -- but the clock has already moved past
+        // triggerTime by then, because it is updated unconditionally above. On
+        // every subsequent call the lower bound therefore excluded the row, and
+        // the event sat pending forever with its consequence never applied. The
+        // rollback was correct and unreachable.
+        //
+        // Without the lower bound, "pending and past due" is the whole condition,
+        // which is the same retry semantics timers already have. The `triggered =
+        // 0` filter in the query above is what keeps this exactly-once: a
+        // successful event is marked (or, if recurring, rescheduled forward) in
+        // the same transaction as its consequence, so it cannot come back.
+        if (compareDateTime(triggerTime, newTime, calendarConfig) <= 0) {
             const eventId = row.id;
             const eventName = row.name;
             const recurring = row.recurring;

package/dist/types/index.d.ts

@@ -465,7 +465,7 @@ export interface Resource {
     id: string;
     gameId: string;
     ownerId: string | null;
-    ownerType: "game" | "character";
+    ownerType: "game" | "character" | "faction" | "location";
     name: string;
     description: string;
     category: string | null;

package/dist/utils/media-path.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export declare class MediaPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export declare function mediaPathWithin(root: string, relativePath: string): string;
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export declare function mediaFilePath(root: string, segments: string[], filename: string): {
+    relativePath: string;
+    fullPath: string;
+};
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export declare function mediaDirPath(root: string, segments: string[]): string;

package/dist/utils/media-path.js

@@ -0,0 +1,106 @@
+import { isAbsolute, join, resolve, sep } from "path";
+import { createLogger } from "./logger.js";
+const log = createLogger("media-path");
+/**
+ * The one place a path beneath a media root is composed or resolved.
+ *
+ * Media file paths are built from ids that arrive over the wire -- a game id,
+ * an entity id, an entity type -- and are then handed to `writeFileSync` and,
+ * worse, to a recursive `rmSync`. `join()` resolves `..` happily, so an id
+ * carrying one walks out of the data directory before the write. The rule this
+ * breaks is the engine's: it writes nothing to the consumer's machine that the
+ * consumer did not name.
+ *
+ * The guard is here, at the composition point, rather than at each call site,
+ * because a per-site check is one forgotten site away from being no check. Two
+ * things are asserted, and both are literal checks over characters -- never an
+ * attempt to read meaning out of a value (root CLAUDE.md hard rule 4):
+ *
+ *   1. Every path segment matches an allowlist. Every id the engine mints is a
+ *      UUID and every entity type is an ASCII word, so the allowlist costs
+ *      nothing the engine actually uses.
+ *   2. The resolved result is strictly beneath the resolved root -- a
+ *      structural backstop that holds even for a path this module did not
+ *      compose, such as one read back out of a row written before this guard
+ *      existed.
+ *
+ * Rejection, never normalisation: an id containing `a/../b` is refused rather
+ * than quietly rewritten to `b`, because the rewrite would silently store one
+ * caller's media under a different id than the caller named.
+ */
+export class MediaPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaPathError";
+    }
+}
+/** Directory names: ids the engine mints, plus pluralised entity types. */
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** Leaf file names: a safe stem, one dot, an alphanumeric extension. */
+const SAFE_FILENAME = /^[A-Za-z0-9_-]+\.[A-Za-z0-9]+$/;
+function reject(what, value) {
+    log.warn("Refused a media path built from an unsafe value", { what, value });
+    throw new MediaPathError(`Unsafe ${what} for a media path: ${JSON.stringify(value)}. ` +
+        `Only letters, digits, underscore and hyphen are allowed; a path separator, ` +
+        `"." or ".." would escape the media directory.`);
+}
+function assertSafeSegment(value) {
+    if (typeof value !== "string" || !SAFE_SEGMENT.test(value)) {
+        reject("path segment", String(value));
+    }
+}
+/**
+ * Resolve a relative path against a media root, refusing anything that is not
+ * strictly beneath it. Use for paths read back from a row; `mediaFilePath` and
+ * `mediaDirPath` funnel through it too, so every media path in the codebase
+ * passes this check exactly once.
+ */
+export function mediaPathWithin(root, relativePath) {
+    if (typeof relativePath !== "string" || relativePath.length === 0) {
+        reject("stored path", String(relativePath));
+    }
+    if (isAbsolute(relativePath)) {
+        reject("stored path", relativePath);
+    }
+    // Split on both separators regardless of platform: a stored path composed on
+    // one and read on another must not sneak a traversal past the check.
+    for (const segment of relativePath.split(/[\\/]/)) {
+        if (segment.length === 0 || segment === "." || segment === "..") {
+            reject("stored path", relativePath);
+        }
+    }
+    const rootResolved = resolve(root);
+    const fullPath = resolve(rootResolved, relativePath);
+    // Compare with the separator appended, so a sibling directory whose name
+    // merely starts with the root's (`<root>-elsewhere`) is not mistaken for a
+    // child of it.
+    if (!fullPath.startsWith(rootResolved + sep)) {
+        reject("stored path", relativePath);
+    }
+    return fullPath;
+}
+/**
+ * Compose the path of a media file from segments and a leaf file name,
+ * returning both the relative path to store in the row and the full path to
+ * write to.
+ */
+export function mediaFilePath(root, segments, filename) {
+    segments.forEach(assertSafeSegment);
+    if (typeof filename !== "string" || !SAFE_FILENAME.test(filename)) {
+        reject("file name", String(filename));
+    }
+    const relativePath = join(...segments, filename);
+    return { relativePath, fullPath: mediaPathWithin(root, relativePath) };
+}
+/**
+ * Compose the path of a directory beneath a media root. The caller of this one
+ * is a recursive delete, so an empty segment list -- which would resolve to the
+ * media root itself -- is refused along with everything else.
+ */
+export function mediaDirPath(root, segments) {
+    if (segments.length === 0) {
+        reject("path segment", "");
+    }
+    segments.forEach(assertSafeSegment);
+    return mediaPathWithin(root, join(...segments));
+}