Consider adding aliases for "dotnet tool"

[paulomorgado]

There are several dotnet tool commands:

• dotnet tool exec
• dotnet tool install
• dotnet tool list
• dotnet tool restore
• dotnet tool run
• dotnet tool search
• dotnet tool uninstall
• dotnet tool update

It would be nice to have aliases to all these.

One possible implementation for dotnet tool exec could be:

    /// <summary>
    /// Executes a .NET tool package with <c>dotnet tool exec</c>.
    /// </summary>
    /// <param name="context">The Cake context.</param>
    /// <param name="packageId">The package ID to execute. Use the <c>package@version</c> syntax to request a specific version.</param>
    /// <example>
    /// <code>
    /// DotNetToolExecute("dotnetsay");
    /// </code>
    /// </example>
    [CakeMethodAlias]
    [CakeAliasCategory("Tool")]
    [CakeNamespaceImport("Cake.Common.Tools.DotNet.Tool")]
    public static void DotNetToolExecute(this ICakeContext context, string packageId)
    {
        ArgumentNullException.ThrowIfNull(context);

        var arguments = new ProcessArgumentBuilder();
        var settings = new DotNetToolSettings();

        context.DotNetToolExecute(null, packageId, arguments, settings);
    }

    /// <summary>
    /// Executes a .NET tool package with <c>dotnet tool exec</c> and the specified settings.
    /// </summary>
    /// <param name="context">The Cake context.</param>
    /// <param name="packageId">The package ID to execute. Use the <c>package@version</c> syntax to request a specific version.</param>
    /// <param name="settings">The settings.</param>
    /// <example>
    /// <code>
    /// var settings = new DotNetToolSettings
    /// {
    ///     Verbosity = DotNetVerbosity.Minimal
    /// };
    ///
    /// DotNetToolExecute("dotnetsay", settings);
    /// </code>
    /// </example>
    [CakeMethodAlias]
    [CakeAliasCategory("Tool")]
    [CakeNamespaceImport("Cake.Common.Tools.DotNet.Tool")]
    public static void DotNetToolExecute(this ICakeContext context, string packageId, DotNetToolSettings settings)
    {
        ArgumentNullException.ThrowIfNull(context);

        var arguments = new ProcessArgumentBuilder();

        context.DotNetToolExecute(null, packageId, arguments, settings);
    }

    /// <summary>
    /// Executes a .NET tool package with <c>dotnet tool exec</c> for the specified project path.
    /// </summary>
    /// <param name="context">The Cake context.</param>
    /// <param name="projectPath">The optional project path.</param>
    /// <param name="packageId">The package ID to execute. Use the <c>package@version</c> syntax to request a specific version.</param>
    /// <example>
    /// <code>
    /// DotNetToolExecute("./src/project", "dotnetsay");
    /// </code>
    /// </example>
    [CakeMethodAlias]
    [CakeAliasCategory("Tool")]
    [CakeNamespaceImport("Cake.Common.Tools.DotNet.Tool")]
    public static void DotNetToolExecute(this ICakeContext context, FilePath? projectPath, string packageId)
    {
        ArgumentNullException.ThrowIfNull(context);

        var arguments = new ProcessArgumentBuilder();
        var settings = new DotNetToolSettings();

        context.DotNetToolExecute(projectPath, packageId, arguments, settings);
    }

    /// <summary>
    /// Executes a .NET tool package with <c>dotnet tool exec</c> and passes arguments to the tool.
    /// </summary>
    /// <param name="context">The Cake context.</param>
    /// <param name="projectPath">The optional project path.</param>
    /// <param name="packageId">The package ID to execute. Use the <c>package@version</c> syntax to request a specific version.</param>
    /// <param name="arguments">The arguments to pass to the tool.</param>
    /// <example>
    /// <code>
    /// DotNetToolExecute("./src/project", "dotnetsay", "Hello World");
    /// </code>
    /// </example>
    [CakeMethodAlias]
    [CakeAliasCategory("Tool")]
    [CakeNamespaceImport("Cake.Common.Tools.DotNet.Tool")]
    public static void DotNetToolExecute(this ICakeContext context, FilePath? projectPath, string packageId, ProcessArgumentBuilder arguments)
    {
        ArgumentNullException.ThrowIfNull(context);

        var settings = new DotNetToolSettings();

        context.DotNetToolExecute(projectPath, packageId, arguments, settings);
    }

    /// <summary>
    /// Executes a .NET tool package with <c>dotnet tool exec</c>, passes arguments to the tool, and applies the specified settings.
    /// </summary>
    /// <param name="context">The Cake context.</param>
    /// <param name="projectPath">The optional project path.</param>
    /// <param name="packageId">The package ID to execute. Use the <c>package@version</c> syntax to request a specific version.</param>
    /// <param name="arguments">The arguments to pass to the tool.</param>
    /// <param name="settings">The settings.</param>
    /// <example>
    /// <code>
    /// DotNetToolExecute("./src/project", "dotnetsay", "Hello World", new DotNetToolSettings());
    /// </code>
    /// </example>
    [CakeMethodAlias]
    [CakeAliasCategory("Tool")]
    [CakeNamespaceImport("Cake.Common.Tools.DotNet.Tool")]
    public static void DotNetToolExecute(this ICakeContext context, FilePath? projectPath, string packageId, ProcessArgumentBuilder arguments, DotNetToolSettings settings)
    {
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(arguments);
        ArgumentNullException.ThrowIfNull(settings);
        ArgumentException.ThrowIfNullOrWhiteSpace(packageId);

        var toolExecArguments = new ProcessArgumentBuilder()
            .Append("exec")
            .Append(packageId);

        var argumentCustomization = settings.ArgumentCustomization;
        if (arguments.Count == 0)
        {
            context.DotNetTool(projectPath, "tool", toolExecArguments, settings);
            return;
        }

        settings.ArgumentCustomization = dotnetArguments =>
        {
            var customizedArguments = argumentCustomization?.Invoke(dotnetArguments) ?? dotnetArguments;
            customizedArguments
                .Append("--")
                .AppendRange(arguments);

            return customizedArguments;
        };

        try
        {
            context.DotNetTool(projectPath, "tool", toolExecArguments, settings);
        }
        finally
        {
            settings.ArgumentCustomization = argumentCustomization;
        }
    }

    public static IEnumerable<object[]> DotNetToolExecuteOverloadCases()
    {
        yield return [nameof(DotNetToolExecuteInvocation.PackageOnly), "\"tool\" exec dotnetsay@1.2.3", false];
        yield return [nameof(DotNetToolExecuteInvocation.PackageWithSettings), "\"tool\" exec dotnetsay@1.2.3 --verbosity minimal", false];
        yield return [nameof(DotNetToolExecuteInvocation.ProjectAndPackage), "\"tool\" exec dotnetsay@1.2.3", true];
        yield return [nameof(DotNetToolExecuteInvocation.ProjectPackageAndArguments), "\"tool\" exec dotnetsay@1.2.3 -- --tool-option tool-value", true];
        yield return [nameof(DotNetToolExecuteInvocation.Full), "\"tool\" exec dotnetsay@1.2.3 --verbosity minimal -- --tool-option tool-value", true];
    }

    [Fact]
    public void DotNetToolExecute_WithNullProjectPath_DoesNotThrow()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            ProjectPath = null,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder(),
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay");
    }

    [Theory]
    [InlineData(null)]
    [InlineData("")]
    [InlineData(" ")]
    public void DotNetToolExecute_WithInvalidPackageId_ThrowsArgumentException(string? packageId)
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = packageId,
            Arguments = new ProcessArgumentBuilder(),
        };
        fixture.GivenDefaultToolDoNotExist();

        // Act

        var exception = Should.Throw<ArgumentException>(() => fixture.Run());

        // Assert

        exception.ParamName.ShouldBe("packageId");
    }

    [Fact]
    public void DotNetToolExecute_WithNullSettings_ThrowsArgumentNullException()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder(),
            Settings = null!,
        };
        fixture.GivenDefaultToolDoNotExist();

        // Act

        var exception = Should.Throw<ArgumentNullException>(() => fixture.Run());

        // Assert

        exception.ParamName.ShouldBe("settings");
    }

    [Fact]
    public void DotNetToolExecute_WhenProcessCannotStart_ThrowsCakeException()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder(),
        };
        fixture.GivenProcessCannotStart();

        // Act

        var exception = Should.Throw<CakeException>(() => fixture.Run());

        // Assert

        exception.Message.ShouldBe(".NET CLI: Process was not started.");
    }

    [Fact]
    public void DotNetToolExecute_WhenProcessHasNonZeroExitCode_ThrowsCakeException()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder(),
        };
        fixture.GivenProcessExitsWithCode(1);

        // Act

        var exception = Should.Throw<CakeException>(() => fixture.Run());

        // Assert

        exception.Message.ShouldBe(".NET CLI: Process returned an error (exit code 1).");
    }

    [Theory]
    [MemberData(nameof(DotNetToolExecuteOverloadCases))]
    public void DotNetToolExecute_AllOverloads_RenderDotnetToolExecCommand(string invocationName, string expectedArguments, bool usesProjectPath)
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = Enum.Parse<DotNetToolExecuteInvocation>(invocationName),
            ProjectPath = "./src/project.csproj",
            PackageId = "dotnetsay@1.2.3",
            Arguments = new ProcessArgumentBuilder()
                .Append("--tool-option")
                .Append("tool-value"),
            Settings =
            {
                Verbosity = DotNetVerbosity.Minimal,
            },
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe(expectedArguments);
        if (usesProjectPath)
        {
            result.Process.WorkingDirectory.FullPath.ShouldBe(fixture.ProjectPath.GetDirectory().FullPath);
        }
    }

    [Fact]
    public void DotNetToolExecute_WithPackageId_ExecutesDotNetToolExec()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.PackageOnly,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder(),
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay");
    }

    [Fact]
    public void DotNetToolExecute_WithToolArguments_SeparatesDotNetArgumentsFromToolArguments()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder()
                .Append("Hello")
                .Append("--name")
                .Append("World"),
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay -- Hello --name World");
    }

    [Fact]
    public void DotNetToolExecute_WithSettings_PreservesDotNetToolSettings()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            ProjectPath = "./src/project.csproj",
            PackageId = "dotnetsay@2.1.0",
            Arguments = new ProcessArgumentBuilder(),
            Settings =
            {
                Verbosity = DotNetVerbosity.Minimal,
            },
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay@2.1.0 --verbosity minimal");
        result.Process.WorkingDirectory.FullPath.ShouldBe(fixture.ProjectPath.GetDirectory().FullPath);
    }

    [Fact]
    public void DotNetToolExecute_WithSettingsAndToolArguments_AppendsToolArgumentsAfterDotNetArguments()
    {
        // Arrange

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder()
                .Append("--tool-option")
                .Append("tool-value"),
            Settings =
            {
                Verbosity = DotNetVerbosity.Minimal,
            },
        };

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay --verbosity minimal -- --tool-option tool-value");
    }

    [Fact]
    public void DotNetToolExecute_WithArgumentCustomization_RestoresOriginalCustomization()
    {
        // Arrange

        Func<ProcessArgumentBuilder, ProcessArgumentBuilder> addInteractive = arguments => arguments.Append("--interactive");

        var fixture = new DotNetToolExecuteFixture
        {
            Invocation = DotNetToolExecuteInvocation.Full,
            PackageId = "dotnetsay",
            Arguments = new ProcessArgumentBuilder()
                .Append("--tool-option"),
        };
        fixture.Settings.ArgumentCustomization = addInteractive;

        // Act

        var result = fixture.Run();

        // Assert

        result.Args.ShouldBe("\"tool\" exec dotnetsay --interactive -- --tool-option");
        fixture.Settings.ArgumentCustomization.ShouldBeSameAs(addInteractive);
    }

    private enum DotNetToolExecuteInvocation
    {
        Full,
        PackageOnly,
        PackageWithSettings,
        ProjectAndPackage,
        ProjectPackageAndArguments,
    }

    private sealed class DotNetToolExecuteFixture : ToolFixture<DotNetToolSettings>
    {
        public DotNetToolExecuteFixture()
            : base("dotnet.exe")
        {
            ProcessRunner.Process.SetStandardOutput(Array.Empty<string>());
        }

        public FilePath? ProjectPath { get; init; }

        public required string? PackageId { get; init; }

        public required ProcessArgumentBuilder Arguments { get; init; }

        public required DotNetToolExecuteInvocation Invocation { get; init; }

        protected override void RunTool()
        {
            var context = CreateContext();

            switch (Invocation)
            {
                case DotNetToolExecuteInvocation.PackageOnly:
                    context.DotNetToolExecute(PackageId!);
                    break;
                case DotNetToolExecuteInvocation.PackageWithSettings:
                    context.DotNetToolExecute(PackageId!, Settings);
                    break;
                case DotNetToolExecuteInvocation.ProjectAndPackage:
                    context.DotNetToolExecute(ProjectPath, PackageId!);
                    break;
                case DotNetToolExecuteInvocation.ProjectPackageAndArguments:
                    context.DotNetToolExecute(ProjectPath, PackageId!, Arguments);
                    break;
                default:
                    context.DotNetToolExecute(ProjectPath, PackageId!, Arguments, Settings);
                    break;
            }
        }

        private ICakeContext CreateContext() =>
            new CakeContext(
                FileSystem,
                Environment,
                Globber,
                new FakeLog(),
                new CakeArguments(Enumerable.Empty<string>().ToLookup(argument => argument, StringComparer.Ordinal)),
                ProcessRunner,
                new Mock<IRegistry>(MockBehavior.Strict).Object,
                Tools,
                new Mock<ICakeDataService>(MockBehavior.Strict).Object,
                Configuration);
    }

[paulomorgado]

I'm working on this.

[augustoproiete]

Tracking issue: #4890