The Problem

witr is a utility that answers the question “Why is this running?” by tracing the causal chain of processes, services, and port bindings from their origin to the present state. Existing diagnostics (ps, lsof, systemctl) expose state but leave the user to infer provenance; witr makes that provenance explicit, both in a static report and an interactive TUI dashboard.

What This Does

The repository consists of four semi‑independent projects (vendor, internal, pkg, cmd) that together provide process introspection across Linux, macOS, FreeBSD and Windows. Core capabilities are concentrated in a few files:

  • internal/app/app.go – defines the main execution flow (runApp, processTarget, processEnvTarget, printMultiMatch). It reaches 188 downstream functions and is the primary entry point for the CLI.
  • internal/proc/process_darwin.go – implements ReadProcess, getCwdAndBinaryPath, getEnvironment and detectLaunchdService; it runs external commands and reads/writes files on macOS.
  • internal/output/printer.go – provides NewPrinter, Printf, Print, Println and sanitisation helpers; called from 7 other modules.
  • internal/tui/data.go – refreshes the TUI view (refreshProcesses, refreshPorts, fetchTree, fetchProcessDetail).
  • internal/launchd/plist.go – macOS launchd service discovery (GetServiceLabel, findServiceByPID, FindPlistPath, ParsePlist).

Measured static‑analysis findings (38 total) highlight two high‑severity code‑quality concerns:

  • [HIGH/cognitive_load] Deep nesting – 16 files including internal/tui/update.go, internal/app/app.go, internal/launchd/plist.go have indentation depth up to 12; guard‑clause refactoring is recommended.
  • [HIGH/clarity] Duplicated code blocks – 228 repeated 6‑line fragments appear across 41 files (e.g., cmd/witr/main.go, main.go, internal/output/children.go, internal/output/tree.go); extracting shared helpers would DRY the logic.

Medium‑severity items include an oversized internal/tui/update.go (1002 lines) and high branching density in internal/proc/command.go, internal/proc/container.go, internal/proc/container_detect.go (25 branch points over ~60 lines).

How It Is Wired

Execution starts at cmd/witr/main.go:16 (main), which calls runApp (internal/app/app.go:165). From there the call graph fans out:

  • runApp → processTarget → ResolveSystemdService – spawns a subprocess via cmd.Run to query systemd.
  • runApp → processEnvTarget → ReadProcess – invokes cmd.Output and os.ReadFile to inspect the environment.

The most‑called self‑symbols are NewPrinter (9 callers), SanitizeTerminal (7), ansiString (7), Warnings (6), Print (4), centerHeader (4), RenderDockerFallback (4), and sendSignal (4). Dependencies are limited to Go modules (go.mod, go.sum) and vendored vendor/; no external runtime services are embedded.

How To Use It

Installation (from the project README)

# Unix (Linux, macOS, FreeBSD)
curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

<details> <summary>Script details</summary> The script detects OS/architecture, downloads the latest binary and man page, and installs to /usr/local/bin/witr. </details>

# Windows PowerShell
irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

Build from source (if desired):

go get ./...
go build -o witr ./cmd/witr

Running

witr                           # static report
witr --tui                     # interactive dashboard
witr --port 8080               # show processes bound to port 8080

Configuration is minimal; the tool reads the host’s process tree and system service databases directly. No environment variables or config files are required.

Real‑World Use

A DevOps engineer investigating an unexpected node process on a CI worker can run witr --tui. The dashboard lists the process, its parent PID, the launching launchd job (or systemd unit), and any open ports. By following the “origin” line, the engineer discovers the process was spawned by a com.docker.compose service definition, eliminating hours of manual ps/lsof correlation.

Code Health & Issues

The SDLC audit (static analysis + CI review) reports the following findings, ranked by severity and production reach:

  • HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows). Currently vmactions/freebsd-vm@v1, amannn/action-semantic-pull-request@v6, goreleaser/goreleaser-action@v7 use version tags that can shift, risking execution of unexpected code with repository secrets.
  • HIGH – Remove continue-on-error from steps that gate correctness (.github/workflows/pr-check.yml, line 23). A failing test suite currently reports a green check, masking breakage.
  • HIGH – Open a pull request instead of pushing directly to the default branch (.github/workflows/update-docs.yml). Automated commits land on the deploying branch without test coverage.
  • MEDIUM – Gate pull requests on a dependency vulnerability scan (no scan present in CI). A known‑vulnerable package could merge unnoticed.
  • LOW – Set timeout-minutes on workflow jobs (.github/workflows/e2e-tests.yml and three other pipelines declare no timeout). A wedged step could run to the six‑hour platform default, causing overlapping runs on a two‑hourly schedule.

The Bottom Line

witr delivers a focused, cross‑platform answer to “Why is this running?” with both a terse report and an interactive TUI, making causal chains visible without manual tool juggling. The codebase is functional but shows several high‑impact maintainability concerns—deep nesting, duplicated blocks, and an oversized file—that should be addressed before the tool is adopted in safety‑critical environments. Teams that need rapid, reliable process provenance on mixed OS fleets will find immediate value, provided the identified code‑health items are remediated.