Skip to content

Modern Docker Management, Designed for Everyone

35.5 KB
Raw Blame
package projects

import (
	"context"
	"errors"
	"fmt"
	"log/slog"
	"maps"
	"os"
	"path/filepath"
	"regexp"
	"slices"
	"strconv"
	"strings"
	"syscall"
	"time"

	"github.com/compose-spec/compose-go/v2/consts"
	"github.com/compose-spec/compose-go/v2/dotenv"
	projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
	"github.com/samber/hot"
	"go.getarcane.app/acfs"
	kit "go.getarcane.app/kit/pkg"

	"github.com/getarcaneapp/arcane/backend/v2/internal/common"
)

const (
	GlobalEnvFileName                     = ".env.global"
	EffectiveEnvFileName                  = ".env"
	GitSourceEnvFileName                  = ".env.git"
	OverrideEnvFileName                   = "project.env"
	ProjectEnvModeDirect   ProjectEnvMode = "direct"
	ProjectEnvModeOverride ProjectEnvMode = "override"

	// Docker Compose pre-defined variable names that compose-go's consts package
	// does not export. See https://docs.docker.com/compose/how-tos/environment-variables/envvars.
	composeEnvFilesKey      = "COMPOSE_ENV_FILES"
	composeRemoveOrphansKey = "COMPOSE_REMOVE_ORPHANS"
	composeIgnoreOrphansKey = "COMPOSE_IGNORE_ORPHANS"
	composeParallelLimitKey = "COMPOSE_PARALLEL_LIMIT"

	defaultComposePathSeparator = ":"
)

type EnvMap = map[string]string

type ProjectEnvMode string

type ProjectEnvState struct {
	Mode             ProjectEnvMode
	EditableFileName string
	EditableContent  string
	EffectiveContent string
	DirectContent    string
	GitContent       string
	OverrideContent  string
	HasEffective     bool
	HasGitSource     bool
	HasOverride      bool
	// The *Unreadable fields report a file that exists on disk but could not be
	// read because of a permission error (e.g. a chmod 000 or foreign-owned
	// file reachable through a bind mount). Such a file is treated as absent
	// for merge purposes, and callers persisting env state must not attempt to
	// write or remove it — its contents are unknown, so writing could either
	// fail (bricking the caller) or silently clobber operator intent.
	EffectiveUnreadable bool
	GitSourceUnreadable bool
	OverrideUnreadable  bool
}

type EnvLoader struct {
	projectsDir   string
	workdir       string
	autoInjectEnv bool
}

type envFileCacheEntry struct {
	path   string
	mtime  time.Time
	size   int64
	exists bool
	values EnvMap
}

var (
	globalEnvFileCache  = hot.NewHotCache[string, envFileCacheEntry](hot.LRU, 4096).Build()
	projectEnvFileCache = hot.NewHotCache[string, envFileCacheEntry](hot.LRU, 4096).Build()
)

func NewEnvLoader(projectsDir, workdir string, autoInjectEnv bool) *EnvLoader {
	return &EnvLoader{
		projectsDir:   projectsDir,
		workdir:       workdir,
		autoInjectEnv: autoInjectEnv,
	}
}

// processEnvAllowlist is the only part of Arcane's own process environment
// that flows into compose interpolation of managed projects: timezone and
// locale, whose container values are safe to share. Everything else is
// excluded so Arcane's variables never leak into ${VAR} references or
// pass-through environment entries — its PORT collides with project port
// mappings, secrets would be readable from any compose file, and vars like
// HOME or PUID carry container-internal values that are wrong for projects.
var processEnvAllowlist = []string{"TZ", "LANG", "LANGUAGE", "LC_ALL"}

func allowedProcessEnvInternal() EnvMap {
	envMap := make(EnvMap)
	for _, key := range processEnvAllowlist {
		if val, ok := os.LookupEnv(key); ok {
			envMap[key] = val
		}
	}
	return envMap
}

// LoadEnvironment loads and merges environment variables from all sources:
// 1. Allowlisted process environment (TZ)
// 2. Global .env.global file (from projects directory)
// 3. Project-specific .env file (from workdir)
// The rest of the Arcane process environment is intentionally excluded so its
// own variables never leak into compose interpolation of managed projects.
func (l *EnvLoader) LoadEnvironment(ctx context.Context) (envMap, injectionVars EnvMap, err error) {
	envMap = allowedProcessEnvInternal()
	injectionVars = make(EnvMap)

	if strings.TrimSpace(l.projectsDir) != "" {
		globalEnvPath := filepath.Join(l.projectsDir, GlobalEnvFileName)
		if loadAndMergeGlobalEnvErr := l.loadAndMergeGlobalEnv(ctx, globalEnvPath, envMap, injectionVars); loadAndMergeGlobalEnvErr != nil && !errors.Is(loadAndMergeGlobalEnvErr, os.ErrNotExist) {
			slog.WarnContext(ctx, "Failed to load global env", "path", globalEnvPath, "error", loadAndMergeGlobalEnvErr)
		}
	}

	// COMPOSE_DISABLE_ENV_FILE skips the project .env entirely, as `docker
	// compose` does. It is read from the sources merged so far — in practice
	// only .env.global, since the process-env allowlist never includes
	// COMPOSE_* variables.
	if parseComposeBoolInternal(envMap, consts.ComposeDisableDefaultEnvFile) {
		slog.DebugContext(ctx, "COMPOSE_DISABLE_ENV_FILE set; skipping project .env", "workdir", l.workdir)
	} else {
		projectEnvPath := filepath.Join(l.workdir, EffectiveEnvFileName)
		if loadAndMergeProjectEnvErr := l.loadAndMergeProjectEnv(ctx, projectEnvPath, envMap, injectionVars); loadAndMergeProjectEnvErr != nil {
			switch {
			case errors.Is(loadAndMergeProjectEnvErr, os.ErrNotExist):
				slog.DebugContext(ctx, "Project .env file does not exist", "path", projectEnvPath)
			case errors.Is(loadAndMergeProjectEnvErr, os.ErrPermission):
				return envMap,
					injectionVars,
					common.Classify(common.ErrProjectEnvUnreadable,
						fmt.Errorf("%s is not readable by the runtime user (uid %d, gid %d); fix its ownership/read permission or set PUID/PGID to a user that can read it: %w",
							projectEnvPath,
							os.Geteuid(),
							os.Getegid(),
							loadAndMergeProjectEnvErr))
			default:
				slog.WarnContext(ctx, "Failed to load project env", "path", projectEnvPath, "error", loadAndMergeProjectEnvErr)
			}
		}
	}

	// COMPOSE_ENV_FILES, when declared, layers additional env files on top of
	// the project .env (later entries win). Reuses the mtime-keyed cache.
	l.mergeComposeEnvFilesInternal(ctx, envMap, injectionVars)

	return envMap, injectionVars, nil
}

func (l *EnvLoader) mergeComposeEnvFilesInternal(ctx context.Context, envMap, injectionVars EnvMap) {
	parse := func(path string, contextEnv EnvMap) (EnvMap, error) {
		key := strings.Join([]string{path, l.projectsDir, strconv.FormatBool(l.autoInjectEnv), strconv.FormatUint(kit.Fingerprint(contextEnv), 16)}, "\x00")
		entry, err := loadCachedEnvFileInternal(ctx, projectEnvFileCache, key, path, contextEnv)
		if err != nil {
			return nil, err
		}
		return kit.Ternary(!entry.exists, nil, entry.values), nil
	}
	onMerged := func(values EnvMap) {
		if l.autoInjectEnv {
			maps.Copy(injectionVars, values)
		}
	}
	mergeComposeEnvFilesInternal(ctx, l.workdir, envMap, parse, onMerged)
}

func (l *EnvLoader) loadAndMergeGlobalEnv(ctx context.Context, path string, envMap, injectionVars EnvMap) error {
	entry, err := loadCachedEnvFileInternal(ctx, globalEnvFileCache, path, path, envMap)
	if err != nil {
		return err
	}
	if !entry.exists {
		return os.ErrNotExist
	}

	for k, v := range entry.values {
		envMap[k] = v
		injectionVars[k] = v
	}

	slog.DebugContext(ctx, "Merged global env into environment map", "totalEnvCount", len(envMap))
	return nil
}

func (l *EnvLoader) loadAndMergeProjectEnv(ctx context.Context, path string, envMap, injectionVars EnvMap) error {
	key := strings.Join([]string{path, l.projectsDir, strconv.FormatBool(l.autoInjectEnv), strconv.FormatUint(kit.Fingerprint(envMap), 16)}, "\x00")
	entry, err := loadCachedEnvFileInternal(ctx, projectEnvFileCache, key, path, envMap)
	if err != nil {
		return err
	}
	if !entry.exists {
		return os.ErrNotExist
	}

	for k, v := range entry.values {
		envMap[k] = v
		if l.autoInjectEnv {
			injectionVars[k] = v
		}
	}

	slog.DebugContext(ctx, "Merged project .env into environment map", "totalEnvCount", len(envMap))
	return nil
}

func loadCachedEnvFileInternal(_ context.Context, envCache *hot.HotCache[string, envFileCacheEntry], key, path string, contextEnv EnvMap) (envFileCacheEntry, error) {
	if cached, ok := envCache.Peek(key); ok {
		if validEnvFileCacheEntryInternal(cached) {
			return cached, nil
		}
		envCache.Delete(key)
	}

	entry, found, err := envCache.GetWithLoaders(key, func(_ []string) (map[string]envFileCacheEntry, error) {
		// Stays on os.*: env files may be symlinks resolving outside any
		// confinement root (a supported setup), which acfs cannot follow.
		info, err := os.Stat(path)
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				return map[string]envFileCacheEntry{key: {path: path}}, nil
			}
			return nil, err
		}
		if info.IsDir() {
			return nil, fmt.Errorf("path is a directory: %s", path)
		}

		parsed, err := parseProjectEnvFileExistingInternal(path, contextEnv)
		if err != nil {
			return nil, fmt.Errorf("parse env file: %w", err)
		}
		return map[string]envFileCacheEntry{key: {
			path:   path,
			mtime:  info.ModTime(),
			size:   info.Size(),
			exists: true,
			values: parsed,
		}}, nil
	})
	if err != nil {
		return envFileCacheEntry{}, err
	}
	if !found {
		return envFileCacheEntry{}, errors.New("environment file cache loader returned no entry")
	}
	return entry, nil
}

func validEnvFileCacheEntryInternal(entry envFileCacheEntry) bool {
	// os.Stat rather than acfs: env files may be symlinks resolving outside
	// any confinement root (a supported setup).
	info, err := os.Stat(entry.path)
	if err != nil {
		return !entry.exists && errors.Is(err, os.ErrNotExist)
	}
	if info.IsDir() {
		return false
	}
	if !entry.exists || !info.ModTime().Equal(entry.mtime) || info.Size() != entry.size {
		return false
	}
	// A chmod does not bump mtime, so confirm the file is still readable.
	file, err := os.Open(entry.path)
	if err != nil {
		return false
	}
	return file.Close() == nil
}

func parseProjectEnvFileExistingInternal(path string, contextEnv EnvMap) (EnvMap, error) {
	content, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read file: %w", err)
	}
	return ParseProjectEnvContent(string(content), contextEnv)
}

// ParseProjectEnvFile parses a project .env file with variable expansion using the provided
// context map (e.g. process env). Returns nil without error when the file does not exist.
// Only the specified file is read — global env files are intentionally not loaded here.
//
// Stays on os.*: env files may be symlinks resolving outside any confinement
// root (a supported setup), which acfs cannot follow.
func ParseProjectEnvFile(path string, contextEnv EnvMap) (EnvMap, error) {
	info, err := os.Stat(path)
	if err != nil || info.IsDir() {
		return nil, nil //nolint:nilerr // missing .env is not an error
	}
	return parseProjectEnvFileExistingInternal(path, contextEnv)
}

// ParseProjectEnvContent parses project .env content from a string using
// compose-go's dotenv parser with variable expansion. Lookups resolve from
// contextEnv (previously loaded vars) only; the Arcane process environment is
// intentionally never consulted so its variables don't leak into project env.
func ParseProjectEnvContent(content string, contextEnv EnvMap) (EnvMap, error) {
	lookupFn := func(key string) (string, bool) {
		val, ok := contextEnv[key]
		return val, ok
	}

	envMap, err := dotenv.ParseWithLookup(strings.NewReader(content), lookupFn)
	if err != nil {
		return nil, fmt.Errorf("parse env: %w", err)
	}

	return envMap, nil
}

// WithTransientValidationEnvFile temporarily writes a project .env file while
// running compose validation, then restores the original file state.
func WithTransientValidationEnvFile(ctx context.Context, projectPath string, effectiveEnvContent *string, run func() error) (err error) {
	// Read through os rather than the root-confined API: a project .env is
	// allowed to be a symlink whose target lives outside the project directory,
	// and that write-through is deliberately preserved (#3556).
	originalContent, readErr := os.ReadFile(filepath.Join(projectPath, ".env"))
	originalExists := readErr == nil
	if readErr != nil && !os.IsNotExist(readErr) {
		if !errors.Is(readErr, os.ErrPermission) && !errors.Is(readErr, syscall.EISDIR) {
			return fmt.Errorf("prepare env file for compose validation: %w", readErr)
		}
		// The path exists but is permission-locked (e.g. chmod 000, foreign-owned) or a directory.
		// Its contents can't be verified or safely overwritten, so leave it
		// untouched and validate against whatever's already on disk instead of
		// aborting the whole update.
		slog.WarnContext(ctx, "skipping unreadable .env during compose validation; leaving it untouched", "projectPath", projectPath, "error", readErr)
		if run == nil {
			return nil
		}
		return run()
	}

	contentMatches := effectiveEnvContent != nil && originalExists && string(originalContent) == *effectiveEnvContent
	shouldWrite := !contentMatches && (effectiveEnvContent != nil || !originalExists)
	if shouldWrite {
		content := ""
		if effectiveEnvContent != nil {
			content = *effectiveEnvContent
		}
		if writeErr := WriteProjectFile(ctx, projectPath, projectPath, ".env", content); writeErr != nil {
			return fmt.Errorf("prepare env file for compose validation: %w", writeErr)
		}

		defer func() {
			var restoreErr error
			switch {
			case originalExists:
				restoreErr = WriteProjectFile(ctx, projectPath, projectPath, ".env", string(originalContent))
			default:
				restoreErr = acfs.Remove(ctx, projectPath, "/.env")
			}

			if restoreErr != nil && !os.IsNotExist(restoreErr) {
				if err == nil {
					err = fmt.Errorf("restore env file after compose validation: %w", restoreErr)
				}
			}
		}()
	}

	if run == nil {
		return nil
	}

	return run()
}

// BuildEffectiveEnvContent merges git and override env sources into the effective
// .env content written to disk. Keys present in both layers are rewritten in place
// on the Git line, preserving ordering and inline comments; override-only keys are
// appended after the Git content. When the in-place rewrite cannot be verified to
// parse identically to plain concatenation (e.g. multiline values), the override
// is appended verbatim instead so duplicate keys resolve to the override value.
func BuildEffectiveEnvContent(gitContent, overrideContent string) (string, error) {
	contextEnv := make(EnvMap)

	gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse git env content: %w", err)
	}
	maps.Copy(contextEnv, gitEnv)

	overrideEnv, err := ParseProjectEnvContent(overrideContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse override env content: %w", err)
	}

	switch {
	case gitContent == "":
		return overrideContent, nil
	case overrideContent == "":
		return gitContent, nil
	}

	separated := strings.HasSuffix(gitContent, "\n") || strings.HasPrefix(overrideContent, "\n")
	concatenated := kit.Ternary(separated, gitContent+overrideContent, gitContent+"\n"+overrideContent)

	candidate, ok := mergeEnvOverridesInPlaceInternal(gitContent, overrideContent, overrideEnv)
	if !ok {
		return concatenated, nil
	}

	candidateEnv, candidateErr := ParseProjectEnvContent(candidate, make(EnvMap))
	expectedEnv, expectedErr := ParseProjectEnvContent(concatenated, make(EnvMap))
	if candidateErr == nil && expectedErr == nil && maps.Equal(candidateEnv, expectedEnv) {
		return candidate, nil
	}
	return concatenated, nil
}

// EnvContentChanged reports whether two env contents differ semantically,
// ignoring ordering and comments. Unparseable content is compared verbatim.
func EnvContentChanged(oldContent, newContent string) bool {
	oldEnv, oldErr := ParseProjectEnvContent(oldContent, nil)
	newEnv, newErr := ParseProjectEnvContent(newContent, nil)
	if oldErr != nil || newErr != nil {
		return oldContent != newContent
	}
	return !maps.Equal(oldEnv, newEnv)
}

var envKeyLineRegexInternal = regexp.MustCompile(`^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_.-]*)(\s*=)(.*)$`)

// mergeEnvOverridesInPlaceInternal rewrites the value of every gitContent line
// whose key has an override — keeping line order and trailing inline comments —
// then appends the override lines whose keys were not rewritten. ok is false when
// no git line matched an override and the caller should fall back to plain
// concatenation.
func mergeEnvOverridesInPlaceInternal(gitContent, overrideContent string, overrideEnv EnvMap) (merged string, ok bool) {
	rewritten := make(map[string]struct{})
	gitLines := strings.Split(gitContent, "\n")

	for i, line := range gitLines {
		body, hadCR := strings.CutSuffix(line, "\r")
		match := envKeyLineRegexInternal.FindStringSubmatch(body)
		if match == nil {
			continue
		}
		overrideValue, exists := overrideEnv[match[2]]
		if !exists {
			continue
		}

		value, comment := splitEnvValueCommentInternal(match[4])
		separator := value[len(strings.TrimRight(value, " \t")):]
		if comment != "" && separator == "" {
			separator = " "
		}

		body = match[1] + match[2] + match[3] + formatEnvValueInternal(overrideValue) + separator + comment
		if hadCR {
			body += "\r"
		}
		gitLines[i] = body
		rewritten[match[2]] = struct{}{}
	}

	if len(rewritten) == 0 {
		return "", false
	}

	remainderLines := make([]string, 0)
	for line := range strings.SplitSeq(overrideContent, "\n") {
		if match := envKeyLineRegexInternal.FindStringSubmatch(strings.TrimSuffix(line, "\r")); match != nil {
			if _, drop := rewritten[match[2]]; drop {
				continue
			}
		}
		remainderLines = append(remainderLines, line)
	}

	merged = strings.Join(gitLines, "\n")
	remainder := strings.Join(remainderLines, "\n")
	switch {
	case strings.TrimSpace(remainder) == "":
		return merged, true
	case strings.HasSuffix(merged, "\n"), strings.HasPrefix(remainder, "\n"):
		return merged + remainder, true
	default:
		return merged + "\n" + remainder, true
	}
}

// splitEnvValueCommentInternal splits a raw single-line env value into the value
// part and a trailing inline comment. A comment starts at an unquoted '#' that is
// at the start of the value or preceded by whitespace.
func splitEnvValueCommentInternal(raw string) (value, comment string) {
	var quote byte
	for i := 0; i < len(raw); i++ {
		c := raw[i]
		switch {
		case quote != 0:
			if c == quote {
				quote = 0
			} else if c == '\\' && quote == '"' {
				i++
			}
		case c == '\'' || c == '"':
			quote = c
		case c == '#' && (i == 0 || raw[i-1] == ' ' || raw[i-1] == '\t'):
			return raw[:i], raw[i:]
		}
	}
	return raw, ""
}

// BuildAdditiveOverrideEnvContent derives override content from a pre-git local
// .env file. Like other generated env helpers, the result is normalized and does
// not preserve comments or original key ordering.
func BuildAdditiveOverrideEnvContent(gitContent, localContent string) (string, error) {
	contextEnv := make(EnvMap)

	gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse git env content: %w", err)
	}
	maps.Copy(contextEnv, gitEnv)

	localEnv, err := ParseProjectEnvContent(localContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse local env content: %w", err)
	}

	override := make(EnvMap)
	for key, value := range localEnv {
		if _, exists := gitEnv[key]; !exists {
			override[key] = value
		}
	}

	return formatEnvMapInternal(override), nil
}

// BuildOverrideEnvContent derives the editable override file from git-backed and
// effective env content. Content that already contains only real overrides is
// returned verbatim; derived or cleaned output uses Arcane's canonical format.
func BuildOverrideEnvContent(gitContent, effectiveContent string) (string, error) {
	contextEnv := make(EnvMap)

	gitEnv, err := ParseProjectEnvContent(gitContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse git env content: %w", err)
	}
	maps.Copy(contextEnv, gitEnv)

	effectiveEnv, err := ParseProjectEnvContent(effectiveContent, contextEnv)
	if err != nil {
		return "", fmt.Errorf("parse effective env content: %w", err)
	}

	override := make(EnvMap)
	for key, value := range effectiveEnv {
		gitValue, exists := gitEnv[key]
		switch {
		case !exists:
			override[key] = value
		case value == "":
			// Empty values for Git-backed keys are treated as deleting the local override,
			// so the Git value is restored on the next effective merge.
			continue
		case gitValue != value:
			override[key] = value
		}
	}

	if maps.Equal(effectiveEnv, override) {
		return effectiveContent, nil
	}

	return formatEnvMapInternal(override), nil
}

// CheckProjectEnvAccess reports a configuration error when the runtime user
// lacks permission to open dir's .env or traverse its path.
func CheckProjectEnvAccess(ctx context.Context, projectsDir, dir string) *projecttypes.ConfigurationError {
	envPath := filepath.Join(dir, EffectiveEnvFileName)
	file, err := os.Open(envPath)
	if err == nil {
		if closeErr := file.Close(); closeErr != nil {
			slog.WarnContext(ctx, "failed to close project env access probe", "path", envPath, "error", closeErr)
		}
		return nil
	}
	if !errors.Is(err, os.ErrPermission) {
		return nil
	}

	disabled := false
	if strings.TrimSpace(projectsDir) != "" {
		globalEnv, globalErr := ParseProjectEnvFile(filepath.Join(projectsDir, GlobalEnvFileName), make(EnvMap))
		if globalErr != nil {
			slog.DebugContext(ctx, "Failed to read global env while checking project env access", "path", projectsDir, "error", globalErr)
		} else {
			disabled = parseComposeBoolInternal(globalEnv, consts.ComposeDisableDefaultEnvFile)
		}
	}

	return &projecttypes.ConfigurationError{
		Code:             common.ConfigurationErrorCodeEnvFileUnreadable,
		Path:             envPath,
		UID:              os.Geteuid(),
		GID:              os.Getegid(),
		BlocksOperations: !disabled,
	}
}

func ReadProjectEnvState(projectPath string) (ProjectEnvState, error) {
	effectiveContent, hasEffective, effectiveUnreadable, err := readOptionalProjectFileInternal(projectPath, EffectiveEnvFileName)
	if err != nil {
		return ProjectEnvState{}, err
	}

	gitContent, hasGitSource, gitSourceUnreadable, err := readOptionalProjectFileInternal(projectPath, GitSourceEnvFileName)
	if err != nil {
		return ProjectEnvState{}, err
	}

	overrideContent, hasOverride, overrideUnreadable, err := readOptionalProjectFileInternal(projectPath, OverrideEnvFileName)
	if err != nil {
		return ProjectEnvState{}, err
	}

	if effectiveUnreadable || gitSourceUnreadable || overrideUnreadable {
		ctx := context.Background() //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
		slog.WarnContext(ctx, "skipping unreadable project env file(s); leaving them untouched",
			"projectPath", projectPath,
			"effectiveUnreadable", effectiveUnreadable,
			"gitSourceUnreadable", gitSourceUnreadable,
			"overrideUnreadable", overrideUnreadable,
		)
	}

	state := ProjectEnvState{
		DirectContent:       effectiveContent,
		EffectiveContent:    effectiveContent,
		HasEffective:        hasEffective,
		EffectiveUnreadable: effectiveUnreadable,
		GitContent:          gitContent,
		HasGitSource:        hasGitSource,
		GitSourceUnreadable: gitSourceUnreadable,
		OverrideContent:     overrideContent,
		HasOverride:         hasOverride,
		OverrideUnreadable:  overrideUnreadable,
	}

	if hasGitSource || hasOverride {
		state.Mode = ProjectEnvModeOverride
		state.EditableFileName = OverrideEnvFileName
		state.EditableContent = overrideContent

		if !hasEffective {
			mergedContent, mergeErr := BuildEffectiveEnvContent(gitContent, overrideContent)
			if mergeErr != nil {
				return ProjectEnvState{}, mergeErr
			}
			state.EffectiveContent = mergedContent
		}

		return state, nil
	}

	state.Mode = ProjectEnvModeDirect
	state.EditableFileName = EffectiveEnvFileName
	state.EditableContent = effectiveContent

	return state, nil
}

// WriteManagedEnvFile writes (or, for project.env, removes) one of the three
// env-merge bookkeeping files — fileName must be EffectiveEnvFileName,
// GitSourceEnvFileName, or OverrideEnvFileName. If the existing path is
// unreadable (permission-locked or a directory), the write is skipped and a
// warning logged instead: its contents can't be verified, and such a path is
// typically unwritable too, so attempting the write would abort the whole caller.
func WriteManagedEnvFile(ctx context.Context, projectsDirectory, projectPath, fileName string, unreadable bool, content string) error {
	if unreadable {
		slog.WarnContext(ctx, "skipping unreadable project env file; leaving it untouched", "projectPath", projectPath, "file", fileName)
		return nil
	}

	switch fileName {
	case EffectiveEnvFileName:
		return WriteProjectFile(ctx, projectsDirectory, projectPath, ".env", content)
	case GitSourceEnvFileName:
		return WriteProjectFile(ctx, projectsDirectory, projectPath, GitSourceEnvFileName, content)
	case OverrideEnvFileName:
		if strings.TrimSpace(content) == "" {
			return RemoveProjectFile(ctx, projectsDirectory, projectPath, OverrideEnvFileName)
		}
		return WriteProjectFile(ctx, projectsDirectory, projectPath, OverrideEnvFileName, content)
	default:
		return fmt.Errorf("write managed env file: unsupported file name %q", fileName)
	}
}

// readOptionalProjectFileInternal reads fileName from projectPath. A missing
// file is reported via exists=false with no error. A permission error or a
// directory at the path is reported via unreadable=true with no error: its
// contents cannot be verified, so callers must treat it as absent for merge
// purposes and must not attempt to overwrite or remove it. Any other I/O
// error is still returned as a hard failure.
// A project env file may itself be a symlink whose target lives outside the
// project directory, so the read goes through os rather than the root-confined
// API — the same deliberate exception the .env write path makes (#3556).
func readOptionalProjectFileInternal(projectPath, fileName string) (content string, exists, unreadable bool, err error) {
	raw, readErr := os.ReadFile(filepath.Join(projectPath, fileName))
	if readErr == nil {
		return string(raw), true, false, nil
	}
	if errors.Is(readErr, os.ErrNotExist) {
		return "", false, false, nil
	}
	if errors.Is(readErr, os.ErrPermission) || errors.Is(readErr, syscall.EISDIR) {
		return "", false, true, nil
	}
	return "", false, false, fmt.Errorf("read %s: %w", fileName, readErr)
}

// formatEnvMapInternal serializes env maps into Arcane's canonical generated
// format. This is intentionally lossy: comments are omitted and keys are sorted
// alphabetically to keep persisted merge output stable.
func formatEnvMapInternal(envMap EnvMap) string {
	if len(envMap) == 0 {
		return ""
	}

	keys := slices.Sorted(maps.Keys(envMap))

	var builder strings.Builder
	for _, key := range keys {
		builder.WriteString(key)
		builder.WriteByte('=')
		builder.WriteString(formatEnvValueInternal(envMap[key]))
		builder.WriteByte('\n')
	}

	return builder.String()
}

func formatEnvValueInternal(value string) string {
	if value == "" {
		return value
	}

	value = strings.ReplaceAll(value, "$", "$$")
	needsQuotes := strings.ContainsAny(value, " \t\r\n#\"'") || strings.TrimSpace(value) != value
	if !needsQuotes {
		return value
	}

	escaped := strings.NewReplacer(
		"\\", "\\\\",
		`"`, `\"`,
		"\t", `\t`,
		"\n", `\n`,
		"\r", `\r`,
	).Replace(value)

	return `"` + escaped + `"`
}

// ComposeEnvOptions holds the deployment-relevant Docker Compose pre-defined
// environment variables parsed from a project's merged environment.
type ComposeEnvOptions struct {
	// ConfigFiles is the resolved, absolute COMPOSE_FILE selection in order (the
	// first entry is the base file). Nil when COMPOSE_FILE is unset.
	ConfigFiles []string
	// Profiles is the COMPOSE_PROFILES selection.
	Profiles []string
	// ProjectName is COMPOSE_PROJECT_NAME (not normalized).
	ProjectName string
	// EnvFiles is the resolved, absolute COMPOSE_ENV_FILES selection in order.
	EnvFiles []string
	// RemoveOrphans is COMPOSE_REMOVE_ORPHANS.
	RemoveOrphans bool
	// IgnoreOrphans is COMPOSE_IGNORE_ORPHANS.
	IgnoreOrphans bool
	// ParallelLimit is COMPOSE_PARALLEL_LIMIT; 0 means unset.
	ParallelLimit int
}

// ParseComposeEnvOptions extracts the deployment-relevant COMPOSE_* variables
// from an already-merged environment map. Malformed path selections return a
// classified common.ErrComposeFileEnvInvalid; malformed scalars are ignored
// with a debug log, matching `docker compose`'s tolerance.
func ParseComposeEnvOptions(workdir string, env EnvMap) (ComposeEnvOptions, error) {
	opts := ComposeEnvOptions{
		ProjectName: strings.TrimSpace(env[consts.ComposeProjectName]),
	}

	files, err := resolveComposeFileSelectionInternal(workdir, env)
	if err != nil {
		return ComposeEnvOptions{}, err
	}
	opts.ConfigFiles = files

	if raw := strings.TrimSpace(env[consts.ComposeProfiles]); raw != "" {
		opts.Profiles = kit.TrimNonEmpty(strings.Split(raw, ","))
	}

	for _, entry := range ComposeEnvFileEntriesFromEnv(env) {
		resolved, resErr := ResolvePathWithinDir(workdir, entry)
		if resErr != nil {
			return ComposeEnvOptions{}, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_ENV_FILES entry %q: %w", entry, resErr))
		}
		opts.EnvFiles = append(opts.EnvFiles, resolved)
	}

	opts.RemoveOrphans = parseComposeBoolInternal(env, composeRemoveOrphansKey)
	opts.IgnoreOrphans = parseComposeBoolInternal(env, composeIgnoreOrphansKey)

	if raw := strings.TrimSpace(env[composeParallelLimitKey]); raw != "" {
		if n, convErr := strconv.Atoi(raw); convErr == nil && n > 0 {
			opts.ParallelLimit = n
		} else {
			slog.DebugContext(context.Background(), "ignoring invalid COMPOSE_PARALLEL_LIMIT", "value", raw) //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
		}
	}

	return opts, nil
}

// ComposeFileEnvSelection resolves the COMPOSE_FILE selection for dir with the
// same layering EnvLoader.LoadEnvironment uses at deployment: .env.global from
// projectsDir first, the project .env on top, then any COMPOSE_ENV_FILES
// entries. Returns nil when the merged environment does not set COMPOSE_FILE.
// COMPOSE_DISABLE_ENV_FILE (declared in .env.global) skips the project .env, as
// `docker compose` does; a global COMPOSE_FILE still applies. An empty
// projectsDir skips the global layer.
func ComposeFileEnvSelection(ctx context.Context, projectsDir, dir string) ([]string, error) {
	envMap := make(EnvMap)
	if strings.TrimSpace(projectsDir) != "" {
		globalEnvPath := filepath.Join(projectsDir, GlobalEnvFileName)
		globalEnv, err := loadCachedEnvFileInternal(ctx, globalEnvFileCache, globalEnvPath+"\x00compose-file-selection", globalEnvPath, envMap)
		if err != nil {
			return nil, err
		}
		maps.Copy(envMap, globalEnv.values)
	}

	// COMPOSE_DISABLE_ENV_FILE skips the project .env; it is read only from the
	// sources merged so far (.env.global), matching LoadEnvironment.
	if !parseComposeBoolInternal(envMap, consts.ComposeDisableDefaultEnvFile) {
		projectEnvPath := filepath.Join(dir, EffectiveEnvFileName)
		projectEnv, err := ParseProjectEnvFile(projectEnvPath, envMap)
		if err != nil {
			if errors.Is(err, os.ErrPermission) {
				return nil,
					common.Classify(common.ErrProjectEnvUnreadable,
						fmt.Errorf("%s is not readable by the runtime user (uid %d, gid %d); fix its ownership/read permission or set PUID/PGID to a user that can read it: %w",
							projectEnvPath,
							os.Geteuid(),
							os.Getegid(),
							err))
			}
			return nil, err
		}
		maps.Copy(envMap, projectEnv)
	}
	if len(envMap) == 0 {
		return nil, nil
	}
	mergeComposeEnvFilesInternal(ctx, dir, envMap, ParseProjectEnvFile, nil)
	return resolveComposeFileSelectionInternal(dir, envMap)
}

// ComposeFileEntriesFromEnv returns the raw COMPOSE_FILE entries declared in env
// (split on COMPOSE_PATH_SEPARATOR, ":" by default), or nil when unset. Entries
// are not resolved, validated, or stat'd.
func ComposeFileEntriesFromEnv(env EnvMap) []string {
	raw, ok := env[consts.ComposeFilePath]
	if !ok || strings.TrimSpace(raw) == "" {
		return nil
	}

	separator := defaultComposePathSeparator
	if custom := strings.TrimSpace(env[consts.ComposePathSeparator]); custom != "" {
		separator = custom
	}

	return kit.TrimNonEmpty(strings.Split(raw, separator))
}

// ComposeEnvFileEntriesFromEnv returns the raw COMPOSE_ENV_FILES entries
// declared in env (comma-separated), or nil when unset. Entries are not
// resolved, validated, or stat'd.
func ComposeEnvFileEntriesFromEnv(env EnvMap) []string {
	raw := strings.TrimSpace(env[composeEnvFilesKey])
	if raw == "" {
		return nil
	}
	return kit.TrimNonEmpty(strings.Split(raw, ","))
}

// resolveComposeFileSelectionInternal parses COMPOSE_FILE from env into an
// ordered list of absolute compose-file paths, or nil when COMPOSE_FILE is
// unset. Every entry must be a relative path to an existing file within
// workdir; the first entry (the base file) must sit directly in workdir.
func resolveComposeFileSelectionInternal(workdir string, env EnvMap) ([]string, error) {
	entries := ComposeFileEntriesFromEnv(env)
	if len(entries) == 0 {
		return nil, nil
	}

	absWorkdir, err := filepath.Abs(filepath.Clean(workdir))
	if err != nil {
		return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("resolve project directory: %w", err))
	}

	files := make([]string, 0, len(entries))
	for i, entry := range entries {
		if filepath.IsAbs(entry) {
			return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q must be relative to the project directory", entry))
		}

		resolved, resErr := ResolvePathWithinDir(absWorkdir, entry)
		if resErr != nil {
			return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q: %w", entry, resErr))
		}

		if i == 0 && filepath.Dir(resolved) != absWorkdir {
			return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("the first COMPOSE_FILE entry %q must be in the project directory", entry))
		}

		// os.Stat rather than acfs: compose files may be symlinks resolving
		// outside any confinement root, and workdir can be an imported project
		// living outside the projects directory.
		info, statErr := os.Stat(resolved)
		if statErr != nil {
			return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q: %w", entry, statErr))
		}
		if info.IsDir() {
			return nil, common.Classify(common.ErrComposeFileEnvInvalid, fmt.Errorf("COMPOSE_FILE entry %q is a directory", entry))
		}

		files = append(files, resolved)
	}

	return files, nil
}

// mergeComposeEnvFilesInternal merges each COMPOSE_ENV_FILES entry (in order,
// later wins) on top of envMap; bad entries are warned and skipped. Unlike
// `docker compose`, the entries are additive on top of the project .env rather
// than a replacement: .env is Arcane's managed effective env file and the place
// COMPOSE_ENV_FILES itself is declared, so replacing it would be self-defeating.
func mergeComposeEnvFilesInternal(ctx context.Context, workdir string, envMap EnvMap, parse func(path string, contextEnv EnvMap) (EnvMap, error), onMerged func(values EnvMap)) {
	for _, entry := range ComposeEnvFileEntriesFromEnv(envMap) {
		resolved, err := ResolvePathWithinDir(workdir, entry)
		if err != nil {
			slog.WarnContext(ctx, "skipping COMPOSE_ENV_FILES entry outside project directory", "entry", entry, "error", err)
			continue
		}
		// os.Stat rather than acfs: env files may be symlinks resolving outside
		// any confinement root (a supported setup).
		if _, statErr := os.Stat(resolved); statErr != nil {
			slog.WarnContext(ctx, "COMPOSE_ENV_FILES entry not found", "path", resolved, "error", statErr)
			continue
		}
		values, err := parse(resolved, envMap)
		if err != nil {
			slog.WarnContext(ctx, "failed to load COMPOSE_ENV_FILES entry", "path", resolved, "error", err)
			continue
		}
		if len(values) == 0 {
			continue
		}
		maps.Copy(envMap, values)
		if onMerged != nil {
			onMerged(values)
		}
	}
}

func parseComposeBoolInternal(env EnvMap, key string) bool {
	raw := strings.TrimSpace(env[key])
	if raw == "" {
		return false
	}
	v, err := strconv.ParseBool(raw)
	if err != nil {
		slog.DebugContext(context.Background(), "ignoring invalid compose boolean env var", //nolint:forbidigo // Compose environment parsing is a pure helper without a request context.
			"key", key, "value", raw)
		return false
	}
	return v
}