Switch the machine's global tool during migration, and target the kept id

Two changes to what fallout-migrate does about the tool package id.

Point the migration at Fallout.GlobalTool. #581 settled on keeping the
NUKE-era id rather than moving to Fallout.GlobalTools, so the current id and
the retired list swap places:

  current:  fallout.globaltool
  retired:  nuke.globaltool, fallout.cli, fallout.globaltools

A consumer already pinning fallout.globaltool now migrates to nothing, which is
the point of keeping that id. Covered by a spec.

Add SwitchGlobalToolStep. Rewriting .config/dotnet-tools.json only fixes the
repo. A machine-wide install of a retired tool stays behind, and two packages
providing the `fallout` command conflict, so the repo-only fix left the machine
broken. The new step reads `dotnet tool list --global`, uninstalls each retired
id that is installed, then installs the current one at the resolved version.

It runs after RewriteToolManifestStep: repo first, so an interrupted run still
leaves the committed state correct. Every command is best-effort — no dotnet on
PATH, no global install, or an unreachable feed produces a Summary warning
naming the command to run by hand, never a failed migration. --dry-run prints
the commands without running them.

Introduces CliWrap (3.10.3, central pin) for the process calls: buffered output
and a cancellation token without hand-rolled ProcessStartInfo plumbing. Scoped
to Fallout.Migrate on purpose. Fallout.Common has its own ProcessTasks layer
that build authors consume, and that is not changing. Added to
docs/dependencies.md under a new Console / process section.

Also flips .config/dotnet-tools.json to fallout.globaltool 10.3.49. The pin
could not move while the id was Fallout.GlobalTools, because nothing was
published there above 10.4.0-rc.4. Verified: `dotnet tool restore` resolves it.

docs/migration/tool-package-id.md rewritten around the kept id. It is now a
"move off a retired id" page, and most readers need no action at all.

Verified: Fallout.Migrate.Specs 63/63; solution builds; dry-run against a
scratch repo pinning fallout.cli rewrites the manifest as expected.

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

Author: ChrisonSimtian

.config/dotnet-tools.json

@@ -2,8 +2,8 @@
   "version": 1,
   "isRoot": true,
   "tools": {
-    "fallout.globaltools": {
-      "version": "10.4.0-rc.4",
+    "fallout.globaltool": {
+      "version": "10.3.49",
       "commands": [
         "fallout"
       ]

Directory.Packages.props

@@ -10,6 +10,7 @@
     <PackageVersion Include="Azure.Security.KeyVault.Secrets" Version="4.8.0" />
     <PackageVersion Include="Basic.Reference.Assemblies.NetStandard20" Version="1.7.9" />
     <PackageVersion Include="BenchmarkDotNet" Version="0.14.0" />
+    <PackageVersion Include="CliWrap" Version="3.10.3" />
     <PackageVersion Include="Glob" Version="1.1.9" />
     <PackageVersion Include="HtmlAgilityPack" Version="1.11.71" />
     <PackageVersion Include="Humanizer" Version="3.0.1" />

README.md

@@ -64,7 +64,7 @@ The CLI installs as `fallout`. Verify with `fallout --help`.
 > dotnet tool uninstall -g Fallout.GlobalTools
 > ```
 >
-> If a repo pins the old id in `.config/dotnet-tools.json`, change the version too — the pin you have does not exist under the new id. `fallout-migrate` does both. See [Fallout.GlobalTool → Fallout.GlobalTools](docs/migration/tool-package-id.md).
+> Same for a repo that pins a retired id in `.config/dotnet-tools.json`: change the version along with the id, because the pin you have does not exist under `Fallout.GlobalTool`. `fallout-migrate` does both, and switches your global install too. See [Moving off a retired tool package id](docs/migration/tool-package-id.md).
 
 For per-repo manifest pinning (`.config/dotnet-tools.json`), project setup, and shell completion, see the [Installation guide on docs.fallout.build](https://docs.fallout.build/getting-started/installation).
 

docs/dependencies.md

@@ -64,6 +64,13 @@ Central package versions are pinned in `Directory.Packages.props`; this page lin
 |---|---|
 | `NuGet.Packaging` | Read .nupkg metadata. Used by `NuGetVersionResolver`, `ProjectUpdater`. |
 
+## Console / process
+
+| Package | Purpose | Used by |
+|---|---|---|
+| `Spectre.Console` (+ `.Cli`) | Console rendering and command-line parsing | `Fallout.Migrate` |
+| `CliWrap` | Run an external process and buffer its output, with a cancellation token and no manual `ProcessStartInfo` plumbing | `Fallout.Migrate` — `SwitchGlobalToolStep` shells out to `dotnet tool`. Deliberately not used in `Fallout.Common`, which has its own `ProcessTasks` layer that build authors consume. |
+
 ## Vendored source
 
 | Package | Source | Why vendored |

docs/introduction.md

@@ -18,7 +18,7 @@ description: Fallout is a C#-first build automation framework for .NET — the h
 
 ```powershell
 # terminal-command
-dotnet tool install Fallout.GlobalTools --global
+dotnet tool install Fallout.GlobalTool --global
 ```
 
 **2. Go to a repository of your choice and set up a build:**

docs/migration/tool-package-id.md

@@ -1,54 +1,55 @@
 ---
-title: Fallout.GlobalTool → Fallout.GlobalTools
-description: The dotnet-tool NuGet package id changed. The fallout command did not. This page shows how to move an existing install or manifest.
+title: Moving off a retired tool package id
+description: The Fallout CLI ships as Fallout.GlobalTool. Three other package ids were used along the way and are now retired. This page shows how to move an install or a manifest onto the current one.
 ---
 
-The dotnet-tool NuGet package id is now **`Fallout.GlobalTools`**. The **command stays `fallout`**, so
-build scripts, CI steps, and shell invocations do not change. Only the install or restore reference
-moves.
+The Fallout CLI ships as **`Fallout.GlobalTool`**. This is the same package id NUKE users have had
+pinned since the rebrand, so most readers have nothing to do.
 
-If you have never installed the tool, you do not need this page. Follow
-[Installation](../01-getting-started/01-installation.md).
+Three other ids were used along the way and are now retired. If you pin one of them, this page shows
+how to move. The **command stays `fallout`** in every case, so build scripts, CI steps, and shell
+invocations do not change. Only the install or restore reference moves.
 
-## Why you need to act
+## Do you need to act?
 
-The older package ids are still on nuget.org, still listed, and frozen. `dotnet tool update` on an old
-id reports that you are already on the latest version, because you are — for that id. The newer
-releases are published under the new id.
+Run `dotnet tool list --global`, and open `.config/dotnet-tools.json` if your repo has one.
 
-| Package id | Last version | Status |
-|---|---|---|
-| `Nuke.GlobalTool` | NUKE-era | Frozen. Not a Fallout package. |
-| `Fallout.GlobalTool` | `10.3.49` | Frozen. Receives no further releases. |
-| `Fallout.Cli` | `10.3.47`, `11.0.18` | Frozen. The `11.0.x` line was withdrawn; see [v11 is defunct](#a-note-on-the-110x-versions). |
-| **`Fallout.GlobalTools`** | current | **Active. All future tool releases.** |
+| Package id | Status |
+|---|---|
+| **`Fallout.GlobalTool`** | **Current. All releases. Nothing to do.** |
+| `Nuke.GlobalTool` | Retired. The NUKE-era id, not a Fallout package. |
+| `Fallout.Cli` | Retired. The `11.0.x` line was withdrawn; see [the note below](#a-note-on-the-110x-versions). |
+| `Fallout.GlobalTools` | Retired. Note the trailing **s**. One prerelease, `10.4.0-rc.4`. |
 
 `rollForward: true` in your manifest does not help. It resolves a version *within* one package id, so
 it cannot move you to a different id.
 
 ## The easy way
 
-`fallout-migrate` rewrites the manifest for you, including the version pin:
+`fallout-migrate` rewrites the manifest for you, including the version pin, and switches your global
+install:
 
 ```sh
 dotnet tool install -g Fallout.Migrate
 fallout-migrate .
 ```
 
+Run it with `--dry-run` first if you want to see the commands it would run without running them.
+
 ## Local manifest, by hand
 
 Open `.config/dotnet-tools.json`. Change the tool id **and the version**. The version you had pinned
-belongs to the old id and does not exist under the new one, so renaming the key alone gives you a
-manifest that fails to restore.
+belongs to the retired id and does not exist under the current one, so renaming the key alone gives
+you a manifest that fails to restore.
 
 ```diff
  {
    "version": 1,
    "isRoot": true,
    "tools": {
--    "fallout.globaltool": {
--      "version": "10.3.49",
-+    "fallout.globaltools": {
+-    "fallout.cli": {
+-      "version": "11.0.18",
++    "fallout.globaltool": {
 +      "version": "<current version>",
        "commands": [ "fallout" ]
      }
@@ -62,15 +63,15 @@ Then restore:
 dotnet tool restore
 ```
 
-`dotnet tool list` should show a `fallout.globaltools` row and no `fallout.globaltool` row.
+`dotnet tool list` should show a `fallout.globaltool` row and no row for the retired id.
 
 ## Global install, by hand
 
-Uninstall the old package first. Two tools claiming the `fallout` command will conflict.
+Uninstall the retired package first. Two tools claiming the `fallout` command will conflict.
 
 ```sh
-dotnet tool uninstall -g Fallout.GlobalTool
-dotnet tool install -g Fallout.GlobalTools
+dotnet tool uninstall -g Fallout.Cli
+dotnet tool install -g Fallout.GlobalTool
 ```
 
 `dotnet tool list -g` confirms the result.
@@ -92,3 +93,5 @@ from `10.x` to calendar versioning without a v11 line. Do not pin `11.0.x`.
 ## Refs
 
 - [#575](https://github.com/Fallout-build/Fallout/issues/575) — the upgrade path this page documents.
+- [#581](https://github.com/Fallout-build/Fallout/pull/581) — settled on `Fallout.GlobalTool` as the id to keep.
+- [#582](https://github.com/Fallout-build/Fallout/issues/582) — the rule that stops this happening again.

src/Fallout.Migrate/Common/MigrationContext.cs

@@ -28,7 +28,7 @@ internal sealed class MigrationContext(AbsolutePath rootDirectory, bool dryRun,
     public string FalloutVersion { get; internal set; }
 
     /// <summary>
-    /// The version to pin for the <c>fallout.globaltools</c> dotnet tool in a rewritten
+    /// The version to pin for the <c>fallout.globaltool</c> dotnet tool in a rewritten
     /// <c>dotnet-tools.json</c>, or <c>null</c> when it could not be resolved. Tracked separately from
     /// <see cref="FalloutVersion"/> because the tool ships under its own package id, which was
     /// introduced later and so has a different set of published versions (#575). Set by

src/Fallout.Migrate/Fallout.Migrate.csproj

@@ -16,6 +16,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="CliWrap" />
     <PackageReference Include="JetBrains.Annotations" />
     <PackageReference Include="Spectre.Console.Cli" />
   </ItemGroup>

src/Fallout.Migrate/Migration.cs

@@ -20,7 +20,10 @@ internal sealed class Migration(AbsolutePath rootDirectory, bool dryRun, TextWri
     /// <summary>
     /// The steps executed by <see cref="RunAsync"/>, in order. <see cref="ResolveFalloutVersionStep"/> must
     /// run first, since later steps read <see cref="MigrationContext.FalloutVersion"/> and
-    /// <see cref="MigrationContext.ToolVersion"/> from it.
+    /// <see cref="MigrationContext.ToolVersion"/> from it. <see cref="SwitchGlobalToolStep"/> runs
+    /// after <see cref="RewriteToolManifestStep"/>: the manifest rewrite fixes the repo, the switch
+    /// fixes the machine, and doing the repo first means an interrupted run still leaves the
+    /// committed state correct.
     /// </summary>
     private static readonly IReadOnlyList<IMigrationStep> steps =
     [
@@ -33,6 +36,7 @@ internal sealed class Migration(AbsolutePath rootDirectory, bool dryRun, TextWri
         new RewriteBootstrapScriptsStep(),
         new CleanupBootstrapScriptsStep(),
         new RewriteToolManifestStep(),
+        new SwitchGlobalToolStep(),
         new RenameNukeDirectoryStep()
     ];
 

src/Fallout.Migrate/Steps/ResolveFalloutVersionStep.cs

@@ -44,7 +44,7 @@ internal sealed class ResolveFalloutVersionStep : IMigrationStep
     /// from <see cref="PackageId"/>: the tool id was introduced later, so it has its own, much
     /// shorter, set of published versions (#575).
     /// </summary>
-    private const string ToolPackageId = "fallout.globaltools";
+    private const string ToolPackageId = RewriteToolManifestStep.CurrentToolId;
 
     private static readonly HttpClient httpClient = CreateHttpClient();