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.
            # A POSITIVE match on what success looks like, not a negative
            # one on an allowlist of English error strings. The negative form
            # returned True for empty output, for $null, and for
            # 'exit status 1: Access is denied.' — so an alias switch that
            # produced nothing, or failed on the symlink permission error this
            # file's own header warns about, was reported as success while the
            # old version kept running. That is the bug #198 was filed about,
            # narrowed rather than removed. It also broke whenever nvm reworded
            # an error. See #208.
            $switched = if ($Version -in @('latest', 'lts', 'newest')) {
                $output -match ('Now using node v' + [regex]::Escape($raw.TrimStart('v')))
            }
            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. If that version is not installed, install it; if it
is, check this shell can write that link:

    nvm install $Version
    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'

# What the machine is put back to afterwards. Beside NODE_VERSION rather than
# duplicated as a parameter default in each script, because two copies of a
# version drift and the half that drifts is the half nobody runs. Both scripts
# still take -DefaultNodeVersion to override it.
$script:DEFAULT_NODE_VERSION = '18.16.1'

# Local runs are three major lines ahead of CI (Node 20 in every workflow) and of
# the production image (node:20-bookworm-slim). That divergence is deliberate but
# not free: post-20 syntax and node: APIs pass here and fail in the pipeline, and
# Node 26 ships an npm that can touch the lockfile in ways CI's npm reads
# differently. The `engines` field in both package.json files records the floor
# machine-readably; nothing yet catches "too new for where this ships". See #208
# part 4, which is an open decision rather than an oversight.

<#
    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-PinnedNode {
    param([scriptblock]$Step, [scriptblock]$Note)

    # Checked BEFORE the switch, against the constant rather than against what
    # ends up running. After the switch $major is whatever NODE_VERSION says,
    # so the old placement could never fire — it validated the switch it had
    # just made instead of the pin it exists to guard. See #208.
    $pinnedMajor = [int](($script:NODE_VERSION -replace '^v', '') -split '\.')[0]
    if ($pinnedMajor -lt 20) {
        throw @"
NODE_VERSION in scripts/NodeVersion.ps1 is $($script:NODE_VERSION), which is below the 20 this project needs.

node-pg-migrate, ts-jest and Playwright all need 20 or newer. Nothing was
switched.
"@
    }

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

<#
    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)" }
    }
}