gdharness 0.12.5 → 0.12.7

package/README.md

@@ -15,10 +15,15 @@
 [![Bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FAureliolo%2Fgdharness%2Fmain%2Fpackage.json&query=%24.engines.bun&label=bun&color=f9f1e1&logo=bun&logoColor=black)](https://bun.sh/)
 [![Licence](https://img.shields.io/github/license/Aureliolo/gdharness)](LICENSE)
 
-Drive a Godot 4 project from an agent: the editor that is open, the game that is running, and the
-project on disk.
+**An agent cannot see a running game.** It reads your scripts and guesses at the rest: whether the
+button is on screen, whether the panel updated, whether that error mattered.
 
-**Hand this to your agent:**
+gdharness makes the engine answerable instead. What the screen says, where a control is, what a
+property reads right now, what the console printed, what broke and on which line.
+
+## Install
+
+Hand this to your agent:
 
 ```text
 Install gdharness into this project by following
@@ -27,31 +32,39 @@ recommend back to me.
 ```
 
 Or do it yourself, and pick your harness:
-[aureliolo.github.io/gdharness](https://aureliolo.github.io/gdharness)
+[aureliolo.github.io/gdharness](https://aureliolo.github.io/gdharness).
 
-## What it is for
-
-An agent cannot see a running game. This makes one answerable: where a control is, what a property
-reads, what the console printed, what broke and on which line.
+## The loop it exists for
 
 ```jsonc
-runtime_inspect { "op": "rect", "nodePath": "/root/Hall/Ledger/BuyButton" }
-
-{ "canvas": { "position": { "x": 812, "y": 418 }, "size": { "x": 180, "y": 34 } },
-  "visible": true }
+editor_run      { "op": "start", "projectPath": "C:/games/hall" }
+runtime_inspect { "op": "find", "says": "Buy" }              // the button, by the word on it
+runtime_input   { "op": "click", "nodePath": "/root/Hall/Ledger/BuyButton" }
+runtime_inspect { "op": "text", "nodePath": "/root/Hall/Ledger" }   // what the panel says now
+editor_output   { "projectPath": "C:/games/hall" }           // errors and warnings, with backtraces
 ```
 
+The open editor plays the game, so its debugger holds it, which is what lets you set a breakpoint
+and read the variables in scope when it stops.
+
+Every answer is read back out of the engine after the fact, never echoed from the request. A tool
+that cannot answer says which state it is in and what would change it, rather than answering
+emptily, so a call that succeeded is a call that was understood.
+
 ## At a glance
 
-|           |                                                                          |
-| --------- | ------------------------------------------------------------------------ |
-| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.            |
-| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                 |
-| Reaches   | The editor that is open, a game it is playing, and the project on disk   |
-| Harnesses | 35, written inside the project wherever the harness has a project config |
-| Skill     | Written to `.agents/skills`, which every major harness reads             |
-| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3       |
-| Proven    | Every tool driven against a pinned Godot in CI, on three platforms       |
+|           |                                                                                  |
+| --------- | -------------------------------------------------------------------------------- |
+| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.                    |
+| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                         |
+| Reaches   | The editor that is open, a game it is playing, and the project on disk           |
+| Harnesses | 35, written inside the project wherever the harness has a project config         |
+| Skill     | Written to `.agents/skills`, which every major harness reads                     |
+| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3               |
+| Proven    | Every tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS         |
+| Status    | 0.x: pin an exact version. [What a bump means](.github/CONTRIBUTING.md#versions) |
+
+Older 4.x is likely to work and is not tested.
 
 ## Documentation
 
@@ -61,30 +74,6 @@ parts connect, and every tool, op and argument.
 [SECURITY.md](.github/SECURITY.md) is how to report something.
 [CONTRIBUTING.md](.github/CONTRIBUTING.md) is what a change has to clear.
 
-## Versions
-
-0.x, and the number is telling the truth: the tools, their arguments and the shape of their
-answers are still moving, because the projects using this keep finding answers that were wrong or
-missing. Pin an exact version and upgrade deliberately.
-
-Built and measured against Godot 4.7.2 on Windows, Linux and macOS. The editor, engine, runtime
-and integration suites run against a real engine on all three before anything is tagged. Older
-4.x is likely to work and is not tested.
-
-What each kind of release means here:
-
-- **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.
-
-1.0 is not a date, it is a condition: the tool surface holding still for a fortnight, and the
-issues arriving being things it cannot do yet rather than things it answers wrongly.
-
 ## Project
 
 Fork of [GoPeak](https://github.com/HaD0Yun/Doyunha-Gopeak) v2.3.9, September 2026, MIT: the

package/build/cli.js

@@ -15427,7 +15427,7 @@ var init_tool_definitions = __esm(() => {
         },
         failFast: {
           type: "boolean",
-          description: "Stop at the first failure. Default false: the whole set runs."
+          description: "Stop each suite at its first failing case. Default false: every case runs. With it on, the counts are of what ran, notRun says how many cases were left, and fixing what is named and running again finds the next one, which looks like a flaky tier and is not."
         },
         timeoutMs: {
           type: "number",
@@ -35167,16 +35167,20 @@ function parseJUnit(xml) {
     throw new MalformedReportError("No <testsuites> or <testsuite> in the report");
   }
   const suiteElements = top.name === "testsuite" ? [top] : top.children.filter((child) => child.name === "testsuite");
-  const suites = suiteElements.map((suite) => ({
-    name: suite.attributes["name"] ?? "",
-    path: pathOf(suite),
-    tests: count(suite.attributes, "tests"),
-    failures: count(suite.attributes, "failures"),
-    errors: count(suite.attributes, "errors"),
-    skipped: count(suite.attributes, "skipped"),
-    time: count(suite.attributes, "time"),
-    cases: suite.children.filter((child) => child.name === "testcase").map((element) => caseOf(suite, element))
-  }));
+  const suites = suiteElements.map((suite) => {
+    const cases = suite.children.filter((child) => child.name === "testcase").map((element) => caseOf(suite, element));
+    return {
+      name: suite.attributes["name"] ?? "",
+      path: pathOf(suite),
+      tests: cases.length,
+      discovered: count(suite.attributes, "tests"),
+      failures: cases.filter((entry) => entry.status === "failed").length,
+      errors: cases.filter((entry) => entry.status === "error").length,
+      skipped: cases.filter((entry) => entry.status === "skipped").length,
+      time: count(suite.attributes, "time"),
+      cases
+    };
+  });
   const all = suites.flatMap((suite) => suite.cases);
   return {
     tests: all.length,
@@ -37475,6 +37479,7 @@ class GodotServer {
       message: `${suite.orphans} node${suite.orphans === 1 ? "" : "s"} were still in the tree when this suite finished. A node built in a test and neither freed nor added to the tree is the usual cause; free it, or add it with auto_free().`
     }));
     const unclean = report.suites.filter((suite) => suite.failures > 0 || suite.errors > 0 || suite.skipped > 0 || orphansIn(suite.path) > 0);
+    const notRun = report.suites.reduce((sum, suite) => sum + Math.max(0, suite.discovered - suite.tests), 0);
     return this.jsonTextResponse({
       passed: !hung && exitCode === 0 && report.failures === 0 && report.errors === 0,
       verdict,
@@ -37487,11 +37492,13 @@ class GodotServer {
       failed,
       warnings: warnings.length > 0 ? warnings : undefined,
       orphans: orphans.total > 0 ? orphans.total : undefined,
-      note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : undefined,
+      notRun: notRun > 0 ? notRun : undefined,
+      note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : notRun > 0 ? `This run stopped at the first failure in each suite it failed in, so ${notRun} case${notRun === 1 ? "" : "s"} never ran and count as neither passed nor failed. Leave failFast out to run every case.` : undefined,
       suites: unclean.map((suite) => ({
         name: suite.name,
         path: suite.path,
         tests: suite.tests,
+        notRun: suite.discovered > suite.tests ? suite.discovered - suite.tests : undefined,
         failures: suite.failures,
         errors: suite.errors,
         skipped: suite.skipped,

package/build/index.js

@@ -26592,16 +26592,20 @@ function parseJUnit(xml) {
     throw new MalformedReportError("No <testsuites> or <testsuite> in the report");
   }
   const suiteElements = top.name === "testsuite" ? [top] : top.children.filter((child) => child.name === "testsuite");
-  const suites = suiteElements.map((suite) => ({
-    name: suite.attributes["name"] ?? "",
-    path: pathOf(suite),
-    tests: count(suite.attributes, "tests"),
-    failures: count(suite.attributes, "failures"),
-    errors: count(suite.attributes, "errors"),
-    skipped: count(suite.attributes, "skipped"),
-    time: count(suite.attributes, "time"),
-    cases: suite.children.filter((child) => child.name === "testcase").map((element) => caseOf(suite, element))
-  }));
+  const suites = suiteElements.map((suite) => {
+    const cases = suite.children.filter((child) => child.name === "testcase").map((element) => caseOf(suite, element));
+    return {
+      name: suite.attributes["name"] ?? "",
+      path: pathOf(suite),
+      tests: cases.length,
+      discovered: count(suite.attributes, "tests"),
+      failures: cases.filter((entry) => entry.status === "failed").length,
+      errors: cases.filter((entry) => entry.status === "error").length,
+      skipped: cases.filter((entry) => entry.status === "skipped").length,
+      time: count(suite.attributes, "time"),
+      cases
+    };
+  });
   const all = suites.flatMap((suite) => suite.cases);
   return {
     tests: all.length,
@@ -28298,7 +28302,7 @@ var TOOL_SPECS = [
       },
       failFast: {
         type: "boolean",
-        description: "Stop at the first failure. Default false: the whole set runs."
+        description: "Stop each suite at its first failing case. Default false: every case runs. With it on, the counts are of what ran, notRun says how many cases were left, and fixing what is named and running again finds the next one, which looks like a flaky tier and is not."
       },
       timeoutMs: {
         type: "number",
@@ -30257,6 +30261,7 @@ class GodotServer {
       message: `${suite.orphans} node${suite.orphans === 1 ? "" : "s"} were still in the tree when this suite finished. A node built in a test and neither freed nor added to the tree is the usual cause; free it, or add it with auto_free().`
     }));
     const unclean = report.suites.filter((suite) => suite.failures > 0 || suite.errors > 0 || suite.skipped > 0 || orphansIn(suite.path) > 0);
+    const notRun = report.suites.reduce((sum, suite) => sum + Math.max(0, suite.discovered - suite.tests), 0);
     return this.jsonTextResponse({
       passed: !hung && exitCode === 0 && report.failures === 0 && report.errors === 0,
       verdict,
@@ -30269,11 +30274,13 @@ class GodotServer {
       failed,
       warnings: warnings.length > 0 ? warnings : undefined,
       orphans: orphans.total > 0 ? orphans.total : undefined,
-      note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : undefined,
+      notRun: notRun > 0 ? notRun : undefined,
+      note: verdict.startsWith("warnings") && warnings.length === 0 ? "gdUnit4 exits 101 for orphan nodes when nothing failed, and this run printed no count of them: orphan reporting may be off in the project settings." : notRun > 0 ? `This run stopped at the first failure in each suite it failed in, so ${notRun} case${notRun === 1 ? "" : "s"} never ran and count as neither passed nor failed. Leave failFast out to run every case.` : undefined,
       suites: unclean.map((suite) => ({
         name: suite.name,
         path: suite.path,
         tests: suite.tests,
+        notRun: suite.discovered > suite.tests ? suite.discovered - suite.tests : undefined,
         failures: suite.failures,
         errors: suite.errors,
         skipped: suite.skipped,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.12.5",
+  "version": "0.12.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",