pfs-tftp-codex/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/: Rust source for the pfs-tftp binary (entrypoint: src/main.rs).
• tests/: Integration tests (create as needed; Cargo auto-discovers tests/*.rs).
• rfc1350.txt: TFTP protocol reference (RFC 1350).
• Cargo.toml / Cargo.lock: Cargo manifest and locked dependency graph.

Keep modules cohesive: protocol parsing/encoding in a dedicated module (e.g., src/tftp.rs), I/O and CLI wiring in src/main.rs.

Build, Test, and Development Commands

• cargo build: Compile the project.
• cargo run: Build and run the local binary.
• cargo test: Run unit and integration tests.
• cargo +nightly fmt: Format code using rustfmt.toml.
• cargo clippy --all-targets --all-features -D warnings: Lint and fail on warnings.
• cargo check: Fast type-check without producing binaries.

Coding Style & Naming Conventions

• Use Rust defaults: 4-space indentation, no tabs, and let rustfmt decide layout.
• Follow naming conventions: snake_case (modules/functions), PascalCase (types/traits), SCREAMING_SNAKE_CASE (consts).
• Prefer small, testable functions and explicit error handling (Result<T, E> with meaningful error messages).

Testing Guidelines

• Unit tests: colocate under #[cfg(test)] mod tests { ... } in the relevant module.
• Integration tests: add tests/<area>.rs (e.g., tests/packet_roundtrip.rs).
• Target behaviors: packet encode/decode round-trips, error cases, and RFC compliance edge cases.

Commit & Pull Request Guidelines

• Git history is currently minimal; use a consistent convention going forward (recommended: Conventional Commits like feat: ..., fix: ..., test: ...).
• Keep commits focused and avoid mixing refactors with behavior changes.
• Commit messages should be clear and descriptive. They should always include enough context so that someone reading them in 5 years can still comprehend the intent, the why, how and everything.

Agent-Specific Notes

• Prefer small, reviewable diffs and update this file when commands or structure change.
• Avoid adding dependencies unless needed; justify new crates in the PR description.