windowsweep 1.0.0

package/bin/windowsweep.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/*
+ * windowsweep - Node.js launcher for npx and global installs.
+ *
+ *   npx windowsweep              (zero install)
+ *   npm i -g windowsweep         (then: windowsweep)
+ *
+ * A thin shim, nothing more. It:
+ *   1. refuses to run anywhere but Windows;
+ *   2. locates windowsweep.ps1 inside the package;
+ *   3. starts Windows PowerShell with -ExecutionPolicy Bypass so the machine's script policy
+ *      cannot block the run (WINDOWSWEEP_SHELL=pwsh or --pwsh selects PowerShell 7 instead);
+ *   4. passes the package version and launcher facts through environment variables;
+ *   5. forwards every argument, stdin/stdout/stderr, Ctrl-C and the exit code unchanged.
+ *
+ * Author:  Ahsan Mahmood <aoneahsan@gmail.com>  https://aoneahsan.com
+ * License: MIT (see LICENSE)
+ */
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { spawn } = require('child_process');
+
+if (process.platform !== 'win32') {
+  process.stderr.write(
+    '\nwindowsweep runs on Windows only. Detected platform: ' + process.platform + '\n' +
+    'Linux:  npx linux-cleanup     macOS:  npx macleanup\n\n'
+  );
+  process.exit(2);
+}
+
+const PKG_DIR = path.resolve(__dirname, '..');
+const SCRIPT = path.join(PKG_DIR, 'windowsweep.ps1');
+if (!fs.existsSync(SCRIPT)) {
+  process.stderr.write('windowsweep: cannot find ' + SCRIPT + ' - the package may be corrupted. Try: npx --yes windowsweep@latest\n');
+  process.exit(2);
+}
+
+let pkgVersion = '';
+try { pkgVersion = require(path.join(PKG_DIR, 'package.json')).version || ''; } catch (_) { /* fall back to the literal in lib/constants.ps1 */ }
+
+const rawArgs = process.argv.slice(2);
+const wantPwsh = rawArgs.includes('--pwsh') || (process.env.WINDOWSWEEP_SHELL || '').toLowerCase() === 'pwsh';
+const args = rawArgs.filter((a) => a !== '--pwsh');
+
+const systemRoot = process.env.SystemRoot || 'C:\\Windows';
+const windowsPowerShell = path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+const shell = wantPwsh ? 'pwsh' : (fs.existsSync(windowsPowerShell) ? windowsPowerShell : 'powershell.exe');
+
+const isNpx = /[\\/]_npx[\\/]/.test(PKG_DIR) || /npx/i.test(process.env.npm_config_user_agent || '');
+
+const env = Object.assign({}, process.env, {
+  WINDOWSWEEP_VERSION: pkgVersion,
+  WINDOWSWEEP_LAUNCHER: 'node',
+  WINDOWSWEEP_NPX: isNpx ? '1' : '0',
+});
+
+const child = spawn(shell, ['-NoProfile', '-NoLogo', '-ExecutionPolicy', 'Bypass', '-File', SCRIPT].concat(args), {
+  stdio: 'inherit',
+  env: env,
+  windowsHide: false,
+});
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    process.stderr.write('\nwindowsweep: ' + shell + ' was not found. Windows PowerShell 5.1 ships with Windows 10/11;' +
+      (wantPwsh ? ' install PowerShell 7 or drop --pwsh.\n\n' : ' check that %SystemRoot%\\System32\\WindowsPowerShell exists.\n\n'));
+  } else {
+    process.stderr.write('windowsweep: failed to start PowerShell: ' + err.message + '\n');
+  }
+  process.exit(2);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) { process.exit(128 + (os.constants.signals[signal] || 0)); }
+  process.exit(code === null ? 0 : code);
+});
+
+['SIGINT', 'SIGTERM', 'SIGHUP'].forEach((sig) => {
+  process.on(sig, () => { if (!child.killed) { child.kill(sig); } });
+});

package/lib/actions.ps1

@@ -0,0 +1,209 @@
+# actions.ps1 - the target-list engine every section drives, plus shared cache-layout helpers.
+# A section is mostly a declaration: New-Target rows (path + mode + guards) run by Invoke-TargetList.
+
+$Script:WS_CHROMIUM_PROFILE_CACHES = @('Cache', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'GrShaderCache', 'ShaderCache', 'Service Worker\ScriptCache')
+$Script:WS_CHROMIUM_ROOT_CACHES = @('ShaderCache', 'GrShaderCache', 'GraphiteDawnCache', 'Crashpad\completed', 'Crashpad\reports', 'SwReporter')
+$Script:WS_ELECTRON_CACHES = @('Cache', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'GrShaderCache', 'ShaderCache', 'Service Worker\CacheStorage', 'Service Worker\ScriptCache', 'Crashpad\completed', 'Crashpad\reports')
+$Script:WS_EDITOR_CACHES = @('Cache', 'CachedData', 'CachedProfilesData', 'CachedExtensionVSIXs', 'Code Cache', 'GPUCache', 'DawnCache', 'DawnGraphiteCache', 'DawnWebGPUCache', 'Service Worker\CacheStorage', 'Service Worker\ScriptCache', 'Crashpad\completed', 'Crashpad\reports')
+$Script:WS_FIREFOX_CACHES = @('cache2', 'startupCache', 'thumbnails', 'jumpListCache', 'OfflineCache', 'shader-cache')
+
+function Get-ChromiumProfileDirs {
+  <# .SYNOPSIS Profile folders of a Chromium "User Data" root. A root that itself holds Cache is its own profile (Opera, Electron). #>
+  param([string] $Root)
+  $out = @()
+  if (-not (Test-DirPresent $Root)) { return $out }
+  foreach ($e in (Get-ChildEntries $Root)) {
+    if (-not ($e -is [IO.DirectoryInfo])) { continue }
+    if ($e.Name -match '^(Default|Profile \d+|Guest Profile|System Profile)$') { $out += (Remove-LongPrefix $e.FullName) }
+  }
+  if ($out.Count -eq 0 -and (Test-DirPresent (Join-Path $Root 'Cache'))) { $out += (Get-FullPath $Root) }
+  return $out
+}
+
+function Get-ChromiumCacheDirs {
+  <# .SYNOPSIS Existing regenerable cache folders under a Chromium root (per profile + root-level). Never profile data. #>
+  param([string] $Root)
+  $out = @()
+  foreach ($prof in (Get-ChromiumProfileDirs $Root)) {
+    foreach ($sub in $Script:WS_CHROMIUM_PROFILE_CACHES) { $p = Join-Path $prof $sub; if (Test-DirPresent $p) { $out += $p } }
+  }
+  foreach ($sub in $Script:WS_CHROMIUM_ROOT_CACHES) { $p = Join-Path $Root $sub; if (Test-DirPresent $p) { $out += $p } }
+  return @($out | Select-Object -Unique)
+}
+
+function Get-FirefoxCacheDirs {
+  param([string] $ProfilesRoot)
+  $out = @()
+  if (-not (Test-DirPresent $ProfilesRoot)) { return $out }
+  foreach ($prof in (Get-ChildEntries $ProfilesRoot)) {
+    if (-not ($prof -is [IO.DirectoryInfo])) { continue }
+    foreach ($sub in $Script:WS_FIREFOX_CACHES) { $p = Join-Path (Remove-LongPrefix $prof.FullName) $sub; if (Test-DirPresent $p) { $out += $p } }
+  }
+  return $out
+}
+
+function Get-SubdirCacheDirs {
+  param([string] $Root, [string[]] $Subdirs)
+  $out = @()
+  if (-not (Test-DirPresent $Root)) { return $out }
+  foreach ($sub in $Subdirs) { $p = Join-Path $Root $sub; if (Test-DirPresent $p) { $out += $p } }
+  return $out
+}
+
+function Get-TargetCachePaths {
+  <# .SYNOPSIS Concrete cache folders for the layout kinds (chromium | firefox | electron | editor). #>
+  param([pscustomobject] $Target)
+  $roots = @()
+  if ($Target.Path -match '[\*\?]') {
+    try { $roots = @(Get-Item -Path $Target.Path -Force -ErrorAction SilentlyContinue | Where-Object { $_ -is [IO.DirectoryInfo] } | ForEach-Object { $_.FullName }) } catch { $roots = @() }
+  } elseif (Test-DirPresent $Target.Path) { $roots = @((Get-FullPath $Target.Path)) }
+  $out = @()
+  foreach ($r in $roots) {
+    switch ($Target.Kind) {
+      'chromium' { $out += Get-ChromiumCacheDirs $r }
+      'firefox' { $out += Get-FirefoxCacheDirs $r }
+      'electron' { $out += Get-SubdirCacheDirs -Root $r -Subdirs $Script:WS_ELECTRON_CACHES }
+      'editor' { $out += Get-SubdirCacheDirs -Root $r -Subdirs $Script:WS_EDITOR_CACHES }
+    }
+  }
+  return @($out)
+}
+
+function Show-TargetSizes {
+  <# .SYNOPSIS Table of the given targets with their current size on disk. Returns total bytes. Skipped when --quiet. #>
+  param([pscustomobject[]] $Targets)
+  $total = [long]0
+  if ($Script:WS.Quiet) { return $total }
+  Write-UiLine ("  {0,-44} {1,10}  {2}" -f 'TARGET', 'ON DISK', 'PATH') 'White'
+  foreach ($t in $Targets) {
+    if ($t.Kind -eq 'cmd') { Write-UiLine ("  {0,-44} {1,10}  {2}" -f $t.Label, '(cmd)', $t.Path) 'DarkGray'; continue }
+    $paths = @(Resolve-TargetPaths $t)
+    if ($paths.Count -eq 0) { Write-UiLine ("  {0,-44} {1,10}  {2}" -f $t.Label, 'absent', $t.Path) 'DarkGray'; continue }
+    $bytes = [long]0
+    foreach ($p in $paths) { $bytes += Get-DirectoryBytes $p }
+    $total += $bytes
+    $shown = $t.Path
+    if ($paths.Count -gt 1) { $shown = "$($t.Path)  ($($paths.Count) folders)" }
+    Write-UiLine ("  {0,-44} {1,10}  {2}" -f $t.Label, (Format-Bytes $bytes), $shown) 'Gray'
+  }
+  Write-UiLine ("  {0,-44} {1,10}" -f 'on disk now', (Format-Bytes $total)) 'Cyan'
+  return $total
+}
+
+function Confirm-Section {
+  <# .SYNOPSIS One confirmation per section. Dry-run needs none; the walkthrough's step prompt counts as one. #>
+  param([string] $Prompt = 'Proceed with this section?', [string] $Default = 'y')
+  $ws = $Script:WS
+  if ($ws.DryRun) { Write-Note '[dry-run] estimating only - nothing is deleted'; return $true }
+  if ($ws.SectionPreConfirmed) { return $true }
+  return (Confirm-Ui -Prompt $Prompt -Default $Default)
+}
+
+function Invoke-TargetList {
+  <# .SYNOPSIS Run every target with its mode under the dry-run, developer, purge and running-app policies. Returns bytes freed/estimated. #>
+  param([pscustomobject[]] $Targets)
+  $ws = $Script:WS
+  $total = [long]0
+  foreach ($t in $Targets) {
+    if ($t.Kind -eq 'cmd') { continue }
+    $paths = @(Resolve-TargetPaths $t)
+    if ($paths.Count -eq 0) { Write-Info "$($t.Label) - absent"; continue }
+    if (@($t.Guard).Count -gt 0 -and (Test-ProcessRunning $t.Guard)) {
+      Write-Warn "$($t.Label) - skipped: $($t.Guard[0]) is running (close it and run this section again)"
+      $ws.Hints += "Close $($t.Guard[0]) and re-run:  windowsweep --only $($t.Section) --yes   (to clear $($t.Label))"
+      continue
+    }
+    $mode = $t.Mode
+    if ($t.Kind -in 'chromium', 'firefox', 'electron', 'editor') {
+      $mode = 'clear'
+      # Second guard: a layout target may only ever clear a known cache folder, never a profile or app root.
+      $known = @($Script:WS_CHROMIUM_PROFILE_CACHES + $Script:WS_CHROMIUM_ROOT_CACHES + $Script:WS_ELECTRON_CACHES + $Script:WS_EDITOR_CACHES + $Script:WS_FIREFOX_CACHES | ForEach-Object { [IO.Path]::GetFileName($_) })
+      $paths = @($paths | Where-Object {
+          $leaf = [IO.Path]::GetFileName($_)
+          if ($known -contains $leaf) { $true } else { Write-Err "REFUSE (not a known cache folder for a $($t.Kind) layout): $_"; $false }
+        })
+    }
+    if ($ws.PurgeAll -and $mode -in 'prune', 'units') { $mode = 'clear' }
+    if ($t.Dev -and $ws.Developer -eq $false -and $mode -in 'prune', 'units') { $mode = 'clear' }
+    $days = $t.Days
+    if ($days -le 0) { $days = $ws.Days }
+    # A target that resolves to several folders (every browser profile, every cache name) labels each result
+    # line with "parent\leaf", so ten "VS Code caches - cleared ..." lines become ten distinguishable ones.
+    $multi = ($paths.Count -gt 1)
+    foreach ($p in $paths) {
+      $label = "$($t.Label)"
+      if ($multi) { $label = "$($t.Label) [$(Split-Path -Leaf (Split-Path -Parent $p))\$([IO.Path]::GetFileName($p))]" }
+      switch ($mode) {
+        'clear' { $r = Clear-DirectoryContents -Path $p -Within $p -Label $label; $total += $r.Freed }
+        'clear-old' { $r = Clear-DirectoryContents -Path $p -Within $p -Label $label -OlderThanDays $days; $total += $r.Freed }
+        'prune' { $r = Remove-StaleFiles -Root $p -Within $p -Days $days -Label $label; $total += $r.Freed }
+        'units' { $r = Remove-StaleUnits -Root $p -Within $p -Days $days -KeepNewest:$t.KeepNewest -DirectoriesOnly -GroupBy $t.GroupBy -ExcludeNames $t.ExcludeNames -Label $label; $total += $r.Freed }
+        'file' {
+          $r = Remove-PathSafe -Path $p -Within (Split-Path -Parent $p) -Label "$($t.Label)"
+          if ($r.Removed -and -not $ws.DryRun -and $r.Bytes -gt 0) { Write-Ok ("$($t.Label) - removed " + (Format-Bytes $r.Bytes)) }
+          $total += $r.Bytes
+        }
+        default { Write-Warn "$($t.Label) - unknown mode '$mode'" }
+      }
+    }
+  }
+  return $total
+}
+
+function Remove-SupersededVersions {
+  <# .SYNOPSIS Squirrel-style installs keep old app-x.y.z folders beside the current one; remove all but the highest version. #>
+  param([string] $Root, [string] $Prefix = 'app-', [string[]] $Guard = @(), [string] $Label = '')
+  if (-not (Test-DirPresent $Root)) { return [long]0 }
+  if ($Guard.Count -gt 0 -and (Test-ProcessRunning $Guard)) { Write-Warn "$Label - superseded versions skipped: $($Guard[0]) is running"; return [long]0 }
+  $versions = @()
+  foreach ($e in (Get-ChildEntries $Root)) {
+    if (-not ($e -is [IO.DirectoryInfo]) -or (Test-ReparsePoint $e)) { continue }
+    if ($e.Name -like "$Prefix*") {
+      $v = $null
+      try { $v = [version]($e.Name.Substring($Prefix.Length) -replace '[^0-9.].*$', '') } catch { $v = $null }
+      if ($v) { $versions += [pscustomobject]@{ Name = $e.Name; Path = (Remove-LongPrefix $e.FullName); Version = $v } }
+    }
+  }
+  if ($versions.Count -lt 2) { return [long]0 }
+  $newest = $versions | Sort-Object Version -Descending | Select-Object -First 1
+  $freed = [long]0
+  foreach ($v in $versions) {
+    if ($v.Path -eq $newest.Path) { Write-Note "kept  $($v.Name)  (current version)"; continue }
+    $r = Remove-PathSafe -Path $v.Path -Within $Root -Label $Label
+    if ($r.Removed) { $freed += $r.Bytes; if (-not $Script:WS.DryRun) { Write-Ok ("$Label - removed superseded $($v.Name) (" + (Format-Bytes $r.Bytes) + ')') } }
+  }
+  return $freed
+}
+
+function ConvertFrom-SizeText {
+  <# .SYNOPSIS "2.891GB" / "12.5 MB" / "20.48kB" -> bytes (docker prints decimal units). #>
+  param([string] $Text)
+  if ($Text -match '([\d.]+)\s*(B|kB|KB|MB|GB|TB)') {
+    $n = [double]$Matches[1]
+    switch ($Matches[2]) { 'kB' { return [long]($n * 1000) } 'KB' { return [long]($n * 1000) } 'MB' { return [long]($n * 1e6) } 'GB' { return [long]($n * 1e9) } 'TB' { return [long]($n * 1e12) } default { return [long]$n } }
+  }
+  return [long]0
+}
+
+function Get-NpmCacheDir {
+  $fallback = Join-Path $Script:P.L 'npm-cache'
+  if (-not (Test-CommandPresent 'npm')) { return $fallback }
+  try {
+    $out = & npm config get cache 2>$null
+    $line = ($out | Select-Object -Last 1)
+    if ($line -and (Test-DirPresent $line.Trim())) { return (Get-FullPath $line.Trim()) }
+  } catch { $null = $_ }
+  return $fallback
+}
+
+function Write-SectionIntro {
+  <# .SYNOPSIS Print what a section does and the current strategy line. #>
+  param([string[]] $Lines, [bool] $Dev = $false)
+  $ws = $Script:WS
+  foreach ($l in $Lines) { Write-Plain "  $l" }
+  if ($Dev) {
+    if ($ws.PurgeAll) { Write-Warn 'strategy: FULL PURGE (--purge-all) - every cache target is emptied, including recently used files' }
+    elseif ($ws.Developer -eq $false) { Write-Info 'strategy: developer mode OFF - these caches are cleared completely' }
+    else { Write-Info "strategy: developer mode ON - only files idle $($ws.Days)+ days go; the newest version of each tool cache is kept" }
+  }
+}

package/lib/config.ps1

@@ -0,0 +1,90 @@
+# config.ps1 - persistent settings (~\.windowsweep\config.json) and the developer question.
+
+function Get-DefaultConfig {
+  return [ordered]@{
+    schema = 1
+    developer = $null
+    developerAskedAt = $null
+    days = 100
+    tempDays = 3
+    largeFileMb = 100
+    scanRoots = @()
+    excludePaths = @()
+    welcomed = $false
+  }
+}
+
+function Import-Config {
+  <# .SYNOPSIS Load config.json over the defaults; a broken file is reported and ignored. #>
+  $ws = $Script:WS
+  $cfg = Get-DefaultConfig
+  $path = $ws.ConfigPath
+  if (Test-Path -LiteralPath $path) {
+    try {
+      $raw = Get-Content -LiteralPath $path -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
+      foreach ($k in @($cfg.Keys)) {
+        $prop = $raw.PSObject.Properties[$k]
+        if ($null -ne $prop) { $cfg[$k] = $prop.Value }
+      }
+      if ($null -eq $cfg.scanRoots) { $cfg.scanRoots = @() }
+      if ($null -eq $cfg.excludePaths) { $cfg.excludePaths = @() }
+    } catch {
+      Write-Warn "config file unreadable, using defaults: $path ($($_.Exception.Message))"
+    }
+  }
+  $ws.Config = $cfg
+  return $cfg
+}
+
+function Save-Config {
+  $ws = $Script:WS
+  try {
+    $dir = Split-Path -Parent $ws.ConfigPath
+    if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
+    [IO.File]::WriteAllText($ws.ConfigPath, ($ws.Config | ConvertTo-Json -Depth 4), (New-Object System.Text.UTF8Encoding($false)))
+  } catch {
+    Write-Warn "could not save config: $($_.Exception.Message)"
+  }
+}
+
+function Get-ToolchainHints {
+  <# .SYNOPSIS Names of developer tools found on this machine (used to suggest the developer answer). #>
+  $found = @()
+  foreach ($c in @('node', 'npm', 'yarn', 'pnpm', 'bun', 'deno', 'git', 'docker', 'python', 'pip', 'uv', 'java', 'gradle', 'dotnet', 'cargo', 'go', 'flutter', 'composer', 'php', 'code', 'cursor')) {
+    if (Get-Command $c -ErrorAction SilentlyContinue) { $found += $c }
+  }
+  $dirs = @{
+    'Gradle caches' = "$env:USERPROFILE\.gradle"; 'Android SDK' = "$env:LOCALAPPDATA\Android\Sdk"; 'VS Code' = "$env:APPDATA\Code"
+    'Docker Desktop' = "$env:LOCALAPPDATA\Docker"; 'JetBrains IDEs' = "$env:LOCALAPPDATA\JetBrains"; 'Visual Studio' = "$env:LOCALAPPDATA\Microsoft\VisualStudio"
+  }
+  foreach ($k in $dirs.Keys) { if (Test-Path -LiteralPath $dirs[$k]) { $found += $k } }
+  return $found
+}
+
+function Resolve-DeveloperMode {
+  <# .SYNOPSIS Decide developer mode: flag > saved answer > interactive question > conservative default (yes). #>
+  $ws = $Script:WS
+  if ($null -ne $ws.DeveloperFlag) { $ws.Developer = [bool]$ws.DeveloperFlag; $ws.DeveloperSource = 'flag'; return }
+  if ($ws.ForgetDeveloper) { $ws.Config.developer = $null; $ws.Config.developerAskedAt = $null }
+  if ($null -ne $ws.Config.developer) { $ws.Developer = [bool]$ws.Config.developer; $ws.DeveloperSource = 'config'; return }
+  if ($ws.Interactive -and -not $ws.Yes) {
+    $hints = @(Get-ToolchainHints)
+    Write-Box 'One question before anything else' 'It decides how package and build caches are treated'
+    Write-Plain '  Are you a developer on this machine?'
+    Write-Note 'yes = package/build/test-runner caches are only pruned when idle 100+ days (recent work stays fast);'
+    Write-Note '      the newest version of every versioned tool cache is always kept.'
+    Write-Note 'no  = those caches are cleared completely; project scans are skipped.'
+    if ($hints.Count -gt 0) { Write-Note ("detected developer tooling: " + ($hints -join ', ')) }
+    $ans = Confirm-Ui -Prompt 'Are you a developer on this machine?' -Default 'y' -NoAutoYes
+    $ws.Developer = $ans
+    $ws.DeveloperSource = 'answer'
+    $ws.Config.developer = $ans
+    $ws.Config.developerAskedAt = (Get-Date).ToString('yyyy-MM-dd')
+    Save-Config
+    if ($ans) { Write-Ok 'developer mode ON - saved to config.json (change with --forget-developer)' } else { Write-Ok 'developer mode OFF - saved to config.json (change with --forget-developer)' }
+    return
+  }
+  $ws.Developer = $true
+  $ws.DeveloperSource = 'default'
+  Write-Note 'developer question not asked (non-interactive run) - defaulting to developer mode ON, the conservative choice; pass --not-developer to override'
+}

package/lib/constants.ps1

@@ -0,0 +1,89 @@
+# constants.ps1 - project metadata, section catalogue, profiles and gates.
+# Dot-sourced by windowsweep.ps1. ASCII only (PowerShell 5.1 reads BOM-less files as ANSI).
+
+# Single source of truth for the version is package.json: the Node launcher exports it as
+# WINDOWSWEEP_VERSION. A direct checkout falls back to this literal; the version:check script
+# asserts the two never drift.
+$Script:WS_VERSION_FALLBACK = '1.0.0'
+
+$Script:WS_NAME = 'windowsweep'
+$Script:WS_TAGLINE = 'Safe-by-default Windows cleanup CLI - developer-aware, dry-run first, zero install via npx.'
+$Script:WS_AUTHOR = 'Ahsan Mahmood'
+$Script:WS_EMAIL = 'aoneahsan@gmail.com'
+$Script:WS_WEB = 'https://aoneahsan.com'
+$Script:WS_LINKEDIN = 'https://linkedin.com/in/aoneahsan'
+$Script:WS_GITHUB = 'https://github.com/aoneahsan'
+$Script:WS_REPO = 'https://github.com/aoneahsan/windowsweep'
+$Script:WS_ISSUES = 'https://github.com/aoneahsan/windowsweep/issues'
+$Script:WS_NPM = 'https://www.npmjs.com/package/windowsweep'
+$Script:WS_DOCS = 'https://github.com/aoneahsan/windowsweep/blob/main/docs/README.md'
+$Script:WS_SUPPORT = 'https://aoneahsan.com/payment?project-id=windowsweep&project-identifier=windowsweep'
+$Script:WS_LICENSE = 'MIT License'
+
+# Exit codes (documented in docs/cli-reference.md).
+$Script:WS_EXIT_OK = 0
+$Script:WS_EXIT_FAIL = 1
+$Script:WS_EXIT_USAGE = 2
+$Script:WS_EXIT_REFUSED = 3
+$Script:WS_EXIT_INTERRUPT = 130
+
+# Section catalogue. Numbering is a public contract frozen at 1.0.0: a section may be retired
+# (kept as a no-op that says so) but a number is never reused for something else.
+#   Tier:  report | rebuilds | slow | permanent | config
+#   Batch: safe (in --all) | optin (--only/--profile with --yes) | deep (needs --i-understand-deep)
+#          | interactive (never batch; dry-run/report allowed)
+$Script:WS_SECTIONS = @(
+  @{ Id = 0;  Key = 'health';     Title = 'System health report';                                   Tier = 'report';    Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section00' }
+  @{ Id = 1;  Key = 'pkg';        Title = 'Package-manager caches (npm, yarn, pnpm, bun, deno, pip, uv, Composer, NuGet, Cargo, Go, pub)'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $true; Fn = 'Invoke-Section01' }
+  @{ Id = 2;  Key = 'build';      Title = 'Build-tool caches (Gradle, Maven, Android, Unity, JetBrains)'; Tier = 'rebuilds';  Admin = $false; Batch = 'safe';        Dev = $true;  Fn = 'Invoke-Section02' }
+  @{ Id = 3;  Key = 'runners';    Title = 'Test-runner browsers (Cypress, Playwright, Puppeteer) - keep newest'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $true; Fn = 'Invoke-Section03' }
+  @{ Id = 4;  Key = 'avd';        Title = 'Android emulators (AVDs) idle N+ days';                    Tier = 'slow';      Admin = $false; Batch = 'optin';       Dev = $true;  Fn = 'Invoke-Section04' }
+  @{ Id = 5;  Key = 'docker';     Title = 'Docker: dangling images, build cache, unused images older than N days'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $true; Fn = 'Invoke-Section05' }
+  @{ Id = 6;  Key = 'editors';    Title = 'Editor caches (VS Code, Cursor, Windsurf, Visual Studio) + superseded extensions'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section06' }
+  @{ Id = 7;  Key = 'browsers';   Title = 'Browser caches (Chrome, Edge, Brave, Vivaldi, Opera, Chromium, Firefox)'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section07' }
+  @{ Id = 8;  Key = 'apps';       Title = 'Desktop app caches (Discord, Slack, Teams, Zoom, Spotify, Postman, Figma, ...)'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section08' }
+  @{ Id = 9;  Key = 'wincaches';  Title = 'Windows user caches (INetCache, WER, crash dumps, shader caches, UWP temp)'; Tier = 'rebuilds'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section09' }
+  @{ Id = 10; Key = 'temp';       Title = 'User temp files older than N days';                        Tier = 'rebuilds';  Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section10' }
+  @{ Id = 11; Key = 'recycle';    Title = 'Empty the Recycle Bin - PERMANENT';                       Tier = 'permanent'; Admin = $false; Batch = 'deep';        Dev = $false; Fn = 'Invoke-Section11' }
+  @{ Id = 12; Key = 'wu';         Title = 'Windows Update + system temp (SoftwareDistribution, Delivery Optimization, Windows\Temp, CBS logs)'; Tier = 'rebuilds'; Admin = $true; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section12' }
+  @{ Id = 13; Key = 'cleanmgr';   Title = 'Windows Disk Cleanup engine (cleanmgr, curated handlers)'; Tier = 'rebuilds'; Admin = $true;  Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section13' }
+  @{ Id = 14; Key = 'dism';       Title = 'Component store cleanup (DISM StartComponentCleanup) - slow'; Tier = 'rebuilds'; Admin = $true; Batch = 'optin';      Dev = $false; Fn = 'Invoke-Section14' }
+  @{ Id = 15; Key = 'hiberfil';   Title = 'Hibernation file (off / reduced)';                         Tier = 'config';    Admin = $true;  Batch = 'deep';        Dev = $false; Fn = 'Invoke-Section15' }
+  @{ Id = 16; Key = 'eventlogs';  Title = 'Clear Windows Event Logs - PERMANENT';                     Tier = 'permanent'; Admin = $true;  Batch = 'deep';        Dev = $false; Fn = 'Invoke-Section16' }
+  @{ Id = 17; Key = 'projects';   Title = 'Stale project build artefacts (node_modules, dist, .next, target, ...)'; Tier = 'rebuilds'; Admin = $false; Batch = 'interactive'; Dev = $true; Fn = 'Invoke-Section17' }
+  @{ Id = 18; Key = 'partials';   Title = 'Partial / orphan downloads -> Recycle Bin';                Tier = 'permanent'; Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section18' }
+  @{ Id = 19; Key = 'large';      Title = 'Large stale personal files (Downloads, Desktop) -> Recycle Bin'; Tier = 'permanent'; Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section19' }
+  @{ Id = 20; Key = 'vhdx';       Title = 'Docker Desktop / WSL disk image compaction (stops Docker + WSL)'; Tier = 'config'; Admin = $true; Batch = 'deep';    Dev = $true;  Fn = 'Invoke-Section20' }
+  @{ Id = 21; Key = 'diskusage';  Title = 'Disk usage report (largest entries, drives, disk images)'; Tier = 'report';    Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section21' }
+)
+
+# The safe batch run by --all. Admin sections 12 and 13 join it only when already elevated.
+$Script:WS_SAFE_BATCH = @(0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 21)
+$Script:WS_SAFE_BATCH_ADMIN = @(12, 13)
+
+$Script:WS_PROFILES = @{
+  'dev'        = @(1, 2, 3, 4, 5, 6, 17)
+  'minimal'    = @(7, 8, 9, 10)
+  'cache-only' = @(1, 2, 3, 6, 7, 8, 9)
+  'system'     = @(12, 13, 14)
+  'deep'       = @(0, 1, 2, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 21)
+  'audit'      = @(0, 21)
+}
+
+# Walkthrough order (interactive default mode). Admin sections are inserted when elevated.
+$Script:WS_WALKTHROUGH = @(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 17, 18, 19)
+$Script:WS_WALKTHROUGH_ADMIN = @(12, 13, 14)
+
+function Get-Section {
+  <# .SYNOPSIS Returns the catalogue entry for a section id, or $null. #>
+  param([int] $Id)
+  foreach ($s in $Script:WS_SECTIONS) { if ($s.Id -eq $Id) { return $s } }
+  return $null
+}
+
+function Get-ToolVersion {
+  <# .SYNOPSIS The running version: launcher-provided env wins over the checkout fallback. #>
+  $v = $env:WINDOWSWEEP_VERSION
+  if ([string]::IsNullOrWhiteSpace($v)) { return $Script:WS_VERSION_FALLBACK }
+  return $v.Trim()
+}

package/lib/fs.ps1

@@ -0,0 +1,180 @@
+# fs.ps1 - long-path-safe filesystem helpers. The walker never descends into reparse points
+# (junctions / symlinks), which .NET's own recursive enumeration does.
+
+function Get-LongPath {
+  <# .SYNOPSIS Prefix an absolute path with \\?\ so .NET accepts paths longer than 260 chars. #>
+  param([string] $Path)
+  if ($Path.StartsWith('\\?\')) { return $Path }
+  if ($Path.StartsWith('\\')) { return ('\\?\UNC\' + $Path.Substring(2)) }
+  return ('\\?\' + $Path)
+}
+
+function Get-FullPath {
+  <# .SYNOPSIS Expand env vars, resolve . and .., strip the long prefix and trailing separators. $null if unresolvable. #>
+  param([string] $Path)
+  if ([string]::IsNullOrWhiteSpace($Path)) { return $null }
+  $p = [Environment]::ExpandEnvironmentVariables($Path.Trim())
+  if ($p.StartsWith('\\?\UNC\')) { $p = '\\' + $p.Substring(8) } elseif ($p.StartsWith('\\?\')) { $p = $p.Substring(4) }
+  try { $p = [IO.Path]::GetFullPath($p) } catch { return $null }
+  if ($p.Length -gt 3) { $p = $p.TrimEnd('\') }
+  return $p
+}
+
+function Get-ItemInfo {
+  <# .SYNOPSIS FileInfo or DirectoryInfo for a path (long-path aware), or $null when absent. #>
+  param([string] $Path)
+  $lp = Get-LongPath $Path
+  try {
+    if ([IO.Directory]::Exists($lp)) { return (New-Object IO.DirectoryInfo($lp)) }
+    if ([IO.File]::Exists($lp)) { return (New-Object IO.FileInfo($lp)) }
+  } catch { $null = $_ }
+  return $null
+}
+
+function Test-PathPresent {
+  param([string] $Path)
+  $lp = Get-LongPath $Path
+  try { return ([IO.Directory]::Exists($lp) -or [IO.File]::Exists($lp)) } catch { return $false }
+}
+
+function Test-DirPresent {
+  param([string] $Path)
+  try { return [IO.Directory]::Exists((Get-LongPath $Path)) } catch { return $false }
+}
+
+function Test-ReparsePoint {
+  <# .SYNOPSIS True when the FileSystemInfo is a junction or symbolic link. #>
+  param([System.IO.FileSystemInfo] $Info)
+  if ($null -eq $Info) { return $false }
+  return (($Info.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)
+}
+
+function Get-ChildEntries {
+  <# .SYNOPSIS Non-recursive children of a directory; empty on access errors. #>
+  param([string] $Path)
+  $out = @()
+  try {
+    $di = New-Object IO.DirectoryInfo((Get-LongPath $Path))
+    foreach ($e in $di.EnumerateFileSystemInfos()) { $out += $e }
+  } catch { $null = $_ }
+  return $out
+}
+
+function Get-NewestTimestampUtc {
+  <# .SYNOPSIS The most recent of write / access / creation time - the safe "last touched" estimate when access tracking is off. #>
+  param([System.IO.FileSystemInfo] $Info)
+  $t = $Info.LastWriteTimeUtc
+  try { if ($Info.LastAccessTimeUtc -gt $t) { $t = $Info.LastAccessTimeUtc } } catch { $null = $_ }
+  try { if ($Info.CreationTimeUtc -gt $t) { $t = $Info.CreationTimeUtc } } catch { $null = $_ }
+  return $t
+}
+
+function Get-DirectoryStats {
+  <# .SYNOPSIS Walk a tree without following reparse points. Returns Bytes, Files, Dirs, Links, Newest (UTC), Errors. #>
+  param([string] $Path)
+  $bytes = [long]0; $files = 0; $dirs = 0; $links = 0; $errors = 0
+  $newest = [datetime]::MinValue
+  $root = Get-ItemInfo $Path
+  if ($null -eq $root) { return [pscustomobject]@{ Bytes = 0; Files = 0; Dirs = 0; Links = 0; Newest = $newest; Errors = 0; Exists = $false } }
+  if ($root -is [IO.FileInfo]) {
+    return [pscustomobject]@{ Bytes = [long]$root.Length; Files = 1; Dirs = 0; Links = 0; Newest = (Get-NewestTimestampUtc $root); Errors = 0; Exists = $true }
+  }
+  if (Test-ReparsePoint $root) {
+    return [pscustomobject]@{ Bytes = 0; Files = 0; Dirs = 0; Links = 1; Newest = (Get-NewestTimestampUtc $root); Errors = 0; Exists = $true }
+  }
+  $stack = New-Object System.Collections.Generic.Stack[System.IO.DirectoryInfo]
+  $stack.Push($root)
+  while ($stack.Count -gt 0) {
+    $dir = $stack.Pop()
+    $entries = $null
+    try { $entries = $dir.EnumerateFileSystemInfos() } catch { $errors++; continue }
+    try {
+      foreach ($e in $entries) {
+        if (($e.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { $links++; continue }
+        if (($e.Attributes -band [IO.FileAttributes]::Directory) -ne 0) { $dirs++; $stack.Push([IO.DirectoryInfo]$e); continue }
+        $files++
+        $bytes += [long]$e.Length
+        $t = $e.LastWriteTimeUtc
+        if ($e.LastAccessTimeUtc -gt $t) { $t = $e.LastAccessTimeUtc }
+        if ($e.CreationTimeUtc -gt $t) { $t = $e.CreationTimeUtc }
+        if ($t -gt $newest) { $newest = $t }
+      }
+    } catch { $errors++ }
+  }
+  if ($newest -eq [datetime]::MinValue) { $newest = Get-NewestTimestampUtc $root }
+  return [pscustomobject]@{ Bytes = $bytes; Files = $files; Dirs = $dirs; Links = $links; Newest = $newest; Errors = $errors; Exists = $true }
+}
+
+function Get-DirectoryBytes {
+  <# .SYNOPSIS Total bytes under a path (0 when absent). Uses robocopy /L when available - it is native and fast. #>
+  param([string] $Path)
+  if (-not (Test-PathPresent $Path)) { return [long]0 }
+  $info = Get-ItemInfo $Path
+  if ($info -is [IO.FileInfo]) { return [long]$info.Length }
+  if (Test-ReparsePoint $info) { return [long]0 }
+  if (Get-Command robocopy.exe -ErrorAction SilentlyContinue) {
+    try {
+      $sink = Join-Path $env:TEMP ('windowsweep-null-' + [guid]::NewGuid().ToString('N'))
+      $lines = & robocopy.exe $Path $sink /L /S /NJH /BYTES /NFL /NDL /NC /NS /XJ /R:0 /W:0 2>$null
+      foreach ($line in $lines) {
+        if ($line -match '^\s*Bytes\s*:\s*(\d+)') { return [long]$Matches[1] }
+      }
+    } catch { $null = $_ }
+  }
+  return [long](Get-DirectoryStats $Path).Bytes
+}
+
+function Get-IdleDays {
+  <# .SYNOPSIS Days since the path (or anything inside it) was last touched. 999999 when absent. #>
+  param([string] $Path)
+  $info = Get-ItemInfo $Path
+  if ($null -eq $info) { return 999999 }
+  if ($info -is [IO.FileInfo] -or (Test-ReparsePoint $info)) {
+    return [int][math]::Floor(([datetime]::UtcNow - (Get-NewestTimestampUtc $info)).TotalDays)
+  }
+  $stats = Get-DirectoryStats $Path
+  return [int][math]::Floor(([datetime]::UtcNow - $stats.Newest).TotalDays)
+}
+
+function Get-StaleFiles {
+  <# .SYNOPSIS Files under Root whose newest timestamp is at least Days old; never follows reparse points.
+     Returns objects with Path, Bytes. Also returns the list of directories visited (for the empty sweep). #>
+  param([string] $Root, [int] $Days)
+  $cutoff = [datetime]::UtcNow.AddDays(-1 * $Days)
+  $stale = New-Object System.Collections.Generic.List[object]
+  $visited = New-Object System.Collections.Generic.List[string]
+  $rootInfo = Get-ItemInfo $Root
+  if ($null -eq $rootInfo -or -not ($rootInfo -is [IO.DirectoryInfo]) -or (Test-ReparsePoint $rootInfo)) {
+    return [pscustomobject]@{ Files = $stale; Dirs = $visited }
+  }
+  $stack = New-Object System.Collections.Generic.Stack[System.IO.DirectoryInfo]
+  $stack.Push($rootInfo)
+  while ($stack.Count -gt 0) {
+    $dir = $stack.Pop()
+    $entries = $null
+    try { $entries = $dir.EnumerateFileSystemInfos() } catch { continue }
+    try {
+      foreach ($e in $entries) {
+        if (($e.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { continue }
+        if (($e.Attributes -band [IO.FileAttributes]::Directory) -ne 0) {
+          $visited.Add($e.FullName)
+          $stack.Push([IO.DirectoryInfo]$e)
+          continue
+        }
+        $t = $e.LastWriteTimeUtc
+        if ($e.LastAccessTimeUtc -gt $t) { $t = $e.LastAccessTimeUtc }
+        if ($e.CreationTimeUtc -gt $t) { $t = $e.CreationTimeUtc }
+        if ($t -le $cutoff) { $stale.Add([pscustomobject]@{ Path = $e.FullName; Bytes = [long]$e.Length }) }
+      }
+    } catch { $null = $_ }
+  }
+  return [pscustomobject]@{ Files = $stale; Dirs = $visited }
+}
+
+function Remove-LongPrefix {
+  <# .SYNOPSIS Strip \\?\ for display. #>
+  param([string] $Path)
+  if ($Path.StartsWith('\\?\UNC\')) { return ('\\' + $Path.Substring(8)) }
+  if ($Path.StartsWith('\\?\')) { return $Path.Substring(4) }
+  return $Path
+}