Update CLAUDE.md

Author: angelofenoglio

CLAUDE.md

@@ -34,22 +34,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Architecture
 
-Leverage CLI is a Python-based command-line tool for managing Binbash Leverage projects. It uses a dockerized approach to encapsulate infrastructure tools.
+Leverage CLI is a Python-based command-line tool for managing Binbash Leverage projects. It uses host-based execution to run infrastructure tools directly on the system.
 
 ### 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/modules/runner.py` - Generic binary runner base class
+- `leverage/modules/tfrunner.py` - Terraform/OpenTofu-specific runner
 - `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
+- **Host-Based Execution**: Direct execution of system binaries (terraform, tofu, kubectl, etc.)
+- **Runner Architecture**: Generic Runner class with specialized subclasses (TFRunner)
 - **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
+- **AWS Integration**: Extensive AWS credential and service management via SSO/MFA
 
 ### Command Structure
 The CLI follows this pattern:
@@ -69,98 +71,16 @@ Key modules include:
 ### 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__`
+- Binary version validation on initialization (for TFRunner)
 
 ### 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
+## Execution Architecture
 
-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-)
-
-**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.
+The CLI executes infrastructure tools directly on the host system using the Runner architecture.
 
 ### Core Runner Classes
 
@@ -179,84 +99,103 @@ Generic command runner base class:
 Terraform/OpenTofu-specific runner extending Runner:
 - **Binaries**: Uses system-installed `terraform` or `tofu` binaries
 - **Configuration**: Accepts `terraform=True` for Terraform, defaults to OpenTofu
+- **Binary Validation**: Validates binary type by checking `--version` output
+  - Ensures `tofu` binary is actually OpenTofu (not Terraform)
+  - Ensures `terraform` binary is actually Terraform (not OpenTofu)
 - **Error Messages**: Provides installation URLs when binaries are not found
   - Terraform: https://developer.hashicorp.com/terraform/install
   - OpenTofu: https://opentofu.org/docs/intro/install/
 - **Environment Variables**: Initialized with AWS credential file paths via `env_vars` parameter
-- **No Containers**: Direct binary execution on host system
-
-### Command Flow Architecture
-
-#### Terraform/OpenTofu Command Flow (`leverage/modules/tf.py`)
-
-1. **CLI Entry Points**:
-   - `@click.group() tofu()` (lines 22-35) - Creates TFRunner with OpenTofu binary
-   - `@click.group() terraform()` (lines 38-51) - Creates TFRunner with Terraform binary
-   - Both set up credential environment variables for AWS config and credentials files
-
-2. **Command Decoration**:
-   - `@pass_runner` - Injects TFRunner instance from Click context
-   - `@pass_paths` - Injects PathsHandler instance for file/directory management
-
-3. **Supported Commands**:
-   - `init` - Layer initialization with backend configuration injection
-   - `plan` - Execution plan generation with auto-discovered tfvars
-   - `apply` - Infrastructure changes with conditional tfvars injection
-   - `destroy` - Infrastructure destruction
-   - `output` - Output variable display
-   - `version` - Binary version display
-   - `format` - Code formatting (recursive by default)
-   - `force-unlock` - State file lock removal
-   - `validate` - Configuration validation
-   - `validate-layout` - Leverage convention validation
-   - `import` - Resource import
-   - `refresh-credentials` - AWS credential refresh
-
-4. **Multi-Layer Support**:
-   - `--layers` option for operating on multiple layers from account directory
-   - Layer validation and backend key management via `invoke_for_all_commands()`
-   - Automatic backend key generation based on layer path structure
-
-### Authentication Management
-
-#### SSO Authentication (`leverage/modules/auth.py`)
-
-**Token Validation** (`check_sso_token()` - lines 98-127):
-- Validates SSO token existence in cache directory
+
+### Command Modules
+
+#### Terraform/OpenTofu Commands (`leverage/modules/tf.py`)
+
+**CLI Entry Points**:
+- `tofu` - Creates TFRunner with OpenTofu binary (`tofu`)
+- `terraform` - Creates TFRunner with Terraform binary (`terraform`)
+- Both set up credential environment variables for AWS config and credentials files
+
+**Command Decorators**:
+- `@pass_runner` - Injects TFRunner instance from Click context
+- `@pass_paths` - Injects PathsHandler instance for file/directory management
+
+**Supported Commands**:
+- `init` - Layer initialization with backend configuration injection
+- `plan` - Execution plan generation with auto-discovered tfvars
+- `apply` - Infrastructure changes with conditional tfvars injection
+- `destroy` - Infrastructure destruction
+- `output` - Output variable display
+- `version` - Binary version display
+- `format` - Code formatting (recursive by default)
+- `force-unlock` - State file lock removal
+- `validate` - Configuration validation
+- `validate-layout` - Leverage convention validation
+- `import` - Resource import
+- `refresh-credentials` - AWS credential refresh
+
+**Multi-Layer Support**:
+- `--layers` option for operating on multiple layers from account directory
+- Layer validation and backend key management via `invoke_for_all_commands()`
+- Automatic backend key generation based on layer path structure
+
+#### Kubectl Commands (`leverage/modules/kubectl.py`)
+
+Uses generic Runner class to execute `kubectl` binary:
+- **Binary**: System-installed `kubectl`
+- **Configuration**: Sets KUBECONFIG environment variable to project-specific path
+- **AWS Integration**: Configures kubectl contexts for EKS clusters
+- **Commands**:
+  - `configure` - Add EKS cluster from current layer to kubectl config
+  - `discover` - Scan for cluster metadata files and configure selected cluster
+- All other kubectl commands pass through to the binary
+
+#### TFAutomv Commands (`leverage/modules/tfautomv.py`)
+
+Uses generic Runner class to execute `tfautomv` binary:
+- **Binary**: System-installed `tfautomv`
+- **Configuration**: Passes terraform binary path via `--terraform-bin` flag
+- **Integration**: Uses same tfvars discovery as Terraform/OpenTofu commands
+
+### Authentication Management (`leverage/modules/auth.py`)
+
+#### SSO Authentication
+
+**Token Validation** (`check_sso_token()`):
+- Validates SSO token existence in cache directory (`~/.aws/sso/cache/<sso_role>`)
 - Checks token expiration against current time
 - Provides clear error messages for missing or expired tokens
-- Token file location: `~/.aws/sso/cache/<sso_role>`
 
-**Credential Refresh** (`refresh_layer_credentials()` - lines 130-204):
+**Credential Refresh** (`refresh_layer_credentials()`):
 - Parses Terraform files to discover required AWS profiles
 - Uses boto3 SSO client to retrieve temporary credentials
 - Updates AWS config file with credential expiration timestamps
 - Writes temporary credentials to AWS credentials file
 - Implements 30-minute early renewal to avoid mid-operation expiration
 - Supports cross-account profile resolution
 
-**Profile Discovery** (`get_profiles()` - lines 68-88):
+**Profile Discovery** (`get_profiles()`):
 - Scans `config.tf`, `locals.tf`, `runtime.tf` for profile references
 - Extracts profile variables from Terraform configurations
 - Reads backend profile from `backend.tfvars`
 
 ### Configuration Management
 
-#### Automatic tfvars Discovery (`tf_default_args()` - lines 133-154):
+#### Automatic tfvars Discovery (`tf_default_args()`):
 - Discovers all `*.tfvars` files in `common/` directory
 - Discovers all `*.tfvars` files in account-specific directory
 - Returns as `-var-file=<path>` arguments for Terraform/OpenTofu
 - Used automatically in plan, destroy, validate, and conditionally in apply
 
 #### Backend Configuration:
-- Backend config file path injected during `init` command (line 336)
-- Automatic backend key generation in `invoke_for_all_commands()` (lines 291-294)
-- Backend key validation in `validate_layout()` (lines 538-550)
+- Backend config file path injected during `init` command
+- Automatic backend key generation in `invoke_for_all_commands()`
+- Backend key validation in `validate_layout()`
 - Support for legacy naming conventions (tf- vs terraform-, base- vs tools-)
 
 ### Execution Flow
 
-**Standard Command Execution**:
+#### Standard Command Execution
 1. User runs `leverage tofu|terraform <command> [args]`
 2. Click creates TFRunner instance with credential environment variables
 3. Command function decorated with `@pass_runner` and `@pass_paths`
@@ -269,26 +208,30 @@ Terraform/OpenTofu-specific runner extending Runner:
    - User-provided arguments
 7. Exit code returned to CLI
 
-**Multi-Layer Execution**:
+#### Multi-Layer Execution
 1. User runs command with `--layers layer1,layer2` from account directory
 2. `invoke_for_all_commands()` validates all layers
 3. Backend keys generated/validated for each layer
 4. Command executed sequentially for each layer with layer-specific working directory
 
-### Benefits of Host-Based Execution
+### System Requirements
 
-- **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 Terraform/OpenTofu plugin caching
-- **Development Speed**: Faster iteration during development
+For full functionality, ensure the following binaries are installed and available in PATH:
 
-### Host Requirements
+**Required**:
+- `terraform` or `tofu` - For Terraform/OpenTofu operations
+- `aws` - AWS CLI for SSO authentication (via boto3)
+- Python 3.9-3.13
 
-For full functionality, ensure the following binaries are installed and available in PATH:
-- `terraform` or `tofu` (for Terraform/OpenTofu operations)
-- `aws` CLI (for SSO authentication via boto3)
+**Optional**:
+- `kubectl` - For Kubernetes operations
+- `tfautomv` - For TFAutomv operations
+
+### Benefits of Current Architecture
 
-Optional binaries:
-- `tfautomv` (for TFAutomv operations)
+- **Performance**: Direct binary execution without overhead
+- **Flexibility**: Use any installed tool version (including custom builds)
+- **IDE Integration**: Better debugging and tooling support
+- **Simplicity**: Standard environment variables and execution
+- **Plugin Compatibility**: Native Terraform/OpenTofu plugin caching
+- **Development Speed**: Faster iteration during development