install.ps1

<#
.SYNOPSIS
Installs the OpenSysML command-line tools from a GitHub release.

.DESCRIPTION
Windows PowerShell 5.1 or PowerShell 7, on Windows:

    irm https://opensysml.org/install.ps1 | iex

With options, save it first (a piped script takes none; the environment
variables below configure it instead):

    irm https://opensysml.org/install.ps1 -OutFile install.ps1
    .\install.ps1 -Version v0.9.1 -Tools sysml

The release's bundle archive (opensysml-windows-amd64.zip; the tar.gz on Linux
and macOS under PowerShell 7) is downloaded with its SHA256SUMS.txt manifest,
every download is checked against the manifest before anything is installed,
and the installed binaries are run once to confirm they report the release they
came from. When a release carries the Authenticode-signed Windows build
(opensysml-windows-amd64-signed.zip, checked against SHA256SUMS-windows-signed.txt),
that is the one installed.

The Windows installer (opensysml-<x.y.z>-windows-amd64.msi on the release page)
remains the alternative that also bundles the Z3 solver and installs for every
user; this script installs for the current user and touches only the user PATH.

Needs: PowerShell 5.1+ (Windows) or PowerShell 7 (elsewhere, with tar).

.PARAMETER Version
Release tag (v0.9.1), `latest` (default) or `nightly`. [OPENSYSML_VERSION]

.PARAMETER Tools
Subset of sysml, sysml-lsp, sysml-grpc, sysml-jupyter-kernel, sysml-mcp (an array, or
comma-separated), or `all` for every tool the chosen release published (read
from its SHA256SUMS.txt); default sysml and sysml-lsp. [OPENSYSML_TOOLS,
comma-separated]

.PARAMETER InstallDir
Where the binaries go; default $env:LOCALAPPDATA\Programs\OpenSysML on Windows,
~/.local/bin elsewhere. [OPENSYSML_INSTALL_DIR]

.PARAMETER Os
Stage another platform's build instead of this machine's (windows, linux or
darwin); it is not run.

.PARAMETER Arch
Architecture of the build (amd64 or arm64); default this machine's.

.PARAMETER BaseUrl
Where the releases are, for a mirror; default
https://github.com/Open-MBEE/OpenSysML/releases. [OPENSYSML_DOWNLOAD_BASE]

.PARAMETER NoPath
Leave the user PATH alone (Windows only; elsewhere PATH is never edited).

.PARAMETER DryRun
Print what would be installed and from where, then exit.

.LINK
https://github.com/Open-MBEE/OpenSysML/blob/main/docs/guide/01-install.md
#>
# Progress is written to the host on purpose: it is for the person running the
# installer, not for a pipeline, and `irm | iex` has no caller to receive output.
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '')]
[CmdletBinding()]
param(
    [string]$Version = $(if ($env:OPENSYSML_VERSION) { $env:OPENSYSML_VERSION } else { 'latest' }),
    [string[]]$Tools = $(if ($env:OPENSYSML_TOOLS) { $env:OPENSYSML_TOOLS -split ',' } else { @('sysml', 'sysml-lsp') }),
    [string]$InstallDir = $env:OPENSYSML_INSTALL_DIR,
    [ValidateSet('', 'windows', 'linux', 'darwin')]
    [string]$Os = '',
    [ValidateSet('', 'amd64', 'arm64')]
    [string]$Arch = '',
    [string]$BaseUrl = $(if ($env:OPENSYSML_DOWNLOAD_BASE) { $env:OPENSYSML_DOWNLOAD_BASE } else { 'https://github.com/Open-MBEE/OpenSysML/releases' }),
    [switch]$NoPath,
    [switch]$DryRun
)

Set-StrictMode -Version 2.0
$ErrorActionPreference = 'Stop'
# Invoke-WebRequest on Windows PowerShell 5.1 is slow while it draws progress.
$ProgressPreference = 'SilentlyContinue'

$RepoUrl = 'https://github.com/Open-MBEE/OpenSysML'
$GoInstallHint = "'go install github.com/Open-MBEE/OpenSysML/cmd/sysml@latest' builds one for this machine"

# Run as a file the script exits with the message; piped into Invoke-Expression it
# throws instead, since exit there would close the caller's session.
$RunAsFile = [bool]$PSCommandPath
function Fail([string]$Message) {
    if (-not $RunAsFile) { throw "error: $Message" }
    [Console]::Error.WriteLine("error: $Message")
    exit 1
}

# --- what is being installed ------------------------------------------------

switch -Regex ($Version) {
    '^(latest|nightly)$' { break }
    '^v\d+\.\d+\.\d+' { break }
    '^\d+\.\d+\.\d+' { $Version = "v$Version"; break }
    default { Fail "-Version must be a release tag like v0.9.1, 'latest' or 'nightly', not '$Version'" }
}

# `all` is resolved against the release's manifest once that is downloaded: a
# release predating a tool does not have it, and `all` means what it published.
$Tools = @($Tools | ForEach-Object { $_ -split ',' } | ForEach-Object { $_.Trim() } | Where-Object { $_ })
$KnownTools = @('sysml', 'sysml-lsp', 'sysml-grpc', 'sysml-jupyter-kernel', 'sysml-mcp')
if ($Tools.Count -eq 0) { Fail '-Tools names nothing to install' }
$InstallAll = ($Tools.Count -eq 1) -and ($Tools[0] -eq 'all')
if (-not $InstallAll) {
    foreach ($tool in $Tools) {
        if ($tool -eq 'all') { Fail "'all' names every tool the release published and stands alone in -Tools" }
        if ($tool -notin $KnownTools) {
            Fail "unknown tool '$tool'; the released tools are sysml, sysml-lsp, sysml-grpc, sysml-jupyter-kernel and sysml-mcp"
        }
    }
}

$BaseUrl = $BaseUrl.TrimEnd('/')

# --- the platform -----------------------------------------------------------

# $IsWindows exists only from PowerShell 6; Windows PowerShell is always on Windows.
function Test-PlatformFlag([string]$Name) { [bool](Get-Variable -Name $Name -ValueOnly -ErrorAction SilentlyContinue) }
$HostIsWindows = ($PSVersionTable.PSEdition -eq 'Desktop') -or ($PSVersionTable.PSVersion.Major -lt 6) -or (Test-PlatformFlag IsWindows)
$HostOs = if ($HostIsWindows) { 'windows' } elseif (Test-PlatformFlag IsMacOS) { 'darwin' } elseif (Test-PlatformFlag IsLinux) { 'linux' } else { '' }

$HostArch = ''
try {
    $osArch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString()
} catch {
    $osArch = $env:PROCESSOR_ARCHITECTURE
}
switch -Regex ($osArch) {
    '^(X64|AMD64)$' { $HostArch = 'amd64' }
    '^(Arm64|ARM64)$' { $HostArch = 'arm64' }
}

if (-not $Os) {
    $Os = $HostOs
    if (-not $Os) { Fail "unsupported operating system: releases are built for Windows, Linux and macOS; see $RepoUrl#install for building from source" }
}
if (-not $Arch) {
    $Arch = $HostArch
    if (-not $Arch) { Fail "unsupported architecture '$osArch': releases are built for amd64 and arm64; $GoInstallHint" }
}
if ($Os -eq 'windows' -and $Arch -ne 'amd64') {
    Fail "no windows/$Arch build is published; $GoInstallHint"
}
$Platform = "$Os-$Arch"
$IsHostPlatform = ($Os -eq $HostOs) -and ($Arch -eq $HostArch)
$Exe = if ($Os -eq 'windows') { '.exe' } else { '' }

# --- where it goes ----------------------------------------------------------

if (-not $InstallDir) {
    if ($HostIsWindows) {
        $InstallDir = Join-Path $env:LOCALAPPDATA 'Programs\OpenSysML'
    } else {
        $InstallDir = Join-Path $HOME '.local/bin'
    }
}

# --- which release ----------------------------------------------------------

if ($BaseUrl -like 'https://*' -or $BaseUrl -like 'http://*') {
    try {
        [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
    } catch {
        $null = $_  # the runtime already speaks TLS 1.2 or later
    }
}

function Resolve-Latest {
    # The redirect GitHub serves for /releases/latest names the tag before anything
    # is downloaded; a mirror without it still works through latest/download/.
    try {
        $request = [System.Net.WebRequest]::Create("$BaseUrl/latest")
        $request.Method = 'HEAD'
        $request.AllowAutoRedirect = $false
        $response = $request.GetResponse()
        try {
            $location = $response.Headers['Location']
        } finally {
            $response.Close()
        }
        if ($location -match '/tag/([^/]+)$') { return $Matches[1] }
    } catch {
        $null = $_  # no redirect to read
    }
    return $null
}

$Tag = $Version
if ($Version -eq 'latest') {
    $Tag = Resolve-Latest
    $AssetDir = if ($Tag) { "$BaseUrl/download/$Tag" } else { "$BaseUrl/latest/download" }
} else {
    $AssetDir = "$BaseUrl/download/$Version"
}
function Get-AssetUrl([string]$Asset) { "$AssetDir/$Asset" }

$ReleaseName = if ($Version -eq 'nightly') { 'the nightly snapshot' } elseif ($Tag) { $Tag } else { 'the latest release' }

# --- download and verify ----------------------------------------------------

$Work = Join-Path ([System.IO.Path]::GetTempPath()) ("opensysml-install-" + [System.IO.Path]::GetRandomFileName())

function Get-Asset([string]$Asset, [switch]$Optional) {
    # Downloads into the work directory; $true when it landed, $false when the
    # release has no such asset and -Optional allowed that.
    $url = Get-AssetUrl $Asset
    $destination = Join-Path $Work $Asset
    try {
        Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $destination
        return $true
    } catch {
        if (Test-Path -LiteralPath $destination) { Remove-Item -LiteralPath $destination -Force }
        if ($Optional) { return $false }
        Fail "could not download $url ($($_.Exception.Message)); is $ReleaseName a published release with a $Platform build? Bundles and SHA256SUMS.txt exist from v0.0.4. See $BaseUrl"
    }
}

function Get-ManifestDigest([string]$Asset, [string]$Manifest) {
    # The asset's distinct digests in the manifest, none when it is not listed;
    # a line repeated verbatim counts once.
    $digests = @()
    foreach ($line in Get-Content -LiteralPath (Join-Path $Work $Manifest)) {
        $fields = $line.Trim() -split '\s+', 2
        if ($fields.Count -eq 2 -and $fields[1].TrimStart('*') -eq $Asset) { $digests += $fields[0].ToLowerInvariant() }
    }
    return @($digests | Select-Object -Unique)
}

function Test-Checksum([string]$Asset, [string]$Manifest) {
    $expected = @(Get-ManifestDigest $Asset $Manifest)
    if ($expected.Count -eq 0) { Fail "$Manifest of $ReleaseName does not list $Asset; releases before v0.0.4 have no bundle, sysml-grpc is published from v0.9.0 and sysml-jupyter-kernel from v0.10.0, and sysml-mcp has its own archive only from the release that introduced it" }
    if ($expected.Count -gt 1) { Fail "$Manifest of $ReleaseName lists $Asset with more than one digest ($($expected -join ' ')); the manifest is corrupt or tampered with" }
    $expected = $expected[0]
    $actual = (Get-FileHash -LiteralPath (Join-Path $Work $Asset) -Algorithm SHA256).Hash.ToLowerInvariant()
    if ($actual -ne $expected) { Fail "$Asset does not match $Manifest (expected $expected, got $actual); the download is corrupt or tampered with" }
    Write-Host "  $Asset verified"
}

function Test-Authenticode([string]$Path, [string]$Name) {
    # The manifest only says which bytes to expect; what vouches for a signed
    # build is its Authenticode signature: valid, from the certificate SignPath
    # Foundation issues the project, over a VERSIONINFO naming this release
    # (README.md, "Code signing policy").
    $signature = Get-AuthenticodeSignature -LiteralPath $Path
    if ($signature.Status -ne 'Valid') {
        Fail "the Authenticode signature of $Name is $($signature.Status) ($($signature.StatusMessage)); not installing an unverified build of $ReleaseName"
    }
    $signer = $signature.SignerCertificate
    # SignPath Foundation certificates name the Foundation and the project.
    if ($signer.Subject -notlike '*SignPath Foundation*' -or $signer.Subject -notlike '*OpenSysML*') {
        Fail "$Name is signed by '$($signer.Subject)', not with the SignPath Foundation certificate issued to OpenSysML; not installing it"
    }
    $info = (Get-Item -LiteralPath $Path).VersionInfo
    if ($info.ProductName -ne 'OpenSysML' -or ($Tag -and "$($info.ProductVersion) $($info.FileVersion)" -notlike "*$Tag*")) {
        Fail "$Name is signed as '$($info.ProductName)' $($info.ProductVersion), not OpenSysML $Tag; not installing it"
    }
    Write-Host "  $Name signed by $($signer.Subject)"
}

# The Authenticode-signed Windows build is published beside the unsigned one
# with its own manifest; a release without it (and every nightly) has only the
# unsigned build. It is chosen only where its signatures can be checked, that
# is on Windows, and settled here, by fetching its small manifest (which the
# installation needs anyway), so a dry run previews the same choice.
New-Item -ItemType Directory -Path $Work -Force | Out-Null
try {
    # The release's own manifest lists everything it published; the signed
    # Windows build's manifest covers only the signed subset.
    $ReleaseManifest = 'SHA256SUMS.txt'
    $ReleaseBundle = if ($Os -eq 'windows') { "opensysml-$Platform.zip" } else { "opensysml-$Platform.tar.gz" }
    $ReleaseGrpcAsset = "sysml-grpc-$Platform$Exe"
    # sysml-mcp ships in its own archive, apart from the bundle.
    $ReleaseMcpAsset = if ($Os -eq 'windows') { "sysml-mcp-$Platform.zip" } else { "sysml-mcp-$Platform.tar.gz" }
    $Manifest = $ReleaseManifest
    $Bundle = $ReleaseBundle
    $GrpcAsset = $ReleaseGrpcAsset
    $McpAsset = $ReleaseMcpAsset
    # The signed Windows build has no kernel; it is always the release's own
    # asset, listed in SHA256SUMS.txt.
    $KernelAsset = "sysml-jupyter-kernel-$Platform$Exe"
    $CanVerifyAuthenticode = $HostIsWindows -and [bool](Get-Command Get-AuthenticodeSignature -ErrorAction SilentlyContinue)
    $SignedBuild = $false
    $SignedBuildNote = ''
    if ($Os -eq 'windows' -and $Version -ne 'nightly') {
        if ($CanVerifyAuthenticode) {
            $SignedBuild = Get-Asset 'SHA256SUMS-windows-signed.txt' -Optional
        } else {
            $SignedBuildNote = "  the signed Windows build is not chosen from $HostOs, where its Authenticode signatures cannot be checked"
        }
    }
    if ($SignedBuild) {
        $Manifest = 'SHA256SUMS-windows-signed.txt'
        $Bundle = "opensysml-$Platform-signed.zip"
        $GrpcAsset = "sysml-grpc-$Platform-signed$Exe"
        $McpAsset = "sysml-mcp-$Platform-signed.zip"
    }

    Write-Host "Installing OpenSysML ($ReleaseName) for $Platform"
    if ($InstallAll) {
        # The summary depends on what the manifest lists, so it is fetched first.
        if (-not (Test-Path -LiteralPath (Join-Path $Work $ReleaseManifest))) { Get-Asset $ReleaseManifest | Out-Null }
        $Tools = @()
        $missing = @()
        foreach ($tool in $KnownTools) {
            $asset = switch ($tool) {
                'sysml-grpc' { $ReleaseGrpcAsset }
                'sysml-jupyter-kernel' { $KernelAsset }
                'sysml-mcp' { $ReleaseMcpAsset }
                default { $ReleaseBundle }
            }
            if (Get-ManifestDigest $asset $ReleaseManifest) { $Tools += $tool } else { $missing += $tool }
        }
        if ($Tools.Count -eq 0) { Fail "$ReleaseManifest of $ReleaseName lists no $Platform build; releases before v0.0.4 have no bundle" }
        if ($missing.Count -gt 0) { Write-Host "  -Tools all: $ReleaseName publishes no $($missing -join ' or ') for $Platform" }
    }
    # The bundle is fetched only for the tools it carries; a tool published on
    # its own (sysml-grpc, sysml-jupyter-kernel) alone does not pull it in.
    $WantBundle = ($Tools -contains 'sysml') -or ($Tools -contains 'sysml-lsp')
    $WantGrpc = $Tools -contains 'sysml-grpc'
    $WantKernel = $Tools -contains 'sysml-jupyter-kernel'
    $WantMcp = $Tools -contains 'sysml-mcp'
    Write-Host "  tools:    $($Tools -join ' ')"
    Write-Host "  binaries: $InstallDir"
    $fromAssets = @()
    if ($WantBundle) { $fromAssets += $Bundle }
    if ($WantGrpc) { $fromAssets += $GrpcAsset }
    if ($WantKernel) { $fromAssets += $KernelAsset }
    if ($WantMcp) { $fromAssets += $McpAsset }
    $fromLabel = '  from:     '
    foreach ($asset in $fromAssets) {
        Write-Host "$fromLabel$(Get-AssetUrl $asset)"
        $fromLabel = '            '
    }
    if ($SignedBuild) {
        $signedAssets = @()
        if ($WantBundle) { $signedAssets += $Bundle }
        if ($WantGrpc) { $signedAssets += $GrpcAsset }
        if ($WantMcp) { $signedAssets += $McpAsset }
        $use = if ($signedAssets.Count -gt 0) { "installing $($signedAssets -join ' and ')" } else { 'none of the requested tools is among its assets' }
        Write-Host "  the release carries the signed Windows build (its $Manifest was fetched to tell); $use"
    }
    if ($SignedBuild -and $WantKernel) { Write-Host "  sysml-jupyter-kernel is not among the signed assets; $KernelAsset is checked against $ReleaseManifest" }
    if ($SignedBuildNote) { Write-Host $SignedBuildNote }
    if ($DryRun) {
        Write-Host 'Dry run: nothing installed.'
        return
    }

    Write-Host 'Downloading...'
    if (-not (Test-Path -LiteralPath (Join-Path $Work $Manifest))) { Get-Asset $Manifest | Out-Null }
    if ($WantBundle) {
        Get-Asset $Bundle | Out-Null
        Test-Checksum $Bundle $Manifest
    }
    if ($WantGrpc) {
        Get-Asset $GrpcAsset | Out-Null
        Test-Checksum $GrpcAsset $Manifest
    }
    if ($WantKernel) {
        if (-not (Test-Path -LiteralPath (Join-Path $Work $ReleaseManifest))) { Get-Asset $ReleaseManifest | Out-Null }
        Get-Asset $KernelAsset | Out-Null
        Test-Checksum $KernelAsset $ReleaseManifest
    }
    if ($WantMcp) {
        Get-Asset $McpAsset | Out-Null
        Test-Checksum $McpAsset $Manifest
    }

    # --- install ------------------------------------------------------------

    function Expand-Release([string]$Archive, [string]$Destination) {
        New-Item -ItemType Directory -Path $Destination -Force | Out-Null
        if ($Archive -like '*.zip') {
            Expand-Archive -LiteralPath (Join-Path $Work $Archive) -DestinationPath $Destination -Force
        } else {
            if (-not (Get-Command tar -ErrorAction SilentlyContinue)) { Fail "tar is needed to extract $Archive" }
            & tar -xzf (Join-Path $Work $Archive) -C $Destination
            if ($LASTEXITCODE -ne 0) { Fail "tar could not extract $Archive" }
        }
    }
    $Extracted = Join-Path $Work 'bundle'
    if ($WantBundle) { Expand-Release $Bundle $Extracted }
    $McpExtracted = Join-Path $Work 'mcp'
    if ($WantMcp) { Expand-Release $McpAsset $McpExtracted }

    try {
        New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
    } catch {
        Fail "cannot create $InstallDir ($($_.Exception.Message)); pass -InstallDir for a writable location"
    }

    # Every tool is checked before any installed one is replaced, so a failure
    # never leaves a mix of old and new tools behind.
    $Sources = @{}
    foreach ($tool in $Tools) {
        $carrier = $Bundle
        $source = switch ($tool) {
            'sysml-grpc' { $carrier = $GrpcAsset; Join-Path $Work $GrpcAsset }
            'sysml-jupyter-kernel' { $carrier = $KernelAsset; Join-Path $Work $KernelAsset }
            'sysml-mcp' { $carrier = $McpAsset; Join-Path $McpExtracted "$tool$Exe" }
            default { Join-Path $Extracted "$tool$Exe" }
        }
        if (-not (Test-Path -LiteralPath $source -PathType Leaf)) { Fail "$carrier has no $tool$Exe" }
        if ($SignedBuild -and $tool -ne 'sysml-jupyter-kernel') { Test-Authenticode $source "$tool$Exe" }
        $Sources[$tool] = $source
    }

    $Installed = @()
    foreach ($tool in $Tools) {
        $source = $Sources[$tool]
        $destination = Join-Path $InstallDir "$tool$Exe"
        # Copy beside the destination first, so an interrupted copy never leaves a
        # half-written binary under the final name.
        $staged = "$destination.tmp.$PID"
        Copy-Item -LiteralPath $source -Destination $staged -Force
        if (-not $HostIsWindows) {
            & chmod 0755 $staged
            if ($LASTEXITCODE -ne 0) { Fail "chmod could not mark $staged executable" }
        }
        Move-Item -LiteralPath $staged -Destination $destination -Force
        $Installed += $destination
    }
} finally {
    Remove-Item -LiteralPath $Work -Recurse -Force -ErrorAction SilentlyContinue
}

# --- check ------------------------------------------------------------------

if ($IsHostPlatform) {
    foreach ($tool in $Tools) {
        $binary = Join-Path $InstallDir "$tool$Exe"
        # Windows PowerShell turns a native command's stderr into a terminating
        # error under 'Stop', so the preference is relaxed for the run itself.
        $previous = $ErrorActionPreference
        $ErrorActionPreference = 'Continue'
        try {
            # Every line is read before the first is kept: a pipeline Select-Object
            # stops early kills the binary before its exit status is recorded.
            $lines = @(& $binary --version 2>&1 | ForEach-Object { "$_" })
            $exit = $LASTEXITCODE
            $reported = ($lines | Select-Object -First 1) -join ''
        } finally {
            $ErrorActionPreference = $previous
        }
        if ($exit -ne 0) { Fail "$binary does not run: $reported" }
        if ($Tag -and $Version -ne 'nightly' -and " $reported " -notlike "* $Tag *") {
            Fail "$binary reports '$reported', not $Tag"
        }
        Write-Host "  $reported"
    }
} else {
    Write-Host "  staged for $Platform, not run on this $HostOs-$HostArch machine"
}

Write-Host "Installed: $($Installed -join ' ')"

# --- PATH -------------------------------------------------------------------

$Separator = [System.IO.Path]::PathSeparator
$OnPath = @(($env:PATH -split [regex]::Escape($Separator)) | ForEach-Object { $_.TrimEnd('\', '/') }) -contains $InstallDir.TrimEnd('\', '/')
if ($HostIsWindows -and -not $NoPath) {
    $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
    $userEntries = @(if ($userPath) { $userPath -split ';' } else { @() }) | ForEach-Object { $_.TrimEnd('\') }
    if ($userEntries -notcontains $InstallDir.TrimEnd('\')) {
        $newPath = if ($userPath) { "$userPath;$InstallDir" } else { $InstallDir }
        [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
        Write-Host "Added $InstallDir to the user PATH; new terminals will see it."
    }
    if (-not $OnPath) { $env:PATH = "$InstallDir$Separator$env:PATH" }
} elseif (-not $OnPath) {
    Write-Warning "$InstallDir is not on PATH; add it to your profile."
}
foreach ($tool in $Tools) {
    $found = Get-Command "$tool$Exe" -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
    if ($found -and $found.Source -ne (Join-Path $InstallDir "$tool$Exe")) {
        Write-Warning "'$tool' on PATH is $($found.Source), which comes before $(Join-Path $InstallDir "$tool$Exe")"
    }
}