engine

type ActionType int8

type AppConfig struct {
	// DirSrcRoot is the absolute path to the source root directory to watch.
	DirSrcRoot string

	// Exclude is a list of glob patterns for files that must not trigger an
	// app rebuild/restart. Matched files are still watched, so custom
	// watchers still fire for them; use WatcherIgnore to drop paths entirely.
	Exclude []string

	// DirCmd is the path to the Go command to build (e.g., "./cmd/server/").
	DirCmd string

	// DirWork is the working directory for building and running the app server.
	DirWork string

	// Flags are flags passed to the app server binary on startup.
	Flags []string

	// Host is the app server's URL for health checks and reverse proxying.
	Host *url.URL
}

type CompilerConfig struct {
	// Flags are pre-assembled compiler flags
	// (e.g. ["-gcflags", "all=-N -l", "-race"]).
	Flags []string

	// Env are environment variables for the compiler (e.g. ["GOARCH=amd64"]).
	Env []string
}

type Config struct {
	// App defines the application being developed.
	App AppConfig

	// Compiler configures the Go compiler. Nil means default compiler settings.
	Compiler *CompilerConfig

	// Debounce is the duration to wait before triggering a rebuild
	// after a file change. Zero means 50ms default.
	Debounce time.Duration

	// ProxyTimeout for proxied requests to the app server.
	// Zero means 2s default.
	ProxyTimeout time.Duration

	// Lint enables golangci-lint before building.
	Lint bool

	// Format enables automatic templ formatting on .templ file changes.
	Format bool

	// TemplierHost is the host:port for the templier proxy server.
	// Example: "127.0.0.1:9999".
	TemplierHost string

	// TLS enables TLS for the templier proxy server. Nil means plain HTTP.
	TLS *TLSConfig

	// CustomWatchers defines additional file watchers with custom commands.
	CustomWatchers []CustomWatcherConfig

	// WatcherIgnore lists glob patterns (relative to App.DirSrcRoot) fully
	// excluded from the fs watcher — no events at all, unlike AppConfig.Exclude
	// which only gates rebuilds.
	WatcherIgnore []string

	// Log configures logging behavior.
	Log LogConfig

	// ReconnectMessage is the message shown in the browser overlay
	// when the WebSocket connection to the dev server is lost.
	// Empty means "reconnecting...".
	ReconnectMessage string
}

type CustomWatcherConfig struct {
	// Name is the display name for the custom watcher.
	Name string

	// Cmd is the shell command to run when an included file changes.
	// Executed via "sh -c". Optional if Requires is set.
	Cmd string

	// Include specifies glob patterns for what files to watch.
	Include []string

	// Exclude specifies glob patterns for what files to ignore
	// that would otherwise match Include.
	Exclude []string

	// Debounce defines how long to wait for more file changes
	// before executing Cmd. Zero means 50ms default.
	Debounce time.Duration

	// FailOnErr shows the command's error output in the browser
	// (like a build error) when the command exits with code 1.
	FailOnErr bool

	// Requires defines what action is required when an included file changes.
	Requires ActionType
}

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

type LogClearOn int8

type LogConfig struct {
	// Level controls the verbosity of logging.
	Level LogLevel

	// ClearOn defines when to clear log output.
	ClearOn LogClearOn

	// PrintJSDebugLogs enables debug logs in the injected browser JavaScript.
	PrintJSDebugLogs bool
}

type LogLevel int8

type Options struct {
	// Logger sets the logger for the engine.
	// If nil, [slog.Default] is used.
	Logger *slog.Logger

	// ClearLogs is called when the engine wants to clear the log output
	// (e.g. on server restart or file change, depending on [LogConfig.ClearOn]).
	// If nil, log clearing is a no-op.
	ClearLogs func()

	// Stdout is the writer for the app server's stdout.
	// If nil, [os.Stdout] is used.
	Stdout io.Writer

	// Stderr is the writer for the app server's stderr.
	// If nil, [os.Stderr] is used.
	Stderr io.Writer

	// Version is the version string (e.g. "1.2.3").
	// When using the CLI, this is set via goreleaser ldflags.
	// When empty, [Version] is used as fallback.
	Version string

	// Commit is the VCS commit hash. Set via goreleaser ldflags in the CLI.
	Commit string

	// Date is the VCS commit date. Set via goreleaser ldflags in the CLI.
	Date string
}

type TLSConfig struct {
	Cert string
	Key  string
}