webnav-ts-mcp 0.1.1 → 0.3.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,78 @@ 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.
+
+## Several calls in one request: `batch`
+
+Reading three files or changing five symbols no longer costs one round-trip each.
+`batch` takes a list of calls for any tool above (reads and writes mixed):
+
+```json
+{"calls": [
+  {"tool": "outline", "args": {"file_path": "src/app.ts"}},
+  {"tool": "symbol_info", "args": {"name": "Cart.total"}},
+  {"tool": "edit", "args": {"file_path": "src/app.ts", "old_string": "x = 1", "new_string": "x = 2"}},
+  {"tool": "edit_symbol", "args": {"action": "delete", "name": "legacyParse"}}
+]}
+```
+
+- Calls run **in order**, each through the real tool, so every write is type-checked,
+  previewed or applied, and undoable on its own (one edit id per write), and later calls
+  see what earlier ones wrote.
+- One numbered section per call, then a summary line (`batch: 3/4 ok, 1 failed`).
+- A bad tool name or argument is reported in its own section with a hint; the rest still run.
+- `stop_on_error` (default: stop when the batch contains a write, continue when it only
+  reads) skips the remaining calls after the first failure or write that was not applied.
+- Not atomic: calls that ran stay applied. After an edit, prefer name-based calls over
+  line/column positions computed earlier. Max 25 calls, no nesting, each result capped at
+  20,000 characters.
+
 ## Environment
 
 | Variable | Default | Purpose |
@@ -99,6 +172,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 +180,18 @@ 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
+  batch.ts        the `batch` engine: runs several registered tools in one request
   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 +212,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 +238,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/batch.js

@@ -0,0 +1,235 @@
+/**
+ * `batch`: several tool calls in one request.
+ *
+ * An agent that wants to read three files or change five symbols would otherwise spend one
+ * round-trip (and the tokens around it) per call. `batch` takes the list, runs the calls in
+ * order through the real tool functions, and returns one numbered section per call. Each
+ * call keeps its own behaviour: every write is type-checked, previewed or applied, and
+ * undoable on its own, and later calls see what earlier calls wrote.
+ *
+ * The registry is plain data (a zod shape plus a run function per tool), so unit tests can
+ * register fake tools and drive `runBatch` without a language server or the MCP SDK.
+ */
+import { z } from "zod";
+import { pyRepr } from "./shared/format.js";
+export const MAX_CALLS = 25;
+export const MAX_CALL_CHARS = 20_000;
+// Text a write tool returns when it did what was asked (applied, undone, previewed, or nothing to do).
+const WRITE_OK_MARKERS = ["Applied as edit", "Applied edit", "Reverted edit", "Preview only", "No changes"];
+function availableTools(registry) {
+    return [...registry.keys()].sort();
+}
+/** Levenshtein edit distance, for the unknown-tool suggestion. */
+function editDistance(a, b) {
+    const width = b.length;
+    let previous = Array.from({ length: width + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = new Array(width + 1).fill(0);
+        current[0] = i;
+        for (let j = 1; j <= width; j++) {
+            const left = previous[j];
+            const up = current[j - 1] + 1;
+            const diagonal = previous[j - 1] + (a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1);
+            current[j] = Math.min(left + 1, up, diagonal);
+        }
+        previous = current;
+    }
+    return previous[width];
+}
+/**
+ * ` Did you mean 'x' or 'y'?` — the two closest registered names, or "" when none is close.
+ *
+ * Deliberately NOT the Python original's difflib.get_close_matches scoring (SequenceMatcher
+ * ratio >= 0.6; this keeps its n=2): this is Levenshtein distance <= floor(0.4 * max(len)).
+ * The two agree on realistic typos and Levenshtein is simpler — don't "fix" this to match difflib.
+ */
+function suggestion(name, registry) {
+    const close = availableTools(registry)
+        .map((candidate) => ({ candidate, distance: editDistance(name, candidate) }))
+        .filter(({ candidate, distance }) => distance <= Math.floor(Math.max(name.length, candidate.length) * 0.4))
+        .sort((a, b) => a.distance - b.distance || (a.candidate < b.candidate ? -1 : 1))
+        .slice(0, 2)
+        .map(({ candidate }) => pyRepr(candidate));
+    return close.length > 0 ? ` Did you mean ${close.join(" or ")}?` : "";
+}
+function unknownToolHint(name, registry) {
+    return `Unknown tool ${pyRepr(name)}.${suggestion(name, registry)} Available: ${availableTools(registry).join(", ")}.`;
+}
+/** True when the parameter may be left out: `.optional()` or `.default(...)` in the zod shape. */
+function mayBeOmitted(schema) {
+    return schema.safeParse(undefined).success;
+}
+/** `name(a, b=...)`: parameters without a default shown bare, with one shown as `=...`. */
+function signatureHint(name, tool) {
+    const parts = Object.entries(tool.inputSchema).map(([key, schema]) => (mayBeOmitted(schema) ? `${key}=...` : key));
+    return `${name}(${parts.join(", ")})`;
+}
+/** Python-repr-ish text for a call argument in a section header: `'x'`, `7`, `true`, `['a', "b"]`. */
+function reprValue(value) {
+    if (typeof value === "string") {
+        return pyRepr(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (value === null || value === undefined) {
+        return "null";
+    }
+    // One style throughout (Python repr-ish): strings single-quoted, arrays `[a, b]`, objects `{k: v}`.
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => reprValue(item)).join(", ")}]`;
+    }
+    if (typeof value === "object") {
+        const items = Object.entries(value).map(([key, v]) => `${pyRepr(key)}: ${reprValue(v)}`);
+        return `{${items.join(", ")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** `edit(file_path='src/a.ts', old_string='...')` — only the arguments the call passed. */
+function label(name, args) {
+    const shown = Object.entries(args)
+        .map(([key, value]) => {
+        const repr = reprValue(value);
+        return repr.length <= 60 ? `${key}=${repr}` : `${key}=...`;
+    })
+        .join(", ");
+    return `${name}(${shown})`;
+}
+/**
+ * Validates one call; returns it ready to run, or the error text for its section.
+ * The flat shape `{"tool": "outline", "file_path": "x.ts"}` is accepted too: keys beside
+ * "tool" are treated as arguments.
+ */
+function prepare(registry, index, raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return `Call ${index} must be an object like {"tool": "outline", "args": {"file_path": "src/a.ts"}}.`;
+    }
+    const rest = { ...raw };
+    let name = rest.tool;
+    delete rest.tool;
+    if (!name) {
+        name = rest.name;
+        delete rest.name;
+    }
+    if (typeof name !== "string" || name === "") {
+        return 'Call is missing "tool" (the tool name, e.g. "outline").';
+    }
+    if (name === "batch") {
+        return "batch calls cannot be nested.";
+    }
+    const tool = registry.get(name);
+    if (!tool) {
+        return unknownToolHint(name, registry);
+    }
+    let args = rest.args;
+    delete rest.args;
+    if (args === undefined || args === null) {
+        args = rest;
+    }
+    else if (Object.keys(rest).length > 0) {
+        const extra = Object.keys(rest).sort().map(pyRepr).join(", ");
+        return `Put [${extra}] inside "args" (call shape: {"tool": ..., "args": {...}}).`;
+    }
+    if (typeof args !== "object" || args === null || Array.isArray(args)) {
+        return `"args" must be an object of ${name} parameters: ${signatureHint(name, tool)}.`;
+    }
+    const parameters = args;
+    const unknown = Object.keys(parameters).filter((key) => !Object.hasOwn(tool.inputSchema, key));
+    if (unknown.length > 0) {
+        return `${name} has no parameter ${unknown.map(pyRepr).join(", ")}. Parameters: ${signatureHint(name, tool)}.`;
+    }
+    for (const [key, value] of Object.entries(parameters)) {
+        const result = tool.inputSchema[key]?.safeParse(value);
+        if (result && !result.success) {
+            const message = result.error.issues[0]?.message ?? "invalid value";
+            return `${name}: invalid ${pyRepr(key)}: ${message}. Parameters: ${signatureHint(name, tool)}.`;
+        }
+    }
+    const missing = Object.entries(tool.inputSchema)
+        .filter(([key, schema]) => !mayBeOmitted(schema) && !Object.hasOwn(parameters, key))
+        .map(([key]) => key);
+    if (missing.length > 0) {
+        return `${name}: missing required ${missing.map(pyRepr).join(", ")}. Parameters: ${signatureHint(name, tool)}.`;
+    }
+    // Fill in the defaults exactly as the MCP server would have; the tools rely on them. The checks
+    // above accept every value the per-key schemas accept, so a failure here means those checks
+    // missed something (e.g. an object-level rule, which a per-key ToolShape cannot express) —
+    // report it instead of silently running the call with default-less arguments.
+    const filled = z.object(tool.inputSchema).safeParse(parameters);
+    if (!filled.success) {
+        const issue = filled.error.issues[0];
+        const where = issue !== undefined && issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+        return `${name}: internal error validating arguments: ${where}${issue?.message ?? "invalid arguments"}.`;
+    }
+    return { name, tool, args: parameters, call: filled.data };
+}
+/** A write tool's result counts as a failure when it did not do what was asked. */
+function writeFailed(tool, text) {
+    return tool.writes && (text.includes("NOT applied") || !WRITE_OK_MARKERS.some((marker) => text.includes(marker)));
+}
+/**
+ * Runs the calls in order through the registered tools and returns one numbered section per
+ * call, then a summary line. One broken call never loses the others' results.
+ *
+ * `stop_on_error`: stop at the first call that fails or does not apply a write, skipping the
+ * rest. Default (null/omitted): stop when the batch contains a write, keep going when it
+ * only reads.
+ */
+export async function runBatch(calls, stopOnError, registry) {
+    if (!Array.isArray(calls) || calls.length === 0) {
+        return 'batch needs a non-empty "calls" list, e.g. [{"tool": "outline", "args": {"file_path": "src/a.ts"}}].';
+    }
+    if (calls.length > MAX_CALLS) {
+        return `batch takes at most ${MAX_CALLS} calls, got ${calls.length}. Split it into several batches.`;
+    }
+    const prepared = calls.map((raw, i) => prepare(registry, i + 1, raw));
+    const hasWrite = prepared.some((item) => typeof item !== "string" && item.tool.writes);
+    const stop = stopOnError === undefined || stopOnError === null ? hasWrite : stopOnError;
+    const sections = [];
+    let failed = 0;
+    let skipped = 0;
+    let halted = false;
+    const total = prepared.length;
+    for (const [offset, item] of prepared.entries()) {
+        const index = offset + 1;
+        if (halted) {
+            skipped += 1;
+            continue;
+        }
+        if (typeof item === "string") {
+            sections.push(`[${index}/${total}] ERROR\n${item}`);
+            failed += 1;
+            halted = stop;
+            continue;
+        }
+        const header = `[${index}/${total}] ${label(item.name, item.args)}`;
+        let text;
+        try {
+            text = await item.tool.run(item.call);
+        }
+        catch (error) {
+            const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            sections.push(`${header}\nERROR: ${message}`);
+            failed += 1;
+            halted = stop;
+            continue;
+        }
+        if (writeFailed(item.tool, text)) {
+            failed += 1;
+            halted = stop;
+            text = `NOT DONE\n${text}`;
+        }
+        if (text.length > MAX_CALL_CHARS) {
+            text = `${text.slice(0, MAX_CALL_CHARS)}\n... [truncated ${text.length - MAX_CALL_CHARS} characters; narrow this call]`;
+        }
+        sections.push(`${header}\n${text}`);
+    }
+    let summary = `batch: ${total - failed - skipped}/${total} ok`;
+    if (failed > 0) {
+        summary += `, ${failed} failed`;
+    }
+    if (skipped > 0) {
+        summary += `, ${skipped} skipped after the first failure (stop_on_error)`;
+    }
+    return [...sections, summary].join("\n\n");
+}