osai-agent 4.0.0

package/src/tools/local.js

@@ -0,0 +1,1254 @@
+// =============================================================================
+// OS AI Agent — Local Tool System (v4.0 — Coding Mode + Todos)
+// =============================================================================
+import { exec, spawn } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import os from 'os';
+import { DEFAULTS, TOOLS } from '../utils/constants.js';
+import { logger } from '../utils/logger.js';
+import { searchDDG, searchSerpAPI, searchTavily, searchDDGHttp, formatSearchOutput } from './search-providers.js';
+import { extractExports, extractLocalImports } from '../parser/dependencies.js';
+
+const execAsync = promisify(exec);
+const COMMAND_TIMEOUT = parseInt(process.env.OSAI_COMMAND_TIMEOUT) || DEFAULTS.COMMAND_TIMEOUT;
+const FETCH_TIMEOUT = parseInt(process.env.OSAI_FETCH_TIMEOUT) || DEFAULTS.FETCH_TIMEOUT;
+const MAX_COMMAND_OUTPUT_CHARS = parseInt(process.env.OSAI_MAX_COMMAND_OUTPUT_CHARS || '40000', 10);
+
+/** Commands that spawn interactive shells — must be blocked */
+const INTERACTIVE_COMMANDS = [
+  /^cmd(\s+\/k)?$/i, /^powershell(\s+-noexit)?$/i, /^bash$/i, /^sh$/i,
+  /^python(\s*\.exe)?$/i, /^node$/i, /^wsl$/i, /^irb$/i, /^ruby$/i,
+  /^php$/i, /^mysql$/i, /^psql$/i, /^sqlite3$/i, /^telnet$/i, /^ftp$/i,
+  /^vim?$/i, /^nano$/i, /^emacs$/i, /^less$/i, /^more$/i,
+];
+
+// ─── Todo Store (scoped per working directory) ───────────────────────────
+const TODO_DIR = path.join(os.homedir(), '.osai-agent', 'todos');
+
+/**
+ * Derive a safe filename from the current working directory.
+ * e.g. D:\Projects\MyApp  →  d__projects__myapp.json
+ *      /home/sam/myproject  →  _home_sam_myproject.json
+ */
+const _cwdToKey = (cwd) => {
+  return cwd
+    .toLowerCase()
+    .replace(/^[a-z]:[\\]/, (m) => m[0] + '__')  // Windows drive letter
+    .replace(/[/\\:]/g, '__')
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/__+/g, '__')
+    .slice(0, 120);
+};
+
+const _getTodoFile = () => {
+  const key = _cwdToKey(process.cwd());
+  return path.join(TODO_DIR, `${key}.json`);
+};
+
+const _saveTodos = async (todos, counter) => {
+  try {
+    const file = _getTodoFile();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify({ todos, counter }, null, 2), 'utf-8');
+  } catch {}
+};
+
+const _loadTodos = () => {
+  try {
+    const file = _getTodoFile();
+    const data = JSON.parse(fsSync.readFileSync(file, 'utf-8'));
+    return { todos: data.todos || [], counter: data.counter || 0 };
+  } catch {
+    return { todos: [], counter: 0 };
+  }
+};
+
+const _initial = _loadTodos();
+const _todos = _initial.todos;
+let _todoIdCounter = _initial.counter;
+
+// Reload todos from disk for the current cwd (called when cwd changes)
+export const reloadTodos = () => {
+  try {
+    const fresh = _loadTodos();
+    _todos.length = 0;
+    for (const t of fresh.todos) _todos.push(t);
+    _todoIdCounter = fresh.counter;
+  } catch {
+    // Corrupted state — reset to empty rather than crash
+    _todos.length = 0;
+    _todoIdCounter = 0;
+  }
+};
+
+export const todoStore = {
+  add(text, priority = 'MEDIUM', mode = null) {
+    const id = ++_todoIdCounter;
+    _todos.push({ id, text, priority, mode, status: 'pending', createdAt: new Date().toISOString() });
+    _saveTodos(_todos, _todoIdCounter);
+    return { id, text, priority, mode, status: 'pending' };
+  },
+  complete(id) {
+    const todo = _todos.find(t => t.id === id);
+    if (!todo) return { success: false, error: `Todo #${id} not found` };
+    todo.status = 'done';
+    todo.completedAt = new Date().toISOString();
+    _saveTodos(_todos, _todoIdCounter);
+    return { success: true, todo };
+  },
+  update(id, updates) {
+    const todo = _todos.find(t => t.id === id);
+    if (!todo) return { success: false, error: `Todo #${id} not found` };
+    if (updates.text) todo.text = updates.text;
+    if (updates.priority) todo.priority = updates.priority;
+    if (updates.mode) todo.mode = updates.mode;
+    if (updates.status) {
+      const s = updates.status.toLowerCase();
+      if (s === 'done' || s === 'completed' || s === 'complete') {
+        todo.status = 'done';
+        todo.completedAt = new Date().toISOString();
+      } else if (s === 'pending' || s === 'open') {
+        todo.status = 'pending';
+        delete todo.completedAt;
+      }
+    }
+    _saveTodos(_todos, _todoIdCounter);
+    return { success: true, todo };
+  },
+  list(mode = null) {
+    if (!mode) return [..._todos];
+    return _todos.filter(t => !t.mode || t.mode === mode);
+  },
+  clear() {
+    _todos.length = 0;
+    _todoIdCounter = 0;
+    _saveTodos(_todos, _todoIdCounter);
+    return { success: true, message: 'All todos cleared' };
+  },
+  getStats(mode = null) {
+    const filtered = mode ? _todos.filter(t => !t.mode || t.mode === mode) : _todos;
+    const pending = filtered.filter(t => t.status === 'pending').length;
+    const done = filtered.filter(t => t.status === 'done').length;
+    return { total: filtered.length, pending, done, projectPath: process.cwd(), projectKey: _cwdToKey(process.cwd()) };
+  },
+};
+
+// ─── Core Functions ────────────────────────────────────────────────────────
+
+/**
+ * Detect the current operating system
+ */
+export const detectOS = () => {
+  const p = process.platform;
+  if (p === 'win32') return 'windows';
+  if (p === 'darwin') return 'macos';
+  return 'linux';
+};
+
+/**
+ * Resolve a path that may contain environment variables or ~
+ */
+export const resolvePath = (p) => {
+  if (!p || typeof p !== 'string') return p;
+  let resolved = p;
+
+  // Windows environment variables
+  resolved = resolved.replace(/%USERPROFILE%/gi, os.homedir());
+  resolved = resolved.replace(/%APPDATA%/gi, process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'));
+  resolved = resolved.replace(/%LOCALAPPDATA%/gi, process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'));
+  resolved = resolved.replace(/%TEMP%/gi, process.env.TEMP || os.tmpdir());
+  resolved = resolved.replace(/%TMP%/gi, process.env.TMP || os.tmpdir());
+  resolved = resolved.replace(/%SYSTEMDRIVE%/gi, process.env.SYSTEMDRIVE || 'C:');
+  resolved = resolved.replace(/%WINDIR%/gi, process.env.WINDIR || 'C:\\Windows');
+  resolved = resolved.replace(/%HOMEPATH%/gi, os.homedir());
+  resolved = resolved.replace(/%USERNAME%/gi, process.env.USERNAME || process.env.USER || 'user');
+
+  // Unix tilde and $HOME
+  resolved = resolved.replace(/^~/, os.homedir());
+  resolved = resolved.replace(/\$HOME/g, os.homedir());
+  resolved = resolved.replace(/\$USER/g, process.env.USER || 'user');
+
+  return resolved;
+};
+
+/**
+ * Get basic system information for prompt context
+ */
+export const getSystemInfo = () => ({
+  os: detectOS(),
+  platform: process.platform,
+  arch: process.arch,
+  nodeVersion: process.version,
+  hostname: os.hostname(),
+  username: process.env.USERNAME || process.env.USER || 'unknown',
+  homedir: os.homedir(),
+  cwd: process.cwd(),
+  cpus: os.cpus().length,
+  totalMemory: `${Math.round(os.totalmem() / 1024 / 1024 / 1024)}GB`,
+  freeMemory: `${Math.round(os.freemem() / 1024 / 1024 / 1024)}GB`,
+});
+
+// ─── Existing Tool Implementations ─────────────────────────────────────────
+
+/**
+ * Execute a local shell command with timeout and safety checks.
+ */
+export const executeLocal = async (command) => {
+  const trimmedCmd = (command || '').trim();
+  if (!trimmedCmd) {
+    return { success: false, output: '', error: 'Empty command' };
+  }
+
+  // Block interactive shells
+  for (const pattern of INTERACTIVE_COMMANDS) {
+    if (pattern.test(trimmedCmd)) {
+      return {
+        success: false,
+        output: '',
+        error: 'Cannot open interactive shell. Describe what you want and the agent will run the appropriate command.',
+      };
+    }
+  }
+
+  logger.debug('Executing local command', { cmd: trimmedCmd, timeout: COMMAND_TIMEOUT });
+
+  const isWindows = detectOS() === 'windows';
+  const finalCommand = isWindows ? `chcp 65001 >nul 2>&1 && ${trimmedCmd}` : trimmedCmd;
+
+  return await new Promise((resolve) => {
+    let output = '';
+    let truncatedChars = 0;
+    let timedOut = false;
+
+    const appendOutput = (chunk) => {
+      const text = String(chunk || '');
+      if (!text) return;
+      const remaining = Math.max(0, MAX_COMMAND_OUTPUT_CHARS - output.length);
+      if (remaining > 0) output += text.slice(0, remaining);
+      if (text.length > remaining) truncatedChars += text.length - remaining;
+    };
+
+    const child = spawn(finalCommand, {
+      shell: isWindows ? 'cmd.exe' : '/bin/sh',
+      windowsHide: true,
+      env: { ...process.env, PYTHONIOENCODING: 'utf-8', LANG: 'en_US.UTF-8' },
+    });
+
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGTERM'); } catch {}
+    }, COMMAND_TIMEOUT);
+
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', appendOutput);
+    child.stderr?.on('data', appendOutput);
+
+    child.on('error', (error) => {
+      clearTimeout(timeoutId);
+      resolve({
+        success: false,
+        output: '',
+        error: error.message || 'Command failed to start',
+      });
+    });
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timeoutId);
+
+      if (isWindows) {
+        output = output
+          .replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F]/g, '')
+          .replace(/\uFFFD/g, '')
+          .replace(/\r\n/g, '\n')
+          .replace(/\r/g, '\n');
+      }
+
+      output = output.trim();
+      if (truncatedChars > 0) {
+        output += `\n\n... output truncated (${truncatedChars} chars hidden; set OSAI_MAX_COMMAND_OUTPUT_CHARS to adjust)`;
+      }
+
+      const tokens = Math.ceil((output || '').length / 4);
+      if (tokens > 4000) {
+        logger.warn('Large output detected', { tokens, chars: output.length, lines: output.split('\n').length });
+      }
+
+      if (timedOut) {
+        resolve({ success: false, output, error: `Command timed out after ${COMMAND_TIMEOUT / 1000}s` });
+        return;
+      }
+
+      if (code !== 0) {
+        const signalText = signal ? ` (signal: ${signal})` : '';
+        resolve({
+          success: false,
+          output,
+          error: output || `Command failed with exit code ${code}${signalText}`,
+          tokens,
+        });
+        return;
+      }
+
+      resolve({
+        success: true,
+        output: output || '(command executed successfully — no output)',
+        error: null,
+        tokens,
+      });
+    });
+  });
+};
+
+/**
+ * Read a file and return its content with metadata
+ */
+export const readFile = async (filePath) => {
+  try {
+    const resolved = resolvePath(filePath);
+    const content = await fs.readFile(resolved, 'utf-8');
+    const lines = content.split('\n').length;
+    const stats = await fs.stat(resolved);
+    return {
+      success: true,
+      output: `File: ${resolved}\nLines: ${lines}\nSize: ${stats.size} bytes\n\n${content}`,
+      error: null,
+      path: resolved,
+      content,
+      tokens: Math.ceil(content.length / 4),
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot read file "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+/**
+ * Write content to a file (creates parent directories automatically)
+ */
+export const writeFile = async (filePath, content) => {
+  try {
+    const resolved = resolvePath(filePath);
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    await fs.writeFile(resolved, content || '', 'utf-8');
+    return {
+      success: true,
+      output: `File created/written: ${resolved} (${(content || '').length} chars, ${(content || '').split('\n').length} lines)`,
+      error: null,
+      path: resolved,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot write file "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+/**
+ * Edit a file using find-and-replace. Supports exact match and fuzzy match.
+ */
+export const editFile = async (filePath, find, replace) => {
+  try {
+    if (!find) return { success: false, output: '', error: 'No find pattern provided', path: resolvePath(filePath) };
+
+    const resolved = resolvePath(filePath);
+    const original = await fs.readFile(resolved, 'utf-8');
+
+    if (!original.includes(find)) {
+      const findTrimmed = find.trim();
+      const findEscaped = findTrimmed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const fuzzyPattern = new RegExp(findEscaped.replace(/\s+/g, '\\s+'), 'i');
+      if (fuzzyPattern.test(original)) {
+        const match = original.match(fuzzyPattern);
+        const count = original.split(match[0]).length - 1;
+        const modified = original.split(match[0]).join(replace || '');
+        await fs.writeFile(resolved, modified, 'utf-8');
+        return {
+          success: true,
+          output: `File edited: ${resolved}\n${count} replacement(s) made (fuzzy match).`,
+          error: null,
+          path: resolved,
+          diff: { find: match[0], replace, count },
+        };
+      }
+
+      const preview = original; // Always return full content on EDIT_FILE failure
+
+      return {
+        success: false,
+        output: '',
+        error: `Pattern not found in "${resolved}".\n\nThe EXACT text you searched for was not found. Full current file content is shown below — extract the exact block you want to change and retry EDIT_FILE with it.\n\nFull file content:\n---\n${preview}\n---`,
+        path: resolved,
+      };
+    }
+
+    const modified = original.split(find).join(replace || '');
+    const count = original.split(find).length - 1;
+    await fs.writeFile(resolved, modified, 'utf-8');
+    return {
+      success: true,
+      output: `File edited: ${resolved}\n${count} replacement(s) made.`,
+      error: null,
+      path: resolved,
+      diff: { find, replace, count },
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot edit file "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+/**
+ * List directory contents with [DIR]/[FILE] prefixes
+ */
+export const listDir = async (dirPath) => {
+  try {
+    const resolved = resolvePath(dirPath || '.');
+    let stat;
+    try { stat = await fs.stat(resolved); } catch { stat = null; }
+    if (stat && stat.isFile()) {
+      const content = await fs.readFile(resolved, 'utf-8');
+      const lines = content.split('\n').length;
+      return {
+        success: true,
+        output: `File: ${resolved}\nLines: ${lines}\nSize: ${stat.size} bytes\n\n${content}`,
+        error: null,
+        path: resolved,
+        content,
+      };
+    }
+    const entries = await fs.readdir(resolved, { withFileTypes: true });
+    const lines = entries.map(e => `${e.isDirectory() ? '[DIR] ' : '[FILE]'} ${e.name}`);
+    const dirs = entries.filter(e => e.isDirectory()).length;
+    const files = entries.filter(e => !e.isDirectory()).length;
+    return {
+      success: true,
+      output: `Directory: ${resolved}\n${dirs} folder(s), ${files} file(s)\n\n${lines.join('\n')}`,
+      error: null,
+      path: resolved,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot list directory "${dirPath}": ${e.message}`, path: resolvePath(dirPath) };
+  }
+};
+
+// ─── NEW CODING TOOLS ─────────────────────────────────────────────────────
+
+/**
+ * Search for text/regex pattern in files within a directory.
+ * {"tool":"SEARCH_FILE","path":"<directory>","pattern":"<regex pattern>","filePattern":"<optional glob like *.js>"}
+ */
+export const searchInFiles = async (dirPath, pattern, filePattern = null) => {
+  try {
+    const resolved = resolvePath(dirPath || '.');
+    const stat = await fs.stat(resolved);
+    if (!stat.isDirectory()) {
+      return { success: false, output: '', error: `"${resolved}" is not a directory` };
+    }
+
+    // Use grep (Linux/Mac) or findstr (Windows)
+    const isWindows = detectOS() === 'windows';
+    let cmd;
+    if (isWindows) {
+      cmd = `findstr /s /n /i "${pattern}" "${resolved}\\*"`;
+    } else {
+      cmd = `grep -rn "${pattern}" "${resolved}" --include="${filePattern || '*'}" 2>/dev/null | head -100`;
+    }
+
+    const { stdout, stderr } = await execAsync(cmd, {
+      timeout: COMMAND_TIMEOUT,
+      maxBuffer: 1024 * 1024 * 10,
+      encoding: 'utf8',
+    });
+
+    const output = (stdout || '').trim();
+    if (!output) {
+      return { success: true, output: `No matches found for "${pattern}" in ${resolved}`, error: null };
+    }
+
+    const lines = output.split('\n');
+    const matchCount = lines.length;
+    const truncated = lines.length >= 100 ? `\n... (showing first 100 of possible more matches)` : '';
+    return {
+      success: true,
+      output: `Found ${matchCount} match(es) for "${pattern}" in ${resolved}:\n\n${output}${truncated}`,
+      error: null,
+      matchCount,
+    };
+  } catch (e) {
+    // grep returns exit code 1 when no matches found
+    if (e.stderr?.includes('No match') || e.code === 1) {
+      return { success: true, output: `No matches found for "${pattern}" in ${resolvePath(dirPath)}`, error: null };
+    }
+    return { success: false, output: '', error: `Search failed: ${e.message}` };
+  }
+};
+
+/**
+ * Append content to an existing file.
+ * {"tool":"APPEND_FILE","path":"<path>","content":"<text to append>"}
+ */
+export const appendFile = async (filePath, content) => {
+  try {
+    const resolved = resolvePath(filePath);
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    await fs.appendFile(resolved, content || '', 'utf-8');
+    const stats = await fs.stat(resolved);
+    return {
+      success: true,
+      output: `Appended ${(content || '').length} chars to: ${resolved} (total size: ${stats.size} bytes)`,
+      error: null,
+      path: resolved,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot append to file "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+/**
+ * Delete a file.
+ * {"tool":"DELETE_FILE","path":"<path>"}
+ */
+export const deleteFile = async (filePath) => {
+  try {
+    const resolved = resolvePath(filePath);
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      await fs.rm(resolved, { recursive: true, force: true });
+      return { success: true, output: `Directory deleted: ${resolved}`, error: null, path: resolved };
+    }
+    await fs.unlink(resolved);
+    return { success: true, output: `File deleted: ${resolved}`, error: null, path: resolved };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot delete "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+/**
+ * Create a directory (with parents).
+ * {"tool":"CREATE_DIR","path":"<path>"}
+ */
+export const createDir = async (dirPath) => {
+  try {
+    const resolved = resolvePath(dirPath);
+    await fs.mkdir(resolved, { recursive: true });
+    return { success: true, output: `Directory created: ${resolved}`, error: null, path: resolved };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot create directory "${dirPath}": ${e.message}`, path: resolvePath(dirPath) };
+  }
+};
+
+/**
+ * Display directory tree structure.
+ * {"tool":"TREE_VIEW","path":"<path>","maxDepth":"<number, default 3>","includeHidden":"<boolean, default false>"}
+ */
+export const treeView = async (dirPath, maxDepth = 3, includeHidden = false) => {
+  try {
+    const resolved = resolvePath(dirPath || '.');
+    const depth = Math.min(parseInt(maxDepth) || 3, 5);
+    const showHidden = includeHidden === true || String(includeHidden).toLowerCase() === 'true';
+    const root = path.resolve(resolved);
+
+    const lines = [];
+    const MAX_TOTAL_LINES = 200;
+    const MAX_FILES_PER_DIR = 50;
+    const IGNORED_NAMES = new Set([
+      '.git', '.svn', '.hg', '.ds_store',
+      'node_modules', '.next', 'dist', 'build', 'coverage', '__pycache__',
+    ]);
+
+    const shouldIncludeEntry = (name) => {
+      if (!showHidden && name.startsWith('.')) return false;
+      return !IGNORED_NAMES.has(name.toLowerCase());
+    };
+
+    async function walk(dir, currentDepth, prefix) {
+      if (currentDepth > depth) return;
+      if (lines.length >= MAX_TOTAL_LINES) return;
+
+      let entries;
+      try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      // Hide technical/hidden entries by default (e.g. .git)
+      const filtered = entries.filter((e) => shouldIncludeEntry(e.name));
+
+      // Sort: dirs first, then files, alphabetically
+      filtered.sort((a, b) => {
+        if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? -1 : 1;
+        return a.name.localeCompare(b.name);
+      });
+
+      const showAll = filtered.length <= MAX_FILES_PER_DIR;
+      const shown = showAll ? filtered : filtered.slice(0, MAX_FILES_PER_DIR);
+
+      for (let i = 0; i < shown.length; i++) {
+        if (lines.length >= MAX_TOTAL_LINES) return;
+        const entry = shown[i];
+        const isLast = i === shown.length - 1;
+        const connector = isLast ? '└── ' : '├── ';
+        const childPrefix = isLast ? '    ' : '│   ';
+
+        if (entry.isDirectory()) {
+          lines.push(`${prefix}${connector}${entry.name}/`);
+          await walk(path.join(dir, entry.name), currentDepth + 1, `${prefix}${childPrefix}`);
+        } else {
+          lines.push(`${prefix}${connector}${entry.name}`);
+        }
+      }
+
+      if (!showAll) {
+        lines.push(`${prefix}└── ... (${filtered.length - MAX_FILES_PER_DIR} more entries)`);
+      }
+    }
+
+    lines.push(root);
+    const stat = await fs.stat(root).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+      return { success: false, output: '', error: `Not a directory: "${root}"`, path: root };
+    }
+
+    await walk(root, 1, '');
+
+    const truncated = lines.length >= MAX_TOTAL_LINES;
+    let output = lines.join('\n');
+    if (truncated) output += '\n... (tree truncated at 200 lines)';
+    if (lines.length <= 1) output += '\n(Aucun fichier ou dossier trouvé)';
+
+    return {
+      success: true,
+      output: `Tree: ${root} (depth: ${depth})\n\n${output}`,
+      error: null,
+      path: root,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot display tree for "${dirPath}": ${e.message}`, path: resolvePath(dirPath) };
+  }
+};
+
+/**
+ * Run a script file (Python, Node.js, shell, etc.)
+ * {"tool":"RUN_SCRIPT","path":"<script path>","args":"<optional arguments>","interpreter":"<optional: python3, node, bash, etc.>"}
+ */
+export const runScript = async (scriptPath, args = '', interpreter = null) => {
+  try {
+    const resolved = resolvePath(scriptPath);
+    const stat = await fs.stat(resolved);
+    if (!stat.isFile()) {
+      return { success: false, output: '', error: `"${resolved}" is not a file` };
+    }
+
+    let cmd;
+    const ext = path.extname(resolved).toLowerCase();
+
+    if (interpreter) {
+      cmd = `${interpreter} "${resolved}" ${args}`;
+    } else if (ext === '.py' || ext === '.pyw') {
+      cmd = detectOS() === 'windows' ? `python "${resolved}" ${args}` : `python3 "${resolved}" ${args}`;
+    } else if (ext === '.js' || ext === '.mjs') {
+      cmd = `node "${resolved}" ${args}`;
+    } else if (ext === '.sh' || ext === '.bash') {
+      cmd = detectOS() === 'windows' ? `bash "${resolved}" ${args}` : `bash "${resolved}" ${args}`;
+    } else if (ext === '.ps1') {
+      cmd = `powershell -ExecutionPolicy Bypass -File "${resolved}" ${args}`;
+    } else if (ext === '.rb') {
+      cmd = `ruby "${resolved}" ${args}`;
+    } else if (ext === '.pl') {
+      cmd = `perl "${resolved}" ${args}`;
+    } else {
+      // Try to make executable and run
+      const isWindows = detectOS() === 'windows';
+      cmd = isWindows ? `"${resolved}" ${args}` : `chmod +x "${resolved}" && "${resolved}" ${args}`;
+    }
+
+    const result = await executeLocal(cmd);
+    const body = result.success
+      ? (result.output || '(no output)')
+      : (result.output || result.error || '');
+
+    return {
+      success: result.success,
+      output: `Script: ${resolved}\nCommand: ${cmd}\n\n${body}`,
+      error: result.success ? null : result.error,
+      path: resolved,
+    };
+  } catch (e) {
+    const isTimeout = e.killed || e.message?.includes('timed out');
+    return {
+      success: false,
+      output: e.stdout || '',
+      error: isTimeout ? `Script timed out after ${COMMAND_TIMEOUT / 1000}s` : (e.stderr || e.message),
+      path: resolvePath(scriptPath),
+    };
+  }
+};
+
+/**
+ * Move or rename a file/directory.
+ * {"tool":"MOVE_FILE","source":"<source path>","destination":"<dest path>"}
+ */
+export const moveFile = async (source, destination) => {
+  try {
+    const src = resolvePath(source);
+    const dest = resolvePath(destination);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.rename(src, dest);
+    return { success: true, output: `Moved: ${src} → ${dest}`, error: null };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot move "${source}" to "${destination}": ${e.message}` };
+  }
+};
+
+/**
+ * Copy a file.
+ * {"tool":"COPY_FILE","source":"<source path>","destination":"<dest path>"}
+ */
+export const copyFile = async (source, destination) => {
+  try {
+    const src = resolvePath(source);
+    const dest = resolvePath(destination);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.copyFile(src, dest);
+    return { success: true, output: `Copied: ${src} → ${dest}`, error: null };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot copy "${source}" to "${destination}": ${e.message}` };
+  }
+};
+
+/**
+ * Get detailed file information (size, type, permissions, dates).
+ * {"tool":"FILE_INFO","path":"<path>"}
+ */
+export const getFileInfo = async (filePath) => {
+  try {
+    const resolved = resolvePath(filePath);
+    const stat = await fs.stat(resolved);
+    const isDir = stat.isDirectory();
+    const info = [
+      `Path: ${resolved}`,
+      `Type: ${isDir ? 'Directory' : 'File'}`,
+      `Size: ${stat.size} bytes (${(stat.size / 1024).toFixed(1)} KB)`,
+      `Created: ${stat.birthtime?.toISOString() || 'N/A'}`,
+      `Modified: ${stat.mtime.toISOString()}`,
+      `Accessed: ${stat.atime.toISOString()}`,
+      `Permissions: ${stat.mode?.toString(8).padStart(6, '0') || 'N/A'}`,
+    ];
+    if (!isDir) {
+      const ext = path.extname(resolved);
+      info.splice(1, 0, `Extension: ${ext || 'none'}`);
+    }
+    return { success: true, output: info.join('\n'), error: null, path: resolved };
+  } catch (e) {
+    return { success: false, output: '', error: `Cannot get info for "${filePath}": ${e.message}`, path: resolvePath(filePath) };
+  }
+};
+
+// ─── WEB TOOLS ─────────────────────────────────────────────────────────────
+
+/**
+ * Fetch content from a URL (for documentation, API data, etc.)
+ * {"tool":"FETCH_URL","url":"<url>","description":"<why>"}
+ */
+export const fetchUrl = async (url, description = '') => {
+  try {
+    if (!url || !url.startsWith('http')) {
+      return { success: false, output: '', error: 'Invalid URL. Must start with http:// or https://' };
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',
+        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,application/json;q=0.8,*/*;q=0.7',
+        'Accept-Language': 'en-US,en;q=0.9',
+      },
+    });
+    clearTimeout(timeoutId);
+
+    const contentType = response.headers.get('content-type') || '';
+    let body = await response.text();
+
+    // Truncate large responses
+    const maxLen = 30000;
+    if (body.length > maxLen) {
+      body = body.slice(0, maxLen) + `\n\n... (truncated, ${(body.length / 1024).toFixed(0)}KB total, showing first ${(maxLen / 1024).toFixed(0)}KB)`;
+    }
+
+    // Try to strip HTML tags for cleaner output
+    if (contentType.includes('text/html')) {
+      body = body
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        .replace(/<style[\s\S]*?<\/style>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    }
+
+    return {
+      success: response.ok,
+      output: `URL: ${url}\nStatus: ${response.status} ${response.statusText}\nContent-Type: ${contentType}\nSize: ${(body.length / 1024).toFixed(1)}KB\n\n${body}`,
+      error: response.ok ? null : `HTTP ${response.status}: ${response.statusText}`,
+    };
+  } catch (e) {
+    if (e.name === 'AbortError') {
+      return { success: false, output: '', error: `Fetch timed out after ${FETCH_TIMEOUT / 1000}s` };
+    }
+    return { success: false, output: '', error: `Fetch failed: ${e.message}` };
+  }
+};
+
+/**
+ * Web search using a search query — works cross-platform without API keys.
+ * Uses a fallback chain: server search → DuckDuckGo Scrape → SerpAPI → Tavily → DDG HTTP
+ * SerpAPI and Tavily support multi-key rotation (comma-separated keys).
+ * {"tool":"WEB_SEARCH","query":"<search query>","description":"<why>"}
+ */
+export const webSearch = async (query, server = null, token = null) => {
+  if (!query || query.trim().length < 2) {
+    return { success: false, output: '', error: 'Search query too short (minimum 2 characters)' };
+  }
+
+  const q = query.trim();
+  let results = null;
+
+  // 1. Server-side search
+  if (server && token) {
+    try {
+      const response = await fetch(`${server}/search`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+        body: JSON.stringify({ query: q, limit: 5 }),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT),
+      });
+      if (response.ok) {
+        const data = await response.json();
+        if (data.results && data.results.length > 0) {
+          results = data.results.map(r => ({ title: r.title || 'Untitled', url: r.url || '', snippet: r.snippet || r.description || '' }));
+        }
+      }
+    } catch {}
+  }
+
+  // 2. DuckDuckGo Scrape (primaire, gratuit)
+  if (!results) {
+    try { results = await searchDDG(q, 5); } catch {}
+  }
+
+  // 3. SerpAPI (fallback, rotation multi-clés)
+  if (!results) {
+    try { results = await searchSerpAPI(q, 5); } catch {}
+  }
+
+  // 4. Tavily (fallback, rotation multi-clés)
+  if (!results) {
+    try { results = await searchTavily(q, 5); } catch {}
+  }
+
+  // 5. Dernier recours: scraping HTTP DDG
+  if (!results) {
+    try { results = await searchDDGHttp(q, 5); } catch {}
+  }
+
+  if (results && results.length > 0) {
+    return formatSearchOutput(q, results);
+  }
+
+  return {
+    success: false,
+    output: '',
+    error: `No web search results found for "${q}". Try rephrasing your query or use FETCH_URL with a specific URL.`,
+  };
+};
+
+// ─── TODO TOOLS ────────────────────────────────────────────────────────────
+
+export const todoAdd = (text, priority = 'MEDIUM', mode = null) => {
+  if (!text || !text.trim()) return { success: false, output: '', error: 'Todo text is required' };
+  const validPriorities = ['HIGH', 'MEDIUM', 'LOW'];
+  const prio = validPriorities.includes(priority.toUpperCase()) ? priority.toUpperCase() : 'MEDIUM';
+  const result = todoStore.add(text.trim(), prio, mode);
+  return { success: true, output: `Todo added: #${result.id} [${prio}] ${result.text}`, error: null, todo: result };
+};
+
+export const todoComplete = (id) => {
+  const numId = parseInt(id);
+  if (isNaN(numId)) return { success: false, output: '', error: 'Todo ID must be a number' };
+  const result = todoStore.complete(numId);
+  if (!result.success) return { success: false, output: '', error: result.error };
+  return { success: true, output: `Todo completed: #${numId} - ${result.todo.text}`, error: null, todo: result.todo };
+};
+
+export const todoUpdate = (id, updates) => {
+  const numId = parseInt(id);
+  if (isNaN(numId)) return { success: false, output: '', error: 'Todo ID must be a number' };
+  const result = todoStore.update(numId, updates);
+  if (!result.success) return { success: false, output: '', error: result.error };
+  return { success: true, output: `Todo updated: #${numId}`, error: null, todo: result.todo };
+};
+
+export const todoList = () => {
+  const todos = todoStore.list();
+  if (todos.length === 0) {
+    return { success: true, output: 'No todos yet. Use TODO_ADD to create tasks.', error: null, todos: [] };
+  }
+  const stats = todoStore.getStats();
+  const lines = [
+    `Todos: ${stats.total} total, ${stats.pending} pending, ${stats.done} completed`,
+    '',
+    ...todos.map(t => {
+      const status = t.status === 'done' ? '[x]' : '[ ]';
+      const prio = t.status === 'done' ? '' : ` (${t.priority})`;
+      return `  ${status} #${t.id}${prio} ${t.text}`;
+    }),
+  ];
+  return { success: true, output: lines.join('\n'), error: null, todos, stats };
+};
+
+export const todoClear = () => {
+  const result = todoStore.clear();
+  return { success: true, output: result.message, error: null };
+};
+
+/**
+ * Validate a local command for dangerous patterns
+ */
+export const validateLocalCommand = (command) => {
+  const dangerousPatterns = [
+    /rm\s+-rf\s+\//, /dd\s+if=/, />\s*\/dev\/sda/, /mkfs\./,
+    /format\s+c:/i, /:\(\)\{\s*:\|:&\s*};/, /curl\s+.*\|\s*(ba)?sh/,
+    /\bnc\s+-[elp]/, /\/dev\/tcp\//, /python\s+-c\s+.*import\s+socket/,
+    /powershell.*-enc/i, /certutil.*-urlcache/i,
+  ];
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      return { safe: false, reason: 'Command contains dangerous pattern' };
+    }
+  }
+  return { safe: true };
+};
+
+// =============================================================================
+// NEW TOOLS — GLOB, GREP, GIT, READ_FILE_RANGE, ASK_USER, DIAG_POST_EDIT
+// =============================================================================
+
+import fastGlob from 'fast-glob';
+import { execFile } from 'child_process';
+
+const execFileAsync = promisify(execFile);
+
+// ─── GLOB — fichiers par pattern ─────────────────────────────────────────────
+// {"tool":"GLOB","pattern":"src/**/*.ts","cwd":"<path>","ignore":["node_modules"]}
+export const globFiles = async (pattern, cwd = process.cwd(), ignore = []) => {
+  try {
+    const resolved = resolvePath(cwd);
+    const defaultIgnore = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/.next/**', '**/__pycache__/**'];
+    const results = await fastGlob(pattern, {
+      cwd: resolved,
+      ignore: [...defaultIgnore, ...ignore],
+      dot: false,
+      absolute: false,
+      followSymbolicLinks: false,
+    });
+    return {
+      success: true,
+      output: results.length > 0
+        ? `Found ${results.length} file(s):\n${results.join('\n')}`
+        : `No files matched pattern: ${pattern}`,
+      files: results,
+      count: results.length,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: e.message };
+  }
+};
+
+// ─── GREP — recherche ripgrep/grep natif ──────────────────────────────────────
+// {"tool":"GREP","pattern":"useState","path":"./src","filePattern":"*.tsx","caseSensitive":false}
+export const grepFiles = async (pattern, searchPath = '.', filePattern = null, caseSensitive = false) => {
+  try {
+    // Reject URLs — GREP is for local files only
+    if (typeof searchPath === 'string' && /^https?:\/\//i.test(searchPath.trim())) {
+      return {
+        success: false,
+        output: '',
+        error: `GREP cannot search URLs. Use FETCH_URL to fetch the page content or WEB_SEARCH to find information online. Path was: ${searchPath}`
+      };
+    }
+    const resolved = resolvePath(searchPath);
+    const isWindows = process.platform === 'win32';
+
+    // Préférer ripgrep si disponible, sinon fallback grep
+    let cmd, args;
+    try {
+      await execFileAsync('rg', ['--version'], { timeout: 2000 });
+      // ripgrep disponible
+      args = ['--line-number', '--color=never', '--max-count=5'];
+      if (!caseSensitive) args.push('--ignore-case');
+      if (filePattern) args.push('--glob', filePattern);
+      args.push('--', pattern, resolved);
+      cmd = 'rg';
+    } catch {
+      // fallback grep
+      if (isWindows) {
+        args = ['/S', '/N', pattern, filePattern ? `${resolved}\\${filePattern}` : `${resolved}\\*`];
+        cmd = 'findstr';
+      } else {
+        args = ['-rn', '--include', filePattern || '*', caseSensitive ? '' : '-i', '--', pattern, resolved].filter(Boolean);
+        cmd = 'grep';
+      }
+    }
+
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+      timeout: 15000,
+      maxBuffer: 1024 * 1024 * 2,
+    }).catch(e => ({ stdout: e.stdout || '', stderr: e.stderr || '' }));
+
+    const lines = (stdout || '').trim().split('\n').filter(Boolean);
+    const MAX = 100;
+    const truncated = lines.length > MAX;
+    const displayed = truncated ? lines.slice(0, MAX) : lines;
+
+    return {
+      success: true,
+      output: lines.length === 0
+        ? `No matches for "${pattern}"${filePattern ? ` in ${filePattern}` : ''}`
+        : `${lines.length} match(es)${truncated ? ` (showing first ${MAX})` : ''}:\n${displayed.join('\n')}`,
+      matches: lines.length,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: e.message };
+  }
+};
+
+// ─── GIT — opérations git intégrées ──────────────────────────────────────────
+// {"tool":"GIT","op":"status|diff|log|add|commit|branch|checkout|push|pull|stash","args":"<optional>","path":"<repo root>"}
+const SAFE_GIT_OPS = ['status', 'diff', 'log', 'branch', 'show', 'stash list', 'remote -v'];
+const WRITE_GIT_OPS = ['add', 'commit', 'checkout', 'stash', 'merge', 'rebase', 'pull', 'push', 'reset'];
+
+export const gitOp = async (op, args = '', repoPath = process.cwd()) => {
+  try {
+    const resolved = resolvePath(repoPath);
+
+    // Sécurité : bloquer les ops destructives sans confirmation (géré par safety/check.js)
+    const opBase = op.split(' ')[0].toLowerCase();
+    const isDangerous = ['reset --hard', 'clean -fd', 'push --force'].some(d => `${op} ${args}`.toLowerCase().includes(d));
+    if (isDangerous) {
+      return { success: false, output: '', error: `Dangerous git op refused: "${op} ${args}". Use LOCAL_CMD with DANGEROUS type if intentional.` };
+    }
+
+    const fullArgs = [op, ...args.split(' ').filter(Boolean)];
+    const { stdout, stderr } = await execFileAsync('git', fullArgs, {
+      cwd: resolved,
+      timeout: 30000,
+      maxBuffer: 1024 * 1024 * 5,
+    }).catch(e => ({ stdout: e.stdout || '', stderr: e.stderr || e.message || '' }));
+
+    const output = (stdout || '').trim() || (stderr || '').trim();
+    return {
+      success: true,
+      output: output || `git ${op}: OK (no output)`,
+      op,
+      args,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: e.message };
+  }
+};
+
+// ─── READ_FILE_RANGE — lecture partielle ──────────────────────────────────────
+// {"tool":"READ_FILE","path":"<path>","startLine":120,"endLine":180}
+export const readFileRange = async (filePath, startLine = null, endLine = null) => {
+  try {
+    const resolved = resolvePath(filePath);
+    const content = await fs.readFile(resolved, 'utf-8');
+    const lines = content.split('\n');
+    const total = lines.length;
+
+    if (startLine === null && endLine === null) {
+      // No range: return full file with line numbers.
+      return {
+        success: true,
+        output: lines.map((l, i) => `${i + 1}: ${l}`).join('\n'),
+        totalLines: total,
+      };
+    }
+
+    const s = Math.max(0, (startLine || 1) - 1);
+    const e = Math.min(total, (endLine || total));
+    const slice = lines.slice(s, e);
+    return {
+      success: true,
+      output: `[Lines ${s + 1}–${e} of ${total}]\n\n` + slice.map((l, i) => `${s + i + 1}: ${l}`).join('\n'),
+      totalLines: total,
+      startLine: s + 1,
+      endLine: e,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: e.message };
+  }
+};
+
+// ─── GET_DEPENDENCIES — export/import summary for local dependencies ─────────
+// {"tool":"GET_DEPENDENCIES","path":"<file path>"}
+// Returns a compact summary of what each local imported file exports,
+// WITHOUT reading the full file contents. The agent uses this to decide
+// whether it needs a full READ_FILE on a dependency.
+export const getDependencies = (filePath) => {
+  try {
+    const resolved = resolvePath(filePath);
+    if (!resolved) {
+      return { success: false, output: '', error: `Cannot resolve path: "${filePath}"` };
+    }
+    const content = fsSync.readFileSync(resolved, 'utf-8');
+    const localImports = extractLocalImports(content);
+    if (localImports.length === 0) {
+      return { success: true, output: `[Dependencies for ${path.basename(resolved)}]\n  (no local imports found)`, dependencies: [] };
+    }
+
+    const baseDir = path.dirname(resolved);
+    const depExts = ['.js', '.mjs', '.jsx', '.ts', '.tsx', '.json', ''];
+    const results = [];
+
+    for (const spec of localImports) {
+      const depBase = path.resolve(baseDir, spec);
+      let depPath = null;
+      for (const ext of depExts) {
+        const attempt = depBase + ext;
+        if (fsSync.existsSync(attempt)) {
+          depPath = attempt;
+          break;
+        }
+      }
+      if (!depPath) {
+        results.push({ name: path.basename(spec), path: spec, lines: 0, exports: [], error: 'not found' });
+        continue;
+      }
+      try {
+        const depContent = fsSync.readFileSync(depPath, 'utf-8');
+        const depLines = depContent.split('\n').length;
+        const depExports = extractExports(depContent);
+        const depImports = extractLocalImports(depContent);
+        results.push({
+          name: path.basename(depPath),
+          path: depPath,
+          lines: depLines,
+          exports: depExports,
+          imports: depImports.map(p => path.basename(p)),
+        });
+      } catch {
+        results.push({ name: path.basename(depPath || spec), path: depPath || spec, lines: 0, exports: [], error: 'read error' });
+      }
+    }
+
+    const lines = results.map(r => {
+      let line = `  ${r.name} (${r.lines} lines)`;
+      if (r.exports && r.exports.length > 0) {
+        line += ` — exported: ${r.exports.join(', ')}`;
+      }
+      if (r.imports && r.imports.length > 0) {
+        line += ` | imports: ${r.imports.join(', ')}`;
+      }
+      if (r.error) {
+        line += ` [${r.error}]`;
+      }
+      return line;
+    });
+
+    return {
+      success: true,
+      output: `[Dependencies for ${path.basename(resolved)}]\n${lines.join('\n')}`,
+      dependencies: results,
+    };
+  } catch (e) {
+    return { success: false, output: '', error: `GET_DEPENDENCIES failed: ${e.message}` };
+  }
+};
+
+// ─── ASK_USER — questions à choix multiple ───────────────────────────────────
+// Utilisé uniquement comme signal au loop — la réponse est capturée par repl-base
+// {"tool":"ASK_USER","question":"<question>","options":["A","B","C"]}
+export const askUserQuestion = (question, options = []) => {
+  return {
+    success: true,
+    output: `[ASK_USER]\n${question}${options.length > 0 ? '\n\nOptions:\n' + options.map((o, i) => `  ${i + 1}. ${o}`).join('\n') : ''}`,
+    isQuestion: true,
+    question,
+    options,
+  };
+};
+
+// ─── DIAG_POST_EDIT — lint/tsc après édition ──────────────────────────────────
+// {"tool":"DIAG_POST_EDIT","path":"<file or dir>","lang":"ts|js|py|go|rust|auto"}
+export const diagPostEdit = async (targetPath, lang = 'auto') => {
+  try {
+    const resolved = resolvePath(targetPath);
+    const ext = path.extname(targetPath).toLowerCase();
+
+    // Détection automatique du langage
+    const detected = lang !== 'auto' ? lang :
+      ['.ts', '.tsx'].includes(ext) ? 'ts' :
+      ['.js', '.jsx', '.mjs'].includes(ext) ? 'js' :
+      ['.py'].includes(ext) ? 'py' :
+      ['.go'].includes(ext) ? 'go' :
+      ['.rs'].includes(ext) ? 'rust' : null;
+
+    if (!detected) {
+      return { success: true, output: `[DIAG] No diagnostic tool configured for extension "${ext}". Skipping.` };
+    }
+
+    const isWindows = process.platform === 'win32';
+    const npxBin = isWindows ? 'npx.cmd' : 'npx';
+
+    const cmds = {
+      ts:   [npxBin, ['tsc', '--noEmit', '--pretty', 'false'], { timeout: 30000 }],
+      js:   [npxBin, ['eslint', '--max-warnings=0', resolved], { timeout: 20000 }],
+      py:   ['python3', ['-m', 'py_compile', resolved], { timeout: 10000 }],
+      go:   ['go', ['vet', './...'], { timeout: 20000 }],
+      rust: ['cargo', ['check', '--message-format=short'], { timeout: 60000 }],
+    };
+
+    const [cmd, args, opts] = cmds[detected];
+    const cwd = resolved.endsWith(ext) ? path.dirname(resolved) : resolved;
+
+    try {
+      const { stdout, stderr } = await execFileAsync(cmd, args, {
+        ...opts,
+        cwd,
+        maxBuffer: 1024 * 1024,
+      }).catch(e => ({ stdout: e.stdout || '', stderr: e.stderr || e.message }));
+
+      const output = [stdout, stderr].filter(Boolean).join('\n').trim();
+
+      if (!output || output.includes('Found 0 errors')) {
+        return { success: true, output: `[DIAG:${detected.toUpperCase()}] ✓ No errors detected.` };
+      }
+
+      const lines = output.split('\n').slice(0, 30);
+      return {
+        success: true,
+        output: `[DIAG:${detected.toUpperCase()}] Issues found:\n${lines.join('\n')}${output.split('\n').length > 30 ? '\n... (truncated)' : ''}`,
+        hasErrors: true,
+      };
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return {
+          success: true,
+          output: `[DIAG:${detected.toUpperCase()}] Linter not found (${cmd} not in PATH). Install it to enable diagnostics. Skipping — this is NOT a sign the file is error-free.`,
+        };
+      }
+      throw err;
+    }
+  } catch (e) {
+    return { success: true, output: `[DIAG] Could not run diagnostics: ${e.message}` };
+  }
+};