dev

Documentation

Overview

Package dev implements the `burrow dev` integrated development server: a file watcher that restarts the application on source changes and (optionally) runs the Tailwind v4 standalone CLI in `--watch` mode alongside it.

The package is dev-tooling only; it is never linked into burrow-built binaries unless they depend on `cmd/burrow` for `go tool` purposes.

Index

• func EnsureEnv(cfg Config, log io.Writer) error
• func ProjectRoot(ctx context.Context) (string, error)
• func Run(ctx context.Context, cfg Config) error
• type Config
  • func Discover(projectRoot string) (Config, error)

Functions

func EnsureEnv

func EnsureEnv(cfg Config, log io.Writer) error

EnsureEnv creates the configured env file with default dev keys when it does not yet exist; existing files are left untouched. It is the entry point for `burrow dev --init-env`, called by the scaffold's `mise run setup` task so freshly-cloned projects have a `.env` ready before any test or app invocation. Returns an error when cfg.EnvFile is empty.

func ProjectRoot

func ProjectRoot(ctx context.Context) (string, error)

ProjectRoot resolves the directory containing the current project's go.mod via `go env GOMOD`. Returns an error when the working directory is outside any Go module.

func Run

func Run(ctx context.Context, cfg Config) error

Run blocks until ctx is cancelled, supervising the application child process. On each debounced file change it:

1. SIGTERMs the running app (waits up to KillTimeout, then SIGKILL).
2. Runs `burrow tailwind` once to regenerate the CSS bundle (when cfg.CSSIn and cfg.CSSOut are both set). This is intentionally sequential, not a parallel `--watch` co-process: the Go binary embeds `app.min.css` at compile time via `//go:embed`, so a running parallel rebuild would not be picked up until the next restart anyway.
3. Spawns `go run cfg.AppPath` again (Go's build cache keeps warm rebuilds fast).

If the app exits on its own (build error, panic, port-in-use) the supervisor state is reset and a notice is logged — the next file change triggers a fresh attempt.

On ctx cancellation Run gracefully stops the child (SIGTERM → cfg.KillTimeout → SIGKILL) before returning.

Types

type Config

type Config struct {
	// ProjectRoot is the project's module root (the directory containing go.mod).
	ProjectRoot string

	// AppPath is the Go package path passed to `go run`, e.g. "./cmd/myapp".
	AppPath string

	// CSSIn / CSSOut are the Tailwind input/output paths (relative to
	// ProjectRoot). Both empty means no Tailwind co-watcher.
	CSSIn  string
	CSSOut string

	// WatchExts is the set of file extensions (lowercase, leading dot)
	// that trigger a restart, e.g. {".go", ".html", ".css", ".toml",
	// ".yml", ".yaml"}. TOML and YAML are included so changes to
	// translation bundles and config files are picked up without an
	// explicit `--watch-exts` override.
	WatchExts []string

	// ExcludeDirs is the set of directory names (no path separators)
	// or repo-relative paths to skip during the project walk. Names
	// match anywhere in the tree (".git" matches every .git dir);
	// path entries (containing a separator) match only at that exact
	// location relative to ProjectRoot.
	ExcludeDirs []string

	// Debounce is the quiet window after the first file event before a
	// restart is triggered. Coalesces editor save-rename storms.
	Debounce time.Duration

	// KillTimeout is how long SIGTERM is given before SIGKILL.
	KillTimeout time.Duration

	// EnvFile, when non-empty, is parsed via godotenv and the
	// resulting KEY=VALUE pairs are injected into the child process
	// environment. Missing file is not an error — the dev server
	// auto-creates it with conventional defaults (see [EnsureEnvFile]).
	EnvFile string

	// Stdout / Stderr are where the dev server writes its own log
	// lines (children always inherit os.Stdout / os.Stderr).
	Stdout io.Writer
	Stderr io.Writer
}

Config drives a single run of the dev server. Most fields can be populated by Discover; flags on the CLI override individual values.

func Discover

func Discover(projectRoot string) (Config, error)

Discover populates a Config from the conventional burrow project layout under projectRoot:

• AppPath = "./cmd/<name>" when exactly one cmd/<name>/main.go exists.
• CSSIn / CSSOut are inferred when tailwind.css exists at the root and exactly one internal/<app>/static/ directory exists; in any other case Tailwind discovery silently no-ops (both stay empty) and the user must supply --css-in / --css-out explicitly.
• All other fields receive their default values. ExcludeDirs is derived from CSSOut by [applyDefaults] *after* CLI overrides are in place, so a `--css-out` flag override correctly excludes the chosen directory.