builtins

type AllowedPath struct {
	Path   string
	Access AllowedPathAccess
}

type AllowedPathAccess string

type CallContext struct {
	Stdout io.Writer
	Stderr io.Writer
	Stdin  io.Reader

	// InLoop is true when the builtin runs inside a for loop.
	InLoop bool

	// LastExitCode is the exit code from the previous command.
	LastExitCode uint8

	// OpenFile opens a file within the shell's path restrictions.
	OpenFile func(ctx context.Context, path string, flags int, mode os.FileMode) (io.ReadWriteCloser, error)

	// ReadDir reads a directory within the shell's path restrictions.
	// Entries are returned sorted by name. Used by builtins like ls
	// that need deterministic sorted output.
	ReadDir func(ctx context.Context, path string) ([]fs.DirEntry, error)

	// OpenDir opens a directory within the shell's path restrictions for
	// incremental reading via ReadDir(n). Caller must close the handle.
	OpenDir func(ctx context.Context, path string) (fs.ReadDirFile, error)

	// IsDirEmpty checks whether a directory is empty by reading at most
	// one entry. More efficient than reading all entries.
	IsDirEmpty func(ctx context.Context, path string) (bool, error)

	// 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
	// contained more entries beyond the returned set.
	ReadDirLimited func(ctx context.Context, path string, offset, maxRead int) ([]fs.DirEntry, bool, error)

	// StatFile returns file info within the shell's path restrictions (follows symlinks).
	StatFile func(ctx context.Context, path string) (fs.FileInfo, error)

	// FileSystemStat returns filesystem-wide metadata for the filesystem
	// containing path. The path is resolved within the shell's path
	// restrictions and symlinks are followed.
	FileSystemStat func(ctx context.Context, path string) (FileSystemInfo, error)

	// LstatFile returns file info within the shell's path restrictions (does not follow symlinks).
	LstatFile func(ctx context.Context, path string) (fs.FileInfo, error)

	// ReadlinkFile returns the destination of a symbolic link within the
	// shell's path restrictions.
	ReadlinkFile func(ctx context.Context, path string) (string, error)

	// AccessFile checks whether the file at path is accessible with the given mode
	// within the shell's path restrictions. Mode: 0x04=read, 0x02=write, 0x01=execute.
	AccessFile func(ctx context.Context, path string, mode uint32) error

	// Truncate sets the size of the file at path within the shell's path
	// restrictions. When create is true, a missing file is created (mode
	// 0666 & ~umask); when create is false, a missing file returns
	// os.ErrNotExist. Negative sizes are rejected. Only available in
	// remediation mode; nil otherwise.
	Truncate func(ctx context.Context, path string, size int64, create bool) error

	// TruncateToZeroIfAtLeast truncates path to zero bytes within the shell's
	// path restrictions when its pre-truncation size is at least minSize.
	// When dryRun is true, it performs the same write-target validation and
	// eligibility check without mutating the file. The size check and truncate
	// share one fd to avoid path-swap races. Missing files are not created.
	// Only available in remediation mode; nil otherwise.
	TruncateToZeroIfAtLeast func(ctx context.Context, path string, minSize int64, dryRun bool) (sizeBefore int64, truncated bool, err error)

	// Remove deletes the file at path within the shell's path restrictions.
	// Directories are always rejected with an error; any other non-directory
	// entry (regular file, symlink, FIFO, socket, device node) may be
	// removed. A symlink argument removes the link itself, not its referent.
	// Only available in remediation mode; nil otherwise.
	//
	// Removals are charged against a cumulative per-run budget of
	// MaxFileRemovalsPerRun files, shared across every invocation, loop
	// iteration, subshell, and pipeline stage in one Runner.Run call. Once the
	// budget is exhausted, Remove returns ErrRemoveBudgetExceeded without
	// touching the file. Failed removals are not charged.
	Remove func(ctx context.Context, path string) error

	// RemediationMode reports whether the shell is running in remediation mode.
	// When false (read-only mode), write-capable builtins such as truncate are
	// not available. Used by the help builtin to partition commands correctly.
	RemediationMode bool

	// PortableErr normalizes an OS error to a POSIX-style message.
	PortableErr func(err error) string

	// Now is the time captured at the start of each Run() call. Builtins
	// should use this instead of calling time.Now() directly, so the time
	// source is consistent across all commands in a single run.
	//
	// Note: this means all builtins within one Run() share the same reference
	// time, whereas bash evaluates each command against its own invocation
	// time. This is an intentional trade-off for consistency within a script
	// run.
	//
	// Run() always sets this before dispatching any builtin; Reset() clears
	// it, so it is always re-set by the next Run() call. The zero value
	// (time.Time{}) is reserved as the unset sentinel; callers constructing
	// CallContext directly (e.g. in tests) must set this to a non-zero value
	// before invoking builtins that use time predicates (find -mmin/-mtime,
	// ls -l).
	Now time.Time

	// FileIdentity extracts canonical file identity from FileInfo.
	// On Unix: dev+inode from Stat_t. On Windows: volume serial + file index
	// via GetFileInformationByHandle. The path parameter is needed on Windows
	// where FileInfo.Sys() lacks identity fields; Unix ignores it.
	FileIdentity func(path string, info fs.FileInfo) (FileID, bool)

	// CommandAllowed reports whether a command name is permitted under the
	// current shell policy. Used by the help builtin to list only executable
	// commands.
	CommandAllowed func(name string) bool

	// AuthorizeSystemd reports whether every operation may be performed under
	// the current shell policy. Implementations must authorize the complete
	// list before a builtin performs any operation so compound requests cannot
	// partially execute.
	AuthorizeSystemd func(operations ...SystemdOperation) error

	// AuthorizeSystemServices is the deprecated unit-only authorization
	// capability retained for compatibility with callers built against the
	// original service allowlist API.
	AuthorizeSystemServices func(action SystemServiceAction, services ...string) error

	// ReadableSystemServices returns the exact, sorted unit selectors granted
	// the read action. The returned slice is a defensive copy. Restricted
	// enumeration commands use this capability instead of listing every unit on
	// the configured systemd target.
	ReadableSystemServices func() []string

	// AllowedSystemServicesList returns the effective, exact unit/action grant
	// pairs sorted by unit and canonical action order. The returned slice is a
	// defensive copy. Used by the help builtin to surface the active systemd
	// capability policy without exposing a mutable authorization map.
	AllowedSystemServicesList func() []SystemdOperation

	// AllowedPathsList returns the resolved absolute paths and configured
	// access modes of the AllowedPaths sandbox roots. An empty/nil slice means
	// no allowed paths are configured, which blocks all filesystem access.
	// Used by the help builtin to surface the active sandbox roots.
	AllowedPathsList func() []AllowedPath

	// WorkDir returns the shell's current working directory (absolute path).
	// Used by builtins that need to compute absolute paths for sub-operations.
	WorkDir func() string

	// HostPrefix returns the configured host-mount prefix used by
	// container-style sandboxes to translate host-absolute paths
	// (e.g. /var/log/pods/...) into the prefixed paths the sandbox can
	// open (e.g. /mnt/host/var/log/pods/...). Returns "" when no prefix
	// is configured. Builtins that resolve absolute symlink targets
	// (e.g. pwd -P) use this to keep their output consistent with what
	// the sandbox itself accepts.
	HostPrefix func() string

	// CanonicalizeRootPrefix translates a configured AllowedPaths root
	// prefix in absPath to that root's canonical (symlink-resolved)
	// form. Used by `pwd -P` so that when the sandbox root is itself a
	// symlink (e.g. /tmp/link -> /tmp/real), the printed path reflects
	// the resolution that os.Root has already followed implicitly. If
	// absPath is outside every root or the matching root is not a
	// symlink, the input is returned unchanged.
	CanonicalizeRootPrefix func(absPath string) string

	// ChangeDir mutates the shell's working directory. The supplied path
	// must be absolute. Implementations validate that the target exists,
	// is a directory, and lies inside AllowedPaths; on any failure the
	// previous working directory is preserved and an error is returned.
	// On success, $OLDPWD is set to the previous directory and $PWD is
	// set to absDir. Used exclusively by the cd builtin.
	ChangeDir func(absDir string) error

	// LookupEnvVar reads an environment variable from the shell's
	// overlay environment. Returns (value, true) if the variable is
	// set, ("", false) otherwise. The cd builtin uses this to resolve
	// $HOME (no-arg form) and $OLDPWD (the `cd -` form) without
	// requiring a full WriteEnviron handle on every CallContext.
	LookupEnvVar func(name string) (string, bool)

	// RunCommand executes a builtin command within the shell's sandbox.
	// dir overrides the working directory for path resolution.
	// Returns the command's exit code.
	RunCommand func(ctx context.Context, dir string, name string, args []string) (uint8, error)

	// RunCommandWithStdin is like RunCommand but lets the caller supply a
	// stdin reader for the child. Used by xargs to give children empty
	// stdin (matching POSIX behavior of redirecting child stdin from
	// /dev/null) while still reading items from the parent's stdin itself.
	// If nil, callers should fall back to RunCommand.
	RunCommandWithStdin func(ctx context.Context, dir string, name string, args []string, stdin io.Reader) (uint8, error)

	// SetVar assigns a value to a shell variable in the calling shell's
	// scope. Returns an error if the value exceeds the per-variable size
	// limit or if the total variable-storage cap would be exceeded.
	// Used by builtins that mutate parent-shell state, such as read.
	SetVar func(name, value string) error

	// GetVar returns the value of a shell variable. The bool reports
	// whether the variable was set; an unset variable returns ("", false).
	// Used by builtins that need to consult shell state, such as read
	// reading IFS for field-splitting.
	GetVar func(name string) (value string, ok bool)

	// Proc provides access to the proc filesystem for the ps and lsof
	// builtins. The path is fixed at construction time and cannot be
	// overridden by callers.
	Proc *ProcProvider

	// Systemd contains structured backends for systemd-aware builtins. Target
	// paths and transports are fixed by trusted runner configuration.
	Systemd *SystemdServices
}

type Command struct {
	Name        string
	Description string
	Help        string
	MakeFlags   func(*FlagSet) HandlerFunc

	// NormalizeArgs, if non-nil, rewrites raw argument slices before pflag
	// parsing. This allows commands to support legacy flag syntax that pflag
	// cannot handle natively (e.g. head/tail -5 → -n 5).
	NormalizeArgs func(args []string) []string

	// RemediationOnly marks a builtin as only available in remediation mode.
	// The interpreter refuses to dispatch such a command — before flag
	// parsing, so --help is refused too — when the shell is in read-only
	// mode, and the help builtin moves it to the disabled list. Builtins
	// keep their own equivalent check as defence in depth; the dispatch
	// gate is what makes the flag load-bearing for future builtins.
	RemediationOnly bool

	// RemediationDeniedMessage overrides the stderr text written by the
	// dispatch-level read-only refusal. It must end with a newline. When
	// empty, DefaultRemediationDeniedMessage is used. Only meaningful
	// together with RemediationOnly.
	RemediationDeniedMessage string
}

type CommandMeta struct {
	Name            string
	Description     string
	Help            string
	HasFlags        bool // true when MakeFlags registers at least one flag
	RemediationOnly bool // true when the command requires remediation mode

	// RemediationDeniedMessage is the stderr text the interpreter writes
	// when the command is dispatched in read-only mode. Non-empty exactly
	// when RemediationOnly is true.
	RemediationDeniedMessage string
}

type FeatureMeta struct {
	Name        string
	Description string
	Supported   []string
	Unsupported []string
	Notes       []string
}

type FileID struct {
	Dev uint64
	Ino uint64
}

type FileSystemInfo struct {
	ID          uint64
	IDAvailable bool

	NameMax          uint64
	NameMaxAvailable bool

	TypeID          uint64
	TypeIDAvailable bool
	TypeName        string

	IOBlockSize          uint64
	FundamentalBlockSize uint64
	Blocks               uint64
	BlocksFree           uint64
	BlocksAvailable      uint64

	Files          uint64
	FilesFree      uint64
	FilesAvailable bool
}

type Flag = pflag.Flag

type FlagSet = pflag.FlagSet

type HandlerFunc func(ctx context.Context, callCtx *CallContext, args []string) Result

type JournalCleaner interface {
	VacuumJournal(ctx context.Context, request JournalVacuumRequest) (JournalVacuumResult, error)
}

type JournalEntry struct {
	Timestamp  time.Time
	Hostname   string
	Identifier string
	PID        string
	Message    string
}

type JournalQuery struct {
	Units       []string
	Kernel      bool
	CurrentBoot bool
	Since       time.Time
	MaxEntries  int
}

type JournalReader interface {
	ReadJournal(ctx context.Context, query JournalQuery, yield func(JournalEntry) error) error
}

type JournalRotator interface {
	RotateJournal(ctx context.Context) error
}

type JournalStorageReader interface {
	JournalDiskUsage(ctx context.Context) (JournalUsage, error)
}

type JournalUsage struct {
	Bytes uint64
	Files int
}

type JournalVacuumRequest struct {
	Now      time.Time
	Before   time.Time
	MaxBytes uint64
	DryRun   bool
}

type JournalVacuumResult struct {
	Files          int
	Bytes          uint64
	RemainingBytes uint64
}

type ProcProvider struct {
	// contains filtered or unexported fields
}

type Result struct {
	// Code is the exit status code.
	Code uint8

	// Exiting signals that the shell should exit (set by the "exit" builtin).
	Exiting bool

	// BreakN > 0 means break out of N enclosing loops.
	BreakN int

	// ContinueN > 0 means continue from N enclosing loops.
	ContinueN int
}

type SystemServiceAction string

type SystemServiceController interface {
	RunSystemServiceJobs(ctx context.Context, action SystemServiceJobAction, services []string) error
	EnableSystemServices(ctx context.Context, services []string) error
	DisableSystemServices(ctx context.Context, services []string) error
}

type SystemServiceJobAction string

type SystemServiceListRequest struct {
	Services        []string
	IncludeInactive bool
}

type SystemServiceState struct {
	Name          string
	CanonicalName string
	Description   string
	LoadState     string
	ActiveState   string
	SubState      string
	UnitFileState string
	MainPID       uint32
	Result        string
	JobID         uint32
}

type SystemServiceStateReader interface {
	ListSystemServices(ctx context.Context, request SystemServiceListRequest) ([]SystemServiceState, error)
	InspectSystemServices(ctx context.Context, services []string) ([]SystemServiceState, error)
}

type SystemdOperation struct {
	Service string
	Action  SystemServiceAction
}

type SystemdServices struct {
	Journal        JournalReader
	JournalStorage JournalStorageReader
	JournalCleaner JournalCleaner
	JournalRotator JournalRotator
	ServiceState   SystemServiceStateReader
	ServiceControl SystemServiceController
}