windowsweep 1.0.1 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h1>windowsweep</h1>
 
-<p><strong>Safe-by-default Windows cleanup CLI - developer-aware, dry-run first, zero install via npx.</strong></p>
+<p><strong>Developer-aware Windows cleanup CLI: dry-run first, personal folders refused, zero install via npx.</strong></p>
 
 [![npm version](https://img.shields.io/npm/v/windowsweep.svg)](https://www.npmjs.com/package/windowsweep)
 [![downloads](https://img.shields.io/npm/dm/windowsweep.svg)](https://www.npmjs.com/package/windowsweep)
@@ -13,35 +13,37 @@
 [![node](https://img.shields.io/node/v/windowsweep.svg)](https://nodejs.org)
 [![platform](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d4?logo=windows&logoColor=white)](https://github.com/aoneahsan/windowsweep#platform-support)
 
-[Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/README.md) · [npm](https://www.npmjs.com/package/windowsweep) · [GitHub](https://github.com/aoneahsan/windowsweep) · [Changelog](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md) · [Contributing](https://github.com/aoneahsan/windowsweep/blob/main/CONTRIBUTING.md) · [Support](https://github.com/aoneahsan/windowsweep/issues)
+[Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/README.md) · [AI Guide](https://github.com/aoneahsan/windowsweep/blob/main/AI-INTEGRATION-GUIDE.md) · [npm](https://www.npmjs.com/package/windowsweep) · [GitHub](https://github.com/aoneahsan/windowsweep) · [Changelog](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md) · [Contributing](https://github.com/aoneahsan/windowsweep/blob/main/CONTRIBUTING.md) · [Support](https://github.com/aoneahsan/windowsweep/issues)
 
 </div>
 
 > [!IMPORTANT]
 > **This tool deletes files.** Most of what it removes are caches that rebuild themselves; personal files it
-> lists go to the Recycle Bin; two sections (emptying the Recycle Bin, clearing event logs) are permanent and
-> gated behind a separate flag. Start with `npx windowsweep --scan`, which deletes nothing, then
+> lists go to the Recycle Bin; and two sections - emptying the Recycle Bin, clearing event logs - are
+> permanent, with no undo of any kind. Those two sit behind `--i-understand-deep`, along with the hibernation
+> file and disk-image compaction. Start with `npx windowsweep --scan`, which deletes nothing, then
 > `npx windowsweep --dry-run --all --yes`, which shows exactly what a real run would remove.
 > **Windows only** - npm refuses to install it elsewhere.
 
-`windowsweep` reclaims the disk space that quietly disappears on a Windows machine: package-manager and build
-caches, browser and app caches, Windows temp and update leftovers, stale `node_modules`, half-finished downloads.
-It is a PowerShell tool with a thin Node launcher, so `npx windowsweep` runs it with nothing to install. What
-sets it apart is restraint: it asks whether you are a developer and keeps the caches you used in the last
-100 days, it names every path before touching it, it never follows a junction, and it makes no network calls.
+What it reclaims is the disk space that quietly disappears on a Windows machine: package-manager and build caches,
+browser and app caches, Windows temp and update leftovers, stale `node_modules`, half-finished downloads.
+It names every path before it touches one, keeps the caches you used in the last 100 days, never follows a
+junction and makes no network calls at all. One question on the first run decides whether your developer caches
+are pruned on the idle gate or cleared completely. A PowerShell engine sits behind a thin Node launcher, so `npx
+windowsweep` runs it with nothing to install.
 It is the Windows member of a family with [linux-cleanup](https://github.com/aoneahsan/linux-cleanup) and
 [macleanup](https://github.com/aoneahsan/macleanup).
 
 | | |
 |---|---|
-| **Version** | `1.0.1` |
+| **Version** | `1.1.0` |
 | **License** | MIT |
 | **Node** | `>=14` (launcher only) |
 | **Runtime** | Windows PowerShell 5.1 (built in) or PowerShell 7 |
 | **Platforms** | Windows 10 (1809+) and Windows 11 |
-| **Install size** | ~81 kB packed · ~273 kB unpacked · 38 files · no dependencies |
+| **Install size** | ~109 kB packed · ~366 kB unpacked · 44 files · no dependencies |
 | **Undo** | Recycle Bin for personal files; none for caches (they regenerate) |
-| **Status** | Stable · actively maintained |
+| **Status** | Stable · 1.1.0, released 2026-09-04 |
 
 <a id="table-of-contents"></a>
 ## 🧭 Table of Contents&nbsp;[#](#table-of-contents)
@@ -57,6 +59,7 @@ It is the Windows member of a family with [linux-cleanup](https://github.com/aon
 - [💻 Command Line](#command-line)
 - [🧪 Examples](#examples)
 - [🎛️ Advanced Features](#advanced-features)
+- [🖥️ Desktop app](#desktop-app)
 - [🚑 Recovery & Troubleshooting](#recovery-troubleshooting)
 - [🚧 Limitations](#limitations)
 - [❓ FAQ](#faq)
@@ -78,8 +81,8 @@ Yarn and npm caches, Gradle, Cypress and Playwright browsers, Android emulator i
 `node_modules` for a project you finished in spring, editor caches, two hundred profiles' worth of Chrome cache.
 Clearing them by hand means keeping a private list of paths and remembering which ones bite back.
 
-A cleaner that wipes every cache it finds trades one problem for another: the next `yarn install` re-downloads
-twelve gigabytes and your afternoon is gone. `windowsweep` takes the narrower path.
+A cleaner that clears every cache it finds trades one problem for another: the next `yarn install` downloads
+the lot again, and your afternoon is gone. `windowsweep` takes the narrower path.
 
 | | `windowsweep` | Windows Disk Cleanup / Storage Sense | A wipe-everything cleaner |
 |---|---|---|---|
@@ -93,21 +96,25 @@ twelve gigabytes and your afternoon is gone. `windowsweep` takes the narrower pa
 
 Nothing here can promise a number. How much comes back depends on your disk; `--scan` measures it.
 
-**Not the right tool when** you want a graphical, set-and-forget cleaner; when you are on Linux or macOS (use the
-siblings); when you want an undo for caches (there is none - they regenerate); or when you are looking for a
-security scanner or a registry cleaner. It reclaims disk space, nothing else.
+**Not the right tool when** you want a set-and-forget cleaner that runs itself; when you are on Linux or macOS (use
+the siblings); when you want an undo for caches (there is none - they regenerate); or when you are looking for a
+security scanner or a registry cleaner. The rest of what it cannot do is under [Limitations](#limitations). It
+reclaims disk space, nothing else.
 
 <a id="features"></a>
 ## ✨ Features&nbsp;[#](#features)
 
 - **Developer mode** - one question on the first run. Yes keeps package, build and test-runner caches used in
   the last 100 days and the newest version of every versioned tool; no clears them completely.
-- **22 numbered sections** - from package-manager caches to Windows Update leftovers, each naming its paths
-  before it acts. Numbers are a public contract.
-- **One deletion chokepoint** - refuses drive roots, Windows, Program Files, your profile root, personal
-  folders, credentials, toolchains and browser or editor state; asserts every deletion sits inside its declared
-  target; never follows a junction or symlink; handles paths beyond 260 characters; skips files another program
-  has open.
+- **26 numbered sections** - from package-manager caches to Windows Update leftovers, plus three read-only
+  audits (global packages, idle programs, startup items) that report and delete nothing. Orphaned application
+  data is a fourth 1.1.0 section and is **not** an audit: it asks you to pick, row by row, and what you pick
+  goes to the Recycle Bin. Every section names its paths before it acts, and the numbers are a public
+  contract.
+- **One deletion chokepoint** - refuses drive roots, Windows, Program Files, your profile root, personal folders,
+- credentials, toolchains and browser or editor state; asserts every deletion sits inside its declared target; never
+- follows a junction or symlink; handles paths beyond 260 characters; skips files another program has open. Self-test
+- check [6] walks every directory and file target and fails if one resolves inside a protected path.
 - **A dry-run that writes nothing** - `--dry-run` short-circuits every deletion and every destructive command
   and reports an exact estimate. `--scan` and `--list-targets` are read-only.
 - **Personal files go to the Recycle Bin** - partial downloads and large stale files are listed, you pick, and
@@ -119,18 +126,19 @@ security scanner or a registry cleaner. It reclaims disk space, nothing else.
 - **Running-app guard** - an open browser, editor or app keeps its caches; the tool tells you which to close.
 - **Session reports** - schema-versioned JSON, exportable to Markdown or a self-contained HTML page, plus
   `--json` for scripts.
-- **Self-test** - 114 checks prove the guards on your machine with a real junction, a 400-character path and
+- **Self-test** - 151 checks prove the guards on your machine with a real junction, a 445-character path and
   a dry-run fixture before you trust it.
-- **Offline by design** - zero network calls, no telemetry, no update check. Crash bundles stay on disk.
+- **Offline by design** - the command-line tool makes zero network calls: no telemetry, no update check.
+  Self-test check [9] fails the build on an HTTP or socket call in the source. Crash bundles stay on disk.
 
 <a id="platform-support"></a>
 ## 📱 Platform Support&nbsp;[#](#platform-support)
 
 | Platform | Supported | Notes |
 |---|---|---|
-| Windows 11 | ✅ | Same engine and PowerShell hosts; a real run on Windows 11 is on the verification list ([roadmap](https://github.com/aoneahsan/windowsweep/blob/main/remaining-work-summary.md)) |
+| Windows 11 | ✅ | Same engine and PowerShell hosts; a real run on Windows 11 is on the verification list ([project status](https://github.com/aoneahsan/windowsweep/blob/main/docs/features/windowsweep-completion/00-tracker.json)) |
 | Windows 10 (1809 and later) | ✅ | The primary development target; every real run so far |
-| Windows Server 2019+ | ⚠️ | Uses nothing newer than 1809; CI runs the self-test and a dry-run on Windows Server (`windows-latest`) on every push, but no real cleanup has been run on Server |
+| Windows Server 2019+ | ⚠️ | Uses nothing newer than 1809; CI runs the self-test and a dry-run on Windows Server (`windows-latest`) on every push to `main` and every pull request, but no real cleanup has been run on Server |
 | Linux | ❌ | `os: ["win32"]` makes npm refuse to install; use [linux-cleanup](https://github.com/aoneahsan/linux-cleanup) |
 | macOS | ❌ | Use [macleanup](https://github.com/aoneahsan/macleanup) |
 
@@ -177,7 +185,7 @@ survives `npx` evictions. Full detail:
 <a id="quick-start"></a>
 ## 🚀 Quick Start&nbsp;[#](#quick-start)
 
-Prove the guards, look, rehearse, then clean:
+Prove the guards, look, rehearse, then reclaim:
 
 ```powershell
 npx windowsweep --self-test
@@ -204,7 +212,7 @@ comes back but costs minutes, *Recycle Bin* is recoverable until you empty it (`
 | 1 | Package-manager caches (npm, yarn, pnpm, bun, deno, pip, uv, Composer, NuGet, Cargo, Go, pub) | rebuilds | - | safe · developer-gated |
 | 2 | Build-tool caches (Gradle, Maven, Android, Unity, JetBrains) | rebuilds | - | safe · developer-gated |
 | 3 | Test-runner browsers (Cypress, Playwright, Puppeteer) - newest kept | rebuilds | - | safe · developer-gated |
-| 4 | Android emulators idle N+ days | slow | - | opt-in |
+| 4 | Android emulators idle N+ days | slow | - | opt-in, developer-gated |
 | 5 | Docker: dangling layers, build cache, unused images older than N days | rebuilds | - | safe · developer-gated |
 | 6 | Editor caches, dead workspace storage, uninstalled extension folders | rebuilds | - | safe |
 | 7 | Browser caches, every profile (Chrome, Edge, Brave, Vivaldi, Opera, Firefox, ...) | rebuilds | - | safe |
@@ -217,24 +225,30 @@ comes back but costs minutes, *Recycle Bin* is recoverable until you empty it (`
 | 14 | Component store cleanup (DISM) | rebuilds | yes | opt-in |
 | 15 | Hibernation file off or reduced | config | yes | deep |
 | 16 | Clear Windows Event Logs | **permanent** | yes | deep |
-| 17 | Stale project build artefacts (`node_modules`, `dist`, `.next`, `target`, ...) | rebuilds | - | interactive |
+| 17 | Stale project build artefacts (`node_modules`, `dist`, `.next`, `target`, ...) | rebuilds | - | interactive, developer-gated |
 | 18 | Partial / orphan downloads | Recycle Bin | - | interactive |
 | 19 | Large stale personal files in Downloads | Recycle Bin | - | interactive |
-| 20 | Docker Desktop / WSL disk-image compaction | config | yes | deep |
+| 20 | Docker Desktop / WSL disk-image compaction | config | yes | deep, developer-gated |
 | 21 | Disk usage report | report | - | safe |
+| 22 | Global packages audit (npm, pnpm, yarn, bun, deno) - never uninstalls | report | - | safe · audit only |
+| 23 | Orphaned application data under AppData | Recycle Bin | - | interactive |
+| 24 | Installed programs not modified for N+ days - never uninstalls | report | - | safe · audit only |
+| 25 | Startup items audit - never changes them | report | - | safe · audit only |
 
 *Safe* sections run in `--all`; *opt-in* ones run when named in `--only` or a profile; *deep* ones also need
-`--i-understand-deep`; *interactive* ones never run unattended. Every section is documented in
-[Sections 0-21](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
+`--i-understand-deep`; *interactive* ones never run unattended unless you pass a selection. The three
+*audit only* sections are read-only and safe, but stay out of `--all` so a cleanup run is a cleanup run -
+`--profile audit` is where they live. Every section is documented in
+[Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
 
-### Clean interactively
+### Reclaim interactively
 
 ```powershell
 windowsweep            # guided walkthrough, one confirmation per step
 windowsweep --menu     # jump to one section; toggle dry-run and auto-yes
 ```
 
-### Clean unattended
+### Reclaim unattended
 
 ```powershell
 windowsweep --all --yes
@@ -300,9 +314,12 @@ windowsweep [mode] [options]
 | `--temp-days N` | `3` | Idle window for temp folders |
 | `--purge-all` | off | 🔥 Clear cache targets completely instead of pruning idle files |
 | `--developer`, `--not-developer`, `--forget-developer` | saved answer | Override or re-ask the developer question |
-| `--scan-roots "P1;P2"`, `--exclude-path P` | auto | Section 17 roots and exclusions |
+| `--scan-roots "P1;P2"` | auto | Section 17 project roots |
+| `--exclude-path P` | - | A tree to leave alone, in **every** section (repeatable) |
 | `--hiberfil off\|reduced\|keep` | ask | What section 15 does |
-| `--permanent` | off | Sections 18/19 delete instead of using the Recycle Bin |
+| `--permanent` | off | Sections 18, 19 and 23 delete instead of using the Recycle Bin |
+| `--select L`, `--select-file P` | off | Answer an interactive section's selection in advance, by index or by path - the one way sections 17/18/19/23 run unattended |
+| `--notify` | off | A Windows notification when the run ends |
 | `--json`, `--quiet`, `--no-color`, `--ascii`, `--no-report`, `--cleanup-logs` | off | Output and record controls |
 
 Every flag, exit code and environment variable:
@@ -313,12 +330,12 @@ Every flag, exit code and environment variable:
 
 | Goal | Command |
 |---|---|
-| See what is reclaimable, risk-free | `windowsweep --scan` |
+| See what is reclaimable, without deleting anything | `windowsweep --scan` |
 | Rehearse tonight's cleanup | `windowsweep --dry-run --all --yes` |
-| Reclaim the most space as a developer | `windowsweep --profile dev --yes` |
+| Reclaim the most space as a developer | `windowsweep --profile dev --yes --dry-run` first; the `dev` profile includes interactive section 17, so a real `--yes` run exits 3 unless you add `--select-file` |
 | Reclaim everything a non-developer can | `windowsweep --all --yes --not-developer` |
-| Find `node_modules` in projects idle 6 months | `windowsweep --only 17 --days 180 --scan-roots "D:\work"` |
-| Free the browser caches after closing the browsers | `windowsweep --only 7 --yes` |
+| Find `node_modules` in projects idle 6 months | `windowsweep --only 17 --days 180 --scan-roots "D:\work" --dry-run` |
+| Reclaim the browser caches after closing the browsers | `windowsweep --only 7 --yes` |
 | Run the admin sections | `windowsweep --profile system --yes --elevate` |
 | Weekly unattended run | `windowsweep --install-task` |
 | Machine-readable output for a script | `windowsweep --all --yes --json` |
@@ -338,7 +355,24 @@ Every flag, exit code and environment variable:
   [Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/admin-and-elevation.md)
 - **Report export** - schema-versioned JSON to Markdown or a self-contained HTML page, no extra tools.
   [Docs](https://github.com/aoneahsan/windowsweep/blob/main/docs/reports-and-logs.md)
-- **Crash bundles** - captured locally on an unexpected exit, never transmitted.
+- **Crash bundles** - the command line writes one locally on an unexpected exit, never transmitted.
+
+<a id="desktop-app"></a>
+## 🖥️ Desktop app&nbsp;[#](#desktop-app)
+
+A Tauri window that drives this engine rather than reimplementing it: it runs the bundled `windowsweep.ps1` with `--json --no-color` and carries no cleanup logic of its own. The chokepoint, the protected lists and every refusal are the command line's.
+
+- **A run you can watch.**
+- **A picker** for the four sections that ask a person to choose.
+- **Settings, most of them flags.**
+
+Screen by screen: [Desktop app](https://github.com/aoneahsan/windowsweep/blob/main/docs/desktop.md).
+
+The engine still makes no network calls at all. The window sends usage and crash reports to improve the product for everyone, and there is no switch. Never sent: a file path, a folder name, a drive label, your user name, your machine name, or the contents of anything. Sign-in is separate and optional.
+
+The installer is not signed with a paid code-signing certificate, so SmartScreen warns on first run. Every release publishes a SHA-256 checksum and a minisign signature the app's own updater checks; neither is a code-signing certificate. What to do about the dialog: [Desktop app](https://github.com/aoneahsan/windowsweep/blob/main/docs/desktop.md).
+
+Download the `.msi` or the `.exe` installer from [Releases](https://github.com/aoneahsan/windowsweep/releases). What each one installs, and what Windows says the first time: [Desktop app](https://github.com/aoneahsan/windowsweep/blob/main/docs/desktop.md).
 
 <a id="recovery-troubleshooting"></a>
 ## 🚑 Recovery & Troubleshooting&nbsp;[#](#recovery-troubleshooting)
@@ -366,7 +400,7 @@ More: [Troubleshooting](https://github.com/aoneahsan/windowsweep/blob/main/docs/
   newest of write, access and creation time - a file can only look fresher than it is, never older. Some old
   caches survive the default window; `--days` and `--purge-all` exist for that.
 - **Admin sections need an elevated console** and a UAC click; a Scheduled Task runs the safe batch only.
-- **Disk Cleanup (section 13) cannot preview** how much it will free; its dry-run lists the handlers only.
+- **Disk Cleanup (section 13) cannot preview sizes.** Its dry-run names the handlers it would run and nothing more.
 - **No automated test suite beyond `--self-test`.** Correctness rests on the self-test's fixtures, dry-runs and
   real runs on Windows 10 and 11.
 
@@ -378,8 +412,10 @@ Not from a protected folder, and not without asking. Documents, Desktop, Picture
 hard refusals. Section 17 lists build artefacts in idle projects and removes only what you select.
 
 **Does it phone home?**
-No. Zero network calls, no telemetry, no update check. The self-test greps the source for HTTP and socket
-calls; `--report-issue` opens your browser at a pre-filled page you submit yourself.
+Not the command-line tool. Zero network calls, no telemetry, no update check. The self-test greps the source for
+HTTP and socket calls; `--report-issue` opens your browser at a pre-filled page you submit yourself. The desktop
+window is a separate program and does send usage and crash reports. What it never sends is listed under [Desktop
+app](#desktop-app).
 
 **Why keep files used in the last 100 days?**
 Because a developer's caches are what make the next install fast. `--days 30` or `--purge-all` when you want
@@ -403,18 +439,21 @@ More: [FAQ](https://github.com/aoneahsan/windowsweep/blob/main/docs/faq.md).
 | [Quick start](https://github.com/aoneahsan/windowsweep/blob/main/docs/quick-start.md) | running your first cleanup |
 | [Safety model](https://github.com/aoneahsan/windowsweep/blob/main/docs/safety-model.md) | you want every guarantee spelled out before deleting anything |
 | [Developer mode](https://github.com/aoneahsan/windowsweep/blob/main/docs/developer-mode.md) | you want to know what the first question changes |
-| [Sections 0-21](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md) | you want to know precisely what one section touches |
+| [Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md) | you want to know precisely what one section touches |
 | [CLI reference](https://github.com/aoneahsan/windowsweep/blob/main/docs/cli-reference.md) | you need an exact flag, exit code or variable |
 | [Admin sections and elevation](https://github.com/aoneahsan/windowsweep/blob/main/docs/admin-and-elevation.md) | before running the system profile or touching the hibernation file |
 | [Reports and logs](https://github.com/aoneahsan/windowsweep/blob/main/docs/reports-and-logs.md) | parsing the JSON or finding a log |
+| [AI integration guide](https://github.com/aoneahsan/windowsweep/blob/main/AI-INTEGRATION-GUIDE.md) | an agent or a script runs it for you |
+| [Desktop app](https://github.com/aoneahsan/windowsweep/blob/main/docs/desktop.md) | you want the window rather than the command line |
 | [Troubleshooting](https://github.com/aoneahsan/windowsweep/blob/main/docs/troubleshooting.md) | something failed |
-| [Roadmap and remaining work](https://github.com/aoneahsan/windowsweep/blob/main/remaining-work-summary.md) | you want to know what is verified, what is planned (1.1, the docs site) and what is still open |
+| [Project status](https://github.com/aoneahsan/windowsweep/blob/main/docs/features/windowsweep-completion/00-tracker.json) | you want to know what is verified and what is still open: every phase and sub-task with its state and evidence |
 
 <a id="changelog"></a>
 ## 🔄 Changelog&nbsp;[#](#changelog)
 
-Latest release: **`1.0.1`** - `--yes` never selects personal or project items; installers refuse under npx;
-exit 130 from the engine; documentation fixes.
+Latest release: **`1.1.0`** - four new sections (global packages, orphaned app data, idle programs, startup
+items), `--select` / `--select-file` so a script or a GUI can drive the interactive sections, `--notify`, and
+`candidates[]`, `targets[]`, progress lines and `--list --json` for machine callers.
 Full history: [CHANGELOG.md](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md).
 
 <a id="contributing"></a>

package/VERSION

@@ -1 +1 @@
-1.0.1
+1.2.0