@join-pantheon/cli 0.31.2 → 0.32.0-rc.2

package/helper/macos/prebuilt/manifest.json

@@ -0,0 +1,29 @@
+{
+  "format": 1,
+  "built_at": "2026-10-03T12:09:02.195Z",
+  "swiftc": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)",
+  "helpers": {
+    "pantheon-tray": {
+      "source": "menubar.swift",
+      "source_sha256": "f079629099a81f9b679ef4133d897ceb09025f675099c5f941951604df3531fa",
+      "sha256": "cc081120555f528c83b38951663d37e8394e3a3e119a19b0bb3b2a737f4d617f",
+      "archs": [
+        "arm64",
+        "x86_64"
+      ],
+      "target": "macos11",
+      "version": "2"
+    },
+    "pantheon-hud": {
+      "source": "main.swift",
+      "source_sha256": "bcf55a19b658d1f09a9d117c76030393ab08a2569062dd7413f884ca05f3a0eb",
+      "sha256": "0414b397a533940e3a5c324add6250e1ed71919e67e462d11dcb2a1d0c2f9b41",
+      "archs": [
+        "arm64",
+        "x86_64"
+      ],
+      "target": "macos11",
+      "version": "4"
+    }
+  }
+}

package/installer/install.ps1

@@ -0,0 +1,554 @@
+# Pantheon installer for Windows (Windows PowerShell 5.1 and PowerShell 7).
+#
+# In PowerShell:
+#   irm https://relay.joinpantheon.network/install.ps1 | iex                       (install only)
+#   $env:PANTHEON_ARGS = "join '<invite link>'"; irm https://relay.joinpantheon.network/install.ps1 | iex
+#   & ([scriptblock]::Create((irm https://relay.joinpantheon.network/install.ps1))) join '<invite link>'
+#     (not under Constrained Language Mode, which refuses [scriptblock]::Create
+#     before this script can explain: there, use the `irm | iex` forms)
+#
+# In Command Prompt (cmd.exe), as one line:
+#   powershell -NoProfile -ExecutionPolicy Bypass -Command "$env:PANTHEON_ARGS='join <invite link>'; irm https://relay.joinpantheon.network/install.ps1 | iex"
+#
+# One line for either window (what `pantheon invite` prints): PowerShell would
+# expand the $env: above inside the outer double quotes before the inner
+# PowerShell runs, so this sets the variable without a $, and with a cmdlet
+# that Constrained Language Mode still allows:
+#   powershell -NoProfile -ExecutionPolicy Bypass -Command "Set-Item Env:PANTHEON_ARGS 'join <invite link>'; irm https://relay.joinpantheon.network/install.ps1 | iex"
+#
+# `irm | iex` cannot pass arguments, so the arguments for pantheon travel in
+# $env:PANTHEON_ARGS, which reads the same from PowerShell and from cmd.exe.
+# The scriptblock form passes them as real arguments instead. When both are
+# given, the real arguments win. PANTHEON_ARGS is cleared once read, so a later
+# plain install in the same window does not repeat a `join`.
+#
+# What it does, and nothing else:
+#   1. downloads one pinned Node release (the win-x64 or win-arm64 zip) from
+#      nodejs.org, checks its sha256 against the one pinned in this file, and
+#      unpacks it into %LOCALAPPDATA%\Pantheon\runtime\node. That Node is
+#      Pantheon's own; a Node you already have is not touched.
+#   2. installs the Pantheon CLI with THAT Node's npm into that same folder.
+#      No administrator rights, no execution-policy change, no WSL.
+#   3. writes %LOCALAPPDATA%\Pantheon\bin\pantheon.cmd, which runs that Node.
+#   4. puts %LOCALAPPDATA%\Pantheon\bin first on your user PATH, and on this
+#      window's PATH.
+#   5. runs `pantheon <the arguments you gave>`.
+#
+# Running it again is safe: whatever is already right is left as it is. Two
+# copies at once are safe too: the second waits for the first.
+# The relay that serves this file fills in the Pantheon version below.
+
+# Constrained Language Mode (an IT policy: AppLocker or WDAC) refuses the .NET
+# calls this installer needs. Said plainly, before the first one fails with an
+# error about "core types". `throw` makes `powershell -Command ... | iex` exit 1
+# (Write-Error inside iex does not), and leaves an open window open.
+if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') {
+  Write-Host 'pantheon install failed: PowerShell on this computer runs in Constrained Language Mode (set by your IT), which this installer cannot run in. Ask IT to allow it, or if you have Node.js 22.13 or newer: npm install -g @join-pantheon/cli' -ForegroundColor Red
+  Remove-Item Env:PANTHEON_ARGS -ErrorAction SilentlyContinue
+  throw 'Pantheon was not installed (Constrained Language Mode).'
+}
+
+# The arguments of the scriptblock form; empty under `irm | iex`.
+$PantheonInstallArgs = @()
+try { if ($null -ne $args) { $PantheonInstallArgs = @($args) } } catch { $PantheonInstallArgs = @() }
+
+# The result travels in $State rather than as output: anything a function
+# returns is captured from its output stream, and pantheon's own output must
+# reach the console untouched.
+function Install-Pantheon {
+  param([string[]]$Arguments = @(), [hashtable]$State)
+
+  $PantheonVersion = '__PANTHEON_VERSION__'
+  $NodeVersion = '22.23.3'
+  # The sha256 of each Node zip this script may install, from nodejs.org's
+  # SHASUMS256.txt for $NodeVersion. A download is checked against THESE, never
+  # against a sums file fetched beside it, which a mirror could serve to match
+  # whatever it sends. Bumping $NodeVersion means new pins: scripts/node-pins.mjs.
+  $NodePins = @{
+    'node-v22.23.3-win-arm64.zip' = '33dad22e4cef5ee8f9fbb1b0d037fdacd0e56d12a4580f0d63f68b894deab535'
+    'node-v22.23.3-win-x64.zip' = '2b0ff57b049cda1bbcea2240eec20467018713c1efe1f7360c2681859b90ed71'
+  }
+  # Another copy of nodejs.org/dist (a company mirror), if nodejs.org is blocked.
+  $NodeDist = if ($env:PANTHEON_NODE_MIRROR) { $env:PANTHEON_NODE_MIRROR.TrimEnd('/') } else { 'https://nodejs.org/dist' }
+  $Site = 'https://relay.joinpantheon.network'
+
+  $ErrorActionPreference = 'Stop'
+  # Invoke-WebRequest's progress bar makes Windows PowerShell 5.1 downloads many times slower.
+  $ProgressPreference = 'SilentlyContinue'
+  # Every failure is one plain line: what failed, and what to do about it.
+  function Fail([string]$Message) { throw "PANTHEON_FAIL:$Message" }
+  function Say([string]$Message) { Write-Host $Message }
+  function Note([string]$Message) { Write-Host "note: $Message" -ForegroundColor Yellow }
+
+  # One argument string as the C runtime (and so node.exe) splits it back up.
+  function ConvertTo-ArgLine([string[]]$Items) {
+    ($Items | ForEach-Object {
+      if ($_ -eq '') { '""' }
+      elseif ($_ -notmatch '[\s"]') { $_ }
+      else { '"' + (($_ -replace '(\\*)"', '$1$1\"') -replace '(\\+)$', '$1$1') + '"' }
+    }) -join ' '
+  }
+
+  # Run a program with its output into a log file and nothing on screen. A
+  # Process object, because in Windows PowerShell 5.1 redirecting a native
+  # command's stderr under ErrorActionPreference=Stop turns its first warning
+  # line into a terminating error.
+  function Invoke-Logged([string]$Exe, [string[]]$Items, [string]$LogFile) {
+    $r = Invoke-Quiet $Exe $Items
+    [IO.File]::WriteAllText($LogFile, $r.out + $r.err)
+    return $r.code
+  }
+  # The same, with the output handed back instead: @{ code; out; err }.
+  function Invoke-Quiet([string]$Exe, [string[]]$Items) {
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = $Exe
+    $psi.Arguments = ConvertTo-ArgLine $Items
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.RedirectStandardInput = $true
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $p = [System.Diagnostics.Process]::Start($psi)
+    $p.StandardInput.Close()
+    $out = $p.StandardOutput.ReadToEndAsync()
+    $err = $p.StandardError.ReadToEndAsync()
+    $p.WaitForExit()
+    return @{ code = $p.ExitCode; out = $out.Result; err = $err.Result }
+  }
+
+  try {
+    if ($PantheonVersion -like '*__*') {
+      Fail "this copy of install.ps1 has no version filled in. Use the one the relay serves: irm $Site/install.ps1 | iex"
+    }
+
+    # ---- what this machine is ----------------------------------------------
+
+    $State.step = 'checking this machine'
+    if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) {
+      Fail "this installer is for Windows. On macOS or Linux: curl -fsSL $Site/install.sh | sh"
+    }
+    if ([Environment]::OSVersion.Version.Major -lt 10) {
+      Fail "Node $NodeVersion needs Windows 10, Windows Server 2016 or newer."
+    }
+    $arch = $null
+    try { $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString() } catch { $arch = $null }
+    if (-not $arch) { $arch = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE } }
+    switch -regex ($arch) {
+      '^(X64|AMD64)$' { $nodeArch = 'x64'; break }
+      '^ARM64$' { $nodeArch = 'arm64'; break }
+      default { Fail "this processor ($arch) has no Node $NodeVersion build for Windows. Pantheon runs on x64 and arm64." }
+    }
+
+    # A cloud workspace can install Pantheon, but what it installs goes away with
+    # the session. The same names src/host-env.ts looks for.
+    $cloud = @('CODESPACES', 'CLOUDENV_ENVIRONMENT_ID', 'REMOTE_CONTAINERS', 'DEVCONTAINER', 'GITPOD_WORKSPACE_ID', 'CLOUD_SHELL', 'REPL_ID', 'KUBERNETES_SERVICE_HOST') |
+      Where-Object { [Environment]::GetEnvironmentVariable($_) }
+    if ($cloud) {
+      Note "this looks like a cloud workspace, not the computer you work on (`$$($cloud -join ', $') set). Pantheon will install, but it goes away with this session."
+    }
+
+    # Windows PowerShell 5.1 may still offer only TLS 1.0 to nodejs.org.
+    try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 } catch { }
+
+    # Both spellings, so Invoke-WebRequest, npm and Pantheon see the same proxy.
+    foreach ($pair in @(@('HTTPS_PROXY', 'https_proxy'), @('HTTP_PROXY', 'http_proxy'), @('NO_PROXY', 'no_proxy'))) {
+      $v = [Environment]::GetEnvironmentVariable($pair[0]); if (-not $v) { $v = [Environment]::GetEnvironmentVariable($pair[1]) }
+      if ($v) { [Environment]::SetEnvironmentVariable($pair[0], $v, 'Process'); [Environment]::SetEnvironmentVariable($pair[1], $v, 'Process') }
+    }
+    $proxy = $env:HTTPS_PROXY
+
+    $localAppData = [Environment]::GetFolderPath('LocalApplicationData')
+    if (-not $localAppData) { $localAppData = $env:LOCALAPPDATA }
+    if (-not $localAppData) { Fail 'LOCALAPPDATA is not set, so there is nowhere to install. Run this from your own Windows account.' }
+    $root = Join-Path $localAppData 'Pantheon'
+    $runtime = Join-Path $root 'runtime'
+    $nodeDir = Join-Path $runtime 'node'
+    $nodeExe = Join-Path $nodeDir 'node.exe'
+    $npmCli = Join-Path $nodeDir 'node_modules\npm\bin\npm-cli.js'
+    $pkgDir = Join-Path $nodeDir 'node_modules\@join-pantheon\cli'
+    $entry = Join-Path $pkgDir 'bin\pantheon.js'
+    $binDir = Join-Path $root 'bin'
+    $launcher = Join-Path $binDir 'pantheon.cmd'
+    $log = Join-Path $root 'install.log'
+
+    $State.step = "creating $root"
+    try { New-Item -ItemType Directory -Force -Path $runtime, $binDir | Out-Null }
+    catch { Fail "could not create $runtime ($($_.Exception.Message)). Check that the folder is yours and the disk has space, then run this again." }
+
+    # ---- one installer at a time -------------------------------------------
+
+    # Two installers at once (a second window, a line pasted twice) would swap
+    # the runtime under each other. The lock is a file this process holds open
+    # with no sharing; Windows lets go of it when the process ends, however it
+    # ends (Ctrl-C, a closed window, Task Manager), so it is never stale. The
+    # second installer waits for the first, then finds everything in place.
+    $State.step = 'waiting for another Pantheon install'
+    $lockFile = Join-Path $runtime 'install.lock'
+    $waited = 0
+    while (-not $State.lock) {
+      try { $State.lock = [IO.File]::Open($lockFile, [IO.FileMode]::OpenOrCreate, [IO.FileAccess]::ReadWrite, [IO.FileShare]::None) }
+      catch {
+        $ex = $_.Exception
+        while ($ex.InnerException) { $ex = $ex.InnerException }
+        if ($ex -isnot [IO.IOException]) { throw }
+        if ($waited -eq 0) { Say 'Another Pantheon install is running; waiting for it to finish...' }
+        if ($waited -ge 600) { Fail 'another Pantheon install has been running for over 10 minutes. Let it finish or close its window, then run this again.' }
+        Start-Sleep -Seconds 1
+        $waited++
+      }
+    }
+    # What an installer stopped by a power cut left behind (see $tmp below).
+    Get-ChildItem -LiteralPath $runtime -Directory -Force -ErrorAction SilentlyContinue |
+      Where-Object { $_.Name -match '^t[0-9a-f]{6}$' } |
+      ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction SilentlyContinue }
+
+    function Get-Download([string]$Url, [string]$OutFile) {
+      $params = @{ Uri = $Url; OutFile = $OutFile; UseBasicParsing = $true }
+      if ($proxy) { $params.Proxy = $proxy; $params.ProxyUseDefaultCredentials = $true }
+      $last = ''
+      for ($i = 1; $i -le 3; $i++) {
+        try { Invoke-WebRequest @params; return } catch { $last = $_.Exception.Message; Start-Sleep -Seconds 2 }
+      }
+      Fail "could not download $Url ($last). Check your internet connection; behind a proxy set HTTPS_PROXY; then run this again."
+    }
+
+    # ---- 1. Pantheon's own Node --------------------------------------------
+
+    $haveNode = ''
+    if (Test-Path -LiteralPath $nodeExe) { try { $haveNode = (& $nodeExe --version) 2>$null } catch { $haveNode = '' } }
+    if ($haveNode -eq "v$NodeVersion") {
+      Say "Node v$NodeVersion for Pantheon is already in $nodeDir."
+    } else {
+      $zipName = "node-v$NodeVersion-win-$nodeArch.zip"
+      # Short names on purpose: npm's deepest file plus this folder must stay
+      # under Windows PowerShell's 260-character path limit.
+      $tmp = Join-Path $runtime ('t' + [Guid]::NewGuid().ToString('N').Substring(0, 6))
+      New-Item -ItemType Directory -Force -Path $tmp | Out-Null
+      $aside = $null
+      try {
+        $State.step = "downloading Node v$NodeVersion"
+        Say "Downloading Node v$NodeVersion for Pantheon (win-$nodeArch)..."
+        $zip = Join-Path $tmp $zipName
+        $want = $NodePins[$zipName]
+        if (-not $want) { Fail "this installer has no checksum for $zipName, so it cannot install Node here. Install Node 22.13 or newer yourself, then: npm install -g @join-pantheon/cli@$PantheonVersion" }
+        Get-Download "$NodeDist/v$NodeVersion/$zipName" $zip
+
+        $State.step = 'checking the Node download'
+        # .NET, not Get-FileHash: that is a script function in Microsoft.PowerShell.Utility,
+        # and Windows PowerShell 5.1 started from PowerShell 7 (the line pasted into pwsh)
+        # inherits pwsh's module path and cannot load it ("Get-FileHash is not recognized").
+        $stream = [IO.File]::OpenRead($zip)
+        try {
+          $sha = [Security.Cryptography.SHA256]::Create()
+          $got = (($sha.ComputeHash($stream) | ForEach-Object { $_.ToString('x2') }) -join '')
+        } finally { $stream.Dispose() }
+        if ($got -ne $want) { Fail "the Node download does not match its published sha256 (expected $want, got $got), so it was not used. Something between you and nodejs.org changed it; run this again on another network." }
+
+        # Unpacked entry by entry with the archive's top folder stripped, so no
+        # path is ever longer than it will be once installed.
+        $State.step = 'unpacking Node'
+        $new = Join-Path $tmp 'n'
+        try { Add-Type -AssemblyName System.IO.Compression.FileSystem -ErrorAction Stop } catch { }
+        try { Add-Type -AssemblyName System.IO.Compression -ErrorAction Stop } catch { }
+        $archive = [System.IO.Compression.ZipFile]::OpenRead($zip)
+        try {
+          foreach ($e in $archive.Entries) {
+            $rel = $e.FullName -replace '^[^/\\]+[/\\]', ''
+            if (-not $rel -or $rel -eq $e.FullName) { continue }
+            $dest = Join-Path $new ($rel -replace '/', '\')
+            if ($e.FullName.EndsWith('/') -or $e.FullName.EndsWith('\')) { New-Item -ItemType Directory -Force -Path $dest | Out-Null; continue }
+            New-Item -ItemType Directory -Force -Path (Split-Path -Parent $dest) | Out-Null
+            [System.IO.Compression.ZipFileExtensions]::ExtractToFile($e, $dest, $true)
+          }
+        } finally { $archive.Dispose() }
+        $newNode = Join-Path $new 'node.exe'
+        if (-not (Test-Path -LiteralPath $newNode)) { Fail 'the Node archive did not have the layout expected. Run this again; if it repeats, send this line to sid@joinpantheon.network' }
+        try { $ok = (& $newNode --version) 2>$null } catch { $ok = '' }
+        if ($ok -ne "v$NodeVersion") { Fail "Node v$NodeVersion does not run on this Windows. Install Node 22.13 or newer yourself, then: npm install -g @join-pantheon/cli@$PantheonVersion" }
+
+        # The CLI from the old runtime moves into the new one with it, so the
+        # pantheon command keeps working until npm below has run.
+        $oldPkgs = Join-Path $nodeDir 'node_modules\@join-pantheon'
+        if (Test-Path -LiteralPath $oldPkgs) {
+          try { Copy-Item -LiteralPath $oldPkgs -Destination (Join-Path $new 'node_modules') -Recurse -Force } catch { }
+        }
+
+        # Swapped by rename, never unpacked over: a half-written runtime is never
+        # the one an agent window starts.
+        $State.step = 'putting Node in place'
+        $aside = $null
+        if (Test-Path -LiteralPath $nodeDir) {
+          $aside = Join-Path $tmp 'old'
+          # A virus scanner looking at the new or old node.exe holds it for a
+          # moment: a few tries before telling the person something is open.
+          $moved = $false
+          for ($i = 1; $i -le 5 -and -not $moved; $i++) {
+            try { Move-Item -LiteralPath $nodeDir -Destination $aside; $moved = $true } catch { Start-Sleep -Seconds 2 }
+          }
+          if (-not $moved) { Fail "Pantheon's Node in $nodeDir is in use. Close your agent windows (Claude Code, Cursor, VS Code) and any pantheon command, then run this again." }
+        }
+        $placed = $false; $lastErr = ''
+        for ($i = 1; $i -le 5 -and -not $placed; $i++) {
+          try { Move-Item -LiteralPath $new -Destination $nodeDir; $placed = $true } catch { $lastErr = $_.Exception.Message; Start-Sleep -Seconds 2 }
+        }
+        if (-not $placed) {
+          if ($aside) { try { Move-Item -LiteralPath $aside -Destination $nodeDir } catch { } }
+          Fail "could not put the new Node in $nodeDir ($lastErr). Check free disk space, then run this again."
+        }
+        Say "Node v$NodeVersion is in $nodeDir."
+      } finally {
+        # Stopped between the two moves: the old runtime goes back, so the
+        # pantheon command keeps working.
+        if ($aside -and -not (Test-Path -LiteralPath $nodeDir) -and (Test-Path -LiteralPath $aside)) {
+          try { Move-Item -LiteralPath $aside -Destination $nodeDir } catch { }
+        }
+        Remove-Item -LiteralPath $tmp -Recurse -Force -ErrorAction SilentlyContinue
+      }
+    }
+
+    # ---- 2. the Pantheon CLI, with that Node's own npm -----------------------
+
+    # The version of the CLI in the runtime, but only when it is whole: its
+    # package.json names that version AND it starts and says so. A run stopped
+    # halfway through npm can leave the first without the second; that is
+    # installed again, never called done.
+    $manifest = Join-Path $pkgDir 'package.json'
+    $installedCli = {
+      $v = ''
+      if ((Test-Path -LiteralPath $manifest) -and (Test-Path -LiteralPath $entry)) {
+        try { $v = [string](Get-Content -LiteralPath $manifest -Raw | ConvertFrom-Json).version } catch { $v = '' }
+        if ($v -and (Invoke-Quiet $nodeExe @($entry, '--version')).out.Trim() -ne $v) { $v = '' }
+      }
+      $v
+    }
+
+    # What npm installs. PANTHEON_INSTALL_SPEC swaps the registry package for a
+    # package file on this machine, so a release candidate goes through this
+    # exact script before its version is on npm. Only a full path on a drive
+    # (C:\...\x.tgz) is taken: no URL, no \\server share, no git or registry
+    # spec, so it can never send an install anywhere npm would not have gone.
+    # Whoever can set it can already set npm_config_registry or NODE_OPTIONS
+    # for this window, so it opens no new way in; and what it installs must
+    # answer as $PantheonVersion (checked below), or the install fails.
+    $spec = "@join-pantheon/cli@$PantheonVersion"
+    if ($env:PANTHEON_INSTALL_SPEC) {
+      $s = $env:PANTHEON_INSTALL_SPEC
+      if ($s -notmatch '^[A-Za-z]:\\.*\.tgz$') { Fail "PANTHEON_INSTALL_SPEC must be the full path of a package .tgz on this machine (C:\...\x.tgz), not $s. Remove it to install from npm: Remove-Item Env:PANTHEON_INSTALL_SPEC" }
+      if (-not (Test-Path -LiteralPath $s -PathType Leaf)) { Fail "PANTHEON_INSTALL_SPEC is $s, which is not a file. Remove it to install from npm: Remove-Item Env:PANTHEON_INSTALL_SPEC" }
+      $spec = $s
+      Note "installing Pantheon $PantheonVersion from $s, not from npm (PANTHEON_INSTALL_SPEC is set)."
+    }
+
+    # The Windows certificate store, as well as Node's own: on a network that
+    # inspects secure traffic, the company's root is only there. npm needs it to
+    # install and pantheon needs it to reach its relay, so the launcher below
+    # runs Node with it too (when this Node has the flag; the pinned one does).
+    $ca = @()
+    if ((Invoke-Quiet $nodeExe @('--use-system-ca', '-e', '0')).code -eq 0) { $ca = @('--use-system-ca') }
+
+    $haveCli = & $installedCli
+    if ($haveCli -eq $PantheonVersion) {
+      Say "Pantheon $PantheonVersion is already installed."
+    } else {
+      $State.step = "installing Pantheon $PantheonVersion"
+      Say "Installing Pantheon $PantheonVersion..."
+      # npm.cmd only runs node.exe on npm-cli.js; doing that directly keeps
+      # cmd.exe, and its way with % and & in a path, out of it. The prefix is
+      # named, because the Node zip's own npmrc sends global installs to
+      # %APPDATA%\npm; the cache is Pantheon's own, so a broken npm cache
+      # elsewhere cannot fail this. --use-system-ca (when this Node has it)
+      # trusts the Windows certificate store, as Invoke-WebRequest just did,
+      # which is what a TLS-inspecting company proxy needs.
+      $env:Path = "$nodeDir;$env:Path"
+      $npmArgs = $ca + @($npmCli, 'install', '-g', '--prefix', $nodeDir, '--cache', (Join-Path $runtime 'npm-cache'),
+        $spec, '--no-audit', '--no-fund', '--loglevel=error', '--fetch-timeout=60000', '--fetch-retries=2')
+      $code = Invoke-Logged $nodeExe $npmArgs $log
+      if ($code -ne 0) {
+        $why = (Get-Content -LiteralPath $log | Where-Object { $_ -match '^npm (error|ERR!) ' } | Select-Object -First 2 | ForEach-Object { $_ -replace '^npm (error|ERR!) ', '' }) -join '; '
+        if (-not $why) { $why = "npm exited $code" }
+        if ((Get-Content -LiteralPath $log -Raw) -match 'ENOSPC') {
+          Fail "npm could not install @join-pantheon/cli@$PantheonVersion because the disk is full ($why). Free some disk space, then run this again."
+        }
+        Fail "npm could not install @join-pantheon/cli@$PantheonVersion ($why). Behind a proxy, set HTTPS_PROXY; if your network inspects TLS, set NODE_EXTRA_CA_CERTS to your company's CA file. Full log: $log"
+      }
+      if (-not (Test-Path -LiteralPath $entry)) { Fail "npm finished but $entry is not there. Full log: $log (send it to sid@joinpantheon.network)" }
+      $haveCli = & $installedCli
+      if ($haveCli -ne $PantheonVersion) { Fail "npm finished, but the Pantheon in $pkgDir does not start as $PantheonVersion$(if ($haveCli) { " (it is $haveCli)" }). Run the same command again; if it fails the same way, send this line and $log to sid@joinpantheon.network" }
+      Say "Pantheon $PantheonVersion is installed."
+    }
+
+    # ---- 3. the launcher -----------------------------------------------------
+
+    # %~dp0 is the folder this .cmd is in, so the file holds no path of its own:
+    # nothing in it depends on PATH, and a profile folder with a % or a
+    # non-ASCII letter in its name (which cmd.exe would read in the console's
+    # code page) cannot break it.
+    $State.step = "writing $launcher"
+    $cmdText = "@echo off`r`n" +
+      "rem The pantheon command, written by the Pantheon installer. It runs Pantheon's own`r`n" +
+      "rem Node by absolute path, so it never depends on which node comes first on PATH.`r`n" +
+      "`"%~dp0..\runtime\node\node.exe`" $(if ($ca.Count) { '--use-system-ca ' })`"%~dp0..\runtime\node\node_modules\@join-pantheon\cli\bin\pantheon.js`" %*`r`n"
+    $current = if (Test-Path -LiteralPath $launcher) { [IO.File]::ReadAllText($launcher) } else { '' }
+    if ($current -ne $cmdText) {
+      try { [IO.File]::WriteAllText($launcher, $cmdText, [Text.Encoding]::ASCII) }
+      catch { Fail "could not write $launcher ($($_.Exception.Message)). Close any window running pantheon, then run this again." }
+    }
+
+    # ---- 4. PATH -------------------------------------------------------------
+
+    $State.step = 'adding Pantheon to your PATH'
+    $same = { param($a, $b) ([Environment]::ExpandEnvironmentVariables($a).TrimEnd('\')) -ieq ([Environment]::ExpandEnvironmentVariables($b).TrimEnd('\')) }
+    # Read raw from the registry: [Environment]::GetEnvironmentVariable expands
+    # %USERPROFILE%-style entries, and writing that back would freeze them.
+    $key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+    try {
+      $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+      $parts = @($raw -split ';' | Where-Object { $_ -ne '' })
+      if ($parts.Count -eq 0 -or -not (& $same $parts[0] $binDir)) {
+        $rest = @($parts | Where-Object { -not (& $same $_ $binDir) })
+        $key.SetValue('Path', ((@($binDir) + $rest) -join ';'), [Microsoft.Win32.RegistryValueKind]::ExpandString)
+        # SetEnvironmentVariable(..., 'User') is what tells Explorer and new
+        # terminals that the user environment changed (WM_SETTINGCHANGE).
+        [Environment]::SetEnvironmentVariable('PANTHEON_PATH_UPDATED', '1', 'User')
+        [Environment]::SetEnvironmentVariable('PANTHEON_PATH_UPDATED', $null, 'User')
+        Say "Put $binDir first on your user PATH."
+      }
+    } finally { $key.Close() }
+    # This window: the bin folder first, and the runtime's own folder (added
+    # for npm above) taken off again, as no new terminal will have it.
+    $env:Path = (@($binDir) + @($env:Path -split ';' | Where-Object { $_ -ne '' -and -not (& $same $_ $binDir) -and -not (& $same $_ $nodeDir) })) -join ';'
+
+    # An older pantheon (npm -g, a checkout) is left exactly as it is. A
+    # pantheon on the SYSTEM PATH still comes before any user PATH entry.
+    $other = Get-Command pantheon -All -ErrorAction SilentlyContinue |
+      Where-Object { $_.Source -and -not $_.Source.StartsWith($root + '\', [StringComparison]::OrdinalIgnoreCase) } | Select-Object -First 1
+    if ($other) { Note "another pantheon is installed at $($other.Source) and was left as it is. New terminals run $launcher first, unless that one is on the system PATH." }
+
+    # ---- 5. hand over to pantheon ------------------------------------------
+
+    $State.lock.Dispose()
+    $State.lock = $null
+    if ($Arguments.Count -eq 0) {
+      Say ''
+      Say "Pantheon $PantheonVersion is installed. Open a new terminal, then:"
+      Say '  pantheon start                    create a team'
+      Say "  pantheon join '<invite link>'     join a teammate's team"
+      $State.code = 0
+      return
+    }
+    Say ''
+    # node.exe directly, not the .cmd: PowerShell hands arguments to a .cmd
+    # through cmd.exe, which would cut an invite at a & or expand a %. And
+    # Start-Process -NoNewWindow, so pantheon gets this console itself: a real
+    # terminal for the sign-in questions, not a pipe PowerShell reads from.
+    $State.step = 'starting pantheon'
+    $line = ConvertTo-ArgLine (@($entry) + $Arguments)
+    $noConsole = $false
+    try { $noConsole = [Console]::IsInputRedirected } catch { $noConsole = $false }
+    if (-not $noConsole) {
+      $p = Start-Process -FilePath $nodeExe -ArgumentList $line -NoNewWindow -PassThru
+      $null = $p.Handle   # without this, ExitCode is empty once the process is gone
+      $p.WaitForExit()
+      $State.code = $p.ExitCode
+      return
+    }
+
+    # No console to type into (CI, input piped in). pantheon still runs: it
+    # never asks a question without a terminal (every prompt checks
+    # process.stdin.isTTY) and works on flags alone, so a join to a team's own
+    # relay, or from a machine already signed in, needs no answers. Its input
+    # is an empty file, so nothing can wait on it. What it cannot do here is
+    # sign in: on the hosted relay join and start stop at once, before anything
+    # is changed, with "sign in first" (or the relay's NOT_SIGNED_IN). When that
+    # is how it ended and config.json still has no account, the last line says
+    # the one thing to do; any other failure keeps pantheon's own words last.
+    $quiet = Join-Path ([IO.Path]::GetTempPath()) ('pantheon-' + [Guid]::NewGuid().ToString('N').Substring(0, 8))
+    New-Item -ItemType Directory -Force -Path $quiet | Out-Null
+    try {
+      $in = Join-Path $quiet 'in'; $errFile = Join-Path $quiet 'err'
+      [IO.File]::WriteAllText($in, '')
+      $p = Start-Process -FilePath $nodeExe -ArgumentList $line -NoNewWindow -PassThru -RedirectStandardInput $in -RedirectStandardError $errFile
+      $null = $p.Handle
+      $p.WaitForExit()
+      $State.code = $p.ExitCode
+      $said = if (Test-Path -LiteralPath $errFile) { [IO.File]::ReadAllText($errFile) } else { '' }
+      if ($said) { [Console]::Error.Write($said) }
+      if ($State.code -ne 0 -and $said -match 'sign in first|NOT_SIGNED_IN' -and $Arguments[0] -in @('join', 'start')) {
+        $pantheonHome = if ($env:PANTHEON_HOME) { $env:PANTHEON_HOME } else { Join-Path ([Environment]::GetFolderPath('UserProfile')) '.pantheon' }
+        $signedIn = $false
+        try { $signedIn = [bool]((Get-Content -LiteralPath (Join-Path $pantheonHome 'config.json') -Raw | ConvertFrom-Json).account) } catch { $signedIn = $false }
+        if (-not $signedIn) {
+          # Quoted only where PowerShell needs it, so it reads as typed.
+          $show = ($Arguments | ForEach-Object { if ($_ -match '^[A-Za-z0-9_./:=@+,-]+$') { $_ } else { "'" + ($_ -replace "'", "''") + "'" } }) -join ' '
+          $what = if ($Arguments[0] -eq 'join') { 'joining' } else { 'creating your team' }
+          Say ''
+          Say "Pantheon is installed. To finish $what, open PowerShell and run: pantheon $show"
+        }
+      }
+    } finally {
+      Remove-Item -LiteralPath $quiet -Recurse -Force -ErrorAction SilentlyContinue
+    }
+  } catch {
+    $m = $_.Exception.Message
+    if ($m -like 'PANTHEON_FAIL:*') { $m = $m.Substring('PANTHEON_FAIL:'.Length) }
+    else { $m = "it stopped while $($State.step) ($m). Run the same command again; if it fails the same way, send this line to sid@joinpantheon.network" }
+    Write-Host "pantheon install failed: $m" -ForegroundColor Red
+    $State.code = 1
+  } finally {
+    # Every way out, Ctrl-C included, lets go of the install lock.
+    if ($State.lock) { $State.lock.Dispose(); $State.lock = $null }
+  }
+}
+
+# `join '<link>'` as two arguments: whitespace splits, and single or double
+# quotes keep a value with spaces in it together.
+function Split-PantheonArgs([string]$Line) {
+  $out = New-Object System.Collections.Generic.List[string]
+  $cur = New-Object System.Text.StringBuilder
+  $quote = [char]0
+  $have = $false
+  foreach ($c in $Line.ToCharArray()) {
+    if ($quote -ne [char]0) {
+      if ($c -eq $quote) { $quote = [char]0 } else { [void]$cur.Append($c) }
+    } elseif ($c -eq "'" -or $c -eq '"') { $quote = $c; $have = $true }
+    elseif ([char]::IsWhiteSpace($c)) { if ($have -or $cur.Length) { $out.Add($cur.ToString()); [void]$cur.Clear(); $have = $false } }
+    else { [void]$cur.Append($c) }
+  }
+  if ($have -or $cur.Length) { $out.Add($cur.ToString()) }
+  return , $out.ToArray()
+}
+
+# Whether this PowerShell was started to run one command and end
+# (`powershell -Command "... | iex"` from cmd.exe), where the exit code is the
+# result, rather than an open window, which `exit` would close. PowerShell
+# takes any prefix of a parameter's name, after -, -- or /; -NoExit anywhere
+# keeps the window open, so then it is never one-shot.
+function Test-PantheonOneShot([string[]]$CommandLine) {
+  $flags = @($CommandLine | Select-Object -Skip 1 | Where-Object { $_ -match '^(--?|/)[A-Za-z]+$' } |
+    ForEach-Object { ($_ -replace '^(--?|/)', '').ToLowerInvariant() })
+  $prefixOf = { param($f, $name, $min) $f.Length -ge $min -and $name.StartsWith($f) }
+  if ($flags | Where-Object { & $prefixOf $_ 'noexit' 3 }) { return $false }
+  foreach ($f in $flags) {
+    if ((& $prefixOf $f 'command' 1) -or (& $prefixOf $f 'commandwithargs' 8) -or $f -eq 'cwa' -or
+      (& $prefixOf $f 'encodedcommand' 1) -or $f -eq 'ec') { return $true }
+  }
+  return $false
+}
+
+if ($PantheonInstallArgs.Count -eq 0 -and $env:PANTHEON_ARGS) {
+  $PantheonInstallArgs = Split-PantheonArgs $env:PANTHEON_ARGS
+}
+Remove-Item Env:PANTHEON_ARGS -ErrorAction SilentlyContinue
+$PantheonInstallState = @{ code = 1; step = 'starting' }
+Install-Pantheon -Arguments $PantheonInstallArgs -State $PantheonInstallState
+$PantheonInstallCode = [int]$PantheonInstallState.code
+
+# `powershell -Command "... | iex"` from cmd.exe: the exit code is the result.
+# In an open PowerShell window `exit` would close the window, so there the
+# result is left in $LASTEXITCODE instead.
+$PantheonOneShot = $false
+try { $PantheonOneShot = Test-PantheonOneShot ([Environment]::GetCommandLineArgs()) } catch { $PantheonOneShot = $false }
+Remove-Item Function:Install-Pantheon, Function:Split-PantheonArgs, Function:Test-PantheonOneShot -ErrorAction SilentlyContinue
+Remove-Variable PantheonInstallArgs, PantheonInstallState -ErrorAction SilentlyContinue
+$global:LASTEXITCODE = $PantheonInstallCode
+if ($PantheonOneShot) { exit $PantheonInstallCode }