docs(01-04): complete CLI integration plan — Phase 1 done
- Create 01-04-SUMMARY.md for Cobra CLI wiring plan - Update STATE.md: advance to ready_for_verification, record decisions, session - Update ROADMAP.md: Phase 1 all 4/4 plans complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 4.6
@@ -0,0 +1,131 @@
|
||||
---
|
||||
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*
|
||||
Reference in New Issue
Block a user