fix(powershell): probe python3 before selecting it in Get-Python3Command

[jawwad-ali]

Problem

Get-Python3Command's first branch returns @('python3') on mere Get-Command presence, with no execution probe — while its own second and third branches do probe:

if (Get-Command python3 -ErrorAction SilentlyContinue) { return @('python3') }   # <-- no probe
if (Get-Command python  -ErrorAction SilentlyContinue) {
    $ver = & python --version 2>&1
    if ($ver -match 'Python 3') { return @('python') }
}

Its own docstring promises "a usable Python 3 executable".

On Windows, python3 almost always resolves to the Microsoft Store App Execution Alias stub, which Get-Command finds but which fails at runtime:

found=True
source=C:\Users\...\AppData\Local\Microsoft\WindowsApps\python3.exe
ver=[Python was not found; run without arguments to install from the Microsoft Store, ...]
LASTEXITCODE=9009
match=False

Note the existing probe already rejects it correctly — the first branch just never runs one.

Precedent in this repo

scripts/bash/common.sh documents this exact hazard by name and defends against it:

"on Windows python3 commonly resolves to the Microsoft Store App Execution Alias stub, which passes command -v but fails at runtime (exit 49), so an availability-gated elif would pick python3, swallow its failure, and never reach the fallback — leaving feature.json unreadable even though it is valid (issue #3304)."

Its _python3_command probes all three candidates. The PowerShell twin probes only the last two.

Second half of the same root cause

The existing probes use & python --version 2>&1. In Windows PowerShell, redirecting a native command's stderr into the success stream wraps each line in an ErrorRecord — so under the $ErrorActionPreference = 'Stop' that every caller sets, the probe raises a terminating NativeCommandError rather than simply failing the match. Reaching branch 2 therefore crashes outright when python is also a Store alias (the Windows 11 default). One function, one fix.

Reproduction — shimmed interpreters on PATH, against upstream/main

python3 = dead stub, python = working  ->  RESULT=[python3]          <-- picks the dead stub
python  = dead stub, nothing else      ->  THREW: RemoteException    <-- probe crashes

Callers (Resolve-TemplateContent → setup-plan.ps1, create-new-feature.ps1) then invoke the dead stub, whose stderr becomes a terminating error under 'Stop', aborting the script instead of falling through to a working interpreter.

With the fix:

python3 = dead stub, python = working  ->  RESULT=[python]
python  = dead stub, nothing else      ->  RESULT=[]        (clean $null, no throw)
python3 + python dead, py -3 working   ->  RESULT=[py -3]

Fix

Extract the probe into Test-Python3Command and apply it to all three branches. The probe saves and restores $ErrorActionPreference around the invocation so a candidate writing to stderr fails the match instead of throwing.

Match semantics are unchanged — still -match 'Python 3', exactly as branches 2 and 3 already did.

Verification

• Fail-before / pass-after: 3 new-vs-baseline failures with common.ps1 reverted to upstream/main → 3 passed with the fix.
• Tests are self-contained: they shim a fake Store stub (stderr + exit 9009) and a working interpreter onto PATH, so they do not depend on the runner actually having a Store alias. Gated on HAS_POWERSHELL.
• Broader PowerShell surface (9 script/parity test modules): 80 passed, 96 skipped, plus one failure — test_setup_tasks_ps_core_template_resolved — which is pre-existing on clean main, fails identically with and without this change, and has an unrelated cause (JSONDecodeError: Invalid control character in emitted stdout). I am not claiming to fix it.
• common.ps1 remains ASCII-only (verified byte-wise: 0 non-ASCII bytes), per this repo's .ps1 encoding rule and tests/test_ps1_encoding.py, which passes.
• uvx ruff@0.15.0 check src tests → clean

No breaking change. A genuinely working python3 still passes the probe and is still selected first; only candidates that cannot actually run are now skipped — which is what the function already promised.

---

Written with assistance from Claude Code. Bug found, reproduced, and verified by me on current main.

[Copilot]

🟡 Changes recommended

The probe ignores nonzero exits, and the new .cmd-based tests fail on POSIX systems with PowerShell.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds runtime validation when selecting Python 3 for PowerShell scripts.

Changes:

• Centralizes interpreter probing across python3, python, and py -3.
• Adds Store-alias fallback tests.

File summaries

File	Description
scripts/powershell/common.ps1	Adds and applies the Python probe.
tests/test_resolve_template_python_parity.py	Tests unusable interpreter fallbacks.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Nice work, and thanks for disclosing the AI assistance. Copilot's review flagged two things worth addressing before I merge: the probe should check the exit code (not just the Python 3 string match, to match the bash contract), and the .cmd-shim tests need to skip on non-Windows even when pwsh is present. Re-request review once those are in.

[mnriem]

Thanks for your contributions here, @jawwad-ali — a quick note on review prioritization. You currently have 6 open pull requests, above the three-open-PR guideline in CONTRIBUTING. This isn't a freeze — your open PRs stay in the queue and can still be reviewed and merged. But beyond three, additional submissions may be placed behind other contributors' work, so the most effective path is to consolidate where you can, or tell us the few you'd most like prioritized, and I'll focus on those first. I'm adding the author-over-cap label here purely as a tracking marker; no action needed beyond letting us know your priority order.

(Drafted with AI assistance — GitHub Copilot.)

[mnriem]

Thanks @jawwad-ali— the probe now captures $LASTEXITCODE immediately and requires success, which addresses that part of the review.

The POSIX shim change still has a problem: the driver replaces PATH with the shim directory, while every POSIX shim uses #!/usr/bin/env sh. There is no sh in that directory, so even the working fake interpreter fails to launch. The equivalent launch exits 127 with env: sh: No such file or directory.

Please make the POSIX shims runnable under that restricted PATH—for example, use an absolute shell interpreter—while keeping real Python installations excluded from the test. Then verify the success and fallback cases on POSIX PowerShell and request re-review.

Drafted for @mnriem by GitHub Copilot (model: GPT-6 Astra).

[Copilot]

🟢 Approval recommended

The implementation addresses the reported failure modes with focused cross-platform regression coverage.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[mnriem]

Please fix test & lint errors

[jawwad-ali]

@mnriem — fixed, and rebased onto current main as a single commit (5554b20).

The test failure was real, and it was mine. The three get_python3 selection tests failed on pytest (macos-latest, 3.13):

test_get_python3_command_skips_unusable_python3   assert '' == 'python'

Root cause: the test driver replaces PATH with the shim directory alone, and the POSIX shims used #!/usr/bin/env sh — so env couldn't find sh and every shim exited 127, leaving nothing selectable. On Windows the .cmd shims are used, which is why it passed locally. Reproduced the mechanism directly:

PATH=<shim dir only>  #!/usr/bin/env sh  -> /usr/bin/env: 'sh': No such file or directory  (exit 127)
PATH=<shim dir only>  #!/bin/sh          -> Python 3.12.0                                   (exit 0)

Shims now use an absolute #!/bin/sh. I executed every shim body under that same restricted PATH to confirm each behaves as designed (dead stub fails, working interpreter prints a version and exits 0, py only succeeds with -3, the lying wrapper prints a version but exits 1).

Rebase: main added a SPECKIT_PYTHON_EXECUTABLE / SPECKIT_PYTHON override block above these branches (#4445). I left it untouched and only replaced the three unprobed fallbacks. Because that override is consulted first and clean_env() strips only SPECIFY_*, the test driver now also pops both override variables — otherwise a runner with either set would bypass the shims and test the override instead. Verified the tests stay green with SPECKIT_PYTHON_EXECUTABLE set in the environment.

Gates on the rebased branch: 4 selection tests fail with common.ps1 at upstream/main → 4 pass with the fix; parity + PowerShell suites 46 passed; ruff check src tests clean (the earlier lint errors were conflict markers from the stale base).

[Copilot]

Copilot review overview

🟡 Changes recommended

The generated test driver uses ASCII encoding, causing the new tests to fail when embedded paths contain non-ASCII characters.

Review effort: Balanced
Findings: 1

Open (1)

• Write generated PowerShell driver as UTF-8 with BOM · New