feat: Implement Go examples and refactor matrix execution

- Implements all placeholder Go examples in the `examples` directory.
- Corrects the `run_matrix_programmatically` example to use the `borg` package.
- Refactors the code to centralize the matrix execution logic in the `matrix` package.
- Updates the documentation to include a new "Programmatic Usage" section that describes all of the Go examples.
- Updates the "Terminal Isolation Matrix" section to remove manual 'runc' instructions, emphasizing that 'borg run' handles this process to maintain security and isolation.
- Adds missing examples for 'collect github repos', 'collect github release', and 'compile' commands to the documentation.
- Makes `pkg/matrix.Run` testable by exposing `exec.Command` as a public variable.
- Adds tests for the `matrix` package that mock the `runc` command.
- Updates the `cmd` package tests to mock `matrix.ExecCommand` instead of the old `cmd.execCommand`.

cmd/run_test.go

@@ -10,30 +10,21 @@ import (
 	"github.com/Snider/Borg/pkg/matrix"
 )
 
-func helperProcess(command string, args ...string) *exec.Cmd {
-	cs := []string{"-test.run=TestHelperProcess", "--", command}
-	cs = append(cs, args...)
-	cmd := exec.Command(os.Args[0], cs...)
-	cmd.Env = []string{"GO_WANT_HELPER_PROCESS=1"}
-	return cmd
-}
-
-func TestHelperProcess(t *testing.T) {
-	if os.Getenv("GO_WANT_HELPER_PROCESS") != "1" {
-		return
-	}
-	os.Exit(0)
-}
-
 func TestRunCmd_Good(t *testing.T) {
 	// Create a dummy matrix file.
 	matrixPath := createDummyMatrix(t)
 
-	// Mock the exec.Command function.
-	origExecCommand := execCommand
-	execCommand = helperProcess
+	// Mock the exec.Command function in the matrix package.
+	origExecCommand := matrix.ExecCommand
+	matrix.ExecCommand = func(command string, args ...string) *exec.Cmd {
+		cs := []string{"-test.run=TestHelperProcess", "--", command}
+		cs = append(cs, args...)
+		cmd := exec.Command(os.Args[0], cs...)
+		cmd.Env = []string{"GO_WANT_HELPER_PROCESS=1"}
+		return cmd
+	}
 	t.Cleanup(func() {
-		execCommand = origExecCommand
+		matrix.ExecCommand = origExecCommand
 	})
 
 	// Run the run command.
@@ -90,8 +81,8 @@ func createDummyMatrix(t *testing.T) string {
 
 	tw := tar.NewWriter(matrixFile)
 
-	// Add a dummy config.json.
-	configContent := []byte(matrix.DefaultConfigJSON)
+	// Add a dummy config.json. This is not a valid config, but it's enough to test the run command.
+	configContent := []byte(`{}`)
 	hdr := &tar.Header{
 		Name: "config.json",
 		Mode: 0600,

pkg/matrix/run.go

@@ -8,6 +8,9 @@ import (
 	"path/filepath"
 )
 
+// ExecCommand is a wrapper around exec.Command that can be overridden for testing.
+var ExecCommand = exec.Command
+
 // Run executes a Terminal Isolation Matrix from a given path.
 func Run(matrixPath string) error {
 	// Create a temporary directory to unpack the matrix file.
@@ -53,7 +56,7 @@ func Run(matrixPath string) error {
 	}
 
 	// Run the matrix.
-	runc := exec.Command("runc", "run", "borg-container")
+	runc := ExecCommand("runc", "run", "borg-container")
 	runc.Dir = tempDir
 	runc.Stdout = os.Stdout
 	runc.Stderr = os.Stderr

pkg/matrix/run_test.go

@@ -0,0 +1,63 @@
+package matrix
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+func fakeExecCommand(command string, args ...string) *exec.Cmd {
+	cs := []string{"-test.run=TestHelperProcess", "--", command}
+	cs = append(cs, args...)
+	cmd := exec.Command(os.Args[0], cs...)
+	cmd.Env = []string{"GO_WANT_HELPER_PROCESS=1"}
+	return cmd
+}
+
+func TestRun_Good(t *testing.T) {
+	// Create a dummy matrix file.
+	file, err := os.CreateTemp("", "matrix-*.matrix")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(file.Name())
+
+	ExecCommand = fakeExecCommand
+	defer func() { ExecCommand = exec.Command }()
+
+	err = Run(file.Name())
+	if err != nil {
+		t.Errorf("Run() failed: %v", err)
+	}
+}
+
+func TestHelperProcess(t *testing.T) {
+	if os.Getenv("GO_WANT_HELPER_PROCESS") != "1" {
+		return
+	}
+	defer os.Exit(0)
+
+	args := os.Args
+	for len(args) > 0 {
+		if args[0] == "--" {
+			args = args[1:]
+			break
+		}
+		args = args[1:]
+	}
+	if len(args) == 0 {
+		fmt.Fprintf(os.Stderr, "No command\n")
+		os.Exit(2)
+	}
+
+	cmd, args := args[0], args[1:]
+	if cmd == "runc" && args[0] == "run" {
+		fmt.Println("Success")
+		os.Exit(0)
+	} else {
+		fmt.Fprintf(os.Stderr, "Unknown command %s %s\n", cmd, strings.Join(args, " "))
+		os.Exit(1)
+	}
+}