cloudy/AGENTS.md

# AGENTS.md

## Purpose
- This repository is primarily infrastructure-as-code for Docker Compose, Docker Swarm, Kubernetes, Helm, and Ansible.
- There is also a small Python Flask service in `webhook/` and a Streamlit app in `src/`.
- Prefer narrow, low-risk edits. Many files are deployment manifests where a small typo can break production behavior.

## Agent Priorities
- Preserve the existing structure and conventions of the file you are editing.
- Favor minimal diffs over broad refactors.
- Do not rotate secrets, change domains, or alter deployment targets unless the task explicitly requires it.
- Treat `archive/` as historical unless the task explicitly mentions it.
- When changing runtime configuration, update only the active path (`compose/`, `swarm/`, `cluster/`, `ansible/`, `webhook/`, `src/`) relevant to the request.

## Rule Files
- No `.cursor/rules/` directory was found.
- No `.cursorrules` file was found.
- No `.github/copilot-instructions.md` file was found.
- This file therefore acts as the main agent guidance for the repository.

## Repository Areas
- `makefile`: top-level operator commands for Compose and Swarm deploys.
- `compose.yml` + `compose/`: Docker Compose configuration assembled via `include:`.
- `swarm/`: Docker Swarm stacks, environment-driven labels, and Traefik config.
- `cluster/`: Kubernetes manifests and Helm charts.
- `ansible/`: playbooks and RKE2 automation.
- `webhook/`: Poetry-managed Flask app.
- `src/`: Streamlit app and Python requirements.
- `scripts/`: setup, build, and smoke-test scripts.

## Build Commands
- Full local compose stack: `make serve`
- Stop local compose stack: `make down`
- Validate merged compose config: `docker compose -f compose.yml config`
- Bring local compose stack up manually: `docker compose -f compose.yml up -d --build --pull always`
- Legacy CI-style compose build path: `./scripts/build.sh`
- Local Streamlit app only: `streamlit run src/app.py`
- Local webhook app only: `cd webhook && poetry run python http_server.py`
- Swarm core deploy: `make deploy-core`
- Swarm app deploy: `make deploy-apps`
- Swarm services deploy: `make deploy-services`
- Ansible RKE2 cluster bootstrap: `cd ansible/rke2 && ansible-playbook site.yaml -i inventory/hosts.ini --key-file ~/.ssh/id_rsa -K`

## Lint And Validation Commands
- There is no repo-wide lint target or CI workflow checked into the repository.
- There are no configured `ruff`, `black`, `flake8`, `mypy`, `yamllint`, `ansible-lint`, or `pytest` configs in the root.
- Use syntax and render validation that matches the area you changed.
- Compose validation: `docker compose -f compose.yml config`
- Swarm file validation: `docker stack deploy --compose-file ./swarm/<stack>.yml <stack> --dry-run` is not available in Docker Swarm, so use `docker compose config` patterns where possible and review label/env interpolation carefully.
- Helm chart render check: `helm template test-release cluster/coder-chart`
- Helm chart lint check: `helm lint cluster/coder-chart`
- Helm dependency check for `cluster/code-server`: `helm dependency update cluster/code-server`
- Kubernetes manifest spot check: `kubectl apply --dry-run=client -f <file>`
- Ansible syntax check: `ansible-playbook --syntax-check <playbook> -i <inventory>`
- Python webhook dependency install: `cd webhook && poetry install`
- Python webhook quick import/run check: `cd webhook && poetry run python http_server.py`

## Test Commands
- Main end-to-end smoke test script: `./scripts/test.sh`
- Legacy CI path: `./scripts/travis.sh`
- The smoke test expects a populated `.env`, reachable hosts, and a running local Traefik/Compose environment.
- It verifies redirects and dashboard auth using values from `.env`.
- Helm chart test hook exists for `cluster/coder-chart`; after install, run: `helm test <release-name>`
- There are example/test deployment files under `test/`, but no unified automated test runner is wired to them.
- There are currently no checked-in Python unit tests for `webhook/` or `src/`.

## Running A Single Test
- There is no first-class single-test command for the main smoke suite in `./scripts/test.sh`; it is a single shell script.
- To run one smoke assertion, copy the relevant `curl` command from `./scripts/test.sh` and execute it directly.
- For Helm, the narrowest useful check is a single chart render/lint:
- `helm lint cluster/coder-chart`
- `helm template test-release cluster/coder-chart`
- For a single Kubernetes manifest, use: `kubectl apply --dry-run=client -f path/to/file.yaml`
- For a single Ansible playbook, use: `ansible-playbook --syntax-check path/to/playbook.yml -i inventory`
- If Python tests are added later, the expected targeted form would be: `cd webhook && poetry run pytest path/to/test_file.py::test_name`
- Do not claim pytest support exists today unless you also add the test dependency and test files.

## Working Safely With Config
- Many YAML files interpolate env vars like `${DOMAINNAME}`, `${POSTGRES_PASSWORD}`, or `${VAR?Variable not set}`.
- Preserve existing variable names exactly; accidental renames will break deployments.
- Prefer existing anchors and aliases, such as `x-environment` blocks, over duplicating env declarations.
- Preserve quoting style when editing Traefik labels or shell-sensitive strings.
- Be careful with `$` escaping inside labels and regex replacements.
- Avoid changing published ports, hostnames, or Traefik router rules unless explicitly requested.

## Code Style: General
- Match the local style of the file you touch rather than imposing a new formatter.
- Keep YAML keys, Helm templates, and Ansible tasks visually aligned and easy to scan.
- Prefer small, direct changes over restructuring files.
- Keep comments only when they explain a non-obvious operational constraint.
- Reuse existing naming patterns like `api_server`, `postgres_db`, `streamlit-fin`, and `deploy-core`.
- Preserve file-specific indentation conventions: YAML uses spaces, Make uses tabs for recipe lines, shell scripts use the existing shell style.

## Imports
- In Python, keep imports at the top of the file.
- Prefer standard library imports first, then third-party imports.
- Avoid unused imports.
- Follow the existing concise import style unless you are already refactoring the file for readability.
- When touching `webhook/http_server.py` or `src/app.py`, it is acceptable to improve import ordering if part of a necessary edit.

## Formatting
- YAML: two-space indentation, no tab characters.
- Helm templates: preserve current whitespace trimming markers like `{{-` and `-}}`.
- Python: use four-space indentation even though some existing files are inconsistent.
- Shell: keep `set -e` or `set -ev` when present; do not remove safety flags casually.
- Markdown: keep bullets short and operational.
- Do not introduce large-scale formatting churn in files that are otherwise working.

## Types And Data Shapes
- Python code in this repo is lightly typed today; there is no mypy configuration.
- Add type hints when they clarify new or changed Python logic, but do not force a repo-wide typing conversion.
- For YAML, respect the existing scalar style and only quote when interpolation, special characters, or parser ambiguity require it.
- Keep environment values as strings unless the target format clearly expects booleans or integers.
- In Helm values and templates, preserve the expected shape of objects and lists; changing key structure is usually a breaking change.

## Naming Conventions
- Docker Compose services commonly use snake_case or hyphenated names already established in the file; follow the surrounding pattern.
- Ansible task names should be descriptive imperative phrases.
- Kubernetes resource names should stay lowercase and DNS-safe.
- Python function names should be `snake_case`.
- Python constants and environment variable names should be uppercase.
- Keep public-facing hostnames and router names consistent with nearby services.

## Error Handling
- Do not swallow errors silently in new Python code.
- Avoid bare `except:`; catch specific exceptions where practical.
- Return clear HTTP responses in Flask handlers.
- In shell scripts, prefer failing fast over ignoring command failures.
- In Ansible, use `register`, `when`, and `changed_when` intentionally; do not mark tasks changed without a reason.
- In deployment config, prefer explicit required vars like `${VAR?Variable not set}` for critical settings.

## Python-Specific Notes
- `webhook/http_server.py` currently uses minimal Flask code and would benefit from improved formatting and more explicit error handling when modified.
- `src/app.py` contains Streamlit logic with some inconsistent spacing and a bare `except:`; fix such issues only when your change touches that area.
- Preserve current runtime entrypoints unless the task explicitly changes startup behavior.

## Ansible-Specific Notes
- Prefer fully qualified module names such as `ansible.builtin.command` where the surrounding file already uses them.
- Keep playbooks idempotent where possible.
- Avoid unnecessary `shell` usage when `command`, `template`, `copy`, or dedicated modules work.
- Respect existing inventory and variable layout under `ansible/rke2/inventory/`.
- Be cautious with `become_user`, `changed_when`, and cluster bootstrap sequencing.

## Helm And Kubernetes Notes
- Render Helm templates locally before making broad chart changes.
- Preserve helper usage like `include`, `toYaml`, `nindent`, and existing label helpers.
- Avoid renaming values keys unless you also update every template consumer.
- Maintain probe, volume, and securityContext structure unless there is a concrete reason to change them.
- For plain manifests, keep apiVersion, kind, metadata, and spec ordering consistent with nearby files.

## Docker And Traefik Notes
- Traefik labels are heavily used and are sensitive to quoting and interpolation.
- Keep router, middleware, and service label names consistent across related files.
- Prefer extending shared env blocks and shared network definitions over one-off duplication.
- Be careful with `host-gateway`, mounted Docker sockets, and certificate storage paths.
- Do not commit real secrets into compose, swarm, or manifest files.

## When Unsure
- Validate the smallest affected surface first.
- Prefer commands that only render or syntax-check before commands that deploy.
- If a task spans multiple deployment systems, confirm which path is active before editing all of them.
- Document assumptions in the final response if the repo does not provide a definitive source of truth.