Skip to content

sc-017.md

Latest commit

 

History

History
45 lines (33 loc) · 5.19 KB

sc-017.md

File metadata and controls

45 lines (33 loc) · 5.19 KB
Raw

← Back to Backlog

[SC-017] ✅ DONE - Auto-terminate distros instead of prompting the user

Status: Done (2026-05-04) Priority: Medium Component: tools/wsl-manager/wsl-manager.ps1, lib/wsl/user.ps1, lib/wsl/proxy.ps1, lib/wsl/docker.ps1, lib/wsl/manager.docker.Integration.Tests.ps1, docs/wsl-manager.md

Summary: As a user, I want wsl-manager to automatically terminate a distribution when required instead of asking me to do it manually, so that actions complete seamlessly without extra manual steps.

Description: Several wsl-manager actions (e.g., setup-docker, setup-podman, setup-user) require a distribution restart to apply wsl.conf changes. Currently some flows print a message telling the user to terminate the distro manually. The tool should handle this automatically; if an action requires a restart, it should terminate and (if needed) re-launch the distribution without user intervention.

The first commit (be944b4) migrated remove/clone/update/configure-wsl/repair-interop/setup-docker/setup-podman/setup-proxy from raw wsl.exe --terminate to the central Stop-WslDistro helper. A post-merge review surfaced gaps that re-open this story:

Gap 1 — New-WslUser was missed by the migration

lib/wsl/user.ps1:151-154 still calls wsl.exe --terminate $DistroName followed by Start-Sleep -Seconds 2. Only the doc comments at :22-23 and :46-47 were updated to claim "automatically terminated". The code therefore bypasses the retry/verification loop that Stop-WslDistro (and SC-012) added, and user.Tests.ps1 has no assertion guarding the auto-terminate behavior. Replace with Stop-WslDistro -Name $DistroName -Confirm:$false | Out-Null and add a unit test mirroring the pattern at commands.Tests.ps1:1107-1117.

Gap 2 — Install-WslProxy mis-reports termination failure as proxy failure (regression)

The migration added Stop-WslDistro at lib/wsl/proxy.ps1:212 inside the case-0 (success) arm of the exit-code switch. The entire arm sits inside an outer try { … } catch { Write-Error "Proxy configuration failed: $_"; return $false }. Stop-WslDistro throws after 3 retries (core.ps1:608) when termination cannot be verified. When that happens the user sees "Proxy configuration failed: Failed to terminate distribution …" — even though setup-proxy.sh returned 0 and every config target was written successfully. Wrap the Stop-WslDistro call in its own try/catch that emits a non-fatal Write-Warning and still returns $true. The proxy was configured; only the convenience restart failed.

Gap 3 — Integration coverage for clone & remove auto-terminate was dropped

Pre-migration, manager.docker.Integration.Tests.ps1 had four state-validation tests (update / clone / remove / "after stop"). The migration collapsed these into a single auto-terminate test for update. Clone and remove auto-terminate is now only verified by mocked unit tests, which don't catch issues like Stop-WslDistro polling not converging on the real WSL VM. Add two integration tests paralleling the existing update test — one for clone, one for remove — under the existing "Auto-terminate for Operations" Context block.

Gap 4 — Stale doc references and undocumented configure-wsl side effect

  • lib/wsl/docker.ps1:110-114 .NOTES still tells users "the user must restart the distribution for group membership to take effect: wsl.exe --terminate " — stale since the install auto-terminates.
  • docs/wsl-manager.md does not mention that configure-wsl now silently shuts down the entire WSL subsystem (Stop-WslSubsystem is invoked at the end). This is a behavior change beyond per-distro auto-termination and warrants a one-line note for users who run configure-wsl and don't expect their other distros to be terminated.

The "Next steps" blocks at docker.ps1:294-299 and podman.ps1:329-334 are fine as-is — they correctly tell the user how to launch the distribution after the auto-terminate.

Acceptance Criteria:

  • No action prompts the user to manually terminate a distribution
  • Actions that require a restart automatically terminate (and re-launch if needed) the distribution (remove, clone, update, configure-wsl, repair-interop, setup-docker, setup-podman, setup-proxy, setup-user migrated)
  • lib/wsl/user.ps1 New-WslUser uses Stop-WslDistro instead of raw wsl.exe --terminate, and Start-Sleep -Seconds 2 is removed
  • user.Tests.ps1 includes a test asserting Stop-WslDistro is invoked after a successful user creation
  • Install-WslProxy returns $true and emits a Write-Warning (not Write-Error) when setup-proxy.sh exits 0 but Stop-WslDistro throws
  • Pester test in proxy.Tests.ps1 asserts the above behavior
  • Integration test added: clone auto-terminates the source distribution when running and completes successfully
  • Integration test added: remove auto-terminates the distribution when running and completes successfully
  • lib/wsl/docker.ps1 .NOTES no longer tells users to manually terminate after install
  • docs/wsl-manager.md notes the configure-wsl subsystem-wide shutdown side effect
  • All existing tests continue to pass

← Back to Backlog