gdharness 0.13.5 → 0.13.7

package/build/godot/operations/serialisation.gd

@@ -10,6 +10,27 @@ extends RefCounted
 
 const Read = preload("reading.gd")
 
+# What the engine carries from one to another without complaint, which is what a value written to a
+# property or handed to a parameter may arrive as. Numbers include bool because the engine counts it
+# as one, and the three text types are one string wearing three hats.
+const NUMBERS: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT]
+const TEXTS: Array[int] = [TYPE_STRING, TYPE_STRING_NAME, TYPE_NODE_PATH]
+
+# The types that cross as a plain JSON list and have to be built back into themselves. A list is
+# what a caller can write by hand and what the serialiser answers with, and the parameter or
+# property being written is the only thing that knows which of these it wanted.
+const LIST_TYPES: Array[int] = [
+	TYPE_PACKED_INT32_ARRAY,
+	TYPE_PACKED_INT64_ARRAY,
+	TYPE_PACKED_FLOAT32_ARRAY,
+	TYPE_PACKED_FLOAT64_ARRAY,
+	TYPE_PACKED_STRING_ARRAY,
+	TYPE_PACKED_VECTOR2_ARRAY,
+	TYPE_PACKED_VECTOR3_ARRAY,
+	TYPE_PACKED_VECTOR4_ARRAY,
+	TYPE_PACKED_COLOR_ARRAY,
+]
+
 # What each Godot type becomes on the wire, as one table you can read rather than an order you
 # have to trust. Keyed on typeof() rather than written as a chain of `is` tests, because the
 # order mattered: Resource had to be tested before Object or every resource came back as a bare
@@ -163,6 +184,91 @@ func deserialize_value(value: Variant) -> Variant:
 	return call(builder, fields)
 
 
+## Whether two values can be compared without the comparison itself failing.
+##
+## GDScript's `==` is not total. An Object against a String is a hard error rather than false, and
+## an error raised inside a game is not a wrong answer: it stops the game. A caller who asked
+## `runtime_wait until` for the wrong kind of value got their game held at a debugger break, every
+## later call answering "did not respond within 10000ms, it may be stuck in a long frame", and
+## nothing anywhere naming the argument that did it. A wrong argument costs a refusal, never the
+## session's game.
+##
+## Only an object is special. Every other pair the engine answers, false where they differ, and
+## refusing those would refuse calls that work: an int against a float is the same number to a
+## caller waiting for 1 on a property holding 1.0.
+static func comparable(one: Variant, other: Variant) -> bool:
+	var left: int = typeof(one)
+	var right: int = typeof(other)
+	if left != TYPE_OBJECT and right != TYPE_OBJECT:
+		return true
+	# An object compares with another object and with null. Anything else is the error above.
+	return (left == TYPE_OBJECT or left == TYPE_NIL) and (right == TYPE_OBJECT or right == TYPE_NIL)
+
+
+## Whether [param value] can be given to something declared as [param type] without damage.
+##
+## Here rather than beside either caller because the running game and the editor ask it of the same
+## values and must not answer differently. What it protects against differs by side and both are
+## silent: `callv` and `==` raise inside a running game, which holds it at a debugger break, while
+## `Object.set` in the editor converts instead and writes the result to the scene file. A word where
+## an int goes is stored as 0, where a bool goes as true, where a Vector2 goes as (0, 0), and the
+## tool reports the change as made. The property keeps a value nobody asked for and the scene is
+## saved with it.
+##
+## A list of what is accepted rather than of what is refused, which is the way round that errs
+## safely. The engine's own conversion table is not readable from GDScript, so either list is a
+## guess at it; guessing narrow costs a caller a refusal naming both types, and guessing wide costs
+## them the damage above. A refusal is the cheaper mistake, and it is the one they can act on.
+static func acceptable(value: Variant, type: int) -> bool:
+	if type == TYPE_NIL:
+		return true
+	var given: int = typeof(value)
+	if given == type:
+		return true
+	# null is a value for anything that holds an object, and for nothing else.
+	if given == TYPE_NIL:
+		return type == TYPE_OBJECT
+	if NUMBERS.has(given) and NUMBERS.has(type):
+		return true
+	if TEXTS.has(given) and TEXTS.has(type):
+		return true
+	return given == TYPE_ARRAY and LIST_TYPES.has(type)
+
+
+## A value from the wire fitted to the type a property or parameter declares. Arguments arrive
+## as strings often enough, and callv refuses a "2.0" where a float is wanted, so a string that
+## reads as the wanted scalar is read as one.
+##
+## The conversion is also what restores a packed array's exact type. Those cross as the plain JSON
+## lists they fit into, so what comes back from the wire is an Array, and the parameter is what says
+## it was a PackedStringArray.
+func fitted(value: Variant, type: int) -> Variant:
+	var rebuilt: Variant = deserialize_value(value)
+	if type == TYPE_NIL or typeof(rebuilt) == type:
+		return rebuilt
+
+	if rebuilt is Array and LIST_TYPES.has(type):
+		return type_convert(rebuilt, type)
+
+	var simple: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING]
+	if not simple.has(type) or not simple.has(typeof(rebuilt)):
+		return rebuilt
+
+	if rebuilt is String and type != TYPE_STRING:
+		var text: String = rebuilt
+		var parsed: Variant = JSON.parse_string(text)
+		# A string that does not read as the type wanted is handed back as the string it is, so
+		# whoever asked can refuse it. type_convert answers 0 for "not an index" and true for any
+		# text at all, and a caller who sent a word got back a number they never sent: get_child
+		# answered about child 0 with no refusal and no note, which is a halt traded for a plausible
+		# wrong answer, and the wrong answer is the worse of the two.
+		if typeof(parsed) == TYPE_NIL or typeof(parsed) == TYPE_STRING:
+			return rebuilt
+		rebuilt = parsed
+
+	return type_convert(rebuilt, type)
+
+
 ## Whether [param fields] carries every key of any one of [param alternatives].
 ##
 ## More than one spelling because a rectangle has two: the two corners it is answered with, and the

package/build/index.js

@@ -4060,13 +4060,14 @@ var require_fast_uri = __commonJS(function(exports, module) {
       if (!malformedIPLiteral) {
         malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
       }
-      if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
-        if (uri.indexOf("%") !== -1) {
-          if (parsed.host !== undefined && !malformedIPLiteral) {
-            const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
-            parsed.host = reescapeHostDelimiters(host, isIP);
-          }
+      if (uri.indexOf("%") !== -1 && parsed.host !== undefined && !malformedIPLiteral) {
+        let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
+        if (!isIP) {
+          host = normalizePercentEncoding(host.toLowerCase());
         }
+        parsed.host = reescapeHostDelimiters(host, isIP);
+      }
+      if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
         if (parsed.path) {
           parsed.path = normalizePathEncoding(parsed.path);
         }
@@ -28755,7 +28756,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_run",
-    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for.",
+    description: "The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call.",
     parameters: {
       projectPath: PROJECT_PATH,
       scene: {
@@ -28831,7 +28832,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_rescan",
-    description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure measured downstream is a change to the declaring script, saved, and then a rescan: the change on its own left every affected file reporting the same errors, and the rescan after it cleared them. Whether a rescan alone would have done it there is not known, because the rescans in that report may have answered before the scan ran, which is the timing this tool no longer has. editor_launch restart also does it, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve can go out of that file with it, which one project saw and two could not reproduce; where it happens the answer names what the file lost under cacheLost, before a fresh engine, a CI run or a clone inherits it. Needs the editor connected.",
+    description: "Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure measured downstream is a change to the declaring script, saved, and then a rescan: the change on its own left every affected file reporting the same errors, and the rescan after it cleared them. Whether a rescan alone would have done it there is not known, because the rescans in that report may have answered before the scan ran, which is the timing this tool no longer has. editor_launch restart also does it, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. Needs the editor connected.",
     parameters: {
       projectPath: PROJECT_PATH,
       timeoutMs: { type: "number", description: "How long to wait for the scan. Default 30000." }
@@ -29123,7 +29124,7 @@ var TOOL_SPECS = [
       says: {
         type: "string",
         ops: ["until"],
-        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included."
+        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
       },
       timeoutMs: {
         type: "number",
@@ -30641,6 +30642,7 @@ class GodotServer {
       };
     }));
     const playing = await this.editorPlayingState();
+    await this.pickUpWhatTheEditorIsPlaying();
     return this.jsonTextResponse({
       editor: {
         ...this.getEditorStatusPayload(),
@@ -30851,6 +30853,7 @@ class GodotServer {
       through: "gdharness",
       pid: started.process.pid ?? null,
       arguments: cmdArgs,
+      transcript: started.transcript,
       refreshedClasses: refreshed.value,
       endedPreviousRun: ended ?? undefined,
       runtime: await this.runtimeUp(project.value.path, alreadyPlaying, runtimeWaitMs),
@@ -31075,6 +31078,33 @@ class GodotServer {
       closeSync(handle);
     }
   }
+  async pickUpWhatTheEditorIsPlaying() {
+    if (this.activeProcess !== null || !this.godotBridge.isConnected()) {
+      return;
+    }
+    const playing = await this.editorPlayingState();
+    if (playing?.playing !== true) {
+      return;
+    }
+    try {
+      await this.dap().connect();
+    } catch (error) {
+      this.logDebug(`Picked up an editor-played run without its adapter: ${errorMessage(error)}`);
+    }
+    this.activeProcess = {
+      process: null,
+      pid: null,
+      log: new GameLog,
+      transcript: null,
+      readOffset: 0,
+      projectPath: this.godotBridge.getStatus().projectPath ?? null,
+      startedAt: Date.now(),
+      exitCode: null,
+      throughEditor: true,
+      brokeOn: null,
+      pickedUpPlaying: true
+    };
+  }
   adoptRecordedRun() {
     const record = readRunRecord();
     if (record === null || !this.couldBeOurs(record.projectPath)) {
@@ -31156,6 +31186,7 @@ class GodotServer {
     });
   }
   async handleWaitForRun(args) {
+    await this.pickUpWhatTheEditorIsPlaying();
     const run = this.currentRun();
     if (!run) {
       return this.createErrorResponse(this.nothingOfOursIsRunning());
@@ -31170,6 +31201,7 @@ class GodotServer {
     return await this.handleGetDebugOutput(args, stillRunning(run) ? budgetMs : undefined);
   }
   async handleGetDebugOutput(args, waitedMs) {
+    await this.pickUpWhatTheEditorIsPlaying();
     const run = this.currentRun();
     if (!run) {
       return this.createErrorResponse(this.nothingOfOursIsRunning());
@@ -31197,6 +31229,9 @@ class GodotServer {
     if (run.endedUnwatched === true) {
       notes.push("This run outlived the server that started it and is over now, so its exit code was never collected. Everything it printed is below, read back from its transcript.");
     }
+    if (run.pickedUpPlaying === true) {
+      notes.push("The editor was already playing this when this server reached it, so this is not the run from its start: what it printed before that went with the server that was listening then. It is the run the editor is holding now, which is the one the debug_* tools answer for.");
+    }
     if (typeof run.endedHere === "string") {
       notes.push(`This run was ended here, by ${run.endedHere}.`);
     } else if (!stillRunning(run) && !run.throughEditor && run.exitCode !== null) {
@@ -31227,6 +31262,7 @@ class GodotServer {
     });
   }
   async handleStopProject() {
+    await this.pickUpWhatTheEditorIsPlaying();
     const stopped = this.currentRun();
     if (!stopped) {
       return this.createErrorResponse(this.nothingOfOursIsRunning());
@@ -31252,7 +31288,7 @@ class GodotServer {
     const projectPath = typeof args["projectPath"] === "string" ? args["projectPath"] : "";
     const before = projectPath === "" ? null : cachedClasses(projectPath);
     const writtenBefore = projectPath === "" ? null : cacheWrittenAt(projectPath);
-    const blind = projectPath === "" ? { unseen: [] } : await this.classesTheEditorCannotSee(args);
+    const blind = await this.classesTheEditorCannotSee(args);
     const atRisk = before === null ? [] : blind.unseen.filter((one) => before.has(one.className));
     const first = await this.handleViaBridge("rescan_filesystem", args);
     if (first.isError) {
@@ -31265,7 +31301,7 @@ class GodotServer {
       const pending = Boolean(status["pending"]) && Date.now() - started < SCAN_START_MS;
       busy = Boolean(status["scanning"]) || Boolean(status["importing"]) || pending;
     }
-    if (!busy && atRisk.length > 0) {
+    if (!busy && projectPath !== "" && (atRisk.length > 0 || blind.unchecked !== undefined)) {
       const until = Date.now() + CACHE_WRITE_MS;
       while (Date.now() < until && cacheWrittenAt(projectPath) === writtenBefore) {
         await new Promise((settle) => setTimeout(settle, 100));
@@ -31273,18 +31309,33 @@ class GodotServer {
     }
     const after = projectPath === "" || busy ? null : cachedClasses(projectPath);
     const lost = before === null || after === null ? [] : [...before.keys()].filter((name) => !after.has(name));
+    const restored = lost.length > 0 ? await this.rebuildCacheAfterLoss(projectPath, lost) : [];
     const checked = busy ? { unseen: [] } : await this.classesTheEditorCannotSee(args);
     const unseen = checked.unseen;
+    const stillGone = lost.filter((name) => !restored.includes(name));
     return this.jsonTextResponse({
-      ok: !busy && unseen.length === 0 && lost.length === 0 && checked.unchecked === undefined,
+      ok: !busy && unseen.length === 0 && stillGone.length === 0 && checked.unchecked === undefined,
       stillWorking: busy,
       waitedMs: Date.now() - started,
       unseenByEditor: unseen.length > 0 ? unseen : undefined,
       cacheLost: lost.length > 0 ? lost : undefined,
+      cacheRestored: restored.length > 0 ? restored : undefined,
       classesUnchecked: checked.unchecked,
-      note: busy ? "The editor was still scanning or importing when the wait ran out, so new files may not be visible yet." : lost.length > 0 ? "The scan wrote the class cache from the list this editor is holding, and that list is shorter than the file was: these classes were in it before the scan and are not now. Every engine that reads the cache next, including a test run, will report them as unknown identifiers in files nobody touched. Run project_import refresh_classes to put them back, and do not rescan again until the editor has been restarted with editor_launch restart, because it will write the same short list over it." : unseen.length > 0 ? "The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Change the declaring script and rescan, or restart the editor with editor_launch restart." : undefined
+      note: busy ? "The editor was still scanning or importing when the wait ran out, so new files may not be visible yet." : stillGone.length > 0 ? "The scan wrote the class cache from the list this editor is holding, that list is shorter than the file was, and rebuilding the cache from the files did not bring these back. Every engine that reads the cache next, including a test run, will report them as unknown identifiers. Restart the editor with editor_launch restart before scanning again." : lost.length > 0 ? "The scan wrote the class cache from the list this editor is holding, which is shorter than the file was, so the cache was rebuilt from the files and these classes are back in it. Nothing was lost, but this editor is still holding the short list: do not rescan again until it has been restarted with editor_launch restart, because it will write the same list over the file each time." : unseen.length > 0 ? "The scan finished and these classes are still not in the list the editor resolves against, so every use of them reads as an unknown identifier. Its walk skips a file another engine has already imported. Change the declaring script and rescan, or restart the editor with editor_launch restart." : undefined
     });
   }
+  async rebuildCacheAfterLoss(projectPath, lost) {
+    if (projectPath === "") {
+      return [];
+    }
+    const rebuilt = await this.operation("refresh_class_cache", {}, projectPath);
+    if (!rebuilt.ok) {
+      this.logDebug(`Could not rebuild the class cache after a scan: ${rebuilt.message}`);
+      return [];
+    }
+    const now = cachedClasses(projectPath);
+    return now === null ? [] : lost.filter((name) => now.has(name));
+  }
   async alsoSayWhatTheEditorCannotSee(answered, args) {
     const first = answered.content[0];
     if (answered.isError || first?.type !== "text" || typeof first.text !== "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "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",