Add front-door delegation to the Node tool + document composition

- With autoRunNode, `version` in a repo with no .NET projects now delegates
  entirely to the Node tool, so net-as-`changeset` transparently handles
  Node-only repos (the interop + autoRunNode post-pass already covers mixed).
- Loop guard via an inherited env marker so a nodeChangesetCommand that
  resolves back to net cannot recurse forever.
- README: "Using alongside @changesets (Node)" with the composition
  principle, a CLI/repo chart, the front-door config, and per-shell
  `changeset-net` setup instructions (zsh/bash/pwsh).
- Delegation parity test + changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: JohnCampionJr

.changeset/front-door-delegation.md

@@ -0,0 +1,5 @@
+---
+"SolarWinds.Changesets": Minor
+---
+
+Make net-changesets a front door to the Node `@changesets` tool. With `autoRunNode` enabled, `version` in a repository with no .NET projects (for example a Node-only repo where `changeset` resolved to net) now delegates entirely to the Node tool instead of just reporting nothing to do — so a single `changeset version` works whether the repo is .NET, Node, or both. A loop guard (an inherited environment marker) prevents infinite recursion if `nodeChangesetCommand` is misconfigured to point back at net. The README now documents how the two tools compose.

README.md

@@ -47,19 +47,62 @@ intentional gaps:
 ## Using alongside @changesets (Node)
 
 net-changesets installs the `changeset` command — the same name as the Node `@changesets` CLI. When both are
-installed globally, whichever comes first on your `PATH` wins, and a .NET tool can expose only one command, so
-there is no built-in second name. To always reach net-changesets regardless of `PATH`, add its `changeset-net`
-shell function:
+installed globally, whichever comes first on your `PATH` wins. A .NET tool can expose only one command, so
+there is no built-in second name.
 
-```bash
-# zsh (~/.zshrc) — bash and pwsh are also supported
+**The key principle: net-changesets can drive the Node tool, but the Node tool cannot drive net-changesets.**
+So in a polyglot repo, let net-changesets own `changeset` and act as the front door — it versions your .NET
+projects and then runs the Node tool for the rest. Enable that in `.changeset/config.json`:
+
+```json
+{
+  "dotnet": { "interop": true, "autoRunNode": true }
+}
+```
+
+With `autoRunNode`, `changeset version` versions the .NET side and then invokes the Node tool
+(`nodeChangesetCommand`, default `npx changeset`); in a repo with no .NET projects it delegates to the Node
+tool entirely. net never deletes a Node changeset it didn't process.
+
+### How it composes
+
+| Repository | `changeset` runs… | What happens |
+| --- | --- | --- |
+| **.NET only** | net | Versions your .NET projects. ✅ |
+| **.NET only** | Node | Node finds no packages — run `changeset-net` instead. |
+| **Node only** | net | With `autoRunNode`, net delegates to the Node tool ✅; otherwise it points you to the Node tool and leaves changesets untouched. |
+| **Node only** | Node | Versions your Node packages. ✅ |
+| **Both** | net | Versions .NET, then runs the Node tool (`interop` + `autoRunNode`) ✅; without interop it versions .NET and keeps Node-only changesets for the Node tool. |
+| **Both** | Node | Versions Node packages only — run `changeset-net version` for the .NET side. |
+
+### Reaching net directly: `changeset-net`
+
+When the Node tool owns `changeset` (it's first on your `PATH`), add net-changesets' `changeset-net` shell
+function so you can always invoke net regardless of `PATH`. Add the line for your shell to its startup file,
+then restart the shell (or re-source the file):
+
+**zsh** — add to `~/.zshrc`:
+
+```zsh
 eval "$(changeset shell-init zsh)"
 ```
 
-`changeset shell-init <shell>` prints the snippet; run `changeset shell-init` for setup instructions. In a
-polyglot repo the smoothest setup is to let net-changesets own `changeset` (it leaves Node changesets untouched
-and guides you to the Node tool when there are no .NET projects), using `changeset-net` only when the Node tool
-owns `changeset`.
+**bash** — add to `~/.bashrc` (on macOS, `$HOME/.bash_profile`):
+
+```bash
+eval "$(changeset shell-init bash)"
+```
+
+**PowerShell** — add to your `$PROFILE` (open it with `notepad $PROFILE`, creating it if prompted):
+
+```powershell
+Invoke-Expression (& changeset shell-init pwsh | Out-String)
+```
+
+The line is evaluated by whichever `changeset` runs first on your `PATH`. If that's the Node tool, replace
+`changeset` in the line with the full path to net's binary (typically `~/.dotnet/tools/changeset`, or
+`%USERPROFILE%\.dotnet\tools\changeset` on Windows). Running `changeset shell-init` with no shell prints these
+instructions with the resolved path already filled in.
 
 ## Documentation
 

src/SolarWinds.Changesets/Commands/Version/VersionChangesetCommand.cs

@@ -89,11 +89,17 @@ public override async Task<int> ExecuteCommandAsync(CommandContext context, Vers
 
         CsProject[] csProjects = _csProjFileHelper.GetCsProjects(ChangesetConfig);
 
-        // No .NET projects: net-changesets has nothing to version. Guide the user rather than silently doing
-        // nothing - this is the case where the shared `changeset` command resolved to net inside a Node (or
-        // misconfigured) repository. The changesets are left untouched.
+        // No .NET projects: net-changesets has nothing to version. This is the case where the shared
+        // `changeset` command resolved to net inside a Node (or misconfigured) repository. As a front door,
+        // delegate to the Node tool when autoRunNode is set; otherwise guide the user and leave changesets be.
         if (csProjects.Length == 0)
         {
+            if (ChangesetConfig.AutoRunNode && NotAlreadyDelegated && !snapshot && !inPreMode && !exiting)
+            {
+                _console.WriteLine("No .NET projects found; delegating to the Node changeset tool.");
+                return await RunNodeVersionAsync();
+            }
+
             WarnNoDotnetProjects();
 
             if (exiting)
@@ -177,14 +183,21 @@ await _changesetsRepository.CleanupProcessedChangesetsAsync(
 
         _console.WriteLine(message);
 
-        if (ChangesetConfig.Interop && ChangesetConfig.AutoRunNode && !snapshot && !inPreMode && !exiting)
+        if (ChangesetConfig.Interop && ChangesetConfig.AutoRunNode && NotAlreadyDelegated && !snapshot && !inPreMode && !exiting)
         {
             return await RunNodeVersionAsync();
         }
 
         return 0;
     }
 
+    // Set on the child environment when net delegates to (or auto-runs) the Node tool, so that a
+    // nodeChangesetCommand mistakenly pointing back at net is caught instead of recursing forever.
+    private const string DelegationGuardVariable = "NET_CHANGESETS_DELEGATED";
+
+    private static bool NotAlreadyDelegated =>
+        Environment.GetEnvironmentVariable(DelegationGuardVariable) is not "1";
+
     private async Task ApplySnapshotVersionsAsync(List<ModuleChangelog> changelogs, VersionChangesetCommandSettings settings)
     {
         string? template = settings.SnapshotPrereleaseTemplate ?? ChangesetConfig.Snapshot.PrereleaseTemplate;
@@ -304,6 +317,9 @@ private void DeleteOwnedChangesets(ChangesetFile[] changesets, CsProject[] csPro
 
     private async Task<int> RunNodeVersionAsync()
     {
+        // Inherited by the Node process; breaks the loop if nodeChangesetCommand resolves back to net.
+        Environment.SetEnvironmentVariable(DelegationGuardVariable, "1");
+
         _console.WriteLine($"Running '{ChangesetConfig.NodeChangesetCommand} version' for the Node packages...");
 
         ProcessOutput result = await _nodeChangesetService.RunAsync(

src/SolarWinds.Changesets/Shared/DotnetConfig.cs

@@ -45,12 +45,17 @@ internal sealed class DotnetConfig
     public string ChangesetExtension { get; init; } = ".net.mkd";
 
     /// <summary>
-    /// When <see cref="Interop"/> is on, run the Node <c>@changesets</c> tool after net-changesets' own pass,
-    /// so a single command drives the whole release.
+    /// Make net-changesets a front door to the Node <c>@changesets</c> tool: it runs the Node tool as part of
+    /// its own commands, so a single <c>changeset</c> invocation drives the whole release.
     /// </summary>
     /// <remarks>
-    /// Default is <c>false</c>. When <c>true</c>, <c>version</c> shells out to <see cref="NodeChangesetCommand"/>
-    /// after processing the .NET side, which also guarantees net-changesets runs before the Node tool.
+    /// Default is <c>false</c>. When <c>true</c>: with <see cref="Interop"/> on and .NET projects present,
+    /// <c>version</c> shells out to <see cref="NodeChangesetCommand"/> after processing the .NET side (so net
+    /// runs before the Node tool); when there are no .NET projects (for example a Node-only repository where
+    /// <c>changeset</c> resolved to net), <c>version</c> delegates entirely to the Node tool. Do not set
+    /// <see cref="NodeChangesetCommand"/> to a bare <c>changeset</c> that resolves back to net - use
+    /// <c>npx changeset</c> (the default) or another command that targets the Node tool; net guards against an
+    /// accidental loop but a distinct command is clearer.
     /// </remarks>
     public bool AutoRunNode { get; init; }
 

tests/SolarWinds.Changesets.Tests/E2E/InteropTests.cs

@@ -162,6 +162,42 @@ public void Version_WithAutoRunNode_DrivesBothEcosystemsInOneCommand()
         ChangesetExists("shared.md").Should().BeFalse();
     }
 
+    [Test]
+    [Category("Parity")]
+    public void Version_NodeOnlyRepo_WithAutoRunNode_DelegatesToNode()
+    {
+        if (!NodeChangeset.IsAvailable)
+        {
+            Assert.Ignore("Node and/or the @changesets CLI are not available.");
+        }
+
+        // A Node-only repo (no .NET project) where `changeset` resolved to net. As a front door, net delegates.
+        Directory.CreateDirectory(Path.Combine(_repo, "packages", "web"));
+        File.WriteAllText(Path.Combine(_repo, "package.json"), """{ "name": "root", "private": true, "workspaces": ["packages/*"] }""");
+        File.WriteAllText(Path.Combine(_repo, "package-lock.json"), "{}");
+        File.WriteAllText(Path.Combine(_repo, "packages", "web", "package.json"), """{ "name": "@demo/web", "version": "1.0.0" }""");
+
+        WriteConfig($$"""
+            {
+              "baseBranch": "main",
+              "updateInternalDependencies": "patch",
+              "dotnet": {
+                "autoRunNode": true,
+                "nodeChangesetCommand": "node {{NodeChangeset.CliBinPath!.Replace("\\", "\\\\", StringComparison.Ordinal)}}"
+              }
+            }
+            """);
+        WriteChangeset("web.md", "\"@demo/web\": minor");
+
+        CliResult version = ChangesetCli.Run(_repo, "version");
+        version.ExitCode.Should().Be(0, version.Output);
+
+        // net found no .NET projects and delegated to the Node tool, which versioned the package and consumed it.
+        version.Output.Should().Contain("delegating to the Node changeset tool");
+        NodePackageVersion("web").Should().Be("1.1.0");
+        ChangesetExists("web.md").Should().BeFalse();
+    }
+
     private string? NodePackageVersion(string packageDirectory)
     {
         string json = File.ReadAllText(Path.Combine(_repo, "packages", packageDirectory, "package.json"));