llm-chess-mcp 0.1.2 → 0.3.0

package/.env.example

@@ -0,0 +1,9 @@
+# Lichess opening explorer (optional; explorer tools disabled if unset)
+# Generate at https://lichess.org/account/oauth/token/create
+LICHESS_TOKEN=
+
+# The published package bundles only Maia3 5m (~20 MB). Leave at 5m.
+MAIA3_MODEL=5m
+
+# Stockfish flavor: lite-single (default, ~7MB) | lite | single | full
+STOCKFISH_FLAVOR=lite-single

package/README.md

@@ -13,14 +13,18 @@ judgment; the MCP server handles all the computation.
 | Engine | Role | Runtime |
 |---|---|---|
 | **Stockfish 18** (WASM) | Objective evaluation, best moves, multipv | In-process (npm `stockfish`) |
-| **Maia3** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
+| **Maia3 5M** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
 | **Lichess explorer** | Real human game statistics | HTTP (needs token) |
 
 Everything runs inside the Node process — no external engine process or Python
-runtime is required at deploy time. Maia3 is exported to ONNX once at build time.
+runtime is required at deploy time. The published package bundles the Maia3 5M
+model; other export variants are not runtime options unless their ONNX files are
+provided separately.
 
 ## Install
 
+Requires Node.js 20 or newer.
+
 No install needed — run it directly with `npx`:
 
 ```bash
@@ -41,6 +45,25 @@ npm install -g llm-chess-mcp
 ```bash
 pnpm install
 pnpm build
+pnpm test
+```
+
+`pnpm test:unit` runs the unit suite. `pnpm test:e2e` builds first, then runs
+the MCP transport tests. `pnpm check` runs the full local gate; use
+`pnpm release:check` before publishing.
+
+### Maintainers
+
+[Architecture](docs/architecture.md) describes runtime and service boundaries;
+[the changelog](CHANGELOG.md) records client-visible changes.
+
+Local quality commands:
+
+```bash
+pnpm typecheck
+pnpm test:coverage
+pnpm contract:check
+pnpm check
 ```
 
 ### Export Maia3 to ONNX (build-time only)
@@ -51,7 +74,7 @@ the reimplementation against the original, and exports `models/maia3-5m.onnx`.
 ```bash
 uv venv .venv-maia3 --python 3.13
 uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
-uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3"
+uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
 pnpm export:maia3            # -> models/maia3-5m.onnx
 ```
 
@@ -69,6 +92,13 @@ cp .env.example .env
 
 Without a token, `opening_explorer` returns a disabled notice; all other tools work.
 
+Explorer filters are strict. Speeds are `ultraBullet`, `bullet`, `blitz`,
+`rapid`, `classical`, and `correspondence`; rating buckets are `0`, `1000`,
+`1200`, `1400`, `1600`, `1800`, `2000`, `2200`, and `2500`. `masters` accepts
+neither filter. Invalid filters fail locally. Transient failures (network,
+timeout, 429, and 5xx) are retried once within a 12-second total budget;
+invalid requests and other 4xx responses are not retried.
+
 ## Configure in your MCP client
 
 ### opencode
@@ -84,8 +114,7 @@ Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
       "command": ["npx", "-y", "llm-chess-mcp"],
       "enabled": true,
       "environment": {
-        "LICHESS_TOKEN": "your-token",
-        "MAIA3_MODEL": "5m"
+        "LICHESS_TOKEN": "your-token"
       }
     }
   }
@@ -107,8 +136,7 @@ claude mcp add llm-chess-mcp -- npx -y llm-chess-mcp
       "command": "npx",
       "args": ["-y", "llm-chess-mcp"],
       "env": {
-        "LICHESS_TOKEN": "your-token",
-        "MAIA3_MODEL": "5m"
+        "LICHESS_TOKEN": "your-token"
       }
     }
   }
@@ -126,7 +154,6 @@ args = ["-y", "llm-chess-mcp"]
 
 [mcp_servers.llm-chess-mcp.env]
 LICHESS_TOKEN = "your-token"
-MAIA3_MODEL = "5m"
 ```
 
 Or via the CLI:
@@ -153,6 +180,20 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `move_candidates_by_intent` | Convenience layer: candidates ranked for a strategic intent |
 | `opening_explorer` | Lichess human game statistics |
 
+## Result format and 0.1.x migration
+
+`structuredContent` is the canonical successful result. Handler-level failures
+set `isError` and provide `structuredContent.error`. Input-schema failures are
+generated by the MCP SDK before the handler and use its standard `isError` text
+result without `structuredContent`. Otherwise, `content` is only a short
+human-readable summary and must not be parsed as data.
+
+Clients upgrading from 0.1.x should stop parsing `content` and consume
+`structuredContent` instead. Check `isError` and the structured error code when
+a tool fails. `move_evaluate` now always returns
+`{ game_id, revision, results }`; its former single-move top-level duplicates
+are removed.
+
 ## Score conventions
 
 - Stockfish scores are **side-to-move perspective**: positive cp = side to move is
@@ -223,6 +264,13 @@ rejected:
 { "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }
 ```
 
+## Runtime limits
+
+- Up to 1,000 game sessions are retained; idle sessions expire after one hour.
+- `move_evaluate` accepts at most 10 moves per call.
+- Imported PGNs are limited to 1 MiB and 4,096 plies.
+- Stockfish accepts up to 32 active or queued analyses.
+
 ## Intents
 
 `move_candidates_by_intent` ranks candidates for a chosen intent. It is a
@@ -270,6 +318,16 @@ It checks top-1/top-k move agreement and max probability error to detect
 export/runtime regressions. The bundled `maia3-5m.onnx` passes with 100% top-1
 and top-5 agreement and max probability error < 1e-4.
 
+## Releases
+
+Releases are verified locally; this project intentionally has no hosted CI
+release workflow.
+
+For `0.2.0`, run `pnpm release:check`, pack the tarball, and smoke-test a clean
+install of that tarball with `llm-chess-mcp`. Publish only after that succeeds.
+Use the same local gate and clean-install smoke test before promoting the proven
+`0.2.x` release process to `1.0.0`.
+
 ## License & attribution
 
 This project is licensed under the **AGPL-3.0** (see `LICENSE`).
@@ -283,6 +341,7 @@ It bundles and depends on third-party components:
 | [onnxruntime-node](https://github.com/microsoft/onnxruntime) | MIT | Microsoft |
 | [chess.js](https://github.com/jhlywa/chess.js) | BSD-2-Clause | Jeff Hlywa |
 
-The Maia3 model weights (`models/maia3-5m.onnx`) are derived from the
-`UofTCSSLab/Maia3-5M` checkpoint. The ONNX export is a build-time step
-(`scripts/export_maia3.py`); the runtime does not execute any Maia3 Python code.
+The bundled Maia3 model (`models/maia3-5m.onnx`) is derived from
+[`UofTCSSLab/Maia3-5M` at `b6559de2398d7140b985f28fd2c19fb5e47ddabe`](https://huggingface.co/UofTCSSLab/Maia3-5M/tree/b6559de2398d7140b985f28fd2c19fb5e47ddabe).
+The ONNX export is a build-time step (`scripts/export_maia3.py`); the runtime
+does not execute any Maia3 Python code.

package/dist/chess.js

@@ -0,0 +1,83 @@
+import { Chess } from "chess.js";
+import { ChessError } from "./errors.js";
+export const MAX_EVALUATED_MOVES = 10;
+export const MAX_PGN_BYTES = 1024 * 1024;
+export const MAX_PGN_PLIES = 4096;
+function moveDescriptor(move) {
+    const base = { from: move.from, to: move.to };
+    return move.promotion ? { ...base, promotion: move.promotion } : base;
+}
+export function snapshotChess(chess) {
+    const history = chess.history({ verbose: true });
+    const snapshot = new Chess(history[0]?.before ?? chess.fen());
+    for (const move of history)
+        snapshot.move(moveDescriptor(move));
+    return snapshot;
+}
+export function drawResult(chess) {
+    if (!chess.isDraw())
+        return null;
+    if (chess.isStalemate())
+        return "stalemate";
+    if (chess.isInsufficientMaterial())
+        return "insufficient_material";
+    if (chess.isThreefoldRepetition())
+        return "threefold_repetition";
+    if (chess.isDrawByFiftyMoves())
+        return "fifty_move_rule";
+    return "draw";
+}
+export function parseImportedPgn(pgn) {
+    if (Buffer.byteLength(pgn, "utf8") > MAX_PGN_BYTES) {
+        throw new ChessError("PGN_TOO_LARGE", `PGN exceeds the ${MAX_PGN_BYTES}-byte limit`);
+    }
+    let chess;
+    try {
+        chess = new Chess();
+        chess.loadPgn(pgn);
+    }
+    catch {
+        throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
+    }
+    if (chess.history().length > MAX_PGN_PLIES) {
+        throw new ChessError("PGN_TOO_MANY_MOVES", `PGN exceeds the ${MAX_PGN_PLIES}-ply limit`);
+    }
+    return chess;
+}
+export function stateOf(chess, revision) {
+    const last = chess.history({ verbose: true }).at(-1);
+    return {
+        fen: chess.fen(),
+        turn: chess.turn(),
+        revision,
+        isCheck: chess.isCheck(),
+        isCheckmate: chess.isCheckmate(),
+        isStalemate: chess.isStalemate(),
+        isDraw: chess.isDraw(),
+        isGameOver: chess.isGameOver(),
+        isInsufficientMaterial: chess.isInsufficientMaterial(),
+        isThreefoldRepetition: chess.isThreefoldRepetition(),
+        isDrawByFiftyMoves: chess.isDrawByFiftyMoves(),
+        moveNumber: chess.moveNumber(),
+        history: chess.history(),
+        lastMove: last ? { san: last.san, uci: last.lan } : null,
+        castling: {
+            whiteKingside: chess.getCastlingRights("w").k,
+            whiteQueenside: chess.getCastlingRights("w").q,
+            blackKingside: chess.getCastlingRights("b").k,
+            blackQueenside: chess.getCastlingRights("b").q,
+        },
+    };
+}
+export function parseMove(chess, move) {
+    const legal = chess.moves({ verbose: true });
+    const san = move.replace(/[+#]$/, "");
+    const found = legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === san) ??
+        legal.find((candidate) => candidate.lan === move);
+    if (!found)
+        throw new ChessError("ILLEGAL_MOVE", `illegal move: ${move}`);
+    return found;
+}
+export function playParsedMove(chess, move) {
+    return chess.move(moveDescriptor(move));
+}

package/dist/engines/stockfish.js

@@ -1,7 +1,34 @@
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
-function flavor() {
-    return process.env.STOCKFISH_FLAVOR || "lite-single";
+export const STOCKFISH_FLAVORS = [
+    "full",
+    "lite",
+    "single",
+    "lite-single",
+    "single-lite",
+    "asm",
+];
+const DEFAULT_FLAVOR = "lite-single";
+const FLAVORS = new Set(STOCKFISH_FLAVORS);
+const DEFAULT_TIMEOUTS = {
+    init: 15000,
+    handshake: 15000,
+    analyze: 30000,
+    stopGrace: 2000,
+};
+const DEFAULT_MAX_QUEUE = 32;
+export function resolveStockfishFlavor(value) {
+    const normalized = (value || DEFAULT_FLAVOR).toLowerCase();
+    if (!FLAVORS.has(normalized)) {
+        throw new Error(`invalid STOCKFISH_FLAVOR: ${JSON.stringify(value)}; expected one of ${STOCKFISH_FLAVORS.join(", ")}`);
+    }
+    return normalized;
+}
+function loadStockfish() {
+    return require("stockfish");
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
 }
 function parseScore(token) {
     if (token.startsWith("cp"))
@@ -11,62 +38,182 @@ function parseScore(token) {
     return { cp: null, mate: null };
 }
 function parseWdl(line) {
-    const m = line.match(/ wdl (\d+) (\d+) (\d+)/);
-    if (!m)
+    const groups = line.match(/ wdl (?<wins>\d+) (?<draws>\d+) (?<losses>\d+)/)?.groups;
+    if (!groups)
         return null;
-    return [Number(m[1]), Number(m[2]), Number(m[3])];
+    return [Number(groups.wins), Number(groups.draws), Number(groups.losses)];
 }
 export class Stockfish {
-    engine = null;
-    ready = null;
+    session = null;
     queue = Promise.resolve();
+    queued = 0;
+    quitGeneration = 0;
+    terminated = new WeakSet();
+    initEngine;
+    configuredFlavor;
+    maxQueue;
+    timeouts;
+    constructor(options = {}) {
+        this.initEngine = options.init;
+        this.configuredFlavor = options.flavor;
+        this.maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
+        this.timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+        if (!Number.isInteger(this.maxQueue) || this.maxQueue < 1) {
+            throw new Error("stockfish maxQueue must be a positive integer");
+        }
+        for (const [name, timeout] of Object.entries(this.timeouts)) {
+            if (!Number.isFinite(timeout) || timeout < 1) {
+                throw new Error(`stockfish ${name} timeout must be positive`);
+            }
+        }
+    }
     init() {
-        if (this.ready)
-            return this.ready;
-        this.ready = new Promise((resolve, reject) => {
-            const init = require("stockfish");
-            const engine = init(flavor(), (err) => {
-                if (err)
-                    return reject(err);
-                this.handshake().then(resolve, reject);
-            });
-            this.engine = engine;
-            engine.listener = () => { };
+        if (this.session)
+            return this.session.ready;
+        let resolve;
+        let reject;
+        const ready = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
         });
-        return this.ready;
+        const session = {
+            engine: null,
+            ready,
+            initSettled: false,
+            initTimer: null,
+            resolve,
+            reject,
+            aborts: new Set(),
+        };
+        this.session = session;
+        session.initTimer = setTimeout(() => this.failSession(session, new Error("stockfish init timeout")), this.timeouts.init);
+        let callbackCalled = false;
+        try {
+            const selectedFlavor = resolveStockfishFlavor(this.configuredFlavor ?? process.env.STOCKFISH_FLAVOR);
+            const engine = (this.initEngine ?? loadStockfish())(selectedFlavor, (error, initializedEngine) => {
+                callbackCalled = true;
+                if (this.session !== session) {
+                    this.terminate(initializedEngine);
+                    return;
+                }
+                if (session.initSettled) {
+                    if (initializedEngine !== session.engine)
+                        this.terminate(initializedEngine);
+                    return;
+                }
+                if (session.engine && session.engine !== initializedEngine) {
+                    this.terminate(session.engine);
+                }
+                session.engine = initializedEngine;
+                if (error) {
+                    this.failSession(session, asError(error));
+                    return;
+                }
+                initializedEngine.listener = () => { };
+                if (session.initTimer)
+                    clearTimeout(session.initTimer);
+                session.initTimer = null;
+                this.handshake(session).then(() => {
+                    if (this.session !== session || session.initSettled)
+                        return;
+                    session.initSettled = true;
+                    session.resolve();
+                }, (handshakeError) => this.failSession(session, asError(handshakeError)));
+            });
+            if (!callbackCalled && this.session === session && !session.initSettled) {
+                session.engine = engine;
+                engine.listener = () => { };
+            }
+        }
+        catch (error) {
+            this.failSession(session, asError(error));
+        }
+        return ready;
     }
-    handshake() {
+    handshake(session) {
         return new Promise((resolve, reject) => {
-            const engine = this.engine;
+            const engine = session.engine;
+            if (!engine) {
+                reject(new Error("stockfish initialized without an engine"));
+                return;
+            }
             let stage = 0;
-            const timer = setTimeout(() => reject(new Error("stockfish handshake timeout")), 15000);
-            engine.listener = (line) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                session.aborts.delete(abort);
+                if (engine.listener === listener)
+                    engine.listener = null;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const abort = (error) => finish(error);
+            const listener = (line) => {
                 if (stage === 0 && line === "uciok") {
                     stage = 1;
-                    engine.sendCommand("isready");
+                    try {
+                        engine.sendCommand("isready");
+                    }
+                    catch (error) {
+                        finish(asError(error));
+                    }
                 }
                 else if (stage === 1 && line === "readyok") {
-                    clearTimeout(timer);
-                    engine.listener = null;
-                    resolve();
+                    finish();
                 }
             };
-            engine.sendCommand("uci");
+            const timer = setTimeout(() => finish(new Error("stockfish handshake timeout")), this.timeouts.handshake);
+            session.aborts.add(abort);
+            engine.listener = listener;
+            try {
+                engine.sendCommand("uci");
+            }
+            catch (error) {
+                finish(asError(error));
+            }
         });
     }
     enqueue(fn) {
-        const run = this.queue.then(fn, fn);
-        this.queue = run.catch(() => { });
-        return run;
+        if (this.queued >= this.maxQueue) {
+            return Promise.reject(new Error("stockfish queue full"));
+        }
+        this.queued++;
+        const run = this.queue.then(fn);
+        this.queue = run.then(() => { }, () => { });
+        return run.finally(() => {
+            this.queued--;
+        });
     }
-    async analyze(fen, depth, multipv) {
-        await this.init();
-        return this.enqueue(() => this.doAnalyze(fen, depth, multipv));
+    analyze(fen, depth, multipv) {
+        const quitGeneration = this.quitGeneration;
+        return this.enqueue(async () => {
+            if (quitGeneration !== this.quitGeneration) {
+                throw new Error("stockfish request cancelled");
+            }
+            await this.init();
+            if (quitGeneration !== this.quitGeneration) {
+                throw new Error("stockfish request cancelled");
+            }
+            const session = this.session;
+            if (!session)
+                throw new Error("stockfish unavailable after initialization");
+            return this.doAnalyze(session, fen, depth, multipv);
+        });
     }
-    doAnalyze(fen, depth, multipv) {
+    doAnalyze(session, fen, depth, multipv) {
         return new Promise((resolve, reject) => {
-            const engine = this.engine;
+            const engine = session.engine;
+            if (!engine) {
+                reject(new Error("stockfish engine unavailable"));
+                return;
+            }
             const byPv = new Map();
+            let settled = false;
             let stopTimer = null;
             let failTimer = null;
             const cleanup = () => {
@@ -76,58 +223,118 @@ export class Stockfish {
                     clearTimeout(failTimer);
                 stopTimer = null;
                 failTimer = null;
+                session.aborts.delete(abort);
+                if (engine.listener === listener)
+                    engine.listener = null;
             };
-            engine.listener = (line) => {
+            const succeed = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve([...byPv.values()].sort((a, b) => a.multipv - b.multipv));
+            };
+            const fail = (error, reset) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (reset)
+                    this.invalidateSession(session, error);
+                reject(error);
+            };
+            const abort = (error) => fail(error, false);
+            const listener = (line) => {
                 if (line.startsWith("info") && line.includes(" multipv ")) {
-                    const m = line.match(/multipv (\d+)/);
-                    const s = line.match(/ score (cp -?\d+|mate -?\d+)/);
-                    const pv = line.match(/ pv (.+)$/);
-                    if (!m)
+                    const multipv = line.match(/multipv (?<value>\d+)/)?.groups?.value;
+                    if (!multipv)
                         return;
-                    const n = Number(m[1]);
-                    const score = s ? parseScore(s[1]) : { cp: null, mate: null };
+                    const scoreToken = line.match(/ score (?<value>cp -?\d+|mate -?\d+)/)?.groups?.value;
+                    const pv = line.match(/ pv (?<value>.+)$/)?.groups?.value;
+                    const n = Number(multipv);
+                    const score = scoreToken
+                        ? parseScore(scoreToken)
+                        : { cp: null, mate: null };
                     byPv.set(n, {
                         multipv: n,
                         scoreCp: score.cp,
                         scoreMate: score.mate,
                         wdl: parseWdl(line),
-                        pv: pv ? pv[1].split(" ") : [],
+                        pv: pv ? pv.split(" ") : [],
                     });
                 }
                 else if (line.startsWith("bestmove")) {
-                    cleanup();
-                    engine.listener = null;
-                    resolve([...byPv.values()].sort((a, b) => a.multipv - b.multipv));
+                    succeed();
                 }
             };
-            engine.sendCommand("position fen " + fen);
-            engine.sendCommand(`setoption name MultiPV value ${multipv}`);
-            engine.sendCommand("setoption name UCI_ShowWDL value true");
-            engine.sendCommand(`go depth ${depth}`);
+            session.aborts.add(abort);
+            engine.listener = listener;
             stopTimer = setTimeout(() => {
-                engine.sendCommand("stop");
-                failTimer = setTimeout(() => {
-                    if (engine.listener) {
-                        engine.listener = null;
-                        this.reset();
-                        reject(new Error("stockfish analyze timeout"));
-                    }
-                }, 2000);
-            }, 30000);
-        });
-    }
-    reset() {
-        if (this.engine) {
+                failTimer = setTimeout(() => fail(new Error("stockfish analyze timeout"), true), this.timeouts.stopGrace);
+                try {
+                    engine.sendCommand("stop");
+                }
+                catch (error) {
+                    fail(asError(error), true);
+                }
+            }, this.timeouts.analyze);
             try {
-                this.engine.terminate();
+                engine.sendCommand("position fen " + fen);
+                engine.sendCommand(`setoption name MultiPV value ${multipv}`);
+                engine.sendCommand("setoption name UCI_ShowWDL value true");
+                engine.sendCommand(`go depth ${depth}`);
+            }
+            catch (error) {
+                fail(asError(error), true);
+                return;
             }
-            catch { }
+        });
+    }
+    failSession(session, error) {
+        if (session.initSettled)
+            return;
+        session.initSettled = true;
+        if (session.initTimer)
+            clearTimeout(session.initTimer);
+        session.initTimer = null;
+        this.invalidateSession(session, error);
+        session.reject(error);
+    }
+    invalidateSession(session, error) {
+        if (this.session !== session)
+            return;
+        this.session = null;
+        if (session.initTimer)
+            clearTimeout(session.initTimer);
+        session.initTimer = null;
+        if (!session.initSettled) {
+            session.initSettled = true;
+            session.reject(error);
+        }
+        const aborts = [...session.aborts];
+        session.aborts.clear();
+        if (session.engine) {
+            session.engine.listener = null;
+            this.terminate(session.engine);
+        }
+        for (const abort of aborts)
+            abort(error);
+    }
+    terminate(engine) {
+        if (this.terminated.has(engine))
+            return;
+        this.terminated.add(engine);
+        engine.listener = null;
+        try {
+            engine.terminate();
         }
-        this.engine = null;
-        this.ready = null;
+        catch { }
     }
     async quit() {
-        this.reset();
+        this.quitGeneration++;
+        const session = this.session;
+        if (session)
+            this.invalidateSession(session, new Error("stockfish quit"));
     }
 }
 export const stockfish = new Stockfish();

package/dist/env.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+const ALLOWED_KEYS = new Set(["LICHESS_TOKEN", "MAIA3_MODEL", "STOCKFISH_FLAVOR"]);
 export function loadEnv(path = ".env") {
     let text;
     try {
@@ -17,7 +18,7 @@ export function loadEnv(path = ".env") {
             continue;
         const key = trimmed.slice(0, eq).trim();
         const value = trimmed.slice(eq + 1).trim();
-        if (key && process.env[key] === undefined) {
+        if (ALLOWED_KEYS.has(key) && process.env[key] === undefined) {
             process.env[key] = value.replace(/^["']|["']$/g, "");
         }
     }

package/dist/errors.js

@@ -1,7 +1,7 @@
 export class ChessError extends Error {
     code;
     constructor(code, message) {
-        super(`${code}: ${message}`);
+        super(message);
         this.code = code;
         this.name = "ChessError";
     }