deps

type Dependency struct {
	// Bin is the executable name used for PATH lookup and as the installed binary name.
	Bin string
	// GoInstall holds the arguments passed to `go install` (build flags + package path).
	// Example: []string{"-tags", "extended", "github.com/gohugoio/hugo@latest"}
	GoInstall []string
	// Env holds optional environment variables set when running go install.
	// Example: map[string]string{"CGO_ENABLED": "1"}
	Env map[string]string
	// GithubRelease, when set, installs the binary by downloading a GitHub Releases asset.
	// Mutually exclusive with GoInstall.
	GithubRelease *GithubRelease
}

type GithubRelease struct {
	// Repo is the GitHub repository in "owner/repo" form.
	// Example: "sass/dart-sass"
	Repo string

	// Version is the release tag to install, e.g. "1.103.1".
	// Leave empty to resolve the latest published release automatically via the GitHub API.
	// Pin this in consumer code when reproducibility matters:
	//   deps.DartSass.GithubRelease.Version = "1.103.1"
	Version string

	// AssetPattern is a Go text/template that is rendered with [ReleaseAssetData] to produce
	// the release asset filename to download.
	// Example: "dart-sass-{{.Version}}-{{.OS}}-{{.Arch}}.tar.gz"
	AssetPattern string

	// BinPath is the path to the executable inside the archive, always relative to the
	// archive root — regardless of whether BundleDir is set.
	//
	// Single-binary install (BundleDir empty): the file at BinPath is copied to
	// InstallDir/Dependency.Bin.
	//
	// Bundle install (BundleDir set): BinPath locates the entry-point within the installed
	// bundle; a symlink InstallDir/Dependency.Bin → InstallDir/BinPath is created so the
	// binary appears on PATH while the bundle's internal layout stays intact.
	//
	// Example: "dart-sass/sass"
	BinPath string

	// BundleDir is the top-level directory inside the archive that must be installed as a
	// whole unit. Set this when the entry-point binary is a wrapper script (or otherwise
	// not a self-contained executable) that depends on sibling files at a fixed relative
	// path within the same directory.
	//
	// When set, the entire subtree is copied to InstallDir/BundleDir and a symlink is
	// created at InstallDir/Dependency.Bin pointing to InstallDir/BinPath.
	//
	// Leave empty for self-contained binaries that can be freely relocated.
	//
	// Example: "dart-sass"
	BundleDir string

	// InstallDir is the directory into which the binary (or bundle) is placed.
	// Defaults to $GOPATH/bin, falling back to $HOME/.local/bin.
	// Override when a specific location is required.
	InstallDir string
}

type Installable interface {
	Install() error
}

type ReleaseAssetData struct {
	// Version is the resolved release tag, e.g. "1.103.1".
	Version string
	// OS is the GOOS-derived platform token used in release asset names.
	// Mapping: darwin → "macos", windows → "windows", anything else → "linux".
	OS string
	// Arch is the GOARCH-derived architecture token used in release asset names.
	// Mapping: arm64 → "arm64", arm → "arm", anything else → "x64".
	Arch string
}