5.7 KiB
Squid desktop
Squid has two native desktop builds, macOS and Windows, built with the same
technology stack as nex_shift:
- Tauri 2 shell and updater handoff
- React 19 + TypeScript UI
- Vite 6 development and asset pipeline
- The existing
squid-core,squid-engine,squid-platformandsquid-statsRust workspace
The desktop application is a second frontend over the same engine used by the CLI and TUI. It does not maintain a separate cleanup implementation.
The shared Nex colour and component standard lives in
DESIGN.md. Squid uses the same primary palette as nex_shift.
Run locally
Prerequisites:
- Node.js 20+ and pnpm
- Rust toolchain and Cargo
- macOS: Xcode Command Line Tools
- Windows: MSVC build tools and WebView2
pnpm install
pnpm desktop:dev
The Vite-only development page cannot call Tauri commands. Use desktop:dev
when exercising scans, deletes, storage analysis, system data, or updates.
Useful checks:
pnpm check
pnpm build
cargo test --manifest-path src-tauri/Cargo.toml --lib
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
Screens
| Screen | What it does |
|---|---|
| Computer overview | Smart scan entry, disk health, cleanup result categories and live CPU/memory/storage summaries |
| Daily cleanup | Runs the normal cleanup rule set, groups results by category, supports per-item and per-category selection, Trash or permanent deletion, then offers undo through History |
| Uninstall apps | Reads installed apps, builds an app-specific removal plan, shows leftover paths and warnings, then uninstalls selected items |
| Deep Clean | Searches chosen project roots for regenerable build artefacts with Git and file-age protections |
| Storage | Measures a chosen folder, exposes the largest children, drills down, and finds the largest files |
| Real-time monitor | Live CPU, memory, network, disk, battery, volume and process data; process termination asks for confirmation |
| History | Lists cleanup sessions, shows the ledger, restores files that are still in Trash/Recycle Bin, and opens the bin |
| Settings | Language, deletion mode, history retention, protected paths, local file locations, and software updates |
⌘1–⌘8 on macOS and Ctrl+1–Ctrl+8 on Windows switch screens.
Tray
Squid keeps running after its main window is closed. The tray menu can reopen the window and jump directly to Daily cleanup, Uninstall apps or Deep Clean. Use Quit Squid in the same menu to stop the background process.
Safety boundary
The UI never submits a path for deletion. A scan returns an array of items and a process-local scan ID. Delete commands accept only indices into that cached scan or removal plan. The Rust command layer then:
- Rejects out-of-range indices.
- Forces locked items to remain unselected.
- Reconstructs the same
CleanupItemset the scanner produced. - Calls
squid-engine::delete, which re-validates ownership, safety anchors, protected locations and the user whitelist before removing anything.
Locked items remain visible but cannot be selected. A permanent delete always
requires the confirm sheet; the default mode comes from the same Settings
file used by the CLI and TUI.
Storage permissions on macOS
Squid measures file metadata only. The normal cleanup scan does not cover
~/Downloads, and disk capacity is read with statvfs rather than through
CoreFoundation's CacheDelete-aware volume API, so neither path asks for access
to downloads or the media library.
Full Disk Access is optional. On first launch Squid shows one setup card that
reports whether the app can read TCC-protected locations such as Safari, Mail and
Messages data. It does not force a permission prompt and does not block the app:
without access those locations are skipped. The same status and a link to
System Settings › Privacy & Security › Full Disk Access remain in
Settings › System permissions. The check runs again when the window regains
focus, and the card can be reopened by setting desktop_setup_reviewed = false
in config.toml.
Folder-dependent tools remain explicit. Storage analysis starts only after you choose a folder. macOS may still show a folder permission prompt when a folder you selected contains protected locations. Deny any access you do not want Squid to have; the rest of the application still works. Deep Clean's default project roots can include Desktop and Documents, so edit that list before scanning if you do not want those prompts.
Updates
The update implementation mirrors nex_shift:
- A build derives its feed from the git
originremote orSQUID_UPDATE_URL. - The feed is an orphan
releasesbranch containing installers andsquid-update.json. - The manifest always provides exact byte size and SHA256; both are checked before an installer can run.
- A build made with
SQUID_UPDATE_PUBKEYadditionally requires and verifiessquid-update.sig, a detached Ed25519 signature over the manifest's exact bytes. - The application checks at most once a day when automatic checks are enabled;
the last-check day lives in
updates.json. - macOS mounts the DMG after exit and swaps
Squid.appwith rollback on failure. - Windows waits for
squid-desktop.exeto exit, runs the same NSIS installer silently, then relaunches it from%LOCALAPPDATA%\Programs\Squid.
See RELEASE.md for the publishing commands, artifact names, and
signing setup.
Native CLI remains separate
The desktop binary is squid-desktop. The existing squid binary continues to
contain the CLI/TUI and is not replaced by the desktop package. Both use the same
configuration and history directories, so a cleanup made in either entry point
appears in the other one's history.