quick checkin to maintain progress

Author: Karthik777

AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+## Project Overview
+
+`fastops` is an nbdev-based Python library providing fluent builders for Docker, Compose, Caddy, Cloudflare DNS/tunnels, and Hetzner VPS provisioning — all composable from Python with no YAML/config files by hand.
+
+## Critical Rule: nbdev Workflow
+
+**Never edit `.py` files in `fastops/` directly.** They are autogenerated. Only edit notebooks in `nbs/` and run `uv run nbdev-prepare` to regenerate `fastops/*.py`, `_modidx.py`, and docs.
+
+Use hyphenated nbdev CLI commands (`nbdev-prepare`, `nbdev-export`, etc.), not underscore variants.
+
+Mapping:
+
+| Notebook | Module |
+|---|---|
+| `nbs/00_core.ipynb` | `fastops/core.py` — Dockerfile, Cli, Docker, Compose, app presets, env/secret helpers |
+| `nbs/01_cloudflare.ipynb` | `fastops/cloudflare.py` — CF wrapper, DNS records, tunnels |
+| `nbs/02_proxy.ipynb` | `fastops/proxy.py` — Caddyfile builder, caddy_svc, cloudflared_svc, crowdsec |
+| `nbs/05_vps.ipynb` | `fastops/vps.py` — cloud-init, Hetzner hcloud, SSH/rsync deploy |
+| `nbs/06_ship.ipynb` | `fastops/ship.py` — end-to-end: provision → build_stack → ship |
+
+## Build System
+
+- **Hatchling** (not setuptools). Build config lives in `pyproject.toml` under `[tool.hatch.build]`. Do NOT edit `MANIFEST.in` for build includes.
+- Package management: `uv add <pkg>` (never `pip install`). Run tools with `uv run`.
+
+## Architecture & Patterns
+
+### Immutable fluent builders (core pattern)
+`Dockerfile`, `Compose`, and `Caddyfile` all extend `fastcore.L` (an immutable list). Every method returns a **new instance** via `_add()` / `_new()` — never mutates. Example:
+```python
+df = Dockerfile().from_('python','3.12-slim').workdir('/app').cmd(['python','app.py'])
+```
+
+### `Cli` base + `__getattr__` dispatch
+`Cli` turns unknown attribute access into CLI subcommands: `Docker().image('prune', f=True)` → `docker image prune -f`. The `_mk_flags()` helper converts kwargs to CLI flags (single-char → `-k v`, multi-char → `--key=v`).
+
+### `@patch` from fastcore
+Methods added after class definition use `@patch` (e.g., `Dockerfile.build`, `Dockerfile.inst_uv`). Check for patched methods in the same notebook — they won't be in the class body.
+
+### Service composition
+`caddy_svc()`, `cloudflared_svc()`, `crowdsec()` return `dict` kwargs meant to be splatted into `Compose().svc('name', **result)`. The `ship._build_stack()` function orchestrates the full topology.
+
+## Code Style
+
+- **fastcore idioms**: `store_attr`, `patch`, `L`, `listify`, `joins`, `bind`, `filter_values`, `Path` (fastcore's, not pathlib's).
+- **Succinct variable names**, dense functions, fast.ai style. No verbose docstrings — one-line descriptions only.
+- Trailing-underscore convention for Python-keyword collisions: `from_()`, `as_=`, `exec_()`.
+
+## Key External Dependencies
+
+- `fastcore` — foundational utilities (`L`, `patch`, `bind`, `run`, `Path`)
+- `cloudflare` — official Cloudflare Python SDK (not requests-based)
+- `hcloud` — Hetzner Cloud Python client
+- `fastcloudinit` — cloud-init YAML generation
+- `pyyaml`, `python-dotenv`, `keyring` — config/secrets
+
+## Environment Variables
+
+| Variable | Used by |
+|---|---|
+| `CLOUDFLARE_API_TOKEN` | `cloudflare.py` — CF class |
+| `HCLOUD_TOKEN` | `vps.py` — Hetzner client |
+| `DOCKR_RUNTIME` | `core.py` — set to `podman` for podman support |
+| `FASTOPS_VPS_HOST` / `FASTOPS_VPS_NAME` | `ship.py` — stored by `provision()` |
+
+Config persists to `~/.config/fastops/.env` via `env_set()`/`env_get()`. Secrets use OS keychain via `keyring` with `secret_set()`/`secret_get()`.
+
+## Testing
+
+Tests live inline in the notebooks as cells. Run: `uv run nbdev-prepare` (exports + tests + docs). For pytest: `uv run pytest`. Include test cells when adding features to notebooks.