fix: expand leading ~ in path builtins

Path builtins were inconsistent about tilde expansion. The shell
expands ~, and get_path's full_path did too, but write_file,
read_file, find_paths, and delete_path handed the raw string
straight to the OS - so the same "~/foo" path that worked in a
shell command failed on the adjacent builtin call. get_path was
even self-contradictory: full_path resolved ~ while exists checked
the un-expanded path, so .exists could be false while .full_path
pointed at a real file.

These builtins now expand a leading ~ consistently, matching what
users expect coming from the shell. Expansion is deliberately
narrow: only an exact "~" or a "~/" prefix resolves to home. A
literal name like "~backup" and an unsupported "~user/..." are
left untouched rather than silently misrouted to $HOME/..., which
preserves the prior raw-path behavior for those cases. If the home
dir can't be resolved, the path is left as-is so the failure
surfaces honestly at the OS call instead of becoming "/foo".

Tilde-only expansion is kept separate from absolutization: relative
paths are still passed through unchanged, so behavior only differs
for tilde inputs.

Closes #125

Author: amterp

core/common/files.go

@@ -8,12 +8,23 @@ import (
 	"strings"
 )
 
-func ToAbsolutePath(path string) string {
-	if strings.HasPrefix(path, "~") {
-		home, _ := os.UserHomeDir()          // todo technically should handle err
-		path = filepath.Join(home, path[1:]) // drop the "~"
+// ExpandTilde resolves a leading "~" (i.e. exactly "~" or a "~/" prefix) to the
+// user's home directory. Anything else is returned unchanged: "~user" (another
+// user's home) is not supported and is left as a literal path rather than
+// silently misexpanded, and a path like "~backup" is treated as a literal name.
+// If the home dir can't be resolved, the path is returned untouched so the
+// failure surfaces honestly at the os call site.
+func ExpandTilde(path string) string {
+	if path == "~" || strings.HasPrefix(path, "~/") {
+		if home, err := os.UserHomeDir(); err == nil {
+			path = filepath.Join(home, path[1:]) // drop the "~"
+		}
 	}
-	abs, _ := filepath.Abs(path) // todo handle err?
+	return path
+}
+
+func ToAbsolutePath(path string) string {
+	abs, _ := filepath.Abs(ExpandTilde(path)) // todo handle err?
 	return abs
 }
 

core/common/files_test.go

@@ -0,0 +1,48 @@
+package com
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestExpandTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Fatalf("could not resolve home dir: %v", err)
+	}
+
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"bare tilde", "~", home},
+		{"tilde with subpath", "~/foo/bar.txt", filepath.Join(home, "foo/bar.txt")},
+		{"no tilde absolute", "/etc/hosts", "/etc/hosts"},
+		{"no tilde relative", "foo/bar.txt", "foo/bar.txt"},
+		{"tilde mid-string untouched", "/foo/~/bar", "/foo/~/bar"},
+		{"tilde literal name untouched", "~backup", "~backup"},
+		{"tilde user untouched", "~bob/config.txt", "~bob/config.txt"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := ExpandTilde(tt.in); got != tt.want {
+				t.Errorf("ExpandTilde(%q) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestToAbsolutePathExpandsTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Fatalf("could not resolve home dir: %v", err)
+	}
+
+	want := filepath.Join(home, "foo/bar.txt")
+	if got := ToAbsolutePath("~/foo/bar.txt"); got != want {
+		t.Errorf("ToAbsolutePath(\"~/foo/bar.txt\") = %q, want %q", got, want)
+	}
+}

core/funcs.go

@@ -790,7 +790,7 @@ func init() {
 
 				radMap.SetPrimitiveStr(constFullPath, NormalizePath(absPath))
 
-				stat, err1 := os.Stat(path)
+				stat, err1 := os.Stat(absPath)
 				if err1 == nil {
 					radMap.SetPrimitiveStr(constBaseName, stat.Name())
 					radMap.SetPrimitiveStr(constPermissions, stat.Mode().Perm().String())
@@ -835,7 +835,7 @@ func init() {
 						relativeMode, []string{constTarget, constCwd, constAbsolute})
 				}
 
-				absTarget, err := filepath.Abs(path) // todo should be abstracted away for testing
+				absTarget, err := filepath.Abs(com.ExpandTilde(path)) // todo should be abstracted away for testing
 				if err != nil {
 					return f.ReturnErrf(rl.ErrGenericRuntime, "Error resolving absolute path for target: %v", err)
 				}
@@ -901,7 +901,7 @@ func init() {
 			// todo should offer args like find_paths
 			Name: FUNC_DELETE_PATH,
 			Execute: func(f FuncInvocation) RadValue {
-				path := f.GetStr("_path").Plain()
+				path := com.ExpandTilde(f.GetStr("_path").Plain())
 				deleted := false
 
 				if _, err := os.Stat(path); err == nil {
@@ -1119,7 +1119,7 @@ func init() {
 			//   - tail              # Last N bytes
 			Name: FUNC_READ_FILE,
 			Execute: func(f FuncInvocation) RadValue {
-				path := f.GetStr("_path").Plain()
+				path := com.ExpandTilde(f.GetStr("_path").Plain())
 				mode := f.GetStr("mode").Plain()
 
 				data, err := os.ReadFile(path)
@@ -1158,7 +1158,7 @@ func init() {
 		{
 			Name: FUNC_WRITE_FILE,
 			Execute: func(f FuncInvocation) RadValue {
-				path := f.GetStr("_path").Plain()
+				path := com.ExpandTilde(f.GetStr("_path").Plain())
 				content := f.GetStr("_content").Plain()
 				appendFlag := f.GetBool("append")
 

core/testing/func_path_tilde_unix_test.go

@@ -0,0 +1,72 @@
+//go:build unix
+
+package testing
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// Issue 125: path builtins should expand a leading "~" consistently, matching
+// shell behavior. These tests point $HOME at a temp dir (os.UserHomeDir reads
+// $HOME on unix) so "~" resolves there without touching the real home.
+
+func Test_PathTilde_WriteReadDeleteRoundTrip(t *testing.T) {
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	script := `
+w = write_file("~/issue125.txt", "hi there")
+print(w.path)
+print(read_file("~/issue125.txt").content)
+print(delete_path("~/issue125.txt"))
+`
+	setupAndRunCode(t, script, "--color=never")
+	expected := fmt.Sprintf("%s/issue125.txt\nhi there\ntrue\n", filepath.ToSlash(tmpHome))
+	assertOnlyOutput(t, stdOutBuffer, expected)
+	assertNoErrors(t)
+
+	if _, err := os.Stat(filepath.Join(tmpHome, "issue125.txt")); !os.IsNotExist(err) {
+		t.Errorf("expected file to be deleted, stat err = %v", err)
+	}
+}
+
+// The headline inconsistency from the issue: get_path("~/...").exists was false
+// even when full_path pointed at a real file.
+func Test_PathTilde_GetPathExists(t *testing.T) {
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	target := filepath.Join(tmpHome, "exists_check.txt")
+	if err := os.WriteFile(target, []byte("x"), 0644); err != nil {
+		t.Fatalf("failed to seed file: %v", err)
+	}
+
+	script := `
+p = get_path("~/exists_check.txt")
+print(p.exists)
+print(p.full_path)
+`
+	setupAndRunCode(t, script, "--color=never")
+	expected := fmt.Sprintf("true\n%s/exists_check.txt\n", filepath.ToSlash(tmpHome))
+	assertOnlyOutput(t, stdOutBuffer, expected)
+	assertNoErrors(t)
+}
+
+func Test_PathTilde_FindPaths(t *testing.T) {
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	if err := os.WriteFile(filepath.Join(tmpHome, "a.txt"), []byte("a"), 0644); err != nil {
+		t.Fatalf("failed to seed file: %v", err)
+	}
+
+	script := `
+print(find_paths("~"))
+`
+	setupAndRunCode(t, script, "--color=never")
+	assertOnlyOutput(t, stdOutBuffer, "[ \"a.txt\" ]\n")
+	assertNoErrors(t)
+}

docs-web/docs/reference/functions.md

@@ -755,6 +755,8 @@ delete_path("directory/")       // -> true (if directory existed and was deleted
 
 Returns `true` if the path was successfully deleted, `false` if it didn't exist or couldn't be deleted.
 
+A leading `~` in `_path` is expanded to your home directory.
+
 ### find_paths
 
 Returns a list of all paths under a directory.
@@ -788,6 +790,8 @@ paths = find_paths("src/", relative="absolute")
 - `"cwd"` - Relative to current directory
 - `"absolute"` - Full absolute paths
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Examples:**
 
 ### input
@@ -1001,6 +1005,8 @@ if not result.success:
 
 In text mode, decodes as UTF-8 and returns a string. In bytes mode, returns a list of integers.
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Return map contains:**
 
 - `size_bytes: int` - File size in bytes
@@ -1056,6 +1062,8 @@ if err:
 
 By default overwrites the file. Use `append=true` to append to existing content.
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Return map contains:**
 
 - `bytes_written: int` - Number of bytes written
@@ -2235,7 +2243,7 @@ if info.exists:
 **Always returns:**
 
 - `exists: bool` - Whether the path exists
-- `full_path: str` - Absolute path
+- `full_path: str` - Absolute path (a leading `~` in `_path` is expanded to your home directory)
 
 **When path exists, also returns:**
 

docs/funcs/delete_path.md

@@ -21,3 +21,5 @@ io
 ## Notes
 
 Returns `true` if the path was successfully deleted, `false` if it didn't exist or couldn't be deleted.
+
+A leading `~` in `_path` is expanded to your home directory.

docs/funcs/find_paths.md

@@ -39,4 +39,6 @@ io
 - `"cwd"` - Relative to current directory
 - `"absolute"` - Full absolute paths
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Examples:**

docs/funcs/get_path.md

@@ -32,7 +32,7 @@ system
 **Always returns:**
 
 - `exists: bool` - Whether the path exists
-- `full_path: str` - Absolute path
+- `full_path: str` - Absolute path (a leading `~` in `_path` is expanded to your home directory)
 
 **When path exists, also returns:**
 

docs/funcs/read_file.md

@@ -40,6 +40,8 @@ io
 
 In text mode, decodes as UTF-8 and returns a string. In bytes mode, returns a list of integers.
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Return map contains:**
 
 - `size_bytes: int` - File size in bytes

docs/funcs/write_file.md

@@ -38,6 +38,8 @@ io
 
 By default overwrites the file. Use `append=true` to append to existing content.
 
+A leading `~` in `_path` is expanded to your home directory.
+
 **Return map contains:**
 
 - `bytes_written: int` - Number of bytes written