@jshookmcp/jshook 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,7 @@
 
 English | [中文](./README.zh.md)
 
-An MCP (Model Context Protocol) server providing **245 built-in tools** — **238 domain tools across 16 domains** plus **8 built-in meta-tools** — with runtime extension loading from `plugins/` and `workflows/` for AI-assisted JavaScript analysis and security analysis. Combines browser automation, Chrome DevTools Protocol debugging, network monitoring, intelligent JavaScript hooks, LLM-powered code analysis, process/memory inspection, WASM toolchain, binary encoding, anti-anti-debug, GraphQL discovery, source map reconstruction, AST transforms, crypto reconstruction, platform package analysis, Burp Suite / native analysis tool bridges, human behavior simulation, CAPTCHA solving, batch account workflows, and high-level composite workflow orchestration in a single server.
+An MCP (Model Context Protocol) server providing **249 built-in tools** — **242 domain tools across 17 domains** plus **7 built-in meta-tools** — with runtime extension loading from `plugins/` and `workflows/` for AI-assisted JavaScript analysis and security analysis. Combines browser automation, Chrome DevTools Protocol debugging, network monitoring, intelligent JavaScript hooks, LLM-powered code analysis, process/memory inspection, WASM toolchain, binary encoding, anti-anti-debug, GraphQL discovery, source map reconstruction, AST transforms, crypto reconstruction, platform package analysis, Burp Suite / native analysis tool bridges, human behavior simulation, CAPTCHA solving, batch account workflows, and high-level composite workflow orchestration in a single server.
 
 ## Documentation / Quick Links
 
@@ -42,11 +42,11 @@ Provides a comprehensive suite of tools for AI-assisted JavaScript analysis, bro
 - **Lazy Domain Initialization**: Handler classes instantiated via Proxy on first invocation, not during startup
 - **Domain Self-Discovery**: Runtime manifest scanning (`domains/*/manifest.ts`) replaces hardcoded imports; add new domains by creating a single manifest file
 - **B-Skeleton Contracts**: Extensibility contracts for plugins (`PluginContract`), workflows (`WorkflowContract`), and observability (`InstrumentationContract`)
-- **Context Efficiency Benchmark**: Built-in tool-schema init delta (Claude server-side count, 2026-03-12): `search` ≈ 2,975 tokens vs `full` ≈ 34,985 tokens (12 vs 238 built-in tools; values change as tools/descriptions evolve)
+- **Context Efficiency Benchmark**: Built-in tool-schema init delta (Claude server-side count, 2026-03-12): `search` ≈ 2,975 tokens vs `full` ≈ 34,985 tokens (12 vs 249 built-in tools; values change as tools/descriptions evolve)
 
 ## Tool Domains
 
-The server provides **245 built-in tools** across **16 domains** (Browser, Debugger, Network, Hooks, Maintenance, Core Analysis, Process/Memory, Workflows, WASM, Streaming, Encoding, Anti-Debug, GraphQL, Platform, Burp Suite, and Native Analysis).
+The server provides **249 built-in tools** across **17 domains** (`antidebug`, `browser`, `coordination`, `core`, `debugger`, `encoding`, `graphql`, `hooks`, `maintenance`, `network`, `platform`, `process`, `sourcemap`, `streaming`, `transform`, `wasm`, and `workflow`).
 
 > **[View the complete Tool Reference ↗](https://vmoranv.github.io/jshookmcp/reference/)**
 
@@ -58,7 +58,7 @@ The server provides **245 built-in tools** across **16 domains** (Browser, Debug
 
 <a href="https://www.star-history.com/?repos=vmoranv%2Fjshookmcp&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
    <img alt="Star History Chart" src="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
  </picture>

package/README.zh.md

@@ -8,7 +8,7 @@
 
 [English](./README.md) | 中文
 
-面向 AI 辅助 JavaScript 分析与安全分析的 MCP（模型上下文协议）服务器，提供 **245 个内置工具**——其中 **16 个域下 238 个域工具**，外加 **8 个内置元工具**——并支持从 `plugins/` 与 `workflows/` 目录运行时动态扩展。集成浏览器自动化、Chrome DevTools Protocol 调试、网络监控、智能 JavaScript Hook、LLM 驱动代码分析、进程/内存操作、WASM 工具链、二进制编码、反反调试、GraphQL 发现、Source Map 重建、AST 变换、加密重构、平台包分析、Burp Suite / Native 分析工具桥接及高层复合工作流编排。
+面向 AI 辅助 JavaScript 分析与安全分析的 MCP（模型上下文协议）服务器，提供 **249 个内置工具**——其中 **17 个域下 242 个域工具**，外加 **7 个内置元工具**——并支持从 `plugins/` 与 `workflows/` 目录运行时动态扩展。集成浏览器自动化、Chrome DevTools Protocol 调试、网络监控、智能 JavaScript Hook、LLM 驱动代码分析、进程/内存操作、WASM 工具链、二进制编码、反反调试、GraphQL 发现、Source Map 重建、AST 变换、加密重构、平台包分析、Burp Suite / Native 分析工具桥接及高层复合工作流编排。
 
 ## 文档与快速导航
 
@@ -42,7 +42,7 @@
 - **域延迟初始化**：处理器类通过 Proxy 在首次调用时实例化，而非启动时预加载
 - **域自发现架构**：运行时扫描 `domains/*/manifest.ts` 替代硬编码导入；新增域只需创建一个 manifest 文件
 - **B-Skeleton 契约**：插件（`PluginContract`）、工作流（`WorkflowContract`）、可观测性（`InstrumentationContract`）的扩展性契约
-- **上下文效率基准**：基于 Claude 服务端对当前内置工具 schema 的实测计数（2026-03-12），`search` 档 ≈ 2,975 tokens，`full` 档 ≈ 34,985 tokens（当前分别为 12 与 238 个 built-in tools；数值会随工具与描述变更而变化）
+- **上下文效率基准**：基于 Claude 服务端对当前内置工具 schema 的实测计数（2026-03-12），`search` 档 ≈ 2,975 tokens，`full` 档 ≈ 34,985 tokens（当前分别为 12 与 249 个 built-in tools；数值会随工具与描述变更而变化）
 
 ## 项目统计
 
@@ -50,7 +50,7 @@
 
 <a href="https://www.star-history.com/?repos=vmoranv%2Fjshookmcp&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
    <img alt="Star History Chart" src="https://api.star-history.com/image?repos=vmoranv/jshookmcp&type=date&legend=top-left" />
  </picture>

package/dist/native/scripts/linux/enum-windows.sh

@@ -1,12 +1,12 @@
-#!/bin/bash
-# enum-windows.sh
-# Linux window enumeration script (placeholder)
-
-TARGET_PID=$1
-
-# Use xdotool or wmctrl for window enumeration
-# This is a placeholder for future implementation
-
-if command -v xdotool &> /dev/null; then
-    xdotool search --pid "$TARGET_PID" --name "" get-window-name
-fi
+#!/bin/bash
+# enum-windows.sh
+# Linux window enumeration script (placeholder)
+
+TARGET_PID=$1
+
+# Use xdotool or wmctrl for window enumeration
+# This is a placeholder for future implementation
+
+if command -v xdotool &> /dev/null; then
+    xdotool search --pid "$TARGET_PID" --name "" get-window-name
+fi

package/dist/native/scripts/macos/enum-windows.applescript

@@ -1,22 +1,22 @@
--- enum-windows.applescript
--- macOS window enumeration script (placeholder)
-
-param TargetPid
-
--- AppleScript implementation for window enumeration
--- This is a placeholder for future implementation
-
-tell application "System Events"
-    set windowList to {}
-    repeat with proc in (every process whose unix id is TargetPid)
-        repeat with win in windows of proc
-            set end of windowList to {¬
-                title: name of win, ¬
-                position: position of win, ¬
-                size: size of win ¬
-            }
-        end repeat
-    end repeat
-end tell
-
-return windowList
+-- enum-windows.applescript
+-- macOS window enumeration script (placeholder)
+
+param TargetPid
+
+-- AppleScript implementation for window enumeration
+-- This is a placeholder for future implementation
+
+tell application "System Events"
+    set windowList to {}
+    repeat with proc in (every process whose unix id is TargetPid)
+        repeat with win in windows of proc
+            set end of windowList to {¬
+                title: name of win, ¬
+                position: position of win, ¬
+                size: size of win ¬
+            }
+        end repeat
+    end repeat
+end tell
+
+return windowList

package/dist/native/scripts/windows/enum-windows-by-class.ps1

@@ -1,51 +1,51 @@
-param(
-    [string]$ClassPattern
-)
-
-Add-Type @"
-  using System;
-  using System.Runtime.InteropServices;
-  public class Win32 {
-    [DllImport("user32.dll")] public static extern IntPtr FindWindowEx(IntPtr parent, IntPtr childAfter, string className, string title);
-    [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr hWnd, out int pid);
-    [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder text, int count);
-    [DllImport("user32.dll")] public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder className, int maxCount);
-  }
-"@
-
-$windows = @()
-$hwnd = [IntPtr]::Zero
-while ($true) {
-  $hwnd = [Win32]::FindWindowEx([IntPtr]::Zero, $hwnd, $null, $null)
-  if ($hwnd -eq [IntPtr]::Zero) { break }
-
-  $className = New-Object System.Text.StringBuilder 256
-  [Win32]::GetClassName($hwnd, $className, 256) | Out-Null
-  $classNameStr = $className.ToString()
-
-  # Support wildcard pattern matching
-  $isMatch = $false
-  if ($ClassPattern -eq $classNameStr) {
-    $isMatch = $true
-  } elseif ($ClassPattern.Contains('*')) {
-    # Convert wildcard pattern to regex
-    $regexPattern = [regex]::Escape($ClassPattern).Replace('\*', '.*')
-    if ($classNameStr -match $regexPattern) {
-      $isMatch = $true
-    }
-  }
-
-  if ($isMatch) {
-    $windowPid = 0
-    [Win32]::GetWindowThreadProcessId($hwnd, [ref]$windowPid) | Out-Null
-    $title = New-Object System.Text.StringBuilder 256
-    [Win32]::GetWindowText($hwnd, $title, 256) | Out-Null
-    $windows += @{
-      Handle = $hwnd.ToString()
-      Title = $title.ToString()
-      ClassName = $classNameStr
-      ProcessId = $windowPid
-    }
-  }
-}
-$windows | ConvertTo-Json -Compress
+param(
+    [string]$ClassPattern
+)
+
+Add-Type @"
+  using System;
+  using System.Runtime.InteropServices;
+  public class Win32 {
+    [DllImport("user32.dll")] public static extern IntPtr FindWindowEx(IntPtr parent, IntPtr childAfter, string className, string title);
+    [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr hWnd, out int pid);
+    [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder text, int count);
+    [DllImport("user32.dll")] public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder className, int maxCount);
+  }
+"@
+
+$windows = @()
+$hwnd = [IntPtr]::Zero
+while ($true) {
+  $hwnd = [Win32]::FindWindowEx([IntPtr]::Zero, $hwnd, $null, $null)
+  if ($hwnd -eq [IntPtr]::Zero) { break }
+
+  $className = New-Object System.Text.StringBuilder 256
+  [Win32]::GetClassName($hwnd, $className, 256) | Out-Null
+  $classNameStr = $className.ToString()
+
+  # Support wildcard pattern matching
+  $isMatch = $false
+  if ($ClassPattern -eq $classNameStr) {
+    $isMatch = $true
+  } elseif ($ClassPattern.Contains('*')) {
+    # Convert wildcard pattern to regex
+    $regexPattern = [regex]::Escape($ClassPattern).Replace('\*', '.*')
+    if ($classNameStr -match $regexPattern) {
+      $isMatch = $true
+    }
+  }
+
+  if ($isMatch) {
+    $windowPid = 0
+    [Win32]::GetWindowThreadProcessId($hwnd, [ref]$windowPid) | Out-Null
+    $title = New-Object System.Text.StringBuilder 256
+    [Win32]::GetWindowText($hwnd, $title, 256) | Out-Null
+    $windows += @{
+      Handle = $hwnd.ToString()
+      Title = $title.ToString()
+      ClassName = $classNameStr
+      ProcessId = $windowPid
+    }
+  }
+}
+$windows | ConvertTo-Json -Compress

package/dist/native/scripts/windows/enum-windows.ps1

@@ -1,44 +1,44 @@
-param(
-    [int]$TargetPid
-)
-
-Add-Type @"
-  using System;
-  using System.Runtime.InteropServices;
-  public class Win32 {
-    [DllImport("user32.dll")] public static extern IntPtr FindWindowEx(IntPtr parent, IntPtr childAfter, string className, string title);
-    [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr hWnd, out int pid);
-    [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder text, int count);
-    [DllImport("user32.dll")] public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder className, int maxCount);
-    [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
-    [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
-  }
-"@
-
-$windows = @()
-$hwnd = [IntPtr]::Zero
-while ($true) {
-  $hwnd = [Win32]::FindWindowEx([IntPtr]::Zero, $hwnd, $null, $null)
-  if ($hwnd -eq [IntPtr]::Zero) { break }
-  $windowPid = 0
-  [Win32]::GetWindowThreadProcessId($hwnd, [ref]$windowPid) | Out-Null
-  if ($windowPid -eq $TargetPid) {
-    $title = New-Object System.Text.StringBuilder 256
-    $className = New-Object System.Text.StringBuilder 256
-    [Win32]::GetWindowText($hwnd, $title, 256) | Out-Null
-    [Win32]::GetClassName($hwnd, $className, 256) | Out-Null
-    $rect = New-Object Win32+RECT
-    [Win32]::GetWindowRect($hwnd, [ref]$rect) | Out-Null
-    $windows += @{
-      Handle = $hwnd.ToString()
-      Title = $title.ToString()
-      ClassName = $className.ToString()
-      ProcessId = $windowPid
-      Left = $rect.Left
-      Top = $rect.Top
-      Right = $rect.Right
-      Bottom = $rect.Bottom
-    }
-  }
-}
-$windows | ConvertTo-Json -Compress
+param(
+    [int]$TargetPid
+)
+
+Add-Type @"
+  using System;
+  using System.Runtime.InteropServices;
+  public class Win32 {
+    [DllImport("user32.dll")] public static extern IntPtr FindWindowEx(IntPtr parent, IntPtr childAfter, string className, string title);
+    [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr hWnd, out int pid);
+    [DllImport("user32.dll")] public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder text, int count);
+    [DllImport("user32.dll")] public static extern int GetClassName(IntPtr hWnd, System.Text.StringBuilder className, int maxCount);
+    [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
+    [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+  }
+"@
+
+$windows = @()
+$hwnd = [IntPtr]::Zero
+while ($true) {
+  $hwnd = [Win32]::FindWindowEx([IntPtr]::Zero, $hwnd, $null, $null)
+  if ($hwnd -eq [IntPtr]::Zero) { break }
+  $windowPid = 0
+  [Win32]::GetWindowThreadProcessId($hwnd, [ref]$windowPid) | Out-Null
+  if ($windowPid -eq $TargetPid) {
+    $title = New-Object System.Text.StringBuilder 256
+    $className = New-Object System.Text.StringBuilder 256
+    [Win32]::GetWindowText($hwnd, $title, 256) | Out-Null
+    [Win32]::GetClassName($hwnd, $className, 256) | Out-Null
+    $rect = New-Object Win32+RECT
+    [Win32]::GetWindowRect($hwnd, [ref]$rect) | Out-Null
+    $windows += @{
+      Handle = $hwnd.ToString()
+      Title = $title.ToString()
+      ClassName = $className.ToString()
+      ProcessId = $windowPid
+      Left = $rect.Left
+      Top = $rect.Top
+      Right = $rect.Right
+      Bottom = $rect.Bottom
+    }
+  }
+}
+$windows | ConvertTo-Json -Compress

package/dist/native/scripts/windows/inject-dll.ps1

@@ -1,21 +1,21 @@
-param(
-    [int]$TargetPid,
-    [string]$DllPath
-)
-
-Add-Type @"
-  using System;
-  using System.Runtime.InteropServices;
-  public class Injector {
-    [DllImport("kernel32.dll")] public static extern IntPtr OpenProcess(int access, bool inherit, int pid);
-    [DllImport("kernel32.dll")] public static extern IntPtr VirtualAllocEx(IntPtr hProcess, IntPtr addr, int size, int alloc, int protect);
-    [DllImport("kernel32.dll")] public static extern bool WriteProcessMemory(IntPtr hProcess, IntPtr addr, byte[] buffer, int size, out int written);
-    [DllImport("kernel32.dll")] public static extern IntPtr CreateRemoteThread(IntPtr hProcess, IntPtr attr, int stack, IntPtr start, IntPtr param, int flags, out int threadId);
-    [DllImport("kernel32.dll")] public static extern IntPtr GetModuleHandle(string name);
-    [DllImport("kernel32.dll")] public static extern IntPtr GetProcAddress(IntPtr hModule, string name);
-    [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
-  }
-"@
-
-# Injection requires elevated privileges and is disabled for safety
-Write-Output "DLL injection is disabled for safety in this implementation. PID: $TargetPid, DLL: $DllPath"
+param(
+    [int]$TargetPid,
+    [string]$DllPath
+)
+
+Add-Type @"
+  using System;
+  using System.Runtime.InteropServices;
+  public class Injector {
+    [DllImport("kernel32.dll")] public static extern IntPtr OpenProcess(int access, bool inherit, int pid);
+    [DllImport("kernel32.dll")] public static extern IntPtr VirtualAllocEx(IntPtr hProcess, IntPtr addr, int size, int alloc, int protect);
+    [DllImport("kernel32.dll")] public static extern bool WriteProcessMemory(IntPtr hProcess, IntPtr addr, byte[] buffer, int size, out int written);
+    [DllImport("kernel32.dll")] public static extern IntPtr CreateRemoteThread(IntPtr hProcess, IntPtr attr, int stack, IntPtr start, IntPtr param, int flags, out int threadId);
+    [DllImport("kernel32.dll")] public static extern IntPtr GetModuleHandle(string name);
+    [DllImport("kernel32.dll")] public static extern IntPtr GetProcAddress(IntPtr hModule, string name);
+    [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
+  }
+"@
+
+# Injection requires elevated privileges and is disabled for safety
+Write-Output "DLL injection is disabled for safety in this implementation. PID: $TargetPid, DLL: $DllPath"

package/dist/packages/extension-sdk/src/bridges/shared.d.ts

@@ -0,0 +1,40 @@
+export type JsonObject = Record<string, unknown>;
+export type TextToolResponse = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export type ProcessRunResult = {
+    ok: boolean;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    truncated: boolean;
+};
+export type HttpJsonResult = {
+    status: number;
+    data: JsonObject;
+    text: string;
+};
+export declare function toTextResponse(payload: Record<string, unknown>): TextToolResponse;
+export declare function toErrorResponse(tool: string, error: unknown, extra?: Record<string, unknown>): TextToolResponse;
+export declare function parseStringArg(args: Record<string, unknown>, key: string, required?: boolean): string | undefined;
+export declare function toDisplayPath(absolutePath: string): string;
+export declare function resolveOutputDirectory(toolName: string, target: string, requestedDir?: string): Promise<{
+    absolutePath: string;
+    displayPath: string;
+}>;
+export declare function checkExternalCommand(command: string, versionArgs: string[], label: string, installHint?: string): Promise<TextToolResponse>;
+export declare function runProcess(command: string, args: string[], options?: {
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+    maxStderrBytes?: number;
+    cwd?: string;
+}): Promise<ProcessRunResult>;
+export declare function assertLoopbackUrl(value: string, label?: string): string;
+export declare function normalizeBaseUrl(value: string): string;
+export declare function buildUrl(baseUrl: string, path: string, query?: Record<string, unknown>): string;
+export declare function requestJson(url: string, method?: string, bodyObj?: Record<string, unknown>, timeoutMs?: number): Promise<HttpJsonResult>;

package/dist/packages/extension-sdk/src/bridges/shared.js

@@ -0,0 +1,196 @@
+import { execFile, spawn } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function toTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+export function toErrorResponse(tool, error, extra = {}) {
+    return toTextResponse({
+        success: false,
+        tool,
+        error: error instanceof Error ? error.message : String(error),
+        ...extra,
+    });
+}
+export function parseStringArg(args, key, required = false) {
+    const value = args[key];
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    if (required) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return undefined;
+}
+export function toDisplayPath(absolutePath) {
+    const relPath = relative(process.cwd(), absolutePath).replace(/\\/g, '/');
+    if (relPath.length === 0)
+        return '.';
+    return relPath.startsWith('..') ? absolutePath.replace(/\\/g, '/') : relPath;
+}
+function sanitizePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+export async function resolveOutputDirectory(toolName, target, requestedDir) {
+    if (requestedDir) {
+        const absolutePath = resolve(requestedDir);
+        await mkdir(absolutePath, { recursive: true });
+        return { absolutePath, displayPath: toDisplayPath(absolutePath) };
+    }
+    const absolutePath = resolve(process.cwd(), 'artifacts', toolName, `${sanitizePathSegment(target)}-${Date.now()}`);
+    await mkdir(absolutePath, { recursive: true });
+    return { absolutePath, displayPath: toDisplayPath(absolutePath) };
+}
+export async function checkExternalCommand(command, versionArgs, label, installHint) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, versionArgs, {
+            timeout: 10_000,
+        });
+        const version = (stdout || stderr).trim().split('\n')[0] ?? '';
+        return toTextResponse({
+            success: true,
+            tool: label,
+            available: true,
+            version,
+        });
+    }
+    catch (error) {
+        return toTextResponse({
+            success: true,
+            tool: label,
+            available: false,
+            reason: error instanceof Error ? error.message : String(error),
+            ...(installHint ? { installHint } : {}),
+        });
+    }
+}
+export async function runProcess(command, args, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const maxStdout = options.maxStdoutBytes ?? 10 * 1024 * 1024;
+    const maxStderr = options.maxStderrBytes ?? 1 * 1024 * 1024;
+    return await new Promise((resolveResult) => {
+        const startedAt = Date.now();
+        const child = spawn(command, args, {
+            shell: false,
+            windowsHide: true,
+            cwd: options.cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let settled = false;
+        let timedOut = false;
+        const finish = (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            resolveResult({
+                ok: exitCode === 0 && !timedOut,
+                exitCode,
+                signal,
+                stdout,
+                stderr,
+                durationMs: Date.now() - startedAt,
+                truncated: stdoutTruncated || stderrTruncated,
+            });
+        };
+        const timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 2_000);
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            if (stdout.length >= maxStdout) {
+                stdoutTruncated = true;
+                return;
+            }
+            const raw = chunk.toString('utf-8');
+            const remaining = maxStdout - stdout.length;
+            stdout += raw.slice(0, remaining);
+            if (raw.length > remaining)
+                stdoutTruncated = true;
+        });
+        child.stderr.on('data', (chunk) => {
+            if (stderr.length >= maxStderr) {
+                stderrTruncated = true;
+                return;
+            }
+            const raw = chunk.toString('utf-8');
+            const remaining = maxStderr - stderr.length;
+            stderr += raw.slice(0, remaining);
+            if (raw.length > remaining)
+                stderrTruncated = true;
+        });
+        child.on('close', (code, signal) => {
+            finish(code, signal);
+        });
+        child.on('error', (error) => {
+            stderr += `${stderr ? '\n' : ''}Spawn error: ${error.message}`;
+            finish(1, null);
+        });
+    });
+}
+export function assertLoopbackUrl(value, label = 'endpoint') {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid ${label} URL: ${value}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${label}: only http/https protocols are allowed, got ${url.protocol}`);
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    const isLoopback = host === '127.0.0.1' || host === 'localhost' || host === '::1';
+    if (!isLoopback) {
+        throw new Error(`${label}: only loopback hosts are allowed (127.0.0.1/localhost/::1), got ${host}`);
+    }
+    return url.toString();
+}
+export function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    return `${url.protocol}//${url.host}`;
+}
+export function buildUrl(baseUrl, path, query = {}) {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const url = new URL(`${baseUrl.replace(/\/$/, '')}${normalizedPath}`);
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+export async function requestJson(url, method = 'GET', bodyObj, timeoutMs = 15_000) {
+    const body = bodyObj ? JSON.stringify(bodyObj) : undefined;
+    const response = await fetch(url, {
+        method,
+        headers: {
+            Accept: 'application/json',
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await response.text();
+    let data = {};
+    if (text.length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { text };
+        }
+    }
+    return { status: response.status, data, text };
+}