Add --list-steps flag to aspire do command (#16085)

* Add --list-steps flag to aspire do command

Implement support for 'aspire do --list-steps' that prints pipeline steps
in execution order with their dependencies and tags, without executing them.

Changes:
- Add PipelineStepInfo DTO to BackchannelDataTypes.cs (source-shared)
- Add ResolveStepsAsync to DistributedApplicationPipeline for resolving
  steps without executing them
- Add GetPipelineStepsAsync RPC method to AppHostRpcTarget with
  'pipeline-steps.v1' capability
- Add GetPipelineStepsAsync to IAppHostCliBackchannel interface and
  implementations
- Add --list-steps option to PipelineCommandBase with formatted output
- Make DoCommand step argument optional when --list-steps is used

Testing:
- Unit tests for DoCommand with --list-steps (returns 0, calls
  GetPipelineStepsAsync, does not execute pipeline, calls RequestStopAsync)
- Unit tests for PrintPipelineSteps formatting (dependencies, tags,
  sequential numbering, empty steps, full pipeline output)
- Unit tests for ResolveStepsAsync and GetTopologicalOrder
- E2E CLI test using Hex1b terminal automation

Fixes #12376

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

* Improve --list-steps output formatting

Add color to the output: green step numbers, blue 'Depends on:' label,
yellow 'Tags:' label, dim 'No dependencies' text. Add hanging indent
for long dependency lists so wrapped items align under the first item.

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

* Fix PrintPipelineSteps tests to strip ANSI escape codes

The Spectre.Console AnsiConsole emits ANSI escape codes even with
AnsiSupport.No in CI environments. Strip ANSI codes before asserting
on output content.

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

* Fix hanging indent alignment and use cyan for step names

Fix the continuation line indent to align wrapped dependency items
directly under the first item (19 chars), not double-indented.
Change step name color from bold white to cyan for better visibility.

Before:
   ├─ Depends on: provision-redis-infra, provision-postgres-infra,
                                          build-webapi
After:
   ├─ Depends on: provision-redis-infra, provision-postgres-infra,
                   build-webapi

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

* Fix wrapped dependency alignment to be computed dynamically

Compute the continuation prefix width from the visible length of the
first line prefix rather than hardcoding spaces. This ensures wrapped
dependency items align correctly under the first item regardless of
unicode box-drawing character widths.

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

* Address review feedback: backchannel spec compliance and versioning

- Use request/response objects (GetPipelineStepsRequest/Response) per
  the backchannel spec contract rules instead of raw array return
- Add capability check for 'pipeline-steps.v1' before calling
  GetPipelineStepsAsync, throwing AppHostIncompatibleException with a
  clear message if the AppHost doesn't support it
- Scope #pragma warning disable ASPIREPIPELINES001 to just the method
  that needs it instead of file-wide
- Fix ResolveStepsAsync XML doc to accurately state it returns
  collection order (not topological order)

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

* Scope --list-steps output to target step and its dependencies

When a target step is specified (e.g. 'aspire do build --list-steps'),
only show that step and its transitive dependencies instead of the
full pipeline graph. This makes the output much more useful for
understanding what a specific target will actually do.

- aspire do --list-steps          -> all steps (no filter)
- aspire do build --list-steps    -> build + its deps only
- aspire publish --list-steps     -> publish + its deps only
- aspire deploy --list-steps      -> deploy + its deps only

Each PipelineCommandBase subclass provides its target step name via
GetTargetStepName(). The step name is passed in GetPipelineStepsRequest
and the AppHost filters using ComputeTransitiveDependencies.

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

* Use System.CommandLine validator for missing step argument

Replace InvalidOperationException with a proper command validator so
users get a standard parse error with help/usage output instead of an
unexpected error when running 'aspire do' without a step argument
and without --list-steps.

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

---------

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

Author: mitchdenny

src/Aspire.Cli/Backchannel/AppHostCliBackchannel.cs

@@ -24,6 +24,7 @@ internal interface IAppHostCliBackchannel
     Task CompletePromptResponseAsync(string promptId, PublishingPromptInputAnswer[] answers, CancellationToken cancellationToken);
     Task UpdatePromptResponseAsync(string promptId, PublishingPromptInputAnswer[] answers, CancellationToken cancellationToken);
     IAsyncEnumerable<CommandOutput> ExecAsync(CancellationToken cancellationToken);
+    Task<GetPipelineStepsResponse> GetPipelineStepsAsync(string? step, CancellationToken cancellationToken);
 }
 
 internal sealed class AppHostCliBackchannel(ILogger<AppHostCliBackchannel> logger, AspireCliTelemetry telemetry) : IAppHostCliBackchannel
@@ -480,5 +481,22 @@ public async IAsyncEnumerable<CommandOutput> ExecAsync([EnumeratorCancellation]
         }
     }
 
+    public async Task<GetPipelineStepsResponse> GetPipelineStepsAsync(string? step, CancellationToken cancellationToken)
+    {
+        using var activity = telemetry.StartDiagnosticActivity();
+        var rpc = await GetRpcTaskAsync().WaitAsync(cancellationToken).ConfigureAwait(false);
+
+        logger.LogDebug("Requesting pipeline steps.");
+
+        var response = await rpc.InvokeWithCancellationAsync<GetPipelineStepsResponse>(
+            "GetPipelineStepsAsync",
+            [new GetPipelineStepsRequest { Step = step }],
+            cancellationToken).ConfigureAwait(false);
+
+        logger.LogDebug("Received {StepCount} pipeline steps.", response.Steps.Length);
+
+        return response;
+    }
+
 }
 

src/Aspire.Cli/Backchannel/BackchannelJsonSerializerContext.cs

@@ -76,6 +76,10 @@ namespace Aspire.Cli.Backchannel;
 [JsonSerializable(typeof(ExecuteResourceCommandResponse))]
 [JsonSerializable(typeof(WaitForResourceRequest))]
 [JsonSerializable(typeof(WaitForResourceResponse))]
+[JsonSerializable(typeof(PipelineStepInfo))]
+[JsonSerializable(typeof(PipelineStepInfo[]))]
+[JsonSerializable(typeof(GetPipelineStepsRequest))]
+[JsonSerializable(typeof(GetPipelineStepsResponse))]
 internal partial class BackchannelJsonSerializerContext : JsonSerializerContext
 {
     [UnconditionalSuppressMessage("ReflectionAnalysis", "IL2026:RequiresUnreferencedCode", Justification = "Using the Json source generator.")]

src/Aspire.Cli/Commands/DeployCommand.cs

@@ -77,6 +77,8 @@ protected override Task<string[]> GetRunArgumentsAsync(string? fullyQualifiedOut
 
     protected override string GetCanceledMessage() => DeployCommandStrings.DeploymentCanceled;
 
+    protected override string? GetTargetStepName(ParseResult parseResult) => "deploy";
+
     protected override string GetProgressMessage(ParseResult parseResult)
     {
         return "Executing step deploy";

src/Aspire.Cli/Commands/DoCommand.cs

@@ -24,13 +24,22 @@ internal sealed class DoCommand : PipelineCommandBase
     public DoCommand(IDotNetCliRunner runner, IInteractionService interactionService, IProjectLocator projectLocator, AspireCliTelemetry telemetry, IFeatures features, ICliUpdateNotifier updateNotifier, CliExecutionContext executionContext, ICliHostEnvironment hostEnvironment, IAppHostProjectFactory projectFactory, IConfiguration configuration, ILogger<DoCommand> logger, IAnsiConsole ansiConsole)
         : base("do", DoCommandStrings.Description, runner, interactionService, projectLocator, telemetry, features, updateNotifier, executionContext, hostEnvironment, projectFactory, configuration, logger, ansiConsole)
     {
-        var isExtensionHost = ExtensionHelper.IsExtensionHost(interactionService, out _, out _);
         _stepArgument = new Argument<string>("step")
         {
             Description = DoCommandStrings.StepArgumentDescription,
-            Arity = isExtensionHost ? ArgumentArity.ZeroOrOne : ArgumentArity.ExactlyOne
+            Arity = ArgumentArity.ZeroOrOne
         };
         Arguments.Add(_stepArgument);
+
+        Validators.Add(result =>
+        {
+            var step = result.GetValue(_stepArgument);
+            var listSteps = result.GetValue(s_listStepsOption);
+            if (string.IsNullOrEmpty(step) && !listSteps && !ExtensionHelper.IsExtensionHost(interactionService, out _, out _))
+            {
+                result.AddError("The 'step' argument is required when not using --list-steps.");
+            }
+        });
     }
 
     protected override string OperationCompletedPrefix => DoCommandStrings.OperationCompletedPrefix;
@@ -92,8 +101,15 @@ protected override async Task<string[]> GetRunArgumentsAsync(string? fullyQualif
 
     protected override string GetCanceledMessage() => DoCommandStrings.OperationCanceled;
 
+    protected override string? GetTargetStepName(ParseResult parseResult) => parseResult.GetValue(_stepArgument);
+
     protected override string GetProgressMessage(ParseResult parseResult)
     {
+        if (parseResult.GetValue(s_listStepsOption))
+        {
+            return "Listing pipeline steps";
+        }
+
         var step = parseResult.GetValue(_stepArgument);
         return $"Executing step {step}";
     }

src/Aspire.Cli/Commands/PipelineCommandBase.cs

@@ -4,6 +4,7 @@
 using System.CommandLine;
 using System.Diagnostics;
 using System.Globalization;
+using System.Text;
 using Aspire.Cli.Backchannel;
 using Aspire.Cli.Configuration;
 using Aspire.Cli.DotNet;
@@ -60,6 +61,11 @@ internal abstract class PipelineCommandBase : BaseCommand
         Description = PublishCommandStrings.NoBuildArgumentDescription
     };
 
+    protected static readonly Option<bool> s_listStepsOption = new("--list-steps")
+    {
+        Description = "List the pipeline steps that would be executed, without running them."
+    };
+
     protected abstract string OperationCompletedPrefix { get; }
     protected abstract string OperationFailedPrefix { get; }
 
@@ -95,6 +101,7 @@ protected PipelineCommandBase(string name, string description, IDotNetCliRunner
         Options.Add(s_environmentOption);
         Options.Add(s_includeExceptionDetailsOption);
         Options.Add(s_noBuildOption);
+        Options.Add(s_listStepsOption);
 
         if (ExtensionHelper.IsExtensionHost(interactionService, out _, out _))
         {
@@ -115,6 +122,12 @@ protected PipelineCommandBase(string name, string description, IDotNetCliRunner
     protected abstract string GetCanceledMessage();
     protected abstract string GetProgressMessage(ParseResult parseResult);
 
+    /// <summary>
+    /// Gets the target pipeline step name for this command, used for --list-steps filtering.
+    /// Returns null to show all steps.
+    /// </summary>
+    protected virtual string? GetTargetStepName(ParseResult parseResult) => null;
+
     /// <summary>
     /// Gets command-specific arguments to forward when starting a debug session from the extension context.
     /// Subclasses should override to include their specific positional arguments.
@@ -250,6 +263,30 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, Cancell
                 throw new InvalidOperationException("Run completed without returning a backchannel.", innerException);
             }, emoji: KnownEmojis.HammerAndWrench);
 
+            // If --list-steps was specified, get pipeline steps and print them instead of executing
+            var listSteps = parseResult.GetValue(s_listStepsOption);
+            if (listSteps)
+            {
+                StopTerminalProgressBar();
+
+                // Check that the AppHost supports this capability before calling
+                var capabilities = await backchannel.GetCapabilitiesAsync(cancellationToken);
+                if (!capabilities.Contains("pipeline-steps.v1"))
+                {
+                    throw new AppHostIncompatibleException(
+                        "The AppHost does not support --list-steps. Update the AppHost to a newer version of Aspire.",
+                        "pipeline-steps.v1");
+                }
+
+                var targetStep = GetTargetStepName(parseResult);
+                var response = await backchannel.GetPipelineStepsAsync(targetStep, cancellationToken);
+                PrintPipelineSteps(response.Steps);
+
+                await backchannel.RequestStopAsync(cancellationToken).ConfigureAwait(false);
+                await pendingRun;
+                return ExitCodeConstants.Success;
+            }
+
             var publishingActivities = backchannel.GetPublishingActivitiesAsync(cancellationToken);
 
             // Check if debug or trace logging is enabled
@@ -361,6 +398,103 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, Cancell
         }
     }
 
+    /// <summary>
+    /// Prints pipeline steps in a numbered tree format showing dependencies and tags.
+    /// </summary>
+    internal void PrintPipelineSteps(PipelineStepInfo[] steps)
+    {
+        if (steps.Length == 0)
+        {
+            _ansiConsole.MarkupLine("[dim]No pipeline steps found.[/]");
+            return;
+        }
+
+        for (var i = 0; i < steps.Length; i++)
+        {
+            var step = steps[i];
+
+            _ansiConsole.MarkupLine($"[bold green]{i + 1}.[/] [cyan]{step.Name.EscapeMarkup()}[/]");
+
+            var hasDeps = step.DependsOn.Length > 0;
+            var hasTags = step.Tags.Length > 0;
+
+            if (!hasDeps && !hasTags)
+            {
+                _ansiConsole.MarkupLine("[dim]   └─ No dependencies[/]");
+            }
+            else
+            {
+                if (hasDeps)
+                {
+                    var connector = hasTags ? "├" : "└";
+                    var continuation = hasTags ? "│" : " ";
+                    var firstLinePrefix = $"   {connector}─ [blue]Depends on:[/] ";
+                    // Build continuation prefix that aligns wrapped items under the first dep value.
+                    // Replace the connector with the continuation char and pad the rest with spaces.
+                    var visibleWidth = StripMarkup(firstLinePrefix).Length;
+                    var continuationPrefix = "   " + continuation + new string(' ', visibleWidth - 4);
+                    var wrappedDeps = FormatWithHangingIndent(step.DependsOn, firstLinePrefix, continuationPrefix);
+                    _ansiConsole.MarkupLine(wrappedDeps);
+                }
+
+                if (hasTags)
+                {
+                    var tagsText = string.Join(", ", step.Tags);
+                    _ansiConsole.MarkupLine($"   └─ [yellow]Tags:[/] {tagsText.EscapeMarkup()}");
+                }
+            }
+
+            if (i < steps.Length - 1)
+            {
+                _ansiConsole.WriteLine();
+            }
+        }
+    }
+
+    /// <summary>
+    /// Formats a list of items with a prefix on the first line and hanging indent on continuation lines.
+    /// Items are comma-separated and wrapped so each line stays readable.
+    /// </summary>
+    private static string FormatWithHangingIndent(string[] items, string firstLinePrefix, string continuationPrefix, int maxLineLength = 100)
+    {
+        if (items.Length == 0)
+        {
+            return firstLinePrefix;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append(firstLinePrefix);
+
+        // Track visible length (without markup tags) for line wrapping
+        var visiblePrefixLength = StripMarkup(firstLinePrefix).Length;
+        var currentLineLength = visiblePrefixLength;
+
+        for (var i = 0; i < items.Length; i++)
+        {
+            var item = items[i].EscapeMarkup();
+            var separator = i < items.Length - 1 ? ", " : "";
+            var chunk = item + separator;
+
+            if (i > 0 && currentLineLength + chunk.Length > maxLineLength)
+            {
+                sb.AppendLine();
+                sb.Append(continuationPrefix);
+                currentLineLength = StripMarkup(continuationPrefix).Length;
+            }
+
+            sb.Append(chunk);
+            currentLineLength += chunk.Length;
+        }
+
+        return sb.ToString();
+    }
+
+    private static string StripMarkup(string text)
+    {
+        // Remove Spectre markup tags like [bold], [/], [blue], etc.
+        return System.Text.RegularExpressions.Regex.Replace(text, @"\[/?[^\]]*\]", "");
+    }
+
     /// <summary>
     /// Conditionally converts markdown to Spectre markup based on the EnableMarkdown flag in the activity data.
     /// </summary>

src/Aspire.Cli/Commands/PublishCommand.cs

@@ -85,5 +85,7 @@ protected override Task<string[]> GetRunArgumentsAsync(string? fullyQualifiedOut
 
     protected override string GetCanceledMessage() => InteractionServiceStrings.OperationCancelled;
 
+    protected override string? GetTargetStepName(ParseResult parseResult) => "publish";
+
     protected override string GetProgressMessage(ParseResult parseResult) => "Executing step publish";
 }

src/Aspire.Hosting/Backchannel/AppHostRpcTarget.cs

@@ -191,7 +191,8 @@ public Task<string[]> GetCapabilitiesAsync(CancellationToken cancellationToken)
 
         _ = cancellationToken;
         return Task.FromResult(new string[] {
-            "baseline.v2"
+            "baseline.v2",
+            "pipeline-steps.v1"
             });
     }
 #pragma warning restore CA1822
@@ -205,4 +206,51 @@ public async Task UpdatePromptResponseAsync(string promptId, PublishingPromptInp
     {
         await activityReporter.CompleteInteractionAsync(promptId, answers, updateResponse: true, cancellationToken).ConfigureAwait(false);
     }
+
+    public async Task<GetPipelineStepsResponse> GetPipelineStepsAsync(GetPipelineStepsRequest? request = null, CancellationToken cancellationToken = default)
+    {
+        logger.LogDebug("Resolving pipeline steps for list-steps request.");
+
+#pragma warning disable ASPIREPIPELINES001
+        var pipeline = serviceProvider.GetRequiredService<IDistributedApplicationPipeline>() as DistributedApplicationPipeline
+            ?? throw new InvalidOperationException("Pipeline is not a DistributedApplicationPipeline.");
+
+        var model = serviceProvider.GetRequiredService<DistributedApplicationModel>();
+        var executionContext = serviceProvider.GetRequiredService<DistributedApplicationExecutionContext>();
+
+        var pipelineContext = new PipelineContext(model, executionContext, serviceProvider, logger, cancellationToken);
+
+        var resolvedSteps = await pipeline.ResolveStepsAsync(pipelineContext).ConfigureAwait(false);
+
+        // If a target step is specified, filter to its transitive dependencies
+        if (!string.IsNullOrEmpty(request?.Step))
+        {
+            var stepsByName = resolvedSteps.ToDictionary(s => s.Name, StringComparer.Ordinal);
+            if (stepsByName.TryGetValue(request.Step, out var targetStep))
+            {
+                resolvedSteps = DistributedApplicationPipeline.ComputeTransitiveDependencies(targetStep, stepsByName);
+            }
+            else
+            {
+                var availableSteps = string.Join(", ", resolvedSteps.Select(s => $"'{s.Name}'"));
+                throw new InvalidOperationException(
+                    $"Step '{request.Step}' not found in pipeline. Available steps: {availableSteps}");
+            }
+        }
+
+        var orderedSteps = DistributedApplicationPipeline.GetTopologicalOrder(resolvedSteps);
+#pragma warning restore ASPIREPIPELINES001
+
+        return new GetPipelineStepsResponse
+        {
+            Steps = orderedSteps.Select(step => new PipelineStepInfo
+            {
+                Name = step.Name,
+                Description = step.Description,
+                DependsOn = [.. step.DependsOnSteps],
+                Tags = [.. step.Tags],
+                ResourceName = step.Resource?.Name
+            }).ToArray()
+        };
+    }
 }

src/Aspire.Hosting/Backchannel/BackchannelDataTypes.cs

@@ -688,6 +688,60 @@ internal class PublishingPromptInputAnswer
     public string? Value { get; set; }
 }
 
+/// <summary>
+/// Represents metadata about a pipeline step for display purposes (e.g., --list-steps).
+/// </summary>
+internal sealed class PipelineStepInfo
+{
+    /// <summary>
+    /// Gets the unique name of the step.
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Gets the description of the step.
+    /// </summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// Gets the names of steps that this step depends on.
+    /// </summary>
+    public string[] DependsOn { get; init; } = [];
+
+    /// <summary>
+    /// Gets the tags that categorize this step.
+    /// </summary>
+    public string[] Tags { get; init; } = [];
+
+    /// <summary>
+    /// Gets the name of the resource this step is associated with, if any.
+    /// </summary>
+    public string? ResourceName { get; init; }
+}
+
+/// <summary>
+/// Request for getting pipeline step metadata.
+/// </summary>
+internal sealed class GetPipelineStepsRequest
+{
+    /// <summary>
+    /// Gets or sets the target step name to filter to (including transitive dependencies).
+    /// When null, all steps are returned.
+    /// </summary>
+    public string? Step { get; init; }
+}
+
+/// <summary>
+/// Response containing pipeline step metadata.
+/// </summary>
+internal sealed class GetPipelineStepsResponse
+{
+    /// <summary>
+    /// Gets the pipeline steps in topological (execution) order.
+    /// </summary>
+    public required PipelineStepInfo[] Steps { get; init; }
+}
+
 /// <summary>
 /// Represents the connection information for the Dashboard MCP server.
 /// </summary>