Files¶

The engine mounts a sandboxed filesystem at the workspace root. All file operations use virtual paths relative to that root, ~ expands to the home directory, and .gitignore / .peggignore rules are respected. Attempting to escape the root returns sdk.ErrOutOfBounds (wrapped as OutOfBoundsError).

Reading¶

ReadFile returns the content with line numbers and metadata:

content, err := eng.ReadFile("src/main.go")
// Path: src/main.go | Hash: 9a2b... | Size: 1820 | Lines: 64
// ---
//      1: package main
// ...

A missing file returns sdk.ErrNotFound. Every read records a content hash used by EditFile's change detection.

Writing¶

out, err := eng.WriteFile("notes.md", []byte("# Notes\n"))
// Path: notes.md | Size: 9 | Hash: 8f3a...
// File written successfully.

Writes are atomic (temp file + rename), create parent directories, and preserve existing file permissions.

Editing¶

EditFile applies a text replacement. The file must have been read first, and its hash must still match — an external change returns sdk.ErrFileChanged and requires a fresh read.

out, err := eng.EditFile("notes.md", "# Notes", "# Updated notes", false)

A read (or write) of the same path satisfies the read-before-edit requirement.

Deleting¶

err := eng.DeleteFile("notes.md")

Listing and stat¶

res, err := eng.ListFiles("src")
// res.Path       = "src"
// res.FileCount  = 12
// res.DirCount   = 2
// res.TotalSize  = 48520
for _, e := range res.Entries {
    fmt.Println(e.Name, e.Path, e.Size, e.IsDir)
}

info, err := eng.StatFile("src/main.go")
// info.Path, info.Name, info.Size, info.IsDir, info.ModTime

ListFiles requires a directory; a missing path returns sdk.ErrNotFound.

Errors¶

Example¶

eng.WriteFile("hello.txt", []byte("hello world"))

got, _ := eng.ReadFile("hello.txt")
eng.EditFile("hello.txt", "hello", "goodbye", false)

list, _ := eng.ListFiles(".")
for _, e := range list.Entries {
    fmt.Println(e.Path)
}