Pristine Cleaner is a desktop file cleaning utility built with Flutter.
It provides a modern sidebar-driven interface to:
- inspect disk usage,
- scan for removable clutter,
- select files/folders/apps to remove,
- move selected items to Trash/Recycle Bin.
Supported desktop targets:
- macOS
- Linux
- Windows
- Reads disk capacity, used space, and free space.
- Shows usage percentage and progress indicators.
- Refresh action re-queries system disk information.
- Scans common cache/temp/log locations.
- Returns itemized results with size totals.
- Supports select/deselect, rescan, and clean actions.
- Two scan modes:
- Large Files (default threshold: 50 MB)
- Downloads folder contents
- Supports item selection and cleanup flow.
- Scans top folders in the user home directory.
- Computes folder sizes and displays storage distribution.
- Supports selection and cleanup.
- Scans installed application directories by platform.
- Returns apps/folders sorted by size.
- Supports selection and cleanup.
- Flutter (desktop)
- Dart
flutter_riverpodfor state managementgo_routerfor navigation/routingwindow_managerfor custom desktop window behaviorfile_picker,path_provider,intl,image- Fastforge (
distribute_options.yaml) for desktop packaging - GitHub Actions + GitHub Releases for release artifact publishing
- Flutter SDK compatible with
sdk: ^3.11.5 - Desktop toolchains installed for your target OS:
- Xcode + Cocoa tools (macOS)
- Visual Studio Build Tools (Windows)
- GTK/CMake toolchain (Linux)
- Install dependencies:
flutter pub get- Run on your current desktop platform:
flutter run- Run on a specific desktop device:
flutter run -d macos
flutter run -d windows
flutter run -d linuxThe desktop app icon is generated with icons_launcher using the source image at assets/images/PristineCleanerIcon.png.
- Fetch dependencies if needed:
flutter pub get- Generate the launcher icons from
pubspec.yaml:
dart run icons_launcher:create --path pubspec.yamlThis updates the platform-specific icon assets for the desktop targets configured in the package:
- macOS:
macos/Runner/Assets.xcassets/AppIcon.appiconset - Linux:
snap/gui/ - Windows:
windows/runner/resources/app_icon.ico
flutter build macos
flutter build windows
flutter build linuxdart run build_runner buildDesktop release packaging is configured in distribute_options.yaml and automated by .github/workflows/release-desktop.yml.
- Triggered by pushing tags that match
v*. - Can also run manually via
workflow_dispatchwith an optionalrelease_taginput. - Build phase (
.github/workflows/release-desktop.yml):- Builds desktop artifacts with Fastforge for macOS (DMG), Windows (EXE/MSIX), and Linux x86_64 (DEB/RPM).
- Signs and submits the macOS DMG to Apple notarization using
notarytoolwith--no-wait. - Uploads the macOS DMG as a workflow artifact named
unnotarized-dmg. - Uploads Windows and Linux artifacts to GitHub Releases.
- Finalize phase (
.github/workflows/release-desktop-finalize.yml):- Triggered by
repository_dispatchevent typenotarization_complete(sent by Cloudflare Worker). - Downloads
unnotarized-dmgfrom the originating workflow run byrun_id. - Staples and validates the DMG, then uploads the stapled DMG to the target release tag.
- Triggered by
Required secrets for async notarization callback:
PRISTINE_CLEANER_WORKER_URL: Cloudflare Worker endpoint used as Apple notarization webhook.PRISTINE_CLEANER_WORKER_SECRET: shared secret appended to webhook query string and validated by the worker.
dart pub global activate fastforge 0.6.6
fastforge release --name desktop-macos --skip-clean
fastforge release --name desktop-windows --skip-clean
fastforge release --name desktop-linux-x64 --skip-cleanArtifacts are written to dist/.
- Clean actions use OS-native trash flows when possible:
- macOS: AppleScript/Finder delete
- Linux:
gio trash(fallback:gvfs-trash) - Windows: PowerShell + Recycle Bin API
- If trash move fails, code falls back to permanent delete for that item.
- File-system errors during scanning/deletion are caught to keep UI responsive.
- Very large recursive scans can be time-consuming on slow disks.
- CI release matrix currently builds Linux
x86_64artifacts only (ARM64 definitions exist indistribute_options.yamlbut are not included in the workflow matrix). - Async macOS finalization depends on Apple webhook delivery and Cloudflare Worker dispatch reliability.
- In-app update checks use GitHub Releases from
RabinApps/PristineCleaner. - Latest release metadata endpoint:
https://api.github.com/repos/RabinApps/PristineCleaner/releases/latest
- Release tags are expected to keep the
vprefix (for examplev1.2.3). - Installer selection is architecture-aware:
- macOS: DMG
- Windows: EXE preferred (MSIX fallback)
- Linux: DEB preferred (RPM fallback)
- Architecture matching rules:
x86_64aliases:x86_64,x64,amd64arm64aliases:arm64,aarch64
- Current release workflow publishes Linux x86_64 artifacts only; Linux arm64 hosts are currently treated as unsupported by the updater.
- App display name/title:
PristineCleaner - Bundle/Application identifiers currently set to:
- macOS bundle ID:
com.rabinapps.pristinecleaner - Linux application ID:
com.rabinapps.pristinecleaner - Windows metadata namespace:
com.rabinapps.pristinecleaner
- macOS bundle ID:
flutter doctor
flutter analyze
flutter testThis project includes a Patrol end-to-end smoke test at patrol_test/app_test.dart.
- Install Patrol CLI:
dart pub global activate patrol_cli- Ensure Dart global executables are on your shell
PATH(zsh example):
export PATH="$PATH:$HOME/.pub-cache/bin"- Verify environment readiness:
patrol doctor- Run Patrol E2E on macOS:
patrol test -d macos --target patrol_test/app_test.dart