Mole/AGENTS.md

AGENTS.md - Development Guide for Mole

This guide provides AI coding assistants with essential commands, patterns, and conventions for working in the Mole codebase.

Quick reference: Build/test commands • Safety rules • Architecture map • Code style

---

Safety Checklist

Before any operation:

• Use safe_* helpers (never raw rm -rf or find -delete)
• Check protection: is_protected(), is_whitelisted()
• Test first: MO_DRY_RUN=1 ./mole clean
• Validate syntax: bash -n <file>
• Run tests: ./scripts/test.sh

NEVER Do These

• Run rm -rf or any raw deletion commands
• Delete files without checking protection lists
• Modify system-critical paths (e.g., /System, /Library/Apple)
• Remove installer flags --prefix/--config from install.sh
• Commit code changes or run git commit unless the user explicitly asks you to commit
• Reply to GitHub issues or PRs on behalf of the user - only prepare responses for user review
• Run destructive operations without dry-run validation
• Use raw git commands when gh CLI is available

ALWAYS Do These

• Use safe_* helper functions for deletions (safe_rm, safe_find_delete)
• Respect whitelist files (e.g., ~/.config/mole/whitelist)
• Check protection logic before cleanup operations
• Test with dry-run modes first
• Validate syntax before suggesting changes: bash -n <file>
• Prioritize gh CLI for ALL GitHub operations - Always use gh to fetch and manipulate GitHub data (issues, PRs, releases, comments, etc.) instead of raw git commands or web scraping
• Document fixes in AGENTS.md instead of committing or replying - Prepare commit messages and GitHub responses for user review, don't execute them
• Review and update SECURITY_AUDIT.md when modifying clean or optimize logic

---

Quick Reference

Build Commands

# Build Go binaries for current platform
make build

# Build release binaries (cross-platform)
make release-amd64  # macOS Intel
make release-arm64   # macOS Apple Silicon

# Clean build artifacts
make clean

Test Commands

# Run full test suite (recommended before commits)
./scripts/test.sh

# Run specific BATS test file
bats tests/clean.bats

# Run specific test case by name
bats tests/clean.bats -f "should respect whitelist"

# Run Go tests only
go test -v ./cmd/...

# Run Go tests for specific package
go test -v ./cmd/analyze

# Shell syntax check
bash -n lib/clean/user.sh
bash -n mole

# Lint shell scripts
shellcheck --rcfile .shellcheckrc lib/**/*.sh bin/**/*.sh

Development Commands

# Test cleanup in dry-run mode
MO_DRY_RUN=1 ./mole clean

# Enable debug logging
MO_DEBUG=1 ./mole clean

# Test Go tool directly
go run ./cmd/analyze

# Test installation locally
./install.sh --prefix /usr/local/bin --config ~/.config/mole

---

Architecture Quick Map

mole/                      # Main CLI entrypoint (menu + routing)
├── mo                     # CLI alias wrapper
├── install.sh             # Manual installer/updater (preserves --prefix/--config)
├── bin/                   # Command entry points (thin wrappers)
│   ├── clean.sh           # Deep cleanup orchestrator
│   ├── uninstall.sh       # App removal with leftover detection
│   ├── optimize.sh        # Cache rebuild + service refresh
│   ├── purge.sh           # Aggressive cleanup mode
│   ├── touchid.sh         # Touch ID sudo enabler
│   ├── analyze.sh         # Disk usage explorer wrapper
│   ├── status.sh          # System health dashboard wrapper
│   ├── installer.sh       # Core installation logic
│   └── completion.sh      # Shell completion support
├── lib/                   # Reusable shell logic
│   ├── core/              # base.sh, log.sh, sudo.sh, ui.sh
│   ├── clean/             # Cleanup modules (user, apps, brew, system...)
│   ├── optimize/          # Optimization modules
│   ├── check/             # Health check modules
│   ├── manage/            # Management utilities
│   ├── ui/                # UI components (balloons, spinners)
│   └── uninstall/         # Uninstallation logic
├── cmd/                   # Go applications
│   ├── analyze/           # Disk analysis tool
│   └── status/            # Real-time monitoring
├── scripts/               # Build and test automation
│   └── test.sh            # Main test runner (shell + go + BATS)
└── tests/                 # BATS integration tests

Decision Tree:

• User cleanup logic → lib/clean/<module>.sh
• Command entry → bin/<command>.sh
• Core utils → lib/core/<util>.sh
• Performance tool → cmd/<tool>/*.go
• Tests → tests/<test>.bats

Language Stack

• Shell (Bash 3.2): Core cleanup and system operations (lib/, bin/)
• Go: Performance-critical tools (cmd/analyze/, cmd/status/)
• BATS: Integration testing (tests/)

---

Code Style Guidelines

Shell Scripts

• Indentation: 4 spaces (configured in .editorconfig)
• Variables: lowercase_with_underscores
• Functions: verb_noun format (e.g., clean_caches, get_size)
• Constants: UPPERCASE_WITH_UNDERSCORES
• Quoting: Always quote variables: "$var" not $var
• Tests: Use [[ instead of [
• Command substitution: Use $(command) not backticks
• Error handling: Use set -euo pipefail at top of files

Go Code

• Formatting: Follow standard Go conventions (gofmt, go vet)
• Package docs: Add package-level documentation for exported functions
• Error handling: Never ignore errors, always handle them explicitly
• Build tags: Use //go:build darwin for macOS-specific code

Comments

• Language: English only
• Focus: Explain "why" not "what" (code should be self-documenting)
• Safety: Document safety boundaries explicitly
• Non-obvious logic: Explain workarounds or complex patterns

---

Key Helper Functions

Safety Helpers (lib/core/base.sh)

• safe_rm <path>: Safe deletion with validation
• safe_find_delete <base> <pattern> <days> <type>: Protected find+delete
• is_protected <path>: Check if path is system-protected
• is_whitelisted <name>: Check user whitelist

Logging (lib/core/log.sh)

• log_info <msg>: Informational messages
• log_success <msg>: Success notifications
• log_warn <msg>: Warnings
• log_error <msg>: Error messages
• debug <msg>: Debug output (requires MO_DEBUG=1)

UI Helpers (lib/core/ui.sh)

• confirm <prompt>: Yes/no confirmation
• show_progress <current> <total> <msg>: Progress display

---

Testing Strategy

Test Types

1. Syntax Validation: bash -n <file> - catches basic errors
2. Unit Tests: BATS tests for individual functions
3. Integration Tests: Full command execution with BATS
4. Dry-run Tests: MO_DRY_RUN=1 to validate without deletion
5. Go Tests: go test -v ./cmd/...

Test Environment Variables

• MO_DRY_RUN=1: Preview changes without execution
• MO_DEBUG=1: Enable detailed debug logging
• BATS_FORMATTER=pretty: Use pretty output for BATS (default)
• BATS_FORMATTER=tap: Use TAP output for CI

---

Common Development Tasks

Adding New Cleanup Module

1. Create lib/clean/new_module.sh
2. Implement cleanup logic using safe_* helpers
3. Source it in bin/clean.sh
4. Add protection checks for critical paths
5. Write BATS test in tests/clean.bats
6. Test with MO_DRY_RUN=1 first

Modifying Go Tools

1. Navigate to cmd/<tool>/
2. Make changes to Go files
3. Test with go run . or make build && ./bin/<tool>-go
4. Run go test -v for unit tests
5. Check integration: ./mole <command>

Debugging Issues

1. Enable debug mode: MO_DEBUG=1 ./mole clean
2. Check logs for error messages
3. Verify sudo permissions: sudo -n true or ./mole touchid
4. Test individual functions in isolation
5. Use shellcheck for shell script issues

---

Linting and Quality

Shell Script Linting

• Tool: shellcheck with custom .shellcheckrc
• Disabled rules: SC2155, SC2034, SC2059, SC1091, SC2038
• Command: shellcheck --rcfile .shellcheckrc lib/**/*.sh bin/**/*.sh

Go Code Quality

• Tools: go vet, go fmt, go test
• Command: go vet ./cmd/... && go test ./cmd/...

CI/CD Pipeline

• Triggers: Push/PR to main, dev branches
• Platforms: macOS 14, macOS 15
• Tools: bats-core, shellcheck, Go 1.24.6
• Security checks: Unsafe rm usage, app protection, secret scanning

---

File Organization Patterns

Shell Modules

• Entry scripts in bin/ should be thin wrappers
• Reusable logic goes in lib/
• Core utilities in lib/core/
• Feature-specific modules in lib/clean/, lib/ui/, etc.

Go Packages

• Each tool in its own cmd/<tool>/ directory
• Main entry point in main.go
• Use standard Go project layout
• macOS-specific code guarded with build tags

---

GitHub Operations

⚡ ALWAYS Use gh CLI for GitHub Information

Golden Rule: Whenever you need to fetch or manipulate GitHub data (issues, PRs, commits, releases, comments, etc.), ALWAYS use gh CLI first. It's more reliable, authenticated, and provides structured output compared to web scraping or raw git commands.

Preferred Commands:

# Issues
gh issue view 123              # View issue details
gh issue list                  # List issues
gh issue comment 123 "message"  # Comment on issue

# Pull Requests
gh pr view                     # View current PR
gh pr diff                     # Show diff
gh pr list                     # List PRs
gh pr checkout 123             # Checkout PR branch
gh pr merge                    # Merge current PR

# Repository operations
gh release create v1.0.0        # Create release
gh repo view                   # Repository info
gh api repos/owner/repo/issues # Raw API access

NEVER use raw git commands for GitHub operations when gh is available:

• ❌ git log --oneline origin/main..HEAD → ✅ gh pr view
• ❌ git remote get-url origin → ✅ gh repo view
• ❌ Manual GitHub API curl commands → ✅ gh api

Error Handling Patterns

Shell Scripts

• Use set -euo pipefail for strict error handling
• Check command exit codes: if command; then ...
• Provide meaningful error messages with log_error
• Use cleanup traps for temporary resources

Go Code

• Never ignore errors: if err != nil { return err }
• Use structured error messages
• Handle context cancellation appropriately
• Log errors with context information

---

Performance Considerations

Shell Optimization

• Use built-in shell operations over external commands
• Prefer find -delete over -exec rm
• Minimize subprocess creation
• Use appropriate timeout mechanisms

Go Optimization

• Use concurrency for I/O-bound operations
• Implement proper caching for expensive operations
• Profile memory usage in scanning operations
• Use efficient data structures for large datasets

---

Security Best Practices

Path Validation

• Always validate user-provided paths
• Check against protection lists before operations
• Use absolute paths to prevent directory traversal
• Implement proper sandboxing for destructive operations

Permission Management

• Request sudo only when necessary
• Use sudo -n true to check sudo availability
• Implement proper Touch ID integration
• Respect user whitelist configurations

---

Common Pitfalls to Avoid

1. Over-engineering: Keep solutions simple. Don't add abstractions for one-time operations.
2. Premature optimization: Focus on correctness first, performance second.
3. Assuming paths exist: Always check before operating on files/directories.
4. Ignoring protection logic: User data loss is unacceptable.
5. Breaking updates: Keep --prefix/--config flags in install.sh.
6. Platform assumptions: Code must work on all supported macOS versions (10.13+).
7. Silent failures: Always log errors and provide actionable messages.

---

Communication Style

• Be concise and technical
• Explain safety implications upfront
• Show before/after for significant changes
• Provide file:line references for code locations
• Suggest testing steps for validation

---

Resources

• Main script: mole (menu + routing logic)
• Protection lists: Check is_protected() implementations
• User config: ~/.config/mole/
• Test directory: tests/
• Build scripts: scripts/
• Documentation: README.md, CONTRIBUTING.md, SECURITY_AUDIT.md

---

Remember: When in doubt, err on the side of safety. It's better to clean less than to risk user data.