gdharness 1.0.9 → 1.0.10

package/build/cli.js

@@ -201,7 +201,11 @@ function userDataIn(home, variables = process.env) {
 function savesStayPut(platform = process.platform) {
   return platform === "darwin";
 }
-var OPENED_BY_A_SERVER = "GDHARNESS_OPENED_BY_A_SERVER", SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
+function environmentFor(options, variables = process.env) {
+  const base = options.savesIn === undefined ? { ...variables } : userDataIn(options.savesIn, variables);
+  return { ...base, ...options.env, GDHARNESS_RUNTIME_DIR: options.runtimeDirectory };
+}
+var OPENED_BY_A_SERVER = "GDHARNESS_OPENED_BY_A_SERVER", RESERVED_VARIABLE_PREFIX = "GDHARNESS_", SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
 
 // node_modules/yaml/dist/nodes/identity.js
 var require_identity = __commonJS(function(exports) {
@@ -16012,6 +16016,16 @@ var init_tool_definitions = __esm(() => {
           description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
         },
         headless: { type: "boolean", ops: ["start"], description: "start: force a window or no window." },
+        savesIn: {
+          type: "string",
+          ops: ["start", "check"],
+          description: "An absolute directory for this run's user://, so a game that saves writes nowhere near the copy somebody plays: opening a save writes the one being left, and a game that autosaves writes on its own. Godot takes no flag for it, so this is the environment, and the run is started by this server rather than played by the editor, which cannot be given one. It does not have to exist: the engine makes it, and the Godot/app_userdata/<project> tree under it, measured on 4.7.2. On macOS the engine reads user:// off HOME and ignores it, also measured, and the answer says so under savesNote rather than leaving the caller to find out from the player's save list."
+        },
+        env: {
+          type: "object",
+          ops: ["start", "check"],
+          description: "Environment variables for this run alone, as a map of strings, over the server's own environment. Like savesIn, a run carrying any is started by this server rather than played by the editor. Names beginning with GDHARNESS_ are refused: they are this server's contract with the addon in the game, and the runtime directory is set here whatever the rest of the environment says, so a game that moves TEMP still announces where this server looks."
+        },
         runtimeWaitMs: {
           type: "number",
           ops: ["start"],
@@ -37650,7 +37664,7 @@ import {
   statSync as statSync5
 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
-import { basename as basename4, dirname as dirname14, join as join21, normalize as normalize3, relative as relative3 } from "node:path";
+import { basename as basename4, dirname as dirname14, isAbsolute as isAbsolute3, join as join21, normalize as normalize3, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { promisify as promisify7 } from "node:util";
@@ -37932,6 +37946,9 @@ function camelCased(params) {
   }
   return result;
 }
+function needsItsOwnProcess(asked) {
+  return asked.savesIn !== undefined || asked.env !== undefined;
+}
 
 class GodotServer {
   mcp;
@@ -38627,6 +38644,51 @@ class GodotServer {
     }
     return { ok: true, value: given };
   }
+  runEnvironment(args) {
+    const savesIn = readNonEmptyString(args, "savesIn");
+    if (savesIn !== undefined && !isAbsolute3(savesIn)) {
+      return {
+        ok: false,
+        response: this.createErrorResponse(`savesIn must be an absolute path, not "${savesIn}".`, [
+          "Name the directory user:// should be under, such as a temporary directory of this run's own"
+        ])
+      };
+    }
+    if (args["env"] === undefined) {
+      return { ok: true, value: savesIn === undefined ? {} : { savesIn } };
+    }
+    const given = readParams(args, "env");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("env must be a map of names to string values.", [
+          'Pass the variables this run needs, such as {"MY_FLAG": "1"}'
+        ])
+      };
+    }
+    const env = {};
+    for (const [name, value] of Object.entries(given)) {
+      if (typeof value !== "string") {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`env values must be strings, and ${name} is ${typeof value}.`, [
+            'Pass every value as a string, such as {"WORKERS": "4"}'
+          ])
+        };
+      }
+      if (name.toUpperCase().startsWith(RESERVED_VARIABLE_PREFIX)) {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`env may not set ${name}: names beginning with ${RESERVED_VARIABLE_PREFIX} are this server's own.`, [
+            "GDHARNESS_RUNTIME_DIR is where the game announces itself and this server looks for it",
+            "Name the directory for user:// with savesIn rather than by moving the environment yourself"
+          ])
+        };
+      }
+      env[name] = value;
+    }
+    return { ok: true, value: { ...savesIn === undefined ? {} : { savesIn }, env } };
+  }
   async debuggedGame(intent) {
     const game = this.activeProcess;
     if (game !== null && game.exitCode !== null) {
@@ -39614,6 +39676,10 @@ class GodotServer {
     if (!given.ok) {
       return given.response;
     }
+    const asked = this.runEnvironment(args);
+    if (!asked.ok) {
+      return asked.response;
+    }
     if (!sceneToRun && !hasMainScene(project.value.file)) {
       return this.createErrorResponse("The project sets no main scene, so there is nothing to run.", [
         "Pass scene to run one scene",
@@ -39630,7 +39696,7 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, asked.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -39648,7 +39714,7 @@ class GodotServer {
     });
     const runtimeWaitMs = this.announceBudget(args, project.value.path);
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
-    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0) {
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value)) {
       return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
     }
     const cmdArgs = runArguments({
@@ -39658,10 +39724,10 @@ class GodotServer {
       userArgs: given.value
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
-    const started = this.spawnKeptGame(engine.value, cmdArgs, project.value.path);
+    const started = this.spawnKeptGame(engine.value, cmdArgs, project.value.path, needsItsOwnProcess(asked.value) ? environmentFor({ ...asked.value, runtimeDirectory: runtimeDirectory() }) : undefined);
     started.announcedBefore = alreadyPlaying;
     this.activeProcess = started;
-    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : "";
+    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : "";
     const endedForThis = endedToStartThis(ended);
     const stranded = wereHereFirst.filter((one) => one.pid !== ended?.pid && alive(one.pid));
     const named = stranded.map((one) => one.protocol === null ? `pid ${one.pid}` : `pid ${one.pid} on protocol ${one.protocol}`).join(", ");
@@ -39674,6 +39740,7 @@ class GodotServer {
       arguments: cmdArgs,
       transcript: started.transcript,
       refreshedClasses: refreshed.value,
+      savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
       message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}${endedForThis}${alsoRunning}`
@@ -40280,11 +40347,11 @@ class GodotServer {
   currentRun() {
     return this.activeProcess ?? this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, asked = {}) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
     const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
-    const boot = this.spawnGame(godotPath, cmdArgs);
+    const boot = this.spawnGame(godotPath, cmdArgs, needsItsOwnProcess(asked) ? environmentFor({ ...asked, runtimeDirectory: runtimeDirectory() }) : undefined);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
         boot.process.kill();
@@ -40309,6 +40376,7 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       entries: forAnswer(boot.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
   }
@@ -41643,7 +41711,7 @@ function displayPath(harness, platform = process3.platform) {
   return `${harness.scope === "home" ? "~/" : ""}${file.replaceAll("\\", "/")}`;
 }
 var OURS = ["GODOT_PATH", "GDHARNESS_PROJECT"];
-function environmentFor(launch, held) {
+function environmentFor2(launch, held) {
   const kept = {};
   if (typeof held === "object" && held !== null && !Array.isArray(held)) {
     for (const [name, value] of Object.entries(held)) {
@@ -41661,7 +41729,7 @@ function entryFor(shape, launch, held) {
       ...before,
       type: "local",
       command: [launch.command, ...launch.args],
-      environment: environmentFor(launch, before["environment"]),
+      environment: environmentFor2(launch, before["environment"]),
       enabled: true
     };
   }
@@ -41670,7 +41738,7 @@ function entryFor(shape, launch, held) {
     ...shape === "typed" ? { type: "stdio" } : {},
     command: launch.command,
     args: [...launch.args],
-    env: environmentFor(launch, before["env"])
+    env: environmentFor2(launch, before["env"])
   };
 }
 function merged(existing, harness, launch) {
@@ -42489,6 +42557,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Whether this engine has a method or property, and what it takes | \`editor_classes info\` with \`member\`, which answers that one member and which class declares it rather than the whole class |
 | Wait for a run to finish | \`editor_run wait\`, never a sleep or a shell loop on the pid: it answers as \`editor_output\` does, once the run is over |
 | End a bench and the workers it opened | \`editor_run stop\` with \`andChildren\`, never a process listing by scene name: it ends every process under the run's, to any depth, that is a game of the project, announced as one or the project's engine run with \`--path\` on it, names them under \`endedChildren\` with what identified each, and leaves and names any other |
+| Play a game without touching the player's saves | \`editor_run start\` with \`savesIn\`, a directory for this run's \`user://\`: the editor plays with its own environment, so a run given one is started by the server, and the answer says under \`savesNote\` when the platform ignores it |
 | A picture, for a person who asked to see one | \`runtime_capture\` |
 
 These need the runtime autoload, which \`gdharness setup\` registers. \`runtime_capture\` needs a

package/build/index.js

@@ -10185,7 +10185,7 @@ import {
   statSync as statSync5
 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename as basename3, dirname as dirname9, join as join15, normalize as normalize2, relative as relative3 } from "node:path";
+import { basename as basename3, dirname as dirname9, isAbsolute as isAbsolute3, join as join15, normalize as normalize2, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { promisify as promisify5 } from "node:util";
@@ -24811,6 +24811,11 @@ function userDataIn(home, variables = process.env) {
 function savesStayPut(platform = process.platform) {
   return platform === "darwin";
 }
+var RESERVED_VARIABLE_PREFIX = "GDHARNESS_";
+function environmentFor(options, variables = process.env) {
+  const base = options.savesIn === undefined ? { ...variables } : userDataIn(options.savesIn, variables);
+  return { ...base, ...options.env, GDHARNESS_RUNTIME_DIR: options.runtimeDirectory };
+}
 var SAVES_NOT_MOVED_NOTE = "On macOS the engine reads user:// off HOME and ignores the variables that move it elsewhere, measured on Godot 4.7.2, so this run wrote its saves where the player keeps theirs. A suite that saves a game has written into the same folder as the copy being played, and one that tidies up after itself may have removed real saves.";
 
 // src/process-children.ts
@@ -29819,6 +29824,16 @@ var TOOL_SPECS = [
         description: `The game's own arguments, what OS.get_cmdline_user_args() answers, such as ["--level=2"]. The separator is added here. A run with any is started by this server rather than by the editor, which fixes the game's command line when it opens the project, so the debug_* tools do not answer for it.`
       },
       headless: { type: "boolean", ops: ["start"], description: "start: force a window or no window." },
+      savesIn: {
+        type: "string",
+        ops: ["start", "check"],
+        description: "An absolute directory for this run's user://, so a game that saves writes nowhere near the copy somebody plays: opening a save writes the one being left, and a game that autosaves writes on its own. Godot takes no flag for it, so this is the environment, and the run is started by this server rather than played by the editor, which cannot be given one. It does not have to exist: the engine makes it, and the Godot/app_userdata/<project> tree under it, measured on 4.7.2. On macOS the engine reads user:// off HOME and ignores it, also measured, and the answer says so under savesNote rather than leaving the caller to find out from the player's save list."
+      },
+      env: {
+        type: "object",
+        ops: ["start", "check"],
+        description: "Environment variables for this run alone, as a map of strings, over the server's own environment. Like savesIn, a run carrying any is started by this server rather than played by the editor. Names beginning with GDHARNESS_ are refused: they are this server's contract with the addon in the game, and the runtime directory is set here whatever the rest of the environment says, so a game that moves TEMP still announces where this server looks."
+      },
       runtimeWaitMs: {
         type: "number",
         ops: ["start"],
@@ -30669,6 +30684,9 @@ function camelCased(params) {
   }
   return result;
 }
+function needsItsOwnProcess(asked) {
+  return asked.savesIn !== undefined || asked.env !== undefined;
+}
 
 class GodotServer {
   mcp;
@@ -31364,6 +31382,51 @@ class GodotServer {
     }
     return { ok: true, value: given };
   }
+  runEnvironment(args) {
+    const savesIn = readNonEmptyString(args, "savesIn");
+    if (savesIn !== undefined && !isAbsolute3(savesIn)) {
+      return {
+        ok: false,
+        response: this.createErrorResponse(`savesIn must be an absolute path, not "${savesIn}".`, [
+          "Name the directory user:// should be under, such as a temporary directory of this run's own"
+        ])
+      };
+    }
+    if (args["env"] === undefined) {
+      return { ok: true, value: savesIn === undefined ? {} : { savesIn } };
+    }
+    const given = readParams(args, "env");
+    if (given === undefined) {
+      return {
+        ok: false,
+        response: this.createErrorResponse("env must be a map of names to string values.", [
+          'Pass the variables this run needs, such as {"MY_FLAG": "1"}'
+        ])
+      };
+    }
+    const env = {};
+    for (const [name, value] of Object.entries(given)) {
+      if (typeof value !== "string") {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`env values must be strings, and ${name} is ${typeof value}.`, [
+            'Pass every value as a string, such as {"WORKERS": "4"}'
+          ])
+        };
+      }
+      if (name.toUpperCase().startsWith(RESERVED_VARIABLE_PREFIX)) {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`env may not set ${name}: names beginning with ${RESERVED_VARIABLE_PREFIX} are this server's own.`, [
+            "GDHARNESS_RUNTIME_DIR is where the game announces itself and this server looks for it",
+            "Name the directory for user:// with savesIn rather than by moving the environment yourself"
+          ])
+        };
+      }
+      env[name] = value;
+    }
+    return { ok: true, value: { ...savesIn === undefined ? {} : { savesIn }, env } };
+  }
   async debuggedGame(intent) {
     const game = this.activeProcess;
     if (game !== null && game.exitCode !== null) {
@@ -32351,6 +32414,10 @@ class GodotServer {
     if (!given.ok) {
       return given.response;
     }
+    const asked = this.runEnvironment(args);
+    if (!asked.ok) {
+      return asked.response;
+    }
     if (!sceneToRun && !hasMainScene(project.value.file)) {
       return this.createErrorResponse("The project sets no main scene, so there is nothing to run.", [
         "Pass scene to run one scene",
@@ -32367,7 +32434,7 @@ class GodotServer {
     }
     const sceneArgument = sceneToRun?.ok ? sceneToRun.relativePath : null;
     if (op === "check") {
-      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value);
+      return await this.checkBoot(engine.value, project.value.path, sceneArgument, args, given.value, asked.value);
     }
     await this.pickUpWhatTheEditorIsPlaying();
     let ended = null;
@@ -32385,7 +32452,7 @@ class GodotServer {
     });
     const runtimeWaitMs = this.announceBudget(args, project.value.path);
     const editorWouldPlay = !headless || editorPlaysHeadless(project.value.file);
-    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0) {
+    if (this.godotBridge.isConnected() && editorWouldPlay && given.value.length === 0 && !needsItsOwnProcess(asked.value)) {
       return await this.playThroughEditor(sceneArgument, refreshed.value, project.value.path, alreadyPlaying, runtimeWaitMs, ended);
     }
     const cmdArgs = runArguments({
@@ -32395,10 +32462,10 @@ class GodotServer {
       userArgs: given.value
     });
     this.logDebug(`Running Godot project: ${engine.value} ${cmdArgs.join(" ")}`);
-    const started = this.spawnKeptGame(engine.value, cmdArgs, project.value.path);
+    const started = this.spawnKeptGame(engine.value, cmdArgs, project.value.path, needsItsOwnProcess(asked.value) ? environmentFor({ ...asked.value, runtimeDirectory: runtimeDirectory() }) : undefined);
     started.announcedBefore = alreadyPlaying;
     this.activeProcess = started;
-    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : "";
+    const spawnedInstead = this.godotBridge.isConnected() && editorWouldPlay && given.value.length > 0 ? " The editor cannot be handed arguments for a game it plays, so this one was started " + "here: the debug_* tools answer only for a game the editor is playing." : this.godotBridge.isConnected() && editorWouldPlay && needsItsOwnProcess(asked.value) ? " The editor plays a game with its own environment, so a run given one was started " + "here: the debug_* tools answer only for a game the editor is playing." : "";
     const endedForThis = endedToStartThis(ended);
     const stranded = wereHereFirst.filter((one) => one.pid !== ended?.pid && alive(one.pid));
     const named = stranded.map((one) => one.protocol === null ? `pid ${one.pid}` : `pid ${one.pid} on protocol ${one.protocol}`).join(", ");
@@ -32411,6 +32478,7 @@ class GodotServer {
       arguments: cmdArgs,
       transcript: started.transcript,
       refreshedClasses: refreshed.value,
+      savesNote: asked.value.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       endedPreviousRun: endedPreviousRun(ended),
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs, given.value.length > 0),
       message: `Use editor_output for what it prints and editor_run stop to end it.${spawnedInstead}${endedForThis}${alsoRunning}`
@@ -33017,11 +33085,11 @@ class GodotServer {
   currentRun() {
     return this.activeProcess ?? this.adoptRecordedRun();
   }
-  async checkBoot(godotPath, projectPath, scene, args, userArgs) {
+  async checkBoot(godotPath, projectPath, scene, args, userArgs, asked = {}) {
     const frames = readPositiveNumber(args, "frames") ?? 3;
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 60000;
     const cmdArgs = runArguments({ projectPath, headless: true, scene, quitAfter: frames, userArgs });
-    const boot = this.spawnGame(godotPath, cmdArgs);
+    const boot = this.spawnGame(godotPath, cmdArgs, needsItsOwnProcess(asked) ? environmentFor({ ...asked, runtimeDirectory: runtimeDirectory() }) : undefined);
     const hung = await new Promise((resolve) => {
       const timer = setTimeout(() => {
         boot.process.kill();
@@ -33046,6 +33114,7 @@ class GodotServer {
       frames,
       errors,
       warnings,
+      savesNote: asked.savesIn !== undefined && savesStayPut() ? SAVES_NOT_MOVED_NOTE : undefined,
       entries: forAnswer(boot.log.select({ severity: "warning", sinceLastCall: false, limit: 200 }).entries)
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",