fix(init): run cookiecutter template hooks from the packaged binary

samcli/__main__.py

@@ -5,8 +5,12 @@
 """
 
 from samcli.cli.main import cli  # pragma: no cover
+from samcli.lib.utils.hook_script import run_hook_script_if_requested  # pragma: no cover
 
 if __name__ == "__main__":  # pragma: no cover
+    # A bundle runs cookiecutter's Python hooks by re-launching itself, so claim those invocations
+    # before the CLI treats the script path as a command name.
+    run_hook_script_if_requested()
     # NOTE(TheSriram): prog_name is always set to "sam". This way when the CLI is invoked as a module,
     # the help text that is generated still says "sam" instead of "__main__".
     cli(prog_name="sam")

samcli/lib/cookiecutter/template.py

@@ -6,6 +6,7 @@
 import logging
 from typing import Dict, List, Optional
 
+from cookiecutter import hooks as cookiecutter_hooks
 from cookiecutter.exceptions import RepositoryNotFound, UnknownRepoType
 from cookiecutter.main import cookiecutter
 
@@ -20,6 +21,7 @@
 from samcli.lib.cookiecutter.plugin import Plugin
 from samcli.lib.cookiecutter.processor import Processor
 from samcli.lib.init.arbitrary_project import generate_non_cookiecutter_project
+from samcli.lib.utils.hook_script import patched_hook_runner
 
 LOG = logging.getLogger(__name__)
 
@@ -167,13 +169,14 @@ def generate_project(self, context: Dict, output_dir: str) -> None:
 
         try:
             LOG.debug("Baking a new template with cookiecutter with all parameters")
-            cookiecutter(
-                template=self._location,
-                output_dir=output_dir,
-                no_input=True,
-                extra_context=context,
-                overwrite_if_exists=True,
-            )
+            with patched_hook_runner(cookiecutter_hooks):
+                cookiecutter(
+                    template=self._location,
+                    output_dir=output_dir,
+                    no_input=True,
+                    extra_context=context,
+                    overwrite_if_exists=True,
+                )
         except RepositoryNotFound:
             # cookiecutter.json is not found in the template. Let's just clone it directly without
             # using cookiecutter and call it done.

samcli/lib/init/__init__.py

@@ -8,6 +8,7 @@
 from pathlib import Path
 from typing import Dict, Optional
 
+from cookiecutter import hooks as cookiecutter_hooks
 from cookiecutter.exceptions import CookiecutterException, RepositoryNotFound, UnknownRepoType
 from cookiecutter.main import cookiecutter
 
@@ -22,6 +23,7 @@
 from samcli.lib.init.template_modifiers.xray_tracing_template_modifier import XRayTracingTemplateModifier
 from samcli.lib.telemetry.event import EventName, EventTracker, UsedFeature
 from samcli.lib.utils import osutils
+from samcli.lib.utils.hook_script import patched_hook_runner
 from samcli.lib.utils.packagetype import ZIP
 from samcli.local.common.runtime_template import RUNTIME_DEP_TEMPLATE_MAPPING, is_custom_runtime
 
@@ -119,7 +121,8 @@ def generate_project(
         LOG.debug("Baking a new template with cookiecutter with all parameters")
         # cookiecutter returns the directory it created, which is the only reliable way to know
         # where the project landed when the template chooses its own project directory name.
-        project_directory = cookiecutter(**params)
+        with patched_hook_runner(cookiecutter_hooks):
+            project_directory = cookiecutter(**params)
         # Fixes gradlew line ending issue caused by Windows git
         # gradlew is a shell script which should not have CR LF line endings
         # Putting the conversion after cookiecutter as cookiecutter processing will also change the line endings

samcli/lib/utils/hook_script.py

@@ -0,0 +1,136 @@
+"""
+Support for running cookiecutter template hooks from a PyInstaller bundle.
+
+Cookiecutter runs a Python hook as ``[sys.executable, script]``. In a bundle ``sys.executable`` is
+the sam executable itself, so the hook never runs. This module supplies a real interpreter: a system
+python3 when one is available, otherwise this executable re-launched in hook mode.
+"""
+
+import logging
+import os
+import runpy
+import shutil
+import subprocess
+import sys
+from contextlib import contextmanager
+from types import ModuleType
+from typing import Iterator, Optional
+
+from samcli.lib.utils.subprocess_utils import is_pyinstaller_bundle, isolate_library_paths_for_subprocess
+
+LOG = logging.getLogger(__name__)
+
+# Set on the hook subprocess so a re-launched bundle runs the script instead of parsing a command name.
+HOOK_SCRIPT_ENV_VAR = "SAM_CLI_RUN_HOOK_SCRIPT"
+
+# A bundle ships no interpreter of its own. A system one is preferred for isolation, so that SAM's
+# bundled dependencies do not become an implicit contract for template authors -- not for fidelity
+# with a pip install, where hooks can in fact import SAM's dependencies. The order matches
+# _get_python_command_name in the terraform prepare hook, and includes the Windows launcher because
+# a default python.org install puts only py.exe on PATH.
+_INTERPRETER_CANDIDATES = ("python3", "py3", "python", "py")
+# Matches requires-python, so a hook never sees an older Python than a pip install would give it.
+_MINIMUM_PYTHON_VERSION = (3, 10)
+_PROBE_TIMEOUT = 10
+
+
+def run_hook_script_if_requested() -> None:
+    """Run the script named in argv and exit, when re-launched by the patched hook runner."""
+    # Popped rather than read so a hook that shells out to sam again gets the normal CLI.
+    requested = os.environ.pop(HOOK_SCRIPT_ENV_VAR, None) == "1"
+    arguments = sys.argv[1:]
+    if not requested or not arguments:
+        return
+
+    LOG.debug("Running template hook script %s through this executable", arguments[0])
+    # The bootloader re-points library paths into the bundle for this process, and the CLI callback
+    # that normally undoes that is never reached here. Hooks routinely shell out to git, npm and pip.
+    isolate_library_paths_for_subprocess()
+    # A hook launched by a real interpreter sees only its own path in argv; run_path fixes argv[0]
+    # but would leave our second argument behind, so give the hook the argv it expects.
+    with _replaced_attribute(sys, "argv", [arguments[0]]):
+        runpy.run_path(arguments[0], run_name="__main__")
+    sys.exit(0)
+
+
+def find_system_interpreter() -> Optional[str]:
+    """Return the path to a usable system Python 3, or None if there isn't one."""
+    for candidate in _INTERPRETER_CANDIDATES:
+        path = shutil.which(candidate)
+        if not path or os.path.realpath(path) == os.path.realpath(sys.executable):
+            continue
+        # Executed rather than trusted because Windows ships a "python" App Execution Alias that
+        # resolves on PATH without being an interpreter, and because /usr/bin/python3 is 3.6 on
+        # older distributions, where a hook using newer syntax would fail with a SyntaxError.
+        try:
+            completed = subprocess.run(
+                [path, "-c", f"import sys; sys.exit(0 if sys.version_info >= {_MINIMUM_PYTHON_VERSION} else 1)"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=_PROBE_TIMEOUT,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if completed.returncode == 0:
+            return path
+    return None
+
+
+@contextmanager
+def _replaced_attribute(target: object, name: str, value: object) -> Iterator[None]:
+    """Set an attribute for the duration of the block, restoring whatever was there before."""
+    original = getattr(target, name)
+    setattr(target, name, value)
+    try:
+        yield
+    finally:
+        setattr(target, name, original)
+
+
+@contextmanager
+def _hook_script_env() -> Iterator[None]:
+    """Mark the environment so the re-launched executable runs the hook script."""
+    original = os.environ.get(HOOK_SCRIPT_ENV_VAR)
+    os.environ[HOOK_SCRIPT_ENV_VAR] = "1"
+    try:
+        yield
+    finally:
+        if original is None:
+            os.environ.pop(HOOK_SCRIPT_ENV_VAR, None)
+        else:
+            os.environ[HOOK_SCRIPT_ENV_VAR] = original
+
+
+@contextmanager
+def patched_hook_runner(hooks_module: ModuleType) -> Iterator[None]:
+    """Make cookiecutter's Python hooks runnable while frozen; a no-op when not frozen.
+
+    The module is passed in so this stays importable without pulling in cookiecutter, which every
+    sam invocation would otherwise pay for at startup.
+    """
+    if not is_pyinstaller_bundle():
+        yield
+        return
+
+    original_run_script = hooks_module.run_script
+
+    def run_script(script_path: str, cwd: str = ".") -> None:
+        # Only .py hooks go through an interpreter; anything else already runs on its own.
+        if not script_path.endswith(".py"):
+            original_run_script(script_path, cwd)
+            return
+
+        interpreter = find_system_interpreter()
+        if interpreter:
+            LOG.debug("Running template hook with system interpreter %s", interpreter)
+            with _replaced_attribute(sys, "executable", interpreter):
+                original_run_script(script_path, cwd)
+            return
+
+        LOG.debug("No system interpreter found, re-launching this executable to run the template hook")
+        with _hook_script_env():
+            original_run_script(script_path, cwd)
+
+    with _replaced_attribute(hooks_module, "run_script", run_script):
+        yield

tests/integration/init/test_init_command.py

@@ -684,7 +684,7 @@ def _assert_template_with_cfn_lint(self, cwd):
 You can run 'sam init' without any options for an interactive initialization flow, or you can provide one of the following required parameter combinations:
 \t--name, --location, or
 \t--name, --package-type, --base-image, or
-\t--name, --runtime, --app-template, --dependency-manager
+\t--name, --runtime, --dependency-manager, --app-template
 """
 
 

tests/unit/lib/cookiecutter/test_template.py

@@ -8,6 +8,7 @@
     PreprocessingError,
     PostprocessingError,
 )
+from cookiecutter import hooks as cookiecutter_hooks
 from cookiecutter.exceptions import RepositoryNotFound, UnknownRepoType
 
 
@@ -102,6 +103,22 @@ def test_run_interactive_flows_throws_user_exception_if_something_wrong(self, mo
             mock_interactive_flow.run.assert_called_once_with({})
             mock_plugin.interactive_flow.run.assert_called_once_with(self._ANY_INTERACTIVE_FLOW_CONTEXT)
 
+    @patch("samcli.lib.cookiecutter.template.patched_hook_runner")
+    @patch("samcli.lib.cookiecutter.template.cookiecutter")
+    def test_hook_runner_is_active_while_cookiecutter_runs(self, mock_cookiecutter, mock_hook_runner):
+        # Without this the wrapper could be dropped and every other test would still pass, because
+        # patched_hook_runner is a no-op unless running from a bundle. This is the sam pipeline init
+        # path, which was missed on the first pass at this fix.
+        events = []
+        mock_hook_runner.return_value.__enter__.side_effect = lambda: events.append("enter")
+        mock_hook_runner.return_value.__exit__.side_effect = lambda *args: events.append("exit")
+        mock_cookiecutter.side_effect = lambda **kwargs: events.append("cookiecutter")
+
+        Template(location=self._ANY_LOCATION).generate_project(context={}, output_dir=Mock())
+
+        mock_hook_runner.assert_called_once_with(cookiecutter_hooks)
+        self.assertEqual(events, ["enter", "cookiecutter", "exit"])
+
     @patch("samcli.lib.cookiecutter.template.cookiecutter")
     @patch("samcli.lib.cookiecutter.interactive_flow")
     @patch("samcli.lib.cookiecutter.processor")

tests/unit/lib/init/test_init.py

@@ -2,6 +2,7 @@
 from unittest.mock import patch
 
 from pathlib import Path
+from cookiecutter import hooks as cookiecutter_hooks
 from cookiecutter.exceptions import CookiecutterException, RepositoryNotFound
 from parameterized import parameterized
 
@@ -22,6 +23,32 @@ def setUp(self):
         self.extra_context = {"project_name": "testing project", "runtime": self.runtime}
         self.template = RUNTIME_DEP_TEMPLATE_MAPPING["python"][0]["init_location"]
 
+    @patch("samcli.lib.init.cookiecutter")
+    @patch("samcli.lib.init._create_default_samconfig")
+    @patch("samcli.lib.init.patched_hook_runner")
+    def test_hook_runner_is_active_while_cookiecutter_runs(
+        self, hook_runner_mock, default_samconfig_mock, cookiecutter_patch
+    ):
+        # Without this the wrapper could be dropped and every other test would still pass, because
+        # patched_hook_runner is a no-op unless running from a bundle.
+        events = []
+        hook_runner_mock.return_value.__enter__.side_effect = lambda: events.append("enter")
+        hook_runner_mock.return_value.__exit__.side_effect = lambda *args: events.append("exit")
+        cookiecutter_patch.side_effect = lambda **kwargs: events.append("cookiecutter")
+
+        generate_project(
+            location=self.location,
+            runtime=self.runtime,
+            package_type=ZIP,
+            dependency_manager=self.dependency_manager,
+            output_dir=self.output_dir,
+            name=self.name,
+            no_input=self.no_input,
+        )
+
+        hook_runner_mock.assert_called_once_with(cookiecutter_hooks)
+        self.assertEqual(events, ["enter", "cookiecutter", "exit"])
+
     @patch("samcli.lib.init.cookiecutter")
     @patch("samcli.lib.init._create_default_samconfig")
     def test_init_successful(self, default_samconfig_mock, cookiecutter_patch):