Self-extracting bundle: trailer format, lazy extraction, setup command, build integration

- Add BundleTrailer (src/Shared/) with read/write/extract helpers for the
  32-byte trailer appended to native AOT CLI binaries
- Change IAppHostServerProjectFactory.Create() → CreateAsync() and update
  all 8 call sites (GuestAppHostProject, SdkGenerateCommand, SdkDumpCommand,
  ScaffoldingService, AppHostServerSession)
- Add EnsureBundleAsync in AppHostServerProjectFactory that lazily extracts
  the embedded tar.gz payload on first polyglot command (run/publish/add)
- Add 'aspire setup' command for explicit extraction with --install-path
  and --force options
- Add --embed-in-cli option to CreateLayout tool that appends tar.gz
  payload + trailer to the native CLI binary
- Update Bundle.proj to pass --embed-in-cli pointing to the layout CLI binary

Author: davidfowl

eng/Bundle.proj

@@ -118,7 +118,13 @@
       <!-- Remove trailing slashes for command line arguments -->
       <_BundleOutputDirArg>$(BundleOutputDir.TrimEnd('\').TrimEnd('/'))</_BundleOutputDirArg>
       <_ArtifactsDirArg>$(ArtifactsDir.TrimEnd('\').TrimEnd('/'))</_ArtifactsDirArg>
-      <_CreateLayoutArgs>--output "$(_BundleOutputDirArg)" --artifacts "$(_ArtifactsDirArg)" --rid $(TargetRid) --bundle-version $(BundleVersion) --runtime-version $(BundleRuntimeVersion) --archive --verbose --download-runtime</_CreateLayoutArgs>
+      
+      <!-- Determine CLI executable name and path for self-extracting bundle -->
+      <_CliExeName Condition="$(TargetRid.StartsWith('win'))">aspire.exe</_CliExeName>
+      <_CliExeName Condition="!$(TargetRid.StartsWith('win'))">aspire</_CliExeName>
+      <_CliOutputPath>$(_BundleOutputDirArg)$([System.IO.Path]::DirectorySeparatorChar)$(_CliExeName)</_CliOutputPath>
+      
+      <_CreateLayoutArgs>--output "$(_BundleOutputDirArg)" --artifacts "$(_ArtifactsDirArg)" --rid $(TargetRid) --bundle-version $(BundleVersion) --runtime-version $(BundleRuntimeVersion) --archive --verbose --download-runtime --embed-in-cli "$(_CliOutputPath)"</_CreateLayoutArgs>
     </PropertyGroup>
 
     <Message Importance="high" Text="Creating bundle layout..." />

src/Aspire.Cli/Aspire.Cli.csproj

@@ -53,6 +53,7 @@
 
   <ItemGroup>
     <Compile Include="$(SharedDir)BundleDiscovery.cs" Link="Layout\BundleDiscovery.cs" />
+    <Compile Include="$(SharedDir)BundleTrailer.cs" Link="Layout\BundleTrailer.cs" />
     <Compile Include="$(SharedDir)KnownConfigNames.cs" Link="Utils\KnownConfigNames.cs" />
     <Compile Include="$(SharedDir)PathNormalizer.cs" Link="Utils\PathNormalizer.cs" />
     <Compile Include="$(SharedDir)CircularBuffer.cs" Link="Utils\CircularBuffer.cs" />

src/Aspire.Cli/Commands/RootCommand.cs

@@ -128,6 +128,7 @@ public RootCommand(
         TelemetryCommand telemetryCommand,
         DocsCommand docsCommand,
         SdkCommand sdkCommand,
+        SetupCommand setupCommand,
         ExtensionInternalCommand extensionInternalCommand,
         IFeatures featureFlags,
         IInteractionService interactionService)
@@ -205,6 +206,7 @@ public RootCommand(
         Subcommands.Add(agentCommand);
         Subcommands.Add(telemetryCommand);
         Subcommands.Add(docsCommand);
+        Subcommands.Add(setupCommand);
 
         if (featureFlags.IsFeatureEnabled(KnownFeatures.ExecCommandEnabled, false))
         {

src/Aspire.Cli/Commands/Sdk/SdkDumpCommand.cs

@@ -124,7 +124,7 @@ private async Task<int> DumpCapabilitiesAsync(
             // TODO: Support bundle mode by using DLL references instead of project references.
             // In bundle mode, we'd need to add integration DLLs to the probing path rather than
             // using additionalProjectReferences. For now, SDK dump only works with .NET SDK.
-            var appHostServerProjectInterface = _appHostServerProjectFactory.Create(tempDir);
+            var appHostServerProjectInterface = await _appHostServerProjectFactory.CreateAsync(tempDir, cancellationToken);
             if (appHostServerProjectInterface is not DotNetBasedAppHostServerProject appHostServerProject)
             {
                 InteractionService.DisplayError("SDK dump is only available with .NET SDK installed.");

src/Aspire.Cli/Commands/Sdk/SdkGenerateCommand.cs

@@ -123,7 +123,7 @@ private async Task<int> GenerateSdkAsync(
             // TODO: Support bundle mode by using DLL references instead of project references.
             // In bundle mode, we'd need to add integration DLLs to the probing path rather than
             // using additionalProjectReferences. For now, SDK generation only works with .NET SDK.
-            var appHostServerProjectInterface = _appHostServerProjectFactory.Create(tempDir);
+            var appHostServerProjectInterface = await _appHostServerProjectFactory.CreateAsync(tempDir, cancellationToken);
             if (appHostServerProjectInterface is not DotNetBasedAppHostServerProject appHostServerProject)
             {
                 InteractionService.DisplayError("SDK generation is only available with .NET SDK installed.");

src/Aspire.Cli/Commands/SetupCommand.cs

@@ -0,0 +1,111 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.CommandLine;
+using Aspire.Cli.Configuration;
+using Aspire.Cli.Interaction;
+using Aspire.Cli.Layout;
+using Aspire.Cli.Projects;
+using Aspire.Cli.Telemetry;
+using Aspire.Cli.Utils;
+using Aspire.Shared;
+using Microsoft.Extensions.Logging;
+
+namespace Aspire.Cli.Commands;
+
+/// <summary>
+/// Extracts the embedded bundle payload from a self-extracting Aspire CLI binary.
+/// </summary>
+internal sealed class SetupCommand : BaseCommand
+{
+    private readonly ILayoutDiscovery _layoutDiscovery;
+    private readonly ILogger<SetupCommand> _logger;
+
+    private static readonly Option<string?> s_installPathOption = new("--install-path")
+    {
+        Description = "Directory to extract the bundle into. Defaults to the parent of the CLI binary's directory."
+    };
+
+    private static readonly Option<bool> s_forceOption = new("--force")
+    {
+        Description = "Force extraction even if the layout already exists."
+    };
+
+    public SetupCommand(
+        ILayoutDiscovery layoutDiscovery,
+        IFeatures features,
+        ICliUpdateNotifier updateNotifier,
+        CliExecutionContext executionContext,
+        IInteractionService interactionService,
+        AspireCliTelemetry telemetry,
+        ILogger<SetupCommand> logger)
+        : base("setup", "Extract the embedded bundle to set up the Aspire CLI runtime.", features, updateNotifier, executionContext, interactionService, telemetry)
+    {
+        _layoutDiscovery = layoutDiscovery;
+        _logger = logger;
+
+        Options.Add(s_installPathOption);
+        Options.Add(s_forceOption);
+    }
+
+    protected override async Task<int> ExecuteAsync(ParseResult parseResult, CancellationToken cancellationToken)
+    {
+        var installPath = parseResult.GetValue(s_installPathOption);
+        var force = parseResult.GetValue(s_forceOption);
+
+        var processPath = Environment.ProcessPath;
+        if (string.IsNullOrEmpty(processPath))
+        {
+            InteractionService.DisplayError("Could not determine the CLI executable path.");
+            return ExitCodeConstants.FailedToBuildArtifacts;
+        }
+
+        var trailer = BundleTrailer.TryRead(processPath);
+        if (trailer is null)
+        {
+            InteractionService.DisplayMessage(":information:", "This CLI binary does not contain an embedded bundle. No extraction needed.");
+            return ExitCodeConstants.Success;
+        }
+
+        // Determine extraction directory
+        if (string.IsNullOrEmpty(installPath))
+        {
+            var cliDir = Path.GetDirectoryName(processPath);
+            installPath = !string.IsNullOrEmpty(cliDir) ? Path.GetDirectoryName(cliDir) ?? cliDir : cliDir;
+        }
+
+        if (string.IsNullOrEmpty(installPath))
+        {
+            InteractionService.DisplayError("Could not determine the installation path.");
+            return ExitCodeConstants.FailedToBuildArtifacts;
+        }
+
+        // Check if layout already exists
+        if (!force && _layoutDiscovery.DiscoverLayout() is not null)
+        {
+            InteractionService.DisplayMessage(":white_check_mark:", "Bundle is already extracted. Use --force to re-extract.");
+            return ExitCodeConstants.Success;
+        }
+
+        // Extract with spinner
+        var exitCode = await InteractionService.ShowStatusAsync(
+            ":package:  Extracting Aspire bundle...",
+            async () =>
+            {
+                await AppHostServerProjectFactory.ExtractPayloadAsync(processPath, trailer, installPath, cancellationToken);
+                return ExitCodeConstants.Success;
+            });
+
+        if (_layoutDiscovery.DiscoverLayout() is not null)
+        {
+            InteractionService.DisplayMessage(":white_check_mark:", $"Bundle extracted to {installPath}");
+        }
+        else
+        {
+            InteractionService.DisplayError($"Bundle was extracted to {installPath} but layout validation failed.");
+            return ExitCodeConstants.FailedToBuildArtifacts;
+        }
+
+        return exitCode;
+    }
+}

src/Aspire.Cli/Program.cs

@@ -375,6 +375,7 @@ internal static async Task<IHost> BuildApplicationAsync(string[] args, Dictionar
         builder.Services.AddTransient<SdkCommand>();
         builder.Services.AddTransient<SdkGenerateCommand>();
         builder.Services.AddTransient<SdkDumpCommand>();
+        builder.Services.AddTransient<SetupCommand>();
         builder.Services.AddTransient<RootCommand>();
         builder.Services.AddTransient<ExtensionInternalCommand>();
 

src/Aspire.Cli/Projects/AppHostServerProject.cs

@@ -1,13 +1,16 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Formats.Tar;
+using System.IO.Compression;
 using System.Security.Cryptography;
 using System.Text;
 using Aspire.Cli.Configuration;
 using Aspire.Cli.DotNet;
 using Aspire.Cli.Layout;
 using Aspire.Cli.NuGet;
 using Aspire.Cli.Packaging;
+using Aspire.Shared;
 using Microsoft.Extensions.Logging;
 
 namespace Aspire.Cli.Projects;
@@ -17,7 +20,7 @@ namespace Aspire.Cli.Projects;
 /// </summary>
 internal interface IAppHostServerProjectFactory
 {
-    IAppHostServerProject Create(string appPath);
+    Task<IAppHostServerProject> CreateAsync(string appPath, CancellationToken cancellationToken = default);
 }
 
 /// <summary>
@@ -32,7 +35,7 @@ internal sealed class AppHostServerProjectFactory(
     BundleNuGetService bundleNuGetService,
     ILoggerFactory loggerFactory) : IAppHostServerProjectFactory
 {
-    public IAppHostServerProject Create(string appPath)
+    public async Task<IAppHostServerProject> CreateAsync(string appPath, CancellationToken cancellationToken = default)
     {
         // Normalize the path
         var normalizedPath = Path.GetFullPath(appPath);
@@ -71,7 +74,10 @@ public IAppHostServerProject Create(string appPath)
                 loggerFactory.CreateLogger<DotNetBasedAppHostServerProject>());
         }
 
-        // Priority 2: Check if we have a bundle layout with a pre-built AppHost server
+        // Priority 2: Ensure bundle is extracted if we have an embedded payload
+        await EnsureBundleAsync(cancellationToken);
+
+        // Priority 3: Check if we have a bundle layout with a pre-built AppHost server
         var layout = layoutDiscovery.DiscoverLayout();
         if (layout is not null && layout.GetAppHostServerPath() is string serverPath && File.Exists(serverPath))
         {
@@ -91,6 +97,145 @@ public IAppHostServerProject Create(string appPath)
             "with a valid bundle layout.");
     }
 
+    /// <summary>
+    /// Extracts the embedded bundle payload if the CLI binary is a self-extracting bundle
+    /// and no valid layout has been discovered yet.
+    /// </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))
+        {
+            return;
+        }
+
+        var trailer = BundleTrailer.TryRead(processPath);
+        if (trailer is null)
+        {
+            return; // No embedded payload (dev build or already-extracted CLI)
+        }
+
+        // Extract to the parent directory 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);
+        if (string.IsNullOrEmpty(cliDir))
+        {
+            return;
+        }
+
+        var extractDir = Path.GetDirectoryName(cliDir) ?? cliDir;
+        var logger = loggerFactory.CreateLogger<AppHostServerProjectFactory>();
+        logger.LogInformation("Extracting embedded bundle to {Path}...", extractDir);
+
+        await ExtractPayloadAsync(processPath, trailer, extractDir, cancellationToken);
+
+        // Verify extraction succeeded
+        if (layoutDiscovery.DiscoverLayout() is null)
+        {
+            logger.LogWarning("Bundle extraction completed but layout discovery still failed");
+        }
+    }
+
+    /// <summary>
+    /// Extracts the embedded tar.gz payload from the CLI binary to the specified directory.
+    /// The tarball contains a top-level directory which is stripped during extraction.
+    /// </summary>
+    internal static async Task ExtractPayloadAsync(string processPath, BundleTrailerInfo trailer, string destinationPath, CancellationToken cancellationToken)
+    {
+        Directory.CreateDirectory(destinationPath);
+
+        using var payloadStream = BundleTrailer.OpenPayload(processPath, trailer);
+        await using var gzipStream = new GZipStream(payloadStream, CompressionMode.Decompress);
+        await using var tarReader = new TarReader(gzipStream);
+
+        while (await tarReader.GetNextEntryAsync(cancellationToken: cancellationToken) is { } entry)
+        {
+            // Strip the top-level directory (equivalent to tar --strip-components=1)
+            var name = entry.Name;
+            var slashIndex = name.IndexOf('/');
+            if (slashIndex < 0)
+            {
+                continue; // Top-level directory entry itself, skip
+            }
+
+            var relativePath = name[(slashIndex + 1)..];
+            if (string.IsNullOrEmpty(relativePath))
+            {
+                continue;
+            }
+
+            var fullPath = Path.Combine(destinationPath, relativePath);
+
+            switch (entry.EntryType)
+            {
+                case TarEntryType.Directory:
+                    Directory.CreateDirectory(fullPath);
+                    break;
+
+                case TarEntryType.RegularFile:
+                    var dir = Path.GetDirectoryName(fullPath);
+                    if (dir is not null)
+                    {
+                        Directory.CreateDirectory(dir);
+                    }
+                    await entry.ExtractToFileAsync(fullPath, overwrite: true, cancellationToken);
+                    break;
+
+                case TarEntryType.SymbolicLink:
+                    var linkDir = Path.GetDirectoryName(fullPath);
+                    if (linkDir is not null)
+                    {
+                        Directory.CreateDirectory(linkDir);
+                    }
+                    if (File.Exists(fullPath))
+                    {
+                        File.Delete(fullPath);
+                    }
+                    File.CreateSymbolicLink(fullPath, entry.LinkName);
+                    break;
+            }
+        }
+
+        // Set executable permissions on Unix for key binaries
+        if (!OperatingSystem.IsWindows())
+        {
+            SetExecutablePermissions(destinationPath);
+        }
+    }
+
+    /// <summary>
+    /// Sets executable permissions on key binaries after extraction on Unix systems.
+    /// </summary>
+    [System.Runtime.Versioning.UnsupportedOSPlatform("windows")]
+    private static void SetExecutablePermissions(string layoutPath)
+    {
+        var muxerName = BundleDiscovery.GetDotNetExecutableName();
+        string[] executablePaths =
+        [
+            Path.Combine(layoutPath, BundleDiscovery.RuntimeDirectoryName, muxerName),
+            Path.Combine(layoutPath, BundleDiscovery.DcpDirectoryName, "dcp"),
+        ];
+
+        foreach (var path in executablePaths)
+        {
+            if (File.Exists(path))
+            {
+                File.SetUnixFileMode(path,
+                    UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute |
+                    UnixFileMode.GroupRead | UnixFileMode.GroupExecute |
+                    UnixFileMode.OtherRead | UnixFileMode.OtherExecute);
+            }
+        }
+    }
+
     /// <summary>
     /// Detects the Aspire repository root for dev mode.
     /// Checks ASPIRE_REPO_ROOT env var first, then walks up from the CLI executable

src/Aspire.Cli/Projects/AppHostServerSession.cs

@@ -105,7 +105,7 @@ public async Task<AppHostServerSessionResult> CreateAsync(
         bool debug,
         CancellationToken cancellationToken)
     {
-        var appHostServerProject = _projectFactory.Create(appHostPath);
+        var appHostServerProject = await _projectFactory.CreateAsync(appHostPath, cancellationToken);
 
         // Prepare the server (create files + build for dev mode, restore packages for prebuilt mode)
         var prepareResult = await appHostServerProject.PrepareAsync(sdkVersion, packages, cancellationToken);