feat(cmd): add debug mode flag (#10)

Author: gorillamoe

README.md

@@ -129,10 +129,62 @@ iwr https://kuba.mwco.app/install.ps1 -useb | iex
 kuba run -- <your-command>
 ```
 
-This will fetch all secrets definded in
+This will fetch all secrets defined in
 `kuba.yaml` and pass them as
 environment variables to any arbitrary command.
 
+### Debug Mode
+
+For troubleshooting configuration issues and seeing detailed execution steps, you can enable debug mode:
+
+```sh
+kuba --debug run -- <your-command>
+# or use the short form
+kuba -d run -- <your-command>
+```
+
+Debug mode provides verbose logging that shows:
+- Configuration file discovery and loading
+- Environment selection and validation
+- Secret provider initialization
+- Secret retrieval attempts and results
+- Environment variable mapping
+- Command execution details
+
+This is particularly useful for:
+- Diagnosing cloud provider authentication issues
+- Troubleshooting configuration file syntax errors
+- Understanding why certain secrets aren't being loaded
+- Verifying environment variable interpolation
+- Debugging provider-specific errors
+
+### Available Commands and Flags
+
+Kuba provides several commands to help you manage your configuration:
+
+```sh
+# Initialize a new configuration file
+kuba init
+
+# Run a command with secrets
+kuba run -- <command>
+
+# Show version information
+kuba version
+
+# Get help
+kuba --help
+```
+
+**Global Flags:**
+- `--debug, -d`: Enable debug mode for verbose logging
+- `--version`: Show version information
+- `--help, -h`: Show help information
+
+**Run Command Flags:**
+- `--env, -e`: Specify environment (default: "default")
+- `--config, -c`: Path to configuration file
+
 Let's say you want to pass
 some secrets from GCP to your node application.
 

cmd/kuba/init.go

@@ -2,6 +2,7 @@ package kuba
 
 import (
 	"github.com/mistweaverco/kuba/internal/lib/fileutils"
+	"github.com/mistweaverco/kuba/internal/lib/log"
 	"github.com/spf13/cobra"
 )
 
@@ -10,6 +11,14 @@ var initCmd = &cobra.Command{
 	Short: "Create a default configuration file",
 	Long:  "This command initializes a default configuration file for kuba, if it does not already exist.",
 	Run: func(cmd *cobra.Command, files []string) {
-		fileutils.GenerateDefaultKubaConfig()
+		logger := log.NewLogger()
+		logger.Debug("Initializing default kuba configuration")
+
+		created := fileutils.GenerateDefaultKubaConfig()
+		if created {
+			logger.Debug("Default configuration file created successfully")
+		} else {
+			logger.Debug("Configuration file already exists, no action taken")
+		}
 	},
 }

cmd/kuba/kuba.go

@@ -5,6 +5,7 @@ import (
 	"os"
 
 	"github.com/mistweaverco/kuba/internal/config"
+	"github.com/mistweaverco/kuba/internal/lib/log"
 	"github.com/mistweaverco/kuba/internal/lib/version"
 	"github.com/spf13/cobra"
 )
@@ -17,6 +18,10 @@ var rootCmd = &cobra.Command{
 	Use:   "kuba",
 	Short: "Kuba CLI",
 	Long:  "Kuba is a CLI tool for accessing secrets and environment variables in a secure and efficient way.",
+	PersistentPreRun: func(cmd *cobra.Command, args []string) {
+		// Initialize logging with debug mode
+		log.SetDebugMode(cfg.Flags.Debug)
+	},
 	Run: func(cmd *cobra.Command, files []string) {
 		if cfg.Flags.Version {
 			fmt.Println(version.VERSION)
@@ -39,6 +44,7 @@ func init() {
 	rootCmd.AddCommand(initCmd)
 	// runCmd is added in run.go init() function
 	rootCmd.PersistentFlags().BoolVar(&cfg.Flags.Version, "version", false, "Kuba version")
+	rootCmd.PersistentFlags().BoolVarP(&cfg.Flags.Debug, "debug", "d", false, "Enable debug mode for verbose logging")
 }
 
 // osExit is a variable to allow overriding in tests

cmd/kuba/run.go

@@ -7,6 +7,7 @@ import (
 	"os/exec"
 
 	"github.com/mistweaverco/kuba/internal/config"
+	"github.com/mistweaverco/kuba/internal/lib/log"
 	"github.com/mistweaverco/kuba/internal/lib/secrets"
 	"github.com/spf13/cobra"
 )
@@ -44,40 +45,54 @@ func init() {
 }
 
 func runCommand(args []string) error {
+	logger := log.NewLogger()
+
 	// Find configuration file if not specified
 	if configFile == "" {
 		var err error
+		logger.Debug("No config file specified, searching for kuba.yaml")
 		configFile, err = config.FindConfigFile()
 		if err != nil {
 			return fmt.Errorf("failed to find configuration file: %w", err)
 		}
+		logger.Debug("Found configuration file", "path", configFile)
+	} else {
+		logger.Debug("Using specified configuration file", "path", configFile)
 	}
 
 	// Load configuration
+	logger.Debug("Loading configuration from file")
 	kubaConfig, err := config.LoadKubaConfig(configFile)
 	if err != nil {
 		return fmt.Errorf("failed to load configuration: %w", err)
 	}
+	logger.Debug("Configuration loaded successfully")
 
 	// Get environment configuration
+	logger.Debug("Getting environment configuration", "environment", environment)
 	env, err := kubaConfig.GetEnvironment(environment)
 	if err != nil {
 		return fmt.Errorf("failed to get environment '%s': %w", environment, err)
 	}
+	logger.Debug("Environment configuration retrieved", "environment", environment, "provider", env.Provider, "mappings_count", len(env.Mappings))
 
 	// Create secrets manager factory
+	logger.Debug("Creating secrets manager factory")
 	factory := secrets.NewSecretManagerFactory()
 
 	// Get secrets for the environment
 	ctx := context.Background()
+	logger.Debug("Fetching secrets from cloud providers")
 	secrets, err := factory.GetSecretsForEnvironment(ctx, env)
 	if err != nil {
 		return fmt.Errorf("failed to get secrets: %w", err)
 	}
+	logger.Debug("Secrets retrieved successfully", "count", len(secrets))
 
 	// Prepare command
 	command := args[0]
 	commandArgs := args[1:]
+	logger.Debug("Preparing command execution", "command", command, "args", commandArgs)
 
 	// Create command
 	cmd := exec.Command(command, commandArgs...)
@@ -90,14 +105,18 @@ func runCommand(args []string) error {
 	for key, value := range secrets {
 		cmd.Env = append(cmd.Env, fmt.Sprintf("%s=%s", key, value))
 	}
+	logger.Debug("Environment variables set", "secrets_count", len(secrets), "total_env_vars", len(cmd.Env))
 
 	// Execute command
+	logger.Debug("Executing command")
 	if err := cmd.Run(); err != nil {
 		if exitErr, ok := err.(*exec.ExitError); ok {
+			logger.Debug("Command exited with non-zero status", "exit_code", exitErr.ExitCode())
 			os.Exit(exitErr.ExitCode())
 		}
 		return fmt.Errorf("command failed: %w", err)
 	}
 
+	logger.Debug("Command executed successfully")
 	return nil
 }

internal/config/config.go

@@ -2,6 +2,7 @@ package config
 
 type ConfigFlags struct {
 	Version bool
+	Debug   bool
 }
 
 type Config struct {

internal/config/kuba_config.go

@@ -7,6 +7,7 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/mistweaverco/kuba/internal/lib/log"
 	"gopkg.in/yaml.v3"
 )
 
@@ -151,54 +152,90 @@ func processValueInterpolations(config *KubaConfig) error {
 
 // LoadKubaConfig loads the kuba.yaml configuration file
 func LoadKubaConfig(configPath string) (*KubaConfig, error) {
+	logger := log.NewLogger()
+
 	if configPath == "" {
 		configPath = "kuba.yaml"
 	}
 
+	logger.Debug("Loading configuration file", "path", configPath)
+
 	// Check if file exists
 	if _, err := os.Stat(configPath); os.IsNotExist(err) {
+		logger.Debug("Configuration file not found", "path", configPath)
 		return nil, fmt.Errorf("configuration file not found: %s", configPath)
 	}
 
 	// Read file
+	logger.Debug("Reading configuration file")
 	data, err := os.ReadFile(configPath)
 	if err != nil {
+		logger.Debug("Failed to read configuration file", "path", configPath, "error", err)
 		return nil, fmt.Errorf("failed to read configuration file: %w", err)
 	}
 
+	logger.Debug("Configuration file read successfully", "size_bytes", len(data))
+
 	// Parse YAML
+	logger.Debug("Parsing YAML configuration")
 	var config KubaConfig
 	if err := yaml.Unmarshal(data, &config); err != nil {
+		logger.Debug("Failed to parse YAML configuration", "error", err)
 		return nil, fmt.Errorf("failed to parse configuration file: %w", err)
 	}
 
+	logger.Debug("YAML parsed successfully", "environments_count", len(config.Environments))
+
 	// Process environment variable interpolations
+	logger.Debug("Processing environment variable interpolations")
 	if err := processValueInterpolations(&config); err != nil {
+		logger.Debug("Failed to process environment variable interpolations", "error", err)
 		return nil, fmt.Errorf("failed to process environment variable interpolations: %w", err)
 	}
 
+	logger.Debug("Environment variable interpolations processed successfully")
+
 	// Validate configuration
+	logger.Debug("Validating configuration")
 	if err := validateConfig(&config); err != nil {
+		logger.Debug("Configuration validation failed", "error", err)
 		return nil, fmt.Errorf("invalid configuration: %w", err)
 	}
 
+	logger.Debug("Configuration validation passed")
 	return &config, nil
 }
 
 // GetEnvironment returns the configuration for a specific environment
 func (c *KubaConfig) GetEnvironment(envName string) (*Environment, error) {
+	logger := log.NewLogger()
+
 	if envName == "" {
 		envName = "default"
+		logger.Debug("No environment specified, using default")
 	}
 
+	logger.Debug("Getting environment configuration", "requested_env", envName, "available_environments", len(c.Environments))
+
 	env, exists := c.Environments[envName]
 	if !exists {
+		logger.Debug("Environment not found in configuration", "requested_env", envName, "available_environments", getEnvironmentNames(c.Environments))
 		return nil, fmt.Errorf("environment '%s' not found in configuration", envName)
 	}
 
+	logger.Debug("Environment configuration retrieved", "environment", envName, "provider", env.Provider, "project", env.Project, "mappings_count", len(env.Mappings))
 	return &env, nil
 }
 
+// getEnvironmentNames returns a slice of available environment names
+func getEnvironmentNames(environments map[string]Environment) []string {
+	names := make([]string, 0, len(environments))
+	for name := range environments {
+		names = append(names, name)
+	}
+	return names
+}
+
 // validateConfig validates the configuration structure
 func validateConfig(config *KubaConfig) error {
 	if len(config.Environments) == 0 {

internal/lib/log/log.go

@@ -7,16 +7,29 @@ import (
 	"github.com/mistweaverco/kuba/internal/lib/version"
 )
 
-var logLevel slog.Level = slog.LevelDebug
+var logLevel slog.Level = slog.LevelInfo
 
 func SetLogLevel(level slog.Level) {
+	logLevel = level
 	slog.SetLogLoggerLevel(level)
 }
 
+func SetDebugMode(debug bool) {
+	if debug {
+		SetLogLevel(slog.LevelDebug)
+	} else {
+		SetLogLevel(slog.LevelInfo)
+	}
+}
+
+func IsDebugMode() bool {
+	return logLevel <= slog.LevelDebug
+}
+
 func NewLogger() *slog.Logger {
 	// When running in a production environment,
-	// set the log level to Error
-	if version.VERSION != "" {
+	// set the log level to Error unless debug mode is enabled
+	if version.VERSION != "" && logLevel > slog.LevelDebug {
 		logLevel = slog.LevelError
 	}
 	return slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: logLevel}))