Restore MSI upgrades from beta releases (#656)

[leynos]

Summary

This branch restores Windows MSI replacement for successive beta releases and
for a final release replacing beta installations in the same release line.
The WiX major-upgrade contract allows same-numeric-version upgrades while
retaining the stable upgrade family and blocking numeric downgrades.

Closes #656.

Review walkthrough

• Start with installer/Package.wxs, which declares the stable UpgradeCode, early major-upgrade scheduling, and safe same-version replacement.
• Review tests/installer_package_wxs_tests.rs, which parses the package and preserves the upgrade metadata contract without building an MSI.
• Then inspect tests/workflow_build_and_package.rs and tests/documentation_installation_tests.rs for stable shared-action inputs and the user-guide replacement claim.

Validation

• make check-fmt: passed
• make lint: passed
• make doc-coverage: passed (99.13%)
• make test: passed (2,774 nextest tests and doctests)
• make markdownlint: passed
• make nixie: passed
• coderabbit review --agent: completed with zero findings

Notes

Functional msiexec upgrade testing remains deferred: package construction
runs in the external shared action, and this repository has no MSI test
harness. The parsed-WiX and workflow-input contracts cover the authored
upgrade metadata and its stable-family wiring.

References

• Lody session

Summary by Sourcery

Restore safe same-version Windows MSI upgrades across beta and final releases.

Bug Fixes:

• Restore Windows MSI replacement when upgrading between beta releases and from a beta to the final release in the same version series.

Enhancements:

• Preserve the stable MSI upgrade family while allowing same-numeric-version replacements and continuing to block numeric downgrades.

Documentation:

• Update the user guide to document beta-to-beta and beta-to-final MSI replacement behavior.

Tests:

• Add parsed-WiX, workflow-wiring, and documentation contract tests for MSI upgrade metadata and stable package inputs.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

Restores Windows MSI replacement across successive beta releases and beta-to-final releases by configuring WiX same-version major upgrades, preserving stable workflow wiring, and adding parsed-WiX, workflow, and documentation contract tests.

Flow diagram for Windows MSI beta-to-final replacement

flowchart LR
    Beta1[Beta MSI 0.1.0-beta1] --> Install[Install MSI]
    Beta2[Beta MSI 0.1.0-beta2] --> Upgrade[WiX major upgrade]
    Final[Final MSI 0.1.0] --> Upgrade
    Upgrade --> Replace[Replace existing installation]
    Upgrade --> StableFamily[Stable UpgradeCode family]

Loading

File-Level Changes

Change	Details	Files
Configure WiX major upgrades to replace beta and final MSI packages within the same numeric release while preserving downgrade protection.	Retain the stable upgrade family identifier and allow WiX to generate a fresh product code. Enable same-version replacement, schedule removal after install initialization, and keep numeric downgrade errors enabled.	installer/Package.wxs CHANGELOG.md
Add source-level tests that validate the authored WiX upgrade metadata without requiring MSI construction.	Parse Package.wxs and assert the stable UpgradeCode, generated ProductCode behavior, major-upgrade settings, schedule, and downgrade message. Add the roxmltree development dependency.	tests/installer_package_wxs_tests.rs Cargo.toml Cargo.lock
Preserve and verify the shared Windows packaging inputs required for a stable MSI upgrade family.	Assert the package action continues to use the binary name for product and install-directory names and the workflow version input.	tests/workflow_build_and_package.rs
Document that later beta and final releases replace earlier MSI installations in the same numeric version series.	Update the user guide wording and add a documentation contract test for the replacement claim.	docs/users-guide.md tests/documentation_installation_tests.rs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#656	Add WiX major-upgrade metadata that enables beta-to-beta and beta-to-final MSI replacement while retaining the stable upgrade family and preventing numeric downgrades.	✅
#656	Ensure the Windows packaging workflow and shared packaging action preserve the stable upgrade-family wiring and pass the required product name, installation directory, and version inputs.	✅
#656	Validate the installer upgrade contract and keep the user documentation aligned with the supported beta and final release replacement behavior.	✅

Possibly linked issues

• Restore MSI upgrades from beta releases to later releases #656: The PR directly implements the issue’s required WiX upgrade metadata, stable family wiring, validation, and documentation updates.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[leynos]

@coderabbitai Please investigate the cause of the following issue using codegraph exploration and research, identify a fix and provide an AI coding agent prompt for the fix:

Run make SHELL=bash test
  make SHELL=bash test
  shell: C:\Program Files\Git\bin\bash.EXE --noprofile --norc -e -o pipefail {0}
  env:
    WINDOWS_LANE_VCPUS: 4
    NEXTEST_VERSION: 0.9.133
    MDTABLEFIX_VERSION: 0.5.1
    PYTHON_BASELINE: 3.14
    CARGO_TERM_COLOR: always
    BUILD_PROFILE: debug
    BUILD_JOBS: -j 4
    NEXTEST_BUILD_JOBS: --build-jobs 4
    NEXTEST_TEST_JOBS: -j 4
    RUSTC_WRAPPER: sccache
    SCCACHE_DIR: D:\a\netsuke\netsuke/.sccache
    SCCACHE_CACHE_SIZE: 4G
    NETSUKE_RUST_TOOLCHAIN: nightly-2026-08-23
    CARGO_INCREMENTAL: 0
    CARGO_PROFILE_DEV_DEBUG: 0
    RUST_BACKTRACE: short
    RUSTFLAGS: -D warnings
    CARGO_UNSTABLE_SPARSE_REGISTRY: true
    CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
    UV_TOOL_BIN_DIR: D:\a\_temp\uv-tool-bin-dir
    UV_TOOL_DIR: D:\a\_temp\uv-tool-dir
    UV_PYTHON_INSTALL_DIR: D:\a\_temp\uv-python-dir
    UV_PYTHON: 3.14
...
        FAIL [   0.111s] (1766/2506) netsuke-build::documentation_installation_tests installation_examples_match_source_and_release_contracts
  stdout ───

    running 1 test
    test installation_examples_match_source_and_release_contracts ... FAILED

    failures:

    failures:
        installation_examples_match_source_and_release_contracts

    test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.07s
    
  stderr ───
    Error: users' guide should document MSI replacement within a version series

    Stack backtrace:
       0: std::backtrace_rs::backtrace::win64::trace
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\..\..\backtrace\src\backtrace\win64.rs:85
       1: std::backtrace_rs::backtrace::trace_unsynchronized
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\..\..\backtrace\src\backtrace\mod.rs:66
       2: std::backtrace::Backtrace::create
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\backtrace.rs:331
       3: std::backtrace::Backtrace::capture
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\backtrace.rs:296
       4: <anyhow::Error>::msg::<&str>
       5: documentation_installation_tests::main
       6: std::rt::lang_start::<()>
       7: documentation_installation_tests::main
       8: std::rt::lang_start::<()>
       9: documentation_installation_tests::main
      10: core::ops::function::FnOnce::call_once
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\core\src\ops\function.rs:250
      11: test::__rust_begin_short_backtrace<enum2$<core::result::Result<tuple$<>,alloc::string::String> >,enum2$<core::result::Result<tuple$<>,alloc::string::String> > (*)()>
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\test\src\lib.rs:733
      12: test::run_test_in_process
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\test\src\lib.rs:756
      13: test::run_test::closure$0
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\test\src\lib.rs:677
      14: test::run_test::closure$1
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\test\src\lib.rs:707
      15: std::sys::backtrace::__rust_begin_short_backtrace<test::run_test::closure_env$1,tuple$<> >
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\sys\backtrace.rs:166
      16: std::thread::lifecycle::spawn_unchecked::closure$1::closure$0
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\thread\lifecycle.rs:70
      17: core::panic::unwind_safe::impl$25::call_once
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\core\src\panic\unwind_safe.rs:275
      18: std::panicking::catch_unwind::do_call
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\panicking.rs:574
      19: std::panicking::catch_unwind
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\panicking.rs:542
      20: std::panic::catch_unwind
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\panic.rs:359
      21: std::thread::lifecycle::spawn_unchecked::closure$1
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\thread\lifecycle.rs:68
      22: core::ops::function::FnOnce::call_once<std::thread::lifecycle::spawn_unchecked::closure_env$1<test::run_test::closure_env$1,tuple$<> >,tuple$<> >
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\core\src\ops\function.rs:250
      23: std::sys::thread::windows::impl$0::new::thread_start
                 at /rustc/c54751567b19c4ceb08b0412d83529c2568cba8b/library\std\src\sys\thread\windows.rs:58
      24: BaseThreadInitThunk
      25: RtlUserThreadStart

  Cancelling due to test failure: 3 tests still running
        PASS [   0.110s] (1767/2506) netsuke-build::env_path_property_tests composition_prepends_and_preserves_order
        PASS [   8.509s] (1768/2506) netsuke-build::dependabot_config_tests manifest_discovery::generated_layouts_include_only_tracked_manifests
        PASS [  59.413s] (1769/2506) netsuke-build::command_env_ui_tests cli_configuration_fixture_compiles
────────────
     Summary [ 112.087s] 1769/2506 tests run: 1768 passed, 1 failed, 2 skipped
        FAIL [   0.111s] (1766/2506) netsuke-build::documentation_installation_tests installation_examples_match_source_and_release_contracts

https://github.com/leynos/netsuke/actions/runs/33991862694/job/101375401545?pr=660

[codescene-access]

No quality gates enabled for this code.