Merge pull request #59 from BetterThanTomorrow/58-multi-edit

Replace four edit tools with one supporting multi edit batch tool

* Fixes #58

Author: PEZ

AGENTS.md

@@ -124,13 +124,14 @@ Implemented in `integrations/calva/editor-util.cljs`:
 ## Structural Editing Tools
 
 ### Text Targeting
-Tools use `targetLineText` (first line of target form) + line number ±2:
+The `clojure_edit_files` tool uses `targetLineText` (first line of target form) + line number ±2:
 ```clojure
-;; replace_top_level_form or insert_top_level_form
-{:filePath "/absolute/path.clj"
- :line 23
- :targetLineText "(defn multiply-numbers"
- :newForm "(defn multiply-numbers\n  [x y]\n  (* x y))"}
+;; clojure_edit_files batch with replace/insert edits
+{:edits [{:type "replace"
+          :filePath "/absolute/path.clj"
+          :line 23
+          :targetLineText "(defn multiply-numbers"
+          :newForm "(defn multiply-numbers\n  [x y]\n  (* x y))"}]}
 ```
 
 ### Automatic Features

CHANGELOG.md

@@ -4,6 +4,11 @@ Changes to Calva Backseat Driver
 
 ## [Unreleased]
 
+- [Replace four structural editing tools with single batch `clojure_edit_files` tool](https://github.com/BetterThanTomorrow/calva-backseat-driver/issues/58)
+  - Supports replace, insert, append, and create operations in one call
+  - Schema pre-validation, automatic sort order, per-file diagnostics
+  - Removes: `replace_top_level_form`, `insert_top_level_form`, `clojure_create_file`, `clojure_append_code`
+
 ## [v0.0.33] - 2026-05-15
 
 - [Make editing tools headless](https://github.com/BetterThanTomorrow/calva-backseat-driver/issues/57)

assets/instructions/backseat-driver.instructions.md

@@ -8,11 +8,11 @@ The term Clojure is used to cover all Clojure dialects and runtimes — Clojure,
 
 "Use the REPL" means `clojure_evaluate_code`. This is the primary tool for Clojure Interactive Programming.
 
-Backseat Driver provides 11 tools in two groups:
+Backseat Driver provides 8 tools in two groups:
 
 **REPL Exploration & Understanding**: `clojure_evaluate_code`, `clojure_load_file`, `clojure_list_sessions`, `clojure_repl_output_log`, `clojure_symbol_info`, `clojuredocs_info`
 
-**Structural Editing**: `clojure_create_file`, `clojure_append_code`, `replace_top_level_form`, `insert_top_level_form`, `clojure_balance_brackets`
+**Structural Editing**: `clojure_edit_files`, `clojure_balance_brackets`
 
 ## Joyride Boundary
 

assets/instructions/editing-clojure-files.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: 'Structural editing rules for Clojure files — read these instructions when creating or modifying Clojure files regardless of dialect or runtime and when using structural editing tools (clojure_create_file, replace_top_level_form, insert_top_level_form, clojure_append_code, clojure_balance_brackets)'
+description: 'Structural editing rules for Clojure files — read these instructions when creating or modifying Clojure files regardless of dialect or runtime and when using structural editing tools (clojure_edit_files, clojure_balance_brackets)'
 ---
 
 # Editing Clojure Files?

assets/skills/backseat-driver/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backseat-driver
-description: 'Effective use of the Backseat Driver extension and its tools for Clojure interactive programming. Use when: working in Clojure (including all dialects and runtimes) project, be it reading, planning, developing, or evaluating code in the REPL, looking up function documentation or ClojureDocs examples, choosing REPL sessions, editing Clojure files structurally, checking REPL output, planning implementations, reviewing code, or developing solutions incrementally. Whenever you consider any of these tools: clojure_evaluate_code, clojure_load_file, clojuredocs_info, clojure_list_sessions, clojure_symbol_info, clojure_repl_output_log, replace_top_level_form, insert_top_level_form, clojure_append_code, clojure_create_file, clojure_balance_brackets. Also use this skill when PLANNING or DISCUSSING Clojure development approaches — not only at the moment of REPL evaluation.'
+description: 'Effective use of the Backseat Driver extension and its tools for Clojure interactive programming. Use when: working in Clojure (including all dialects and runtimes) project, be it reading, planning, developing, or evaluating code in the REPL, looking up function documentation or ClojureDocs examples, choosing REPL sessions, editing Clojure files structurally, checking REPL output, planning implementations, reviewing code, or developing solutions incrementally. Whenever you consider any of these tools: clojure_evaluate_code, clojure_load_file, clojuredocs_info, clojure_list_sessions, clojure_symbol_info, clojure_repl_output_log, clojure_edit_files, clojure_balance_brackets. Also use this skill when PLANNING or DISCUSSING Clojure development approaches — not only at the moment of REPL evaluation.'
 ---
 
 # Backseat Driver — Effective Tool Usage

assets/skills/editing-clojure-files/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: editing-clojure-files
-description: 'Structural editing of Clojure files using Backseat Driver tools. Use when: creating/adding/inserting/replacing/deleting top-level forms, fixing bracket balance, resolving indentation issues, planning multi-edit sequences, recovering from failed edits, or working with Rich Comment Forms in Clojure files, regardless of dialect or runtime. Use whenever you consider any of these tools: clojure_create_file, clojure_append_code, insert_top_level_form, replace_top_level_form, clojure_balance_brackets. Use when editing Clojure and unsure which tool to pick. Use this skill when PLANNING or DISCUSSING Clojure file edits — not only at the moment of editing.'
+description: 'Structural editing of Clojure files using Backseat Driver tools. Use when: creating/adding/inserting/replacing/deleting top-level forms, fixing bracket balance, resolving indentation issues, planning multi-edit sequences, recovering from failed edits, or working with Rich Comment Forms in Clojure files, regardless of dialect or runtime. Use whenever you consider any of these tools: clojure_edit_files, clojure_balance_brackets. Use when editing Clojure and unsure which tool to pick. Use this skill when PLANNING or DISCUSSING Clojure file edits — not only at the moment of editing.'
 ---
 
 # Editing Clojure Files
@@ -23,40 +23,58 @@ Smaller, simpler forms mean less code to get right in a single edit, fewer inden
 
 When a function you need to modify is already long or deeply nested, improve its structure first, then make the requested change. Structural edits on bloated forms are error-prone.
 
-## Tool Selection
+## The Tool: `clojure_edit_files`
 
+One tool handles all structural editing operations. It accepts a batch of edits, validates them up front, groups by file, sorts for safe application order, and applies them sequentially.
+
+### Edit Types
+
+| Type | Purpose | Required fields |
+|------|---------|-----------------|
+| `create` | Create a new file with content | `filePath`, `content` |
+| `append` | Append forms to end of file | `filePath`, `code` |
+| `replace` | Replace an existing top-level form | `filePath`, `line`, `targetLineText`, `newForm` |
+| `insert` | Insert a form before an existing form | `filePath`, `line`, `targetLineText`, `newForm` |
+
+### Constraints
+
+- At most one `create` per file per call
+- At most one `append` per file per call
+- All edits are schema-validated before any are applied — one invalid edit blocks the entire batch
+- Within a file: creates run first, then replace/insert (highest line first), then appends
+- Across files: files are processed sequentially
+
+### Usage Pattern
+
+```json
+{
+  "edits": [
+    {"type": "replace", "filePath": "/path/to/file.clj", "line": 23, "targetLineText": "(defn process-data", "newForm": "(defn process-data\n  [items]\n  (map transform items))"},
+    {"type": "insert", "filePath": "/path/to/file.clj", "line": 10, "targetLineText": "(defn helper", "newForm": "(defn new-fn\n  [x]\n  (inc x))"},
+    {"type": "append", "filePath": "/path/to/other.clj", "code": "(defn added-fn\n  []\n  :done)"},
+    {"type": "create", "filePath": "/path/to/new_file.clj", "content": "(ns my.new-file)\n\n(defn init []\n  :ok)"}
+  ]
+}
 ```
-What are you doing?
-├── Creating a new file?
-│   → clojure_create_file
-│     Include all known content at creation time.
-│     Namespace kebab-case → filename snake_case.
-│
-├── Adding forms to end of existing file?
-│   → clojure_append_code
-│
-├── Inserting a form before an existing form?
-│   → insert_top_level_form
-│
-├── Modifying an existing form?
-│   → replace_top_level_form
-│
-├── Deleting a form?
-│   → replace_top_level_form with empty newForm
-│
-├── Fixing broken brackets?
-│   → clojure_balance_brackets
-│     Accept its output as authoritative. NEVER modify it.
-│
-└── Editing line comments (; ...)?
-    → Use built-in text editing tools (not structural tools)
+
+### Deleting a Form
+
+Use `replace` with an empty `newForm`:
+```json
+{"type": "replace", "filePath": "/path/file.clj", "line": 15, "targetLineText": "(defn obsolete-fn", "newForm": ""}
 ```
 
-When brackets are broken, structural top-level edits are not possible. Use `clojure_balance_brackets` to analyse the breakage, then fall back to regular text editing tools if needed. If repeated attempts fail, escalate to the human via the #askQuestions tool.
+### When Brackets Are Broken
+
+Structural top-level edits are not possible when brackets are unbalanced. Use `clojure_balance_brackets` to analyse the breakage, then fall back to regular text editing tools if needed. If repeated attempts fail, escalate to the human via the #askQuestions tool.
+
+### Line Comments
+
+Structural tools operate on forms, not line comments (`;`). Use built-in text editing tools for line comments.
 
 ## Targeting Forms
 
-The `replace_top_level_form` and `insert_top_level_form` tools locate forms using two parameters: `line` (1-based line number) and `targetLineText` (the exact first line of the target form). Accuracy here is critical.
+The `replace` and `insert` edit types locate forms using two parameters: `line` (1-based line number) and `targetLineText` (the exact first line of the target form). Accuracy here is critical.
 
 Read the file immediately before editing to get accurate line numbers and exact text.
 
@@ -102,27 +120,20 @@ Definitions must precede their call sites in the file. When edits would create a
 
 ## Edit Process
 
-Verification is mandatory after every edit:
+Verification is mandatory after every batch:
 
 1. **Check problems first** — review current diagnostics; fix existing compilation problems before introducing new edits
-2. **Edit the file** — use the structural tool with REPL-verified code
-3. **Check diagnostics** — read post-edit linting info; act on unexpected problems before the next edit
+2. **Batch edits** — assemble all edits for the call with REPL-verified code
+3. **Check diagnostics** — read post-edit diagnostics from the response; act on unexpected problems before the next batch
 4. **Reload** — `clojure_load_file` to load the file, or `(require 'the.namespace :reload)` to confirm the file loads cleanly
 
 In a hot-reload environment, the REPL output log shows compile errors and warnings immediately after the edit. Read and act on them before proceeding.
 
-## Multiple Edits: Bottom-to-Top
-
-Always edit from highest line number to lowest. Each edit shifts line numbers below it — working bottom-up keeps planned numbers accurate.
+## Multiple Edits Are Automatic
 
-1. Read the file — identify all edit targets with line numbers
-2. Sort edits by line number, **descending**
-3. Apply each edit (highest line first)
-4. Read the file afterward to verify final state
+The tool automatically sorts edits within each file for safe application order (highest line number first for replace/insert). You do not need to manually sort — just provide all edits in a single call and the tool handles ordering.
 
-Example: editing forms at lines 10, 25, 40 → edit order: 40 → 25 → 10.
-
-Expect temporary linter warnings about undefined symbols during a multi-edit sequence — they resolve once the full sequence completes.
+Expect temporary linter warnings about undefined symbols during a multi-edit sequence — they resolve once the full batch completes.
 
 ## Error Recovery
 
@@ -140,17 +151,13 @@ Target line text not found. Expected: '(defn wrong-function [x]' near line 23
 ```
 Fix: Use `grep_search` scoped to the file to find the target text's current line number — cheaper than reading the whole file. Plain text mode for exact matches; in regex mode, escape parens as `\(`.
 
-### Comment Targeting
+### Partial Batch Failure
 
-Structural tools operate on forms, not line comments:
-```
-Target line text cannot start with a comment (;). You can only target forms/sexpressions.
-```
-Fix: Use `replace_string_in_file` or equivalent text tool for line comments.
+The tool continues on failure within a file. The response shows which edits succeeded and which failed. For failed edits, re-read the file, get updated line numbers, and retry in a new batch.
 
 ### Scan Window Miss
 
-The text exists but outside the ±2 window — most commonly because previous edits shifted line numbers. Search the file for the target text to get its current line number.
+The text exists but outside the ±2 window — most commonly because a prior edit in the same batch shifted line numbers beyond the ±2 tolerance. Re-read the file and retry with updated targeting.
 
 ## Extensibility
 
@@ -160,9 +167,8 @@ When this skill is loaded, also load any corresponding `clojure-coding` or `cloj
 
 ## Invariants
 
-- Clojure file edits use structural tools; line comments use text editing tools
-- New `.clj`/`.cljs`/`.cljc`/`.bb` files are created with `clojure_create_file`
-- Multi-edit sequences proceed bottom-to-top (highest line number first)
+- Clojure file edits use `clojure_edit_files`; line comments use text editing tools
+- New `.clj`/`.cljs`/`.cljc`/`.bb` files are created with `clojure_edit_files` type `create`
 - Indentation is verified before every structural edit — Parinfer depends on it
 - Post-edit diagnostics are read and acted on before proceeding
 - `targetLineText` is always the exact first line of the target form