run-dmcp 0.1.0 → 0.2.0

package/dist/utils/webui.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Port the web UI listens on when nothing says otherwise.
+ */
+export declare const DEFAULT_HTTP_PORT = 3456;
+/**
+ * Which port the web UI should listen on, read from an environment rather than
+ * from the ambient process, so the answer can be tested from a value.
+ *
+ * An out-of-range or unparseable DMCP_HTTP_PORT falls back to the default. The
+ * inherited code did `parseInt(value || "3456", 10)` and handed the NaN
+ * straight to `listen()`, which quietly bound a random port instead -- an
+ * operator who mistyped a port got a working server on an address they could
+ * not predict. `0` is kept, because that is the real way to ask for any free
+ * port.
+ */
+export declare function httpPortFromEnv(env?: NodeJS.ProcessEnv): number;
+/**
+ * Whether the executable should serve the web UI.
+ *
+ * The web UI is an application's feature, not a library's: a process that only
+ * needs the engine has no use for an admin page, and one that starts a server
+ * squats a port and cannot exit. Importing this package therefore starts
+ * nothing at all (see src/index.ts), and the shipped executable serves the
+ * web UI by default -- unless DMCP_NO_HTTP says not to, which is what a host
+ * that spawns this as an MCP subprocess sets for it.
+ *
+ * `0`, `false` and an empty value leave it on, because a launcher that writes
+ * `DMCP_NO_HTTP=${disabled ? 1 : 0}` means the web UI to run when it writes 0.
+ * These are literal tokens in a variable this project defines, not an attempt
+ * to read intent out of prose.
+ */
+export declare function webUiEnabled(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Set the actual HTTP port after server starts
  */

package/dist/utils/webui.js

@@ -1,3 +1,56 @@
+import { createLogger } from "./logger.js";
+const log = createLogger("webui");
+/**
+ * Port the web UI listens on when nothing says otherwise.
+ */
+export const DEFAULT_HTTP_PORT = 3456;
+/**
+ * Which port the web UI should listen on, read from an environment rather than
+ * from the ambient process, so the answer can be tested from a value.
+ *
+ * An out-of-range or unparseable DMCP_HTTP_PORT falls back to the default. The
+ * inherited code did `parseInt(value || "3456", 10)` and handed the NaN
+ * straight to `listen()`, which quietly bound a random port instead -- an
+ * operator who mistyped a port got a working server on an address they could
+ * not predict. `0` is kept, because that is the real way to ask for any free
+ * port.
+ */
+export function httpPortFromEnv(env = process.env) {
+    const raw = env.DMCP_HTTP_PORT;
+    if (!raw)
+        return DEFAULT_HTTP_PORT;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        log.warn("DMCP_HTTP_PORT is not a port number; using the default", {
+            value: raw,
+            default: DEFAULT_HTTP_PORT,
+        });
+        return DEFAULT_HTTP_PORT;
+    }
+    return port;
+}
+/**
+ * Whether the executable should serve the web UI.
+ *
+ * The web UI is an application's feature, not a library's: a process that only
+ * needs the engine has no use for an admin page, and one that starts a server
+ * squats a port and cannot exit. Importing this package therefore starts
+ * nothing at all (see src/index.ts), and the shipped executable serves the
+ * web UI by default -- unless DMCP_NO_HTTP says not to, which is what a host
+ * that spawns this as an MCP subprocess sets for it.
+ *
+ * `0`, `false` and an empty value leave it on, because a launcher that writes
+ * `DMCP_NO_HTTP=${disabled ? 1 : 0}` means the web UI to run when it writes 0.
+ * These are literal tokens in a variable this project defines, not an attempt
+ * to read intent out of prose.
+ */
+export function webUiEnabled(env = process.env) {
+    const raw = env.DMCP_NO_HTTP;
+    if (!raw)
+        return true;
+    const value = raw.trim().toLowerCase();
+    return value === "0" || value === "false";
+}
 /**
  * Actual port the HTTP server is running on (set at runtime)
  */
@@ -12,7 +65,7 @@ export function setHttpPort(port) {
  * Get the base URL for the HTTP web UI
  */
 export function getWebUiBaseUrl() {
-    const port = actualHttpPort ?? parseInt(process.env.DMCP_HTTP_PORT || "3456", 10);
+    const port = actualHttpPort ?? httpPortFromEnv();
     return `http://localhost:${port}`;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-dmcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An MCP server for LLM-run interactive fiction where the server owns what is true - including when it was true. A continuation of DMCP.",
   "license": "MIT",
   "author": "Derek Ferguson",
@@ -10,15 +10,27 @@
   },
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rpg": {
+      "types": "./dist/rpg/index.d.ts",
+      "default": "./dist/rpg/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "run-dmcp": "dist/index.js"
+    "run-dmcp": "dist/bin/run-dmcp.js"
   },
   "scripts": {
     "build": "tsc && npm run build:client",
     "build:server": "tsc",
     "build:client": "cd client && npm run build",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
+    "start": "node dist/bin/run-dmcp.js",
+    "dev": "tsx src/bin/run-dmcp.ts",
     "dev:client": "cd client && npm run dev",
     "test": "vitest",
     "test:run": "vitest run",
@@ -69,6 +81,10 @@
   ],
   "files": [
     "dist/",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*",
+    "!dist/test-setup.*",
     "README.md",
     "LICENSE"
   ]

package/dist/__tests__/engineVocabulary.test.d.ts

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

package/dist/__tests__/engineVocabulary.test.js

@@ -1,147 +0,0 @@
-// No client's vocabulary reaches the engine.
-//
-// run-dmcp exists to serve more than one piece of interactive fiction. Two
-// consumers were in the room when it was designed and they are deliberately
-// unlike each other: a geopolitical roleplay whose world advances one turn at a
-// time, and a music-video pipeline whose units have duration and no player at
-// all. Neither may become the reason the engine exists.
-//
-// That intention cannot survive as a rule people remember. The predecessor's
-// own history shows why: `resource_history` and `relationship_history` were
-// added because somebody needed them, and nothing generalised the idea, so the
-// concept of versioning existed for exactly two tables for the life of the
-// project. Good intentions do not generalise; tests do.
-//
-// So the line is a test. It runs in CI on every push, against the actual
-// tracked file list, and it fails when a specific client's language appears in
-// the engine — which is the first observable symptom of "engine with two
-// consumers" decaying into "one client's library with a second bolted on".
-//
-// WHAT THIS IS NOT: a check that the engine is free of narrative vocabulary.
-// Dice, combat, quests and factions are inherited and generic — they belong to
-// the RPG layer above the core, not to any one client. The forbidden list is
-// specifically the vocabulary of the two named consumers, plus terms that could
-// only have come from one of them.
-//
-// WHERE FIXTURES COME FROM: grain, treasury, population. A throwaway vocabulary
-// for exercising the mechanism, never a starter set anyone should build on.
-import { describe, it, expect } from "vitest";
-import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { resolve, basename } from "node:path";
-const REPO_ROOT = resolve(__dirname, "..", "..");
-/**
- * The design brief is excluded, and only it.
- *
- * That document's entire job is to explain where the boundary between engine
- * and consumer falls, and it cannot do that without naming the consumers on
- * either side of it. Excluding the explanation of a rule is not a hole in the
- * rule. Excluding anything else would be.
- */
-const EXCLUDED_PATHS = new Set(["docs/DESIGN.md"]);
-function scannedFiles() {
-    return execFileSync("git", ["ls-files"], { cwd: REPO_ROOT, encoding: "utf8" })
-        .split("\n")
-        .filter(Boolean)
-        .filter((f) => !EXCLUDED_PATHS.has(f))
-        .filter((f) => basename(f) !== "engineVocabulary.test.ts")
-        .filter((f) => !/package-lock\.json$/.test(f))
-        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|svg|woff2?|ttf|otf|mp3|wav|onnx|pth|bin)$/i.test(f));
-}
-/**
- * Each entry carries why, because a bare list of forbidden words is exactly the
- * thing a future contributor deletes when it gets in their way.
- *
- * Note the shapes chosen. `\baccords?\b` and not `\baccord` — the latter also
- * matches "accordance" and "according", which are ordinary English. `chunk_id`
- * and not `chunk` — a chunked read is a legitimate generic idea. No bare
- * `shot`: the tree already says "in one shot" and `"wide shot"` as an image
- * framing, both of which are fine. A rule that cries wolf gets deleted, and
- * then it is protecting nothing.
- */
-const FORBIDDEN = [
-    {
-        pattern: /\bDEFCON\b/i,
-        what: "a consumer's escalation ladder",
-        why: "one game's bounded resource. The engine has `bounded` constraints; it has never heard of a ladder.",
-    },
-    {
-        pattern: /\bprestige\b/i,
-        what: "a consumer's conserved resource",
-        why: "the engine offers conserved resource SETS. Which resource is conserved, and among whom, is the game's.",
-    },
-    {
-        pattern: /\bflashpoints?\b/i,
-        what: "a consumer's contested location",
-        why: "the engine has entities and locations. 'Flashpoint' is a geopolitical reading of one.",
-    },
-    {
-        pattern: /\bcohesion\b/i,
-        what: "a consumer's per-location scalar",
-        why: "a resource on a location. The name belongs to the game that decided what it measures.",
-    },
-    {
-        pattern: /\bcompellence\b|\bARMED_STRIKE\b|\bPRESTIGE_CONTEST\b|\bFLASHPOINT_SEIZURE\b/,
-        what: "a consumer's mechanic names",
-        why: "mechanics are registered BY a game (design §5.2a). The engine dispatches them and never learns what they mean.",
-    },
-    {
-        pattern: /\baccords?\b/i,
-        what: "a consumer's negotiated agreement",
-        why: "the engine has facts with obligations. 'Accord' is one game's word for a bundle of them.",
-    },
-    {
-        pattern: /\bseats?\b/i,
-        what: "a consumer's player positions",
-        why: "the engine has entities and (eventually) per-entity visibility. Seats are how one game partitions them.",
-    },
-    {
-        pattern: /\bcrises\b|\bcrisis\b/i,
-        what: "a consumer's timed pressure",
-        why: "the engine has scheduled events with on-expiry consequences. What makes one a crisis is the game's fiction.",
-    },
-    {
-        pattern: /\blyrics?\b|\bchorus\b|\bverses?\b|\bstoryboards?\b/i,
-        what: "the other consumer's source material",
-        why: "the engine renders state at t. That the state was authored against a song is not its business.",
-    },
-    {
-        pattern: /\bchunk_id\b|\bchunkId\b|\bshot_id\b|\bshotId\b|\bshot lines?\b/i,
-        what: "the other consumer's unit identifiers",
-        why: "and these are the ones that must never appear, because that client's own rule is that an index " +
-            "into re-segmentable units is the wrong axis (design §5.1). The engine takes `t`, never a unit id.",
-    },
-    {
-        pattern: /\bgeopolitic(s|al)\b/i,
-        what: "the domain of one consumer",
-        why: "if the engine describes itself by one client's genre, the second client is already a guest.",
-    },
-];
-describe("no client's vocabulary reaches the engine", () => {
-    const files = scannedFiles();
-    it("scans a meaningful number of tracked files (guard against a vacuous pass)", () => {
-        expect(files.length).toBeGreaterThan(50);
-    });
-    it.each(FORBIDDEN)("contains no $what", ({ pattern, why }) => {
-        const offenders = [];
-        for (const file of files) {
-            let contents;
-            try {
-                contents = readFileSync(resolve(REPO_ROOT, file), "utf8");
-            }
-            catch {
-                continue;
-            }
-            contents.split("\n").forEach((line, i) => {
-                if (pattern.test(line))
-                    offenders.push(`${file}:${i + 1}: ${line.trim().slice(0, 100)}`);
-            });
-        }
-        expect(offenders, `${why}\n\n${offenders.join("\n")}`).toEqual([]);
-    });
-    it("keeps the design brief excluded, and nothing else", () => {
-        // If this list ever grows, the rule is being routed around rather than
-        // enforced. One exclusion, for the document that explains the rule.
-        expect([...EXCLUDED_PATHS]).toEqual(["docs/DESIGN.md"]);
-    });
-});

package/dist/db/__tests__/connection.test.d.ts

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

package/dist/db/__tests__/connection.test.js

@@ -1,72 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { createTestDb, destroyTestDb } from './testDb.js';
-import { withTransaction, getDatabase } from '../connection.js';
-import { createGame } from '../../tools/game.js';
-import { createResource, getResource } from '../../tools/resource.js';
-describe('withTransaction', () => {
-    let gameId;
-    beforeEach(() => {
-        createTestDb();
-        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
-    });
-    afterEach(() => {
-        destroyTestDb();
-    });
-    it('commits all writes performed inside the callback when it succeeds', () => {
-        const result = withTransaction(() => {
-            const a = createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
-            const b = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 2 });
-            return { a, b };
-        });
-        expect(getResource(result.a.id)?.value).toBe(1);
-        expect(getResource(result.b.id)?.value).toBe(2);
-    });
-    it('returns the callback return value', () => {
-        const value = withTransaction(() => 42);
-        expect(value).toBe(42);
-    });
-    it('rolls back every write in the callback when it throws, leaving no partial writes', () => {
-        const first = createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
-        expect(() => {
-            withTransaction(() => {
-                // This write should succeed at the SQLite level...
-                createResource({ gameId, ownerType: 'game', name: 'treasury', value: 2 });
-                // ...but the transaction as a whole should never commit because of this throw.
-                throw new Error('boom');
-            });
-        }).toThrow('boom');
-        // The pre-existing resource is untouched.
-        expect(getResource(first.id)?.value).toBe(1);
-        // The resource created inside the doomed transaction must not exist.
-        const db = getDatabase();
-        const rows = db.prepare('SELECT * FROM resources WHERE name = ?').all('treasury');
-        expect(rows).toHaveLength(0);
-    });
-    it('propagates the original error when rolling back', () => {
-        class CustomError extends Error {
-        }
-        expect(() => withTransaction(() => {
-            createResource({ gameId, ownerType: 'game', name: 'grain', value: 1 });
-            throw new CustomError('custom failure');
-        })).toThrow(CustomError);
-    });
-    it('rolls back a mid-operation failure across two dependent writes (debit/credit style)', () => {
-        const from = createResource({ gameId, ownerType: 'game', name: 'grain', value: 100 });
-        const to = createResource({ gameId, ownerType: 'game', name: 'treasury', value: 0 });
-        const shouldFailBeforeCredit = true;
-        expect(() => {
-            withTransaction(() => {
-                const db = getDatabase();
-                db.prepare('UPDATE resources SET value = value - 10 WHERE id = ?').run(from.id);
-                // Simulate a failure that happens after the first write but before the second.
-                if (shouldFailBeforeCredit) {
-                    throw new Error('credit step failed');
-                }
-                db.prepare('UPDATE resources SET value = value + 10 WHERE id = ?').run(to.id);
-            });
-        }).toThrow('credit step failed');
-        // Neither side of the transfer should have taken effect.
-        expect(getResource(from.id)?.value).toBe(100);
-        expect(getResource(to.id)?.value).toBe(0);
-    });
-});

package/dist/db/__tests__/testDb.d.ts

@@ -1,33 +0,0 @@
-import type Database from "better-sqlite3";
-/**
- * Test fixture: gives each test a clean, fully migrated, isolated SQLite
- * database, backed by an in-memory database rather than a file on disk.
- *
- * Why this is needed: `getDatabase()` in `src/db/connection.ts` caches a
- * single database handle at module scope. Without resetting it, every test
- * in a process would share one connection and bleed state into each other.
- *
- * Usage:
- *   let db: Database.Database;
- *   beforeEach(() => {
- *     db = createTestDb();
- *   });
- *   afterEach(() => {
- *     destroyTestDb();
- *   });
- *
- * Call `destroyTestDb()` in `afterEach` (not just before the next
- * `createTestDb()`) so a failed/skipped test doesn't leak its connection
- * into whichever test happens to run next.
- */
-export declare function createTestDb(): Database.Database;
-/**
- * Tears down the database created by `createTestDb()`.
- *
- * Deliberately does NOT delete `DMCP_DB_PATH`. `src/test-setup.ts` sets it
- * process-wide as a safety net so that any `getDatabase()` call -- including
- * one made outside this fixture, e.g. at module scope in a test file -- can
- * never open the real on-disk database. Clearing it here would punch a hole
- * in that net for every test that ran after the first teardown.
- */
-export declare function destroyTestDb(): void;

package/dist/db/__tests__/testDb.js

@@ -1,41 +0,0 @@
-import { closeDatabase, getDatabase } from "../connection.js";
-import { initializeSchema } from "../schema.js";
-/**
- * Test fixture: gives each test a clean, fully migrated, isolated SQLite
- * database, backed by an in-memory database rather than a file on disk.
- *
- * Why this is needed: `getDatabase()` in `src/db/connection.ts` caches a
- * single database handle at module scope. Without resetting it, every test
- * in a process would share one connection and bleed state into each other.
- *
- * Usage:
- *   let db: Database.Database;
- *   beforeEach(() => {
- *     db = createTestDb();
- *   });
- *   afterEach(() => {
- *     destroyTestDb();
- *   });
- *
- * Call `destroyTestDb()` in `afterEach` (not just before the next
- * `createTestDb()`) so a failed/skipped test doesn't leak its connection
- * into whichever test happens to run next.
- */
-export function createTestDb() {
-    process.env.DMCP_DB_PATH = ":memory:";
-    const db = getDatabase();
-    initializeSchema();
-    return db;
-}
-/**
- * Tears down the database created by `createTestDb()`.
- *
- * Deliberately does NOT delete `DMCP_DB_PATH`. `src/test-setup.ts` sets it
- * process-wide as a safety net so that any `getDatabase()` call -- including
- * one made outside this fixture, e.g. at module scope in a test file -- can
- * never open the real on-disk database. Clearing it here would punch a hole
- * in that net for every test that ran after the first teardown.
- */
-export function destroyTestDb() {
-    closeDatabase();
-}

package/dist/test-setup.d.ts

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

package/dist/test-setup.js

@@ -1,13 +0,0 @@
-// Vitest setupFiles entry (see vitest.config.ts): a process-wide safety net
-// guaranteeing no test can ever open the real on-disk database.
-//
-// `getDatabase()` resolves DMCP_DB_PATH lazily, so the per-test fixture in
-// src/db/__tests__/testDb.ts is normally sufficient. This exists for the
-// cases the fixture cannot cover -- a `getDatabase()` reached at module scope,
-// or from code a test imports before its own `beforeEach` runs. A setupFiles
-// module is imported before the test file itself, so this lands first.
-//
-// Nothing should ever `delete` this env var mid-run; doing so re-opens the
-// hole for every subsequent test.
-process.env.DMCP_DB_PATH = ":memory:";
-export {};

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

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

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

@@ -1,59 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { v4 as uuidv4 } from 'uuid';
-import { createTestDb, destroyTestDb } from '../../db/__tests__/testDb.js';
-import { getDatabase } from '../../db/connection.js';
-import { createGame } from '../game.js';
-import { createCharacter } from '../character.js';
-import { getAudio, setPrimaryAudio } from '../audio.js';
-// Inserts a stored_audio row directly via SQL so these tests can exercise
-// setPrimaryAudio() without going through storeAudio()'s file I/O / network
-// fetch, which is unrelated to the atomicity behavior under test here.
-function insertStoredAudio(params) {
-    const db = getDatabase();
-    const id = uuidv4();
-    db.prepare(`
-    INSERT INTO stored_audio (id, game_id, entity_id, entity_type, file_path, file_size, mime_type, source, is_primary, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(id, params.gameId, params.entityId, params.entityType, `${id}.mp3`, 100, 'audio/mpeg', 'uploaded', params.isPrimary ? 1 : 0, new Date().toISOString());
-    return id;
-}
-describe('setPrimaryAudio', () => {
-    let gameId;
-    let characterId;
-    beforeEach(() => {
-        createTestDb();
-        gameId = createGame({ name: 'Test Game', setting: 'Test Setting', style: 'Test Style' }).id;
-        characterId = createCharacter({ gameId, name: 'Narrator', isPlayer: false }).id;
-    });
-    afterEach(() => {
-        destroyTestDb();
-    });
-    it('unsets the previous primary and sets the new one', () => {
-        const first = insertStoredAudio({ gameId, entityId: characterId, entityType: 'character', isPrimary: true });
-        const second = insertStoredAudio({ gameId, entityId: characterId, entityType: 'character', isPrimary: false });
-        setPrimaryAudio(second);
-        expect(getAudio(first)?.isPrimary).toBe(false);
-        expect(getAudio(second)?.isPrimary).toBe(true);
-    });
-    it('leaves NO partial write when the second update fails mid-operation: the old primary stays primary', () => {
-        const first = insertStoredAudio({ gameId, entityId: characterId, entityType: 'character', isPrimary: true });
-        const second = insertStoredAudio({ gameId, entityId: characterId, entityType: 'character', isPrimary: false });
-        // Fault injection: make the UPDATE that sets `second` as primary fail,
-        // simulating a mid-operation failure between the unset and the set.
-        const db = getDatabase();
-        db.exec(`
-      CREATE TRIGGER fail_set_new_primary_audio
-      BEFORE UPDATE ON stored_audio
-      WHEN NEW.id = '${second}' AND NEW.is_primary = 1
-      BEGIN
-        SELECT RAISE(ABORT, 'simulated failure');
-      END;
-    `);
-        expect(() => setPrimaryAudio(second)).toThrow();
-        // Without a real transaction, the first UPDATE (unsetting `first`)
-        // would have already committed, leaving NO primary at all. With a
-        // transaction, `first` must still be primary.
-        expect(getAudio(first)?.isPrimary).toBe(true);
-        expect(getAudio(second)?.isPrimary).toBe(false);
-    });
-});

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

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