# Contributing
Thanks for helping improve `kinjo`. This project is a Rust terminal UI for
browsing DNS-SD services and launching configured actions.
## Development Setup
Install the Rust toolchain from `rust-toolchain.toml`:
```sh
rustup show
```
On Debian or Ubuntu, install the native dependencies used by discovery and the
terminal UI stack:
```sh
sudo apt-get update
sudo apt-get install -y clang libavahi-client-dev libxcb-shape0-dev libxcb-xfixes0-dev xorg-dev
```
For real mDNS discovery, the Avahi daemon must be available on the system. For
UI and command development, you can run without Avahi by using fake discovery.
## Local Commands
Build the project:
```sh
cargo build --locked
```
Run tests:
```sh
cargo test --locked
```
Check formatting:
```sh
cargo fmt -- --check
```
Run lint checks:
```sh
cargo clippy --locked --all-targets -- -D warnings
```
Run the TUI with sample records:
```sh
cargo run -- --fake-discovery
```
Validate command configs:
```sh
cargo run -- list-commands
```
Validate command configs from a specific directory:
```sh
cargo run -- list-commands --config-dir ./actions
```
Build a Debian package if `cargo-deb` is installed:
```sh
cargo deb
```
## Fuzzing
The parser and the discovery entry model are exercised by [`cargo-fuzz`]
(libFuzzer) targets in `fuzz/`. They require a nightly toolchain; the helper
script installs `cargo-fuzz` if needed:
```sh
scripts/fuzz.sh # run every target for 60s each
scripts/fuzz.sh 300 # 5 minutes per target
scripts/fuzz.sh 120 parse_command # one target
```
Targets:
- `parse_command`: the command/action file parser (`MatcherBuilder::add_str`).
- `discovery_entry`: building, id-resolving, and grouping arbitrary entries.
- `decode_dns_sd`: the DNS-SD decimal-escape name decoder.
CI runs a short soak on every push/PR and a longer one on a weekly schedule
(`.github/workflows/fuzz.yml`); any crash inputs are uploaded as artifacts.
[`cargo-fuzz`]: https://github.com/rust-fuzz/cargo-fuzz
## Project Layout
- `src/discovery/`: the discovery layer — produces `Entry` values behind the
`Discovery` trait (mDNS and fake backends).
- `src/plumber/`: the rules engine — command-file parsing, matching, and
execution behind the `RuleEngine` trait.
- `src/ui/`: CLI parsing, config/keymap loading, app state, and rendering.
- `src/lib.rs` / `src/main.rs`: the library composition root and its thin binary.
- `fuzz/`: `cargo-fuzz` targets; `scripts/fuzz.sh`: the fuzz runner.
- `actions/`: bundled command examples installed as system command defaults in
the Debian package.
- `docs/actions.md`: custom command file reference.
- `docs/keybindings.md`: keybinding configuration reference.
- `.github/workflows/`: CI, fuzzing, and release packaging workflows.
## Contribution Guidelines
Keep changes focused and easy to review. If a change affects command files,
keybindings, or user-facing behavior, update the matching README or `docs/`
page in the same pull request.
Before opening a pull request, run:
```sh
cargo fmt -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
```
When reporting bugs, include:
- operating system and version
- how `kinjo` was installed
- command used to run it
- whether `--fake-discovery` works
- relevant command or keybinding config snippets
- the full error output