feat(cli): introduce explicit run/exec subcommands to prevent typo-execution

Prevent the ambiguity where a mistyped subcommand was interpreted as the target
wrapped process.

- Introduce `run` and `exec` (alias) subcommands for launching wrapped processes.
- Promote internal test commands (`test-ns`, `test-args`, `test-lifecycle`) to explicit subcommands.
- Update CLI routing to return an error for unknown subcommands instead of falling back to the default execution path.
- Update `README.md` usage examples and all test suites to use the new subcommand structure.

9 files changed, 18 insertions, 18 deletions

diff --git a/tests/e2e/config_hotswap_test.go b/tests/e2e/config_hotswap_test.go
index 54155a0..09d9cb1 100644
--- a/tests/e2e/config_hotswap_test.go
+++ b/tests/e2e/config_hotswap_test.go
@@ -39,7 +39,7 @@ Endpoint = 1.1.1.1:51820
 	}
 
 	// Start a process to establish the session
-	cmdA := exec.Command(binaryPath, "--profile", profile, "--", "sleep", "1.0")
+	cmdA := exec.Command(binaryPath, "run", "--profile", profile, "--", "sleep", "1.0")
 	cmdA.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
@@ -68,7 +68,7 @@ Endpoint = 8.8.8.8:51820
 
 	// 3. Launch a second process. It should join the existing session
 	// regardless of the fact that the .conf file has changed.
-	cmdB := exec.Command(binaryPath, "--profile", profile, "--", "ls")
+	cmdB := exec.Command(binaryPath, "run", "--profile", profile, "--", "ls")
 	cmdB.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/config_test.go b/tests/e2e/config_test.go
index 33eb6e6..28857c8 100644
--- a/tests/e2e/config_test.go
+++ b/tests/e2e/config_test.go
@@ -53,7 +53,7 @@ AllowedIPs = 10.0.0.0/24
 	}
 
 	// Test 2: Configuration after bootstrap (Isolated)
-	cmdIsolated := exec.Command(binaryPath, "--profile", profile, "--", "sh", "-c", "echo $XDG_RUNTIME_DIR")
+	cmdIsolated := exec.Command(binaryPath, "run", "--profile", profile, "--", "sh", "-c", "echo $XDG_RUNTIME_DIR")
 	cmdIsolated.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/crash_recovery_test.go b/tests/e2e/crash_recovery_test.go
index 11d6ca3..ea29025 100644
--- a/tests/e2e/crash_recovery_test.go
+++ b/tests/e2e/crash_recovery_test.go
@@ -60,7 +60,7 @@ Endpoint = 1.1.1.1:51820
 	// 2. Try to run wg-wrap.
 	// It should see the stale PID, prune it, realize the namespace is actually dead,
 	// and start a fresh tunnel.
-	cmd := exec.Command(binaryPath, "--profile", profile, "--", "ls")
+	cmd := exec.Command(binaryPath, "run", "--profile", profile, "--", "ls")
 	cmd.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/e2e_test.go b/tests/e2e/e2e_test.go
index 907bb22..98711e4 100644
--- a/tests/e2e/e2e_test.go
+++ b/tests/e2e/e2e_test.go
@@ -57,7 +57,7 @@ AllowedIPs = 10.0.0.0/24
 	}
 
 	// 3. Launch wg-wrap with a command that triggers traffic
-	cmd := exec.Command(binaryPath, "--profile", profile, "--", "ping", "-c", "1", "-W", "1", "10.0.0.1")
+	cmd := exec.Command(binaryPath, "run", "--profile", profile, "--", "ping", "-c", "1", "-W", "1", "10.0.0.1")
 	cmd.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpDir),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpDir),
@@ -138,7 +138,7 @@ AllowedIPs = 10.0.0.0/24
 
 	// 3. Test /etc/resolv.conf modification
 	expectedDNS := "1.1.1.1"
-	cmd := exec.Command(binaryPath, "--profile", profile, "--dns-server", expectedDNS, "--", "cat", "/etc/resolv.conf")
+	cmd := exec.Command(binaryPath, "run", "--profile", profile, "--dns-server", expectedDNS, "--", "cat", "/etc/resolv.conf")
 	cmd.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpDir),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpDir),
@@ -154,7 +154,7 @@ AllowedIPs = 10.0.0.0/24
 	}
 
 	// 4. Test Data Path: Send a ping to trigger Handshake on the mock server
-	cmdQuery := exec.Command(binaryPath, "--profile", profile, "--", "ping", "-c", "1", "-W", "1", dnsServerIP)
+	cmdQuery := exec.Command(binaryPath, "run", "--profile", profile, "--", "ping", "-c", "1", "-W", "1", dnsServerIP)
 	cmdQuery.Env = cmd.Env
 
 	packetReceived := make(chan bool, 1)
@@ -236,7 +236,7 @@ AllowedIPs = 10.0.0.0/24
 			_ = os.WriteFile(profilePath, []byte(confContent), 0644)
 
 			// Prepare command args
-			args := []string{"--profile", profileName}
+			args := []string{"run", "--profile", profileName}
 			if tt.cliDNS != "" {
 				args = append(args, "--dns-server", tt.cliDNS)
 			}
@@ -263,7 +263,7 @@ AllowedIPs = 10.0.0.0/24
 func TestMTUFragmentation(t *testing.T) {
 	binaryPath := EnsureBinary(t)
 
-	cmd := exec.Command(binaryPath, "--profile", "default", "--", "true")
+	cmd := exec.Command(binaryPath, "run", "--profile", "default", "--", "true")
 	if err := cmd.Run(); err != nil {
 		t.Errorf("expected command to pass, got: %v", err)
 	}
@@ -273,7 +273,7 @@ func TestExitCodePropagation(t *testing.T) {
 	binaryPath := EnsureBinary(t)
 
 	// Run a command that exits with code 42
-	cmd := exec.Command(binaryPath, "--profile", "default", "--", "sh", "-c", "exit 42")
+	cmd := exec.Command(binaryPath, "run", "--profile", "default", "--", "sh", "-c", "exit 42")
 	err := cmd.Run()
 	if err == nil {
 		t.Fatalf("expected command to fail with exit status 42, but it succeeded")
diff --git a/tests/e2e/lifecycle_test.go b/tests/e2e/lifecycle_test.go
index d0d7271..8158593 100644
--- a/tests/e2e/lifecycle_test.go
+++ b/tests/e2e/lifecycle_test.go
@@ -76,7 +76,7 @@ func TestNamespaceLifecycleAutomation(t *testing.T) {
 
 	t.Run("ReferenceCounting", func(t *testing.T) {
 		// Start a process that exits quickly
-		cmd1 := exec.Command(binaryPath, "--profile", "default", "--", "sleep", "1.0")
+		cmd1 := exec.Command(binaryPath, "run", "--profile", "default", "--", "sleep", "1.0")
 		cmd1.Env = SetEnvOverrides(map[string]string{"XDG_RUNTIME_DIR": tmpRuntimeDir})
 		cmd1.Stdout = os.Stdout
 		cmd1.Stderr = os.Stderr
@@ -88,7 +88,7 @@ func TestNamespaceLifecycleAutomation(t *testing.T) {
 		waitForLifecycle(t, binaryPath, tmpRuntimeDir, "default", true)
 
 		// Start a second process using the same profile with a longer sleep
-		cmd2 := exec.Command(binaryPath, "--profile", "default", "--", "sleep", "5.0")
+		cmd2 := exec.Command(binaryPath, "run", "--profile", "default", "--", "sleep", "5.0")
 		cmd2.Env = SetEnvOverrides(map[string]string{"XDG_RUNTIME_DIR": tmpRuntimeDir})
 		cmd2.Stdout = os.Stdout
 		cmd2.Stderr = os.Stderr
diff --git a/tests/e2e/network_change_test.go b/tests/e2e/network_change_test.go
index f1ca215..98614b7 100644
--- a/tests/e2e/network_change_test.go
+++ b/tests/e2e/network_change_test.go
@@ -38,7 +38,7 @@ Endpoint = 1.1.1.1:51820
 	}
 
 	// Launch a long-running command to keep the tunnel alive
-	cmd := exec.Command(binaryPath, "--profile", profile, "--", "sleep", "5")
+	cmd := exec.Command(binaryPath, "run", "--profile", profile, "--", "sleep", "5")
 	cmd.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
@@ -57,7 +57,7 @@ Endpoint = 1.1.1.1:51820
 	// operational and hasn't crashed due to the host socket's nature.
 
 	// We launch a second process to verify the session is still valid.
-	cmdJoin := exec.Command(binaryPath, "--profile", profile, "--", "ls")
+	cmdJoin := exec.Command(binaryPath, "run", "--profile", profile, "--", "ls")
 	cmdJoin.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/resource_exhaustion_test.go b/tests/e2e/resource_exhaustion_test.go
index b5cdaf9..3c8d202 100644
--- a/tests/e2e/resource_exhaustion_test.go
+++ b/tests/e2e/resource_exhaustion_test.go
@@ -37,7 +37,7 @@ Endpoint = 1.1.1.1:51820
 	// We run a burst of short-lived commands to stress the lock and cleanup logic.
 	iterations := 50
 	for i := 0; i < iterations; i++ {
-		cmd := exec.Command(binaryPath, "--profile", profile, "--", "true")
+		cmd := exec.Command(binaryPath, "run", "--profile", profile, "--", "true")
 		cmd.Env = append(os.Environ(),
 			fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 			fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/sharing_test.go b/tests/e2e/sharing_test.go
index 1ecfbe6..f6c8476 100644
--- a/tests/e2e/sharing_test.go
+++ b/tests/e2e/sharing_test.go
@@ -40,7 +40,7 @@ Endpoint = 1.1.1.1:51820
 	pidsDir := filepath.Join(tmpRuntimeDir, "profiles", profile, "pids")
 
 	// Start Process A running a command that outputs its netns and sleeps
-	cmdA := exec.Command(binaryPath, "--profile", profile, "--", "sh", "-c", "readlink /proc/self/ns/net && sleep 5")
+	cmdA := exec.Command(binaryPath, "run", "--profile", profile, "--", "sh", "-c", "readlink /proc/self/ns/net && sleep 5")
 	cmdA.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
@@ -75,7 +75,7 @@ Endpoint = 1.1.1.1:51820
 	waitForPids(t, pidsDir, 1)
 
 	// Start Process B to check its netns ID
-	cmdB := exec.Command(binaryPath, "--profile", profile, "--", "readlink", "/proc/self/ns/net")
+	cmdB := exec.Command(binaryPath, "run", "--profile", profile, "--", "readlink", "/proc/self/ns/net")
 	cmdB.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
diff --git a/tests/e2e/vulnerability_test.go b/tests/e2e/vulnerability_test.go
index 26536fe..23de6bd 100644
--- a/tests/e2e/vulnerability_test.go
+++ b/tests/e2e/vulnerability_test.go
@@ -87,7 +87,7 @@ Endpoint = 1.1.1.1:51820
 
 	// 2. Run a command that performs a DNS lookup using exec.Command on the wg-wrap binary.
 	// We use 'timeout 3 getent hosts google.com' to ensure it fails quickly instead of waiting on timeouts.
-	cmd := exec.Command(binaryPath, "--profile", profileName, "--", "timeout", "3", "getent", "hosts", "google.com")
+	cmd := exec.Command(binaryPath, "run", "--profile", profileName, "--", "timeout", "3", "getent", "hosts", "google.com")
 	cmd.Env = append(os.Environ(),
 		fmt.Sprintf("XDG_CONFIG_HOME=%s", tmpConfigDir),
 		fmt.Sprintf("XDG_RUNTIME_DIR=%s", tmpRuntimeDir),