tw93/mole

1. Overall shape

Mole is a macOS-focused maintenance toolkit delivered as a single CLI entrypoint, mo, with a mixed implementation split between Go and shell scripts. The repository is organized around user-facing commands such as clean, uninstall, optimize, analyze, status, purge, installer, update, and remove.

2. Primary execution boundary

The top-level bin/*.sh scripts are the main user entrypoints and wrappers. They expose the CLI commands, handle shell integration, and delegate into the shared shell libraries under lib/, or into the Go-built subcommands where appropriate. This makes the repo feel like one product, but with multiple implementation layers behind it.

3. Go-based subsystems

cmd/analyze and cmd/status are the main Go subsystems. They appear to own the more interactive and structured features:

- analyze handles disk exploration, JSON output, live scanning, view formatting, deletion/update flows, and caching.

- status gathers machine health and runtime metrics, diagnoses conditions, and renders the live dashboard.

These commands are likely the most data-rich parts of the application and also the ones that support machine-readable output.

4. Shell-based maintenance engine

Most destructive or system-touching maintenance work lives in shell libraries under lib/. These are grouped by domain:

- lib/clean for cache and artifact cleanup

- lib/uninstall for app removal

- lib/optimize for system refresh and maintenance tasks

- lib/manage for whitelist and purge-path management

- lib/ui for interactive menu components

- lib/core for shared plumbing

This is the core operational backend for cleanup, uninstall, optimize, purge, and related actions.

5. Common infrastructure layer

lib/core is the shared foundation used by the shell subsystems. It centralizes things like command wiring, common helpers, logging, file operations, timeouts, sudo handling, help text, and bundle/app resolution. Architecturally, this is the low-level boundary that keeps each maintenance command from reimplementing the same safety and runtime logic.

6. Safety and destructive-operation controls

Safety is a first-class boundary across the repo. The README and tree show dedicated safety docs, review agents, and tests for dangerous paths. In practice, the destructive commands rely on:

- path validation and protected-directory rules

- dry-run behavior

- whitelists / protected lists

- logging of file operations

- confirmation gates for high-risk actions

This means the architecture is intentionally conservative: commands prefer refusing or skipping over broad deletion.

7. Data flow for cleanup and uninstall

For clean and uninstall, the flow is roughly: user selection or scan discovery → classification of targets → safety filtering → deletion or trash/removal actions → summary of freed space. The repo also distinguishes between removing apps that are still installed versus cleaning leftovers for already-removed apps. That split is reflected in separate cleanup and uninstall domains.

8. Data flow for analysis

analyze operates as a disk traversal and inspection pipeline. It scans a target path, aggregates directory and file sizes, identifies large files, formats the results for interactive browsing, and can emit JSON for scripting. The README indicates a key behavioral boundary: deletion from analyze goes through Trash/Finder rather than direct removal, making it safer for ad hoc cleanup.

9. Data flow for live status

status is a read-only telemetry pipeline. It collects system state across CPU, memory, disk, network, battery/power, hardware, and process metrics, then computes a health score and renders a live dashboard. It also supports JSON output and auto-switches to JSON when piped, which makes it suitable for automation without changing the command path.

10. Interactive UI layer

The repo has a dedicated terminal UI layer in lib/ui and corresponding view logic in the Go commands. This supports menu navigation, paginated selection, and keyboard-driven interaction for actions like choosing apps, selecting files, or reviewing cleanup candidates. The UI is not just presentation; it directly gates destructive operations by forcing user review.

11. Support tooling and install/update path

The scripts/ and install.sh files support installation, release automation, quick-launcher setup, and repository maintenance tasks. This sits outside the core command runtime but is important architecturally because it defines how the CLI is distributed, updated, and integrated into shell environments.

12. Testing and validation boundaries

The repo uses a strong split between:

- Go tests under cmd/analyze, cmd/status, and internal/

- BATS integration tests under tests/ for shell commands and system behavior

- CI workflows under .github/workflows/

This testing structure mirrors the implementation split: Go logic is unit-tested, while system-affecting shell behavior is validated with higher-level integration tests.

13. Security and operational governance

Security-related files and workflows are prominent: SECURITY.md, SECURITY_AUDIT.md, gitleaks, CodeQL, and dedicated safety review agents. That indicates the project treats local-destructive operations, path handling, and shell execution as architectural risk areas, not just implementation details.

14. How to diagram it

The clean architecture view is: **user/terminal → mo entry scripts → command-specific engine (cmd/* or lib/*) → filesystem/system APIs → output/logging/trash. Around that core, add side boundaries for interactive UI, safety validation, metrics collection, installation/release tooling, and testing/CI**.