Skip to content

AGENTS.md

Latest commit

 

History

History
156 lines (115 loc) · 4.88 KB

AGENTS.md

File metadata and controls

156 lines (115 loc) · 4.88 KB
Raw

AGENTS.md — dsct

Project Overview

dsct is an LLM-friendly packet dissector CLI built on top of the packet-dissector family of crates.

  • Rust edition: 2024
  • MSRV: see rust-version in Cargo.toml
  • Primary purpose: machine-consumable packet analysis, not human-first terminal output
  • Dependency boundary: this repo consumes public crates from the packet-dissector family published on crates.io

Repository Layout

Cargo.toml                 # Standalone crate manifest
src/                       # Library + CLI implementation
tests/                     # Integration / CLI tests
benches/                   # Criterion benchmarks
docs/                      # Supporting documentation
.github/workflows/ci.yml   # CI source of truth

Build, Test, and Validation

CI is defined in .github/workflows/ci.yml. Run the same checks locally before committing:

cargo test --all-targets
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
taplo fmt --check

Useful development commands:

cargo build
cargo test <test_name>
cargo bench

If taplo is not installed:

cargo install taplo-cli

Development Rules

General Principles

  • Fix root causes, not symptoms.
  • Keep the CLI predictable for agents; avoid clever output shortcuts.
  • Prefer correctness and explicit errors over convenience.
  • Do not add compatibility shims unless they are clearly required.
  • Be direct in reviews: unclear behavior, weak validation, and schema drift are bugs.

TDD Required

All non-trivial changes should follow test-first development:

  1. Add or update tests first
  2. Confirm the test fails for the intended reason
  3. Implement the change
  4. Re-run tests until green
  5. Refactor without changing behavior

When changing existing behavior, update the tests first to reflect the new expected behavior.

CLI Design Constraints

Structured Output

  • Commands must produce structured JSON or JSONL output.
  • Output must remain stable and machine-consumable.
  • Do not add presentation-oriented formatting that makes parsing harder.

Structured Errors

  • Errors and warnings must be emitted as structured JSON to stderr.
  • Exit codes must stay aligned with the CLI contract documented in README.md.
  • Do not silently ignore malformed input or invalid arguments.

Streaming and Performance

  • Preserve streaming behavior for large capture files.
  • Avoid unnecessary intermediate Vec, HashMap, or String allocations in hot paths.
  • Keep fast paths intact when no filters or transformations are active.

Pipe-Friendly Behavior

  • Continue to support stdin input (-) where applicable.
  • Avoid changes that require seekable input unless explicitly scoped.

Dependency Boundary

This repo depends on packet-dissector, packet-dissector-core, packet-dissector-pcap, and packet-dissector-test-alloc published on crates.io.

Rules:

  • Treat those crates as external dependencies.
  • Prefer consuming their public APIs as-is rather than reshaping them here.
  • If a needed capability is missing, document the gap and add the corresponding API in packet-dissector rather than duplicating protocol logic in dsct.
  • Keep dsct focused on CLI, filtering, formatting, MCP, and TUI concerns.

Rust Coding Conventions

  • No unsafe — enforced by #![deny(unsafe_code)] in lib.rs. unsafe is permitted only in CaptureMap (src/tui/state.rs) and BgIndexer::spawn (src/tui/bg_indexer.rs) for memmap2 mmap operations, guarded by #[allow(unsafe_code)] with SAFETY comments.
  • No .unwrap() / .expect() in src/; use ? and contextual errors. const context unwrap() / panic! is permitted as it is evaluated at compile time and cannot cause runtime panics.
  • Public items should have doc comments.
  • Prefer small, explicit helpers over tangled control flow.
  • Follow Rust naming conventions:
    • snake_case for functions, modules, and variables
    • PascalCase for types and traits
    • SCREAMING_SNAKE_CASE for constants
  • No wildcard imports except use super::* in test modules.

Testing Guidance

  • Unit tests live alongside the code under src/.
  • Integration and CLI behavior tests live under tests/.
  • Benchmarks live under benches/ using Criterion.
  • Add tests for:
    • invalid arguments
    • malformed capture data
    • structured error output
    • filtering and schema behavior
    • protocol-specific display logic when behavior changes

Documentation Guidance

  • Keep README.md accurate for standalone repo usage.
  • When CLI flags, output shape, or behavior change, update the README in the same change.
  • Keep examples copy-pastable.

CI and Release Notes

  • .github/workflows/ci.yml is the source of truth for required checks.
  • If you add a new mandatory local check, add it to CI too.
  • Keep the repo independently buildable from the packet-dissector monorepo.