Refactor NodeJs Integration (#12530)

* Refactor JavaScript Integration

- Obsolete AddNpmApp.
- Add JavaScriptAppResource and AddJavaScriptApp extension method
- Refactor AddViteApp to be a specialization of AddJavaScriptApp
- Replace NodeInstallerResource with JavaScriptInstallerResource
- Add JavaScriptPackageManagerAnnotation to handle different package managers
- Replace JavaScriptRunCommandAnnotation with JavaScriptRunScriptAnnotation
- Replace JavaScriptBuildCommandAnnotation with JavaScriptBuildScriptAnnotation

Contributes to #8350

* Default install command args in publish mode.

* Only use clean installs when the lock file exists in publish mode.

* Address copilot feedback

* More PR feedback

* Fix PublishAsDockerFile to always clear the args when it is called, even if it is called a second time.

* Update npm install command comment in AppHost.cs

Clarified npm install command requirement for clean install.

---------

Co-authored-by: David Fowler <davidfowl@gmail.com>

Author: eerhardt

playground/AspireWithJavaScript/AspireJavaScript.AppHost/AppHost.cs

@@ -3,33 +3,30 @@
 var weatherApi = builder.AddProject<Projects.AspireJavaScript_MinimalApi>("weatherapi")
     .WithExternalHttpEndpoints();
 
-builder.AddNpmApp("angular", "../AspireJavaScript.Angular")
-    .WithNpm(install: true)
+builder.AddJavaScriptApp("angular", "../AspireJavaScript.Angular")
     .WithReference(weatherApi)
     .WaitFor(weatherApi)
     .WithHttpEndpoint(env: "PORT")
     .WithExternalHttpEndpoints()
     .PublishAsDockerFile();
 
-builder.AddNpmApp("react", "../AspireJavaScript.React")
-    .WithNpm(install: true)
+builder.AddJavaScriptApp("react", "../AspireJavaScript.React")
     .WithReference(weatherApi)
     .WaitFor(weatherApi)
     .WithEnvironment("BROWSER", "none") // Disable opening browser on npm start
     .WithHttpEndpoint(env: "PORT")
     .WithExternalHttpEndpoints()
     .PublishAsDockerFile();
 
-builder.AddNpmApp("vue", "../AspireJavaScript.Vue")
-    .WithInstallCommand("npm", ["ci"]) // Use 'npm ci' for clean install
+builder.AddJavaScriptApp("vue", "../AspireJavaScript.Vue")
+    .WithNpm(installCommand: "ci") // Use 'npm ci' for clean install, requires lock file
     .WithReference(weatherApi)
     .WaitFor(weatherApi)
     .WithHttpEndpoint(env: "PORT")
     .WithExternalHttpEndpoints()
     .PublishAsDockerFile();
 
 var reactvite = builder.AddViteApp("reactvite", "../AspireJavaScript.Vite")
-    .WithNpm(install: true)
     .WithReference(weatherApi)
     .WithEnvironment("BROWSER", "none")
     .WithExternalHttpEndpoints();

playground/AspireWithNode/AspireWithNode.AppHost/AppHost.cs

@@ -10,7 +10,7 @@
 
 var weatherapi = builder.AddProject<Projects.AspireWithNode_AspNetCoreApi>("weatherapi");
 
-var frontend = builder.AddNpmApp("frontend", "../NodeFrontend", "watch")
+var frontend = builder.AddJavaScriptApp("frontend", "../NodeFrontend", "watch")
     .WithReference(weatherapi)
     .WaitFor(weatherapi)
     .WithReference(cache)

src/Aspire.Hosting.NodeJs/JavaScriptAppResource.cs

@@ -0,0 +1,15 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting;
+
+/// <summary>
+/// A resource that represents a JavaScript application.
+/// </summary>
+/// <param name="name">The name of the resource.</param>
+/// <param name="command">The command to execute.</param>
+/// <param name="workingDirectory">The working directory to use for the command.</param>
+public class JavaScriptAppResource(string name, string command, string workingDirectory)
+    : ExecutableResource(name, command, workingDirectory), IResourceWithServiceDiscovery, IResourceWithContainerFiles;

src/Aspire.Hosting.NodeJs/JavaScriptBuildCommandAnnotation.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.NodeJs;
+
+/// <summary>
+/// Represents the annotation for the JavaScript package manager's build script.
+/// </summary>
+/// <param name="scriptName">The name of the JavaScript package manager's build script.</param>
+/// <param name="args">The command line arguments for the JavaScript package manager's build script.</param>
+public sealed class JavaScriptBuildScriptAnnotation(string scriptName, string[]? args) : IResourceAnnotation
+{
+    /// <summary>
+    /// Gets the name of the script used to build.
+    /// </summary>
+    public string ScriptName { get; } = scriptName;
+
+    /// <summary>
+    /// Gets the command-line arguments supplied to the build script.
+    /// </summary>
+    public string[] Args { get; } = args ?? [];
+}

src/Aspire.Hosting.NodeJs/JavaScriptBuildScriptAnnotation.cs

@@ -8,17 +8,14 @@ namespace Aspire.Hosting.NodeJs;
 /// <summary>
 /// Represents the annotation for the JavaScript package manager's install command.
 /// </summary>
-/// <param name="command">The executable command name</param>
-/// <param name="args">The command line arguments for the JavaScript package manager's install command.</param>
-public sealed class JavaScriptInstallCommandAnnotation(string command, string[] args) : IResourceAnnotation
+/// <param name="args">
+/// The command line arguments for the JavaScript package manager's install command.
+/// This includes the command itself (i.e. "install").
+/// </param>
+public sealed class JavaScriptInstallCommandAnnotation(string[] args) : IResourceAnnotation
 {
     /// <summary>
-    /// Gets the executable command name.
-    /// </summary>
-    public string Command { get; } = command;
-
-    /// <summary>
-    /// Gets the command-line arguments supplied to the application.
+    /// Gets the command-line arguments supplied to the JavaScript package manager.
     /// </summary>
     public string[] Args { get; } = args;
 }

src/Aspire.Hosting.NodeJs/JavaScriptInstallCommandAnnotation.cs

@@ -6,9 +6,9 @@
 namespace Aspire.Hosting.NodeJs;
 
 /// <summary>
-/// A resource that represents a package installer for a node app.
+/// A resource that represents a package installer for a JavaScript app.
 /// </summary>
 /// <param name="name">The name of the resource.</param>
 /// <param name="workingDirectory">The working directory to use for the command.</param>
-public class NodeInstallerResource(string name, string workingDirectory)
+public class JavaScriptInstallerResource(string name, string workingDirectory)
     : ExecutableResource(name, "node", workingDirectory);

src/Aspire.Hosting.NodeJs/NodeInstallerResource.cs renamed to src/Aspire.Hosting.NodeJs/JavaScriptInstallerResource.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.NodeJs;
+
+/// <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>
+public sealed class JavaScriptPackageManagerAnnotation(string executableName, string? runScriptCommand) : 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;
+}

src/Aspire.Hosting.NodeJs/JavaScriptPackageManagerAnnotation.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.NodeJs;
+
+/// <summary>
+/// Represents the annotation for the script used during run mode in a JavaScript resource.
+/// </summary>
+/// <param name="scriptName">The name of the JavaScript package manager's run script.</param>
+/// <param name="args">The command line arguments for the JavaScript package manager's run script.</param>
+public sealed class JavaScriptRunScriptAnnotation(string scriptName, string[]? args) : IResourceAnnotation
+{
+    /// <summary>
+    /// Gets the name of the script to run.
+    /// </summary>
+    public string ScriptName { get; } = scriptName;
+
+    /// <summary>
+    /// Gets the command-line arguments for the script.
+    /// </summary>
+    public string[] Args { get; } = args ?? [];
+}