windowsweep 1.0.1 → 1.1.0

package/modules/globals_audit.ps1

@@ -0,0 +1,236 @@
+# globals_audit.ps1 - section 22: globally installed packages, read-only.
+# Lists what npm, pnpm, yarn, bun and deno installed globally, flags the ones nothing has referenced for
+# N+ days, and prints the exact uninstall command. It NEVER removes anything, in any mode: several of these
+# roots (nvm4w, AppData\npm, pnpm\global, .bun, .deno\bin) are protected subtrees by design.
+
+# Never proposed as a candidate: the tool itself and the package managers everything else depends on.
+$Script:WS_GLOBAL_KEEP = @('npm', 'corepack', 'pnpm', 'yarn', 'windowsweep')
+
+function Get-GlobalPackageRoots {
+  <# .SYNOPSIS Existing global install roots, one row per manager. Style: node_modules (packages) | bin (shims). #>
+  $P = $Script:P
+  $rows = @()
+  $npmRoot = ''
+  if (Test-CommandPresent 'npm') {
+    try {
+      $out = & npm root -g 2>$null
+      $line = ($out | Select-Object -Last 1)
+      if ($line) { $npmRoot = $line.Trim() }
+    } catch { $null = $_ }
+  }
+  if (-not $npmRoot) { $npmRoot = Join-Path $P.A 'npm\node_modules' }
+  $fixed = @(
+    @('npm', $npmRoot, 'node_modules'),
+    @('yarn', "$($P.L)\Yarn\Data\global\node_modules", 'node_modules'),
+    @('bun', "$($P.U)\.bun\install\global\node_modules", 'node_modules'),
+    @('deno', "$($P.U)\.deno\bin", 'bin')
+  )
+  foreach ($f in $fixed) {
+    if (Test-DirPresent $f[1]) { $rows += [pscustomobject]@{ Manager = $f[0]; Root = (Get-FullPath $f[1]); Style = $f[2] } }
+  }
+  # Version-managed and store-style roots are globs: one root per installed Node version / pnpm version.
+  $globs = @()
+  $globs += @(@('npm', "$($P.A)\nvm\v*\node_modules"))
+  if ($env:NVM_HOME) { $globs += @(@('npm', (Join-Path $env:NVM_HOME 'v*\node_modules'))) }
+  $globs += @(@('pnpm', "$($P.L)\pnpm\global\*\node_modules"))
+  foreach ($g in $globs) {
+    $hits = @()
+    try { $hits = @(Get-Item -Path $g[1] -Force -ErrorAction SilentlyContinue | Where-Object { $_ -is [IO.DirectoryInfo] } | ForEach-Object { $_.FullName }) } catch { $hits = @() }
+    foreach ($h in $hits) { $rows += [pscustomobject]@{ Manager = $g[0]; Root = (Get-FullPath $h); Style = 'node_modules' } }
+  }
+  $seen = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  return @($rows | Where-Object { $seen.Add($_.Root) })
+}
+
+function Get-PackageBinNames {
+  <# .SYNOPSIS Command names a package.json 'bin' field installs: a string means one bin named after the package. #>
+  param([object] $Manifest, [string] $Name)
+  $out = @()
+  if ($null -eq $Manifest) { return $out }
+  $bin = $Manifest.bin
+  if ($null -eq $bin) { return $out }
+  if ($bin -is [string]) { return @(($Name -split '/')[-1]) }
+  foreach ($p in $bin.PSObject.Properties) { $out += $p.Name }
+  return $out
+}
+
+function Get-GlobalPackages {
+  <# .SYNOPSIS Packages under one global root. Reads each package.json (top level only) - never walks a global tree. #>
+  param([pscustomobject] $RootRow)
+  $rows = @()
+  if ($RootRow.Style -eq 'bin') {
+    foreach ($e in (Get-ChildEntries $RootRow.Root)) {
+      if ($e -is [IO.DirectoryInfo]) { continue }
+      if ($e.Extension -eq '.cmd') { continue }
+      $idle = [int][math]::Floor(([datetime]::UtcNow - (Get-NewestTimestampUtc $e)).TotalDays)
+      $rows += [pscustomobject]@{ Manager = $RootRow.Manager; Name = [IO.Path]::GetFileNameWithoutExtension($e.Name)
+        Version = ''; Path = (Remove-LongPrefix $e.FullName); Bytes = [long]$e.Length; Idle = $idle
+        Bins = @([IO.Path]::GetFileNameWithoutExtension($e.Name)) }
+    }
+    return $rows
+  }
+  $dirs = @()
+  foreach ($e in (Get-ChildEntries $RootRow.Root)) {
+    if (-not ($e -is [IO.DirectoryInfo]) -or (Test-ReparsePoint $e)) { continue }
+    if ($e.Name -eq '.bin') { continue }
+    if ($e.Name.StartsWith('@')) {
+      foreach ($s in (Get-ChildEntries (Remove-LongPrefix $e.FullName))) {
+        if ($s -is [IO.DirectoryInfo]) { $dirs += [pscustomobject]@{ Name = ($e.Name + '/' + $s.Name); Dir = (Remove-LongPrefix $s.FullName) } }
+      }
+      continue
+    }
+    $dirs += [pscustomobject]@{ Name = $e.Name; Dir = (Remove-LongPrefix $e.FullName) }
+  }
+  foreach ($d in $dirs) {
+    $manifest = $null
+    $mf = Join-Path $d.Dir 'package.json'
+    if (Test-PathPresent $mf) { try { $manifest = @(Read-JsonFile $mf)[0] } catch { $manifest = $null } }
+    $version = ''
+    if ($manifest -and $manifest.version) { $version = [string]$manifest.version }
+    # The newest of the package's own top-level entries: a global node_modules is far too big to walk.
+    $newest = [datetime]::MinValue
+    foreach ($c in (Get-ChildEntries $d.Dir)) { $t = Get-NewestTimestampUtc $c; if ($t -gt $newest) { $newest = $t } }
+    if ($newest -eq [datetime]::MinValue) { $newest = [datetime]::UtcNow }
+    $rows += [pscustomobject]@{ Manager = $RootRow.Manager; Name = $d.Name; Version = $version; Path = $d.Dir
+      Bytes = [long](Get-DirectoryBytes $d.Dir); Idle = [int][math]::Floor(([datetime]::UtcNow - $newest).TotalDays)
+      Bins = @(Get-PackageBinNames -Manifest $manifest -Name $d.Name) }
+  }
+  return $rows
+}
+
+function Get-ProjectPackageIndex {
+  <# .SYNOPSIS What the project roots reference: dependency names, script text and local .bin command names.
+     Only manifests touched inside the idle window count - an ancient project does not keep a global alive. #>
+  param([string[]] $Roots, [int] $Days, [int] $MaxDepth = 4, [int] $MaxFiles = 2000)
+  $names = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  $bins = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  $script = New-Object System.Text.StringBuilder
+  $seen = 0
+  foreach ($root in $Roots) {
+    $stack = New-Object System.Collections.Generic.Stack[object]
+    $stack.Push(@($root, 0))
+    while ($stack.Count -gt 0 -and $seen -lt $MaxFiles) {
+      $item = $stack.Pop()
+      $dir = [string]$item[0]; $depth = [int]$item[1]
+      foreach ($e in (Get-ChildEntries $dir)) {
+        if (Test-ReparsePoint $e) { continue }
+        if ($e -is [IO.DirectoryInfo]) {
+          if ($e.Name -eq 'node_modules') {
+            foreach ($b in (Get-ChildEntries (Join-Path (Remove-LongPrefix $e.FullName) '.bin'))) { $null = $bins.Add([IO.Path]::GetFileNameWithoutExtension($b.Name)) }
+            continue
+          }
+          if ($Script:WS_NEVER_ENTER -contains $e.Name -or $e.Name.StartsWith('.')) { continue }
+          if ($depth -lt $MaxDepth) { $stack.Push(@((Remove-LongPrefix $e.FullName), $depth + 1)) }
+          continue
+        }
+        if ($e.Name -ne 'package.json') { continue }
+        $seen++
+        if ([int][math]::Floor(([datetime]::UtcNow - (Get-NewestTimestampUtc $e)).TotalDays) -ge $Days) { continue }
+        $m = $null
+        try { $m = @(Read-JsonFile (Remove-LongPrefix $e.FullName))[0] } catch { $m = $null }
+        if ($null -eq $m) { continue }
+        foreach ($field in @('dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies')) {
+          if ($m.$field) { foreach ($p in $m.$field.PSObject.Properties) { $null = $names.Add($p.Name) } }
+        }
+        if ($m.scripts -and $script.Length -lt 200000) {
+          foreach ($p in $m.scripts.PSObject.Properties) { $null = $script.Append(' ').Append([string]$p.Value) }
+        }
+      }
+    }
+  }
+  return [pscustomobject]@{ Names = $names; Bins = $bins; ScriptText = $script.ToString().ToLowerInvariant(); Scanned = $seen }
+}
+
+function Get-GlobalPackageVerdict {
+  <# .SYNOPSIS Pure verdict for one global package: keep | candidate, plus whether a project shadows its command.
+     Candidate needs all three: idle past the window, never referenced, and not a package manager we protect. #>
+  param([pscustomobject] $Package, [pscustomobject] $Index, [int] $Days)
+  $short = ($Package.Name -split '/')[-1]
+  $shadowed = $false
+  foreach ($b in @($Package.Bins)) { if ($Index.Bins.Contains($b)) { $shadowed = $true } }
+  if ($Script:WS_GLOBAL_KEEP -contains $short -or $Script:WS_GLOBAL_KEEP -contains $Package.Name) {
+    return [pscustomobject]@{ Verdict = 'keep'; Reason = 'package manager / this tool'; Shadowed = $shadowed }
+  }
+  if ($Index.Names.Contains($Package.Name)) { return [pscustomobject]@{ Verdict = 'keep'; Reason = 'a recent project depends on it'; Shadowed = $shadowed } }
+  foreach ($b in @($Package.Bins)) {
+    if ($b -and $Index.ScriptText.Contains($b.ToLowerInvariant())) { return [pscustomobject]@{ Verdict = 'keep'; Reason = "a recent project script runs '$b'"; Shadowed = $shadowed } }
+  }
+  if ($Package.Idle -lt $Days) { return [pscustomobject]@{ Verdict = 'keep'; Reason = "touched $($Package.Idle) days ago"; Shadowed = $shadowed } }
+  return [pscustomobject]@{ Verdict = 'candidate'; Reason = "nothing referenced it and it is $($Package.Idle) days old"; Shadowed = $shadowed }
+}
+
+function Get-GlobalUninstallCommand {
+  <# .SYNOPSIS The exact command that removes one global package for its manager. #>
+  param([string] $Manager, [string] $Name)
+  switch ($Manager) {
+    'npm' { return "npm uninstall -g $Name" }
+    'pnpm' { return "pnpm remove -g $Name" }
+    'yarn' { return "yarn global remove $Name" }
+    'bun' { return "bun remove -g $Name" }
+    'deno' { return "deno uninstall $Name" }
+    default { return "# remove $Name manually" }
+  }
+}
+
+function Get-Targets22 {
+  <# .SYNOPSIS Informational rows only. Section 22 declares NO deletable target: these roots are protected. #>
+  $t = @()
+  foreach ($r in (Get-GlobalPackageRoots)) { $t += (New-Target 22 "$($r.Manager) global root" $r.Root -Kind cmd -Note 'read-only audit; this section never deletes') }
+  if ($t.Count -eq 0) { $t += (New-Target 22 'global package roots' '(none detected)' -Kind cmd -Note 'read-only audit; this section never deletes') }
+  return $t
+}
+
+function Invoke-Section22 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'What npm, pnpm, yarn, bun and deno installed globally, and which of those nothing has referenced lately.',
+    "A package is a candidate only when it is $($ws.Days)+ days old AND no project touched recently names it.",
+    'This section never uninstalls anything - it prints the command and leaves the decision to you.'
+  )
+  $roots = @(Get-GlobalPackageRoots)
+  if ($roots.Count -eq 0) { Write-Info 'no global package roots found'; return }
+  Write-Info ('roots: ' + (($roots | ForEach-Object { "$($_.Manager) -> $($_.Root)" }) -join '   '))
+  $packages = @()
+  foreach ($r in $roots) { $packages += @(Get-GlobalPackages -RootRow $r) }
+  if ($packages.Count -eq 0) { Write-Info 'no globally installed packages found'; return }
+  $projectRoots = @(Get-ProjectScanRoots)
+  $index = Get-ProjectPackageIndex -Roots $projectRoots -Days $ws.Days
+  Write-Note "checked $($index.Scanned) project manifest(s) under: $($projectRoots -join '  ')"
+  $lines = @("global packages audit - $(Get-Date -Format 'yyyy-MM-dd HH:mm') - idle window $($ws.Days) days", '')
+  $kept = @(); $cand = @()
+  foreach ($p in ($packages | Sort-Object Bytes -Descending)) {
+    $v = Get-GlobalPackageVerdict -Package $p -Index $index -Days $ws.Days
+    $row = [pscustomobject]@{ Package = $p; Verdict = $v }
+    if ($v.Verdict -eq 'candidate') { $cand += $row } else { $kept += $row }
+  }
+  Write-Section 'Kept'
+  Write-UiLine ("  {0,-34} {1,-10} {2,10} {3,6}  {4}" -f 'PACKAGE', 'VERSION', 'SIZE', 'IDLE', 'WHY') 'White'
+  foreach ($r in $kept) {
+    $line = "  {0,-34} {1,-10} {2,10} {3,5}d  {4}" -f $r.Package.Name, $r.Package.Version, (Format-Bytes $r.Package.Bytes), $r.Package.Idle, $r.Verdict.Reason
+    Write-UiLine $line 'Gray'; $lines += ('kept      ' + $line.Trim())
+  }
+  Write-Section 'Candidates - nothing recent referenced these'
+  if ($cand.Count -eq 0) { Write-Info 'none' } else {
+    Write-UiLine ("  {0,-34} {1,-10} {2,10} {3,6}  {4}" -f 'PACKAGE', 'VERSION', 'SIZE', 'IDLE', 'NOTE') 'White'
+    $total = [long]0
+    foreach ($r in $cand) {
+      $note = ''
+      if ($r.Verdict.Shadowed) { $note = 'a project installs this command locally' }
+      $line = "  {0,-34} {1,-10} {2,10} {3,5}d  {4}" -f $r.Package.Name, $r.Package.Version, (Format-Bytes $r.Package.Bytes), $r.Package.Idle, $note
+      Write-UiLine $line 'Yellow'; $lines += ('candidate ' + $line.Trim())
+      $total += $r.Package.Bytes
+    }
+    Write-Info ('candidates hold ' + (Format-Bytes $total))
+    Write-Section 'Remove them yourself with'
+    $lines += ''; $lines += 'uninstall commands:'
+    foreach ($r in $cand) {
+      $cmd = Get-GlobalUninstallCommand -Manager $r.Package.Manager -Name $r.Package.Name
+      Write-Plain "  $cmd"; $lines += "  $cmd"
+    }
+    Write-Note 'windowsweep does not run these: a global package can be a command you rely on rarely.'
+  }
+  if (-not $ws.NoReport) {
+    $out = Join-Path $ws.ReportsDir ('global-packages-' + $ws.Stamp + '.txt')
+    try { [IO.File]::WriteAllLines($out, $lines); Write-Note "list saved: $out" } catch { $null = $_ }
+  }
+}

package/modules/health.ps1

@@ -76,7 +76,7 @@ function Invoke-Section00 {
     } catch { $null = $_ }
   }
   Write-UiLine '' 'Gray'
-  try { $n = @(Get-CimInstance Win32_StartupCommand -ErrorAction Stop).Count; Write-Kv 'Startup items:' "$n (review in Task Manager > Startup; this tool does not change them)" } catch { $null = $_ }
+  try { $n = @(Get-CimInstance Win32_StartupCommand -ErrorAction Stop).Count; Write-Kv 'Startup items:' "$n (section 25 lists them all; change them in Task Manager > Startup - this tool never does)" } catch { $null = $_ }
   try {
     $ss = (Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\StorageSense\Parameters\StoragePolicy' -ErrorAction Stop).'01'
     $ssText = 'off'

package/modules/installed_programs.ps1

@@ -0,0 +1,118 @@
+# installed_programs.ps1 - section 24: installed programs nothing has modified for N+ days. Report only.
+#
+# It NEVER runs an uninstaller, in any mode. Windows keeps no reliable "last launched" record, so the number
+# reported is "not modified", derived from the files under InstallLocation - never described as "unused".
+
+function Get-WingetIdMap {
+  <# .SYNOPSIS One winget call, parsed once: normalised program name -> package id. Empty when winget is absent. #>
+  $map = @{}
+  if (-not (Test-CommandPresent 'winget')) { return $map }
+  $lines = @()
+  try { $lines = @(& winget list --disable-interactivity 2>$null) } catch { return $map }
+  foreach ($line in $lines) {
+    $text = [string]$line
+    # "Name   Id   Version   Source" with runs of spaces between columns; ids never contain a space.
+    if ($text -notmatch '^(.+?)\s\s+([^\s]+)\s\s+') { continue }
+    $name = ConvertTo-MatchToken $Matches[1]
+    $id = $Matches[2]
+    if ($name.Length -lt 3 -or $id -eq 'Id') { continue }
+    if (-not $map.ContainsKey($name)) { $map[$name] = $id }
+  }
+  return $map
+}
+
+function Get-InstallLocationIdleDays {
+  <# .SYNOPSIS Days since the newest LAST-WRITE at depth <= 2 under an install folder, or -1 when unknowable.
+     Deliberately NOT Get-NewestTimestampUtc, which the cleanup sections use: that takes the newest of write,
+     access and creation, and last-access is live on this machine - measured 2026-09-04, every install folder
+     read as 0 days idle that way (Git, Gpg4win, RustDesk, Malwarebytes all 0d) while last-write gave 120d,
+     203d, 163d and 148d. This section asks "not modified", so last-write is the matching question. #>
+  param([string] $Location, [int] $MaxEntries = 4000)
+  if ([string]::IsNullOrWhiteSpace($Location)) { return -1 }
+  $root = Get-FullPath ($Location.Trim().Trim('"').TrimEnd('\'))
+  if (-not $root -or -not (Test-DirPresent $root)) { return -1 }
+  $newest = [datetime]::MinValue
+  $seen = 0
+  $stack = New-Object System.Collections.Generic.Stack[object]
+  $stack.Push(@($root, 0))
+  while ($stack.Count -gt 0 -and $seen -lt $MaxEntries) {
+    $item = $stack.Pop()
+    foreach ($e in (Get-ChildEntries ([string]$item[0]))) {
+      $seen++
+      if (Test-ReparsePoint $e) { continue }
+      if ($e -is [IO.DirectoryInfo]) {
+        if ([int]$item[1] -lt 2) { $stack.Push(@((Remove-LongPrefix $e.FullName), [int]$item[1] + 1)) }
+        continue
+      }
+      if ($e.LastWriteTimeUtc -gt $newest) { $newest = $e.LastWriteTimeUtc }
+    }
+  }
+  if ($newest -eq [datetime]::MinValue) { return -1 }
+  return [int][math]::Floor(([datetime]::UtcNow - $newest).TotalDays)
+}
+
+function Get-ProgramRemovalHint {
+  <# .SYNOPSIS The command that removes a program: winget when it knows it, otherwise its own UninstallString. #>
+  param([pscustomobject] $Row, [hashtable] $WingetMap)
+  $key = ConvertTo-MatchToken $Row.DisplayName
+  if ($WingetMap.ContainsKey($key)) { return "winget uninstall --id $($WingetMap[$key])" }
+  if ($Row.UninstallString) { return $Row.UninstallString }
+  return '(no uninstall command recorded - remove it from Settings > Apps)'
+}
+
+function Get-Targets24 {
+  <# .SYNOPSIS Informational only. Section 24 declares nothing deletable: Program Files is protected. #>
+  return @((New-Target 24 'Installed programs (registry)' 'HKLM + HKCU Uninstall hives' -Kind cmd -Note 'report only; this section never runs an uninstaller'))
+}
+
+function Invoke-Section24 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'Programs whose files nothing has modified for a long time, largest first, with the command that removes',
+    'each one. Windows keeps no reliable record of when a program last RAN, so this is "not modified", not',
+    '"not used" - check the list before acting. This section never runs an uninstaller.'
+  )
+  $rows = @(Get-InstalledProgramRows | Where-Object { $_.SystemComponent -ne 1 })
+  if ($rows.Count -eq 0) { Write-Warn 'no uninstall entries could be read'; return }
+  Write-Note "$($rows.Count) installed program(s) found; measuring the ones with an install folder"
+  $winget = Get-WingetIdMap
+  $scored = @()
+  foreach ($r in $rows) {
+    $idle = Get-InstallLocationIdleDays -Location $r.InstallLocation
+    if ($idle -lt $ws.Days) { continue }
+    $scored += [pscustomobject]@{ Row = $r; Idle = $idle; Bytes = ([long]$r.EstimatedSizeKb * 1024) }
+  }
+  $lines = @("installed programs not modified for $($ws.Days)+ days - $(Get-Date -Format 'yyyy-MM-dd HH:mm')", '')
+  if ($scored.Count -eq 0) {
+    Write-Info "no installed program has been untouched for $($ws.Days)+ days"
+  } else {
+    Write-UiLine ("  {0,-44} {1,-14} {2,10} {3,6}  {4}" -f 'PROGRAM', 'VERSION', 'SIZE', 'IDLE', 'PUBLISHER') 'White'
+    foreach ($s in ($scored | Sort-Object Bytes -Descending)) {
+      $size = 'unknown'
+      if ($s.Bytes -gt 0) { $size = Format-Bytes $s.Bytes }
+      $line = "  {0,-44} {1,-14} {2,10} {3,5}d  {4}" -f $s.Row.DisplayName, $s.Row.DisplayVersion, $size, $s.Idle, $s.Row.Publisher
+      Write-UiLine $line 'Gray'
+      $lines += $line.Trim()
+      $lines += ('    remove with: ' + (Get-ProgramRemovalHint -Row $s.Row -WingetMap $winget))
+    }
+    Write-Section 'Remove one yourself with'
+    foreach ($s in ($scored | Sort-Object Bytes -Descending | Select-Object -First 10)) {
+      Write-Plain ('  ' + (Get-ProgramRemovalHint -Row $s.Row -WingetMap $winget))
+    }
+  }
+  Write-Section 'Store apps (not system packages)'
+  $appx = @()
+  try { $appx = @(Get-AppxPackage -ErrorAction SilentlyContinue | Where-Object { -not $_.IsFramework -and $_.SignatureKind -ne 'System' }) } catch { $appx = @() }
+  if ($appx.Count -eq 0) { Write-Info 'none found' } else {
+    foreach ($a in ($appx | Sort-Object Name)) {
+      Write-UiLine ("  {0,-52} {1}" -f $a.Name, $a.Version) 'Gray'
+      $lines += ("store  {0}  {1}" -f $a.Name, $a.Version)
+      $lines += ('    remove with: Remove-AppxPackage -Package ' + $a.PackageFullName)
+    }
+    Write-Note 'remove one with:  Remove-AppxPackage -Package <PackageFullName>'
+  }
+  if (-not $ws.NoReport) {
+    $out = Join-Path $ws.ReportsDir ('installed-programs-' + $ws.Stamp + '.txt')
+    try { [IO.File]::WriteAllLines($out, $lines); Write-Note "list saved: $out" } catch { $null = $_ }
+  }
+}

package/modules/menu.ps1

@@ -37,7 +37,9 @@ function Invoke-Menu {
   }
   while ($true) {
     Show-Menu
-    $choice = Read-Choice -Prompt '  Select [0-21 / A / D / Y / S / Q]: ' -Default ''
+    $lo = ($Script:WS_SECTIONS | Measure-Object Id -Minimum).Minimum
+    $hi = ($Script:WS_SECTIONS | Measure-Object Id -Maximum).Maximum
+    $choice = Read-Choice -Prompt "  Select [$lo-$hi / A / D / Y / S / Q]: " -Default ''
     if ($choice -eq '') { continue }
     switch -Regex ($choice) {
       '^q' { Show-SessionSummary; return }

package/modules/notify.ps1

@@ -0,0 +1,60 @@
+# notify.ps1 - --notify: one Windows notification when a run ends.
+#
+# Off by default. --quiet still notifies (that is the point of the flag when a Scheduled Task runs it).
+# Every path is wrapped: a notification that cannot be shown is not a failed run, so this NEVER touches the
+# exit code and NEVER writes to stdout - --json promises exactly one line there.
+
+function Get-RunNotificationText {
+  <# .SYNOPSIS The two lines a notification carries. Pure, so the self-test can read it without a toast. #>
+  $ws = $Script:WS
+  $ran = @($ws.Report.steps | Where-Object { $_.status -in 'ran', 'dry-run' }).Count
+  if ($ws.DryRun) {
+    return [pscustomobject]@{ Title = "$Script:WS_NAME - dry run finished"; Body = ("about " + (Format-Bytes $ws.TotalEstimated) + " could be freed across $ran section(s)") }
+  }
+  return [pscustomobject]@{ Title = "$Script:WS_NAME finished"; Body = ("freed " + (Format-Bytes $ws.TotalFreed) + " across $ran section(s)") }
+}
+
+function Show-ToastNotification {
+  <# .SYNOPSIS Windows PowerShell 5.1: a real toast through WinRT, under the PowerShell AppUserModelId. #>
+  param([string] $Title, [string] $Body)
+  $appId = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
+  $null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+  $null = [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime]
+  $tpl = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+  $texts = $tpl.GetElementsByTagName('text')
+  $null = $texts.Item(0).AppendChild($tpl.CreateTextNode($Title))
+  $null = $texts.Item(1).AppendChild($tpl.CreateTextNode($Body))
+  $toast = New-Object Windows.UI.Notifications.ToastNotification($tpl)
+  [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($appId).Show($toast)
+}
+
+function Show-BalloonNotification {
+  <# .SYNOPSIS PowerShell 7 has no WinRT projection by default: a tray balloon instead. #>
+  param([string] $Title, [string] $Body)
+  Add-Type -AssemblyName System.Windows.Forms -ErrorAction Stop
+  Add-Type -AssemblyName System.Drawing -ErrorAction Stop
+  $icon = New-Object System.Windows.Forms.NotifyIcon
+  try {
+    $icon.Icon = [System.Drawing.SystemIcons]::Information
+    $icon.Visible = $true
+    $icon.ShowBalloonTip(5000, $Title, $Body, [System.Windows.Forms.ToolTipIcon]::Info)
+    # The balloon needs the tray icon to survive a moment; without this it is created and destroyed unseen.
+    Start-Sleep -Milliseconds 600
+  } finally {
+    $icon.Visible = $false
+    $icon.Dispose()
+  }
+}
+
+function Send-RunNotification {
+  <# .SYNOPSIS --notify: show the end-of-run notification, or say quietly in the log why it could not. #>
+  if (-not $Script:WS.Notify) { return }
+  $text = Get-RunNotificationText
+  try {
+    if ($PSVersionTable.PSEdition -eq 'Core') { Show-BalloonNotification -Title $text.Title -Body $text.Body }
+    else { Show-ToastNotification -Title $text.Title -Body $text.Body }
+    Write-LogLine "notification shown: $($text.Title) - $($text.Body)"
+  } catch {
+    Write-LogLine "notification could not be shown (this never affects the exit code): $($_.Exception.Message)"
+  }
+}

package/modules/orphaned_appdata.ps1

@@ -0,0 +1,189 @@
+# orphaned_appdata.ps1 - section 23: folders directly under %APPDATA% and %LOCALAPPDATA% that belong to no
+# installed program. Interactive only; selected folders go to the Recycle Bin.
+#
+# The dangerous direction here is calling something orphaned when it is not, so every test errs the other
+# way: matching is generous, the exclusion list is long, and an EMPTY program index produces ZERO candidates
+# rather than "everything is orphaned".
+
+# Windows' own folders, shared infrastructure, and vendors whose data outlives an uninstall.
+$Script:WS_ORPHAN_EXCLUDE = @(
+  'Microsoft', 'Windows', 'WindowsPowerShell', 'PowerShell', 'Packages', 'Programs', 'Temp', 'Tmp', 'Comms',
+  'ConnectedDevicesPlatform', 'D3DSCache', 'Google', 'Mozilla', 'CrashDumps', 'VirtualStore', 'PeerDistRepub',
+  'Publishers', 'History', 'IconCache', 'ElevatedDiagnostics', 'Application Data', 'Local Settings',
+  'Deployment', 'assembly', 'GroupPolicy', 'Roaming', 'Local', 'LocalLow', 'Low', 'Diagnostics',
+  'PlaceholderTileLogoFolder', 'Desktop', 'Downloads', 'Documents', 'Start Menu', 'SendTo',
+  'Recent', 'NetHood', 'PrintHood', 'Templates', 'Cookies',
+  # Platform folders that belong to Windows or .NET rather than to any one program: they look orphaned
+  # because no uninstall entry names them, and one of them holds settings a .NET app wrote.
+  'IsolatedStorage', 'ToastNotificationManagerCompat', 'AppV', 'Package Cache', 'DBG', 'CLR_v4.0', 'CLR_v4.0_32'
+)
+
+function ConvertTo-MatchToken {
+  <# .SYNOPSIS Lower-case, alphanumerics only - so "Slack Technologies, Inc." and "slack" compare equal. #>
+  param([string] $Text)
+  if ([string]::IsNullOrWhiteSpace($Text)) { return '' }
+  return ($Text.ToLowerInvariant() -replace '[^a-z0-9]', '')
+}
+
+function Add-MatchTokens {
+  <# .SYNOPSIS Add a display string to the token set: the whole thing, plus each word of 4+ characters. #>
+  param([System.Collections.Generic.HashSet[string]] $Set, [string] $Text)
+  $whole = ConvertTo-MatchToken $Text
+  if ($whole.Length -ge 3) { $null = $Set.Add($whole) }
+  foreach ($w in ($Text -split '[^A-Za-z0-9]+')) {
+    $t = ConvertTo-MatchToken $w
+    if ($t.Length -ge 4) { $null = $Set.Add($t) }
+  }
+}
+
+function Get-InstalledProgramRows {
+  <# .SYNOPSIS Raw uninstall-hive rows from all three registry views. Shared with section 24. #>
+  $rows = @()
+  $hives = @(
+    'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall',
+    'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall',
+    'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'
+  )
+  foreach ($h in $hives) {
+    $keys = @()
+    try { $keys = @(Get-ChildItem -LiteralPath $h -ErrorAction Stop) } catch { $keys = @() }
+    foreach ($k in $keys) {
+      $props = $null
+      try { $props = Get-ItemProperty -LiteralPath $k.PSPath -ErrorAction Stop } catch { continue }
+      if (-not $props.DisplayName) { continue }
+      $rows += [pscustomobject]@{
+        DisplayName = [string]$props.DisplayName; DisplayVersion = [string]$props.DisplayVersion
+        Publisher = [string]$props.Publisher; InstallDate = [string]$props.InstallDate
+        EstimatedSizeKb = [long]0 + $props.EstimatedSize; InstallLocation = [string]$props.InstallLocation
+        UninstallString = [string]$props.UninstallString; SystemComponent = [int]0 + $props.SystemComponent
+      }
+    }
+  }
+  return $rows
+}
+
+function Get-InstalledProgramIndex {
+  <# .SYNOPSIS Everything that says "a program owns this name": uninstall entries, program folders, Store
+     package names and running processes. RegistryCount drives the fail-closed gate in section 23. #>
+  $P = $Script:P
+  $set = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::Ordinal)
+  $rows = @(Get-InstalledProgramRows)
+  foreach ($r in $rows) {
+    Add-MatchTokens -Set $set -Text $r.DisplayName
+    Add-MatchTokens -Set $set -Text $r.Publisher
+    if ($r.InstallLocation) { Add-MatchTokens -Set $set -Text (Split-Path -Leaf ($r.InstallLocation.TrimEnd('\'))) }
+  }
+  foreach ($dir in @($P.PF, $P.PF86, (Join-Path $P.L 'Programs'), (Join-Path $P.L 'Microsoft\WindowsApps'), (Join-Path $P.PD 'Microsoft\Windows\Start Menu\Programs'))) {
+    if (-not $dir -or -not (Test-DirPresent $dir)) { continue }
+    foreach ($e in (Get-ChildEntries $dir)) { Add-MatchTokens -Set $set -Text (($e.Name -split '_')[0]) }
+  }
+  foreach ($e in (Get-ChildEntries (Join-Path $P.L 'Packages'))) { Add-MatchTokens -Set $set -Text (($e.Name -split '_')[0]) }
+  try { foreach ($proc in (Get-Process -ErrorAction SilentlyContinue)) { Add-MatchTokens -Set $set -Text $proc.ProcessName } } catch { $null = $_ }
+  return [pscustomobject]@{ Tokens = $set; RegistryCount = $rows.Count; Rows = $rows }
+}
+
+function Get-OrphanExclusions {
+  <# .SYNOPSIS Folder names section 23 never offers: the fixed list plus, derived at run time, the first
+     segment under AppData of every target the tool already declares - so a vendor folder we clean can never
+     also be offered for deletion, and the list cannot drift as sections are added. #>
+  $P = $Script:P
+  $set = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  foreach ($n in $Script:WS_ORPHAN_EXCLUDE) { $null = $set.Add($n) }
+  $prefixes = @("$($P.A)\", "$($P.L)\")
+  foreach ($t in (Get-AllTargets)) {
+    $path = [string]$t.Path
+    foreach ($pre in $prefixes) {
+      if ($path.StartsWith($pre, [StringComparison]::OrdinalIgnoreCase)) {
+        $seg = ($path.Substring($pre.Length) -split '\\')[0]
+        if ($seg) { $null = $set.Add($seg) }
+      }
+    }
+  }
+  # ,$set - a bare `return $set` UNROLLS the HashSet into an Object[], whose .Contains is case-SENSITIVE,
+  # so a folder named "slack" would slip past the "Slack" entry. The comma keeps the set a set.
+  return , $set
+}
+
+function Test-OrphanFolderName {
+  <# .SYNOPSIS True when NOTHING installed claims this folder name. Deliberately generous in the other
+     direction: a token that merely starts with the name (or the reverse) counts as a claim. #>
+  param([string] $Name, [pscustomobject] $Index)
+  $n = ConvertTo-MatchToken $Name
+  if ($n.Length -lt 3) { return $false }
+  if ($Index.Tokens.Contains($n)) { return $false }
+  foreach ($t in $Index.Tokens) {
+    if ($t.Length -lt 4) { continue }
+    if ($t.StartsWith($n) -or $n.StartsWith($t)) { return $false }
+  }
+  return $true
+}
+
+function Find-OrphanedAppData {
+  <# .SYNOPSIS Top-level AppData folders idle N+ days that no installed program claims. Fails closed.
+     -Index is for the self-test: it proves the fail-closed gate without touching the real registry. #>
+  param([int] $Days, [pscustomobject] $Index = $null)
+  $P = $Script:P
+  $index = $Index
+  if ($null -eq $index) { $index = Get-InstalledProgramIndex }
+  if ($index.RegistryCount -eq 0) {
+    Write-Warn 'no uninstall entries could be read: refusing to call anything orphaned (fail closed).'
+    return @()
+  }
+  Write-Note "cross-checked against $($index.RegistryCount) installed-program entries"
+  $exclude = Get-OrphanExclusions
+  $out = @()
+  foreach ($root in @($P.A, $P.L)) {
+    if (-not (Test-DirPresent $root)) { continue }
+    foreach ($e in (Get-ChildEntries $root)) {
+      if (-not ($e -is [IO.DirectoryInfo]) -or (Test-ReparsePoint $e)) { continue }
+      if ($exclude.Contains($e.Name)) { continue }
+      $full = Remove-LongPrefix $e.FullName
+      if (Get-ProtectionReason $full) { continue }
+      if (-not (Test-OrphanFolderName -Name $e.Name -Index $index)) { continue }
+      $idle = Get-IdleDays $full
+      if ($idle -lt $Days) { continue }
+      $out += [pscustomobject]@{ Name = $e.Name; Path = $full; Root = (Get-FullPath $root); Idle = $idle; Bytes = [long](Get-DirectoryBytes $full) }
+    }
+  }
+  return @($out | Sort-Object Bytes -Descending | Select-Object -First 200)
+}
+
+function Get-Targets23 {
+  <# .SYNOPSIS Informational rows: the candidates are found at run time, never declared as fixed paths. #>
+  $P = $Script:P
+  $t = @()
+  foreach ($r in @($P.A, $P.L)) {
+    if (Test-DirPresent $r) { $t += (New-Target 23 'AppData root scanned for orphans' (Get-FullPath $r) -Kind cmd -Note 'top-level folders only; you pick what goes, and it lands in the Recycle Bin') }
+  }
+  return $t
+}
+
+function Invoke-Section23 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'Uninstalling a program usually leaves its AppData folder behind. This lists top-level folders under',
+    "Roaming and Local that no installed program, Store package or running process claims and that nothing",
+    "has touched for $($ws.Days)+ days. You pick what goes; it lands in the Recycle Bin."
+  )
+  $rows = @(Find-OrphanedAppData -Days $ws.Days)
+  if ($rows.Count -eq 0) { Write-Info 'no orphaned application data found'; return }
+  Write-UiLine ("  {0,3}  {1,10} {2,6}  {3}" -f '#', 'SIZE', 'IDLE', 'FOLDER') 'White'
+  $i = 1; $total = [long]0
+  foreach ($r in $rows) {
+    Write-UiLine ("  {0,3}  {1,10} {2,5}d  {3}" -f $i, (Format-Bytes $r.Bytes), $r.Idle, $r.Path) 'Gray'
+    Add-JsonCandidate -Section 23 -Index $i -Path $r.Path -Bytes $r.Bytes -IdleDays $r.Idle
+    $total += $r.Bytes; $i++
+  }
+  Write-Info ('total: ' + (Format-Bytes $total))
+  Write-Note 'a folder here can still hold settings or a licence for a program you plan to reinstall - read the list.'
+  $dest = 'the Recycle Bin'
+  if ($ws.Permanent) { $dest = 'PERMANENT deletion (--permanent)' }
+  Write-Note "selected folders go to $dest"
+  $picks = @(Read-MultiSelect -Total $rows.Count -NoAutoYes -Candidates @($rows | ForEach-Object { $_.Path }))
+  if ($picks.Count -eq 0) { Write-Info 'nothing selected'; return }
+  if (-not $ws.DryRun) {
+    # Orphaned app data never auto-confirms: --yes does not apply. An explicit --select / --select-file does.
+    if (-not (Confirm-Ui -Prompt "Move $($picks.Count) folder(s) to $dest ?" -Default 'n' -NoAutoYes -ScriptedOk)) { Write-Info 'skipped'; return }
+  }
+  foreach ($k in $picks) { $null = Send-ToRecycleBin -Path $rows[$k - 1].Path -Within $rows[$k - 1].Root }
+}