Track builder state to skip redundant rebuilds

Each builder now serializes its configuration (builder type, content,
scheme, channels, flags, envVars, and builder-specific fields) to
appose.json in the environment directory after a successful build.
On subsequent build() calls, if the state matches the recorded JSON
the build is skipped entirely. If the state differs, the environment
is rebuilt from scratch (programmatic builds wipe the dir first to
avoid pixi init / mamba create conflicts with stale state).

- BaseBuilder: addStateFields / buildStateString / isUpToDate /
  writeApposeStateFile infrastructure
- PixiBuilder: addStateFields (condaPackages, pypiPackages,
  pixiEnvironment); removed isPixiDir gate in favour of appose.json;
  split createEnvironment into runPixiInstall + buildPixiEnvironment
  so the fast path can return without running pixi install
- MambaBuilder: removed isCondaDir gate; wipes env dir before mamba
  create on rebuild; falls back to wrap-as-is for externally-managed
  conda envs that have no environment.yml and no appose.json
- UvBuilder: addStateFields (pythonVersion, packages); removed outer
  isVenvBuilt gate; inner isVenvBuilt check retained for createVenv

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ctrueden

src/main/java/org/apposed/appose/Builder.java

@@ -38,7 +38,6 @@
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.nio.file.Paths;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;

src/main/java/org/apposed/appose/builder/BaseBuilder.java

@@ -35,15 +35,20 @@
 import org.apposed.appose.Scheme;
 import org.apposed.appose.util.Environments;
 import org.apposed.appose.util.FilePaths;
+import org.apposed.appose.util.Json;
 import org.apposed.appose.scheme.Schemes;
 
 import java.io.File;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.TreeMap;
 import java.util.function.Consumer;
 
 /**
@@ -164,6 +169,49 @@ private T typedThis() {
 		return (T) this;
 	}
 
+	/**
+	 * Populates the given map with this builder's state fields for
+	 * {@code appose.json} comparison. Subclasses should override this method,
+	 * calling {@code super.addStateFields(state)} first, then adding their own fields.
+	 *
+	 * @param state The map to populate with state fields.
+	 */
+	protected void addStateFields(Map<String, Object> state) {
+		state.put("content", content);
+		state.put("scheme", scheme != null ? scheme.name() : null);
+		state.put("channels", channels);
+		state.put("flags", flags);
+		state.put("envVars", new TreeMap<>(envVars));
+	}
+
+	/**
+	 * Returns true if {@code appose.json} in the given directory matches
+	 * the current builder's state, meaning no rebuild is needed.
+	 *
+	 * @param envDir The environment directory to check.
+	 * @return True if up to date, false if a rebuild is needed.
+	 * @throws IOException If reading {@code appose.json} fails.
+	 */
+	protected boolean isUpToDate(File envDir) throws IOException {
+		File apposeJson = new File(envDir, "appose.json");
+		if (!apposeJson.isFile()) return false;
+		String existing = new String(Files.readAllBytes(apposeJson.toPath()), StandardCharsets.UTF_8);
+		return existing.equals(buildStateString());
+	}
+
+	/**
+	 * Writes the current builder state to {@code appose.json} in the given directory.
+	 * This should be called after a successful build to record the state,
+	 * so that future calls can skip the build when the state is unchanged.
+	 *
+	 * @param envDir The environment directory.
+	 * @throws IOException If writing fails.
+	 */
+	protected void writeApposeStateFile(File envDir) throws IOException {
+		File apposeJson = new File(envDir, "appose.json");
+		Files.write(apposeJson.toPath(), buildStateString().getBytes(StandardCharsets.UTF_8));
+	}
+
 	/** Determines the environment directory path. */
 	protected File resolveEnvDir() {
 		if (envDir != null) return envDir;
@@ -193,4 +241,17 @@ protected Environment createEnv(String base, List<String> binPaths, List<String>
 			@Override public Builder<?> builder() { return BaseBuilder.this; }
 		};
 	}
+
+	/**
+	 * Builds a JSON string representing this builder's current configuration state.
+	 * Used to determine whether an existing environment needs to be rebuilt.
+	 *
+	 * @return JSON string of builder state.
+	 */
+	private final String buildStateString() {
+		Map<String, Object> state = new LinkedHashMap<>();
+		state.put("builder", envType());
+		addStateFields(state);
+		return Json.toJson(state);
+	}
 }

src/main/java/org/apposed/appose/builder/MambaBuilder.java

@@ -69,27 +69,22 @@ public Environment build() throws BuildException {
 			throw new BuildException(this, "Cannot use MambaBuilder: environment already managed by uv/venv at " + envDir);
 		}
 
-		// Create Mamba tool instance early so it's available for wrapping.
-		Mamba mamba = new Mamba();
+		// Infer scheme from content if available.
+		if (content != null && scheme == null) scheme = Schemes.fromContent(content);
 
-		// Is this envDir an already-existing conda directory?
-		boolean isCondaDir = new File(envDir, "conda-meta").isDirectory();
-		if (isCondaDir) {
-			// Environment already exists, just wrap it.
-			return createEnvironment(mamba, envDir);
+		// Validate content and scheme when content is provided.
+		if (content != null && !"environment.yml".equals(scheme.name())) {
+			throw new IllegalArgumentException("MambaBuilder only supports environment.yml scheme, got: " + scheme);
 		}
 
-		// Building a new environment - config content is required.
-		if (content == null) {
-			throw new IllegalStateException("No source specified for MambaBuilder. Use .file() or .content()");
+		// Check for unsupported features.
+		if (!channels.isEmpty()) {
+			throw new UnsupportedOperationException(
+				"MambaBuilder does not yet support programmatic channel configuration. " +
+				"Please specify channels in your environment.yml file.");
 		}
 
-		// Infer scheme if not explicitly set.
-		if (scheme == null) scheme = Schemes.fromContent(content);
-
-		if (!"environment.yml".equals(scheme.name())) {
-			throw new IllegalArgumentException("MambaBuilder only supports environment.yml scheme, got: " + scheme);
-		}
+		Mamba mamba = new Mamba();
 
 		// Set up progress/output consumers.
 		mamba.setOutputConsumer(msg -> outputSubscribers.forEach(sub -> sub.accept(msg)));
@@ -102,16 +97,27 @@ public Environment build() throws BuildException {
 		mamba.setEnvVars(envVars);
 		mamba.setFlags(flags);
 
-		// Check for unsupported features.
-		if (!channels.isEmpty()) {
-			throw new UnsupportedOperationException(
-				"MambaBuilder does not yet support programmatic channel configuration. " +
-				"Please specify channels in your environment.yml file.");
-		}
-
 		try {
+			// If the env state matches our current configuration,
+			// skip all package management and return immediately.
+			if (isUpToDate(envDir)) {
+				return createEnvironment(mamba, envDir);
+			}
+
+			// If no content was provided but this is an existing externally-managed
+			// conda env (no appose.json), wrap it as-is without rebuilding.
+			if (content == null) {
+				if (new File(envDir, "conda-meta").isDirectory()) {
+					return createEnvironment(mamba, envDir);
+				}
+				throw new IllegalStateException("No source specified for MambaBuilder. Use .file() or .content()");
+			}
+
 			mamba.install();
 
+			// Wipe any existing env to avoid conflicts with mamba create.
+			if (envDir.exists()) FilePaths.deleteRecursively(envDir);
+
 			// Two-step build: create empty env, write config, then update.
 			// Step 1: Create empty environment.
 			mamba.create(envDir);
@@ -123,6 +129,7 @@ public Environment build() throws BuildException {
 			// Step 3: Update environment from yml.
 			mamba.update(envDir, envYaml);
 
+			writeApposeStateFile(envDir);
 			return createEnvironment(mamba, envDir);
 		}
 		catch (IOException | InterruptedException e) {

src/main/java/org/apposed/appose/builder/PixiBuilder.java

@@ -43,6 +43,7 @@
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Type-safe builder for Pixi-based environments.
@@ -100,6 +101,14 @@ public String envType() {
 		return "pixi";
 	}
 
+	@Override
+	protected void addStateFields(Map<String, Object> state) {
+		super.addStateFields(state);
+		state.put("condaPackages", condaPackages);
+		state.put("pypiPackages", pypiPackages);
+		state.put("pixiEnvironment", pixiEnvironment);
+	}
+
 	@Override
 	public Environment build() throws BuildException {
 		File envDir = resolveEnvDir();
@@ -135,25 +144,17 @@ public Environment build() throws BuildException {
 		pixi.setFlags(flags);
 
 		try {
+			// Always ensure the pixi tool itself is available.
 			pixi.install();
 
-			// Check if this is already a pixi project.
-			boolean isPixiDir = new File(envDir, "pixi.toml").isFile() ||
-			                    new File(envDir, "pyproject.toml").isFile() ||
-			                    new File(envDir, ".pixi").isDirectory();
-
-			if (isPixiDir && content == null && condaPackages.isEmpty() && pypiPackages.isEmpty()) {
-				// Environment already exists, just use it.
-				return createEnvironment(pixi, envDir);
+			// If the env state matches our current configuration,
+			// skip all package management and return immediately.
+			if (isUpToDate(envDir)) {
+				return buildPixiEnvironment(pixi, envDir);
 			}
 
-			// Handle source-based build (file or content).
+			// Build (or rebuild) the environment.
 			if (content != null) {
-				if (isPixiDir) {
-					// Already initialized, just use it.
-					return createEnvironment(pixi, envDir);
-				}
-
 				if (!envDir.exists() && !envDir.mkdirs()) {
 					throw new BuildException(this, "Failed to create environment directory: " + envDir);
 				}
@@ -181,12 +182,10 @@ else if ("environment.yml".equals(scheme.name())) {
 				}
 			} else {
 				// Programmatic package building.
-				if (isPixiDir) {
-					// Already initialized, just use it.
-					return createEnvironment(pixi, envDir);
-				}
-
-				if (!envDir.exists() && !envDir.mkdirs()) {
+				// Wipe any existing env before reinitializing, to avoid conflicts
+				// with pixi init and to ensure no stale packages remain.
+				if (envDir.exists()) FilePaths.deleteRecursively(envDir);
+				if (!envDir.mkdirs()) {
 					throw new BuildException(this, "Failed to create environment directory: " + envDir);
 				}
 
@@ -230,7 +229,9 @@ else if ("environment.yml".equals(scheme.name())) {
 				}
 			}
 
-			return createEnvironment(pixi, envDir);
+			runPixiInstall(pixi, envDir);
+			writeApposeStateFile(envDir);
+			return buildPixiEnvironment(pixi, envDir);
 		}
 		catch (IOException | InterruptedException e) {
 			throw new BuildException(this, e);
@@ -276,8 +277,7 @@ private static List<String> withFlag(List<String> flags, String flag) {
 		return result;
 	}
 
-	private Environment createEnvironment(Pixi pixi, File envDir) throws IOException, InterruptedException {
-		// Check which manifest file exists (pyproject.toml takes precedence).
+	private void runPixiInstall(Pixi pixi, File envDir) throws IOException, InterruptedException {
 		File manifestFile = new File(envDir, "pyproject.toml");
 		if (!manifestFile.exists()) manifestFile = new File(envDir, "pixi.toml");
 
@@ -315,6 +315,11 @@ private Environment createEnvironment(Pixi pixi, File envDir) throws IOException
 				pixi.setFlags(flags);
 			}
 		}
+	}
+
+	private Environment buildPixiEnvironment(Pixi pixi, File envDir) {
+		File manifestFile = new File(envDir, "pyproject.toml");
+		if (!manifestFile.exists()) manifestFile = new File(envDir, "pixi.toml");
 
 		String base = envDir.getAbsolutePath();
 		String envName = pixiEnvironment != null ? pixiEnvironment : "default";

src/main/java/org/apposed/appose/builder/UvBuilder.java

@@ -44,6 +44,7 @@
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Type-safe builder for uv-based virtual environments.
@@ -86,6 +87,13 @@ public String envType() {
 		return "uv";
 	}
 
+	@Override
+	protected void addStateFields(Map<String, Object> state) {
+		super.addStateFields(state);
+		state.put("pythonVersion", pythonVersion);
+		state.put("packages", packages);
+	}
+
 	@Override
 	public Environment build() throws BuildException {
 		File envDir = resolveEnvDir();
@@ -129,16 +137,18 @@ public Environment build() throws BuildException {
 		}
 
 		try {
-			uv.install();
-
-			// Check if this is already a uv virtual environment.
-			boolean isUvVenv = new File(envDir, "pyvenv.cfg").isFile();
-
-			if (isUvVenv && content == null && packages.isEmpty()) {
-				// Environment already exists and no new config/packages, just use it.
+			// If the env state matches our current configuration,
+			// skip all package management and return immediately.
+			if (isUpToDate(envDir)) {
 				return createEnvironment(envDir);
 			}
 
+			uv.install();
+
+			// Determine whether the venv already exists.
+			boolean isVenvBuilt = new File(envDir, "pyvenv.cfg").isFile() ||
+			                      new File(envDir, ".venv").isDirectory();
+
 			// Handle source-based build (file or content).
 			if (content != null) {
 
@@ -158,7 +168,7 @@ public Environment build() throws BuildException {
 				} else {
 					// Handle requirements.txt - traditional venv + pip install.
 					// Create virtual environment if it doesn't exist.
-					if (!isUvVenv) {
+					if (!isVenvBuilt) {
 						uv.createVenv(envDir, pythonVersion);
 					}
 
@@ -171,7 +181,7 @@ public Environment build() throws BuildException {
 				}
 			} else {
 				// Programmatic package building.
-				if (!isUvVenv) {
+				if (!isVenvBuilt) {
 					// Create virtual environment.
 					uv.createVenv(envDir, pythonVersion);
 				}
@@ -187,6 +197,7 @@ public Environment build() throws BuildException {
 				}
 			}
 
+			writeApposeStateFile(envDir);
 			return createEnvironment(envDir);
 		}
 		catch (IOException | InterruptedException e) {