11 KiB
11 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-output-distribution | 02 | execute | 1 |
|
true |
|
|
Purpose: Makes tcptop installable via cargo install (OPS-03), provides man page documentation (OUTP-04), and configures .deb/.rpm package generation (OPS-04). Also ensures --help is complete (OUTP-03). Output: doc/tcptop.1 man page, updated tcptop/Cargo.toml with package metadata and deb/rpm config.
<execution_context> @/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/workflows/execute-plan.md @/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md ```rust #[derive(Parser, Debug)] #[command(name = "tcptop", about = "Real-time per-connection network monitor")] struct Cli { #[arg(long)] port: Option, #[arg(long)] pid: Option, #[arg(long)] process: Option, #[arg(long, short = 'i')] interface: Option, #[arg(long)] tcp: bool, #[arg(long)] udp: bool, #[arg(long, default_value = "1")] interval: u64, // NOTE: Plan 01 will add: #[arg(long)] log: Option, } ``` Task 1: Create hand-written man page at doc/tcptop.1 doc/tcptop.1 - tcptop/src/main.rs (Cli struct to ensure all flags are documented) - .planning/phases/03-output-distribution/03-RESEARCH.md (man page troff example) - .planning/phases/03-output-distribution/03-CONTEXT.md (D-08, D-09, D-10 decisions) Create `doc/` directory at workspace root (not inside tcptop/) and write `doc/tcptop.1` in troff format.The man page MUST include these sections (per D-08, D-09):
**Header:** `.TH TCPTOP 1 "2026-03-22" "tcptop 0.1.0" "User Commands"`
**NAME:** `tcptop \- real-time per-connection network monitor`
**SYNOPSIS:** `\fBtcptop\fR [\fIOPTIONS\fR]`
**DESCRIPTION:** Paragraph explaining what tcptop does -- live per-connection TCP/UDP stats using eBPF, sortable TUI, minimal overhead. Mention requires root privileges or CAP_BPF + CAP_PERFMON. Exits with code 77 if insufficient privileges (per CONTEXT.md specifics referencing Phase 1 D-11).
**OPTIONS:** One `.TP` block per CLI flag:
- `--port PORT` - Filter by port (matches source or destination)
- `--pid PID` - Filter by process ID
- `--process NAME` - Filter by process name (substring match)
- `-i, --interface IFACE` - Network interface to monitor
- `--tcp` - Show only TCP connections
- `--udp` - Show only UDP connections
- `--interval SECS` - Refresh interval in seconds (default: 1)
- `--log PATH` - Log connection data to CSV file. Runs in headless mode (no TUI). Overwrites existing file. Snapshots all connections at --interval cadence.
**INTERACTIVE KEYS:** q/Ctrl-C quit, Up/Down scroll, Left/Right sort column, / filter, Esc clear filter.
**EXAMPLES section (per D-09)** with these exact use cases:
- `sudo tcptop` -- Monitor all connections
- `sudo tcptop --tcp --port 443` -- Monitor only TCP connections to port 443
- `sudo tcptop --pid 1234` -- Monitor a specific process
- `sudo tcptop --port 443 --log capture.csv --interval 2` -- Log to CSV with 2-second intervals
- `sudo tcptop --tcp --interval 2` -- TCP only with custom refresh
**EXIT STATUS:** 0 = normal exit, 77 = insufficient privileges
**REQUIREMENTS:** Linux kernel 5.8+ with eBPF support. List the kernel probes attached: tcp_sendmsg, tcp_recvmsg, udp_sendmsg, udp_recvmsg, inet_sock_set_state.
**SEE ALSO:** top(1), ss(8), netstat(8), bpftool(8)
**AUTHORS:** tcptop contributors.
Use the exact troff format from RESEARCH.md Pattern: Man Page Format as the structural template.
Note: `repository` URL uses the user's GitHub username from the project context. If incorrect, executor should use the actual repo URL.
**Step 2: Add [package.metadata.deb] section** (per D-12, D-14):
```toml
[package.metadata.deb]
maintainer = "tcptop contributors"
section = "net"
priority = "optional"
depends = "$auto"
assets = [
["target/release/tcptop", "usr/bin/", "755"],
["../doc/tcptop.1", "usr/share/man/man1/tcptop.1", "644"],
]
```
No declared kernel version dependency (per D-15).
**Step 3: Add [package.metadata.generate-rpm] section** (per D-12, D-14):
```toml
[package.metadata.generate-rpm]
assets = [
{ source = "target/release/tcptop", dest = "/usr/bin/tcptop", mode = "755" },
{ source = "../doc/tcptop.1", dest = "/usr/share/man/man1/tcptop.1", mode = "644", doc = true },
]
```
**Step 4: Create LICENSE file** at workspace root if it does not exist:
Create a standard MIT license file so `cargo package` doesn't fail. Use year 2026, holder "tcptop contributors".
**Step 5: Verify --help includes --log** (OUTP-03 per D-07):
The --help is auto-generated by clap from the Cli struct. Plan 01 adds the `--log` field with doc comment `/// Log connection data to CSV file (headless mode, no TUI)`. No extra work needed for OUTP-03 beyond Plan 01's Cli change. Just verify it appears in `cargo run -- --help` output (on macOS this will show help before the "Linux only" exit).
<success_criteria>
- doc/tcptop.1 is a complete man page with all flags, examples section, and eBPF requirements
- tcptop/Cargo.toml has description, license, repository for cargo install / crates.io
- cargo-deb metadata references binary and man page with correct install paths
- cargo-generate-rpm metadata references binary and man page with correct install paths
- No declared kernel version dependency in packages (D-15)
- LICENSE file exists at workspace root </success_criteria>