sc-036a.md

← Back to Backlog

[SC-036a] ✅ DONE - Add setup-proxy mode/auth prompts and mode marker

Status: Done (2026-04-20) Priority: High Component: lib/wsl/proxy.ps1, lib/wsl/scripts/setup-proxy.sh, lib/wsl/scripts/setup-proxy-negotiate.sh (new), lib/wsl/proxy.Tests.ps1 Parent: SC-036

Summary: As a developer, I want setup-proxy to ask me upfront whether I want Auto, Manual, or Remove — and, when a proxy URL is resolved, whether to use Basic or Negotiate auth — so that the tool's intent is obvious from the first prompt and I can opt into Kerberos mode in later slices.

Description: Foundation slice for the SC-036 epic. Two prompt changes plus a mode marker:

1. Top-level mode prompt [A]uto / [M]anual / [R]emove replaces the current PAC-first branching in Install-WslProxy. Auto runs PAC detection and asks the user to confirm the resolved URL. Manual goes straight to a host:port prompt. Remove dispatches setup-proxy.sh --remove with no further prompts.
2. Auth-method prompt [B]asic / [N]egotiate, shown only after a URL is resolved. Negotiate is stubbed in this slice: Install-WslProxy dispatches to a new sibling script setup-proxy-negotiate.sh which prints "not yet implemented" and exits with code 10.
3. Mode marker file /etc/wsl-manager/proxy-mode (values basic or negotiate) so future --remove (SC-036e) can tear down the correct set of artifacts without guessing.

Basic mode continues to call setup-proxy.sh unchanged, but now also writes basic to the marker file so SC-036e's mode-aware teardown works uniformly from day one.

Scope Decisions:

• Upfront A/M/R prompt over PAC-first branching: makes the tool's intent obvious from the first prompt rather than surfacing different follow-up prompts depending on whether PAC was found. "Remove" also gives users an interactive path to tear down config without needing to remember the --remove flag.
• Auto → DIRECT collapses to Remove: when PAC resolves to DIRECT, dispatch the same setup-proxy.sh --remove teardown that the Remove branch uses. Semantically identical (no proxy applies to this network) and keeps the concept count small.
• Auto with no PAC errors out: if the user explicitly picks Auto and no PAC/AutoConfigURL is present in the registry, fail with a hint to re-run and choose Manual. No silent fallback — the user's intent was "figure it out for me", and we can't.
• Auto confirmation gate: after PAC resolves to a URL, show it and ask [Y/N] before proceeding. Preserves the transparency of the old flow, where the resolved proxy was always printed.
• --remove flag stays: scripted/non-interactive teardown must not require a TTY. The interactive Remove branch is a convenience over the flag, not a replacement.
• Sibling script, not branching: Negotiate logic goes in a new setup-proxy-negotiate.sh rather than branching inside setup-proxy.sh. Keeps each script single-purpose (the existing script writes config files; the new one also installs packages and starts a service — three different kinds of work).
• Marker file location: /etc/wsl-manager/proxy-mode. System-wide (setup-proxy already writes root-owned files to /etc/apt/apt.conf.d/), survives user-home churn, explicit over auto-detecting by presence of ~/.local/bin/px.
• Stub the Negotiate path: emit "not yet implemented", exit code 10, so later slices land as functional additions rather than behavior changes.

Acceptance Criteria:

• Install-WslProxy prompts upfront: [A]uto / [M]anual / [R]emove
• Auto runs PAC detection, shows the resolved URL, and asks [Y/N] to confirm before proceeding
• Auto → PAC resolves to DIRECT: dispatches setup-proxy.sh --remove (same path as Remove)
• Auto → no PAC/AutoConfigURL in registry: throws with a hint to re-run and choose Manual
• Manual prompts for host:port and proceeds to the auth-method prompt
• Remove dispatches setup-proxy.sh --remove with no auth-method or credential prompts
• --remove CLI flag continues to work for non-interactive teardown
• Auth-method prompt [B]asic / [N]egotiate is shown only after a proxy URL is resolved (never for Remove, never for Auto → DIRECT)
• Basic path dispatches to existing setup-proxy.sh unchanged
• Negotiate path dispatches to new setup-proxy-negotiate.sh
• New setup-proxy-negotiate.sh exists, accepts the same base args (--proxy-url, --no-proxy, --username), prints a clear "not yet implemented" message, and exits with code 10
• Basic mode writes basic to /etc/wsl-manager/proxy-mode (creates the directory if missing)
• --remove in setup-proxy.sh deletes /etc/wsl-manager/proxy-mode on successful teardown
• Pester unit tests cover all three top-level branches (Auto/Manual/Remove) and the Auto sub-branches (URL confirm Y, URL confirm N, DIRECT, no PAC)
• Pester unit tests cover the auth-method prompt branch (mock the script invocation; assert correct script is called)
• All Y/N confirmation prompts use the utils.ps1 Y/N helper so that Enter is accepted as the default answer
• Credential prompt (Do you want to provide proxy credentials?) defaults to Yes — corporate proxies almost always require authentication
• All existing tests continue to pass
• docs/wsl-manager.md updated: Step 4 walkthrough, Setup Proxy command reference, and module structure reflect the new [A/M/R] flow, auth-method prompt, and setup-proxy-negotiate.sh
• UAT procedure below executed on a corporate WSL distro; all steps pass

UAT Procedure (run on a WSL distro with the feature branch checked out):

1. Auto — happy path: wsl-manager setup-proxy → A → confirm detected URL with Y → auth B → credentials as usual. Expect: /etc/wsl-manager/proxy-mode contains basic; proxy configured.
2. Auto — reject detected URL: A → N at the confirm prompt. Expect: throws with hint mentioning Re-run and Manual; no files changed.
3. Auto — no PAC (run off VPN or on a network without PAC): A. Expect: throws with No PAC/AutoConfigURL detected in registry. Re-run setup-proxy and choose [M]anual.
4. Manual: M → enter proxy.corp.com:8080. Expect: no PAC probe (feels instant), then auth/credentials prompts as before.
5. Remove (interactive): R. Expect: no auth or credential prompts; setup-proxy.sh --remove runs; /etc/wsl-manager/proxy-mode is deleted.
6. Invalid input: enter X (or just Enter). Expect: throws with Invalid choice 'X'. Expected [A]uto, [M]anual, or [R]emove.
7. Negotiate stub: A → Y → N. Expect: "not yet implemented" message, exit code 10.
8. --remove flag (non-interactive): wsl-manager setup-proxy --remove. Expect: no prompts; teardown runs; marker deleted.
9. Regression: after a fresh Basic setup, confirm .profile, /etc/apt/apt.conf.d/99proxy, ~/.docker/config.json, and ~/.config/containers/containers.conf all get the proxy config as before.
10. Credential prompt default: M → enter host:port → auth B → press Enter at the credential prompt. Expect: prompt accepts Enter as Yes and proceeds to ask for username/password.

UAT Issues:

• General — Y/N prompts do not accept Enter as default: All [Y/N] confirmation prompts require an explicit key press; pressing Enter is not accepted. Resolved: switched all prompts to the utils.ps1 Y/N helper.

← Back to Backlog