From 757a12086c10aebff5b9b2e8943a8a13ff30afb2 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 13 Nov 2025 19:27:12 +0000
Subject: [PATCH] feat: Add programmatic examples for matrix creation and
 execution

This commit adds two new Go programs to the `examples` directory to
demonstrate how to use the `pkg/matrix` and `pkg/datanode` packages
programmatically:

- `examples/create_matrix_programmatically`: Shows how to create a
  `.matrix` file from scratch.
- `examples/run_matrix_programmatically`: Shows how to unpack and execute
  a `.matrix` file using `runc`.

The `examples` directory has been reorganized to place each runnable
example in its own subdirectory, which is the standard Go practice for
handling multiple `main` packages.
---
 .../create_matrix_programmatically/main.go    | 35 +++++++++
 .../main.go}                                  |  0
 examples/run_matrix_programmatically/main.go  | 75 +++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 examples/create_matrix_programmatically/main.go
 rename examples/{inspect_datanode.go => inspect_datanode/main.go} (100%)
 create mode 100644 examples/run_matrix_programmatically/main.go

diff --git a/examples/create_matrix_programmatically/main.go b/examples/create_matrix_programmatically/main.go
new file mode 100644
index 0000000..64e2fe3
--- /dev/null
+++ b/examples/create_matrix_programmatically/main.go
@@ -0,0 +1,35 @@
+package main
+
+import (
+	"log"
+	"os"
+
+	"github.com/Snider/Borg/pkg/datanode"
+	"github.com/Snider/Borg/pkg/matrix"
+)
+
+func main() {
+	// Create a new DataNode to hold the root filesystem.
+	dn := datanode.New()
+	dn.AddData("hello.txt", []byte("Hello from within the matrix!"))
+
+	// Create a new TerminalIsolationMatrix from the DataNode.
+	m, err := matrix.FromDataNode(dn)
+	if err != nil {
+		log.Fatalf("Failed to create matrix: %v", err)
+	}
+
+	// Serialize the matrix to a tarball.
+	tarball, err := m.ToTar()
+	if err != nil {
+		log.Fatalf("Failed to serialize matrix to tar: %v", err)
+	}
+
+	// Write the tarball to a file.
+	err = os.WriteFile("programmatic.matrix", tarball, 0644)
+	if err != nil {
+		log.Fatalf("Failed to write matrix file: %v", err)
+	}
+
+	log.Println("Successfully created programmatic.matrix")
+}
diff --git a/examples/inspect_datanode.go b/examples/inspect_datanode/main.go
similarity index 100%
rename from examples/inspect_datanode.go
rename to examples/inspect_datanode/main.go
diff --git a/examples/run_matrix_programmatically/main.go b/examples/run_matrix_programmatically/main.go
new file mode 100644
index 0000000..3807cdf
--- /dev/null
+++ b/examples/run_matrix_programmatically/main.go
@@ -0,0 +1,75 @@
+package main
+
+import (
+	"archive/tar"
+	"io"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+)
+
+func main() {
+	// Open the matrix file.
+	matrixFile, err := os.Open("programmatic.matrix")
+	if err != nil {
+		log.Fatalf("Failed to open matrix file (run create_matrix_programmatically first): %v", err)
+	}
+	defer matrixFile.Close()
+
+	// Create a temporary directory to unpack the matrix.
+	tempDir, err := os.MkdirTemp("", "borg-run-example-*")
+	if err != nil {
+		log.Fatalf("Failed to create temporary directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	log.Printf("Unpacking matrix to %s", tempDir)
+
+	// Unpack the tar archive.
+	tr := tar.NewReader(matrixFile)
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break // End of archive
+		}
+		if err != nil {
+			log.Fatalf("Failed to read tar header: %v", err)
+		}
+
+		target := filepath.Join(tempDir, header.Name)
+
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(target, 0755); err != nil {
+				log.Fatalf("Failed to create directory: %v", err)
+			}
+		case tar.TypeReg:
+			outFile, err := os.Create(target)
+			if err != nil {
+				log.Fatalf("Failed to create file: %v", err)
+			}
+			if _, err := io.Copy(outFile, tr); err != nil {
+				log.Fatalf("Failed to write file content: %v", err)
+			}
+			outFile.Close()
+		default:
+			log.Printf("Skipping unsupported type: %c in %s", header.Typeflag, header.Name)
+		}
+	}
+
+	log.Println("Executing matrix with runc...")
+
+	// Execute the matrix using runc.
+	cmd := exec.Command("runc", "run", "borg-container-example")
+	cmd.Dir = tempDir
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	cmd.Stdin = os.Stdin
+
+	if err := cmd.Run(); err != nil {
+		log.Fatalf("Failed to run matrix: %v", err)
+	}
+
+	log.Println("Matrix execution finished.")
+}