executor

type Executor interface {
	// Run executes a command and returns the result. Timeout defaults to 30s.
	Run(name string, args ...string) Result

	// RunContext executes a command with the given context for cancellation/timeout.
	RunContext(ctx context.Context, name string, args ...string) Result

	// RunTimeout is a convenience wrapper: creates a context with the given timeout.
	RunTimeout(timeout time.Duration, name string, args ...string) Result

	// ReadFile reads the contents of a file.
	ReadFile(path string) ([]byte, error)

	// WriteFileAtomic writes data to a temp file then renames to path (atomic on same FS).
	WriteFileAtomic(path string, data []byte, perm os.FileMode) error

	// FileExists returns true if path exists (file or directory).
	FileExists(path string) bool

	// MkdirAll creates a directory tree (like os.MkdirAll).
	MkdirAll(path string, perm os.FileMode) error

	// Chown changes file ownership.
	Chown(path string, uid, gid int) error

	// Chmod changes file permissions.
	Chmod(path string, perm os.FileMode) error

	// Remove deletes a file or empty directory.
	Remove(path string) error

	// Symlink creates a symbolic link (newname -> oldname).
	Symlink(oldname, newname string) error

	// Rename atomically renames oldpath to newpath. Same-filesystem
	// semantics equivalent to syscall.Rename. Implementations route
	// through whatever primitive their host abstraction provides
	// (RealExecutor uses os.Rename; MockExecutor records the call and
	// updates its in-memory file map).
	//
	// Added in PR-26-code-B per §43.2 lock to replace the previous
	// Run("mv", ...) indirection used by restore_deps_csf.go's A.3
	// binary-restore step. Mutation surface is bounded by
	// INV-PR26-NEW-MUTATION-SURFACES-BOUNDED (§44 row 2).
	Rename(oldpath, newpath string) error

	// Stat returns the FileMeta (mode / uid / gid / size) for a path.
	// Read-only introspection. Added in PR-26-code-C for the CSF
	// cron-backup manifest writer + reader. Per §51.5-A2 invariant,
	// read-only typed introspection is OUTSIDE the bounded-3 mutation
	// cap; no new mutation surface is introduced.
	//
	// Returns an error if the path does not exist or cannot be
	// stat'd (per os.Stat semantics in the real implementation).
	Stat(path string) (FileMeta, error)

	// NftTableExists returns true if the given nft table exists in the kernel.
	// family: "ip", "ip6", or "inet". table: e.g. "nftban".
	NftTableExists(family, table string) bool

	// NftListSet returns the elements of an nft set as a raw string.
	// Returns ("", error) if the set does not exist.
	NftListSet(family, table, set string) (string, error)

	// NftAddElement adds an element to an nft set.
	NftAddElement(family, table, set string, element string) error

	// NftDeleteTable deletes an nft table. Ignores "not found" errors.
	NftDeleteTable(family, table string) error

	// NftCheck runs nft -c -f on the given config content (syntax validation).
	// Returns nil if valid, error with details if invalid.
	NftCheck(configContent string) error

	// ServiceActive returns true if the systemd unit is active.
	ServiceActive(unit string) bool

	// ServiceEnable enables a systemd unit.
	ServiceEnable(unit string) error

	// ServiceStart starts a systemd unit.
	ServiceStart(unit string) error

	// ServiceStop stops a systemd unit.
	ServiceStop(unit string) error

	// ServiceDisable disables a systemd unit.
	ServiceDisable(unit string) error

	// ServiceMask masks a systemd unit (prevents start by any means).
	ServiceMask(unit string) error

	// ServiceUnmask unmasks a systemd unit (inverse of ServiceMask).
	// Used by the CSF restore A.1 step. Added in PR-26-code-B per
	// §43.2 lock to replace the previous
	// Run("systemctl", "unmask", ...) indirection. Mutation surface
	// is bounded by INV-PR26-NEW-MUTATION-SURFACES-BOUNDED (§44 row 2).
	ServiceUnmask(unit string) error

	// ServiceResetFailed clears systemd's "failed" state for a unit
	// (the `Result: signal` / `Result: exit-code` cosmetic marker that
	// persists after stop/mask escalation paths). Used by takeover
	// after successful ServiceMask of conflicting firewalls (csf, lfd,
	// future ufw / firewalld) so `systemctl --failed` does not show
	// stale entries for units nftban intentionally tore down.
	// PR-P1 / closes #524.
	//
	// Mutation surface bounded: callers must only invoke for units
	// they have just successfully masked. The restore path does NOT
	// call ServiceResetFailed (re-arming the watchdog is restore-side
	// and out of scope per Amendment 1 §31).
	ServiceResetFailed(unit string) error

	// DaemonReload runs systemctl daemon-reload.
	DaemonReload() error

	// CommandExists returns true if the named command is in PATH.
	CommandExists(name string) bool

	// UserExists returns true if the named system user exists.
	UserExists(name string) bool

	// GroupExists returns true if the named system group exists.
	GroupExists(name string) bool

	// Getenv returns the value of an environment variable.
	Getenv(key string) string
}

type FileMeta struct {
	Mode os.FileMode
	UID  int
	GID  int
	Size int64
}

type MockExecutor struct {

	// Commands records every command executed (for assertion).
	Commands []RecordedCommand

	// RunResults maps "name:arg1:arg2" to a preset Result.
	// If a command is not in RunResults, it returns exit 0 with empty output.
	RunResults map[string]Result

	// Files maps path -> content for ReadFile/FileExists.
	Files map[string][]byte

	// FileStats maps path -> FileMeta for Stat. PR-26-code-C
	// addition. When a path is in Files but absent from FileStats,
	// Stat synthesizes a default-mode (0644 root:root) FileMeta with
	// Size derived from the in-memory content. Tests that need to
	// pin specific mode/uid/gid populate FileStats explicitly.
	FileStats map[string]FileMeta

	// WrittenFiles records what was written via WriteFileAtomic.
	WrittenFiles map[string][]byte

	// Dirs records directories created via MkdirAll.
	Dirs map[string]bool

	// NftTables maps "family:table" -> exists.
	NftTables map[string]bool

	// NftSets maps "family:table:set" -> element list as string.
	NftSets map[string]string

	// Services maps "unit" -> active.
	Services map[string]bool

	// Users maps "name" -> exists.
	Users map[string]bool

	// Groups maps "name" -> exists.
	Groups map[string]bool

	// Env maps "key" -> value.
	Env map[string]string

	// ExistingCommands maps "name" -> exists.
	ExistingCommands map[string]bool

	// PR-26-code-B: typed-method error injection. When set non-nil,
	// the corresponding typed method returns the assigned error
	// instead of nil. Mirrors the RunResults pattern that controls
	// Run() exit codes.
	ServiceMaskErr        error
	ServiceUnmaskErr      error
	ServiceResetFailedErr error
	RenameErr             error
	// contains filtered or unexported fields
}

type RealExecutor struct{}

type RecordedCommand struct {
	Name string
	Args []string
}

type Result struct {
	ExitCode int
	Stdout   string
	Stderr   string
}