webnav-ts-mcp 0.1.1 → 0.2.0

package/README.md

@@ -2,8 +2,9 @@
 
 An MCP server that gives AI agents JS/TS/HTML/CSS navigation, plus a
 cross-file index of CSS custom properties and `#id`/`.class` selectors that
-single-file language servers can't provide. It needs only Node.js and installs
-with a web project's own package manager.
+single-file language servers can't provide, and write tools that type-check an
+edit before it is written. It needs only Node.js and installs with a web
+project's own package manager.
 
 ## Quick start
 
@@ -92,6 +93,53 @@ Then use the position tools once you have a `path:line:col`:
 Positions are **1-indexed**; `column` is a UTF-16 character offset (a leading
 tab counts as one character).
 
+## Write tools: change code with a type check before every write
+
+The navigation tools above are read-only. These change code, and share one rule:
+**the edit is shown to the language servers as an in-memory overlay first, the
+edited files and the script files importing them are re-checked, and the
+response says which diagnostics the edit would add or fix. Nothing is written
+until that is on the table.**
+
+| Tool | Does |
+|------|------|
+| `edit` | Type-checked text edit of a JS/TS/HTML/CSS file: `old_string`/`new_string` or a whole `new_text` (also creates a file). For anything that is not a whole definition. Line endings follow the file |
+| `edit_symbol` | `action="replace"` / `"insert"` / `"delete"` a function, class, interface, enum, const or member by name: re-indented to the file's own style (tabs or spaces), doc comment kept, `imports=[...]` merged into the file, blank-line spacing handled. Delete refuses while anything uses the symbol and prunes imports only the deleted code used |
+| `rename_symbol` | JS/TS: rename through the TypeScript language server (imports, aliases, overriding members; `parameter=` for one parameter). CSS/HTML: a name starting with `--`, `#` or `.` renames that custom property / id / class across stylesheets, `<style>` and `style=""`, markup (`class`, `id`, `for`, `aria-*`, `href="#id"`) and scripts (`getElementById`, `classList`, `querySelector`, `className`, `setProperty`, markup in strings). Names built dynamically and script strings that merely equal the name are listed, not renamed; other places still using the old name (docs, `.vue`/`.scss`, strings) are listed too |
+| `move` | With `name`: move a top-level function/class/interface/type/const to another file with the imports it needs, repoint every importer and re-export, drop imports only the moved code used, warn about import cycles. Without it: move or rename the file `file_path` (any file): imports (the language server's own rewrite), `<script src>`/`<link href>`/`<img src>` and CSS `url()`/`@import` follow, and the moved file's own relative references are re-based |
+| `quick_fix` | Apply the language server's own fixes (missing imports, misspellings, ...) one by one, re-checking after each; or a source action: `organize_imports`, `remove_unused_imports`, `sort_imports`, `fix_all`. Ambiguous fixes are listed instead of guessed |
+| `verify_changes` | After editing with any tool (your own included): which diagnostics the working tree gained or lost since a git revision (default `HEAD`) |
+| `apply_edit` / `undo_edit` | Write a previewed edit by id; revert an applied one |
+
+One rule for every write tool: it writes when the edit adds no more than
+`max_new_errors` (default 0) errors in the edited files and their importers and
+the result parses. Otherwise nothing is written and you get the diagnostics plus
+an id for `apply_edit`. `apply=false` always previews. Hints and warnings are
+shown but not counted. Syntax errors (TypeScript's 1xxx codes, any CSS error)
+block a write even with `max_new_errors=null`.
+
+Safety rules, enforced in code:
+
+- Only `.js`/`.mjs`/`.cjs`/`.jsx`/`.ts`/`.mts`/`.cts`/`.tsx`/`.html`/`.css` files inside the
+  workspace are edited (`move` also carries any file, such as an image a stylesheet
+  uses); `node_modules`, `dist`, `.git` and the other skipped folders, generated output
+  (`WEBNAV_MCP_EXCLUDE`) and symlinks are refused.
+- A preview remembers the exact bytes of every file; `apply_edit` refuses if any file
+  changed since. Files are replaced atomically (temp file + rename), and a failure
+  part-way restores the ones already written.
+- Every applied edit is undoable (`undo_edit`) unless a file was changed after it.
+- Line endings and a leading BOM are preserved.
+- Edits touching more than 40 files need `allow_large=true`.
+- `WEBNAV_MCP_READ_ONLY=1` turns every write into a refusal (previews still work).
+
+Scope: the importers that get re-checked are found by relative `import`/`export
+... from`/`require()`/`import()` specifiers (`./a`, `./a.js` for `a.ts`, `./dir`
+for `dir/index.ts`); a file reached only through a path alias is checked with its
+own edit alone. `move`'s HTML/CSS rewrite understands relative and root-absolute
+(`/src/main.ts`) references; bundler config, path aliases and string paths are
+listed as mentions, not rewritten. HTML/CSS edits are checked by their language
+servers (syntax and CSS lint), not against the cross-file index.
+
 ## Environment
 
 | Variable | Default | Purpose |
@@ -99,6 +147,7 @@ tab counts as one character).
 | `WEBNAV_MCP_WORKSPACE` | unset: follows the client's MCP roots when they name a worktree of the same git repository, else `CLAUDE_PROJECT_DIR`, else the working directory | Pins the project root (never overridden). See the `workspace` tool |
 | `WEBNAV_MCP_ROOTS` | the whole workspace as one root, labelled `web` | Comma-separated `label=relative/path` pairs to index separately, e.g. `app=src,prototypes=design` |
 | `WEBNAV_MCP_EXCLUDE` | nothing | Comma-separated workspace-relative paths of generated script output (e.g. the JS a TS build emits). Not opened, hidden from `search_symbol`, rejected by the position tools; the CSS/selector index still reads them |
+| `WEBNAV_MCP_READ_ONLY` | unset | `1`/`true`: write tools refuse to write (previews and checks still work) |
 | `WEBNAV_MCP_PUBLIC` | nothing | Comma-separated workspace-relative stylesheets (files or directories) that are a public API, e.g. a design-token file consumed by other projects. `diagnostics` stops reporting their custom properties as "declared but never used" and their selectors as "never referenced"; undefined `var()` usages are still reported |
 
 ## Layout
@@ -106,13 +155,17 @@ tab counts as one character).
 ```
 src/
   cli.ts          stdio entry point (exits when the host closes stdin)
-  server.ts       registers the twelve tools on the MCP SDK
+  server.ts       registers the tools on the MCP SDK
   webnav.ts       the tools as plain async functions returning text; owns all state
   webIndex.ts     CSS var / selector index
   langCommand.ts  how to launch tsc / html / css language servers
   glob.ts         just enough glob for jsconfig `include`
   shared/         lspClient, format, resolve, workspace, notices, errors,
                   params, exclude
+  write/          the write tools: edits (plans, diffs), transaction (guard,
+                  journal, undo), simulate + diagnosticsDelta (the type check),
+                  finish (preview/apply), one module per tool, webTokens
+                  (CSS var/id/class finder), jsImports (import rewriting)
 tests/            vitest; fixtures/sample-app is the shared fixture
 ```
 
@@ -133,10 +186,10 @@ Source: [github.com/illescasDaniel/webnav-ts-mcp](https://github.com/illescasDan
 `webnav` is glue: it spawns three Node language servers and formats their answers,
 plus a regex-grade index.
 
-**Tests:** vitest (unit tests for the index/format code, real language servers
-against the fixture, MCP protocol over an in-memory transport incl. worktree
-selection via client roots with a real `git worktree`, LSP client failure modes,
-and the built executable).
+**Tests:** vitest (unit tests for the index/format code and the pure parts of the
+write tools, real language servers against the fixture and temporary projects,
+MCP protocol over an in-memory transport incl. worktree selection via client roots
+with a real `git worktree`, LSP client failure modes, and the built executable).
 
 ### Things worth knowing
 
@@ -159,6 +212,20 @@ and the built executable).
   aren't followed).
 - **`callers` and `implementations`** are offered because the server advertises
   `callHierarchyProvider` and `implementationProvider`.
+- **Type-checking an edit without writing it** relies on documents the client
+  opens with `didOpen`/`didChange` shadowing the disk (`LspClient.withOverlay`).
+  tsc's native server resolves imports of a file that exists only as an overlay,
+  but needs its *directory* to exist and remembers a failed resolution, so the
+  overlay opens new files first and creates (then removes) empty directories.
+- **A file with no `import`/`export` is a global script** to TypeScript. Moving
+  the last export out of a module turns it into one, and every top-level name in
+  it becomes visible everywhere; the type check can then miss references that
+  should have broken.
+- **Symbol ranges from `documentSymbol` are tight:** no doc comment, no
+  `export const` keyword, one symbol per declarator. `edit_symbol` and `move`
+  widen them (`extentOf`) and refuse declarators that share a statement.
+- **The server's unused-import hints identify what a deletion orphaned:** hints
+  after the edit minus hints before it, so imports that were already unused stay.
 
 ### Costs
 

package/dist/server.js

@@ -11,6 +11,17 @@ import { z } from "zod";
 import { INSTRUCTIONS, Webnav } from "./webnav.js";
 const POSITION_DOC = "`line` and `column` are 1-indexed. `column` is a UTF-16 character offset on the line " +
     "(not a visual/display column): a leading tab counts as one character.";
+const WRITE_RULE = "The edit is shown to the language servers as an in-memory overlay first and the edited files and the " +
+    "files importing them are re-checked: it is written only when that adds no more errors than " +
+    "`max_new_errors` (default 0; null = no limit) and the result parses. Otherwise nothing is written and " +
+    "you get the new diagnostics plus a preview id for `apply_edit`. `apply=false` always previews. " +
+    "`undo_edit` reverts an applied edit.";
+const WRITES = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+const READS = { readOnlyHint: true, openWorldHint: false };
+const writeParams = {
+    apply: z.boolean().default(true),
+    max_new_errors: z.number().int().min(0).nullable().optional(),
+};
 const text = (value) => ({
     content: [{ type: "text", text: value }],
 });
@@ -160,5 +171,189 @@ export function createServer(version) {
             "accepted as an alias for `name`.",
         inputSchema: { name: z.string().optional(), query: z.string().optional() },
     }, async (args) => text(await webnav.selectorLookup(args)));
+    registerWriteTools(server, webnav);
     return { server, webnav };
 }
+function registerWriteTools(server, webnav) {
+    server.registerTool("edit", {
+        description: 'Edit text in a JS/TS/HTML/CSS file, type-checked: `edit(file_path="src/app.ts", old_string="x = 1", new_string="x = 2")`.\n\n' +
+            "For changes that are not a whole definition (a few lines, an import, a rule, markup) or for rewriting a " +
+            "whole file (`new_text`, which also creates a new file). To replace, add or delete a function/class/method " +
+            "by name use `edit_symbol`. `old_string` must match exactly once unless `replace_all=true` " +
+            "(line endings follow the file). `include_dependents=false` skips checking the importers. " +
+            WRITE_RULE,
+        inputSchema: {
+            file_path: z.string().optional(),
+            old_string: z.string().optional(),
+            new_string: z.string().optional(),
+            replace_all: z.boolean().default(false),
+            new_text: z.string().optional(),
+            include_dependents: z.boolean().default(true),
+            ...writeParams,
+        },
+        annotations: WRITES,
+    }, async ({ max_new_errors, ...a }) => text(await webnav.edit({
+        filePath: a.file_path,
+        oldString: a.old_string,
+        newString: a.new_string,
+        replaceAll: a.replace_all,
+        newText: a.new_text,
+        includeDependents: a.include_dependents,
+        apply: a.apply,
+        maxNewErrors: max_new_errors,
+    })));
+    server.registerTool("edit_symbol", {
+        description: "Replace, add or delete a JS/TS function, class, interface, enum, const or member by name. Examples: " +
+            '`edit_symbol(action="replace", name="Cart.total", source="total(): number { ... }")`, ' +
+            '`edit_symbol(action="insert", file_path="src/utils.ts", name="parse", source="function helper() {}")`, ' +
+            '`edit_symbol(action="delete", name="legacyParse")`.\n\n' +
+            '- `action="replace"`: `name` (dotted `Class.method` ok) and `source` (the complete new definition, ' +
+            "decorators included; re-indented to the old one's place in the file's own indent style). The doc comment " +
+            "above is kept unless `source` brings its own. A changed signature shows up as errors at call sites.\n" +
+            '- `action="insert"`: `source` and `file_path`. `position` is relative to `name`: "after" (default when ' +
+            '`name` is given) / "before" a symbol, "into" a class/interface/enum/namespace (appended to its body), or ' +
+            '"end" of the file (default without `name`; creates the file if missing). Refuses a name that already exists there.\n' +
+            '- `action="delete"`: `name` only. Refuses while anything still uses it and lists the users (`force=true` ' +
+            "deletes anyway and shows what breaks). Imports only the deleted code used are removed (`prune_imports`). " +
+            "Strings, comments and docs naming it are listed and the deletion is previewed instead of applied.\n\n" +
+            "`file_path` narrows `name` when several symbols share it. `imports` (replace/insert) is a list of " +
+            'import statements the new code needs (`["import { Money } from \\"./money\\""]`), merged into the file if missing. ' +
+            WRITE_RULE,
+        inputSchema: {
+            action: z.enum(["replace", "insert", "delete"]).optional(),
+            name: z.string().optional(),
+            source: z.string().optional(),
+            file_path: z.string().optional(),
+            position: z.enum(["after", "before", "into", "end"]).optional(),
+            imports: z.array(z.string()).optional(),
+            force: z.boolean().default(false),
+            prune_imports: z.boolean().default(true),
+            ...writeParams,
+        },
+        annotations: WRITES,
+    }, async ({ max_new_errors, ...a }) => text(await webnav.editSymbol({
+        action: a.action,
+        name: a.name,
+        source: a.source,
+        filePath: a.file_path,
+        position: a.position,
+        imports: a.imports,
+        force: a.force,
+        pruneImports: a.prune_imports,
+        apply: a.apply,
+        maxNewErrors: max_new_errors,
+    })));
+    server.registerTool("rename_symbol", {
+        description: 'Rename a symbol everywhere it is used. Examples: `rename_symbol(name="Cart.total", new_name="sum")`, ' +
+            '`rename_symbol(name="--accent", new_name="--brand")`, `rename_symbol(name=".card-title", new_name="heading")`.\n\n' +
+            "JS/TS: give `name` (dotted `Class.method` ok; `file_path` narrows it) or `file_path` + `line` + `column` " +
+            "(1-indexed). Built on the TypeScript language server's rename (imports, aliases, overriding members); " +
+            '`parameter="x"` with a function\'s name renames one parameter. Places that still say the old name that ' +
+            "the type checker cannot link (strings, comments, docs, other languages) are listed.\n\n" +
+            "CSS/HTML: a `name` starting with `--`, `#` or `.` renames that custom property / id / class across " +
+            "stylesheets (declarations, `var()`, selectors), HTML (`class`, `id`, and the attributes that refer to ids: " +
+            '`for`, `aria-*`, `href="#id"`) and scripts (`getElementById`, `classList`, `querySelector`, `className`, ' +
+            '`setProperty`/`getPropertyValue`, markup inside strings). Names built dynamically (`"row-" + id`) are listed, ' +
+            "not renamed; script string literals that merely equal the name are listed and renamed only with " +
+            "`include_string_literals=true`. Refuses a new name that already exists (`force=true` merges). With several " +
+            "`WEBNAV_MCP_ROOTS` pass `file_path` to say which root. " +
+            WRITE_RULE,
+        inputSchema: {
+            new_name: z.string().optional(),
+            name: z.string().optional(),
+            file_path: z.string().optional(),
+            line: z.number().int().optional(),
+            column: z.number().int().optional(),
+            parameter: z.string().optional(),
+            force: z.boolean().default(false),
+            include_string_literals: z.boolean().default(false),
+            allow_large: z.boolean().default(false),
+            ...writeParams,
+        },
+        annotations: WRITES,
+    }, async ({ max_new_errors, ...a }) => text(await webnav.renameSymbol({
+        newName: a.new_name,
+        name: a.name,
+        filePath: a.file_path,
+        line: a.line,
+        column: a.column,
+        parameter: a.parameter,
+        force: a.force,
+        includeStringLiterals: a.include_string_literals,
+        allowLarge: a.allow_large,
+        apply: a.apply,
+        maxNewErrors: max_new_errors,
+    })));
+    server.registerTool("move", {
+        description: "Move a declaration to another file, or a whole file, and fix every reference. Examples: " +
+            '`move(name="parseDate", to_file="src/app/dates.ts")`, `move(file_path="src/old/util.ts", to_file="src/lib/util.ts")`.\n\n' +
+            "With `name`: moves that top-level function/class/interface/enum/type/const (`file_path` narrows which). " +
+            "The destination is created if missing; the code gets the imports it needs (found by the language server), " +
+            '`export` is added if it was private, every `import { name } from "old"` elsewhere is repointed, the old ' +
+            "file imports it from the new place if it still uses it (`keep_reexport=true` also leaves `export { name } " +
+            'from "new"`), and imports only the moved code used are dropped. Import cycles are warned about.\n\n' +
+            "Without `name`: `file_path` is the file to move or rename (any file; `to_file` may be a directory). Every " +
+            "import/re-export in JS/TS (the language server's own rewrite), `<script src>`/`<link href>`/`<img src>` in " +
+            "HTML (relative and root-absolute), and `url()`/`@import` in CSS follow, and the moved file's own relative " +
+            "references are re-based. Configs, path aliases and string paths are listed, not rewritten. " +
+            WRITE_RULE,
+        inputSchema: {
+            to_file: z.string().optional(),
+            name: z.string().optional(),
+            file_path: z.string().optional(),
+            keep_reexport: z.boolean().default(false),
+            allow_large: z.boolean().default(false),
+            ...writeParams,
+        },
+        annotations: WRITES,
+    }, async ({ max_new_errors, ...a }) => text(await webnav.move({
+        toFile: a.to_file,
+        name: a.name,
+        filePath: a.file_path,
+        keepReexport: a.keep_reexport,
+        allowLarge: a.allow_large,
+        apply: a.apply,
+        maxNewErrors: max_new_errors,
+    })));
+    server.registerTool("quick_fix", {
+        description: 'Apply the TypeScript language server\'s own fixes to a JS/TS file: `quick_fix(file_path="src/app.ts")`.\n\n' +
+            "`action=\"fix\"` (default) fixes the file's errors one by one with the server's code actions (missing " +
+            "imports, misspelled names, ...), re-checking after each; `line` limits it to errors starting on that line. " +
+            "A fix with several candidates is listed, not guessed. The other actions are source actions on the whole " +
+            "file: `organize_imports`, `remove_unused_imports`, `sort_imports`, `fix_all`. " +
+            WRITE_RULE,
+        inputSchema: {
+            file_path: z.string().optional(),
+            line: z.number().int().optional(),
+            action: z.enum(["fix", "organize_imports", "remove_unused_imports", "sort_imports", "fix_all"]).optional(),
+            ...writeParams,
+        },
+        annotations: WRITES,
+    }, async ({ max_new_errors, ...a }) => text(await webnav.quickFix({
+        filePath: a.file_path,
+        line: a.line,
+        action: a.action,
+        apply: a.apply,
+        maxNewErrors: max_new_errors,
+    })));
+    server.registerTool("verify_changes", {
+        description: "What did the edits since a git revision break? Compares the language servers' diagnostics now against " +
+            "`since` (default `HEAD`).\n\nRun it after editing with any tool (your own Edit/Write included): the " +
+            "changed JS/TS/HTML/CSS files and the script files importing them are checked, with the committed versions " +
+            'substituted in for the "before" side. Read-only.',
+        inputSchema: { since: z.string().default("HEAD"), include_dependents: z.boolean().default(true) },
+        annotations: READS,
+    }, async ({ since, include_dependents }) => text(await webnav.verifyChanges({ since, includeDependents: include_dependents })));
+    server.registerTool("apply_edit", {
+        description: "Write a previewed edit (the id comes from a write tool's preview). Fails, writing nothing, if any file " +
+            "changed since the preview.",
+        inputSchema: { id: z.string().optional(), allow_large: z.boolean().default(false) },
+        annotations: WRITES,
+    }, async ({ id, allow_large }) => text(await webnav.applyEdit(id ?? "", allow_large)));
+    server.registerTool("undo_edit", {
+        description: "Revert an edit applied by the write tools (the latest one by default). Refuses when any of its files " +
+            "changed after the edit, so later work is never overwritten.",
+        inputSchema: { id: z.string().optional() },
+        annotations: WRITES,
+    }, async ({ id }) => text(await webnav.undoEdit(id)));
+}

package/dist/shared/lspClient.js

@@ -18,6 +18,7 @@ import { InvalidPositionError, LanguageServerExitedError, LspRequestError, LspTi
 import { EXCLUDED_DIR_NAMES } from "./exclude.js";
 import { uriToPath } from "./format.js";
 import { debug } from "./log.js";
+import { canonicalPath, removeEmptyDirChain } from "./paths.js";
 import { LINE_BREAK_RE, readTextStrict } from "./text.js";
 /** Max ms to wait for a push-only server's publishDiagnostics after a sync. */
 export const PUSH_DIAGNOSTICS_TIMEOUT_MS = 5000;
@@ -40,6 +41,8 @@ const DEFAULT_TIMEOUT_MS = 20_000;
 const FILE_CREATED = 1;
 const FILE_CHANGED = 2;
 const FILE_DELETED = 3;
+// `mtimeNs` of a document whose text came from `withOverlay`, never equal to a real stamp.
+const OVERLAY_STAMP = -2n;
 function deferred() {
     const d = { done: false };
     d.promise = new Promise((resolve) => {
@@ -84,6 +87,8 @@ export class LspClient {
     configSnapshot;
     configHashes = new Map();
     refreshChain = Promise.resolve();
+    // uri -> text shown to the server instead of the disk's (a simulated edit, see `withOverlay`).
+    overlays = new Map();
     constructor(options) {
         this.workspaceRoot = options.workspaceRoot;
         this.command = options.command;
@@ -176,8 +181,20 @@ export class LspClient {
                             documentSymbol: { hierarchicalDocumentSymbolSupport: true },
                             callHierarchy: {},
                             typeHierarchy: {},
+                            rename: { prepareSupport: true },
+                            codeAction: {
+                                codeActionLiteralSupport: {
+                                    codeActionKind: { valueSet: ["quickfix", "source", "source.organizeImports"] },
+                                },
+                                resolveSupport: { properties: ["edit"] },
+                            },
+                        },
+                        workspace: {
+                            workspaceFolders: true,
+                            didChangeWatchedFiles: { dynamicRegistration: true },
+                            workspaceEdit: { documentChanges: true, resourceOperations: ["create", "rename", "delete"] },
+                            fileOperations: { willRename: true },
                         },
-                        workspace: { workspaceFolders: true, didChangeWatchedFiles: { dynamicRegistration: true } },
                     },
                     workspaceFolders: [{ uri: rootUri, name: path.basename(this.workspaceRoot) }],
                 }),
@@ -229,6 +246,7 @@ export class LspClient {
         this.openFiles = new Map();
         this.diagEvents = new Map();
         this.symbolCache = new Map();
+        this.overlays = new Map();
         await this.start();
         if (this.onRestart) {
             await this.onRestart(this);
@@ -320,13 +338,7 @@ export class LspClient {
     }
     // -- document sync -------------------------------------------------------
     toPath(filePath) {
-        const abs = path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath);
-        try {
-            return fs.realpathSync(abs);
-        }
-        catch {
-            return path.resolve(abs);
-        }
+        return canonicalPath(path.isAbsolute(filePath) ? filePath : path.join(this.workspaceRoot, filePath));
     }
     languageIdFor(p) {
         return this.languageIds[path.extname(p).toLowerCase()] ?? this.languageId;
@@ -334,12 +346,24 @@ export class LspClient {
     async ensureOpen(filePath) {
         const abs = this.toPath(filePath);
         const uri = pathToFileURL(abs).href;
-        const stamp = statStamp(abs);
         const known = this.openFiles.get(uri);
-        if (known && known.mtimeNs === stamp.mtimeNs && known.size === stamp.size) {
-            return uri;
+        const overlay = this.overlays.get(uri);
+        let stamp;
+        let text;
+        if (overlay !== undefined) {
+            if (known && known.overlay === overlay) {
+                return uri;
+            }
+            stamp = { mtimeNs: OVERLAY_STAMP, size: overlay.length };
+            text = overlay;
+        }
+        else {
+            stamp = statStamp(abs);
+            if (known && known.overlay === undefined && known.mtimeNs === stamp.mtimeNs && known.size === stamp.size) {
+                return uri;
+            }
+            text = readTextStrict(abs);
         }
-        const text = readTextStrict(abs);
         this.diagEvents.set(uri, deferred());
         // The previous version's pushed diagnostics describe text that no longer
         // exists; keeping them would resurface fixed errors as a "cache fallback".
@@ -350,7 +374,7 @@ export class LspClient {
             this.notify("textDocument/didOpen", {
                 textDocument: { uri, languageId: this.languageIdFor(abs), version: 1, text },
             });
-            this.openFiles.set(uri, { uri, version: 1, ...stamp });
+            this.openFiles.set(uri, { uri, version: 1, ...stamp, overlay });
         }
         else {
             const version = known.version + 1;
@@ -358,10 +382,74 @@ export class LspClient {
                 textDocument: { uri, version },
                 contentChanges: [{ text }],
             });
-            this.openFiles.set(uri, { uri, version, ...stamp });
+            this.openFiles.set(uri, { uri, version, ...stamp, overlay });
         }
         return uri;
     }
+    /** Change the text of a file shown through `withOverlay` (only valid while one is active). */
+    updateOverlay(filePath, text) {
+        if (this.overlays.size === 0) {
+            throw new Error("updateOverlay needs an active overlay");
+        }
+        this.overlays.set(pathToFileURL(this.toPath(filePath)).href, text);
+    }
+    /**
+     * Run `body` with the language server shown `texts` (absolute path -> text) in
+     * place of those files' disk content, files that don't exist yet included.
+     * Nothing is written: this is how an edit is type-checked before it is
+     * applied. Afterwards every overlaid file is resynced from the disk (or
+     * closed when it has none), so later calls see the real project again.
+     * One overlay at a time: callers must not nest or overlap it.
+     */
+    async withOverlay(texts, body) {
+        if (this.overlays.size > 0) {
+            throw new Error("overlays cannot be nested");
+        }
+        const paths = [...texts.keys()].map((p) => this.toPath(p));
+        for (const [p, text] of texts) {
+            this.overlays.set(pathToFileURL(this.toPath(p)).href, text);
+        }
+        // The server finds modules through the file system, so a module that would live in a directory
+        // that doesn't exist yet needs the (empty) directory for the few moments of the check.
+        const madeDirs = [];
+        for (const p of paths) {
+            if (!fs.existsSync(p)) {
+                const top = fs.mkdirSync(path.dirname(p), { recursive: true });
+                if (top !== undefined) {
+                    madeDirs.push({ leaf: path.dirname(p), top });
+                }
+            }
+        }
+        try {
+            // Open files that don't exist yet first: the server remembers a failed module resolution, so an
+            // importer opened before the module it imports would keep reporting it missing.
+            for (const p of [...paths].sort((a, b) => Number(fs.existsSync(a)) - Number(fs.existsSync(b)))) {
+                await this.ensureOpen(p);
+            }
+            return await body();
+        }
+        finally {
+            this.overlays = new Map();
+            for (const p of paths) {
+                const uri = pathToFileURL(p).href;
+                if (fs.existsSync(p)) {
+                    try {
+                        await this.ensureOpen(p);
+                    }
+                    catch (error) {
+                        debug(`could not resync ${p} after an overlay`, error);
+                        this.closeDocument(uri);
+                    }
+                }
+                else if (this.openFiles.has(uri)) {
+                    this.closeDocument(uri);
+                }
+            }
+            for (const { leaf, top } of madeDirs) {
+                removeEmptyDirChain(leaf, top);
+            }
+        }
+    }
     closeDocument(uri) {
         this.notify("textDocument/didClose", { textDocument: { uri } });
         this.openFiles.delete(uri);
@@ -522,8 +610,8 @@ export class LspClient {
             }
         }
         for (const [uri, known] of [...this.openFiles]) {
-            if (known.mtimeNs === -1n) {
-                continue; // scratch document: never on disk
+            if (known.mtimeNs === -1n || this.overlays.has(uri)) {
+                continue; // scratch or overlaid document: not what the disk says
             }
             const file = uriToPath(uri);
             if (!fs.existsSync(file)) {
@@ -639,6 +727,49 @@ export class LspClient {
     async incomingCalls(item) {
         return (await this.request("callHierarchy/incomingCalls", { item })) ?? [];
     }
+    // -- edit-producing calls ----------------------------------------------------
+    /** The range `textDocument/rename` would rewrite at a position, or `null` when the symbol can't be renamed. */
+    async prepareRename(filePath, line, column) {
+        let result;
+        try {
+            result = await this.positionRequest("textDocument/prepareRename", filePath, line, column);
+        }
+        catch (error) {
+            if (error instanceof LspRequestError) {
+                return null;
+            }
+            throw error;
+        }
+        if (result === null || result === undefined) {
+            return null;
+        }
+        return "start" in result ? { range: result } : result;
+    }
+    async rename(filePath, line, column, newName) {
+        return ((await this.positionRequest("textDocument/rename", filePath, line, column, {
+            newName,
+        })) ?? {});
+    }
+    /** The import rewrites the server proposes for moving files (`workspace/willRenameFiles`). */
+    async willRenameFiles(files) {
+        const params = {
+            files: files.map((f) => ({
+                oldUri: pathToFileURL(this.toPath(f.oldPath)).href,
+                newUri: pathToFileURL(this.toPath(f.newPath)).href,
+            })),
+        };
+        return (await this.request("workspace/willRenameFiles", params)) ?? {};
+    }
+    /** Code actions of the given kinds at a range (`diagnostics` are the ones the range overlaps). */
+    async codeActions(filePath, range, diagnostics, only) {
+        const uri = await this.ensureOpen(filePath);
+        const result = await this.request("textDocument/codeAction", {
+            textDocument: { uri },
+            range,
+            context: { diagnostics, only },
+        });
+        return (result ?? []).filter((action) => "title" in action);
+    }
 }
 function sameStampMaps(a, b) {
     if (a.size !== b.size) {

package/dist/shared/overlayGate.js

@@ -0,0 +1,75 @@
+/**
+ * Keeps simulated edits away from everything else.
+ *
+ * While a write tool shows the language server unsaved text (`LspClient.withOverlay`), no other
+ * tool may query that server, or it would answer from text that is not on disk. Every tool call
+ * runs as a shared holder; an overlay section is exclusive: it waits for the other holders to
+ * finish and holds new ones back until it is done. Exclusive sections queue first-come.
+ */
+export class OverlayGate {
+    shared = 0;
+    exclusiveActive = false;
+    waiting = [];
+    wake() {
+        const queue = this.waiting;
+        this.waiting = [];
+        for (const resume of queue) {
+            resume();
+        }
+    }
+    enterShared() {
+        if (this.exclusiveActive) {
+            return false;
+        }
+        this.shared++;
+        return true;
+    }
+    /** Wait until `take()` succeeds; it checks and claims in one synchronous step, so waiters never pass together. */
+    async until(take) {
+        while (!take()) {
+            await new Promise((resolve) => this.waiting.push(resolve));
+        }
+    }
+    /** Run `body` as a shared holder (a tool call). */
+    async hold(body) {
+        await this.until(() => this.enterShared());
+        try {
+            return await body();
+        }
+        finally {
+            this.shared--;
+            this.wake();
+        }
+    }
+    /**
+     * Run `body` alone. Called from inside a shared holder (`holding`): that holder steps aside for
+     * the duration, so it does not wait for itself, and takes its place back afterwards.
+     */
+    async exclusive(body, holding = true) {
+        if (holding) {
+            this.shared--;
+            this.wake();
+        }
+        try {
+            await this.until(() => {
+                if (this.exclusiveActive || this.shared > 0) {
+                    return false;
+                }
+                this.exclusiveActive = true;
+                return true;
+            });
+            try {
+                return await body();
+            }
+            finally {
+                this.exclusiveActive = false;
+                this.wake();
+            }
+        }
+        finally {
+            if (holding) {
+                await this.until(() => this.enterShared());
+            }
+        }
+    }
+}