# AI Agent Instructions for fshc
This document provides guidance for AI coding assistants working on this codebase.
## Project Overview
**fshc** (File and Socket Handle Counter) is a small, cross-platform CLI tool that counts file and socket descriptors for a process.
It outputs JSON for machine consumption.
## Repository Structure
* `src/`:
- `main.rs`: entry point, CLI parsing with clap
- `outcome.rs`: error types and result handling
- `fds.rs`: platform-agnostic FD enumeration (Linux, macOS)
- `fds/windows.rs`: Windows-specific implementation
* `tests/`:
- `cli_tests.rs`: integration tests using `assert_cmd`
- `test_helpers.rs`: test helpers such as `run_succeeds`, `run_fails`
- `bin/target_process.rs`: helper binary to run integration tests against
* `.github/workflows/`: GitHub Actions workflows
* `.config/nextest.toml`: `cargo nextest` configuration
## Key Files
| `src/main.rs` | CLI entry point using clap derive macros |
| `src/outcome.rs` | Custom error type `FshcError` with exit code mapping |
| `src/fds.rs` | `FdList` struct with platform-specific implementations |
| `src/fds/windows.rs` | Windows FFI using `windows-sys` crate |
| `tests/cli_tests.rs` | Integration tests using `assert_cmd` |
| `tests/bin/target_process.rs` | Spawns a process with 1 file + 2 sockets for testing |
## Build and Test Commands
```shell
# Build
cargo build
# Build release
cargo build --release
# Run tests
cargo nextest run
# Lint
cargo clippy --all-targets
# Format
cargo fmt --all
```
## Target Rust Version
* This tool targets recent stable Rust
## Architecture Notes
### Platform Abstraction
The codebase uses conditional compilation (`#[cfg]`) to provide platform-specific implementations:
* Linux: `procfs` to read `/proc/<pid>/fd`
* macOS: `libproc` and the BSD API
* Windows: `windows-sys` and `NtQuerySystemInformation`
All platforms expose the same public interface via `FdList`:
* `FdList::list_by_type(pid)`: returns counts by type (file vs socket)
* `FdList::list_total(pid)`: returns only total count
## Dependencies
Avoid adding heavy dependencies. This tool should remain lightweight.
## Code Style
* Use `cargo fmt` before committing
* Ensure `cargo clippy` passes with no warnings
* Keep the codebase minimal: this is intentionally a small, focused tool
* Preserve platform abstraction patterns when adding features
* Use conditional compilation for platform-specific code
* Use top-level `use` statements (imports) instead of fully-qualified names
* Never use function-local `use` statements (imports)
* Add tests to the modules under `tests/`, never in the implementation files
## 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.