# CLAUDE.md

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

## What this repo is

A collection of Kestra workflow flows (YAML) and helper scripts (Python) for homelab automation. The flows run inside Kestra and use this Git repository as the source for versioned logic.

**Core separation of concerns:**
- `*.yaml` — Kestra flows (orchestration, task sequencing, SSH commands)
- `*.py` — Python scripts called at runtime by Kestra (data processing, transformation)
- `.env` — Secrets and credentials, never committed (see `.env.example`)

## Testing the Python script locally

```bash
export OPTIONS_B64_JSON='["WyJkb2NrZXIxOzE5Mi4xNjguMTAwLjEwO21laW51c2VyOy9ob21lL21laW51c2VyL2RvY2tlci9uZXh0Y2xvdWQiXQ=="]'
python3 build_select_options.py
cat select_options.json
```

The script reads `OPTIONS_B64_JSON` (a JSON array of base64-encoded per-host results) and writes `select_options.json`.

## Architecture: how flows use Python scripts

The `docker_stack_inventory_scan` flow does **not** bundle the Python script inline. Instead, it clones this Git repo at runtime via `io.kestra.plugin.git.Clone` inside a `WorkingDirectory` task, then finds and runs `build_select_options.py` dynamically using `find`. This means:
- Changes to `.py` files take effect on the next flow run without redeploying the flow
- The flow variable `git_repo_url` and `git_branch` control which repo/branch is used

## Kestra secrets

Secrets are referenced in flows as `{{ secret('SECRET_NAME') }}`. For Kestra OSS, secrets must be stored base64-encoded in `.env` with the `SECRET_` prefix:

```bash
# Encode a value
echo -n "my-secret-value" | base64 -w 0

# Encode an SSH private key
base64 -w 0 ~/.ssh/id_ed25519
```

Then in `.env`:
```env
SECRET_SSH_PRIVATE_KEY=base64_encoded_value
```

## KV-Store data format

The `docker_stack_inventory_scan` flow writes to the KV key `docker_stack_select_options`. Each entry is a semicolon-delimited string:

```
hostname;ip-address;ssh-user;/path/to/compose-dir
```

The `docker_hosts` variable in the flow uses the same `hostname;ip-address` format.

## Flow namespaces

All flows use the `homelab.docker` namespace.

## Compose file discovery

The SSH scan uses `find -maxdepth 2` under `base_dir`. Compose files must be named exactly `compose.yml`, `compose.yaml`, `docker-compose.yml`, or `docker-compose.yaml` and located at most 2 levels deep to be detected.