@basein/runner 0.2.8 → 0.2.10

package/scripts/install.ps1

@@ -0,0 +1,669 @@
+<#
+.SYNOPSIS
+    Set up the BaseIn runner on Windows in one paste: a Node if needed, the
+    @basein/runner package, Claude Code, then `bir setup` for this folder.
+
+.DESCRIPTION
+    Served by the API as https://api.<domain>/install.ps1 and meant to be run
+    from a terminal opened in the project you start Claude Code in:
+
+        $env:BIR_SETUP_TOKEN="<token>"; irm https://api.<domain>/install.ps1 | iex
+
+    It never prompts, never calls exit (under iex that would close the window),
+    never touches the execution policy, and is safe to re-run: re-running is
+    also the upgrade path. Everything lives under ~\.baseinstrunner.
+
+    Steps, in order (each prints a "==> " line):
+
+      0. the folder: the home directory and a drive root are refused before
+         anything is downloaded; the setup token is taken out of the
+         environment before anything else runs
+      1. Node: a Node >= 20 on PATH is used as long as its real binary is not
+         inside a version manager (fnm, nvm, Volta, Scoop, asdf, mise), else a
+         private, digest-checked Node goes to ~\.baseinstrunner\node\v<V>\ and
+         is never put on PATH
+      2. the runner: @basein/runner is installed into ~\.baseinstrunner\npm,
+         always through npm-cli.js (never the npm shim); bir.cmd and
+         bir-hooks.cmd are written to ~\.baseinstrunner\bin, which goes first
+         on the user Path
+      3. Claude Code, through its official installer, when `claude` is missing
+      4. `bir setup --auth-url <api> --project <folder>`: signs in, wires the
+         project, starts the recorder, and prints what is left to do
+
+    The API rewrites two placeholders in this file (the service address and
+    the runner version, marked TEMPLATED below). Read raw from the repository
+    they count as unset: BIR_AUTH_URL is then required, the version is latest.
+
+    Environment (all optional):
+
+      BIR_SETUP_TOKEN   one-time setup token from the console; removed from the
+                        environment at once and handed to `bir setup` only
+      BIR_AUTH_URL      the API address, when this file was not served by it
+      BIR_PROJECT       the project folder, instead of the current one
+      BIR_NODE_VERSION  private Node version instead of the pinned one; its
+                        digest then comes from nodejs.org's SHASUMS256.txt
+      BIR_NODE_ARCHIVE  a local node-v<V>-win-<arch>.zip instead of the download
+      BIR_TARBALL       a local @basein/runner .tgz instead of the registry
+      BIR_NO_CLAUDE=1   do not install Claude Code
+      BIR_DRY_RUN=1     print every action and perform none: no download, no
+                        install, no registry write, no `bir setup`. For support:
+                        it shows what the line would do on a given machine.
+      HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS
+                        used for the downloads and passed to every child
+#>
+
+function Invoke-BirInstall {
+    # The token first, before any other statement: copied out of the environment
+    # and removed from it, so npm, the Claude Code installer and the `claude` the
+    # person starts next never see it. It reaches `bir setup` through that
+    # child's environment only, set right before the spawn and removed after.
+    $setupToken = $env:BIR_SETUP_TOKEN
+    if ($setupToken) { Remove-Item -Path Env:BIR_SETUP_TOKEN -ErrorAction SilentlyContinue }
+
+    # Inside the function on purpose: under `irm | iex` these would otherwise
+    # change the session the person keeps working in.
+    Set-StrictMode -Version Latest
+    $ErrorActionPreference = 'Stop'
+    # Invoke-WebRequest repaints a progress bar per chunk; on a 30 MB zip that
+    # takes longer than the download itself.
+    $ProgressPreference = 'SilentlyContinue'
+
+    # -- what the API templated in ----------------------------------------------
+    #
+    # TEMPLATED: the server rewrites the two values below. The comparison
+    # assembles the placeholder name at run time, so the comparison itself is
+    # never rewritten.
+    $templatedAuthUrl = '__BIR_AUTH_URL__'
+    $templatedVersion = '__BIR_VERSION__'
+
+    $packageName = '@basein/runner'
+    $pinnedNodeVersion = '24.21.0'
+    # Published digests for the pinned version, the same six as install.sh
+    # embeds; only the two Windows ones are used here. Anything else is checked
+    # against nodejs.org's SHASUMS256.txt, which is not pinned.
+    $pinnedDigests = @{
+        'node-v24.21.0-win-x64.zip'         = '158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541'
+        'node-v24.21.0-win-arm64.zip'       = '8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921'
+        'node-v24.21.0-darwin-arm64.tar.gz' = 'bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057'
+        'node-v24.21.0-darwin-x64.tar.gz'   = '1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097'
+        'node-v24.21.0-linux-x64.tar.gz'    = '6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff'
+        'node-v24.21.0-linux-arm64.tar.gz'  = '724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5'
+    }
+
+    $dryRun = ($env:BIR_DRY_RUN -eq '1')
+    $birHome = Join-Path $env:USERPROFILE '.baseinstrunner'
+    $tlsHint = "Your network inspects TLS. Set NODE_EXTRA_CA_CERTS to your company's CA bundle (ask IT) and run this again. Offline: BIR_TARBALL=<file.tgz> and BIR_NODE_ARCHIVE=<archive>."
+
+    # -- output -----------------------------------------------------------------
+
+    function Write-Step([string]$Message) { Write-Host "==> $Message" -ForegroundColor Cyan }
+    function Write-Note([string]$Message) { Write-Host "    $Message" -ForegroundColor DarkGray }
+    function Write-Warn([string]$Message) { Write-Host "    $Message" -ForegroundColor Yellow }
+    function Write-Would([string]$Message) { Write-Host "    [dry-run] would $Message" -ForegroundColor Magenta }
+
+    # -- helpers ----------------------------------------------------------------
+
+    # Runs a program and returns its exit code with everything it printed.
+    # $ErrorActionPreference is 'Continue' in here on purpose: Windows PowerShell
+    # 5.1 turns each redirected stderr line into an ErrorRecord, and under 'Stop'
+    # the first one (an "npm warn", say) would end the whole run.
+    function Invoke-Tool([string]$Exe, [string[]]$Arguments, [switch]$Quiet) {
+        $ErrorActionPreference = 'Continue'
+        $lines = New-Object System.Collections.Generic.List[string]
+        # Reset first: a program that never started (access denied, a quarantined
+        # binary) leaves $LASTEXITCODE at the previous command's value, which
+        # after a successful npm is 0 - and 0 would read as "it worked".
+        $global:LASTEXITCODE = -1
+        & $Exe @Arguments 2>&1 | ForEach-Object {
+            if ($_ -is [System.Management.Automation.ErrorRecord]) { $line = $_.Exception.Message } else { $line = [string]$_ }
+            $lines.Add($line)
+            if (-not $Quiet) { Write-Host $line }
+        }
+        $code = $global:LASTEXITCODE
+        if ($code -eq -1) { $lines.Add("$Exe could not be started."); $code = 127 }
+        return @{ Code = $code; Lines = $lines.ToArray() }
+    }
+
+    # The version line among a program's output. stderr is merged into stdout
+    # above, so a warning node prints at startup (a NODE_OPTIONS note, an extra
+    # certs complaint) can come first; the version is the line that looks like one.
+    function Get-VersionLine([string[]]$Lines) {
+        foreach ($l in @($Lines)) { if ($l.Trim() -match '^v?\d+\.\d+\.\d+$') { return $l.Trim() } }
+        return ''
+    }
+
+    # The first output line that names an existing file - for `node -p process.execPath`.
+    function Get-ExistingPathLine([string[]]$Lines) {
+        foreach ($l in @($Lines)) {
+            $t = $l.Trim()
+            if ($t -and (Test-Path -LiteralPath $t -PathType Leaf)) { return $t }
+        }
+        return ''
+    }
+
+    # A command line as the dry run prints it: arguments with spaces quoted, so
+    # the line can be pasted as it is.
+    function Format-CommandLine([string]$Exe, [string[]]$Arguments) {
+        $parts = New-Object System.Collections.Generic.List[string]
+        foreach ($a in @($Exe) + @($Arguments)) {
+            if ($a -match '\s') { $parts.Add('"' + $a + '"') } else { $parts.Add($a) }
+        }
+        return ($parts -join ' ')
+    }
+
+    # Trailing separators trimmed and case folded: "C:\Users\me\" and
+    # "c:\users\me" are the same folder.
+    function Get-ComparablePath([string]$Path) {
+        $trimmed = $Path.TrimEnd('\', '/')
+        if ($trimmed -eq '') { $trimmed = $Path }
+        return $trimmed.ToLowerInvariant()
+    }
+
+    # "v24.21.0" -> major, minor, and the bare text; $null when it is not a version.
+    function Get-NodeVersionParts([string]$Text) {
+        if ($Text.Trim() -match '^v?(\d+)\.(\d+)\.(\d+)') {
+            return @{ Major = [int]$matches[1]; Minor = [int]$matches[2]; Text = $Text.Trim().TrimStart('v') }
+        }
+        return $null
+    }
+
+    # --use-system-ca exists from Node 22.15; with it a corporate root in the
+    # Windows store is trusted without NODE_EXTRA_CA_CERTS.
+    function Get-NodeFlags([int]$Major, [int]$Minor) {
+        if (($Major -gt 22) -or ($Major -eq 22 -and $Minor -ge 15)) { return @('--use-system-ca') }
+        return @()
+    }
+
+    # A per-shell or per-version directory: fnm's multishell links vanish with
+    # the shell, and nvm, Volta, Scoop, asdf and mise switch or remove versions
+    # under the same path. The SessionStart hook pins an absolute node path, so
+    # such a Node must not be the one it pins.
+    function Test-ManagedNodePath([string]$Path) {
+        $markers = @('fnm_multishells', 'fnm', '.nvm', 'nvm', '.volta', 'volta', 'nodenv', '.nodenv', 'asdf', '.asdf', 'mise', '.mise', 'scoop')
+        foreach ($segment in $Path.Split([char[]]@('\', '/'))) {
+            if ($markers -icontains $segment) { return $true }
+        }
+        return $false
+    }
+
+    function Get-Sha256([string]$Path) {
+        return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
+    }
+
+    # The digest of one archive from nodejs.org's SHASUMS256.txt: an anchored,
+    # exact-filename match, and exactly one line or nothing.
+    function Get-PublishedDigest([string]$Version, [string]$FileName) {
+        $url = "https://nodejs.org/dist/v$Version/SHASUMS256.txt"
+        Write-Note "v$Version is not the pinned version; its digest comes from $url"
+        $text = (Invoke-WebRequest -UseBasicParsing -Uri $url @webOptions).Content
+        $pattern = '^([0-9a-fA-F]{64})\s+\*?' + [regex]::Escape($FileName) + '\s*$'
+        $found = New-Object System.Collections.Generic.List[string]
+        foreach ($line in ($text -split "`n")) {
+            if ($line.TrimEnd("`r") -match $pattern) { $found.Add($matches[1].ToLowerInvariant()) }
+        }
+        if ($found.Count -ne 1) { throw "SHASUMS256.txt for v$Version lists $FileName $($found.Count) times; expected exactly once." }
+        return $found[0]
+    }
+
+    # A private Node under ~\.baseinstrunner\node\v<V>\: versioned, so a running
+    # recorder keeps its files and nothing is extracted over a locked node.exe.
+    function Install-PrivateNode([string]$Version) {
+        $arch = $env:PROCESSOR_ARCHITEW6432
+        if (-not $arch) { $arch = $env:PROCESSOR_ARCHITECTURE }
+        switch ($arch) {
+            'AMD64' { $nodeArch = 'x64' }
+            'ARM64' { $nodeArch = 'arm64' }
+            default { throw "No Node build for a $arch Windows. Install Node 20 or newer from https://nodejs.org and paste the line again." }
+        }
+        $fileName = "node-v$Version-win-$nodeArch.zip"
+        $nodeDir = Join-Path $birHome "node\v$Version"
+        $exe = Join-Path $nodeDir 'node.exe'
+
+        if (Test-Path -LiteralPath $exe) {
+            $probe = Invoke-Tool $exe @('-v') -Quiet
+            if ($probe.Code -eq 0 -and (Get-VersionLine $probe.Lines) -eq "v$Version") {
+                Write-Note "node v$Version already at $exe"
+                return $exe
+            }
+            # Half an extraction or a foreign file: removed, never extracted over.
+            if ($dryRun) { Write-Would "remove the unusable $nodeDir" }
+            else {
+                try { Remove-Item -LiteralPath $nodeDir -Recurse -Force }
+                catch { throw "$nodeDir is unusable and cannot be removed (a recorder still using it?). Run 'bir down' and paste the line again." }
+            }
+        }
+
+        if ($Version -eq $pinnedNodeVersion -and $pinnedDigests.ContainsKey($fileName)) {
+            $expected = $pinnedDigests[$fileName]
+        }
+        elseif ($dryRun) {
+            Write-Would "fetch https://nodejs.org/dist/v$Version/SHASUMS256.txt for the digest of $fileName"
+            $expected = '<from SHASUMS256.txt>'
+        }
+        else {
+            $expected = Get-PublishedDigest $Version $fileName
+        }
+
+        $url = "https://nodejs.org/dist/v$Version/$fileName"
+        $archive = $env:BIR_NODE_ARCHIVE
+        $downloaded = $false
+        if ($archive) {
+            if (-not (Test-Path -LiteralPath $archive -PathType Leaf)) { throw "BIR_NODE_ARCHIVE is not a file: $archive" }
+            $archive = (Resolve-Path -LiteralPath $archive).ProviderPath
+            Write-Note "using the local archive $archive (BIR_NODE_ARCHIVE)"
+        }
+        else {
+            $archive = Join-Path $env:TEMP "bir-$fileName"
+            $downloaded = $true
+        }
+
+        $tar = Join-Path $env:SystemRoot 'System32\tar.exe'
+        $useTar = Test-Path -LiteralPath $tar
+        if ($dryRun) {
+            if ($downloaded) { Write-Would "download $url to $archive" }
+            Write-Would "check its SHA-256 against $expected"
+            if ($useTar) { Write-Would "extract it with $tar --strip-components=1 into $nodeDir" }
+            else { Write-Would "extract it with Expand-Archive (slow in Windows PowerShell 5.1) into $nodeDir" }
+            return $exe
+        }
+
+        if ($downloaded) {
+            Write-Note "downloading $url"
+            Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $archive @webOptions
+        }
+        $actual = Get-Sha256 $archive
+        if ($actual -ne $expected) {
+            if ($downloaded) { Remove-Item -LiteralPath $archive -Force -ErrorAction SilentlyContinue }
+            throw "$fileName does not match its published digest (expected $expected, got $actual). Nothing was installed."
+        }
+        Write-Note "digest ok: $expected"
+
+        # Extracted into a sibling directory, then one rename into place: there
+        # is never a half-written v<V>, and the rename stays on one volume.
+        $staging = Join-Path (Split-Path -Parent $nodeDir) (".v$Version-" + [guid]::NewGuid().ToString('N').Substring(0, 8))
+        New-Item -ItemType Directory -Path $staging -Force | Out-Null
+        try {
+            if ($useTar) {
+                # bsdtar reads zip files and strips the inner folder itself.
+                # Windows 10 1803+ ships it; Git's tar.exe is GNU tar and does not
+                # read zips, which is why the System32 one is named explicitly.
+                $r = Invoke-Tool $tar @('-xf', $archive, '-C', $staging, '--strip-components=1') -Quiet
+                if ($r.Code -ne 0) { throw "tar.exe could not extract $archive`: $($r.Lines -join ' ')" }
+                Move-Item -LiteralPath $staging -Destination $nodeDir
+            }
+            else {
+                Expand-Archive -LiteralPath $archive -DestinationPath $staging -Force
+                $inner = @(Get-ChildItem -LiteralPath $staging -Directory)
+                if ($inner.Count -ne 1) { throw "$fileName did not unpack into one folder as expected." }
+                Move-Item -LiteralPath $inner[0].FullName -Destination $nodeDir
+            }
+        }
+        finally {
+            if (Test-Path -LiteralPath $staging) { Remove-Item -LiteralPath $staging -Recurse -Force -ErrorAction SilentlyContinue }
+            if ($downloaded) { Remove-Item -LiteralPath $archive -Force -ErrorAction SilentlyContinue }
+        }
+
+        $probe = Invoke-Tool $exe @('-v') -Quiet
+        if (-not ($probe.Code -eq 0 -and (Get-VersionLine $probe.Lines) -eq "v$Version")) {
+            throw "$exe does not run as v$Version after extraction."
+        }
+        Write-Note "node v$Version at $exe (not on PATH; only the runner uses it)"
+        return $exe
+    }
+
+    # %USERPROFILE% instead of the literal profile path in a .cmd file: cmd.exe
+    # reads it in the console code page, and a profile named after a person
+    # (an umlaut, say) would not survive that as ASCII.
+    function ConvertTo-LauncherPath([string]$Path) {
+        $profileDir = $env:USERPROFILE.TrimEnd('\')
+        if ($Path.Length -gt $profileDir.Length -and $Path.Substring(0, $profileDir.Length + 1) -ieq ($profileDir + '\')) {
+            return '%USERPROFILE%' + $Path.Substring($profileDir.Length)
+        }
+        return $Path
+    }
+
+    function Write-Launcher([string]$Path, [string]$NodeExe, [string[]]$NodeFlags, [string]$Script) {
+        $flags = ''
+        if (@($NodeFlags).Count -gt 0) { $flags = ' ' + (@($NodeFlags) -join ' ') }
+        $content = '@"' + (ConvertTo-LauncherPath $NodeExe) + '"' + $flags + ' "' + (ConvertTo-LauncherPath $Script) + '" %*' + "`r`n"
+        if ($dryRun) {
+            Write-Would "write $Path`: $($content.Trim())"
+            return
+        }
+        $encoding = [System.Text.Encoding]::ASCII
+        foreach ($c in $content.ToCharArray()) {
+            if ([int]$c -gt 127) {
+                $encoding = [System.Text.Encoding]::GetEncoding([System.Globalization.CultureInfo]::CurrentCulture.TextInfo.OEMCodePage)
+                break
+            }
+        }
+        [System.IO.File]::WriteAllText($Path, $content, $encoding)
+        Write-Note "$Path -> $($content.Trim())"
+    }
+
+    # Explorer, and so every terminal started from the taskbar or Start, reads
+    # the user environment again only after this broadcast. setx sends it,
+    # Set-ItemProperty does not. Best effort: a host without a C# compiler still
+    # has the registry change, picked up at the next sign-in.
+    function Send-EnvironmentChange {
+        try {
+            if (-not ('BirInstall.Native' -as [type])) {
+                Add-Type -Namespace BirInstall -Name Native -MemberDefinition @'
+[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Auto)]
+public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint Msg, UIntPtr wParam, string lParam, uint fuFlags, uint uTimeout, out UIntPtr lpdwResult);
+'@
+            }
+            $result = [UIntPtr]::Zero
+            [BirInstall.Native]::SendMessageTimeout([IntPtr]0xffff, 0x1A, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$result) | Out-Null
+        }
+        catch {
+            Write-Note 'could not tell Explorer about the new Path; terminals opened from Start see it after the next sign-in'
+        }
+    }
+
+    # Additive only: this runs inside the person's shell, and replacing
+    # $env:Path would drop what that shell added for itself (a venv, a tool's
+    # per-shell directory). Registry entries missing here are appended.
+    function Update-SessionPath {
+        $known = New-Object System.Collections.Generic.List[string]
+        foreach ($p in $env:Path.Split(';')) { $known.Add($p.Trim().TrimEnd('\').ToLowerInvariant()) }
+        $registry = [string][Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [string][Environment]::GetEnvironmentVariable('Path', 'User')
+        foreach ($p in $registry.Split(';')) {
+            $dir = $p.Trim()
+            if ($dir -eq '') { continue }
+            $key = $dir.TrimEnd('\').ToLowerInvariant()
+            if (-not $known.Contains($key)) {
+                $env:Path = $env:Path + ';' + $dir
+                $known.Add($key)
+            }
+        }
+    }
+
+    # `claude` on PATH, or the native installer's ~\.local\bin when the Path
+    # change has not reached this shell yet.
+    function Get-ClaudePath {
+        $found = @(Get-Command claude -CommandType Application -ErrorAction SilentlyContinue)
+        if ($found.Count -ge 1) { return $found[0].Source }
+        $native = Join-Path $env:USERPROFILE '.local\bin\claude.exe'
+        if (Test-Path -LiteralPath $native) { return $native }
+        return ''
+    }
+
+    # ===========================================================================
+
+    try {
+        if ($dryRun) { Write-Warn 'BIR_DRY_RUN=1: printing what would happen; nothing is downloaded, installed or written.' }
+
+        # -- 00. the folder, before anything is downloaded ----------------------
+        #
+        # A terminal opened from Start begins in the home folder, and that is
+        # where a first paste often lands. Nothing is fetched until the folder
+        # looks like a project; BIR_PROJECT names one explicitly.
+        $project = ''
+        if ($env:BIR_PROJECT) {
+            if (-not (Test-Path -LiteralPath $env:BIR_PROJECT -PathType Container)) {
+                throw "BIR_PROJECT is not a folder: $($env:BIR_PROJECT)"
+            }
+            $project = (Resolve-Path -LiteralPath $env:BIR_PROJECT).ProviderPath
+            # Tab completion leaves a trailing backslash, and `"C:\has space\proj\"`
+            # on a command line reads as a path ending in a quote. A root keeps its.
+            if ($project.Length -gt ([System.IO.Path]::GetPathRoot($project)).Length) { $project = $project.TrimEnd('\', '/') }
+            Set-Location -LiteralPath $project
+            Write-Step "Setting up in $project (BIR_PROJECT)"
+        }
+        else {
+            $project = (Get-Location -PSProvider FileSystem).ProviderPath
+            $here = Get-ComparablePath $project
+            $reason = ''
+            foreach ($candidate in @($env:USERPROFILE, $HOME)) {
+                if ($candidate -and (Get-ComparablePath $candidate) -eq $here) { $reason = 'your home folder' }
+            }
+            if (-not $reason -and (Get-ComparablePath ([System.IO.Path]::GetPathRoot($project))) -eq $here) {
+                $reason = 'the root of a drive'
+            }
+            if ($reason) {
+                Write-Host "This is $reason. Open a terminal in the project you start Claude Code in (cd there) and paste the line again." -ForegroundColor Red
+                Write-Note 'Or name the project first:  $env:BIR_PROJECT = "C:\path\to\your\project"'
+                return
+            }
+            Write-Step "Setting up in $project"
+        }
+
+        # -- the service address and the version ---------------------------------
+        $authUrl = $templatedAuthUrl
+        if (-not $authUrl -or $authUrl -eq ('__BIR_' + 'AUTH_URL__')) { $authUrl = $env:BIR_AUTH_URL }
+        if (-not $authUrl) {
+            throw 'No service address: this file was not served by the API. Set $env:BIR_AUTH_URL = "https://api.your-service" and run it again.'
+        }
+        $authUrl = $authUrl.Trim().TrimEnd('/')
+        $version = $templatedVersion
+        if (-not $version -or $version -eq ('__BIR_' + 'VERSION__')) { $version = 'latest' }
+        Write-Note "service $authUrl, runner $packageName@$version"
+
+        # TLS 1.2 for the downloads; PowerShell 5.1 on an older Windows 10 still
+        # offers 1.0 and 1.1 by default and nodejs.org refuses those.
+        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+        $webOptions = @{}
+        $proxy = $env:HTTPS_PROXY
+        if (-not $proxy) { $proxy = $env:HTTP_PROXY }
+        if ($proxy) {
+            $webOptions['Proxy'] = $proxy
+            Write-Note "downloads go through $proxy"
+        }
+
+        # -- 1. Node ------------------------------------------------------------
+        Write-Step 'Checking Node'
+        $nodeExe = ''
+        $nodeFlags = @()
+        $npmCli = ''
+        if (Get-Command node -ErrorAction SilentlyContinue) {
+            $probe = Invoke-Tool 'node' @('-v') -Quiet
+            $parts = $null
+            if ($probe.Code -eq 0) { $parts = Get-NodeVersionParts (Get-VersionLine $probe.Lines) }
+            if ($null -eq $parts) {
+                Write-Note 'the node on PATH does not answer -v; installing a private one'
+            }
+            elseif ($parts.Major -lt 20) {
+                Write-Note "node v$($parts.Text) on PATH is older than 20; installing a private one"
+            }
+            else {
+                # The real binary: shims (Volta, Scoop, fnm, nvm) exec it, and
+                # that is where node_modules\npm lives.
+                $real = Invoke-Tool 'node' @('-p', 'process.execPath') -Quiet
+                $realPath = ''
+                if ($real.Code -eq 0) { $realPath = Get-ExistingPathLine $real.Lines }
+                if (-not $realPath -or -not (Test-Path -LiteralPath $realPath -PathType Leaf)) {
+                    Write-Note 'the node on PATH does not say where its binary is; installing a private one'
+                }
+                elseif (Test-ManagedNodePath $realPath) {
+                    Write-Note "node v$($parts.Text) at $realPath belongs to a version manager; installing a private one so the hook outlives this shell"
+                }
+                else {
+                    $candidateCli = Join-Path (Split-Path -Parent $realPath) 'node_modules\npm\bin\npm-cli.js'
+                    if (-not (Test-Path -LiteralPath $candidateCli -PathType Leaf)) {
+                        Write-Note "node v$($parts.Text) at $realPath has no npm next to it; installing a private one"
+                    }
+                    else {
+                        $nodeExe = $realPath
+                        $npmCli = $candidateCli
+                        # @(...) around the call: a one-element array unrolls to a
+                        # string on assignment, and string + array is one string.
+                        $nodeFlags = @(Get-NodeFlags $parts.Major $parts.Minor)
+                        Write-Note "node v$($parts.Text) at $realPath"
+                    }
+                }
+            }
+        }
+        else {
+            Write-Note 'no node on PATH; installing a private one'
+        }
+        if (-not $nodeExe) {
+            $nodeVersion = $pinnedNodeVersion
+            if ($env:BIR_NODE_VERSION) {
+                $nodeVersion = $env:BIR_NODE_VERSION.Trim().TrimStart('v')
+                if ($nodeVersion -notmatch '^\d+\.\d+\.\d+$') { throw "BIR_NODE_VERSION must look like 24.21.0, not '$($env:BIR_NODE_VERSION)'." }
+            }
+            Write-Step "Installing Node $nodeVersion privately"
+            $nodeExe = Install-PrivateNode $nodeVersion
+            $npmCli = Join-Path (Split-Path -Parent $nodeExe) 'node_modules\npm\bin\npm-cli.js'
+            $pinnedParts = Get-NodeVersionParts $nodeVersion
+            $nodeFlags = @(Get-NodeFlags $pinnedParts.Major $pinnedParts.Minor)
+        }
+
+        # -- 2. the runner ------------------------------------------------------
+        #
+        # One code path for every Node: always into the private prefix, never
+        # into the machine's npm prefix (per-version under nvm and Volta,
+        # shim-managed under Scoop) and always through npm-cli.js, never the npm
+        # shim (PowerShell resolves npm.ps1 first, and a Restricted policy blocks it).
+        Write-Step 'Installing the runner'
+        $npmPrefix = Join-Path $birHome 'npm'
+        $spec = "$packageName@$version"
+        if ($env:BIR_TARBALL) {
+            if (-not (Test-Path -LiteralPath $env:BIR_TARBALL -PathType Leaf)) { throw "BIR_TARBALL is not a file: $($env:BIR_TARBALL)" }
+            $spec = (Resolve-Path -LiteralPath $env:BIR_TARBALL).ProviderPath
+            Write-Note "from $spec (BIR_TARBALL)"
+        }
+        else {
+            Write-Note "$spec from the registry"
+        }
+        $npmArgs = @($nodeFlags) + @($npmCli, 'install', '-g', '--prefix', $npmPrefix, '--no-fund', '--no-audit', $spec)
+        $runnerDir = Join-Path $npmPrefix ('node_modules\' + $packageName.Replace('/', '\'))
+        $birJs = Join-Path $runnerDir 'dist\bin\bir.js'
+        $hooksJs = Join-Path $runnerDir 'dist\bin\bir-hooks.js'
+        if ($dryRun) {
+            Write-Would "run: $(Format-CommandLine $nodeExe $npmArgs)"
+        }
+        else {
+            New-Item -ItemType Directory -Path $npmPrefix -Force | Out-Null
+            $r = Invoke-Tool $nodeExe $npmArgs
+            if ($r.Code -ne 0) {
+                if (($r.Lines -join "`n") -match 'CERT|ISSUER|SELF_SIGNED') { Write-Warn $tlsHint }
+                throw "npm install failed (exit $($r.Code)); see above."
+            }
+            if (-not (Test-Path -LiteralPath $birJs -PathType Leaf)) { throw "npm reported success but $birJs is missing." }
+            $installed = (Get-Content -LiteralPath (Join-Path $runnerDir 'package.json') -Raw | ConvertFrom-Json).version
+            Write-Note "bir $installed at $runnerDir"
+            # `bir setup` arrived in 0.2.9. A registry whose `latest` is older
+            # would install cleanly and then fail on the next line with nothing
+            # to say; say it here.
+            if ([version]($installed -replace '[^0-9.].*$', '') -lt [version]'0.2.9') {
+                throw "@basein/runner $installed has no 'bir setup'. This service must serve RUNNER_VERSION >= 0.2.9 (or set BIR_TARBALL to a newer build)."
+            }
+        }
+
+        # Launchers first on the user Path: `bir` in PowerShell then resolves to
+        # bir.cmd, so no execution-policy change, ever. The private Node stays
+        # off PATH; the launchers name it.
+        Write-Step 'Putting bir on your PATH'
+        $binDir = Join-Path $birHome 'bin'
+        if (-not $dryRun) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
+        # The launchers carry the same node flags this run used, so a `bir setup`
+        # typed later - and everything it wires - trusts the same certificates.
+        Write-Launcher (Join-Path $binDir 'bir.cmd') $nodeExe $nodeFlags $birJs
+        Write-Launcher (Join-Path $binDir 'bir-hooks.cmd') $nodeExe $nodeFlags $hooksJs
+
+        # The user Path is read raw and written back as REG_EXPAND_SZ. Not
+        # [Environment]::SetEnvironmentVariable: it flattens the value to REG_SZ,
+        # and every %USERPROFILE% already in there stops expanding.
+        $pathEntry = '%USERPROFILE%\.baseinstrunner\bin'
+        $rawPath = [string](Get-Item -Path HKCU:\Environment).GetValue('Path', '', 'DoNotExpandEnvironmentNames')
+        $present = $false
+        foreach ($part in $rawPath.Split(';')) {
+            $p = $part.Trim().TrimEnd('\')
+            if ($p -ieq $pathEntry -or $p -ieq $binDir.TrimEnd('\')) { $present = $true }
+        }
+        if ($present) {
+            Write-Note "user Path already has $pathEntry"
+        }
+        else {
+            $newPath = if ($rawPath.Trim() -eq '') { $pathEntry } else { $pathEntry + ';' + $rawPath }
+            if ($dryRun) {
+                Write-Would "prepend $pathEntry to the user Path in HKCU:\Environment (REG_EXPAND_SZ); it is now: $rawPath"
+            }
+            else {
+                Set-ItemProperty -Path HKCU:\Environment -Name Path -Value $newPath -Type ExpandString
+                Send-EnvironmentChange
+                Write-Note "user Path: $pathEntry first; new terminals see it"
+            }
+        }
+        $sessionHas = $false
+        foreach ($part in $env:Path.Split(';')) {
+            if ($part.Trim().TrimEnd('\') -ieq $binDir.TrimEnd('\')) { $sessionHas = $true }
+        }
+        if (-not $sessionHas) {
+            if ($dryRun) { Write-Would "prepend $binDir to `$env:Path for this window" }
+            else { $env:Path = $binDir + ';' + $env:Path }
+        }
+
+        # -- 3. Claude Code -----------------------------------------------------
+        Write-Step 'Checking Claude Code'
+        Update-SessionPath
+        $claude = Get-ClaudePath
+        if ($claude) {
+            Write-Note "claude at $claude"
+        }
+        elseif ($env:BIR_NO_CLAUDE -eq '1') {
+            Write-Note 'not installed; skipping (BIR_NO_CLAUDE=1)'
+        }
+        else {
+            Write-Step 'Installing Claude Code (this can take a minute)'
+            # A child process, so the installer's own policy switch and any exit
+            # it calls stay in that child.
+            $powershell = Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe'
+            if (-not (Test-Path -LiteralPath $powershell)) { $powershell = 'powershell.exe' }
+            $claudeArgs = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', 'irm https://claude.ai/install.ps1 | iex')
+            if ($dryRun) {
+                Write-Would "run: $(Format-CommandLine $powershell $claudeArgs)"
+            }
+            else {
+                $r = Invoke-Tool $powershell $claudeArgs
+                Update-SessionPath
+                $claude = Get-ClaudePath
+                if ($r.Code -ne 0 -or -not $claude) {
+                    Write-Warn "Claude Code did not install (exit $($r.Code)). The runner is set up anyway; install it later with: irm https://claude.ai/install.ps1 | iex"
+                }
+                else {
+                    Write-Note "claude at $claude"
+                    Write-Note 'Claude Code needs a Claude subscription and asks you to sign in the first time it starts.'
+                }
+            }
+        }
+
+        # -- 4. setup -----------------------------------------------------------
+        Write-Step 'Running bir setup'
+        $setupArgs = @($nodeFlags) + @($birJs, 'setup', '--auth-url', $authUrl, '--project', $project)
+        if ($dryRun) {
+            Write-Would "run: $(Format-CommandLine $nodeExe $setupArgs)"
+            if ($setupToken) { Write-Would 'hand it BIR_SETUP_TOKEN through its environment (set right before, removed right after)' }
+            else { Write-Would 'run it without a token: it uses the cached sign-in or opens the browser' }
+            Write-Step 'Dry run finished; nothing was changed.'
+            return
+        }
+        # The token goes to this one child through its environment: set right
+        # before the spawn, removed right after, never on a command line.
+        if ($setupToken) { $env:BIR_SETUP_TOKEN = $setupToken }
+        try {
+            $r = Invoke-Tool $nodeExe $setupArgs
+        }
+        finally {
+            Remove-Item -Path Env:BIR_SETUP_TOKEN -ErrorAction SilentlyContinue
+        }
+        if ($r.Code -ne 0) {
+            throw "bir setup ended with exit code $($r.Code). Fix what it reported above, then paste the line again or run: bir setup"
+        }
+        # This window only when it is the PowerShell the line was pasted into: the
+        # cmd variant runs this in a child powershell.exe, whose $env:Path dies
+        # with it, so a cmd window sees `bir` only once it is a new window.
+        Write-Note 'bir works in every new terminal (and in this window when it is PowerShell); `bir doctor` checks the setup.'
+        Write-Note 'From a cmd window: open a new one, or run   set PATH=%USERPROFILE%\.baseinstrunner\bin;%USERPROFILE%\.local\bin;%PATH%'
+    }
+    catch {
+        $message = $_.Exception.Message
+        if ($message -match 'CERT|ISSUER|SELF_SIGNED|secure channel|trust relationship') { Write-Warn $tlsHint }
+        Write-Host "error: $message" -ForegroundColor Red
+        return
+    }
+}
+
+Invoke-BirInstall