windowsweep 1.1.0 → 1.2.0

package/lib/config.ps1

@@ -1,99 +1,108 @@
-# 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'
-}
-
-function Confirm-PurgeAllOnce {
-  <# .SYNOPSIS --purge-all from a console asks for a typed word once per run; --yes is the confirmation in batch runs. #>
-  $ws = $Script:WS
-  if (-not $ws.PurgeAll -or $ws.DryRun -or $ws.Yes) { return }
-  if (Confirm-Typed -Prompt 'FULL PURGE: --purge-all empties every cache target completely, including files you used yesterday.' -Word 'purge') { Write-Ok 'purge-all confirmed for this run'; return }
-  $ws.PurgeAll = $false
-  Write-Info 'purge-all declined - this run prunes by the idle window instead'
-}
+# 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).
+     -ReadOnly resolves from the flag or the saved answer ONLY. A read-only mode may not ask the question,
+     may not write config.json, and may not invent a decision the person never made - so when neither a flag
+     nor a saved answer exists it leaves Developer $null and the health report keeps saying "not decided yet",
+     which is the truth. Without this, --scan ignored --developer and --not-developer outright: the flag was
+     parsed, stored in DeveloperFlag, and never read, so section 0 printed "not decided yet" whatever you
+     passed and --json returned developer: null. The desktop window passes those flags to --scan
+     (desktop/src/lib/engine.ts) and could not read back the setting it had just sent. #>
+  param([switch] $ReadOnly)
+  $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 ($ReadOnly) { 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 $($ws.Days)+ days (recent work stays fast);"
+    Write-Note '      the newest version of every versioned tool cache is kept, unless --purge-all.'
+    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'
+}
+
+function Confirm-PurgeAllOnce {
+  <# .SYNOPSIS --purge-all from a console asks for a typed word once per run; --yes is the confirmation in batch runs. #>
+  $ws = $Script:WS
+  if (-not $ws.PurgeAll -or $ws.DryRun -or $ws.Yes) { return }
+  if (Confirm-Typed -Prompt 'FULL PURGE: --purge-all empties every cache target completely, including files you used yesterday.' -Word 'purge') { Write-Ok 'purge-all confirmed for this run'; return }
+  $ws.PurgeAll = $false
+  Write-Info 'purge-all declined - this run prunes by the idle window instead'
+}

package/lib/constants.ps1

@@ -1,93 +1,103 @@
-# 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.1.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 | recycle | 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 = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section18' }
-  @{ Id = 19; Key = 'large';      Title = 'Large stale personal files (Downloads) -> Recycle Bin';    Tier = 'recycle';   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' }
-  @{ Id = 22; Key = 'globals';    Title = 'Globally installed packages audit (npm, pnpm, yarn, bun, deno) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $true; Fn = 'Invoke-Section22' }
-  @{ Id = 23; Key = 'orphaned';   Title = 'Orphaned application data under AppData -> Recycle Bin';   Tier = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section23' }
-  @{ Id = 24; Key = 'programs';   Title = 'Installed programs not modified for N+ days - report only'; Tier = 'report';   Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section24' }
-  @{ Id = 25; Key = 'startup';    Title = 'Startup items audit (Run keys, Startup folders, logon tasks) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section25' }
-)
-
-# 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, 22, 24, 25)
-}
-
-# 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, 23)
-$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()
-}
+# 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.2.0'
+
+$Script:WS_NAME = 'windowsweep'
+$Script:WS_TAGLINE = 'Developer-aware Windows cleanup CLI: dry-run first, personal folders refused, 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
+
+# The protected-path CATEGORIES, in the wording the tool shows a person. Both --list-targets and
+# --list --json read this one list: the JSON is the same sentences, so a front end cannot show a user
+# a narrower promise than the console does.
+$Script:WS_PROTECT_CATEGORIES = @(
+  'every drive root, Windows, System32, Program Files, ProgramData, the user profile root and AppData roots',
+  'browser profile data (Local Storage, IndexedDB, cookies, history, bookmarks, extensions, PWA CacheStorage)',
+  'editor user data (settings, globalStorage, local History); UWP LocalState; toolchains (nvm, npm globals, corepack, ...)',
+  'NTUSER.DAT, UsrClass.dat, hiberfil/pagefile/swapfile (only powercfg touches hiberfil), Prefetch, Windows\Installer, WinSxS (DISM only)'
+)
+
+# 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 | recycle | 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 = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section18' }
+  @{ Id = 19; Key = 'large';      Title = 'Large stale personal files (Downloads) -> Recycle Bin';    Tier = 'recycle';   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' }
+  @{ Id = 22; Key = 'globals';    Title = 'Globally installed packages audit (npm, pnpm, yarn, bun, deno) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section22' }
+  @{ Id = 23; Key = 'orphaned';   Title = 'Orphaned application data under AppData -> Recycle Bin';   Tier = 'recycle';   Admin = $false; Batch = 'interactive'; Dev = $false; Fn = 'Invoke-Section23' }
+  @{ Id = 24; Key = 'programs';   Title = 'Installed programs not modified for N+ days - report only'; Tier = 'report';   Admin = $false; Batch = 'safe';        Dev = $false; Fn = 'Invoke-Section24' }
+  @{ Id = 25; Key = 'startup';    Title = 'Startup items audit (Run keys, Startup folders, logon tasks) - report only'; Tier = 'report'; Admin = $false; Batch = 'safe'; Dev = $false; Fn = 'Invoke-Section25' }
+)
+
+# 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, 22, 24, 25)
+}
+
+# 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, 23)
+$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()
+}