Implement render subcommand and internal/render package (closes #3)

- Add internal/render/render.go:
  - Envsubst mode: replace ${VAR} and $VAR with env var values
  - GoTemplate mode: full Go text/template with env vars as data map
- Add internal/render/render_test.go with 17 tests:
  - envsubst: basic, missing var, empty, no vars, empty value, special
    chars, multiline, adjacent vars, underscores, dollar without var
  - gotemplate: basic, missing var, empty, invalid syntax, conditional,
    special chars, envToMap
- Add internal/cmd/render.go: render subcommand with --template,
  --output, --workdir, --mode (envsubst|gotemplate), --json flags
- Add internal/cmd/render_test.go with 11 command-level tests:
  - no template, no output, invalid mode, envsubst, gotemplate,
    path traversal, missing template, nested output dir, invalid
    go template syntax, JSON output, empty template
- Register render command in cmd/initium/main.go
- Update docs/usage.md with render section
- Update CHANGELOG.md

Author: mikkeldamsgaard

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `render` subcommand and `internal/render` package: render templates into config files with `envsubst` (default) and Go `text/template` modes, path traversal prevention, and automatic intermediate directory creation
 - `seed` subcommand: run database seed commands with structured logging and exit code forwarding (no idempotency — distinct from `migrate`)
 - `migrate` subcommand: run database migration commands with structured logging, exit code forwarding, and optional idempotency via `--lock-file`
 - FAQ.md with functionality, security, and deployment questions for junior-to-mid-level engineers

cmd/initium/main.go

@@ -35,6 +35,7 @@ and security guardrails.`,
 	root.AddCommand(cmd.NewWaitForCmd(log))
 	root.AddCommand(cmd.NewMigrateCmd(log))
 	root.AddCommand(cmd.NewSeedCmd(log))
+	root.AddCommand(cmd.NewRenderCmd(log))
 	if err := root.Execute(); err != nil {
 		log.Error(err.Error())
 		os.Exit(1)

docs/usage.md

@@ -154,14 +154,48 @@ initium seed --json -- python3 /scripts/seed.py
 | `1` | Seed command failed, or invalid arguments |
 | _N_ | Forwarded from the seed command |
 
-### render _(coming soon)_
+### render
 
-Render templates into config files.
+Render a template file into a config file using environment variable substitution.
+
+Two modes are supported:
+
+- **envsubst** (default) — replaces `${VAR}` and `$VAR` patterns with environment variable values. Missing variables are left as-is.
+- **gotemplate** — full Go `text/template` support with environment variables as `.VarName`. Missing variables produce empty strings.
+
+Output files are written relative to `--workdir` with path traversal prevention. Intermediate directories are created automatically.
 
 ```bash
-initium render --template /templates/app.conf.tmpl --output config/app.conf --workdir /work
+# envsubst mode (default)
+initium render --template /templates/app.conf.tmpl --output app.conf
+
+# Go template mode
+initium render --mode gotemplate --template /templates/app.conf.tmpl --output app.conf
+
+# Custom workdir
+initium render --template /tpl/nginx.conf.tmpl --output nginx.conf --workdir /etc/nginx
+
+# Nested output directory (created automatically)
+initium render --template /tpl/db.conf.tmpl --output config/db.conf --workdir /work
 ```
 
+**Flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--template` | _(required)_ | Path to template file |
+| `--output` | _(required)_ | Output file path relative to workdir |
+| `--workdir` | `/work` | Working directory for output files |
+| `--mode` | `envsubst` | Template mode: `envsubst` or `gotemplate` |
+| `--json` | `false` | Enable JSON log output |
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Render succeeded |
+| `1` | Invalid arguments, missing template, template syntax error, or path traversal |
+
 ### fetch _(coming soon)_
 
 Fetch secrets or config from HTTP endpoints.

internal/cmd/render.go

@@ -0,0 +1,102 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/kitstream/initium/internal/logging"
+	"github.com/kitstream/initium/internal/render"
+	"github.com/kitstream/initium/internal/safety"
+	"github.com/spf13/cobra"
+)
+
+func NewRenderCmd(log *logging.Logger) *cobra.Command {
+	var (
+		templatePath string
+		outputPath   string
+		workdir      string
+		mode         string
+		jsonLogs     bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "render",
+		Short: "Render templates into config files",
+		Long: `Render a template file into a config file using environment variable
+substitution. Supports two modes:
+
+  envsubst    — replaces ${VAR} and $VAR patterns (default)
+  gotemplate  — full Go text/template with env vars as .VarName
+
+Output files are written relative to --workdir with path traversal prevention.
+Intermediate directories are created automatically.`,
+		Example: `  # envsubst mode (default)
+  initium render --template /templates/app.conf.tmpl --output app.conf
+
+  # Go template mode
+  initium render --mode gotemplate --template /templates/app.conf.tmpl --output app.conf
+
+  # Custom workdir
+  initium render --template /tpl/nginx.conf.tmpl --output nginx.conf --workdir /etc/nginx`,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if jsonLogs {
+				log.SetJSON(true)
+			}
+
+			if templatePath == "" {
+				return fmt.Errorf("--template is required")
+			}
+			if outputPath == "" {
+				return fmt.Errorf("--output is required")
+			}
+			if mode != "envsubst" && mode != "gotemplate" {
+				return fmt.Errorf("--mode must be envsubst or gotemplate, got %q", mode)
+			}
+
+			outPath, err := safety.ValidateFilePath(workdir, outputPath)
+			if err != nil {
+				return fmt.Errorf("invalid output path: %w", err)
+			}
+
+			data, err := os.ReadFile(templatePath)
+			if err != nil {
+				return fmt.Errorf("reading template %s: %w", templatePath, err)
+			}
+
+			log.Info("rendering template", "template", templatePath, "output", outPath, "mode", mode)
+
+			var result string
+			switch mode {
+			case "envsubst":
+				result = render.Envsubst(string(data))
+			case "gotemplate":
+				result, err = render.GoTemplate(string(data))
+				if err != nil {
+					return fmt.Errorf("rendering template: %w", err)
+				}
+			}
+
+			if err := os.MkdirAll(filepath.Dir(outPath), 0o755); err != nil {
+				return fmt.Errorf("creating output directory: %w", err)
+			}
+
+			if err := os.WriteFile(outPath, []byte(result), 0o644); err != nil {
+				return fmt.Errorf("writing output %s: %w", outPath, err)
+			}
+
+			log.Info("render completed", "output", outPath)
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&templatePath, "template", "", "Path to template file (required)")
+	cmd.Flags().StringVar(&outputPath, "output", "", "Output file path relative to workdir (required)")
+	cmd.Flags().StringVar(&workdir, "workdir", "/work", "Working directory for output files")
+	cmd.Flags().StringVar(&mode, "mode", "envsubst", "Template mode: envsubst or gotemplate")
+	cmd.Flags().BoolVar(&jsonLogs, "json", false, "Enable JSON log output")
+
+	return cmd
+}