Add integration tests and documentation for resource-based package installers

Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com>

Author: Copilot

src/CommunityToolkit.Aspire.Hosting.NodeJS.Extensions/REFACTORING_NOTES.md

@@ -0,0 +1,107 @@
+# Node.js Package Installer Refactoring
+
+This refactoring transforms the Node.js package installers from lifecycle hooks to ExecutableResource-based resources, addressing issue #732.
+
+## What Changed
+
+### Before (Lifecycle Hook Approach)
+- Package installation was handled by lifecycle hooks during `BeforeStartAsync`
+- No visibility into installation progress in the dashboard
+- Limited logging capabilities
+- Process management handled manually via `Process.Start`
+
+### After (Resource-Based Approach)
+- Package installers are now proper `ExecutableResource` instances
+- They appear as separate resources in the Aspire dashboard
+- Full console output visibility and logging
+- DCP (Distributed Application Control Plane) handles process management
+- Parent-child relationships ensure proper startup ordering
+
+## New Resource Classes
+
+### NpmInstallerResource
+```csharp
+var installer = new NpmInstallerResource("npm-installer", "/path/to/project", useCI: true);
+// Supports both 'npm install' and 'npm ci' commands
+```
+
+### YarnInstallerResource
+```csharp
+var installer = new YarnInstallerResource("yarn-installer", "/path/to/project");
+// Executes 'yarn install' command
+```
+
+### PnpmInstallerResource
+```csharp
+var installer = new PnpmInstallerResource("pnpm-installer", "/path/to/project");
+// Executes 'pnpm install' command
+```
+
+## Usage Examples
+
+### Basic Usage (No API Changes)
+```csharp
+var builder = DistributedApplication.CreateBuilder();
+
+// API remains the same - behavior is now resource-based
+var viteApp = builder.AddViteApp("frontend", "./frontend")
+    .WithNpmPackageInstallation(useCI: true);
+
+var backendApp = builder.AddYarnApp("backend", "./backend")
+    .WithYarnPackageInstallation();
+```
+
+### What Happens Under the Hood
+```csharp
+// This now creates:
+// 1. NodeAppResource named "frontend" 
+// 2. NpmInstallerResource named "frontend-npm-install" (child of frontend)
+// 3. WaitAnnotation on frontend to wait for installer completion
+// 4. ResourceRelationshipAnnotation linking installer to parent
+```
+
+## Benefits
+
+### Dashboard Visibility
+- Installer resources appear as separate items in the Aspire dashboard
+- Real-time console output from package installation
+- Clear status indication (starting, running, completed, failed)
+- Ability to re-run installations if needed
+
+### Better Resource Management
+- DCP handles process lifecycle instead of manual `Process.Start`
+- Proper resource cleanup and error handling
+- Integration with Aspire's logging and monitoring systems
+
+### Improved Startup Ordering
+- Parent resources automatically wait for installer completion
+- Failed installations prevent app startup (fail-fast behavior)
+- Clear dependency visualization in the dashboard
+
+### Development vs Production
+- Installers only run during development (excluded from publish mode)
+- No overhead in production deployments
+- Maintains backward compatibility
+
+## Migration Guide
+
+### For Users
+No changes required! The existing APIs (`WithNpmPackageInstallation`, `WithYarnPackageInstallation`, `WithPnpmPackageInstallation`) work exactly the same.
+
+### For Contributors
+The lifecycle hook classes are marked as `[Obsolete]` but remain functional for backward compatibility:
+- `NpmPackageInstallerLifecycleHook`
+- `YarnPackageInstallerLifecycleHook` 
+- `PnpmPackageInstallerLifecycleHook`
+- `NodePackageInstaller`
+
+These will be removed in a future version once all usage has migrated to the resource-based approach.
+
+## Testing
+
+Comprehensive test coverage includes:
+- Unit tests for installer resource properties and command generation
+- Integration tests for parent-child relationships
+- Cross-platform compatibility (Windows vs Unix commands)
+- Publish mode exclusion verification
+- Wait annotation and resource relationship validation

tests/CommunityToolkit.Aspire.Hosting.NodeJS.Extensions.Tests/IntegrationTests.cs

@@ -0,0 +1,94 @@
+using Aspire.Hosting.ApplicationModel;
+
+namespace CommunityToolkit.Aspire.Hosting.NodeJS.Extensions.Tests;
+
+/// <summary>
+/// Integration test that demonstrates the new resource-based package installer architecture.
+/// This shows how installer resources appear as separate resources in the application model.
+/// </summary>
+public class IntegrationTests
+{
+    [Fact]
+    public void ResourceBasedPackageInstallersAppearInApplicationModel()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        // Add multiple Node.js apps with different package managers
+        var viteApp = builder.AddViteApp("vite-app", "./frontend")
+            .WithNpmPackageInstallation(useCI: true);
+
+        var yarnApp = builder.AddYarnApp("yarn-app", "./backend")
+            .WithYarnPackageInstallation();
+
+        var pnpmApp = builder.AddPnpmApp("pnpm-app", "./admin")
+            .WithPnpmPackageInstallation();
+
+        using var app = builder.Build();
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+
+        // Verify all Node.js app resources are present
+        var nodeResources = appModel.Resources.OfType<NodeAppResource>().ToList();
+        Assert.Equal(3, nodeResources.Count);
+
+        // Verify all installer resources are present as separate resources
+        var npmInstallers = appModel.Resources.OfType<NpmInstallerResource>().ToList();
+        var yarnInstallers = appModel.Resources.OfType<YarnInstallerResource>().ToList();
+        var pnpmInstallers = appModel.Resources.OfType<PnpmInstallerResource>().ToList();
+
+        Assert.Single(npmInstallers);
+        Assert.Single(yarnInstallers);
+        Assert.Single(pnpmInstallers);
+
+        // Verify installer resources have expected names (would appear on dashboard)
+        Assert.Equal("vite-app-npm-install", npmInstallers[0].Name);
+        Assert.Equal("yarn-app-yarn-install", yarnInstallers[0].Name);
+        Assert.Equal("pnpm-app-pnpm-install", pnpmInstallers[0].Name);
+
+        // Verify parent-child relationships
+        foreach (var installer in npmInstallers.Cast<IResource>()
+            .Concat(yarnInstallers.Cast<IResource>())
+            .Concat(pnpmInstallers.Cast<IResource>()))
+        {
+            Assert.True(installer.TryGetAnnotationsOfType<ResourceRelationshipAnnotation>(out var relationships));
+            Assert.Single(relationships);
+            Assert.Equal("Parent", relationships.First().Relationship);
+        }
+
+        // Verify all Node.js apps wait for their installers
+        foreach (var nodeApp in nodeResources)
+        {
+            Assert.True(nodeApp.TryGetAnnotationsOfType<WaitAnnotation>(out var waitAnnotations));
+            Assert.Single(waitAnnotations);
+            
+            var waitedResource = waitAnnotations.First().Resource;
+            Assert.True(waitedResource is NpmInstallerResource ||
+                       waitedResource is YarnInstallerResource ||
+                       waitedResource is PnpmInstallerResource);
+        }
+    }
+
+    [Fact]
+    public void InstallerResourcesHaveCorrectExecutableConfiguration()
+    {
+        var builder = DistributedApplication.CreateBuilder();
+
+        var nodeApp = builder.AddNpmApp("test-app", "./test")
+            .WithNpmPackageInstallation(useCI: true);
+
+        using var app = builder.Build();
+        var appModel = app.Services.GetRequiredService<DistributedApplicationModel>();
+
+        var installer = Assert.Single(appModel.Resources.OfType<NpmInstallerResource>());
+
+        // Verify it's configured as an ExecutableResource
+        Assert.IsAssignableFrom<ExecutableResource>(installer);
+        
+        // Verify working directory matches parent
+        var parentApp = Assert.Single(appModel.Resources.OfType<NodeAppResource>());
+        Assert.Equal(parentApp.WorkingDirectory, installer.WorkingDirectory);
+
+        // Verify command arguments are configured
+        Assert.True(installer.TryGetAnnotationsOfType<CommandLineArgsCallbackAnnotation>(out var argsAnnotations) ||
+                   installer.TryGetAnnotationsOfType<CommandLineArgsAnnotation>(out var directArgs));
+    }
+}