feat(stack): add git hooks with sourcing architecture (#926)

Implement a new hook structure that separates user-modifiable wrappers
from managed scripts:

- .git/hooks/{hook} - Thin wrapper (user can add custom logic)
- .git/hooks/mergify-hooks/{hook}.sh - Managed script (auto-upgradable)

This allows automatic upgrades of hook logic without touching user
customizations. Legacy hooks are detected and can be migrated with
--force flag.

CLI changes:
- `mergify stack setup --force`: Force reinstall wrappers
- `mergify stack setup --check`: Check status without changes
- `mergify stack push --no-upgrade-hooks`: Skip auto-upgrade

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: jd

mergify_cli/stack/cli.py

@@ -97,9 +97,20 @@ def github_server_to_context(
 
 
 @stack.command(help="Configure the required git commit-msg hooks")  # type: ignore[untyped-decorator]
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Force reinstall of hook wrappers, even if user modified them",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Only check hook status without making changes",
+)
 @utils.run_with_asyncio
-async def setup() -> None:
-    await stack_setup_mod.stack_setup()
+async def setup(*, force: bool, check: bool) -> None:
+    await stack_setup_mod.stack_setup(force=force, check_only=check)
 
 
 @stack.command(help="Edit the stack history")  # type: ignore[untyped-decorator]
@@ -115,6 +126,11 @@ async def edit() -> None:
     is_flag=True,
     hidden=True,
 )
+@click.option(
+    "--no-upgrade-hooks",
+    is_flag=True,
+    help="Skip automatic hook script upgrades",
+)
 @click.option("--dry-run", "-n", is_flag=True, default=False, help="dry run")
 @click.option(
     "--next-only",
@@ -177,6 +193,7 @@ async def push(
     ctx: click.Context,
     *,
     setup: bool,
+    no_upgrade_hooks: bool,
     dry_run: bool,
     next_only: bool,
     skip_rebase: bool,
@@ -192,6 +209,10 @@ async def push(
         await stack_setup_mod.stack_setup()
         return
 
+    # Auto-upgrade hook scripts (not wrappers) unless disabled
+    if not no_upgrade_hooks:
+        await stack_setup_mod.ensure_hooks_updated()
+
     await stack_push_mod.stack_push(
         github_server=ctx.obj["github_server"],
         token=ctx.obj["token"],

mergify_cli/stack/hooks/commit-msg …fy_cli/stack/hooks/scripts/commit-msg.shmergify_cli/stack/hooks/commit-msg renamed to mergify_cli/stack/hooks/scripts/commit-msg.sh mergify_cli/stack/hooks/commit-msg renamed to mergify_cli/stack/hooks/scripts/commit-msg.sh

@@ -1,4 +1,8 @@
 #!/bin/sh
+# Mergify CLI Hook Script
+# This file is managed by mergify-cli and will be auto-upgraded.
+# Do not modify - add custom logic to the wrapper file instead.
+#
 # Based on Gerrit Code Review 3.1.3
 #
 # Part of Gerrit Code Review (https://www.gerritcodereview.com/)
@@ -28,11 +32,6 @@ if test ! -f "$1" ; then
   exit 1
 fi
 
-# Do not create a change id if requested
-#if test "false" = "`git config --bool --get gerrit.createChangeId`" ; then
-#  exit 0
-#fi
-
 # $RANDOM will be undefined if not using bash, so don't use set -u
 random=$( (whoami ; hostname ; date; cat $1 ; echo $RANDOM) | git hash-object --stdin)
 dest="$1.tmp.${random}"

…rgify_cli/stack/hooks/prepare-commit-msg …tack/hooks/scripts/prepare-commit-msg.shmergify_cli/stack/hooks/prepare-commit-msg renamed to mergify_cli/stack/hooks/scripts/prepare-commit-msg.sh mergify_cli/stack/hooks/prepare-commit-msg renamed to mergify_cli/stack/hooks/scripts/prepare-commit-msg.sh

@@ -1,4 +1,7 @@
 #!/bin/sh
+# Mergify CLI Hook Script
+# This file is managed by mergify-cli and will be auto-upgraded.
+# Do not modify - add custom logic to the wrapper file instead.
 #
 #  Copyright © 2021-2024 Mergify SAS
 #

mergify_cli/stack/hooks/wrappers/commit-msg

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Mergify CLI Hook Wrapper
+# This file is managed by mergify-cli. You can add custom logic below the marker.
+
+MERGIFY_HOOKS_DIR="$(dirname "$0")/mergify-hooks"
+if [ -f "$MERGIFY_HOOKS_DIR/commit-msg.sh" ]; then
+    "$MERGIFY_HOOKS_DIR/commit-msg.sh" "$@" || exit $?
+fi
+
+# --- USER CUSTOM LOGIC BELOW ---
+# Add your custom hook logic here (preserved during upgrades)

mergify_cli/stack/hooks/wrappers/prepare-commit-msg

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Mergify CLI Hook Wrapper
+# This file is managed by mergify-cli. You can add custom logic below the marker.
+
+MERGIFY_HOOKS_DIR="$(dirname "$0")/mergify-hooks"
+if [ -f "$MERGIFY_HOOKS_DIR/prepare-commit-msg.sh" ]; then
+    "$MERGIFY_HOOKS_DIR/prepare-commit-msg.sh" "$@" || exit $?
+fi
+
+# --- USER CUSTOM LOGIC BELOW ---
+# Add your custom hook logic here (preserved during upgrades)