emozilla e5f19af2a5 feat(install.ps1): stage protocol + Windows clean-VM hardening pass ...

Adds an opt-in stage protocol that lets programmatic drivers (the
desktop GUI's onboarding wizard, CI, future install.sh parity) drive
install.ps1 one step at a time with structured JSON results. Default
invocation (`irm | iex` one-liner) behaves unchanged.

Entry points:
  install.ps1                  Today's interactive install (unchanged)
  install.ps1 -ProtocolVersion Emit protocol version integer
  install.ps1 -Manifest        Emit JSON manifest of available stages
  install.ps1 -Stage <name>    Run one stage, emit JSON result
  install.ps1 -NonInteractive  Suppress Read-Host prompts (skips the
                               setup wizard and gateway autostart)
  install.ps1 -Json            Machine-readable completion frame

Manifest exposes 14 stages across prereqs/install/finalize/post-install
categories, with 2 (configure, gateway) flagged needs_user_input=true
so GUI drivers can skip them and handle the equivalent UX themselves.

Along the way, clean-VM testing on stock Windows 10/11 surfaced a
series of latent install.ps1 bugs that were never exercised by
developer machines. Fixed in the same commit:

* Encoding: file is now pure ASCII with no BOM. Windows PowerShell
  5.1 reads BOM-less files as Windows-1252 and chokes on em-dashes
  (and other UTF-8 sequences), while iex chokes on a leading U+FEFF.
  Pure-ASCII satisfies both invocation paths.

* EAP=Stop + native `2>&1` captures: PowerShell wraps stderr lines
  from native commands as ErrorRecord objects under EAP=Stop and
  throws even when the command exits 0. Relaxed to EAP=Continue
  around the astral.sh uv installer, `uv python install`, `npm
  install`, `npx playwright install`, the venv import probes, and
  the Node winget fallback. Check $LASTEXITCODE for the real signal.

* Cross-process state: each `-Stage <name>` invocation spawns a
  fresh powershell child. $script:UvCmd set by Stage-Uv was invisible
  to Stage-Python; PATH updated by Stage-Git/Stage-Node was invisible
  to subsequent stages spawned by the driver shell. Added Resolve-UvCmd
  helper called at the top of every stage that needs uv, and a
  Sync-EnvPath helper called at the top of Invoke-Stage to refresh
  PATH from the registry.

* UAC avoidance: `winget install OpenJS.NodeJS.LTS` triggers a UAC
  prompt that often appears minimized in the taskbar -- looks like a
  hang. Switched Test-Node to prefer the official portable Node zip
  dropped into %LOCALAPPDATA%\hermes\node\ (mirrors the PortableGit
  pattern Install-Git already uses). winget kept as fallback.

* npx hangs on confirmation: `npx playwright install chromium` blocks
  on stdin waiting for "Need to install playwright@X.Y.Z (y/N)" when
  playwright isn't in local node_modules. Tee-Object pipelines
  disconnect stdin from the user's TTY so the install hangs forever.
  Pass `--yes` to auto-accept.

* Silent long-running installs: `*> $logPath` redirected every stream
  to disk and left the user staring at a frozen "Installing..." line
  for the 5-10 minutes Playwright Chromium takes to download. Switched
  to `2>&1 | ForEach-Object { "$_" } | Tee-Object -FilePath $log` so
  output streams live to the console AND captures to log for failure
  diagnostics. ForEach-Object coercion strips PowerShell's red
  NativeCommandError formatter from stderr items.

* Console encoding: forced [Console]::OutputEncoding to UTF-8 so
  playwright/git/npm progress bars, box-drawing, and check marks render
  correctly instead of as IBM437/Windows-1252 mojibake.

* Performance: set $ProgressPreference = "SilentlyContinue" so
  Invoke-WebRequest doesn't paint its per-chunk progress bar. The
  PS 5.1 progress UI throttles downloads by 10-100x (a 57MB PortableGit
  grab takes 5 minutes with the bar on vs ~20 seconds with it off,
  same network). Affects PortableGit, Node portable zip, and the
  Hermes repo zip fallback.

Tests: scripts/tests/test-install-ps1-stage-protocol.ps1 provides 19
metadata-only assertions covering -ProtocolVersion, -Manifest schema,
and unknown -Stage error frame. No install side effects.

End-to-end validated on a clean Windows 10 VM via:
  1. `irm <branch>/scripts/install.ps1 | iex` (canonical CLI path)
  2. `powershell -File install.ps1 -Stage X` iterated through every
     stage (GUI driver path, exercises cross-process fixes)

2026-05-16 22:55:12 -07:00

..

test-install-ps1-stage-protocol.ps1

feat(install.ps1): stage protocol + Windows clean-VM hardening pass

2026-05-16 22:55:12 -07:00