breakpoint-mcp 1.28.0 → 1.72.7

package/dist/dap.js

@@ -9,6 +9,52 @@ export class DapError extends Error {
         this.name = "DapError";
     }
 }
+/**
+ * Per-line breakpoint modifier fields, each gated by an adapter capability. Godot
+ * advertises all three false AND ignores them — a "conditional" breakpoint halts
+ * unconditionally (measured live on 4.3 and 4.7), so an undropped modifier is not a
+ * no-op, it is the opposite of what the caller asked for.
+ */
+export const BREAKPOINT_MODIFIER_CAPS = {
+    condition: "supportsConditionalBreakpoints",
+    hitCondition: "supportsHitConditionalBreakpoints",
+    logMessage: "supportsLogPoints",
+};
+/**
+ * Which of condition/hitCondition/logMessage the connected adapter does NOT support, out
+ * of the ones actually requested.
+ *
+ * `caps === null` returns [] — nothing can be feature-detected before the adapter has
+ * advertised anything. 🔴 That branch is DEFENSIVE TYPING, NOT A LIVE PATH, and the
+ * mutation sweep proved it by surviving a mutation that made it drop everything: the
+ * only caller is `applyBreakpoints`, a response body is normalised to `{}` before it is
+ * ever assigned, and the handshake sets `capabilities` before it applies any breakpoint.
+ * Recorded rather than deleted because the field's TYPE is nullable and a future caller
+ * could reach it; what IS reachable — an adapter answering `initialize` with an empty
+ * body, so `caps` is `{}` and advertises nothing — is pinned by a unit test instead.
+ *
+ * 🔴 CAPABILITIES ARE UNKNOWN UNTIL `initialize` ANSWERS, AND BREAKPOINTS ARE ORDINARILY
+ * BUFFERED BEFORE THAT. That is why this is called from `applyBreakpoints` — the moment
+ * the modifiers are actually put on the wire — and not only from the tool layer at set
+ * time. Detecting at set time alone left the buffered path, which is the documented and
+ * overwhelmingly common one, sending modifiers to an adapter that ignores them with no
+ * warning: the caller asked for "break when counter < 0" and got a breakpoint that halts
+ * every frame, reported as success. Measured, D1 of this release.
+ */
+export function unsupportedBreakpointModifiers(caps, requested) {
+    if (!caps)
+        return [];
+    const out = [];
+    for (const field of ["condition", "hitCondition", "logMessage"]) {
+        if (requested[field] && caps[BREAKPOINT_MODIFIER_CAPS[field]] !== true)
+            out.push(field);
+    }
+    return out;
+}
+/** True when a per-line modifier array carries at least one non-null, non-empty entry. */
+export function hasModifier(arr) {
+    return Array.isArray(arr) && arr.some((v) => v != null && v !== "");
+}
 /**
  * Minimal DAP client for Godot's Debug Adapter (raw TCP + DAP framing). Runs the
  * initialize → (breakpoints) → configurationDone → launch/attach handshake, and
@@ -20,6 +66,8 @@ export class DapClient extends EventEmitter {
     seq = 1;
     pending = new Map();
     breakpoints = new Map();
+    /** Modifier fields dropped at apply time this session; reset by `start()`. */
+    droppedModifiers = new Set();
     /**
      * Seqs whose deadline fired, so a response arriving later is recognised, not
      * dropped. `seq` is monotonic and is never reset, so a seq is never reused and
@@ -29,6 +77,18 @@ export class DapClient extends EventEmitter {
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
+    /**
+     * True only between a launch/attach the adapter ACCEPTED and the session ending.
+     *
+     * 🔴 Before this existed, exactly one of the fifteen `dbg_*` tools (`dbg_restart`)
+     * knew whether a session had ever been started, and it knew by accident — it reads
+     * `lastStartMode`. Everything else fired its request at the adapter and reported the
+     * answer, so `dbg_continue` on a never-launched client returned
+     * `{"state":"running"}` with `isError:false` AND left `state = "running"` behind
+     * (see `resume()`'s optimistic assignment), which made every later answer read as if
+     * a session existed. Measured live against Godot 4.7.
+     */
+    sessionStarted = false;
     /** The mode + args of the last start(), so restart() can reuse/override them. */
     lastStartMode = null;
     lastStartArgs = null;
@@ -36,6 +96,23 @@ export class DapClient extends EventEmitter {
     state = "disconnected";
     lastStoppedThreadId = null;
     lastStoppedReason = null;
+    /**
+     * Whether a launch/attach the adapter accepted is still in force. The `dbg_*` tools
+     * that can only answer from a live session consult this instead of asking the
+     * adapter and reporting whatever came back.
+     */
+    get hasSession() {
+        return this.sessionStarted && this.state !== "terminated" && this.state !== "disconnected";
+    }
+    /**
+     * Whether the adapter has reported a stop, read through a call so TypeScript's
+     * control-flow narrowing does not collapse it: `state` is mutated by the event
+     * handler across every `await` in `start()`, and a literal `this.state === "stopped"`
+     * after a `this.state = "running"` is (wrongly) an impossible comparison to tsc.
+     */
+    stoppedNow() {
+        return this.state === "stopped";
+    }
     constructor(host, port, timeoutMs) {
         super();
         this.timeoutMs = timeoutMs;
@@ -160,21 +237,46 @@ export class DapClient extends EventEmitter {
         if (this.configured) {
             return this.applyBreakpoints(path);
         }
-        return { buffered: true, path, lines };
+        // 🔴 Buffered: capabilities are still unknown, so the modifiers CANNOT be
+        // feature-detected yet. Say so rather than let the caller read a bare
+        // `buffered: true` as "your condition was accepted" — detection happens in
+        // `applyBreakpoints` during the handshake, and `dbg_launch` reports the result.
+        const deferred = hasModifier(conditions) || hasModifier(hitConditions) || hasModifier(logMessages);
+        return deferred ? { buffered: true, path, lines, modifier_detection_deferred: true } : { buffered: true, path, lines };
+    }
+    /**
+     * Modifier fields dropped because the connected adapter does not support them,
+     * accumulated across every `applyBreakpoints` since the last `start()`. Read by
+     * `dbg_launch` / `dbg_attach` so a buffered modifier's fate is reported to the
+     * caller that buffered it.
+     */
+    droppedBreakpointModifiers() {
+        return [...this.droppedModifiers];
     }
     applyBreakpoints(path) {
         const bp = this.breakpoints.get(path);
         if (!bp)
             return Promise.resolve({});
+        // 🔴 Feature-detect HERE, where the modifiers actually go on the wire. This is the
+        // only point that sees both the modifiers and the adapter's capabilities on every
+        // path — the buffered one included. See `unsupportedBreakpointModifiers`.
+        const dropped = unsupportedBreakpointModifiers(this.capabilities, {
+            condition: hasModifier(bp.conditions),
+            hitCondition: hasModifier(bp.hitConditions),
+            logMessage: hasModifier(bp.logMessages),
+        });
+        for (const d of dropped)
+            this.droppedModifiers.add(d);
+        const drop = new Set(dropped);
         return this.request("setBreakpoints", {
             source: { path },
             // DAP SourceBreakpoint: line + optional condition / hitCondition / logMessage.
             // A logMessage turns the breakpoint into a logpoint (adapter logs, doesn't halt).
             breakpoints: bp.lines.map((line, i) => {
                 const b = { line };
-                const condition = bp.conditions?.[i];
-                const hit = bp.hitConditions?.[i];
-                const log = bp.logMessages?.[i];
+                const condition = drop.has("condition") ? null : bp.conditions?.[i];
+                const hit = drop.has("hitCondition") ? null : bp.hitConditions?.[i];
+                const log = drop.has("logMessage") ? null : bp.logMessages?.[i];
                 if (condition)
                     b.condition = condition;
                 if (hit)
@@ -240,11 +342,38 @@ export class DapClient extends EventEmitter {
             await this.applyBreakpoints(path).catch(() => undefined);
         }
     }
-    /** Full handshake: initialize → launch/attach → (breakpoints) → configurationDone. */
-    async start(mode, args) {
+    /**
+     * Full handshake: initialize → launch/attach → (breakpoints) → configurationDone.
+     *
+     * 🔴 THREE THINGS HERE WERE WRONG AT ONCE, and Godot's adapter reaches all three.
+     *
+     * 1. `startReq.catch(...)` was attached on the LAST line of the handshake. Godot
+     *    rejects the `launch`/`attach` request ITSELF — `wrong_path` when `project`
+     *    does not match the editor's open project (trivially reachable on macOS, where
+     *    `/tmp` realpaths to `/private/tmp`), `not_running` when nothing is running to
+     *    attach to. That rejection lands DURING the handshake, before the `.catch()`
+     *    existed, so it was an UNHANDLED REJECTION — which Node terminates the process
+     *    for. Measured twice, exit code 1. The handler is now attached at creation.
+     * 2. It emitted on `"error"`. An unlistened `error` emit on an EventEmitter THROWS
+     *    (158 §1). The notification goes out on a distinct name, `start_failed`.
+     * 3. `state = "running"` was unconditional, so a session the adapter refused was
+     *    reported as running. It is now only set from `initialized`, which also stops
+     *    it clobbering a `stopped` that arrives mid-handshake (the race CI found in
+     *    #166 and this Mac never did).
+     *
+     * `entryStopWaitMs > 0` additionally waits, bounded, for the entry `stopped` event
+     * before returning — see `dbg_launch`'s `stop_on_entry`. Godot 4.7 does not honour
+     * `stopOnEntry` at all, so this wait times out there and the caller is told so
+     * rather than being handed a bare `running` that reads like it worked.
+     */
+    async start(mode, args, entryStopWaitMs = 0) {
         // Remember how we started so restart() can reuse (or override) these params.
         this.lastStartMode = mode;
         this.lastStartArgs = args;
+        this.sessionStarted = false;
+        // A fresh session re-detects against whatever adapter answers this time — a
+        // restart may reach a different build than the one that dropped last time.
+        this.droppedModifiers.clear();
         // Listen for `initialized` before we ask, so we cannot miss it.
         const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
         this.capabilities = await this.request("initialize", {
@@ -258,15 +387,47 @@ export class DapClient extends EventEmitter {
         });
         this.state = "initialized";
         // Send launch/attach but don't await it yet — many adapters only resolve it
-        // after configurationDone.
+        // after configurationDone. The rejection handler is attached HERE, on the same
+        // tick the promise is created: see (1) above. It records rather than throws, so
+        // a rejection arriving at any point is observable and never unhandled.
+        let startFailure = null;
         const startReq = this.request(mode, args);
+        startReq.catch((err) => {
+            startFailure = err;
+            this.sessionStarted = false;
+            // Only the handshake's own window may report `running`; a failure arriving
+            // later ends the session so the tools' session guard refuses from then on.
+            if (!this.stoppedNow())
+                this.state = "terminated";
+            this.emit("start_failed", err);
+        });
+        // An entry stop can arrive before configurationDone answers — arm first.
+        const entryStop = entryStopWaitMs > 0 ? this.waitEvent("stopped", entryStopWaitMs) : null;
         await onInit;
         await this.applyAllBreakpoints();
         await this.request("configurationDone", {}).catch(() => undefined);
+        // 🔴 By the time we get here an already-arrived rejection has ALREADY run its
+        // `.catch()`: the `.catch(() => undefined)` on the configurationDone request adds
+        // a microtask hop, so the recorder is queued ahead of this continuation even when
+        // both responses land in a single TCP read. A `setImmediate` here looked like
+        // prudence and was measurably dead code — a mutation deleting it survived every
+        // test in the suite, including one written specifically to catch it. The
+        // same-read ordering is pinned by a unit test instead, which is the thing that
+        // would actually notice if that hop were ever removed.
+        // A rejection arriving LATER than this ends the session via the handler above.
+        if (startFailure)
+            throw startFailure;
         this.configured = true;
-        this.state = "running";
-        // Surface a launch/attach failure if one occurs, but don't hang on success.
-        startReq.catch((err) => this.emit("error", err));
+        this.sessionStarted = true;
+        // Guarded, not unconditional: a `stopped` that landed mid-handshake stays.
+        if (this.state === "initialized")
+            this.state = "running";
+        if (entryStop) {
+            await entryStop;
+            if (startFailure)
+                throw startFailure;
+        }
+        return { entryStopSeen: this.stoppedNow() };
     }
     threadId() {
         return this.lastStoppedThreadId ?? 1;
@@ -361,6 +522,7 @@ export class DapClient extends EventEmitter {
         this.conn.close();
         this.state = "disconnected";
         this.configured = false;
+        this.sessionStarted = false;
     }
 }
 //# sourceMappingURL=dap.js.map

package/dist/index.js

@@ -41,7 +41,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.28.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.72.7" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -63,14 +63,14 @@ async function main() {
     // Capability groups — a risk-based axis over the toolsets. `code-execution` is
     // OFF by default; a disabled group's tools are DROPPED at
     // registration (omitted from tools/list), so the secure-default surface is
-    // 289 − 13 = 276 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
+    // 291 − 13 = 278 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
     // server.registerTool AFTER applyOutputSchemas (schema wrapper stays innermost).
     const privilegedGroups = selectPrivilegedGroups(config.privilegedGroups, (unknown) => log(`ignoring unknown BREAKPOINT_PRIVILEGED_GROUPS token(s): ${unknown.join(", ")}`));
     applyCapabilities(server, privilegedGroups);
     // The A/B/C/D planes ARE the grouping. Build the ordered toolset registry
     // (the single source of truth, shared with the registration tests) and
     // register only the selected groups. Default (BREAKPOINT_TOOLSETS unset) =
-    // every group → the full 289-tool surface, byte-identical to before. A filter
+    // every group → the full 291-tool surface, byte-identical to before. A filter
     // lets a client that can't defer tools, or a user who wants a smaller default
     // menu, load only the planes a project needs (GitHub-MCP `--toolsets` style).
     let processes;
@@ -110,7 +110,7 @@ async function main() {
         log(`toolsets enabled: ${[...enabled].sort().join(", ")} (${enabled.size}/${toolsets.length} groups)`);
     }
     // Recipes: a free, curated task-recipe layer exposed as MCP prompts (discoverable
-    // via prompts/list). Adds NO tools — the 289-tool count is unchanged — and drives
+    // via prompts/list). Adds NO tools — the 291-tool count is unchanged — and drives
     // the enforced tools above, so it's a skill-pack layer over typed/undoable tools.
     registerRecipes(server);
     // Always-on capability affordance — never behind a toolset or a privileged

package/dist/path-cohort.js

@@ -0,0 +1,177 @@
+/**
+ * THE PATH-LIKE PARAMETER COHORT — the enumeration every containment session scopes
+ * its work with, promoted out of scratch and into the shipped surface.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────
+ * 🔴 WHY THIS FILE EXISTS AND WHY IT IS NOT A SCRATCH SCRIPT
+ *
+ * Sessions 163–165 scoped their path work against "78 path-like parameters". That
+ * number came from a twelve-line loop in `_to_delete/enum163.mjs` that nobody read.
+ * The loop was blind THREE ways, and each blindness hid real defects:
+ *
+ *   1. it walked TOP-LEVEL `inputSchema.properties` only, so a nested parameter
+ *      appeared in no count at all;
+ *   2. 🔴 it DISCARDED every parameter literally named `path` —
+ *      `if (prop === "path") { pathNamed++; continue; }` — because session 162 had
+ *      concluded "I already swept those". That line is not a bug. It is a FINDING
+ *      COMPILED INTO THE MEASURING INSTRUMENT, and it kept asserting itself for
+ *      three sessions after 165 disproved it. It threw away 124 rows, 15 of which
+ *      were escaping;
+ *   3. its name test was an ANCHORED EXACT-WORD list, so a compound name like
+ *      `font_path` could only ever be found through its DESCRIPTION — and
+ *      `card_template_create.theme.font_path` has no description, which made it
+ *      invisible to both tests at once.
+ *
+ * Corrected, the enumeration is 258 rows, not 78. Session 167 re-implemented the
+ * corrected rules independently, with FIVE further candidate blindnesses closed
+ * (multi-branch unions, non-object array items, camelCase boundaries, identity-based
+ * dedupe, additionalProperties containers) and confirmed the same 258: a strict
+ * superset that loses nothing and adds one false positive. The instrument is sound.
+ *
+ * 🔴 THE RULE THIS FILE ENCODES: **a measurement's conclusion must never become the
+ * next measurement's filter.** So this enumerator EXCLUDES NOTHING. Over-inclusion is
+ * cheap — a row you ask about once and clear. Under-inclusion cost four releases.
+ * ─────────────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Name segments that make a parameter path-like. Deliberately broad: a name only has
+ * to CONTAIN one of these as a segment, so `font_path`, `to_path` and `theme_path`
+ * all match where an exact-word test saw nothing.
+ */
+const NAME_SEG = "(path|paths|file|files|scene|scenes|program|uri|url|source|src|dest|destination|target|to|from|dir|" +
+    "directory|out|output|input|script|scripts|asset|assets|resource|template|config|cwd|exe|binary|bin|art|" +
+    "texture|image|icon|font|sound|audio|mesh|material|shader|theme|tileset|tres|pck|glb|obj|sprite|atlas)";
+const NAME_HINT = new RegExp(`(^|_)${NAME_SEG}(_|$)`, "i");
+const SEG_EXACT = new RegExp(`^${NAME_SEG}$`, "i");
+const DESC_HINT = /res:\/\/|user:\/\/|file path|path to|filesystem|absolute path|\.tscn|\.gd\b|\.cs\b|\.tres|\.png|directory/i;
+/** Split a name on underscores AND camelCase/digit boundaries, so `toPath` segments. */
+function segments(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .split(/[_\-.\s]+/)
+        .filter(Boolean);
+}
+function nameLooksPathLike(name) {
+    return NAME_HINT.test(name) || segments(name).some((s) => SEG_EXACT.test(s));
+}
+/**
+ * Every non-null branch of a union, or the node itself. enum166 unwrapped ONLY when a
+ * single branch survived, so a `string | string[]` parameter fell off the end of its
+ * loop — matched neither the stringy test nor the container test.
+ */
+function branchesOf(node) {
+    const n = node;
+    const b = n?.anyOf ?? n?.oneOf;
+    if (!b)
+        return [node];
+    const nonNull = b.filter((x) => x && x.type !== "null");
+    return nonNull.length ? nonNull : [node];
+}
+/** A node is stringy if it, or any branch, is a string or an array of strings. */
+function isStringy(node) {
+    for (const br of branchesOf(node)) {
+        const b = br;
+        if (b?.type === "string")
+            return true;
+        if (b?.type === "array") {
+            for (const it of branchesOf(b.items)) {
+                if (it?.type === "string")
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Every child property-map reachable from a node: objects, array items, maps. */
+function childMaps(node) {
+    const out = [];
+    for (const br of branchesOf(node)) {
+        const b = br;
+        if (!b || typeof b !== "object")
+            continue;
+        if (b.properties)
+            out.push(b.properties);
+        if (b.type === "array" || b.items) {
+            for (const it of branchesOf(b.items)) {
+                const i = it;
+                if (i?.properties)
+                    out.push(i.properties);
+            }
+        }
+        if (b.additionalProperties && typeof b.additionalProperties === "object" && b.additionalProperties.properties) {
+            out.push(b.additionalProperties.properties);
+        }
+        if (b.patternProperties) {
+            for (const sub of Object.values(b.patternProperties))
+                if (sub?.properties)
+                    out.push(sub.properties);
+        }
+    }
+    return out;
+}
+function describe(schema) {
+    const own = schema?.description;
+    if (own)
+        return own;
+    for (const br of branchesOf(schema)) {
+        const d = br?.description;
+        if (d)
+            return d;
+    }
+    return "";
+}
+const MAX_DEPTH = 6;
+function walk(tool, props, trail, depth, seen, sink) {
+    for (const [prop, schema] of Object.entries(props ?? {})) {
+        if (!schema || typeof schema !== "object")
+            continue;
+        const dotted = trail ? `${trail}.${prop}` : prop;
+        // dedupe by TRAIL, not by object identity: two parameters may share one schema
+        // object, and identity-dedupe silently drops the second.
+        if (seen.has(dotted))
+            continue;
+        seen.add(dotted);
+        if (isStringy(schema)) {
+            const desc = describe(schema);
+            const byName = nameLooksPathLike(prop);
+            const byDesc = DESC_HINT.test(desc);
+            if (byName || byDesc) {
+                sink.set(`${tool}\t${dotted}`, {
+                    tool,
+                    param: dotted,
+                    depth,
+                    why: `${byName ? "name" : ""}${byName && byDesc ? "+" : ""}${byDesc ? "desc" : ""}`,
+                    desc: desc.replace(/\s+/g, " ").trim(),
+                    named: prop.toLowerCase() === "path",
+                });
+            }
+            // deliberately NO `continue`: a union can be stringy AND a container at once.
+        }
+        if (depth < MAX_DEPTH) {
+            for (const child of childMaps(schema))
+                walk(tool, child, dotted, depth + 1, seen, sink);
+        }
+    }
+}
+/**
+ * Enumerate every path-like parameter across a tool list, nested ones included,
+ * sorted by tool then parameter so two runs are diffable.
+ */
+export function enumeratePathCohort(tools) {
+    const sink = new Map();
+    for (const t of [...tools].sort((a, b) => a.name.localeCompare(b.name))) {
+        walk(t.name, t.inputSchema?.properties, "", 0, new Set(), sink);
+    }
+    return [...sink.values()].sort((a, b) => a.tool.localeCompare(b.tool) || a.param.localeCompare(b.param));
+}
+/** Cohort sizes, kept comparable to the numbers the handoffs quote. */
+export function summarisePathCohort(rows) {
+    return {
+        total: rows.length,
+        topLevelNamedPath: rows.filter((r) => r.depth === 0 && r.named).length,
+        topLevelOther: rows.filter((r) => r.depth === 0 && !r.named).length,
+        nested: rows.filter((r) => r.depth > 0).length,
+    };
+}
+//# sourceMappingURL=path-cohort.js.map

package/dist/paths.js

@@ -25,4 +25,115 @@ export function readFileText(absPath) {
         return "";
     }
 }
+function refuse(code, message) {
+    throw Object.assign(new Error(message), { refusal: true, code });
+}
+/**
+ * THE containment test. One implementation, and every guard in the codebase calls it.
+ *
+ * 🔴 `root + path.sep`, never a bare `startsWith(root)`: a SIBLING directory named
+ * `<root>_evil` shares the prefix and would otherwise pass. That is the exact spelling
+ * every measurement uses, and the trap 160 §7 records as carried.
+ *
+ * Before 1.40.0 this comparison existed FIVE times — here, and hand-rolled in lsp.ts,
+ * cslsp.ts, dap.ts and csdap.ts. Four copies of a security-relevant check is three too
+ * many; 161 §8 item 5 said so, and said to measure the four before folding them.
+ */
+export function escapesProject(fsPath, root) {
+    return fsPath !== root && !fsPath.startsWith(root + path.sep);
+}
+/**
+ * Resolve a caller-supplied path and REFUSE one that escapes the project root.
+ * Returns the resolved absolute path.
+ *
+ * An absolute path that lands INSIDE the root stays legal — several tools
+ * document `table_path` and friends as "res:// or absolute", and narrowing that
+ * would break callers who pass a full path to a file in their own project.
+ * What is refused is the resolved location, not the spelling.
+ */
+export function resolveInsideProject(p, projectPath, label = "path") {
+    const fsPath = path.resolve(toFsPath(p, projectPath));
+    const root = path.resolve(projectPath);
+    if (escapesProject(fsPath, root)) {
+        refuse("path_outside_project", `Refusing ${label} ${JSON.stringify(p)}: it resolves to ${fsPath}, which is outside ` +
+            `the Godot project root (${root}). Pass a res:// path, or a path inside the project.`);
+    }
+    return fsPath;
+}
+/**
+ * `resolveInsideProject`, and the target must already exist AS A REGULAR FILE.
+ *
+ * This is what separates the four causes `readFileText`'s "" used to conflate.
+ * Measured: a missing file, a real but EMPTY file, a DIRECTORY, and `""` (which
+ * resolves to the project root itself) all produced the identical
+ * "…(does it exist?)" refusal, and three of those four DID exist. Existence and
+ * emptiness are different answers and the caller has to be able to tell them
+ * apart — an empty table is a data problem, a missing one is a path problem.
+ */
+export function resolveExistingFile(p, projectPath, label = "path") {
+    const fsPath = resolveInsideProject(p, projectPath, label);
+    let stat;
+    try {
+        stat = fs.statSync(fsPath);
+    }
+    catch {
+        refuse("not_found", `Refusing ${label} ${JSON.stringify(p)}: no such file (${fsPath}).`);
+    }
+    if (stat.isDirectory()) {
+        refuse("not_a_file", `Refusing ${label} ${JSON.stringify(p)}: ${fsPath} is a directory, not a file` +
+            `${p === "" ? " — an empty path resolves to the project root itself" : ""}.`);
+    }
+    if (!stat.isFile()) {
+        refuse("not_a_file", `Refusing ${label} ${JSON.stringify(p)}: ${fsPath} is not a regular file.`);
+    }
+    return fsPath;
+}
+/**
+ * `resolveInsideProject` for a WRITE target, honouring an `overwrite` flag.
+ *
+ * Returns `{ fsPath, exists }` so the caller can decide what an existing target
+ * needs beyond permission to replace it — the tabletop scene creators have to
+ * close a stale editor tab first, because the editor reuses an already-open
+ * scene rather than re-reading the fresh root the addon just saved.
+ */
+export function resolveWriteTarget(p, projectPath, opts = {}) {
+    const label = opts.label ?? "path";
+    const fsPath = resolveInsideProject(p, projectPath, label);
+    const exists = fs.existsSync(fsPath);
+    if (exists && !opts.overwrite) {
+        refuse("exists", `Refusing to write ${label} ${JSON.stringify(p)}: ${fsPath} already exists. ` +
+            `Pass overwrite:true to replace it, or choose another path.`);
+    }
+    return { fsPath, exists };
+}
+/**
+ * The guard the four language/debug planes share: refuse a source that escapes the
+ * project root, names nothing, or names something that is not a regular file.
+ *
+ * Separate from `resolveExistingFile` on purpose. That one serves tabletop/netcode,
+ * whose refusals are worded around READING A TABLE and whose gate pins "is a
+ * directory, not a file"; these four are worded around A BREAKPOINT THAT CANNOT BIND
+ * and their gates pin "is not a file". Same check, two shipped vocabularies — folding
+ * the vocabularies together would change answers this session did not measure.
+ */
+export function resolveSourceFile(p, projectPath, w) {
+    const fsPath = path.resolve(toFsPath(p, projectPath));
+    const root = path.resolve(projectPath);
+    const anchored = !w.anchoredOnly || !path.isAbsolute(p);
+    if (anchored && escapesProject(fsPath, root)) {
+        refuse("path_outside_project", `Refusing ${JSON.stringify(p)}: it resolves to ${fsPath}, which is outside ${w.root} ` +
+            `(${root}). ${w.escapeHint}`);
+    }
+    let stat;
+    try {
+        stat = fs.statSync(fsPath);
+    }
+    catch {
+        refuse("file_not_found", `Refusing ${JSON.stringify(p)}: no such file (${fsPath}). ${w.missingHint}`);
+    }
+    if (!stat.isFile()) {
+        refuse("not_a_file", `Refusing ${JSON.stringify(p)}: ${fsPath} is not a file${p === "" ? w.emptyNote ?? "" : ""}.`);
+    }
+    return fsPath;
+}
 //# sourceMappingURL=paths.js.map

package/dist/recipes.js

@@ -7,7 +7,7 @@
  * it's **free** (MIT, shipped in the server), and it sits **over typed,
  * schema-validated, undoable tools** — so the contract is executed by the
  * server, not merely described in prose the model might misapply. Recipes are
- * discoverable via MCP `prompts/list`; they add **no tools** (the 289-tool
+ * discoverable via MCP `prompts/list`; they add **no tools** (the 291-tool
  * count is unchanged) and cost nothing until a client pulls one.
  */
 import { z } from "zod";