Support multiple pixi envs w/ Environment.activate

Replaces the builder-level .environment() method (which baked a single
pixi environment name into the built Environment) with a runtime
activate(name) method on Environment itself. This better reflects the
pixi data model: a pixi project directory is a single unit that can
house multiple named environments, all sharing one build step.

env.activate("foo") eagerly runs `pixi install --environment foo` and
returns a new, ready Environment targeting that prefix. The default
environment is installed as usual during build(); non-default ones are
installed on demand via activate(). The base Environment.activate()
throws UnsupportedOperationException so other environment types stay
clean.

As per apposed/appose-python@59e6d94.

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

Author: ctrueden

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

@@ -74,6 +74,26 @@ default String type() {
 		return builder().envType();
 	}
 
+	/**
+	 * Returns a new Environment targeting a named sub-environment.
+	 * <p>
+	 * For pixi projects this installs (if needed) and activates the named
+	 * pixi environment, equivalent to {@code pixi run --environment <name>}.
+	 * The returned Environment is fully ready to launch services.
+	 * </p>
+	 *
+	 * @param name The sub-environment name (e.g. {@code "gpu"}, {@code "shiny"}).
+	 * @return A new Environment configured for the named sub-environment.
+	 * @throws BuildException If something goes wrong during activation.
+	 * @throws UnsupportedOperationException If this environment type does not
+	 *   support named sub-environments.
+	 */
+	default Environment activate(String name) throws BuildException {
+		throw new UnsupportedOperationException(
+			getClass().getSimpleName() + " does not support named sub-environments"
+		);
+	}
+
 	/**
 	 * Rebuilds this environment from scratch.
 	 * This deletes the existing environment directory and rebuilds it using the

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

@@ -232,13 +232,35 @@ protected Scheme resolveScheme() {
 		throw new IllegalStateException("Cannot determine scheme: neither scheme nor content is set");
 	}
 
+	/** Functional interface for activating a named sub-environment. */
+	@FunctionalInterface
+	public interface Activator {
+		Environment activate(String name) throws BuildException;
+	}
+
 	protected Environment createEnv(String base, List<String> binPaths, List<String> launchArgs) {
+		return createEnv(base, binPaths, launchArgs, null);
+	}
+
+	protected Environment createEnv( String base, List<String> binPaths,
+		List<String> launchArgs, Activator activator)
+	{
 		return new Environment() {
 			@Override public String base() { return base; }
 			@Override public List<String> binPaths() { return binPaths; }
 			@Override public List<String> launchArgs() { return launchArgs; }
 			@Override public Map<String, String> envVars() { return envVars; }
 			@Override public Builder<?> builder() { return BaseBuilder.this; }
+
+			@Override
+			public Environment activate(String name) throws BuildException {
+				if (activator == null) {
+					throw new UnsupportedOperationException(
+						getClass().getSimpleName() + " does not support named sub-environments"
+					);
+				}
+				return activator.activate(name);
+			}
 		};
 	}
 

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

@@ -54,24 +54,9 @@ public final class PixiBuilder extends BaseBuilder<PixiBuilder> {
 
 	private final List<String> condaPackages = new ArrayList<>();
 	private final List<String> pypiPackages = new ArrayList<>();
-	private String pixiEnvironment;
 
 	// -- PixiBuilder methods --
 
-	/**
-	 * Selects which pixi environment to activate within the manifest.
-	 * Pixi supports multiple named environments in a single {@code pixi.toml};
-	 * use this method to target one other than {@code "default"}.
-	 * Maps to {@code pixi run --environment <name>}.
-	 *
-	 * @param name The pixi environment name (e.g. {@code "cuda"}, {@code "cpu"}).
-	 * @return This builder instance, for fluent-style programming.
-	 */
-	public PixiBuilder environment(String name) {
-		this.pixiEnvironment = name;
-		return this;
-	}
-
 	/**
 	 * Adds conda packages to the environment.
 	 *
@@ -106,7 +91,6 @@ protected void addStateFields(Map<String, Object> state) {
 		super.addStateFields(state);
 		state.put("condaPackages", condaPackages);
 		state.put("pypiPackages", pypiPackages);
-		state.put("pixiEnvironment", pixiEnvironment);
 	}
 
 	@Override
@@ -289,22 +273,14 @@ private void runPixiInstall(Pixi pixi, File envDir) throws IOException, Interrup
 				pixi.setFlags(withFlag(flags, "-vv"));
 			}
 
-			String envName = pixiEnvironment != null ? pixiEnvironment : "default";
-			monitor = new PixiInstallMonitor(envDir, envName, progressSubscribers,
+			monitor = new PixiInstallMonitor(envDir, "default", progressSubscribers,
 				msg -> errorSubscribers.forEach(sub -> sub.accept(msg)));
 			pixi.setErrorConsumer(monitor::intercept);
 		}
 
 		// Ensure the pixi environment is fully installed.
-		List<String> installCmd = new ArrayList<>(Arrays.asList(
-				"install", "--manifest-path", manifestFile.getAbsolutePath()
-		));
-		if (pixiEnvironment != null) {
-			installCmd.add("--environment");
-			installCmd.add(pixiEnvironment);
-		}
 		try {
-			pixi.exec(installCmd.toArray(new String[0]));
+			pixi.exec("install", "--manifest-path", manifestFile.getAbsolutePath());
 		}
 		finally {
 			if (monitor != null) {
@@ -322,18 +298,31 @@ private Environment buildPixiEnvironment(Pixi pixi, File envDir) {
 		if (!manifestFile.exists()) manifestFile = new File(envDir, "pixi.toml");
 
 		String base = envDir.getAbsolutePath();
-		String envName = pixiEnvironment != null ? pixiEnvironment : "default";
 		List<String> launchArgs = new ArrayList<>(Arrays.asList(
-				pixi.command, "run", "--manifest-path",
-				manifestFile.getAbsolutePath()
+			pixi.command, "run", "--manifest-path", manifestFile.getAbsolutePath()
 		));
-		if (pixiEnvironment != null) {
-			launchArgs.add("--environment");
-			launchArgs.add(pixiEnvironment);
-		}
 		List<String> binPaths = Collections.singletonList(
-			envDir.toPath().resolve(".pixi").resolve("envs").resolve(envName).resolve("bin").toString()
+			envDir.toPath().resolve(".pixi").resolve("envs").resolve("default").resolve("bin").toString()
 		);
-		return createEnv(base, binPaths, launchArgs);
+
+		final File manifestFileFinal = manifestFile;
+		Activator activator = name -> {
+			try {
+				pixi.exec("install", "--manifest-path", manifestFileFinal.getAbsolutePath(),
+					"--environment", name);
+			}
+			catch (IOException | InterruptedException e) {
+				throw new org.apposed.appose.BuildException(this, e);
+			}
+			List<String> activatedLaunchArgs = new ArrayList<>(launchArgs);
+			activatedLaunchArgs.add("--environment");
+			activatedLaunchArgs.add(name);
+			List<String> activatedBinPaths = Collections.singletonList(
+				envDir.toPath().resolve(".pixi").resolve("envs").resolve(name).resolve("bin").toString()
+			);
+			return createEnv(base, activatedBinPaths, activatedLaunchArgs);
+		};
+
+		return createEnv(base, binPaths, launchArgs, activator);
 	}
 }

src/test/java/org/apposed/appose/builder/PixiBuilderTest.java

@@ -196,25 +196,25 @@ public void testContentPixiToml() throws Exception {
 		cowsayAndAssert(env, "toml!");
 	}
 
-	/** Tests that {@code .environment()} selects a non-default pixi environment. */
+	/** Tests that {@code env.activate()} launches a service in a non-default pixi environment. */
 	@Test
-	public void testPixiEnvironmentSelection() throws Exception {
+	public void testPixiActivate() throws Exception {
 		Environment env = Appose
 			.pixi("src/test/resources/envs/cowsay-multi-env.toml")
 			.base("target/envs/pixi-multi-env")
-			.environment("alt")
 			.logDebug()
 			.build();
 		assertInstanceOf(PixiBuilder.class, env.builder());
+		Environment altEnv = env.activate("alt");
 		// Verify launch args include --environment alt.
-		List<String> launchArgs = env.launchArgs();
+		List<String> launchArgs = altEnv.launchArgs();
 		int idx = launchArgs.indexOf("--environment");
 		assertTrue(idx >= 0, "launchArgs should contain --environment");
 		assertEquals("alt", launchArgs.get(idx + 1));
 		// Verify bin path resolves to the alt environment directory.
-		assertTrue(env.binPaths().get(0).contains(File.separator + "alt" + File.separator),
+		assertTrue(altEnv.binPaths().get(0).contains(File.separator + "alt" + File.separator),
 			"binPaths should reference the alt environment");
-		cowsayAndAssert(env, "multi-env");
+		cowsayAndAssert(altEnv, "multi-env");
 	}
 
 	/**