windowsweep 1.1.0 → 1.3.0

package/lib/ui.ps1

@@ -1,275 +1,275 @@
-# ui.ps1 - console output, glyphs, colours and prompts. ASCII only; glyphs come from [char] codes.
-# Every human-readable line goes through Write-UiLine so it is also logged and, in --json mode,
-# routed to stderr (stdout then carries only the JSON summary).
-
-function Initialize-Ui {
-  <# .SYNOPSIS Decide colour + glyph set from flags, environment and redirection state. #>
-  $ws = $Script:WS
-  $outRedirected = [Console]::IsOutputRedirected
-  $inRedirected = [Console]::IsInputRedirected
-  $noColorEnv = (-not [string]::IsNullOrEmpty($env:NO_COLOR)) -or ($env:WINDOWSWEEP_NO_COLOR -eq '1')
-  $ws.Color = (-not $ws.NoColor) -and (-not $noColorEnv) -and (-not $outRedirected) -and (-not $ws.JsonMode)
-  $ws.Interactive = (-not $inRedirected) -and (-not $ws.JsonMode)
-  $useUnicode = (-not $ws.Ascii) -and (-not $outRedirected) -and ($env:WINDOWSWEEP_ASCII -ne '1')
-  if ($useUnicode) {
-    $ws.Glyph = @{
-      ok = [string][char]0x2713; err = [string][char]0x2717; info = [string][char]0x2139; warn = '!'
-      bullet = [string][char]0x00B7; arrow = [string][char]0x2192; hline = [string][char]0x2500
-      dline = [string][char]0x2550; tl = [string][char]0x2554; tr = [string][char]0x2557
-      bl = [string][char]0x255A; br = [string][char]0x255D; vbar = [string][char]0x2551
-    }
-    try {
-      $ws.PrevOutputEncoding = [Console]::OutputEncoding
-      [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
-    } catch { $ws.PrevOutputEncoding = $null }
-  } else {
-    $ws.Glyph = @{ ok = '+'; err = 'x'; info = 'i'; warn = '!'; bullet = '*'; arrow = '->'; hline = '-'; dline = '='; tl = '+'; tr = '+'; bl = '+'; br = '+'; vbar = '|' }
-  }
-}
-
-function Restore-Ui {
-  <# .SYNOPSIS Put the console encoding back the way we found it. #>
-  $ws = $Script:WS
-  if ($ws.PrevOutputEncoding) { try { [Console]::OutputEncoding = $ws.PrevOutputEncoding } catch { $null = $_ } }
-}
-
-function Write-UiLine {
-  <# .SYNOPSIS Print one line (coloured when allowed) and append it to the log. #>
-  param([string] $Text = '', [string] $Color = 'Gray', [switch] $NoLog, [switch] $NoNewline)
-  $ws = $Script:WS
-  if (-not $NoLog) { Write-LogLine $Text }
-  if ($ws.Mute) { return }
-  if ($ws.JsonMode) { [Console]::Error.WriteLine($Text); return }
-  if ($ws.Color) {
-    if ($NoNewline) { Write-Host $Text -ForegroundColor $Color -NoNewline } else { Write-Host $Text -ForegroundColor $Color }
-  } else {
-    if ($NoNewline) { Write-Host $Text -NoNewline } else { Write-Host $Text }
-  }
-}
-
-function Write-Info {
-  param([string] $Text)
-  if ($Script:WS.Quiet) { Write-LogLine "INFO $Text"; return }
-  Write-UiLine ("$($Script:WS.Glyph.info) $Text") 'Cyan'
-}
-
-function Write-Ok {
-  param([string] $Text)
-  Write-UiLine ("$($Script:WS.Glyph.ok) $Text") 'Green'
-}
-
-function Write-Warn {
-  param([string] $Text)
-  Write-UiLine ("$($Script:WS.Glyph.warn) $Text") 'Yellow'
-}
-
-function Write-Err {
-  param([string] $Text)
-  Write-UiLine ("$($Script:WS.Glyph.err) $Text") 'Red'
-}
-
-function Write-Note {
-  param([string] $Text)
-  if ($Script:WS.Quiet) { Write-LogLine "NOTE $Text"; return }
-  Write-UiLine ("    $Text") 'DarkGray'
-}
-
-function Write-Plain {
-  param([string] $Text)
-  Write-UiLine $Text 'Gray'
-}
-
-function Write-DryRun {
-  param([string] $Text)
-  Write-UiLine ("    [dry-run] $Text") 'Magenta'
-}
-
-function Write-Section {
-  <# .SYNOPSIS A dashed section heading. #>
-  param([string] $Title)
-  $h = $Script:WS.Glyph.hline
-  Write-UiLine '' 'Gray'
-  Write-UiLine ("$h$h $Title $h$h") 'Blue'
-}
-
-function Write-Separator {
-  Write-UiLine ([string]::new([char]($Script:WS.Glyph.hline), 78)) 'DarkGray'
-}
-
-function Write-Box {
-  <# .SYNOPSIS Double-lined title box with an optional dim subtitle. #>
-  param([string] $Title, [string] $Subtitle = '')
-  $line = [string]::new([char]($Script:WS.Glyph.dline), 78)
-  Write-UiLine '' 'Gray'
-  Write-UiLine $line 'Blue'
-  Write-UiLine ("   $Title") 'Blue'
-  if ($Subtitle) { Write-UiLine ("   $Subtitle") 'DarkGray' }
-  Write-UiLine $line 'Blue'
-}
-
-function Write-Step {
-  <# .SYNOPSIS Walkthrough step header: [ STEP n/N ]  Title #>
-  param([int] $N, [int] $Total, [string] $Title)
-  Write-UiLine '' 'Gray'
-  Write-Separator
-  Write-UiLine ("  [ STEP $N/$Total ]  $Title") 'Cyan'
-  Write-Separator
-}
-
-function Write-Kv {
-  param([string] $Key, [string] $Value)
-  Write-UiLine ("  {0,-24} {1}" -f $Key, $Value) 'Gray'
-}
-
-function Write-Banner {
-  $g = $Script:WS.Glyph
-  $inner = "   $Script:WS_NAME v$(Get-ToolVersion) - safe, developer-aware Windows cleanup   "
-  $bar = [string]::new([char]($g.dline), $inner.Length)
-  Write-UiLine ("$($g.tl)$bar$($g.tr)") 'Blue'
-  Write-UiLine ("$($g.vbar)$inner$($g.vbar)") 'Blue'
-  Write-UiLine ("$($g.bl)$bar$($g.br)") 'Blue'
-}
-
-function Format-Bytes {
-  <# .SYNOPSIS Human-readable size (B, KB, MB, GB, TB). #>
-  param([double] $Bytes)
-  if ($Bytes -lt 0) { $Bytes = 0 }
-  $units = @('B', 'KB', 'MB', 'GB', 'TB')
-  $i = 0
-  while ($Bytes -ge 1024 -and $i -lt ($units.Length - 1)) { $Bytes = $Bytes / 1024; $i++ }
-  if ($i -eq 0) { return ("{0:N0} {1}" -f $Bytes, $units[$i]) }
-  return ("{0:N1} {1}" -f $Bytes, $units[$i])
-}
-
-function Format-Duration {
-  param([double] $Seconds)
-  $m = [math]::Floor($Seconds / 60); $s = [math]::Floor($Seconds % 60)
-  return ("{0}m {1:00}s" -f $m, $s)
-}
-
-function Read-Line {
-  <# .SYNOPSIS Read one line from the console, or $null when not interactive / at EOF. #>
-  param([string] $Prompt = '')
-  if (-not $Script:WS.Interactive) { return $null }
-  if ($Prompt) { Write-UiLine $Prompt 'White' -NoNewline -NoLog }
-  try { $line = [Console]::In.ReadLine() } catch { return $null }
-  if ($null -eq $line) { return $null }
-  Write-LogLine ("> $line")
-  return $line
-}
-
-function Confirm-Ui {
-  <# .SYNOPSIS y/N prompt. --yes auto-confirms (unless -NoAutoYes); non-interactive runs answer no.
-     -ScriptedOk: the prompt that follows an explicit --select / --select-file choice. The selection IS the
-     person's decision, so it answers this one question - and only when the preceding prompt really was
-     answered from a script (LastSelectionScripted), never merely because the flag was passed. #>
-  param([string] $Prompt = 'Proceed?', [string] $Default = 'n', [switch] $NoAutoYes, [switch] $ScriptedOk)
-  $ws = $Script:WS
-  if ($ScriptedOk -and $ws.LastSelectionScripted) { Write-Warn "[scripted selection] $Prompt - yes (--select / --select-file)"; return $true }
-  if ($ws.Yes -and -not $NoAutoYes) { Write-UiLine ("    [auto-yes] $Prompt") 'DarkGray'; return $true }
-  if (-not $ws.Interactive) {
-    Write-Note "non-interactive session: '$Prompt' answered no (pass --yes to confirm in batch)"
-    return $false
-  }
-  $hint = '[y/N]'
-  if ($Default -eq 'y') { $hint = '[Y/n]' }
-  $reply = Read-Line ("? $Prompt $hint ")
-  if ($null -eq $reply) { return $false }
-  $reply = $reply.Trim()
-  if ($reply -eq '') { $reply = $Default }
-  return ($reply -match '^(y|yes)$')
-}
-
-function Confirm-Typed {
-  <# .SYNOPSIS Critical confirmation: the user must type the literal word. Never auto-answered. #>
-  param([string] $Prompt, [string] $Word = 'yes')
-  if (-not $Script:WS.Interactive) { Write-Note "non-interactive session: '$Prompt' requires a typed '$Word'; skipped"; return $false }
-  Write-Warn $Prompt
-  $reply = Read-Line ("  Type '$Word' to proceed: ")
-  if ($null -eq $reply) { return $false }
-  return ($reply.Trim() -eq $Word)
-}
-
-function Read-MultiSelect {
-  <# .SYNOPSIS Parse "1,3,5-7" / all / none into a sorted unique list of 1-based indexes.
-     Order of answers: a --select-file path list matched against -Candidates, then the next queued --select
-     list, then --yes (only for callers that do not pass -NoAutoYes), then the console, then nothing.
-     --yes NEVER selects for the personal and project pickers: they pass -NoAutoYes, so under --yes they
-     still ask when a console is present and select nothing when it is not. #>
-  param([int] $Total, [switch] $NoAutoYes, [string[]] $Candidates = @())
-  $ws = $Script:WS
-  $ws.LastSelectionScripted = $false
-  if ($Total -le 0) { return @() }
-  if ($ws.SelectPaths.Count -gt 0 -and $Candidates.Count -gt 0) {
-    $picked = @(Resolve-SelectedPaths -Candidates $Candidates)
-    $ws.LastSelectionScripted = $true
-    Write-Info ("--select-file matched $($picked.Count) of $Total candidate(s)")
-    return $picked
-  }
-  if ($ws.SelectQueue.Count -gt 0) {
-    $spec = [string]$ws.SelectQueue[0]
-    $ws.SelectQueue = @($ws.SelectQueue | Select-Object -Skip 1)
-    $picked = @(ConvertTo-IndexList -Text $spec -Total $Total)
-    $ws.LastSelectionScripted = $true
-    Write-Info ("--select '$spec' -> $($picked.Count) of $Total item(s)")
-    return $picked
-  }
-  if ($ws.Yes -and -not $NoAutoYes) { return @(1..$Total) }
-  if (-not $ws.Interactive) { Write-Note 'non-interactive session: nothing selected (a person has to pick these)'; return @() }
-  Write-UiLine "  Selection: 1,3,5-10 | all | none (Enter = none)" 'DarkGray' -NoLog
-  $reply = Read-Line ("  Select items (1..$Total): ")
-  return (ConvertTo-IndexList -Text $reply -Total $Total)
-}
-
-function Resolve-SelectedPaths {
-  <# .SYNOPSIS Match the --select-file lines against this prompt's candidate paths, case-insensitively.
-     Returns 1-based indexes into $Candidates. A line matching nothing here is reported once and skipped:
-     the same file is offered to every prompt, so an unmatched line is normal and never fatal. #>
-  param([string[]] $Candidates)
-  $set = New-Object System.Collections.Generic.SortedSet[int]
-  $matched = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
-  for ($i = 0; $i -lt $Candidates.Count; $i++) {
-    foreach ($want in $Script:WS.SelectPaths) {
-      if ([string]$Candidates[$i] -eq $want) { $null = $set.Add($i + 1); $null = $matched.Add($want) }
-    }
-  }
-  foreach ($want in $Script:WS.SelectPaths) {
-    if (-not $matched.Contains($want)) { Write-Note "--select-file: no candidate here matches $want" }
-  }
-  return @($set)
-}
-
-function ConvertTo-IndexList {
-  <# .SYNOPSIS Pure parser behind Read-MultiSelect (kept separate so the self-test can exercise it). #>
-  param([string] $Text, [int] $Total)
-  if ([string]::IsNullOrWhiteSpace($Text)) { return @() }
-  $t = $Text.Trim().ToLowerInvariant()
-  if ($t -in @('n', 'none')) { return @() }
-  if ($t -in @('a', 'all')) { return @(1..$Total) }
-  $set = New-Object System.Collections.Generic.SortedSet[int]
-  foreach ($part in ($t -split ',')) {
-    $part = $part.Trim()
-    if ($part -match '^(\d+)-(\d+)$') {
-      $a = [int]$Matches[1]; $b = [int]$Matches[2]
-      if ($a -gt $b) { $tmp = $a; $a = $b; $b = $tmp }
-      for ($i = $a; $i -le $b; $i++) { if ($i -ge 1 -and $i -le $Total) { $null = $set.Add($i) } }
-    } elseif ($part -match '^\d+$') {
-      $i = [int]$part
-      if ($i -ge 1 -and $i -le $Total) { $null = $set.Add($i) }
-    }
-  }
-  return @($set)
-}
-
-function Read-Choice {
-  <# .SYNOPSIS One-key choice; returns the lower-cased key or the default. #>
-  param([string] $Prompt, [string] $Default = '')
-  $reply = Read-Line $Prompt
-  if ($null -eq $reply -or $reply.Trim() -eq '') { return $Default }
-  return $reply.Trim().ToLowerInvariant()
-}
-
-function Wait-Enter {
-  if (-not $Script:WS.Interactive) { return }
-  $null = Read-Line "  - press Enter to continue - "
-}
+# ui.ps1 - console output, glyphs, colours and prompts. ASCII only; glyphs come from [char] codes.
+# Every human-readable line goes through Write-UiLine so it is also logged and, in --json mode,
+# routed to stderr (stdout then carries only the JSON summary).
+
+function Initialize-Ui {
+  <# .SYNOPSIS Decide colour + glyph set from flags, environment and redirection state. #>
+  $ws = $Script:WS
+  $outRedirected = [Console]::IsOutputRedirected
+  $inRedirected = [Console]::IsInputRedirected
+  $noColorEnv = (-not [string]::IsNullOrEmpty($env:NO_COLOR)) -or ($env:WINDOWSWEEP_NO_COLOR -eq '1')
+  $ws.Color = (-not $ws.NoColor) -and (-not $noColorEnv) -and (-not $outRedirected) -and (-not $ws.JsonMode)
+  $ws.Interactive = (-not $inRedirected) -and (-not $ws.JsonMode)
+  $useUnicode = (-not $ws.Ascii) -and (-not $outRedirected) -and ($env:WINDOWSWEEP_ASCII -ne '1')
+  if ($useUnicode) {
+    $ws.Glyph = @{
+      ok = [string][char]0x2713; err = [string][char]0x2717; info = [string][char]0x2139; warn = '!'
+      bullet = [string][char]0x00B7; arrow = [string][char]0x2192; hline = [string][char]0x2500
+      dline = [string][char]0x2550; tl = [string][char]0x2554; tr = [string][char]0x2557
+      bl = [string][char]0x255A; br = [string][char]0x255D; vbar = [string][char]0x2551
+    }
+    try {
+      $ws.PrevOutputEncoding = [Console]::OutputEncoding
+      [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+    } catch { $ws.PrevOutputEncoding = $null }
+  } else {
+    $ws.Glyph = @{ ok = '+'; err = 'x'; info = 'i'; warn = '!'; bullet = '*'; arrow = '->'; hline = '-'; dline = '='; tl = '+'; tr = '+'; bl = '+'; br = '+'; vbar = '|' }
+  }
+}
+
+function Restore-Ui {
+  <# .SYNOPSIS Put the console encoding back the way we found it. #>
+  $ws = $Script:WS
+  if ($ws.PrevOutputEncoding) { try { [Console]::OutputEncoding = $ws.PrevOutputEncoding } catch { $null = $_ } }
+}
+
+function Write-UiLine {
+  <# .SYNOPSIS Print one line (coloured when allowed) and append it to the log. #>
+  param([string] $Text = '', [string] $Color = 'Gray', [switch] $NoLog, [switch] $NoNewline)
+  $ws = $Script:WS
+  if (-not $NoLog) { Write-LogLine $Text }
+  if ($ws.Mute) { return }
+  if ($ws.JsonMode) { [Console]::Error.WriteLine($Text); return }
+  if ($ws.Color) {
+    if ($NoNewline) { Write-Host $Text -ForegroundColor $Color -NoNewline } else { Write-Host $Text -ForegroundColor $Color }
+  } else {
+    if ($NoNewline) { Write-Host $Text -NoNewline } else { Write-Host $Text }
+  }
+}
+
+function Write-Info {
+  param([string] $Text)
+  if ($Script:WS.Quiet) { Write-LogLine "INFO $Text"; return }
+  Write-UiLine ("$($Script:WS.Glyph.info) $Text") 'Cyan'
+}
+
+function Write-Ok {
+  param([string] $Text)
+  Write-UiLine ("$($Script:WS.Glyph.ok) $Text") 'Green'
+}
+
+function Write-Warn {
+  param([string] $Text)
+  Write-UiLine ("$($Script:WS.Glyph.warn) $Text") 'Yellow'
+}
+
+function Write-Err {
+  param([string] $Text)
+  Write-UiLine ("$($Script:WS.Glyph.err) $Text") 'Red'
+}
+
+function Write-Note {
+  param([string] $Text)
+  if ($Script:WS.Quiet) { Write-LogLine "NOTE $Text"; return }
+  Write-UiLine ("    $Text") 'DarkGray'
+}
+
+function Write-Plain {
+  param([string] $Text)
+  Write-UiLine $Text 'Gray'
+}
+
+function Write-DryRun {
+  param([string] $Text)
+  Write-UiLine ("    [dry-run] $Text") 'Magenta'
+}
+
+function Write-Section {
+  <# .SYNOPSIS A dashed section heading. #>
+  param([string] $Title)
+  $h = $Script:WS.Glyph.hline
+  Write-UiLine '' 'Gray'
+  Write-UiLine ("$h$h $Title $h$h") 'Blue'
+}
+
+function Write-Separator {
+  Write-UiLine ([string]::new([char]($Script:WS.Glyph.hline), 78)) 'DarkGray'
+}
+
+function Write-Box {
+  <# .SYNOPSIS Double-lined title box with an optional dim subtitle. #>
+  param([string] $Title, [string] $Subtitle = '')
+  $line = [string]::new([char]($Script:WS.Glyph.dline), 78)
+  Write-UiLine '' 'Gray'
+  Write-UiLine $line 'Blue'
+  Write-UiLine ("   $Title") 'Blue'
+  if ($Subtitle) { Write-UiLine ("   $Subtitle") 'DarkGray' }
+  Write-UiLine $line 'Blue'
+}
+
+function Write-Step {
+  <# .SYNOPSIS Walkthrough step header: [ STEP n/N ]  Title #>
+  param([int] $N, [int] $Total, [string] $Title)
+  Write-UiLine '' 'Gray'
+  Write-Separator
+  Write-UiLine ("  [ STEP $N/$Total ]  $Title") 'Cyan'
+  Write-Separator
+}
+
+function Write-Kv {
+  param([string] $Key, [string] $Value)
+  Write-UiLine ("  {0,-24} {1}" -f $Key, $Value) 'Gray'
+}
+
+function Write-Banner {
+  $g = $Script:WS.Glyph
+  $inner = "   $Script:WS_NAME v$(Get-ToolVersion) - names every path before it touches one   "
+  $bar = [string]::new([char]($g.dline), $inner.Length)
+  Write-UiLine ("$($g.tl)$bar$($g.tr)") 'Blue'
+  Write-UiLine ("$($g.vbar)$inner$($g.vbar)") 'Blue'
+  Write-UiLine ("$($g.bl)$bar$($g.br)") 'Blue'
+}
+
+function Format-Bytes {
+  <# .SYNOPSIS Human-readable size (B, KB, MB, GB, TB). #>
+  param([double] $Bytes)
+  if ($Bytes -lt 0) { $Bytes = 0 }
+  $units = @('B', 'KB', 'MB', 'GB', 'TB')
+  $i = 0
+  while ($Bytes -ge 1024 -and $i -lt ($units.Length - 1)) { $Bytes = $Bytes / 1024; $i++ }
+  if ($i -eq 0) { return ("{0:N0} {1}" -f $Bytes, $units[$i]) }
+  return ("{0:N1} {1}" -f $Bytes, $units[$i])
+}
+
+function Format-Duration {
+  param([double] $Seconds)
+  $m = [math]::Floor($Seconds / 60); $s = [math]::Floor($Seconds % 60)
+  return ("{0}m {1:00}s" -f $m, $s)
+}
+
+function Read-Line {
+  <# .SYNOPSIS Read one line from the console, or $null when not interactive / at EOF. #>
+  param([string] $Prompt = '')
+  if (-not $Script:WS.Interactive) { return $null }
+  if ($Prompt) { Write-UiLine $Prompt 'White' -NoNewline -NoLog }
+  try { $line = [Console]::In.ReadLine() } catch { return $null }
+  if ($null -eq $line) { return $null }
+  Write-LogLine ("> $line")
+  return $line
+}
+
+function Confirm-Ui {
+  <# .SYNOPSIS y/N prompt. --yes auto-confirms (unless -NoAutoYes); non-interactive runs answer no.
+     -ScriptedOk: the prompt that follows an explicit --select / --select-file choice. The selection IS the
+     person's decision, so it answers this one question - and only when the preceding prompt really was
+     answered from a script (LastSelectionScripted), never merely because the flag was passed. #>
+  param([string] $Prompt = 'Proceed?', [string] $Default = 'n', [switch] $NoAutoYes, [switch] $ScriptedOk)
+  $ws = $Script:WS
+  if ($ScriptedOk -and $ws.LastSelectionScripted) { Write-Warn "[scripted selection] $Prompt - yes (--select / --select-file)"; return $true }
+  if ($ws.Yes -and -not $NoAutoYes) { Write-UiLine ("    [auto-yes] $Prompt") 'DarkGray'; return $true }
+  if (-not $ws.Interactive) {
+    Write-Note "non-interactive session: '$Prompt' answered no (pass --yes to confirm in batch)"
+    return $false
+  }
+  $hint = '[y/N]'
+  if ($Default -eq 'y') { $hint = '[Y/n]' }
+  $reply = Read-Line ("? $Prompt $hint ")
+  if ($null -eq $reply) { return $false }
+  $reply = $reply.Trim()
+  if ($reply -eq '') { $reply = $Default }
+  return ($reply -match '^(y|yes)$')
+}
+
+function Confirm-Typed {
+  <# .SYNOPSIS Critical confirmation: the user must type the literal word. Never auto-answered. #>
+  param([string] $Prompt, [string] $Word = 'yes')
+  if (-not $Script:WS.Interactive) { Write-Note "non-interactive session: '$Prompt' requires a typed '$Word'; skipped"; return $false }
+  Write-Warn $Prompt
+  $reply = Read-Line ("  Type '$Word' to proceed: ")
+  if ($null -eq $reply) { return $false }
+  return ($reply.Trim() -eq $Word)
+}
+
+function Read-MultiSelect {
+  <# .SYNOPSIS Parse "1,3,5-7" / all / none into a sorted unique list of 1-based indexes.
+     Order of answers: a --select-file path list matched against -Candidates, then the next queued --select
+     list, then --yes (only for callers that do not pass -NoAutoYes), then the console, then nothing.
+     --yes NEVER selects for the personal and project pickers: they pass -NoAutoYes, so under --yes they
+     still ask when a console is present and select nothing when it is not. #>
+  param([int] $Total, [switch] $NoAutoYes, [string[]] $Candidates = @())
+  $ws = $Script:WS
+  $ws.LastSelectionScripted = $false
+  if ($Total -le 0) { return @() }
+  if ($ws.SelectPaths.Count -gt 0 -and $Candidates.Count -gt 0) {
+    $picked = @(Resolve-SelectedPaths -Candidates $Candidates)
+    $ws.LastSelectionScripted = $true
+    Write-Info ("--select-file matched $($picked.Count) of $Total candidate(s)")
+    return $picked
+  }
+  if ($ws.SelectQueue.Count -gt 0) {
+    $spec = [string]$ws.SelectQueue[0]
+    $ws.SelectQueue = @($ws.SelectQueue | Select-Object -Skip 1)
+    $picked = @(ConvertTo-IndexList -Text $spec -Total $Total)
+    $ws.LastSelectionScripted = $true
+    Write-Info ("--select '$spec' -> $($picked.Count) of $Total item(s)")
+    return $picked
+  }
+  if ($ws.Yes -and -not $NoAutoYes) { return @(1..$Total) }
+  if (-not $ws.Interactive) { Write-Note 'non-interactive session: nothing selected (a person has to pick these)'; return @() }
+  Write-UiLine "  Selection: 1,3,5-10 | all | none (Enter = none)" 'DarkGray' -NoLog
+  $reply = Read-Line ("  Select items (1..$Total): ")
+  return (ConvertTo-IndexList -Text $reply -Total $Total)
+}
+
+function Resolve-SelectedPaths {
+  <# .SYNOPSIS Match the --select-file lines against this prompt's candidate paths, case-insensitively.
+     Returns 1-based indexes into $Candidates. A line matching nothing here is reported once and skipped:
+     the same file is offered to every prompt, so an unmatched line is normal and never fatal. #>
+  param([string[]] $Candidates)
+  $set = New-Object System.Collections.Generic.SortedSet[int]
+  $matched = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  for ($i = 0; $i -lt $Candidates.Count; $i++) {
+    foreach ($want in $Script:WS.SelectPaths) {
+      if ([string]$Candidates[$i] -eq $want) { $null = $set.Add($i + 1); $null = $matched.Add($want) }
+    }
+  }
+  foreach ($want in $Script:WS.SelectPaths) {
+    if (-not $matched.Contains($want)) { Write-Note "--select-file: no candidate here matches $want" }
+  }
+  return @($set)
+}
+
+function ConvertTo-IndexList {
+  <# .SYNOPSIS Pure parser behind Read-MultiSelect (kept separate so the self-test can exercise it). #>
+  param([string] $Text, [int] $Total)
+  if ([string]::IsNullOrWhiteSpace($Text)) { return @() }
+  $t = $Text.Trim().ToLowerInvariant()
+  if ($t -in @('n', 'none')) { return @() }
+  if ($t -in @('a', 'all')) { return @(1..$Total) }
+  $set = New-Object System.Collections.Generic.SortedSet[int]
+  foreach ($part in ($t -split ',')) {
+    $part = $part.Trim()
+    if ($part -match '^(\d+)-(\d+)$') {
+      $a = [int]$Matches[1]; $b = [int]$Matches[2]
+      if ($a -gt $b) { $tmp = $a; $a = $b; $b = $tmp }
+      for ($i = $a; $i -le $b; $i++) { if ($i -ge 1 -and $i -le $Total) { $null = $set.Add($i) } }
+    } elseif ($part -match '^\d+$') {
+      $i = [int]$part
+      if ($i -ge 1 -and $i -le $Total) { $null = $set.Add($i) }
+    }
+  }
+  return @($set)
+}
+
+function Read-Choice {
+  <# .SYNOPSIS One-key choice; returns the lower-cased key or the default. #>
+  param([string] $Prompt, [string] $Default = '')
+  $reply = Read-Line $Prompt
+  if ($null -eq $reply -or $reply.Trim() -eq '') { return $Default }
+  return $reply.Trim().ToLowerInvariant()
+}
+
+function Wait-Enter {
+  if (-not $Script:WS.Interactive) { return }
+  $null = Read-Line "  - press Enter to continue - "
+}

package/modules/android_avd.ps1

@@ -1,36 +1,36 @@
-# android_avd.ps1 - section 4: Android emulators (AVDs). Slow to recreate, so per-AVD idle gate and never in --all.
-
-function Get-Targets04 {
-  return @((New-Target 4 'Android AVDs (each .avd + .ini pair)' "$($Script:P.U)\.android\avd" -Mode units -Dev $true -Note "an AVD goes only when nothing inside it changed for $($Script:WS.Days)+ days"))
-}
-
-function Invoke-Section04 {
-  $ws = $Script:WS
-  $root = Join-Path $Script:P.U '.android\avd'
-  Write-SectionIntro @(
-    'An emulator image is 5-15 GB and takes minutes to recreate. Each AVD is one unit: it is removed only when',
-    "every file inside it has been idle for $($ws.Days)+ days (booting an emulator updates its files)."
-  ) -Dev $true
-  if (-not (Test-DirPresent $root)) { Write-Info 'no AVDs found'; return }
-  if (Test-ProcessRunning @('qemu-system-x86_64', 'emulator', 'emulator64-crash-service')) { Write-Warn 'an Android emulator is running - section skipped'; return }
-  $avds = @()
-  foreach ($e in (Get-ChildEntries $root)) {
-    if (-not ($e -is [IO.DirectoryInfo]) -or $e.Name -notlike '*.avd') { continue }
-    $full = Remove-LongPrefix $e.FullName
-    $avds += [pscustomobject]@{ Name = $e.Name; Path = $full; Ini = (Join-Path $root ($e.Name -replace '\.avd$', '.ini')); Idle = (Get-IdleDays $full); Bytes = (Get-DirectoryBytes $full) }
-  }
-  if ($avds.Count -eq 0) { Write-Info 'no AVDs found'; return }
-  Write-UiLine ("  {0,-36} {1,10} {2,8}" -f 'AVD', 'SIZE', 'IDLE') 'White'
-  foreach ($a in $avds) { Write-UiLine ("  {0,-36} {1,10} {2,7}d" -f $a.Name, (Format-Bytes $a.Bytes), $a.Idle) 'Gray' }
-  $avds = @($avds)
-  $stale = @($avds | Where-Object { $_.Idle -ge $ws.Days -or $ws.PurgeAll })
-  if ($stale.Count -eq 0) { Write-Info "every AVD was used within the last $($ws.Days) days - nothing to prune"; return }
-  if (-not (Confirm-Section "Remove $($stale.Count) idle AVD(s)?" 'n')) { Write-Info 'skipped'; return }
-  foreach ($a in $stale) {
-    $r = Remove-PathSafe -Path $a.Path -Within $root -Label $a.Name
-    if ($r.Removed) {
-      if (Test-PathPresent $a.Ini) { $null = Remove-PathSafe -Path $a.Ini -Within $root -Label "$($a.Name) ini" }
-      if (-not $ws.DryRun) { Write-Ok ("removed AVD $($a.Name) ($($a.Idle)d idle, " + (Format-Bytes $r.Bytes) + ')') }
-    }
-  }
-}
+# android_avd.ps1 - section 4: Android emulators (AVDs). Slow to recreate, so per-AVD idle gate and never in --all.
+
+function Get-Targets04 {
+  return @((New-Target 4 'Android AVDs (each .avd + .ini pair)' "$($Script:P.U)\.android\avd" -Mode units -Dev $true -Note "an AVD goes only when nothing inside it changed for $($Script:WS.Days)+ days"))
+}
+
+function Invoke-Section04 {
+  $ws = $Script:WS
+  $root = Join-Path $Script:P.U '.android\avd'
+  Write-SectionIntro @(
+    'An emulator image is 5-15 GB and takes minutes to recreate. Each AVD is one unit: it is removed only when',
+    "every file inside it has been idle for $($ws.Days)+ days (booting an emulator updates its files)."
+  ) -Dev $true
+  if (-not (Test-DirPresent $root)) { Write-Info 'no AVDs found'; return }
+  if (Test-ProcessRunning @('qemu-system-x86_64', 'emulator', 'emulator64-crash-service')) { Write-Warn 'an Android emulator is running - section skipped'; return }
+  $avds = @()
+  foreach ($e in (Get-ChildEntries $root)) {
+    if (-not ($e -is [IO.DirectoryInfo]) -or $e.Name -notlike '*.avd') { continue }
+    $full = Remove-LongPrefix $e.FullName
+    $avds += [pscustomobject]@{ Name = $e.Name; Path = $full; Ini = (Join-Path $root ($e.Name -replace '\.avd$', '.ini')); Idle = (Get-IdleDays $full); Bytes = (Get-DirectoryBytes $full) }
+  }
+  if ($avds.Count -eq 0) { Write-Info 'no AVDs found'; return }
+  Write-UiLine ("  {0,-36} {1,10} {2,8}" -f 'AVD', 'SIZE', 'IDLE') 'White'
+  foreach ($a in $avds) { Write-UiLine ("  {0,-36} {1,10} {2,7}d" -f $a.Name, (Format-Bytes $a.Bytes), $a.Idle) 'Gray' }
+  $avds = @($avds)
+  $stale = @($avds | Where-Object { $_.Idle -ge $ws.Days -or $ws.PurgeAll })
+  if ($stale.Count -eq 0) { Write-Info "every AVD was used within the last $($ws.Days) days - nothing to prune"; return }
+  if (-not (Confirm-Section "Remove $($stale.Count) idle AVD(s)?" 'n')) { Write-Info 'skipped'; return }
+  foreach ($a in $stale) {
+    $r = Remove-PathSafe -Path $a.Path -Within $root -Label $a.Name
+    if ($r.Removed) {
+      if (Test-PathPresent $a.Ini) { $null = Remove-PathSafe -Path $a.Ini -Within $root -Label "$($a.Name) ini" }
+      if (-not $ws.DryRun) { Write-Ok ("removed AVD $($a.Name) ($($a.Idle)d idle, " + (Format-Bytes $r.Bytes) + ')') }
+    }
+  }
+}