Add multi-pwsh virtual environment management (#24)

## Summary
- add multi-pwsh virtual environment management commands for creating,
listing, deleting, exporting, and importing named module environments
- allow `multi-pwsh host` to consume `-VirtualEnvironment` and `-venv`,
validate the selected environment, and temporarily set `PSModulePath`
before handing control to `pwsh`
- add `MULTI_PWSH_VENV_DIR`, expand CLI and integration coverage,
refresh the README for the renamed `Devolutions/multi-pwsh` repository,
and disable PowerShell update checks in host launches

## Verification
- `cargo fmt --all --check`
- `cargo clippy --workspace --all-targets` (existing `result_large_err`
warnings only)
- `cargo build --all-targets`
- `cargo test --all-targets`
- `dotnet build dotnet/Bindings.csproj`
- `dotnet test dotnet/Bindings.csproj --no-build -v minimal`

Author: mamoreau-devolutions

README.md

@@ -1,46 +1,42 @@
-# pwsh-host-rs
+# multi-pwsh
 
-Rust PowerShell hosting library that loads .NET delegates and drives `System.Management.Automation.PowerShell` through unmanaged entry points.
-
-## multi-pwsh
-
-Install and manage side-by-side PowerShell versions from GitHub Releases.
+Install and manage side-by-side PowerShell versions with aliases and native hosting.
 
 ![multi-pwsh](docs/images/multi-pwsh.png)
 
-### Bootstrap
+## Bootstrap
 
 Latest release bootstrap scripts:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/install-multi-pwsh.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/install-multi-pwsh.sh | bash
 ```
 
 ```powershell
-irm https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/install-multi-pwsh.ps1 | iex
+irm https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/install-multi-pwsh.ps1 | iex
 ```
 
 Install a specific tag (example `v0.6.0`):
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/install-multi-pwsh.sh | bash -s -- v0.6.0
+curl -fsSL https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/install-multi-pwsh.sh | bash -s -- v0.6.0
 ```
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/install-multi-pwsh.ps1))) -Version v0.6.0
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/install-multi-pwsh.ps1))) -Version v0.6.0
 ```
 
 Uninstall bootstrap scripts:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/uninstall-multi-pwsh.sh | bash
+curl -fsSL https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/uninstall-multi-pwsh.sh | bash
 ```
 
 ```powershell
-irm https://raw.githubusercontent.com/Devolutions/pwsh-host-rs/refs/heads/master/tools/uninstall-multi-pwsh.ps1 | iex
+irm https://raw.githubusercontent.com/Devolutions/multi-pwsh/refs/heads/master/tools/uninstall-multi-pwsh.ps1 | iex
 ```
 
-### Install and verify aliases
+## Install and verify aliases
 
 ```powershell
 multi-pwsh install 7.4
@@ -55,7 +51,7 @@ pwsh-7.4 --version
 pwsh-7.5 --version
 ```
 
-### Manage installed lines
+## Manage installed lines
 
 ```powershell
 multi-pwsh install 7.4.x
@@ -71,7 +67,12 @@ multi-pwsh install 7.6.0-rc.1
 multi-pwsh update 7.6 --include-prerelease
 multi-pwsh alias set 7.4 7.4.11
 multi-pwsh alias unset 7.4
-multi-pwsh host 7.4 -NoLogo -NoProfile -Command "$PSVersionTable.PSVersion"
+multi-pwsh venv create msgraph
+multi-pwsh venv export msgraph msgraph.zip
+multi-pwsh venv import msgraph-copy msgraph.zip
+multi-pwsh venv delete msgraph
+multi-pwsh venv list
+multi-pwsh host 7.4 -venv msgraph -NoLogo -NoProfile -Command "$env:PSModulePath"
 multi-pwsh doctor --repair-aliases
 ```
 
@@ -82,9 +83,14 @@ multi-pwsh install <version|major|major.minor|major.minor.x> [--arch <auto|x64|x
 multi-pwsh update <major.minor> [--arch <auto|x64|x86|arm64|arm32>] [--include-prerelease]
 multi-pwsh uninstall <version> [--force]
 multi-pwsh list [--available] [--include-prerelease]
+multi-pwsh venv create <name>
+multi-pwsh venv delete <name>
+multi-pwsh venv export <name> <archive.zip>
+multi-pwsh venv import <name> <archive.zip>
+multi-pwsh venv list
 multi-pwsh alias set <major.minor> <version|latest>
 multi-pwsh alias unset <major.minor>
-multi-pwsh host <version|major|major.minor|pwsh-alias> [pwsh arguments...]
+multi-pwsh host <version|major|major.minor|pwsh-alias> [-VirtualEnvironment <name>|-venv <name>] [pwsh arguments...]
 multi-pwsh doctor --repair-aliases
 ```
 
@@ -103,18 +109,88 @@ Native host mode:
 
 - `multi-pwsh host <selector> ...` runs PowerShell through native hosting (`pwsh-host` crate) instead of launching a `pwsh` subprocess.
 - `<selector>` supports `7`, `7.4`, `7.4.13`, or alias-form selectors such as `pwsh-7.4`.
+- `-VirtualEnvironment <name>` and `-venv <name>` are consumed by `multi-pwsh` before handing control to PowerShell and set `PSModulePath` to the selected venv root for that launch.
 - Alias lifecycle now maintains native host shims as hard links to `multi-pwsh` automatically during install/update/doctor alias repair.
 - On Windows, host shims are `pwsh-*.exe` files alongside `.cmd` wrappers in `MULTI_PWSH_BIN_DIR` (default: `~/.pwsh/bin`).
 - On Linux/macOS, alias command paths (`pwsh-*`) are hard links to `multi-pwsh`.
 - `multi-pwsh doctor --repair-aliases` performs a shim health check and re-links broken hard links automatically.
 - You can still manually copy/rename `multi-pwsh.exe` under `MULTI_PWSH_BIN_DIR` (default: `~/.pwsh/bin`) to an alias-like name (for example `pwsh-7.4.exe`); it automatically enters host mode and resolves the target installation from that alias name.
 - `-NamedPipeCommand <pipeName>` is supported in host mode (Windows only), matching `pwsh-host` behavior.
 
+### Virtual environments
+
+`multi-pwsh` virtual environments provide isolated PowerShell module roots. They are conceptually similar to Python virtual environments, but in this first version the isolation is implemented by selecting a venv-specific `PSModulePath` root for hosted launches.
+
+By default, venvs live under `~/.pwsh/venv/<name>`. If `MULTI_PWSH_VENV_DIR` is set, they live under that directory instead.
+
+Available commands:
+
+- `multi-pwsh venv create <name>` creates a named venv.
+- `multi-pwsh venv delete <name>` removes a named venv.
+- `multi-pwsh venv export <name> <archive.zip>` exports a named venv to a zip archive.
+- `multi-pwsh venv import <name> <archive.zip>` imports a named venv from a zip archive.
+- `multi-pwsh venv list` shows the configured venv root and all known venvs.
+
+#### Create and use a venv
+
+Create a venv and launch a hosted PowerShell session that uses it:
+
+```powershell
+multi-pwsh venv create msgraph
+multi-pwsh host 7.4 -venv msgraph -NoLogo -NoProfile
+```
+
+You can verify which module root is being used:
+
+```powershell
+multi-pwsh host 7.4 -venv msgraph -NoLogo -NoProfile -Command "$env:PSModulePath"
+```
+
+Both `-venv <name>` and `-VirtualEnvironment <name>` are supported.
+
+#### Populate a venv with modules
+
+Venvs are module discovery roots, so modules should live directly under `<venv-root>/<ModuleName>`.
+
+For the current implementation, the safest way to place modules into a venv is to save them directly into that venv root:
+
+```powershell
+$venvRoot = Join-Path $HOME ".pwsh/venv/msgraph"
+Save-Module -Name Microsoft.Graph.Authentication -Repository PSGallery -Path $venvRoot -Force
+Save-Module -Name Microsoft.Graph.Users -Repository PSGallery -Path $venvRoot -Force
+```
+
+Then use the venv when launching PowerShell:
+
+```powershell
+multi-pwsh host 7.4 -venv msgraph -NoLogo -NoProfile -Command "Get-Module -ListAvailable Microsoft.Graph.Authentication"
+```
+
+#### Export and import a venv
+
+You can package a venv as a zip archive and recreate it elsewhere:
+
+```powershell
+multi-pwsh venv export msgraph msgraph.zip
+multi-pwsh venv import msgraph-copy msgraph.zip
+multi-pwsh host 7.4 -venv msgraph-copy -NoLogo -NoProfile
+```
+
+Import is intentionally conservative: importing into an existing destination venv is rejected instead of merging archive contents.
+
+#### Current behavior and limitations
+
+- Venv selection changes module discovery and import precedence for hosted launches.
+- In this first version, `Install-Module` is not automatically redirected into the venv just because `-venv` is used.
+- PowerShell may still include some built-in or default module paths in the effective `PSModulePath`; the venv is intended to be the selected module root, not a perfect process-level sandbox.
+- The venv feature currently applies to `multi-pwsh host ...` and implicit host shims such as `pwsh-7.4.exe`, not to arbitrary external `pwsh` processes.
+
 Managed paths can be controlled with environment variables:
 
-- `MULTI_PWSH_HOME`: override the multi-pwsh home directory (default: `~/.pwsh`). Extracted PowerShell versions are stored under `MULTI_PWSH_HOME/multi`, and alias metadata is stored in `MULTI_PWSH_HOME/aliases.json`.
+- `MULTI_PWSH_HOME`: override the multi-pwsh home directory (default: `~/.pwsh`). Extracted PowerShell versions are stored under `MULTI_PWSH_HOME/multi`, virtual environments are stored under `MULTI_PWSH_HOME/venv` unless `MULTI_PWSH_VENV_DIR` is set, and alias metadata is stored in `MULTI_PWSH_HOME/aliases.json`.
 - `MULTI_PWSH_BIN_DIR`: override the shim and launcher directory (default: `MULTI_PWSH_HOME/bin`).
 - `MULTI_PWSH_CACHE_DIR`: override archive cache directory (default: `MULTI_PWSH_HOME/cache`).
+- `MULTI_PWSH_VENV_DIR`: override the virtual-environment root directory (default: `MULTI_PWSH_HOME/venv`).
 - `MULTI_PWSH_CACHE_KEEP`: keep downloaded archives after extraction when set to a truthy value (`1`, `true`, `yes`, or `on`).
 
 CI cache example:
@@ -123,6 +199,7 @@ CI cache example:
 $env:MULTI_PWSH_HOME = "$(Join-Path $HOME '.pwsh')"
 $env:MULTI_PWSH_BIN_DIR = "$(Join-Path $env:MULTI_PWSH_HOME 'bin')"
 $env:MULTI_PWSH_CACHE_DIR = "$(Join-Path $env:MULTI_PWSH_HOME 'cache')"
+$env:MULTI_PWSH_VENV_DIR = "$(Join-Path $env:MULTI_PWSH_HOME 'venv')"
 $env:MULTI_PWSH_CACHE_KEEP = "1"
 multi-pwsh install 7.4.x
 ```
@@ -140,7 +217,7 @@ For background on this approach, see [dotnet/runtime#46652: Native Host using ex
 
 Download the `pwsh-host-<os>-<arch>.zip` artifact for your platform from:
 
-- https://github.com/Devolutions/pwsh-host-rs/releases
+- https://github.com/Devolutions/multi-pwsh/releases
 
 Current artifact names:
 

crates/multi-pwsh/src/layout.rs

@@ -11,6 +11,7 @@ pub struct InstallLayout {
     home: PathBuf,
     bin_dir: PathBuf,
     cache_dir: PathBuf,
+    venvs_dir: PathBuf,
     os: HostOs,
 }
 
@@ -26,11 +27,15 @@ impl InstallLayout {
         let cache_dir = env::var_os("MULTI_PWSH_CACHE_DIR")
             .map(PathBuf::from)
             .unwrap_or_else(|| home.join("cache"));
+        let venvs_dir = env::var_os("MULTI_PWSH_VENV_DIR")
+            .map(PathBuf::from)
+            .unwrap_or_else(|| home.join("venv"));
 
         Ok(InstallLayout {
             home,
             bin_dir,
             cache_dir,
+            venvs_dir,
             os,
         })
     }
@@ -51,6 +56,14 @@ impl InstallLayout {
         self.cache_dir.clone()
     }
 
+    pub fn venvs_dir(&self) -> PathBuf {
+        self.venvs_dir.clone()
+    }
+
+    pub fn venv_dir(&self, name: &str) -> PathBuf {
+        self.venvs_dir().join(name)
+    }
+
     pub fn versions_dir(&self) -> PathBuf {
         self.home.join("multi")
     }
@@ -106,6 +119,7 @@ impl InstallLayout {
         fs::create_dir_all(&self.home)?;
         fs::create_dir_all(self.bin_dir())?;
         fs::create_dir_all(self.cache_dir())?;
+        fs::create_dir_all(self.venvs_dir())?;
         fs::create_dir_all(self.versions_dir())?;
         Ok(())
     }
@@ -119,7 +133,7 @@ impl InstallLayout {
         collect_versions_from_dir(&self.versions_dir(), &[], self.executable_name(), &mut versions)?;
         collect_versions_from_dir(
             self.home(),
-            &["bin", "cache", "multi"],
+            &["bin", "cache", "multi", "venv"],
             self.executable_name(),
             &mut versions,
         )?;
@@ -197,13 +211,16 @@ mod tests {
         home: Option<&Path>,
         bin_dir: Option<&Path>,
         cache_dir: Option<&Path>,
+        venv_dir: Option<&Path>,
         action: impl FnOnce() -> T,
     ) -> T {
         let _guard = ENV_LOCK.lock().unwrap();
 
         with_env_var("MULTI_PWSH_HOME", home, || {
             with_env_var("MULTI_PWSH_BIN_DIR", bin_dir, || {
-                with_env_var("MULTI_PWSH_CACHE_DIR", cache_dir, action)
+                with_env_var("MULTI_PWSH_CACHE_DIR", cache_dir, || {
+                    with_env_var("MULTI_PWSH_VENV_DIR", venv_dir, action)
+                })
             })
         })
     }
@@ -213,11 +230,13 @@ mod tests {
         let temp_dir = TempDir::new().unwrap();
         let expected_home = temp_dir.path().join("pwsh-home");
 
-        with_layout_env(Some(&expected_home), None, None, || {
+        with_layout_env(Some(&expected_home), None, None, None, || {
             let layout = InstallLayout::new(HostOs::Windows).unwrap();
             assert_eq!(layout.home(), expected_home.as_path());
             assert_eq!(layout.bin_dir(), expected_home.join("bin"));
             assert_eq!(layout.cache_dir(), expected_home.join("cache"));
+            assert_eq!(layout.venvs_dir(), expected_home.join("venv"));
+            assert_eq!(layout.venv_dir("msgraph"), expected_home.join("venv").join("msgraph"));
             assert_eq!(layout.versions_dir(), expected_home.join("multi"));
             assert_eq!(layout.aliases_file(), expected_home.join("aliases.json"));
         });
@@ -230,11 +249,33 @@ mod tests {
         let expected_bin = temp_dir.path().join("shims");
         let expected_cache = temp_dir.path().join("cache-root");
 
-        with_layout_env(Some(&expected_home), Some(&expected_bin), Some(&expected_cache), || {
+        with_layout_env(
+            Some(&expected_home),
+            Some(&expected_bin),
+            Some(&expected_cache),
+            None,
+            || {
+                let layout = InstallLayout::new(HostOs::Linux).unwrap();
+                assert_eq!(layout.home(), expected_home.as_path());
+                assert_eq!(layout.bin_dir(), expected_bin);
+                assert_eq!(layout.cache_dir(), expected_cache);
+                assert_eq!(layout.venvs_dir(), expected_home.join("venv"));
+                assert_eq!(layout.versions_dir(), expected_home.join("multi"));
+            },
+        );
+    }
+
+    #[test]
+    fn layout_uses_explicit_venv_override() {
+        let temp_dir = TempDir::new().unwrap();
+        let expected_home = temp_dir.path().join("pwsh-home");
+        let expected_venv = temp_dir.path().join("venvs-root");
+
+        with_layout_env(Some(&expected_home), None, None, Some(&expected_venv), || {
             let layout = InstallLayout::new(HostOs::Linux).unwrap();
             assert_eq!(layout.home(), expected_home.as_path());
-            assert_eq!(layout.bin_dir(), expected_bin);
-            assert_eq!(layout.cache_dir(), expected_cache);
+            assert_eq!(layout.venvs_dir(), expected_venv);
+            assert_eq!(layout.venv_dir("msgraph"), expected_venv.join("msgraph"));
             assert_eq!(layout.versions_dir(), expected_home.join("multi"));
         });
     }
@@ -247,7 +288,7 @@ mod tests {
         let legacy_dir = expected_home.join(version.to_string());
         fs::create_dir_all(&legacy_dir).unwrap();
 
-        with_layout_env(Some(&expected_home), None, None, || {
+        with_layout_env(Some(&expected_home), None, None, None, || {
             let layout = InstallLayout::new(HostOs::Linux).unwrap();
             assert_eq!(layout.version_dir(&version), legacy_dir);
             assert_eq!(
@@ -271,7 +312,7 @@ mod tests {
         fs::write(new_dir.join("pwsh"), "").unwrap();
         fs::write(legacy_dir.join("pwsh"), "").unwrap();
 
-        with_layout_env(Some(&expected_home), None, None, || {
+        with_layout_env(Some(&expected_home), None, None, None, || {
             let layout = InstallLayout::new(HostOs::Linux).unwrap();
             assert_eq!(layout.installed_versions().unwrap(), vec![new_version, legacy_version]);
         });