Add DNS cache flush support (--flush flag) (#48)

* Add `FlushDNSCache` method with platform-specific error handling

Introduces the `FlushDNSCache` function to handle DNS cache flushing with platform context. Includes a custom `FlushError` type for detailed errors and a helper for formatting command arguments.

* Add macOS-specific DNS cache flush implementation

Introduces `flushDNSCachePlatform` for darwin builds, using `dscacheutil -flushcache` and `killall -HUP mDNSResponder`. Handles potential error scenarios with platform-specific context.

* Add `saveHosts` helper for DryRun/Save/Flush pattern with error handling

Introduces the `saveHosts` function to standardize the DryRun/Save/Flush process across mutation commands. Handles DNS cache flush warnings and provides improved error messaging for failures.

* Add Linux-specific DNS cache flush implementation

Introduces `flushDNSCachePlatform` for Linux builds, attempting `resolvectl` first and falling back to `systemd-resolve`. Handles errors with platform-specific context using the `FlushError` type.

* Add DNS cache flush stub for unsupported platforms

Introduces a no-op `flushDNSCachePlatform` function that returns an error on unsupported platforms. Uses `FlushError` for consistent error handling with platform-specific context.

* Add comprehensive tests for `FlushError`, `joinArgs`, and DNS cache flush behaviors

Introduce unit tests to validate `FlushError` error handling, including `Error`, `Unwrap`, and `errors.As`. Add tests for `joinArgs` utility. Mock DNS cache flush scenarios to verify behavior with AutoFlush-enabled save operations.

* Add Windows-specific DNS cache flush implementation

Introduce `flushDNSCachePlatform` for Windows builds using `ipconfig /flushdns`. Handles errors with `FlushError` for consistent platform-specific error reporting.

* Refactor `add` command to use `saveHosts` helper for DryRun/Save logic standardization.

* Refactor `remove_cidr` command to use `saveHosts` helper for standardized DryRun/Save logic.

* Refactor `remove_comment` command to use `saveHosts` helper for standardized DryRun/Save logic.

* Refactor `remove_host` command to use `saveHosts` helper for standardized DryRun/Save logic.

* Refactor `remove_ip` command to use `saveHosts` helper for standardized DryRun/Save logic.

* Add `--flush` flag to `root` command for DNS cache flushing

Introduces `--flush` flag and `TXEH_AUTO_FLUSH` environment variable to enable automatic DNS cache flush after modifying the hosts file.

* Add integration tests for `--flush` flag and `TXEH_AUTO_FLUSH` behavior

Introduce tests to validate the `--flush` flag, the `TXEH_AUTO_FLUSH` environment variable, and DryRun scenarios. Ensure proper logic for DNS cache flushing in various configurations.

* Add `AutoFlush` option to trigger DNS cache flush on save operations

Introduce `AutoFlush` field to the Hosts struct, enabling automatic DNS cache flush after successful `Save` or `SaveAs` calls. Handle flush failures with `FlushError`.

* Add comprehensive integration tests for `--flush`, `DryRun`, and DNS cache flush scenarios

Expand test coverage to validate flush behavior under multiple configurations, including success, failures, and quiet mode. Ensure logic correctness for `--flush` flag, `TXEH_AUTO_FLUSH` environment variable, and DryRun settings.

* Expand `flush_test.go` with extensive test coverage for DNS cache flush scenarios

Add tests to validate `FlushError` formatting, `joinArgs`, and `FlushDNSCache` behavior, including success, failures, and command sequencing. Introduce `mockExec` helper for mocking `execCommandFunc` in tests.

* Add functions to get and set `execCommandFunc` for testability

Introduce `ExecCommandFunc` and `SetExecCommandFunc` to retrieve and replace the `execCommandFunc` variable. These functions enhance testability by allowing command execution to be mocked.

* Document `--flush` flag and DNS cache flushing behavior in CLI guide

* Document platform-specific details for `FlushDNSCache` function

* Document macOS-specific DNS cache flush commands in `flushDNSCachePlatform` function

* Clarify error message and add documentation for Linux-specific `flushDNSCachePlatform` behavior and resolver limitations

* Document Windows-specific `flushDNSCachePlatform` command and behavior in function comments

* Expand DNS cache flush section in troubleshooting guide with `--flush` flag and `TXEH_AUTO_FLUSH` details

* Add platform-specific DNS cache flush tests for macOS and Linux

Expand test coverage with new test cases for macOS (`flush_darwin_test.go`) and Linux (`flush_linux_test.go`) to validate DNS cache flush behavior. Include success, failure, and command sequencing scenarios.

* Remove macOS-specific DNS cache flush tests and update Go version to 1.24.7

Author: cjimti

docs/cli.md

@@ -70,6 +70,7 @@ sudo txeh add 127.0.0.1 myapp.local --dryrun
 | `--quiet` | `-q` | Suppress output |
 | `--read` | `-r` | Override path to read hosts file |
 | `--write` | `-w` | Override path to write hosts file |
+| `--flush` | `-f` | Flush DNS cache after modifying the hosts file |
 | `--max-hosts-per-line` | `-m` | Max hostnames per line (0=auto, -1=unlimited) |
 
 ## Commands
@@ -206,3 +207,34 @@ Print the txeh version.
 ```bash
 txeh version
 ```
+
+## DNS Cache Flushing
+
+The `--flush` (`-f`) flag triggers a DNS cache flush after writing the hosts file. This makes new entries resolve immediately without manual intervention.
+
+```bash
+sudo txeh add 127.0.0.1 myapp.local --flush
+```
+
+You can also set the `TXEH_AUTO_FLUSH` environment variable to always flush:
+
+```bash
+export TXEH_AUTO_FLUSH=1
+sudo txeh add 127.0.0.1 myapp.local   # flush happens automatically
+```
+
+If the flush fails (e.g., the resolver binary is missing), the hosts file is still saved. txeh prints a warning to stderr and exits normally.
+
+### Platform Commands
+
+txeh runs these OS-provided commands. Nothing extra needs to be installed.
+
+| Platform | Command | Notes |
+|----------|---------|-------|
+| macOS | `dscacheutil -flushcache` + `killall -HUP mDNSResponder` | Ships with macOS. Works on 10.15 Catalina through current. |
+| Linux | `resolvectl flush-caches` or `systemd-resolve --flush-caches` | Requires systemd-resolved. See below. |
+| Windows | `ipconfig /flushdns` | Ships with all supported Windows versions. |
+
+### Linux Without systemd-resolved
+
+If your Linux system doesn't run systemd-resolved (common with dnsmasq, unbound, or no local caching), txeh prints a warning and exits normally. In this case, flushing isn't needed because DNS lookups go directly to `/etc/hosts` or to a remote resolver that doesn't cache your local entries.

docs/troubleshooting.md

@@ -32,7 +32,7 @@ Add this line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to make it p
 
 After adding entries, if the hostname doesn't resolve:
 
-1. **Flush DNS cache:**
+1. **Flush DNS cache.** You can do this automatically with `txeh --flush` (or set `TXEH_AUTO_FLUSH=1`). See the [CLI reference](cli.md#dns-cache-flushing) for details. To flush manually:
 
     === "macOS"
 

flush.go

@@ -0,0 +1,62 @@
+package txeh
+
+import (
+	"fmt"
+	"os/exec"
+	"strings"
+)
+
+// execCommandFunc is a variable that wraps exec.Command for testability.
+var execCommandFunc = exec.Command
+
+// ExecCommandFunc returns the current exec command function.
+// This is intended for test code that needs to save and restore the original.
+func ExecCommandFunc() func(string, ...string) *exec.Cmd {
+	return execCommandFunc
+}
+
+// SetExecCommandFunc replaces the exec command function.
+// This is intended for test code that needs to mock command execution.
+func SetExecCommandFunc(fn func(string, ...string) *exec.Cmd) {
+	execCommandFunc = fn
+}
+
+// FlushError represents a DNS cache flush failure with platform context.
+type FlushError struct {
+	Platform string
+	Command  string
+	Err      error
+}
+
+// Error returns a human-readable error message.
+func (e *FlushError) Error() string {
+	return fmt.Sprintf("flush DNS cache on %s (%s): %s", e.Platform, e.Command, e.Err)
+}
+
+// Unwrap returns the underlying error.
+func (e *FlushError) Unwrap() error {
+	return e.Err
+}
+
+// FlushDNSCache flushes the operating system's DNS cache.
+//
+// Platform commands (all are OS-provided utilities, not installable dependencies):
+//   - macOS: dscacheutil -flushcache + killall -HUP mDNSResponder (ships with macOS)
+//   - Linux: resolvectl flush-caches (systemd 239+) or systemd-resolve --flush-caches (older systemd).
+//     Returns ErrNoResolver if neither binary is found, which typically means the system
+//     does not cache DNS locally and hosts file changes take effect immediately.
+//   - Windows: ipconfig /flushdns (ships with Windows)
+//
+// Returns a *FlushError on failure, or nil on unsupported platforms
+// where no resolver is detected.
+func FlushDNSCache() error {
+	return flushDNSCachePlatform()
+}
+
+// joinArgs joins command arguments for error display.
+func joinArgs(name string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, name)
+	parts = append(parts, args...)
+	return strings.Join(parts, " ")
+}

flush_darwin.go

@@ -0,0 +1,40 @@
+//go:build darwin
+
+package txeh
+
+import "runtime"
+
+// flushDNSCachePlatform flushes the DNS cache on macOS.
+//
+// Commands:
+//   - dscacheutil -flushcache: flushes the Directory Service cache.
+//     Source: man dscacheutil (local man page, -flushcache flag).
+//     Present since macOS 10.5 Leopard (2007).
+//   - killall -HUP mDNSResponder: restarts the mDNS responder to clear its cache.
+//     Standard Apple convention, widely documented.
+//
+// Both commands together are the standard recommendation from macOS 10.15 Catalina (2019)
+// through current releases. On 10.12-10.14, only the killall was strictly needed, but
+// running dscacheutil there is harmless (flushes the Directory Service cache, a no-op
+// if DNS isn't cached there).
+//
+// Both binaries ship with macOS. No external dependencies.
+//
+// The killall step is non-fatal since mDNSResponder may not be running.
+func flushDNSCachePlatform() error {
+	cmd := execCommandFunc("dscacheutil", "-flushcache") // #nosec G204 -- hardcoded command, not user input
+	if err := cmd.Run(); err != nil {
+		return &FlushError{
+			Platform: runtime.GOOS,
+			Command:  joinArgs("dscacheutil", []string{"-flushcache"}),
+			Err:      err,
+		}
+	}
+
+	// Attempt to restart mDNSResponder. This may fail if the process
+	// is not running, which is not an error condition.
+	cmd = execCommandFunc("killall", "-HUP", "mDNSResponder") // #nosec G204 -- hardcoded command, not user input
+	_ = cmd.Run()
+
+	return nil
+}

flush_darwin_test.go

@@ -0,0 +1,135 @@
+//go:build darwin
+
+package txeh
+
+import (
+	"context"
+	"errors"
+	"os/exec"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// --- Platform flush command verification (darwin) ---
+
+// Given execCommandFunc is mocked to record calls and succeed
+// When FlushDNSCache() is called on darwin
+// Then exactly 2 commands are invoked:
+//
+//	1st: "dscacheutil" with args ["-flushcache"]
+//	2nd: "killall" with args ["-HUP", "mDNSResponder"]
+//
+// And no error is returned.
+func TestFlushDNSCache_Darwin_CommandsAndArgs(t *testing.T) {
+	origFunc := ExecCommandFunc()
+	defer SetExecCommandFunc(origFunc)
+
+	fn, calls, mu := mockExec("true")
+	SetExecCommandFunc(fn)
+
+	err := FlushDNSCache()
+	if err != nil {
+		t.Fatalf("FlushDNSCache() returned error: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	if len(*calls) != 2 {
+		t.Fatalf("expected 2 exec calls, got %d: %+v", len(*calls), *calls)
+	}
+
+	// First call: dscacheutil -flushcache
+	first := (*calls)[0]
+	if first.Name != "dscacheutil" {
+		t.Errorf("call[0].Name = %q, want %q", first.Name, "dscacheutil")
+	}
+	wantArgs := []string{"-flushcache"}
+	if strings.Join(first.Args, " ") != strings.Join(wantArgs, " ") {
+		t.Errorf("call[0].Args = %v, want %v", first.Args, wantArgs)
+	}
+
+	// Second call: killall -HUP mDNSResponder
+	second := (*calls)[1]
+	if second.Name != "killall" {
+		t.Errorf("call[1].Name = %q, want %q", second.Name, "killall")
+	}
+	wantArgs2 := []string{"-HUP", "mDNSResponder"}
+	if strings.Join(second.Args, " ") != strings.Join(wantArgs2, " ") {
+		t.Errorf("call[1].Args = %v, want %v", second.Args, wantArgs2)
+	}
+}
+
+// Given execCommandFunc is mocked to fail (exit 1)
+// When FlushDNSCache() is called on darwin
+// Then a *FlushError is returned with Platform="darwin"
+// And Command="dscacheutil -flushcache"
+// And only 1 command was attempted (killall is not reached).
+func TestFlushDNSCache_Darwin_FirstCommandFails(t *testing.T) {
+	origFunc := ExecCommandFunc()
+	defer SetExecCommandFunc(origFunc)
+
+	fn, calls, mu := mockExec("false")
+	SetExecCommandFunc(fn)
+
+	err := FlushDNSCache()
+	if err == nil {
+		t.Fatal("expected error when dscacheutil fails")
+	}
+
+	var fe *FlushError
+	if !errors.As(err, &fe) {
+		t.Fatalf("expected *FlushError, got %T: %v", err, err)
+	}
+
+	if fe.Platform != "darwin" {
+		t.Errorf("Platform = %q, want %q", fe.Platform, "darwin")
+	}
+	if fe.Command != "dscacheutil -flushcache" {
+		t.Errorf("Command = %q, want %q", fe.Command, "dscacheutil -flushcache")
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	// Only dscacheutil should have been attempted. killall should not run.
+	if len(*calls) != 1 {
+		t.Errorf("expected 1 exec call (dscacheutil only), got %d: %+v", len(*calls), *calls)
+	}
+}
+
+// Given execCommandFunc where dscacheutil succeeds but killall fails
+// When FlushDNSCache() is called
+// Then no error is returned (killall failure is non-fatal).
+func TestFlushDNSCache_Darwin_KillallFails_NonFatal(t *testing.T) {
+	origFunc := ExecCommandFunc()
+	defer SetExecCommandFunc(origFunc)
+
+	callCount := 0
+	var mu sync.Mutex
+	SetExecCommandFunc(func(name string, args ...string) *exec.Cmd {
+		mu.Lock()
+		callCount++
+		n := callCount
+		mu.Unlock()
+
+		if n == 1 {
+			// dscacheutil succeeds
+			return exec.CommandContext(context.Background(), "true") //nolint:gosec // test
+		}
+		// killall fails
+		return exec.CommandContext(context.Background(), "false") //nolint:gosec // test
+	})
+
+	err := FlushDNSCache()
+	if err != nil {
+		t.Errorf("killall failure should be non-fatal, got error: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if callCount != 2 {
+		t.Errorf("expected 2 exec calls, got %d", callCount)
+	}
+}

flush_linux.go

@@ -0,0 +1,64 @@
+//go:build linux
+
+package txeh
+
+import (
+	"errors"
+	"os/exec"
+	"runtime"
+)
+
+// ErrNoResolver is returned when no supported DNS resolver is found on the system.
+// If your system does not cache DNS locally (e.g., no systemd-resolved, dnsmasq, or
+// unbound), hosts file changes take effect immediately without flushing.
+var ErrNoResolver = errors.New(
+	"systemd-resolved not detected (tried resolvectl, systemd-resolve). " +
+		"If your system does not cache DNS locally, hosts file changes take effect immediately without flushing",
+)
+
+// flushDNSCachePlatform flushes the DNS cache on Linux.
+//
+// Commands:
+//   - resolvectl flush-caches: systemd-resolved 239+ (2018).
+//     Source: https://man7.org/linux/man-pages/man1/resolvectl.1.html
+//   - systemd-resolve --flush-caches: pre-239 name for the same operation.
+//
+// Tries resolvectl first, then falls back to systemd-resolve.
+// Returns ErrNoResolver (wrapped in FlushError) if neither is available.
+//
+// Other resolvers (dnsmasq, unbound, nscd) are intentionally not supported here
+// because flushing them reliably depends on per-site configuration (socket paths,
+// service names, etc.) that we can't safely assume.
+func flushDNSCachePlatform() error {
+	// Try resolvectl first (systemd 239+).
+	if _, err := exec.LookPath("resolvectl"); err == nil {
+		cmd := execCommandFunc("resolvectl", "flush-caches") // #nosec G204 -- hardcoded command, not user input
+		if err := cmd.Run(); err != nil {
+			return &FlushError{
+				Platform: runtime.GOOS,
+				Command:  joinArgs("resolvectl", []string{"flush-caches"}),
+				Err:      err,
+			}
+		}
+		return nil
+	}
+
+	// Fallback to systemd-resolve (older systemd).
+	if _, err := exec.LookPath("systemd-resolve"); err == nil {
+		cmd := execCommandFunc("systemd-resolve", "--flush-caches") // #nosec G204 -- hardcoded command, not user input
+		if err := cmd.Run(); err != nil {
+			return &FlushError{
+				Platform: runtime.GOOS,
+				Command:  joinArgs("systemd-resolve", []string{"--flush-caches"}),
+				Err:      err,
+			}
+		}
+		return nil
+	}
+
+	return &FlushError{
+		Platform: runtime.GOOS,
+		Command:  "",
+		Err:      ErrNoResolver,
+	}
+}