diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..468e3f977 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,9 @@ + + +# Repository guidance + +- Nested `AGENTS.md` files hold area guidance. Before changing files under a directory, read each `AGENTS.md` between that directory and this one. +- `gen/` contains generated code only. Preserve its existing layout and do not add handwritten files, except `gen/README.md`, which documents the tree. +- Keep scripts that generate code into `gen/` in the root `scripts/` directory, not beside their output. Read [gen/README.md](gen/README.md) when regenerating those artifacts. +- New files need the SPDX header; `make lint-license` checks it. +- Postgres tests and e2e runs use disposable Docker containers on this machine; run and rerun them without asking. Load tests (`E2E_LOAD=true`) also start a persistent observability stack. diff --git a/cli/AGENTS.md b/cli/AGENTS.md index e7b7bdbef..0a3fe0d66 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -1,27 +1,14 @@ -# IBC CLI Development Guide for AI Agents +# IBC CLI -- Use `make lint-fix` to auto-format and lint code before finishing work. -- Don't add verbose comments. Be concise. -- `gen/` at the repository root holds generated code only, and its layout is fixed by an ADR — don't - move it or put anything handwritten there. Generator scripts belong in the root `scripts/` - directory, not beside their output. The one exception is `gen/README.md`, which documents the tree. -- Repository-wide black-box e2e lives in `../e2e`, with its harness in - `../e2e/internal/harness` as a separate Go module. The real relayer submits packets through - ICS26Router with attestation proofs signed by harness-managed attestors. Keep - `make -C e2e test` green when changing that transport contract. +- Interfaces listed in `.mockery.yaml` have generated mocks. After changing one, run + `make codegen-mocks` from `cli/`; CI does not regenerate them. +- `make -C e2e test` defaults to `E2E_MODE=fast`, which skips tests that require Besu without + failing; `E2E_MODE=complete` runs them. See + [Running the acceptance tests](../e2e/README.md#running-the-acceptance-tests). ## Documentation generated from this code -The reference pages under `docs/6-ibc-cli/` carry tables generated from this -directory. **If you change anything here, the documentation must be regenerated -before the pull request is opened**, and the regenerated pages belong in the -same pull request as the code. - -Follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). -It covers what to run, what the generator refuses and why, and what you may -write yourself. - -Never hand-edit between a `` marker and its `END`: the -next run overwrites it. +When changing commands or flags, configuration, cited behavior, or build inputs represented in the +CLI reference pages, follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). diff --git a/cli/CLAUDE.md b/cli/CLAUDE.md deleted file mode 120000 index 47dc3e3d8..000000000 --- a/cli/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/cli/CONTEXT.md b/cli/CONTEXT.md deleted file mode 100644 index abdad7b72..000000000 --- a/cli/CONTEXT.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# IBC CLI Environment - -The IBC CLI environment context describes the on-chain protocol topology and off-chain actors that a test declares and obtains as a ready Environment. - -## Language - -**Environment Spec**: -A declaration of the Chains, IBC Instances, IBC Connections, Attestors, and Relayers a test requires. It describes desired resources rather than their ready state. - -**Environment**: -The realized, ready set of resources declared by an Environment Spec. It is the lifecycle boundary through which a test accesses those resources. - -**Realization**: -The process by which an Environment Spec becomes an Environment, satisfying each declaration with a newly created or already-existing resource. - -**Chain**: -A blockchain network that hosts zero or more IBC Instances. - -**IBC Instance**: -An installation of the IBC protocol hosted on a Chain. An IBC Instance may be newly created or already exist. -_Avoid_: Deployment - -**IBC Client**: -One end of an IBC Connection, hosted by an IBC Instance and tracking the counterparty. Its counterparty client identifier points to the reciprocal IBC Client. - -**IBC Connection**: -The IBC protocol relationship between two IBC Instances, constituted by a reciprocal pair of IBC Clients. -_Avoid_: Route as a synonym for an IBC Connection - -**Attestor**: -An independent logical actor configured to serve a particular IBC Client. Its identity is independent of process or endpoint placement. - -**Relayer**: -An independent logical actor that relays protocol messages for one or more IBC Connections. Its identity is independent of process or endpoint placement, and multiple Relayers may serve the same IBC Connection. - -**Relayer Route**: -A directed configuration belonging to a Relayer when it needs to carry messages in one direction over an IBC Connection. It is not an independent Environment resource and does not replace the Connection. - -**Test Application**: -A test-only application deployed on a Chain to originate protocol traffic or expose observable state. It is explicit test setup, not an Environment resource. - -**Test Application Binding**: -A typed, non-owning test-side handle to the source and destination contracts used by one application on a directed synthetic route. It hides application ABI and RPC mechanics but does not own lifecycle, relayer state, or cross-resource orchestration. diff --git a/cli/cmd/ibc/AGENTS.md b/cli/cmd/ibc/AGENTS.md deleted file mode 100644 index 2589452dc..000000000 --- a/cli/cmd/ibc/AGENTS.md +++ /dev/null @@ -1,15 +0,0 @@ - - -# CLI development (located in cmd/ibc/) - -1. Use a single `init()` function in main.go to wire all subcommands. Never create init() per CLI file. -2. Commands implemented in this package should be variables and start with a `cmd*` prefix. The relayer - family is constructed by an importable command package because its transport types are shared with - the e2e harness. Examples for commands that remain here: - - `ibc attestor run` corresponds to `var cmdAttestorRun = ...`; - - `ibc config validate` corresponds to `var cmdConfigValidate = ...`; - - `ibc migrate up` corresponds to `var cmdMigrateUp = ...`; -3. Command implementations in this package should use `func commandName(cmd *cobra.Command, args []string) error`. - Importable command packages may pass command-owned option structs to injected handlers so flags stay - local to the command constructor. Be consistent within each command family. -4. Global CLI flags such as `--home` or `--config` belong in `config.FlagSet`. Add new global flags there, and don't use a separate variable if it can be global. diff --git a/cli/internal/config/AGENTS.md b/cli/internal/config/AGENTS.md deleted file mode 100644 index e4ca34acf..000000000 --- a/cli/internal/config/AGENTS.md +++ /dev/null @@ -1,15 +0,0 @@ - - -# Config package development rules - -1. Follow the following code blocks ordering (excluding test cases): - - exported interfaces - - unexported interfaces - - exported consts - - unexported consts - - exported types definitions. Nested types should have child definitions below parent - - `Default*()` `Declare*() functions - - exported methods, same order as as types - - unexported methods - - exported functions - - unexported functions \ No newline at end of file diff --git a/cli/internal/server/AGENTS.md b/cli/internal/server/AGENTS.md index 0aec9598d..74b63d16d 100644 --- a/cli/internal/server/AGENTS.md +++ b/cli/internal/server/AGENTS.md @@ -1,15 +1,6 @@ -# ConnectRPC Guide for AI Agents +# ConnectRPC adapters -Development flow: -1. Update raw protos in `proto/cli/*`. -2. Run `make codegen` (proto and mocks included). -3. Implement ConnectRPC handlers in `attestor_handler.go` or `relayer_handler.go`. -4. Add missing `AttestorService`/`RelayerService` methods if needed. - - Use idiomatic Go: `ctx` first. - - If a service method needs more than 3 args, use a DTO struct. -5. Keep `server/` as an adapter only: - - Convert ConnectRPC/proto types to service DTOs. - - Call the service interface. - - Map domain errors to `connect.Code*`. \ No newline at end of file +Keep this package as a transport adapter: convert ConnectRPC/proto types to service DTOs, call the +service interface, and map domain errors to `connect.Code*`. diff --git a/cli/internal/store/AGENTS.md b/cli/internal/store/AGENTS.md index 3b21ab516..386c541b0 100644 --- a/cli/internal/store/AGENTS.md +++ b/cli/internal/store/AGENTS.md @@ -1,54 +1,16 @@ -# Store guidelines for AI Agents +# Store `store.Store` is the single entrypoint for other packages that rely on DB. -## I. Creating migrations - -To create a migration, run the script from the project's root (./cli) - -```bash -go run scripts/migratenew.go add-packet-index -✔︎ Created /path/to/ibc/cli/internal/store/migrations/sqlite/002-add-packet-index.sql -✔︎ Created /path/to/ibc/cli/internal/store/migrations/postgres/002-add-packet-index.sql -``` - -The script prints absolute paths and assigns the next migration number automatically. - -Edit both `migrations/sqlite/*.sql` and `migrations/postgres/*.sql`; keep behavior identical, syntax dialect-specific. - -## II. Query creation, code generation - -For types & queries generation, `sqlc` tool is used. - -When creating `sqlc` SQL queries in `queries/*`, use "macros" to build unified files that -can be used both for sqlite and postgres. Example: - -```sql --- name: GetAuthorByName :one -SELECT * -FROM authors -WHERE lower(name) = sqlc.arg(name); --- "sqlc.arg" is a macro, "sqlc.narg" is similar, but makes a param nullable --- macros docs: https://docs.sqlc.dev/en/latest/reference/macros.html - --- >>> EXPANDS TO >>> - --- name: GetAuthorByName :one -SELECT * -FROM authors -WHERE lower(name) = ?; -``` - -- (re)generate bindings with `make codegen-sql`. -- Don't edit generated files in `repository/sqlite` or `repository/postgres`. - -### III. Unified repository layer - -After ensuring that the new migration is in place and the sqlc models and queries have been generated: - -- Add public persistence methods to `Repository` interface in `store.go`. Use idiomatic Go -- Implement every method in both `store_sqlite.go` and `store_postgres.go`. +- From `cli/`, create paired migrations with `go run scripts/migratenew.go `. Edit both + `migrations/sqlite/` and `migrations/postgres/`; keep their behavior equivalent while using each + dialect's syntax. +- For persistence or schema changes, test against both backends from `cli/`. PostgreSQL tests are + skipped unless `TEST_POSTGRES=true`; enabled tests require working Docker. Report any backend + you could not verify. +- `queries/` is shared by both dialects: write portable SQL with `sqlc.arg` and `sqlc.narg`, then + run `make codegen-sql` from `cli/`. +- Add public persistence methods to the `Repository` interface in `store.go`, not to `Store`. - Return domain structs from `store.go`, not generated sqlc row types. -- Implement basic input validation. if method arg is a struct, implement `.Validate() error` for it diff --git a/docs/6-ibc-cli/5-configuration.md b/docs/6-ibc-cli/5-configuration.md index 216ba6220..2adc9ebdf 100644 --- a/docs/6-ibc-cli/5-configuration.md +++ b/docs/6-ibc-cli/5-configuration.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/6-cli-commands.md b/docs/6-ibc-cli/6-cli-commands.md index c5c81da2f..482894e31 100644 --- a/docs/6-ibc-cli/6-cli-commands.md +++ b/docs/6-ibc-cli/6-cli-commands.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/7-api.md b/docs/6-ibc-cli/7-api.md index 50c491ed3..62d0db9f2 100644 --- a/docs/6-ibc-cli/7-api.md +++ b/docs/6-ibc-cli/7-api.md @@ -11,8 +11,8 @@ repository by docs/6-ibc-cli/tools/refgen.py. Do not edit inside them: the next run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request. +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md. --> diff --git a/docs/6-ibc-cli/tools/AGENTS.md b/docs/6-ibc-cli/tools/AGENTS.md index 29e470c2f..5ea1ca7c5 100644 --- a/docs/6-ibc-cli/tools/AGENTS.md +++ b/docs/6-ibc-cli/tools/AGENTS.md @@ -2,223 +2,67 @@ # Updating the reference pages -You are here because something under `cli/`, `proto/` or `gen/` changed. That -includes changes that rename no symbol at all: the `go` directive in a `go.mod` -is quoted as a prerequisite on two of these pages, and a dependency bump that -moves it is a documentation change. Do not skip this for a merge that only -touches build files. - -Three pages carry tables derived from that surface: - -| Page | Covers | Derived from | -|------|--------|--------------| -| [5-configuration.md](../5-configuration.md) | every key in `ibc.yml`, and the example config | the config structs in `cli/internal/config/`, and the yaml fixture that package's tests load | -| [6-cli-commands.md](../6-cli-commands.md) | every command and flag | the built binary's command tree, plus the wiring in `cli/cmd/ibc/` | -| [7-api.md](../7-api.md) | all three gRPC services (relayer, attestation, prover) | `proto/cli/*.proto` | - -Do this **before the pull request is opened**, in the same pull request as the -code. Run everything from the repository root. Three things must be on PATH: - -- `python3` — the generator uses only the standard library -- a **Go toolchain** — both the CLI and config pages build the binary and ask - it: a flag's default is only honest once assembled, and whether a config key - is required is asked by removing it and seeing whether the binary objects -- **`buf`** — the API page is generated from the descriptor set it compiles, - which is how this repository already builds its protos (`proto/buf.gen.yaml`). - Install it from https://buf.build/docs/installation - -None of the three is optional and none has a fallback. Without `buf` the API -page refuses rather than falling back to reading the `.proto` as text: a reader -that understands the schema less well than the compiler is how a page goes -quietly wrong when the schema grows a construct. - -[REFERENCE.md](REFERENCE.md) is the catalogue: every plan kind, the constants -you may edit, the probe fixtures behind the required column, and the two -formats below. This file is the procedure. - -[AUDIT.md](AUDIT.md) is separate work: checking whether the pages are *true* -rather than current. `--check` cannot answer that, so nothing below calls for -it — read it when that is the question you have. - -**The one rule: never edit between a `` and its `END`.** -Those blocks are rewritten from source, so an edit there disappears the next -time anyone regenerates — a change that looks like a fix and is not. Everything -else on those pages is yours: prose, headings, section order, examples. - -The example config is generated like everything else, so `--check` covers it — -but it is *copied* from the fixture the Go tests validate, so the way to change -it is to edit `cli/internal/config/testdata/sample.yml`, not the page. - -What the generator does not watch is the other pages in `docs/6-ibc-cli/` — the -overview, the tutorial, the two guides — which describe this same surface in -hand-written prose. **They carry no markers and no citations, so nothing in this -file will ever name them.** Step 7 is how you check those, and it is the only -thing that does. - -## 1. Find out what moved +Use this procedure when a change affects the CLI commands or flags, configuration surface, public +API under `proto/cli/`, code cited by the reference prose, or build inputs represented on the pages. +Internal changes that cannot affect those surfaces do not require regeneration. -```sh -python3 docs/6-ibc-cli/tools/refgen.py all --check # a diff per stale table -python3 docs/6-ibc-cli/tools/refgen.py all --plan # the work order, as JSON -``` - -Neither writes to a page. Both build the CLI and run every one of its commands -to read what they require, so they are not free and not inert. +The generated pages are: -`--plan` is the list to work from; **REFERENCE.md explains every kind it can -report, and the exit codes.** `--list-regions` prints the stale region ids -alone: the prose to re-read in step 4. +| Page | Derived from | +|------|--------------| +| [5-configuration.md](../5-configuration.md) | config structs and `cli/internal/config/testdata/sample.yml` | +| [6-cli-commands.md](../6-cli-commands.md) | the built command tree | +| [7-api.md](../7-api.md) | `proto/cli/*.proto` | -One kind is worth knowing before you see it. If you renamed or moved a Go -symbol, expect `stale_citation`: sentences in the prose cite the code they came -from, by path and symbol, and the check refuses when one no longer resolves. It -is not asking you to repoint the comment — it is asking whether your change made -that *sentence* wrong. REFERENCE.md has the format. +Run the commands below from the repository root. To change the generated example configuration, +edit `cli/internal/config/testdata/sample.yml`. -## 2. Resolve everything that needs a decision +## 1. Find what moved -Nothing is written while any of these remain, and each is named. **Read -REFERENCE.md before resolving anything** — it says what each kind means and -what fixes it. - -Three things govern every one of them: +```sh +python3 docs/6-ibc-cli/tools/refgen.py all --check +python3 docs/6-ibc-cli/tools/refgen.py all --plan +``` -- **Fix it at the source where you can.** A doc comment on the declaration - beats an entry in this directory, because the page then documents itself. -- **If the code does not say what something means, ask the person you are - working with.** A guess reads exactly like knowledge on the page. -- **Hand it back where the decision is not yours.** See step 6. +Read [REFERENCE.md](REFERENCE.md) for the reported kinds and exit codes. -**A page blocked by one item still has work you can do.** Resolve everything -else on it — descriptions, markers, sections, prose. Leaving them because the -page will not regenerate yet is how a whole page gets skipped over one line of -protobuf. +## 2. Resolve decisions -**`SKIP_FIELDS` and `CLI_EXCLUDED` delete a row, and nothing checks either for -obsolescence.** A key listed there is gone from the page for good, including -after it is renamed. Never reach for one to make a refusal go away: that -answers a refusal with the short-table-that-reads-complete this tool refuses -everywhere else. Use them only for something readers never write or run. +Fix missing or stale information at its source when possible. Do not guess facts the source does not +establish, use `SKIP_FIELDS` or `CLI_EXCLUDED` merely to silence a refusal, or bypass validation with +`REFGEN_NO_REQUIRED_FLAGS`, `REFGEN_NO_REQUIRED_KEYS`, or `REFGEN_NO_BUILD`. Report an unresolved +decision as a blocker using the hand-back format in [REFERENCE.md](REFERENCE.md). -## 3. Heal the tables +## 3. Regenerate ```sh python3 docs/6-ibc-cli/tools/refgen.py all ``` -Deterministic. Run it as often as you like. +## 4. Update prose -## 4. Correct the prose the code has overtaken +Read each changed region against its source and correct the surrounding prose. Also update the +hand-written pages in `docs/6-ibc-cli/` when the change affects behavior, examples, defaults, output, +or configuration that they describe; the generator cannot detect those inconsistencies. -Regenerating repairs a table and leaves the paragraph above it saying the old -thing. For every region that moved, fix the prose beside it — a key that gained -a default the text still calls required, an example that no longer works, a -sentence about a flag that is gone. **The code is the authority.** Match the -page you are writing into; do not restate a table in words. - -## 5. Check your work +## 5. Verify ```sh -python3 docs/6-ibc-cli/tools/refgen.py all --check # must be clean +python3 docs/6-ibc-cli/tools/refgen.py all --check ``` -Then read each region you touched against the code it came from, once. Running -twice and changing nothing proves the tool is stable, not that it is right. - -That is the whole check **unless this pull request changes `refgen.py`** — the suites below -test the generator, not the documentation. Budget about a minute for the unit -suite and **ten or more for the end-to-end one** — it builds the binary -repeatedly. If your tool has a timeout, run it in the background rather than -reading the overrun as a hang. +If `refgen.py` changed, also run: ```sh -# only if you changed refgen.py python3 docs/6-ibc-cli/tools/test-refgen.py python3 docs/6-ibc-cli/tools/test-refgen-e2e.py ``` -**The suites read the working tree**, so a refusal you are handing back makes -them fail until it is resolved. That part is expected. **Do not classify those -failures by eye** — a failure can name the refusal you were told to expect and -still be yours. REFERENCE.md gives the comparison that tells them apart. - -## 6. Report what you wrote - -```sh -python3 docs/6-ibc-cli/tools/refgen.py all --report -``` +When preparing a pull request, generate its documentation report with +`python3 docs/6-ibc-cli/tools/refgen.py all --report` and identify any prose written by hand or work +handed back. The documentation work is complete when affected prose has been reviewed and `--check` +is clean. If unresolved blockers remain, report the work as incomplete and list them using the +hand-back format in [REFERENCE.md](REFERENCE.md). -Put it in the pull request description, and **add one line under *Written by -hand, not derived* for everything you wrote yourself**, naming where it went. -That section is the point of the report: everything above it is as true as the -code, everything below it is only as true as you. - -If something is blocked, **say so; do not go quiet.** Add a *Handed back* -section in the format REFERENCE.md shows, one line per item. Unfinished and -reported is a fine outcome — unfinished and unmentioned is not, because whoever -reads the pull request cannot tell a page you left alone from a page that -needed nothing. - -## 7. Check the pages nothing generates - -The overview, the tutorial and the two standalone guides describe this surface -in prose, in pasteable examples, and in **captured terminal output**. Nothing -checks any of it. - -**Grepping for the names that changed is not enough, and this is the step -people get wrong.** Grep finds a rename. It does not find a behaviour change, -because the sentence that is now false often contains no changed identifier at -all. A real example: `render-config` began merging the deployment into the -whole config instead of printing three sections. Nothing was renamed, every -grep came back clean, and the overview went on describing the old behaviour. - -So work from the change, not from the text. For each thing the diff changes, -ask **what a reader would now see that these pages show**: - -| If the change... | look for | -|---|---| -| alters what a command prints or writes | every sentence describing that command's output, and every captured transcript of it | -| adds or removes a startup step, a migration, a log line | transcripts — a line that should now be *present* cannot be grepped for by its absence | -| changes a count, a total, a version, a duration | the same number quoted anywhere in prose or output | -| changes a default | sentences stating the old value, and examples that relied on it | -| adds a required config key | every pasteable config block, which now fails to load | - -Two shortcuts worth taking, with one trap. A `yaml` block that is a *whole* -config can be checked by running `ibc config validate` against it. Most blocks -on these pages are not: they are fragments a reader pastes *into* a config — a -bare `attestors:` list, a `signers:` entry — and `config validate` rejects each -as an incomplete config, complaining about the fragment rather than the keys. To -check a fragment, splice it into `cli/internal/config/testdata/sample.yml` and -validate that. Any block of captured output can be checked by running the -command that produced it, when it does not need a live chain. - -Say in the report which of these pages you read and what you changed. "I -grepped and found nothing" is not an answer to this step. - -**You are done when** `--check` is clean, or everything outstanding is listed -under *Handed back*. - -## What you must never do - -Write a heading with a placeholder under it. State a value the source does not -state. Edit inside a generated region. Delete a marker the generator still -fills — deleting the pair for something the source no longer has is -`orphaned_marker`, and is correct; the difference is whether the subject is -gone or merely unreadable. - -**Never set `REFGEN_NO_REQUIRED_FLAGS`, `REFGEN_NO_REQUIRED_KEYS` or -`REFGEN_NO_BUILD`.** Two switch off the checks that catch a whole page rendering -every flag or key as optional; the third builds the tables from a stale binary. -The refusals name them for someone who has confirmed the CLI genuinely has no -required flags. You are not that person: if you trip one, it is a hand-back. - -A refusal is not an obstacle to route around. The tool refuses because it would -otherwise publish something it could not verify, and a wrong page is worse than -a missing one: a reader trusts a default, a required flag, a key name, and acts -on it. - -## Not automated yet - -**Nothing runs `--check` for you.** These pages go stale silently, and this -procedure is the only thing that catches it. Run step 1 whenever a change -touches `cli/`, `proto/` or `gen/`. +Read [AUDIT.md](AUDIT.md) only when the task is to establish whether the generated pages are true, +rather than whether they are current. diff --git a/docs/6-ibc-cli/tools/REFERENCE.md b/docs/6-ibc-cli/tools/REFERENCE.md index 516ced111..5f316047d 100644 --- a/docs/6-ibc-cli/tools/REFERENCE.md +++ b/docs/6-ibc-cli/tools/REFERENCE.md @@ -7,7 +7,9 @@ holds the rules; this one holds the detail you look up while following it. ## Plan entries -`--plan` classifies every gap. Each entry carries the file and line to go to. +`--plan` classifies generation gaps. Each entry carries the file and line to go to. +`--report` summarizes the same plan. Neither checks notice placement or prose citations; +resolve errors from `--check` as well as plan entries. | Kind | Meaning | What you do | |------|---------|-------------| @@ -17,8 +19,6 @@ holds the rules; this one holds the detail you look up while following it. | `curation` | a choice the source cannot express | step 2 | | `unreadable_method` | a method's body could not be located, so any rule inside it is invisible | teach `_body_brace` the new signature shape | | `nested_proto_type` | a proto declares a message or enum inside another; only top-level types are documented | move it to the top level, or decide where nested types belong on the page | -| `moved_citation` | a cited symbol is now declared in exactly one other file; the message names it | repoint, after confirming the sentence | -| `stale_citation` | a sentence in the prose cites a symbol that is gone, or was never there | see below | `--list-regions` prints just the ids of the stale regions, one per line — the list of prose sections to re-read once the tables are rewritten. @@ -112,7 +112,7 @@ Sentences outside the generated tables carry the code they came from: The path is from the repository root and is **required**; the symbol is a declaration in that file, and `Type.Member` must be that type's method or that struct's field. `--check` verifies all of this and refuses with `stale_citation` -otherwise. +otherwise. Citation errors appear in `--check` output, not in `--plan` or `--report`. A path is the one derived fact left in a citation, so a move is answered rather than merely refused. When the cited path no longer resolves but the symbol is diff --git a/docs/6-ibc-cli/tools/refgen.py b/docs/6-ibc-cli/tools/refgen.py index bc321926b..1e1049302 100644 --- a/docs/6-ibc-cli/tools/refgen.py +++ b/docs/6-ibc-cli/tools/refgen.py @@ -7,9 +7,9 @@ flag, every config key, and every gRPC message and field. This script builds those tables from the code and writes them onto the pages, replacing only the text inside the GEN markers. Run `refgen.py all` to update them and -`refgen.py all --check` to fail when a page no longer matches the code. Run it -before opening a pull request that changes `cli/`, `proto/` or `gen/`; the -procedure is in AGENTS.md beside this file. +`refgen.py all --check` to fail when a page no longer matches the code. Use it +when changing the commands, configuration, API, or cited code represented by +the pages; the procedure is in AGENTS.md beside this file. A reference page is part prose and part table. The prose is written by a human and the tables are derived from code, so the tables can be regenerated whenever @@ -3230,8 +3230,8 @@ def inherited_by(path): run overwrites whatever is there, so a hand edit looks like a fix and is not. The prose around them is written by hand and is yours to change. -After changing cli/, proto/ or gen/, follow docs/6-ibc-cli/tools/AGENTS.md -before opening a pull request.""" +When changing commands, configuration, APIs, or cited behavior represented on +these pages, follow docs/6-ibc-cli/tools/AGENTS.md.""" def _notice(): diff --git a/e2e/AGENTS.md b/e2e/AGENTS.md index 399a521fb..e20dc3750 100644 --- a/e2e/AGENTS.md +++ b/e2e/AGENTS.md @@ -1,30 +1,18 @@ -# Repository E2E Tests Guide for AI Agents +# E2E tests -This module contains one root repository-level acceptance package: linear Go tests over the -`internal/harness` surface. Tests relay real IBC packets through the real relayer and -Solidity IBC stack (ICS26Router, ICS20Transfer, ICS27GMP) with attestation light clients and -managed attestors. +Read the relevant [README.md](README.md) section first: +- [Running the acceptance tests](README.md#running-the-acceptance-tests) before running tests +- [Writing a test](README.md#writing-a-test) before adding one, +- [Provider and topology matrix](README.md#provider-and-topology-matrix) before changing requirements or topology +- [Debugging](README.md#debugging) for environment or cleanup behavior. -- Run from the repository root: `make -C e2e test` uses fast mode; - `make -C e2e test E2E_MODE=complete|production` selects another mode, and - `E2E_FLAGS='-run TestTransfer_AutoRelay -count=1'` focuses a run. `-e2e.mode` in `E2E_FLAGS` - overrides `E2E_MODE`. `-e2e.load` overrides `E2E_LOAD`; `E2E_LOAD=true` also enables load tests. -- Tests declare portable EVM, controlled-mining, or node-lifecycle requirements. Fast mode may - skip an unresolved requirement; complete and production modes fail it. Fast and complete prefer - Anvil, while production prefers Besu where the requirements allow it. -- Tests start an `Environment` (which realizes Chains, the IBC contract stack, attestation light - clients, and attestors), hold the temporary IBC CLI driver and relayer explicitly, and assert through - route-bound application bindings (ICS20 transfers, ICS27 GMP calls, IFT transfers). This e2e-only setup - lives in `internal/e2etest`; transport-contract tests may call the concrete driver or Relayer directly. -- E2e may import the IBC CLI's public packages, such as its command transport types, generated RPC - clients, signer-keyfile package, and router access policy, but it must not import `cli/internal` - or invoke handlers in process. -- Each test gets a fresh environment. Managed Anvil uses one-second mixed mining; after mining is - paused and resumed it is interval-only, so transaction inclusion may take one second. -- `Environment` cleans up managed resources only. Attached chains remain caller-owned and expose no - harness mining or node-lifecycle controls. -- Run `make -C e2e generate-matrix` after changing requirements or topology, and - `make -C e2e check-matrix` to check the committed matrix. Both require Docker. -- After a hard crash: `make -C e2e clean-dry-run`, then `make -C e2e clean` from the repository root. +- Transport-contract tests may call the concrete driver or relayer directly; acceptance tests follow + the sequence in "Writing a test". +- Application-effect wait budgets derive from the resolved Chain's `environment.Timing`, never from a + literal tuned to instant Anvil. +- After changing requirements or topology, run `make -C e2e generate-matrix` and + `make -C e2e check-matrix`; `make -C e2e test` does not check the matrix. +- Preserve inner quotes in `E2E_FLAGS`, because Make expands it into a shell command: + `make -C e2e test E2E_FLAGS="-run '^(TestA|TestB)' -count=1"`. diff --git a/e2e/README.md b/e2e/README.md index ffda775fa..08db51c4e 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -87,7 +87,8 @@ func TestTransfer_AutoRelay(t *testing.T) { `e2etest.NewSigner` creates an independent identity; tests create one per role and pass them explicitly — `Deploy` takes the deployer and relayer signers, the app constructors take the sender (the signer that deployed the apps). Managed Chains fund them through their resolved funding capability; an attached Chain must fund the public addresses out of band before `Deploy`. Credentials are written only to protected temporary signer files referenced by alias in the temporary IBC CLI configuration. -Declare capabilities instead of naming a provider. For example, a controlled-mining test uses: +Declare capabilities, naming a provider only when the test depends on it. For example, a +controlled-mining test uses: ```go chains := e2etest.EVMChains(t, e2etest.EVMRequirements{ControlledMining: true}, diff --git a/e2e/internal/harness/AGENTS.md b/e2e/internal/harness/AGENTS.md index 6d4b6d9f9..fa3ee74ba 100644 --- a/e2e/internal/harness/AGENTS.md +++ b/e2e/internal/harness/AGENTS.md @@ -1,22 +1,6 @@ -# E2E Harness Development Guide for AI Agents +# E2E harness -This internal package tree of the e2e module is the black-box e2e harness. Its IBC CLI adapter observes the `ibc` binary only through -its public wire surface — CLI commands with JSON output, config YAML, and the status API — and -corroborates outcomes by reading chain state with its own clients. - -- **The wall:** the harness never imports `cli/internal/...` or the stub's guts. It may import - public IBC CLI packages, while behavior remains observable only through the executable and HTTP - surface. -- Wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned - to instant Anvil. Launch-side readiness uses `chain/evm/poll.Until`; test-application effect and - stability observation lives with the e2e-only bindings that interpret those effects. -- **Docker discipline.** Containers and networks carry the `ibc-cli-e2e=true` and - `ibc-cli-run=` labels, which cleanup finds them by; containers also carry the - `ibc-cli-e2e-` name prefix and pinned images. Anvil runs - with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt - instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. - StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. -- Lint with `make -C e2e lint` from the repository root; the shared root `.golangci.yml` covers the - harness and excludes exported-doc mandates for this internal test surface. +- Chain transaction wait budgets derive from the resolved Chain's `environment.Timing`, never from a literal tuned to instant Anvil. Provider and process startup and shutdown use separate lifecycle deadlines. +- **Docker discipline.** Containers and networks carry `chain/evm/container.Labels` so `e2e/scripts/clean.sh` can find them. Anvil runs with `--entrypoint anvil` (PID 1, so `docker stop`'s SIGTERM reaches it and shutdown is prompt instead of waiting out the kill grace). Don't reintroduce a shell-wrapped entrypoint. StopNode/StartNode fault injection is docker pause/unpause; chain state stays in memory. diff --git a/proto/AGENTS.md b/proto/AGENTS.md index 551f1420c..08c0deaaa 100644 --- a/proto/AGENTS.md +++ b/proto/AGENTS.md @@ -1,15 +1,9 @@ -## Documentation generated from this code +# CLI API -The reference pages under `docs/6-ibc-cli/` carry tables generated from this -directory. **If you change anything here, the documentation must be regenerated -before the pull request is opened**, and the regenerated pages belong in the -same pull request as the code. +When changing schemas under `proto/cli/` or their generation configuration, run +`make -C cli codegen-proto` from the repository root and include the updated bindings in `cli/api/v2/`. -Follow [`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md). -It covers what to run, what the generator refuses and why, and what you may -write yourself. - -Never hand-edit between a `` marker and its `END`: the -next run overwrites it. +When changing the public API under `proto/cli/`, follow +[`docs/6-ibc-cli/tools/AGENTS.md`](../docs/6-ibc-cli/tools/AGENTS.md).