Add bundled pwsh sample

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: mamoreau-devolutions

README.md

@@ -152,6 +152,7 @@ Native host mode:
 - 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.
+- A `.NET 10` bundled-host sample that publishes the packaged `pwsh.exe` from the `PowerShell` NuGet payload alongside `pwsh.dll` lives under `dotnet\samples\BundledPwshHost\README.md`.
 - `-NamedPipeCommand <pipeName>` is supported in host mode (Windows only), matching `pwsh-host` behavior.
 
 ### Virtual environments

crates/multi-pwsh/src/main.rs

@@ -33,6 +33,7 @@ const POWERSHELL_UPDATECHECK_ENV_VAR: &str = "POWERSHELL_UPDATECHECK";
 const POWERSHELL_UPDATECHECK_OFF: &str = "Off";
 const VIRTUAL_ENVIRONMENT_FLAG: &str = "-virtualenvironment";
 const VIRTUAL_ENVIRONMENT_SHORT_FLAG: &str = "-venv";
+const BUNDLED_PWSH_HOME_ENV_VAR: &str = "MULTI_PWSH_BUNDLED_PWSH_HOME";
 
 fn print_usage() {
     eprintln!(
@@ -525,6 +526,29 @@ fn run_host_mode(selector_input: &str, pwsh_args: Vec<OsString>) -> Result<i32>
     layout.ensure_base_dirs()?;
 
     let (_version, executable) = resolve_host_executable(&layout, selector_input)?;
+    let pwsh_dir = executable.parent().ok_or_else(|| {
+        MultiPwshError::InvalidArguments(format!(
+            "resolved host selector '{}' to {}, but executable has no parent directory",
+            selector_input,
+            executable.display()
+        ))
+    })?;
+    run_host_for_pwsh_dir(
+        &layout,
+        os,
+        pwsh_dir,
+        pwsh_args,
+        format!("selector '{}'", selector_input),
+    )
+}
+
+fn run_host_for_pwsh_dir(
+    layout: &InstallLayout,
+    os: HostOs,
+    pwsh_dir: &Path,
+    pwsh_args: Vec<OsString>,
+    failure_context: String,
+) -> Result<i32> {
     let HostLaunchOptions {
         pwsh_args,
         virtual_environment,
@@ -543,10 +567,10 @@ fn run_host_mode(selector_input: &str, pwsh_args: Vec<OsString>) -> Result<i32>
         .map(|venv_dir| configure_virtual_environment_host_env(os, &venv_dir))
         .transpose()?;
 
-    pwsh_host::run_pwsh_command_line_for_pwsh_exe(&executable, pwsh_args).map_err(|error| {
+    pwsh_host::run_pwsh_command_line_for_pwsh_dir(pwsh_dir, pwsh_args).map_err(|error| {
         MultiPwshError::Host(format!(
-            "failed to start native host for selector '{}': {}",
-            selector_input, error
+            "failed to start native host for {}: {}",
+            failure_context, error
         ))
     })
 }
@@ -597,8 +621,61 @@ fn detect_implicit_host_selector(bin_dir: &Path, executable_path: &Path) -> Opti
     Some(selector)
 }
 
+fn resolve_bundled_pwsh_home(executable_path: &Path, configured_home: &Path) -> Option<PathBuf> {
+    let candidate = if configured_home.is_absolute() {
+        configured_home.to_path_buf()
+    } else {
+        executable_path.parent()?.join(configured_home)
+    };
+
+    if is_bundled_pwsh_home(&candidate) {
+        Some(candidate)
+    } else {
+        None
+    }
+}
+
+fn is_bundled_pwsh_home(path: &Path) -> bool {
+    path.join("pwsh.dll").is_file()
+        && (path.join("pwsh.deps.json").is_file() || path.join("pwsh.runtimeconfig.json").is_file())
+}
+
+fn detect_bundled_pwsh_home(executable_path: &Path) -> Option<PathBuf> {
+    let selector_name = executable_selector_name(executable_path)?;
+    if !selector_name.eq_ignore_ascii_case("pwsh") {
+        return None;
+    }
+
+    if let Some(configured_home) = env::var_os(BUNDLED_PWSH_HOME_ENV_VAR) {
+        return resolve_bundled_pwsh_home(executable_path, Path::new(&configured_home));
+    }
+
+    let parent = executable_path.parent()?;
+    if is_bundled_pwsh_home(parent) {
+        Some(parent.to_path_buf())
+    } else {
+        None
+    }
+}
+
 fn run_implicit_host_mode_if_needed() -> Result<Option<i32>> {
     let executable_path = env::current_exe()?;
+    let args: Vec<OsString> = env::args_os().skip(1).collect();
+
+    if let Some(bundled_pwsh_home) = detect_bundled_pwsh_home(&executable_path) {
+        let os = HostOs::detect()?;
+        let layout = InstallLayout::new(os)?;
+        layout.ensure_base_dirs()?;
+
+        let exit_code = run_host_for_pwsh_dir(
+            &layout,
+            os,
+            &bundled_pwsh_home,
+            args,
+            format!("bundled pwsh home '{}'", bundled_pwsh_home.display()),
+        )?;
+        return Ok(Some(exit_code));
+    }
 
     let selector_name = match executable_selector_name(&executable_path) {
         Some(selector_name) => selector_name,
@@ -616,7 +693,6 @@ fn run_implicit_host_mode_if_needed() -> Result<Option<i32>> {
         return Ok(None);
     };
 
-    let args: Vec<OsString> = env::args_os().skip(1).collect();
     let exit_code = run_host_mode(&selector, args)?;
     Ok(Some(exit_code))
 }
@@ -1581,6 +1657,51 @@ mod tests {
         assert!(selector.is_none());
     }
 
+    #[test]
+    fn is_bundled_pwsh_home_requires_pwsh_dll_and_manifest() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        fs::write(temp_dir.path().join("pwsh.dll"), []).unwrap();
+        assert!(!is_bundled_pwsh_home(temp_dir.path()));
+
+        fs::write(temp_dir.path().join("pwsh.runtimeconfig.json"), "{}").unwrap();
+        assert!(is_bundled_pwsh_home(temp_dir.path()));
+    }
+
+    #[test]
+    fn detect_bundled_pwsh_home_accepts_pwsh_name_with_sibling_payload() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        fs::write(temp_dir.path().join("pwsh.dll"), []).unwrap();
+        fs::write(temp_dir.path().join("pwsh.deps.json"), "{}").unwrap();
+
+        let bundled_home = detect_bundled_pwsh_home(&temp_dir.path().join("pwsh.exe"));
+        assert_eq!(bundled_home, Some(temp_dir.path().to_path_buf()));
+    }
+
+    #[test]
+    fn detect_bundled_pwsh_home_rejects_non_pwsh_name() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        fs::write(temp_dir.path().join("pwsh.dll"), []).unwrap();
+        fs::write(temp_dir.path().join("pwsh.deps.json"), "{}").unwrap();
+
+        let bundled_home = detect_bundled_pwsh_home(&temp_dir.path().join("multi-pwsh.exe"));
+        assert!(bundled_home.is_none());
+    }
+
+    #[test]
+    fn detect_bundled_pwsh_home_supports_relative_env_override() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let payload_dir = temp_dir.path().join("payload");
+        fs::create_dir_all(&payload_dir).unwrap();
+        fs::write(payload_dir.join("pwsh.dll"), []).unwrap();
+        fs::write(payload_dir.join("pwsh.runtimeconfig.json"), "{}").unwrap();
+
+        let bundled_home = with_env_var(BUNDLED_PWSH_HOME_ENV_VAR, Some("payload"), || {
+            detect_bundled_pwsh_home(&temp_dir.path().join("pwsh.exe"))
+        });
+
+        assert_eq!(bundled_home, Some(payload_dir));
+    }
+
     #[test]
     fn parse_release_selection_options_accepts_prerelease() {
         let args = vec!["--include-prerelease".to_string()];

dotnet/samples/BundledPwshHost/BundledPwshHost.csproj

@@ -0,0 +1,78 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0;net10.0-windows</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <SelfContained>true</SelfContained>
+    <PublishSingleFile>false</PublishSingleFile>
+    <PublishTrimmed>false</PublishTrimmed>
+    <UseAppHost>true</UseAppHost>
+    <BundledPwshSdkVersion>7.4.0</BundledPwshSdkVersion>
+    <BundledPwshLayoutToolProject>$(MSBuildThisFileDirectory)tools\BundlePwshLayout\BundlePwshLayout.csproj</BundledPwshLayoutToolProject>
+    <BundledPwshDotNetRoot Condition="'$(BundledPwshDotNetRoot)' == '' and '$(DOTNET_ROOT)' != ''">$(DOTNET_ROOT)</BundledPwshDotNetRoot>
+    <BundledPwshDotNetRoot Condition="'$(BundledPwshDotNetRoot)' == '' and '$(OS)' == 'Windows_NT'">$(ProgramFiles)\dotnet</BundledPwshDotNetRoot>
+  </PropertyGroup>
+
+  <PropertyGroup Condition="'$(TargetFramework)' == 'net10.0-windows'">
+    <UseWindowsForms>true</UseWindowsForms>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Remove="tools\**\*.cs" />
+    <PackageReference Include="Microsoft.PowerShell.SDK" Version="$(BundledPwshSdkVersion)" />
+    <PackageReference Include="PowerShell"
+                      Version="$(BundledPwshSdkVersion)"
+                      GeneratePathProperty="true"
+                      ExcludeAssets="all"
+                      PrivateAssets="all" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <BundledPwshTargetPlatform Condition="$([System.String]::Copy('$(RuntimeIdentifier)').StartsWith('win'))">win</BundledPwshTargetPlatform>
+    <BundledPwshTargetPlatform Condition="'$(BundledPwshTargetPlatform)' == '' and ($([System.String]::Copy('$(RuntimeIdentifier)').StartsWith('linux')) or $([System.String]::Copy('$(RuntimeIdentifier)').StartsWith('osx')))">unix</BundledPwshTargetPlatform>
+    <BundledPwshPackageRoot Condition="'$(BundledPwshTargetPlatform)' != ''">$(PkgPowerShell)\tools\net8.0\any\$(BundledPwshTargetPlatform)</BundledPwshPackageRoot>
+  </PropertyGroup>
+
+  <Target Name="ValidateBundledPwshPublish" BeforeTargets="Publish">
+    <Error Condition="'$(RuntimeIdentifier)' == ''"
+           Text="BundledPwshHost requires a RuntimeIdentifier. Example: dotnet publish -c Release -f net10.0-windows -r win-x64" />
+    <Error Condition="'$(BundledPwshTargetPlatform)' == ''"
+           Text="Unsupported RuntimeIdentifier '$(RuntimeIdentifier)'. Use a win-*, linux-*, or osx-* RID." />
+    <Error Condition="'$(BundledPwshTargetPlatform)' == 'win' and '$(TargetFramework)' != 'net10.0-windows'"
+           Text="Windows bundled publish requires -f net10.0-windows." />
+    <Error Condition="'$(BundledPwshTargetPlatform)' != 'win' and '$(TargetFramework)' != 'net10.0'"
+           Text="Non-Windows bundled publish requires -f net10.0." />
+    <Error Condition="!Exists('$(BundledPwshPackageRoot)\pwsh.dll')"
+           Text="PowerShell payload root was not found at $(BundledPwshPackageRoot)." />
+    <Error Condition="!Exists('$(BundledPwshPackageRoot)\pwsh.exe') and '$(BundledPwshTargetPlatform)' == 'win'"
+           Text="PowerShell package payload does not include pwsh.exe at $(BundledPwshPackageRoot)." />
+    <Error Condition="!Exists('$(BundledPwshPackageRoot)\pwsh') and '$(BundledPwshTargetPlatform)' != 'win'"
+           Text="PowerShell package payload does not include pwsh at $(BundledPwshPackageRoot)." />
+    <Error Condition="!Exists('$(BundledPwshLayoutToolProject)')"
+           Text="Bundled pwsh layout tool was not found at $(BundledPwshLayoutToolProject)." />
+    <Error Condition="'$(BundledPwshDotNetRoot)' == ''"
+           Text="Unable to resolve the local dotnet root. Set BundledPwshDotNetRoot or DOTNET_ROOT before publishing." />
+  </Target>
+
+  <Target Name="BundlePowerShellPayload" AfterTargets="Publish">
+    <ItemGroup>
+      <BundledPwshPayload Include="$(BundledPwshPackageRoot)\**\*" />
+      <BundledPwshMissingPayload Include="@(BundledPwshPayload)"
+                                Condition="!Exists('$(PublishDir)%(BundledPwshPayload.RecursiveDir)%(BundledPwshPayload.Filename)%(BundledPwshPayload.Extension)')" />
+    </ItemGroup>
+
+    <Copy SourceFiles="@(BundledPwshMissingPayload)"
+          DestinationFiles="@(BundledPwshMissingPayload -> '$(PublishDir)%(RecursiveDir)%(Filename)%(Extension)')"
+          SkipUnchangedFiles="true" />
+  </Target>
+
+  <Target Name="PrepareBundledPwshRuntime" AfterTargets="BundlePowerShellPayload">
+    <PropertyGroup>
+      <BundledPwshPublishDirNoSlash>$([System.String]::Copy('$(PublishDir)').TrimEnd('\'))</BundledPwshPublishDirNoSlash>
+    </PropertyGroup>
+    <Exec Command="dotnet run --project &quot;$(BundledPwshLayoutToolProject)&quot; -- &quot;$(BundledPwshPublishDirNoSlash)&quot; &quot;$(PublishDir)BundledPwshHost.runtimeconfig.json&quot; &quot;$(PublishDir)pwsh.runtimeconfig.json&quot; &quot;$(BundledPwshDotNetRoot)&quot;"
+          WorkingDirectory="$(MSBuildThisFileDirectory)" />
+  </Target>
+</Project>

dotnet/samples/BundledPwshHost/Program.cs

@@ -0,0 +1,33 @@
+using System.Management.Automation;
+
+namespace BundledPwshHost;
+
+internal static class Program
+{
+    private static int Main()
+    {
+        using PowerShell powerShell = PowerShell.Create();
+        powerShell.AddScript("$PSVersionTable | Select-Object PSVersion, PSEdition | ConvertTo-Json -Compress");
+
+        var results = powerShell.Invoke();
+        if (powerShell.HadErrors)
+        {
+            foreach (ErrorRecord error in powerShell.Streams.Error)
+            {
+                Console.Error.WriteLine(error);
+            }
+
+            return 1;
+        }
+
+        Console.WriteLine("Managed PowerShell SDK invocation:");
+        foreach (PSObject result in results)
+        {
+            Console.WriteLine(result.BaseObject);
+        }
+
+        Console.WriteLine($"Base directory: {AppContext.BaseDirectory}");
+        Console.WriteLine("Publish this project with a RID to assemble a bundled pwsh payload.");
+        return 0;
+    }
+}

dotnet/samples/BundledPwshHost/README.md

@@ -0,0 +1,56 @@
+# BundledPwshHost
+
+This sample shows how to:
+
+- target `.NET 10`;
+- reference `Microsoft.PowerShell.SDK` from managed code;
+- publish a merged PowerShell-style output;
+- use the `pwsh.exe` shipped in the `PowerShell` NuGet package;
+- boot `pwsh.dll` from the publish directory without depending on a separately installed PowerShell.
+
+## What the publish step does
+
+`dotnet publish` for this sample:
+
+1. publishes the sample app as a self-contained `.NET 10` app;
+2. overlays the `PowerShell` NuGet package payload (`pwsh.exe`, `pwsh.dll`, `pwsh.deps.json`, modules, and related files);
+4. rewrites `pwsh.runtimeconfig.json` to the local `.NET 10` shared framework version;
+5. copies the matching shared runtime folders from the local dotnet installation into `publish\shared\...`.
+
+The bundled `pwsh.exe` is the official apphost that ships inside the `PowerShell` NuGet package payload. The sample keeps that executable and adjusts the runtime layout around it so it can start against the local `.NET 10` runtime copied into the publish output.
+
+The package versions are intentionally linked: the `PowerShell` payload package reuses the same version property as `Microsoft.PowerShell.SDK` (`BundledPwshSdkVersion`), so changing the SDK version automatically changes the imported `pwsh.exe` / `pwsh.dll` payload version too.
+
+## Prerequisites
+
+Publish the sample from this directory so the local `global.json` selects `.NET 10`:
+
+```powershell
+dotnet publish -c Release -f net10.0-windows -r win-x64
+```
+
+## Validate the output
+
+Run the managed sample app:
+
+```powershell
+.\bin\Release\net10.0-windows\win-x64\publish\BundledPwshHost.exe
+```
+
+Run the bundled PowerShell host:
+
+```powershell
+.\bin\Release\net10.0-windows\win-x64\publish\pwsh.exe -NoLogo -NoProfile -Command '$PSHOME; [System.Runtime.InteropServices.RuntimeInformation]::FrameworkDescription'
+```
+
+On a successful run:
+
+- `BundledPwshHost.exe` shows a PowerShell SDK invocation result;
+- `pwsh.exe` reports the sample publish directory as `$PSHOME`;
+- `pwsh.exe` reports the local `.NET 10` runtime version from the bundled layout.
+
+## Current notes
+
+- The payload selection logic is RID-aware (`win` / `unix`), but the validated path in this repository session is `win-x64`.
+- The PowerShell packages currently emit `NU1903` vulnerability warnings for transitive dependencies during publish. The sample does not suppress them.
+- This sample is a proof of concept for local hosting layout. It intentionally favors clarity and reproducibility over minimal output size.

dotnet/samples/BundledPwshHost/global.json

@@ -0,0 +1,7 @@
+{
+  "sdk": {
+    "version": "10.0.103",
+    "allowPrerelease": false,
+    "rollForward": "latestPatch"
+  }
+}

dotnet/samples/BundledPwshHost/tools/BundlePwshLayout/BundlePwshLayout.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="Program.cs" />
+  </ItemGroup>
+</Project>