diff --git a/CHANGELOG.md b/CHANGELOG.md index 691ffe67c..5c255d310 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Breaking changes +- **AES-GCM v2 secret format for `EncryptionUtility` — `parameters.json` encrypted values** (#214, closes #212). The secret-encryption scheme used by `fallout :secrets` is now AES-GCM with per-secret random salt + nonce and 600,000 PBKDF2-SHA256 iterations (OWASP 2023). Previous `v1:` (AES-CBC, static salt, 10,000 iterations, unauthenticated) values **continue to decrypt** — the `Decrypt` path dispatches on `v1:`/`v2:`/unprefixed-legacy. New `Encrypt` calls always emit `v2:`. + - **On-disk format**: `v2:base64(salt[16] || nonce[12] || tag[16] || ciphertext)`. `v1:` was `v1:base64(salt-as-iv || ciphertext)` with a static `"Ivan Medvedev"` salt. + - **Migration path**: existing `.fallout/parameters.json` files with `v1:` values stay readable. Re-running `fallout :secrets` to add or update **any** secret naturally re-encrypts that entry under `v2:` (existing `SaveSecrets` flow already calls `Encrypt` per value). A whole-file rekey command can be added if there's demand. + - **Mixed-version repos**: developers on Fallout < 11.0 pulling a `parameters.json` that contains `v2:` values from a teammate on 11.0+ get `Could not decrypt 'X' with provided password`. Upgrade direction is fine (`v1:` reads keep working); downgrade is not. + - **`Rfc2898DeriveBytes` constructor obsoletion (`SYSLIB0060`)** cleared — both legacy and current paths now use the static `Rfc2898DeriveBytes.Pbkdf2(...)`. No public-API impact; just stops the warning. + +- **`Fallout.GlobalTool` package renamed to `Fallout.Cli`** (#206). The dotnet-tool install command is now `dotnet tool install -g Fallout.Cli`. The CLI **command name stays `fallout`** — no script or invocation changes needed. + - **NuGet package ID changes**: `Fallout.GlobalTool` (frozen at 10.3.40, then unlisted) → `Fallout.Cli` (10.3.41 onward, then 11.0.x). + - **Project / assembly / namespace rename**: `src/Fallout.GlobalTool/` → `src/Fallout.Cli/`, `tests/Fallout.GlobalTool.Tests/` → `tests/Fallout.Cli.Tests/`, `namespace Fallout.GlobalTool[.*]` → `namespace Fallout.Cli[.*]` across 48 files. Internal types only — no public-API consumer breakage from the namespace rename itself. + - **Migration for consumers**: see [`docs/migration/from-globaltool-to-cli.md`](docs/migration/from-globaltool-to-cli.md). Short form: `dotnet tool uninstall -g Fallout.GlobalTool && dotnet tool install -g Fallout.Cli`, and in repos with a local manifest, edit `.config/dotnet-tools.json` to replace `fallout.globaltool` with `fallout.cli`. + - **Update-notification text** in `UpdateNotificationAttribute` already points at the new name, so existing `Fallout.GlobalTool` installs will prompt users toward `Fallout.Cli` on next run. + +- **Thin bootstrappers + `.config/dotnet-tools.json` manifest; `build.cmd` dropped** (#204, PR-B of #203). The per-repo `build.cmd`/`build.sh`/`build.ps1` shape changes substantially — and the `[GitHubActions]` generator now emits a different workflow shape downstream consumers will see on the next regen. + - **`build.cmd` is gone** from the canonical scaffold. `fallout :setup` no longer emits it. New repos get only `build.sh` + `build.ps1`. + - **`build.sh` / `build.ps1` are ~60-line thin shims**: provision dotnet (kept verbatim from the pre-existing block), `dotnet tool restore`, `exec dotnet fallout "$@"`. The `BUILD_PROJECT_FILE` / `BUILD_DIRECTORY` config + explicit `dotnet build` + `dotnet run --project` lines are gone — `Fallout.Cli`'s in-tool runner (added in #201) does that work now. + - **`.config/dotnet-tools.json`** is the new home of the pin. `fallout :setup` writes one with the tool pinned at the running CLI's own version. Skipped if one already exists (consumer may have other local tools pinned). + - **`[GitHubActions]` generator** (`Fallout.Common/CI/GitHubActions/Configuration/GitHubActionsRunStep.cs`): the single `run: ./{BuildCmdPath} {targets}` step is replaced with three steps — `actions/setup-dotnet@v4` (reads `global.json`), `dotnet tool restore`, `dotnet fallout {targets}`. Downstream consumers using `[GitHubActions(InvokedTargets = ...)]` see the new shape on next workflow regen. + - **`BuildCmdPath` property** on `GitHubActionsAttribute` is no longer consumed (the run-step no longer references it). The Azure Pipelines / AppVeyor / TeamCity / SpaceAutomation generators still fall back to a literal `"build.cmd"` if `BuildCmdPath` is unset — keeps those legacy providers functional for the demand-driven revival (#8) without forcing this repo to keep a `build.cmd`. + - **Migration**: existing repos can keep their fat bootstrappers and they'll work indefinitely (the bootstrapper does its own `dotnet build` + `dotnet run --project`, doesn't depend on the global tool). To adopt the new shape, re-run `fallout :setup --force` (or hand-edit the shims to match the new template). + - **Last-mile Newtonsoft removal — closes the #83 migration tree** (#119 STJ-6, #115 STJ-2 tail). Every Fallout source file is STJ-native; `Newtonsoft.Json.dll` survives in the closure only as a transitive of `NuGet.Packaging` and `Serilog.Formatting.Compact.Reader`. The `Newtonsoft.Json` `PackageVersion` is gone from `Directory.Packages.props` entirely. - **`GitHubActions.GitHubEvent` is now `JsonObject`** (was Newtonsoft `JObject`). Consumers that introspect the event payload need to swap `using Newtonsoft.Json.Linq` → `using System.Text.Json.Nodes` and update accessors (`["key"].Value()` → `["key"].GetValue()`, `Property(name)` → indexer, etc.). - **`Fallout.Utilities.Net` `HttpRequestExtensions.WithJsonContent` / `HttpResponseExtensions.GetBodyAsJson` defaults are STJ.** The `[Obsolete]`-marked Newtonsoft overloads (`JsonSerializerSettings` parameter, `JObject` return) are gone. `JsonSerializerOptions` overloads remain for explicit configuration; the parameterless default uses STJ with default options. `GetBodyAsJsonObject` returns `System.Text.Json.Nodes.JsonObject`. diff --git a/docs/migration/from-globaltool-to-cli.md b/docs/migration/from-globaltool-to-cli.md new file mode 100644 index 000000000..fb1fc27e7 --- /dev/null +++ b/docs/migration/from-globaltool-to-cli.md @@ -0,0 +1,96 @@ +--- +title: Fallout.GlobalTool → Fallout.Cli +description: Migrating from the renamed Fallout CLI NuGet package. Short guide — the command name didn't change, just the package ID. +--- + +In v11, the dotnet-tool NuGet package id was renamed: **`Fallout.GlobalTool` → `Fallout.Cli`**. The **command name stays `fallout`**, so build scripts and shell invocations don't change. The only thing that moves is the install/restore reference. + +> If you've never installed `Fallout.GlobalTool`, you don't need this page — install `Fallout.Cli` directly per the [Install section in the README](https://github.com/ChrisonSimtian/Fallout#install). + +## TL;DR + +**Global install:** + +```sh +dotnet tool uninstall -g Fallout.GlobalTool +dotnet tool install -g Fallout.Cli +``` + +**Local manifest (`.config/dotnet-tools.json`):** open the file, replace the `fallout.globaltool` entry with `fallout.cli`, restore. + +```diff + { + "version": 1, + "isRoot": true, + "tools": { +- "fallout.globaltool": { ++ "fallout.cli": { + "version": "11.0.0", + "commands": [ "fallout" ] + } + } + } +``` + +```sh +dotnet tool restore +``` + +That's it. `fallout :setup`, `fallout Compile`, etc. all work unchanged because the command name (`fallout`) is the same. + +## Why the rename + +`dotnet tool install Fallout.Cli` is easier to type and remember than `dotnet tool install Fallout.GlobalTool`. The "GlobalTool" suffix was a NUKE-era artefact distinguishing the dotnet-tool wrapper from the framework libraries — but every consumer's first encounter with the tool is at install-time, and `Fallout.Cli` is what they reach for naturally. + +The change is purely cosmetic at the NuGet metadata layer. No source-level API changed; the C# namespace inside the tool moved from `Fallout.GlobalTool.*` to `Fallout.Cli.*` but those types are `internal` so external consumers never referenced them. + +## Affected versions + +| Package | Last published | Status | +|---|---|---| +| `Fallout.GlobalTool` | `10.3.40` | Frozen on nuget.org. **Unlisted** as part of the v11 semver cleanup (see [#220](https://github.com/ChrisonSimtian/Fallout/pull/220)). Existing installs keep working; `dotnet tool update` won't find newer versions. | +| `Fallout.Cli` | `11.0.x` (current) | Active. Receives all future tool releases. | + +The `10.3.41` through `10.3.47` patch releases of `Fallout.Cli` are **also unlisted** — they shipped under a patch number that hid breaking changes, fixed by the v11 major bump. Pin to **`11.0.0`** or later. + +## Migration scenarios + +### You installed `Fallout.GlobalTool` globally on your machine + +```sh +dotnet tool uninstall -g Fallout.GlobalTool +dotnet tool install -g Fallout.Cli +``` + +`dotnet tool list -g` confirms only `Fallout.Cli` remains. The `fallout` command on your PATH now resolves to the renamed package. + +### Your repo has a local `.config/dotnet-tools.json` manifest + +Edit the manifest, replace `fallout.globaltool` with `fallout.cli` (both the key and any references). Bump the version pin to the current `Fallout.Cli` release (`11.0.x` and above). + +```sh +dotnet tool restore +``` + +Confirm with `dotnet tool list` — the `fallout.cli` row should appear, the `fallout.globaltool` row should not. + +### Your repo uses the thin `build.sh` / `build.ps1` shims + +Nothing to do. The shims call `dotnet fallout "$@"` — they look up the command by name, not by package ID, and `dotnet tool restore` resolves whatever your manifest pins. + +If your repo is still on the **old fat bootstrappers** (with the `BUILD_PROJECT_FILE` config block + explicit `dotnet build` + `dotnet run --project`), those don't depend on the global tool at all and keep working unchanged. To adopt the new shape, re-run `fallout :setup --force` after upgrading. See [the v11 CHANGELOG entry for #204](https://github.com/ChrisonSimtian/Fallout/blob/main/CHANGELOG.md) for what the new shape looks like. + +### Your repo's CI calls `dotnet fallout` directly (no shim) + +Update the workflow's `dotnet tool restore` step's manifest to reference `fallout.cli`. The actual `dotnet fallout ` lines stay identical. + +## Stuck on 10.3.40 of `Fallout.GlobalTool`? + +The package is unlisted but still downloadable if you have an explicit pin in your manifest. You can keep running on `10.3.40` indefinitely. When you're ready to upgrade, follow the steps above — there is no required intermediate step. `Fallout.GlobalTool 10.3.40` and `Fallout.Cli 11.0.0` are the same code-base; the only consequential difference is the package ID and the semver-correct breaking changes that have accumulated. + +## Refs + +- [#206](https://github.com/ChrisonSimtian/Fallout/pull/206) — the rename PR. +- [#210](https://github.com/ChrisonSimtian/Fallout/pull/210) — README install section + the prompt to uninstall old CLI. +- [#220](https://github.com/ChrisonSimtian/Fallout/pull/220) — the v11 semver-policy bump that catalysed unlisting the 10.3.41-47 range. +- [`from-nuke.md`](from-nuke.md) — if you're also migrating from NUKE, do that first; this guide is downstream of it.