mole

Repository: git clone https://github.com/moses-y/mole Primary language: Go (CLI) + Shell scripts Size: 124 files, 36 test files, CI via GitHub Actions

The Problem

Mac users accumulate caches, stale installers, and orphaned app files that silently consume tens of gigabytes. Manual removal is error‑prone and scattered across many locations (~/Library/Caches, /usr/local/Cellar, etc.). A repeatable, scriptable way to locate and purge these artifacts is missing from the default OS toolset.

What This Does

mole provides a single binary (mo) that bundles the functionality of several mac‑maintenance utilities. The CLI offers commands such as clean, uninstall, optimize, status, and analyze. Core behaviours are split between Go code (command parsing, decision making) and a library of vetted shell scripts that perform the actual file system operations.

Key files:

Area	Responsibility	Representative file
CLI entry	`cmd/analyze/main.go` (invoked as `mo analyze`)	`cmd/analyze/main.go`
Disk scan	`scanner.go` builds a list of candidates	`cmd/analyze/scanner.go`
Cleanable model	`cleanable.go` ranks items, assigns risk levels	`cmd/analyze/cleanable.go`
Deletion	`delete.go` calls removal scripts and logs	`cmd/analyze/delete.go`
UI/Output	`view.go` renders tables, progress bars	`cmd/analyze/view.go`
System metrics	`cmd/status/*.go` gathers CPU, GPU, memory, etc.	`cmd/status/metrics_cpu.go`
Shell actions	`lib/clean/.sh`, `lib/optimize/.sh`, `lib/uninstall/*.sh`	`lib/clean/system.sh`
Helper scripts	`bin/*.sh` are thin wrappers that forward to the Go binary	`bin/clean.sh`

The Go layer validates user flags (--dry-run, --whitelist, --debug), loads a JSON cache (cache.go), and then invokes the appropriate shell script via exec.Command. The scripts contain the low‑level rm -rf, brew uninstall, or pkgutil --forget commands that actually free space.

How It Is Wired

mo (binary) ──► cmd/<command>/main.go
   │
   ├─ flag parsing (cobra) → calls command handler
   │
   ├─ analyze flow:
   │   main.go → loadCache() (cache.go)
   │   → scanFS() (scanner.go) → list of paths
   │   → rankCleanable() (cleanable.go) → risk levels
   │   → if --dry-run: view.printPlan() (view.go)
   │   → else: delete.run(paths) (delete.go)
   │          └─ exec lib/clean/*.sh per category
   │
   └─ status flow:
       main.go → metrics.*.go (collect system stats) → view.render()

The cmd/status package follows the same pattern: each metrics_*.go file calls a small shell helper in lib/check/ or reads system files (/proc, sysctl). Results are assembled into a unified dashboard printed by cmd/status/view.go.

All test suites target these layers:

Go unit tests (*_test.go) under cmd/analyze/ and cmd/status/ verify flag handling, cache logic, and metric calculations.
BATS tests (tests/*.bats) exercise the shell scripts end‑to‑end, confirming that bin/clean.sh removes expected files without error.

GitHub Actions run go test ./... and bats tests/ on every push, and golangci-lint + shellcheck enforce linting.

How To Use It

# Build from source (requires Go >=1.20)
git clone https://github.com/moses-y/mole
cd mole
make build          # produces ./mo

# Quick install (provided by repo)
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash

# Run interactive menu
./mo                 # or just `mo` after PATH update

# Dry‑run a deep clean, see what would be removed
mo clean --dry-run

# Apply the plan, preserving whitelisted paths
mo clean --whitelist

# View live system health
mo status

Configuration is file‑based: whitelist entries are stored in ~/.mole/whitelist.json (created on first run). No environment variables are required.

Real‑World Use

A CI workstation that builds iOS apps accumulates derived data (~/Library/Developer/Xcode/DerivedData) and old simulators. Adding mo clean --dry-run to the nightly shutdown script lets the team preview disk reclamation, then mo clean safely removes 15 GB of stale artifacts without touching active projects.

Code Health & Issues

Low – Missing version bump – README.md badge points to tw93/mole releases, not the fork; version tag may be out of sync.
Low – Duplicate CI steps – Both test.yml and check.yml run golangci-lint; could be consolidated.
Low – No explicit OS check – Go code assumes macOS but does not abort on other platforms; could cause runtime errors on Linux/macOS CI runners.

Static analysis found no dead code, no license violations, and test coverage is adequate (36 BATS + Go tests). All expected CI files (.github/workflows/*.yml) and lint configs (.golangci.yml, .shellcheckrc) are present.

The Bottom Line

mole delivers a practical, well‑tested CLI for macOS cleanup, coupling Go’s argument handling with battle‑tested shell scripts. It’s suitable for power users or teams that need repeatable, auditable disk hygiene. The main gaps are minor CI redundancy and a lack of explicit platform guards; otherwise the codebase is clean and ready for extension.