# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`ilum-cli` is a Python CLI tool for deploying and managing the Ilum data lakehouse platform on Kubernetes via Helm. It wraps Helm/kubectl operations with module dependency resolution, values safety (drift detection), interactive wizards, and structured error handling.

**Entry point:** `src/ilum/cli/main.py` — Typer app registered as the `ilum` console script.

## Commands

```bash
# Setup
pip install -e ".[dev]"

# Run all checks (format + lint + typecheck + tests)
ruff format --check src tests && ruff check src tests && mypy src && pytest tests/unit -v

# Individual checks
ruff format src tests              # format code
ruff format --check src tests      # check formatting
ruff check src tests               # lint
mypy src                           # type check (strict mode)

# Tests
pytest tests/unit -v                                      # all unit tests
pytest tests/unit/test_modules.py -v                      # single file
pytest tests/unit/test_modules.py::test_resolve_enables_sql -v  # single test
pytest tests/unit -v --cov=ilum --cov-report=term-missing      # with coverage

# Build standalone binary
pip install -e ".[build]"
pyinstaller ilum.spec --clean

# Cross-platform builds (Docker)
make build-linux-amd64
make build-linux-arm64
make release              # all platforms + checksums
```

## Architecture

### Layer Structure

```
cli/          Command layer (Typer commands, output formatting)
  ↓ calls
core/         Business logic (HelmClient, KubeClient, ModuleResolver, ReleaseManager)
  ↓ calls
config/       Configuration persistence (Pydantic models, YAML I/O with file locking)
wizard/       Interactive setup flow (preflight checks, cluster creation, module selection)
doctor/       Health check system (13 checks, phased execution)
```

### Key Patterns

**Module System** (`core/modules.py`): 31 modules defined as frozen `ModuleDefinition` dataclasses in `MODULE_REGISTRY`. Each module has `pod_label` for pod queries, `required` flag for mandatory modules, and optional `crd_chart` for CRD pre-install (e.g., monitoring module installs prometheus CRDs before enable). `ModuleResolver` walks the dependency graph topologically, detects conflicts, and generates Helm `--set` flags for enable/disable operations.

**Values Safety Pipeline** (`core/safety.py`, `core/values.py`, `core/release.py`):
1. Fetch live values from running release (`helm get values`)
2. Compare against last CLI snapshot (stored in `~/.local/state/ilum/snapshots/`)
3. Detect drift (external changes since last CLI operation)
4. Merge: live values + CLI overlay + user `--set` flags
5. Show diff table, confirm, execute `helm upgrade`, save new snapshot

**ReleaseManager** (`core/release.py`): Orchestration facade between CLI commands and HelmClient/KubeClient. Produces a `ReleasePlan` (action, chart, values, drift, diff) then executes it.

**HelmClient** (`core/helm.py`): Subprocess wrapper that builds `helm` commands, runs them with timeouts, and parses JSON output into `HelmResult` objects.

**Output** (`cli/output.py`): `IlumConsole` singleton wrapping Rich. Respects `--quiet`, `--verbose`, and `--output json|yaml|table` flags set in the main callback.

**Error Handling** (`errors.py`, `error_codes.py`): `IlumError` base with typed subclasses. Every error carries optional `suggestion`, `error_code` (e.g., `ILUM-020`), and `recovery_steps`.

### Configuration

- **IlumPaths** (`config/paths.py`): Cross-platform directory resolution (XDG on Linux/macOS, APPDATA on Windows)
- **ConfigManager** (`config/manager.py`): YAML I/O with file locking (`fcntl` on Unix, `msvcrt` on Windows)
- **Pydantic v2 models** (`config/models.py`): `IlumConfig` → `ProfileConfig` → `ClusterConfig`

## Code Style

- Python 3.12+, strict mypy, ruff lint rules: `E, F, W, I, N, UP, B, A, SIM`
- Line length: 100 characters
- All source uses `from __future__ import annotations`
- Frozen dataclasses for immutable data, Pydantic v2 for validated config models
- `ruamel.yaml` for round-trip YAML preservation (comments and ordering)

## Testing

Tests are in `tests/unit/` (53 files, 963+ tests). Nearly all tests mock `HelmClient` and `KubeClient` to avoid subprocess/cluster calls. Shared fixtures are in `tests/conftest.py` (autouse console reset, `tmp_config_dir`, `mock_helm`, `mock_k8s`, `resolver`, `mock_release_mgr`, `cli_runner`).

## Versioning

Version is auto-detected from git tags matching `cli-v*` (e.g., `cli-v0.3.0`) via `hatch-vcs`. Falls back to `0.1.0` if no tags found. The git tag pattern is distinct from the parent Helm chart's `RELEASE.*` tags.
