synAdminandClaude Opus 5
022ab8edcf
Starting the stack locally failed to build with four copies of
error TS2307: Cannot find module '@simplewebauthn/server'
naming a package that is right there in package.json. That reads as a broken checkout rather than a missing install, which is why it costs more than it should.
The cause is one line in Install-IfMissing. It asked whether node_modules existed and returned early if it did, which is true for anyone who has ever run the script. So a branch that ADDS a dependency never installs it: the pull brings a new package.json and a new lockfile, the script says dependencies already installed, and the build then fails on an import the source is entirely right to make.
The passkeys work is what surfaced it, adding @simplewebauthn/server to the backend and @simplewebauthn/browser to the frontend, but nothing about it is specific to those. Any dependency added on any branch would have done the same, and the failure would have looked equally unrelated to its cause each time.
It now compares timestamps instead. npm writes node_modules/.package-lock.json describing exactly what it put there, so holding that against package-lock.json answers the question actually being asked: is what is installed what is currently asked for. A pull that changes dependencies makes the lockfile newer and this notices; a pull that does not leaves the check skipping the install exactly as before, which is the whole reason the check exists.
Both branches were exercised against the real working tree: stale before installing, up to date after.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
463 lines
18 KiB
PowerShell
463 lines
18 KiB
PowerShell
#Requires -Version 7
|
|
<#
|
|
.SYNOPSIS
|
|
Starts the Redefined Designs stack locally for testing and review.
|
|
|
|
.DESCRIPTION
|
|
Brings up a Postgres container, runs migrations, builds and starts the
|
|
backend, and starts the Vite dev server. Safe to run repeatedly: an
|
|
existing container is reused rather than recreated, and processes already
|
|
listening are left alone.
|
|
|
|
Logs and process ids go to .local/ at the repository root.
|
|
|
|
.PARAMETER Fresh
|
|
Drop the database container and its data before starting, so migrations
|
|
run against an empty database.
|
|
|
|
.PARAMETER Stop
|
|
Stop the backend, the dev server and the database container, then exit.
|
|
|
|
.PARAMETER DbPort
|
|
Host port for Postgres. Change it if something already holds the default.
|
|
|
|
.EXAMPLE
|
|
.\scripts\start-local.ps1
|
|
.\scripts\start-local.ps1 -Fresh
|
|
.\scripts\start-local.ps1 -Stop
|
|
#>
|
|
[CmdletBinding()]
|
|
param(
|
|
# Deliberately not 55432. That port is reserved by Hyper-V on at least one
|
|
# machine here, and Docker's failure when it cannot bind does not mention
|
|
# reservations, which has cost time more than once.
|
|
[int]$DbPort = 55500,
|
|
[int]$ApiPort = 3000,
|
|
[int]$WebPort = 5173,
|
|
[switch]$Fresh,
|
|
# Runs the stack against the throwaway end-to-end database instead of the
|
|
# development one: a separate container on a separate port, with tmpfs
|
|
# storage, so it starts empty every time.
|
|
#
|
|
# The e2e suite used to run against the development database, and nothing
|
|
# ever truncated it. Every run seeded more fixtures and left them, so the
|
|
# unfiltered storefront grew monotonically — 1,662 items by the time #186
|
|
# was filed — until rendering it outran the assertions' timeout. It failed
|
|
# locally, passed in CI where the database is fresh, and got steadily worse.
|
|
#
|
|
# This does not touch the development database, so anything you have set up
|
|
# there by hand survives.
|
|
[switch]$E2eDb,
|
|
[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.
|
|
# Resolved after NodeVersion.ps1 is dot-sourced below, not here. A param
|
|
# block runs before anything else in the script, so $script:DEFAULT_NODE_VERSION
|
|
# is still $null at this point and using it as the default would silently
|
|
# restore nothing — leaving the machine on the pinned version, which is the
|
|
# exact failure the restore exists to prevent. See #208.
|
|
[string]$DefaultNodeVersion = ''
|
|
)
|
|
|
|
$ErrorActionPreference = 'Stop'
|
|
|
|
$RepoRoot = Split-Path -Parent $PSScriptRoot
|
|
$StateDir = Join-Path $RepoRoot '.local'
|
|
$PidFile = Join-Path $StateDir 'pids.json'
|
|
# Which database the stack is actually using, written for the test runner to
|
|
# read. See Write-DatabaseChoice and #273.
|
|
$DatabaseFile = Join-Path $StateDir 'database.json'
|
|
|
|
# Whether this run is starting from an empty database. Set below, and read by
|
|
# Start-Backend, which must refuse to reuse a backend that is still serving the
|
|
# previous one. See #257.
|
|
$script:DatabaseIsNew = $false
|
|
# Which database this run uses. Everything downstream reads these four, so the
|
|
# choice is made once here rather than branched at each use.
|
|
if ($E2eDb) {
|
|
$Container = 'redefined-designs-e2e-db'
|
|
$DbUser = 'redefined_e2e'
|
|
$DbPassword = 'redefined_e2e'
|
|
$DbName = 'redefined_e2e'
|
|
# Not 55500 (development) and not 55432 (the integration suite). The three
|
|
# must not collide: the integration suite truncates between tests, so
|
|
# sharing a database with an e2e run would delete that run's fixtures
|
|
# underneath it (#116).
|
|
if (-not $PSBoundParameters.ContainsKey('DbPort')) { $DbPort = 55501 }
|
|
}
|
|
else {
|
|
$Container = 'redefined-designs-local-db'
|
|
$DbUser = 'redefined_local'
|
|
$DbPassword = 'redefined_local'
|
|
$DbName = 'redefined_local'
|
|
}
|
|
|
|
function Write-Step { param([string]$Message) Write-Host "==> $Message" -ForegroundColor Cyan }
|
|
function Write-Note { param([string]$Message) Write-Host " $Message" -ForegroundColor DarkGray }
|
|
function Write-Good { param([string]$Message) Write-Host " $Message" -ForegroundColor Green }
|
|
|
|
# $ErrorActionPreference = 'Stop' does NOT stop the script when a native
|
|
# executable exits non-zero, only when a cmdlet throws. Everything here is
|
|
# node, npm or docker, so without this wrapper a failed migration is a line of
|
|
# red text the script prints and then carries straight past. It did exactly
|
|
# that once, and reported a healthy stack sitting on an empty database.
|
|
function Invoke-Checked {
|
|
param([scriptblock]$Command, [string]$What)
|
|
& $Command
|
|
if ($LASTEXITCODE -ne 0) {
|
|
throw "$What failed (exit code $LASTEXITCODE)."
|
|
}
|
|
}
|
|
|
|
function Assert-Docker {
|
|
docker info *>$null
|
|
if ($LASTEXITCODE -ne 0) {
|
|
throw "Docker is not running. Start Docker Desktop and try again."
|
|
}
|
|
}
|
|
|
|
. (Join-Path $PSScriptRoot 'NodeVersion.ps1')
|
|
|
|
# The one home for this value is NodeVersion.ps1, beside NODE_VERSION. It cannot
|
|
# be a param default (see the note there), so it is filled in here instead, and
|
|
# an explicit -DefaultNodeVersion still wins.
|
|
if (-not $DefaultNodeVersion) { $DefaultNodeVersion = $script:DEFAULT_NODE_VERSION }
|
|
|
|
# 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.
|
|
function Get-TrackedProcesses {
|
|
if (-not (Test-Path $PidFile)) { return @{} }
|
|
try { return (Get-Content $PidFile -Raw | ConvertFrom-Json -AsHashtable) }
|
|
catch { return @{} }
|
|
}
|
|
|
|
function Stop-Tracked {
|
|
param([string]$Name)
|
|
$tracked = Get-TrackedProcesses
|
|
if (-not $tracked.ContainsKey($Name)) { return }
|
|
$process = Get-Process -Id $tracked[$Name] -ErrorAction SilentlyContinue
|
|
if ($process) {
|
|
Stop-Process -Id $process.Id -Force -ErrorAction SilentlyContinue
|
|
Write-Good "stopped $Name (pid $($process.Id))"
|
|
}
|
|
}
|
|
|
|
<#
|
|
.SYNOPSIS
|
|
Records the database this run chose, so the test runner does not have to guess.
|
|
|
|
.DESCRIPTION
|
|
The end-to-end helper (frontend/tests/e2e/support/db.ts) opens its own
|
|
connection to read a password-reset token, and nothing guaranteed it pointed at
|
|
the same database as the application under test. With -E2eDb the app moves to
|
|
redefined_e2e on 55501 while the helper stayed on its redefined_local default,
|
|
so the app wrote to one database and the suite read another and the specs failed
|
|
for a reason that had nothing to do with them.
|
|
|
|
Writing it here makes the answer a fact rather than a convention: it is recorded
|
|
by the thing that made the choice, at the moment it made it, and a missing file
|
|
is a clear failure in run-tests.ps1 rather than a silent connection to the wrong
|
|
data. See #273.
|
|
#>
|
|
function Write-DatabaseChoice {
|
|
@{
|
|
host = 'localhost'
|
|
port = $DbPort
|
|
user = $DbUser
|
|
password = $DbPassword
|
|
database = $DbName
|
|
} | ConvertTo-Json | Set-Content $DatabaseFile
|
|
Write-Note "recorded $DbName on $DbPort in .local/database.json"
|
|
}
|
|
|
|
function Set-Tracked {
|
|
param([string]$Name, [int]$ProcessId)
|
|
$tracked = Get-TrackedProcesses
|
|
$tracked[$Name] = $ProcessId
|
|
$tracked | ConvertTo-Json | Set-Content $PidFile
|
|
}
|
|
|
|
function Test-Listening {
|
|
param([int]$Port)
|
|
return [bool](Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue)
|
|
}
|
|
|
|
function Wait-For {
|
|
param(
|
|
[scriptblock]$Condition,
|
|
[string]$What,
|
|
[int]$TimeoutSeconds = 60
|
|
)
|
|
for ($i = 1; $i -le $TimeoutSeconds; $i++) {
|
|
if (& $Condition) {
|
|
Write-Good "$What ready after ${i}s"
|
|
return
|
|
}
|
|
Start-Sleep -Seconds 1
|
|
}
|
|
throw "$What did not become ready within ${TimeoutSeconds}s."
|
|
}
|
|
|
|
function Stop-Environment {
|
|
Write-Step 'Stopping'
|
|
Stop-Tracked 'backend'
|
|
Stop-Tracked 'frontend'
|
|
docker stop $Container *>$null
|
|
if ($LASTEXITCODE -eq 0) { Write-Good "stopped container $Container" }
|
|
else { Write-Note "container $Container was not running" }
|
|
Remove-Item $PidFile -ErrorAction SilentlyContinue
|
|
# Removed with the pids: a stopped stack must not leave behind a file saying
|
|
# which database is up, or the next test run trusts a container that is gone.
|
|
Remove-Item $DatabaseFile -ErrorAction SilentlyContinue
|
|
Write-Host ''
|
|
Write-Host 'Stopped.' -ForegroundColor Green
|
|
}
|
|
|
|
function Start-Database {
|
|
if ($Fresh) {
|
|
Write-Step 'Removing the existing database (-Fresh)'
|
|
docker rm -f $Container *>$null
|
|
Write-Good 'removed'
|
|
$script:DatabaseIsNew = $true
|
|
}
|
|
|
|
# The e2e container stores its data on tmpfs, so it comes up empty whether it
|
|
# is created or merely restarted. There is no case where it carries anything
|
|
# over, which is the point of it (#186) — and it means a backend from a
|
|
# previous run is always stale against it.
|
|
if ($E2eDb) { $script:DatabaseIsNew = $true }
|
|
|
|
$existing = (docker ps -a --filter "name=^/$Container$" --format '{{.Names}}')
|
|
if ($existing -eq $Container) {
|
|
Write-Step "Reusing the database container"
|
|
docker start $Container *>$null
|
|
}
|
|
else {
|
|
$script:DatabaseIsNew = $true
|
|
Write-Step "Creating the database container on port $DbPort"
|
|
# tmpfs for the e2e database only: its contents are worthless the
|
|
# moment the run ends, and storing nothing is what makes it start empty
|
|
# every time rather than accumulating fixtures the way the development
|
|
# database did (#186). Migrations run on every start below, so an empty
|
|
# volume is a working one. The development database keeps its storage.
|
|
$storage = if ($E2eDb) { @('--tmpfs', '/var/lib/postgresql/data') } else { @() }
|
|
|
|
docker run -d --name $Container `
|
|
-e "POSTGRES_USER=$DbUser" `
|
|
-e "POSTGRES_PASSWORD=$DbPassword" `
|
|
-e "POSTGRES_DB=$DbName" `
|
|
-p "${DbPort}:5432" `
|
|
@storage `
|
|
postgres:16 *>$null
|
|
|
|
if ($LASTEXITCODE -ne 0) {
|
|
# The message Docker gives for a reserved port does not say
|
|
# "reserved", so name the likely cause and the way out of it.
|
|
throw @"
|
|
Could not start Postgres on port $DbPort.
|
|
|
|
If the port is in use, or reserved by Hyper-V (which silently claims ranges on
|
|
Windows), pick another one:
|
|
|
|
.\scripts\start-local.ps1 -DbPort 55600
|
|
|
|
Reserved ranges: netsh interface ipv4 show excludedportrange protocol=tcp
|
|
"@
|
|
}
|
|
}
|
|
|
|
Wait-For -What 'Postgres' -Condition {
|
|
docker exec $Container pg_isready -U $DbUser -d $DbName *>$null
|
|
$LASTEXITCODE -eq 0
|
|
}
|
|
}
|
|
|
|
function Install-IfMissing {
|
|
param([string]$Directory)
|
|
$name = Split-Path -Leaf $Directory
|
|
|
|
# Whether node_modules matches the lockfile, not merely whether it exists.
|
|
#
|
|
# This used to ask only `Test-Path node_modules`, which meant a branch that
|
|
# ADDED a dependency never installed it for anyone who already had the
|
|
# directory — and almost everyone always does. The build then failed on
|
|
# "Cannot find module", naming a package that is right there in
|
|
# package.json, which reads as a broken checkout rather than a missing
|
|
# install. It cost an afternoon the first time #37 added @simplewebauthn.
|
|
#
|
|
# npm writes node_modules/.package-lock.json describing exactly what it put
|
|
# there, so comparing its timestamp against package-lock.json answers the
|
|
# real question: is what is installed what is currently asked for. A pull
|
|
# that changes dependencies makes the lockfile newer, and this notices.
|
|
$lockfile = Join-Path $Directory 'package-lock.json'
|
|
$installed = Join-Path $Directory 'node_modules/.package-lock.json'
|
|
|
|
if ((Test-Path $installed) -and (Test-Path $lockfile)) {
|
|
$lockTime = (Get-Item $lockfile).LastWriteTimeUtc
|
|
$installedTime = (Get-Item $installed).LastWriteTimeUtc
|
|
if ($installedTime -ge $lockTime) {
|
|
Write-Note "$name dependencies are up to date"
|
|
return
|
|
}
|
|
Write-Step "Installing $name dependencies (the lockfile has changed)"
|
|
}
|
|
else {
|
|
Write-Step "Installing $name dependencies"
|
|
}
|
|
|
|
Push-Location $Directory
|
|
try { Invoke-Checked { npm install } "$name npm install" } finally { Pop-Location }
|
|
}
|
|
|
|
function Start-Backend {
|
|
$backend = Join-Path $RepoRoot 'backend'
|
|
|
|
# The six the backend refuses to boot without, plus the two that make a
|
|
# local run behave. Set in this session so the child process inherits them.
|
|
$env:PGHOST = 'localhost'
|
|
$env:PGPORT = "$DbPort"
|
|
$env:PGUSER = $DbUser
|
|
$env:PGPASSWORD = $DbPassword
|
|
$env:PGDATABASE = $DbName
|
|
$env:UPLOADS_DIR = (Join-Path $StateDir 'uploads')
|
|
$env:PORT = "$ApiPort"
|
|
# No PayPal credentials locally. DEMO_MODE lets the whole cart and checkout
|
|
# path run without them and with no way to reach live PayPal.
|
|
$env:DEMO_MODE = 'true'
|
|
# Needs to be set for the submission page's checkbox to appear at all, but
|
|
# not to resolve: no e2e submission reaches the sidecar, because the
|
|
# worker only cuts out after a draft and drafting is not configured
|
|
# locally.
|
|
$env:REMBG_URL = 'http://127.0.0.1:7000'
|
|
New-Item -ItemType Directory -Force -Path $env:UPLOADS_DIR *>$null
|
|
|
|
Write-Step 'Running migrations'
|
|
Push-Location $backend
|
|
try {
|
|
Invoke-Checked { node migrate.js up } 'Migrations'
|
|
Write-Step 'Building the backend'
|
|
Invoke-Checked { npm run build } 'Backend build'
|
|
}
|
|
finally { Pop-Location }
|
|
|
|
if (Test-Listening -Port $ApiPort) {
|
|
# Leaving a stranger's backend alone is only safe when the database has
|
|
# not just changed underneath it. When it has, that process is serving a
|
|
# database it no longer owns, and its in-memory state describes rows that
|
|
# no longer exist.
|
|
#
|
|
# That is not theoretical. The rate limiter keys on customer id and keeps
|
|
# its buckets in memory for an hour; a recreated database restarts ids at
|
|
# 1, so a new customer inherits a previous run's spent allowance. It
|
|
# reproduced exactly the intermittent resend-verification failure in #257
|
|
# — three refusal toasts where one was expected — and the control (same
|
|
# id restart, restarted backend) passed. Whatever else is stale, a
|
|
# process serving the wrong database gives wrong answers confidently,
|
|
# which is the worst kind.
|
|
#
|
|
# So this refuses rather than continuing, and says what to do. A run that
|
|
# stops loudly is recoverable; one that quietly tests the wrong thing is
|
|
# what cost two wrong measurements in this project already.
|
|
$tracked = Get-TrackedProcesses
|
|
$ours = $tracked.ContainsKey('backend') -and
|
|
(Get-Process -Id $tracked['backend'] -ErrorAction SilentlyContinue)
|
|
|
|
if ($script:DatabaseIsNew -and -not $ours) {
|
|
throw @"
|
|
Something is already listening on $ApiPort, and this run just created a new database.
|
|
|
|
That process is serving the previous database. Its in-memory state — rate-limit
|
|
buckets keyed on customer id, most obviously — describes rows that no longer
|
|
exist, and recycled ids will inherit them (#257).
|
|
|
|
Stop it and run this again:
|
|
|
|
.\scripts\start-local.ps1 -Stop
|
|
"@
|
|
}
|
|
|
|
Write-Note "something is already listening on $ApiPort; leaving it alone"
|
|
return
|
|
}
|
|
|
|
Write-Step "Starting the backend on $ApiPort"
|
|
# Separate files: Start-Process cannot redirect both streams to one path.
|
|
$process = Start-Process -FilePath 'node' -ArgumentList 'dist/server.js' `
|
|
-WorkingDirectory $backend `
|
|
-RedirectStandardOutput (Join-Path $StateDir 'backend.log') `
|
|
-RedirectStandardError (Join-Path $StateDir 'backend.err.log') `
|
|
-WindowStyle Hidden -PassThru
|
|
Set-Tracked 'backend' $process.Id
|
|
|
|
Wait-For -What 'Backend' -Condition {
|
|
try {
|
|
$null = Invoke-WebRequest "http://localhost:$ApiPort/api/config" -TimeoutSec 2 -UseBasicParsing
|
|
$true
|
|
}
|
|
catch { $false }
|
|
}
|
|
}
|
|
|
|
function Start-Frontend {
|
|
if (Test-Listening -Port $WebPort) {
|
|
Write-Note "something is already listening on $WebPort; leaving it alone"
|
|
return
|
|
}
|
|
|
|
Write-Step "Starting the dev server on $WebPort"
|
|
$process = Start-Process -FilePath 'npm.cmd' -ArgumentList 'run', 'dev' `
|
|
-WorkingDirectory (Join-Path $RepoRoot 'frontend') `
|
|
-RedirectStandardOutput (Join-Path $StateDir 'frontend.log') `
|
|
-RedirectStandardError (Join-Path $StateDir 'frontend.err.log') `
|
|
-WindowStyle Hidden -PassThru
|
|
Set-Tracked 'frontend' $process.Id
|
|
|
|
Wait-For -What 'Dev server' -Condition { Test-Listening -Port $WebPort }
|
|
}
|
|
|
|
New-Item -ItemType Directory -Force -Path $StateDir *>$null
|
|
|
|
if ($Stop) {
|
|
Stop-Environment
|
|
Restore-Node -Version $DefaultNodeVersion @NodeOut
|
|
return
|
|
}
|
|
|
|
Use-PinnedNode @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
|
|
# Recorded as soon as the database is actually up, and before anything reads
|
|
# it. Written after Start-Database rather than before, so the file never
|
|
# claims a database that failed to start.
|
|
Write-DatabaseChoice
|
|
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
|
|
Write-Host " Storefront http://localhost:$WebPort"
|
|
Write-Host " Admin http://localhost:$WebPort/admin"
|
|
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 (also restores Node $DefaultNodeVersion)"
|
|
Write-Host ''
|