Centralize path-safe root joins and atomic file operations

internal/pathsafe/relative_destination_test.go

@@ -2,6 +2,8 @@ package pathsafe
 
 import (
 	"errors"
+	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -41,3 +43,76 @@ func TestNormalizeRelativeDestination(t *testing.T) {
 		})
 	}
 }
+
+func TestJoinSlashRelativeUnderRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr error
+	}{
+		{name: "valid relative", input: "artifacts/session_recap.md", want: filepath.Join(root, "artifacts", "session_recap.md")},
+		{name: "windows separators normalized", input: `artifacts\session_recap.md`, want: filepath.Join(root, "artifacts", "session_recap.md")},
+		{name: "reject empty", input: "", wantErr: ErrRelativePathRequired},
+		{name: "reject absolute", input: "/artifacts/session_recap.md", wantErr: ErrRelativePathAbsolute},
+		{name: "reject traversal", input: "../artifacts/session_recap.md", wantErr: ErrRelativePathEscape},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := JoinSlashRelativeUnderRoot(root, tt.input)
+			if tt.wantErr != nil {
+				if !errors.Is(err, tt.wantErr) {
+					t.Fatalf("JoinSlashRelativeUnderRoot() error = %v, want %v", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("JoinSlashRelativeUnderRoot() error = %v", err)
+			}
+			if got != tt.want {
+				t.Fatalf("JoinSlashRelativeUnderRoot() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSlashRelativeFromRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+	target := filepath.Join(root, "transcripts", "full.json")
+
+	got, err := SlashRelativeFromRoot(root, target)
+	if err != nil {
+		t.Fatalf("SlashRelativeFromRoot() error = %v", err)
+	}
+	if got != "transcripts/full.json" {
+		t.Fatalf("SlashRelativeFromRoot() = %q, want transcripts/full.json", got)
+	}
+
+	got, err = SlashRelativeFromRoot(root, `transcripts\full.json`)
+	if err != nil {
+		t.Fatalf("SlashRelativeFromRoot(relative with windows separators) error = %v", err)
+	}
+	if got != "transcripts/full.json" {
+		t.Fatalf("SlashRelativeFromRoot(relative with windows separators) = %q, want transcripts/full.json", got)
+	}
+}
+
+func TestSlashRelativeFromRootRejectsOutsideRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+	outside := filepath.Join(filepath.Dir(root), "outside", "file.txt")
+
+	_, err := SlashRelativeFromRoot(root, outside)
+	if !errors.Is(err, ErrRelativePathEscape) {
+		t.Fatalf("SlashRelativeFromRoot() error = %v, want %v", err, ErrRelativePathEscape)
+	}
+}
+
+func TestJoinSlashRelativeUnderRootRequiresRoot(t *testing.T) {
+	_, err := JoinSlashRelativeUnderRoot("", "artifacts/session_recap.md")
+	if err == nil || !strings.Contains(err.Error(), "root path is required") {
+		t.Fatalf("JoinSlashRelativeUnderRoot() error = %v, want root-required error", err)
+	}
+}

internal/pathsafe/root_scoped.go

@@ -0,0 +1,58 @@
+package pathsafe
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+// JoinSlashRelativeUnderRoot validates a slash-style relative path and resolves
+// it under root. The returned path uses the host filepath separator.
+func JoinSlashRelativeUnderRoot(root, relative string) (string, error) {
+	rootClean := filepath.Clean(strings.TrimSpace(root))
+	if rootClean == "." || rootClean == "" {
+		return "", fmt.Errorf("root path is required")
+	}
+
+	normalized, err := NormalizeRelativeDestination(relative)
+	if err != nil {
+		return "", err
+	}
+
+	joined := filepath.Clean(filepath.Join(rootClean, filepath.FromSlash(normalized)))
+	rel, err := filepath.Rel(rootClean, joined)
+	if err != nil {
+		return "", fmt.Errorf("resolve relative path under root: %w", err)
+	}
+	if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return "", ErrRelativePathEscape
+	}
+	return joined, nil
+}
+
+// SlashRelativeFromRoot derives a slash-style relative path for target under
+// root. Target may be absolute or relative to root.
+func SlashRelativeFromRoot(root, target string) (string, error) {
+	rootClean := filepath.Clean(strings.TrimSpace(root))
+	if rootClean == "." || rootClean == "" {
+		return "", fmt.Errorf("root path is required")
+	}
+
+	targetClean := filepath.Clean(strings.TrimSpace(target))
+	if targetClean == "." || targetClean == "" {
+		return "", ErrRelativePathRequired
+	}
+	if !filepath.IsAbs(targetClean) {
+		targetClean = filepath.Clean(filepath.Join(rootClean, targetClean))
+	}
+
+	rel, err := filepath.Rel(rootClean, targetClean)
+	if err != nil {
+		return "", fmt.Errorf("derive path relative to root: %w", err)
+	}
+	normalized, err := NormalizeRelativeDestination(filepath.ToSlash(rel))
+	if err != nil {
+		return "", err
+	}
+	return normalized, nil
+}