From 167bc7ac8d74fa49316e557ca38fee2172451bd5 Mon Sep 17 00:00:00 2001 From: tw93 Date: Sat, 28 Feb 2026 11:51:16 +0800 Subject: [PATCH] docs: Add local file path guideline to `AGENTS.md` and `CLAUDE.md`, and update `.gitignore` to ignore these and `mole_guidelines.md`. --- .gitignore | 3 + AGENTS.md | 380 -------------------------------- CLAUDE.md | 619 ----------------------------------------------------- 3 files changed, 3 insertions(+), 999 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 8efd5c9..d245179 100644 --- a/.gitignore +++ b/.gitignore @@ -76,3 +76,6 @@ coverage.html session.json run_tests.ps1 +AGENTS.md +mole_guidelines.md +CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index d3e866d..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,380 +0,0 @@ -# AGENTS.md - Mole Project Knowledge Base - -## Project Identity - -**Mole** is a hybrid macOS cleanup tool combining: - -- **Bash 3.2** for system operations and orchestration (`lib/`, `bin/`) -- **Go 1.24+** for high-performance TUI components (`cmd/analyze`, `cmd/status`) -- **Safety-first philosophy**: User data loss is unacceptable - -**Mission**: Deep clean and optimize macOS while maintaining strict safety boundaries. - ---- - -## Architecture Overview - -```text -mole/ # Main CLI entrypoint (menu + routing) -├── mo # Lightweight wrapper, exec's mole -├── install.sh # Standalone installer/updater -├── 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 # Project artifact cleanup -│ ├── 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 (see lib/AGENTS.md) -│ ├── 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 (see cmd/AGENTS.md) -│ ├── analyze/ # Disk analysis tool (Bubble Tea TUI) -│ └── status/ # Real-time monitoring (Bubble Tea TUI) -├── scripts/ # Build and test automation -│ ├── build.sh # Cross-platform Go builds -│ ├── test.sh # Main test runner (shell + go + BATS) -│ └── check.sh # Format + lint + optimization score -└── tests/ # BATS integration tests (see tests/AGENTS.md) -``` - -### Entry Point Flow - -1. **User invokes**: `mo clean` or `./mole clean` -2. **`mole` script**: Routes to `bin/clean.sh` via `exec` -3. **`bin/clean.sh`**: Sources `lib/clean/*.sh` modules -4. **Cleanup modules**: Call `safe_*` helpers from `lib/core/base.sh` -5. **Logging/UI**: Handled by `lib/core/log.sh` + `lib/core/ui.sh` - ---- - -## Safety Philosophy (CRITICAL) - -### NEVER Do These - -- Run `rm -rf` or any raw deletion commands -- Delete files without checking protection lists (`is_protected()`, `is_whitelisted()`) -- Modify system-critical paths (`/System`, `/Library/Apple`, `/usr/bin`) -- Remove `--prefix`/`--config` flags from `install.sh` -- Commit or push to remote without explicit user request -- Add `Co-Authored-By` (AI attribution) in commit messages -- Change the 1s ESC key timeout in `lib/core/ui.sh` -- Touch `com.apple.*` LaunchAgents/Daemons -- Clean during active Time Machine backups - -### ALWAYS Do These - -- Use `safe_*` helpers (`safe_rm`, `safe_find_delete` from `lib/core/base.sh`) -- Validate paths before operations (`validate_path`, `is_protected`) -- Test with `MO_DRY_RUN=1` before destructive operations -- Run `./scripts/check.sh` before committing shell changes -- Use `gh` CLI for ALL GitHub operations (issues, PRs, releases) -- Respect whitelist files (`~/.config/mole/whitelist`) -- Review and update `SECURITY_AUDIT.md` when modifying cleanup logic - -### Protection Mechanisms - -| Function | Location | Purpose | -|----------|----------|---------| -| `is_protected()` | `lib/core/base.sh` | System path protection | -| `is_whitelisted()` | `lib/core/base.sh` | User whitelist check | -| `safe_rm()` | `lib/core/base.sh` | Validated deletion | -| `safe_find_delete()` | `lib/core/base.sh` | Protected find+delete | -| `validate_path()` | Various | Path safety checks | - ---- - -## Code Style & Conventions - -### Shell Scripts (Bash 3.2) - -**Formatting**: Run `./scripts/check.sh --format` before committing. - -```bash -# shfmt flags: -i 4 -ci -sr -w -# 4-space indent, case body indent, space after redirect - -# CORRECT -command 2> /dev/null -echo "hello" > file.txt - -case "$var" in - pattern) - action - ;; -esac - -# WRONG -command 2>/dev/null # Missing space after > -``` - -**Naming Conventions**: - -- Variables: `lowercase_with_underscores` -- Functions: `verb_noun` (e.g., `clean_caches`, `get_size`) -- Constants: `UPPERCASE_WITH_UNDERSCORES` - -**Error Handling**: - -```bash -set -euo pipefail # Mandatory at top of files - -# Always quote variables -"$var" not $var - -# Use [[ instead of [ -if [[ -f "$file" ]]; then - ... -fi -``` - -**BSD/macOS Commands**: Use BSD-style flags, not GNU. - -```bash -# CORRECT (BSD) -stat -f%z "$file" - -# WRONG (GNU) -stat --format=%s "$file" -``` - -### Go Code - -**Formatting**: Standard `gofmt` or `goimports -local github.com/tw93/Mole` - -**Build Tags**: Use for macOS-specific code - -```go -//go:build darwin -``` - -**Error Handling**: Never ignore errors - -```go -if err != nil { - return fmt.Errorf("operation failed: %w", err) -} -``` - -### Comments - -- **Language**: English only -- **Focus**: Explain "why" not "what" -- **Safety**: Document protection boundaries explicitly - ---- - -## Build & Test - -### Build Commands - -```bash -make build # Current platform -make release-amd64 # macOS Intel -make release-arm64 # macOS Apple Silicon -make clean # Remove artifacts -``` - -### Test Commands - -```bash -./scripts/test.sh # Full suite (recommended) -bats tests/clean.bats # Specific BATS test -go test -v ./cmd/... # Go tests only -bash -n lib/clean/*.sh # Syntax check -shellcheck lib/**/*.sh # Lint shell scripts -``` - -### CI/CD Pipeline - -**Triggers**: Push/PR to `main`, `dev` branches - -**Key Checks**: - -- **Auto-formatting**: CI commits `shfmt` + `goimports` fixes back to branch -- **Safety audits**: Scans for raw `rm -rf`, validates protection lists -- **Secret scanning**: Blocks hardcoded credentials -- **Optimization score**: `scripts/check.sh` enforces performance standards - -**Environment Requirements**: - -- Go 1.24.6 (pinned) -- macOS 14/15 runners -- bats-core for shell integration tests -- Performance limits via `MOLE_PERF_*` env vars - ---- - -## GitHub Workflow - -### Always Use `gh` CLI - -```bash -# Issues -gh issue view 123 -gh issue list - -# Pull Requests -gh pr view -gh pr diff -gh pr checkout 123 - -# NEVER use raw git for GitHub operations -# ❌ git log --oneline origin/main..HEAD -# ✅ gh pr view -``` - -### Branch Strategy - -- **PRs target `dev`**, not `main` -- Release process: `dev` → `main` → tagged release → Homebrew update -- **Do not create new branches by default**. Stay on the current branch unless the user explicitly requests branch creation. - -### Commit Grouping Strategy - -- When the user asks for commits, **group commits by requirement**, not by command sequence. -- Keep each commit scoped to one logical change (feature/fix/docs/release), and avoid mixing unrelated files. -- If one request contains multiple requirements, submit them as separate commits in dependency order. -- Before committing, review staged files to ensure they belong to the same requirement. - -### Suggesting Latest Version for Testing - -When a bug fix is done but not yet released, you can suggest users to install the latest version, but **must distinguish between install methods**: - -1. **For Script Users (`curl | bash`)**: - Users can directly run `mo update --nightly` to pull the latest unreleased `main` branch. - -2. **For Homebrew Users (`brew`)**: - Homebrew users **cannot** use `mo update --nightly` (it will throw an error). Reinstalling via brew (`brew uninstall mole && brew install mole`) also will NOT fetch the unreleased fix, because Brew follows official tags. - If they want to test immediately, suggest they `brew uninstall mole`, then reinstall using the official curl script. - ---- - -## Logging & Debugging - -### Log Files - -| File | Purpose | Control | -|------|---------|---------| -| `~/.config/mole/mole.log` | General log (INFO/SUCCESS/WARNING/ERROR) | Always | -| `~/.config/mole/mole_debug_session.log` | Debug session log | `MO_DEBUG=1` | -| `~/.config/mole/operations.log` | All file deletions | Disable: `MO_NO_OPLOG=1` | - -### Environment Variables - -- `MO_DRY_RUN=1`: Preview without execution -- `MO_DEBUG=1`: Verbose debug output -- `MO_NO_OPLOG=1`: Disable operation logging - -### Operation Log Format - -```text -[2024-01-26 10:30:15] [clean] REMOVED /Users/xxx/Library/Caches/com.old.app (15.2MB) -[2024-01-26 10:30:15] [clean] SKIPPED /Users/xxx/Library/Caches/com.protected.app (whitelist) -``` - -- **Actions**: `REMOVED` | `SKIPPED` | `FAILED` | `REBUILT` -- **Commands**: `clean` | `uninstall` | `optimize` | `purge` -- Auto-rotates at 5MB - ---- - -## Project-Specific Patterns - -### Installer Self-Containment - -`install.sh` duplicates core UI/logging functions to remain standalone during bootstrap. This is intentional—it cannot depend on `lib/`. - -### Atomic Update Flow - -1. User runs `mo update` -2. Fetches latest `install.sh` from GitHub -3. Installer modifies `SCRIPT_DIR` in installed `mole` to point to `~/.config/mole` -4. Ensures CLI always uses latest synced modules - -### Dual Entry Points - -- **`mole`**: Main executable (menu + routing) -- **`mo`**: Lightweight alias (recommended for users) - -Both are functionally identical (`mo` calls `exec mole`). - ---- - -## Communication Style - -- **Address user as "汤帅" (Tang Shuai)** in all responses -- **Be concise and technical** -- **Explain safety implications upfront** -- **Provide file:line references** for code locations -- **Suggest validation steps** (dry-run, syntax check) -- **Avoid em dashes** in responses - -### Responding to Bug Reports (English) - -When replying to users after fixing a bug: - -```markdown -Thanks for your feedback! This issue has been fixed. - -**Root cause**: [Brief explanation of the bug cause] - -You can install the latest version to test: - -\`\`\`bash -curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s latest -\`\`\` - -I'll publish a new official release soon. -``` - -**Key elements**: - -- Start with "Thanks for your feedback!" -- Explain root cause concisely -- Provide the install command for testing -- Mention a new release is coming soon - ---- - -## Quick Reference - -### Decision Tree - -| Task | Location | Pattern | -|------|----------|---------| -| Add cleanup logic | `lib/clean/.sh` | Use `safe_*` helpers | -| Create command | `bin/.sh` | Thin wrapper, source `lib/` | -| Add core utility | `lib/core/.sh` | Reusable functions | -| Build performance tool | `cmd//` | Go with build tags | -| Write tests | `tests/.bats` | BATS + isolated `$HOME` | - -### Common Pitfalls - -1. **Over-engineering**: Keep it simple -2. **Assuming paths exist**: Always check first -3. **Ignoring protection logic**: Data loss is unacceptable -4. **Breaking installer flags**: Keep `--prefix`/`--config` in `install.sh` -5. **Silent failures**: Log errors with actionable messages - ---- - -## Resources - -- **Root documentation**: `README.md`, `CONTRIBUTING.md`, `SECURITY_AUDIT.md` -- **Code guidelines**: `CLAUDE.md` (AI assistant instructions) -- **Subdirectory guides**: `lib/AGENTS.md`, `cmd/AGENTS.md`, `tests/AGENTS.md` -- **Protection lists**: Check `is_protected()` implementations -- **User config**: `~/.config/mole/` - ---- - -**Remember**: When in doubt, err on the side of safety. It's better to clean less than to risk user data. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9b33cef..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,619 +0,0 @@ -# CLAUDE.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 - -**For deeper context**: See `AGENTS.md` (architecture overview) and subdirectory guides: `lib/AGENTS.md`, `cmd/AGENTS.md`, `tests/AGENTS.md` - ---- - -## 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 ` -- 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** -- **Push to remote repositories with `git push` or create commits automatically** -- **Create new git branches unless the user explicitly asks for a new branch** -- **Add `Co-Authored-By` lines in commit messages** - never include AI attribution in commits -- **Reply to GitHub issues or PRs on behalf of the user** - only prepare responses for user review -- **Comment on GitHub issues or create pull requests without explicit user request** -- Run destructive operations without dry-run validation -- Use raw `git` commands when `gh` CLI is available -- **Change the ESC key timeout in `lib/core/ui.sh`** - The 1s timeout in `read_key()` is intentional, do NOT reduce it - -## 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 ` -- **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 -- **ONLY analyze and provide solutions** - When user asks about GitHub issues, read the content, investigate code, provide diagnostic information and fixes, but NEVER commit or comment without explicit request -- **Wait for explicit permission** - Before any git commit, git push, or GitHub interaction, wait for user to explicitly request it -- **Stay on the current branch by default** - Only create or switch branches when the user explicitly requests it -- **Group commits by requirement** - Use one logical commit per requirement and do not mix unrelated file changes in the same commit -- Review and update `SECURITY_AUDIT.md` when modifying `clean` or `optimize` logic - ---- - -## Quick Reference - -### Build Commands - -```bash -# 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 - -```bash -# 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 - -```bash -# Test cleanup in dry-run mode -MO_DRY_RUN=1 ./mole clean - -# Enable debug logging -MO_DEBUG=1 ./mole clean - -# Disable operation logging -MO_NO_OPLOG=1 ./mole clean - -# Test Go tool directly -go run ./cmd/analyze - -# Test installation locally -./install.sh --prefix /usr/local/bin --config ~/.config/mole -``` - -### Log Files - -| File | Purpose | -|------|---------| -| `~/.config/mole/mole.log` | General log (INFO/SUCCESS/WARNING/ERROR) | -| `~/.config/mole/mole_debug_session.log` | Debug session log (MO_DEBUG=1) | -| `~/.config/mole/operations.log` | Operation log (all file deletions) | - -**Operation Log Format**: - -```text -[2024-01-26 10:30:15] [clean] REMOVED /Users/xxx/Library/Caches/com.old.app (15.2MB) -[2024-01-26 10:30:15] [clean] SKIPPED /Users/xxx/Library/Caches/com.protected.app (whitelist) -[2024-01-26 10:30:20] [uninstall] REMOVED /Applications/OldApp.app (150MB) -``` - -- **Actions**: `REMOVED` | `SKIPPED` | `FAILED` | `REBUILT` -- **Commands**: `clean` | `uninstall` | `optimize` | `purge` -- Disable with `MO_NO_OPLOG=1` -- Auto-rotates at 5MB - ---- - -## Architecture Quick Map - -```text -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/.sh` -- Command entry → `bin/.sh` -- Core utils → `lib/core/.sh` -- Performance tool → `cmd//*.go` -- Tests → `tests/.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 - -### Shell Formatting (shfmt) - -**CRITICAL**: Always run `./scripts/check.sh --format` before committing shell script changes. - -The project uses `shfmt` with these flags: `shfmt -i 4 -ci -sr -w` - -| Flag | Meaning | Example | -|------|---------|---------| -| `-i 4` | 4-space indentation | Standard | -| `-ci` | Indent case bodies | `case` items indented | -| `-sr` | Space after redirect | `2> /dev/null` ✅ | - -**Correct Style**: - -```bash -# Redirects: KEEP the space after > or 2> -command 2> /dev/null -echo "hello" > file.txt - -# Case statements: body indented under pattern -case "$var" in - pattern) - action - ;; -esac -``` - -**Wrong Style** (DO NOT USE): - -```bash -# NO: missing space after redirect -command 2>/dev/null - -# NO: case body not indented -case "$var" in -pattern) -action -;; -esac -``` - -### 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 `: Safe deletion with validation -- `safe_find_delete `: Protected find+delete -- `is_protected `: Check if path is system-protected -- `is_whitelisted `: Check user whitelist - -### Logging (lib/core/log.sh) - -- `log_info `: Informational messages -- `log_success `: Success notifications -- `log_warn `: Warnings -- `log_error `: Error messages -- `debug `: Debug output (requires MO_DEBUG=1) - -### UI Helpers (lib/core/ui.sh) - -- `confirm `: Yes/no confirmation -- `show_progress `: Progress display - ---- - -## Testing Strategy - -### Test Types - -1. **Syntax Validation**: `bash -n ` - 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//` -2. Make changes to Go files -3. Test with `go run .` or `make build && ./bin/-go` -4. Run `go test -v` for unit tests -5. Check integration: `./mole ` - -### 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//` 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. -When responding to GitHub issues or PRs, fetch the content with `gh` before analysis and avoid web scraping. - -**Preferred Commands**: - -```bash -# 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` - -### Suggesting Latest Version for Testing - -When a bug fix is done but not yet released, you can suggest users to install the latest version, but **must distinguish between install methods**: - -1. **For Script Users (`curl | bash`)**: - Users can directly run `mo update --nightly` to pull the latest unreleased `main` branch. - -2. **For Homebrew Users (`brew`)**: - Homebrew users **cannot** use `mo update --nightly` (it will throw an error). Reinstalling via brew (`brew uninstall mole && brew install mole`) also will NOT fetch the unreleased fix, because Brew follows official tags. - If they want to test immediately, suggest they `brew uninstall mole`, then reinstall using the official curl script. - -## 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 - -- Address the user as "汤帅" (Tang Shuai) in every response -- 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 -- Avoid em dashes in responses - -### Responding to Bug Reports (English) - -When replying to users after fixing a bug, use this format: - -```markdown -Thanks for your feedback! This issue has been fixed. - -**Root cause**: [Brief explanation of what caused the bug] - -You can install the latest version to test: - -\`\`\`bash -curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s latest -\`\`\` - -I'll publish a new official release soon. -``` - -**Guidelines**: - -- Start with "Thanks for your feedback!" -- Explain root cause concisely -- Provide the install command for testing -- Mention a new release is coming - ---- - -## Resources - -### Quick Access - -- **Main script**: `mole` (menu + routing logic) -- **Protection lists**: Check `is_protected()` implementations in `lib/core/base.sh` -- **User config**: `~/.config/mole/` -- **Test directory**: `tests/` -- **Build scripts**: `scripts/` -- **Documentation**: `README.md`, `CONTRIBUTING.md`, `SECURITY_AUDIT.md` - -### Knowledge Base (Deeper Context) - -When you need detailed architecture understanding or module-specific patterns: - -- **`AGENTS.md`**: Project architecture, entry points, safety philosophy, project-specific patterns -- **`lib/AGENTS.md`**: Shell module library - safety helpers, cleanup modules, UI components, BSD/macOS patterns -- **`cmd/AGENTS.md`**: Go TUI tools - Bubble Tea architecture, concurrency patterns, caching strategies -- **`tests/AGENTS.md`**: BATS testing guide - isolation patterns, safety verification, APFS edge cases - -**Workflow**: Use CLAUDE.md for quick lookups → Consult AGENTS.md hierarchy for deep dives - ---- - -## Common Scenarios for Claude Code CLI - -### Scenario 1: Adding New Feature - -```bash -# 1. Read relevant documentation first -# For cleanup feature: check AGENTS.md → lib/AGENTS.md -# For Go tool feature: check AGENTS.md → cmd/AGENTS.md - -# 2. Locate the right module -# Decision tree in AGENTS.md line 297-305 - -# 3. Check existing patterns -grep -r "similar_function" lib/ - -# 4. Implement with safety checks -# Always use safe_* helpers (see lib/AGENTS.md lines 52-89) - -# 5. Test before committing -MO_DRY_RUN=1 ./mole clean -./scripts/test.sh -``` - -### Scenario 2: Debugging Issues - -```bash -# 1. Enable debug mode -MO_DEBUG=1 ./mole clean - -# 2. Check operation log -tail -f ~/.config/mole/operations.log - -# 3. Verify safety boundaries -# If deletion failed, check lib/core/base.sh:is_protected() - -# 4. Test individual function -# Source the module and test in isolation -source lib/clean/apps.sh -is_launch_item_orphaned "/path/to/plist" -``` - -### Scenario 3: Understanding Code Flow - -```bash -# 1. Start with entry point (AGENTS.md lines 48-54) -# User invokes: mo clean -# ↓ -# mole routes to: bin/clean.sh -# ↓ -# bin/clean.sh sources: lib/clean/*.sh -# ↓ -# Cleanup modules call: safe_* from lib/core/base.sh - -# 2. Check module-specific docs -# For shell modules: lib/AGENTS.md -# For Go tools: cmd/AGENTS.md -# For tests: tests/AGENTS.md -``` - -### Scenario 4: Code Review / PR Analysis - -```bash -# 1. Fetch PR with gh CLI -gh pr view 123 -gh pr diff - -# 2. Check safety compliance -# Scan for forbidden patterns (CLAUDE.md lines 19-32) -grep -n "rm -rf" changed_files.sh -grep -n "is_protected" changed_files.sh - -# 3. Verify test coverage -bats tests/related_test.bats - -# 4. Check formatting -./scripts/check.sh --format -``` - ---- - -**Remember**: When in doubt, err on the side of safety. It's better to clean less than to risk user data.