Add version check, update --self extraction, tests, and README docs

- Version marker file (.aspire-bundle-version) written after extraction;
  EnsureBundleAsync and SetupCommand skip extraction when version matches
- update --self proactively extracts embedded payload after replacing binary
- 10 unit tests for BundleTrailer: roundtrip, payload slicing, version
  marker, and tar.gz extraction with strip-components
- README documents self-extracting binary install path

Author: davidfowl

eng/scripts/README.md

@@ -303,10 +303,38 @@ Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Aspire"
 
 ### Bundle vs CLI-Only
 
-| Feature | CLI-Only Scripts | Bundle Scripts |
-|---------|-----------------|----------------|
-| Requires .NET SDK | Yes | No |
-| Package size | ~25 MB | ~200 MB compressed |
-| Polyglot support | Partial | Full |
-| Components included | CLI only | CLI, Runtime, Dashboard, DCP |
-| Use case | .NET developers | TypeScript, Python, Go developers |
+| Feature | CLI-Only Scripts | Bundle Scripts | Self-Extracting Binary |
+|---------|-----------------|----------------|----------------------|
+| Requires .NET SDK | Yes | No | No |
+| Package size | ~25 MB | ~200 MB compressed | ~210 MB (single file) |
+| Polyglot support | Partial | Full | Full |
+| Components included | CLI only | CLI, Runtime, Dashboard, DCP | CLI, Runtime, Dashboard, DCP |
+| Installation steps | Download + PATH | Download + extract + PATH | Download + `aspire setup` |
+| Use case | .NET developers | TypeScript, Python, Go developers | Simplest install path |
+
+### Self-Extracting Binary
+
+The Aspire CLI can also be distributed as a self-extracting binary that embeds the full bundle
+payload inside the native AOT executable. This is the simplest installation method:
+
+```bash
+# Linux/macOS - download and extract
+mkdir -p ~/.aspire/bin
+curl -fsSL <url>/aspire -o ~/.aspire/bin/aspire
+chmod +x ~/.aspire/bin/aspire
+~/.aspire/bin/aspire setup
+
+# Add to PATH
+export PATH="$HOME/.aspire/bin:$PATH"
+```
+
+```powershell
+# Windows - download and extract
+New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Aspire\bin"
+Invoke-WebRequest -Uri <url>/aspire.exe -OutFile "$env:LOCALAPPDATA\Aspire\bin\aspire.exe"
+& "$env:LOCALAPPDATA\Aspire\bin\aspire.exe" setup
+```
+
+The `aspire setup` command extracts the embedded payload to the parent directory of the CLI binary.
+Alternatively, extraction happens lazily on the first command that needs the bundle layout
+(e.g., `aspire run` with a polyglot project).

src/Aspire.Cli/Commands/SetupCommand.cs

@@ -80,11 +80,15 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, Cancell
             return ExitCodeConstants.FailedToBuildArtifacts;
         }
 
-        // Check if layout already exists
+        // Check if layout already exists with matching version
         if (!force && _layoutDiscovery.DiscoverLayout() is not null)
         {
-            InteractionService.DisplayMessage(":white_check_mark:", "Bundle is already extracted. Use --force to re-extract.");
-            return ExitCodeConstants.Success;
+            var existingHash = BundleTrailer.ReadVersionMarker(installPath);
+            if (existingHash == trailer.VersionHash)
+            {
+                InteractionService.DisplayMessage(":white_check_mark:", "Bundle is already extracted and up to date. Use --force to re-extract.");
+                return ExitCodeConstants.Success;
+            }
         }
 
         // Extract with spinner
@@ -93,6 +97,7 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, Cancell
             async () =>
             {
                 await AppHostServerProjectFactory.ExtractPayloadAsync(processPath, trailer, installPath, cancellationToken);
+                BundleTrailer.WriteVersionMarker(installPath, trailer.VersionHash);
                 return ExitCodeConstants.Success;
             });
 

src/Aspire.Cli/Commands/UpdateCommand.cs

@@ -16,6 +16,7 @@
 using Aspire.Cli.Resources;
 using Aspire.Cli.Telemetry;
 using Aspire.Cli.Utils;
+using Aspire.Shared;
 using Microsoft.Extensions.Logging;
 using Spectre.Console;
 
@@ -485,6 +486,17 @@ private async Task ExtractAndUpdateAsync(string archivePath, CancellationToken c
                 // If we get here, the update was successful, clean up old backups
                 CleanupOldBackupFiles(targetExePath);
 
+                // If the new binary is a self-extracting bundle, proactively extract it
+                // so the user doesn't have to wait on next run
+                var trailer = BundleTrailer.TryRead(targetExePath);
+                if (trailer is not null)
+                {
+                    InteractionService.DisplayMessage("package", "Extracting embedded bundle...");
+                    var extractDir = Path.GetDirectoryName(installDir) ?? installDir;
+                    await AppHostServerProjectFactory.ExtractPayloadAsync(targetExePath, trailer, extractDir, cancellationToken);
+                    BundleTrailer.WriteVersionMarker(extractDir, trailer.VersionHash);
+                }
+
                 // Display helpful message about PATH
                 if (!IsInPath(installDir))
                 {

src/Aspire.Cli/Projects/AppHostServerProject.cs

@@ -103,12 +103,6 @@ public async Task<IAppHostServerProject> CreateAsync(string appPath, Cancellatio
     /// </summary>
     private async Task EnsureBundleAsync(CancellationToken cancellationToken)
     {
-        // If a layout already exists, nothing to do
-        if (layoutDiscovery.DiscoverLayout() is not null)
-        {
-            return;
-        }
-
         // Check if the current process has an embedded bundle payload
         var processPath = Environment.ProcessPath;
         if (string.IsNullOrEmpty(processPath))
@@ -122,7 +116,7 @@ private async Task EnsureBundleAsync(CancellationToken cancellationToken)
             return; // No embedded payload (dev build or already-extracted CLI)
         }
 
-        // Extract to the parent directory of the CLI binary's directory.
+        // Determine extraction directory: parent of the CLI binary's directory.
         // If CLI is at ~/.aspire/bin/aspire, extract to ~/.aspire/ so layout discovery
         // finds components via the bin/ layout pattern ({layout}/bin/aspire + {layout}/runtime/).
         var cliDir = Path.GetDirectoryName(processPath);
@@ -132,11 +126,25 @@ private async Task EnsureBundleAsync(CancellationToken cancellationToken)
         }
 
         var extractDir = Path.GetDirectoryName(cliDir) ?? cliDir;
+
+        // If layout exists and version matches, skip extraction
+        if (layoutDiscovery.DiscoverLayout() is not null)
+        {
+            var existingHash = BundleTrailer.ReadVersionMarker(extractDir);
+            if (existingHash == trailer.VersionHash)
+            {
+                return; // Already extracted with matching version
+            }
+        }
+
         var logger = loggerFactory.CreateLogger<AppHostServerProjectFactory>();
         logger.LogInformation("Extracting embedded bundle to {Path}...", extractDir);
 
         await ExtractPayloadAsync(processPath, trailer, extractDir, cancellationToken);
 
+        // Write version marker so subsequent runs skip extraction
+        BundleTrailer.WriteVersionMarker(extractDir, trailer.VersionHash);
+
         // Verify extraction succeeded
         if (layoutDiscovery.DiscoverLayout() is null)
         {

src/Shared/BundleTrailer.cs

@@ -114,6 +114,36 @@ public static Stream OpenPayload(string filePath, BundleTrailerInfo trailer)
         return new SubStream(stream, (long)trailer.PayloadSize, ownsStream: true);
     }
 
+    /// <summary>
+    /// Name of the marker file written after successful extraction.
+    /// </summary>
+    public const string VersionMarkerFileName = ".aspire-bundle-version";
+
+    /// <summary>
+    /// Writes a version marker file to the extraction directory.
+    /// </summary>
+    public static void WriteVersionMarker(string extractDir, ulong versionHash)
+    {
+        var markerPath = Path.Combine(extractDir, VersionMarkerFileName);
+        File.WriteAllText(markerPath, versionHash.ToString("X16", System.Globalization.CultureInfo.InvariantCulture));
+    }
+
+    /// <summary>
+    /// Reads the version hash from a previously written marker file.
+    /// Returns null if the marker doesn't exist or is invalid.
+    /// </summary>
+    public static ulong? ReadVersionMarker(string extractDir)
+    {
+        var markerPath = Path.Combine(extractDir, VersionMarkerFileName);
+        if (!File.Exists(markerPath))
+        {
+            return null;
+        }
+
+        var content = File.ReadAllText(markerPath).Trim();
+        return ulong.TryParse(content, System.Globalization.NumberStyles.HexNumber, null, out var hash) ? hash : null;
+    }
+
     /// <summary>
     /// A stream wrapper that exposes a fixed-length window of an underlying stream.
     /// </summary>