Mole/AGENT.md

Mole AI Agent Notes

Use this file as the single source of truth for how to work on Mole.

Principles

• Safety first: never risk user data or system stability.
• Never run destructive operations that could break the user's machine.
• Do not delete user-important files; cleanup must be conservative and reversible.
• Always use safe_* helpers (no raw rm -rf).
• Keep changes small and confirm uncertain behavior.
• Follow the local code style in the file you are editing (Bash 3.2 compatible).
• Comments must be English, concise, and intent-focused.
  • Use comments for safety boundaries, non-obvious logic, or flow context.
  • Entry scripts start with ~3 short lines describing purpose/behavior.
• Shell code must use shell-only helpers (no Python).
• Go code must use Go-only helpers (no Python).
• Do not remove installer flags --prefix/--config (update flow depends on them).
• Do not commit or submit code changes unless explicitly requested.
• You may use gh to access GitHub information when needed.

Architecture

• mole: main CLI entrypoint (menu + command routing).
• mo: CLI alias wrapper.
• install.sh: manual installer/updater (download/build + install).
• bin/: command entry points (clean.sh, uninstall.sh, optimize.sh, purge.sh, touchid.sh, analyze.sh, status.sh).
• lib/: shell logic (core/, clean/, ui/).
• cmd/: Go apps (analyze/, status/).
• scripts/: build/test helpers.
• tests/: BATS integration tests.

Workflow

• Shell work: add logic under lib/, call from bin/.
• Go work: edit cmd/<app>/*.go.
• Prefer dry-run modes while validating cleanup behavior.

Build & Test

• ./scripts/test.sh runs unit/go/integration tests.
• make build builds Go binaries for local development.
• go run ./cmd/analyze for dev runs without building.

Key Behaviors

• mole update uses install.sh with --prefix/--config; keep these flags.
• Cleanup must go through safe_* and respect protection lists.