fix(agent): Support running agent on bootstrap classpath

- Update `Agent.java` to use `Agent.class.getResource()` instead of
  `Agent.class.getClassLoader().getResource()` when locating the agent JAR.
  This prevents a `NullPointerException` when the agent is loaded by the
  bootstrap class loader (where `getClassLoader()` returns null).
- Modify `Properties.java` to automatically default `appmap.debug.disableGit`
  to `true` if the agent is running on the bootstrap classpath. This avoids
  crashes in JGit initialization, which relies on `ResourceBundle` loading
  that is problematic in the bootstrap context.
- Add a warning log in `Agent.premain` when running on the bootstrap
  classpath, advising that this configuration is for troubleshooting only.

Author: dividedmind

agent/src/main/java/com/appland/appmap/Agent.java

@@ -74,6 +74,10 @@ public static void premain(String agentArgs, Instrumentation inst) {
     logger.info("config: {}", AppMapConfig.get());
     logger.debug("System properties: {}", System.getProperties());
 
+    if (Agent.class.getClassLoader() == null) {
+      logger.warn("AppMap agent is running on the bootstrap classpath. This is not a recommended configuration and should only be used for troubleshooting. Git integration will be disabled.");
+    }
+
     addAgentJars(agentArgs, inst);
 
 
@@ -162,12 +166,18 @@ private static void addAgentJars(String agentArgs, Instrumentation inst) {
     Path agentJarPath = null;
     try {
       Class<Agent> agentClass = Agent.class;
-      URL resourceURL = agentClass.getClassLoader()
-          .getResource(agentClass.getName().replace('.', '/') + ".class");
+      // When the agent is loaded by the bootstrap class loader (e.g., via -Xbootclasspath/a:),
+      // agentClass.getClassLoader() returns null, leading to a NullPointerException. To handle
+      // this, we use Class.getResource() which correctly resolves resources even when the
+      // class is loaded by the bootstrap class loader. The leading '/' in the resource name
+      // is crucial for absolute path resolution when using Class.getResource().
+      URL resourceURL = agentClass.getResource("/" + agentClass.getName().replace('.', '/') + ".class");
+
       // During testing of the agent itself, classes get loaded from a directory, and will have the
       // protocol "file". The rest of the time (i.e. when it's actually deployed), they'll always
-      // come from a jar file.
-      if (resourceURL.getProtocol().equals("jar")) {
+      // come from a jar file. We must also check that resourceURL is not null before using it,
+      // as getResource() can return null if the resource is not found.
+      if (resourceURL != null && resourceURL.getProtocol().equals("jar")) {
         String resourcePath = resourceURL.getPath();
         URL jarURL = new URL(resourcePath.substring(0, resourcePath.indexOf('!')));
         logger.debug("jarURL: {}", jarURL);

agent/src/main/java/com/appland/appmap/config/Properties.java

@@ -21,7 +21,12 @@ public class Properties {
   public static final String DebugClassPrefix = resolveProperty("appmap.debug.classPrefix", (String) null);
   public static final Boolean SaveInstrumented =
       resolveProperty("appmap.debug.saveInstrumented", false);
-  public static final Boolean DisableGit = resolveProperty("appmap.debug.disableGit", false);
+  public static final Boolean DisableGit =
+      // Git integration (JGit) uses resource bundles, which are not reliably available
+      // when the agent is loaded by the bootstrap class loader (i.e., when
+      // getClassLoader() returns null). In such cases, automatically disable Git
+      // to prevent NullPointerExceptions during initialization.
+      resolveProperty("appmap.debug.disableGit", Properties.class.getClassLoader() == null);
 
   public static final Boolean RecordingAuto = resolveProperty("appmap.recording.auto", false);
   public static final String RecordingName = resolveProperty("appmap.recording.name", (String) null);

agent/test/classloading/app/build.gradle

@@ -47,12 +47,21 @@ application {
     // Define the main class for the application.
     mainClass = 'com.appland.appmap.test.fixture.Runner'
     def libJar = tasks.getByPath(':lib:jar').outputs.files.singleFile
+
+    // Allow testing with bootstrap classpath instead of javaagent
+    def useBootstrapClasspath = findProperty("useBootstrapClasspath") == "true"
+
     applicationDefaultJvmArgs += [
-      "-javaagent:${appmapJar}",
-      /*"-Dsun.misc.URLClassPath.debug",*/
-      "-DtestJars=${configurations.servlet.asPath};${libJar}",
-      "-Djava.util.logging.config.file=${System.env.JUL_CONFIG}"
+        "-javaagent:${appmapJar}",
+        /*"-Dsun.misc.URLClassPath.debug",*/
+        "-DtestJars=${configurations.servlet.asPath};${libJar}",
+        "-Djava.util.logging.config.file=${System.env.JUL_CONFIG}"
     ]
+    if (useBootstrapClasspath) {
+        applicationDefaultJvmArgs += [
+          "-Xbootclasspath/a:${appmapJar}",
+        ]
+    }
 }
 
 tasks.named('test') {

agent/test/classloading/app/src/main/java/com/appland/appmap/test/fixture/TestBootstrapClasspath.java

@@ -0,0 +1,45 @@
+package com.appland.appmap.test.fixture;
+
+import com.appland.appmap.Agent;
+import com.appland.appmap.config.Properties;
+
+/**
+ * Test that verifies the agent can run when loaded on the bootstrap classpath.
+ * This is a regression test for the fix that prevents NullPointerException when
+ * Agent.class.getClassLoader() returns null.
+ */
+public class TestBootstrapClasspath implements TestClass {
+
+  @Override
+  public int beforeTest() throws Exception {
+    return 0;
+  }
+
+  @Override
+  public int runTest() throws Exception {
+    // Verify that the agent is actually running on the bootstrap classpath
+    ClassLoader agentClassLoader = Agent.class.getClassLoader();
+    if (agentClassLoader != null) {
+      System.err.println("ERROR: Agent is not running on bootstrap classpath");
+      System.err.println("Agent class loader: " + agentClassLoader);
+      return 1;
+    }
+
+    // Verify that Properties class is also on bootstrap classpath
+    ClassLoader propertiesClassLoader = Properties.class.getClassLoader();
+    if (propertiesClassLoader != null) {
+      System.err.println("ERROR: Properties is not running on bootstrap classpath");
+      System.err.println("Properties class loader: " + propertiesClassLoader);
+      return 1;
+    }
+
+    // Verify that Git integration is automatically disabled when on bootstrap classpath
+    if (!Properties.DisableGit) {
+      System.err.println("ERROR: Git integration should be automatically disabled on bootstrap classpath");
+      return 1;
+    }
+
+    System.out.println("SUCCESS: Agent running on bootstrap classpath with Git disabled");
+    return 0;
+  }
+}

agent/test/classloading/classloading.bats

@@ -1,9 +1,11 @@
+#!/usr/bin/env bats
+
 load '../helper'
 
 setup_file() {
   export AGENT_JAR="$(find_agent_jar)"
 
-  cd test/classloading
+  cd "$BATS_TEST_DIRNAME"
   _configure_logging
 }
 
@@ -24,3 +26,17 @@ setup_file() {
   assert_json_eq ".events[0].method_id" "getGreeting"
   assert_json_eq ".events[0].path" "lib/src/main/java/com/appland/appmap/test/fixture/helloworld/HelloWorld.java"
 }
+
+@test "Bootstrap Classpath" {
+  # Regression test for fix that allows running agent on bootstrap classpath.
+  # This verifies that:
+  # 1. Agent.class.getResource() works when getClassLoader() returns null
+  # 2. Git integration is automatically disabled on bootstrap classpath
+  # 3. No NullPointerException occurs during agent initialization
+  run \
+    gradlew ${BATS_VERSION+-q} -PappmapJar="$AGENT_JAR" -PuseBootstrapClasspath=true run --args "TestBootstrapClasspath"
+  assert_success
+
+  # Verify the test confirmed running on bootstrap classpath with Git disabled
+  assert_output --partial "SUCCESS: Agent running on bootstrap classpath with Git disabled"
+}