Skip to content

About

Pristine Cleaner is a desktop file cleaning utility built with Flutter.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Pristine Cleaner

Donate Buy me a coffee

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

What Is Implemented

Home

  • Reads disk capacity, used space, and free space.
  • Shows usage percentage and progress indicators.
  • Refresh action re-queries system disk information.

Cleanup

  • Scans common cache/temp/log locations.
  • Returns itemized results with size totals.
  • Supports select/deselect, rescan, and clean actions.

Clutter

  • Two scan modes:
    • Large Files (default threshold: 50 MB)
    • Downloads folder contents
  • Supports item selection and cleanup flow.

Space View

  • Scans top folders in the user home directory.
  • Computes folder sizes and displays storage distribution.
  • Supports selection and cleanup.

Applications

  • Scans installed application directories by platform.
  • Returns apps/folders sorted by size.
  • Supports selection and cleanup.

Tech Stack

  • Flutter (desktop)
  • Dart
  • flutter_riverpod for state management
  • go_router for navigation/routing
  • window_manager for custom desktop window behavior
  • file_picker, path_provider, intl, image
  • Fastforge (distribute_options.yaml) for desktop packaging
  • GitHub Actions + GitHub Releases for release artifact publishing

Requirements

  • 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)

Getting Started

  1. Install dependencies:
flutter pub get
  1. Run on your current desktop platform:
flutter run
  1. Run on a specific desktop device:
flutter run -d macos
flutter run -d windows
flutter run -d linux

App Icon Generation

The desktop app icon is generated with icons_launcher using the source image at assets/images/PristineCleanerIcon.png.

  1. Fetch dependencies if needed:
flutter pub get
  1. Generate the launcher icons from pubspec.yaml:
dart run icons_launcher:create --path pubspec.yaml

This 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

Build Commands

flutter build macos
flutter build windows
flutter build linux

Update Translations

dart run build_runner build

Release and Distribution

Desktop release packaging is configured in distribute_options.yaml and automated by .github/workflows/release-desktop.yml.

CI release flow

  • Triggered by pushing tags that match v*.
  • Can also run manually via workflow_dispatch with an optional release_tag input.
  • 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 notarytool with --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_dispatch event type notarization_complete (sent by Cloudflare Worker).
    • Downloads unnotarized-dmg from the originating workflow run by run_id.
    • Staples and validates the DMG, then uploads the stapled DMG to the target release tag.

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.

Local packaging command (without upload)

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-clean

Artifacts are written to dist/.

Behavior and Safety Notes

  • 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.

Current Limitations

  • Very large recursive scans can be time-consuming on slow disks.
  • CI release matrix currently builds Linux x86_64 artifacts only (ARM64 definitions exist in distribute_options.yaml but are not included in the workflow matrix).
  • Async macOS finalization depends on Apple webhook delivery and Cloudflare Worker dispatch reliability.

Desktop updater source

  • 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 v prefix (for example v1.2.3).
  • Installer selection is architecture-aware:
    • macOS: DMG
    • Windows: EXE preferred (MSIX fallback)
    • Linux: DEB preferred (RPM fallback)
  • Architecture matching rules:
    • x86_64 aliases: x86_64, x64, amd64
    • arm64 aliases: arm64, aarch64
  • Current release workflow publishes Linux x86_64 artifacts only; Linux arm64 hosts are currently treated as unsupported by the updater.

Configuration Notes

  • 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

Useful Flutter Commands

flutter doctor
flutter analyze
flutter test

Patrol E2E Tests (macOS)

This project includes a Patrol end-to-end smoke test at patrol_test/app_test.dart.

  1. Install Patrol CLI:
dart pub global activate patrol_cli
  1. Ensure Dart global executables are on your shell PATH (zsh example):
export PATH="$PATH:$HOME/.pub-cache/bin"
  1. Verify environment readiness:
patrol doctor
  1. Run Patrol E2E on macOS:
patrol test -d macos --target patrol_test/app_test.dart

About

Pristine Cleaner is a desktop file cleaning utility built with Flutter.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Contributors

Languages