242 lines
11 KiB
Markdown
242 lines
11 KiB
Markdown
---
|
|
phase: 03-output-distribution
|
|
plan: 02
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified:
|
|
- doc/tcptop.1
|
|
- tcptop/Cargo.toml
|
|
autonomous: true
|
|
requirements: [OUTP-03, OUTP-04, OPS-03, OPS-04]
|
|
|
|
must_haves:
|
|
truths:
|
|
- "Man page exists at doc/tcptop.1 with NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, and EXIT STATUS sections"
|
|
- "Package metadata in Cargo.toml satisfies crates.io requirements (description, license, repository)"
|
|
- "cargo-deb and cargo-generate-rpm configuration includes the man page asset"
|
|
- "--help output includes the --log flag documentation"
|
|
artifacts:
|
|
- path: "doc/tcptop.1"
|
|
provides: "Hand-written troff man page per D-08"
|
|
contains: ".TH TCPTOP 1"
|
|
min_lines: 80
|
|
- path: "tcptop/Cargo.toml"
|
|
provides: "Package metadata + deb/rpm config"
|
|
contains: "[package.metadata.deb]"
|
|
key_links:
|
|
- from: "tcptop/Cargo.toml [package.metadata.deb] assets"
|
|
to: "doc/tcptop.1"
|
|
via: "asset reference installs man page to /usr/share/man/man1/"
|
|
pattern: "doc/tcptop.1.*usr/share/man"
|
|
---
|
|
|
|
<objective>
|
|
Man page, package metadata, and .deb/.rpm packaging configuration.
|
|
|
|
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.
|
|
</objective>
|
|
|
|
<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>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
|
|
<interfaces>
|
|
<!-- From tcptop/src/main.rs Cli struct (lines 16-46): -->
|
|
```rust
|
|
#[derive(Parser, Debug)]
|
|
#[command(name = "tcptop", about = "Real-time per-connection network monitor")]
|
|
struct Cli {
|
|
#[arg(long)] port: Option<u16>,
|
|
#[arg(long)] pid: Option<u32>,
|
|
#[arg(long)] process: Option<String>,
|
|
#[arg(long, short = 'i')] interface: Option<String>,
|
|
#[arg(long)] tcp: bool,
|
|
#[arg(long)] udp: bool,
|
|
#[arg(long, default_value = "1")] interval: u64,
|
|
// NOTE: Plan 01 will add: #[arg(long)] log: Option<String>,
|
|
}
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Create hand-written man page at doc/tcptop.1</name>
|
|
<files>doc/tcptop.1</files>
|
|
<read_first>
|
|
- 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)
|
|
</read_first>
|
|
<action>
|
|
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.
|
|
</action>
|
|
<verify>
|
|
<automated>test -f /Users/zrowitsch/local_src/tcptop/doc/tcptop.1 && grep -c "\.TH TCPTOP" /Users/zrowitsch/local_src/tcptop/doc/tcptop.1 && grep -c "EXAMPLES" /Users/zrowitsch/local_src/tcptop/doc/tcptop.1 && grep -c "\-\-log" /Users/zrowitsch/local_src/tcptop/doc/tcptop.1 && wc -l < /Users/zrowitsch/local_src/tcptop/doc/tcptop.1</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- doc/tcptop.1 exists at workspace root (not inside tcptop/)
|
|
- doc/tcptop.1 contains `.TH TCPTOP 1`
|
|
- doc/tcptop.1 contains `.SH NAME`
|
|
- doc/tcptop.1 contains `.SH SYNOPSIS`
|
|
- doc/tcptop.1 contains `.SH DESCRIPTION`
|
|
- doc/tcptop.1 contains `.SH OPTIONS`
|
|
- doc/tcptop.1 contains `.SH EXAMPLES`
|
|
- doc/tcptop.1 contains `.SH EXIT STATUS`
|
|
- doc/tcptop.1 contains `--log`
|
|
- doc/tcptop.1 contains `--port`
|
|
- doc/tcptop.1 contains `--pid`
|
|
- doc/tcptop.1 contains `--process`
|
|
- doc/tcptop.1 contains `--interval`
|
|
- doc/tcptop.1 contains `--tcp`
|
|
- doc/tcptop.1 contains `--udp`
|
|
- doc/tcptop.1 contains `--interface`
|
|
- doc/tcptop.1 contains `code 77` or `exit.*77`
|
|
- doc/tcptop.1 contains `sudo tcptop --port 443 --log capture.csv --interval 2`
|
|
- doc/tcptop.1 is at least 80 lines
|
|
</acceptance_criteria>
|
|
<done>Man page at doc/tcptop.1 with all sections, all flags documented, examples section with common use cases</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: Add package metadata and deb/rpm configuration to Cargo.toml</name>
|
|
<files>tcptop/Cargo.toml</files>
|
|
<read_first>
|
|
- tcptop/Cargo.toml (current state -- Plan 01 may have added deps)
|
|
- .planning/phases/03-output-distribution/03-RESEARCH.md (Pattern 4 and 5 for cargo-deb/rpm config)
|
|
- .planning/phases/03-output-distribution/03-CONTEXT.md (D-11 through D-15 decisions)
|
|
</read_first>
|
|
<action>
|
|
**Step 1: Add/update [package] metadata** for crates.io compatibility (OPS-03 per D-11):
|
|
Add these fields to the existing `[package]` section (after `edition = "2021"`):
|
|
```toml
|
|
description = "Real-time per-connection network monitor using eBPF"
|
|
license = "MIT"
|
|
repository = "https://github.com/zrowitsch/tcptop"
|
|
readme = "../README.md"
|
|
keywords = ["network", "monitoring", "ebpf", "tui", "tcp"]
|
|
categories = ["command-line-utilities", "network-programming"]
|
|
```
|
|
|
|
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).
|
|
</action>
|
|
<verify>
|
|
<automated>cd /Users/zrowitsch/local_src/tcptop && grep -c "metadata.deb" tcptop/Cargo.toml && grep -c "metadata.generate-rpm" tcptop/Cargo.toml && grep -c 'description = ' tcptop/Cargo.toml && grep -c 'license = ' tcptop/Cargo.toml</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- tcptop/Cargo.toml contains `description = "Real-time per-connection network monitor using eBPF"`
|
|
- tcptop/Cargo.toml contains `license = "MIT"`
|
|
- tcptop/Cargo.toml contains `repository = `
|
|
- tcptop/Cargo.toml contains `keywords = `
|
|
- tcptop/Cargo.toml contains `[package.metadata.deb]`
|
|
- tcptop/Cargo.toml contains `section = "net"`
|
|
- tcptop/Cargo.toml contains `usr/share/man/man1/tcptop.1` (in deb assets)
|
|
- tcptop/Cargo.toml contains `[package.metadata.generate-rpm]`
|
|
- tcptop/Cargo.toml contains `/usr/share/man/man1/tcptop.1` (in rpm assets)
|
|
- LICENSE file exists at workspace root
|
|
- `cargo build --package tcptop` still exits 0
|
|
</acceptance_criteria>
|
|
<done>Cargo.toml has crates.io metadata, cargo-deb config with man page asset, cargo-generate-rpm config with man page asset, LICENSE file exists</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
1. `grep -c "metadata.deb" tcptop/Cargo.toml` -- returns 1
|
|
2. `grep -c "metadata.generate-rpm" tcptop/Cargo.toml` -- returns 1
|
|
3. `test -f doc/tcptop.1` -- man page exists
|
|
4. `grep ".SH EXAMPLES" doc/tcptop.1` -- examples section present
|
|
5. `test -f LICENSE` -- license file exists
|
|
6. `cargo build --package tcptop` -- still compiles
|
|
</verification>
|
|
|
|
<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>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/03-output-distribution/03-02-SUMMARY.md`
|
|
</output>
|