# Instructions for AI Agents

## Overview

This is [`rabbitmqadmin v2`](https://www.rabbitmq.com/docs/management-cli), a CLI tool
that targets RabbitMQ's HTTP API.


## Build and Test

```bash
cargo build

cargo fmt --all

RUSTFLAGS="-D warnings" cargo nextest run --all-features
RUSTFLAGS="-D warnings" cargo clippy --all-features
```

To [filter](https://nexte.st/docs/filtersets/) tests with `cargo nextest`:

```bash
cargo nextest run -E "test(test_name)"
```

### Test Node Configuration

Test suites require a RabbitMQ node running on `localhost:15672` with `rabbitmq_management` plugin enabled.
See [CONTRIBUTING.md](./CONTRIBUTING.md) for step-by-step Docker setup instructions.


## Key Files

### Implementation

 * `src/main.rs`: the entry point
 * `src/cli/mod.rs`: `clap`-based CLI parser
 * `src/cli/dispatch.rs`: command dispatching
 * `src/commands.rs`: command implementations
 * `src/config.rs`: configuration file support
 * `src/errors.rs`: error types
 * `src/output.rs`: table styling, output formatting
 * `src/tables.rs`: custom tables for certain commands
 * `src/arg_helpers.rs`: argument parsing helpers
 * `src/columns.rs`: selects individual columns for output
 * `src/constants.rs`: default values and constants
 * `src/pre_flight.rs`: interactivity mode detection
 * `src/static_urls.rs`: documentation and resource URLs
 * `src/tanzu_cli.rs`: Tanzu RabbitMQ-specific CLI parser
 * `src/tanzu_commands.rs`: Tanzu RabbitMQ-specific commands dispatching

### Testing

 * `tests/integration/`: integration tests that drive the CLI binary and require a running RabbitMQ node
 * `tests/integration/test_helpers.rs`: shared test helpers (endpoints, API client, cleanup)
 * `tests/unit/`: pure logic tests with no external dependencies
 * `tests/proptests/`: property-based tests
 * `tests/fixtures/`: fixture files (e.g. definition files)
 * `bin/ci/*`: CI and RabbitMQ node setup scripts


## Key Dependencies

 * `clap`: CLI framework
 * [`rabbitmq_http_client`](https://crates.io/crates/rabbitmq_http_client): RabbitMQ [HTTP API](https://www.rabbitmq.com/docs/http-api-reference) client
 * `serde`, `serde_json`: JSON serialization
 * `tabled` formats results as tables
 * Via `rabbitmq_http_client`: `reqwest` with `rustls` and `aws_lc_rs`: HTTP client, TLS and HTTPS

## Target Rust Version

 * This tool targets very recent Rust (such as `1.94`)

## Rust Code Style

 * Use top-level `use` statements (imports) to fully-qualified names, e.g. `Display` or `fmt::Display` with a `use` statement, to `std::fmt::Display`
 * Never use function-local `use` statements (imports)
 * Add integration tests to `tests/integration/`, unit tests to `tests/unit/`, property-based tests to `tests/proptests/`
 * Never add tests in the implementation files
 * At the end of each task, run `cargo fmt --all`
 * At the end of each task, run `RUSTFLAGS="-D warnings" cargo clippy --all-features` and fix any warnings it might emit

## Comments

 * Only add very important comments, both in tests and in the implementation

## Git Instructions

 * Never add yourself to the list of commit co-authors
 * Never mention yourself in commit messages in any way (no "Generated by", no AI tool links, etc)

## Style Guide

 * Never add full stops to Markdown list items

## After Completing a Task

### Iterative Reviews

After completing a task, perform up to twenty iterative reviews of your changes.
In every iteration, look for meaningful improvements that were missed, for gaps in test coverage,
and for deviations from the instructions in this file.

If no meaningful improvements are found for three iterations in a row,
report it and stop iterating.

## Releases

### How to Roll (Produce) a New Release

Suppose the current development version in `Cargo.toml` is `2.N.0` and `CHANGELOG.md` has
a `## v2.N.0 (in development)` section at the top.

To produce a new release:

 1. Update the changelog: replace `(in development)` with today's date, e.g. `(Feb 20, 2026)`. Make sure all notable changes since the previous release are listed
 2. Refresh `Cargo.lock` so it matches `Cargo.toml`: `cargo update --workspace`. Then verify the crates.io publish step will pass: `cargo publish --dry-run --locked --allow-dirty`. If the dry-run fails with `cannot update the lock file ... because --locked was passed`, the lockfile is stale. Fix it before tagging
 3. Commit changelog and lockfile changes with the message `2.N.0` (just the version number, nothing else)
 4. Tag the commit: `git tag v2.N.0`
 5. Bump the dev version: back on `main`, set `Cargo.toml` version to `2.(N+1).0`
 6. Run `cargo generate-lockfile`
 7. Add a new `## v2.(N+1).0 (in development)` section to `CHANGELOG.md` with `No changes yet.` underneath
 8. Commit with the message `Bump dev version`
 9. Push: `git push && git push --tags`
 10. GitHub Actions workflow now publishes to crates.io using [Trusted Publishing](https://blog.rust-lang.org/2023/11/10/trusted-publishing.html), builds release artifacts, and publishes a GitHub Release

### GitHub Actions

The release workflow uses [`michaelklishin/rust-build-package-release-action`](https://github.com/michaelklishin/rust-build-package-release-action).

For verifying YAML file syntax, use `yq`, Ruby or Python YAML modules (whichever is available).

The `NEXT_RELEASE_VERSION` repository variable must match the version being released
for the workflow's validation step to pass.
