feat: no config debug support

wenytang-ms · wenytang-ms · commit e1ab7c05f6d4 · 2025-10-15T11:01:28.000+08:00
diff --git a/bundled/scripts/noConfigScripts/README.md b/bundled/scripts/noConfigScripts/README.md
@@ -6,10 +6,11 @@ This feature enables configuration-less debugging for Java applications, similar
 
 When you open a terminal in VS Code with this extension installed, the following environment variables are automatically set:
 
-- `JAVA_TOOL_OPTIONS`: Configured with JDWP to enable debugging on a random port
 - `VSCODE_JDWP_ADAPTER_ENDPOINTS`: Path to a communication file for port exchange
 - `PATH`: Includes the `javadebug` command wrapper
 
+Note: `JAVA_TOOL_OPTIONS` is NOT set globally to avoid affecting other Java tools (javac, maven, gradle). Instead, it's set only when you run the `javadebug` command.
+
 ## Usage
 
 ### Basic Usage
@@ -60,11 +61,12 @@ javadebug -jar myapp.jar --spring.profiles.active=dev
 
 ## How It Works Internally
 
-1. The extension sets `JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0,quiet=y`
-2. When you run `javadebug`, it wraps the Java process
-3. The wrapper captures the JDWP port from JVM output: "Listening for transport dt_socket at address: 12345"
-4. The port is written to a communication file
-5. VS Code's file watcher detects the file and automatically starts an attach debug session
+1. When you run `javadebug`, the wrapper script temporarily sets `JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0`
+2. The wrapper launches the Java process with JDWP enabled
+3. JVM starts and outputs: "Listening for transport dt_socket at address: 12345"
+4. The wrapper captures the JDWP port from this output
+5. The port is written to a communication file
+6. VS Code's file watcher detects the file and automatically starts an attach debug session
 
 ## Troubleshooting
 
@@ -74,19 +76,21 @@ If you see "Address already in use", another Java debug session is running. Term
 
 ### No Breakpoints Hit
 
-1. Ensure you're running with `javadebug` command
-2. Check that JAVA_TOOL_OPTIONS is set in your terminal
+1. Ensure you're running with `javadebug` command (not plain `java`)
+2. Check that the `javadebug` command is available: `which javadebug` (Unix) or `Get-Command javadebug` (PowerShell)
 3. Verify the terminal was opened AFTER the extension activated
+4. Check the Debug Console for error messages
 
 ### Node.js Not Found
 
 The wrapper script requires Node.js to be installed and available in PATH.
 
 ## Limitations
 
-- Requires Node.js to be installed
+- Requires Node.js to be installed and available in PATH
 - Only works in terminals opened within VS Code
-- Cannot debug applications that override JAVA_TOOL_OPTIONS
+- Requires using the `javadebug` command instead of `java`
+- The Java process will suspend (hang) until the debugger attaches
 
 ## See Also
 
diff --git a/bundled/scripts/noConfigScripts/javadebug b/bundled/scripts/noConfigScripts/javadebug
@@ -5,6 +5,10 @@
 # Export the endpoint file path for JDWP port communication
 export JDWP_ADAPTER_ENDPOINTS=$VSCODE_JDWP_ADAPTER_ENDPOINTS
 
+# Set JDWP options only for this javadebug invocation
+# This overrides the global JAVA_TOOL_OPTIONS to avoid affecting other Java processes
+export JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0"
+
 # Get the directory of this script
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
diff --git a/bundled/scripts/noConfigScripts/javadebug.bat b/bundled/scripts/noConfigScripts/javadebug.bat
@@ -5,5 +5,9 @@ REM This script intercepts java commands and automatically enables JDWP debuggin
 REM Export the endpoint file path for JDWP port communication
 set JDWP_ADAPTER_ENDPOINTS=%VSCODE_JDWP_ADAPTER_ENDPOINTS%
 
+REM Set JDWP options only for this javadebug invocation
+REM This overrides the global JAVA_TOOL_OPTIONS to avoid affecting other Java processes
+set JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0
+
 REM Use Node.js wrapper to capture JDWP port
 node "%~dp0jdwp-wrapper.js" %*
diff --git a/bundled/scripts/noConfigScripts/javadebug.ps1 b/bundled/scripts/noConfigScripts/javadebug.ps1
@@ -4,6 +4,10 @@
 # Export the endpoint file path for JDWP port communication
 $env:JDWP_ADAPTER_ENDPOINTS = $env:VSCODE_JDWP_ADAPTER_ENDPOINTS
 
+# Set JDWP options only for this javadebug invocation
+# This overrides the global JAVA_TOOL_OPTIONS to avoid affecting other Java processes
+$env:JAVA_TOOL_OPTIONS = "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0"
+
 # Get the directory of this script
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 
diff --git a/bundled/scripts/noConfigScripts/jdwp-wrapper.js b/bundled/scripts/noConfigScripts/jdwp-wrapper.js
@@ -43,64 +43,52 @@ if (!isDebugEnabled) {
     let portCaptured = false;
     const jdwpPortRegex = /Listening for transport dt_socket at address:\s*(\d+)/;
 
+    // Shared function to capture JDWP port from output
+    const capturePort = (output) => {
+        if (portCaptured) return;
+        
+        const match = output.match(jdwpPortRegex);
+        if (match && match[1]) {
+            const port = parseInt(match[1], 10);
+            
+            // Validate port range
+            if (port < 1 || port > 65535) {
+                console.error(`[Java Debug] Invalid port number: ${port}`);
+                return;
+            }
+            
+            console.log(`[Java Debug] Captured JDWP port: ${port}`);
+            
+            // Write port to endpoint file
+            const endpointData = JSON.stringify({
+                client: {
+                    host: 'localhost',
+                    port: port
+                }
+            });
+
+            try {
+                fs.writeFileSync(endpointFile, endpointData, 'utf8');
+                console.log(`[Java Debug] Wrote endpoint file: ${endpointFile}`);
+                portCaptured = true;
+            } catch (err) {
+                console.error(`[Java Debug] Failed to write endpoint file: ${err}`);
+            }
+        }
+    };
+
     // Monitor stdout for JDWP port
     child.stdout.on('data', (data) => {
         const output = data.toString();
         process.stdout.write(data);
-
-        if (!portCaptured) {
-            const match = output.match(jdwpPortRegex);
-            if (match && match[1]) {
-                const port = parseInt(match[1], 10);
-                console.log(`[Java Debug] Captured JDWP port: ${port}`);
-                
-                // Write port to endpoint file
-                const endpointData = JSON.stringify({
-                    client: {
-                        host: 'localhost',
-                        port: port
-                    }
-                });
-
-                try {
-                    fs.writeFileSync(endpointFile, endpointData, 'utf8');
-                    console.log(`[Java Debug] Wrote endpoint file: ${endpointFile}`);
-                    portCaptured = true;
-                } catch (err) {
-                    console.error(`[Java Debug] Failed to write endpoint file: ${err}`);
-                }
-            }
-        }
+        capturePort(output);
     });
 
-    // Monitor stderr
+    // Monitor stderr for JDWP port (it might appear on stderr)
     child.stderr.on('data', (data) => {
         const output = data.toString();
         process.stderr.write(data);
-
-        // JDWP message might appear on stderr
-        if (!portCaptured) {
-            const match = output.match(jdwpPortRegex);
-            if (match && match[1]) {
-                const port = parseInt(match[1], 10);
-                console.log(`[Java Debug] Captured JDWP port: ${port}`);
-                
-                const endpointData = JSON.stringify({
-                    client: {
-                        host: 'localhost',
-                        port: port
-                    }
-                });
-
-                try {
-                    fs.writeFileSync(endpointFile, endpointData, 'utf8');
-                    console.log(`[Java Debug] Wrote endpoint file: ${endpointFile}`);
-                    portCaptured = true;
-                } catch (err) {
-                    console.error(`[Java Debug] Failed to write endpoint file: ${err}`);
-                }
-            }
-        }
+        capturePort(output);
     });
 
     child.on('exit', (code) => process.exit(code || 0));
diff --git a/src/noConfigDebugInit.ts b/src/noConfigDebugInit.ts
@@ -49,22 +49,22 @@ export async function registerNoConfigDebug(
     if (!fs.existsSync(tempDirPath)) {
         fs.mkdirSync(tempDirPath, { recursive: true });
     } else {
-        // remove endpoint file in the temp directory if it exists
+        // remove endpoint file in the temp directory if it exists (async to avoid blocking)
         if (fs.existsSync(tempFilePath)) {
-            fs.unlinkSync(tempFilePath);
+            fs.promises.unlink(tempFilePath).catch((err) => {
+                console.error(`[Java Debug] Failed to cleanup old endpoint file: ${err}`);
+            });
         }
     }
 
     // clear the env var collection to remove any existing env vars
     collection.clear();
 
-    // Add env vars for VSCODE_JDWP_ADAPTER_ENDPOINTS and JAVA_TOOL_OPTIONS
+    // Add env var for VSCODE_JDWP_ADAPTER_ENDPOINTS
+    // Note: We do NOT set JAVA_TOOL_OPTIONS globally to avoid affecting all Java processes
+    // (javac, maven, gradle, language server, etc.). Instead, JAVA_TOOL_OPTIONS is set
+    // only in the javadebug wrapper scripts (javadebug.ps1, javadebug.bat, javadebug)
     collection.replace('VSCODE_JDWP_ADAPTER_ENDPOINTS', tempFilePath);
-    
-    // Configure JDWP to listen on a random port and suspend until debugger attaches
-    // quiet=y prevents the "Listening for transport..." message from appearing in terminal
-    collection.replace('JAVA_TOOL_OPTIONS', 
-        '-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=0,quiet=y');
 
     const noConfigScriptsDir = path.join(extPath, 'bundled', 'scripts', 'noConfigScripts');
     const pathSeparator = process.platform === 'win32' ? ';' : ':';
@@ -81,10 +81,19 @@ export async function registerNoConfigDebug(
         new vscode.RelativePattern(tempDirPath, '**/*.txt')
     );
     
-    const fileCreationEvent = fileSystemWatcher.onDidCreate(async (uri) => {
+    // Track active debug sessions to prevent duplicates
+    const activeDebugSessions = new Set<number>();
+    
+    // Handle both file creation and modification to support multiple runs
+    const handleEndpointFile = async (uri: vscode.Uri) => {
         console.log('[Java Debug] No-config debug session detected');
 
         const filePath = uri.fsPath;
+        
+        // Add a small delay to ensure file is fully written
+        // File system events can fire before write is complete
+        await new Promise(resolve => setTimeout(resolve, 100));
+        
         fs.readFile(filePath, (err, data) => {
             if (err) {
                 console.error(`[Java Debug] Error reading endpoint file: ${err}`);
@@ -94,8 +103,31 @@ export async function registerNoConfigDebug(
                 // parse the client port
                 const dataParse = data.toString();
                 const jsonData = JSON.parse(dataParse);
-                const clientPort = jsonData.client?.port;
+                
+                // Validate JSON structure
+                if (!jsonData || typeof jsonData !== 'object' || !jsonData.client) {
+                    console.error(`[Java Debug] Invalid endpoint file format: ${dataParse}`);
+                    return;
+                }
+                
+                const clientPort = jsonData.client.port;
+                
+                // Validate port number
+                if (!clientPort || typeof clientPort !== 'number' || clientPort < 1 || clientPort > 65535) {
+                    console.error(`[Java Debug] Invalid port number: ${clientPort}`);
+                    return;
+                }
+                
+                // Check if we already have an active session for this port
+                if (activeDebugSessions.has(clientPort)) {
+                    console.log(`[Java Debug] Debug session already active for port ${clientPort}, skipping`);
+                    return;
+                }
+                
                 console.log(`[Java Debug] Parsed JDWP port: ${clientPort}`);
+                
+                // Mark this port as active
+                activeDebugSessions.add(clientPort);
 
                 const options: vscode.DebugSessionOptions = {
                     noDebug: false,
@@ -116,24 +148,52 @@ export async function registerNoConfigDebug(
                     (started) => {
                         if (started) {
                             console.log('[Java Debug] Successfully started no-config debug session');
+                            // Clean up the endpoint file after successful debug session start (async)
+                            if (fs.existsSync(filePath)) {
+                                fs.promises.unlink(filePath).then(() => {
+                                    console.log('[Java Debug] Cleaned up endpoint file');
+                                }).catch((cleanupErr) => {
+                                    console.error(`[Java Debug] Failed to cleanup endpoint file: ${cleanupErr}`);
+                                });
+                            }
                         } else {
                             console.error('[Java Debug] Error starting debug session, session not started.');
+                            // Remove from active sessions on failure
+                            activeDebugSessions.delete(clientPort);
                         }
                     },
                     (error) => {
                         console.error(`[Java Debug] Error starting debug session: ${error}`);
+                        // Remove from active sessions on error
+                        activeDebugSessions.delete(clientPort);
                     },
                 );
             } catch (parseErr) {
                 console.error(`[Java Debug] Error parsing JSON: ${parseErr}`);
             }
         });
+    };
+
+    // Listen for both file creation and modification events
+    const fileCreationEvent = fileSystemWatcher.onDidCreate(handleEndpointFile);
+    const fileChangeEvent = fileSystemWatcher.onDidChange(handleEndpointFile);
+    
+    // Clean up active sessions when debug session ends
+    const debugSessionEndListener = vscode.debug.onDidTerminateDebugSession((session) => {
+        if (session.name === 'Attach to Java (No-Config)' && session.configuration.port) {
+            const port = session.configuration.port;
+            activeDebugSessions.delete(port);
+            console.log(`[Java Debug] Debug session ended for port ${port}`);
+        }
     });
 
     return Promise.resolve(
         new vscode.Disposable(() => {
             fileSystemWatcher.dispose();
             fileCreationEvent.dispose();
+            fileChangeEvent.dispose();
+            debugSessionEndListener.dispose();
+            activeDebugSessions.clear();
         }),
     );
 }
