feat(config): implement loading of .forge.yaml for app-level configuration

- Added functionality to load .forge.yaml file to configure app settings such as port and build output.
- Enhanced the newApp function to read configuration before server initialization, ensuring proper port setup.
- Updated DevPlugin to utilize app-level configuration for port settings, prioritizing explicit flags and environment variables.

This update improves the flexibility and configurability of the application.

Author: juicycleff

app_impl.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"path/filepath"
 	"runtime"
 	"sync"
 	"syscall"
@@ -19,6 +20,7 @@ import (
 	metricsinternal "github.com/xraph/forge/internal/metrics"
 	"github.com/xraph/forge/internal/shared"
 	"github.com/xraph/vessel"
+	"gopkg.in/yaml.v3"
 )
 
 // app implements the App interface.
@@ -195,6 +197,10 @@ func newApp(config AppConfig) *app {
 		}
 	}
 
+	// Load .forge.yaml for app-level configuration (port, build settings, etc.)
+	// This runs BEFORE server initialization to ensure port is configured
+	config = loadForgeYAMLConfig(config, logger)
+
 	// Create health manager with full config support
 	var healthManager HealthManager
 
@@ -1303,3 +1309,103 @@ func (a *app) handleHealthReady(ctx Context) error {
 		"message": "one or more services unhealthy",
 	})
 }
+
+// forgeYAMLConfig represents the app-level .forge.yaml configuration
+// This is loaded at runtime to provide app-specific settings like port.
+type forgeYAMLConfig struct {
+	App struct {
+		Name    string `yaml:"name"`
+		Type    string `yaml:"type"`
+		Version string `yaml:"version"`
+	} `yaml:"app"`
+	Dev struct {
+		Port int    `yaml:"port"`
+		Host string `yaml:"host"`
+	} `yaml:"dev"`
+	Build struct {
+		Output string `yaml:"output"`
+	} `yaml:"build"`
+}
+
+// loadForgeYAMLConfig searches for and loads .forge.yaml to configure runtime settings.
+// This ensures the app can read its configuration when run directly (not through forge dev).
+func loadForgeYAMLConfig(config AppConfig, logger Logger) AppConfig {
+	// Search for .forge.yaml starting from current directory
+	dir, err := os.Getwd()
+	if err != nil {
+		return config
+	}
+
+	var forgeConfigPath string
+	maxDepth := 5
+
+	// Search up the directory tree
+	for i := 0; i < maxDepth; i++ {
+		yamlPath := filepath.Join(dir, ".forge.yaml")
+		ymlPath := filepath.Join(dir, ".forge.yml")
+
+		if _, err := os.Stat(yamlPath); err == nil {
+			forgeConfigPath = yamlPath
+			break
+		}
+
+		if _, err := os.Stat(ymlPath); err == nil {
+			forgeConfigPath = ymlPath
+			break
+		}
+
+		// Move up one directory
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			// Reached root
+			break
+		}
+		dir = parent
+	}
+
+	// If no .forge.yaml found, return original config
+	if forgeConfigPath == "" {
+		return config
+	}
+
+	// Read and parse .forge.yaml
+	data, err := os.ReadFile(forgeConfigPath)
+	if err != nil {
+		if logger != nil {
+			logger.Debug("failed to read .forge.yaml", F("path", forgeConfigPath), F("error", err.Error()))
+		}
+		return config
+	}
+
+	var forgeConfig forgeYAMLConfig
+	if err := yaml.Unmarshal(data, &forgeConfig); err != nil {
+		if logger != nil {
+			logger.Debug("failed to parse .forge.yaml", F("path", forgeConfigPath), F("error", err.Error()))
+		}
+		return config
+	}
+
+	// Apply configuration from .forge.yaml
+	// Priority: Explicit AppConfig > .forge.yaml > Defaults
+
+	// Set HTTPAddress from dev.port if:
+	// 1. HTTPAddress is still the default ":8080"
+	// 2. dev.port is set in .forge.yaml
+	// 3. PORT environment variable is not set (env vars take precedence)
+	if config.HTTPAddress == ":8080" && forgeConfig.Dev.Port > 0 && os.Getenv("PORT") == "" {
+		config.HTTPAddress = fmt.Sprintf(":%d", forgeConfig.Dev.Port)
+		if logger != nil {
+			logger.Info("loaded port from .forge.yaml", F("port", forgeConfig.Dev.Port), F("path", forgeConfigPath))
+		}
+	}
+
+	// If PORT env var is set, use it (highest priority for port)
+	if portEnv := os.Getenv("PORT"); portEnv != "" {
+		config.HTTPAddress = ":" + portEnv
+		if logger != nil {
+			logger.Info("using port from environment variable", F("port", portEnv))
+		}
+	}
+
+	return config
+}

cmd/forge/plugins/dev.go

@@ -113,9 +113,15 @@ func (p *DevPlugin) runDev(ctx cli.CommandContext) error {
 		return err
 	}
 
-	// Set port if specified
+	// Set port: use --port flag if provided, otherwise use app config, otherwise let app decide
 	if port > 0 {
+		// Explicit flag takes precedence
 		os.Setenv("PORT", strconv.Itoa(port))
+	} else if app.AppConfig != nil && app.AppConfig.Dev.GetPort() > 0 {
+		// Use port from app's .forge.yaml
+		appPort := app.AppConfig.Dev.GetPort()
+		os.Setenv("PORT", strconv.Itoa(appPort))
+		ctx.Info(fmt.Sprintf("Using port %d from app configuration", appPort))
 	}
 
 	if watch {
@@ -210,17 +216,20 @@ func (p *DevPlugin) buildDev(ctx cli.CommandContext) error {
 
 // AppInfo represents a discoverable app.
 type AppInfo struct {
-	Name string
-	Path string
-	Type string
+	Name      string
+	Path      string
+	Type      string
+	AppConfig *config.AppConfig // App-level .forge.yaml configuration
 }
 
 func (p *DevPlugin) discoverApps() ([]AppInfo, error) {
 	var apps []AppInfo
 
 	if p.config.IsSingleModule() {
 		// For single-module, scan cmd directory
-		cmdDir := filepath.Join(p.config.RootDir, p.config.Project.GetStructure().Cmd)
+		structure := p.config.Project.GetStructure()
+		cmdDir := filepath.Join(p.config.RootDir, structure.Cmd)
+		appsDir := filepath.Join(p.config.RootDir, structure.Apps)
 
 		entries, err := os.ReadDir(cmdDir)
 		if err != nil {
@@ -235,11 +244,19 @@ func (p *DevPlugin) discoverApps() ([]AppInfo, error) {
 			if entry.IsDir() {
 				mainPath := filepath.Join(cmdDir, entry.Name(), "main.go")
 				if _, err := os.Stat(mainPath); err == nil {
-					apps = append(apps, AppInfo{
+					appInfo := AppInfo{
 						Name: entry.Name(),
 						Path: filepath.Join(cmdDir, entry.Name()),
 						Type: "app",
-					})
+					}
+
+					// Try to load app-level .forge.yaml from apps/{appname}/
+					appConfigDir := filepath.Join(appsDir, entry.Name())
+					if appConfig, err := config.LoadAppConfig(appConfigDir); err == nil {
+						appInfo.AppConfig = appConfig
+					}
+
+					apps = append(apps, appInfo)
 				}
 			}
 		}
@@ -263,11 +280,18 @@ func (p *DevPlugin) discoverApps() ([]AppInfo, error) {
 				cmdDir := filepath.Join(appDir, "cmd")
 
 				if _, err := os.Stat(cmdDir); err == nil {
-					apps = append(apps, AppInfo{
+					appInfo := AppInfo{
 						Name: entry.Name(),
 						Path: cmdDir,
 						Type: "app",
-					})
+					}
+
+					// Try to load app-level .forge.yaml from apps/{appname}/
+					if appConfig, err := config.LoadAppConfig(appDir); err == nil {
+						appInfo.AppConfig = appConfig
+					}
+
+					apps = append(apps, appInfo)
 				}
 			}
 		}