# Instructions for AI Agents
## Overview
`bel7-cli` is a small library providing common CLI utilities:
colored console output, string truncation, table styling, clap extensions,
shell completion generation, and progress reporting.
## Build and Test
```bash
cargo build --all-features
cargo fmt --all
cargo nextest run --all-features
cargo clippy --all-features
```
## Repository Layout
* `src/lib.rs`: crate root, re-exports
* `src/output.rs`: colored console output helpers (print_success, print_error, etc.)
* `src/truncate.rs`: string truncation utilities
* `src/tables.rs`: table styling with tabled (requires the `tables` feature)
* `src/clap_ext.rs`: clap argument parsing extensions (requires the `clap` feature)
* `src/completions.rs`: shell completion generation (requires the `completions` feature)
* `src/progress.rs`: progress reporting utilities (requires the `progress` feature)
* `src/errors.rs`: exit code mapping (requires the `errors` feature)
## Key Dependencies
* `owo-colors`: terminal colors
* `tabled`: table formatting (optional)
* `terminal_size`: terminal width detection (optional, with `tables`)
* `clap`: CLI argument parsing (optional)
* `clap_complete` and `clap_complete_nushell`: shell completion generation (optional)
* `indicatif`: progress bars and spinners (optional)
* `sysexits`: exit code mapping (optional)
## Target Rust Version
* This library targets very recent stable Rust
## Rust Code Style
* Use top-level `use` statements (imports), e.g. `Display` or `fmt::Display` with a `use` statement, not `std::fmt::Display`
* Never use function-local `use` statements (imports)
* Add tests to the `tests/` directory, not inline with implementation
* At the end of each task, run `cargo fmt --all`
* At the end of each task, run `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
## Releases
### How to Roll (Produce) a New Release
Suppose the current development version in `Cargo.toml` is `0.N.0` and `CHANGELOG.md` has
a `## 0.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 `0.N.0` (just the version number, nothing else)
4. Tag the commit: `git tag v0.N.0`
5. Bump the dev version: back on `main`, set `Cargo.toml` version to `0.(N+1).0`
6. Run `cargo generate-lockfile`
7. Add a new `## 0.(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) and publishes a GitHub Release with the changelog section as release notes
### GitHub Actions
The release workflow uses [`michaelklishin/rust-build-package-release-action`](https://github.com/michaelklishin/rust-build-package-release-action) at `@v3`.
The Trusted Publishing setup requires a GitHub Actions environment named `release` and a
Trusted Publisher registered on crates.io (workflow filename `release.yml`, environment `release`).
For verifying YAML file syntax, use `yq`, Ruby or Python YAML modules (whichever is available).