refactor(parser): consolidate kool.yml discovery into a single source of truth

The "look for kool.yml, then kool.yaml" lookup had six independent
implementations that had drifted apart: core/parser used path.Join
(producing forward-slash paths on Windows) while everyone else used
filepath.Join, the proxy manager stat'd before parsing while the
environment package used a parse error as its discovery signal, and
core/environment/workspace.go hand-unrolled the loop into two
sequential ParseKoolYaml calls.

Add parser.FindKoolYaml and parser.LoadKoolYaml, and route every call
site through them. LoadKoolYaml returns ErrKoolYmlNotFound only when no
config file exists, so a malformed config is now distinguishable from a
missing one at the API level.

initProxy now receives the already-parsed config instead of re-reading
the same file from disk, dropping one of the three kool.yml parses that
happened on every environment init.

Error handling at each call site is intentionally unchanged, keeping
this refactor behavior-neutral.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: fabriciojs

commands/workspace.go

@@ -6,7 +6,6 @@ import (
 	"kool-dev/kool/core/environment"
 	"kool-dev/kool/core/parser"
 	"kool-dev/kool/core/shell"
-	"path/filepath"
 	"sort"
 	"strings"
 )
@@ -35,15 +34,13 @@ func configuredWorkspaceServices(env environment.EnvStorage) []string {
 	if services := workspaceServices(env); len(services) > 0 {
 		return services
 	}
-	for _, name := range []string{"kool.yml", "kool.yaml"} {
-		config, err := parser.ParseKoolYaml(filepath.Join(env.Get("PWD"), name))
-		if err == nil {
-			services := append([]string(nil), config.Workspaces...)
-			sort.Strings(services)
-			return services
-		}
+	config, err := parser.LoadKoolYaml(env.Get("PWD"))
+	if err != nil {
+		return nil
 	}
-	return nil
+	services := append([]string(nil), config.Workspaces...)
+	sort.Strings(services)
+	return services
 }
 
 func sourceProject(env environment.EnvStorage) string {

core/environment/env.go

@@ -68,7 +68,7 @@ func InitEnvironmentVariables(envStorage EnvStorage) {
 	if config != nil && config.Proxy != nil {
 		envStorage.Set("KOOL_PROXY_ENABLED", "true")
 		initSourceProject(envStorage, workDir)
-		initProxy(envStorage, workDir)
+		initProxy(envStorage, config)
 	}
 
 	// Now that we loaded up the files, we will check for
@@ -110,14 +110,15 @@ func envKeySet(entries []string) map[string]bool {
 	return keys
 }
 
+// loadKoolConfig decodes the kool config file for the given directory, or
+// returns nil when there is none - or when it cannot be decoded, since
+// environment setup runs before we have any means of reporting the failure.
 func loadKoolConfig(workDir string) *parser.KoolYaml {
-	for _, name := range []string{"kool.yml", "kool.yaml"} {
-		config, err := parser.ParseKoolYaml(filepath.Join(workDir, name))
-		if err == nil {
-			return config
-		}
+	config, err := parser.LoadKoolYaml(workDir)
+	if err != nil {
+		return nil
 	}
-	return nil
+	return config
 }
 
 func initSourceProject(envStorage EnvStorage, workDir string) {

core/environment/proxy.go

@@ -3,21 +3,13 @@ package environment
 import (
 	"kool-dev/kool/core/parser"
 	"os"
-	"path/filepath"
 	"strings"
 
 	"github.com/compose-spec/compose-go/template"
 )
 
-func initProxy(envStorage EnvStorage, workDir string) {
-	var config *parser.KoolYaml
-	var err error
-	for _, name := range []string{"kool.yml", "kool.yaml"} {
-		if config, err = parser.ParseKoolYaml(filepath.Join(workDir, name)); err == nil {
-			break
-		}
-	}
-	if err != nil || config.Proxy == nil {
+func initProxy(envStorage EnvStorage, config *parser.KoolYaml) {
+	if config == nil || config.Proxy == nil {
 		return
 	}
 

core/environment/proxy_test.go

@@ -13,7 +13,7 @@ func TestInitProxySourceHost(t *testing.T) {
 	}
 	env := NewFakeEnvStorage()
 
-	initProxy(env, workDir)
+	initProxy(env, loadKoolConfig(workDir))
 
 	if got := env.Get("KOOL_PROXY_DOMAIN"); got != "exlink.localhost" {
 		t.Errorf("expected proxy domain, got %q", got)
@@ -32,7 +32,7 @@ func TestInitProxyWorkspaceHost(t *testing.T) {
 	env.Set("KOOL_WORKSPACE", "true")
 	env.Set("KOOL_WORKSPACE_NAME", "vite-smoke")
 
-	initProxy(env, workDir)
+	initProxy(env, loadKoolConfig(workDir))
 
 	if got := env.Get("KOOL_PROXY_HOST"); got != "vite-smoke.workspace.exlink.localhost" {
 		t.Errorf("expected workspace proxy host, got %q", got)
@@ -49,7 +49,7 @@ func TestInitProxyGitWorktreeHost(t *testing.T) {
 	env.Set("KOOL_WORKSPACE_NAME", "vite-smoke")
 	env.Set("KOOL_WORKSPACE_PROVIDER", "worktree")
 
-	initProxy(env, workDir)
+	initProxy(env, loadKoolConfig(workDir))
 
 	if got := env.Get("KOOL_PROXY_HOST"); got != "vite-smoke.workspace.exlink.localhost" {
 		t.Errorf("expected Git worktree proxy host, got %q", got)

core/environment/workspace.go

@@ -3,7 +3,6 @@ package environment
 import (
 	"crypto/sha256"
 	"fmt"
-	"kool-dev/kool/core/parser"
 	"os"
 	"path/filepath"
 	"sort"
@@ -96,11 +95,8 @@ type workspaceComposeConfig struct {
 }
 
 func initWorkspaceCompose(envStorage EnvStorage, workDir string) []string {
-	koolConfig, err := parser.ParseKoolYaml(filepath.Join(workDir, "kool.yml"))
-	if err != nil {
-		koolConfig, err = parser.ParseKoolYaml(filepath.Join(workDir, "kool.yaml"))
-	}
-	if err != nil || len(koolConfig.Workspaces) == 0 {
+	koolConfig := loadKoolConfig(workDir)
+	if koolConfig == nil || len(koolConfig.Workspaces) == 0 {
 		return nil
 	}
 	unique := make(map[string]bool, len(koolConfig.Workspaces))

core/parser/discover.go

@@ -0,0 +1,37 @@
+package parser
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// koolYamlFileNames lists the accepted kool config file names, in lookup order.
+var koolYamlFileNames = []string{"kool.yml", "kool.yaml"}
+
+// FindKoolYaml returns the path of the kool config file within the given
+// directory, preferring kool.yml over kool.yaml. It returns ErrKoolYmlNotFound
+// when neither file exists.
+func FindKoolYaml(dir string) (file string, err error) {
+	for _, name := range koolYamlFileNames {
+		candidate := filepath.Join(dir, name)
+		if _, err = os.Stat(candidate); err == nil {
+			return candidate, nil
+		}
+	}
+
+	return "", ErrKoolYmlNotFound
+}
+
+// LoadKoolYaml finds and decodes the kool config file within the given
+// directory. It returns ErrKoolYmlNotFound when no config file exists; any
+// other error means a file was found but could not be decoded, so callers can
+// tell a malformed config apart from a missing one.
+func LoadKoolYaml(dir string) (parsed *KoolYaml, err error) {
+	var file string
+
+	if file, err = FindKoolYaml(dir); err != nil {
+		return
+	}
+
+	return ParseKoolYaml(file)
+}

core/parser/discover_test.go

@@ -0,0 +1,88 @@
+package parser
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFindKoolYamlPrefersYml(t *testing.T) {
+	dir := t.TempDir()
+	for _, name := range []string{"kool.yml", "kool.yaml"} {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte("scripts: {}\n"), 0644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	file, err := FindKoolYaml(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if expected := filepath.Join(dir, "kool.yml"); file != expected {
+		t.Errorf("expected %q, got %q", expected, file)
+	}
+}
+
+func TestFindKoolYamlFallsBackToYaml(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "kool.yaml"), []byte("scripts: {}\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	file, err := FindKoolYaml(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if expected := filepath.Join(dir, "kool.yaml"); file != expected {
+		t.Errorf("expected %q, got %q", expected, file)
+	}
+}
+
+func TestFindKoolYamlNotFound(t *testing.T) {
+	if _, err := FindKoolYaml(t.TempDir()); !errors.Is(err, ErrKoolYmlNotFound) {
+		t.Errorf("expected ErrKoolYmlNotFound, got %v", err)
+	}
+}
+
+func TestLoadKoolYaml(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "kool.yml"), []byte("workspaces:\n  - app\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	parsed, err := LoadKoolYaml(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if len(parsed.Workspaces) != 1 || parsed.Workspaces[0] != "app" {
+		t.Errorf("expected workspaces [app], got %v", parsed.Workspaces)
+	}
+}
+
+func TestLoadKoolYamlMissing(t *testing.T) {
+	if _, err := LoadKoolYaml(t.TempDir()); !errors.Is(err, ErrKoolYmlNotFound) {
+		t.Errorf("expected ErrKoolYmlNotFound, got %v", err)
+	}
+}
+
+// A malformed config must be distinguishable from a missing one, so callers
+// can choose to report it rather than silently behaving as if unconfigured.
+func TestLoadKoolYamlMalformed(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "kool.yml"), []byte("scripts: [oops\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := LoadKoolYaml(dir)
+	if err == nil {
+		t.Fatal("expected a decoding error, got none")
+	}
+
+	if errors.Is(err, ErrKoolYmlNotFound) {
+		t.Error("malformed config reported as not found")
+	}
+}

core/parser/parser.go

@@ -2,8 +2,6 @@ package parser
 
 import (
 	"errors"
-	"os"
-	"path"
 	"sort"
 	"strings"
 
@@ -37,25 +35,16 @@ func (p *DefaultParser) AddLookupPath(rootPath string) (err error) {
 		p.lookedUp = make(map[string]bool)
 	}
 
-	ymlPath := path.Join(rootPath, "kool.yml")
-	yamlPath := path.Join(rootPath, "kool.yaml")
-
-	if _, err = os.Stat(ymlPath); err == nil {
-		koolFile = ymlPath
-	} else if _, err = os.Stat(yamlPath); err == nil {
-		koolFile = yamlPath
+	if koolFile, err = FindKoolYaml(rootPath); err != nil {
+		return
 	}
 
-	if koolFile == "" {
-		err = ErrKoolYmlNotFound
-	} else {
-		if !p.lookedUp[koolFile] {
-			p.targetFiles = append(p.targetFiles, koolFile)
-		}
-
-		p.lookedUp[koolFile] = true
+	if !p.lookedUp[koolFile] {
+		p.targetFiles = append(p.targetFiles, koolFile)
 	}
 
+	p.lookedUp[koolFile] = true
+
 	return
 }
 

services/proxy/manager.go

@@ -289,20 +289,10 @@ func (m *DefaultManager) Trust() error {
 }
 
 func (m *DefaultManager) loadConfig() (*config, error) {
-	workDir := m.env.Get("PWD")
-	var file string
-	for _, name := range []string{"kool.yml", "kool.yaml"} {
-		candidate := filepath.Join(workDir, name)
-		if _, err := os.Stat(candidate); err == nil {
-			file = candidate
-			break
-		}
-	}
-	if file == "" {
+	parsed, err := parser.LoadKoolYaml(m.env.Get("PWD"))
+	if errors.Is(err, parser.ErrKoolYmlNotFound) {
 		return nil, nil
 	}
-
-	parsed, err := parser.ParseKoolYaml(file)
 	if err != nil || parsed.Proxy == nil {
 		return nil, err
 	}