ae-test-win.sh

#!/usr/bin/env bash
#
# ae-test-win.sh — Manage VSCode test environments for Atlas Explorer manual
#                  visual testing. AE is a WSL-only extension — all extension
#                  management operates on the WSL vscode-server.
#                  GitHub operations are delegated to WSL.
#
# Windows prerequisites:  code (VSCode on PATH), wsl, tasklist.exe
# WSL prerequisites:      gh (authenticated via 'gh auth login'), jq, unzip

[ -z "${BASH_VERSION:-}" ] && { printf "%s\n" "Error: This script requires Bash." >&2; exit 1; }

set -eufo pipefail

# ── constants ────────────────────────────────────────────────────────────────

readonly _GH_REPO="MIPS/gyrfalcon-ui"
readonly _AE_PATTERN="mips.atlasexplorer*"
# shellcheck disable=SC2155
readonly _SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Mutable globals — set in main() once USERNAME is verified.
_win_user=""
_state_dir=""
_state_file=""
_win_code_user_dir=""  # %APPDATA%\Code\User (Git Bash path)
_win_blank_dir=""      # ${_win_code_user_dir}.ae-test-blank — blank backup
_wsl_home=""           # resolved at startup via WSL — no ~ expansion ambiguity
_wsl_ext_dir=""        # ${_wsl_home}/.vscode-server/extensions
_wsl_backup_dir=""     # ${_wsl_home}/.local/share/ae-test/backup-wsl
_wsl_blank_ext_dir=""  # ${_wsl_home}/.local/share/ae-test/blank-wsl-ext
_verbosity=0

# ── helpers ──────────────────────────────────────────────────────────────────

die()  { printf "%s\n" "${1:-Unknown error}" >&2; exit "${2:-1}"; }
info() { printf "%s\n" "${1:-}" >&2; }
dbg()  { [ "${_verbosity}" -ge 1 ] || return 0; printf "[debug] %s\n" "${1:-}" >&2; }

# Printed on every invocation. Atlas Explorer releases moved from
# gyrfalcon-ui GitHub Releases to VSCode Marketplace pre-releases, so the
# 'gh release' calls this script depends on no longer see current builds.
# The script is left runnable (e.g. to fetch old archived releases) but
# should be considered unmaintained.
warn_deprecated() {
  cat <<'EOF' >&2
=================================================================
 DEPRECATED: ae-test-win.sh no longer reflects how Atlas Explorer
 is released.

 Atlas Explorer releases are no longer published to
 https://github.com/MIPS/gyrfalcon-ui/releases. They are now
 published as pre-releases on the VSCode Extension Marketplace.

 This script only knows how to fetch/install from gyrfalcon-ui
 releases, so 'init' and 'fetch' will not see current builds.
 Use the Marketplace pre-release channel instead. This script is
 unmaintained and may be removed.
=================================================================
EOF
}

usage() {
  warn_deprecated
  cat <<EOF
ae-test-win.sh — Manage Windows-native VSCode test environments for
                  Atlas Explorer visual testing.

Usage: ae-test-win.sh <command> [options]

Commands:
  init                      Download latest AE, back up real profile, activate
                            'new' scenario
  select new                Activate the new-user scenario (no AE installed)
  select new --reset        Rebuild and re-activate the new-user scenario
  select backup             Temporarily restore your original AE (stays in test mode)
  select blank              Factory-fresh VSCode — no extensions, no user settings
  select blank --reset      Wipe what VSCode wrote during blank session and start fresh
  fetch                     Download the latest AE release next to this script
  cleanup                   Restore real profile, remove all test dirs

Options:
  -v            Enable debug output
  -vv           Enable full trace (set -x, implies -v)
  --help, -h    Show this help message

Requires VSCode and WSL on Windows; gh (authenticated), jq, unzip in WSL.
Debug output goes to stderr. Capture with: ./ae-test-win.sh -v 2>debug.log
EOF
  exit 0
}

check_dependencies() {
  # Git Bash sets MSYSTEM (MINGW64/MINGW32/MSYS); WSL and native Linux bash
  # never do. Catching this here gives a clear error instead of a confusing
  # PATH lookup failure or a mkdir into a nonexistent /c/... path later on.
  case "${MSYSTEM:-}" in
    MINGW*|MSYS) ;;
    *) die "Error: This script must be run in Git Bash on Windows, not WSL or native Linux bash." ;;
  esac

  local tool=""
  for tool in "code" "wsl" "tasklist.exe"; do
    command -v "${tool}" >/dev/null 2>&1 \
      || die "Error: Required tool '${tool}' not found on PATH."
  done
  wsl bash -c 'command -v gh'    >/dev/null 2>&1 || die "Error: 'gh' is not installed in WSL."
  wsl bash -c 'command -v jq'    >/dev/null 2>&1 || die "Error: 'jq' is not installed in WSL."
  wsl bash -c 'command -v unzip' >/dev/null 2>&1 || die "Error: 'unzip' is not installed in WSL."
}

# Returns 0 if Code.exe is running, 1 otherwise.
# Uses //FI and //NH to prevent MSYS2 from converting /FI to a Windows path.
_vscode_running() {
  local count=0
  count="$(tasklist.exe //FI "IMAGENAME eq Code.exe" //NH </dev/null 2>/dev/null \
    | grep -Evc "^[[:space:]]*$|INFO:")" || true
  dbg "Code.exe process count: ${count}"
  [ "${count}" -gt 0 ] || return 1
}

_check_no_vscode() {
  _vscode_running \
    && die "Error: VSCode is currently running. Close all VSCode windows first." \
    || return 0
}

# Verify GitHub CLI auth in WSL *and* read access to the private AE repo.
# `gh auth status` only proves the token is valid — it doesn't prove the
# account can see ${_GH_REPO}. Checking both up front turns a confusing
# downstream "Could not determine latest release tag" into a clear,
# actionable error before any download work begins.
_check_gh_access() {
  wsl gh auth status >/dev/null 2>&1 \
    || die "Error: Not authenticated with GitHub in WSL. Run: wsl gh auth login"

  wsl gh repo view "${_GH_REPO}" >/dev/null 2>&1 \
    || die "Error: Cannot access ${_GH_REPO} in WSL.
  This usually means your account isn't a member of the MIPS org, or (for
  SAML SSO orgs) your gh token hasn't been SSO-authorized. Run:
    wsl gh repo view ${_GH_REPO}
  to see the actual error, then request org access or authorize your token
  at https://github.com/settings/tokens, and retry."
}

# Convert a Git Bash /drive/... path to a WSL /mnt/drive/... path.
_to_wsl_path() {
  local p="${1}"
  [[ "${p}" == /[a-z]/* ]] \
    || die "Error: Cannot convert to WSL path: '${p}' (expected /drive/... format)"
  printf "%s" "/mnt${p}"
}

# Convert a Git Bash /drive/... path to a Windows-native C:\... path for display.
_to_win_path() {
  cygpath -w "${1}" 2>/dev/null || printf "%s" "${1}"
}

# Run a command in WSL bash, suppressing the spurious "Failed to translate"
# warnings that WSL emits for unmappable Windows PATH entries (e.g. U:\bin).
# Stdout is passed through untouched. Stderr is filtered and reprinted.
# The caller's exit code is preserved.
_wsl() {
  local _rc=0 _stderr
  _stderr="$(mktemp)"
  wsl bash -c "${1}" 2>"${_stderr}" || _rc=$?
  grep -Fv "Failed to translate" "${_stderr}" >&2 || true
  rm -f "${_stderr}"
  return "${_rc}"
}

# ── state helpers ─────────────────────────────────────────────────────────────

# Read a key from state.txt. Prints empty string if key or file not found.
_state_get() {
  local key="${1}"
  grep "^${key}=" "${_state_file}" 2>/dev/null | cut -d= -f2- || true
}

# Write or update a key in state.txt. Atomic via tmp-file + mv.
_state_set() {
  local key="${1}" value="${2}"
  local tmp="${_state_file}.$$.tmp"
  { grep -v "^${key}=" "${_state_file}" 2>/dev/null || true
    printf "%s=%s\n" "${key}" "${value}"
  } > "${tmp}"
  mv "${tmp}" "${_state_file}"
}

# ── WSL extension helpers ──────────────────────────────────────────────────────
#
# AE is a WSL-only extension — it cannot be installed in the Windows-native
# VSCode context. All extension management operates on the WSL vscode-server.
# _wsl_home, _wsl_ext_dir, and _wsl_backup_dir are resolved at startup by
# querying WSL directly — no ~ expansion, no ambiguity.

# Returns 0 if the WSL vscode-server extensions dir exists.
_wsl_ext_dir_exists() {
  _wsl "[ -d '${_wsl_ext_dir}' ]" 2>/dev/null
}

# Filter AE entries from WSL extensions.json. No-op if file absent.
_wsl_ae_clean_extensions_json() {
  _wsl "
    [ -f '${_wsl_ext_dir}/extensions.json' ] || exit 0
    jq '[.[] | select((.identifier.id // \"\") | ascii_downcase | startswith(\"mips.atlasexplorer\") | not)]' \
      '${_wsl_ext_dir}/extensions.json' > '${_wsl_ext_dir}/extensions.json.tmp' \
      && mv '${_wsl_ext_dir}/extensions.json.tmp' '${_wsl_ext_dir}/extensions.json'
  "
}

# Back up WSL-side AE to WSL backup dir; clean WSL extensions.json.
_wsl_ae_backup() {
  if ! _wsl_ext_dir_exists; then
    info "  (WSL vscode-server not found — skipping WSL backup)"
    _state_set "wsl_backup_taken" "false"
    return 0
  fi

  info "Backing up existing WSL AE installation..."
  _wsl "
    rm -rf '${_wsl_backup_dir}'
    mkdir -p '${_wsl_backup_dir}'
    [ -f '${_wsl_ext_dir}/extensions.json' ] \
      && cp '${_wsl_ext_dir}/extensions.json' '${_wsl_backup_dir}/extensions.json' || true
    find '${_wsl_ext_dir}' -maxdepth 1 -name 'mips.atlasexplorer*' -type d \
      -exec mv {} '${_wsl_backup_dir}/' \;
  "
  _wsl_ae_clean_extensions_json
  _state_set "wsl_backup_taken" "true"
  info "  Done."
}

# Remove AE from WSL vscode-server extensions dir; clean extensions.json.
_wsl_ae_remove() {
  _wsl_ext_dir_exists || return 0
  _wsl "
    find '${_wsl_ext_dir}' -maxdepth 1 -name 'mips.atlasexplorer*' -type d -exec rm -rf {} +
  "
  _wsl_ae_clean_extensions_json
}

# Restore WSL-side AE from backup. No-op if no backup was taken.
_wsl_ae_restore() {
  local wsl_backup_taken
  wsl_backup_taken="$(_state_get "wsl_backup_taken")"
  [ "${wsl_backup_taken}" = "true" ] || return 0

  info "Restoring original WSL extension state..."
  _wsl "
    find '${_wsl_ext_dir}' -maxdepth 1 -name 'mips.atlasexplorer*' -type d -exec rm -rf {} +
    if [ -d '${_wsl_backup_dir}' ]; then
      find '${_wsl_backup_dir}' -mindepth 1 -maxdepth 1 -type d \
        -exec mv {} '${_wsl_ext_dir}/' \;
      [ -f '${_wsl_backup_dir}/extensions.json' ] \
        && mv '${_wsl_backup_dir}/extensions.json' '${_wsl_ext_dir}/extensions.json' || true
      rm -rf '${_wsl_backup_dir}'
    fi
  "
  info "  Done."
}

# ── blank scenario helpers ─────────────────────────────────────────────────────

# Apply window title for a scenario. On first activation (active=""), saves the
# original title to state.txt via _inject_window_title. On subsequent switches,
# only updates the title without overwriting the saved original.
_apply_scenario_window_title() {
  local scenario="${1}"
  local active
  active="$(_state_get "active")"
  if [ -z "${active}" ]; then
    _inject_window_title "${scenario}"
  else
    local new_title
    # shellcheck disable=SC2016  # single quotes intentional: VSCode template vars
    new_title="$(printf '[AE Test: %s] ${activeEditorShort}${separator}${rootName}' "${scenario}")"
    _window_title_set "${new_title}"
  fi
}

# Back up all WSL extensions to blank-wsl-ext. Normalizes first by removing AE
# (which is already safely in backup-wsl) so the blank backup never contains AE.
_wsl_blank_backup_extensions() {
  info "  Backing up all WSL extensions..."
  _wsl "
    mkdir -p '${_wsl_blank_ext_dir}'
    find '${_wsl_ext_dir}' -maxdepth 1 -name 'mips.atlasexplorer*' -type d -exec rm -rf {} +
    [ -f '${_wsl_ext_dir}/extensions.json' ] \
      && mv '${_wsl_ext_dir}/extensions.json' '${_wsl_blank_ext_dir}/' || true
    find '${_wsl_ext_dir}' -maxdepth 1 -mindepth 1 -type d \
      -exec mv {} '${_wsl_blank_ext_dir}/' \;
  "
}

# Restore all WSL extensions from blank backup. No-op if backup absent.
_wsl_blank_restore_extensions() {
  _wsl "
    [ -d '${_wsl_blank_ext_dir}' ] || exit 0
    find '${_wsl_ext_dir}' -maxdepth 1 -mindepth 1 -exec rm -rf {} +
    find '${_wsl_blank_ext_dir}' -maxdepth 1 -mindepth 1 -type d \
      -exec mv {} '${_wsl_ext_dir}/' \;
    [ -f '${_wsl_blank_ext_dir}/extensions.json' ] \
      && mv '${_wsl_blank_ext_dir}/extensions.json' '${_wsl_ext_dir}/' || true
    rm -rf '${_wsl_blank_ext_dir}'
  "
}

# Move Code\User to blank backup, replace with empty dir.
_blank_backup_win_settings() {
  info "  Backing up Windows user settings..."
  [ -d "${_win_code_user_dir}" ] && mv "${_win_code_user_dir}" "${_win_blank_dir}" || true
  mkdir -p "${_win_code_user_dir}"
}

# Restore Code\User from blank backup. Removes whatever VSCode wrote during blank session.
_blank_restore_win_settings() {
  if [ -d "${_win_blank_dir}" ]; then
    rm -rf "${_win_code_user_dir}"
    mv "${_win_blank_dir}" "${_win_code_user_dir}"
  fi
}

# Restore everything backed up by select blank, then clear the blank backup state.
_restore_blank_backup() {
  info "Restoring from blank scenario..."
  _wsl_blank_restore_extensions
  _blank_restore_win_settings
  _state_set "blank_backup_taken" "false"
  info "  Done."
}



_settings_json_wsl() {
  printf "%s" "/mnt/c/Users/${_win_user}/AppData/Roaming/Code/User/settings.json"
}

# Read the current window.title from settings.json via WSL jq.
# Prints empty string if the key is absent or the file does not exist.
_window_title_get() {
  local settings_wsl
  settings_wsl="$(_settings_json_wsl)"
  _wsl "[ -f '${settings_wsl}' ] || exit 0
    jq -r '.\"window.title\" // empty' '${settings_wsl}' 2>/dev/null" || true
}

# Atomically write a new window.title into settings.json via WSL jq.
# Title is passed via a temp file so VSCode template variables (${activeEditorShort}
# etc.) survive shell expansion intact.
#
# env.WINDOW_TITLE is used in the jq filter instead of --arg/$t to avoid a
# MSYS2 Git Bash quirk: \$t in a double-quoted string becomes $t, which Git Bash
# then expands as a shell variable (empty), silently dropping the value from the filter.
_window_title_set() {
  local title="${1}"
  local settings_wsl
  settings_wsl="$(_settings_json_wsl)"
  local tmp_title="/c/Users/${_win_user}/AppData/Local/Temp/ae-test-title-$$.txt"
  local tmp_title_wsl="/mnt/c/Users/${_win_user}/AppData/Local/Temp/ae-test-title-$$.txt"
  local tmp_json_wsl="/mnt/c/Users/${_win_user}/AppData/Local/Temp/ae-test-json-$$.json"

  printf '%s' "${title}" > "${tmp_title}"

  _wsl "
    WINDOW_TITLE=\"\$(cat '${tmp_title_wsl}')\"
    if [ -f '${settings_wsl}' ]; then
      jq '.\"window.title\" = env.WINDOW_TITLE' '${settings_wsl}' > '${tmp_json_wsl}' && mv '${tmp_json_wsl}' '${settings_wsl}'
    else
      jq -n '{\"window.title\": env.WINDOW_TITLE}' > '${settings_wsl}'
    fi
    rm -f '${tmp_title_wsl}'
  "
  rm -f "${tmp_title}" 2>/dev/null || true
}

# Remove the window.title key from settings.json (used when it was absent originally).
_window_title_remove() {
  local settings_wsl
  settings_wsl="$(_settings_json_wsl)"
  local tmp_json_wsl="/mnt/c/Users/${_win_user}/AppData/Local/Temp/ae-test-json-$$.json"
  _wsl "[ -f '${settings_wsl}' ] || exit 0; jq 'del(.\"window.title\")' '${settings_wsl}' > '${tmp_json_wsl}' && mv '${tmp_json_wsl}' '${settings_wsl}'"
}

# Save the current window.title to state.txt, then inject the test label.
# Single-quoted printf format keeps VSCode template vars literal (not bash-expanded).
_inject_window_title() {
  local scenario="${1}"
  local settings_wsl
  settings_wsl="$(_settings_json_wsl)"

  # Record whether settings.json existed so cleanup can restore the exact original state.
  local existed="true"
  _wsl "[ -f '${settings_wsl}' ]" 2>/dev/null || existed="false"
  _state_set "settings_json_existed" "${existed}"

  local original=""
  [ "${existed}" = "true" ] && original="$(_window_title_get)" || true
  _state_set "original_window_title" "${original}"

  local new_title
  # shellcheck disable=SC2016  # single quotes intentional: keeps VSCode template vars literal
  new_title="$(printf '[AE Test: %s] ${activeEditorShort}${separator}${rootName}' "${scenario}")"
  _window_title_set "${new_title}"
  dbg "window title set: ${new_title}"
}

# Restore window.title from state.txt.
# If settings.json did not exist before init, delete it entirely (do not leave {}).
_restore_window_title() {
  local original existed
  original="$(_state_get "original_window_title")"
  existed="$(_state_get "settings_json_existed")"

  # Both empty means select was never run — window title was never touched.
  if [ -z "${existed}" ] && [ -z "${original}" ]; then
    dbg "window title was never set — nothing to restore"
    return 0
  fi

  if [ "${existed}" = "false" ]; then
    local settings="/c/Users/${_win_user}/AppData/Roaming/Code/User/settings.json"
    rm -f "${settings}"
    dbg "settings.json did not exist before init — deleted"
  elif [ -z "${original}" ]; then
    _window_title_remove
    dbg "window title key removed (was not originally set)"
  else
    _window_title_set "${original}"
    dbg "window title restored: '${original}'"
  fi
}

# ── commands ──────────────────────────────────────────────────────────────────

cmd_init() {
  [ -f "${_state_file}" ] \
    && die "Error: Test environment already initialized. Run 'ae-test-win.sh cleanup' first."

  # Guard against leftover WSL backup from a previously interrupted session.
  if _wsl "[ -d '${_wsl_backup_dir}' ]" 2>/dev/null; then
    die "Error: Leftover WSL backup from a previous session detected.
  Run 'ae-test-win.sh cleanup' to remove it before initializing."
  fi

  _check_no_vscode

  _check_gh_access

  # ── fetch latest release tag ──────────────────────────────────────────────

  info "Fetching latest release from ${_GH_REPO}..."
  local tag=""
  tag="$(_wsl "gh release list --repo '${_GH_REPO}' --limit 1 --json tagName | jq -r '.[0].tagName'")"
  [ -n "${tag}" ] || die "Error: Could not determine latest release tag."
  info "  latest: ${tag}"

  # ── download and validate VSIX ────────────────────────────────────────────

  local vsix_dir="${_state_dir}/vsix"
  local vsix_dir_wsl
  vsix_dir_wsl="$(_to_wsl_path "${vsix_dir}")"
  mkdir -p "${vsix_dir}"

  # Remove incomplete download on failure — but only until the backup is taken.
  # After backup, the user must run cleanup to recover.
  # shellcheck disable=SC2064
  trap "rm -rf '${vsix_dir}'" EXIT

  info "Downloading VSIX for ${tag} (all platforms)..."
  _wsl "gh release download '${tag}' \
    --repo '${_GH_REPO}' \
    --pattern '*.vsix' \
    --dir '${vsix_dir_wsl}'"

  local vsix_count
  vsix_count="$(find "${vsix_dir}" -maxdepth 1 -name "*.vsix" | wc -l)"
  [ "${vsix_count}" -gt 0 ] || die "Error: No VSIX files found after download."
  if [ "${vsix_count}" -gt 1 ]; then
    info "Error: Expected exactly one VSIX but found ${vsix_count}. The release may have added platform-specific variants."
    info "  Downloaded files:"
    find "${vsix_dir}" -maxdepth 1 -name "*.vsix" \
      | while IFS= read -r f; do info "    $(_to_win_path "${f}")"; done
    die "Run 'ae-test-win.sh cleanup' and investigate the release before retrying."
  fi
  local vsix_file=""
  vsix_file="$(find "${vsix_dir}" -maxdepth 1 -name "*.vsix" -print -quit)"
  info "  $(_to_win_path "${vsix_file}")"

  info "Checking VSIX integrity..."
  _wsl "unzip -t '${vsix_dir_wsl}/$(basename "${vsix_file}")'" >/dev/null \
    || die "Error: VSIX integrity check failed: $(basename "${vsix_file}")"

  # Backup about to be taken — clear the download trap.
  # From here, failure recovery is via 'ae-test-win.sh cleanup'.
  trap "" EXIT

  # ── write initial state ───────────────────────────────────────────────────
  # Must happen before _wsl_ae_backup so its _state_set "wsl_backup_taken"
  # isn't overwritten by the truncate below.

  mkdir -p "${_state_dir}"
  : > "${_state_file}"
  _state_set "version"               "${tag}"
  _state_set "active"                ""
  _state_set "backup_created_at"     "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  _state_set "new_built_at"          "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  _state_set "wsl_backup_taken"      ""
  _state_set "blank_backup_taken"    ""
  _state_set "settings_json_existed" ""
  _state_set "original_window_title" ""

  # ── back up existing WSL AE ───────────────────────────────────────────────
  # Updates wsl_backup_taken in state.txt to "true" or "false".

  _wsl_ae_backup

  # ── default to 'new' scenario ─────────────────────────────────────────────
  # AE is already removed by the backup step. Activating 'new' now ensures
  # VSCode is in a defined state immediately — no manual select required.

  info "Activating 'new' scenario by default..."
  _wsl_ae_remove
  _inject_window_title "new"
  _state_set "active" "new"

  local vsix_src="" vsix_dest="" vsix_win=""
  vsix_src="$(find "${_state_dir}/vsix" -maxdepth 1 -name "*.vsix" -print -quit 2>/dev/null || true)"
  if [ -n "${vsix_src}" ]; then
    vsix_dest="${_SCRIPT_DIR}/$(basename "${vsix_src}")"
    cp "${vsix_src}" "${vsix_dest}"
    vsix_win="$(_to_win_path "${vsix_dest}")"
  fi

  info "Initialized (${tag}) — 'new' scenario active."
  info "Open VSCode to test the first-time install flow."
  if [ -n "${vsix_win}" ]; then
    info "  To install: Extensions panel → ⋮ → Install from VSIX... then select:"
    info "  ${vsix_win}"
  fi
  info "Run 'ae-test-win.sh cleanup' when done testing."
}

cmd_select() {
  local scenario="${1:-}"
  [ -n "${scenario}" ] \
    || die "Error: 'select' requires a scenario. Use 'new', 'backup', or 'blank'."
  shift

  local reset=0
  while [ $# -gt 0 ]; do
    case "$1" in
      --reset) reset=1; shift ;;
      *) die "Error: Unknown option '${1}' for 'select'." ;;
    esac
  done

  case "${scenario}" in
    new|backup|blank) ;;
    *) die "Error: Unknown scenario '${scenario}'. Use 'new', 'backup', or 'blank'." ;;
  esac

  [ -f "${_state_file}" ] \
    || die "Error: Test environment not initialized. Run 'ae-test-win.sh init' first."

  [ "${scenario}" = "backup" ] && [ "${reset}" = "1" ] \
    && die "Error: --reset is not valid for 'select backup'. The backup is read-only."

  _check_no_vscode

  # ── blank ─────────────────────────────────────────────────────────────────

  if [ "${scenario}" = "blank" ]; then
    local current_active
    current_active="$(_state_get "active")"

    if [ "${reset}" = "1" ]; then
      # Reset: restore blank backup (undo anything VSCode wrote), then re-blank.
      [ "${current_active}" = "blank" ] \
        || die "Error: --reset for 'blank' requires blank to already be active."
      info "Resetting 'blank' scenario..."
      _wsl_blank_restore_extensions
      _blank_restore_win_settings
      _state_set "blank_backup_taken" "false"
      # Fall through to re-activate blank below.
    else
      [ "${current_active}" = "blank" ] \
        && die "Error: Already in blank scenario. Use --reset to wipe and restart it."
    fi

    info "Activating 'blank' scenario (factory-fresh VSCode)..."
    _wsl_blank_backup_extensions
    _blank_backup_win_settings
    _apply_scenario_window_title "blank"
    _state_set "active"             "blank"
    _state_set "blank_backup_taken" "true"
    info "Done. Open VSCode — no extensions or user settings will be present."
    info "Run 'ae-test-win.sh select <scenario>' to switch, or 'cleanup' when done."
    return
  fi

  # ── non-blank scenarios: restore blank backup if needed ───────────────────

  local blank_backup_taken
  blank_backup_taken="$(_state_get "blank_backup_taken")"
  if [ "${blank_backup_taken}" = "true" ]; then
    _restore_blank_backup
  fi

  # ── backup ────────────────────────────────────────────────────────────────

  if [ "${scenario}" = "backup" ]; then
    _wsl "[ -d '${_wsl_backup_dir}' ]" 2>/dev/null \
      || die "Error: No backup found. Has 'ae-test-win.sh init' been run?"
    info "Activating 'backup' scenario..."
    _wsl_ae_remove
    _wsl "
      find '${_wsl_backup_dir}' -mindepth 1 -maxdepth 1 -type d \
        -exec cp -r {} '${_wsl_ext_dir}/' \;
      [ -f '${_wsl_backup_dir}/extensions.json' ] \
        && cp '${_wsl_backup_dir}/extensions.json' '${_wsl_ext_dir}/extensions.json' || true
    "
    _apply_scenario_window_title "backup"
    _state_set "active" "backup"
    info "Done. Your original AE is temporarily active."
    info "Run 'ae-test-win.sh select new' or 'select returning' to resume testing."
    return
  fi

  # ── new ───────────────────────────────────────────────────────────────────

  if [ "${reset}" = "1" ]; then
    info "Resetting 'new' scenario..."
    _state_set "new_built_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
    # Fall through to activation below.
  fi

  info "Activating 'new' scenario..."
  _wsl_ae_remove
  _apply_scenario_window_title "new"
  _state_set "active" "new"

  # Copy VSIX next to this script for easy access in VSCode's file picker.
  local vsix_src="" vsix_dest="" vsix_win=""
  vsix_src="$(find "${_state_dir}/vsix" -maxdepth 1 -name "*.vsix" -print -quit 2>/dev/null || true)"
  if [ -n "${vsix_src}" ]; then
    vsix_dest="${_SCRIPT_DIR}/$(basename "${vsix_src}")"
    cp "${vsix_src}" "${vsix_dest}"
    vsix_win="$(_to_win_path "${vsix_dest}")"
  fi

  info "Done. Open VSCode — no Atlas Explorer will be installed."
  if [ -n "${vsix_win}" ]; then
    info "  To install: Extensions panel → ⋮ → Install from VSIX... then select:"
    info "  ${vsix_win}"
  fi
  info "Run 'ae-test-win.sh cleanup' when done testing."
}

cmd_fetch() {
  _check_gh_access

  info "Fetching latest release from ${_GH_REPO}..."
  local tag=""
  tag="$(_wsl "gh release list --repo '${_GH_REPO}' --limit 1 --json tagName | jq -r '.[0].tagName'")"
  [ -n "${tag}" ] || die "Error: Could not determine latest release tag."
  info "  latest: ${tag}"

  local tmp_dir="/c/Users/${_win_user}/AppData/Local/Temp/ae-test-fetch-$$"
  mkdir -p "${tmp_dir}"
  local tmp_dir_wsl
  tmp_dir_wsl="$(_to_wsl_path "${tmp_dir}")"
  # shellcheck disable=SC2064
  trap "rm -rf '${tmp_dir}'" EXIT

  info "Downloading VSIX for ${tag}..."
  _wsl "gh release download '${tag}' \
    --repo '${_GH_REPO}' \
    --pattern '*.vsix' \
    --dir '${tmp_dir_wsl}'"

  local vsix_count
  vsix_count="$(find "${tmp_dir}" -maxdepth 1 -name "*.vsix" | wc -l)"
  [ "${vsix_count}" -gt 0 ] || die "Error: No VSIX files found after download."
  if [ "${vsix_count}" -gt 1 ]; then
    info "Error: Expected exactly one VSIX but found ${vsix_count}."
    find "${tmp_dir}" -maxdepth 1 -name "*.vsix" \
      | while IFS= read -r f; do info "    $(basename "${f}")"; done
    die "Investigate the release at https://github.com/${_GH_REPO}/releases"
  fi

  local vsix_file=""
  vsix_file="$(find "${tmp_dir}" -maxdepth 1 -name "*.vsix" -print -quit)"
  local vsix_dest=""
  vsix_dest="${_SCRIPT_DIR}/$(basename "${vsix_file}")"

  if [ -f "${vsix_dest}" ]; then
    info "  Already downloaded: $(_to_win_path "${vsix_dest}")"
    return 0
  fi

  mv "${vsix_file}" "${vsix_dest}"
  trap "" EXIT
  rm -rf "${tmp_dir}"
  info "  $(_to_win_path "${vsix_dest}")"
}

cmd_cleanup() {
  [ -d "${_state_dir}" ] \
    || die "Error: No test environment found. Nothing to clean up."

  _check_no_vscode

  info "Cleaning up test environment..."

  # Restore blank backup first if active — brings extensions and settings back
  # to post-init state before the regular WSL AE restore runs.
  local blank_backup_taken
  blank_backup_taken="$(_state_get "blank_backup_taken" 2>/dev/null || true)"
  [ "${blank_backup_taken}" = "true" ] && _restore_blank_backup || true

  # Safety net: restore _win_blank_dir if it still exists regardless of state.
  # It is the user's settings backup and must always be restored, never deleted.
  [ -d "${_win_blank_dir}" ] && _blank_restore_win_settings || true

  [ -f "${_state_file}" ] && _wsl_ae_restore || true

  if [ -f "${_state_file}" ]; then
    _restore_window_title
  else
    info "  Warning: state.txt missing — window.title in settings.json could not be restored."
    info "  If your VSCode title bar shows '[AE Test: ...]', remove the window.title key manually."
  fi

  # Remove all state dirs — WSL side and Windows side — in a single WSL call.
  # WSL can reach the Windows filesystem at /mnt/c/..., keeping cleanup atomic.
  local win_state_dir_wsl="/mnt/c/Users/${_win_user}/AppData/Local/ae-test"
  _wsl "
    rm -rf '${_wsl_home}/.local/share/ae-test'
    rm -rf '${win_state_dir_wsl}'
  "

  # Remove any VSIX copied next to the script (not inside state_dir).
  find "${_SCRIPT_DIR}" -maxdepth 1 -name "*.vsix" -exec rm -f {} +

  # Remove any temp files left by interrupted window title operations.
  local tmp_dir_wsl="/mnt/c/Users/${_win_user}/AppData/Local/Temp"
  _wsl "find '${tmp_dir_wsl}' -maxdepth 1 \
    \( -name 'ae-test-title-*.txt' -o -name 'ae-test-json-*.json' \) \
    -exec rm -f {} + 2>/dev/null || true"

  info "Done. Your original VSCode profile has been restored."
}

# ── main ─────────────────────────────────────────────────────────────────────

main() {
  local cmd=""

  while [ $# -gt 0 ]; do
    case "$1" in
      -v)        _verbosity=1; shift ;;
      -vv)       _verbosity=2; shift ;;
      --help|-h) usage ;;
      -*) die "Error: Unknown option '${1}'. Run './ae-test-win.sh --help' for usage." ;;
      *)  cmd="${1}"; shift; break ;;
    esac
  done

  [ -n "${cmd}" ] || usage

  warn_deprecated
  check_dependencies
  [ "${_verbosity}" -ge 2 ] && set -x || true

  [ -n "${USERNAME:-}" ] \
    || die "Error: \$USERNAME is not set. Cannot determine Windows username."
  _win_user="${USERNAME}"
  _state_dir="/c/Users/${_win_user}/AppData/Local/ae-test"
  _state_file="${_state_dir}/state.txt"
  _win_code_user_dir="/c/Users/${_win_user}/AppData/Roaming/Code/User"
  _win_blank_dir="${_win_code_user_dir}.ae-test-blank"

  # Resolve WSL home explicitly — no ~ expansion ambiguity.
  # Single quotes intentional: prevents Git Bash from expanding $HOME before WSL sees it.
  # shellcheck disable=SC2016
  _wsl_home="$(wsl bash -c 'printf "%s" "$HOME"' 2>/dev/null)" \
    || die "Error: Could not resolve WSL home directory."
  [ -n "${_wsl_home}" ] \
    || die "Error: WSL home directory is empty. Is WSL configured correctly?"
  _wsl_ext_dir="${_wsl_home}/.vscode-server/extensions"
  _wsl_backup_dir="${_wsl_home}/.local/share/ae-test/backup-wsl"
  _wsl_blank_ext_dir="${_wsl_home}/.local/share/ae-test/blank-wsl-ext"

  dbg "Windows user:    ${_win_user}"
  dbg "state dir:       ${_state_dir}"
  dbg "win code/user:   ${_win_code_user_dir}"
  dbg "WSL home:        ${_wsl_home}"
  dbg "WSL ext dir:     ${_wsl_ext_dir}"
  dbg "WSL blank ext:   ${_wsl_blank_ext_dir}"
  dbg "command:         ${cmd}"

  case "${cmd}" in
    init)    cmd_init "$@" ;;
    select)  cmd_select "$@" ;;
    fetch)   cmd_fetch "$@" ;;
    cleanup) cmd_cleanup "$@" ;;
    *) die "Error: Unknown command '${cmd}'. Run './ae-test-win.sh --help' for usage." ;;
  esac
}

main "$@"