windowsweep 1.0.1 → 1.2.0

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +1,203 @@
+# AI integration guide
+
+This is the contract an automated caller can rely on: what windowsweep promises, what it refuses, what it
+prints, and what it returns. It is written for an agent or a script rather than a person. For what the tool
+*is*, read the [README](https://github.com/aoneahsan/windowsweep#readme); for what each section touches, read
+[Sections 0-25](https://github.com/aoneahsan/windowsweep/blob/main/docs/sections.md).
+
+**windowsweep deletes files.** Every command below that is not marked read-only can remove data. There is no
+undo for caches. Treat a real run as an irreversible operation and preview it first.
+
+## The safe sequence
+
+```powershell
+npx windowsweep --self-test --no-color --no-report     # read-only: proves the guards on this machine
+npx windowsweep --scan --no-color --no-report          # read-only: every target and its size
+npx windowsweep --dry-run --all --yes --no-color       # writes nothing; reports what a real run would remove
+npx windowsweep --all --yes --no-color                 # the real safe batch
+```
+
+Add `--json` when a program reads the result. In that mode **stdout carries exactly one line, the JSON
+summary**, and every human-readable line goes to stderr. `--json` also implies `--quiet`.
+
+## What `--yes` covers, and what it never covers
+
+`--yes` auto-confirms **regenerable caches only**: sections 0-3, 5-10, 21, and 12-13 when the console is
+already elevated.
+
+| Never covered by `--yes` | Behaviour |
+|---|---|
+| Sections 17, 18, 19, 23 | The selection prompt appears even with `--yes` and defaults to none. With no console attached nothing is selected, and each asks a final question `--yes` does not answer. Only `--select` / `--select-file` supply a choice (see below) |
+| Sections 11, 15, 16, 20 | Deep. Refused in batch mode unless `--i-understand-deep` is also passed |
+| `--uninstall-data` | Always asks; `--yes` does not answer it |
+| `--purge-all` | From a console it asks for a typed `purge` once per run. In a batch run `--yes` is the confirmation |
+
+In batch mode (`--all`, `--only`, `--profile`) sections 17, 18, 19 and 23 are refused outright and reported as
+`refused`, unless a `--select` or `--select-file` choice was supplied. They need a person choosing items -
+in advance is fine, absent is not.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | A section failed, or the self-test found a failure |
+| 2 | Usage error, or an interactive mode was started without a console |
+| 3 | A section named in `--only` was refused, or an installer was started from `npx` |
+| 130 | Interrupted before the run finished (Ctrl-C) |
+
+## Flags that matter to automation
+
+| Flag | Effect |
+|---|---|
+| `--json` | One JSON line on stdout; everything else on stderr. Implies `--quiet` |
+| `--no-color`, `--ascii` | Disable colour and Unicode glyphs. Both are automatic when output is redirected |
+| `--no-report` | Skip the JSON report file; the session log is still written |
+| `--cleanup-logs` | Delete this run's log at exit; reports are kept |
+| `--quiet` | Fewer informational lines |
+| `--only L`, `--profile NAME`, `--exclude L` | Choose sections: `--only 1,3,5-7`; profiles `dev`, `minimal`, `cache-only`, `system`, `deep`, `audit` |
+| `--days N`, `--temp-days N` | Idle windows, default 100 and 3 |
+| `--developer`, `--not-developer` | Override the saved developer answer for this run |
+| `--scan-roots "P1;P2"`, `--exclude-path P` | Section 17 roots and exclusions |
+| `--logs-dir P`, `--reports-dir P` | Redirect this run's output |
+| `--select L`, `--select-file P` | Supply an interactive section's selection in advance, by index or by full path. The only way sections 17/18/19/23 run unattended |
+| `--notify` | A Windows notification when the run ends. Never changes the exit code, never writes to stdout |
+| `--list --json` | Print the section catalogue as one JSON line instead of the human table |
+| `--pwsh` | Launcher only: run the engine on PowerShell 7 |
+
+A non-interactive run with no saved developer answer defaults to developer mode **on**, the conservative
+choice, and says so.
+
+## The `--json` line
+
+```json
+{"tool":"windowsweep","version":"1.1.0","mode":"all","dry_run":false,"elevated":false,"developer":true,
+ "freed_bytes":0,"estimated_bytes":0,
+ "sections":[{"section":1,"status":"ran","freed_bytes":0}],
+ "candidates":[],"targets":[],
+ "refusals":[],"excluded":[],"log_file":"...","report_file":"..."}
+```
+
+| Key | Meaning |
+|---|---|
+| `tool`, `version` | Always `windowsweep` and the running version |
+| `mode` | `all`, `only`, `scan`, `walkthrough`, `menu`, ... |
+| `dry_run`, `elevated` | The two booleans that change what a run does |
+| `developer` | `true`, `false`, or `null` in a mode that never resolves the question (`--scan`, `--list`) |
+| `freed_bytes` | Real bytes removed. `0` in a dry-run |
+| `estimated_bytes` | What a dry-run says a real run would remove. `0` in a real run |
+| `sections[]` | One entry per section attempted: `section`, `status`, `freed_bytes` |
+| `candidates[]` | What an interactive section offered: `section`, `index`, `path`, `bytes`, `idle_days`, `project`. Always present, empty when none were collected |
+| `targets[]` | Scan mode only: `section`, `label`, `path`, `bytes`, `newest_write_utc`. Always present, empty otherwise |
+| `refusals[]` | Human-readable reasons a section was refused in batch mode, plus one `excluded: <path>` line per honoured `--exclude-path` |
+| `excluded[]` | Every path an exclusion actually kept, listed once each. Empty means "nothing was excluded", never "not reported" |
+| `log_file`, `report_file` | Absolute paths, or `null` under `--no-report` |
+
+`status` is one of `ran`, `dry-run`, `skipped`, `refused`, `failed`.
+
+`newest_write_utc` is ISO 8601 UTC (`2026-09-08T13:14:15Z`) - the newest of write, access and creation time
+found anywhere under that target, which is the same rule the idle gate uses. It is **`null`** when the
+target is absent or holds no files, rather than a zero date a caller would sort as if it were real. It is
+emitted only under `--json`, because computing it needs the file walk that `--json` already performs.
+
+## Where output lands
+
+| Item | Path |
+|---|---|
+| Session logs | `%USERPROFILE%\.windowsweep\logs\` |
+| JSON reports and exports | `%USERPROFILE%\.windowsweep\reports\` |
+| Debug and crash bundles | `%USERPROFILE%\.windowsweep\feedback\` |
+| Settings | `%USERPROFILE%\.windowsweep\config.json` |
+
+Override the root with `WINDOWSWEEP_HOME`, or the two folders with `--logs-dir` / `--reports-dir`
+(`WINDOWSWEEP_LOG_DIR` / `WINDOWSWEEP_REPORTS_DIR`). `WINDOWSWEEP_NO_COLOR`, `NO_COLOR` and
+`WINDOWSWEEP_ASCII` are honoured; `WINDOWSWEEP_SHELL=pwsh` selects PowerShell 7 through the Node launcher.
+
+The report file is schema-versioned JSON (`schema_version: 1`) with five top-level blocks: `credits`, `meta`
+(times, host, OS, PowerShell version, mode, the three flags, the idle windows, the launcher), `disk`
+(`before` and `after` snapshots per fixed drive), `steps` (one row per section with `status` and
+`freed_bytes`), and `totals`. `--export md|html|both [N|latest|all]` renders any report to Markdown or a
+self-contained HTML page without extra tools.
+
+## Elevation
+
+Sections 12-16 and 20 need Administrator rights. Without them the runner skips each with the exact command
+to run. `--elevate` relaunches the whole run through a UAC prompt: **a new elevated window opens with its own
+log and report**, and the original process waits and returns the child's exit code. That prompt cannot be
+answered by a script, so `--elevate` does not belong in an unattended context.
+
+## Guarantees
+
+- - **No network calls of its own**. Self-test check [9] greps every source file for `Invoke-WebRequest`, `Invoke-RestMethod`, `Net.WebClient`, `HttpClient`, `Sockets.TcpClient`, `curl.exe` and `wget`, and fails the run if it finds one. There is no telemetry and no update check. `--report-issue` and `--feedback` hand a URL to the user's browser after they confirm, and neither belongs in an unattended run.
+- - **Every deletion of anything on the user's machine passes one chokepoint** with a declared root, and is refused if it falls outside it. windowsweep's own logs, reports and fixtures are the exception, reachable only through `--cleanup-logs`, `--prune-history` and `--uninstall-data`.
+- - **Protected paths are refused regardless of flags**: every drive root, fifteen declared roots (Windows, System32, SysWOW64, both Program Files folders, ProgramData, `C:\Users` with Default and Public, the profile root, and the AppData Roaming, Local and LocalLow folders), 66 protected subtrees, 50 path patterns and 13 file names. Two paths are declared exceptions - `%LOCALAPPDATA%\Android\Sdk\.temp` and `.downloadIntermediates` - and there are no others. No flag bypasses any of it.
+- **Junctions and symlinks are removed as links, never followed.**
+- **`--dry-run` and `--scan` write nothing** but the log and the report.
+- **Section numbers are a public contract.** 0-25 today; a section may be retired as a no-op, and a number is
+  never reused. Read `--list --json` rather than hard-coding the set.
+- **Zero runtime dependencies.** The package is PowerShell plus a Node launcher that uses only built-in
+  modules.
+
+## Do not
+
+- Do not run `npx windowsweep` from a directory that contains a checkout of this repository: npx resolves the
+  local package and the command fails. Run it from anywhere else.
+- Do not schedule `npx windowsweep` as a task action. The npx cache is evicted and the task breaks; install
+  globally and use `--install-task`, which refuses under npx for this reason.
+- Do not pipe `y` into the tool to force a personal section. Sections 17, 18, 19 and 23 are interactive by
+  design and a piped answer selects nothing - pass `--select` or `--select-file` instead, which is the
+  supported way and names exactly what goes.
+- Do not treat a green `--dry-run` as proof that a real run frees the same amount: an app that is open at run
+  time keeps its caches.
+
+## Driving the interactive sections (1.1.0+)
+
+Sections 17, 18, 19 and 23 refuse to run unattended, because they delete things a person should choose. Two
+flags supply that choice in advance, and either one lifts the refusal:
+
+```powershell
+# 1. list what the section would offer - deletes nothing
+npx windowsweep --only 17 --dry-run --json --no-color
+#    -> read .candidates[] from the single stdout line:
+#       { "section": 17, "index": 1, "path": "...", "bytes": 0, "idle_days": 400, "project": "..." }
+
+# 2. act on exactly the ones you chose
+npx windowsweep --only 17 --select 1,3            # by index, one list per prompt, in prompt order
+npx windowsweep --only 17 --select-file picks.txt # by full path, one per line, UTF-8, # comments allowed
+```
+
+Rules a caller can rely on:
+
+- **`--yes` alone still selects nothing.** It never has. Only `--select` / `--select-file` do.
+- The scripted selection also answers that section's final confirmation, so the run does not stall.
+- `--select` is repeatable and consumed one list per prompt; `--select-file` is offered to every prompt, so
+  a line that matches nothing in a given section is reported once and skipped.
+- Neither flag reaches a path the deletion chokepoint would otherwise refuse.
+
+## Reading the catalogue and following progress
+
+```powershell
+npx windowsweep --list --json
+```
+
+One stdout line: `sections[]` (`id`, `key`, `title`, `tier`, `admin`, `batch`, `dev`), `safe_batch`,
+`safe_batch_admin`, `profiles`, `walkthrough`, `walkthrough_admin`. Read it instead of hard-coding section
+numbers - they are frozen, but the set grows.
+
+In `--json` mode every section brackets itself on **stderr**:
+
+```text
+##windowsweep section=7 event=start
+##windowsweep section=7 event=end status=ran freed_bytes=4096
+```
+
+`status` is one of `ran`, `dry-run`, `skipped`, `refused`, `failed`. Scan mode also fills `targets[]`
+(`section`, `label`, `path`, `bytes`, `newest_write_utc`) in the final JSON line. `candidates` and `targets`
+are always present, empty when nothing was collected.
+
+## The read-only audits
+
+`--profile audit` runs sections 0, 21, 22, 24 and 25 and deletes nothing in any mode: the health report, disk
+usage, globally installed packages, installed programs not modified for `--days`+ days, and startup items.
+Sections 22, 24 and 25 print removal commands but never execute one, and section 25 never changes a startup
+entry. Section 24 reports "not modified", not "not used" - Windows keeps no reliable last-launched record.

package/CHANGELOG.md

@@ -7,6 +7,130 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ---
 
+## [Unreleased]
+
+## [1.2.0] - 2026-09-08
+
+### Added
+
+- **`targets[].newest_write_utc` in `--scan --json`.** ISO 8601 UTC, the newest of write, access and creation
+  time found anywhere under the target - the same rule the idle gate uses - or `null` when the target is
+  absent or holds no files. It costs no extra walk: under `--json` the size pass already enumerates every
+  file, so the timestamp comes out of that same enumeration. A human `--scan` keeps the faster path.
+- **`protected` in `--list --json`.** `subtrees` (every protected folder, resolved for this machine) and
+  `categories` (the same four sentences `--list-targets` prints). Both readers now take the category list
+  from one constant, so the machine-readable copy cannot quietly promise less than the console does.
+- **`excluded[]` in the `--json` summary**, naming every path an exclusion actually kept, once each.
+
+### Changed
+
+- **`--exclude-path` is honoured in every section, not only section 17.** It was parsed globally and read by
+  exactly one consumer, so someone who excluded a folder was protected in one section and silently not in the
+  other twenty-five. It is now enforced at the deletion chokepoint itself - the one place every section
+  already passes through - and an excluded path is refused, logged as `excluded: <path>` and reported in
+  `excluded[]`. The same reach applies to `excludePaths` in the config file. **No deletion behaviour widens:
+  `--exclude-path` only ever refuses more.** A path that is both protected and excluded still reports the
+  protected reason, because that is the promise no flag can lift.
+
+### Fixed
+
+- 🔴 **`--exclude-path` only ever refused the path you named, never anything inside it.** The normalised
+  prefix was built with a PowerShell literal `'\'`, which is **two** characters, so the prefix ended in a
+  doubled backslash and no child path could ever match it. Excluding a folder protected the folder and
+  nothing in it - which is the opposite of what anyone excluding a folder means. The self-test check that
+  was supposed to cover this asserted only on the excluded path itself, so it passed throughout; it now
+  asserts on a child, and the fix was watched failing on the original bug reintroduced.
+- 🔴 **A dry-run counted files a real run would skip.** `Remove-StaleFiles` applied the protection guard
+  only in its real-run loop, so the rehearsal's estimate included protected and excluded files that the run
+  then refused - for exactly the files a person most wants the two numbers to agree about. One filter now
+  decides both, and a check proves a dry-run and a real prune report the same count and the same bytes.
+- **`--help` said `--permanent` covers "Sections 18/19".** It reaches **18, 19 and 23**: `Send-ToRecycleBin`
+  is called from `modules/personal.ps1` (18, 19) and from `modules/orphaned_appdata.ps1` (23). Someone who
+  passed `--permanent` believing it applied to two sections would have had section 23's orphaned
+  application data deleted outright instead of recycled. The reference docs already said 18, 19 and 23;
+  only the engine's own help text - the one place a person actually reads it from - was wrong.
+- **Section 22 declared `Dev = $true` with no behavioural branch**, so `--list --json` advertised a developer
+  flag that changed nothing. It now reads `false`, and the Dev column in `docs/sections.md` agrees.
+- 🔴 **`--scan` parsed `--developer` and `--not-developer` and then never read them.**
+  `Resolve-DeveloperMode` ran only for the walkthrough, the menu, `--all` and `--only`, so in scan mode the
+  flag reached `DeveloperFlag` and nothing looked at it: section 0 printed `Developer mode: not decided yet`
+  whatever you passed, and `--json` returned `developer: null`. The desktop window sends those flags to
+  `--scan` and could not read back the setting it had just sent. A scan now resolves it from the flag or the
+  saved answer and stops there - it may not ask the question, may not write `config.json`, and may not invent
+  a decision you never made, so with neither a flag nor a saved answer it still reports "not decided yet",
+  which is the truth. **No scan result changes:** the scan reports what is on disk, not what a run would
+  remove, and `Show-ScanTable` never read the developer answer in the first place.
+- **The hibernation target's one-line note contradicted the section's own explanation two lines below.** It
+  said `reduced` keeps Fast Startup "at roughly 40% of RAM", which is the size of the **whole** file; the
+  section intro says `reduced` is about half of that. The note now states the figure once, on the thing it
+  belongs to: the full file is about 40% of RAM and `reduced` keeps roughly half that.
+
+## [1.1.0] - 2026-09-04
+
+### Added
+
+- **Section 22 - global packages audit.** Lists what npm, pnpm, yarn, bun and deno installed globally with
+  size and idle days, flags the ones no recent project references, and prints the exact uninstall command.
+  It never uninstalls anything and declares no deletable target: several of those roots are protected paths.
+- **Section 23 - orphaned application data.** Top-level folders under `%APPDATA%` and `%LOCALAPPDATA%` that
+  no installed program, Store package or running process claims and that nothing has touched for `--days`+
+  days. Interactive, Recycle Bin, and it **fails closed** - an unreadable uninstall registry produces zero
+  candidates rather than treating everything as orphaned. Every vendor folder another section already cleans
+  is excluded automatically, derived from the declared target list so the exclusions cannot drift.
+- **Section 24 - installed programs not modified for N+ days.** Report only, largest first, with
+  `winget uninstall --id` when one `winget list` call resolves the program and its own `UninstallString`
+  otherwise; Store apps listed separately. It never runs an uninstaller.
+- **Section 25 - startup items audit.** Run and RunOnce keys, both Startup folders, logon-triggered scheduled
+  tasks and `Win32_StartupCommand` in one table with each item's enabled state. It changes nothing.
+- **`--select L` and `--select-file P`.** Answer an interactive section's selection in advance, by index or
+  by full path. Either flag lets sections 17, 18, 19 and 23 run unattended - a person did choose - and the
+  selection answers that section's final confirmation. `--yes` alone still selects nothing.
+- **`--notify`.** A Windows notification when a run ends: a real toast on Windows PowerShell 5.1, a tray
+  balloon on PowerShell 7. It never changes the exit code and never writes to stdout. `--install-task` adds
+  it to the weekly task, so the Sunday run reports itself.
+- **`--json` additions.** `candidates[]` (what an interactive section offered) and `targets[]` (what scan
+  mode measured), both always present so a caller can rely on the shape, plus per-section progress lines on
+  stderr: `##windowsweep section=NN event=start|end status=<status> freed_bytes=<n>`.
+- **`--list --json`** prints the section catalogue - sections, tiers, batch policy, the safe batch, the
+  profiles and the walkthrough order - so a front end reads it instead of hard-coding it.
+- Section 1 gained the Hugging Face model cache (`~\.cache\huggingface\hub`, pruned by the idle gate,
+  developer-gated). Section 9 lists `wsreset.exe` as the Microsoft Store cache lever and offers it as a next
+  step rather than running it: `wsreset` has no silent mode and always opens the Store.
+- Section 17 recognises `.nx`, `.mypy_cache`, `.ruff_cache`, `.tox`, `.eggs`, `.output` and `.serverless`,
+  and treats `.cache` as an artefact only when a Gatsby or Parcel config sits beside it. `.venv`, `venv` and
+  `.terraform` are deliberately still excluded.
+- `docs/sections.md` records the candidate targets that are researched but **not** shipped because the
+  software is not installed on the build machine, and why `C:\Intel` was inspected and rejected.
+
+### Fixed
+
+- `Get-OrphanExclusions` returned its exclusion set as an unrolled array, whose `.Contains` is
+  case-sensitive, so a folder named `slack` would have slipped past the `Slack` entry. Found by a new check
+  before the section shipped.
+- Section 24's idle measurement used the newest of write, access and creation time. Last-access is live on
+  many systems, so every install folder read as touched today and the section could never report anything;
+  it now reads last-write only, which is what "not modified" means.
+
+### Changed
+
+- The target table is collected from the section catalogue instead of a literal `0..21` range, so a new
+  section is reachable by `--scan`, `--list-targets` and the safety checks the moment it is declared. The
+  menu's prompt range is derived the same way.
+- Profile `audit` is now `0, 21, 22, 24, 25`. The three new report sections are read-only and safe, but stay
+  out of `--all` so a cleanup run remains a cleanup run.
+- Self-test: 27 more checks (151 total) cover the catalogue, section 23's fail-closed gate and derived
+  exclusions, section 22 declaring nothing deletable, the scripted-selection flags, the `--json` and
+  catalogue shapes, the progress-line format, the global-package verdict, the startup-state rule and the
+  artefact list. Each was proved red against a planted defect before it was kept.
+- Self-test: ten more checks cover the argument parser, section lists, docker size text, the layout-guard leaf
+  test, the `--json` shape, superseded versions, the Chromium layout, workspace storage, stale artefacts and
+  the report exporters. `Test-KnownCacheLeaf` and `Get-JsonSummary` were split out of `Invoke-TargetList` and
+  `Write-JsonSummary` so the logic can be exercised directly; no behaviour changed.
+- `AI-INTEGRATION-GUIDE.md` ships in the npm package and is mirrored on the documentation site: the contract
+  an agent or a script relies on - the safe command sequence, what `--yes` never covers, exit codes, the
+  `--json` line, output paths and the guarantees.
+- A documentation site at `windowsweep-docs.aoneahsan.com` (Docusaurus on GitHub Pages), mirroring `docs/`.
+
 ## [1.0.1] - 2026-09-03
 
 ### Fixed

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Ahsan Mahmood
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Ahsan Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.