natureco-cli 5.7.0 → 5.7.2

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to NatureCo CLI will be documented in this file.
 
+## [5.7.1] - 2026-06-25 — "BUG FIX SPRINT"
+
+Comprehensive audit-driven sprint: 7 real runtime bugs fixed, 6 new
+utility modules with ~90%+ test coverage, ESLint + flat config installed,
+test scripts wired to vitest (previously `npm test` was just running
+`--help`). Pure quality / stability — no public API change.
+
+### 🐛 Fixed (runtime bugs)
+- **REPL `/system <text>` crashed with TypeError** (`commands/repl.js`):
+  systemPrompt was `const` but the slash handler reassigned it. → `let`.
+- **Telegram + IRC + SMS message handlers ReferenceError on every inbound**
+  (`commands/gateway-server.js`): `cleanCommand` variable never declared
+  in those scopes. Added `stripSlashPrefix(text)` helper mirroring the
+  v5.6.41+ WhatsApp transform; all three channels now derive it correctly.
+- **Tool-alias rewrites threw ReferenceError** (`utils/tools.js`): typo
+  `TOOL_ALIASES[t.name]` where the local was `ALIAS_MAP`. Fixed.
+- **5 silent `no-undef` ReferenceErrors** across `commands/{chat,nodes,
+  gateway,config}.js` + `utils/error.js` — missing `require()` calls
+  that had been hidden by CommonJS load-order side effects (would
+  crash on a fresh process or worker restart).
+
+### 🔒 Security
+- **exec-approvals.json was world-readable (0644)** — local privilege
+  escalation hedef. Now 0o600 (file) + 0o700 (parent dir), with
+  auto-tightening of pre-existing loose installs. Removed dangling
+  `APPROVALS_SOCKET_PATH` constant + unused `net` require (socket never
+  existed; storage is the JSON file).
+- **Anthropic `system` field sent as `''` or `undefined`** (api.js): now
+  always non-empty via `extractSystemForAnthropic(messages)` helper with
+  a meaningful default. Prevents 400 "system: cannot be empty" on
+  recent Messages API revisions + unanchored-model drift.
+
+### ⚙️ Reliability
+- **Crash-safe atomic file writes** for sessions, history, memory,
+  approvals (new `utils/atomic-file.js`: temp-write + rename(2)).
+  Prior `fs.writeFileSync` left truncated JSON on SIGTERM / OOM /
+  power loss.
+- **Memory fact cap silent fail fixed** (`tools/memory_write.js`): the
+  hardcoded `slice(0, 15)` ran BEFORE push, so once 15 high-score
+  facts were saved, every new write was the next iteration's eviction
+  victim — silently. Now: `MAX_FACTS_PER_USER` default 50 (env
+  `NATURECO_MAX_FACTS`), cap applied AFTER push, just-written fact
+  pinned at top, `console.warn` on breach (`NATURECO_QUIET_MEMORY=1`
+  to silence).
+- **Global `unhandledRejection` + `uncaughtException` handlers**
+  (`utils/process-errors.js`, installed as the first statement in
+  `bin/natureco.js`): structured audit log entry + friendly Turkish
+  stderr + exit 1, instead of Node's default ugly stack dump.
+- **Dashboard port + host de-hardcoded** (`utils/ports.js`):
+  `NATURECO_DASHBOARD_PORT` + `NATURECO_DASHBOARD_HOST` env overrides
+  with range/format validation. Previously 7421 was inlined in two
+  separate modules; drift risk eliminated.
+
+### 🧹 Refactor (DRY)
+- **Streaming tool-call delta accumulator** extracted to
+  `utils/streaming-tools.js`. The per-index buffer + string-concat
+  pattern was duplicated in `utils/api.js` and `commands/repl.js` —
+  any drift between them would silently break tool calling on
+  Groq / MiniMax / DeepSeek / OpenAI.
+- **Provider detection** centralized in `utils/provider-detect.js`.
+  Three call sites (`utils/api.js`, `commands/setup.js`) used three
+  different versions of the URL→provider mapping; the setup.js variant
+  was already incorrect (missed `minimax.cn`). Helper makes
+  `detectProvider`, `isMiniMax`, `isAnthropic`, `isGroq`, `isOllama`
+  the single source of truth.
+
+### 🧪 Testing
+- **`npm test` actually runs tests now** — was previously just
+  `node bin/natureco.js help` (a load-smoke). Wired to `vitest run`.
+- **+95 unit tests** across 9 new spec files. Coverage of the new
+  utility modules: streaming-tools 97%, provider-detect 100%,
+  process-errors 88%, ports ~93%, atomic-file ~93%, memory_write
+  internals ~85%.
+- **Test suite: 12 files / 270 tests → 21 files / 365 tests.**
+- `@vitest/coverage-v8` dev dep added; `npm run test:coverage` works.
+- **prepublishOnly gate strengthened**: now runs `node --check` +
+  `eslint --quiet` + `vitest run` in sequence. A broken publish to
+  `npm install -g natureco-cli` users is now strictly blocked.
+
+### 🔧 Tooling
+- **ESLint v9 flat config added** (`eslint.config.js`):
+  `@eslint/js` recommended + warn-level checks for unused-vars,
+  useless-escape, case-declarations, control-regex. Test files get
+  ES-module sourceType + vitest globals; `src/tools/browser*.js`
+  get browser globals for Playwright page.evaluate context.
+  Scripts: `npm run lint`, `lint:fix`, `lint:errors-only`.
+  After the no-undef fixes: 0 errors (293 unused-vars warnings
+  remain for a follow-up sprint).
+
 ## [5.7.0] - 2026-06-24 - SOUL SCRUBBED (MINOR)
 
 ### Security

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "natureco-cli",
-  "version": "5.7.0",
+  "version": "5.7.2",
   "description": "OpenClaw'dan daha güvenli, daha hızlı, daha ucuz AI agent CLI. Multi-agent, self-evolving skills, audit log, maliyet optimizasyonu ve NatureCo platform-native.",
   "bin": {
     "natureco": "bin/natureco.js"
@@ -15,12 +15,16 @@
     "DEPLOY_v2.0.0.md"
   ],
   "scripts": {
-    "test": "node bin/natureco.js help",
-    "test:unit": "node --check bin/natureco.js && node -e \"console.log('All files OK')\"",
-    "test:watch": "node --watch bin/natureco.js",
-    "test:coverage": "node --check bin/natureco.js",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ bin/ test/",
+    "lint:fix": "eslint src/ bin/ test/ --fix",
+    "lint:errors-only": "eslint src/ bin/ test/ --quiet",
+    "smoke": "node --check bin/natureco.js && node bin/natureco.js help",
     "postinstall": "node bin/natureco.js doctor || true",
-    "prepublishOnly": "node --check bin/natureco.js"
+    "prepublishOnly": "node --check bin/natureco.js && eslint src/ bin/ test/ --quiet && vitest run"
   },
   "keywords": [
     "natureco",
@@ -81,6 +85,10 @@
     "ws": "^8.20.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@vitest/coverage-v8": "^4.1.9",
+    "eslint": "^9.39.4",
+    "globals": "^15.15.0",
     "vitest": "^4.1.9"
   }
 }

package/src/commands/chat.js

@@ -17,6 +17,11 @@ const { runHooks } = require('../utils/hooks');
 const { createSession, loadSession, getLatestSession, addMessageToSession, loadLastSession, listSessions, saveSession } = require('../utils/sessions');
 const { NatureCoError, ApiError, handleError } = require('../utils/errors');
 const { getSessionStats, resetSessionStats } = require('../utils/tool-runner');
+// getBots + sendMessage / _sendMessage are referenced later (loadProviders
+// pre-warm, fallback non-streaming path) but the require was missing —
+// the code only worked when something else in the load order had already
+// required api.js.
+const { getBots, sendMessage, _sendMessage } = require('../utils/api');
 
 const ASCII_LOGO = [
   '███╗   ██╗ █████╗ ████████╗██╗   ██╗██████╗ ███████╗ ██████╗  ██████╗',

package/src/commands/config.js

@@ -4,6 +4,10 @@ const path = require('path');
 const fs = require('fs');
 const { getConfig, setConfigValue, getAllConfig, listBackups, restoreConfig, saveConfig, CONFIG_FILE, CONFIG_BACKUP_DIR } = require('../utils/config');
 const TB = require('../utils/token-budget');
+// `tui` is referenced 25× below for styled output. Was relying on a
+// side-effect global from elsewhere in the load order; require it
+// explicitly so the file works in isolation too (caught by no-undef).
+const tui = require('../utils/tui');
 
 function config(args) {
   const [action, key, ...valueParts] = args;

package/src/commands/gateway-server.js

@@ -10,6 +10,31 @@ const { ApiError } = require('../utils/errors');
 const PID_FILE = path.join(os.homedir(), '.natureco', 'gateway.pid');
 const LOG_FILE = path.join(os.homedir(), '.natureco', 'gateway.log');
 
+// `https` is used in the webhook delivery path (~line 570). The require was
+// missing; the module only worked because Node's CommonJS cache happens to
+// have it loaded from elsewhere, but in a fresh process or after a worker
+// restart this would crash. Explicit.
+const https = require('https');
+// saveConfig (and the loaded `config` value, when not shadowed in scope)
+// referenced in the Discord ready handler / Mattermost HTTP path. Same
+// side-effect-global story as above.
+const { saveConfig } = require('../utils/config');
+
+/**
+ * Strip a leading slash command prefix from a messaging-channel inbound.
+ * v5.6.41+ added slash-prefix routing (e.g. `/ask`, `/help`, `/translate`)
+ * for iMessage + WhatsApp; the Telegram/IRC/SMS handlers were referencing
+ * a `cleanCommand` variable that no longer existed (3 ReferenceError sites,
+ * caught by ESLint no-undef). This helper restores the missing transform:
+ *   "/ask merhaba"  → "merhaba"
+ *   "merhaba"       → "merhaba"
+ *   "" / undefined  → ""
+ */
+function stripSlashPrefix(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text.replace(/^\/[a-zA-Z0-9_-]+\s*/, '').trim() || text.trim();
+}
+
 // Silent logger for Baileys
 const silentLogger = {
   level: 'silent',
@@ -655,9 +680,10 @@ async function startTelegramProvider(config) {
           systemPrompt += '\n\n' + memoryPrompt;
         }
         
+        const cleanCommand = stripSlashPrefix(messageText);
         const response = await sendMessage(cfg.providerApiKey || cfg.apiKey || '', botId, cleanCommand, conversationId, systemPrompt);
         const reply = response?.reply || response?.message || '';
-        
+
         if (reply) {
           log('telegram', 'Sending reply...', 'cyan');
           
@@ -1171,6 +1197,8 @@ async function processIrcMessage(config, sender, target, text, socket) {
     let systemPrompt = `You are a helpful IRC assistant. Keep responses concise. Use IRC-friendly formatting.`;
     if (memoryPrompt) systemPrompt += '\n\n' + memoryPrompt;
 
+    // IRC handler's parameter is `text` (see signature above), not `messageText`.
+    const cleanCommand = stripSlashPrefix(text);
     const response = await sendMessage(
       cfg.providerApiKey || cfg.apiKey || '', botId, cleanCommand,
       conversationId, systemPrompt
@@ -1732,6 +1760,9 @@ async function handleSmsWebhook(config, body, req) {
     let systemPrompt = `You are a helpful SMS assistant. Keep responses concise (SMS format).`;
     if (memoryPrompt) systemPrompt += '\n\n' + memoryPrompt;
 
+    // SMS handler binds the inbound to `text` (Twilio webhook body), unlike
+    // Telegram/IRC which use `messageText`.
+    const cleanCommand = stripSlashPrefix(text);
     const response = await sendMessage(
       cfg.providerApiKey || cfg.apiKey || '', botId, cleanCommand,
       conversationId, systemPrompt
@@ -1880,7 +1911,10 @@ function startHttpServer() {
               res.end(JSON.stringify({ error: 'Mattermost not connected' }));
               return;
             }
-            await sendMattermostMessage(config, target, message);
+            // Load fresh config inside the handler — the surrounding
+            // `startHttpServer` scope does not bind `config`.
+            const { getConfig: _gc1 } = require('../utils/config');
+            await sendMattermostMessage(_gc1(), target, message);
             log('http', `Mattermost message sent to channel ${target}`, 'green');
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true, channel: 'mattermost', target }));
@@ -1907,7 +1941,8 @@ function startHttpServer() {
               res.end(JSON.stringify({ error: 'SMS not connected' }));
               return;
             }
-            await sendSmsMessage(config, target, message);
+            const { getConfig: _gc2 } = require('../utils/config');
+            await sendSmsMessage(_gc2(), target, message);
             log('http', `SMS sent to ${target}`, 'green');
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: true, channel: 'sms', target }));

package/src/commands/gateway.js

@@ -12,6 +12,8 @@ const { loadBaileys } = require('../utils/baileys');
 const { NatureCoError, GatewayError, handleError } = require('../utils/errors');
 const pino = require('pino');
 const logger = pino({ level: 'silent' });
+// Version banner pulls packageJson at line 315 — was missing the require.
+const packageJson = require('../../package.json');
 
 async function gateway(action, ...args) {
   if (action === 'start') {

package/src/commands/nodes.js

@@ -4,6 +4,10 @@ const F = require('../utils/format');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+// getConfig + saveConfig referenced 8× below — missing require relied on
+// side-effect global from another module's load order.
+const { getConfig, saveConfig } = require('../utils/config');
+
 function nodes(args) {
   const [action, ...params] = args || [];
 

package/src/commands/repl.js

@@ -23,6 +23,8 @@ const { spawn } = require('child_process');
 const chalk = require('chalk');
 const tui = require('../utils/tui');
 const { loadToolDefinitions, toOpenAIFormat, executeTool } = require('../utils/tools');
+const { accumulateToolCallDeltas, finalizeToolCalls } = require('../utils/streaming-tools');
+const { createPasteSafeInput, enableBracketedPaste, disableBracketedPaste, restoreNewlines } = require('../utils/paste-safe-input');
 
 // v5.4.6: Model adi sizintisini engelle — global'e ata, callback'lerden erisebilir olsun
 const MODEL_NAMES_TO_HIDE = ['MiniMax-M2.5', 'MiniMaxM2.5', 'minimaxm25', 'Claude-3', 'GPT-4', 'ChatGPT'];
@@ -313,17 +315,10 @@ async function sendStreaming(providerUrl, providerApiKey, messages, model, onChu
                 onChunk(delta.content);
               }
 
-              // Tool calls (streaming delta)
+              // Tool calls (streaming delta) — shared accumulator,
+              // see src/utils/streaming-tools.js for the per-index pattern.
               if (delta.tool_calls) {
-                for (const tcDelta of delta.tool_calls) {
-                  const idx = tcDelta.index;
-                  if (!toolCalls[idx]) {
-                    toolCalls[idx] = { index: idx, id: '', name: '', args: '' };
-                  }
-                  if (tcDelta.id) toolCalls[idx].id = tcDelta.id;
-                  if (tcDelta.function?.name) toolCalls[idx].name += tcDelta.function.name;
-                  if (tcDelta.function?.arguments) toolCalls[idx].args += tcDelta.function.arguments;
-                }
+                accumulateToolCallDeltas(toolCalls, delta.tool_calls);
               }
             } catch {}
           }
@@ -338,17 +333,15 @@ async function sendStreaming(providerUrl, providerApiKey, messages, model, onChu
 
     fullText = result.streamText;
 
-    // Tool call var mı?
-    if (result.toolCalls && result.toolCalls.length > 0 && result.toolCalls[0].name) {
+    // Tool call var mı? finalizeToolCalls drops empty entries + synthesizes ids,
+    // so we only need to check the resulting length.
+    const finalized = finalizeToolCalls(result.toolCalls);
+    if (finalized.length > 0) {
       // Assistant mesajını ekle (tool_calls ile)
       currentMessages.push({
         role: 'assistant',
         content: result.streamText || null,
-        tool_calls: result.toolCalls.map(tc => ({
-          id: tc.id || `call_${Date.now()}_${tc.index}`,
-          type: 'function',
-          function: { name: tc.name, arguments: tc.args },
-        })),
+        tool_calls: finalized,
       });
       // Her tool call'ı çalıştır, sonuçları tool mesajı olarak ekle
       const toolResults = await processToolCalls(result.toolCalls, onToolCall);
@@ -530,7 +523,10 @@ async function startRepl(args) {
                        (cfg.providerUrl || '').includes('mistral.ai') ||
                        (cfg.providerUrl || '').includes('localhost') ||
                        (cfg.providerUrl || '').includes('ollama');
-  const systemPrompt = [
+  // `let` (not `const`) because /system <text> reassigns it at line ~796.
+  // Before this fix, /system would throw "Assignment to constant variable"
+  // and tear down the REPL session mid-conversation.
+  let systemPrompt = [
     // === v5.4.14: EN KRITIK KIMLIK BILGILERI (her zaman ilk) ===
     `SENIN ADIN: ${botName}. SADECE ${botName} adini kullan, model adi SOYLEME.`,
     `PATRONUN: Gencay (Parton) — NatureCo CEO'sudur. Sana "Parton" diye hitap eder.`,
@@ -620,8 +616,10 @@ async function startRepl(args) {
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
 
+  enableBracketedPaste(process.stdout);
+
   const rl = readline.createInterface({
-    input: process.stdin,
+    input: createPasteSafeInput(process.stdin),
     output: process.stdout,
     prompt: tui.styled('\n  You  ', { color: tui.PALETTE.primary, bold: true }),
     terminal: true,
@@ -648,6 +646,7 @@ async function startRepl(args) {
     }
     // Global buffer temizle
     if (global._fixBuffer) global._fixBuffer = '';
+    disableBracketedPaste(process.stdout);
     console.log(chalk.gray('\n  👋 Görüşürüz!\n'));
     process.exit(exitCode);
   };
@@ -726,7 +725,7 @@ async function startRepl(args) {
   process.on('SIGTERM', () => cleanup(0));
 
   rl.on('line', async (input) => {
-    const line = input.trim();
+    const line = restoreNewlines(input).trim();
     if (!line) { rl.prompt(); return; }
 
     // Slash komutlar

package/src/commands/setup.js

@@ -631,22 +631,23 @@ module.exports = setup;
 async function validateApiKey(providerUrl, apiKey) {
   return new Promise((resolve) => {
     const https = require('https');
-    const url = new URL(providerUrl);
-    const isMM = url.hostname.includes('minimax') || url.hostname.includes('minimaxi');
-    const endpoint = isMM 
+    const { isMiniMax, isGroq, isAnthropic } = require('../utils/provider-detect');
+    const isMM = isMiniMax(providerUrl);
+    const endpoint = isMM
       ? providerUrl.replace(/\/+$/, '') + '/v1/text/chatcompletion_v2'
       : providerUrl.replace(/\/+$/, '') + '/chat/completions';
 
     // Her provider icin test modeli
     let testModel = 'gpt-3.5-turbo';
-    if (providerUrl.includes('groq.com')) testModel = 'llama-3.1-8b-instant';
-    else if (providerUrl.includes('anthropic.com')) testModel = 'claude-3-haiku-20240307';
+    if (isGroq(providerUrl)) testModel = 'llama-3.1-8b-instant';
+    else if (isAnthropic(providerUrl)) testModel = 'claude-3-haiku-20240307';
     else if (isMM) testModel = 'MiniMax-M2.5';
     else if (providerUrl.includes('gemini')) testModel = 'gemini-1.5-flash';
     else if (providerUrl.includes('mistral.ai')) testModel = 'mistral-tiny';
     else if (providerUrl.includes('openrouter.ai')) testModel = 'meta-llama/llama-3.1-8b-instruct:free';
     else if (providerUrl.includes('deepseek.com')) testModel = 'deepseek-chat';
-    
+
+
     const data = JSON.stringify({
       model: testModel,
       messages: [{ role: 'user', content: 'hi' }],

package/src/tools/dashboard.js

@@ -15,8 +15,9 @@ const http = require("http");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { getDashboardPort } = require("../utils/ports");
 
-const PORT = 7421;
+const PORT = getDashboardPort();
 const DASHBOARD_HTML = `
 <!DOCTYPE html>
 <html lang="tr">

package/src/tools/edit_file.js

@@ -0,0 +1,143 @@
+/**
+ * edit_file — Precise string replacement in an existing file.
+ *
+ * Modeled after Claude Code's `Edit` tool semantics, with three rules
+ * that catch ~all "the agent broke my file" failure modes:
+ *
+ *   1. The file must exist (no accidental file creation via Edit — use
+ *      write_file for that).
+ *   2. `old_string` must appear in the file. If it doesn't, return an
+ *      error pointing at the file path; do NOT silently no-op.
+ *   3. `old_string` must be UNIQUE in the file unless `replace_all: true`
+ *      is passed. Otherwise the agent would mutate an unintended site
+ *      without realizing it.
+ *
+ * On success: writes via atomic rename (no half-edited files on crash),
+ * returns the patched line count + a small diff summary.
+ *
+ * Why this exists in natureco: until this commit, natureco's only file
+ * mutation tool was `write_file`, which overwrites the entire file. Any
+ * "rename X to Y in src/foo.js" request meant the agent had to read the
+ * file, do the substitution in its head, and re-emit the whole file —
+ * a process that loses indentation, drops trailing newlines, and
+ * occasionally hallucinates unrelated edits. `edit_file` makes the
+ * mutation a 2-3 line delta the agent can't get wrong.
+ */
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomicSync } = require('../utils/atomic-file');
+
+function _expand(p) {
+  if (!p) return p;
+  if (p.startsWith('~')) {
+    return path.join(require('os').homedir(), p.slice(1));
+  }
+  return path.resolve(p);
+}
+
+async function editFile({ path: filePath, old_string, new_string, replace_all = false }) {
+  if (!filePath || typeof filePath !== 'string') {
+    return { success: false, error: 'path is required (absolute path or ~-prefixed)' };
+  }
+  if (typeof old_string !== 'string' || old_string.length === 0) {
+    return { success: false, error: 'old_string is required and cannot be empty' };
+  }
+  if (typeof new_string !== 'string') {
+    return { success: false, error: 'new_string is required (use empty string to delete)' };
+  }
+  if (old_string === new_string) {
+    return { success: false, error: 'old_string and new_string are identical — nothing to do' };
+  }
+
+  const target = _expand(filePath);
+  if (!fs.existsSync(target)) {
+    return {
+      success: false,
+      error: `file not found: ${target}. Edit cannot create files; use write_file for that.`,
+    };
+  }
+  let original;
+  try {
+    original = fs.readFileSync(target, 'utf8');
+  } catch (e) {
+    return { success: false, error: `read failed: ${e.message}` };
+  }
+
+  // Find occurrences. Use indexOf loop for an accurate count without
+  // pulling in regex escaping bugs (old_string is raw text, not a pattern).
+  let count = 0;
+  let i = 0;
+  while ((i = original.indexOf(old_string, i)) !== -1) {
+    count++;
+    i += old_string.length;
+  }
+
+  if (count === 0) {
+    // Help the agent debug: include a small excerpt so it sees how close
+    // its old_string is to reality (whitespace, casing).
+    const excerpt = original.length > 400 ? original.slice(0, 400) + '\n... (truncated)' : original;
+    return {
+      success: false,
+      error: 'old_string not found in file',
+      path: target,
+      hint: 'Verify exact whitespace, casing, and that you Read the file recently.',
+      file_excerpt: excerpt,
+    };
+  }
+
+  if (count > 1 && !replace_all) {
+    return {
+      success: false,
+      error: `old_string is not unique (${count} occurrences). Pass replace_all: true to change every instance, or extend old_string with more surrounding context to make it unique.`,
+      path: target,
+      occurrences: count,
+    };
+  }
+
+  const updated = replace_all
+    ? original.split(old_string).join(new_string)
+    : original.replace(old_string, new_string);
+
+  try {
+    writeFileAtomicSync(target, updated);
+  } catch (e) {
+    return { success: false, error: `write failed: ${e.message}` };
+  }
+
+  const linesBefore = original.split('\n').length;
+  const linesAfter = updated.split('\n').length;
+  const lineDelta = linesAfter - linesBefore;
+
+  return {
+    success: true,
+    path: target,
+    replacements: count,
+    replace_all: !!replace_all,
+    lines_before: linesBefore,
+    lines_after: linesAfter,
+    line_delta: lineDelta,
+  };
+}
+
+module.exports = {
+  name: 'edit_file',
+  description:
+    'Performs exact string replacement in an existing file. The old_string ' +
+    'must match the file content EXACTLY (including whitespace and indentation) ' +
+    'and must be UNIQUE unless replace_all=true. Use this for any targeted ' +
+    'rename/refactor/patch instead of rewriting the file with write_file. ' +
+    'Fails with a helpful hint when old_string is missing or ambiguous.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Absolute path of file to edit (~/-prefix allowed)' },
+      old_string: { type: 'string', description: 'Exact substring to replace (case-sensitive, whitespace-sensitive)' },
+      new_string: { type: 'string', description: 'Replacement text (must differ from old_string; pass "" to delete)' },
+      replace_all: { type: 'boolean', description: 'Replace every occurrence instead of failing on multiple matches', default: false },
+    },
+    required: ['path', 'old_string', 'new_string'],
+  },
+  execute: editFile,
+  // Exposed for unit tests.
+  _internals: { editFile },
+};