feat: add WAR file support with full JAR parity (#2431)

maxandersen · claude · web-flow · commit fb47430be8b2 · 2026-03-28T01:03:14.000+01:00
Co-authored-by: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/docs/modules/ROOT/pages/dependencies.adoc b/docs/modules/ROOT/pages/dependencies.adoc
@@ -116,6 +116,17 @@ jbang eu.maveniverse.maven.plugins:toolbox:0.1.9:cli@fatjar
 
 Without `@fatjar` it would resolve dependencies which would be redundant.
 
+== Dependencies with WAR Files
+
+You can add dependencies to WAR files just like JAR files:
+
+[source, bash]
+----
+$ jbang --deps org.postgresql:postgresql:42.3.1 app.war
+----
+
+WAR files support all dependency-related features including `//DEPS` directives, BOM POMs, and custom repositories.
+
 == Managed dependencies ("BOM POM"'s) [Experimental]
 
 When using libraries and frameworks it can get tedious to manage and update multiple versions.
diff --git a/docs/modules/ROOT/pages/running.adoc b/docs/modules/ROOT/pages/running.adoc
@@ -12,6 +12,25 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
+== Running WAR Files
+
+JBang can run executable WAR files that contain a Main-Class manifest entry:
+
+[source, bash]
+----
+$ jbang https://download.structurizr.com/structurizr-2026.03.06.war version
+----
+
+WAR files are treated identically to JAR files and support all the same features:
+
+* Run with arguments: `jbang app.war arg1 arg2`
+* Add dependencies: `jbang --deps com.google.gson:gson:2.8.9 app.war`
+* Use in interactive mode: `jbang --interactive app.war`
+* Create aliases and use in catalogs
+
+The WAR file must contain a Main-Class entry in its META-INF/MANIFEST.MF, just like
+executable JAR files.
+
 == Interactive REPL
 
 `jbang --interactive` enables use of `jshell` to explore and use your script and any dependencies in a REPL editor.
diff --git a/docs/modules/cli/pages/jbang-run.adoc b/docs/modules/cli/pages/jbang-run.adoc
@@ -39,6 +39,9 @@ jbang-run - Builds and runs provided script. (default command)
 
 Builds and runs provided script. (default command)
 
+The script can be a Java source file, JAR file, WAR file, or URL reference.
+WAR files are supported just like JAR files and must contain a Main-Class manifest entry.
+
 // end::picocli-generated-man-section-description[]
 
 // tag::picocli-generated-man-section-options[]
diff --git a/src/main/java/dev/jbang/cli/Edit.java b/src/main/java/dev/jbang/cli/Edit.java
@@ -167,7 +167,7 @@ public Integer doCall() throws IOException {
 			ProjectBuilder pb = createProjectBuilder();
 			final Project prj = pb.build(scriptMixin.scriptOrFile);
 
-			if (prj.isJar() || prj.getMainSourceSet().getSources().isEmpty()) {
+			if (prj.isExecutableArchive() || prj.getMainSourceSet().getSources().isEmpty()) {
 				throw new ExitException(EXIT_INVALID_INPUT, "You can only edit source files");
 			}
 
diff --git a/src/main/java/dev/jbang/cli/Export.java b/src/main/java/dev/jbang/cli/Export.java
@@ -555,7 +555,7 @@ int apply(BuildContext ctx) throws IOException {
 		}
 
 		Project prj = ctx.getProject();
-		if (prj.isJar() || prj.getMainSourceSet().getSources().isEmpty()) {
+		if (prj.isExecutableArchive() || prj.getMainSourceSet().getSources().isEmpty()) {
 			Util.errorMsg("You can only export source files");
 			return EXIT_INVALID_INPUT;
 		}
diff --git a/src/main/java/dev/jbang/resources/resolvers/RenamingScriptResourceResolver.java b/src/main/java/dev/jbang/resources/resolvers/RenamingScriptResourceResolver.java
@@ -57,7 +57,7 @@ public ResourceRef resolve(String resource) {
 				List<String> knownExtensions = forceType != null ? Collections.singletonList(forceType.extension)
 						: Source.Type.extensions();
 				String ext = Util.extension(probe.getName());
-				if (!ext.equals("jar")
+				if (!ext.equals("jar") && !ext.equals("war")
 						&& !knownExtensions.contains(ext)
 						&& (!Util.isPreview() || !Project.BuildFile.fileNames().contains(probe.getName()))) {
 					if (probe.isDirectory()) {
diff --git a/src/main/java/dev/jbang/source/AppBuilder.java b/src/main/java/dev/jbang/source/AppBuilder.java
@@ -49,8 +49,8 @@ public CmdGeneratorBuilder build() throws IOException {
 		// always build the jar for native mode
 		// it allows integrations the options to produce the native image
 		boolean buildRequired = true;
-		if (project.isJar()) {
-			Util.verboseMsg("The resource is a jar, no compilation to be done.");
+		if (project.isExecutableArchive()) {
+			Util.verboseMsg("The resource is an executable archive, no compilation to be done.");
 			buildRequired = false;
 		} else if (fresh) {
 			Util.verboseMsg("Building as fresh build explicitly requested.");
diff --git a/src/main/java/dev/jbang/source/BuildContext.java b/src/main/java/dev/jbang/source/BuildContext.java
@@ -57,7 +57,7 @@ public Project getProject() {
 	public Path getJarFile() {
 		if (project.isJShell()) {
 			return null;
-		} else if (project.isJar()) {
+		} else if (project.isExecutableArchive()) {
 			return project.getResourceRef().getFile();
 		} else {
 			return getBasePath(".jar");
diff --git a/src/main/java/dev/jbang/source/CodeBuilderProvider.java b/src/main/java/dev/jbang/source/CodeBuilderProvider.java
@@ -76,7 +76,7 @@ protected Builder<CmdGeneratorBuilder> getBuilder(BuildContext ctx) {
 		if (prj.getMainSource() != null) {
 			return prj.getMainSource().getBuilder(ctx);
 		} else {
-			if (prj.isJar() && prj.isNativeImage()) {
+			if (prj.isExecutableArchive() && prj.isNativeImage()) {
 				// JARs normally don't need building unless a native image
 				// was requested
 				return new JavaSource.JavaAppBuilder(ctx);
diff --git a/src/main/java/dev/jbang/source/Project.java b/src/main/java/dev/jbang/source/Project.java
@@ -322,14 +322,38 @@ public static Builder<CmdGeneratorBuilder> codeBuilder(BuildContext ctx) {
 		return CodeBuilderProvider.create(ctx).get();
 	}
 
+	/**
+	 * @return true if this project is backed by an executable archive (jar or war)
+	 * @deprecated Use isExecutableArchive() for clarity. Kept for backwards
+	 *             compatibility.
+	 */
+	@Deprecated
 	public boolean isJar() {
-		return Project.isJar(getResourceRef().getFile());
+		return isExecutableArchive();
+	}
+
+	public boolean isExecutableArchive() {
+		return Project.isExecutableArchive(getResourceRef().getFile());
+	}
+
+	static boolean isExecutableArchive(Path backingFile) {
+		return hasExecutableExtension(backingFile);
 	}
 
 	static boolean isJar(Path backingFile) {
 		return backingFile != null && backingFile.toString().endsWith(".jar");
 	}
 
+	/**
+	 * Checks if the given file has an executable archive extension (.jar or .war)
+	 *
+	 * @param backingFile the file to check
+	 * @return true if the file has a .jar or .war extension, false otherwise
+	 */
+	static boolean hasExecutableExtension(Path backingFile) {
+		return Util.hasExecutableExtension(backingFile);
+	}
+
 	public boolean isJShell() {
 		return Project.isJShell(getResourceRef().getFile());
 	}
diff --git a/src/main/java/dev/jbang/source/ProjectBuilder.java b/src/main/java/dev/jbang/source/ProjectBuilder.java
@@ -305,7 +305,7 @@ public Project build(ResourceRef resourceRef) {
 		}
 
 		Project prj;
-		if (resourceRef.getFile().getFileName().toString().endsWith(".jar")) {
+		if (Project.hasExecutableExtension(resourceRef.getFile())) {
 			prj = createJarProject(resourceRef);
 		} else if (Util.isPreview()
 				&& resourceRef.getFile().getFileName().toString().equals(Project.BuildFile.jbang.fileName)) {
diff --git a/src/main/java/dev/jbang/util/Util.java b/src/main/java/dev/jbang/util/Util.java
@@ -86,6 +86,8 @@ public class Util {
 	public static final String JBANG_PREFER_GUI = "JBANG_PREFER_GUI";
 	private static final String JBANG_DOWNLOAD_SOURCES = "JBANG_DOWNLOAD_SOURCES";
 
+	private static final List<String> EXECUTABLE_EXTENSIONS = Arrays.asList(".jar", ".war");
+
 	public static final Pattern patternMainMethod = Pattern.compile(
 			"^.*(public\\s+static|static\\s+public)\\s+void\\s+main\\s*\\(.*|void\\s+main\\s*\\(\\)",
 			Pattern.MULTILINE);
@@ -424,6 +426,34 @@ public static Path basePathWithoutPattern(String path) {
 		}
 	}
 
+	/**
+	 * Checks if the given file has an executable archive extension (.jar or .war)
+	 *
+	 * @param backingFile the file to check
+	 * @return true if the file has a .jar or .war extension, false otherwise
+	 */
+	public static boolean hasExecutableExtension(Path backingFile) {
+		if (backingFile == null) {
+			return false;
+		}
+		return hasExecutableExtension(backingFile.toString());
+	}
+
+	/**
+	 * Checks if the given filename has an executable archive extension (.jar or
+	 * .war)
+	 *
+	 * @param filename the filename to check
+	 * @return true if the filename has a .jar or .war extension, false otherwise
+	 */
+	public static boolean hasExecutableExtension(String filename) {
+		if (filename == null) {
+			return false;
+		}
+		String lowerFilename = filename.toLowerCase();
+		return EXECUTABLE_EXTENSIONS.stream().anyMatch(lowerFilename::endsWith);
+	}
+
 	/**
 	 * @param name script name
 	 * @return camel case of kebab string if name does not end with .java or .jsh
@@ -432,6 +462,10 @@ public static String unkebabify(String name) {
 		if (name.endsWith(".sh")) {
 			name = name.substring(0, name.length() - 3);
 		}
+		// Don't rename executable archives
+		if (hasExecutableExtension(name)) {
+			return name;
+		}
 		boolean valid = false;
 		for (String extension : Source.Type.extensions()) {
 			valid |= name.endsWith("." + extension);
@@ -657,8 +691,9 @@ public static Path swizzleContent(String fileURL, Path filePath) throws IOExcept
 		// to handle if kubectl-style name (i.e. extension less)
 		File f = filePath.toFile();
 		String nonkebabname = f.getName();
-		if (!f.getName().endsWith(".jar") && !f.getName().endsWith(".jsh")) { // avoid directly downloaded jar files
-																				// getting renamed to .java
+		if (!hasExecutableExtension(f.getName()) && !f.getName().endsWith(".jsh")) { // avoid directly downloaded
+																						// executable archives
+			// getting renamed to .java
 			nonkebabname = unkebabify(f.getName());
 		}
 		if (nonkebabname.equals(f.getName())) {
diff --git a/src/test/java/dev/jbang/cli/TestExport.java b/src/test/java/dev/jbang/cli/TestExport.java
@@ -593,4 +593,5 @@ void testExportFatjarSignatures(@TempDir Path temp) throws Exception {
 		assertThat(result.err, containsString("DUMMY.DSA"));
 		assertThat(result.err, containsString("DUMMY.RSA"));
 	}
+
 }
diff --git a/src/test/java/dev/jbang/cli/TestInfo.java b/src/test/java/dev/jbang/cli/TestInfo.java
@@ -5,13 +5,16 @@
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.Collection;
 
 import org.hamcrest.Matchers;
 import org.junit.jupiter.api.Test;
 
 import dev.jbang.BaseTest;
+import dev.jbang.util.WarTestFixtures;
 
 import picocli.CommandLine;
 
@@ -198,4 +201,23 @@ void testInfoToolsWithDocs() throws IOException {
 		Tools docs = (Tools) pr.subcommand().subcommand().commandSpec().userObject();
 		docs.call();
 	}
+
+	@Test
+	void testInfoClasspathForWar() throws IOException {
+		Path warPath = Files.createTempFile("app", ".war");
+		try {
+			WarTestFixtures.createExecutableWar(warPath, "TestMain");
+			String war = warPath.toString();
+			CommandLine.ParseResult pr = JBang.getCommandLine().parseArgs("info", "tools", war);
+			Tools tools = (Tools) pr.subcommand().subcommand().commandSpec().userObject();
+			BaseInfoCommand.ScriptInfo info = tools.getInfo(false);
+			assertThat(info.originalResource, equalTo(war));
+			assertThat(info.applicationJar, equalTo(war));
+			assertThat(info.backingResource, equalTo(war));
+			assertThat(info.mainClass, equalTo("TestMain"));
+			assertThat(info.resolvedDependencies, empty());
+		} finally {
+			Files.deleteIfExists(warPath);
+		}
+	}
 }
diff --git a/src/test/java/dev/jbang/cli/TestRun.java b/src/test/java/dev/jbang/cli/TestRun.java
@@ -82,6 +82,7 @@
 import dev.jbang.util.JavaUtil;
 import dev.jbang.util.NetUtil;
 import dev.jbang.util.Util;
+import dev.jbang.util.WarTestFixtures;
 
 import picocli.CommandLine;
 
@@ -2663,4 +2664,32 @@ void testForceJavaSourceTypeOnJshFile() throws Exception {
 			}
 		}
 	}
+
+	@Test
+	void testRunLocalWarFile() throws IOException {
+		environmentVariables.clear("JAVA_HOME");
+
+		Path warPath = jbangTempDir.resolve("test-app.war");
+		try {
+			// Create executable WAR file
+			WarTestFixtures.createExecutableWar(warPath, "TestMain");
+			String war = warPath.toAbsolutePath().toString();
+
+			// Verify the WAR file can be run
+			CommandLine.ParseResult pr = JBang.getCommandLine().parseArgs("run", war);
+			Run run = (Run) pr.subcommand().commandSpec().userObject();
+
+			ProjectBuilder pb = run.createProjectBuilderForRun();
+			Project code = pb.build(war);
+
+			// The WAR file should be recognized as a JAR/executable
+			assertThat(code.getResourceRef().getFile().toString(), equalTo(war));
+			assertThat(code.isJar(), equalTo(true));
+
+			// Main class should be set from WAR manifest
+			assertThat(code.getMainClass(), equalTo("TestMain"));
+		} finally {
+			Files.deleteIfExists(warPath);
+		}
+	}
 }
diff --git a/src/test/java/dev/jbang/source/TestAppBuilder.java b/src/test/java/dev/jbang/source/TestAppBuilder.java
@@ -0,0 +1,30 @@
+package dev.jbang.source;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+
+import dev.jbang.BaseTest;
+import dev.jbang.util.WarTestFixtures;
+
+public class TestAppBuilder extends BaseTest {
+
+	@Test
+	void testWarSkipsCompilation() throws IOException {
+		Path warPath = Files.createTempFile("test", ".war");
+		try {
+			WarTestFixtures.createExecutableWar(warPath, "TestMain");
+			Project project = Project.builder().build(warPath);
+			BuildContext ctx = BuildContext.forProject(project);
+			assertTrue(project.isExecutableArchive());
+			assertNotNull(ctx.getJarFile());
+		} finally {
+			Files.deleteIfExists(warPath);
+		}
+	}
+}
diff --git a/src/test/java/dev/jbang/source/TestBuildContext.java b/src/test/java/dev/jbang/source/TestBuildContext.java
@@ -0,0 +1,31 @@
+package dev.jbang.source;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.Test;
+
+import dev.jbang.BaseTest;
+import dev.jbang.util.WarTestFixtures;
+
+public class TestBuildContext extends BaseTest {
+
+	@Test
+	void testGetJarFileForWar() throws IOException {
+		Path warPath = Files.createTempFile("test", ".war");
+		try {
+			WarTestFixtures.createExecutableWar(warPath, "TestMain");
+			Project project = Project.builder().build(warPath);
+			BuildContext ctx = BuildContext.forProject(project);
+			Path jarFile = ctx.getJarFile();
+			assertNotNull(jarFile);
+			assertEquals(warPath, jarFile);
+		} finally {
+			Files.deleteIfExists(warPath);
+		}
+	}
+}
diff --git a/src/test/java/dev/jbang/source/TestCodeBuilderProvider.java b/src/test/java/dev/jbang/source/TestCodeBuilderProvider.java
diff --git a/src/test/java/dev/jbang/source/TestProject.java b/src/test/java/dev/jbang/source/TestProject.java
diff --git a/src/test/java/dev/jbang/source/TestProjectBuilder.java b/src/test/java/dev/jbang/source/TestProjectBuilder.java
diff --git a/src/test/java/dev/jbang/util/TestUtil.java b/src/test/java/dev/jbang/util/TestUtil.java
diff --git a/src/test/java/dev/jbang/util/TestWarFixtures.java b/src/test/java/dev/jbang/util/TestWarFixtures.java
diff --git a/src/test/java/dev/jbang/util/WarTestFixtures.java b/src/test/java/dev/jbang/util/WarTestFixtures.java

Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,7 @@ public Integer doCall() throws IOException {`
`167`	`167`	`ProjectBuilder pb = createProjectBuilder();`
`168`	`168`	`final Project prj = pb.build(scriptMixin.scriptOrFile);`
`169`	`169`
`170`		`- if (prj.isJar() \|\| prj.getMainSourceSet().getSources().isEmpty()) {`
	`170`	`+ if (prj.isExecutableArchive() \|\| prj.getMainSourceSet().getSources().isEmpty()) {`
`171`	`171`	`throw new ExitException(EXIT_INVALID_INPUT, "You can only edit source files");`
`172`	`172`	`}`
`173`	`173`
Original file line number	Diff line number	Diff line change
`@@ -555,7 +555,7 @@ int apply(BuildContext ctx) throws IOException {`
`555`	`555`	`}`
`556`	`556`
`557`	`557`	`Project prj = ctx.getProject();`
`558`		`- if (prj.isJar() \|\| prj.getMainSourceSet().getSources().isEmpty()) {`
	`558`	`+ if (prj.isExecutableArchive() \|\| prj.getMainSourceSet().getSources().isEmpty()) {`
`559`	`559`	`Util.errorMsg("You can only export source files");`
`560`	`560`	`return EXIT_INVALID_INPUT;`
`561`	`561`	`}`