Refactor: separate execv into its own package (#3720)

## Changes

Move process replacement functionality from libs/exec to libs/execv to
separate concerns. The exec package now focuses on command execution,
while execv handles process replacement via syscalls.

Shell preparation code is extracted to prepare.go. ShellExecv is moved
to the execv package and renamed to Shell for clarity.

The next step is to also rename `exec` to something that implies
executing scripts through a shell.

## Why

I looked into the package while working on #3659 and found this could be
improved.

Author: pietern

cmd/bundle/run.go

@@ -19,7 +19,7 @@ import (
 	"github.com/databricks/cli/libs/auth"
 	"github.com/databricks/cli/libs/cmdctx"
 	"github.com/databricks/cli/libs/cmdio"
-	"github.com/databricks/cli/libs/exec"
+	"github.com/databricks/cli/libs/execv"
 	"github.com/databricks/cli/libs/flags"
 	"github.com/databricks/cli/libs/logdiag"
 	"github.com/spf13/cobra"
@@ -278,7 +278,7 @@ func scriptEnv(cmd *cobra.Command, b *bundle.Bundle) []string {
 }
 
 func executeScript(content string, cmd *cobra.Command, b *bundle.Bundle) error {
-	return exec.ShellExecv(content, b.BundleRootPath, scriptEnv(cmd, b))
+	return execv.Shell(content, b.BundleRootPath, scriptEnv(cmd, b))
 }
 
 func executeInline(cmd *cobra.Command, args []string, b *bundle.Bundle) error {
@@ -287,7 +287,7 @@ func executeInline(cmd *cobra.Command, args []string, b *bundle.Bundle) error {
 		return err
 	}
 
-	return exec.Execv(exec.ExecvOptions{
+	return execv.Execv(execv.Options{
 		Args: args,
 		Env:  scriptEnv(cmd, b),
 		Dir:  dir,

libs/exec/execv.go

@@ -0,0 +1,43 @@
+package exec
+
+// ShellPreparation contains everything needed to execute a shell command.
+type ShellPreparation struct {
+	// Executable is the path to the shell executable.
+	Executable string
+	// Args contains all arguments including the executable as the first element.
+	Args []string
+	// CleanupFn should be called to clean up any temporary resources.
+	// It may be nil if no cleanup is needed.
+	CleanupFn func()
+}
+
+// PrepareShellCommand prepares a command string for execution through a shell.
+// It finds an available shell (bash, sh, or cmd.exe) and returns the prepared
+// command with executable, arguments, and an optional cleanup function.
+func PrepareShellCommand(command string) (*ShellPreparation, error) {
+	shell, err := findShell()
+	if err != nil {
+		return nil, err
+	}
+
+	ec, err := shell.prepare(command)
+	if err != nil {
+		return nil, err
+	}
+
+	args := []string{ec.executable}
+	args = append(args, ec.args...)
+
+	var cleanupFn func()
+	if ec.scriptFile != "" {
+		cleanupFn = func() {
+			ec.cleanup()
+		}
+	}
+
+	return &ShellPreparation{
+		Executable: ec.executable,
+		Args:       args,
+		CleanupFn:  cleanupFn,
+	}, nil
+}

libs/exec/prepare.go

@@ -0,0 +1,22 @@
+package exec
+
+import (
+	"os/exec"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPrepareShellCommand(t *testing.T) {
+	prep, err := PrepareShellCommand("echo hello")
+	require.NoError(t, err)
+
+	bashPath, err := exec.LookPath("bash")
+	require.NoError(t, err)
+	assert.Equal(t, bashPath, prep.Executable)
+	assert.Equal(t, bashPath, prep.Args[0])
+	assert.Equal(t, "-ec", prep.Args[1])
+	assert.Equal(t, "echo hello", prep.Args[2])
+	assert.Nil(t, prep.CleanupFn)
+}

libs/exec/prepare_test.go

@@ -0,0 +1,44 @@
+package execv
+
+import "os"
+
+// Options specifies the configuration for process replacement.
+type Options struct {
+	// Args is the name of the command to run and its arguments.
+	// Eg: ["echo", "hello"] for "echo hello"
+	Args []string
+
+	// Env specifies the environment variables to set in the child process.
+	Env []string
+
+	// Dir specifies the working directory of the command.
+	// If Dir is an empty string, Execv runs the command in the
+	// calling process's current directory.
+	Dir string
+
+	// cleanup is called before process replacement (Windows only).
+	// Use this to clean up temporary files created during command preparation.
+	// On Unix systems, cleanup cannot be performed after Execv because
+	// the process is replaced.
+	cleanup func()
+
+	// windowsExit is a callback to exit the current process on Windows.
+	// This field is used for testing and should not be set by callers.
+	windowsExit func(status int)
+}
+
+// Execv replaces the current process with the specified command.
+//
+// On Unix systems (Linux, macOS), this uses the execve syscall which
+// replaces the current process image with a new process image.
+// Control never returns to the caller on success.
+//
+// On Windows, which doesn't have an equivalent syscall, this function
+// creates a child process, waits for it to complete, and exits with
+// the child's exit code to emulate Unix behavior.
+func Execv(opts Options) error {
+	if opts.windowsExit == nil {
+		opts.windowsExit = os.Exit
+	}
+	return execv(opts)
+}

libs/exec/shell_execv.go

@@ -1,6 +1,6 @@
 //go:build linux || darwin
 
-package exec
+package execv
 
 import (
 	"fmt"
@@ -9,7 +9,7 @@ import (
 	"syscall"
 )
 
-func execv(opts ExecvOptions) error {
+func execv(opts Options) error {
 	if opts.Dir != "" {
 		err := os.Chdir(opts.Dir)
 		if err != nil {

libs/execv/execv.go

@@ -1,6 +1,6 @@
 //go:build windows
 
-package exec
+package execv
 
 import (
 	"fmt"
@@ -9,22 +9,23 @@ import (
 	"strings"
 )
 
-// Note: Windows does not support an execv syscall that replaces the current process.
-// To emulate this, we create a child process, pass the stdin, stdout and stderr file descriptors,
-// and return the exit code.
+// execv emulates Unix execv behavior on Windows.
+//
+// Windows does not support an execv syscall that replaces the current process.
+// To emulate this, we create a child process, pass the stdin, stdout and stderr
+// file descriptors, wait for it to complete, and exit with its exit code.
+//
 // ref: https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/execv-wexecv?view=msvc-170
-func execv(opts ExecvOptions) error {
+func execv(opts Options) error {
 	if opts.cleanup != nil {
 		defer opts.cleanup()
 	}
 
 	windowsExit := func(status int) {
-		// First clean up the temporary script if it exists.
+		// Clean up before exiting (defer will not run).
 		if opts.cleanup != nil {
 			opts.cleanup()
 		}
-
-		// Then exit the process.
 		opts.windowsExit(status)
 	}
 
@@ -43,7 +44,7 @@ func execv(opts ExecvOptions) error {
 
 	err = cmd.Start()
 	if err != nil {
-		return fmt.Errorf(" %s failed: %w", strings.Join(opts.Args, " "), err)
+		return fmt.Errorf("%s failed: %w", strings.Join(opts.Args, " "), err)
 	}
 
 	err = cmd.Wait()

libs/exec/execv_unix.go libs/execv/execv_unix.golibs/exec/execv_unix.go renamed to libs/execv/execv_unix.go

@@ -0,0 +1,32 @@
+package execv
+
+import "github.com/databricks/cli/libs/exec"
+
+// Shell executes a shell script by replacing the current process.
+//
+// The script content is executed through the system's default shell:
+// - On Unix systems: bash (preferred) or sh
+// - On Windows: cmd.exe
+//
+// This function calls the execve syscall on Unix systems, which replaces
+// the current process. On Windows, it creates a child process and exits
+// with the child's exit code.
+//
+// Note: For cmd.exe, the script is written to a temporary file which is
+// automatically cleaned up. On Unix systems, temporary files in /tmp are
+// periodically cleaned up by the system.
+//
+// This function does not return on success.
+func Shell(content, dir string, env []string) error {
+	prep, err := exec.PrepareShellCommand(content)
+	if err != nil {
+		return err
+	}
+
+	return Execv(Options{
+		Args:    prep.Args,
+		Env:     env,
+		Dir:     dir,
+		cleanup: prep.CleanupFn,
+	})
+}

libs/exec/execv_windows.go libs/execv/execv_windows.golibs/exec/execv_windows.go renamed to libs/execv/execv_windows.go

@@ -1,37 +1,24 @@
-package exec
+package execv
 
 import (
 	"os"
-	"os/exec"
+	osexec "os/exec"
 	"path/filepath"
 	"runtime"
 	"testing"
 
 	"github.com/databricks/cli/internal/testutil"
+	"github.com/databricks/cli/libs/exec"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestShellExecvOpts(t *testing.T) {
-	opts, err := shellExecvOpts("echo hello", "/a/b/c", []string{"key1=value1", "key2=value2"})
-	require.NoError(t, err)
-
-	assert.Equal(t, []string{"key1=value1", "key2=value2"}, opts.Env)
-	assert.Equal(t, "/a/b/c", opts.Dir)
-
-	bashPath, err := exec.LookPath("bash")
-	require.NoError(t, err)
-	assert.Equal(t, bashPath, opts.Args[0])
-	assert.Equal(t, "-ec", opts.Args[1])
-	assert.Equal(t, "echo hello", opts.Args[2])
-}
-
-func TestShellExecv_Windows(t *testing.T) {
+func TestShell_Windows(t *testing.T) {
 	if runtime.GOOS != "windows" {
 		t.Skip("skipping windows test")
 	}
 
-	cmdExePath, err := exec.LookPath("cmd.exe")
+	cmdExePath, err := osexec.LookPath("cmd.exe")
 	require.NoError(t, err)
 
 	// Cleanup environment so that other shells like bash and sh are not used.
@@ -56,7 +43,7 @@ func TestShellExecv_Windows(t *testing.T) {
 		dir := t.TempDir()
 		t.Setenv("TMP", dir)
 
-		opts, err := shellExecvOpts(test.content, dir, []string{})
+		prep, err := exec.PrepareShellCommand(test.content)
 		require.NoError(t, err)
 
 		// Verify that the temporary file is created.
@@ -66,8 +53,14 @@ func TestShellExecv_Windows(t *testing.T) {
 		assert.Regexp(t, "cli-exec.*\\.cmd", files[0].Name())
 
 		exitCode := -1
-		opts.windowsExit = func(status int) {
-			exitCode = status
+		opts := Options{
+			Args:    prep.Args,
+			Env:     []string{},
+			Dir:     dir,
+			cleanup: prep.CleanupFn,
+			windowsExit: func(status int) {
+				exitCode = status
+			},
 		}
 
 		// Execute the script.