windowsweep 1.0.0

package/modules/reports.ps1

@@ -0,0 +1,212 @@
+# reports.ps1 - list, view, export (Markdown / HTML) and summarise past JSON reports. No external tools needed.
+
+function Get-ReportFiles {
+  $dir = $Script:WS.ReportsDir
+  if (-not (Test-Path -LiteralPath $dir)) { return @() }
+  return @(Get-ChildItem -LiteralPath $dir -Filter 'report-*.json' -File -ErrorAction SilentlyContinue | Sort-Object Name -Descending)
+}
+
+function Read-Report {
+  param([string] $Path)
+  try { return (Get-Content -LiteralPath $Path -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop) } catch { return $null }
+}
+
+function Show-ReportList {
+  $files = @(Get-ReportFiles)
+  if ($files.Count -eq 0) { Write-Info 'no reports yet - run a cleanup first'; return @() }
+  Write-UiLine ("  {0,3}  {1,-34} {2,8}  {3,-17} {4,-12} {5}" -f '#', 'REPORT', 'SIZE', 'STARTED', 'RECLAIMED', 'MODE') 'White'
+  $i = 1
+  foreach ($f in $files) {
+    $r = Read-Report $f.FullName
+    $started = '?'; $rec = '?'; $mode = '?'
+    if ($r) {
+      $started = ([string]$r.meta.started_at).Substring(0, [math]::Min(16, ([string]$r.meta.started_at).Length)).Replace('T', ' ')
+      $rec = $r.totals.total_reclaimed_human
+      if ($r.meta.dry_run) { $rec = "~$($r.totals.total_estimated_human) (dry)" }
+      $mode = $r.meta.mode
+    }
+    Write-UiLine ("  {0,3}  {1,-34} {2,8}  {3,-17} {4,-12} {5}" -f $i, $f.Name, (Format-Bytes $f.Length), $started, $rec, $mode) 'Gray'
+    $i++
+  }
+  return $files
+}
+
+function ConvertTo-HtmlText { param([string] $Text) return [System.Net.WebUtility]::HtmlEncode([string]$Text) }
+
+function Convert-ReportToMarkdown {
+  param([string] $Json, [string] $Out = '')
+  $r = Read-Report $Json
+  if (-not $r) { Write-Err "cannot read $Json"; return $null }
+  if (-not $Out) { $Out = [IO.Path]::ChangeExtension($Json, '.md') }
+  $dry = 'no'
+  if ($r.meta.dry_run) { $dry = 'yes' }
+  $l = @()
+  $l += "# $Script:WS_NAME session report"; $l += ''
+  $l += "_Generated from ``$([IO.Path]::GetFileName($Json))``_"; $l += ''
+  $l += '## Overview'; $l += ''; $l += '| Field | Value |'; $l += '|---|---|'
+  $l += "| Started | $($r.meta.started_at) |"; $l += "| Finished | $($r.meta.finished_at) |"; $l += "| Duration | $($r.meta.duration_seconds) s |"
+  $l += "| Host | $($r.meta.host) |"; $l += "| User | $($r.meta.user) |"; $l += "| Windows | $($r.meta.os) |"; $l += "| Mode | $($r.meta.mode) |"
+  $l += "| Dry-run | $dry |"; $l += "| Elevated | $($r.meta.elevated) |"; $l += "| Developer mode | $($r.meta.developer_mode) |"; $l += "| Idle window | $($r.meta.idle_days) days |"
+  $l += ''; $l += '## Result'; $l += ''
+  if ($r.meta.dry_run) { $l += "**Would free (estimate): $($r.totals.total_estimated_human)**  " } else { $l += "**Reclaimed: $($r.totals.total_reclaimed_human)** ($($r.totals.total_reclaimed_bytes) bytes)  " }
+  $l += "Sections run: $($r.totals.steps_run) - skipped/refused: $($r.totals.steps_skipped)"; $l += ''
+  $l += '## Drives'; $l += ''; $l += '| Drive | Before free | After free | Size |'; $l += '|---|---|---|---|'
+  foreach ($b in $r.disk.before) {
+    $a = $r.disk.after | Where-Object { $_.drive -eq $b.drive } | Select-Object -First 1
+    $afterFree = '?'
+    if ($a) { $afterFree = Format-Bytes $a.free_bytes }
+    $l += "| $($b.drive) | $(Format-Bytes $b.free_bytes) | $afterFree | $(Format-Bytes $b.size_bytes) |"
+  }
+  $l += ''; $l += '## Steps'; $l += ''; $l += '| # | Section | Title | Status | Freed |'; $l += '|---:|---:|---|---|---:|'
+  foreach ($s in $r.steps) { $l += "| $($s.n) | $($s.section) | $($s.title) | $($s.status) | $(Format-Bytes $s.freed_bytes) |" }
+  $l += ''; $l += "_${Script:WS_NAME} v$($r.meta.tool_version) by $($r.credits.author.name) - $($r.credits.tool_homepage)_"
+  [IO.File]::WriteAllLines($Out, $l)
+  Write-Ok "wrote $Out"
+  return $Out
+}
+
+function Convert-ReportToHtml {
+  param([string] $Json, [string] $Out = '')
+  $r = Read-Report $Json
+  if (-not $r) { Write-Err "cannot read $Json"; return $null }
+  if (-not $Out) { $Out = [IO.Path]::ChangeExtension($Json, '.html') }
+  $headline = "Reclaimed"; $big = $r.totals.total_reclaimed_human
+  if ($r.meta.dry_run) { $headline = 'Would free (dry-run estimate)'; $big = $r.totals.total_estimated_human }
+  $rows = ''
+  foreach ($s in $r.steps) {
+    $cls = ([string]$s.status) -replace '[^a-z-]', ''
+    $rows += "<tr class=`"row-$cls`"><td>$($s.n)</td><td>$($s.section)</td><td>$(ConvertTo-HtmlText $s.title)</td><td><span class=`"badge $cls`">$(ConvertTo-HtmlText $s.status)</span></td><td class=`"num`">$(ConvertTo-HtmlText (Format-Bytes $s.freed_bytes))</td></tr>`n"
+  }
+  $drives = ''
+  foreach ($b in $r.disk.before) {
+    $a = $r.disk.after | Where-Object { $_.drive -eq $b.drive } | Select-Object -First 1
+    $afterFree = '?'
+    if ($a) { $afterFree = Format-Bytes $a.free_bytes }
+    $drives += "<tr><td>$(ConvertTo-HtmlText $b.drive)</td><td class=`"num`">$(Format-Bytes $b.size_bytes)</td><td class=`"num`">$(Format-Bytes $b.free_bytes)</td><td class=`"num`">$afterFree</td></tr>`n"
+  }
+  $html = @"
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>$Script:WS_NAME report - $(ConvertTo-HtmlText $r.meta.started_at)</title>
+<style>
+  :root{--fg:#1c1c1f;--bg:#fafafa;--muted:#7a7a85;--ok:#0a7d54;--warn:#b8860b;--line:#e6e6ea;--card:#fff;--accent:#0b6bcb}
+  @media (prefers-color-scheme:dark){:root{--fg:#eaeaea;--bg:#16161a;--muted:#9d9da8;--line:#2a2a30;--card:#1f1f25;--accent:#5aa9ff}}
+  *{box-sizing:border-box}html,body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.55 'Segoe UI',system-ui,sans-serif}
+  .wrap{max-width:960px;margin:2rem auto;padding:0 1.25rem}h1{font-size:1.6rem;margin:0 0 .3rem}
+  h2{font-size:1.05rem;margin:2.2rem 0 .7rem;color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
+  .subtitle{color:var(--muted);margin:0 0 1.5rem}.totals{display:flex;align-items:baseline;gap:1rem;padding:1.5rem 1.75rem;border:1px solid var(--line);border-radius:12px;background:var(--card);margin:1rem 0}
+  .totals .big{font-size:2.5rem;font-weight:800;color:var(--ok);line-height:1}.totals .label{color:var(--muted);text-transform:uppercase;font-size:.75rem;letter-spacing:.08em}
+  dl{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:.6rem 1.5rem;margin:0;padding:1rem 1.25rem;border:1px solid var(--line);border-radius:10px;background:var(--card)}
+  dt{color:var(--muted);font-size:.75rem;text-transform:uppercase;letter-spacing:.05em}dd{margin:.1rem 0 0;font-weight:600;word-break:break-all}
+  table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+  th,td{text-align:left;padding:.55rem .85rem;border-bottom:1px solid var(--line)}tr:last-child td{border-bottom:none}
+  th{font-size:.72rem;color:var(--muted);text-transform:uppercase;letter-spacing:.07em;background:var(--bg)}td.num{text-align:right;font-variant-numeric:tabular-nums}
+  .badge{display:inline-block;padding:.12em .5em;border-radius:999px;font-size:.75em;font-weight:600;text-transform:uppercase}
+  .badge.ran,.badge.dry-run{background:rgba(10,125,84,.12);color:var(--ok)}.badge.skipped,.badge.refused{background:rgba(184,134,11,.12);color:var(--warn)}.badge.failed{background:rgba(192,57,43,.12);color:#c0392b}
+  footer{margin:3rem 0 1rem;color:var(--muted);font-size:.85rem;text-align:center}a{color:var(--accent)}
+</style>
+</head>
+<body><div class="wrap">
+  <h1>$Script:WS_NAME session report</h1>
+  <p class="subtitle">$(ConvertTo-HtmlText $r.meta.started_at) to $(ConvertTo-HtmlText $r.meta.finished_at) - $($r.meta.duration_seconds)s - $(ConvertTo-HtmlText $r.meta.host)</p>
+  <div class="totals"><div><div class="label">$headline</div><div class="big">$(ConvertTo-HtmlText $big)</div></div>
+  <div style="margin-left:auto;text-align:right;color:var(--muted)"><div><strong>$($r.totals.steps_run)</strong> sections run</div><div><strong>$($r.totals.steps_skipped)</strong> skipped</div></div></div>
+  <h2>Run</h2>
+  <dl><div><dt>Mode</dt><dd>$(ConvertTo-HtmlText $r.meta.mode)</dd></div><div><dt>Dry-run</dt><dd>$($r.meta.dry_run)</dd></div><div><dt>Elevated</dt><dd>$($r.meta.elevated)</dd></div>
+  <div><dt>Developer mode</dt><dd>$($r.meta.developer_mode)</dd></div><div><dt>Idle window</dt><dd>$($r.meta.idle_days) days</dd></div><div><dt>Windows</dt><dd>$(ConvertTo-HtmlText $r.meta.os)</dd></div>
+  <div><dt>Log file</dt><dd><code>$(ConvertTo-HtmlText $r.meta.log_file)</code></dd></div></dl>
+  <h2>Sections</h2>
+  <table><thead><tr><th>#</th><th>Section</th><th>Title</th><th>Status</th><th class="num">Freed</th></tr></thead><tbody>
+$rows  </tbody></table>
+  <h2>Drives</h2>
+  <table><thead><tr><th>Drive</th><th class="num">Size</th><th class="num">Free before</th><th class="num">Free after</th></tr></thead><tbody>
+$drives  </tbody></table>
+  <footer>Generated from <code>$(ConvertTo-HtmlText ([IO.Path]::GetFileName($Json)))</code> by <a href="$Script:WS_REPO">$Script:WS_NAME</a> v$(ConvertTo-HtmlText $r.meta.tool_version) - $(ConvertTo-HtmlText $r.credits.author.name)</footer>
+</div></body></html>
+"@
+  [IO.File]::WriteAllText($Out, $html, (New-Object System.Text.UTF8Encoding($false)))
+  Write-Ok "wrote $Out"
+  return $Out
+}
+
+function Export-Reports {
+  <# .SYNOPSIS --export FMT ID. Returns an exit code. #>
+  param([string] $Format = 'both', [string] $Id = 'latest')
+  if ($Format -notin 'md', 'html', 'both') { Write-Err 'format must be md, html or both'; return $Script:WS_EXIT_USAGE }
+  $files = @(Get-ReportFiles)
+  if ($files.Count -eq 0) { Write-Err "no reports in $($Script:WS.ReportsDir)"; return $Script:WS_EXIT_FAIL }
+  $picked = @()
+  switch -Regex ($Id) {
+    '^all$' { $picked = $files }
+    '^latest$' { $picked = @($files[0]) }
+    '^\d+$' { $n = [int]$Id; if ($n -lt 1 -or $n -gt $files.Count) { Write-Err "index $Id out of range (1..$($files.Count))"; return $Script:WS_EXIT_USAGE }; $picked = @($files[$n - 1]) }
+    default { Write-Err 'ID must be a number, latest or all'; return $Script:WS_EXIT_USAGE }
+  }
+  foreach ($f in $picked) {
+    if ($Format -in 'md', 'both') { $null = Convert-ReportToMarkdown -Json $f.FullName }
+    if ($Format -in 'html', 'both') { $null = Convert-ReportToHtml -Json $f.FullName }
+  }
+  return $Script:WS_EXIT_OK
+}
+
+function Invoke-ReportsManager {
+  Write-Box 'Reports manager' $Script:WS.ReportsDir
+  $files = @(Show-ReportList)
+  if ($files.Count -eq 0) { return }
+  if (-not $Script:WS.Interactive) { Write-Note 'non-interactive: use --export md|html|both N|latest|all'; return }
+  Write-UiLine '' 'Gray'
+  Write-Plain '  cm N  markdown    ch N  html    cb N  both    all  export everything    v N  view JSON    o N  open HTML    d N  delete    q  quit'
+  $answer = Read-Line '  > '
+  if ($null -eq $answer) { return }
+  $parts = $answer.Trim() -split '\s+'
+  $cmd = $parts[0].ToLowerInvariant()
+  $n = 0
+  if ($parts.Count -gt 1 -and $parts[1] -match '^\d+$') { $n = [int]$parts[1] }
+  $target = $null
+  if ($n -ge 1 -and $n -le $files.Count) { $target = $files[$n - 1].FullName }
+  switch ($cmd) {
+    'cm' { if ($target) { $null = Convert-ReportToMarkdown -Json $target } else { Write-Err 'invalid index' } }
+    'ch' { if ($target) { $null = Convert-ReportToHtml -Json $target } else { Write-Err 'invalid index' } }
+    'cb' { if ($target) { $null = Convert-ReportToMarkdown -Json $target; $null = Convert-ReportToHtml -Json $target } else { Write-Err 'invalid index' } }
+    'all' { foreach ($f in $files) { $null = Convert-ReportToMarkdown -Json $f.FullName; $null = Convert-ReportToHtml -Json $f.FullName } }
+    'v' { if ($target) { Get-Content -LiteralPath $target | ForEach-Object { Write-Plain $_ } } else { Write-Err 'invalid index' } }
+    'o' {
+      if ($target) {
+        $html = [IO.Path]::ChangeExtension($target, '.html')
+        if (-not (Test-Path -LiteralPath $html)) { $null = Convert-ReportToHtml -Json $target }
+        try { Start-Process $html | Out-Null; Write-Ok "opened $html" } catch { Write-Warn "could not open $html" }
+      } else { Write-Err 'invalid index' }
+    }
+    'd' {
+      if ($target) {
+        if (Confirm-Ui -Prompt "Delete $([IO.Path]::GetFileName($target)) and its .md/.html siblings?" -Default 'n') {
+          foreach ($ext in '.json', '.md', '.html') { $p = [IO.Path]::ChangeExtension($target, $ext); if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Force -ErrorAction SilentlyContinue } }
+          Write-Ok 'deleted'
+        }
+      } else { Write-Err 'invalid index' }
+    }
+    'q' { return }
+    default { Write-Warn "unknown action: $cmd" }
+  }
+}
+
+function Show-Stats {
+  Write-Box 'Run history' $Script:WS.Home
+  $files = @(Get-ReportFiles)
+  if ($files.Count -eq 0) { Write-Info 'no runs recorded yet'; return }
+  $total = [long]0; $runs = 0; $dry = 0
+  foreach ($f in $files) {
+    $r = Read-Report $f.FullName
+    if (-not $r) { continue }
+    if ($r.meta.dry_run) { $dry++ } else { $runs++; $total += [long]$r.totals.total_reclaimed_bytes }
+  }
+  Write-Kv 'Real runs:' $runs
+  Write-Kv 'Dry-runs:' $dry
+  Write-Kv 'Reclaimed overall:' (Format-Bytes $total)
+  Write-Kv 'Latest report:' $files[0].FullName
+  $logs = Join-Path $Script:WS.Home 'logs'
+  if (Test-Path -LiteralPath $logs) { Write-Kv 'Logs on disk:' (Format-Bytes (Get-DirectoryBytes $logs)) }
+}

package/modules/runner.ps1

@@ -0,0 +1,190 @@
+# runner.ps1 - section dispatch, batch policy enforcement, the read-only scan mode and the summary.
+
+function Get-SectionIdList {
+  <# .SYNOPSIS Parse "1,3,5-7" into section ids; validates against the catalogue. #>
+  param([string] $Text)
+  $ids = New-Object System.Collections.Generic.SortedSet[int]
+  foreach ($part in ($Text -split ',')) {
+    $part = $part.Trim()
+    if (-not $part) { continue }
+    if ($part -match '^(\d+)-(\d+)$') {
+      $a = [int]$Matches[1]; $b = [int]$Matches[2]
+      if ($a -gt $b) { $t = $a; $a = $b; $b = $t }
+      for ($i = $a; $i -le $b; $i++) { if (Get-Section $i) { $null = $ids.Add($i) } else { Write-Warn "no section $i - ignored" } }
+    } elseif ($part -match '^\d+$') {
+      $i = [int]$part
+      if (Get-Section $i) { $null = $ids.Add($i) } else { Write-Warn "no section $i - ignored" }
+    } else {
+      Write-Warn "cannot parse section '$part' - ignored"
+    }
+  }
+  return @($ids)
+}
+
+function Get-RequestedSections {
+  <# .SYNOPSIS Resolve --all / --only / --profile / --exclude into the ordered list to run. #>
+  $ws = $Script:WS
+  $ids = @()
+  if ($ws.Mode -eq 'all') {
+    $ids = @($Script:WS_SAFE_BATCH)
+    if ($ws.IsAdmin) { $ids += $Script:WS_SAFE_BATCH_ADMIN }
+  } elseif ($ws.OnlyList) {
+    $ids = Get-SectionIdList $ws.OnlyList
+  } elseif ($ws.Profile) {
+    $ids = @($Script:WS_PROFILES[$ws.Profile])
+    Write-Info "profile '$($ws.Profile)' = sections $($ids -join ',')"
+  }
+  if ($ws.Exclude) {
+    $ex = Get-SectionIdList $ws.Exclude
+    $ids = @($ids | Where-Object { $ex -notcontains $_ })
+    Write-Info "after --exclude: sections $($ids -join ',')"
+  }
+  return @($ids | Sort-Object -Unique)
+}
+
+function Invoke-SectionById {
+  <# .SYNOPSIS Run one section under the batch, admin and developer policies; records the report step. #>
+  param([int] $Id)
+  $ws = $Script:WS
+  $sec = Get-Section $Id
+  if (-not $sec) { Write-Warn "no section $Id"; return }
+  $title = "[{0:00}] {1}" -f $sec.Id, $sec.Title
+  Write-Box $title
+  # Batch policy: deep and interactive-only sections never run unattended without an explicit opt-in.
+  if ($ws.BatchMode -and -not $ws.DryRun) {
+    if ($sec.Batch -eq 'interactive') {
+      Write-Warn "section $Id is interactive-only: it needs a person at the keyboard. Run it from the walkthrough or the menu."
+      $ws.Refusals += "section $Id (interactive-only)"
+      Add-ReportStep -Section $Id -Title $sec.Title -Status 'refused' -Note 'interactive-only section in batch mode'
+      return
+    }
+    if ($sec.Batch -eq 'deep' -and -not $ws.Deep) {
+      Write-Warn "section $Id is deep (irreversible or system-changing): refused in batch mode without --i-understand-deep."
+      $ws.Refusals += "section $Id (deep, add --i-understand-deep)"
+      Add-ReportStep -Section $Id -Title $sec.Title -Status 'refused' -Note 'deep section without --i-understand-deep'
+      return
+    }
+  }
+  if ($sec.Admin -and -not $ws.IsAdmin) {
+    Write-Warn "section $Id needs Administrator rights - skipped."
+    Write-Note "run it elevated:  windowsweep --only $Id --yes --elevate"
+    $ws.Hints += "Admin section $Id skipped: windowsweep --only $Id --yes --elevate"
+    Add-ReportStep -Section $Id -Title $sec.Title -Status 'skipped' -Note 'needs Administrator'
+    return
+  }
+  if ($sec.Dev -and $ws.Developer -eq $false -and $Id -in @(4, 17, 20)) {
+    Write-Info "developer mode is off - section $Id (developer-only data) skipped."
+    Add-ReportStep -Section $Id -Title $sec.Title -Status 'skipped' -Note 'developer mode off'
+    return
+  }
+  $ws.SectionFreed = [long]0
+  $before = Get-SystemDriveFree
+  $status = 'ran'
+  if ($ws.DryRun) { $status = 'dry-run' }
+  try {
+    & $sec.Fn
+  } catch {
+    $status = 'failed'
+    Write-Err "section $Id failed: $($_.Exception.Message)"
+    Write-Log ("section $Id error: " + $_.ScriptStackTrace)
+    $ws.ExitCode = $Script:WS_EXIT_FAIL
+  }
+  $after = Get-SystemDriveFree
+  $delta = $after - $before
+  if ($delta -lt 0) { $delta = 0 }
+  $freed = $ws.SectionFreed
+  if ($ws.DryRun) {
+    if ($freed -gt 0) { Write-UiLine ("  [dry-run] this section would free about {0}" -f (Format-Bytes $freed)) 'Magenta' }
+  } elseif ($freed -gt 0 -or $delta -gt 0) {
+    Write-UiLine ("  {0} this section freed {1} (system drive gained {2})   running total: {3}" -f $ws.Glyph.ok, (Format-Bytes $freed), (Format-Bytes $delta), (Format-Bytes $ws.TotalFreed)) 'Green'
+  } else {
+    Write-Note 'no measurable change in this section'
+  }
+  Add-ReportStep -Section $Id -Title $sec.Title -Status $status -Freed $freed
+}
+
+function Invoke-BatchMode {
+  <# .SYNOPSIS --all / --only / --profile #>
+  $ws = $Script:WS
+  $ids = @(Get-RequestedSections)
+  if ($ids.Count -eq 0) { Write-Err 'no sections to run'; $ws.ExitCode = $Script:WS_EXIT_USAGE; return }
+  Write-Banner
+  Show-RunHeader
+  Write-Info "running sections: $($ids -join ',')"
+  foreach ($id in $ids) { Invoke-SectionById -Id $id }
+  Show-SessionSummary
+  if ($ws.Refusals.Count -gt 0 -and $ws.Mode -eq 'only' -and $ws.ExitCode -eq 0) { $ws.ExitCode = $Script:WS_EXIT_REFUSED }
+}
+
+function Show-RunHeader {
+  $ws = $Script:WS
+  $strategy = "prune files idle $($ws.Days)+ days (temp: $($ws.TempDays)+ days)"
+  if ($ws.PurgeAll) { $strategy = 'FULL PURGE of cache targets' }
+  $dev = 'off'
+  if ($ws.Developer) { $dev = "on ($($ws.DeveloperSource))" }
+  $adm = 'no'
+  if ($ws.IsAdmin) { $adm = 'yes' }
+  Write-Info "mode: $($ws.Mode)   strategy: $strategy   developer: $dev   elevated: $adm   auto-yes: $($ws.Yes)"
+  if ($ws.DryRun) { Write-UiLine '  DRY-RUN: nothing will be deleted; sizes below are estimates of what a real run would remove.' 'Magenta' }
+  Write-Info "log: $($ws.LogFile)"
+}
+
+function Invoke-ScanMode {
+  <# .SYNOPSIS --scan: health report + every target's size + the read-only personal scanners. Deletes nothing. #>
+  $ws = $Script:WS
+  Write-Banner
+  Write-Info 'read-only scan - nothing is deleted'
+  if (Get-Command Invoke-Section00 -ErrorAction SilentlyContinue) { Invoke-Section00 }
+  Write-Box 'Targets on disk' 'What each section can reach, and how much it currently holds'
+  $null = Show-ScanTable
+  if (Get-Command Show-PersonalScan -ErrorAction SilentlyContinue) { Show-PersonalScan }
+  Add-ReportStep -Section -1 -Title 'Read-only scan' -Status 'ran'
+  Show-SessionSummary
+}
+
+function Show-SessionSummary {
+  $ws = $Script:WS
+  Write-Box 'Session summary'
+  if ($ws.DryRun) {
+    Write-Kv 'Mode:' 'DRY-RUN - nothing was deleted'
+    Write-Kv 'Would free (estimate):' (Format-Bytes $ws.TotalEstimated)
+  } else {
+    Write-Kv 'Reclaimed:' (Format-Bytes $ws.TotalFreed)
+  }
+  $secs = [int][math]::Round(((Get-Date).Ticks - $ws.Report.startedTicks) / 10000000)
+  Write-Kv 'Duration:' (Format-Duration $secs)
+  $ran = @($ws.Report.steps | Where-Object { $_.status -in 'ran', 'dry-run' }).Count
+  $skipped = @($ws.Report.steps | Where-Object { $_.status -notin 'ran', 'dry-run' }).Count
+  Write-Kv 'Sections run / skipped:' "$ran / $skipped"
+  Write-Kv 'Log:' $ws.LogFile
+  $rep = Save-Report
+  if ($rep) { Write-Kv 'Report (JSON):' $rep } elseif ($ws.NoReport) { Write-Kv 'Report:' '(disabled via --no-report)' }
+  Write-UiLine '' 'Gray'
+  Show-DriveTable
+  if ($ws.Refusals.Count -gt 0) {
+    Write-UiLine '' 'Gray'
+    Write-Warn 'refused in batch mode:'
+    foreach ($r in $ws.Refusals) { Write-Note $r }
+  }
+  if ($ws.Hints.Count -gt 0) {
+    Write-UiLine '' 'Gray'
+    Write-Info 'next steps:'
+    foreach ($h in ($ws.Hints | Sort-Object -Unique)) { Write-Note $h }
+  }
+  Write-UiLine '' 'Gray'
+  Write-Note "$Script:WS_NAME v$(Get-ToolVersion) by $Script:WS_AUTHOR - $Script:WS_REPO"
+  if ($ws.JsonMode) { Write-JsonSummary }
+}
+
+function Write-JsonSummary {
+  <# .SYNOPSIS --json: the only line written to stdout. #>
+  $ws = $Script:WS
+  $doc = [ordered]@{
+    tool = $Script:WS_NAME; version = (Get-ToolVersion); mode = $ws.Mode; dry_run = [bool]$ws.DryRun
+    elevated = [bool]$ws.IsAdmin; developer = $ws.Developer
+    freed_bytes = [long]$ws.TotalFreed; estimated_bytes = [long]$ws.TotalEstimated
+    sections = @($ws.Report.steps | ForEach-Object { [ordered]@{ section = $_.section; status = $_.status; freed_bytes = $_.freed_bytes } })
+    refusals = @($ws.Refusals); log_file = $ws.LogFile; report_file = $ws.ReportFile
+  }
+  [Console]::Out.WriteLine(($doc | ConvertTo-Json -Depth 5 -Compress))
+}

package/modules/system_admin.ps1

@@ -0,0 +1,220 @@
+# system_admin.ps1 - sections 12-16: Windows Update cache, Disk Cleanup engine, DISM, hibernation file, event logs.
+# Every section here needs Administrator rights; the runner skips them (with the --elevate hint) when not elevated.
+
+function Get-Targets12 {
+  $SR = $Script:P.SR; $PD = $Script:P.PD
+  return @(
+    (New-Target 12 'Windows Update download cache' "$SR\SoftwareDistribution\Download" -Mode clear -Note 'wuauserv and bits are stopped for the wipe and restarted')
+    (New-Target 12 'Delivery Optimization cache' 'Delete-DeliveryOptimizationCache -Force' -Kind cmd)
+    (New-Target 12 'Windows temp' "$SR\Temp" -Mode prune -Days $Script:WS.TempDays)
+    (New-Target 12 'LocalService temp' "$SR\ServiceProfiles\LocalService\AppData\Local\Temp" -Mode prune -Days $Script:WS.TempDays)
+    (New-Target 12 'NetworkService temp' "$SR\ServiceProfiles\NetworkService\AppData\Local\Temp" -Mode prune -Days $Script:WS.TempDays)
+    (New-Target 12 'CBS servicing logs' "$SR\Logs\CBS" -Mode prune -Days 30 -Note 'the live CBS.log is open and skipped')
+    (New-Target 12 'DISM logs' "$SR\Logs\DISM" -Mode prune -Days 30)
+    (New-Target 12 'Windows Update logs' "$SR\Logs\WindowsUpdate" -Mode prune -Days 30)
+    (New-Target 12 'Live kernel reports' "$SR\LiveKernelReports" -Mode clear-old -Days 7)
+    (New-Target 12 'Windows Error Reporting queue (system)' "$PD\Microsoft\Windows\WER\ReportQueue" -Mode clear)
+    (New-Target 12 'Windows Error Reporting archive (system)' "$PD\Microsoft\Windows\WER\ReportArchive" -Mode clear)
+    (New-Target 12 'Windows Error Reporting temp (system)' "$PD\Microsoft\Windows\WER\Temp" -Mode clear)
+  )
+}
+
+function Set-ServiceState {
+  <# .SYNOPSIS Stop or start a service through the dry-run-aware wrapper. Returns $true when it was running before a stop. #>
+  param([string] $Name, [string] $Action)
+  $svc = Get-Service -Name $Name -ErrorAction SilentlyContinue
+  if (-not $svc) { return $false }
+  if ($Action -eq 'stop') {
+    if ($svc.Status -ne 'Running') { return $false }
+    if ($Script:WS.DryRun) { Write-DryRun "would stop service $Name"; return $true }
+    try { Stop-Service -Name $Name -Force -ErrorAction Stop; Write-Note "stopped $Name" } catch { Write-Warn "could not stop $Name : $($_.Exception.Message)" }
+    return $true
+  }
+  if ($Script:WS.DryRun) { Write-DryRun "would start service $Name"; return $true }
+  try { Start-Service -Name $Name -ErrorAction Stop; Write-Note "started $Name" } catch { Write-Warn "could not start $Name : $($_.Exception.Message)" }
+  return $true
+}
+
+function Invoke-Section12 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'Windows Update keeps every downloaded package after installing it; Delivery Optimization keeps peer-share',
+    'copies; C:\Windows\Temp and the servicing logs grow forever. All of it is rebuilt on demand.'
+  )
+  if (-not $ws.IsAdmin) { Write-Warn 'needs Administrator - skipped'; return }
+  $targets = Get-Targets12
+  $null = Show-TargetSizes $targets
+  if (-not (Confirm-Section 'Clear Windows Update and system temp caches now?')) { Write-Info 'skipped'; return }
+  $wuWasRunning = Set-ServiceState -Name 'wuauserv' -Action 'stop'
+  $bitsWasRunning = Set-ServiceState -Name 'bits' -Action 'stop'
+  try {
+    $null = Invoke-TargetList $targets
+  } finally {
+    if ($wuWasRunning) { $null = Set-ServiceState -Name 'wuauserv' -Action 'start' }
+    if ($bitsWasRunning) { $null = Set-ServiceState -Name 'bits' -Action 'start' }
+  }
+  if (Get-Command Delete-DeliveryOptimizationCache -ErrorAction SilentlyContinue) {
+    if ($ws.DryRun) { Write-DryRun 'would run Delete-DeliveryOptimizationCache -Force' }
+    else {
+      try { Delete-DeliveryOptimizationCache -Force -ErrorAction Stop; Write-Ok 'Delivery Optimization cache cleared' } catch { Write-Warn "Delivery Optimization: $($_.Exception.Message)" }
+    }
+  }
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 13 - Disk Cleanup engine (cleanmgr)
+# ---------------------------------------------------------------------------------------------
+
+# Handlers this tool enables. Deliberately absent: DownloadsFolder (your files), Recycle Bin (section 11 asks
+# separately), User file versions (File History), Windows ESD installation files (needed for Reset this PC),
+# Language Pack (removes installed languages).
+$Script:WS_CLEANMGR_HANDLERS = @(
+  'Active Setup Temp Folders', 'BranchCache', 'Content Indexer Cleaner', 'D3D Shader Cache', 'Delivery Optimization Files',
+  'Device Driver Packages', 'Diagnostic Data Viewer database files', 'Downloaded Program Files', 'Internet Cache Files',
+  'Offline Pages Files', 'Old ChkDsk Files', 'Previous Installations', 'RetailDemo Offline Content', 'Setup Log Files',
+  'System error memory dump files', 'System error minidump files', 'Temporary Files', 'Temporary Setup Files',
+  'Temporary Sync Files', 'Thumbnail Cache', 'Update Cleanup', 'Upgrade Discarded Files', 'Windows Defender',
+  'Windows Error Reporting Files', 'Windows Upgrade Log Files'
+)
+$Script:WS_CLEANMGR_KEY = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\VolumeCaches'
+$Script:WS_CLEANMGR_FLAG = 'StateFlags0077'
+
+function Get-Targets13 {
+  return @((New-Target 13 'cleanmgr /sagerun:77 with curated handlers' ($Script:WS_CLEANMGR_HANDLERS -join ', ') -Kind cmd -Note 'never Downloads, Recycle Bin, File History, ESD files or language packs'))
+}
+
+function Invoke-Section13 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    "Windows' own Disk Cleanup engine, driven with a curated handler list: temporary files, Update Cleanup,",
+    'thumbnail cache, memory dumps, setup and upgrade logs, previous Windows installations. It never touches',
+    'your Downloads folder, the Recycle Bin, File History or the files Reset-this-PC needs.'
+  )
+  if (-not $ws.IsAdmin) { Write-Warn 'needs Administrator - skipped'; return }
+  if (-not (Test-CommandPresent 'cleanmgr.exe')) { Write-Warn 'cleanmgr.exe not found on this edition of Windows - skipped'; return }
+  $present = @()
+  foreach ($h in $Script:WS_CLEANMGR_HANDLERS) { if (Test-Path -LiteralPath (Join-Path $Script:WS_CLEANMGR_KEY $h)) { $present += $h } }
+  Write-Info "handlers available on this machine: $($present.Count) of $($Script:WS_CLEANMGR_HANDLERS.Count)"
+  foreach ($h in $present) { Write-Note $h }
+  if ($ws.DryRun) { Write-DryRun 'would run cleanmgr.exe /sagerun:77 with those handlers (cleanmgr cannot preview sizes)'; return }
+  if (-not (Confirm-Section 'Run Disk Cleanup with these handlers now? (a progress window may appear; it can take several minutes)')) { Write-Info 'skipped'; return }
+  $before = Get-SystemDriveFree
+  try {
+    foreach ($h in $present) { Set-ItemProperty -LiteralPath (Join-Path $Script:WS_CLEANMGR_KEY $h) -Name $Script:WS_CLEANMGR_FLAG -Value 2 -Type DWord -ErrorAction Stop }
+    $r = Invoke-External -FilePath 'cleanmgr.exe' -ArgumentList @('/sagerun:77') -Destructive -Quiet -Label 'cleanmgr /sagerun:77'
+    if ($r.ExitCode -ne 0) { Write-Warn "cleanmgr returned $($r.ExitCode)" }
+  } catch {
+    Write-Err "could not configure Disk Cleanup: $($_.Exception.Message)"
+  } finally {
+    foreach ($h in $present) { Remove-ItemProperty -LiteralPath (Join-Path $Script:WS_CLEANMGR_KEY $h) -Name $Script:WS_CLEANMGR_FLAG -ErrorAction SilentlyContinue }
+  }
+  $gain = [math]::Max([long]0, (Get-SystemDriveFree) - $before)
+  Add-Freed $gain
+  Write-Ok ("Disk Cleanup finished - system drive gained " + (Format-Bytes $gain))
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 14 - DISM component store
+# ---------------------------------------------------------------------------------------------
+
+function Get-Targets14 {
+  $note = 'superseded component versions in WinSxS'
+  if ($Script:WS.ResetBase) { $note += '; --reset-base also removes the ability to uninstall installed updates' }
+  return @((New-Target 14 'Dism /Online /Cleanup-Image /StartComponentCleanup' "$($Script:P.SR)\WinSxS" -Kind cmd -Note $note))
+}
+
+function Invoke-Section14 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'The component store (WinSxS) keeps superseded versions of Windows components. DISM removes the ones no',
+    'installed update needs. It is slow (5-20 minutes) and safe; /ResetBase (opt-in) also drops the ability to',
+    'uninstall currently installed updates.'
+  )
+  if (-not $ws.IsAdmin) { Write-Warn 'needs Administrator - skipped'; return }
+  if (-not (Test-CommandPresent 'Dism.exe')) { Write-Warn 'Dism.exe not found - skipped'; return }
+  Write-Info 'analyzing the component store (read-only, about a minute)...'
+  $a = Invoke-External -FilePath 'Dism.exe' -ArgumentList @('/Online', '/Cleanup-Image', '/AnalyzeComponentStore') -Quiet -Label 'dism analyze'
+  foreach ($l in $a.Output) { if ($l -match 'Size|Cleanup|Reclaimable|Date' ) { Write-Note ($l.Trim()) } }
+  $dismArgs = @('/Online', '/Cleanup-Image', '/StartComponentCleanup')
+  if ($ws.ResetBase) { $dismArgs += '/ResetBase'; Write-Warn '/ResetBase requested: installed updates can no longer be uninstalled afterwards' }
+  if (-not (Confirm-Section 'Run the component store cleanup now?')) { Write-Info 'skipped'; return }
+  $before = Get-SystemDriveFree
+  $r = Invoke-External -FilePath 'Dism.exe' -ArgumentList $dismArgs -Destructive -Quiet -Label 'dism StartComponentCleanup'
+  if ($r.Ran) {
+    $gain = [math]::Max([long]0, (Get-SystemDriveFree) - $before)
+    Add-Freed $gain
+    if ($r.ExitCode -eq 0) { Write-Ok ("component store cleanup finished - system drive gained " + (Format-Bytes $gain)) } else { Write-Warn "DISM returned $($r.ExitCode) - see the log" }
+  }
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 15 - hibernation file
+# ---------------------------------------------------------------------------------------------
+
+function Get-Targets15 {
+  return @((New-Target 15 'hiberfil.sys (powercfg /hibernate off | /type reduced)' (Join-Path $Script:P.SD '\hiberfil.sys') -Kind cmd -Note 'off frees the whole file; reduced keeps Fast Startup at roughly 40% of RAM'))
+}
+
+function Invoke-Section15 {
+  $ws = $Script:WS
+  $h = Get-HiberfilInfo
+  Write-SectionIntro @(
+    'hiberfil.sys holds a copy of RAM for Hibernate and Fast Startup, so it is about 40% of your RAM - permanently.',
+    '  off      removes it. Sleep still works; Hibernate, Fast Startup and hibernate-on-critical-battery do not.',
+    '  reduced  keeps Fast Startup only, at a smaller file (Windows decides the size, usually about half).',
+    'Running speed is unaffected either way; this is purely disk space.'
+  )
+  if ($h.Bytes -gt 0) { Write-Kv 'hiberfil.sys now:' ("{0} (hibernation {1})" -f (Format-Bytes $h.Bytes), $h.State) } else { Write-Info 'hiberfil.sys is absent - hibernation is already off'; return }
+  if (-not $ws.IsAdmin) { Write-Warn 'needs Administrator - skipped'; return }
+  $choice = $ws.Hiberfil
+  if (-not $choice) {
+    if (-not $ws.Interactive) { Write-Warn 'pass --hiberfil off|reduced|keep to run this section unattended'; return }
+    $choice = Read-Choice -Prompt '  [o] turn hibernation off   [r] reduced (keep Fast Startup)   [k] keep as is  > ' -Default 'k'
+    switch ($choice) { 'o' { $choice = 'off' } 'r' { $choice = 'reduced' } default { $choice = 'keep' } }
+  }
+  if ($choice -eq 'keep') { Write-Info 'left unchanged'; return }
+  $pcArgs = @('/hibernate', 'off')
+  if ($choice -eq 'reduced') { $pcArgs = @('/hibernate', '/type', 'reduced') }
+  if ($ws.DryRun) { Write-DryRun ("would run powercfg $($pcArgs -join ' ') (frees up to " + (Format-Bytes $h.Bytes) + ')'); Add-Freed $h.Bytes; return }
+  if (-not (Confirm-Ui -Prompt "Run powercfg $($pcArgs -join ' ') now?" -Default 'n')) { Write-Info 'skipped'; return }
+  $r = Invoke-External -FilePath 'powercfg.exe' -ArgumentList $pcArgs -Destructive -Quiet -Label "powercfg $($pcArgs -join ' ')"
+  Start-Sleep -Seconds 2
+  $after = Get-HiberfilInfo
+  $gain = [math]::Max([long]0, $h.Bytes - $after.Bytes)
+  Add-Freed $gain
+  if ($r.ExitCode -eq 0) { Write-Ok ("hibernation set to '$choice' - hiberfil.sys " + (Format-Bytes $h.Bytes) + ' -> ' + (Format-Bytes $after.Bytes) + ' (freed ' + (Format-Bytes $gain) + ')') } else { Write-Warn "powercfg returned $($r.ExitCode)" }
+}
+
+# ---------------------------------------------------------------------------------------------
+# Section 16 - event logs
+# ---------------------------------------------------------------------------------------------
+
+function Get-Targets16 {
+  return @((New-Target 16 'Windows Event Logs (wevtutil cl for every log)' "$($Script:P.SR)\System32\winevt\Logs" -Kind cmd -Note 'PERMANENT - troubleshooting history is lost'))
+}
+
+function Invoke-Section16 {
+  $ws = $Script:WS
+  $logDir = Join-Path $Script:P.SR 'System32\winevt\Logs'
+  Write-SectionIntro @(
+    'Clears every Windows Event Log (Application, System, Security and the hundreds of per-component logs).',
+    'This is permanent and removes the history a technician would use to diagnose a problem. Only do this on',
+    'a machine that is behaving normally.'
+  )
+  if (-not $ws.IsAdmin) { Write-Warn 'needs Administrator - skipped'; return }
+  $before = Get-DirectoryBytes $logDir
+  Write-Kv 'event log store:' (Format-Bytes $before)
+  if ($ws.DryRun) { Write-DryRun ("would clear every event log (about " + (Format-Bytes $before) + ')'); Add-Freed $before; return }
+  if (-not (Confirm-Ui -Prompt 'Permanently clear ALL Windows Event Logs?' -Default 'n')) { Write-Info 'skipped'; return }
+  $list = Invoke-External -FilePath 'wevtutil.exe' -ArgumentList @('el') -Quiet -Label 'wevtutil el'
+  $ok = 0; $failed = 0
+  foreach ($name in $list.Output) {
+    $n = ([string]$name).Trim()
+    if (-not $n) { continue }
+    $r = Invoke-External -FilePath 'wevtutil.exe' -ArgumentList @('cl', $n) -Destructive -Quiet -Label "wevtutil cl $n"
+    if ($r.ExitCode -eq 0) { $ok++ } else { $failed++ }
+  }
+  $gain = [math]::Max([long]0, $before - (Get-DirectoryBytes $logDir))
+  Add-Freed $gain
+  Write-Ok ("cleared $ok logs ($failed could not be cleared - analytic/debug channels), freed " + (Format-Bytes $gain))
+}

package/modules/test_runners.ps1

@@ -0,0 +1,24 @@
+# test_runners.ps1 - section 3: downloaded test browsers (Cypress, Playwright, Puppeteer). Keep the newest of each.
+
+$Script:WS_GROUP_BY_FAMILY = { param($name) ($name -replace '[-_]?v?\d[\d.]*$', '') }
+
+function Get-Targets03 {
+  $P = $Script:P
+  return @(
+    (New-Target 3 'Cypress binary versions' "$($P.L)\Cypress\Cache" -Mode units -Dev $true -KeepNewest $true -Note 'one folder per Cypress version; newest kept')
+    (New-Target 3 'Playwright browsers' "$($P.L)\ms-playwright" -Mode units -Dev $true -KeepNewest $true -GroupBy $Script:WS_GROUP_BY_FAMILY -ExcludeNames @('.links', 'daemon') -Note 'newest build of each browser kept')
+    (New-Target 3 'Playwright-Go browsers' "$($P.L)\ms-playwright-go" -Mode units -Dev $true -KeepNewest $true -GroupBy $Script:WS_GROUP_BY_FAMILY)
+    (New-Target 3 'Puppeteer browsers' "$($P.U)\.cache\puppeteer\*" -Kind glob -Mode units -Dev $true -KeepNewest $true -Note 'per browser family: newest build kept')
+  )
+}
+
+function Invoke-Section03 {
+  Write-SectionIntro @(
+    'Test runners download whole browsers per version. The newest build of each browser is always kept; older',
+    'builds go once idle for the window. A missing build is re-downloaded by the next install or "playwright install".'
+  ) -Dev $true
+  $targets = Get-Targets03
+  $null = Show-TargetSizes $targets
+  if (-not (Confirm-Section 'Prune superseded test-runner browsers now?')) { Write-Info 'skipped'; return }
+  $null = Invoke-TargetList $targets
+}