chore: bump version to 4.5.0

Bug fixes:
- Fix inverted pager detection logic (returned error instead of path)
- Fix repo.Clone ignoring destination directory parameter
- Fix sheet loading using append on pre-sized slices
- Clean up partial files on copy failure
- Trim whitespace from editor config

Security:
- Add path traversal protection for cheatsheet names

Performance:
- Move regex compilation outside search loop
- Replace string concatenation with strings.Join in search

Build:
- Remove go:generate; embed config and usage as string literals
- Parallelize release builds
- Add fuzz testing infrastructure

Testing:
- Improve test coverage from 38.9% to 50.2%
- Add fuzz tests for search, filter, tags, and validation

Documentation:
- Fix inaccurate code examples in HACKING.md
- Add missing --conf and --all options to man page
- Add ADRs for path traversal, env parsing, and search parallelization
- Update CONTRIBUTING.md to reflect project policy

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

internal/cheatpath/cheatpath.go

@@ -2,6 +2,8 @@
 // management.
 package cheatpath
 
+import "fmt"
+
 // Cheatpath encapsulates cheatsheet path information
 type Cheatpath struct {
 	Name     string   `yaml:"name"`
@@ -9,3 +11,18 @@ type Cheatpath struct {
 	ReadOnly bool     `yaml:"readonly"`
 	Tags     []string `yaml:"tags"`
 }
+
+// Validate ensures that the Cheatpath is valid
+func (c Cheatpath) Validate() error {
+	// Check that name is not empty
+	if c.Name == "" {
+		return fmt.Errorf("cheatpath name cannot be empty")
+	}
+
+	// Check that path is not empty
+	if c.Path == "" {
+		return fmt.Errorf("cheatpath path cannot be empty")
+	}
+
+	return nil
+}

internal/cheatpath/cheatpath_test.go

@@ -0,0 +1,113 @@
+package cheatpath
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestCheatpathValidate(t *testing.T) {
+	tests := []struct {
+		name      string
+		cheatpath Cheatpath
+		wantErr   bool
+		errMsg    string
+	}{
+		{
+			name: "valid cheatpath",
+			cheatpath: Cheatpath{
+				Name:     "personal",
+				Path:     "/home/user/.config/cheat/personal",
+				ReadOnly: false,
+				Tags:     []string{"personal"},
+			},
+			wantErr: false,
+		},
+		{
+			name: "empty name",
+			cheatpath: Cheatpath{
+				Name:     "",
+				Path:     "/home/user/.config/cheat/personal",
+				ReadOnly: false,
+				Tags:     []string{"personal"},
+			},
+			wantErr: true,
+			errMsg:  "cheatpath name cannot be empty",
+		},
+		{
+			name: "empty path",
+			cheatpath: Cheatpath{
+				Name:     "personal",
+				Path:     "",
+				ReadOnly: false,
+				Tags:     []string{"personal"},
+			},
+			wantErr: true,
+			errMsg:  "cheatpath path cannot be empty",
+		},
+		{
+			name: "both empty",
+			cheatpath: Cheatpath{
+				Name:     "",
+				Path:     "",
+				ReadOnly: true,
+				Tags:     nil,
+			},
+			wantErr: true,
+			errMsg:  "cheatpath name cannot be empty",
+		},
+		{
+			name: "minimal valid",
+			cheatpath: Cheatpath{
+				Name: "x",
+				Path: "/",
+			},
+			wantErr: false,
+		},
+		{
+			name: "with readonly and tags",
+			cheatpath: Cheatpath{
+				Name:     "community",
+				Path:     "/usr/share/cheat",
+				ReadOnly: true,
+				Tags:     []string{"community", "shared", "readonly"},
+			},
+			wantErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.cheatpath.Validate()
+			if (err != nil) != tt.wantErr {
+				t.Errorf("Validate() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if err != nil && tt.errMsg != "" && !strings.Contains(err.Error(), tt.errMsg) {
+				t.Errorf("Validate() error = %v, want error containing %q", err, tt.errMsg)
+			}
+		})
+	}
+}
+
+func TestCheatpathStruct(t *testing.T) {
+	// Test that the struct fields work as expected
+	cp := Cheatpath{
+		Name:     "test",
+		Path:     "/test/path",
+		ReadOnly: true,
+		Tags:     []string{"tag1", "tag2"},
+	}
+
+	if cp.Name != "test" {
+		t.Errorf("expected Name to be 'test', got %q", cp.Name)
+	}
+	if cp.Path != "/test/path" {
+		t.Errorf("expected Path to be '/test/path', got %q", cp.Path)
+	}
+	if !cp.ReadOnly {
+		t.Error("expected ReadOnly to be true")
+	}
+	if len(cp.Tags) != 2 || cp.Tags[0] != "tag1" || cp.Tags[1] != "tag2" {
+		t.Errorf("expected Tags to be [tag1 tag2], got %v", cp.Tags)
+	}
+}

internal/cheatpath/doc.go

@@ -0,0 +1,63 @@
+// Package cheatpath manages collections of cheat sheets organized in filesystem directories.
+//
+// A Cheatpath represents a directory containing cheat sheets, with associated
+// metadata such as tags and read-only status. Multiple cheatpaths can be
+// configured to organize sheets from different sources (personal, community, work, etc.).
+//
+// # Cheatpath Structure
+//
+// Each cheatpath has:
+//   - Name: A friendly identifier (e.g., "personal", "community")
+//   - Path: The filesystem path to the directory
+//   - Tags: Tags automatically applied to all sheets in this path
+//   - ReadOnly: Whether sheets in this path can be modified
+//
+// Example configuration:
+//
+//	cheatpaths:
+//	  - name: personal
+//	    path: ~/cheat
+//	    tags: []
+//	    readonly: false
+//	  - name: community
+//	    path: ~/cheat/community
+//	    tags: [community]
+//	    readonly: true
+//
+// # Directory-Scoped Cheatpaths
+//
+// The package supports directory-scoped cheatpaths via `.cheat` directories.
+// When running cheat from a directory containing a `.cheat` subdirectory,
+// that directory is temporarily added to the available cheatpaths.
+//
+// # Precedence and Overrides
+//
+// When multiple cheatpaths contain a sheet with the same name, the sheet
+// from the most "local" cheatpath takes precedence. This allows users to
+// override community sheets with personal versions.
+//
+// Key Functions
+//
+//   - Filter: Filters cheatpaths by name
+//   - Validate: Ensures cheatpath configuration is valid
+//   - Writeable: Returns the first writeable cheatpath
+//
+// Example Usage
+//
+//	// Filter cheatpaths to only "personal"
+//	filtered, err := cheatpath.Filter(paths, "personal")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//
+//	// Find a writeable cheatpath
+//	writeable, err := cheatpath.Writeable(paths)
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//
+//	// Validate cheatpath configuration
+//	if err := cheatpath.Validate(paths); err != nil {
+//	    log.Fatal(err)
+//	}
+package cheatpath

internal/cheatpath/validate.go

@@ -2,16 +2,38 @@ package cheatpath
 
 import (
 	"fmt"
+	"path/filepath"
+	"strings"
 )
 
-// Validate returns an error if the cheatpath is invalid
-func (c *Cheatpath) Validate() error {
-
-	if c.Name == "" {
-		return fmt.Errorf("invalid cheatpath: name must be specified")
+// ValidateSheetName ensures that a cheatsheet name does not contain
+// directory traversal sequences or other potentially dangerous patterns.
+func ValidateSheetName(name string) error {
+	// Reject empty names
+	if name == "" {
+		return fmt.Errorf("cheatsheet name cannot be empty")
 	}
-	if c.Path == "" {
-		return fmt.Errorf("invalid cheatpath: path must be specified")
+
+	// Reject names containing directory traversal
+	if strings.Contains(name, "..") {
+		return fmt.Errorf("cheatsheet name cannot contain '..'")
+	}
+
+	// Reject absolute paths
+	if filepath.IsAbs(name) {
+		return fmt.Errorf("cheatsheet name cannot be an absolute path")
+	}
+
+	// Reject names that start with ~ (home directory expansion)
+	if strings.HasPrefix(name, "~") {
+		return fmt.Errorf("cheatsheet name cannot start with '~'")
+	}
+
+	// Reject hidden files (files that start with a dot)
+	// We don't display hidden files, so we shouldn't create them
+	filename := filepath.Base(name)
+	if strings.HasPrefix(filename, ".") {
+		return fmt.Errorf("cheatsheet name cannot start with '.' (hidden files are not supported)")
 	}
 
 	return nil

internal/cheatpath/validate_fuzz_test.go

@@ -0,0 +1,169 @@
+package cheatpath
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+)
+
+// FuzzValidateSheetName tests the ValidateSheetName function with fuzzing
+// to ensure it properly prevents path traversal and other security issues
+func FuzzValidateSheetName(f *testing.F) {
+	// Add seed corpus with various valid and malicious inputs
+	// Valid names
+	f.Add("docker")
+	f.Add("docker/compose")
+	f.Add("lang/go/slice")
+	f.Add("my-cheat_sheet")
+	f.Add("file.txt")
+	f.Add("a")
+	f.Add("123")
+
+	// Path traversal attempts
+	f.Add("..")
+	f.Add("../etc/passwd")
+	f.Add("foo/../bar")
+	f.Add("foo/../../etc/passwd")
+	f.Add("..\\windows\\system32")
+	f.Add("foo\\..\\..\\windows")
+
+	// Encoded traversal attempts
+	f.Add("%2e%2e")
+	f.Add("%2e%2e%2f")
+	f.Add("..%2f")
+	f.Add("%2e.")
+	f.Add(".%2e")
+	f.Add("\x2e\x2e")
+	f.Add("\\x2e\\x2e")
+
+	// Unicode and special characters
+	f.Add("€test")
+	f.Add("test€")
+	f.Add("中文")
+	f.Add("🎉emoji")
+	f.Add("\x00null")
+	f.Add("test\x00null")
+	f.Add("\nnewline")
+	f.Add("test\ttab")
+
+	// Absolute paths
+	f.Add("/etc/passwd")
+	f.Add("C:\\Windows\\System32")
+	f.Add("\\\\server\\share")
+	f.Add("//server/share")
+
+	// Home directory
+	f.Add("~")
+	f.Add("~/config")
+	f.Add("~user/file")
+
+	// Hidden files
+	f.Add(".hidden")
+	f.Add("dir/.hidden")
+	f.Add(".git/config")
+
+	// Edge cases
+	f.Add("")
+	f.Add(" ")
+	f.Add("  ")
+	f.Add("\t")
+	f.Add(".")
+	f.Add("./")
+	f.Add("./file")
+	f.Add(".../")
+	f.Add("...")
+	f.Add("....")
+
+	// Very long names
+	f.Add(strings.Repeat("a", 255))
+	f.Add(strings.Repeat("a/", 100) + "file")
+	f.Add(strings.Repeat("../", 50) + "etc/passwd")
+
+	f.Fuzz(func(t *testing.T, input string) {
+		// The function should never panic
+		func() {
+			defer func() {
+				if r := recover(); r != nil {
+					t.Errorf("ValidateSheetName panicked with input %q: %v", input, r)
+				}
+			}()
+
+			err := ValidateSheetName(input)
+
+			// Security invariants that must always hold
+			if err == nil {
+				// If validation passed, verify security properties
+
+				// Should not contain ".." for path traversal
+				if strings.Contains(input, "..") {
+					t.Errorf("validation passed but input contains '..': %q", input)
+				}
+
+				// Should not be empty
+				if input == "" {
+					t.Error("validation passed for empty input")
+				}
+
+				// Should not start with ~ (home directory)
+				if strings.HasPrefix(input, "~") {
+					t.Errorf("validation passed but input starts with '~': %q", input)
+				}
+
+				// Base filename should not start with .
+				parts := strings.Split(input, "/")
+				if len(parts) > 0 {
+					lastPart := parts[len(parts)-1]
+					if strings.HasPrefix(lastPart, ".") && lastPart != "." {
+						t.Errorf("validation passed but filename starts with '.': %q", input)
+					}
+				}
+
+				// Additional check: result should be valid UTF-8
+				if !utf8.ValidString(input) {
+					// While the function doesn't explicitly check this,
+					// we want to ensure it handles invalid UTF-8 gracefully
+					t.Logf("validation passed for invalid UTF-8: %q", input)
+				}
+			}
+		}()
+	})
+}
+
+// FuzzValidateSheetNamePathTraversal specifically targets path traversal bypasses
+func FuzzValidateSheetNamePathTraversal(f *testing.F) {
+	// Seed corpus focusing on path traversal variations
+	f.Add("..", "/", "")
+	f.Add("", "..", "/")
+	f.Add("a", "b", "c")
+
+	f.Fuzz(func(t *testing.T, prefix string, middle string, suffix string) {
+		// Construct various path traversal attempts
+		inputs := []string{
+			prefix + ".." + suffix,
+			prefix + "/.." + suffix,
+			prefix + "\\.." + suffix,
+			prefix + middle + ".." + suffix,
+			prefix + "../" + middle + suffix,
+			prefix + "..%2f" + suffix,
+			prefix + "%2e%2e" + suffix,
+			prefix + "%2e%2e%2f" + suffix,
+		}
+
+		for _, input := range inputs {
+			func() {
+				defer func() {
+					if r := recover(); r != nil {
+						t.Errorf("ValidateSheetName panicked with constructed input %q: %v", input, r)
+					}
+				}()
+
+				err := ValidateSheetName(input)
+
+				// If the input contains literal "..", it must be rejected
+				if strings.Contains(input, "..") && err == nil {
+					t.Errorf("validation incorrectly passed for input containing '..': %q", input)
+				}
+			}()
+		}
+	})
+}

internal/cheatpath/validate_test.go

@@ -1,56 +1,106 @@
 package cheatpath
 
 import (
+	"strings"
 	"testing"
 )
 
-// TestValidateValid asserts that valid cheatpaths validate successfully
-func TestValidateValid(t *testing.T) {
-
-	// initialize a valid cheatpath
-	cheatpath := Cheatpath{
-		Name:     "foo",
-		Path:     "/foo",
-		ReadOnly: false,
-		Tags:     []string{},
+func TestValidateSheetName(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		wantErr bool
+		errMsg  string
+	}{
+		// Valid names
+		{
+			name:    "simple name",
+			input:   "docker",
+			wantErr: false,
+		},
+		{
+			name:    "name with slash",
+			input:   "docker/compose",
+			wantErr: false,
+		},
+		{
+			name:    "name with multiple slashes",
+			input:   "lang/go/slice",
+			wantErr: false,
+		},
+		{
+			name:    "name with dash and underscore",
+			input:   "my-cheat_sheet",
+			wantErr: false,
+		},
+		// Invalid names
+		{
+			name:    "empty name",
+			input:   "",
+			wantErr: true,
+			errMsg:  "empty",
+		},
+		{
+			name:    "parent directory traversal",
+			input:   "../etc/passwd",
+			wantErr: true,
+			errMsg:  "'..'",
+		},
+		{
+			name:    "complex traversal",
+			input:   "foo/../../etc/passwd",
+			wantErr: true,
+			errMsg:  "'..'",
+		},
+		{
+			name:    "absolute path",
+			input:   "/etc/passwd",
+			wantErr: true,
+			errMsg:  "absolute",
+		},
+		{
+			name:    "home directory",
+			input:   "~/secrets",
+			wantErr: true,
+			errMsg:  "'~'",
+		},
+		{
+			name:    "just dots",
+			input:   "..",
+			wantErr: true,
+			errMsg:  "'..'",
+		},
+		{
+			name:    "hidden file not allowed",
+			input:   ".hidden",
+			wantErr: true,
+			errMsg:  "cannot start with '.'",
+		},
+		{
+			name:    "current dir is ok",
+			input:   "./current",
+			wantErr: false,
+		},
+		{
+			name:    "nested hidden file not allowed",
+			input:   "config/.gitignore",
+			wantErr: true,
+			errMsg:  "cannot start with '.'",
+		},
 	}
 
-	// assert that no errors are returned
-	if err := cheatpath.Validate(); err != nil {
-		t.Errorf("failed to validate valid cheatpath: %v", err)
-	}
-}
-
-// TestValidateMissingName asserts that paths that are missing a name fail to
-// validate
-func TestValidateMissingName(t *testing.T) {
-
-	// initialize a valid cheatpath
-	cheatpath := Cheatpath{
-		Path:     "/foo",
-		ReadOnly: false,
-		Tags:     []string{},
-	}
-
-	// assert that no errors are returned
-	if err := cheatpath.Validate(); err == nil {
-		t.Errorf("failed to invalidate cheatpath without name")
-	}
-}
-
-// TestValidateMissingPath asserts that paths that are missing a path fail to
-// validate
-func TestValidateMissingPath(t *testing.T) {
-
-	// initialize a valid cheatpath
-	cheatpath := Cheatpath{
-		Name:     "foo",
-		ReadOnly: false,
-		Tags:     []string{},
-	}
-
-	// assert that no errors are returned
-	if err := cheatpath.Validate(); err == nil {
-		t.Errorf("failed to invalidate cheatpath without path")
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateSheetName(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ValidateName(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
+				return
+			}
+			if err != nil && tt.errMsg != "" {
+				if !strings.Contains(err.Error(), tt.errMsg) {
+					t.Errorf("ValidateName(%q) error = %v, want error containing %q", tt.input, err, tt.errMsg)
+				}
+			}
+		})
 	}
 }