---
phase: 01-capture-and-classification
plan: 04
subsystem: cli
tags: [go, cobra, signal-handling, channels, pipeline, cli, stderr-output]

# Dependency graph
requires:
  - phase: 01-capture-and-classification
    provides: capture.StartCapture, capture.ListInterfaces, capture.OpenCapture from capture/capture.go (Plan 02)
  - phase: 01-capture-and-classification
    provides: classify.Classifier, classify.DefaultRules, classify.ClassifiedPacket types from classify/ (Plan 01)
  - phase: 01-capture-and-classification
    provides: aggregate.Aggregate, aggregate.PrintSummary, aggregate.PrintWindowLine, aggregate.AccumulateTotals from aggregate/ (Plan 03)

provides:
  - Cobra CLI binary (cmd/netsynth/main.go) wiring all three pipeline stages
  - -i / --interface flag for specifying capture interface
  - --list-interfaces flag that enumerates available interfaces and exits
  - --verbose flag enabling per-window protocol activity on stderr
  - Ctrl+C / SIGTERM clean shutdown with Aggregate done-channel propagation
  - Exit summary showing per-protocol packet counts and percentages

affects: [02-audio-synthesis]

# Tech tracking
tech-stack:
  added:
    - github.com/spf13/cobra v1.10.2 (Cobra CLI framework)
  patterns:
    - "Cobra RunE pattern: RunE returns error, Cobra handles exit code"
    - "signal.NotifyContext for clean SIGINT/SIGTERM shutdown — cancels context which closes packet channel which drains pipeline"
    - "Three-stage pipeline via goroutine + channels: capture -> classify -> aggregate"
    - "Atomic drop counter (droppedPtr) surfaced at exit if non-zero"

key-files:
  created:
    - cmd/netsynth/main.go
    - cmd/netsynth/main_test.go
  modified: []

key-decisions:
  - "Cobra RunE (not Run) used so errors propagate cleanly to stderr and exit code 1"
  - "signal.NotifyContext chosen over manual signal.Notify channel — cancels context automatically on SIGINT/SIGTERM, simpler shutdown chain"
  - "classified channel buffered at 1024 to absorb burst traffic between capture and aggregate goroutines"
  - "Permission error message lives in capture.StartCapture (Plan 02); main.go just returns it — single source of truth for platform-specific sudo hint"

patterns-established:
  - "Pattern: context cancellation is the single stop signal — capture reads ctx.Done(), packet channel close propagates to classify goroutine, which closes classified channel, which drains Aggregate"
  - "Pattern: pipeline stages communicate only via channels — no shared state beyond atomic drop counter"

requirements-completed: [CAPT-01, CAPT-02, CAPT-04, CLAS-01, CLAS-03, CLAS-04]

# Metrics
duration: ~15min
completed: 2026-03-25
---

# Phase 01 Plan 04: CLI Integration Summary

**Cobra CLI wiring all three pipeline stages (capture -> classify -> aggregate) with signal-handling, --verbose per-window stderr output, and Ctrl+C exit summary — completes Phase 1 runnable netsynth binary**

## Performance

- **Duration:** ~15 min
- **Started:** 2026-03-25T11:25:00Z
- **Completed:** 2026-03-25T11:40:00Z
- **Tasks:** 2 (1 code + 1 human-verify checkpoint)
- **Files modified:** 2

## Accomplishments

- cmd/netsynth/main.go wires capture, classify, and aggregate packages into a three-stage goroutine pipeline with buffered channels
- Cobra CLI exposes -i/--interface, --list-interfaces, and --verbose flags with correct validation and error messages
- signal.NotifyContext propagates SIGINT/SIGTERM through context cancellation to cleanly drain all pipeline stages before exit
- Per-window verbose output enabled via onSnapshot callback into aggregate.PrintWindowLine on stderr
- Exit summary printed via aggregate.PrintSummary after pipeline drains — shows per-protocol packet counts with percentages
- Binary builds with CGO_ENABLED=0 (Phase 1 has no CGo dependency; LAME is deferred to Phase 2+)
- Manual smoke test approved: live capture, verbose output, and Ctrl+C summary all verified on real interface

## Task Commits

Each task was committed atomically:

1. **Task 1: Wire Cobra CLI with capture-classify-aggregate pipeline and signal handling** - `1be56a5` (feat)
2. **Task 2: Smoke test live capture on real interface** - checkpoint:human-verify (approved by user, no code commit)

**Plan metadata:** TBD (docs: complete plan)

## Files Created/Modified

- `cmd/netsynth/main.go` - Cobra root command, run() pipeline assembly, runListInterfaces(), signal handling
- `cmd/netsynth/main_test.go` - Tests: TestListInterfacesFlag, TestMissingInterfaceFlag, TestHelpOutput

## Decisions Made

- Cobra RunE (not Run) pattern used so error propagates cleanly — Cobra prints to stderr and sets exit code 1
- signal.NotifyContext preferred over manual signal channel — context cancellation is already the pipeline stop signal, so one mechanism handles both
- classified channel buffered at 1024 to absorb classify goroutine burst processing without blocking packet capture
- Permission error message owned by capture.StartCapture, not main.go — keeps platform-specific hint in one place

## Deviations from Plan

None — plan executed exactly as written. Task 1 implementation matched the plan's code template precisely. All acceptance criteria passed.

## Issues Encountered

None — build succeeded on first attempt, tests passed, smoke test approved.

## User Setup Required

**Live capture requires elevated privileges.** Two options:
1. Run as root: `sudo ./netsynth -i eth0`
2. Grant capability: `sudo setcap cap_net_raw+eip ./netsynth` then run without sudo

## Next Phase Readiness

- Phase 1 complete: capture, classify, aggregate, and CLI all wired and verified
- Phase 2 (audio synthesis) receives WindowSnapshot channel from aggregate.Aggregate — the Phase 2 synthesizer plugs in between the Aggregate output and the final exit summary
- No blockers for Phase 2; frequency mapping and oscillator math are the next open design decisions

## Self-Check: PASSED

- `cmd/netsynth/main.go` exists
- `cmd/netsynth/main_test.go` exists
- `01-04-SUMMARY.md` exists
- Commit `1be56a5` (feat(01-04): wire Cobra CLI) confirmed in git history

---
*Phase: 01-capture-and-classification*
*Completed: 2026-03-25*