Add pre-configure hook for destination rewriting

[jeremy]

Summary

Adds a pre-configure hook that fires before configuration is created, allowing hooks to inject or rewrite the deployment destination dynamically.

Lifecycle

configure(destination: "beta")  →  pre-configure hook fires
→  hook writes KAMAL_DESTINATION=beta2  →  reconfigure(destination: "beta2")
→  config loads with deploy.beta2.yml  →  specific_hosts/roles applied

The hook fires whenever .kamal/hooks/pre-configure exists, not gated on -d. It can inject a destination for plain kamal deploy, not just rewrite an explicit one. Skipped when the config file doesn't exist (e.g. kamal init, kamal version).

Implementation

• before_config callback in Commander fires before first config access
• Pre-configure hook runs as a lightweight hook (no config-derived env) since config may be invalid without a destination
• Hook writes KAMAL_DESTINATION=<new> to $KAMAL_OUTPUT to rewrite
• command/subcommand made nil-safe since the hook fires before Thor has fully initialized invocations

Depends on #1782 for the KAMAL_OUTPUT mechanism.

Test plan

• pre-configure hook rewrites destination
• Hook can inject destination when require_destination is set
• KAMAL_MESSAGE displayed after hook runs
• Hook outputs accumulate for subsequent hooks
• Hook failure raises HookError
• Tempfile cleaned up on failure
• Skipped with --skip-hooks
• Does not fire for commands that skip config (e.g. kamal version)
• Clears leaked KAMAL_DESTINATION env var when no -d flag
• Falls back to default hooks_path on config ERB error
• Honors destination-aware hooks_path

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 61414304cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR introduces a new post-configure hook that fires before configuration is created, allowing hooks to inject or rewrite deployment destinations dynamically. This builds on the hook output mechanism from PR #1782.

Changes:

• Added before_config callback mechanism in Commander for lazy hook execution
• Implemented post-configure hook that can rewrite KAMAL_DESTINATION before config validation
• Enhanced command/subcommand methods with nil-safety to handle hook execution context

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lib/kamal/commander.rb	Added before_config callback mechanism and lazy config evaluation to support pre-configuration hooks
lib/kamal/cli/base.rb	Implemented run_post_configure_hook method with destination-aware hooks_path resolution; improved nil-safety in command/subcommand methods
lib/kamal/cli/templates/sample_hooks/post-configure.sample	New sample hook demonstrating destination rewriting with clear documentation
test/cli/post_configure_test.rb	Comprehensive test coverage including destination rewriting, require_destination interaction, error handling, and cleanup
test/cli/main_test.rb	Changed from rigid .expects().times(4) to flexible .stubs() to accommodate variable Pathname.exist? calls during initialization

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rience]

This solves a real problem for us — we deploy a monorepo (~20 apps) where every generated deploy.*.yml starts with an ERB line that loads an internal library and mutates ENV in-process (re-parsing -d out of ARGV along the way) so the rest of the YAML can read <%= ENV[...] %>. pre-configure is exactly the right replacement.

One gap for that use case: hook output other than KAMAL_DESTINATION flows to subsequent hooks but is never visible to the config file's own ERB. I've opened #1926 (stacked on this branch) that exports non-reserved $KAMAL_OUTPUT keys into ENV before config creation — happy for it to be folded in here instead if you'd prefer.