redefined-designs/scripts/NodeVersion.ps1

<#
.SYNOPSIS
    Switching the machine's Node version, shared by start-local.ps1 and
    run-tests.ps1.

.DESCRIPTION
    Both scripts need Node 20 or newer for the same reason: node-pg-migrate
    pulls in an lru-cache that calls diagnostics_channel.tracingChannel(), which
    does not exist before Node 19.9. On Node 18 the migration dies inside
    minified library code with "(0 , U.tracingChannel) is not a function", a
    message that says nothing about versions. ts-jest and Playwright are subject
    to the same floor.

    Kept in one file because two copies of a version switch would drift, and the
    half that drifts is the half nobody runs.

    nvm-windows rewrites a machine-global symlink (NVM_SYMLINK, typically
    C:\nvm4w\nodejs) rather than changing one shell, so switching here changes
    the Node version for every terminal on the machine. That is intended — the
    point is to work in whatever shell is already open — but it is announced
    rather than done quietly, and it is put back afterwards.
#>

function Get-NodeVersionString {
    return (node --version 2>$null)
}

function Get-NodeMajor {
    $raw = Get-NodeVersionString
    if (-not $raw) { return 0 }
    return [int](($raw -replace '^v', '') -split '\.')[0]
}

<#
    Switches, then checks what is actually running.

    nvm-windows exits 0 for switches that did not take: a version it cannot
    find, a symlink it cannot rewrite without elevation, and — seen on this
    machine — a rewrite immediately after another one, where the directory
    symlink is briefly still the old target. So the result is verified rather
    than trusted, and retried once, because reporting a version that is not the
    one running is worse than not switching at all.

    nvm's own output is captured rather than discarded. Suppressing it hid the
    only message that explained a failed switch.
#>
function Use-Node {
    param(
        [Parameter(Mandatory)][string]$Version,
        [Parameter(Mandatory)][string]$Why,
        [scriptblock]$Step,
        [scriptblock]$Note
    )

    if ($Step) { & $Step "Switching Node to $Version ($Why)" }
    if ($Note) { & $Note 'nvm changes the version for every shell on this machine, not just this one' }

    $output = $null
    foreach ($attempt in 1..2) {
        $output = (nvm use $Version 2>&1 | Out-String).Trim()

        $raw = Get-NodeVersionString
        if ($raw) {
            # An alias resolves to whatever nvm picked, so there is no version
            # string to compare it against — the caller checks the major
            # instead. What is checked here is nvm's own report, because it
            # announces a switch it could not make while still exiting 0.
            # Treating an alias as always-successful is what turned "the version
            # nvm wanted is not installed" into a claim that the newest install
            # was too old, which sent the reader to `nvm install` holding a list
            # that already had newer versions on it.
            $switched = if ($Version -in @('latest', 'lts', 'newest')) {
                $output -notmatch 'activation error|not installed'
            }
            else {
                $raw.TrimStart('v') -eq $Version.TrimStart('v')
            }

            if ($switched) {
                if ($Note) { & $Note "node $raw" }
                return $raw
            }
        }

        if ($attempt -eq 1) {
            if ($Note) { & $Note 'the switch has not taken yet; retrying' }
            Start-Sleep -Milliseconds 750
        }
    }

    $running = Get-NodeVersionString
    if (-not $running) {
        throw "Node is not on PATH after 'nvm use $Version'. Check that nvm-windows is installed.`n`nnvm said:`n$output"
    }

    throw @"
Asked nvm for Node $Version, but $running is still what runs.

nvm said:
$output

nvm-windows rewrites a symlink at $env:NVM_SYMLINK, and can report success
without having rewritten it. Check the version is installed, and that this shell
can write that link:

    nvm list
"@
}

# The version every local run uses. Pinned rather than asked for by alias, so
# two machines run the same Node instead of whatever each happens to have
# installed. Bump it here and it moves for start-local.ps1 and run-tests.ps1
# together; the floor check below is a backstop against pinning it too low, not
# the specification.
$script:NODE_VERSION = '26.7.0'

<#
    Switches to the pinned version and insists it clears the floor.

    Asking nvm for an alias is what this used to do, and the two alias names are
    worth recording because they are easy to swap by accident. `newest` means
    the newest version installed on this machine. `latest` means the newest that
    exists — nvm-windows resolves it against the remote release list — so on a
    machine whose newest install is behind the current release, `nvm use latest`
    reports "activation error: Version not installed" and leaves the old version
    running. This asked for `latest` and reported the failure as "the newest
    version nvm has installed is too old", which was false and sent the reader
    to install something they already had. See #198.

    A version that is not installed is Use-Node's error to report, and it now
    reports nvm's own reason, so there is nothing to say about it here.
#>
function Use-NodeLatest {
    param([scriptblock]$Step, [scriptblock]$Note)

    Use-Node -Version $script:NODE_VERSION -Why 'this project needs Node 20 or newer' -Step $Step -Note $Note | Out-Null

    $major = Get-NodeMajor
    if ($major -lt 20) {
        throw @"
Node is v$major after switching to $($script:NODE_VERSION), which is below the 20 this project needs.

NODE_VERSION in scripts/NodeVersion.ps1 is pinned to a version that is too old.
node-pg-migrate, ts-jest and Playwright all need 20 or newer.
"@
    }
}

<#
    Best effort by design. A failure to switch back must not mask the error that
    got us here, nor turn a passing run into a failing one — but it must still
    say so, because leaving the machine on the wrong version silently is how the
    next confusing failure starts.
#>
function Restore-Node {
    param(
        [Parameter(Mandatory)][string]$Version,
        [scriptblock]$Step,
        [scriptblock]$Note
    )

    try {
        Use-Node -Version $Version -Why 'restoring the machine default' -Step $Step -Note $Note | Out-Null
    }
    catch {
        if ($Note) { & $Note "could not restore Node ${Version}: $($_.Exception.Message)" }
    }
}