chore: release v0.5.0

- Add debug logging for performance profiling
- Add performance warnings for config-based secrets
- Add comprehensive configuration documentation
- Update CHANGELOG and website docs

Author: speier

CHANGELOG.md

@@ -7,17 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-10-10
+
 ### Added
+- **Debug logging** - Added detailed debug logs for performance profiling of stack parsing, esbuild bundling, and secret resolution. Enable with `log_level: debug` in config or `COMET_LOG_LEVEL=debug` environment variable.
+- **Configuration documentation** - New comprehensive configuration guide in website docs covering all options, environment variables, and performance considerations.
 - **`comet types` command** - Generate TypeScript definitions for IDE support on-demand
 
 ### Fixed
 - Skip parsing TypeScript definition files (`.d.ts`) to prevent parse errors
 
 ### Changed
+- **Performance warning for config-based secrets** - Added warning when using `op://` or `sops://` references in `comet.yaml` env section, as these are resolved on every command and can add 3-5 seconds. Documentation now recommends setting frequently-used secrets in shell environment instead.
 - TypeScript definitions are now opt-in via `comet types` instead of auto-generated
 
 ### Added
-- **Config-based environment variables** - Pre-load environment variables from `comet.yaml` before any command runs. Perfect for setting `SOPS_AGE_KEY` and other secrets needed during stack parsing. Supports secret resolution via `op://` and `sops://` prefixes. Shell environment variables take precedence.
+- **Config-based environment variables** - Pre-load environment variables from `comet.yaml` before any command runs. Perfect for setting `SOPS_AGE_KEY` and other secrets needed during stack parsing. Supports secret resolution via `op://` and `sops://` prefixes. Shell environment variables take precedence. ⚠️ **Note:** Secret resolution can be slow (3-5s per secret with 1Password CLI); consider setting in shell for frequently-used values.
 - **`comet init` command** - Initialize backends and providers without running plan/apply operations. Useful for read-only operations like `comet output` or troubleshooting provider/backend initialization issues.
 - **DSL Improvements** - Two core enhancements to reduce boilerplate by ~30%:
   - Bulk environment variables: `envs({})` accepts objects to set multiple vars at once
@@ -58,5 +63,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for Terraform and OpenTofu
 - CLI commands: plan, apply, destroy, list, output, clean
 
-[Unreleased]: https://github.com/moonwalker/comet/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/moonwalker/comet/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/moonwalker/comet/releases/tag/v0.5.0
 [0.1.0]: https://github.com/moonwalker/comet/releases/tag/v0.1.0

Makefile

@@ -1,27 +1,27 @@
-VERSION=v0.4.7
+VERSION=v0.5.0
 
-# Bump patch version, commit, tag, and release
-bump:
-	@echo "Current version: ${VERSION}"
-	@NEW_VERSION=v0.4.7
-	echo "Bumping to $$NEW_VERSION..." && \
-	sed -i.bak "s/VERSION=v0.4.7
-	rm -f Makefile.bak && \
-	git add Makefile && \
-	git commit -m "chore: bump version to $$NEW_VERSION" && \
-	git tag -a $$NEW_VERSION -m "Release $$NEW_VERSION" && \
-	git push && git push origin $$NEW_VERSION && \
-	echo "✅ Released $$NEW_VERSION - GitHub Action will build and publish"
+.PHONY: build
+build:
+	@echo "Building comet..."
+	go build -o comet
 
-# Bump minor version (0.x.0)
-bump-minor:
-	@echo "Current version: ${VERSION}"
-	@NEW_VERSION=v0.4.7
-	echo "Bumping to $$NEW_VERSION..." && \
-	sed -i.bak "s/VERSION=v0.4.7
-	rm -f Makefile.bak && \
-	git add Makefile && \
-	git commit -m "chore: bump version to $$NEW_VERSION" && \
-	git tag -a $$NEW_VERSION -m "Release $$NEW_VERSION" && \
-	git push && git push origin $$NEW_VERSION && \
-	echo "✅ Released $$NEW_VERSION - GitHub Action will build and publish"
+.PHONY: release
+release:
+	@echo "Creating release ${VERSION}..."
+	@echo "Make sure CHANGELOG.md is updated!"
+	@read -p "Continue? [y/N] " -n 1 -r; \
+	echo; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		git add -A && \
+		git commit -m "chore: release ${VERSION}" && \
+		git tag -a ${VERSION} -m "Release ${VERSION}" && \
+		git push && git push origin ${VERSION} && \
+		echo "✅ Released ${VERSION} - GitHub Action will build and publish"; \
+	else \
+		echo "❌ Release cancelled"; \
+	fi
+
+.PHONY: website
+website:
+	@echo "Deploying website (triggers on push to main)..."
+	@echo "Website changes will deploy automatically when pushed to main"

README.md

@@ -381,19 +381,37 @@ Pre-load environment variables before any command runs. Perfect for secrets need
 ```yaml
 # comet.yaml
 env:
-  # Load SOPS AGE key from 1Password (or other secret manager)
-  SOPS_AGE_KEY: op://ci-cd/sops-age-key/private
-  
-  # Plain values work too
+  # Plain values - fast and simple
   TF_LOG: DEBUG
   AWS_REGION: us-west-2
+  
+  # Secret references - convenient but SLOW (3-5s per secret on every command)
+  # SOPS_AGE_KEY: op://ci-cd/sops-age-key/private  # ⚠️ Adds ~4s to EVERY command
 ```
 
 **Features:**
 - Supports `op://` (1Password) and `sops://` secret resolution
 - Shell environment variables take precedence
 - Loaded before stack parsing begins
 
+**⚠️ Performance Warning:**
+
+Secret references (`op://`, `sops://`) are resolved on **EVERY** comet command (plan, apply, list, etc.), which can add 3-5 seconds due to CLI overhead. 
+
+**Recommended approach for frequently-used secrets:**
+
+```bash
+# Set in your shell (one-time cost)
+export SOPS_AGE_KEY=$(op read "op://ci-cd/sops-age-key/private")
+
+# Or add to ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, etc.
+```
+
+Only use secret references in `comet.yaml` for:
+- Secrets that change frequently
+- CI/CD environments where shell setup is inconvenient
+- Situations where the ~3-5s overhead is acceptable
+
 See [Best Practices](docs/best-practices.md) for more configuration examples. 
 
 ## Development

cmd/root.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -50,19 +51,28 @@ func loadConfigEnv(config *schema.Config) {
 	for key, value := range config.Env {
 		// Skip if already set in shell environment (shell wins)
 		if os.Getenv(key) != "" {
+			log.Debug("Env var already set, skipping", "key", key)
 			continue
 		}
 
 		// Resolve secrets if value starts with op:// or sops://
 		if strings.HasPrefix(value, "op://") || strings.HasPrefix(value, "sops://") {
+			start := time.Now()
+			log.Debug("Resolving secret for env var", "key", key, "ref", value)
+			log.Warn(fmt.Sprintf("Loading secret for %s from config - this runs on EVERY command and may be slow (consider setting in shell instead)", key))
+
 			resolved, err := secrets.Get(value)
+			duration := time.Since(start)
+			log.Debug("Secret resolution completed", "key", key, "duration", duration)
+
 			if err != nil {
 				log.Error(fmt.Sprintf("failed to resolve env var %s: %v", key, err))
 				continue
 			}
 			os.Setenv(key, resolved)
 		} else {
 			// Plain value
+			log.Debug("Setting env var from config", "key", key)
 			os.Setenv(key, value)
 		}
 	}

comet.yaml

@@ -2,7 +2,14 @@ stacks_dir: stacks
 work_dir: stacks/_components
 generate_backend: false
 
-# Pre-load environment variables before any command runs
-# Perfect for SOPS AGE key which is needed during stack parsing
-env:
-  SOPS_AGE_KEY: op://ci-cd/sops-age-key/private
+# Environment variables loaded before every command
+# NOTE: Shell environment variables take precedence over these
+# WARNING: Using op:// or sops:// references here can be slow (3-5s per secret)
+#          as they are resolved on EVERY comet command (plan, apply, list, etc.)
+#          Consider setting frequently-used secrets in your shell instead:
+#            export SOPS_AGE_KEY=$(op read "op://vault/item/field")
+# env:
+#   EXAMPLE_VAR: "plain-value"
+#   SLOW_SECRET: "op://vault/item/field"  # ⚠️  Adds ~4s to every command!
+
+

internal/parser/js/js.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"reflect"
 	"strings"
+	"time"
 
 	"github.com/dop251/goja"
 	"github.com/evanw/esbuild/pkg/api"
@@ -36,11 +37,17 @@ func NewInterpreter() (*jsinterpreter, error) {
 }
 
 func (vm *jsinterpreter) Parse(path string) (*schema.Stack, error) {
+	log.Debug("JS Parse started", "path", path)
+
+	buildStart := time.Now()
 	result := api.Build(api.BuildOptions{
 		EntryPoints: []string{path},
 		Bundle:      true,
 		Write:       false,
 	})
+	buildTime := time.Since(buildStart)
+	log.Debug("esbuild completed", "path", path, "duration", buildTime)
+
 	if len(result.Errors) > 0 {
 		return nil, fmt.Errorf(errBuild, path, result.Errors)
 	}
@@ -50,6 +57,7 @@ func (vm *jsinterpreter) Parse(path string) (*schema.Stack, error) {
 
 	stack := schema.NewStack(path, "js")
 
+	setupStart := time.Now()
 	vm.rt.Set("print", fmt.Println)
 	vm.rt.Set("env", vm.envProxy())
 	vm.rt.Set("envs", vm.envsFunc)
@@ -61,9 +69,15 @@ func (vm *jsinterpreter) Parse(path string) (*schema.Stack, error) {
 	vm.rt.Set("component", vm.registerComponent(stack))
 	vm.rt.Set("append", vm.registerAppend(stack))
 	vm.rt.Set("kubeconfig", vm.registerKubeconfig(stack))
+	setupTime := time.Since(setupStart)
+	log.Debug("Runtime setup completed", "path", path, "duration", setupTime)
 
+	execStart := time.Now()
 	src := result.OutputFiles[0].Contents
 	_, err := vm.rt.RunString(string(src))
+	execTime := time.Since(execStart)
+	log.Debug("Script execution completed", "path", path, "duration", execTime)
+
 	if err != nil {
 		return nil, err
 	}
@@ -124,7 +138,13 @@ func (vm *jsinterpreter) envsFunc(args ...goja.Value) any {
 }
 
 func (vm *jsinterpreter) secretsFunc(ref string) any {
+	start := time.Now()
+	log.Debug("secrets.Get called", "ref", ref)
+
 	res, err := secrets.Get(ref)
+	duration := time.Since(start)
+	log.Debug("secrets.Get completed", "ref", ref, "duration", duration)
+
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -144,17 +164,24 @@ func (vm *jsinterpreter) secretsConfigFunc(config map[string]interface{}) {
 
 // secretFunc is a shorthand version of secretsFunc using configured defaults
 func (vm *jsinterpreter) secretFunc(path string) any {
+	start := time.Now()
+	log.Debug("secret called", "path", path)
+
 	// If path already has a provider prefix, use it as-is
 	if strings.HasPrefix(path, "sops://") || strings.HasPrefix(path, "op://") {
-		return vm.secretsFunc(path)
+		result := vm.secretsFunc(path)
+		log.Debug("secret completed", "path", path, "duration", time.Since(start))
+		return result
 	}
 
 	// Support dot notation (e.g., "datadog.api_key" -> "datadog/api_key")
 	path = strings.ReplaceAll(path, ".", "/")
 
 	// Construct full reference using defaults
 	ref := fmt.Sprintf("%s://%s#/%s", vm.secretsDefaultProvider, vm.secretsDefaultPath, path)
-	return vm.secretsFunc(ref)
+	result := vm.secretsFunc(ref)
+	log.Debug("secret completed", "path", path, "duration", time.Since(start))
+	return result
 }
 
 func (vm *jsinterpreter) registerStack(stack *schema.Stack) func(string, map[string]interface{}) goja.Value {

internal/parser/parser.go

@@ -7,9 +7,11 @@ import (
 	"path/filepath"
 	"slices"
 	"strings"
+	"time"
 
 	"github.com/bmatcuk/doublestar/v4"
 
+	"github.com/moonwalker/comet/internal/log"
 	"github.com/moonwalker/comet/internal/parser/js"
 	"github.com/moonwalker/comet/internal/schema"
 )
@@ -27,6 +29,9 @@ var (
 )
 
 func LoadStacks(dir string) (*schema.Stacks, error) {
+	start := time.Now()
+	log.Debug("LoadStacks started", "dir", dir)
+
 	stacks := &schema.Stacks{}
 
 	err := doublestar.GlobWalk(os.DirFS(dir), globpattern, func(p string, d fs.DirEntry) error {
@@ -36,16 +41,24 @@ func LoadStacks(dir string) (*schema.Stacks, error) {
 		}
 
 		path := filepath.Join(dir, p)
+		fileStart := time.Now()
+		log.Debug("Parsing stack file", "path", p)
 
 		parser, err := getParser(path)
 		if err != nil {
 			return err
 		}
+		parserTime := time.Since(fileStart)
+		log.Debug("getParser completed", "path", p, "duration", parserTime)
 
+		parseStart := time.Now()
 		stack, err := parser.Parse(path)
 		if err != nil {
+			log.Debug("Parse failed", "path", p, "error", err, "duration", time.Since(parseStart))
 			return err
 		}
+		parseTime := time.Since(parseStart)
+		log.Debug("Parse completed", "path", p, "duration", parseTime)
 
 		if stack.Valid() {
 			return stacks.AddStack(stack)
@@ -54,6 +67,9 @@ func LoadStacks(dir string) (*schema.Stacks, error) {
 		return nil
 	})
 
+	totalTime := time.Since(start)
+	log.Debug("LoadStacks completed", "total_duration", totalTime)
+
 	return stacks, err
 }