# 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).
