From 52b99b2da66db43003318c50b4780d3de9cd19d9 Mon Sep 17 00:00:00 2001 From: Ljubisa Gacevic Date: Wed, 27 May 2026 14:22:58 +0200 Subject: [PATCH] docs: add AGENTS.md guidance for AI coding assistants --- AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 68 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..80aa23df --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# AGENTS.md + +This file provides guidance to AI coding assistants (Claude Code, Cursor, and others) when working with code in this repository. + +## Project overview + +Beekeeper is the orchestration and integration-testing tool for [Ethereum Swarm Bee](https://github.com/ethersphere/bee) clusters. A single Go CLI (`cmd/beekeeper`, built on Cobra/Viper) covers several distinct jobs: + +- **Cluster lifecycle** — create/delete Bee clusters as Kubernetes resources (`create`, `delete`). +- **Integration checks** — run tests such as `pingpong`, `pushsync`, `retrieval` against a cluster (`check`). This is the primary purpose; checks are also what Bee's CI runs against PRs. +- **Operational tooling against already-running clusters** — `stamper` (postage batch create/topup/dilute/set), `node-funder`/`node-operator` (top up ETH/BZZ), `nuke` (DB reset + resync), `restart`. + +Beekeeper consumes Bee as a library (`github.com/ethersphere/bee/v2` in `go.mod`) for shared types (e.g. `swarm.Address`, postage) and talks to running nodes over Bee's HTTP API. + +## Essential commands + +```bash +make binary # build ./dist/beekeeper (CGO disabled, version stamped via -ldflags) +make test # unit tests: go test -v ./pkg/... +make lint # golangci-lint (pinned v2.10.1; auto-installs if missing) +``` + +Run a single test: `go test -run TestName ./pkg//...` (add `-race` to mirror CI). + +CI (`.github/workflows/go.yml`) runs `make vet`, `make check-whitespace`, golangci-lint, `make build`, and `make test`. PR titles are linted as Conventional Commits (`.github/workflows/pr-title.yml`). + +Requires Go 1.26. For a full local cluster (K3s/k3d + Geth), follow the **Local Development** quick start in `README.md`. + +## How a run is wired together + +The root command (`cmd/beekeeper/cmd/cmd.go`) builds shared dependencies in `PersistentPreRunE` before any subcommand runs: + +1. Loads global config (Viper: `$HOME/.beekeeper.yaml`, flags, env). +2. Loads the **config directory** (cluster/check definitions) from a local path *or* a Git repo. +3. Constructs the logger (optional Loki), the Kubernetes client (unless `--enable-k8s=false`), and the swap/blockchain client (`swap.NotSet{}` when no `geth-url`). + +Subcommands receive these via the `command` struct and pass them into runners/clients as constructor args — there is no global singleton. + +## Architecture + +The big-picture layers (each is one or more packages under `pkg/`): + +- **Config (`pkg/config/`)** — parses the YAML config dir (`clusters`, `node-groups`, `bee-configs`, `checks`, `simulations`), resolves `_inherit` inheritance, and exports into the `orchestration.*Options` types. Read from a local dir or a Git repo (`config-git-repo`). +- **Orchestration (`pkg/orchestration/`)** — backend-agnostic `Cluster` → `NodeGroup` → `Node` model. The `k8s/` backend translates it into Kubernetes resources; `notset/` is the no-op fallback when K8s is disabled. +- **Checks (`pkg/check/`)** — each check implements the `beekeeper.Action` interface and is registered by name in the `Checks` map in `pkg/config/check.go`; `pkg/check/runner.go` resolves names to implementations and runs them. +- **Clients** — `pkg/bee/` (+ `pkg/bee/api/`) is the HTTP client for a running Bee node; `pkg/k8s/` wraps the Kubernetes client (with fakes under `pkg/k8s/mocks/`); `pkg/swap/` is the Geth/blockchain client. +- **Operational packages** — `stamper`, `nuker`, `restart`, `funder` act on already-running nodes and discover them through `pkg/node/` (`NodeProvider`: Beekeeper cluster, namespace+label, or Helm), not the orchestration layer. + +## Deployment / operating modes + +Commands work against clusters provisioned in three different ways — know which one applies: + +1. **Beekeeper-managed Kubernetes** — Beekeeper creates the cluster from the config dir (`create bee-cluster`); checks/ops resolve nodes from the cluster definition. +2. **Static endpoints (no Kubernetes)** — set `enable-k8s: false` and point at static Bee node URLs in config (see `config/public-testnet-static.yaml`). Used for public-testnet checks. +3. **Externally-deployed clusters** — `stamper`/`nuke`/`restart`/`node-funder` target nodes by namespace/label or a Helm deployment (`--deployment-type=helm`), without a Beekeeper cluster definition. + +## Conventions + +- **Code style**: prefer clear, idiomatic Go that follows standard best practices and principles — small focused functions, explicit error wrapping with context, no premature abstraction. Keep changes minimal and consistent with the surrounding code. +- **Commits & PR titles**: Conventional Commits, lowercase type, no trailing period, `feat(scope): …` style (enforced by `commitlint.config.js`). Do not push commits; when a commit message is requested, use the subject line only — no body/description. +- **Tests**: prefer external test packages (`package foo_test`); use the `pkg/k8s/mocks` fakes instead of a live cluster. The race detector must pass. +- **Dependencies**: do not add or bump modules unless the task requires it (Dependabot handles routine bumps). +- **Linting**: `gofmt` + `gofumpt` formatting and the linters in `.golangci.yml` (errorlint, errname, nilerr, goconst, misspell, unconvert, copyloopvar) must pass. Note this repo does **not** use BSD copyright file headers — don't add them. + +## Pre-commit checklist + +Run before committing: `make build`, `make vet`, `make lint`, `make test` (use `make test-race` when touching concurrent code). Keep changes minimal and focused on the task. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md