gdharness 0.11.1 → 0.12.1

package/README.md

@@ -73,11 +73,12 @@ and integration suites run against a real engine on all three before anything is
 
 What each kind of release means here:
 
-- **Patch**: an answer that was wrong is now right. The output can change, because a wrong answer
-  corrected is a fix rather than a feature, and leaving one wrong to protect whoever parsed it is
-  how a tool stops being worth asking.
-- **Minor**: a tool, an op, an argument or a field was added, or behaviour a caller can see
-  changed.
+- **Patch**: nearly everything. An answer that was wrong is now right, and the output may change
+  shape for it, because a wrong answer corrected is a fix rather than a feature and leaving one
+  wrong to protect whoever parsed it is how a tool stops being worth asking. An addition nothing
+  has to adapt to is a patch too: a new argument, a new field, an argument reaching further than it
+  did. Ignore all of it and your calls still work.
+- **Minor**: a new tool or a new op, meaning this does something it could not do before.
 - **Major**: a tool, an op, an argument or a field was renamed or taken away. Nothing else earns
   one.
 

package/build/cli.js

@@ -15799,7 +15799,7 @@ var init_tool_definitions = __esm(() => {
         property: {
           type: "string",
           ops: ["property", "find"],
-          description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through the objects a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about; a step that is not there is named.'
+          description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through what a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about. A number or a key steps into a list or a map, "_game:run:roster:0:traits", which is how the lists a game keeps its state in are walked: a roster, a board, an in-tray. A negative number counts from the end. A step that is not there is named, and says what was there instead.'
         },
         depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
         includeProperties: {
@@ -15873,7 +15873,7 @@ var init_tool_definitions = __esm(() => {
         property: {
           type: "string",
           ops: ["set"],
-          description: 'set: which one to write. Colons write through the objects a node holds, "_game:run:day", and the answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+          description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
         },
         value: {
           ops: ["set"],
@@ -15883,7 +15883,7 @@ var init_tool_definitions = __esm(() => {
         method: {
           type: "string",
           ops: ["call"],
-          description: 'call: which one to call. Colons call through the objects a node holds, "_game:run:advance", the same way a property is written through them.'
+          description: 'call: which one to call. Colons call through what a node holds, "_game:run:advance", the same way a property is written through them, and a list or a map is stepped into by index or key, "_game:run:roster:0:retire".'
         },
         args: {
           type: "array",
@@ -39477,6 +39477,9 @@ async function enablePlugins(engine, projectPath, names) {
   }
   return outcomes;
 }
+function autoloadIsOurs(named) {
+  return named === null || named === `res://${RUNTIME_AUTOLOAD.path}`;
+}
 async function setRuntime(engine, projectPath, on) {
   return on ? await runOperation2(engine, "add_autoload", { name: RUNTIME_AUTOLOAD.name, path: `res://${RUNTIME_AUTOLOAD.path}`, enabled: true }, projectPath) : await runOperation2(engine, "remove_autoload", { name: RUNTIME_AUTOLOAD.name }, projectPath);
 }
@@ -39533,7 +39536,9 @@ function inspectProject(projectPath) {
     }
   }
   const autoload = settings["autoload"];
-  const runtimeAutoload = autoload !== undefined && typeof readString(autoload, RUNTIME_AUTOLOAD.name) === "string";
+  const registered = autoload === undefined ? undefined : readString(autoload, RUNTIME_AUTOLOAD.name);
+  const runtimeAutoload = typeof registered === "string";
+  const runtimeAutoloadPath = typeof registered === "string" ? registered.replace(/^\*/, "") : null;
   const named = autoloadPaths(settings);
   const tracked = trackedByGit(projectPath, [...named.values()]);
   for (const [name, path] of named) {
@@ -39553,6 +39558,7 @@ function inspectProject(projectPath) {
     addons,
     pluginsEnabled,
     runtimeAutoload,
+    runtimeAutoloadPath,
     staleClasses,
     classCacheExists: cached !== null,
     problems
@@ -39839,6 +39845,18 @@ function said2(outcome, what) {
     console.error(`  engine ${entry.severity}: ${entry.text}`);
   }
 }
+async function registerRuntime(godot, projectPath) {
+  const named = inspectProject(projectPath).runtimeAutoloadPath;
+  if (autoloadIsOurs(named)) {
+    said2(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
+    console.log(`${RUNTIME_AUTOLOAD.name} autoload registered at res://${RUNTIME_AUTOLOAD.path}`);
+    return;
+  }
+  console.log(`${RUNTIME_AUTOLOAD.name} autoload left at ${named}, which this project registers itself`);
+  if (!existsSync13(join17(projectPath, (named ?? "").replace(/^res:\/\//, "")))) {
+    console.log(`  that file is not in this project, so it boots with a missing script: restore it, or point the entry at res://${RUNTIME_AUTOLOAD.path}`);
+  }
+}
 var SETUP_FLAGS = new Set(["--runtime", "--no-runtime", "--no-connect", "--no-skill", "--json", "--yes"]);
 function namedHarnesses() {
   const flags = args.filter((arg) => arg.startsWith("--") && !SETUP_FLAGS.has(arg));
@@ -39941,8 +39959,7 @@ async function setup() {
     console.log(`${name}: ${outcome.ok ? String(outcome.payload["action"]) : "failed"}`);
   }
   if (runtime) {
-    said2(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
-    console.log(`${RUNTIME_AUTOLOAD.name} autoload registered`);
+    await registerRuntime(godot, projectPath);
   }
   const classes = await runOperation(godot, "refresh_class_cache", {}, projectPath);
   said2(classes, "rebuilding the class list");
@@ -40042,7 +40059,7 @@ async function upgrade() {
     said2(outcome, `enabling ${EDITOR_PLUGINS[index] ?? ""}`);
   }
   if (before.runtimeAutoload) {
-    said2(await setRuntime(godot, projectPath, true), "registering the runtime autoload");
+    await registerRuntime(godot, projectPath);
   }
   said2(await runOperation(godot, "refresh_class_cache", {}, projectPath), "rebuilding the class list");
   const launch = launchFor(version, godot.godotPath, projectPath);
@@ -40092,8 +40109,12 @@ async function runtime3() {
   }
   const projectPath = projectArgument(2);
   const godot = await engine();
-  said2(await setRuntime(godot, projectPath, state === "on"), `turning the runtime ${state}`);
-  console.log(`${RUNTIME_AUTOLOAD.name} autoload ${state === "on" ? "registered" : "removed"}`);
+  if (state === "on") {
+    await registerRuntime(godot, projectPath);
+    return;
+  }
+  said2(await setRuntime(godot, projectPath, false), "turning the runtime off");
+  console.log(`${RUNTIME_AUTOLOAD.name} autoload removed`);
 }
 async function classes() {
   const projectPath = projectArgument(1);

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -172,12 +172,12 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	if reached.has("message"):
 		entry["has_property"] = false
 		return entry
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var has: bool = _has_property(holder, named)
+	var has: bool = _can_read(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(holder.get(named))
+		entry["value"] = _values.serialize(_read(holder, named))
 	return entry
 
 
@@ -500,18 +500,18 @@ func get_property(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	# Asked of the property list rather than read and compared to null, because a property the
-	# holder does not have and a property that is null both read as null.
-	if not _has_property(holder, named):
-		return {"type": "error", "message": "%s has no property %s" % [reached["called"], named]}
+	# Asked of the holder rather than read and compared to null, because a property the holder does
+	# not have and a property that is null both read as null.
+	if not _can_read(holder, named):
+		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
 
 	return {
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(holder.get(named)),
+		"value": _values.serialize(_read(holder, named)),
 	}
 
 
@@ -532,21 +532,115 @@ func get_property(params: Dictionary) -> Dictionary:
 ## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
 func _reached(node: Node, node_path: String, reaching: String) -> Dictionary:
 	var parts: PackedStringArray = reaching.split(":")
-	var holder: Object = node
+	var holder: Variant = node
 	var called: String = node_path
 	for step: int in parts.size() - 1:
 		var named: String = parts[step]
-		if not _has_property(holder, named):
-			return {"type": "error", "message": "%s has no property %s" % [called, named]}
-		var next: Variant = holder.get(named)
+		if not _can_read(holder, named):
+			return {"type": "error", "message": _nothing_there(holder, named, called)}
+		holder = _read(holder, named)
 		called = "%s:%s" % [called, named]
-		if not next is Object:
+		if not _can_hold(holder):
 			var wanted: String = parts[step + 1]
 			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
-		holder = next
 	return {"holder": holder, "name": parts[parts.size() - 1], "called": called}
 
 
+## Whether a step can be taken into [param value] at all: an object, a list or a map can be walked
+## into, and a number or a string is where a path ends whether the caller meant it to or not.
+static func _can_hold(value: Variant) -> bool:
+	return value is Object or value is Array or value is Dictionary
+
+
+## Whether [param named] is something [param holder] has.
+##
+## Three kinds of holder, because the state a game keeps is not all properties of objects: a roster
+## is a list and an in-tray is a map, and a path that could not step into either stopped at the
+## first one. An index reads the way a property does, and a negative one counts from the end the
+## way GDScript's own does, so reading the last of something does not mean asking how many first.
+static func _can_read(holder: Variant, named: String) -> bool:
+	if holder is Array:
+		var items: Array = holder
+		return _index_in(named, items.size()) != -1
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		return map.has(named) or map.has(StringName(named))
+	if holder is Object:
+		return _has_property(holder, named)
+	return false
+
+
+## Put [param value] where [param named] points. Only ever called once [method _can_read] agrees,
+## and lists and maps are reference types, so writing into one reaches the game's own copy.
+static func _write(holder: Variant, named: String, value: Variant) -> void:
+	if holder is Array:
+		var items: Array = holder
+		items[_index_in(named, items.size())] = value
+		return
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		# Written back under the key it was found under, since a map keyed by StringName and one
+		# keyed by String both read the same way and a write to the wrong one adds a second entry.
+		if map.has(named):
+			map[named] = value
+		else:
+			map[StringName(named)] = value
+		return
+	var object: Object = holder
+	object.set(named, value)
+
+
+## What [param holder] holds under [param named]. Only ever called once [method _can_read] agrees.
+static func _read(holder: Variant, named: String) -> Variant:
+	if holder is Array:
+		var items: Array = holder
+		return items[_index_in(named, items.size())]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		if map.has(named):
+			return map[named]
+		return map[StringName(named)]
+	var object: Object = holder
+	return object.get(named)
+
+
+## Where [param named] lands in a list of [param size], or -1 for a step that is not in it.
+##
+## -1 for "nowhere" is safe because every answer this gives is an index into a list that long, so a
+## real one is never negative by the time it is returned.
+static func _index_in(named: String, size: int) -> int:
+	if not named.is_valid_int():
+		return -1
+	var index: int = int(named)
+	if index < 0:
+		index += size
+	return index if index >= 0 and index < size else -1
+
+
+## Why a step could not be taken, said in the terms of what was actually there.
+##
+## "has no property 0" about a list is a true sentence that sends somebody looking for a property,
+## so a list says how long it is and a map says what it is keyed by. The step is named rather than
+## the whole path, because the step is the typo.
+static func _nothing_there(holder: Variant, named: String, called: String) -> String:
+	if holder is Array:
+		var items: Array = holder
+		return "%s is a list of %d, so there is no %s in it" % [called, items.size(), named]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		var keys: Array = map.keys()
+		# Eight of them, because a map keyed by something unexpected is told by the first few and a
+		# map of two hundred would bury the sentence saying which key was missing.
+		var some: PackedStringArray = []
+		for key: Variant in keys.slice(0, 8):
+			some.append(str(key))
+		var rest: String = ""
+		if keys.size() > 8:
+			rest = " and %d more" % [keys.size() - 8]
+		return "%s has no key %s; it is keyed by %s%s" % [called, named, ", ".join(some), rest]
+	return "%s has no property %s" % [called, named]
+
+
 ## Whether [param holder] declares [param named]. Its own function because three ops ask it and a
 ## property read back as null answers it wrongly.
 static func _has_property(holder: Object, named: String) -> bool:
@@ -576,17 +670,19 @@ func set_property(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var old_value: Variant = holder.get(named)
-	holder.set(named, _values.fitted(value, typeof(old_value)))
+	if not _can_read(holder, named):
+		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
+	var old_value: Variant = _read(holder, named)
+	_write(holder, named, _values.fitted(value, typeof(old_value)))
 
 	return {
 		"type": "property_set",
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(holder.get(named))
+		"new_value": _values.serialize(_read(holder, named))
 	}
 
 
@@ -610,6 +706,19 @@ func call_method(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
+	# A list or a map can be stepped through on the way, and is not a thing with methods when the
+	# path stops on one: said in those terms rather than as "has no method", which reads as a
+	# misspelling of a method that was never going to be there.
+	if not reached["holder"] is Object:
+		var sort: String = "a list" if reached["holder"] is Array else "a map"
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s is %s, which has no methods: name the element to call it on, as in %s:0:%s"
+				% [reached["called"], sort, reached["called"], reached["name"]]
+			)
+		}
 	var holder: Object = reached["holder"]
 	var named: String = reached["name"]
 	if not holder.has_method(named):

package/build/godot/addons/gdharness_runtime/runtime_values.gd

@@ -136,7 +136,36 @@ func _serialize_object(value: Object) -> Dictionary:
 		var node: Node = value
 		if node.is_inside_tree():
 			return {"_type": "Node", "class": node.get_class(), "path": str(node.get_path())}
-	return {"_type": "Object", "class": value.get_class()}
+	return _describe_object(value)
+
+
+## A plain object, said in enough detail to tell it from the one beside it.
+##
+## `{"class": "RefCounted"}` was all of it, so a roster of twelve people came back as the word
+## RefCounted twelve times: correct, useless, and indistinguishable from a list of twelve of
+## anything else. The state worth looking at in a game is lists of these, so each one carries what
+## it is (the `class_name` its script declares, or the script's path when it has no name), what it
+## says about itself when the game has given it a `_to_string`, and an id that is at least
+## different per object. None of it is invented: every field is left out when there is nothing to
+## put in it, because a key holding "" is a worse answer than a key that is not there.
+func _describe_object(value: Object) -> Dictionary:
+	var described: Dictionary = {"_type": "Object", "class": value.get_class()}
+	# Asked as a Variant and narrowed, because get_script answers one and an object without a
+	# script answers null: casting that to Script is the unsafe cast the engine refuses to compile.
+	var attached: Variant = value.get_script()
+	if attached is Script:
+		var script: Script = attached
+		var declared: String = String(script.get_global_name())
+		if not declared.is_empty():
+			described["script_class"] = declared
+		elif not script.resource_path.is_empty():
+			described["script"] = script.resource_path
+	# Only when the game wrote one. The default is "<RefCounted#31098236>", which is the id again
+	# in a costume and reads as if the object had been asked and had nothing to say.
+	if value.has_method("_to_string"):
+		described["says"] = value.to_string()
+	described["id"] = value.get_instance_id()
+	return described
 
 
 ## Rebuilds a Godot value from the shape serialize gave it.

package/build/index.js

@@ -28603,7 +28603,7 @@ var TOOL_SPECS = [
       property: {
         type: "string",
         ops: ["property", "find"],
-        description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through the objects a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about; a step that is not there is named.'
+        description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through what a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about. A number or a key steps into a list or a map, "_game:run:roster:0:traits", which is how the lists a game keeps its state in are walked: a roster, a board, an in-tray. A negative number counts from the end. A step that is not there is named, and says what was there instead.'
       },
       depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
       includeProperties: {
@@ -28677,7 +28677,7 @@ var TOOL_SPECS = [
       property: {
         type: "string",
         ops: ["set"],
-        description: 'set: which one to write. Colons write through the objects a node holds, "_game:run:day", and the answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+        description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
       },
       value: {
         ops: ["set"],
@@ -28687,7 +28687,7 @@ var TOOL_SPECS = [
       method: {
         type: "string",
         ops: ["call"],
-        description: 'call: which one to call. Colons call through the objects a node holds, "_game:run:advance", the same way a property is written through them.'
+        description: 'call: which one to call. Colons call through what a node holds, "_game:run:advance", the same way a property is written through them, and a list or a map is stepped into by index or key, "_game:run:roster:0:retire".'
       },
       args: {
         type: "array",

package/package.json

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