Joshua Jenks
Menu

Work / macadmin

A Mac is low on disk space. What is the tool allowed to delete?

macadmin is a zsh-based macOS administration toolkit built around visible scope, dry-run behavior, deliberate authorization, and tests that do not use a real machine as the destructive fixture.

Inspect source ↗

A concrete workflow

Find development debris before deciding what to remove.

The recent dev-cleanup work scans package caches, Xcode DerivedData, unavailable simulators, old node_modules, and other recreatable development state. Scan is the default; deletion is a separate decision.

  1. 01Scan

    Report candidates without changing state.

  2. 02Constrain

    Search known project roots or an explicit override and stay inside the user-home boundary.

  3. 03Exclude

    Honor ~/.macadminignore and path safety checks.

  4. 04Authorize

    Require an explicit destructive path before cleanup actually removes anything.

  5. 05Test

    Exercise behavior with hermetic fixtures and mocked system commands instead of a developer’s live files.

The safety contract

The flags only matter if the implementation agrees with them.

--dry-run
Where supported, show intended work without mutation.
--yes
Make destructive authorization explicit.
--protect
Block covered destructive paths even when --yes is also present.

KNOWN GAP The protect-enforcement suite proves unconditional --protect + --yes refusal for archive deletion/recompression, duplicate deletion, and file rename/sort/organization. Cleanup, Wi-Fi, OS update, and Homebrew ensure have weaker semantics today. I keep that inconsistency visible because the safety abstraction itself deserves testing.

A useful failure

It worked in my checkout and failed in a fresh clone.

That is exactly the kind of test I want an operations tool to fail before somebody depends on it.

  1. 01Fresh clone

    The committed launcher was not executable, producing permission denied.

  2. 02Installed symlink

    The launcher resolved the symlink path instead of the real script path, so it looked for shared libraries under ~/bin.

  3. 03Installer assumptions

    BSD chmod and read-only copied files exposed additional portability problems.

  4. 04Repair

    The fix committed the executable bit, resolved the real path, copied cleanly, and made the installed entry point executable.

This is a small bug story, but it is representative: the important check was not “does the script work on my machine?” It was “does the path a new user actually takes work from a clean state?”

How I keep it testable

Shared policy, focused commands, mockable boundaries.

bin/macadmin owns dispatch and global flags. Focused scripts/*.zsh commands do one job. Shared libraries handle arguments, exit codes, logging, safety, paths, configuration, macOS behavior, and I/O.

System commands are pushed behind a mockable system boundary so the test suite can exercise destructive decision paths without destructively “testing” the host.

dispatcher→shared policy→focused command→mockable system boundary

The actual surface

The commands stay ordinary on purpose.

These are current command forms from the toolkit.

macadmin system-info --json
macadmin dev-cleanup scan
macadmin cleanup --user --dry-run
macadmin disk largest --path ~ --limit 10 --json
macadmin files sort --path ~/Downloads --dry-run

Why this project fits me

A one-line fix can still have expensive consequences.

Support and operations work taught me that technical difficulty and operational risk are not the same thing. A command can be easy to write and still be the wrong thing to run against the wrong scope.

macadmin is a personal/admin toolkit, not a fleet-management product. The parts I find most interesting are the ones that make those consequences visible before the command runs.