feat(wanda): add Artifact struct to spec for extraction

Define Artifact struct for specifying files to extract from built images:
- src: absolute path inside container (supports glob patterns like "/*.whl")
- dst: relative path in artifacts directory
- optional: if true, missing files warn instead of fail

Includes helper methods for path resolution and validation:
- Validate(): ensures src is absolute, dst is relative, no path traversal
- ResolveSrcs(): resolves glob patterns against container file list
- ResolveDst(): resolves destination within artifacts directory
- CopyIntoDir(): determines if copying into directory vs renaming

Topic: wanda-artifact-spec

Signed-off-by: andrew <andrew@anyscale.com>

Author: andrew-anyscale

wanda/artifact.go

@@ -0,0 +1,103 @@
+package wanda
+
+import (
+	"fmt"
+	"path"
+	"path/filepath"
+	"strings"
+)
+
+// Artifact defines a file or directory to extract from a built image.
+type Artifact struct {
+	// Src is the path inside the container to extract.
+	// Can be a file, directory, or glob pattern (e.g., "/*.whl").
+	// Must be an absolute path. Supports variable expansion.
+	Src string `yaml:"src"`
+
+	// Dst is the destination path relative to the artifacts directory.
+	// If it ends with "/" or src matches multiple files, src is copied
+	// into that directory (preserving original filenames).
+	// Otherwise, src is renamed to dst during copy.
+	// Must be a relative path (no ".." allowed).
+	Dst string `yaml:"dst"`
+
+	// Optional marks this artifact as best-effort.
+	// If true, extraction failure will be logged but won't fail the build.
+	Optional bool `yaml:"optional,omitempty"`
+}
+
+// Validate checks that the artifact paths are safe.
+// Src must be an absolute path (inside the container).
+// Dst must be relative and cannot escape the artifacts directory.
+func (a *Artifact) Validate() error {
+	if !strings.HasPrefix(a.Src, "/") {
+		return fmt.Errorf("artifact src must be absolute path: %q", a.Src)
+	}
+
+	if filepath.IsAbs(a.Dst) {
+		return fmt.Errorf("artifact dst must be relative path: %q", a.Dst)
+	}
+
+	cleaned := filepath.Clean(a.Dst)
+	if strings.HasPrefix(cleaned, "..") || strings.Contains(cleaned, string(filepath.Separator)+"..") {
+		return fmt.Errorf("artifact dst cannot escape artifacts directory: %q", a.Dst)
+	}
+
+	return nil
+}
+
+// HasGlob returns true if the artifact source path contains glob characters.
+func (a *Artifact) HasGlob() bool {
+	return strings.ContainsAny(a.Src, "*?[")
+}
+
+// ResolveSrcs returns the source paths to extract.
+func (a *Artifact) ResolveSrcs(containerFiles []string) []string {
+	if a.HasGlob() {
+		return a.matchFiles(containerFiles)
+	}
+	return []string{a.Src}
+}
+
+// CopyIntoDir returns true if sources should be copied into dst as a directory.
+func (a *Artifact) CopyIntoDir(numSrcs int) bool {
+	return strings.HasSuffix(a.Dst, "/") || numSrcs > 1
+}
+
+// matchFiles returns files that match the artifact's glob pattern.
+func (a *Artifact) matchFiles(files []string) []string {
+	var matches []string
+	for _, f := range files {
+		if matched, _ := path.Match(a.Src, f); matched {
+			matches = append(matches, f)
+		}
+	}
+	return matches
+}
+
+// ResolveDst resolves the destination path for the artifact.
+// Returns an error if the resolved path would escape the artifacts directory.
+func (a *Artifact) ResolveDst(artifactsDir string) (string, error) {
+	if filepath.IsAbs(a.Dst) {
+		return "", fmt.Errorf("artifact dst must be relative path: %q", a.Dst)
+	}
+
+	resolved := filepath.Join(artifactsDir, a.Dst)
+	resolved = filepath.Clean(resolved)
+
+	absArtifactsDir, err := filepath.Abs(artifactsDir)
+	if err != nil {
+		return "", fmt.Errorf("resolve artifacts dir: %w", err)
+	}
+	absResolved, err := filepath.Abs(resolved)
+	if err != nil {
+		return "", fmt.Errorf("resolve dst: %w", err)
+	}
+
+	if !strings.HasPrefix(absResolved, absArtifactsDir+string(filepath.Separator)) &&
+		absResolved != absArtifactsDir {
+		return "", fmt.Errorf("artifact dst escapes artifacts directory: %q", a.Dst)
+	}
+
+	return resolved, nil
+}

wanda/artifact_test.go

@@ -0,0 +1,160 @@
+package wanda
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestArtifact_Validate(t *testing.T) {
+	tests := []struct {
+		name    string
+		src     string
+		dst     string
+		wantErr string
+	}{
+		{"valid absolute src", "/app/file.txt", "output.txt", ""},
+		{"valid glob src", "/*.whl", "wheels/", ""},
+		{"valid nested dst", "/app/file.txt", "subdir/output.txt", ""},
+		{"relative src rejected", "relative/path.txt", "output.txt", "must be absolute"},
+		{"absolute dst rejected", "/app/file.txt", "/absolute/path.txt", "must be relative"},
+		{"dst with .. rejected", "/app/file.txt", "../escape.txt", "cannot escape"},
+		{"dst with nested .. rejected", "/app/file.txt", "subdir/../../escape.txt", "cannot escape"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			a := &Artifact{Src: tt.src, Dst: tt.dst}
+			err := a.Validate()
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Errorf("Validate() unexpected error: %v", err)
+				}
+			} else {
+				if err == nil {
+					t.Errorf("Validate() expected error containing %q, got nil", tt.wantErr)
+				} else if !strings.Contains(err.Error(), tt.wantErr) {
+					t.Errorf("Validate() error = %q, want containing %q", err.Error(), tt.wantErr)
+				}
+			}
+		})
+	}
+}
+
+func TestArtifact_HasGlob(t *testing.T) {
+	tests := []struct {
+		src  string
+		want bool
+	}{
+		{"/app/file.txt", false},
+		{"/app/*.txt", true},
+		{"/app/file?.txt", true},
+		{"/app/[abc].txt", true},
+		{"/*.whl", true},
+		{"/path/to/dir/", false},
+	}
+
+	for _, tt := range tests {
+		a := &Artifact{Src: tt.src}
+		got := a.HasGlob()
+		if got != tt.want {
+			t.Errorf("Artifact{Src: %q}.HasGlob() = %v, want %v", tt.src, got, tt.want)
+		}
+	}
+}
+
+func TestArtifact_ResolveSrcs(t *testing.T) {
+	containerFiles := []string{
+		"/app.whl",
+		"/other.whl",
+		"/readme.txt",
+		"/etc/config",
+		"/build/output.whl",
+	}
+
+	tests := []struct {
+		src  string
+		want []string
+	}{
+		{"/*.whl", []string{"/app.whl", "/other.whl"}},
+		{"/*.txt", []string{"/readme.txt"}},
+		{"/build/*.whl", []string{"/build/output.whl"}},
+		{"/*.exe", nil},
+		{"/app.whl", []string{"/app.whl"}},         // non-glob returns src directly
+		{"/nonexistent", []string{"/nonexistent"}}, // non-glob doesn't check existence
+	}
+
+	for _, tt := range tests {
+		a := &Artifact{Src: tt.src}
+		got := a.ResolveSrcs(containerFiles)
+		if len(got) != len(tt.want) {
+			t.Errorf("Artifact{Src: %q}.ResolveSrcs() = %v, want %v", tt.src, got, tt.want)
+			continue
+		}
+		for i := range got {
+			if got[i] != tt.want[i] {
+				t.Errorf("Artifact{Src: %q}.ResolveSrcs()[%d] = %q, want %q", tt.src, i, got[i], tt.want[i])
+			}
+		}
+	}
+}
+
+func TestArtifact_CopyIntoDir(t *testing.T) {
+	tests := []struct {
+		dst     string
+		numSrcs int
+		want    bool
+	}{
+		{"wheels/", 1, true},  // trailing slash
+		{"wheels/", 2, true},  // trailing slash + multiple
+		{"wheels", 1, false},  // no slash, single file
+		{"wheels", 2, true},   // no slash, multiple files
+		{"out.txt", 1, false}, // single file rename
+	}
+
+	for _, tt := range tests {
+		a := &Artifact{Dst: tt.dst}
+		got := a.CopyIntoDir(tt.numSrcs)
+		if got != tt.want {
+			t.Errorf("Artifact{Dst: %q}.CopyIntoDir(%d) = %v, want %v", tt.dst, tt.numSrcs, got, tt.want)
+		}
+	}
+}
+
+func TestArtifact_ResolveDst(t *testing.T) {
+	artifactsDir := t.TempDir()
+
+	tests := []struct {
+		name    string
+		dst     string
+		want    string
+		wantErr string
+	}{
+		{"simple file", "output.txt", filepath.Join(artifactsDir, "output.txt"), ""},
+		{"subdirectory", "wheels/file.whl", filepath.Join(artifactsDir, "wheels/file.whl"), ""},
+		{"trailing slash", "wheels/", filepath.Join(artifactsDir, "wheels"), ""},
+		{"absolute rejected", "/absolute/path.txt", "", "must be relative"},
+		{"escape rejected", "../escape.txt", "", "escapes artifacts"},
+		{"nested escape rejected", "sub/../../escape.txt", "", "escapes artifacts"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			a := &Artifact{Dst: tt.dst}
+			got, err := a.ResolveDst(artifactsDir)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Errorf("ResolveDst() unexpected error: %v", err)
+				} else if got != tt.want {
+					t.Errorf("ResolveDst() = %q, want %q", got, tt.want)
+				}
+			} else {
+				if err == nil {
+					t.Errorf("ResolveDst() expected error containing %q, got nil", tt.wantErr)
+				} else if !strings.Contains(err.Error(), tt.wantErr) {
+					t.Errorf("ResolveDst() error = %q, want containing %q", err.Error(), tt.wantErr)
+				}
+			}
+		})
+	}
+}

wanda/spec.go

@@ -28,6 +28,9 @@ type Spec struct {
 
 	// DisableCaching disables use of caching.
 	DisableCaching bool `yaml:"disable_caching,omitempty"`
+
+	// Artifacts defines files and directories to extract from the built image.
+	Artifacts []*Artifact `yaml:"artifacts,omitempty"`
 }
 
 func parseSpecFile(f string) (*Spec, error) {
@@ -116,6 +119,21 @@ func stringsExpandVar(slice []string, lookup lookupFunc) []string {
 	return result
 }
 
+func artifactsExpandVar(artifacts []*Artifact, lookup lookupFunc) []*Artifact {
+	if len(artifacts) == 0 {
+		return nil
+	}
+	result := make([]*Artifact, len(artifacts))
+	for i, a := range artifacts {
+		result[i] = &Artifact{
+			Src:      expandVar(a.Src, lookup),
+			Dst:      expandVar(a.Dst, lookup),
+			Optional: a.Optional,
+		}
+	}
+	return result
+}
+
 func (s *Spec) expandVar(lookup lookupFunc) *Spec {
 	result := new(Spec)
 
@@ -127,6 +145,7 @@ func (s *Spec) expandVar(lookup lookupFunc) *Spec {
 	result.BuildArgs = stringsExpandVar(s.BuildArgs, lookup)
 	result.BuildHintArgs = stringsExpandVar(s.BuildHintArgs, lookup)
 	result.DisableCaching = s.DisableCaching
+	result.Artifacts = artifactsExpandVar(s.Artifacts, lookup)
 
 	return result
 }