// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System.Diagnostics.CodeAnalysis;
using Aspire.Hosting.ApplicationModel;
using Aspire.Hosting.ApplicationModel.Docker;
 
namespace Aspire.Hosting.JavaScript;
 
/// <summary>
/// Represents the annotation for the JavaScript package manager used in a resource.
/// </summary>
/// <param name="executableName">The name of the executable used to run the package manager.</param>
/// <param name="runScriptCommand">The command used to run a script with the JavaScript package manager.</param>
/// <param name="cacheMount">The BuildKit cache mount path for the package manager, or null if not supported.</param>
public sealed class JavaScriptPackageManagerAnnotation(string executableName, string? runScriptCommand, string? cacheMount = null) : IResourceAnnotation
{
    /// <summary>
    /// Gets the executable used to run the JavaScript package manager.
    /// </summary>
    public string ExecutableName { get; } = executableName;
 
    /// <summary>
    /// Gets the command used to run a script with the JavaScript package manager.
    /// </summary>
    public string? ScriptCommand { get; } = runScriptCommand;
 
    /// <summary>
    /// Gets the string used to separate individual commands in a command sequence, or <see langword="null"/> if one shouldn't be used.
    /// Defaults to "--".
    /// </summary>
    public string? CommandSeparator { get; init; } = "--";
 
    /// <summary>
    /// Gets the BuildKit cache mount path for the package manager, or null if not supported.
    /// </summary>
    public string? CacheMount { get; } = cacheMount;
 
    /// <summary>
    /// Gets the file patterns for package dependency files.
    /// </summary>
    public List<CopyFilePattern> PackageFilesPatterns { get; } = [];
 
    /// <summary>
    /// Gets or sets a callback to initialize the Docker build stage before installing packages.
    /// </summary>
    [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public Action<DockerfileStage>? InitializeDockerBuildStage { get; init; }
 
    /// <summary>
    /// Gets or sets a callback to initialize the Docker runtime stage before configuring the entrypoint.
    /// </summary>
    [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    internal Action<DockerfileStage>? InitializeDockerRuntimeStage { get; init; }
 
    /// <summary>
    /// Gets or sets a callback to resolve the default <c>PublishAsPackageScript</c> runtime image from the build image.
    /// </summary>
    internal Func<string, string>? ResolvePackageScriptRuntimeImage { get; init; }
 
    /// <summary>
    /// Gets the build image to use when the resource has no explicit build image configured.
    /// </summary>
    /// <remarks>
    /// Package managers such as bun and deno are not present in the default Node.js base images, so Dockerfile
    /// generation must fall back to a runtime-specific image rather than the Node.js default. This is consulted
    /// after <see cref="DockerfileBaseImageAnnotation.BuildImage"/> so that a caller-supplied build image always
    /// wins, and it covers the case where the caller configured only a runtime image.
    /// </remarks>
    internal string? DefaultBuildImage { get; init; }
}