feat(scripts): switch Node automatically, and add a test runner (#140)

start-local.ps1 knew exactly what was wrong when Node was too old and then made you fix it by hand. Assert-NodeVersion read node --version, found a major below 20, and threw a message telling you to run `nvm use 24.13.1` and start again in a new shell. A good error for a problem the script could simply solve — and since nvm's default here is 18.16.1, it was hit on every fresh shell.

It now runs `nvm use latest` itself and -Stop puts the machine back to 18.16.1. The revert also runs when a start fails partway: without that, a run dying in migrations leaves the machine switched with nothing started, and the -Stop that would restore it is never reached.

nvm rewrites a machine-global symlink rather than changing one shell, so this changes the Node version for every terminal on the machine while a script runs. That is the intent — the point is to work in whatever shell is already open — but it is announced every time rather than done quietly.

The switch is verified rather than trusted. nvm-windows exits 0 for switches that did not happen: a version it cannot find, a symlink it cannot rewrite without elevation, and — observed here — a rewrite issued immediately after another one, where the directory symlink is briefly still the old target. That last case turned up while testing this change: `nvm use latest` reported success and left Node on 18.16.1. So the result is read back and retried once, and nvm's own output is captured rather than discarded, because suppressing it hid the only message that explained the failure.

run-tests.ps1 runs the suites: -Suite unit|integration|e2e|all. One script with a parameter rather than three, because the version switch, the database bring-up and the TEST_PGPORT handling are shared and three copies would drift. The integration suite gets its own throwaway Postgres started and stopped around it, in a finally so a failing suite still tidies up. The e2e suite checks the backend is answering first and says what to start, rather than leaving twenty-five specs to fail on a refused connection that names nothing.

`all` runs cheapest and most isolated first, so a break several suites would show is reported by the one that localises it best.

The version switching lives in scripts/NodeVersion.ps1, dot-sourced by both, since two copies of it would drift and the half that drifts is the half nobody runs.

Closes #140

scripts/start-local.ps1

@@ -35,7 +35,11 @@ param(
     [int]$ApiPort = 3000,
     [int]$WebPort = 5173,
     [switch]$Fresh,
-    [switch]$Stop
+    [switch]$Stop,
+    # What -Stop puts the machine back to. nvm's default here is 18.16.1, which
+    # is too old to run this project's tooling but is what everything else on
+    # the machine expects.
+    [string]$DefaultNodeVersion = '18.16.1'
 )
 
 $ErrorActionPreference = 'Stop'
@@ -72,26 +76,11 @@ function Assert-Docker {
     }
 }
 
-# node-pg-migrate pulls in an lru-cache that calls
-# diagnostics_channel.tracingChannel, which does not exist before Node 20. On
-# Node 18 the migration dies in minified library code with "(0 , U.tracingChannel)
-# is not a function", which says nothing about versions. CI runs Node 20.
-function Assert-NodeVersion {
-    $raw = (node --version)
-    $major = [int](($raw -replace '^v', '') -split '\.')[0]
-    if ($major -lt 20) {
-        throw @"
-Node $raw is too old. This needs Node 20 or newer.
+. (Join-Path $PSScriptRoot 'NodeVersion.ps1')
 
-If you use nvm-windows:
-
-    nvm use 24.13.1
-
-Then run this script again in a new shell.
-"@
-    }
-    Write-Note "node $raw"
-}
+# Bound once so the shared switcher reports through this script's own output
+# style rather than printing in a voice of its own.
+$NodeOut = @{ Step = ${function:Write-Step}; Note = ${function:Write-Note} }
 
 # Reads back only the ids this script wrote. Killing by port would be shorter
 # and would also kill whatever else happened to be listening.
@@ -277,16 +266,27 @@ New-Item -ItemType Directory -Force -Path $StateDir *>$null
 
 if ($Stop) {
     Stop-Environment
+    Restore-Node -Version $DefaultNodeVersion @NodeOut
     return
 }
 
-Assert-NodeVersion
-Assert-Docker
-Start-Database
-Install-IfMissing (Join-Path $RepoRoot 'backend')
-Install-IfMissing (Join-Path $RepoRoot 'frontend')
-Start-Backend
-Start-Frontend
+Use-NodeLatest @NodeOut
+
+# Anything after the switch reverts on the way out of a failure. Without this a
+# run that dies in migrations leaves the machine on the new version with nothing
+# started, and the -Stop that would put it back is never reached.
+try {
+    Assert-Docker
+    Start-Database
+    Install-IfMissing (Join-Path $RepoRoot 'backend')
+    Install-IfMissing (Join-Path $RepoRoot 'frontend')
+    Start-Backend
+    Start-Frontend
+}
+catch {
+    Restore-Node -Version $DefaultNodeVersion @NodeOut
+    throw
+}
 
 Write-Host ''
 Write-Host 'Running.' -ForegroundColor Green
@@ -296,5 +296,5 @@ Write-Host "  API          http://localhost:$ApiPort/api/config"
 Write-Host "  Postgres     localhost:$DbPort  ($DbUser / $DbPassword / $DbName)"
 Write-Host ''
 Write-Host "  Logs         $StateDir"
-Write-Host "  Stop         .\scripts\start-local.ps1 -Stop"
+Write-Host "  Stop         .\scripts\start-local.ps1 -Stop  (also restores Node $DefaultNodeVersion)"
 Write-Host ''