Skip to content

Personal AI, On Personal Devices

Python

fix(windows installer): validate Python candidates and MSVC prerequisites (#1056)

srcreativepro-art9833a2bdcb0a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 46ce500f..d752bd33 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -135,7 +135,7 @@ jobs:
- name: Run Windows-specific tests (hardware + CLI + daemon)
shell: bash
run: |
- uv run pytest tests/hardware/test_hardware_profiles.py tests/cli/test_cli.py tests/cli/test_daemon_cmd.py tests/cli/test_daemon_state.py tests/core/test_utils.py -v -m "not live and not cloud"
+ uv run pytest tests/hardware/test_hardware_profiles.py tests/cli/test_cli.py tests/cli/test_daemon_cmd.py tests/cli/test_daemon_state.py tests/core/test_utils.py tests/install/test_windows_prerequisites.py -v -m "not live and not cloud"
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
diff --git a/deploy/windows/install.ps1 b/deploy/windows/install.ps1
index 16732715..900ed83f 100644
--- a/deploy/windows/install.ps1
+++ b/deploy/windows/install.ps1
@@ -16,6 +16,8 @@
4. Install uv (https://astral.sh/uv) if absent.
5. Clone the OpenJarvis repository to $env:LOCALAPPDATA\OpenJarvis
(override with $env:OPENJARVIS_HOME).
+ 5b. Check for MSVC build tools and explain how to install them if absent - the mandatory
+ openjarvis-rust extension is compiled from source in step 6.
6. Run `uv sync --extra desktop --group desktop-native` so the FastAPI
server, speech backend, and native extension are importable.
7. Optionally register the scheduled-task service (see
@@ -148,11 +150,28 @@ Write-Ok "Windows build $build"
# ---------------------------------------------------------------------------
function Get-PythonCommand {
- # Prefer `python3` (matches our cross-platform helper convention),
- # fall back to `python` (the Windows store / python.org default).
- foreach ($name in @('python3', 'python')) {
- $cmd = Get-Command $name -ErrorAction SilentlyContinue
- if ($cmd) { return $cmd.Source }
+ # A Store alias can point to installed Python or to the Store placeholder;
+ # its zero-byte file size does not distinguish them. Probe with an argument
+ # (which never opens the Store) and continue past failed/shadowing aliases.
+ $seen = @{}
+ foreach ($name in @('python', 'python3')) {
+ foreach ($cmd in @(Get-Command $name -All -CommandType Application -ErrorAction SilentlyContinue)) {
+ if (-not $cmd.Source -or $seen.ContainsKey($cmd.Source)) { continue }
+ $seen[$cmd.Source] = $true
+ try {
+ $version = & $cmd.Source --version 2>$null
+ $match = [regex]::Match(($version -join ' '), '^Python (\d+)\.(\d+)\.\d+')
+ if ($LASTEXITCODE -eq 0 -and $match.Success -and
+ [int]$match.Groups[1].Value -eq 3 -and
+ [int]$match.Groups[2].Value -ge 10 -and
+ [int]$match.Groups[2].Value -le 13) {
+ return $cmd.Source
+ }
+ } catch {
+ # PS 5.1 can turn a native stderr message into an exception.
+ }
+ Write-Warn2 " Ignoring unavailable or unsupported Python at $($cmd.Source)"
+ }
}
return $null
}
@@ -161,7 +180,9 @@ Write-Info "Checking Python (3.10 - 3.13)..."
$pythonExe = Get-PythonCommand
if (-not $pythonExe) {
Write-Info "Python not on PATH - attempting auto-install via winget..."
- $pythonExe = Install-WithWinget -WingetId 'Python.Python.3.13' -CommandName 'python'
+ $null = Install-WithWinget -WingetId 'Python.Python.3.13' -CommandName 'python'
+ # Refreshing PATH can still leave a failed Store alias ahead of python.org.
+ $pythonExe = Get-PythonCommand
if (-not $pythonExe) {
Write-Fail @"
Python 3.10 - 3.13 not found and auto-install via winget failed.
@@ -287,6 +308,73 @@ if (Test-Path (Join-Path $srcDir '.git')) {
Write-Ok "Cloned to $srcDir"
}
+# ---------------------------------------------------------------------------
+# 5b. MSVC build tools - required by the mandatory Rust extension
+# ---------------------------------------------------------------------------
+
+# `--group desktop-native` builds openjarvis-rust from source via maturin
+# (pyproject.toml pins it to a local path; it is not published to PyPI), and
+# src/openjarvis/_rust_bridge.py raises a hard ImportError when the module is
+# missing - there is no pure-Python fallback. maturin will bootstrap a Rust
+# toolchain into a temp dir if cargo is absent, which is why this failure is
+# so confusing: cargo appears to run fine and then every build script dies at
+# `error: linker 'link.exe' not found`. The x86_64-pc-windows-msvc target
+# needs the MSVC linker, which no earlier step installs (#1060).
+function Test-MsvcLinker {
+ # Git/MSYS can put an unrelated GNU link.exe on PATH. Only Microsoft's
+ # linker satisfies the native extension's MSVC prerequisite.
+ foreach ($cmd in @(Get-Command link.exe -All -CommandType Application -ErrorAction SilentlyContinue)) {
+ $item = Get-Item -LiteralPath $cmd.Source -ErrorAction SilentlyContinue
+ if ($item -and $item.VersionInfo.CompanyName -match '^Microsoft' -and
+ $item.VersionInfo.OriginalFilename -ieq 'link.exe') {
+ return $true
+ }
+ }
+ # link.exe is only on PATH inside a Developer Command Prompt, so probe
+ # the install root via vswhere (shipped with any VS 2017+ installer).
+ if (-not ${env:ProgramFiles(x86)}) { return $false }
+ $vswhere = Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe'
+ if (-not (Test-Path -LiteralPath $vswhere)) { return $false }
+ $found = & $vswhere -latest -products * `
+ -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
+ -find 'VC\Tools\MSVC\**\bin\Host*\*\link.exe' 2>$null
+ if ($LASTEXITCODE -ne 0) { return $false }
+ foreach ($linker in $found) {
+ if (Test-Path -LiteralPath $linker -PathType Leaf) { return $true }
+ }
+ return $false
+}
+
+Write-Info "Checking MSVC build tools (needed to compile the native extension)..."
+if (Test-MsvcLinker) {
+ Write-Ok "MSVC build tools present"
+} else {
+ # Detect and instruct only. Installing the Build Tools is a multi-GB
+ # download behind a UAC prompt, which is not something an installer
+ # should start on the user's behalf without asking.
+ Write-Fail @"
+MSVC build tools not found.
+
+The next step compiles the mandatory openjarvis-rust extension, which
+needs the MSVC linker (link.exe). Without it every cargo build script
+fails with "error: linker ``link.exe`` not found".
+
+Install via winget - expect a multi-GB download and a UAC prompt:
+
+ winget install --id Microsoft.VisualStudio.2022.BuildTools ``
+ --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+
+--override is load-bearing: the default Build Tools install ships no
+workload at all, so VCTools has to be requested explicitly.
+
+Alternatively download "Build Tools for Visual Studio" from
+https://visualstudio.microsoft.com/downloads/ and select the
+"Desktop development with C++" workload.
+
+Then re-run this installer.
+"@
+}
+
# ---------------------------------------------------------------------------
# 6. uv sync --extra desktop --group desktop-native
# ---------------------------------------------------------------------------
diff --git a/tests/install/test_windows_prerequisites.py b/tests/install/test_windows_prerequisites.py
new file mode 100644
index 00000000..d8d7836f
--- /dev/null
+++ b/tests/install/test_windows_prerequisites.py
@@ -0,0 +1,207 @@
+"""Run Windows prerequisite helpers in PowerShell without installing anything."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+_INSTALLER = Path(__file__).parents[2] / "deploy" / "windows" / "install.ps1"
+_POWERSHELL = (
+ os.environ.get("OPENJARVIS_TEST_PWSH")
+ # Prefer Windows PowerShell 5.1 where available: it is the installer's
+ # minimum supported shell. The portable pwsh runtime also runs these tests.
+ or shutil.which("powershell")
+ or shutil.which("pwsh")
+)
+pytestmark = pytest.mark.skipif(not _POWERSHELL, reason="PowerShell is not installed")
+
+_HARNESS = r"""
+param([string]$Installer, [string]$Case)
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+$tokens = $null
+$errors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseFile(
+ $Installer, [ref]$tokens, [ref]$errors)
+if ($errors.Count) { throw ($errors | Out-String) }
+$definitions = $ast.FindAll({
+ param($node)
+ $node -is [System.Management.Automation.Language.FunctionDefinitionAst] -and
+ $node.Name -in @('Get-PythonCommand', 'Test-MsvcLinker')
+}, $true)
+foreach ($definition in $definitions) { Invoke-Expression $definition.Extent.Text }
+
+$global:Probes = @()
+$global:VswhereArguments = @()
+$global:Installed = $false
+function Write-Warn2 { param($Message) }
+function Write-Info { param($Message) }
+function Write-Fail { param($Message) throw $Message }
+function Install-WithWinget {
+ param($WingetId, $CommandName)
+ $global:Installed = $true
+ 'Invoke-BadPython'
+}
+function Invoke-GoodPython {
+ $global:Probes += 'good'
+ $global:LASTEXITCODE = 0
+ 'Python 3.12.10'
+}
+function Invoke-BadPython {
+ $global:Probes += 'bad'
+ if ($Case -in @('python-too-old', 'python-too-new')) {
+ $global:LASTEXITCODE = 0
+ if ($Case -eq 'python-too-old') { 'Python 2.7.18' } else { 'Python 3.14.0' }
+ return
+ }
+ $global:LASTEXITCODE = 9009
+ 'Python was not found'
+}
+function Invoke-TestVswhere {
+ $global:VswhereArguments = @($args)
+ $global:LASTEXITCODE = 0
+ 'C:\VS\VC\Tools\MSVC\14.0\bin\Hostx64\x64\link.exe'
+}
+function Get-Command {
+ param([string]$Name, [switch]$All, $CommandType, $ErrorAction)
+ if ($Name -eq 'python') {
+ if ($Case -eq 'active-store-alias') {
+ return [pscustomobject]@{Source='Invoke-GoodPython'}
+ }
+ if ($Case -in @('shadowed-python', 'python-too-old', 'python-too-new') -or
+ ($Case -eq 'winget-shadowed-python' -and $global:Installed)) {
+ $bad = [pscustomobject]@{Source='Invoke-BadPython'}
+ $good = [pscustomobject]@{Source='Invoke-GoodPython'}
+ if ($All) { return @($bad, $good) }
+ return $bad
+ }
+ if ($Case -eq 'failed-python-alias') {
+ return [pscustomobject]@{Source='Invoke-BadPython'}
+ }
+ }
+ if ($Name -eq 'python3' -and $Case -eq 'failed-python-alias') {
+ return [pscustomobject]@{Source='Invoke-GoodPython'}
+ }
+ if ($Name -eq 'link.exe' -and $Case -in @('gnu-linker', 'msvc-on-path')) {
+ return [pscustomobject]@{Source='C:\tools\link.exe'}
+ }
+}
+function Get-Item {
+ param($LiteralPath, $ErrorAction)
+ # Installed Store Python aliases can still have a zero-byte file size.
+ $company = if ($Case -eq 'msvc-on-path') {
+ 'Microsoft Corporation'
+ } else { 'Free Software Foundation' }
+ [pscustomobject]@{
+ Length=0
+ VersionInfo=[pscustomobject]@{CompanyName=$company; OriginalFilename='LINK.EXE'}
+ }
+}
+function Join-Path { param($Path, $ChildPath) 'Invoke-TestVswhere' }
+function Test-Path {
+ param($LiteralPath, $PathType)
+ if ($LiteralPath -eq 'Invoke-TestVswhere') {
+ return $Case -in @('msvc-vswhere', 'vswhere-missing-linker')
+ }
+ return $Case -eq 'msvc-vswhere' -and $PathType -eq 'Leaf'
+}
+${env:ProgramFiles(x86)} = 'C:\Program Files (x86)'
+$pythonCases = @(
+ 'active-store-alias', 'shadowed-python', 'failed-python-alias', 'no-python',
+ 'python-too-old', 'python-too-new')
+if ($Case -eq 'winget-shadowed-python') {
+ $pythonExe = Get-PythonCommand
+ $bootstrap = $ast.EndBlock.Statements | Where-Object {
+ $_ -is [System.Management.Automation.Language.IfStatementAst] -and
+ $_.Extent.Text.Contains("Install-WithWinget -WingetId 'Python.Python.3.13'")
+ } | Select-Object -First 1
+ Invoke-Expression $bootstrap.Extent.Text
+ @{selected=$pythonExe; probes=$global:Probes} | ConvertTo-Json -Compress
+} elseif ($Case -in $pythonCases) {
+ $selected = Get-PythonCommand
+ @{selected=$selected; probes=$global:Probes} | ConvertTo-Json -Compress
+} else {
+ $present = Test-MsvcLinker
+ @{present=$present; arguments=$global:VswhereArguments} | ConvertTo-Json -Compress
+}
+"""
+
+
+def _run_case(tmp_path: Path, case: str) -> dict:
+ script = tmp_path / "prerequisites.ps1"
+ script.write_text(_HARNESS)
+ result = subprocess.run(
+ [
+ _POWERSHELL,
+ "-NoLogo",
+ "-NoProfile",
+ "-NonInteractive",
+ "-File",
+ str(script),
+ "-Installer",
+ str(_INSTALLER),
+ "-Case",
+ case,
+ ],
+ text=True,
+ capture_output=True,
+ timeout=30,
+ )
+ assert result.returncode == 0, result.stdout + result.stderr
+ return json.loads(result.stdout)
+
+
+def test_installed_store_alias_is_not_rejected_for_zero_file_size(tmp_path):
+ result = _run_case(tmp_path, "active-store-alias")
+ assert result["selected"] == "Invoke-GoodPython"
+ assert result["probes"] == ["good"]
+
+
+def test_probe_continues_past_a_shadowing_failed_python(tmp_path):
+ result = _run_case(tmp_path, "shadowed-python")
+ assert result["selected"] == "Invoke-GoodPython"
+ assert result["probes"] == ["bad", "good"]
+
+
[email protected]("case", ["python-too-old", "python-too-new"])
+def test_supported_python_is_selected_after_an_unsupported_version(tmp_path, case):
+ result = _run_case(tmp_path, case)
+ assert result["selected"] == "Invoke-GoodPython"
+ assert result["probes"] == ["bad", "good"]
+
+
+def test_probe_falls_back_to_python3_when_python_is_a_store_placeholder(tmp_path):
+ result = _run_case(tmp_path, "failed-python-alias")
+ assert result["selected"] == "Invoke-GoodPython"
+ assert result["probes"] == ["bad", "good"]
+
+
+def test_no_working_python_returns_none(tmp_path):
+ assert _run_case(tmp_path, "no-python")["selected"] is None
+
+
+def test_python_is_reprobed_after_winget_refreshes_path(tmp_path):
+ result = _run_case(tmp_path, "winget-shadowed-python")
+ assert result["selected"] == "Invoke-GoodPython"
+ assert result["probes"] == ["bad", "good"]
+
+
+def test_gnu_link_executable_is_not_accepted_as_msvc(tmp_path):
+ assert _run_case(tmp_path, "gnu-linker")["present"] is False
+
+
+def test_microsoft_linker_on_path_is_accepted(tmp_path):
+ assert _run_case(tmp_path, "msvc-on-path")["present"] is True
+
+
+def test_vswhere_must_find_an_actual_linker_file(tmp_path):
+ result = _run_case(tmp_path, "msvc-vswhere")
+ assert result["present"] is True
+ assert "-find" in result["arguments"]
+ assert "Microsoft.VisualStudio.Component.VC.Tools.x86.x64" in result["arguments"]
+ assert _run_case(tmp_path, "vswhere-missing-linker")["present"] is False