Implement migrate subcommand (closes #1)

- Add internal/cmd/migrate.go with full implementation:
  - Execute migration command via execve (no shell) using -- separator
  - Capture stdout/stderr with timestamps
  - Optional JSON log output via --json
  - Forward child process exit code
  - --workdir flag for file operations (default /work)
  - --lock-file flag for idempotency (skip if marker file exists)
- Add internal/cmd/migrate_test.go with 14 tests covering:
  - No args error, success, exit code forwarding
  - stdout/stderr capture, JSON output
  - Lock file skip, creation, non-creation on failure
  - Path traversal prevention, command not found
  - ExitCodeFromError helper, runCommand success/failure
- Register migrate command in cmd/initium/main.go
- Update docs/usage.md with migrate 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
+- `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
 - Project scaffolding with Go module, CLI framework (cobra), and repo layout
 - `wait-for` subcommand: wait for TCP and HTTP(S) endpoints with retries, exponential backoff, and jitter

cmd/initium/context.go

@@ -8,6 +8,7 @@ import (
 
 type loggerKey struct{}
 
+// withLogger returns a new context.Context that carries a logger.
 func withLogger(ctx context.Context, log *logging.Logger) context.Context {
 	return context.WithValue(ctx, loggerKey{}, log)
 }

docs/usage.md

@@ -67,15 +67,52 @@ initium wait-for \
 
 Targets are checked sequentially. All must become reachable before the command succeeds.
 
-### migrate _(coming soon)_
+### migrate
 
-Run a database migration command with structured logging.
+Run a database migration command with structured logging, exit code forwarding,
+and optional idempotency via a lock file.
+
+The command is executed directly via `execve` (no shell). Use `--` to separate
+initium flags from the migration command and its arguments.
 
 ```bash
+# Run a flyway migration
 initium migrate -- flyway migrate
+
+# Run with JSON logs
 initium migrate --json -- /app/migrate -path /migrations up
+
+# Idempotent: skip if already migrated
+initium migrate --lock-file .migrated --workdir /work -- /app/migrate up
 ```
 
+**Flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--workdir` | `/work` | Working directory for file operations |
+| `--lock-file` | _(none)_ | Skip migration if this file exists in workdir (idempotency) |
+| `--json` | `false` | Enable JSON log output |
+
+**Behavior:**
+
+- stdout and stderr from the migration command are captured and logged with timestamps
+- The child process exit code is forwarded: a non-zero exit code causes `migrate` to fail
+- When `--lock-file` is set:
+  - If the lock file exists in `--workdir`, the migration is skipped (exit 0)
+  - On successful completion, the lock file is created so subsequent runs become no-ops
+  - If the migration fails, no lock file is created
+- Lock file paths are validated against `--workdir` to prevent path traversal
+- No shell is used: the command is executed directly via `execve`
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| `0` | Migration succeeded (or skipped via lock file) |
+| `1` | Migration command failed, or invalid arguments |
+| _N_ | Forwarded from the migration command |
+
 ### seed _(coming soon)_
 
 Run a database seed command.

internal/cmd/migrate.go

@@ -0,0 +1,188 @@
+package cmd
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"sync"
+	"syscall"
+
+	"github.com/kitstream/initium/internal/logging"
+	"github.com/kitstream/initium/internal/safety"
+	"github.com/spf13/cobra"
+)
+
+func NewMigrateCmd(log *logging.Logger) *cobra.Command {
+	var (
+		workdir  string
+		lockFile string
+		jsonLogs bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "migrate -- COMMAND [ARGS...]",
+		Short: "Run a database migration command with structured logging",
+		Long: `Execute a database migration command with structured logging, exit code
+forwarding, and optional idempotency via a lock file.
+
+The command is executed directly via execve (no shell). Use "--" to separate
+initium flags from the migration command and its arguments.
+
+If --lock-file is set, the migration is skipped when the lock file already
+exists inside --workdir. On successful completion the lock file is created
+so subsequent runs become no-ops.`,
+		Example: `  # Run a flyway migration
+  initium migrate -- flyway migrate
+
+  # Run with JSON logs
+  initium migrate --json -- /app/migrate -path /migrations up
+
+  # Idempotent: skip if already migrated
+  initium migrate --lock-file .migrated --workdir /work -- /app/migrate up`,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if jsonLogs {
+				log.SetJSON(true)
+			}
+
+			if len(args) == 0 {
+				return fmt.Errorf("migration command is required after \"--\"")
+			}
+
+			if lockFile != "" {
+				lockPath, err := safety.ValidateFilePath(workdir, lockFile)
+				if err != nil {
+					return fmt.Errorf("invalid lock file path: %w", err)
+				}
+
+				if _, err := os.Stat(lockPath); err == nil {
+					log.Info("lock file exists, skipping migration", "lock-file", lockPath)
+					return nil
+				}
+			}
+
+			log.Info("starting migration", "command", args[0])
+
+			exitCode, err := runCommand(log, args)
+			if err != nil {
+				return fmt.Errorf("migration failed: %w", err)
+			}
+
+			if exitCode != 0 {
+				return fmt.Errorf("migration exited with code %d", exitCode)
+			}
+
+			if lockFile != "" {
+				lockPath, err := safety.ValidateFilePath(workdir, lockFile)
+				if err != nil {
+					return fmt.Errorf("invalid lock file path: %w", err)
+				}
+
+				if err := os.MkdirAll(workdir, 0o755); err != nil {
+					return fmt.Errorf("creating workdir %s: %w", workdir, err)
+				}
+
+				if err := os.WriteFile(lockPath, []byte("migrated\n"), 0o644); err != nil {
+					return fmt.Errorf("writing lock file %s: %w", lockPath, err)
+				}
+				log.Info("lock file created", "lock-file", lockPath)
+			}
+
+			log.Info("migration completed successfully")
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&workdir, "workdir", "/work", "Working directory for file operations")
+	cmd.Flags().StringVar(&lockFile, "lock-file", "", "Skip migration if this file exists in workdir (idempotency)")
+	cmd.Flags().BoolVar(&jsonLogs, "json", false, "Enable JSON log output")
+
+	return cmd
+}
+
+func runCommand(log *logging.Logger, args []string) (int, error) {
+	c := exec.Command(args[0], args[1:]...)
+	c.Stdin = nil
+
+	stdoutPipe, err := c.StdoutPipe()
+	if err != nil {
+		return -1, fmt.Errorf("creating stdout pipe: %w", err)
+	}
+
+	stderrPipe, err := c.StderrPipe()
+	if err != nil {
+		return -1, fmt.Errorf("creating stderr pipe: %w", err)
+	}
+
+	if err := c.Start(); err != nil {
+		return -1, fmt.Errorf("starting command %q: %w", args[0], err)
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+		streamLines(log, stdoutPipe, "stdout")
+	}()
+
+	go func() {
+		defer wg.Done()
+		streamLines(log, stderrPipe, "stderr")
+	}()
+
+	wg.Wait()
+
+	err = c.Wait()
+	if err == nil {
+		return 0, nil
+	}
+
+	var exitErr *exec.ExitError
+	if ok := asExitError(err, &exitErr); ok {
+		return exitErr.ExitCode(), nil
+	}
+
+	return -1, err
+}
+
+func asExitError(err error, target **exec.ExitError) bool {
+	if e, ok := err.(*exec.ExitError); ok {
+		*target = e
+		return true
+	}
+	return false
+}
+
+func streamLines(log *logging.Logger, r io.Reader, stream string) {
+	scanner := bufio.NewScanner(r)
+	for scanner.Scan() {
+		log.Info(scanner.Text(), "stream", stream)
+	}
+}
+
+// ExitCodeFromError extracts the exit code from a command error.
+// Used by callers that need to propagate exit codes (e.g., os.Exit).
+func ExitCodeFromError(err error) int {
+	if err == nil {
+		return 0
+	}
+
+	// Check if the error message contains an exit code pattern
+	var exitCode int
+	if n, _ := fmt.Sscanf(err.Error(), "migration exited with code %d", &exitCode); n == 1 {
+		return exitCode
+	}
+
+	// Check for underlying process exit status
+	if exitErr, ok := err.(*exec.ExitError); ok {
+		if status, ok := exitErr.Sys().(syscall.WaitStatus); ok {
+			return status.ExitStatus()
+		}
+	}
+
+	return 1
+}