[P5] Build Fallout.Migrate CLI tool — automated NUKE → Fallout repo migration

[ChrisonSimtian]

Implementation issue spun off from #35 (bridge strategy).

Goal

Ship a dotnet tool that migrates an existing NUKE consumer repo to Fallout in one command:

dotnet tool install -g Fallout.Migrate
cd path/to/my-nuke-repo
fallout-migrate

After the tool exits, ./build.ps1 should compile and run identically against Fallout.

What it must do

Step	Action
1	Detect _build.csproj (or equivalent build orchestrator project)
2	Rewrite PackageReference Include="Nuke.*" → Fallout.*
3	Rewrite using Nuke.* directives → using Fallout.* across all .cs files
4	Rewrite attribute references where namespace import differs ([GitHubActions(...)] etc.)
5	Rewrite bootstrap scripts: dotnet nuke → dotnet fallout in build.ps1, build.sh, build.cmd
6	Detect .nuke/ directory and (depending on the [P2] decision in #29) leave it, rename it, or migrate config
7	Detect CI YAML files generated by NUKE and offer to regenerate (don't auto-rewrite — they're idempotent on next Fallout build)
8	Print a summary: files changed, manual follow-ups needed, link to migration guide (#37)

Non-goals

• Not a general C# refactor tool — scope limited to NUKE → Fallout migration patterns.
• Not a replacement for the Roslyn codefix ([P5] Build Roslyn codefix for Nuke.* → Fallout.* using directives #36) — the codefix is for in-IDE per-file fixes; this CLI is for whole-repo bulk migration.
• Not a replacement for the shim packages — the CLI does a clean cutover; shims are for projects that can't migrate yet.

Implementation approach

• New project: source/Fallout.Migrate/Fallout.Migrate.csproj, packaged as <PackAsTool>true</PackAsTool>.
• Reuse the existing Cake-rewriting infrastructure in source/Nuke.GlobalTool/Rewriting/Cake/ as a template — it already does AST-level rewrites with Roslyn.
• Test fixtures: a tests/ directory of mock "pre-migration NUKE repos" and their expected post-migration state. Verify via Verify.Xunit snapshots, matching the rest of the project's testing conventions.

Done when

• CLI builds and packs as a dotnet tool
• Migrates a vanilla _build.csproj (DotNet only) test fixture cleanly
• Migrates a complex multi-CI test fixture (GitHub Actions + custom attributes) cleanly
• Tested on a real external NUKE consumer repo (volunteer needed)
• Published to GitHub Packages
• Linked from [P5] Write NUKE → Fallout migration guide #37 migration guide

Dependencies

• Blocked by [P3] Plan: Nuke.* → Fallout.* namespace mapping #31 (namespace mapping locked — strict 1:1, done)
• Blocked by [P3] Execute solution-wide Nuke.* → Fallout.* namespace rename (BREAKING) #32 (Fallout.* namespaces actually exist before the CLI can target them)
• Blocked by [P4] Reserve Fallout.* package IDs on nuget.org #33, [P4] Rename .csproj files and project references (BREAKING) #34 (package IDs reserved, .csproj filenames renamed)
• Should ship alongside or before the first Fallout.* release on GitHub Packages

[ChrisonSimtian]

Scope adjustment (2026-05-19)

Per the revised bridge strategy on #35 and the rewrite of #47, PackageReference rewriting is no longer the default path. Consumers can stay on Nuke.<X> IDs by adding our GitHub Packages feed and bumping the version.

Updated tool behavior

Default fallout-migrate run, in order of how aggressive each step is:

Default	Step	Notes
✅	Detect _build.csproj (or equivalent)	required
✅	Patch nuget.config to add the GitHub Packages feed for ChrisonSimtian/Fallout	required for the bridge to resolve
✅	Bump <PackageReference Include="Nuke.*" Version="11.0.0" /> to the latest Fallout-release version	this is enough — Nuke.<X> 11.x is a shim that type-forwards to Fallout.<X>
✅	Rewrite bootstrap scripts: dotnet nuke → dotnet fallout in build.ps1, build.sh, build.cmd	global tool rename per #38
✅	Print summary + link to migration guide (#37)	required
--full-rename	Rewrite PackageReference Include="Nuke.*" → Fallout.*	hard cutover off the shim
--full-rename	Rewrite using Nuke.* → using Fallout.* across all .cs files	hard cutover
--full-rename	Rewrite attribute references where namespace import differs	hard cutover
--full-rename	Handle .nuke/ directory (per #29 decision)	hard cutover

So the default is the soft migration — feed + version bump + bootstrap rename. The --full-rename flag opts into the hard cutover that drops the Nuke.<X> shim and goes native Fallout.<X>.

Implications

• The hard-cutover path is still implemented identically to the original plan, just behind a flag.
• The soft-migration path needs new logic: NuGet feed editing, version detection of latest Fallout release.
• Test fixtures should cover both paths.
• The migration guide ([P5] Write NUKE → Fallout migration guide #37) should document soft migration as the recommended starting point, with hard cutover as the "once you're ready" follow-up.

[ChrisonSimtian]

MVP shipped in #68 — kept this issue open for the deferred items.

Done:

• CLI builds and packs as a `dotnet tool` (will appear on nuget.org via next release)
• Migrates a vanilla `_build.csproj` (DotNet only) test fixture cleanly
• Migrates a complex multi-CI test fixture (GitHub Actions + custom attributes) cleanly — via the in-test fixtures
• 17 unit + integration tests covering each rewriter and end-to-end

Still open:

• Tested on a real external NUKE consumer repo (volunteer needed — e.g. `ChrisonSimtian/ErpForFactoryGames`)
• Published to GitHub Packages — should happen automatically via the release pipeline on the next push to main; verify after that
• Linked from [P5] Write NUKE → Fallout migration guide #37 migration guide once that exists

Approach notes: shipped regex-based, not Roslyn — vanilla consumer repos don't need AST-level smarts. Architecture splits cleanly per rewriter class (`CsprojRewriter`, `CodeRewriter`, `ScriptRewriter`, directory rename) so we can swap to Roslyn behind the same interface if real-world repos surface cases regex can't handle.

[ChrisonSimtian]

Verified end-to-end against a synthetic NUKE consumer fixture (multi-using Build.cs with : NukeBuild, [Parameter]/[Secret]/[Solution]/[CI] attrs, component interfaces, fully-qualified type refs, the Target X => _ => _ DSL, [GitHubActions] attribute; plus _build.csproj with <NukeRootDirectory> and two Nuke.* PackageReferences; plus build.sh/build.ps1/build.cmd with dotnet nuke and NUKE_TELEMETRY_OPTOUT; plus .nuke/parameters.json).

Results:

• 25 edits across 5 files, 1 directory renamed (.nuke → .fallout)
• Zero remaining Nuke. references in any file post-migration
• --dry-run correctly counts edits without writing
• Help/exit-code paths exercised
• Existing tests/Fallout.Migrate.Tests/MigrationIntegrationTest.cs already snapshot-tests the rewrite logic

Closing as done. Any consumer-side issues that surface in the wild become new tickets.