feat: Implement sam build --watch for automatic rebuilds

samcli/commands/build/command.py

@@ -4,10 +4,13 @@
 
 import logging
 import os
-from typing import Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
 
 import click
 
+if TYPE_CHECKING:
+    from samcli.commands.build.build_context import BuildContext
+
 from samcli.cli.cli_config_file import ConfigProvider, configuration_option, save_params_option
 from samcli.cli.context import Context
 from samcli.cli.main import aws_creds_options, pass_context, print_cmdline_args
@@ -30,6 +33,7 @@
     template_option_without_build,
     terraform_project_root_path_option,
     use_container_build_option,
+    watch_exclude_option,
 )
 from samcli.commands.build.click_container import ContainerOptions
 from samcli.commands.build.core.command import BuildCommand
@@ -45,7 +49,10 @@
 
 DESCRIPTION = """
   Build AWS serverless function code to generate artifacts targeting
-  AWS Lambda execution environment.\n
+  AWS Lambda execution environment.
+
+  Use --watch to automatically rebuild when source files change,
+  similar to 'sam sync --watch' for local development workflows.\n
   \b
   Supported Resource Types
   ------------------------
@@ -106,6 +113,16 @@
 @click.option(
     "--parallel", "-p", is_flag=True, help="Enable parallel builds for AWS SAM template's functions and layers."
 )
+@click.option(
+    "--watch/--no-watch",
+    is_flag=True,
+    help="Watch local files and automatically rebuild when changes are detected. "
+    "When enabled, monitors your source code and template for changes and "
+    "triggers automatic rebuilds. Changes are debounced to avoid excessive rebuilds "
+    "during rapid file modifications. Build artifacts, cache directories, and "
+    "temporary files are automatically excluded from monitoring. "
+    "Press Ctrl+C to stop watch mode. Similar to 'sam sync --watch' workflow.",
+)
 @click.option(
     "--mount-with",
     "-mw",
@@ -117,6 +134,7 @@
     cls=ContainerOptions,
 )
 @mount_symlinks_option
+@watch_exclude_option
 @build_dir_option
 @cache_dir_option
 @base_dir_option
@@ -144,6 +162,8 @@ def cli(
     use_container: bool,
     cached: bool,
     parallel: bool,
+    watch: bool,
+    watch_exclude: Optional[Dict[str, List[str]]],
     manifest: Optional[str],
     docker_network: Optional[str],
     container_env_var: Optional[Tuple[str]],
@@ -180,6 +200,8 @@ def cli(
         use_container,
         cached,
         parallel,
+        watch,
+        watch_exclude,
         manifest,
         docker_network,
         skip_pull_image,
@@ -207,6 +229,8 @@ def do_cli(  # pylint: disable=too-many-locals, too-many-statements
     use_container: bool,
     cached: bool,
     parallel: bool,
+    watch: bool,
+    watch_exclude: Optional[Dict[str, List[str]]],
     manifest_path: Optional[str],
     docker_network: Optional[str],
     skip_pull_image: bool,
@@ -261,7 +285,41 @@ def do_cli(  # pylint: disable=too-many-locals, too-many-statements
         mount_with=mount_with,
         mount_symlinks=mount_symlinks,
     ) as ctx:
-        ctx.run()
+        if watch:
+            watch_excludes_filter = watch_exclude or {}
+            execute_build_watch(
+                template=template,
+                build_context=ctx,
+                watch_exclude=watch_excludes_filter,
+            )
+        else:
+            ctx.run()
+
+
+def execute_build_watch(
+    template: str,
+    build_context: "BuildContext",
+    watch_exclude: Dict[str, List[str]],
+) -> None:
+    """Start build watch execution
+
+    Parameters
+    ----------
+    template : str
+        Template file path
+    build_context : BuildContext
+        BuildContext for build operations
+    watch_exclude : Dict[str, List[str]]
+        Dictionary of watch exclusion patterns per resource
+    """
+    from samcli.lib.build.watch_manager import BuildWatchManager
+
+    build_watch_manager = BuildWatchManager(
+        template,
+        build_context,
+        watch_exclude,
+    )
+    build_watch_manager.start()
 
 
 def _get_mode_value_from_envvar(name: str, choices: List[str]) -> Optional[str]:

samcli/commands/build/core/command.py

@@ -44,6 +44,10 @@ def format_examples(ctx: Context, formatter: BuildCommandHelpTextFormatter):
                         name=style(f"$ {ctx.command_path} && {ctx.parent.command_path} local invoke"),  # type: ignore
                         extra_row_modifiers=[ShowcaseRowModifier()],
                     ),
+                    RowDefinition(
+                        name=style(f"$ {ctx.command_path} --watch"),
+                        extra_row_modifiers=[ShowcaseRowModifier()],
+                    ),
                     RowDefinition(
                         name=style(f"$ {ctx.command_path} && {ctx.parent.command_path} deploy"),  # type: ignore
                         extra_row_modifiers=[ShowcaseRowModifier()],

samcli/commands/build/core/options.py

@@ -29,7 +29,15 @@
 
 EXTENSION_OPTIONS: List[str] = ["hook_name", "skip_prepare_infra"]
 
-BUILD_STRATEGY_OPTIONS: List[str] = ["parallel", "exclude", "manifest", "cached", "build_in_source"]
+BUILD_STRATEGY_OPTIONS: List[str] = [
+    "build_in_source",
+    "cached",
+    "exclude",
+    "manifest",
+    "parallel",
+    "watch",
+    "watch_exclude",
+]
 
 ARTIFACT_LOCATION_OPTIONS: List[str] = [
     "build_dir",