Implement find builtin command

SHELL_FEATURES.md

@@ -12,6 +12,7 @@ Blocked features are rejected before execution with exit code 2.
 - ✅ `echo [-neE] [ARG]...` — write arguments to stdout; `-n` suppresses trailing newline, `-e` enables backslash escapes, `-E` disables them (default)
 - ✅ `exit [N]` — exit the shell with status N (default 0)
 - ✅ `false` — return exit code 1
+- ✅ `find [-L] [PATH...] [EXPRESSION]` — search for files in a directory hierarchy; supports `-name`, `-iname`, `-path`, `-ipath`, `-type`, `-size`, `-empty`, `-newer`, `-mtime`, `-mmin`, `-maxdepth`, `-mindepth`, `-print`, `-print0`, `-prune`, logical operators (`!`, `-a`, `-o`, `()`); blocks `-exec`, `-delete`, `-regex` for sandbox safety
 - ✅ `grep [-EFGivclLnHhoqsxw] [-e PATTERN] [-m NUM] [-A NUM] [-B NUM] [-C NUM] PATTERN [FILE]...` — print lines that match patterns; uses RE2 regex engine (linear-time, no backtracking)
 - ✅ `head [-n N|-c N] [-q|-v] [FILE]...` — output the first part of files (default: first 10 lines); `-z`/`--zero-terminated` and `--follow` are rejected
 - ✅ `sort [-rnubfds] [-k KEYDEF] [-t SEP] [-c|-C] [FILE]...` — sort lines of text files; `-o`, `--compress-program`, and `-T` are rejected (filesystem write / exec)

allowedpaths/portable_unix.go

@@ -19,6 +19,16 @@ func IsErrIsDirectory(err error) bool {
 	return errors.Is(err, syscall.EISDIR)
 }
 
+// FileIdentity extracts canonical file identity (dev+inode) from FileInfo.
+// On Unix, this is extracted directly from Stat_t via info.Sys().
+func FileIdentity(_ string, info fs.FileInfo, _ *Sandbox) (uint64, uint64, bool) {
+	st, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, 0, false
+	}
+	return uint64(st.Dev), uint64(st.Ino), true
+}
+
 // effectiveHasPerm checks whether the current process has the requested
 // permission (writeMask or execMask, each a 3-bit pattern like 0222 or 0111)
 // by inspecting the file's owner/group/other permission class that applies to

allowedpaths/portable_windows.go

@@ -8,6 +8,7 @@ package allowedpaths
 import (
 	"errors"
 	"io/fs"
+	"os"
 	"syscall"
 )
 
@@ -21,6 +22,28 @@ func IsErrIsDirectory(err error) bool {
 	return false
 }
 
+// FileIdentity extracts canonical file identity on Windows using
+// GetFileInformationByHandle (volume serial + file index).
+// The path and sandbox are needed to open the file through the sandbox.
+func FileIdentity(absPath string, _ fs.FileInfo, sandbox *Sandbox) (uint64, uint64, bool) {
+	root, relPath, ok := sandbox.resolve(absPath)
+	if !ok {
+		return 0, 0, false
+	}
+	f, err := root.OpenFile(relPath, os.O_RDONLY, 0)
+	if err != nil {
+		return 0, 0, false
+	}
+	defer f.Close()
+
+	h := syscall.Handle(f.Fd())
+	var d syscall.ByHandleFileInformation
+	if err := syscall.GetFileInformationByHandle(h, &d); err != nil {
+		return 0, 0, false
+	}
+	return uint64(d.VolumeSerialNumber), uint64(d.FileIndexHigh)<<32 | uint64(d.FileIndexLow), true
+}
+
 // effectiveHasPerm checks whether the current process has the requested
 // permission on Windows.  Windows does not use Unix UID/GID permission classes,
 // so we fall back to checking any-class bits (0222 / 0111) as before.

allowedpaths/sandbox.go

@@ -242,6 +242,47 @@ func (s *Sandbox) readDirN(path string, cwd string, maxEntries int) ([]fs.DirEnt
 	return entries, nil
 }
 
+// OpenDir opens a directory within the sandbox for incremental reading
+// via ReadDir(n). The caller must close the returned handle when done.
+// Returns fs.ReadDirFile to expose only read-only directory methods.
+func (s *Sandbox) OpenDir(path string, cwd string) (fs.ReadDirFile, error) {
+	absPath := toAbs(path, cwd)
+
+	root, relPath, ok := s.resolve(absPath)
+	if !ok {
+		return nil, &os.PathError{Op: "opendir", Path: path, Err: os.ErrPermission}
+	}
+
+	f, err := root.Open(relPath)
+	if err != nil {
+		return nil, PortablePathError(err)
+	}
+	return f, nil
+}
+
+// IsDirEmpty checks whether a directory is empty by reading at most one
+// entry. More efficient than reading all entries when only emptiness
+// needs to be determined.
+func (s *Sandbox) IsDirEmpty(path string, cwd string) (bool, error) {
+	absPath := toAbs(path, cwd)
+
+	root, relPath, ok := s.resolve(absPath)
+	if !ok {
+		return false, &os.PathError{Op: "readdir", Path: path, Err: os.ErrPermission}
+	}
+
+	f, err := root.Open(relPath)
+	if err != nil {
+		return false, PortablePathError(err)
+	}
+	defer f.Close()
+	entries, err := f.ReadDir(1)
+	if err != nil && err != io.EOF {
+		return false, PortablePathError(err)
+	}
+	return len(entries) == 0, nil
+}
+
 // ReadDirLimited reads directory entries, skipping the first offset entries
 // and returning up to maxRead entries sorted by name within the read window.
 // Returns (entries, truncated, error). When truncated is true, the directory

allowedsymbols/symbols_allowedpaths.go

@@ -17,39 +17,43 @@ package allowedsymbols
 //
 // The permanently banned packages (reflect, unsafe) apply here too.
 var allowedpathsAllowedSymbols = []string{
-	"errors.As",               // error type assertion; pure function, no I/O.
-	"errors.Is",               // error comparison; pure function, no I/O.
-	"errors.New",              // creates a simple error value; pure function, no I/O.
-	"fmt.Errorf",              // formatted error creation; pure function, no I/O.
-	"io.EOF",                  // sentinel error value; pure constant.
-	"io.ReadWriteCloser",      // combined interface type; no side effects.
-	"io/fs.DirEntry",          // interface type for directory entries; no side effects.
-	"io/fs.ErrExist",          // sentinel error for "already exists"; pure constant.
-	"io/fs.ErrNotExist",       // sentinel error for "does not exist"; pure constant.
-	"io/fs.ErrPermission",     // sentinel error for permission denied; pure constant.
-	"io/fs.FileInfo",          // interface type for file metadata; no side effects.
-	"io/fs.FileMode",          // file permission bits type; pure type.
-	"os.DevNull",              // platform null device path constant; pure constant.
-	"os.ErrPermission",        // sentinel error for permission denied; pure constant.
-	"os.FileMode",             // file permission bits type; pure type.
-	"os.Getgid",               // returns the numeric group id of the caller; read-only syscall.
-	"os.Getgroups",            // returns supplementary group ids; read-only syscall.
-	"os.Getuid",               // returns the numeric user id of the caller; read-only syscall.
-	"os.O_RDONLY",             // read-only file flag constant; pure constant.
-	"os.OpenRoot",             // opens a directory as a root for sandboxed file access; needed for sandbox.
-	"os.PathError",            // error type wrapping path and operation; pure type.
-	"os.Root",                 // sandboxed directory root type; core of the filesystem sandbox.
-	"os.Stat",                 // returns file info for a path; needed for sandbox path validation.
-	"path/filepath.Abs",       // returns absolute path; pure path computation.
-	"path/filepath.IsAbs",     // checks if path is absolute; pure function, no I/O.
-	"path/filepath.Join",      // joins path elements; pure function, no I/O.
-	"path/filepath.Rel",       // returns relative path; pure path computation.
-	"path/filepath.Separator", // OS path separator constant; pure constant.
-	"slices.SortFunc",         // sorts a slice with a comparison function; pure function, no I/O.
-	"strings.Compare",         // compares two strings lexicographically; pure function, no I/O.
-	"strings.EqualFold",       // case-insensitive string comparison; pure function, no I/O.
-	"strings.HasPrefix",       // pure function for prefix matching; no I/O.
-	"syscall.EISDIR",          // "is a directory" errno constant; pure constant.
-	"syscall.Errno",           // system call error number type; pure type.
-	"syscall.Stat_t",          // file stat structure type; pure type for Unix file metadata.
+	"errors.As",                          // error type assertion; pure function, no I/O.
+	"errors.Is",                          // error comparison; pure function, no I/O.
+	"errors.New",                         // creates a simple error value; pure function, no I/O.
+	"fmt.Errorf",                         // formatted error creation; pure function, no I/O.
+	"io.EOF",                             // sentinel error value; pure constant.
+	"io.ReadWriteCloser",                 // combined interface type; no side effects.
+	"io/fs.DirEntry",                     // interface type for directory entries; no side effects.
+	"io/fs.ErrExist",                     // sentinel error for "already exists"; pure constant.
+	"io/fs.ErrNotExist",                  // sentinel error for "does not exist"; pure constant.
+	"io/fs.ErrPermission",                // sentinel error for permission denied; pure constant.
+	"io/fs.FileInfo",                     // interface type for file metadata; no side effects.
+	"io/fs.FileMode",                     // file permission bits type; pure type.
+	"io/fs.ReadDirFile",                  // read-only directory handle interface; no write capability.
+	"os.DevNull",                         // platform null device path constant; pure constant.
+	"os.ErrPermission",                   // sentinel error for permission denied; pure constant.
+	"os.FileMode",                        // file permission bits type; pure type.
+	"os.Getgid",                          // returns the numeric group id of the caller; read-only syscall.
+	"os.Getgroups",                       // returns supplementary group ids; read-only syscall.
+	"os.Getuid",                          // returns the numeric user id of the caller; read-only syscall.
+	"os.O_RDONLY",                        // read-only file flag constant; pure constant.
+	"os.OpenRoot",                        // opens a directory as a root for sandboxed file access; needed for sandbox.
+	"os.PathError",                       // error type wrapping path and operation; pure type.
+	"os.Root",                            // sandboxed directory root type; core of the filesystem sandbox.
+	"os.Stat",                            // returns file info for a path; needed for sandbox path validation.
+	"path/filepath.Abs",                  // returns absolute path; pure path computation.
+	"path/filepath.IsAbs",                // checks if path is absolute; pure function, no I/O.
+	"path/filepath.Join",                 // joins path elements; pure function, no I/O.
+	"path/filepath.Rel",                  // returns relative path; pure path computation.
+	"path/filepath.Separator",            // OS path separator constant; pure constant.
+	"slices.SortFunc",                    // sorts a slice with a comparison function; pure function, no I/O.
+	"strings.Compare",                    // compares two strings lexicographically; pure function, no I/O.
+	"strings.EqualFold",                  // case-insensitive string comparison; pure function, no I/O.
+	"strings.HasPrefix",                  // pure function for prefix matching; no I/O.
+	"syscall.ByHandleFileInformation",    // Windows file identity structure; pure type for file metadata.
+	"syscall.EISDIR",                     // "is a directory" errno constant; pure constant.
+	"syscall.Errno",                      // system call error number type; pure type.
+	"syscall.GetFileInformationByHandle", // Windows API for file identity (vol serial + file index); read-only syscall.
+	"syscall.Handle",                     // Windows file handle type; pure type alias.
+	"syscall.Stat_t",                     // file stat structure type; pure type for Unix file metadata.
 }