// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
namespace Aspire.Cli.DotNet;
 
/// <summary>
/// Represents a configured process execution that can be started and awaited. Disposal is
/// asynchronous because the underlying primitive drains its stdout/stderr pumps and releases the
/// anonymous pipes + console handles it owns (the isolated-console path on Windows), which cannot
/// be done from a synchronous <see cref="IDisposable.Dispose"/> without blocking.
/// </summary>
internal interface IProcessExecution : IAsyncDisposable
{
    /// <summary>
    /// Gets the file name of the executable to run.
    /// </summary>
    string FileName { get; }
 
    /// <summary>
    /// Gets the command-line arguments.
    /// </summary>
    IReadOnlyList<string> Arguments { get; }
 
    /// <summary>
    /// Gets the environment variables configured for the process.
    /// </summary>
    IReadOnlyDictionary<string, string?> EnvironmentVariables { get; }
 
    /// <summary>
    /// Starts the execution.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns><c>true</c> if the process was started successfully; otherwise, <c>false</c>.</returns>
    Task<bool> StartAsync(CancellationToken cancellationToken);
 
    /// <summary>
    /// Gets the process ID. Only valid after <see cref="StartAsync"/> returns <c>true</c>.
    /// </summary>
    int ProcessId { get; }
 
    /// <summary>
    /// Gets the process start time, when available. Only valid after <see cref="StartAsync"/> returns <c>true</c>.
    /// </summary>
    DateTimeOffset? StartTime { get; }
 
    /// <summary>
    /// Waits for the process to exit asynchronously.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The exit code of the process.</returns>
    Task<int> WaitForExitAsync(CancellationToken cancellationToken);
 
    /// <summary>
    /// Gets a value indicating whether the process has exited. Only valid after <see cref="StartAsync"/> returns <c>true</c>.
    /// </summary>
    bool HasExited { get; }
 
    /// <summary>
    /// Gets the exit code of the process. Only valid after <see cref="HasExited"/> returns <c>true</c>.
    /// </summary>
    int ExitCode { get; }
 
    /// <summary>
    /// Kills the process.
    /// </summary>
    /// <param name="entireProcessTree">When <c>true</c>, kills the entire process tree; otherwise kills only the root process.</param>
    void Kill(bool entireProcessTree);
}