Add completion spec: tcpdump

[warp-agent-staging]

Summary

Adds a completion spec for tcpdump, which Warp did not ship a signature for — typing tcpdump <tab> fell back to generic path completions. Resolves APP-3966 / warpdotdev/warp#9780.

• command-signatures/json/tcpdump.json — 64 options transcribed from the fish completion and cross-checked against tcpdump --help and the tcpdump(1) man page (4.99.4): capture selection (-i, -c, -s, -p, -Q, --immediate-mode), savefiles (-w, -r, -V, -C, -G, -W, -z), output control (-A/-x/-xx/-X/-XX, -e, -q, -v/-vv/-vvv, -n/-nn/-N/-f), timestamps (-t through -ttttt, -j, --time-stamp-precision, --micro, --nano), the -d/-dd/-ddd BPF dumps, and the listing flags (-D, -J, -L). Static enumerations come from the tool itself: the -T packet types were each probed against tcpdump -T <type> so only the ones it accepts are offered, and -Q/-j/--time-stamp-precision carry their documented value sets. Path-taking options use filepaths, and -w uses filepathsMayNotExist since it creates its savefile. The positional argument is the variadic pcap-filter expression, seeded with the common primitives and combinators (host, net, port, src, dst, tcp, and, not, …).
• command-signatures/src/generators/tcpdump.rs — two generators. interfaces (for -i/--interface) parses tcpdump --list-interfaces; user_name (for -Z) is common::users_generator(), already shared by pkill, killall and lsof.

Why -i does not reuse nmap's network_interfaces

nmap.rs has a network_interfaces generator that lists kernel netdevs from /sys/class/net or ifconfig. For tcpdump that list is strictly worse: tcpdump -D is the authority on what libpcap can actually capture on, and it additionally reports the pseudo-devices (any, nflog, nfqueue, dbus-system, …) plus a human description and link status per interface — none of which appear in a netdev listing. any in particular is one of the most commonly typed values for -i. The two generators answer different questions from different sources, so this is not the shared-generator case that add-command-spec asks to hoist into common.rs; -Z is, and it reuses the shared one.

Missing tools fail soft: the generator runs through single_command_and_ignore_stderr, so a host without tcpdump on PATH (or one where the capture devices are unreadable) yields no suggestions rather than error text, and nothing blocks or hangs.

Verification

./script/presubmit is green — npm run format:check, cargo fmt --check, cargo clippy --all-targets --all-features -D warnings, and cargo test (99 passed, 0 failed).

The #[cfg(test)] mod tests at the bottom of command-signatures/src/generators/tcpdump.rs adds 6 parser tests over real --list-interfaces output: index ordering is preserved, descriptions combine the parenthesized text with the link status, nested parentheses survive, a bare [none] status falls back to a generic label, the older name-only output shape works, and non-index lines and empty output produce nothing.

Exercised against the registry and a real tcpdump (4.99.4 / libpcap 1.10.4) with a scratch harness (not committed) that resolves the signature through signature_by_name the same way the client does:

signature name: tcpdump
option count: 64
-i argument types: [Generator(GeneratorName("interfaces"))]
-i generator command: tcpdump --list-interfaces 2>/dev/null
-i live suggestions:
  eth0 — "Up, Running, Connected"
  any — "Pseudo-device that captures on all interfaces (Up, Running)"
  lo — "Up, Running, Loopback"
  docker0 — "Up, Disconnected"
  bluetooth-monitor — "Bluetooth Linux Monitor (Wireless)"
  nflog — "Linux netfilter log (NFLOG) interface"
  dbus-system — "D-Bus system bus"
  …

That live run is what caught the nested-parenthesis bug now covered by a test — the first parser truncated nflog to Linux netfilter log (NFLOG.

Fail-soft was checked directly: with tcpdump removed from PATH, tcpdump --list-interfaces 2>/dev/null exits 127 immediately with empty stdout, so the generator returns no suggestions.

Visual proof — not produced here

.agents/skills/add-command-spec asks for a Warp dropdown screenshot per generator. This cloud agent runs in a headless container with no display, so a Warp GUI build could not be exercised; the same exception was accepted on the journalctl spec (#299). The ticket's Testing section calls registry/unit-level proof sufficient for a signature-data change, and that is what the evidence above is. Anyone wanting the dropdowns can reproduce them with .agents/skills/test-local-warp — point warp's warp-command-signatures dependency at this checkout, cargo run --features fast_dev, then tcpdump -i <tab> and tcpdump -Z <tab>.

Follow-up

warpdotdev/warp needs a warp-command-signatures git rev bump after this merges for the client to pick the signature up, the same way warp#14742 did for journalctl. No warp PR is opened here.

Originating thread: https://warpdev.slack.com/archives/C0BDQDW8V5E/p1785980450.964609

Conversation: https://staging.warp.dev/conversation/2c02c743-e687-4176-9a7d-77cab1072d4b
Run: https://oz.staging.warp.dev/runs/019fd4c2-8186-77cb-9fc2-607b21a615d4

This PR was generated with Oz.

[oz-for-oss]

@warp-agent-staging[bot]

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

Adds a tcpdump command signature covering documented options, pcap-filter positional suggestions, dynamic interface/user generators, and parser tests for representative tcpdump interface-list output.

Concerns

• No blocking concerns found in the changed lines.
• spec_context.md reports no approved or repository spec context, so there is no spec drift to flag.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz