feat: interactive TUI with session persistence and UX polish

Made-with: Cursor

Author: TMHSDigital

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Interactive terminal UI (`-tui` flag) built with Bubble Tea — form-based config screen and live-scrolling results view; no CLI arguments required to launch
+- `make tui` Makefile target for one-command TUI launch
+- `internal/scan` package: extracted scan engine (`scan.Run`) with typed `Event` channel, usable by both CLI and TUI
+- TUI session persistence: last-used form values written to `~/.config/subenum/last.json` and restored on next launch or after pressing `r` (new scan)
+
+### Changed
+- CLI scan loop in `main.go` now delegates to `scan.Run()` instead of containing the worker pool inline
+- External dependencies added: `github.com/charmbracelet/bubbletea` and `github.com/charmbracelet/bubbles` (TUI only; CLI path has zero external dependencies)
+- TUI form field order: Simulate toggle promoted to field 3 (was field 8); Hit Rate row is hidden when Simulate is OFF
+- TUI now shows a blinking cursor inside the active text input
+- Pressing `r` on the scan results screen returns to the form with last-used values pre-filled (was reset to defaults)
+
 ## [0.4.0] - 2026-03-14
 
 ### Added

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test clean lint run docker-build docker-run wordlist wordlist-gen simulate simulate-verbose
+.PHONY: build test clean lint run tui docker-build docker-run wordlist wordlist-gen simulate simulate-verbose
 
 # Default Go parameters
 GOCMD=go
@@ -54,6 +54,10 @@ wordlist: wordlist-gen
 	@echo "Generated wordlist: $(WL_OUTPUT)"
 	@echo "Use it with: make WORDLIST=$(WL_OUTPUT) DOMAIN=$(WL_DOMAIN) run-verbose"
 
+# Launch the interactive TUI (one-click, no arguments needed)
+tui: build
+	./$(BINARY_NAME) -tui
+
 # Run with default parameters
 run: build
 	./$(BINARY_NAME) -w $(WORDLIST) -t $(CONCURRENCY) -timeout $(TIMEOUT) -dns-server $(DNS_SERVER) $(DOMAIN)
@@ -98,6 +102,7 @@ help:
 	@echo "  make test-short       - Run short tests"
 	@echo "  make clean            - Clean build artifacts"
 	@echo "  make lint             - Run linter"
+	@echo "  make tui              - Launch the interactive terminal UI (no arguments needed)"
 	@echo ""
 	@echo "  LIVE MODE (performs real DNS queries):"
 	@echo "  make run              - Build and run with default parameters"

README.md

@@ -14,7 +14,7 @@
 [![Release](https://img.shields.io/github/v/release/TMHSDigital/subenum?style=for-the-badge)](https://github.com/TMHSDigital/subenum/releases)
 [![Go Report Card](https://goreportcard.com/badge/github.com/TMHSDigital/subenum?style=for-the-badge&v=0.4.0)](https://goreportcard.com/report/github.com/TMHSDigital/subenum)
 
-`Concurrent Workers` · `Context-Aware Cancellation` · `Retry with Backoff` · `Wildcard Detection` · `Simulation Mode` · `Zero Dependencies`
+`Concurrent Workers` · `Context-Aware Cancellation` · `Retry with Backoff` · `Wildcard Detection` · `Simulation Mode` · `Interactive TUI`
 
 [Quick Start](#installation) | [Documentation](./docs) | [Architecture](#system-architecture) | [Changelog](./CHANGELOG.md)
 
@@ -39,6 +39,7 @@
 | Simulation Mode | Generate synthetic DNS results at a configurable hit rate without network I/O. |
 | Output Pipeline | Stream resolved domains to stdout (pipe-friendly); progress and diagnostics go to stderr. |
 | Progress Reporting | Live terminal progress with atomic counters, updated on a 2-second ticker. |
+| Interactive TUI | Form-based config screen and live-scrolling results view via `-tui` flag (Bubble Tea). No arguments required. |
 
 <br>
 
@@ -141,6 +142,7 @@ make help         # list all targets
 | `-progress` | `true` | Live progress line on stderr (disable with `-progress=false`) |
 | `-simulate` | `false` | Simulation mode: no real DNS queries |
 | `-hit-rate <n>` | `15` | Simulated resolution rate, percent (1-100) |
+| `-tui` | `false` | Launch the interactive Terminal UI (no other flags required) |
 | `-version` | -- | Print version and exit |
 | `-retries <n>` | -- | **Deprecated:** alias for `-attempts`, prints a warning |
 
@@ -194,6 +196,25 @@ subenum -w <wordlist> [flags] <domain>
 
 **Graceful shutdown:** press `Ctrl+C` at any time. In-flight queries drain, partial results are flushed.
 
+**Interactive TUI (no arguments):**
+
+```bash
+./subenum -tui
+# or
+make tui
+```
+
+Fill in the form, press `ctrl+r` to scan. Last-used values are saved to `~/.config/subenum/last.json` and restored on next launch.
+
+| Key | Action |
+| :--- | :--- |
+| `tab` / `shift+tab` / `↑↓` | Navigate fields |
+| `space` | Toggle Simulate / Force |
+| `ctrl+r` | Start scan |
+| `ctrl+c` | Abort scan (in scan view) / quit (in form) |
+| `r` | New scan — returns to form with last values pre-filled |
+| `q` | Quit after scan completes |
+
 <br>
 
 ---

docs/ARCHITECTURE.md

@@ -23,11 +23,16 @@ This architecture is designed to be efficient by performing multiple DNS lookups
 ### Package Structure
 
 ```
-main.go                     — CLI entry point (flag parsing, wiring, worker loop)
-internal/dns/resolver.go    — ResolveDomain, ResolveDomainWithRetry, CheckWildcard
-internal/dns/simulate.go    — SimulateResolution
-internal/output/writer.go   — Thread-safe Writer (results→stdout, diagnostics→stderr)
-internal/wordlist/reader.go — LoadWordlist (dedup + sanitize)
+main.go                        — CLI entry point (flag parsing, wiring, -tui dispatch)
+internal/scan/runner.go        — Scan engine: Config, Event types, Run(ctx, cfg, events)
+internal/dns/resolver.go       — ResolveDomain, ResolveDomainWithRetry, CheckWildcard
+internal/dns/simulate.go       — SimulateResolution
+internal/output/writer.go      — Thread-safe Writer (results→stdout, diagnostics→stderr)
+internal/wordlist/reader.go    — LoadWordlist (dedup + sanitize)
+internal/tui/model.go          — Root Bubble Tea model (form → scan state machine)
+internal/tui/form.go           — Config form screen (textinput fields + toggles)
+internal/tui/scan_view.go      — Live results screen (viewport + progress bar)
+internal/tui/config.go         — Session persistence (load/save ~/.config/subenum/last.json)
 ```
 
 ## 2. Key Components / Modules
@@ -75,20 +80,18 @@ internal/wordlist/reader.go — LoadWordlist (dedup + sanitize)
     *   The function returns `true` if `LookupHost` returns no error (i.e., the domain resolved), and `false` otherwise.
 *   **Interactions**: Workers call `dns.ResolveDomainWithRetry`, which delegates to `dns.ResolveDomain` with retry logic. It takes a fully qualified domain name, timeout duration, DNS server address, verbose flag, and retry count as input. It outputs a boolean indicating whether the domain resolved successfully. The result is used to decide if the domain should be printed to the console and/or written to the output file.
 
-### 2.4. Concurrency Management (Worker Pool)
+### 2.4. Concurrency Management (`internal/scan`)
 
 *   **Purpose**: To efficiently perform DNS lookups for a large number of potential subdomains, `subenum` employs a worker pool pattern. This allows multiple DNS queries to be in flight concurrently, significantly speeding up the enumeration process compared to sequential lookups.
-*   **Implementation**:
-    *   **`subdomains := make(chan string)`**: A buffered channel (though currently unbuffered in `main.go`, could be buffered for performance tuning) is created to act as a work queue. Subdomain prefixes read from the wordlist are sent to this channel.
-    *   **`var wg sync.WaitGroup`**: A `sync.WaitGroup` is used to wait for all worker goroutines to complete their tasks before the main function exits.
-    *   **Worker Goroutines Loop (`for i := 0; i < *concurrency; i++`)**: A loop launches a number of goroutines specified by the `-t` (concurrency) flag. Each goroutine acts as a worker.
-        *   `wg.Add(1)`: Increments the `WaitGroup` counter for each worker started.
-        *   `go func() { ... }()`: Each worker runs in its own goroutine.
-        *   `defer wg.Done()`: Decrements the `WaitGroup` counter when the goroutine exits.
-        *   `for subdomainPrefix := range subdomains { ... }`: Each worker continuously reads subdomain prefixes from the `subdomains` channel until the channel is closed. For each prefix, it constructs the full domain and calls `dns.ResolveDomainWithRetry()`.
-    *   **Closing the Channel (`close(subdomains)`)**: After all subdomain prefixes from the wordlist have been sent to the `subdomains` channel, the channel is closed. This signals to the worker goroutines that no more work will be added.
-    *   **Waiting for Completion (`wg.Wait()`)**: The main goroutine blocks until all worker goroutines have called `wg.Done()`, ensuring all lookups are finished.
-*   **Interactions**: This component orchestrates the parallel execution of DNS lookups. It receives subdomain prefixes from the Wordlist Processing component (via the `subdomains` channel) and utilizes the DNS Resolution Engine within each worker goroutine. The number of workers is controlled by the Argument Parsing component.
+*   **Implementation**: The worker pool logic lives in `internal/scan/runner.go` as `scan.Run(ctx, cfg, events)`. Both the CLI (`run()` in `main.go`) and the TUI (`internal/tui`) call this function.
+    *   **`scan.Config`**: A struct carrying all scan parameters (domain, entries slice, concurrency, timeout, DNS server, simulate flag, etc.).
+    *   **`scan.Event` / `scan.EventKind`**: Typed events emitted on a `chan<- scan.Event` — `EventResult`, `EventProgress`, `EventWildcard`, `EventError`, `EventDone`.
+    *   **`subdomains := make(chan string)`**: An internal channel acts as a work queue. Entries from the pre-loaded wordlist slice are fed into it.
+    *   **`var wg sync.WaitGroup`**: A `sync.WaitGroup` waits for all worker goroutines to finish.
+    *   **Worker Goroutines Loop**: `cfg.Concurrency` goroutines are launched. Each reads prefixes from the channel, constructs the full domain, and calls `dns.ResolveDomainWithRetry()` (or `dns.SimulateResolution()` in simulate mode).
+    *   **Progress ticker**: A separate goroutine fires every second and emits `EventProgress` events so callers can update their display.
+    *   **Closing the Channel**: After all entries are sent, the channel is closed, signalling workers to exit. `wg.Wait()` blocks until all workers are done, then `EventDone` is emitted.
+*   **Interactions**: `scan.Run` is the single entry point for scanning used by both the CLI output pipeline and the Bubble Tea TUI. It decouples the scan engine from any specific display layer.
 
 ### 2.5. Output Formatting (`internal/output`)
 
@@ -119,6 +122,16 @@ internal/wordlist/reader.go — LoadWordlist (dedup + sanitize)
         *   Shows percentage completion, processed count, and found count
 *   **Interactions**: The Progress Monitoring component works alongside the worker goroutines, using atomic operations to safely track counts across multiple goroutines. Writing to stderr keeps stdout pipe-clean.
 
+### 2.7. Session Persistence (`internal/tui/config.go`)
+
+*   **Purpose**: Remember the last-used TUI form values across sessions so users don't have to re-type domain, wordlist path, and scan parameters every time.
+*   **Implementation**:
+    *   `savedConfig` struct mirrors `formValues` with JSON tags.
+    *   `configPath()` — returns `os.UserConfigDir()/subenum/last.json` (e.g. `~/.config/subenum/last.json` on Linux/macOS, `%AppData%\subenum\last.json` on Windows).
+    *   `saveConfig(fv formValues) error` — marshals `formValues` to JSON and writes it atomically with `os.WriteFile`. Called in `beginScan()` immediately before launching the scan goroutine. Errors are silently discarded so a write failure never blocks the scan.
+    *   `loadSavedConfig() (savedConfig, bool)` — reads and unmarshals the file. Returns `false` if the file doesn't exist or is unreadable, causing `newFormModel` to fall back to hardcoded defaults.
+*   **Interactions**: `tui.New()` calls `loadSavedConfig()` on startup and passes the result to `newFormModel`. The `r` keybind (new scan) also calls `loadSavedConfig()` so the form is pre-filled with the values from the scan that just completed.
+
 ## 3. Data Flow
 
 The flow of data through the `subenum` application can be summarized as follows:
@@ -151,7 +164,7 @@ The flow of data through the `subenum` application can be summarized as follows:
 
 Visually, this can be seen as:
 
-`User Input -> Argument Parser -> [Wordlist File] -> Wordlist Processor -> subdomains channel -> Worker Goroutines -> DNS Resolver -> Output (if resolved)`
+`User Input -> Argument Parser -> [Wordlist File] -> Wordlist Processor -> scan.Run() -> Worker Goroutines -> DNS Resolver -> Event Channel -> Output (if resolved)`
 
 ## 4. Error Handling Strategy
 

docs/DEVELOPER_GUIDE.md

@@ -48,6 +48,11 @@ To work with `subenum`, you'll need:
     
     # Or with custom parameters
     ./subenum -w path/to/wordlist.txt -t 50 -timeout 2000 yourtarget.com
+
+    # Launch the interactive TUI (no flags required)
+    ./subenum -tui
+    # or via Make
+    make tui
     ```
 
 ## Project Structure
@@ -92,6 +97,13 @@ subenum/
 │   ├── output/
 │   │   ├── writer.go           # Thread-safe output (results→stdout, rest→stderr)
 │   │   └── writer_test.go      # Output writer tests
+│   ├── scan/
+│   │   └── runner.go           # Scan engine: Config, Event types, Run(ctx, cfg, events)
+│   ├── tui/
+│   │   ├── model.go            # Root Bubble Tea model (form → scan state machine)
+│   │   ├── form.go             # Config form screen (textinput fields + toggles)
+│   │   ├── scan_view.go        # Live results screen (viewport + progress bar)
+│   │   └── config.go           # Session persistence: load/save ~/.config/subenum/last.json
 │   └── wordlist/
 │       ├── reader.go           # LoadWordlist (dedup + sanitize)
 │       └── reader_test.go      # Wordlist loading and dedup tests
@@ -102,7 +114,7 @@ subenum/
 ├── .golangci.yml               # Linter configuration (golangci-lint v2)
 ├── main.go                     # CLI entry point: flag parsing, wiring
 ├── main_test.go                # CLI-level tests: validation, flag logic
-├── go.mod                      # Go module (zero external dependencies)
+├── go.mod                      # Go module (Bubble Tea for TUI; zero deps in CLI-only builds)
 ├── Dockerfile                  # Multi-stage Alpine build
 ├── docker-compose.yml          # Compose orchestration
 ├── Makefile                    # Build, test, lint, simulate, Docker targets
@@ -226,7 +238,14 @@ Please follow these style guidelines when contributing:
 
 ## Dependencies Management
 
-`subenum` aims to minimize external dependencies, relying primarily on the Go standard library. If you need to add a dependency:
+`subenum` aims to minimize external dependencies, relying primarily on the Go standard library.
+
+The CLI path (`run()`) has zero external dependencies. The TUI path (`-tui` flag) adds:
+
+- [`github.com/charmbracelet/bubbletea`](https://github.com/charmbracelet/bubbletea) — Elm-architecture terminal UI framework
+- [`github.com/charmbracelet/bubbles`](https://github.com/charmbracelet/bubbles) — reusable TUI components (textinput, viewport, progress bar)
+
+If you need to add a further dependency:
 
 1.  Evaluate whether it's truly necessary or if the functionality can be implemented using the standard library.
 2.  If a dependency is needed, add it with:
@@ -239,6 +258,7 @@ Please follow these style guidelines when contributing:
 
 Areas for potential enhancement include:
 
+*   **Terminal UI**: An interactive TUI (`-tui` flag) built with Bubble Tea. Provides a form-based config screen and a live-scrolling results view — no arguments required to launch. Last-used values persist to `~/.config/subenum/last.json` across sessions.
 *   **Output Formats**: Supporting different output formats (JSON, CSV) in addition to the current plain text output file (`-o`).
 *   **Result Filtering**: Allowing users to filter results based on DNS record types.
 *   **Recursive Enumeration**: Adding support for recursive subdomain enumeration (e.g., finding subdomains of discovered subdomains).

docs/index.md

@@ -22,6 +22,7 @@ A Go-based CLI tool for subdomain enumeration designed for educational purposes
 - Graceful shutdown on Ctrl+C (SIGINT/SIGTERM)
 - Simulation mode for safe testing without network access
 - Domain and DNS server input validation
+- Interactive TUI (`-tui` flag) — form-based config and live-scrolling results, no arguments required; saves last-used values to `~/.config/subenum/last.json`
 - Docker support for containerized usage
 - Extensive documentation and examples
 
@@ -73,6 +74,9 @@ make help
 # Build and run with default settings
 make run
 
+# Launch the interactive TUI
+make tui
+
 # Build and run with verbose output
 make run-verbose
 

go.mod

@@ -1,3 +1,31 @@
 module github.com/TMHSDigital/subenum
 
-go 1.22 
+go 1.24.2
+
+require (
+	github.com/atotto/clipboard v0.1.4 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/charmbracelet/bubbles v1.0.0 // indirect
+	github.com/charmbracelet/bubbletea v1.3.10 // indirect
+	github.com/charmbracelet/colorprofile v0.4.1 // indirect
+	github.com/charmbracelet/harmonica v0.2.0 // indirect
+	github.com/charmbracelet/lipgloss v1.1.0 // indirect
+	github.com/charmbracelet/x/ansi v0.11.6 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.9.0 // indirect
+	github.com/clipperhouse/stringish v0.1.1 // indirect
+	github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.19 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/text v0.3.8 // indirect
+)