config

type ClientShim struct {
	Name     string   `yaml:"name" json:"name"`
	Binaries []string `yaml:"binary,omitempty" json:"binary,omitempty"`
}

type CommandNotFoundError struct{ Name string }

type CommandValidationError struct{ Reason string }

type ContainerConfig struct {
	Port          int    `yaml:"port"`                    // port the app listens on inside the container (required)
	Containerfile string `yaml:"containerfile,omitempty"` // path to Containerfile, default "Containerfile.lerd"
	BuildContext  string `yaml:"build_context,omitempty"` // build context directory, default "."
	Target        string `yaml:"target,omitempty"`        // multi-stage build target passed as --target to podman build
	SSL           bool   `yaml:"ssl,omitempty"`           // proxy to the container via HTTPS (app serves TLS on its port)
}

type CustomService struct {
	Name          string            `yaml:"name"`
	Image         string            `yaml:"image"`
	Ports         []string          `yaml:"ports,omitempty"`
	Environment   map[string]string `yaml:"environment,omitempty"`
	DataDir       string            `yaml:"data_dir,omitempty"`
	Exec          string            `yaml:"exec,omitempty"`
	EnvVars       []string          `yaml:"env_vars,omitempty"`
	EnvDetect     *EnvDetect        `yaml:"env_detect,omitempty"`
	SiteInit      *SiteInit         `yaml:"site_init,omitempty"`
	Dashboard     string            `yaml:"dashboard,omitempty"`
	ConnectionURL string            `yaml:"connection_url,omitempty"`
	Description   string            `yaml:"description,omitempty"`
	DependsOn     []string          `yaml:"depends_on,omitempty"`
	// Files is deprecated as a YAML user field but kept with its yaml tag so
	// LoadCustomServiceFromFile can detect legacy on-disk entries and migrate
	// them away. The authoritative source of file mounts is presetFiles in
	// preset_files.go, looked up by Preset at materialise time.
	Files []FileMount `yaml:"files,omitempty"`
	// Family groups related services so admin UIs can auto-discover every
	// member. e.g. the mysql preset declares family: mysql, and phpMyAdmin
	// uses dynamic_env to read all family members at quadlet generation time.
	Family string `yaml:"family,omitempty"`
	// Tuning, when set, exposes a user-editable runtime config override
	// for this service via the web UI's Config tab and the
	// `lerd service config` CLI. Custom services declare their own
	// override path here without needing a known family — the built-in
	// mysql/mariadb/redis families remain the fallback when this is nil.
	// See ServiceTuningMount / ServiceTuningTemplate / ServiceTuningCommand.
	Tuning *TuningSpec `yaml:"tuning,omitempty"`
	// Preset is the bundled preset name this service was installed from.
	// Set by InstallPresetByName. Used so the init wizard can store a
	// preset reference in .lerd.yaml instead of an inlined definition.
	Preset string `yaml:"preset,omitempty"`
	// PresetVersion is the picked version tag for multi-version presets.
	// Empty for single-version presets.
	PresetVersion string `yaml:"preset_version,omitempty"`
	// PreviousImage is set by the update flow to the image that was running
	// before the last update, so a one-click rollback can swap back to it.
	// Toggled on each rollback so consecutive rollbacks redo the update.
	PreviousImage string `yaml:"previous_image,omitempty"`
	// LastOp is "update" or "migrate" — set by serviceops to mark whether the
	// most recent change is rollback-safe. Migrate is one-way: rolling back the
	// image without restoring the pre-migrate data dir would run the old binary
	// against the new schema, so the rollback path refuses unless this is empty
	// or "update".
	LastOp string `yaml:"last_op,omitempty"`
	// PreMigrateBackup is the absolute host path to the data dir that was
	// preserved when the most recent op was a migrate.
	PreMigrateBackup string `yaml:"pre_migrate_backup,omitempty"`
	// ShareHosts mounts the browser-testing hosts file
	// (~/.local/share/lerd/browser-hosts) into the container at /etc/hosts,
	// so the container can resolve .test domains to the nginx container's IP
	// on the Podman network. Used by browser testing services like Selenium
	// that need to reach lerd sites by domain name.
	ShareHosts bool `yaml:"share_hosts,omitempty" json:"share_hosts,omitempty"`
	// DynamicEnv declares container env vars whose value is computed at
	// quadlet generation time. Currently supported directive:
	//   discover_family:<name>  -> comma-joined hostnames of every installed
	//   service in the named family (built-in or custom).
	DynamicEnv map[string]string `yaml:"dynamic_env,omitempty"`
	// Userns sets the quadlet UserNS= line verbatim, e.g. "keep-id:uid=1000,gid=0"
	// for images whose process runs as a non-root UID and needs that UID
	// mapped to the host user for bind-mounted volumes.
	Userns string `yaml:"userns,omitempty"`
	// ChownData adds :U to the data_dir mount so podman re-chowns the host
	// directory to the container's expected UID at mount time. Pair with
	// Userns to keep bind-mounted data writable to non-root container users.
	ChownData bool `yaml:"chown_data,omitempty"`
	// DashboardExternal opens the dashboard URL in a new browser tab instead
	// of embedding it as an iframe. Use for admin UIs that set session
	// cookies the iframe can't carry across origins (e.g. RabbitMQ Cowboy).
	DashboardExternal bool `yaml:"dashboard_external,omitempty" json:"dashboard_external,omitempty"`
	// Init injects podman's catatonit as PID 1 (--init) so SIGTERM gets
	// forwarded to the container's main process. Required for images whose
	// main binary (e.g. mysqld in mysql:8.4) doesn't install a signal
	// handler when it runs as PID 1, which makes podman stop time out and
	// systemctl restart wedge for ~90s.
	Init bool `yaml:"init,omitempty" json:"init,omitempty"`
	// ClientShims lists the client tools this service exposes as host shims
	// (mysqldump, pg_dump, psql…) so host tools and IDEs can run them against
	// external databases. Empty for services with nothing to expose.
	ClientShims []ClientShim `yaml:"client_shims,omitempty" json:"client_shims,omitempty"`
}

type DoctorCheck struct {
	Name  string `yaml:"name"`
	Type  string `yaml:"type"`
	Label string `yaml:"label,omitempty"`
	// Fix names a command from the framework's command set a UI can run to
	// resolve the finding, so the doctor never grows its own mutation endpoints.
	Fix string `yaml:"fix,omitempty"`
	// Detail overrides the generated finding message when set.
	Detail string `yaml:"detail,omitempty"`
	// Severity overrides the triggered status ("warn" or "fail"); each type has
	// a sensible default (command→fail, the rest→warn).
	Severity string `yaml:"severity,omitempty"`

	// env_key_set
	EnvKey string `yaml:"env_key,omitempty"`

	// env_combo
	When   map[string]string `yaml:"when,omitempty"`
	WarnIf map[string]string `yaml:"warn_if,omitempty"`

	// symlink
	Link        string `yaml:"link,omitempty"`
	Target      string `yaml:"target,omitempty"`
	RequiresDir string `yaml:"requires_dir,omitempty"`

	// command
	Command              string `yaml:"command,omitempty"`
	FailIfOutputContains string `yaml:"fail_if_output_contains,omitempty"`
	UnknownOnError       bool   `yaml:"unknown_on_error,omitempty"`
	TimeoutSeconds       int    `yaml:"timeout,omitempty"`
}

type EnvDetect struct {
	Key         string `yaml:"key,omitempty"`
	ValuePrefix string `yaml:"value_prefix,omitempty"`
	// Composer triggers detection when the named package is present in the
	// project's composer.json (require or require-dev). Used instead of Key
	// when the service should be auto-detected by a dependency rather than
	// an existing .env variable (e.g. selenium detected via laravel/dusk).
	Composer string `yaml:"composer,omitempty"`
}

type EnvKeyGeneration struct {
	EnvKey         string `yaml:"env_key"`                   // env var to check/set (e.g. "APP_KEY")
	Command        string `yaml:"command,omitempty"`         // console command to run if vendor/ exists, via the framework's console binary (e.g. "key:generate")
	FallbackPrefix string `yaml:"fallback_prefix,omitempty"` // prefix for random key fallback (e.g. "base64:")
}

type FileMount struct {
	// Target is the absolute path inside the container where the file appears.
	Target string `yaml:"target"`
	// Content is the literal file body, written verbatim. Ignored when
	// ContentFn is set.
	Content string `yaml:"content"`
	// ContentFn dynamically generates the file body at materialise time
	// based on the resolved service (e.g. to inject family-discovered
	// hosts into pgAdmin's servers.json). Not loadable from YAML directly;
	// a preset selects one by name via Generator.
	ContentFn func(*CustomService) (string, error) `yaml:"-"`
	// Generator names a built-in content generator (see presetFileGenerators)
	// for dynamic mounts a preset can't express as static Content, such as
	// pgAdmin's family-discovered servers.json. Resolved to ContentFn when the
	// preset's files are read; an unknown name is skipped, not fatal, so a store
	// preset built for a newer lerd degrades gracefully.
	Generator string `yaml:"generator,omitempty"`
	// Mode is the octal permission bits, e.g. "0600". Defaults to "0644".
	Mode string `yaml:"mode,omitempty"`
	// Chown adds the :U flag to the volume mount so podman re-chowns the file
	// to match the container's expected UID. Required when the in-container
	// process runs as a non-root user (e.g. pgAdmin runs as uid 5050) and the
	// file mode would otherwise hide it from that user (e.g. 0600).
	Chown bool `yaml:"chown,omitempty"`
}

type Framework struct {
	Name  string `yaml:"name"`
	Label string `yaml:"label"`
	// Version is the framework major version this definition targets (e.g. "11", "7").
	Version string `yaml:"version,omitempty"`
	// DetectedVersion is the project's real major version when it differs from
	// Version because no exact definition existed and we clamped to the nearest
	// available one. Runtime only, never serialized.
	DetectedVersion string `yaml:"-"`
	// VersionGuessed is true when Version was clamped to a borrowed definition
	// because the detected version had none of its own (Laravel 6 served by the
	// Laravel 10 definition); callers must not clamp PHP to its range.
	VersionGuessed bool `yaml:"-"`
	// PHP defines the supported PHP version range for this framework version.
	PHP       FrameworkPHP    `yaml:"php,omitempty"`
	Detect    []FrameworkRule `yaml:"detect,omitempty"`
	PublicDir string          `yaml:"public_dir"`
	// SourceDirs overrides which project directories the activity watcher treats
	// as source for idle-suspend (a save there keeps the site awake). When empty,
	// config.DefaultSourceDirs applies. Paths are relative to the project root.
	SourceDirs []string                   `yaml:"source_dirs,omitempty"`
	Env        FrameworkEnvConf           `yaml:"env,omitempty"`
	Composer   string                     `yaml:"composer,omitempty"` // auto | true | false
	NPM        string                     `yaml:"npm,omitempty"`      // auto | true | false
	Workers    map[string]FrameworkWorker `yaml:"workers,omitempty"`
	Setup      []FrameworkSetupCmd        `yaml:"setup,omitempty"`
	// Commands are on-demand actions surfaced in the dashboard "Run command"
	// dropdown. See FrameworkCommand for the schema. Projects extend or
	// override this list in .lerd.yaml; use ResolveCommands to merge.
	Commands []FrameworkCommand `yaml:"commands,omitempty"`
	// Console is the console command to run (without 'php' prefix).
	// Example: "artisan", "bin/console"
	Console string `yaml:"console,omitempty"`
	// Tinker, when set, defines how to run an interactive PHP REPL for
	// this framework (the in-browser Tinker tab + `lerd tinker` CLI).
	// Absent → fall back to plain `php` execution.
	Tinker *FrameworkTinker `yaml:"tinker,omitempty"`
	// Create is the scaffold command used by "lerd new". The target directory is appended automatically.
	// Example: "composer create-project --no-install --no-plugins --no-scripts laravel/laravel"
	Create string `yaml:"create,omitempty"`
	// Logs defines where application log files live for this framework.
	Logs []FrameworkLogSource `yaml:"logs,omitempty"`
	// Favicon is the path to the favicon file relative to the public directory.
	// When set, detectFavicon checks this path in addition to the standard candidates.
	// Example: "core/misc/favicon.ico" for Drupal.
	Favicon string `yaml:"favicon,omitempty"`
	// FrankenPHP, when set, tells lerd how to start a FrankenPHP container
	// for this framework. When absent, lerd falls back to the generic
	// `frankenphp php-server -r <public>/` entrypoint.
	FrankenPHP *FrameworkFrankenPHP `yaml:"frankenphp,omitempty"`
	// Doctor, when set, declares framework-specific health checks the site
	// doctor runs in addition to the universal defaults (env, dependency, and
	// audit checks every framework gets). See FrameworkDoctor.
	Doctor *FrameworkDoctor `yaml:"doctor,omitempty"`
}

type FrameworkCommand struct {
	Name        string         `yaml:"name" json:"name"`                                   // stable identifier, also the `lerd run` argument
	Label       string         `yaml:"label" json:"label"`                                 // human label shown in the UI
	Command     string         `yaml:"command" json:"command"`                             // shell command, passed to `sh -c`
	Description string         `yaml:"description,omitempty" json:"description,omitempty"` // one-line description for tooltips
	Output      string         `yaml:"output,omitempty" json:"output,omitempty"`           // silent | text | url | terminal (default: silent)
	Confirm     bool           `yaml:"confirm,omitempty" json:"confirm,omitempty"`         // gate behind a confirm modal before running
	Icon        string         `yaml:"icon,omitempty" json:"icon,omitempty"`               // icon name from the known set
	Check       *FrameworkRule `yaml:"check,omitempty" json:"check,omitempty"`             // hide the command when this rule fails
	CWD         string         `yaml:"cwd,omitempty" json:"cwd,omitempty"`                 // working dir relative to project root (default: ".")
	// Disabled, in a project .lerd.yaml entry, suppresses the framework default
	// of the same Name without replacing it. Ignored when read from a framework yaml.
	Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
	// ProjectOrigin marks a command that came from the untrusted project .lerd.yaml
	// (top-level commands or framework_def), so the host-execution gate can require
	// consent before running it. Never persisted; set only at the merge point.
	ProjectOrigin bool `yaml:"-" json:"-"`
}

type FrameworkDoctor struct {
	Checks []DoctorCheck `yaml:"checks,omitempty"`
}

type FrameworkEnvConf struct {
	File           string `yaml:"file,omitempty"`            // primary env file (relative to project)
	ExampleFile    string `yaml:"example_file,omitempty"`    // example to copy from if File missing
	Format         string `yaml:"format,omitempty"`          // dotenv | php-const (default: dotenv)
	FallbackFile   string `yaml:"fallback_file,omitempty"`   // used when File doesn't exist
	FallbackFormat string `yaml:"fallback_format,omitempty"` // format for FallbackFile

	// URLKey is the env key that holds the application URL (default: APP_URL).
	URLKey string `yaml:"url_key,omitempty"`

	// Vars are unconditional KEY=VALUE env defaults the framework always wants
	// applied during `lerd env`, regardless of which services are detected
	// (e.g. CodeIgniter's CI_ENVIRONMENT=development for local dev). They
	// support the same {{...}} template placeholders as service vars and are
	// applied as defaults, so detected-service values and personal
	// .env.lerd_override entries still win over them.
	Vars []string `yaml:"vars,omitempty"`

	// Services defines per-service detection rules and env vars to apply.
	// Keys match the built-in service names: mysql, postgres, redis, meilisearch, rustfs, mailpit.
	Services map[string]FrameworkServiceDef `yaml:"services,omitempty"`

	// KeyGeneration describes how to generate an application key if missing.
	KeyGeneration *EnvKeyGeneration `yaml:"key_generation,omitempty"`
}

type FrameworkFetchFunc func(name, version string) (*Framework, error)

type FrameworkFile struct {
	Path    string
	Version string // "" for unversioned
	Source  FrameworkSource
}

type FrameworkFrankenPHP struct {
	// Entrypoint is the command to run when the site is served in normal
	// (non-worker) FrankenPHP mode. Example: ["php","artisan","octane:start",
	// "--server=frankenphp","--host=0.0.0.0","--port=8000"].
	Entrypoint []string `yaml:"entrypoint,omitempty"`
	// WorkerEntrypoint, when set and the site opts into worker mode, is used
	// instead of Entrypoint. When SupportsWorker is false the flag is ignored.
	WorkerEntrypoint []string `yaml:"worker_entrypoint,omitempty"`
	// WorkerReloadEntrypoint, when set, is the watch-enabled variant of
	// WorkerEntrypoint, selected instead of it when the project opts the
	// "octane" worker into auto-reload (restart on file changes) for
	// development. Keeping the watch flag in the framework definition rather
	// than rewriting WorkerEntrypoint in Go means the store stays the single
	// source of truth for what runs; core only appends the platform polling
	// flag on hosts where the container can't observe filesystem events (see
	// ResolveFrankenPHPWorkerEntrypoint). Laravel sets it to the octane:start
	// command with --watch.
	WorkerReloadEntrypoint []string `yaml:"worker_reload_entrypoint,omitempty"`
	// SupportsWorker declares whether the framework ships a FrankenPHP worker
	// script. If false, `--worker` is a no-op and the regular entrypoint is used.
	SupportsWorker bool `yaml:"supports_worker,omitempty"`
	// Env is the list of environment variables to set in the container in
	// normal mode (appended to the defaults lerd always sets).
	Env map[string]string `yaml:"env,omitempty"`
	// WorkerEnv, when the site opts into worker mode, is merged on top of Env.
	// Example for Symfony: {"FRANKENPHP_CONFIG": "worker ./public/index.php"}.
	WorkerEnv map[string]string `yaml:"worker_env,omitempty"`
}

type FrameworkInfo struct {
	*Framework
	Source FrameworkSource
}

type FrameworkLogSource struct {
	Path   string `yaml:"path"`             // glob relative to project root, e.g. "storage/logs/*.log"
	Format string `yaml:"format,omitempty"` // "monolog" | "raw" (default: "raw")
}

type FrameworkPHP struct {
	Min string `yaml:"min,omitempty"` // minimum PHP version (e.g. "8.2")
	Max string `yaml:"max,omitempty"` // maximum PHP version (e.g. "8.4")
}

type FrameworkRule struct {
	File             string   `yaml:"file,omitempty" json:"file,omitempty"`                           // file must exist in project root
	Composer         string   `yaml:"composer,omitempty" json:"composer,omitempty"`                   // package must be in composer.json require/require-dev
	ComposerSections []string `yaml:"composer_sections,omitempty" json:"composer_sections,omitempty"` // extra composer.json keys to search (e.g. flex-require)
	VersionKey       string   `yaml:"version_key,omitempty" json:"version_key,omitempty"`             // dot-path to version in composer.json (e.g. extra.symfony.require)
	VersionFile      string   `yaml:"version_file,omitempty" json:"version_file,omitempty"`           // file to read version from (relative to project root)
	VersionPattern   string   `yaml:"version_pattern,omitempty" json:"version_pattern,omitempty"`     // regex with capture group for version (e.g. "\\$wp_version = '([^']+)'")
}

type FrameworkServiceDef struct {
	// Detect lists env key conditions; any match signals the service is in use.
	Detect []FrameworkServiceDetect `yaml:"detect,omitempty"`
	// Vars is the list of KEY=VALUE pairs to apply when the service is detected.
	// Use {{site}} for the per-project database name.
	Vars []string `yaml:"vars,omitempty"`
}

type FrameworkServiceDetect struct {
	Key         string `yaml:"key"`
	ValuePrefix string `yaml:"value_prefix,omitempty"`
}

type FrameworkSetupCmd struct {
	Label   string         `yaml:"label"`
	Command string         `yaml:"command"`
	Default bool           `yaml:"default,omitempty"`
	Check   *FrameworkRule `yaml:"check,omitempty"` // only show when check passes (file exists or composer package installed)
}

type FrameworkSource string

type FrameworkTinker struct {
	// Command is the argv to run, the first item is typically the entry
	// script (e.g. "artisan", "bin/console psysh"). Each item is passed
	// verbatim to `podman exec … php <Command…>`.
	// Example for Laravel: ["artisan", "tinker"]
	// Example for Symfony+psysh: ["vendor/bin/psysh"]
	Command []string `yaml:"command"`
	// ExecuteFlag, when set, is the flag used to pass user code as a
	// single argument. Example: "--execute" → `--execute=<code>`.
	// Mutually exclusive with ExecutePositional.
	ExecuteFlag string `yaml:"execute_flag,omitempty"`
	// ExecutePositional, when true, appends user code as a final
	// positional argv element instead of using a flag. Useful for tools
	// like `drush php:eval <code>` and `wp eval <code>` that take code
	// as a bare argument. Mutually exclusive with ExecuteFlag.
	ExecutePositional bool `yaml:"execute_positional,omitempty"`
	// When neither ExecuteFlag nor ExecutePositional is set, user code
	// is piped to the process via stdin.
	//
	// RequiresPackage is the composer package that must be installed in
	// vendor/ for this REPL to work. Example: "laravel/tinker".
	// When the package isn't found, lerd falls back to plain PHP.
	RequiresPackage string `yaml:"requires_package,omitempty"`
	// RequiresFile, similarly, is a relative path that must exist for
	// this REPL to be usable (e.g. "artisan"). Defaults to no check.
	RequiresFile string `yaml:"requires_file,omitempty"`
}

type FrameworkWorker struct {
	Label   string `yaml:"label,omitempty"`
	Command string `yaml:"command"`
	// ReloadCommand is the alternate command run when a project opts this
	// worker into auto-reload (restart on file changes) for development.
	// Empty means the worker has no reload variant. Laravel's horizon worker
	// sets it to "php artisan horizon:listen"; core selects it over Command
	// when the project enables reload for the worker and, on platforms where
	// the container cannot observe host filesystem events, appends the polling
	// flag (see resolveWorkerCommand). Keeping the literal command text in the
	// framework definition rather than rewriting Command in Go means the store
	// stays the single source of truth for what actually runs.
	ReloadCommand string `yaml:"reload_command,omitempty"`
	// TuneCommand is the parameterized variant of Command for `lerd queue:start`,
	// a template with {queue}/{tries}/{timeout} placeholders so each framework
	// declares its own flag syntax. Empty falls back to Command verbatim.
	TuneCommand string `yaml:"tune_command,omitempty"`
	// RestartCommand gracefully restarts the queue worker in-container (e.g.
	// Laravel's "php artisan queue:restart"). Empty means no graceful restart.
	RestartCommand string         `yaml:"restart_command,omitempty"`
	Restart        string         `yaml:"restart,omitempty"`        // always | on-failure (default: always)
	Schedule       string         `yaml:"schedule,omitempty"`       // systemd OnCalendar expression (e.g. "minutely"); when set, the worker is run as a Type=oneshot service triggered by a .timer rather than a long-running daemon. Use this for Laravel <=10 schedule:run, cron-style cleanup tasks, etc.
	Check          *FrameworkRule `yaml:"check,omitempty"`          // only show when check passes (file exists or composer package installed)
	ExcludeCheck   *FrameworkRule `yaml:"exclude_check,omitempty"`  // only show when check FAILS (e.g. queue is hidden when laravel/horizon is installed because horizon supersedes it)
	ConflictsWith  []string       `yaml:"conflicts_with,omitempty"` // workers to stop before starting this one (e.g. horizon conflicts_with queue)
	Proxy          *WorkerProxy   `yaml:"proxy,omitempty"`          // WebSocket/HTTP proxy config for nginx
	Host           bool           `yaml:"host,omitempty"`           // run on the host via fnm instead of inside the PHP-FPM container
	// PerWorktree opts the worker into running independently per git worktree
	// (lerd-<wname>-<site>-<wt>). Defaults to false; set true on workers that
	// need a separate process per checkout (e.g. dev servers like vite).
	PerWorktree *bool `yaml:"per_worktree,omitempty"`
	// ReplacesBuild declares that, while this worker is running, the framework
	// can render pages without a static asset build. Used by lerd worktree add
	// and lerd setup to skip the npm run build step when the user opted into
	// such a worker (vite is the canonical case).
	ReplacesBuild bool `yaml:"replaces_build,omitempty"`
	// ProjectOrigin marks a worker that came from the untrusted project .lerd.yaml
	// (custom_workers), so the host-execution gate can require consent for it.
	// Never persisted; set only at the merge point.
	ProjectOrigin bool `yaml:"-" json:"-"`
}

type FrankenPHPHint struct {
	// Signal is a short machine-readable tag: "laravel-octane-franken",
	// "symfony-runtime", "runtime-frankenphp", "containerfile", "caddyfile".
	Signal string
	// Reason is a one-line human-readable explanation.
	Reason string
}

type GlobalConfig struct {
	// Editor is the command lerd runs to open a file at a line (the
	// "open in editor" links in the dashboard). Optional {file} and {line}
	// placeholders; if omitted, lerd appends the file. Empty = autodetect a
	// known GUI editor (code/cursor/phpstorm/subl/zed), then xdg-open/open.
	Editor string `yaml:"editor,omitempty" mapstructure:"editor"`
	PHP    struct {
		DefaultVersion string            `yaml:"default_version" mapstructure:"default_version"`
		XdebugEnabled  map[string]bool   `yaml:"xdebug_enabled"  mapstructure:"xdebug_enabled"`
		XdebugMode     map[string]string `yaml:"xdebug_mode,omitempty" mapstructure:"xdebug_mode"`
		// XdebugStart maps a PHP version to its xdebug.start_with_request value
		// (yes | trigger | no). Absent means the default "yes" (connect on every
		// request). "trigger"/"no" support on-demand debugging via the control
		// socket without flooding the IDE from every request and worker.
		XdebugStart map[string]string   `yaml:"xdebug_start,omitempty" mapstructure:"xdebug_start"`
		Extensions  map[string][]string `yaml:"extensions"      mapstructure:"extensions"`
		// ExtApkDeps maps a custom extension name to extra Alpine packages its
		// build needs. Keyed by extension (deps don't vary by PHP version).
		// lerd already knows the deps for some extensions; this is for the rest.
		ExtApkDeps map[string][]string `yaml:"ext_apk_deps,omitempty" mapstructure:"ext_apk_deps"`
		// Packages maps a PHP version to extra Alpine packages to install in the
		// FPM image's runtime stage (lerd php:pkg). For CLI tools and runtime
		// libraries users want available in the container; re-applied on rebuild.
		Packages map[string][]string `yaml:"packages,omitempty" mapstructure:"packages"`
		// FPMPorts maps a PHP version to extra host ports published on that
		// version's shared FPM container, so a process bound inside `lerd shell`
		// (a Vite dev server, a websocket, an ad-hoc listener) is reachable at
		// localhost:PORT. Environment-wide per version, not per site; the one
		// shared FPM container per version owns the list, so two sites wanting
		// the same in-container port on the same version collide. Each mapping is
		// a "host:container" spec; the loopback/LAN bind is applied centrally on
		// write. Managed via the PHP page's Ports tab (lerd php:ports).
		FPMPorts map[string][]string `yaml:"fpm_ports,omitempty" mapstructure:"fpm_ports"`
	} `yaml:"php" mapstructure:"php"`
	Node struct {
		DefaultVersion string `yaml:"default_version" mapstructure:"default_version"`
		// Managed records whether lerd manages Node.js via fnm shims. A pointer
		// so a config predating the field (nil) keeps the historical
		// shim-presence behaviour, while an explicit false survives updates that
		// would otherwise re-add the shims a `node:unmanage` removed.
		Managed *bool `yaml:"managed,omitempty" mapstructure:"managed"`
	} `yaml:"node" mapstructure:"node"`
	Nginx struct {
		HTTPPort  int `yaml:"http_port"  mapstructure:"http_port"`
		HTTPSPort int `yaml:"https_port" mapstructure:"https_port"`
		// RequestTimeout is the default nginx request timeout in seconds,
		// overridable per project via .lerd.yaml request_timeout. Zero falls
		// back to nginx's own 60s default; read it via RequestTimeoutSeconds.
		RequestTimeout int `yaml:"request_timeout,omitempty" mapstructure:"request_timeout"`
	} `yaml:"nginx" mapstructure:"nginx"`
	DNS struct {
		// Enabled=false skips lerd-dns, mkcert CA, sudoers, and resolver
		// config; sites use *.localhost (RFC 6761). HTTPS is unavailable
		// in that mode. Default true preserves historical behaviour.
		Enabled bool   `yaml:"enabled" mapstructure:"enabled"`
		TLD     string `yaml:"tld"     mapstructure:"tld"`
		// Upstream pins the upstream DNS servers dnsmasq forwards
		// non-.test queries to. When empty, lerd auto-detects them from
		// the system resolver. Set this when auto-detection picks the
		// wrong servers (e.g. systemd-resolved fallbacks instead of your
		// LAN resolver). Accepts plain IPs; #port is allowed.
		Upstream []string `yaml:"upstream,omitempty" mapstructure:"upstream"`
	} `yaml:"dns" mapstructure:"dns"`
	LAN struct {
		// Exposed controls whether lerd's services are reachable from
		// other devices on the local network. When false (the default,
		// safe-on-coffee-shop-wifi state) every container PublishPort is
		// rewritten to bind 127.0.0.1, lerd-ui binds 127.0.0.1:7073, and
		// the lerd-dns-forwarder is stopped. When true, container ports
		// bind 0.0.0.0, lerd-ui binds 0.0.0.0:7073, dnsmasq is rewritten
		// to answer .test queries with the host's LAN IP, and the
		// userspace lerd-dns-forwarder runs to bridge LAN-IP:5300 to the
		// loopback-only DNS container.
		//
		// Toggled via `lerd lan:expose on/off`. The previous standalone
		// `dns:expose` flag was folded in here because there is no
		// meaningful state where the DNS resolver answers the LAN but
		// the actual services don't.
		Exposed bool `yaml:"exposed,omitempty" mapstructure:"exposed"`
	} `yaml:"lan,omitempty" mapstructure:"lan"`
	Autostart struct {
		// Disabled controls whether lerd boots itself at login. The
		// zero value (false) means lerd autostarts as it always has:
		// every lerd-* container quadlet ships with its [Install]
		// section, the podman generator wires it into
		// default.target.wants on every daemon-reload, and the
		// lerd-ui / lerd-watcher / per-site worker units are enabled.
		// Setting this to true makes WriteQuadletDiff strip the
		// [Install] section before write (so the generator stops
		// emitting wants symlinks), disables ui/watcher and every
		// per-site worker, and stops them. Toggled via
		// `lerd autostart enable / disable` and the dashboard / tray
		// switches.
		//
		// Inverted form (Disabled rather than Enabled) so the YAML zero
		// value preserves the historical autostart-on behaviour for
		// every existing install — users who never touch the toggle
		// see no change.
		Disabled bool `yaml:"disabled,omitempty" mapstructure:"disabled"`
	} `yaml:"autostart,omitempty" mapstructure:"autostart"`
	UI struct {
		// RemoteControl gates non-loopback access to the lerd dashboard.
		// Empty PasswordHash = disabled = LAN clients get 403. With a hash
		// set, LAN clients must present matching HTTP Basic auth. Loopback
		// (127.0.0.1, ::1) always bypasses both checks.
		Username     string `yaml:"username,omitempty" mapstructure:"username"`
		PasswordHash string `yaml:"password_hash,omitempty" mapstructure:"password_hash"`
	} `yaml:"ui,omitempty" mapstructure:"ui"`
	Workers struct {
		// ExecMode controls how framework workers (queue, schedule, horizon,
		// reverb, custom) are launched on macOS. "exec" (default) wraps a
		// single `podman exec` per worker in a dedup guard and lets launchd
		// supervise that process, matching Linux's lower-memory behaviour.
		// "container" runs each worker as its own detached container, which
		// costs more memory per worker but makes the podman supervisor
		// boundary 1:1 and sidesteps the SSH-bridge hiccups that can
		// otherwise produce phantom or duplicate workers.
		//
		// The field is ignored on Linux, which always runs workers as
		// `podman exec` into the shared FPM container (systemd is a
		// dependable supervisor there). Use WorkerExecMode() to read the
		// effective value.
		ExecMode string `yaml:"exec_mode,omitempty" mapstructure:"exec_mode"`
	} `yaml:"workers,omitempty" mapstructure:"workers"`
	Dumps struct {
		// Enabled is the single switch for the whole debug window: the dump
		// bridge AND the lerd_devtools collector (queries, mail, views, events,
		// jobs, http). Both the bridge and the extension read one runtime
		// sentinel (`enabled.flag`); their PHP/ini assets are always mounted
		// regardless of this flag, so what Enabled controls is just that
		// sentinel — touch = capture, missing = fast no-op, no FPM restart.
		// Toggled via `lerd dump on/off` or the dashboard Debug view.
		Enabled bool `yaml:"enabled,omitempty" mapstructure:"enabled"`
		// Passthrough controls whether dump()/dd() ALSO emit to the response
		// while the bridge is enabled. False (default) means captured-only:
		// the dashboard is the single destination and the response stays
		// clean (matching Herd's behaviour). True forwards each call through
		// Symfony's stock VarDumper handler after capture, useful as a
		// safety net when lerd-ui isn't running. No effect when Enabled is
		// false — without the bridge, dump() behaves exactly as Symfony
		// ships it.
		Passthrough bool `yaml:"passthrough,omitempty" mapstructure:"passthrough"`
	} `yaml:"dumps,omitempty" mapstructure:"dumps"`
	Devtools struct {
		// Workers includes long-running queue/scheduler worker queries in
		// capture. Off by default because their constant polling floods the
		// buffer; toggled from the dashboard "Show worker queries" checkbox.
		// The collector's enable state is shared with the debug bridge: one
		// sentinel (enabled.flag) and one config flag (Dumps.Enabled) arm both,
		// so there is no separate devtools enable toggle.
		Workers bool `yaml:"workers,omitempty" mapstructure:"workers"`
	} `yaml:"devtools,omitempty" mapstructure:"devtools"`
	Profiler struct {
		// Enabled toggles the SPX profiler globally. When on, nginx injects
		// SPX_ENABLED into every PHP-FPM site's requests so each is profiled.
		// Toggled via `lerd profile on/off` and the dashboard Profiler view.
		Enabled bool `yaml:"enabled,omitempty" mapstructure:"enabled"`
	} `yaml:"profiler,omitempty" mapstructure:"profiler"`
	Notifications struct {
		// Disabled globally mutes the notifier (WebSocket banners + Web
		// Push fanout). Inverted form so the zero value keeps existing
		// installs on. Toggled via `lerd notify on/off` and the tray.
		Disabled bool `yaml:"disabled,omitempty" mapstructure:"disabled"`
	} `yaml:"notifications,omitempty" mapstructure:"notifications"`
	HostProxy struct {
		// Disabled refuses to set up or start any host-proxy dev-server unit,
		// for users who never want lerd supervising a process on the host.
		// Inverted so the zero value keeps the feature available.
		Disabled bool `yaml:"disabled,omitempty" mapstructure:"disabled"`
		// SkipConfirmation runs a newly-linked host-proxy command without the
		// interactive "start this on your host?" prompt. Off by default so a
		// command from a cloned repo never runs unconfirmed.
		SkipConfirmation bool `yaml:"skip_confirmation,omitempty" mapstructure:"skip_confirmation"`
	} `yaml:"host_proxy,omitempty" mapstructure:"host_proxy"`
	HostCommands struct {
		// Disabled refuses to run any project-supplied host command or host
		// worker (custom_workers / commands from a project .lerd.yaml). Inverted
		// so the zero value keeps the feature available.
		Disabled bool `yaml:"disabled,omitempty" mapstructure:"disabled"`
		// SkipConfirmation runs project-supplied host commands and workers without
		// the interactive confirm. Off by default so a command from a cloned repo
		// never runs unconfirmed.
		SkipConfirmation bool `yaml:"skip_confirmation,omitempty" mapstructure:"skip_confirmation"`
	} `yaml:"host_commands,omitempty" mapstructure:"host_commands"`
	IdleSuspend struct {
		// Enabled turns on activity-driven worker suspension: when a site sees
		// no activity for Timeout, its suspendable workers (queue, horizon, ...)
		// are gracefully stopped and resumed on the next request. Off by default
		// so a quiet dev box reclaims worker memory only once the user opts in.
		// Idle-suspend is a single global policy, not configured per site.
		Enabled bool `yaml:"enabled,omitempty" mapstructure:"enabled"`
		// Timeout is how long a site must be idle before its workers suspend, as
		// a Go duration string ("30m"). Empty or unparseable falls back to
		// DefaultIdleSuspendTimeout; read it via IdleSuspendTimeout.
		Timeout string `yaml:"timeout,omitempty" mapstructure:"timeout"`
	} `yaml:"idle_suspend,omitempty" mapstructure:"idle_suspend"`
	// AutoCleanup lets the watcher periodically reclaim orphaned lerd images
	// (safe tier only, never service images). On by default; set false to turn
	// off the daily sweep. Read it via AutoCleanupEnabled for nil-safety.
	AutoCleanup       bool                     `yaml:"auto_cleanup"       mapstructure:"auto_cleanup"`
	ParkedDirectories []string                 `yaml:"parked_directories" mapstructure:"parked_directories"`
	Services          map[string]ServiceConfig `yaml:"services"           mapstructure:"services"`
}

type Preset struct {
	CustomService     `yaml:",inline"`
	Versions          []PresetVersion       `yaml:"versions,omitempty"`
	DefaultVersion    string                `yaml:"default_version,omitempty"`
	Default           bool                  `yaml:"default,omitempty"`
	UpdateStrategy    string                `yaml:"update_strategy,omitempty"`
	PlatformOverrides []PresetPlatformImage `yaml:"platform_overrides,omitempty"`
	// AllowMajorUpgrade lets the cross-strategy "Upgrade" button cross numeric
	// major boundaries. Default false: major upgrades typically require manual
	// data migration and should be installed as a separate alternate instead.
	AllowMajorUpgrade bool `yaml:"allow_major_upgrade,omitempty"`
	// TrackLatest makes fresh installs resolve the actual newest tag from the
	// registry at first start (within same-major + variant constraints). The
	// preset's `image:` field becomes a fallback for offline / registry-down
	// installs. Existing users with a saved image override are untouched —
	// they progress through the Update / Upgrade buttons instead.
	TrackLatest bool `yaml:"track_latest,omitempty"`
}

type PresetFetchFunc func(name string) error

type PresetMeta struct {
	Name           string          `json:"name"`
	Description    string          `json:"description"`
	Dashboard      string          `json:"dashboard,omitempty"`
	DependsOn      []string        `json:"depends_on,omitempty"`
	Image          string          `json:"image"`
	Versions       []PresetVersion `json:"versions,omitempty"`
	DefaultVersion string          `json:"default_version,omitempty"`
}

type PresetPlatformImage struct {
	OS         string `yaml:"os"`
	ImageMatch string `yaml:"image_match"`
	Image      string `yaml:"image"`
}

type PresetVersion struct {
	Tag   string `yaml:"tag" json:"tag"`
	Label string `yaml:"label,omitempty" json:"label,omitempty"`
	Image string `yaml:"image" json:"image"`
	// HostPort is the host-side port published for this version. Since #704
	// every member of a family shares the family's canonical port (e.g. 3306,
	// 5432); the runtime port-ownership guard shifts a later sibling off it only
	// when another installed service already holds it, so the common single
	// instance lands on the familiar port. Substituted into the family's
	// templated ports, env_vars and connection_url via {{host_port}}.
	HostPort int `yaml:"host_port,omitempty" json:"host_port,omitempty"`
	// Canonical marks this version as the default-preset's bare instance:
	// the service keeps the family name (no -<tag_safe> suffix), uses the
	// preset's top-level ports literally, and skips {{host_port}}/{{tag_safe}}
	// substitution. Exactly one version per multi-version preset may set it.
	Canonical bool `yaml:"canonical,omitempty" json:"canonical,omitempty"`
}

type ProjectConfig struct {
	Domains     []string `yaml:"domains,omitempty"`
	PHPVersion  string   `yaml:"php_version,omitempty"`
	NodeVersion string   `yaml:"node_version,omitempty"`
	// JSRuntime pins the JavaScript runtime for this project's host workers and
	// install/build steps: "bun" forces bun, "node" (or "npm") forces Node/npm
	// and opts out of the no-Node bun fallback. Empty auto-detects bun from a
	// bun.lockb / bunfig.toml / packageManager field. Use "node" for apps bun
	// can't run (e.g. NestJS with native addons). See node.UsesBun.
	JSRuntime        string     `yaml:"js_runtime,omitempty"`
	Framework        string     `yaml:"framework,omitempty"`
	FrameworkVersion string     `yaml:"framework_version,omitempty"`
	FrameworkDef     *Framework `yaml:"framework_def,omitempty"`
	// PublicDir overrides the framework's default document-root subdirectory
	// for this project, e.g. "public_html" for a Laravel skeleton that doesn't
	// use the conventional "public/" folder. Empty means use the framework
	// default. Wins over Framework.PublicDir at nginx-config time.
	PublicDir     string                     `yaml:"public_dir,omitempty"`
	Secured       bool                       `yaml:"secured,omitempty"`
	Services      []ProjectService           `yaml:"services,omitempty"`
	Workers       []string                   `yaml:"workers,omitempty"`
	CustomWorkers map[string]FrameworkWorker `yaml:"custom_workers,omitempty"`
	// ReloadWorkers lists worker names this project runs in auto-reload mode
	// (restart on file changes) for development, for workers that declare a
	// reload_command variant. Per project so one project can develop with
	// reload while another stays in standard mode. Laravel's horizon worker is
	// currently the only worker with a reload variant.
	ReloadWorkers []string `yaml:"reload_workers,omitempty"`
	// Commands extends or overrides the framework's command set. Entries with
	// a Name matching a framework command replace it (set Disabled: true to
	// suppress instead). Entries with a new Name are appended. See
	// ResolveCommands for the merge logic.
	Commands []FrameworkCommand `yaml:"commands,omitempty"`
	// AppURL, when set, is the value lerd writes to the project's APP_URL (or
	// the framework-configured URL key) on every `lerd env` run. Committed to
	// the repo so the choice is shared across machines. Takes precedence over
	// the per-machine override in sites.yaml.
	AppURL    string           `yaml:"app_url,omitempty"`
	DB        ProjectDB        `yaml:"db,omitempty"`
	Container *ContainerConfig `yaml:"container,omitempty"`
	// Proxy, when set, makes this a host-proxy site (see ProxyConfig). Mutually
	// exclusive with Container; Validate rejects setting both.
	Proxy *ProxyConfig `yaml:"proxy,omitempty"`
	// Runtime selects how the site's PHP is served. "fpm" (default) uses the
	// shared lerd-php{version}-fpm container; "frankenphp" spins up a
	// per-site dunglas/frankenphp container that keeps PHP resident.
	Runtime string `yaml:"runtime,omitempty"`
	// RuntimeWorker, when true and Runtime is "frankenphp", starts the
	// FrankenPHP container in worker mode. Framework-specific entrypoints
	// decide whether this flag is honoured.
	RuntimeWorker bool `yaml:"runtime_worker,omitempty"`
	// DBIsolated, when true on a worktree's .lerd.yaml, opts the worktree
	// into its own database (named <parent_db>_<sanitized_branch>) so
	// migrations don't bleed into the parent. Off by default.
	DBIsolated bool `yaml:"db_isolated,omitempty"`
	// EnvOverrides maps env keys to template values that are resolved and
	// written into the worktree's .env when a worktree is created. Supported
	// placeholders: {{domain}} (worktree domain), {{scheme}} (http/https),
	// {{site}} (database-safe name). When APP_URL is present here it takes
	// precedence over the default scheme://domain rewrite.
	EnvOverrides map[string]string `yaml:"env_overrides,omitempty"`
	// RequestTimeout overrides the nginx request timeout for this project, in
	// seconds. Zero inherits the global nginx.request_timeout (default 60s).
	// Raise it for apps with deliberately long-running requests.
	RequestTimeout int `yaml:"request_timeout,omitempty"`
	// Stripe holds optional per-project Stripe webhook listener settings: the
	// route events forward to and which .env key holds the secret. Absent for
	// projects on the Laravel defaults, which are auto-detected.
	Stripe *StripeConfig `yaml:"stripe,omitempty"`
	// MCPInject opts the project out of automatic AI/MCP config refresh. When set
	// to false, `lerd update`/`install` leaves the project's committed MCP config
	// and skill files untouched so they change only when the user asks. Nil/unset
	// keeps the default (refresh in place). An explicit `lerd mcp:inject` still
	// writes, since that is the user asking.
	MCPInject *bool `yaml:"mcp_inject,omitempty"`
}

type ProjectDB struct {
	Service  string `yaml:"service,omitempty"`
	Database string `yaml:"database,omitempty"`
}

type ProjectService struct {
	Name          string
	Preset        string         // empty unless this is a preset reference
	PresetVersion string         // empty for single-version presets
	Custom        *CustomService // nil unless this is an inline definition
}

type ProxyConfig struct {
	Command    string `yaml:"command,omitempty"`      // dev command, e.g. "npm run start:dev"; empty = proxy-only
	Port       int    `yaml:"port"`                   // host port the app binds (required)
	SSL        bool   `yaml:"ssl,omitempty"`          // app serves TLS on its port; proxy via https
	PortEnvKey string `yaml:"port_env_key,omitempty"` // env var the port is injected as (default "PORT")
	HostEnvKey string `yaml:"host_env_key,omitempty"` // env var the bind address is injected as (default "HOST")
	InjectHost *bool  `yaml:"inject_host,omitempty"`  // inject the bind-address env (HOST) so the server listens where the proxy container reaches it; nil/unset = true, set false to opt out
}

type ServiceConfig struct {
	Enabled    bool     `yaml:"enabled"        mapstructure:"enabled"`
	Image      string   `yaml:"image"          mapstructure:"image"`
	Port       int      `yaml:"port"           mapstructure:"port"`
	ExtraPorts []string `yaml:"extra_ports"    mapstructure:"extra_ports"`
	// PublishedPort overrides the host (published) port of this service's
	// primary mapping. 0 = use the preset/version default (e.g. 3306 for MySQL
	// 8.4). Set it to free the default port for a second server — e.g. move
	// lerd-mysql to 3307 so the host system MySQL can keep 127.0.0.1:3306. The
	// container-internal port is unchanged, so bridge clients still use 3306.
	// Unlike Port (auto-seeded from the preset), this stays 0 until the user
	// explicitly overrides, so it is an unambiguous "use default" sentinel.
	PublishedPort int `yaml:"published_port,omitempty" mapstructure:"published_port"`
	// PublishedPorts overrides the host (published) side of this service's
	// secondary mappings, keyed by container-internal port. A multi-port service
	// (mailpit's 8025 UI behind the 1025 SMTP primary, rustfs' 9001 console)
	// exposes ports past the primary; this lets the user remap each one while the
	// primary stays in PublishedPort. Empty = every secondary on its preset
	// default. Keyed on the container port because that is the stable identity
	// when the host side moves.
	PublishedPorts map[int]int `yaml:"published_ports,omitempty" mapstructure:"published_ports"`
	PreviousImage  string      `yaml:"previous_image,omitempty" mapstructure:"previous_image"`
	// LastOp records the most recent mutation kind ("update" or "migrate") so
	// the rollback flow can refuse a swap that would race the new image
	// against the post-migrate (fresh) data dir. Empty means no recent op or a
	// state predating the field — treated as plain update for compatibility.
	LastOp string `yaml:"last_op,omitempty" mapstructure:"last_op"`
	// PreMigrateBackup is the absolute path to the data dir that was preserved
	// when the most recent operation was a migrate. Used by rollback to refuse
	// (or, in future, restore) when undoing the migrate would corrupt data.
	PreMigrateBackup string `yaml:"pre_migrate_backup,omitempty" mapstructure:"pre_migrate_backup"`
	// CanonicalVersion pins the preset version tag this service was first
	// installed on, so flipping the YAML's canonical (e.g. pg 16 → 18 in a
	// future release) never silently major-jumps existing installs.
	CanonicalVersion string `yaml:"canonical_version,omitempty" mapstructure:"canonical_version"`
}

type Site struct {
	Name        string   `yaml:"-"`
	Domains     []string `yaml:"-"`
	Path        string   `yaml:"path"`
	PHPVersion  string   `yaml:"php_version"`
	NodeVersion string   `yaml:"node_version"`
	Secured     bool     `yaml:"secured"`
	// SecuredBeforeDNSOff records that the site was on HTTPS when lerd DNS was
	// last disabled, so re-enabling can restore it even for a site with no
	// .lerd.yaml to carry the intent. Cleared once HTTPS is restored.
	SecuredBeforeDNSOff bool     `yaml:"secured_before_dns_off,omitempty"`
	Ignored             bool     `yaml:"ignored,omitempty"`
	Paused              bool     `yaml:"paused,omitempty"`
	PausedWorkers       []string `yaml:"paused_workers,omitempty"`
	// Pinned excludes the site from idle-suspend: its workers stay running even
	// when the global idle policy is on, so a site you want always-warm never
	// sleeps.
	Pinned    bool   `yaml:"pinned,omitempty"`
	Framework string `yaml:"framework,omitempty"`
	PublicDir string `yaml:"public_dir,omitempty"`
	// AppURL, when set, is the per-machine override for APP_URL in the
	// project's env file. Lower priority than ProjectConfig.AppURL (which is
	// committed to the repo) and higher priority than the default generator
	// (`<scheme>://<primary-domain>`). Use this for personal customizations
	// you don't want to share via .lerd.yaml.
	AppURL string `yaml:"app_url,omitempty"`
	// LANPort, when non-zero, means a host-level reverse proxy is (or should
	// be) listening on 0.0.0.0:LANPort, forwarding to the site with the Host
	// header rewritten. LAN devices can reach the site at <lanIP>:LANPort
	// without any DNS configuration.
	LANPort int `yaml:"lan_port,omitempty"`
	// ContainerPort, when non-zero, means this site uses a per-project custom
	// container instead of the shared PHP-FPM image. The value is the port the
	// app listens on inside the container; nginx reverse-proxies to it.
	ContainerPort int `yaml:"container_port,omitempty"`
	// ContainerSSL, when true, means the app inside the custom container serves
	// TLS on its port; nginx will proxy_pass via HTTPS with ssl_verify off.
	ContainerSSL bool `yaml:"container_ssl,omitempty"`
	// Runtime is "fpm" (default) or "frankenphp". When "frankenphp" the site
	// runs a per-site dunglas/frankenphp:php<version> container and nginx
	// reverse-proxies to it on port 8000.
	Runtime string `yaml:"runtime,omitempty"`
	// RuntimeWorker toggles FrankenPHP worker mode when Runtime=="frankenphp".
	RuntimeWorker bool `yaml:"runtime_worker,omitempty"`
	// HostPort, when non-zero, means this site is a host-proxy site: it has no
	// container, and nginx reverse-proxies the domain to a process running on
	// the host (the dev server) listening on this port.
	HostPort int `yaml:"host_port,omitempty"`
	// HostSSL, when true, means the host process serves TLS on its port; nginx
	// proxies via HTTPS with ssl_verify off.
	HostSSL bool `yaml:"host_ssl,omitempty"`
	// HostCommand is the dev command lerd supervises for a host-proxy site
	// (e.g. "npm run start:dev"). Empty means proxy-only: the user runs the
	// server themselves and lerd only wires the proxy.
	HostCommand string `yaml:"host_command,omitempty"`
	// ApprovedCommands holds exact command strings the user has consented to run
	// on the host for this site (project-origin custom host workers and commands).
	// Keyed by the exact string so a changed command re-prompts.
	ApprovedCommands []string `yaml:"approved_commands,omitempty"`
	// Group is the group key shared by a main site and its secondaries. It is
	// set to the main site's name. Empty when the site is not grouped.
	Group string `yaml:"group,omitempty"`
	// GroupSubdomain is the subdomain label a secondary occupies on the group
	// main's base domain (e.g. "admin" -> admin.<main-domain>). Empty on the
	// main site; non-empty identifies a secondary.
	GroupSubdomain string `yaml:"group_subdomain,omitempty"`
	// GroupSharedDB, when true on a secondary, means the site shares the group
	// main's database instead of its own: DB_DATABASE in its .env is kept in
	// sync with the main's database name.
	GroupSharedDB bool `yaml:"group_shared_db,omitempty"`
	// IdleSuspendedWorkers records the workers the idle engine gracefully
	// stopped while the site was quiet, so activity can resume them. Kept
	// distinct from PausedWorkers (manual `lerd pause`) so an automatic suspend
	// and a manual pause never clobber each other's restore list. Idle-suspend
	// itself is configured globally (config.yaml idle_suspend), not per site.
	IdleSuspendedWorkers []string `yaml:"idle_suspended_workers,omitempty"`

	// WorktreeIdleSuspended records, per git worktree (keyed by the worktree's
	// unit-slug base), the workers the idle engine stopped while that worktree was
	// quiet. Each worktree idles on its own timer, independent of the main site
	// and of the other worktrees, so its suspended set is tracked separately.
	WorktreeIdleSuspended map[string][]string `yaml:"worktree_idle_suspended,omitempty"`
}

type SiteInit struct {
	// Container to exec into. Defaults to lerd-<service name>.
	Container string `yaml:"container,omitempty"`
	// Exec is passed to sh -c inside the container.
	Exec string `yaml:"exec"`
}

type SiteRegistry struct {
	Sites []Site
}

type StripeConfig struct {
	// Path is the webhook route the listener forwards events to, e.g.
	// "/webhooks/stripe". Empty uses DefaultStripeWebhookPath.
	Path string `yaml:"path,omitempty"`
	// SecretEnvKey pins which .env key holds the Stripe secret. Empty probes
	// StripeSecretEnvCandidates in order.
	SecretEnvKey string `yaml:"secret_env_key,omitempty"`
}

type TuningSpec struct {
	// Target is the absolute in-container path the override is mounted
	// to. Required. Lerd bind-mounts the host file
	// (ServiceTuningFile(svc.Name)) read-only at this path; the image
	// must auto-include the file or be pointed at it via Command.
	Target string `yaml:"target"`
	// Template is the body lerd seeds the host file with on first use.
	// Optional; defaults to an empty file. Conventionally a commented
	// hint sheet so users discover the available knobs without lerd
	// having to ship working defaults.
	Template string `yaml:"template,omitempty"`
	// Command, when set, overrides the container Exec so the image
	// actually loads the override (e.g. `redis-server <path>` for an
	// image that loads no config by default). Leave empty for images
	// whose entrypoint already auto-includes the target path.
	Command string `yaml:"command,omitempty"`
}

type WorkerNotFoundError struct {
	Name string
}

type WorkerProxy struct {
	Path        string `yaml:"path"`                   // URL path to proxy (e.g. "/app")
	PortEnvKey  string `yaml:"port_env_key,omitempty"` // env key holding the port (e.g. "REVERB_SERVER_PORT")
	DefaultPort int    `yaml:"default_port,omitempty"` // fallback port if env key is missing (default: 8080)
}

type WorktreeDBEntry struct {
	Site    string `yaml:"site"`
	Branch  string `yaml:"branch"`
	Service string `yaml:"service"`
	DBName  string `yaml:"db_name"`
}

type WorktreeLANEntry struct {
	Site   string `yaml:"site"`
	Branch string `yaml:"branch"`
	Port   int    `yaml:"port"`
}