run-dmcp 0.1.0 → 0.3.0

package/README.md

@@ -12,21 +12,110 @@ holds full adjudication discretion over a world that only ever stores *now*.
 
 ## Status
 
-**0.1.0 — the foundation, not the thesis.** What ships today is the predecessor's engine plus four
-pieces of generic mechanism that were built for it and offered back to it:
+**0.3.0.** The base is the predecessor's engine plus four pieces of generic mechanism that were built
+for it and offered back to it:
 
 - **Atomicity** — `withTransaction()` wired into the multi-write operations that were running
   non-atomically.
-- **Declarative constraints** — resources can be declared `bounded`, `monotonic` or `resolve_only`,
-  and the store enforces it rather than trusting every caller.
+- **Declarative constraints** — resources can be declared `bounded` or `monotonic`, and the store
+  enforces it rather than trusting every caller. `resolve_only` — every direct write rejected, so a
+  value can move only through an adjudicating call — joined them alongside the resolve protocol, and
+  is enforced by a trigger rather than by a checker anyone has to remember to call; see
+  [docs/DESIGN.md](docs/DESIGN.md) §5.2a.
 - **Conserved resource sets** — a set of resources can be declared conserved, with an atomic transfer
   that never silently clamps.
 - **On-expiry consequences** — scheduled events and timers can carry a consequence that actually
   lands when they expire, rather than expiring into nothing.
 
+0.1.1 added the packaging half of that: importing the library starts nothing, the database resolves
+to the consuming application rather than into `node_modules`, and a consumer can bring up its own
+tables through the migration hook below. 0.3.0 adds the consuming half — the entity/property spine is
+exported as library functions, so a consumer that deletes its own vendored copy has something to
+import rather than a server to make tool calls into.
+
 The timeline that gives this project its reason to exist — interval-versioned facts, `replay(t)`,
-irreversibility, `changes_within` — is designed and accepted but **not yet built**. See
-[docs/DESIGN.md](docs/DESIGN.md), which is the authority, and §11 for the order things land in.
+irreversibility, timeline export, `changes_within` — is built, and every write of world state appends
+to it in the same transaction, through generated triggers rather than edited write sites.
+
+**There is one versioning substrate, and it is the timeline.** A resource's value is a constrained
+numeric fact: declared constraints (`bounded`, `monotonic`, conserved sets, `irreversible`) are
+checked at a single choke point, and "what did this value used to be" is answered by the fact
+intervals rather than by a history table beside them. The former `resource_history` and
+`relationship_history` tables no longer accept writes. See [docs/DESIGN.md](docs/DESIGN.md), which is
+the authority, §5.4 for that decision and §11 for the order the rest lands in.
+
+## Running it, and depending on it
+
+These are two different things, and the package keeps them apart.
+
+**As an application** — `run-dmcp` (or `node dist/bin/run-dmcp.js`) serves MCP over stdio and the web
+UI alongside it. `DMCP_HTTP_PORT` moves the web UI; `DMCP_NO_HTTP=1` turns it off entirely, which is
+what a host that spawns this as a subprocess wants: a referee has no use for an admin page, and a
+server it cannot close squats a port.
+
+**As a dependency** — importing the package starts nothing. No listener, no database file, no work at
+all: the entry point is exports, and the application lives behind `bin`. A consumer decides when the
+schema comes up, where the database lives, and whether anything listens.
+
+**The package root is the core, and the tabletop surface is a layer above it.** Dice, combat,
+abilities, status effects, random tables and quests are genuinely game-shaped — an optional
+dependency, not part of the engine (see [docs/DESIGN.md](docs/DESIGN.md) §8). A consumer that only
+needs entities, facts, events and the timeline imports `run-dmcp` and calls `createCoreMcpServer`. A
+consumer that wants the full tabletop surface imports `run-dmcp/rpg` and calls `createMcpServer` —
+same name, same options, the whole assembly this package has always served:
+
+```ts
+import { initializeSchema, type SchemaMigration } from "run-dmcp";
+import { createMcpServer } from "run-dmcp/rpg";
+
+const migrations: SchemaMigration[] = [
+  {
+    name: "my-tables",
+    up(db) {
+      db.exec(`CREATE TABLE IF NOT EXISTS my_table (id TEXT PRIMARY KEY)`);
+      try {
+        db.exec(`ALTER TABLE my_table ADD COLUMN added_later TEXT`);
+      } catch {
+        // Already added -- migrations run on every startup, so they must be idempotent.
+      }
+    },
+  },
+];
+
+initializeSchema({ migrations });   // engine tables first, then yours, one pass, one database
+const server = createMcpServer();   // built, not started -- connect it to a transport yourself
+```
+
+The hook is a parameter rather than a global `register()` because a parameter cannot be registered
+too late to run. There is no framework behind it: no version table, no record of what already ran, no
+down-migrations. Every migration runs on every startup, exactly like the engine's own DDL — which is
+what forces them to be idempotent, and it is tested against an existing database, not just a fresh
+one.
+
+The database lands in the consuming application: `DMCP_DB_PATH` if set, else an existing
+`~/.local/share/dmcp`, else `./data/games.db` relative to the working directory. Never inside the
+installed package.
+
+**The spine is importable, not only callable over a transport.** Games, locations, characters,
+factions, relationships, resources, secrets, items, notes, tags, time and timers are library
+functions first and MCP tools second, so a consumer reads and writes its own world directly and only
+serves the tools it actually wants an LLM to reach. That includes the constrained-write choke point:
+a number that moves through `updateResourceValue` is checked against its declared constraints and its
+history is `facts`, queryable with `valueHistory`.
+
+```ts
+import { createGame, createResource, updateResourceValue, valueHistory } from "run-dmcp";
+
+const game = createGame({ name: "The Granary", setting: "…", style: "…" });
+const grain = createResource({ gameId: game.id, ownerType: "game", name: "grain", value: 100 });
+
+updateResourceValue({ resourceId: grain.id, mode: "delta", value: -30, reason: "the winter ration" });
+valueHistory(grain.id, "value"); // → the transitions, with the reason each one carried
+```
+
+The annotations, input limits, error envelope and logger the engine's own tools are built from are
+exported too (`ANNOTATIONS`, `LIMITS`, `errors`, `createLogger`), so a consumer's own tools can
+refuse and bound the way these do instead of re-implementing it.
 
 ## Provenance
 
@@ -35,9 +124,10 @@ commit was 2026-01-06. This repository carries its full history rather than a sq
 first commit here is his, from 2025-12-30.
 
 It is **not** a GitHub fork, deliberately — a repository inside another's fork network is discoverable
-only as "a fork of" and cannot own its issue tracker. The four offers listed above stand as open pull
-requests against the original and remain valid there; they are merged here because this project
-cannot wait on a repository that has not moved in seven months.
+only as "a fork of" and cannot own its issue tracker. The four offers listed above were opened as pull
+requests against the original ([#6](https://github.com/shawnrushefsky/dmcp/pull/6)–[#9](https://github.com/shawnrushefsky/dmcp/pull/9))
+and withdrawn on 2026-08-18 after seven months without a maintainer response; they are merged here
+instead. Their diffs remain readable upstream at `refs/pull/6..9/head`.
 
 MIT, and his copyright notice travels with the code. See [LICENSE](LICENSE).
 
@@ -67,12 +157,12 @@ npm run typecheck     # tsc --noEmit
 npm run test:run      # vitest, one shot
 npm run build         # tsc + client build
 
-npm run dev           # tsx src/index.ts
+npm run dev           # tsx src/bin/run-dmcp.ts
 ```
 
 CI runs lint, typecheck, tests and build on every push, for both the server and the client.
 
-Local MCP inspection: `npx @modelcontextprotocol/inspector node dist/index.js`
+Local MCP inspection: `npx @modelcontextprotocol/inspector node dist/bin/run-dmcp.js`
 
 ## License
 

package/dist/bin/run-dmcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/run-dmcp.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// The application.
+//
+// Everything this file does to the machine -- create the database, bind a
+// port, hold stdio open until it is killed -- is exactly what a library must
+// not do on import, which is why it lives here and not in src/index.ts. The
+// package's `bin` points at this file; the package's `main` points at the
+// library, which starts nothing.
+//
+// The web UI runs by default, as it always has. DMCP_NO_HTTP turns it off, for
+// a host that spawns this as an MCP subprocess and has no use for an admin
+// page it cannot close.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { closeDatabase } from "../db/connection.js";
+import { initializeSchema } from "../db/schema.js";
+import { startHttpServer } from "../http/server.js";
+// The full assembly -- core plus the RPG layer -- now lives one layer up
+// (design §8, issue #17). The application always served the full surface,
+// so it reaches for it here rather than the core-only `createCoreMcpServer`
+// in ../mcp-server.js.
+import { createMcpServer } from "../rpg/index.js";
+import { httpPortFromEnv, setHttpPort, webUiEnabled } from "../utils/webui.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("bin");
+async function main() {
+    // An application owns its database, so this is where the schema is brought
+    // up -- not at import time, and not in any module a consumer might load.
+    initializeSchema();
+    const server = createMcpServer();
+    if (webUiEnabled(process.env)) {
+        const actualPort = await startHttpServer(httpPortFromEnv(process.env));
+        setHttpPort(actualPort);
+    }
+    else {
+        log.info("Web UI disabled by DMCP_NO_HTTP; no port will be bound");
+    }
+    // Start MCP server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Handle cleanup
+process.on("SIGINT", () => {
+    closeDatabase();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    closeDatabase();
+    process.exit(0);
+});
+main().catch((error) => {
+    log.error("Server error", { error: error instanceof Error ? error.message : String(error) });
+    console.error(error);
+    closeDatabase();
+    process.exit(1);
+});

package/dist/db/connection.d.ts

@@ -1,4 +1,36 @@
 import Database from "better-sqlite3";
+export interface DataPathInputs {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    home: string;
+    exists: (path: string) => boolean;
+}
+/**
+ * Resolve database path with the following priority:
+ * 1. `env.DMCP_DB_PATH` -- the explicit path, wins over everything. Passed
+ *    through verbatim (including the literal ":memory:"), with
+ *    `dataDir = dirname(dbPath)`.
+ * 2. The XDG data directory -- `env.XDG_DATA_HOME || join(home, ".local",
+ *    "share")`, plus "/dmcp/games.db" -- but only when that directory
+ *    already exists. An existing `~/.local/share/dmcp` means a previous
+ *    install's data already lives there, and moving the default out from
+ *    under it would orphan someone's saved state.
+ * 3. Otherwise `join(cwd, "data", "games.db")` -- the CONSUMING
+ *    application's working directory. This is the fix for the "installed as
+ *    a dependency" bug: the default lands where the application runs, never
+ *    where the package is installed. `cwd` and `home` are supplied by the
+ *    caller (see `resolveDataPath` below) and the package's own install
+ *    location is never an input to this function, so it cannot resolve
+ *    there -- structurally, not by a runtime check.
+ *
+ * Pure and deterministically testable: no ambient reads (`process.env`,
+ * `process.cwd()`, `os.homedir()`) and no filesystem access except through
+ * the injected `exists`. See `src/db/__tests__/dataPath.test.ts`.
+ */
+export declare function resolveDataPathFrom(inputs: DataPathInputs): {
+    dataDir: string;
+    dbPath: string;
+};
 export declare function getDatabase(): Database.Database;
 export declare function closeDatabase(): void;
 /**

package/dist/db/connection.js

@@ -1,41 +1,63 @@
 import Database from "better-sqlite3";
-import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 import { mkdirSync, existsSync } from "fs";
 import { homedir } from "os";
 import { createLogger } from "../utils/logger.js";
 const log = createLogger("db");
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 /**
  * Resolve database path with the following priority:
- * 1. DMCP_DB_PATH environment variable (absolute path)
- * 2. XDG_DATA_HOME/dmcp/games.db (Linux/macOS standard)
- * 3. Fallback to ./data/games.db (relative to project)
+ * 1. `env.DMCP_DB_PATH` -- the explicit path, wins over everything. Passed
+ *    through verbatim (including the literal ":memory:"), with
+ *    `dataDir = dirname(dbPath)`.
+ * 2. The XDG data directory -- `env.XDG_DATA_HOME || join(home, ".local",
+ *    "share")`, plus "/dmcp/games.db" -- but only when that directory
+ *    already exists. An existing `~/.local/share/dmcp` means a previous
+ *    install's data already lives there, and moving the default out from
+ *    under it would orphan someone's saved state.
+ * 3. Otherwise `join(cwd, "data", "games.db")` -- the CONSUMING
+ *    application's working directory. This is the fix for the "installed as
+ *    a dependency" bug: the default lands where the application runs, never
+ *    where the package is installed. `cwd` and `home` are supplied by the
+ *    caller (see `resolveDataPath` below) and the package's own install
+ *    location is never an input to this function, so it cannot resolve
+ *    there -- structurally, not by a runtime check.
+ *
+ * Pure and deterministically testable: no ambient reads (`process.env`,
+ * `process.cwd()`, `os.homedir()`) and no filesystem access except through
+ * the injected `exists`. See `src/db/__tests__/dataPath.test.ts`.
  */
-function resolveDataPath() {
+export function resolveDataPathFrom(inputs) {
+    const { env, cwd, home, exists } = inputs;
     // Priority 1: Explicit environment variable
-    if (process.env.DMCP_DB_PATH) {
-        const dbPath = process.env.DMCP_DB_PATH;
+    if (env.DMCP_DB_PATH) {
+        const dbPath = env.DMCP_DB_PATH;
         const dataDir = dirname(dbPath);
         log.info("Using database path from DMCP_DB_PATH", { dbPath });
         return { dataDir, dbPath };
     }
-    // Priority 2: XDG Base Directory spec
-    const xdgDataHome = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+    // Priority 2: XDG Base Directory spec, only if it already exists
+    const xdgDataHome = env.XDG_DATA_HOME || join(home, ".local", "share");
     const xdgDataDir = join(xdgDataHome, "dmcp");
     const xdgDbPath = join(xdgDataDir, "games.db");
-    // Use XDG path if it exists or if we're not in a development context
-    if (existsSync(xdgDataDir) || !existsSync(join(__dirname, "..", "..", "package.json"))) {
+    if (exists(xdgDataDir)) {
         log.info("Using XDG data directory", { dbPath: xdgDbPath });
         return { dataDir: xdgDataDir, dbPath: xdgDbPath };
     }
-    // Priority 3: Fallback to project-relative path (development)
-    const fallbackDataDir = join(__dirname, "..", "..", "data");
+    // Priority 3: Fallback to the consuming application's working directory
+    const fallbackDataDir = join(cwd, "data");
     const fallbackDbPath = join(fallbackDataDir, "games.db");
-    log.debug("Using project-relative data directory", { dbPath: fallbackDbPath });
+    log.debug("Using cwd-relative data directory", { dbPath: fallbackDbPath });
     return { dataDir: fallbackDataDir, dbPath: fallbackDbPath };
 }
+/** Thin real-world wrapper around `resolveDataPathFrom`. */
+function resolveDataPath() {
+    return resolveDataPathFrom({
+        env: process.env,
+        cwd: process.cwd(),
+        home: homedir(),
+        exists: existsSync,
+    });
+}
 // Resolved lazily (on first getDatabase() call after startup, or after every
 // closeDatabase()) rather than once at module-import time. This makes
 // DMCP_DB_PATH re-readable at any point before the first real connection is

package/dist/db/schema.d.ts

@@ -1 +1,29 @@
-export declare function initializeSchema(): void;
+import type Database from "better-sqlite3";
+/**
+ * A schema change a consuming application wants applied to the same SQLite
+ * file the engine's own tables live in, during the engine's own startup
+ * pass. Passed as an array to `initializeSchema()`, not registered through
+ * a global function: a registry would make the engine's schema depend on
+ * module import order and on side effects at import time, which is exactly
+ * what this release is removing elsewhere. A parameter can't be "registered
+ * too late" -- it's either in the array passed to the one call that matters,
+ * or it isn't.
+ *
+ * There is no framework: no version table, no record of what already ran,
+ * no down-migrations. Every migration in the array runs on every startup,
+ * exactly like the engine's own DDL below, which is what forces `up` to be
+ * idempotent (`CREATE TABLE IF NOT EXISTS`, and
+ * `try { db.exec("ALTER TABLE ...") } catch {}` for added columns).
+ *
+ * Migrations run after every core table has been created, so `up` may
+ * declare a foreign key into one (e.g. `games`).
+ */
+export interface SchemaMigration {
+    /** Stable identifier. Used for duplicate detection and error messages. */
+    name: string;
+    /** Applies the migration. MUST be idempotent: it runs on every startup. */
+    up(db: Database.Database): void;
+}
+export declare function initializeSchema(options?: {
+    migrations?: readonly SchemaMigration[];
+}): void;