winclean-cli 0.1.0 → 0.1.1

package/DART_LICENSE

@@ -0,0 +1,26 @@
+Copyright 2012, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,41 +1,345 @@
 # winclean
 
-Windows temp and cache cleaner. Ships a self-contained `win32-x64` executable;
-no Dart SDK required.
+A junk cleaner for Windows 10 and 11 that runs in the terminal. It scans the usual temp and cache locations, lets you pick what to remove, and exits. No window, no tray icon, no background process.
 
-## Install
+**[English](#english) | [Русский](#русский)**
+
+---
+
+## English
+
+winclean removes the junk that builds up on a Windows machine: user and Windows temp files, browser caches, crash dumps, Windows Update downloads, Prefetch data, Error Reporting dumps, Windows logs, the Recycle Bin, and caches from developer tools and apps (npm, pip, uv, Pub, Go, NVIDIA, D3D, Steam, Epic, PowerToys). It does not touch cookies, browser history, downloads, or documents.
+
+Run it by hand: a keyboard-driven screen lists every discovered target with its size, you choose what to clean, and it does the work and closes. Nothing keeps running afterwards.
+
+The interface is in English.
+
+### What you need
+
+| | |
+|---|---|
+| Operating system | Windows 10 or Windows 11 (64-bit) |
+| Node.js | version 18 or newer, only for the npm launcher. The cleaner itself is a self-contained Dart AOT build and does not need Dart or Node. |
+| Terminal | Windows Terminal or PowerShell works best |
+
+A few targets (Windows temp, Windows Update cache, Prefetch, Error Reporting, Windows logs, Recycle Bin) need administrator rights. Without elevation they are shown as `needs admin` and cannot be selected. In non-interactive output they are marked `needs admin` instead of failing silently.
+
+### Install, step by step (no prior experience needed)
+
+If you have never installed a command-line tool before, follow these in order.
+
+**1. Install Node.js.**
+Node.js runs the small npm launcher. Go to [nodejs.org](https://nodejs.org), download the version labelled "LTS", and run the installer. Keep every option at its default and click through to the end.
+
+**2. Open a terminal.**
+Press the Start button, type "PowerShell", and open it. This is the window where you type commands.
+
+**3. Check that Node.js is there.**
+Type this and press Enter:
+
+```powershell
+node --version
+```
+
+If you see something like `v20.11.0`, Node.js is installed. If you get an error, close the terminal, open a new one, and try again. A fresh terminal is needed so it picks up the new installation.
+
+**4. Install winclean.**
 
 ```powershell
 npm install -g winclean-cli
 ```
 
-## Usage
+The `-g` part installs it globally, which means the `winclean` command works from any terminal.
+
+**5. Run it.**
+
+```powershell
+winclean
+```
+
+If the command is not found right after installing, close the terminal and open a new one, then run `winclean` again. The new terminal picks up the updated path.
+
+### Install from source (for developers)
+
+Requires the Dart SDK 3.11 or newer.
+
+From the repository root:
+
+```powershell
+dart pub get
+dart run bin/winclean.dart
+```
+
+There is no build step for normal use. To create the standalone AOT build:
+
+```powershell
+dart compile aot-snapshot bin/winclean.dart -o winclean.aot
+dartaotruntime winclean.aot
+```
+
+The npm package is assembled with `tool/build-npm.ps1`, which compiles the AOT snapshot and copies `dartaotruntime.exe` into `npm/vendor/`.
+
+### First run
+
+There is no setup wizard. The first launch opens the selector. Sizes are scanned in the background, rows sort largest first, and every target you are allowed to use starts selected. Uncheck anything you do not want, then press `Enter` to clean.
+
+Press `q` or `Esc` to cancel without deleting anything.
+
+### The screens
+
+| Screen | What it does |
+|---|---|
+| Select | Targets found on this machine, their size and file count, selection state, and a running total. Toggle with `Space`, confirm with `Enter`. |
+| Running | Live progress for each selected target: files, bytes, busy files, skipped links, and current state. |
+| Results | Final per-target results and totals. Errors are shown below the table. Press `q` or `Esc` to exit. |
+
+Keys: `↑↓` move, `PgUp/PgDn` scroll a page, `Home/End` jump to start or end, `Space` toggle, `Enter` confirm, `q`/`Esc` cancel or exit.
+
+### What it cleans
+
+Targets are discovered from the current machine; only existing folders appear in the selector. Rows you can use are selected by default. Admin-only rows become selectable and selected when the terminal is elevated.
+
+| Category | Admin | Notes |
+|---|:---:|---|
+| User temp | | `%TEMP%` |
+| Windows temp | admin | `%SystemRoot%\Temp` |
+| Crash dumps | | `%LOCALAPPDATA%\CrashDumps` |
+| INetCache | | `%LOCALAPPDATA%\Microsoft\Windows\INetCache` |
+| Browser caches | | Chrome, Edge, Brave `Cache` and `Code Cache` per profile; Firefox `cache2`. Logins, cookies, and history stay. |
+| Developer and tool caches | | Go build, npm, pip, uv, Pub, NVIDIA DXCache/GLCache, D3DSCache, Explorer cache, Steam htmlcache/appcache, Epic webcache, PowerToys Updates, Cryptnet URL cache. Only folders that exist are listed. |
+| System elements | | Upgrade leftovers under `%TEMP%\NLTmpMnt\...`, only when present |
+| Windows Update cache | admin | already-installed update downloads |
+| Prefetch | admin | first launch of an app afterwards is a little slower |
+| Windows Error Reports | admin | crash dumps (WER) |
+| Windows logs | admin | `%SystemRoot%\Logs` |
+| Recycle Bin | admin | deletion is irreversible |
+
+### Command-line options
 
 ```powershell
-winclean              # interactive TUI: pick targets, watch progress, review results
-winclean --dry-run    # report what would be deleted
-winclean --json       # machine-readable output
-winclean --quiet      # print only the total
-winclean --older-than 7d
+winclean --dry-run               # report what would be deleted, change nothing
+winclean --older-than 7d         # only files older than the given duration (30m, 12h, 7d)
+winclean --json                  # machine-readable output on stdout
+winclean --quiet                 # print only the total
+winclean --help
 ```
 
-Run `winclean --help` for all options.
+`--older-than 0` (the default) means no age filter.
+
+The interactive selector is used only when both stdin and stdout are terminals and neither `--json` nor `--quiet` is set. Redirected or piped output goes to the plain-text or JSON path.
+
+**Warning:** `--json`, `--quiet`, and redirected output skip the selector and process every discovered target without confirmation. Run `winclean --dry-run` first when you are unsure.
+
+Exit codes: `0` when no target reported errors, `1` when at least one target had an error, `2` for invalid arguments or an unexpected failure.
+
+### Safety
+
+The design limits the damage in advance.
+
+- A target must be an absolute path. A bare drive root such as `C:\` is always refused.
+- Protected locations (`SystemRoot`, `USERPROFILE`, `LOCALAPPDATA`, `APPDATA`, `ProgramFiles`, `ProgramData`) are never cleaned as targets. Any target that contains one of them is refused too, so `C:\`, `C:\Users`, and `C:\Windows` cannot be selected by mistake.
+- Symlinks and junctions are skipped, never followed.
+- Busy files are skipped and counted; they are not forced or retried forever.
+- Duplicate target paths are merged.
+- Missing folders are reported as `missing`, not treated as errors.
+- The cleaner never deletes the target root folder itself, only its contents.
+- Every result is reported per target, with errors and exit code.
+- There is no config file, whitelist, plugin, or command execution path. Selection is made in the TUI or by the flags above.
+
+Browser caches may be partially skipped while the browser is open because those files are busy. Close the browser for a complete clean.
+
+### Uninstall
+
+```powershell
+npm uninstall -g winclean-cli
+```
+
+The cleaner stores no settings, history, or logs. Removing the package is enough.
+
+### For developers
+
+```powershell
+dart pub get
+dart run bin/winclean.dart
+dart run bin/winclean.dart --dry-run --quiet --older-than 0
+dart test
+dart analyze lib test bin
+```
+
+When testing, never run a destructive clean (Recycle Bin, browser caches, real temp folders) on a machine you care about. Use `--dry-run`, or point the library at isolated test folders.
+
+The interactive TUI is documented in `docs/TUI_DESIGN.md` in the repository.
+
+### License
+
+[BSD 3-Clause](./LICENSE). The package includes the Dart runtime, also under the BSD 3-Clause license; see [`DART_LICENSE`](./DART_LICENSE).
+
+---
+
+## Русский
 
-## Safety
+winclean удаляет мусор, который накапливается в Windows: временные файлы пользователя и Windows, кэш браузеров, дампы после сбоев, загруженные обновления Windows, Prefetch, отчёты об ошибках, логи Windows, Корзину, а также кэш инструментов и приложений (npm, pip, uv, Pub, Go, NVIDIA, D3D, Steam, Epic, PowerToys). Cookies, историю браузера, папку «Загрузки» и документы программа не трогает.
 
-- Cleaning requires selected targets; nothing is deleted until you confirm.
-- Protected paths (`SystemRoot`, `USERPROFILE`, `LOCALAPPDATA`, `APPDATA`,
-  `ProgramFiles`, `ProgramData`) are never cleaned.
-- Windows Temp and Windows Update cache need an elevated shell.
-- `--dry-run` previews without deleting.
+Запуск ручной: экран с управлением с клавиатуры показывает найденные цели и их размер, вы выбираете, что чистить, программа делает работу и закрывается. Ничего не остаётся работать в фоне.
+
+Интерфейс на английском.
+
+### Что нужно
+
+| | |
+|---|---|
+| Операционная система | Windows 10 или Windows 11 (64-bit) |
+| Node.js | версия 18 или новее, только для npm-запускатора. Сам клинер — самостоятельная Dart AOT-сборка, Dart и Node ему не нужны. |
+| Терминал | лучше всего Windows Terminal или PowerShell |
+
+Нескольким целям (временные файлы Windows, кэш обновлений Windows, Prefetch, отчёты об ошибках, логи Windows, Корзина) нужны права администратора. Без них они показываются как `needs admin` и не выбираются. В неинтерактивном выводе они помечаются `needs admin`, а не падают молча.
+
+### Установка по шагам (опыт не нужен)
+
+Если вы никогда не ставили программы из командной строки, делайте по порядку.
+
+**1. Поставьте Node.js.**
+Node.js запускает небольшой npm-запускатор. Зайдите на [nodejs.org](https://nodejs.org), скачайте версию с пометкой «LTS» и запустите установщик. Оставляйте все галочки по умолчанию и дойдите до конца.
+
+**2. Откройте терминал.**
+Нажмите «Пуск», наберите «PowerShell» и откройте его. Это окно, куда вы вводите команды.
+
+**3. Проверьте, что Node.js на месте.**
+Введите и нажмите Enter:
+
+```powershell
+node --version
+```
+
+Если видите что-то вроде `v20.11.0`, значит Node.js установлен. Если выходит ошибка, закройте терминал, откройте новый и попробуйте снова. Новый терминал нужен, чтобы он подхватил установку.
+
+**4. Установите winclean.**
+
+```powershell
+npm install -g winclean-cli
+```
+
+Часть `-g` ставит программу глобально, то есть команда `winclean` будет работать из любого терминала.
+
+**5. Запустите.**
+
+```powershell
+winclean
+```
+
+Если сразу после установки команда не находится, закройте терминал, откройте новый и снова наберите `winclean`. Новый терминал подхватит обновлённый путь.
+
+### Установка из исходников (для разработчиков)
+
+Нужен Dart SDK 3.11 или новее.
+
+Из корня репозитория:
+
+```powershell
+dart pub get
+dart run bin/winclean.dart
+```
+
+Для обычного запуска шага сборки нет. Чтобы собрать самостоятельную AOT-сборку:
+
+```powershell
+dart compile aot-snapshot bin/winclean.dart -o winclean.aot
+dartaotruntime winclean.aot
+```
+
+npm-пакет собирается скриптом `tool/build-npm.ps1`: он компилирует AOT-снимок и копирует `dartaotruntime.exe` в `npm/vendor/`.
+
+### Первый запуск
+
+Мастера настройки нет. При первом запуске сразу открывается выбор целей. Размеры сканируются в фоне, строки сортируются от больших к меньшим, все доступные цели изначально отмечены. Снимите галочки с того, что чистить не нужно, и нажмите `Enter`.
+
+`q` или `Esc` отменяют выбор без удаления.
+
+### Экраны
+
+| Экран | Что делает |
+|---|---|
+| Выбор | Найденные на машине цели, их размер и число файлов, состояние выбора и общий итог. `Space` переключает, `Enter` подтверждает. |
+| Выполнение | Живой прогресс по каждой выбранной цели: файлы, байты, занятые файлы, пропущенные ссылки, состояние. |
+| Результаты | Итог по каждой цели и общий итог. Ошибки показываются под таблицей. `q` или `Esc` — выход. |
+
+Клавиши: `↑↓` перемещение, `PgUp/PgDn` прокрутка страницей, `Home/End` в начало или конец, `Space` переключить, `Enter` подтвердить, `q`/`Esc` отмена или выход.
+
+### Что чистит
+
+Цели ищутся на текущей машине; в списке появляются только существующие папки. Доступные строки отмечены по умолчанию. Строки, требующие администратора, становятся доступными и отмеченными, если терминал запущен с повышением прав.
+
+| Категория | Админ | Примечания |
+|---|:---:|---|
+| Временные файлы пользователя | | `%TEMP%` |
+| Временные файлы Windows | админ | `%SystemRoot%\Temp` |
+| Дампы после сбоев | | `%LOCALAPPDATA%\CrashDumps` |
+| INetCache | | `%LOCALAPPDATA%\Microsoft\Windows\INetCache` |
+| Кэш браузеров | | Chrome, Edge, Brave: `Cache` и `Code Cache` по профилям; Firefox: `cache2`. Входы, cookies и история остаются. |
+| Кэш инструментов и приложений | | Go build, npm, pip, uv, Pub, NVIDIA DXCache/GLCache, D3DSCache, кэш Explorer, Steam htmlcache/appcache, Epic webcache, PowerToys Updates, Cryptnet URL cache. Показываются только существующие папки. |
+| Элементы системы | | Остатки обновления в `%TEMP%\NLTmpMnt\...`, только если есть |
+| Кэш обновлений Windows | админ | уже установленные файлы обновлений |
+| Prefetch | админ | первый запуск программы после этого чуть медленнее |
+| Отчёты об ошибках Windows | админ | дампы WER |
+| Логи Windows | админ | `%SystemRoot%\Logs` |
+| Корзина | админ | удаление необратимо |
+
+### Параметры командной строки
+
+```powershell
+winclean --dry-run               # показать, что было бы удалено, ничего не меняя
+winclean --older-than 7d         # только файлы старше указанного срока (30m, 12h, 7d)
+winclean --json                  # машиночитаемый вывод в stdout
+winclean --quiet                 # печатать только итог
+winclean --help
+```
+
+`--older-than 0` (значение по умолчанию) означает отсутствие фильтра по возрасту.
+
+Интерактивный выбор используется, только когда stdin и stdout — терминалы и не заданы `--json` или `--quiet`. При перенаправлении вывода программа переходит в обычный текстовый или JSON-режим.
+
+**Внимание:** `--json`, `--quiet` и перенаправленный вывод пропускают экран выбора и обрабатывают все найденные цели без подтверждения. Если не уверены, сначала запустите `winclean --dry-run`.
+
+Коды выхода: `0` — ни одна цель не сообщила об ошибке, `1` — хотя бы одна цель с ошибкой, `2` — неверные аргументы или непредвиденный сбой.
+
+### Безопасность
+
+Программа заранее ограничивает ущерб.
+
+- Цель должна быть абсолютным путём. Голый корень диска вроде `C:\` всегда отклоняется.
+- Защищённые каталоги (`SystemRoot`, `USERPROFILE`, `LOCALAPPDATA`, `APPDATA`, `ProgramFiles`, `ProgramData`) никогда не чистятся как цели. Любая цель, которая содержит такой каталог, тоже отклоняется, поэтому `C:\`, `C:\Users` и `C:\Windows` нельзя выбрать по ошибке.
+- Символические ссылки и junction-точки пропускаются, по ним программа не идёт.
+- Занятые файлы пропускаются и подсчитываются; их не пытаются удалить силой и не повторяют бесконечно.
+- Дублирующиеся пути целей объединяются.
+- Отсутствующие папки помечаются как `missing`, а не считаются ошибкой.
+- Корневая папка цели не удаляется, очищается только её содержимое.
+- Результат по каждой цели выводится отдельно, с ошибками и кодом выхода.
+- Нет файла конфигурации, whitelist, плагинов и путей выполнения команд. Выбор делается в TUI или параметрами выше.
+
+Кэш браузера может очиститься не полностью, если браузер открыт: занятые файлы пропускаются. Для полной очистки закройте браузер.
+
+### Удаление
+
+```powershell
+npm uninstall -g winclean-cli
+```
+
+Программа не хранит настройки, историю или логи. Удаления пакета достаточно.
+
+### Для разработчиков
+
+```powershell
+dart pub get
+dart run bin/winclean.dart
+dart run bin/winclean.dart --dry-run --quiet --older-than 0
+dart test
+dart analyze lib test bin
+```
 
-## Requirements
+При тестировании никогда не запускайте удаляющую чистку (Корзина, кэш браузеров, реальные временные папки) на машине, которую жалко. Используйте `--dry-run` или направьте библиотеку на изолированные тестовые папки.
 
-- Windows x64
-- Node.js 18 or newer (only for the npm launcher)
+Устройство интерактивного TUI описано в `docs/TUI_DESIGN.md` в репозитории.
 
-The interactive TUI needs both stdin and stdout attached to a terminal.
-Redirected or piped output uses plain text or JSON instead.
+### Лицензия
 
-The executable is not code-signed. Windows Smart App Control may block
-unsigned programs; if Windows blocks it, use a signed release when available.
+[BSD 3-Clause](./LICENSE). В пакет входит runtime Dart, тоже под лицензией BSD 3-Clause; см. [`DART_LICENSE`](./DART_LICENSE).

package/bin/winclean.js

@@ -4,12 +4,16 @@
 const { spawn } = require('node:child_process');
 const path = require('node:path');
 
-const exe = path.join(__dirname, '..', 'vendor', 'winclean.exe');
+const vendor = path.join(__dirname, '..', 'vendor');
+const runtime = path.join(vendor, 'dartaotruntime.exe');
+const snapshot = path.join(vendor, 'winclean.aot');
 
-const child = spawn(exe, process.argv.slice(2), { stdio: 'inherit' });
+const child = spawn(runtime, [snapshot, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
 
 child.on('error', (error) => {
-  console.error(`winclean: failed to launch ${exe}: ${error.message}`);
+  console.error(`winclean: failed to launch ${runtime}: ${error.message}`);
   process.exit(1);
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "winclean-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Windows temp and cache cleaner with an interactive TUI",
   "license": "BSD-3-Clause",
   "author": "winclean contributors",
@@ -9,7 +9,9 @@
   },
   "files": [
     "bin/winclean.js",
-    "vendor/winclean.exe",
+    "vendor/dartaotruntime.exe",
+    "vendor/winclean.aot",
+    "DART_LICENSE",
     "README.md",
     "LICENSE"
   ],