Add CLAUDE.md

Author: angelofenoglio

CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Setup
+- `poetry install --with=dev --with=main` - Install all dependencies including dev tools
+- `poetry shell` - Activate virtual environment for development
+
+### Testing
+- `poetry run pytest` - Run unit tests
+- `poetry run pytest --verbose --cov=./ --cov-report=xml` - Run unit tests with coverage
+- `make test-unit` - Run unit tests in Docker (with coverage)
+- `make test-unit-no-cov` - Run unit tests in Docker (no coverage)
+- `make test-int` - Run integration tests using bats in Docker
+- `make tests` - Run full test suite (unit + integration)
+
+### Code Quality
+- `poetry run black .` - Format code with Black (line length: 120)
+- `poetry run pylint leverage/` - Run linting
+- `poetry run pre-commit install` - Install pre-commit hooks
+- `poetry run pre-commit run --all-files` - Run pre-commit checks manually
+
+### Build and Distribution
+- `make build` - Build distributables (cleans first)
+- `make check` - Check distributables with twine
+- `poetry build` - Build package using Poetry
+- `make clean` - Clean build artifacts
+
+### Docker
+- `make build-image` - Build Docker testing image
+- All test commands can run in Docker using the testing image
+
+## Architecture
+
+Leverage CLI is a Python-based command-line tool for managing Binbash Leverage projects. It uses a dockerized approach to encapsulate infrastructure tools.
+
+### Core Structure
+- `leverage/leverage.py` - Main CLI entry point using Click framework
+- `leverage/modules/` - Command modules (aws, terraform, kubectl, etc.)
+- `leverage/container.py` - Docker container management and execution
+- `leverage/conf.py` - Configuration loading from build.env files
+- `leverage/tasks.py` - Task system for build scripts
+- `leverage/path.py` - Path utilities and git repository handling
+
+### Key Components
+- **Module System**: Commands are organized in modules under `leverage/modules/`
+- **Container Integration**: Heavy use of Docker containers for tool execution
+- **Configuration Management**: Hierarchical loading of build.env files
+- **Task System**: Decorator-based task definition system for build scripts
+- **AWS Integration**: Extensive AWS credential and service management
+
+### Command Structure
+The CLI follows this pattern:
+```
+leverage [global-options] <module> <subcommand> [args]
+```
+
+Key modules include:
+- `project` - Project initialization and management
+- `terraform`/`tf`/`tofu` - Terraform/OpenTofu operations
+- `aws` - AWS service interactions
+- `credentials` - Credential management
+- `kubectl`/`kc` - Kubernetes operations
+- `run` - Custom task execution
+- `shell` - Interactive shell access
+
+### Version Management
+- Supports Python 3.9-3.13
+- Version defined in `leverage/__init__.py`
+- Minimum tool versions enforced via `MINIMUM_VERSIONS`
+- Docker image versioning through `__toolbox_version__`
+
+### Configuration
+- Uses `build.env` files for project configuration
+- Hierarchical loading from project root to current directory
+- Environment-specific overrides supported
+
+## Docker Container Architecture for Terraform/OpenTofu
+
+The CLI uses a containerized approach for all Terraform/OpenTofu operations to ensure consistent tool versions and isolated execution environments.
+
+### Container Classes
+
+#### TFContainer (`leverage/container.py:436-687`)
+Primary container for Terraform/OpenTofu execution:
+- **Image**: `binbash/leverage-toolbox` with user-specific permissions
+- **Binaries**: `/bin/terraform` (when `terraform=True`) or `/bin/tofu` (default)
+- **Mount Points**:
+  - Project root → `/leverage` (guest base path)
+  - AWS credentials directory → `/tmp/.aws`
+  - Git config file → `/etc/gitconfig`
+  - Optional: TF plugin cache directory (maintains symlinks)
+  - Optional: SSH agent socket → `/ssh-agent`
+
+#### TFautomvContainer (`leverage/container.py:689-717`)
+Extends TFContainer for TFAutomv operations:
+- **Binary**: `/usr/local/bin/tfautomv`
+- Inherits all TFContainer mounts and configuration
+
+### Configuration File Management
+
+#### Environment Variables in Containers:
+- `COMMON_CONFIG_FILE` → `common.tfvars`
+- `ACCOUNT_CONFIG_FILE` → `account.tfvars`
+- `BACKEND_CONFIG_FILE` → `backend.tfvars`
+- `AWS_SHARED_CREDENTIALS_FILE` → `/tmp/.aws/credentials`
+- `AWS_CONFIG_FILE` → `/tmp/.aws/config`
+- `SSO_CACHE_DIR` → `/tmp/.aws/sso/cache`
+
+#### Terraform Variable Files:
+The `tf_default_args` property automatically includes:
+- All `*.tfvars` files from `common/` directory
+- All `*.tfvars` files from account-specific directory
+
+### Docker Execution Points
+
+#### Terraform/OpenTofu Commands (`leverage/modules/tf.py`)
+- Container creation for `tofu` and `terraform` commands (lines 38, 56)
+- Command execution via `tf.start()` for all operations
+- **Supported Commands**: `init`, `plan`, `apply`, `destroy`, `output`, `version`, `shell`, `format`, `validate`, `import`, `refresh-credentials`
+
+#### TFAutomv Commands (`leverage/modules/tfautomv.py`)
+- Container creation for `tfautomv` commands (line 24)
+- Command execution via `tf.start_in_layer()` (line 36)
+
+### Container Lifecycle
+
+1. **Image Verification**: `ensure_image()` builds local image with user permissions
+2. **Container Creation**: `_create_container()` with mounted volumes and environment
+3. **Authentication Setup**: SSO token validation or MFA credential handling
+4. **Command Execution**: Interactive (`_start()`) or silent (`_exec()`)
+5. **Cleanup**: Automatic container stop and removal
+
+### Authentication & Credentials
+
+#### SSO Authentication:
+- Token validation before container execution
+- Automatic credential refresh via `refresh_layer_credentials()`
+- Browser-based authentication flow with user code
+
+#### MFA Authentication:
+- Script-based authentication via `aws-mfa-entrypoint.sh`
+- Environment variable adjustments for credential paths
+
+#### Credential Mounting:
+- Host AWS credentials directory mounted to container
+- Separate credential files for different authentication methods
+
+### Backend Configuration Management
+
+#### S3 Backend Handling:
+- Automatic `backend.tfvars` parameter injection for `init` commands
+- Dynamic state key generation based on layer path structure
+- Backend block validation in `config.tf` files
+- Support for legacy naming conventions (tf- vs terraform-)
+
+#### Execution Flow (Host-Based):
+1. **CLI Command** → 2. **Environment Setup** → 3. **Authentication Context** → 4. **Host Binary Execution** → 5. **Result Return**
+
+**IMPORTANT**: As of the latest update, Leverage CLI now uses **host-based execution** instead of Docker containers:
+
+## Host-Based Execution Architecture
+
+The CLI has been updated to use host-based execution for improved performance and flexibility while maintaining all functionality.
+
+### New Executor Classes
+
+#### TerraformExecutor (`leverage/executors/terraform.py`)
+Host-based Terraform/OpenTofu executor:
+- **Binaries**: Uses system-installed `terraform` or `tofu` binaries
+- **Environment Management**: Context managers handle environment variables
+- **Authentication**: Supports SSO and MFA through host AWS CLI
+- **Configuration**: Automatic discovery and injection of .tfvars files
+- **Working Directory**: Direct filesystem operations (no mounting required)
+
+#### TFAutomvExecutor (`leverage/executors/tfautomv.py`)
+Extends TerraformExecutor for TFAutomv operations:
+- **Binary**: Uses system-installed `tfautomv` binary
+- Inherits all TerraformExecutor functionality
+
+### Context Manager Architecture
+
+#### Environment Context (`leverage/executors/context.py`)
+- **environment_context()**: Temporarily modifies environment variables with automatic cleanup
+- **run_command()**: Executes commands with environment and working directory context
+- Clean separation between interactive and silent execution modes
+
+#### Authentication Context (`leverage/executors/auth.py`)
+- **aws_credentials_context()**: Manages AWS authentication setup
+- SSO token validation and refresh
+- MFA credential path management
+- Automatic credential file discovery
+
+### Benefits of Host-Based Execution
+
+- **Performance**: No container startup overhead or image building
+- **Flexibility**: Use any installed tool version (including custom builds)
+- **IDE Integration**: Better debugging and tooling support
+- **Simplicity**: Direct binary execution with standard environment variables
+- **Plugin Compatibility**: Native plugin caching and management
+
+### Migration from Container-Based Execution
+
+The transition maintains full CLI compatibility:
+- All existing commands work identically
+- Same authentication methods (SSO/MFA)
+- Same configuration file handling
+- Same working directory behavior
+- Improved performance and reduced resource usage
+
+### Host Requirements
+
+For full functionality, ensure the following binaries are installed:
+- `terraform` or `tofu` (for Terraform/OpenTofu operations)  
+- `tfautomv` (for TFAutomv operations)
+- `aws` CLI (for authentication)
+- `hcledit` (for configuration management)