mirror of
https://github.com/tw93/Mole.git
synced 2026-02-04 19:09:43 +00:00
115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# Mole AI Agent Guide
|
|
|
|
Quick reference for AI assistants working on Mole (Mac system cleaner).
|
|
**Last updated**: 2026-01-04
|
|
|
|
## 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
|
|
|
|
- Raw deletions without `safe_*` helpers
|
|
- Remove `--prefix`/`--config` flags from install.sh
|
|
- Commit code unless explicitly requested
|
|
- Mix languages: Python in shell, shell in Go
|
|
- Delete without checking protection lists
|
|
|
|
## Architecture Quick Map
|
|
|
|
```
|
|
mole # CLI entrypoint (menu + routing)
|
|
├── bin/ # Commands: clean, uninstall, optimize, analyze, status
|
|
├── lib/ # Shell logic: core/, clean/, ui/
|
|
├── cmd/ # Go apps: analyze/, status/
|
|
├── tests/ # BATS integration tests
|
|
└── scripts/ # Build and test automation
|
|
```
|
|
|
|
**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`
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Validation (run before suggesting changes)
|
|
bash -n <file> # Syntax check
|
|
./scripts/test.sh # Full test suite
|
|
MO_DRY_RUN=1 ./mole clean # Safe dry-run test
|
|
|
|
# Development
|
|
make build # Build Go binaries
|
|
go run ./cmd/analyze # Test without building
|
|
bats tests/clean.bats -f "name" # Specific test
|
|
|
|
# Debugging
|
|
MO_DEBUG=1 ./mole clean # Verbose output
|
|
```
|
|
|
|
## Code Style Rules
|
|
|
|
**Shell** (Bash 3.2 compatible):
|
|
|
|
- 2-space indent, quote variables: `"$var"`
|
|
- Use `[[` not `[`, prefer `$(cmd)` over backticks
|
|
- Comments: English, intent-focused, for safety boundaries only
|
|
- Entry scripts: 2-3 line header describing purpose
|
|
|
|
**Go**:
|
|
|
|
- Standard conventions: `gofmt`, `go vet`
|
|
- Never ignore errors
|
|
|
|
## Key Helpers
|
|
|
|
- `safe_rm <path>` - Protected deletion
|
|
- `safe_find_delete <base> <pattern> <days> <type>` - Safe find+delete
|
|
- `is_protected <path>` - Check system protection
|
|
- `is_whitelisted <name>` - Check user whitelist
|
|
- `log_info/success/warn/error <msg>` - Logging
|
|
|
|
## Workflow
|
|
|
|
1. **Read first**: Never propose changes to unread code
|
|
2. **Shell work**: Logic in `lib/`, called from `bin/`
|
|
3. **Go work**: Edit `cmd/<app>/*.go`
|
|
4. **Test**: Dry-run → BATS → full test suite
|
|
5. **Style**: Match existing file conventions (Bash 3.2)
|
|
|
|
## Example: Add New Cleanup
|
|
|
|
```bash
|
|
# 1. Create lib/clean/my_module.sh
|
|
clean_my_cache() {
|
|
local dir="$HOME/Library/Caches/MyApp"
|
|
[[ -d "$dir" ]] && ! is_whitelisted "my_app" || return
|
|
safe_find_delete "$dir" "*" "30" "f"
|
|
log_success "Cleaned MyApp cache"
|
|
}
|
|
|
|
# 2. Call from bin/clean.sh
|
|
source "${LIB_DIR}/clean/my_module.sh"
|
|
clean_my_cache
|
|
|
|
# 3. Test
|
|
bats tests/clean.bats -f "my_cache"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
- Tests fail → `bats tests/<file>.bats -f "test name"`
|
|
- Syntax error → `bash -n <file>`
|
|
- Permission denied → `./mole touchid`
|
|
- Cleanup not working → Check `is_protected()` or `~/.config/mole/whitelist`
|