fix(install): write apm.cmd shim as ASCII (cmd.exe cannot parse UTF-16LE)

[danielmeppiel]

TL;DR

PR #1512 switched the Windows apm.cmd shim encoding to UTF-16LE with BOM on the assumption that cmd.exe auto-detects UTF-16 via the BOM. The Windows CI Test install.ps1 end-to-end job in run 26541947119 proves that wrong: invoking apm.cmd via PATH surfaces as garbled output (D:\a\apm\apm>��@) and exit code 1. Revert to ASCII; the %LOCALAPPDATA% literal token from #1509 keeps the embedded target ASCII-only, so the original non-ASCII profile-path bug stays fixed.

Problem (WHY)

Three failures on windows-latest in the post-merge CI for PR #1512:

[FAIL] Shim points into per-user releases dir (...Temp\apm-install-test-...\releases), not temp
[FAIL] apm.cmd --version exits 0 (got 1; output: D:\a\apm\apm>��@
[FAIL] apm.cmd --version reports v0.14.0

Two root causes:

1. UTF-16LE BOM is not auto-detected by cmd.exe on PATH invocation. cmd.exe parses .cmd files through the system OEM/ANSI code page. The BOM bytes (FF FE) and LE-encoded @echo off get interpreted as ANSI and surface as >��@ garbage. cmd reports the prompt and exits 1.
2. The E2E PowerShell test compared the shim text against the expanded release-dir path. On GitHub Windows runners, the test's temp prefix lives under %LOCALAPPDATA%\Temp\, so the install.ps1 if-branch fires and writes %LOCALAPPDATA%\Temp\... (the token form) instead of the expanded path. The string match fails.

Approach (WHAT)

• Write apm.cmd with Set-Content -Encoding ASCII -NoNewline (the encoding that worked pre-fix(install): use %LOCALAPPDATA% literal in Windows shim (closes #1509) #1512).
• The %LOCALAPPDATA% literal token from [BUG] The system cannot find the path specified. #1509 keeps the embedded shim target ASCII-only even when the user's profile directory contains non-ASCII characters -- so ASCII encoding does NOT re-introduce the [BUG] The system cannot find the path specified. #1509 bug for the default install location.
• Custom APM_INSTALL_DIR roots with non-ASCII characters fall outside this contract (and were never tested before); the percent-escape and absolute-path fallback in the else branch are preserved as-is.
• Relax the E2E "Shim points into per-user releases dir" assertion to accept either the expanded path or the %LOCALAPPDATA%-tokenized form.
• Invert the encoding regression contract in test_windows_shim_template.py: trap UTF-16/UTF-8 writers, positively require -Encoding ASCII.

Implementation (HOW)

install.ps1 -- shim write call:

$shimContent = "@echo off`r`nREM Generated by install.ps1 (microsoft/apm#1509) -- do not hand-edit.`r`nREM cmd.exe expands %LOCALAPPDATA% at runtime; hand-edited paths break.`r`n`"$shimTarget`" %*`r`n"
Set-Content -Path $shimPath -Value $shimContent -Encoding ASCII -NoNewline

scripts/windows/test-install-script.ps1 -- accept tokenized form:

$expectedExpanded = $releaseRoot.Path
$expectedTokenized = $null
if ($localAppData -and $expectedExpanded.StartsWith($localAppData, ...)) {
    $expectedTokenized = "%LOCALAPPDATA%" + $expectedExpanded.Substring($localAppData.Length)
}
Assert-True ($matchesExpanded -or $matchesTokenized) ...

Validation evidence

• All 8 regression tests in tests/unit/install/test_windows_shim_template.py pass locally.
• Full lint chain silent: ruff check, ruff format --check, pylint R0801, scripts/lint-auth-signals.sh.
• The actual Windows CI Test install.ps1 end-to-end job will run on this PR -- this is the only ground-truth verification for cmd.exe interpretation behavior and is what regressed previously.

Trade-offs

• Custom APM_INSTALL_DIR roots with non-ASCII paths are not robustly supported. ASCII encoding may strip such characters. This matches pre-fix(install): use %LOCALAPPDATA% literal in Windows shim (closes #1509) #1512 behavior; the case was never tested. Users hitting it should set APM_INSTALL_DIR to an ASCII path or rely on the default %LOCALAPPDATA% location.
• A truly bulletproof encoding for non-ASCII custom paths would require writing the shim in the active OEM code page ([System.Text.Encoding]::GetEncoding(0)), which differs between Windows PowerShell and PowerShell Core. Out of scope for this fix.

Refs #1509, #1512.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

This PR fixes a Windows regression where apm.cmd was written in UTF-16LE (with BOM) and became unreadable by cmd.exe when invoked via PATH. It reverts the shim output to ASCII and updates tests to reflect the corrected encoding and %LOCALAPPDATA% tokenization behavior.

Changes:

• Write apm.cmd using Set-Content -Encoding ASCII -NoNewline to keep the shim cmd.exe-compatible.
• Relax the end-to-end Windows install test to accept either expanded or %LOCALAPPDATA%-tokenized shim targets.
• Update the unit regression tests to forbid UTF-16/UTF-8 writers and positively assert ASCII encoding.

Show a summary per file

File	Description
install.ps1	Switches shim writing back to ASCII and documents why UTF-16 is not reliable for cmd.exe batch parsing.
scripts/windows/test-install-script.ps1	Adjusts E2E assertion to accept tokenized %LOCALAPPDATA% form in shim content.
tests/unit/install/test_windows_shim_template.py	Inverts regression contract: forbid UTF-16/UTF-8 writers and require -Encoding ASCII.
CHANGELOG.md	Updates the prior Windows shim entry to describe ASCII encoding behavior.

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 2