Mole/AGENT.md

# Mole AI Agent Documentation

> **READ THIS FIRST**: This file serves as the single source of truth for any AI agent trying to work on the Mole repository. It aggregates architectural context, development workflows, and behavioral guidelines.

## 1. Philosophy & Guidelines

### Core Philosophy

- **Safety First**: Never risk user data. Always use `safe_*` wrappers. When in doubt, ask.
- **Incremental Progress**: Break complex tasks into manageable stages.
- **Clear Intent**: Prioritize readability and maintainability over clever hacks.
- **Native Performance**: Use Go for heavy lifting (scanning), Bash for system glue.

### Eight Honors and Eight Shames

- **Shame** in guessing APIs, **Honor** in careful research.
- **Shame** in vague execution, **Honor** in seeking confirmation.
- **Shame** in assuming business logic, **Honor** in human verification.
- **Shame** in creating interfaces, **Honor** in reusing existing ones.
- **Shame** in skipping validation, **Honor** in proactive testing.
- **Shame** in breaking architecture, **Honor** in following specifications.
- **Shame** in pretending to understand, **Honor** in honest ignorance.
- **Shame** in blind modification, **Honor** in careful refactoring.

### Quality Standards

- **English Only**: Comments and code must be in English.
- **No Unnecessary Comments**: Code should be self-explanatory.
- **Pure Shell Style**: Use `[[ ]]` over `[ ]`, avoid `local var` assignments on definition line if exit code matters.
- **Go Formatting**: Always run `gofmt` (or let the build script do it).

## 2. Project Identity

- **Name**: Mole
- **Purpose**: A lightweight, robust macOS cleanup and system analysis tool.
- **Core Value**: Native, fast, safe, and dependency-free (pure Bash + static Go binary).
- **Mechanism**:
  - **Cleaning**: Pure Bash scripts for transparency and safety.
  - **Analysis**: High-concurrency Go TUI (Bubble Tea) for disk scanning.
  - **Monitoring**: Real-time Go TUI for system status.

## 3. Technology Stack

- **Shell**: Bash 3.2+ (macOS default compatible).
- **Go**: Latest Stable (Bubble Tea framework).
- **Testing**:
  - **Shell**: `bats-core`, `shellcheck`.
  - **Go**: Native `testing` package.

## 4. Repository Architecture

### Directory Structure

- **`bin/`**: Standalone entry points.
  - `mole`: Main CLI wrapper.
  - `clean.sh`, `uninstall.sh`: Logic wrappers calling `lib/`.
- **`cmd/`**: Go applications.
  - `analyze/`: Disk space analyzer (concurrent, TUI).
  - `status/`: System monitor (TUI).
- **`lib/`**: Core Shell Logic.
  - `core/`: Low-level utilities (logging, `safe_remove`, sudo helpers).
  - `clean/`: Domain-specific cleanup tasks (`brew`, `caches`, `system`).
  - `ui/`: Reusable TUI components (`menu_paginated.sh`).
- **`scripts/`**: Development tools (`run-tests.sh`, `build-analyze.sh`).
- **`tests/`**: BATS integration tests.

## 5. Key Workflows

### Development

1. **Understand**: Read `lib/core/` to know what tools are available.
2. **Implement**:
    - For Shell: Add functions to `lib/`, source them in `bin/`.
    - For Go: Edit `cmd/app/*.go`.
3. **Verify**: Use dry-run modes first.

**Commands**:

- `./scripts/run-tests.sh`: **Run EVERYTHING** (Lint, Syntax, Unit, Go).
- `./bin/clean.sh --dry-run`: Test cleanup logic safely.
- `go run ./cmd/analyze`: Run analyzer in dev mode.

### Building

- `./scripts/build-analyze.sh`: Compiles `analyze-go` binary (Universal).
- `./scripts/build-status.sh`: Compiles `status-go` binary.

### Release

- Versions managed via git tags.
- Build scripts embed version info into binaries.

## 6. Implementation Details

### Safety System (`lib/core/file_ops.sh`)

- **Crucial**: Never use `rm -rf` directly.
- **Use**:
  - `safe_remove "/path"`
  - `safe_find_delete "/path" "*.log" 7 "f"`
- **Protection**:
  - `validate_path_for_deletion` prevents root/system deletion.
  - `checks` ensure path is absolute and safe.

### Go Concurrency (`cmd/analyze`)

- **Worker Pool**: Tuned dynamically (16-64 workers) to respect system load.
- **Throttling**: UI updates throttled (every 100 items) to keep TUI responsive (80ms tick).
- **Memory**: Uses Heaps for top-file tracking to minimize RAM usage.

### TUI Unification

- **Keybindings**: `j/k` (Nav), `space` (Select), `enter` (Action), `R` (Refresh).
- **Style**: Compact footers ` | ` and standard colors defined in `lib/core/base.sh` or Go constants.

## 7. Common AI Tasks

- **Adding a Cleanup Task**:
    1. Create/Edit `lib/clean/topic.sh`.
    2. Define `clean_topic()`.
    3. Register in `lib/optimize/tasks.sh` or `bin/clean.sh`.
    4. **MUST** use `safe_*` functions.
- **Modifying Go UI**:
    1. Update `model` struct in `main.go`.
    2. Update `View()` in `view.go`.
    3. Run `./scripts/build-analyze.sh` to test.
- **Fixing a Bug**:
    1. Reproduce with a new BATS test in `tests/`.
    2. Fix logic.
    3. Verify with `./scripts/run-tests.sh`.