|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build & Test Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +cargo build # Dev build |
| 9 | +cargo build --release # Release build (LTO, stripped) |
| 10 | +cargo test # Run all tests (unit + integration) |
| 11 | +cargo test <test_name> # Run a single test |
| 12 | +cargo clippy -- -D warnings # Lint (CI enforces zero warnings) |
| 13 | +cargo fmt --check # Check formatting (CI enforces) |
| 14 | +cargo fmt # Auto-format |
| 15 | +``` |
| 16 | + |
| 17 | +Integration tests use `ListenerGuard` (in `tests/helpers/mod.rs`) to bind real TCP ports, so tests exercise actual OS port scanning. |
| 18 | + |
| 19 | +## Architecture |
| 20 | + |
| 21 | +``` |
| 22 | +CLI parsing (main.rs, cli.rs) |
| 23 | + ↓ |
| 24 | +Command layer (commands/{kill,list,watch,free,wait,completions}.rs) |
| 25 | + ↓ |
| 26 | +PortScanner trait (scanner.rs) |
| 27 | + ↓ |
| 28 | +Platform implementations (platform/{macos,linux,windows}.rs) |
| 29 | + ↓ |
| 30 | +OS APIs (libproc on macOS, procfs on Linux) |
| 31 | +``` |
| 32 | + |
| 33 | +**Key patterns:** |
| 34 | +- `scanner::create_scanner()` is a factory that returns the platform-specific `Box<dyn PortScanner>` via conditional compilation |
| 35 | +- `process.rs` holds shared types: `ProcessInfo`, `KillSignal`, `KillResult`, `PortSpec`, `WaitCondition` |
| 36 | +- `output.rs` handles Table/JSON/Plain formatting — human messages go to stderr, structured data to stdout |
| 37 | +- `killer.rs` implements graceful shutdown: SIGTERM → poll → SIGKILL escalation |
| 38 | +- `cli.rs` defines clap structs; `main.rs` converts CLI enums to internal types (e.g., `convert_signal`, `convert_format`) |
| 39 | +- Long-running commands (`watch`, `wait`) use `signal_hook` with `Arc<AtomicBool>` for SIGINT/SIGTERM handling |
| 40 | +- The `tui.rs` module is a self-contained ratatui app with its own event loop, theming, and config persistence |
| 41 | + |
| 42 | +**Config:** stored at `~/.config/portzap/config.toml` (theme, confirmation dialog, animation duration). |
| 43 | + |
| 44 | +## NPM Distribution |
| 45 | + |
| 46 | +The `npm/` directory contains platform-specific packages (`@portzap/{platform}-{arch}`) and a wrapper package. The release workflow (`.github/workflows/release.yml`) builds binaries, copies them into npm package dirs, and publishes to both npm and crates.io on git tags matching `v*`. |
| 47 | + |
| 48 | +## CI |
| 49 | + |
| 50 | +Runs on push/PR: `cargo test`, `cargo clippy -- -D warnings`, `cargo fmt --check` on both macOS and Ubuntu. |
| 51 | + |
| 52 | +## MSRV |
| 53 | + |
| 54 | +Minimum supported Rust version: **1.74** (set in `Cargo.toml`). |
| 55 | + |
| 56 | +## Windows |
| 57 | + |
| 58 | +The Windows platform scanner (`platform/windows.rs`) and killer are stubs returning "not yet implemented" errors. macOS and Linux are fully implemented. |
0 commit comments