gdharness 1.1.48 → 1.1.50

package/build/cli.js

@@ -17843,10 +17843,14 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "script_diagnostics",
-      description: "Errors and warnings for a script from the editor's language server, and whether the script is clean. Needs the editor running. Diagnostics are checked against the project's own files, and the two that the files disprove are named rather than passed on: a member the class cache's file declares, a method, property, constant, static function or enum member, comes back under contradictedByTheFile, and a class this project declares that the diagnostic could not resolve comes back under typesTheEditorHasNotLoaded, with inTheClassCache saying whether a launched game would resolve it. staleAnalysis then says what to do, and for both states it is editor_rescan first: it asks the editor already running, starts nothing, and has cleared each in every reproduction measured. Two exceptions are named when they apply. For an enum member, constant or static function of a global class the reload comes first: in the one project that has reproduced a stale enum member, editor_rescan with reloadScript on the declaring script cleared it and a plain rescan did not. And an editor whose last scan wrote the class cache shorter than the file holds a list behind the files and writes it on every scan, so on that editor the rescan loads nothing and staleAnalysis says editor_launch restart instead. What follows differs: for a stale analysed type, editor_rescan with reloadScript recompiles the held copy and editor_launch restart is the last resort that costs a window; for a class missing from the cache, project_import refresh_classes rewrites the cache from disk at the cost of a short headless engine, which matters beside a running bench.",
+      description: "Errors and warnings for a script, or for several, from the editor's language server, and whether each is clean. Needs the editor running. Diagnostics are checked against the project's own files, and the two that the files disprove are named rather than passed on: a member the class cache's file declares, a method, property, constant, static function or enum member, comes back under contradictedByTheFile, and a class this project declares that the diagnostic could not resolve comes back under typesTheEditorHasNotLoaded, with inTheClassCache saying whether a launched game would resolve it. staleAnalysis then says what to do, and for both states it is editor_rescan first: it asks the editor already running, starts nothing, and has cleared each in every reproduction measured. Two exceptions are named when they apply. For an enum member, constant or static function of a global class the reload comes first: in the one project that has reproduced a stale enum member, editor_rescan with reloadScript on the declaring script cleared it and a plain rescan did not. And an editor whose last scan wrote the class cache shorter than the file holds a list behind the files and writes it on every scan, so on that editor the rescan loads nothing and staleAnalysis says editor_launch restart instead. What follows differs: for a stale analysed type, editor_rescan with reloadScript recompiles the held copy and editor_launch restart is the last resort that costs a window; for a class missing from the cache, project_import refresh_classes rewrites the cache from disk at the cost of a short headless engine, which matters beside a running bench.",
       parameters: {
         projectPath: PROJECT_PATH,
-        scriptPath: SCRIPT_PATH
+        scriptPath: {
+          type: ["string", "array"],
+          items: { type: "string" },
+          description: 'A script inside the project, a folder, or a list of either, such as "scripts/player.gd" or ["scripts/economy", "ui/shop.gd"]. A folder is its .gd files at any depth, skipping what the engine skips. One script is answered as it always was; several are answered together under scripts, each in that same shape, with clean, errors and warnings for all of them beside it, and a script that could not be read is named there with why while the rest are still asked about. At most 300 scripts a call.'
+        }
       },
       requires: ["projectPath", "scriptPath"]
     },
@@ -18589,6 +18593,106 @@ var init_headless_operations = __esm(() => {
   });
 });
 
+// src/tool-reference.ts
+function namedType(declared) {
+  if (typeof declared === "string") {
+    return declared;
+  }
+  if (Array.isArray(declared) && declared.every((kind) => typeof kind === "string")) {
+    return declared.join(" or ");
+  }
+  return "any";
+}
+function argumentShape(schema) {
+  const named = namedType(schema["type"]);
+  const items = schema["items"];
+  const held = typeof items === "object" && items !== null && !Array.isArray(items) ? namedType(items["type"]) : "any";
+  return named.split(" or ").map((kind) => kind === "array" && held !== "any" ? `array of ${held}s` : kind).join(" or ");
+}
+function headlessSection() {
+  const everyOp = new Map;
+  for (const table of [HEADLESS_OPERATIONS, ENGINE_PASSES]) {
+    for (const [tool, ops] of Object.entries(table)) {
+      everyOp.set(tool, [...everyOp.get(tool) ?? [], ...Object.keys(ops)]);
+    }
+  }
+  const byTool = [...everyOp].map(([tool, ops]) => `\`${tool}\` (${ops.join(", ")})`).sort();
+  return [
+    "## What a gate can call",
+    "",
+    "These answer from a short-lived headless engine: no editor window, no running game, and no",
+    "process or port outliving the answer. They are the only calls an automatic check can make at",
+    "all, because every other tool needs an editor somebody has open or a game somebody is running.",
+    "",
+    ...byTool.map((line) => `- ${line}`),
+    "",
+    "Needing nothing is not the same as changing nothing, and a gate wants both. Most of these",
+    "write to the project because that is what they are for: `script_edit create` writes a file,",
+    "`project_settings set` rewrites `project.godot`, `project_import reimport` and `refresh_classes`",
+    "write under `.godot`, and `project_import refresh_uids` writes a `.uid` beside each script that",
+    "had none. The reading ops are the ones to gate on, and which is which is in each",
+    "op's own summary below rather than assumed from this list.",
+    "",
+    "Everything else needs the editor (`editor_*`, `debug_*`, `scene_*`, `resource_*`) or a running",
+    "game (`runtime_*`).",
+    "",
+    'One of these can be pointed the other way: `project_settings get` takes `from: "editor"` to ask',
+    "the open editor instead of the file, which is a different reading and costs no engine start. A",
+    "gate leaves it alone, because there is no editor on a build machine and the call is refused",
+    "rather than answered from the file.",
+    ""
+  ];
+}
+function renderToolsMarkdown() {
+  const lines = [
+    "# Tools",
+    "",
+    `${TOOL_SPECS.length} tools, named \`domain_verb\`. A tool that does several related things takes an`,
+    "`op`. An unknown op or argument is refused with the valid set listed. Generated from the server.",
+    "",
+    `${projectPathSentence()}: the \`runtime_*\` and \`debug_*\` ones pick between running games`,
+    "instead, and the others answer about the editor on this server. The pick, when a call names",
+    `neither \`projectPath\` nor \`pid\`: ${theGamePicked()}. An argument a tool does not`,
+    "declare is refused rather than ignored. Answers are read from the engine after the change, not",
+    "echoed from the request. Engine stderr comes back under `engine_messages`.",
+    "",
+    ...headlessSection()
+  ];
+  for (const tool of TOOL_SPECS) {
+    lines.push(`## ${tool.name}`, "", tool.description, "");
+    const operations = Object.entries(tool.operations ?? {});
+    if (operations.length > 0) {
+      for (const [op, spec] of operations) {
+        const needs = [...tool.requires, ...spec.requires];
+        const isDefault = tool.defaultOperation === op ? " (default)" : "";
+        const wants = needs.length > 0 ? ` Needs: ${needs.map((name) => `\`${name}\``).join(", ")}.` : "";
+        const spare = argumentsOf(tool, op).filter((name) => !needs.includes(name) && name !== "projectPath");
+        const takes = spare.length > 0 ? ` Takes: ${spare.map((name) => `\`${name}\``).join(", ")}.` : "";
+        lines.push(`- \`op: ${op}\`${isDefault}: ${spec.summary}.${wants}${takes}`);
+      }
+      lines.push("");
+    } else if (tool.requires.length > 0) {
+      lines.push(`Needs: ${tool.requires.map((name) => `\`${name}\``).join(", ")}.`, "");
+    }
+    const parameters = Object.entries(tool.parameters).filter(([name]) => name !== "projectPath");
+    if (parameters.length > 0) {
+      lines.push("Arguments:", "");
+      for (const [name, schema] of parameters) {
+        const type = argumentShape(schema);
+        const note = typeof schema["description"] === "string" ? `: ${schema["description"]}` : "";
+        lines.push(`- \`${name}\` (${type})${note}`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join(`
+`);
+}
+var init_tool_reference = __esm(() => {
+  init_headless_operations();
+  init_tool_definitions();
+});
+
 // node_modules/zod/v3/helpers/util.js
 var util, objectUtil, ZodParsedType, getParsedType = (data) => {
   const t = typeof data;
@@ -39388,7 +39492,7 @@ class GodotLSPClient {
       const diagnosticsPromise = new Promise((resolveDiagnostics, rejectDiagnostics) => {
         const timer = setTimeout(() => {
           this.diagnosticsWaiters.delete(key);
-          rejectDiagnostics(new Error(`Godot published no diagnostics for ${key} within ${DIAGNOSTICS_TIMEOUT_MS}ms. ` + "The language server may not be running, or may not have this file in its workspace."));
+          rejectDiagnostics(new NoDiagnosticsPublished(`Godot published no diagnostics for ${key} within ${DIAGNOSTICS_TIMEOUT_MS}ms. ` + "The language server may not be running, or may not have this file in its workspace."));
         }, DIAGNOSTICS_TIMEOUT_MS);
         this.diagnosticsWaiters.set(key, {
           resolve: resolveDiagnostics,
@@ -39618,11 +39722,12 @@ async function handleLSPTool(client, toolName, args) {
     return asToolResponse({
       error: normalizeLSPError(error, client.port),
       ...error instanceof AnotherProjectsServer ? { serves: error.serves } : {},
-      ...error instanceof ArgumentRefusal ? { refusedArguments: true } : {}
+      ...error instanceof ArgumentRefusal ? { refusedArguments: true } : {},
+      ...error instanceof NoDiagnosticsPublished ? { aboutThisFile: true } : {}
     });
   }
 }
-var DEFAULT_LSP_PORT = 6005, DIAGNOSTICS_TIMEOUT_MS = 5000, REQUEST_TIMEOUT_MS2 = 1e4, REFERENCES_TIMEOUT_MS = 180000, LSPTimeout, ArgumentRefusal, AnotherProjectsServer;
+var DEFAULT_LSP_PORT = 6005, DIAGNOSTICS_TIMEOUT_MS = 5000, REQUEST_TIMEOUT_MS2 = 1e4, REFERENCES_TIMEOUT_MS = 180000, LSPTimeout, ArgumentRefusal, NoDiagnosticsPublished, AnotherProjectsServer;
 var init_lsp_client = __esm(() => {
   init_answer_json();
   init_errors();
@@ -39640,6 +39745,8 @@ var init_lsp_client = __esm(() => {
   };
   ArgumentRefusal = class ArgumentRefusal extends Refusal {
   };
+  NoDiagnosticsPublished = class NoDiagnosticsPublished extends Error {
+  };
   AnotherProjectsServer = class AnotherProjectsServer extends Refusal {
     serves;
     constructor(port, serves, asked) {
@@ -42468,6 +42575,82 @@ function testPathsIn(projectPath, given) {
     value: unique.filter((path) => !unique.some((other) => other !== path && within(path, other))).map((path) => `res://${path}`)
   };
 }
+function scriptsToDiagnose(projectPath, given) {
+  const listed = Array.isArray(given);
+  if (!listed) {
+    const one = typeof given === "string" ? resolveWithinProject(projectPath, given) : null;
+    if (one === null || !one.ok || !isDirectory(one.absolutePath)) {
+      return { ok: true, value: null };
+    }
+  }
+  const entries = listed ? given : [given];
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      reason: "scriptPath is an empty list: name a script, a folder, or a list of either."
+    };
+  }
+  const found = [];
+  const empty = [];
+  for (const [index, entry] of entries.entries()) {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      return {
+        ok: false,
+        reason: `scriptPath${listed ? `[${index}]` : ""} is ${typeof entry === "string" ? "empty" : describeValue(entry)}, not a script or a folder in the project.`
+      };
+    }
+    const location = resolveWithinProject(projectPath, entry);
+    if (!location.ok) {
+      return { ok: false, reason: location.reason };
+    }
+    const relative = location.relativePath.replace(/\/+$/, "");
+    if (!isDirectory(location.absolutePath)) {
+      found.push(relative);
+      continue;
+    }
+    const inside = scriptsUnder(location.absolutePath, relative);
+    if (inside.length === 0) {
+      empty.push(entry);
+    }
+    found.push(...inside);
+  }
+  const unique = [...new Set(found)];
+  if (unique.length === 0) {
+    return { ok: false, reason: `No .gd script is under ${empty.join(" or ")}.` };
+  }
+  if (unique.length > MOST_DIAGNOSED) {
+    return {
+      ok: false,
+      reason: `scriptPath names ${unique.length} scripts, and one call asks about at most ${MOST_DIAGNOSED}, each a round trip through the language server: name narrower folders, or call again for the rest.`
+    };
+  }
+  return { ok: true, value: unique };
+}
+function isDirectory(path) {
+  try {
+    return statSync9(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function scriptsUnder(directory, prefix) {
+  if (existsSync20(join26(directory, ".gdignore"))) {
+    return [];
+  }
+  const found = [];
+  for (const entry of readdirSync10(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      found.push(...scriptsUnder(join26(directory, entry.name), path));
+    } else if (entry.isFile() && entry.name.endsWith(".gd")) {
+      found.push(path);
+    }
+  }
+  return found;
+}
 function hasMainScene(projectFile) {
   const scene = parseProjectGodot(readFileSync22(projectFile, "utf8"))["application"]?.["run/main_scene"];
   return typeof scene === "string" && scene !== "";
@@ -42945,7 +43128,14 @@ class GodotServer {
       const asked = readString(args, "op");
       const named = asked !== undefined && spec.operations?.[asked] !== undefined ? asked : null;
       const wanted = named === null ? [...known] : [...argumentsOf(spec, named), "op"];
-      const takes = wanted.length === 0 ? "It takes no arguments." : `It takes: ${wanted.join(", ")}.`;
+      const shaped = wanted.map((name) => {
+        const schema = spec.parameters[name];
+        if (schema !== undefined) {
+          return `${name} (${argumentShape(schema)})`;
+        }
+        return name === "op" && named === null && spec.operations !== undefined ? `op (${Object.keys(spec.operations).join(", ")})` : name;
+      });
+      const takes = wanted.length === 0 ? "It takes no arguments." : `It takes: ${shaped.join(", ")}.`;
       const where = named === null ? spec.name : `${spec.name} ${named}`;
       return {
         ok: false,
@@ -44289,39 +44479,88 @@ class GodotServer {
     }
   }
   async handleScriptDiagnostics(args) {
+    const project = this.project(args);
+    const scripts = project.ok ? scriptsToDiagnose(project.value.path, args["scriptPath"]) : null;
+    if (scripts !== null && !scripts.ok) {
+      return this.createErrorResponse(scripts.reason);
+    }
+    if (scripts?.value == null) {
+      const one = await this.diagnosticsOf(args);
+      return "refusal" in one ? one.refusal : this.jsonTextResponse(this.markedIfStale(one.answer));
+    }
+    const progress = callProgress();
+    const answers = [];
+    let errors = 0;
+    let warnings = 0;
+    let unread = 0;
+    for (const [at, scriptPath] of scripts.value.entries()) {
+      progress?.(at + 1, `${at + 1} of ${scripts.value.length}: ${scriptPath}`);
+      const one = await this.diagnosticsOf({ ...args, scriptPath });
+      if ("refusal" in one) {
+        if (!one.perScript) {
+          return one.refusal;
+        }
+        unread += 1;
+        answers.push({ scriptPath, error: one.refusal.content[0]?.text ?? "not read" });
+        continue;
+      }
+      errors += Number(one.answer["errors"]);
+      warnings += Number(one.answer["warnings"]);
+      answers.push(one.answer);
+    }
+    return this.jsonTextResponse(this.markedIfStale({
+      clean: errors === 0 && unread === 0,
+      scriptsChecked: answers.length,
+      errors,
+      warnings,
+      ...unread > 0 ? { scriptsNotRead: unread } : {},
+      scripts: answers
+    }));
+  }
+  markedIfStale(answer) {
+    return markIfStale(answer, this.godotBridge.getStatus().addonVersion, SERVER_VERSION, this.godotBridge.getStatus().addonDigest, shippedEditorDigest(), this.editorCodeOnDisk());
+  }
+  async diagnosticsOf(args) {
     const answer = await this.handleLSP("lsp_get_diagnostics", args);
     const payload = asParams(JSON.parse(answer.content[0]?.text ?? "{}"));
     if (payload["error"] !== undefined) {
       const reason = typeof payload["error"] === "string" ? payload["error"] : JSON.stringify(payload["error"]);
       if (payload["refusedArguments"] === true) {
-        return this.createErrorResponse(reason);
+        return { refusal: this.createErrorResponse(reason), perScript: true };
       }
       if (typeof payload["serves"] === "string") {
-        return this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
-          "editor_status names the editor on the bridge and the port it says it serves",
-          "editor_launch opens this project's own editor, on a language server port of its own",
-          "GDHARNESS_LSP_PORT points this server at the right one"
-        ]);
+        return {
+          refusal: this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
+            "editor_status names the editor on the bridge and the port it says it serves",
+            "editor_launch opens this project's own editor, on a language server port of its own",
+            "GDHARNESS_LSP_PORT points this server at the right one"
+          ]),
+          perScript: false
+        };
       }
-      return this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
-        `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
-        "GDHARNESS_LSP_PORT points this server at another one"
-      ]);
+      return {
+        refusal: this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
+          `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
+          "GDHARNESS_LSP_PORT points this server at another one"
+        ]),
+        perScript: payload["aboutThisFile"] === true
+      };
     }
     const diagnostics = readArray(payload, "diagnostics") ?? [];
     const errors = diagnostics.filter((entry) => {
       const severity = asParams(entry)["severity"];
       return severity === 1 || severity === "error" || severity === "ERROR";
     }).length;
-    const disagrees = this.whereTheFileDisagrees(diagnostics, args);
-    return this.jsonTextResponse(markIfStale({
-      scriptPath: readString(args, "scriptPath"),
-      clean: errors === 0,
-      errors,
-      warnings: diagnostics.length - errors,
-      diagnostics,
-      ...disagrees
-    }, this.godotBridge.getStatus().addonVersion, SERVER_VERSION, this.godotBridge.getStatus().addonDigest, shippedEditorDigest(), this.editorCodeOnDisk()));
+    return {
+      answer: {
+        scriptPath: readString(args, "scriptPath"),
+        clean: errors === 0,
+        errors,
+        warnings: diagnostics.length - errors,
+        diagnostics,
+        ...this.whereTheFileDisagrees(diagnostics, args)
+      }
+    };
   }
   whereTheFileDisagrees(diagnostics, args) {
     const messages = diagnostics.map((entry) => asParams(entry)["message"]).filter((message) => typeof message === "string");
@@ -47131,7 +47370,7 @@ async function runGodotServer() {
   const server = new GodotServer;
   await server.run();
 }
-var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run4, __dirname2, GREETING_WAIT_MS = 1e4, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, STOP_WAIT_MS = 1e4, KEEPER_ANSWER_MS = 15000, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, SCAN_WAIT_MS = 30000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, SCAN_SETTLED_MS = 500, REIMPORT_TIMEOUT_MS = 300000, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/";
+var UPDATE_NOTICE_EVERY = 500, FEEDBACK_NOTICE_EVERY = 250, run4, __dirname2, GREETING_WAIT_MS = 1e4, HOLD_PING_MS = 2000, SLOWEST_FRAME_RATE = 20, PLAY_STARTS_WITHIN_MS = 30000, STOP_WAIT_MS = 1e4, KEEPER_ANSWER_MS = 15000, EXIT_REPORTED_WITHIN_MS = 2000, CONSOLE_WRAPPER, LONGEST_BOOT_NOTED_MS, MOST_GROUPS = 20, VALUE_NAMES, BRIDGE_RETRY_MS = 2000, SUCCESSOR_CHECK_MS = 1e4, CONSOLE_WATCH_MS = 250, BOUNDARY_WAIT_MS = 2000, HANDOVER_MS, HANDOVER_POLL_MS = 250, CACHE_WRITE_MS = 2000, SCAN_WAIT_MS = 30000, STREAMS_GRACE_MS = 2000, PLAYING_STATUS_MS = 1000, SCAN_START_MS = 2000, SCAN_SETTLED_MS = 500, REIMPORT_TIMEOUT_MS = 300000, AUDIO_BUS_OPS, STALLED_AFTER_MS = 30000, TEST_HEARTBEAT_MS = 20000, DEPENDED_FAILED = "Failed to compile depended scripts", WAIT_FOR_RUN_MS = 600000, RUN_POLL_MS = 250, PATH_SOLUTIONS, PROJECT_FILE_ARGUMENTS, DEBUG_STATE_CALLS, PROJECT_INFO_SECTIONS2, RUNNER_DIRECTORY = "addons/gdUnit4/", MOST_DIAGNOSED = 300;
 var init_server3 = __esm(() => {
   init_mcp();
   init_stdio2();
@@ -47177,6 +47416,7 @@ var init_server3 = __esm(() => {
   init_server_version();
   init_setup();
   init_tool_definitions();
+  init_tool_reference();
   init_update_check();
   run4 = promisify5(execFile5);
   __dirname2 = dirname19(fileURLToPath5(import.meta.url));
@@ -48170,102 +48410,9 @@ init_setup();
 // src/skill.ts
 init_setup();
 init_tool_definitions();
+init_tool_reference();
 import { existsSync as existsSync11, mkdirSync as mkdirSync5, readdirSync as readdirSync5, rmSync as rmSync6, writeFileSync as writeFileSync7 } from "node:fs";
 import { basename as basename4, dirname as dirname6, join as join11 } from "node:path";
-
-// src/tool-reference.ts
-init_headless_operations();
-init_tool_definitions();
-function namedType(declared) {
-  if (typeof declared === "string") {
-    return declared;
-  }
-  if (Array.isArray(declared) && declared.every((kind) => typeof kind === "string")) {
-    return declared.join(" or ");
-  }
-  return "any";
-}
-function headlessSection() {
-  const everyOp = new Map;
-  for (const table of [HEADLESS_OPERATIONS, ENGINE_PASSES]) {
-    for (const [tool, ops] of Object.entries(table)) {
-      everyOp.set(tool, [...everyOp.get(tool) ?? [], ...Object.keys(ops)]);
-    }
-  }
-  const byTool = [...everyOp].map(([tool, ops]) => `\`${tool}\` (${ops.join(", ")})`).sort();
-  return [
-    "## What a gate can call",
-    "",
-    "These answer from a short-lived headless engine: no editor window, no running game, and no",
-    "process or port outliving the answer. They are the only calls an automatic check can make at",
-    "all, because every other tool needs an editor somebody has open or a game somebody is running.",
-    "",
-    ...byTool.map((line) => `- ${line}`),
-    "",
-    "Needing nothing is not the same as changing nothing, and a gate wants both. Most of these",
-    "write to the project because that is what they are for: `script_edit create` writes a file,",
-    "`project_settings set` rewrites `project.godot`, `project_import reimport` and `refresh_classes`",
-    "write under `.godot`, and `project_import refresh_uids` writes a `.uid` beside each script that",
-    "had none. The reading ops are the ones to gate on, and which is which is in each",
-    "op's own summary below rather than assumed from this list.",
-    "",
-    "Everything else needs the editor (`editor_*`, `debug_*`, `scene_*`, `resource_*`) or a running",
-    "game (`runtime_*`).",
-    "",
-    'One of these can be pointed the other way: `project_settings get` takes `from: "editor"` to ask',
-    "the open editor instead of the file, which is a different reading and costs no engine start. A",
-    "gate leaves it alone, because there is no editor on a build machine and the call is refused",
-    "rather than answered from the file.",
-    ""
-  ];
-}
-function renderToolsMarkdown() {
-  const lines = [
-    "# Tools",
-    "",
-    `${TOOL_SPECS.length} tools, named \`domain_verb\`. A tool that does several related things takes an`,
-    "`op`. An unknown op or argument is refused with the valid set listed. Generated from the server.",
-    "",
-    `${projectPathSentence()}: the \`runtime_*\` and \`debug_*\` ones pick between running games`,
-    "instead, and the others answer about the editor on this server. The pick, when a call names",
-    `neither \`projectPath\` nor \`pid\`: ${theGamePicked()}. An argument a tool does not`,
-    "declare is refused rather than ignored. Answers are read from the engine after the change, not",
-    "echoed from the request. Engine stderr comes back under `engine_messages`.",
-    "",
-    ...headlessSection()
-  ];
-  for (const tool of TOOL_SPECS) {
-    lines.push(`## ${tool.name}`, "", tool.description, "");
-    const operations = Object.entries(tool.operations ?? {});
-    if (operations.length > 0) {
-      for (const [op, spec] of operations) {
-        const needs = [...tool.requires, ...spec.requires];
-        const isDefault = tool.defaultOperation === op ? " (default)" : "";
-        const wants = needs.length > 0 ? ` Needs: ${needs.map((name) => `\`${name}\``).join(", ")}.` : "";
-        const spare = argumentsOf(tool, op).filter((name) => !needs.includes(name) && name !== "projectPath");
-        const takes = spare.length > 0 ? ` Takes: ${spare.map((name) => `\`${name}\``).join(", ")}.` : "";
-        lines.push(`- \`op: ${op}\`${isDefault}: ${spec.summary}.${wants}${takes}`);
-      }
-      lines.push("");
-    } else if (tool.requires.length > 0) {
-      lines.push(`Needs: ${tool.requires.map((name) => `\`${name}\``).join(", ")}.`, "");
-    }
-    const parameters = Object.entries(tool.parameters).filter(([name]) => name !== "projectPath");
-    if (parameters.length > 0) {
-      lines.push("Arguments:", "");
-      for (const [name, schema] of parameters) {
-        const type = namedType(schema["type"]);
-        const note = typeof schema["description"] === "string" ? `: ${schema["description"]}` : "";
-        lines.push(`- \`${name}\` (${type})${note}`);
-      }
-      lines.push("");
-    }
-  }
-  return lines.join(`
-`);
-}
-
-// src/skill.ts
 var SKILL_NAME = "gdharness";
 var SHARED_SKILLS = join11(".agents", "skills");
 function skillMarkdown(version) {

package/build/index.js

@@ -29729,6 +29729,9 @@ class LSPTimeout extends Error {
 class ArgumentRefusal extends Refusal {
 }
 
+class NoDiagnosticsPublished extends Error {
+}
+
 class AnotherProjectsServer extends Refusal {
   serves;
   constructor(port, serves, asked) {
@@ -30116,7 +30119,7 @@ class GodotLSPClient {
       const diagnosticsPromise = new Promise((resolveDiagnostics, rejectDiagnostics) => {
         const timer = setTimeout(() => {
           this.diagnosticsWaiters.delete(key);
-          rejectDiagnostics(new Error(`Godot published no diagnostics for ${key} within ${DIAGNOSTICS_TIMEOUT_MS}ms. ` + "The language server may not be running, or may not have this file in its workspace."));
+          rejectDiagnostics(new NoDiagnosticsPublished(`Godot published no diagnostics for ${key} within ${DIAGNOSTICS_TIMEOUT_MS}ms. ` + "The language server may not be running, or may not have this file in its workspace."));
         }, DIAGNOSTICS_TIMEOUT_MS);
         this.diagnosticsWaiters.set(key, {
           resolve: resolveDiagnostics,
@@ -30346,7 +30349,8 @@ async function handleLSPTool(client, toolName, args) {
     return asToolResponse({
       error: normalizeLSPError(error, client.port),
       ...error instanceof AnotherProjectsServer ? { serves: error.serves } : {},
-      ...error instanceof ArgumentRefusal ? { refusedArguments: true } : {}
+      ...error instanceof ArgumentRefusal ? { refusedArguments: true } : {},
+      ...error instanceof NoDiagnosticsPublished ? { aboutThisFile: true } : {}
     });
   }
 }
@@ -33520,10 +33524,14 @@ var TOOL_SPECS = [
   },
   {
     name: "script_diagnostics",
-    description: "Errors and warnings for a script from the editor's language server, and whether the script is clean. Needs the editor running. Diagnostics are checked against the project's own files, and the two that the files disprove are named rather than passed on: a member the class cache's file declares, a method, property, constant, static function or enum member, comes back under contradictedByTheFile, and a class this project declares that the diagnostic could not resolve comes back under typesTheEditorHasNotLoaded, with inTheClassCache saying whether a launched game would resolve it. staleAnalysis then says what to do, and for both states it is editor_rescan first: it asks the editor already running, starts nothing, and has cleared each in every reproduction measured. Two exceptions are named when they apply. For an enum member, constant or static function of a global class the reload comes first: in the one project that has reproduced a stale enum member, editor_rescan with reloadScript on the declaring script cleared it and a plain rescan did not. And an editor whose last scan wrote the class cache shorter than the file holds a list behind the files and writes it on every scan, so on that editor the rescan loads nothing and staleAnalysis says editor_launch restart instead. What follows differs: for a stale analysed type, editor_rescan with reloadScript recompiles the held copy and editor_launch restart is the last resort that costs a window; for a class missing from the cache, project_import refresh_classes rewrites the cache from disk at the cost of a short headless engine, which matters beside a running bench.",
+    description: "Errors and warnings for a script, or for several, from the editor's language server, and whether each is clean. Needs the editor running. Diagnostics are checked against the project's own files, and the two that the files disprove are named rather than passed on: a member the class cache's file declares, a method, property, constant, static function or enum member, comes back under contradictedByTheFile, and a class this project declares that the diagnostic could not resolve comes back under typesTheEditorHasNotLoaded, with inTheClassCache saying whether a launched game would resolve it. staleAnalysis then says what to do, and for both states it is editor_rescan first: it asks the editor already running, starts nothing, and has cleared each in every reproduction measured. Two exceptions are named when they apply. For an enum member, constant or static function of a global class the reload comes first: in the one project that has reproduced a stale enum member, editor_rescan with reloadScript on the declaring script cleared it and a plain rescan did not. And an editor whose last scan wrote the class cache shorter than the file holds a list behind the files and writes it on every scan, so on that editor the rescan loads nothing and staleAnalysis says editor_launch restart instead. What follows differs: for a stale analysed type, editor_rescan with reloadScript recompiles the held copy and editor_launch restart is the last resort that costs a window; for a class missing from the cache, project_import refresh_classes rewrites the cache from disk at the cost of a short headless engine, which matters beside a running bench.",
     parameters: {
       projectPath: PROJECT_PATH,
-      scriptPath: SCRIPT_PATH
+      scriptPath: {
+        type: ["string", "array"],
+        items: { type: "string" },
+        description: 'A script inside the project, a folder, or a list of either, such as "scripts/player.gd" or ["scripts/economy", "ui/shop.gd"]. A folder is its .gd files at any depth, skipping what the engine skips. One script is answered as it always was; several are answered together under scripts, each in that same shape, with clean, errors and warnings for all of them beside it, and a script that could not be read is named there with why while the rest are still asked about. At most 300 scripts a call.'
+      }
     },
     requires: ["projectPath", "scriptPath"]
   },
@@ -34268,6 +34276,23 @@ function buildToolDefinitions() {
   });
 }
 
+// src/tool-reference.ts
+function namedType(declared) {
+  if (typeof declared === "string") {
+    return declared;
+  }
+  if (Array.isArray(declared) && declared.every((kind) => typeof kind === "string")) {
+    return declared.join(" or ");
+  }
+  return "any";
+}
+function argumentShape(schema) {
+  const named = namedType(schema["type"]);
+  const items = schema["items"];
+  const held = typeof items === "object" && items !== null && !Array.isArray(items) ? namedType(items["type"]) : "any";
+  return named.split(" or ").map((kind) => kind === "array" && held !== "any" ? `array of ${held}s` : kind).join(" or ");
+}
+
 // src/server.ts
 var UPDATE_NOTICE_EVERY = 500;
 var FEEDBACK_NOTICE_EVERY = 250;
@@ -35037,6 +35062,83 @@ function testPathsIn(projectPath, given) {
     value: unique.filter((path) => !unique.some((other) => other !== path && within(path, other))).map((path) => `res://${path}`)
   };
 }
+var MOST_DIAGNOSED = 300;
+function scriptsToDiagnose(projectPath, given) {
+  const listed = Array.isArray(given);
+  if (!listed) {
+    const one = typeof given === "string" ? resolveWithinProject(projectPath, given) : null;
+    if (one === null || !one.ok || !isDirectory(one.absolutePath)) {
+      return { ok: true, value: null };
+    }
+  }
+  const entries = listed ? given : [given];
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      reason: "scriptPath is an empty list: name a script, a folder, or a list of either."
+    };
+  }
+  const found = [];
+  const empty = [];
+  for (const [index, entry] of entries.entries()) {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      return {
+        ok: false,
+        reason: `scriptPath${listed ? `[${index}]` : ""} is ${typeof entry === "string" ? "empty" : describeValue(entry)}, not a script or a folder in the project.`
+      };
+    }
+    const location = resolveWithinProject(projectPath, entry);
+    if (!location.ok) {
+      return { ok: false, reason: location.reason };
+    }
+    const relative = location.relativePath.replace(/\/+$/, "");
+    if (!isDirectory(location.absolutePath)) {
+      found.push(relative);
+      continue;
+    }
+    const inside = scriptsUnder(location.absolutePath, relative);
+    if (inside.length === 0) {
+      empty.push(entry);
+    }
+    found.push(...inside);
+  }
+  const unique = [...new Set(found)];
+  if (unique.length === 0) {
+    return { ok: false, reason: `No .gd script is under ${empty.join(" or ")}.` };
+  }
+  if (unique.length > MOST_DIAGNOSED) {
+    return {
+      ok: false,
+      reason: `scriptPath names ${unique.length} scripts, and one call asks about at most ${MOST_DIAGNOSED}, each a round trip through the language server: name narrower folders, or call again for the rest.`
+    };
+  }
+  return { ok: true, value: unique };
+}
+function isDirectory(path) {
+  try {
+    return statSync8(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function scriptsUnder(directory, prefix) {
+  if (existsSync17(join22(directory, ".gdignore"))) {
+    return [];
+  }
+  const found = [];
+  for (const entry of readdirSync9(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      found.push(...scriptsUnder(join22(directory, entry.name), path));
+    } else if (entry.isFile() && entry.name.endsWith(".gd")) {
+      found.push(path);
+    }
+  }
+  return found;
+}
 function hasMainScene(projectFile) {
   const scene = parseProjectGodot(readFileSync20(projectFile, "utf8"))["application"]?.["run/main_scene"];
   return typeof scene === "string" && scene !== "";
@@ -35514,7 +35616,14 @@ class GodotServer {
       const asked = readString(args, "op");
       const named = asked !== undefined && spec.operations?.[asked] !== undefined ? asked : null;
       const wanted = named === null ? [...known] : [...argumentsOf(spec, named), "op"];
-      const takes = wanted.length === 0 ? "It takes no arguments." : `It takes: ${wanted.join(", ")}.`;
+      const shaped = wanted.map((name) => {
+        const schema = spec.parameters[name];
+        if (schema !== undefined) {
+          return `${name} (${argumentShape(schema)})`;
+        }
+        return name === "op" && named === null && spec.operations !== undefined ? `op (${Object.keys(spec.operations).join(", ")})` : name;
+      });
+      const takes = wanted.length === 0 ? "It takes no arguments." : `It takes: ${shaped.join(", ")}.`;
       const where = named === null ? spec.name : `${spec.name} ${named}`;
       return {
         ok: false,
@@ -36858,39 +36967,88 @@ class GodotServer {
     }
   }
   async handleScriptDiagnostics(args) {
+    const project = this.project(args);
+    const scripts = project.ok ? scriptsToDiagnose(project.value.path, args["scriptPath"]) : null;
+    if (scripts !== null && !scripts.ok) {
+      return this.createErrorResponse(scripts.reason);
+    }
+    if (scripts?.value == null) {
+      const one = await this.diagnosticsOf(args);
+      return "refusal" in one ? one.refusal : this.jsonTextResponse(this.markedIfStale(one.answer));
+    }
+    const progress = callProgress();
+    const answers = [];
+    let errors = 0;
+    let warnings = 0;
+    let unread = 0;
+    for (const [at, scriptPath] of scripts.value.entries()) {
+      progress?.(at + 1, `${at + 1} of ${scripts.value.length}: ${scriptPath}`);
+      const one = await this.diagnosticsOf({ ...args, scriptPath });
+      if ("refusal" in one) {
+        if (!one.perScript) {
+          return one.refusal;
+        }
+        unread += 1;
+        answers.push({ scriptPath, error: one.refusal.content[0]?.text ?? "not read" });
+        continue;
+      }
+      errors += Number(one.answer["errors"]);
+      warnings += Number(one.answer["warnings"]);
+      answers.push(one.answer);
+    }
+    return this.jsonTextResponse(this.markedIfStale({
+      clean: errors === 0 && unread === 0,
+      scriptsChecked: answers.length,
+      errors,
+      warnings,
+      ...unread > 0 ? { scriptsNotRead: unread } : {},
+      scripts: answers
+    }));
+  }
+  markedIfStale(answer) {
+    return markIfStale(answer, this.godotBridge.getStatus().addonVersion, SERVER_VERSION, this.godotBridge.getStatus().addonDigest, shippedEditorDigest(), this.editorCodeOnDisk());
+  }
+  async diagnosticsOf(args) {
     const answer = await this.handleLSP("lsp_get_diagnostics", args);
     const payload = asParams(JSON.parse(answer.content[0]?.text ?? "{}"));
     if (payload["error"] !== undefined) {
       const reason = typeof payload["error"] === "string" ? payload["error"] : JSON.stringify(payload["error"]);
       if (payload["refusedArguments"] === true) {
-        return this.createErrorResponse(reason);
+        return { refusal: this.createErrorResponse(reason), perScript: true };
       }
       if (typeof payload["serves"] === "string") {
-        return this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
-          "editor_status names the editor on the bridge and the port it says it serves",
-          "editor_launch opens this project's own editor, on a language server port of its own",
-          "GDHARNESS_LSP_PORT points this server at the right one"
-        ]);
+        return {
+          refusal: this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
+            "editor_status names the editor on the bridge and the port it says it serves",
+            "editor_launch opens this project's own editor, on a language server port of its own",
+            "GDHARNESS_LSP_PORT points this server at the right one"
+          ]),
+          perScript: false
+        };
       }
-      return this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
-        `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
-        "GDHARNESS_LSP_PORT points this server at another one"
-      ]);
+      return {
+        refusal: this.createErrorResponse(`Diagnostics unavailable: ${reason}`, [
+          `Ensure the Godot editor is running with its language server enabled, on port ${this.editorServes("lspPort", "GDHARNESS_LSP_PORT", DEFAULT_LSP_PORT)}`,
+          "GDHARNESS_LSP_PORT points this server at another one"
+        ]),
+        perScript: payload["aboutThisFile"] === true
+      };
     }
     const diagnostics = readArray(payload, "diagnostics") ?? [];
     const errors = diagnostics.filter((entry) => {
       const severity = asParams(entry)["severity"];
       return severity === 1 || severity === "error" || severity === "ERROR";
     }).length;
-    const disagrees = this.whereTheFileDisagrees(diagnostics, args);
-    return this.jsonTextResponse(markIfStale({
-      scriptPath: readString(args, "scriptPath"),
-      clean: errors === 0,
-      errors,
-      warnings: diagnostics.length - errors,
-      diagnostics,
-      ...disagrees
-    }, this.godotBridge.getStatus().addonVersion, SERVER_VERSION, this.godotBridge.getStatus().addonDigest, shippedEditorDigest(), this.editorCodeOnDisk()));
+    return {
+      answer: {
+        scriptPath: readString(args, "scriptPath"),
+        clean: errors === 0,
+        errors,
+        warnings: diagnostics.length - errors,
+        diagnostics,
+        ...this.whereTheFileDisagrees(diagnostics, args)
+      }
+    };
   }
   whereTheFileDisagrees(diagnostics, args) {
     const messages = diagnostics.map((entry) => asParams(entry)["message"]).filter((message) => typeof message === "string");

package/package.json

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