enhance - add sys.stat built in tool

docs/docs/tools/system.md

@@ -1,64 +1,106 @@
 # System Tools
+
 GPTScript comes with a set of system tools that provide various core functionalities.
 
 ## sys.abort
+
 Aborts the operation and provides an error message.
+
 #### Arguments
+
 - `message`: The description of the error or unexpected result that caused abort to be called.
 
 ## sys.download
+
 Downloads a file from a specified URL to an optional location on disk with an option to override existing files.
+
 #### Arguments
+
 - `location` (optional): The on-disk location to store the downloaded file.
 - `override`: If true, allows overwriting of an existing file. Default is false.
 - `url`: The HTTP or HTTPS URL of the file to be downloaded.
 
 ## sys.exec
+
 Executes a command with the ability to specify command arguments and the working directory.
+
 #### Arguments
+
 - `command`: The full command to run, including all arguments.
 - `directory`: The working directory for the command. Defaults to the current directory ".".
 
 ## sys.find
+
 Searches for files within a directory that match a given pattern using Unix glob format.
+
 #### Arguments
+
 - `directory`: The directory to perform the search in. Defaults to the current directory ".".
 - `pattern`: The pattern to match against filenames.
 
 ## sys.getenv
+
 Retrieves the value of an environment variable.
+
 #### Arguments
+
 - `name`: The name of the environment variable to retrieve.
 
 ## sys.http.get
+
 Performs an HTTP GET request to the specified URL.
+
 #### Arguments
+
 - `url`: The URL to perform the GET request.
 
 ## sys.http.html2text
+
 Converts the HTML content from a given URL to plain text.
+
 #### Arguments
+
 - `url`: The URL of the HTML content to be converted.
 
 ## sys.http.post
+
 Sends an HTTP POST request with given content to a specified URL.
+
 #### Arguments
+
 - `content`: The content to be posted.
 - `contentType`: The MIME type of the content being posted.
 - `url`: The URL to which the POST request should be sent.
 
 ## sys.read
+
 Reads the content from a specified file.
+
 #### Arguments
+
 - `filename`: The name of the file from which to read content.
 
 ## sys.remove
+
 Removes a file from the specified location.
+
 #### Arguments
+
 - `location`: The path to the file that needs to be removed.
 
+## sys.stat
+
+Retrieves the status of a file, such as size, permissions, and last modified time.
+
+#### Arguments
+
+- `filepath`: The path to the file for which to retrieve status.
+
 ## sys.write
+
 Writes content to a specified file.
+
 #### Arguments
+
 - `content`: The content to be written to the file.
 - `filename`: The filename where the content should be written.

pkg/builtin/builtin.go

@@ -118,6 +118,15 @@ var tools = map[string]types.Tool{
 		},
 		BuiltinFunc: SysRemove,
 	},
+	"sys.stat": {
+		Parameters: types.Parameters{
+			Description: "Gets size, modfied time, and mode of the specified file",
+			Arguments: types.ObjectSchema(
+				"filepath", "The complete path and filename of the file",
+			),
+		},
+		BuiltinFunc: SysStat,
+	},
 }
 
 func SysProgram() *types.Program {
@@ -377,6 +386,22 @@ func SysRemove(ctx context.Context, env []string, input string) (string, error)
 	return fmt.Sprintf("Removed file: %s", params.Location), os.Remove(params.Location)
 }
 
+func SysStat(ctx context.Context, env []string, input string) (string, error) {
+	var params struct {
+		Filepath string `json:"filepath,omitempty"`
+	}
+	if err := json.Unmarshal([]byte(input), &params); err != nil {
+		return "", err
+	}
+
+	stat, err := os.Stat(params.Filepath)
+	if err != nil {
+		return "", err
+	}
+
+	return fmt.Sprintf("File %s mode: %s, size: %d bytes, modtime: %s", params.Filepath, stat.Mode().String(), stat.Size(), stat.ModTime().String()), nil
+}
+
 func SysDownload(ctx context.Context, env []string, input string) (_ string, err error) {
 	var params struct {
 		URL      string `json:"url,omitempty"`