How wp043/wp-mac-watch works
This is a Rust workspace that produces:
• a main interactive TUI binary (wp-mac-watch/): “Activity Monitor alternative” (process list + system metrics + process actions).
• a scriptable CLI binary (crates/cli/): snapshot (JSON), kill, kill-tree.
Architecture-wise, it’s a local-only, macOS-native observability + control tool (no server, no network services). The key design intent in the README is: a clean “core” data model that multiple frontends can consume (TUI now; potential menubar later).
• crate/module boundaries
• data flow (snapshots → diff → filtering/sorting → rendering)
• control flow (user input → action → kill/kill-tree)
• macOS integration points (process enumeration, launchd attribution, signals)
File structure → architectural decomposition
From the tree + README:
Workspace root
• Cargo.toml = workspace orchestrator (multiple crates)
• crates/ = reusable libraries + a CLI binary crate
• wp-mac-watch/ = main binary crate wiring everything together
Crates
• crates/core (wp_mac_watch_core): domain layer
Data model + diffing + search + filter/sort. This is the “clean core”.
• crates/mac (wp_mac_watch_mac): platform adapter / collectors
MacCollector (process + CPU/mem/swap), launchd attribution, kill helpers, “handle_action”.
• crates/tui (wp_mac_watch_tui): presentation + interaction loop
run_tui(rx, tx) suggests it consumes updates from a channel and emits commands/actions to another channel.
• crates/cli (wp_mac_watch_cli): non-interactive interface
clap-based command parsing; calls into mac/core to output JSON snapshot and perform actions.
Main binary
• wp-mac-watch/src/main.rs: the composition root
“wires sampler + TUI + actions” (per README). This is where concurrency/channels typically live.
Data/Domain (Core)
• ProcessSnapshot / ProcessRow
• SystemMetrics
• Attribution / AttributionKind
• SearchQuery / GroupMode / SortKey
• build_snapshot / diff_snapshots / filter_and_sort
Platform layer (macOS collectors + actions)
• MacCollector (collect processes + CPU/mem/swap)
• launchd plist index (attribution)
• kill_pid / kill_tree / handle_action
• OS APIs: process table, memory stats, signals (SIGKILL/SIGTERM), launchd plists
TUI frontend (ratatui)
• event loop run_tui(rx, tx)
• renders: header/system bar, process table, details pane, footer
• handles keybindings → emits “actions” (force kill, kill tree, sort, search, group toggle)
CLI frontend
• clap parsing
• snapshot outputs JSON
• kill / kill-tree invoke process control
Composition root + runtime wiring (main binary)
• sampling loop / scheduler (periodic collection)
• channels between sampler ↔ TUI (rx/tx)
• action handler loop (receives actions from UI; dispatches to mac kill functions)
• state store (current snapshot, diff, selected row, search/sort/group mode)
macOS → MacCollector
(process list, CPU%, memory, swap; launchd attribution)
MacCollector → core::build_snapshot
produces ProcessSnapshot + SystemMetrics
core::diff_snapshots
previous snapshot + current snapshot → SnapshotDiff
core::filter_and_sort
uses SearchQuery, SortKey, GroupMode → filtered list for display
→ TUI render
table + details pane + system bar
User input in TUI (keys /, s, Tab, f, t)
→ emits an Action/Command message (via tx)
Action handler (in main binary)
→ calls wp_mac_watch_mac::handle_action / kill_pid / kill_tree
CLI flow
• wp-mac-watch-cli snapshot:
CLI → MacCollector/core build_snapshot → JSON stdout
• kill / kill-tree:
CLI → mac kill_pid/kill_tree → macOS signals
Keep CLI separate from the TUI runtime wiring (it’s a different entrypoint).
• Clean-ish layering / Hexagonal tendency
• core = domain + pure logic (filter/sort/diff)
• mac = adapter to OS (impure, platform-specific)
• tui / cli = delivery mechanisms (UI + commands)
• wp-mac-watch = composition root
• Snapshot + Diff model
• periodic sampling → immutable-ish snapshots → diff for change representation
• Message passing / channels
• run_tui(rx, tx) strongly implies decoupled event loops (producer/consumer)
Small callouts like: “core has no OS/UI dependencies; reused by both CLI and TUI”.