# Contributing to Kuberoku

Contributions are welcome. Whether it's a bug fix, a new feature, documentation, or just a question — we're glad you're here.

## Getting started

```bash
git clone https://github.com/amanjain/kuberoku.git
cd kuberoku
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Use your GitHub noreply email to keep your personal email private
git config user.email "USERNAME@users.noreply.github.com"
```

Find your noreply email at [github.com/settings/emails](https://github.com/settings/emails).

## Local dev environment

### Quick setup (macOS)

```bash
./scripts/dev-setup.sh
```

This installs everything: Python venv, colima (Docker + Kubernetes), and act (local CI runner). If you prefer manual setup, read on.

### Manual setup

**Prerequisites:**

```bash
brew install act colima kubectl
```

| Tool | What it does |
|------|-------------|
| **colima** | Lightweight Docker + Kubernetes runtime (no Docker Desktop needed) |
| **act** | Runs GitHub Actions workflows locally |
| **kubectl** | Kubernetes CLI (also installed by colima, but good to have) |

**Start colima with Docker + Kubernetes:**

```bash
colima start --kubernetes --cpu 2 --memory 4
```

This gives you both Docker (for `act`) and a single-node K8s cluster. First start downloads ~300MB and takes a few minutes. Subsequent starts are fast.

**Set the Docker socket** (add to your `~/.zshrc` or `~/.bashrc`):

```bash
export DOCKER_HOST="unix://${HOME}/.colima/docker.sock"
```

**Verify:**

```bash
docker ps                    # Docker works
kubectl get nodes            # K8s works — should show "colima Ready"
```

**Stop when done:**

```bash
colima stop
```

### Run CI locally

Run the full GitHub Actions workflow on your machine before pushing:

```bash
./scripts/act-local.sh                     # full matrix (all combos)
./scripts/act-local.sh 3.12 latest         # single Python + K8s combo (fastest)
```

This runs lint, type check, and the full test suite inside a Linux container — identical to what GitHub Actions runs.

### Run tests directly

```bash
./scripts/test.sh                  # all tests + coverage
./scripts/lint.sh                  # ruff + mypy + vulture
pytest tests/ -v                   # pytest directly
pytest tests/apps/ -v              # just one feature
pytest tests/ -v -k "test_create"  # just one test name
```

### Scripts reference

| Script | What it does |
|--------|-------------|
| `scripts/dev-setup.sh` | One-time dev environment bootstrap |
| `scripts/test.sh` | Run tests with coverage |
| `scripts/lint.sh` | Lint, type check, dead code analysis |
| `scripts/act-local.sh` | Run GitHub Actions workflow locally via act + colima |

## Before you submit

Run all checks. Every PR must pass these:

```bash
pytest tests/ -v                    # tests pass
mypy src/kuberoku/ --strict         # types check
ruff check src/ tests/              # lint clean
```

## Architecture

Kuberoku has a strict three-layer architecture:

```
CLI (Click commands)  -->  SDK (business logic)  -->  K8s (protocol + client)
```

- **CLI never touches K8s directly.** It calls one SDK method, formats the result.
- **SDK never prints.** It returns dataclasses, raises typed exceptions.
- **K8s client returns `dict[str, Any]`.** No K8s model objects leak upward.

The full specification lives in [`docs/NORTHSTAR.txt`](docs/NORTHSTAR.txt). Read it before making architectural changes.

## Adding a new command

Follow the TDD workflow from NORTHSTAR.txt Section 12:

1. Write `tests/{feature}/test_{command}.py` first (SDK + CLI tests)
2. Implement the SDK method in `src/kuberoku/sdk/`
3. Wire the CLI command in `src/kuberoku/cli/`
4. Verify: tests pass, mypy passes, ruff passes

## Code style

- Python 3.11+. Use `from __future__ import annotations`.
- Frozen dataclasses for all data models.
- Typed exceptions — every error is a `KuberokuError` subclass.
- No shell=True. pathlib everywhere. Cross-platform from day 1.
- Keep it simple. Don't add abstractions for one-time operations.

## Reporting bugs

Open an issue at [github.com/amanjain/kuberoku/issues](https://github.com/amanjain/kuberoku/issues).

## License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
