env

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package env declares the portable execution environment of pi-durable: a file system and a shell that tools and prompt sections use through a conversation's environment.

Ports packages/durable/src/env/index.ts

Go mapping: upstream operations return `Result<T, E>` instead of throwing. Each Go method returns `(T, error)`; an expected failure is a *FileError or *ExecutionError and never a panic. The Result helpers stay for callers that hold a value-or-failure pair.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetOrThrow

func GetOrThrow[TValue any, TError error](result Result[TValue, TError]) (TValue, error)

GetOrThrow returns the value, or the failure as a Go error.

func GetOrUndefined

func GetOrUndefined[TValue, TError any](result Result[*TValue, TError]) *TValue

GetOrUndefined returns the value, or nil for a failure.

func ToError

func ToError(value any) error

ToError converts a thrown value to an error: an error is kept, a string becomes its message, and any other value becomes its JSON text, or its default formatting when JSON fails.

Types

type CreateDirOptions

type CreateDirOptions struct {
	// Recursive creates missing parents; nil means true, as upstream's options?.recursive ?? true.
	Recursive *bool
}

CreateDirOptions configures FileSystem.CreateDir.

type CreateTempFileOptions

type CreateTempFileOptions struct {
	Prefix string
	Suffix string
}

CreateTempFileOptions configures FileSystem.CreateTempFile.

type ExecutionEnv

type ExecutionEnv interface {
	FileSystem
	Shell
}

ExecutionEnv is a file system and a shell.

type ExecutionError

type ExecutionError struct {
	Code    ExecutionErrorCode
	Message string
	// SpillPath is the spill file of a command that timed out or was aborted after its output crossed the spill
	// thresholds; empty otherwise.
	SpillPath string
	Cause     error
}

ExecutionError is the expected failure of a Shell command.

func NewExecutionError

func NewExecutionError(code ExecutionErrorCode, message string, cause error) *ExecutionError

NewExecutionError returns an ExecutionError; cause may be nil.

func (*ExecutionError) Error

func (e *ExecutionError) Error() string

func (*ExecutionError) Unwrap

func (e *ExecutionError) Unwrap() error

Unwrap returns the cause.

type ExecutionErrorCode

type ExecutionErrorCode string

ExecutionErrorCode classifies an ExecutionError.

const (
	ExecutionErrorAborted          ExecutionErrorCode = "aborted"
	ExecutionErrorTimeout          ExecutionErrorCode = "timeout"
	ExecutionErrorShellUnavailable ExecutionErrorCode = "shell_unavailable"
	ExecutionErrorSpawnError       ExecutionErrorCode = "spawn_error"
	ExecutionErrorCallbackError    ExecutionErrorCode = "callback_error"
	ExecutionErrorUnknown          ExecutionErrorCode = "unknown"
)

type FileError

type FileError struct {
	Code    FileErrorCode
	Message string
	// Path is empty when the failure has no path.
	Path  string
	Cause error
}

FileError is the expected failure of a FileSystem operation.

func NewFileError

func NewFileError(code FileErrorCode, message, path string, cause error) *FileError

NewFileError returns a FileError; path and cause may be empty.

func (*FileError) Error

func (e *FileError) Error() string

func (*FileError) Unwrap

func (e *FileError) Unwrap() error

Unwrap returns the cause.

type FileErrorCode

type FileErrorCode string

FileErrorCode classifies a FileError.

const (
	FileErrorAborted          FileErrorCode = "aborted"
	FileErrorNotFound         FileErrorCode = "not_found"
	FileErrorPermissionDenied FileErrorCode = "permission_denied"
	FileErrorNotDirectory     FileErrorCode = "not_directory"
	FileErrorIsDirectory      FileErrorCode = "is_directory"
	FileErrorInvalid          FileErrorCode = "invalid"
	FileErrorNotSupported     FileErrorCode = "not_supported"
	FileErrorUnknown          FileErrorCode = "unknown"
)

type FileInfo

type FileInfo struct {
	Name    string   `json:"name"`
	Path    string   `json:"path"`
	Kind    FileKind `json:"kind"`
	Size    int64    `json:"size"`
	MtimeMs float64  `json:"mtimeMs"`
}

FileInfo describes one file system entry.

type FileKind

type FileKind string

FileKind is "file", "directory", or "symlink".

const (
	FileKindFile      FileKind = "file"
	FileKindDirectory FileKind = "directory"
	FileKindSymlink   FileKind = "symlink"
)

type FileSystem

type FileSystem interface {
	// Id names the file namespace: equal ids see the same files at the same paths, whatever their cwd. Every local
	// environment shares one id; each container or remote host has its own.
	Id() string
	Cwd() string
	SetCwd(cwd string)
	AbsolutePath(ctx context.Context, path string) (string, error)
	JoinPath(ctx context.Context, parts []string) (string, error)
	ReadTextFile(ctx context.Context, path string) (string, error)
	OpenTextLineReader(ctx context.Context, path string) (TextLineReader, error)
	ReadTextLines(ctx context.Context, path string, options *ReadTextLinesOptions) ([]string, error)
	ReadBinaryFile(ctx context.Context, path string) ([]byte, error)
	// WriteFile writes content, a string or []byte.
	WriteFile(ctx context.Context, path string, content any) error
	// AppendFile appends content, a string or []byte.
	AppendFile(ctx context.Context, path string, content any) error
	// TruncateFile truncates or extends a file to exactly size bytes.
	TruncateFile(ctx context.Context, path string, size int64) error
	// FlushFile flushes file contents and the metadata needed to retrieve them from an open file handle.
	FlushFile(ctx context.Context, path string) error
	RenameFile(ctx context.Context, sourcePath, destinationPath string) error
	FileInfo(ctx context.Context, path string) (FileInfo, error)
	ListDir(ctx context.Context, path string) ([]FileInfo, error)
	CanonicalPath(ctx context.Context, path string) (string, error)
	Exists(ctx context.Context, path string) (bool, error)
	CreateDir(ctx context.Context, path string, options *CreateDirOptions) error
	Remove(ctx context.Context, path string, options *RemoveOptions) error
	CreateTempDir(ctx context.Context, prefix *string) (string, error)
	CreateTempFile(ctx context.Context, options *CreateTempFileOptions) (string, error)
	Cleanup(ctx context.Context) error
}

FileSystem is the portable file system capability. Operations return failures rather than panicking. Context comes first, as Go convention, where upstream passes it last.

type ReadTextLinesOptions

type ReadTextLinesOptions struct {
	MaxLines *int
}

ReadTextLinesOptions bounds FileSystem.ReadTextLines; nil MaxLines reads every line.

type RemoveOptions

type RemoveOptions struct {
	Recursive bool
	Force     bool
}

RemoveOptions configures FileSystem.Remove.

type Result

type Result[TValue, TError any] struct {
	Ok    bool
	Value TValue
	Error TError
}

Result is the value or the expected failure of a fallible operation.

func Err

func Err[TValue, TError any](err TError) Result[TValue, TError]

Err returns a failed result.

func Ok

func Ok[TValue, TError any](value TValue) Result[TValue, TError]

Ok returns a successful result.

type Shell

type Shell interface {
	Exec(ctx context.Context, command string, options *ShellExecOptions) (ShellExecResult, error)
	Cleanup(ctx context.Context) error
}

Shell runs commands.

type ShellExecOptions

type ShellExecOptions struct {
	Cwd        string
	Env        map[string]string
	InheritEnv *bool
	// Timeout is in seconds; nil has no timeout.
	Timeout *float64
	// OnOutput receives every decoded chunk of combined stdout and stderr as it arrives: raw, unbounded, and
	// unthrottled.
	OnOutput func(ctx context.Context, text string)
	Spill    *ShellSpillOptions
}

ShellExecOptions configures Shell.Exec.

type ShellExecResult

type ShellExecResult struct {
	ExitCode int
	// SpillPath is the temporary file holding the complete raw output when the spill thresholds were exceeded.
	SpillPath string
}

ShellExecResult is the result of a completed command.

type ShellSpillOptions

type ShellSpillOptions struct {
	AfterBytes int64
	// AfterLines counts complete or partial lines.
	AfterLines int64
}

ShellSpillOptions spills the complete output to a temporary file once it exceeds either threshold.

type TextLine

type TextLine struct {
	Text       string `json:"text"`
	Terminated bool   `json:"terminated"`
}

TextLine is one line read by a TextLineReader.

type TextLineReader

type TextLineReader interface {
	// ReadLine returns nil at the end of the file.
	ReadLine(ctx context.Context) (*TextLine, error)
	Close(ctx context.Context) error
}

TextLineReader reads a text file line by line.

Directories

Path Synopsis
Package node is the local execution environment of pi-durable: NodeExecutionEnv runs on the host file system and shell.
Package node is the local execution environment of pi-durable: NodeExecutionEnv runs on the host file system and shell.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL