fix: prevent incorrect entrypoint inference when multiple candidates exist (#313)

- Changed detect_entrypoint() return type from Optional[Path] to List[Path]
- Updated CLI layer to handle 0/1/multiple file cases appropriately
- Show error listing all files when ambiguous, require explicit path
- Updated 5 test cases to validate new list-based behavior

Fixes issue where agent.py was incorrectly inferred as entrypoint when
both agent.py (implementation) and main.py (actual entrypoint) exist.
Users must now explicitly specify path when multiple candidates found.

All tests pass (51/51). Pre-commit hooks validated.

Co-authored-by: Abhimanyu Siwach <siwabhi@amazon.com>

Author: siwachabhi

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
   # PRE-COMMIT STAGE (Fast, Auto-fixing)
   # Runs on every commit
   # ========================================
-  
+
   # uv lock file management
   - repo: https://github.com/astral-sh/uv-pre-commit
     rev: 0.7.13
@@ -98,4 +98,4 @@ ci:
   submodules: false
 
 default_install_hook_types: [pre-commit, pre-push]
-default_stages: [pre-commit]
+default_stages: [pre-commit]

src/bedrock_agentcore_starter_toolkit/cli/runtime/commands.py

@@ -162,20 +162,28 @@ def _detect_entrypoint_in_source(source_path: str, non_interactive: bool = False
     # Use operations layer for detection
     detected = detect_entrypoint(source_dir)
 
-    if not detected:
-        # No fallback prompt - fail with clear error message
+    if len(detected) == 0:
+        # No files found - error
         rel_source = get_relative_path(source_dir)
         _handle_error(
             f"No entrypoint file found in {rel_source}\n"
             f"Expected one of: main.py, agent.py, app.py, __main__.py\n"
             f"Please specify full file path (e.g., {rel_source}/your_agent.py)"
         )
+    elif len(detected) > 1:
+        # Multiple files found - error with list
+        rel_source = get_relative_path(source_dir)
+        files_list = ", ".join(f.name for f in detected)
+        _handle_error(
+            f"Multiple entrypoint files found in {rel_source}: {files_list}\n"
+            f"Please specify full file path (e.g., {rel_source}/main.py)"
+        )
 
-    # Show detection and confirm
-    rel_entrypoint = get_relative_path(detected)
+    # Exactly one file - show detection and confirm
+    rel_entrypoint = get_relative_path(detected[0])
 
     _print_success(f"Using entrypoint file: [cyan]{rel_entrypoint}[/cyan]")
-    return str(detected)
+    return str(detected[0])
 
 
 # Define options at module level to avoid B008

src/bedrock_agentcore_starter_toolkit/operations/runtime/configure.py

@@ -60,26 +60,30 @@ def get_relative_path(path: Path, base: Optional[Path] = None) -> str:
         return str(path_obj)
 
 
-def detect_entrypoint(source_path: Path) -> Optional[Path]:
-    """Detect entrypoint file in source directory.
+def detect_entrypoint(source_path: Path) -> List[Path]:
+    """Detect entrypoint files in source directory.
 
     Args:
         source_path: Directory to search for entrypoint
 
     Returns:
-        Path to detected entrypoint file, or None if not found
+        List of detected entrypoint files (empty list if none found)
     """
     ENTRYPOINT_CANDIDATES = ["agent.py", "app.py", "main.py", "__main__.py"]
 
     source_dir = Path(source_path)
+    found_files = []
+
     for candidate in ENTRYPOINT_CANDIDATES:
         candidate_path = source_dir / candidate
         if candidate_path.exists():
+            found_files.append(candidate_path)
             log.debug("Detected entrypoint: %s", candidate_path)
-            return candidate_path
 
-    log.debug("No entrypoint found in %s", source_path)
-    return None
+    if not found_files:
+        log.debug("No entrypoint found in %s", source_path)
+
+    return found_files
 
 
 def detect_requirements(source_path: Path):

tests/operations/runtime/test_configure.py

@@ -2290,7 +2290,7 @@ def test_detect_entrypoint_not_found(self, tmp_path):
         empty_dir.mkdir()
 
         result = detect_entrypoint(empty_dir)
-        assert result is None
+        assert result == []
 
     def test_detect_entrypoint_finds_agent_py(self, tmp_path):
         """Test detect_entrypoint finds agent.py."""
@@ -2300,7 +2300,9 @@ def test_detect_entrypoint_finds_agent_py(self, tmp_path):
         agent_file.write_text("# agent")
 
         result = detect_entrypoint(test_dir)
-        assert result == agent_file
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert result[0] == agent_file
 
     def test_detect_entrypoint_finds_app_py(self, tmp_path):
         """Test detect_entrypoint finds app.py when agent.py doesn't exist."""
@@ -2310,7 +2312,9 @@ def test_detect_entrypoint_finds_app_py(self, tmp_path):
         app_file.write_text("# app")
 
         result = detect_entrypoint(test_dir)
-        assert result == app_file
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert result[0] == app_file
 
     def test_detect_entrypoint_finds_main_py(self, tmp_path):
         """Test detect_entrypoint finds main.py when agent.py and app.py don't exist."""
@@ -2320,10 +2324,12 @@ def test_detect_entrypoint_finds_main_py(self, tmp_path):
         main_file.write_text("# main")
 
         result = detect_entrypoint(test_dir)
-        assert result == main_file
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert result[0] == main_file
 
     def test_detect_entrypoint_priority_order(self, tmp_path):
-        """Test detect_entrypoint follows priority order: agent.py > app.py > main.py."""
+        """Test detect_entrypoint returns all matching files in priority order."""
         test_dir = tmp_path / "test"
         test_dir.mkdir()
 
@@ -2336,8 +2342,12 @@ def test_detect_entrypoint_priority_order(self, tmp_path):
         main_file.write_text("# main")
 
         result = detect_entrypoint(test_dir)
-        # Should find agent.py first (highest priority)
-        assert result == agent_file
+        # Should return all three files in priority order
+        assert isinstance(result, list)
+        assert len(result) == 3
+        assert result[0] == agent_file  # First in priority
+        assert result[1] == app_file  # Second in priority
+        assert result[2] == main_file  # Third in priority
 
     def test_infer_agent_name_with_py_extension(self, tmp_path):
         """Test infer_agent_name removes .py extension."""