windowsweep 1.0.0

package/modules/walkthrough.ps1

@@ -0,0 +1,79 @@
+# walkthrough.ps1 - the default interactive mode: every category, one step at a time, with a running total.
+
+function Show-Welcome {
+  $ws = $Script:WS
+  Write-Banner
+  Write-Box "$Script:WS_NAME" $Script:WS_TAGLINE
+  Show-DriveTable
+  Write-UiLine '' 'Gray'
+  Write-Plain '  This walkthrough visits every cleanup category. At each step:'
+  Write-Plain '    a  run it (default)     s  skip it     q  stop the walkthrough'
+  if ($ws.DryRun) { Write-UiLine '  DRY-RUN: every step only reports what it would remove.' 'Magenta' }
+  $dev = 'off'
+  if ($ws.Developer) { $dev = 'on' }
+  Write-Note "developer mode: $dev   idle window: $($ws.Days) days   temp window: $($ws.TempDays) days"
+  Write-Note "logs and reports: $($ws.Home)"
+  Write-Note "by $Script:WS_AUTHOR - $Script:WS_WEB"
+  Wait-Enter
+}
+
+function Invoke-Walkthrough {
+  $ws = $Script:WS
+  if (-not $ws.Interactive) {
+    Write-Err 'The walkthrough needs an interactive console. For unattended runs use:  windowsweep --all --yes   (or --scan / --dry-run to look first)'
+    $ws.ExitCode = $Script:WS_EXIT_USAGE
+    return
+  }
+  Show-Welcome
+  Write-Box 'Pre-scan' 'Read-only - what each section can reach right now'
+  if (Get-Command Invoke-Section00 -ErrorAction SilentlyContinue) { Invoke-Section00 }
+  $null = Show-ScanTable
+  Wait-Enter
+
+  $steps = @($Script:WS_WALKTHROUGH)
+  if ($ws.IsAdmin) { $steps += $Script:WS_WALKTHROUGH_ADMIN }
+  $total = $steps.Count + 2
+  $n = 0
+  $quit = $false
+  foreach ($id in $steps) {
+    $n++
+    $sec = Get-Section $id
+    Write-Step -N $n -Total $total -Title $sec.Title
+    $choice = Read-Choice -Prompt '  action: a run   s skip   q quit  > ' -Default 'a'
+    if ($choice -eq 'q') { Write-Warn 'walkthrough stopped'; Add-ReportStep -Section $id -Title $sec.Title -Status 'skipped' -Note 'quit'; $quit = $true; break }
+    if ($choice -eq 's') { Write-Info 'skipped'; Add-ReportStep -Section $id -Title $sec.Title -Status 'skipped'; continue }
+    $ws.SectionPreConfirmed = $true
+    try { Invoke-SectionById -Id $id } finally { $ws.SectionPreConfirmed = $false }
+  }
+  if (-not $quit -and -not $ws.IsAdmin) {
+    $n++
+    Write-Step -N $n -Total $total -Title 'System-level cleanup (needs Administrator)'
+    Write-Plain '  Sections 12 (Windows Update cache), 13 (Disk Cleanup engine) and 14 (component store) need an elevated'
+    Write-Plain '  console. Run them afterwards with:'
+    Write-Plain '      windowsweep --profile system --yes --elevate'
+    Write-Plain '  and, if you want the hibernation file gone too (section 15):'
+    Write-Plain '      windowsweep --only 12,13,14,15 --hiberfil off --yes --i-understand-deep --elevate'
+    $ws.Hints += 'Admin sections:  windowsweep --profile system --yes --elevate'
+    Wait-Enter
+  }
+  if (-not $quit) {
+    $n++
+    Write-Step -N $n -Total $total -Title 'Disk usage report'
+    Invoke-SectionById -Id 21
+  }
+  Show-SessionSummary
+  Show-NextSteps
+}
+
+function Show-NextSteps {
+  $ws = $Script:WS
+  $tips = @()
+  if (-not (Get-ScheduledTask -TaskName $Script:WS_TASK_NAME -ErrorAction SilentlyContinue)) { $tips += 'Schedule the safe batch weekly:   windowsweep --install-task' }
+  $tips += 'Browse or export past reports:    windowsweep --reports'
+  if ($ws.DryRun) { $tips += 'This was a dry-run. Run the same command without --dry-run to reclaim the space.' }
+  if ($tips.Count -gt 0) {
+    Write-UiLine '' 'Gray'
+    Write-Info 'next steps:'
+    foreach ($t in $tips) { Write-Note $t }
+  }
+}

package/modules/windows_user.ps1

@@ -0,0 +1,112 @@
+# windows_user.ps1 - section 9 (Windows user caches), section 10 (user temp), section 11 (Recycle Bin).
+
+function Get-Targets09 {
+  $P = $Script:P
+  return @(
+    (New-Target 9 'Internet cache (INetCache)' "$($P.L)\Microsoft\Windows\INetCache" -Mode clear -Note 'IE / legacy WebView cache')
+    (New-Target 9 'Windows Error Reporting (user)' "$($P.L)\Microsoft\Windows\WER" -Mode clear)
+    (New-Target 9 'Crash dumps' "$($P.L)\CrashDumps" -Mode clear-old -Days 7)
+    (New-Target 9 'DirectX shader cache' "$($P.L)\D3DSCache" -Mode clear)
+    (New-Target 9 'NVIDIA DirectX shader cache' "$($P.L)\NVIDIA\DXCache" -Mode clear)
+    (New-Target 9 'NVIDIA OpenGL shader cache' "$($P.L)\NVIDIA\GLCache" -Mode clear)
+    (New-Target 9 'NVIDIA NV_Cache' "$($P.L)\NVIDIA Corporation\NV_Cache" -Mode clear)
+    (New-Target 9 'AMD DirectX shader cache' "$($P.L)\AMD\DxCache" -Mode clear)
+    (New-Target 9 'AMD OpenGL shader cache' "$($P.L)\AMD\GLCache" -Mode clear)
+    (New-Target 9 'Intel shader cache' "$($P.L)\Intel\ShaderCache" -Mode clear)
+    (New-Target 9 'Remote Desktop bitmap cache' "$($P.L)\Microsoft\Terminal Server Client\Cache" -Mode clear)
+    (New-Target 9 'OneDrive logs' "$($P.L)\Microsoft\OneDrive\logs" -Mode clear-old -Days 7)
+    (New-Target 9 'OneDrive setup logs' "$($P.L)\Microsoft\OneDrive\setup\logs" -Mode clear-old -Days 7)
+    (New-Target 9 'Store apps TempState' "$($P.L)\Packages\*\TempState" -Kind glob -Mode clear)
+    (New-Target 9 'Store apps AC\Temp' "$($P.L)\Packages\*\AC\Temp" -Kind glob -Mode clear)
+    (New-Target 9 'Store apps AC\INetCache' "$($P.L)\Packages\*\AC\INetCache" -Kind glob -Mode clear)
+    (New-Target 9 'Themes cached files' "$($P.L)\Microsoft\Windows\Themes\CachedFiles" -Mode clear)
+    (New-Target 9 'PowerShell startup profile data' "$($P.L)\Microsoft\Windows\PowerShell\StartupProfileData-*" -Kind fileglob -Mode file)
+    (New-Target 9 'CLR usage logs' "$($P.L)\Microsoft\CLR_v4.0\UsageLogs" -Mode clear)
+    (New-Target 9 'CLR usage logs (32-bit)' "$($P.L)\Microsoft\CLR_v4.0_32\UsageLogs" -Mode clear)
+    (New-Target 9 'Explorer thumbcache leftovers' "$($P.L)\Microsoft\Windows\Explorer\ThumbCacheToDelete" -Mode clear)
+    (New-Target 9 'Explorer iconcache leftovers' "$($P.L)\Microsoft\Windows\Explorer\IconCacheToDelete" -Mode clear)
+    (New-Target 9 'Explorer startup logs' "$($P.L)\Microsoft\Windows\Explorer\ExplorerStartupLog*.etl" -Kind fileglob -Mode file)
+    (New-Target 9 'Windows schema cache' "$($P.L)\Microsoft\Windows\SchCache" -Mode clear)
+    (New-Target 9 'Delivery Optimization (per user)' "$($P.L)\Microsoft\Windows\DeliveryOptimization\Cache" -Mode clear)
+    (New-Target 9 'Certificate URL cache' "$($P.LL)\Microsoft\CryptnetUrlCache" -Mode clear)
+    (New-Target 9 'Diagnostics results' "$($P.L)\Diagnostics" -Mode clear-old -Days 30)
+    (New-Target 9 'DNS resolver cache' 'ipconfig /flushdns' -Kind cmd)
+  )
+}
+
+function Invoke-Section09 {
+  Write-SectionIntro @(
+    'Caches Windows and its drivers rebuild silently: shader caches, error-report queues, crash dumps, Store-app',
+    'temp folders, Remote Desktop bitmaps. Files an app is holding open are skipped. The Explorer thumbnail and',
+    'icon databases themselves belong to Disk Cleanup (section 13, admin), which rebuilds them cleanly.'
+  )
+  $targets = Get-Targets09
+  $null = Show-TargetSizes $targets
+  if (-not (Confirm-Section 'Clear Windows user caches now?')) { Write-Info 'skipped'; return }
+  $null = Invoke-TargetList $targets
+  $r = Invoke-External -FilePath 'ipconfig.exe' -ArgumentList @('/flushdns') -Destructive -Quiet -Label 'ipconfig /flushdns'
+  if ($r.Ran -and $r.ExitCode -eq 0) { Write-Ok 'DNS resolver cache flushed' }
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 10 - user temp
+# ---------------------------------------------------------------------------------------------
+
+function Get-TempRoots {
+  $P = $Script:P
+  $roots = @()
+  foreach ($r in @($P.TEMP, $P.TMP, (Join-Path $P.L 'Temp'), (Join-Path $P.LL 'Temp'))) {
+    if ($r -and (Test-DirPresent $r)) { $f = Get-FullPath $r; if ($roots -notcontains $f) { $roots += $f } }
+  }
+  return $roots
+}
+
+function Get-Targets10 {
+  $t = @()
+  foreach ($r in (Get-TempRoots)) { $t += (New-Target 10 'User temp' $r -Mode prune -Days $Script:WS.TempDays -Note "files idle $($Script:WS.TempDays)+ days; open files are skipped") }
+  return $t
+}
+
+function Invoke-Section10 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    "Temporary files idle for $($ws.TempDays)+ days. Files a running program still has open are skipped, so an",
+    'installer or build that is in progress right now is safe. Lower the window with --temp-days 1 for a harder sweep.'
+  )
+  $targets = @(Get-Targets10)
+  if ($targets.Count -eq 0) { Write-Info 'no temp folders found'; return }
+  $null = Show-TargetSizes $targets
+  if (-not (Confirm-Section "Remove temp files idle $($ws.TempDays)+ days?")) { Write-Info 'skipped'; return }
+  $null = Invoke-TargetList $targets
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 11 - Recycle Bin
+# ---------------------------------------------------------------------------------------------
+
+function Get-Targets11 { return @((New-Target 11 'Recycle Bin (all drives)' 'Clear-RecycleBin' -Kind cmd -Note 'PERMANENT - everything in the bin is gone')) }
+
+function Get-RecycleBinStats {
+  $items = 0; $bytes = [long]0
+  try {
+    $shell = New-Object -ComObject Shell.Application
+    $bin = $shell.NameSpace(0xA)
+    foreach ($i in $bin.Items()) { $items++; try { $bytes += [long]$i.Size } catch { $null = $_ } }
+  } catch { $null = $_ }
+  return [pscustomobject]@{ Items = $items; Bytes = $bytes }
+}
+
+function Invoke-Section11 {
+  $ws = $Script:WS
+  Write-SectionIntro @('Emptying the Recycle Bin is permanent: nothing in it can be restored afterwards.')
+  $s = Get-RecycleBinStats
+  Write-Kv 'Recycle Bin:' ("{0} item(s), {1}" -f $s.Items, (Format-Bytes $s.Bytes))
+  if ($s.Items -eq 0) { Write-Info 'already empty'; return }
+  if ($ws.DryRun) { Write-DryRun ("would empty the Recycle Bin (" + (Format-Bytes $s.Bytes) + ')'); Add-Freed $s.Bytes; return }
+  if (-not (Confirm-Ui -Prompt "Permanently delete all $($s.Items) item(s) in the Recycle Bin?" -Default 'n')) { Write-Info 'skipped'; return }
+  try {
+    Clear-RecycleBin -Force -ErrorAction Stop
+    Add-Freed $s.Bytes
+    Write-Ok ("Recycle Bin emptied (" + (Format-Bytes $s.Bytes) + ')')
+  } catch { Write-Err "could not empty the Recycle Bin: $($_.Exception.Message)" }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "windowsweep",
+  "version": "1.0.0",
+  "description": "Safe-by-default Windows cleanup CLI - developer-aware, dry-run first, zero install via npx.",
+  "bin": {
+    "windowsweep": "bin/windowsweep.js"
+  },
+  "scripts": {
+    "start": "node bin/windowsweep.js",
+    "test": "node bin/windowsweep.js --self-test --no-color",
+    "dry-run": "node bin/windowsweep.js --dry-run --all --yes --no-color --no-report",
+    "list": "node bin/windowsweep.js --list",
+    "lint:syntax": "node -c bin/windowsweep.js && node bin/windowsweep.js --self-test --no-color --no-report",
+    "version:check": "node -e \"const fs=require('fs');const v=require('./package.json').version;const c=fs.readFileSync('lib/constants.ps1','utf8');const f=fs.readFileSync('VERSION','utf8').trim();if(!c.includes(\\\"WS_VERSION_FALLBACK = '\\\"+v+\\\"'\\\")||f!==v){console.error('version mismatch: package.json '+v+' VERSION '+f);process.exit(1)}console.log('version parity OK: '+v)\"",
+    "prepublishOnly": "npm run --silent version:check && node -c bin/windowsweep.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "modules/",
+    "windowsweep.ps1",
+    "windowsweep.cmd",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "VERSION"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "os": [
+    "win32"
+  ],
+  "keywords": [
+    "windows",
+    "cleanup",
+    "disk-cleanup",
+    "cache-cleanup",
+    "disk-space",
+    "temp-files",
+    "node-modules",
+    "npm-cache",
+    "yarn-cache",
+    "developer-tools",
+    "powershell",
+    "cli",
+    "dry-run"
+  ],
+  "author": {
+    "name": "Ahsan Mahmood",
+    "email": "aoneahsan@gmail.com",
+    "url": "https://aoneahsan.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/aoneahsan/windowsweep",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aoneahsan/windowsweep.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aoneahsan/windowsweep/issues",
+    "email": "aoneahsan@gmail.com"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://aoneahsan.com/payment?project-id=windowsweep&project-identifier=windowsweep"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": true
+}

package/windowsweep.cmd

@@ -0,0 +1,6 @@
+@echo off
+rem windowsweep - launcher for users without Node. Same engine, same flags: windowsweep.cmd --help
+setlocal
+if not defined WINDOWSWEEP_LAUNCHER set "WINDOWSWEEP_LAUNCHER=cmd"
+"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0windowsweep.ps1" %*
+exit /b %ERRORLEVEL%

package/windowsweep.ps1

@@ -0,0 +1,292 @@
+# windowsweep - safe, developer-aware Windows cleanup CLI. Entry point.
+#
+#   windowsweep.ps1                (guided walkthrough)
+#   windowsweep.ps1 --help         (every mode and option)
+#
+# Runs on Windows PowerShell 5.1 and PowerShell 7. Flags are parsed from $args (no param block) so
+# GNU-style options survive `powershell -File`. Source is ASCII-only by design.
+#
+# Author:  Ahsan Mahmood <aoneahsan@gmail.com>  https://aoneahsan.com
+# License: MIT (see LICENSE)
+
+$ErrorActionPreference = 'Continue'
+$Script:WS_ROOT = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+$Script:WS = @{
+  Mode = 'walkthrough'; RawArgs = @($args); ScriptPath = $MyInvocation.MyCommand.Path
+  DryRun = $false; Yes = $false; Deep = $false; Elevate = $false; ElevatedChild = $false; BatchMode = $false
+  Days = $null; TempDays = $null; LargeFileMb = $null; PurgeAll = $false
+  DeveloperFlag = $null; ForgetDeveloper = $false; Developer = $null; DeveloperSource = ''
+  ScanRoots = @(); ExcludePaths = @(); Hiberfil = ''; ResetBase = $false; Permanent = $false
+  OnlyList = ''; Profile = ''; Exclude = ''; ExportFmt = 'both'; ExportId = 'latest'; PruneDays = 90
+  LogsDir = ''; ReportsDir = ''; NoReport = $false; CleanupLogs = $false
+  JsonMode = $false; Quiet = $false; NoColor = $false; Ascii = $false
+  TotalFreed = [long]0; TotalEstimated = [long]0; SectionFreed = [long]0
+  Refusals = @(); Hints = @(); ExitCode = 0; Finished = $false; AllowOwnData = $false
+}
+
+foreach ($lib in @('constants', 'ui', 'log', 'fs', 'safety', 'config', 'scan', 'actions')) {
+  . (Join-Path $Script:WS_ROOT "lib\$lib.ps1")
+}
+foreach ($m in (Get-ChildItem -LiteralPath (Join-Path $Script:WS_ROOT 'modules') -Filter '*.ps1' | Sort-Object Name)) {
+  . $m.FullName
+}
+
+function Show-Usage {
+  $v = Get-ToolVersion
+  $text = @"
+$Script:WS_NAME v$v - safe, developer-aware Windows cleanup
+
+USAGE
+  windowsweep [mode] [options]
+
+MODES  (default = guided walkthrough through every category)
+  -w, --walkthrough     Guided walkthrough, asks before every step
+  -m, --menu            Jump-to menu - run one section at a time
+  -a, --all             Safe batch: sections $($Script:WS_SAFE_BATCH -join ',') (+12,13 when elevated)
+  -s, --scan            Read-only: every target with its size, nothing deleted
+      --only L          Run exactly these sections, e.g. --only 1,3,5-7
+      --profile NAME    dev | minimal | cache-only | system | deep | audit
+      --exclude L       Drop sections from --all / --profile
+      --list            Print the section catalogue and exit
+      --list-targets    Print every path the tool can touch (read-only)
+      --self-test       Verify syntax, safety guards, dry-run and junction handling
+      --reports         Reports manager: list / view / export past runs
+      --export F [ID]   Export a report: F = md | html | both, ID = N | latest | all
+      --stats           Run history from ~\.windowsweep
+      --prune-history N Delete logs + reports older than N days (default 90)
+      --feedback        How to report a bug (offline; nothing is sent)
+      --report-issue    Open a pre-filled GitHub issue in your browser (you review it first)
+      --debug-bundle    Zip the latest log + report for a bug report
+      --install-task    Weekly Scheduled Task (Sunday 03:00, safe batch)   --uninstall-task
+      --install-alias   Add a 'cleanup' function to your PowerShell profile   --uninstall-alias
+      --uninstall-data  Remove ~\.windowsweep (logs, reports, config) after confirming
+  -V, --version         Version and author        -h, --help   This text
+
+OPTIONS
+      --dry-run         Delete nothing; show what would go and how much it frees
+  -y, --yes             Auto-confirm regenerable-cache steps (never personal files)
+      --i-understand-deep  Allow deep sections (11 Recycle Bin, 15 hibernation, 16 event logs,
+                        20 disk-image compaction) to run unattended with --yes
+      --elevate         Relaunch elevated (UAC prompt) so admin sections can run
+  -d, --days N          Idle threshold for caches (default 100). A file goes only when its newest
+                        timestamp (write, access, creation) is at least N days old
+      --temp-days N     Idle threshold for %TEMP% (default 3)
+      --purge-all       Clear cache targets completely instead of pruning idle files
+      --developer / --not-developer   Override the saved developer answer for this run
+      --forget-developer   Ask the developer question again
+      --scan-roots "P1;P2"   Project roots for section 17     --exclude-path P   (repeatable)
+      --large-file-mb N    Minimum size for section 19 (default 100)
+      --hiberfil off|reduced|keep   What section 15 does       --reset-base   DISM /ResetBase in 14
+      --permanent       Sections 18/19 delete instead of using the Recycle Bin
+      --logs-dir P / --reports-dir P / --no-report / --cleanup-logs
+      --json            One-line JSON summary on stdout (everything else on stderr)
+  -q, --quiet           Less chatter     --no-color     --ascii (plain glyphs)
+
+SAFETY
+  Every deletion passes one chokepoint that refuses drive roots, Windows, Program Files, your
+  profile root, Documents/Pictures/Desktop, credentials, toolchains and browser/editor state, and
+  that never follows a junction or symlink. Personal-file sections are interactive only and use the
+  Recycle Bin. --scan and --dry-run change nothing. No network calls, ever.
+
+OUTPUT
+  Logs:    $($Script:WS.LogsDir)
+  Reports: $($Script:WS.ReportsDir)
+
+$Script:WS_NAME v$v  by $Script:WS_AUTHOR <$Script:WS_EMAIL>  $Script:WS_WEB
+$Script:WS_REPO  -  $Script:WS_LICENSE
+"@
+  Write-Host $text
+}
+
+function Get-NextArg {
+  param([string[]] $Argv, [ref] $Index, [string] $Name)
+  $Index.Value++
+  if ($Index.Value -ge $Argv.Count) { throw "option $Name needs a value" }
+  return [string]$Argv[$Index.Value]
+}
+
+function Read-Arguments {
+  $ws = $Script:WS
+  $argv = @($ws.RawArgs)
+  $i = 0
+  while ($i -lt $argv.Count) {
+    $a = [string]$argv[$i]
+    $inline = $null
+    if ($a -match '^(--[A-Za-z][A-Za-z0-9-]*)=(.*)$') { $a = $Matches[1]; $inline = $Matches[2] }
+    switch ($a) {
+      { $_ -in '-w', '--walkthrough' } { $ws.Mode = 'walkthrough' }
+      { $_ -in '-m', '--menu', '-i', '--interactive' } { $ws.Mode = 'menu' }
+      { $_ -in '-a', '--all', '--all-safe' } { $ws.Mode = 'all'; $ws.BatchMode = $true }
+      { $_ -in '-s', '--scan' } { $ws.Mode = 'scan' }
+      '--only' { $ws.Mode = 'only'; $ws.BatchMode = $true; if ($null -ne $inline) { $ws.OnlyList = $inline } else { $ws.OnlyList = Get-NextArg $argv ([ref]$i) $a } }
+      '--profile' { $ws.Mode = 'only'; $ws.BatchMode = $true; if ($null -ne $inline) { $ws.Profile = $inline } else { $ws.Profile = Get-NextArg $argv ([ref]$i) $a } }
+      '--exclude' { if ($null -ne $inline) { $ws.Exclude = $inline } else { $ws.Exclude = Get-NextArg $argv ([ref]$i) $a } }
+      '--list' { $ws.Mode = 'list' }
+      '--list-targets' { $ws.Mode = 'list_targets' }
+      '--self-test' { $ws.Mode = 'self_test' }
+      '--reports' { $ws.Mode = 'reports' }
+      '--export' {
+        $ws.Mode = 'export'
+        if ($null -ne $inline) { $ws.ExportFmt = $inline } elseif (($i + 1) -lt $argv.Count -and -not ([string]$argv[$i + 1]).StartsWith('-')) { $i++; $ws.ExportFmt = [string]$argv[$i] }
+        if (($i + 1) -lt $argv.Count -and -not ([string]$argv[$i + 1]).StartsWith('-')) { $i++; $ws.ExportId = [string]$argv[$i] }
+      }
+      '--stats' { $ws.Mode = 'stats' }
+      '--prune-history' {
+        $ws.Mode = 'prune_history'
+        if ($null -ne $inline) { $ws.PruneDays = [int]$inline } elseif (($i + 1) -lt $argv.Count -and ([string]$argv[$i + 1]) -match '^\d+$') { $i++; $ws.PruneDays = [int]$argv[$i] }
+      }
+      '--feedback' { $ws.Mode = 'feedback' }
+      { $_ -in '--report-issue', '--report-bug' } { $ws.Mode = 'report_issue' }
+      '--debug-bundle' { $ws.Mode = 'debug_bundle' }
+      '--install-task' { $ws.Mode = 'install_task' }
+      '--uninstall-task' { $ws.Mode = 'uninstall_task' }
+      '--install-alias' { $ws.Mode = 'install_alias' }
+      '--uninstall-alias' { $ws.Mode = 'uninstall_alias' }
+      '--uninstall-data' { $ws.Mode = 'uninstall_data' }
+      { $_ -in '-V', '--version' } { $ws.Mode = 'version' }
+      { $_ -in '-h', '--help', '/?', '-?' } { $ws.Mode = 'help' }
+      { $_ -in '-n', '--dry-run' } { $ws.DryRun = $true }
+      { $_ -in '-y', '--yes' } { $ws.Yes = $true }
+      '--i-understand-deep' { $ws.Deep = $true }
+      '--elevate' { $ws.Elevate = $true }
+      '--elevated-child' { $ws.ElevatedChild = $true }
+      { $_ -in '-d', '--days' } { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; if ($v -notmatch '^\d+$') { throw "--days needs a whole number, got '$v'" }; $ws.Days = [int]$v }
+      '--temp-days' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; if ($v -notmatch '^\d+$') { throw "--temp-days needs a whole number, got '$v'" }; $ws.TempDays = [int]$v }
+      '--purge-all' { $ws.PurgeAll = $true }
+      '--developer' { $ws.DeveloperFlag = $true }
+      { $_ -in '--not-developer', '--no-developer' } { $ws.DeveloperFlag = $false }
+      '--forget-developer' { $ws.ForgetDeveloper = $true }
+      '--scan-roots' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; $ws.ScanRoots = @($v -split ';' | ForEach-Object { $_.Trim() } | Where-Object { $_ }) }
+      '--exclude-path' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; $ws.ExcludePaths += $v }
+      '--large-file-mb' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; if ($v -notmatch '^\d+$') { throw "--large-file-mb needs a whole number, got '$v'" }; $ws.LargeFileMb = [int]$v }
+      '--hiberfil' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; if ($v -notin 'off', 'reduced', 'keep') { throw "--hiberfil must be off, reduced or keep" }; $ws.Hiberfil = $v }
+      '--reset-base' { $ws.ResetBase = $true }
+      '--permanent' { $ws.Permanent = $true }
+      '--logs-dir' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; $ws.LogsDir = $v }
+      '--reports-dir' { $v = $inline; if ($null -eq $v) { $v = Get-NextArg $argv ([ref]$i) $a }; $ws.ReportsDir = $v }
+      '--no-report' { $ws.NoReport = $true }
+      '--cleanup-logs' { $ws.CleanupLogs = $true }
+      '--json' { $ws.JsonMode = $true; $ws.Quiet = $true }
+      { $_ -in '-q', '--quiet' } { $ws.Quiet = $true }
+      '--no-color' { $ws.NoColor = $true }
+      '--ascii' { $ws.Ascii = $true }
+      '--pwsh' { }
+      default { throw "unknown argument: $a" }
+    }
+    $i++
+  }
+  if ($ws.Profile -and -not $Script:WS_PROFILES.ContainsKey($ws.Profile)) {
+    throw "unknown profile '$($ws.Profile)' (known: $($Script:WS_PROFILES.Keys -join ', '))"
+  }
+}
+
+function Initialize-Paths {
+  $ws = $Script:WS
+  $ws.Stamp = (Get-Date -Format 'yyyy-MM-dd_HHmmss') + '-' + $PID
+  $dataHome = $env:WINDOWSWEEP_HOME
+  if ([string]::IsNullOrWhiteSpace($dataHome)) { $dataHome = Join-Path $env:USERPROFILE ".$Script:WS_NAME" }
+  $ws.Home = Get-FullPath $dataHome
+  if (-not $ws.LogsDir) { $ws.LogsDir = $env:WINDOWSWEEP_LOG_DIR }
+  if (-not $ws.LogsDir) { $ws.LogsDir = Join-Path $ws.Home 'logs' }
+  if (-not $ws.ReportsDir) { $ws.ReportsDir = $env:WINDOWSWEEP_REPORTS_DIR }
+  if (-not $ws.ReportsDir) { $ws.ReportsDir = Join-Path $ws.Home 'reports' }
+  $ws.LogsDir = Get-FullPath $ws.LogsDir
+  $ws.ReportsDir = Get-FullPath $ws.ReportsDir
+  $ws.FeedbackDir = Join-Path $ws.Home 'feedback'
+  $ws.ConfigPath = Join-Path $ws.Home 'config.json'
+  $ws.Launcher = $env:WINDOWSWEEP_LAUNCHER
+  if (-not $ws.Launcher) { $ws.Launcher = 'powershell' }
+  # Well-known roots used by every module. LL = LocalLow, SR = SystemRoot, PD = ProgramData, SD = system drive.
+  $Script:P = @{
+    U = (Get-FullPath $env:USERPROFILE); L = (Get-FullPath $env:LOCALAPPDATA); A = (Get-FullPath $env:APPDATA)
+    LL = (Get-FullPath (Join-Path (Split-Path -Parent $env:LOCALAPPDATA) 'LocalLow')); SR = (Get-FullPath $env:SystemRoot)
+    PD = (Get-FullPath $env:ProgramData); SD = $env:SystemDrive; TEMP = (Get-FullPath $env:TEMP); TMP = (Get-FullPath $env:TMP)
+    PF = (Get-FullPath $env:ProgramFiles); PF86 = (Get-FullPath ${env:ProgramFiles(x86)})
+  }
+  $ws.Npx = ($env:WINDOWSWEEP_NPX -eq '1')
+  $ws.IsAdmin = Test-IsAdmin
+  try { $ws.OsCaption = (Get-CimInstance Win32_OperatingSystem -ErrorAction Stop).Caption } catch { $ws.OsCaption = 'Windows' }
+}
+
+function Initialize-Settings {
+  <# .SYNOPSIS Merge config defaults under explicit flags. #>
+  $ws = $Script:WS
+  $cfg = Import-Config
+  if ($null -eq $ws.Days) { $ws.Days = [int]$cfg.days }
+  if ($null -eq $ws.TempDays) { $ws.TempDays = [int]$cfg.tempDays }
+  if ($null -eq $ws.LargeFileMb) { $ws.LargeFileMb = [int]$cfg.largeFileMb }
+  if ($ws.ScanRoots.Count -eq 0 -and $cfg.scanRoots) { $ws.ScanRoots = @($cfg.scanRoots) }
+  if ($cfg.excludePaths) { $ws.ExcludePaths = @($ws.ExcludePaths) + @($cfg.excludePaths) }
+}
+
+function Invoke-Main {
+  $ws = $Script:WS
+  switch ($ws.Mode) {
+    'help' { Show-Usage; return }
+    'version' { Show-Version; return }
+    'list' { Show-SectionList; return }
+    'list_targets' { Show-TargetList; return }
+    'self_test' { $ws.ExitCode = Invoke-SelfTest; return }
+    'scan' { Invoke-ScanMode; return }
+    'all' { Invoke-BatchMode; return }
+    'only' { Invoke-BatchMode; return }
+    'walkthrough' { Invoke-Walkthrough; return }
+    'menu' { Invoke-Menu; return }
+    'reports' { Invoke-ReportsManager; return }
+    'export' { $ws.ExitCode = Export-Reports -Format $ws.ExportFmt -Id $ws.ExportId; return }
+    'stats' { Show-Stats; return }
+    'prune_history' { Remove-OldHistory -Days $ws.PruneDays; return }
+    'feedback' { Show-Feedback; return }
+    'report_issue' { Invoke-ReportIssue; return }
+    'debug_bundle' { New-DebugBundle; return }
+    'install_task' { Install-WeeklyTask; return }
+    'uninstall_task' { Uninstall-WeeklyTask; return }
+    'install_alias' { Install-ProfileAlias; return }
+    'uninstall_alias' { Uninstall-ProfileAlias; return }
+    'uninstall_data' { Remove-ToolData; return }
+    default { Write-Err "unknown mode: $($ws.Mode)"; $ws.ExitCode = $Script:WS_EXIT_USAGE }
+  }
+}
+
+# ---------------------------------------------------------------------------------------------
+# Bootstrap
+# ---------------------------------------------------------------------------------------------
+try {
+  Read-Arguments
+} catch {
+  [Console]::Error.WriteLine("windowsweep: $($_.Exception.Message)")
+  [Console]::Error.WriteLine("try: windowsweep --help")
+  exit 2
+}
+Initialize-Paths
+Initialize-Ui
+Initialize-Safety
+$quietModes = @('help', 'version', 'list')
+if ($Script:WS.Mode -notin $quietModes) { Initialize-Log }
+Initialize-Settings
+Initialize-Report
+Initialize-CrashTrap
+
+if ($Script:WS.Elevate -and -not $Script:WS.IsAdmin) {
+  $code = Invoke-Elevated
+  Restore-Ui
+  exit $code
+}
+if ($Script:WS.Elevate -and $Script:WS.IsAdmin) { Write-Note 'already elevated; --elevate is a no-op' }
+
+if ($Script:WS.Mode -in @('walkthrough', 'menu', 'all', 'only')) { Resolve-DeveloperMode }
+
+try {
+  Invoke-Main
+  $Script:WS.Finished = $true
+} catch {
+  Invoke-CrashBundle -ErrorRecord $_
+  $Script:WS.ExitCode = $Script:WS_EXIT_FAIL
+} finally {
+  Restore-Ui
+  if ($Script:WS.CleanupLogs -and $Script:WS.LogFile -and (Test-Path -LiteralPath $Script:WS.LogFile)) {
+    try { Remove-Item -LiteralPath $Script:WS.LogFile -Force -ErrorAction SilentlyContinue } catch { $null = $_ }
+  }
+}
+exit $Script:WS.ExitCode