MILAB-6205: add freesasa with opt-in MSVC activation for Windows

[xnacly]

Second try at MILAB-6205 (first attempt was #86, reverted in #87 because the windows-x64 wheel build failed).

What broke

freesasa publishes no cp312 wheels for any platform, so #86 added a buildWheel entry to compile from the sdist on the native runner. Four platforms compiled fine; windows-x64 failed with:

error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

The windows-latest runner has VS 2022 Build Tools installed, but the env vars vcvarsall.bat normally sets (INCLUDE / LIB / LIBPATH / PATH) aren't present in the prebuild job's shell, so setuptools' distutils-based MSVC compiler shim can't find cl.exe.

Why not the kalign-python approach

kalign-python uses scikit-build-core + cmake + clang-cl, which sidesteps distutils entirely. That works because kalign's source ships a CMakeLists.txt that cmake can drive. freesasa's source is plain setup.py / setuptools / distutils with a pre-generated SWIG C wrapper. Replicating the kalign approach would require forking freesasa or wrapping it in a cmake harness, which is much more work than activating vcvars for the one package that needs it.

What this PR does

Opt-in MSVC activation via a new needsMsvc: true flag on a buildWheel entry. When set on Windows, the builder runs vcvarsall.bat once (memoized per-arch) and merges the resulting env delta into the pip wheel subprocess.

Builder code

• builder/src/msvc.ts (new): resolveMsvcEnv(arch) probes vswhere.exe for VS 2022 with the C++ toolset, runs vcvarsall.bat <arch> in a cmd subshell with && set, parses, returns the env delta vs current process env. No-op on non-Windows.
• builder/src/util.ts: runCommand grows an extraEnv opt that merges on top of the inherited process env. Other call sites unchanged.
• builder/src/build.ts: in the buildWheel branch, resolves msvcEnv when osType === 'windows' && buildWheel.needsMsvc; otherwise the env stays empty. Passed to both the pip install of build-requires and the pip wheel call.

Config

• python-3.12.10/config.json: re-adds freesasa==2.2.1 to deps. buildWheel entries for all five platforms; windows-x64 carries needsMsvc: true.

Blast radius

• kalign-python is the only other Windows buildWheel entry in the repo. It does NOT set needsMsvc and keeps using scikit-build-core + clang-cl + cmake. cmake handles its own toolchain discovery, and the MSVC env vars are never set for its build.
• Prebuilt wheels and pure-Python installs don't go through the buildWheel branch at all, so they're untouched.
• Other Windows buildWheels added later opt in to MSVC explicitly by setting needsMsvc: true.

Verification

• TypeScript compiles clean (tsc --noEmit --esModuleInterop against the changed files).
• JSON is valid.
• The local build path is unchanged on Linux / macOS for every existing package.
• Real verification is the Windows CI run on this PR — that's the one we need to watch.

Ref: previous attempt #86, revert #87.

Greptile Summary

This PR re-introduces freesasa==2.2.1 to the Python 3.12.10 runenv by adding an opt-in MSVC activation path (needsMsvc: true) that runs vcvarsall.bat before pip wheel on Windows, fixing the cl.exe-not-found failure from the first attempt (#86).

• builder/src/msvc.ts (new): probes vswhere.exe, captures the post-vcvarsall.bat environment delta, memoizes it per-arch, and returns {} on non-Windows — other build paths are completely unaffected.
• builder/src/util.ts: extends runCommand with an extraEnv option that layers additional vars on top of the inherited process env without touching any existing call sites.
• python-3.12.10/config.json: adds freesasa==2.2.1 with buildWheel entries for all five platforms; only windows-x64 carries needsMsvc: true.

Confidence Score: 4/5

Safe to merge for Linux/macOS builds; Windows wheel build for freesasa hinges on the cmd.exe quoting in captureVcvarsEnv working correctly on the runner, which should hold for the standard VS install path.

The builder changes are well-scoped: the opt-in flag means no existing package is affected, and the extraEnv merge in util.ts is clean. The only real concern is in the new msvc.ts file — JSON.stringify is used to quote a cmd.exe command, which is non-standard (cmd.exe uses "" not " for quote escaping) and also suppresses vcvarsall stderr, making failures opaque. These work in the expected runner environment but are fragile if paths or runner images change.

builder/src/msvc.ts — specifically the captureVcvarsEnv function's command construction and stderr suppression.

Important Files Changed

Filename	Overview
builder/src/msvc.ts	New module: probes vswhere, captures vcvarsall env delta, memoizes per-arch. Two issues: stderr suppressed via >NUL 2>&1 (loses vcvarsall error messages), and JSON.stringify used for cmd.exe quoting (non-standard, accidental correctness for standard VS paths).
builder/src/build.ts	Adds opt-in MSVC env resolution for the buildWheel branch; correctly gates on osType === 'windows' && needsMsvc, passes msvcEnv to both the build-requires install and pip wheel invocations.
builder/src/util.ts	Adds extraEnv option to runCommand; merges on top of defaultExecOpts.env cleanly. All existing call sites are unaffected.
python-3.12.10/config.json	Adds freesasa==2.2.1 with buildWheel entries for all 5 platforms; windows-x64 correctly sets needsMsvc: true. Missing trailing newline.
.changeset/milab-6205-freesasa-windows-msvc.md	Changeset file marking patch bumps for the runenv and builder packages; accurate description of the change.

Sequence Diagram

sequenceDiagram
    participant B as build.ts (buildWheel branch)
    participant M as msvc.ts
    participant VS as vswhere.exe
    participant VC as vcvarsall.bat
    participant U as util.ts (runCommand)
    participant PIP as pip

    B->>B: "osType === 'windows' && needsMsvc?"
    alt "needsMsvc = true (windows-x64 / freesasa)"
        B->>M: resolveMsvcEnv(arch)
        M->>M: cache.get(arch)?
        alt not cached
            M->>VS: execFileSync(vswhere, [...])
            VS-->>M: VS installationPath
            M->>VC: "execSync(vcvarsall.bat amd64 >NUL 2>&1 && set)"
            VC-->>M: env dump (stdout)
            M->>M: compute delta vs process.env
            M->>M: cache.set(arch, delta)
        end
        M-->>B: msvcEnv (delta)
    else "needsMsvc = false / non-Windows"
        B->>B: "msvcEnv = {}"
    end
    B->>U: runCommand(pip install buildRequires, extraEnv: msvcEnv)
    U->>PIP: spawn with merged env
    B->>U: runCommand(pip wheel ..., extraEnv: msvcEnv)
    U->>PIP: spawn with merged env
    PIP-->>B: .whl artifact

Loading

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
builder/src/msvc.ts:75-76
**vcvarsall stderr silently discarded on failure**

`>NUL 2>&1` redirects both stdout _and_ stderr of `vcvarsall.bat` to NUL, so if vcvarsall fails (wrong arch string, incomplete VS install, runner image change, etc.) the only signal is the non-zero exit code that `execSync` throws. The actual error message — printed by vcvarsall to stderr — is gone. Changing to `>NUL` (stdout only) lets stderr pass through to the console so CI logs contain the real reason instead of a bare "exit code 1".

### Issue 2 of 3
builder/src/msvc.ts:75-76
**`JSON.stringify` is not a safe cmd.exe quoting mechanism**

`JSON.stringify` escapes internal `"` as `\"` and `\` as `\\`. cmd.exe does not recognise `\"` as an escaped quote — it's not a cmd.exe escape sequence — and it would see the doubled backslashes (e.g. `C:\\Program Files\\`) literally. In practice the standard VS install path survives this, but it is accidental: any path with characters that JSON and cmd.exe escape differently would break silently. Using `cp.execFileSync('cmd.exe', ['/c', vcvarsall, arch, '&&', 'set'])` (or building the arg list without the shell-level re-quoting) is the conventional approach for Windows subprocess invocation.

```suggestion
  const cmd = `"${vcvarsall}" ${arch} >NUL && set`;
  const out = cp.execSync(`cmd /c ${cmd}`, {
```

### Issue 3 of 3
python-3.12.10/config.json:70
**Missing newline at end of file**

The diff shows `\ No newline at end of file`. Adding a trailing newline avoids noisy diffs in future edits and keeps the file consistent with JSON style in the repo.

_{Reviews (1): Last reviewed commit: "review: dynamic vswhere path, direct exe..." | Re-trigger Greptile}

Greptile also left 3 inline comments on this PR.

[gemini-code-assist]

Code Review

This pull request adds support for building freesasa 2.2.1 from source across platforms, introducing MSVC environment activation on Windows via vcvarsall.bat when needsMsvc is enabled. The review feedback highlights critical issues on Windows: JSON.stringify breaks path quoting when executing vcvarsall.bat, merging environment variables can lead to case-insensitive duplicates (like Path and PATH), and hardcoding the C:\ drive for vswhere.exe may fail on systems with different drive configurations. Addressing these issues will ensure robust and reliable builds on Windows.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.