fix: introduce example pyproject for enhance (#287)

Author: eliasecchig

docs/remote-templates/creating-remote-templates.md

@@ -9,6 +9,8 @@ When creating a remote template, you need to consider:
 ### Dependencies (`pyproject.toml`)
 **Required for custom dependencies:** If your agent has custom Python dependencies, you **must** include a `pyproject.toml` file at the template root with those dependencies listed.
 
+For guidance on the structure and content of your `pyproject.toml`, you can reference the [base template pyproject.toml](https://github.com/GoogleCloudPlatform/agent-starter-pack/blob/main/src/base_template/pyproject.toml) as an example of the expected format and common dependencies.
+
 ### Configuration (`[tool.agent-starter-pack]`)
 **Optional but recommended:** Add this section to your `pyproject.toml` for:
 - **Discoverability:** Templates with this section appear in `uvx agent-starter-pack list` commands

src/cli/utils/template.py

@@ -705,89 +705,93 @@ def process_template(
                     for item in generated_project_dir.iterdir():
                         dest_item = final_destination / item.name
 
-                        # Special handling for README files - use base template README if conflict exists
+                        # Special handling for README files - always preserve existing README
+                        # Special handling for pyproject.toml files - only preserve for in-folder updates
+                        should_preserve_file = item.name.lower().startswith(
+                            "readme"
+                        ) or (item.name == "pyproject.toml" and in_folder)
                         if (
-                            item.name.lower().startswith("readme")
+                            should_preserve_file
                             and (final_destination / item.name).exists()
                         ):
-                            # The existing README stays, use base template README with starter_pack prefix
+                            # The existing file stays, use base template file with starter_pack prefix
                             base_name = item.stem
                             extension = item.suffix
                             dest_item = (
                                 final_destination
                                 / f"starter_pack_{base_name}{extension}"
                             )
 
-                            # Try to use base template README instead of templated README
-                            base_readme = base_template_path / item.name
-                            if base_readme.exists():
+                            # Try to use base template file instead of templated file
+                            base_file = base_template_path / item.name
+                            if base_file.exists():
                                 logging.debug(
-                                    f"README conflict: preserving existing {item.name}, using base template README as starter_pack_{base_name}{extension}"
+                                    f"{item.name} conflict: preserving existing {item.name}, using base template {item.name} as starter_pack_{base_name}{extension}"
                                 )
-                                # Process the base template README through cookiecutter
+                                # Process the base template file through cookiecutter
                                 try:
                                     import tempfile as tmp_module
 
                                     with (
-                                        tmp_module.TemporaryDirectory() as temp_readme_dir
+                                        tmp_module.TemporaryDirectory() as temp_file_dir
                                     ):
-                                        temp_readme_path = pathlib.Path(temp_readme_dir)
+                                        temp_file_path = pathlib.Path(temp_file_dir)
 
-                                        # Create a minimal cookiecutter structure for just the README
-                                        readme_template_dir = (
-                                            temp_readme_path / "readme_template"
+                                        # Create a minimal cookiecutter structure for just the file
+                                        file_template_dir = (
+                                            temp_file_path / "file_template"
                                         )
-                                        readme_template_dir.mkdir()
-                                        readme_project_dir = (
-                                            readme_template_dir
+                                        file_template_dir.mkdir()
+                                        file_project_dir = (
+                                            file_template_dir
                                             / "{{cookiecutter.project_name}}"
                                         )
-                                        readme_project_dir.mkdir()
+                                        file_project_dir.mkdir()
 
-                                        # Copy base README to template structure
+                                        # Copy base file to template structure
                                         shutil.copy2(
-                                            base_readme, readme_project_dir / item.name
+                                            base_file, file_project_dir / item.name
                                         )
 
                                         # Create cookiecutter.json with same config as main template
                                         with open(
-                                            readme_template_dir / "cookiecutter.json",
+                                            file_template_dir / "cookiecutter.json",
                                             "w",
                                             encoding="utf-8",
                                         ) as f:
                                             json.dump(cookiecutter_config, f, indent=4)
 
-                                        # Process the README template
+                                        # Process the file template
                                         cookiecutter(
-                                            str(readme_template_dir),
+                                            str(file_template_dir),
                                             no_input=True,
                                             overwrite_if_exists=True,
-                                            output_dir=str(temp_readme_path),
+                                            output_dir=str(temp_file_path),
                                             extra_context={
                                                 "project_name": project_name,
                                                 "agent_name": agent_name,
                                             },
                                         )
 
-                                        # Copy the processed README
-                                        processed_readme = (
-                                            temp_readme_path / project_name / item.name
+                                        # Copy the processed file
+                                        processed_file = (
+                                            temp_file_path / project_name / item.name
                                         )
-                                        if processed_readme.exists():
-                                            shutil.copy2(processed_readme, dest_item)
+                                        if processed_file.exists():
+                                            shutil.copy2(processed_file, dest_item)
                                         else:
                                             # Fallback to original behavior if processing fails
                                             shutil.copy2(item, dest_item)
 
                                 except Exception as e:
                                     logging.warning(
-                                        f"Failed to process base template README: {e}. Using templated README instead."
+                                        f"Failed to process base template {item.name}: {e}. Using templated {item.name} instead."
                                     )
                                     shutil.copy2(item, dest_item)
                             else:
-                                # Fallback to original behavior if base README doesn't exist
+                                # Fallback to original behavior if base file doesn't exist
                                 logging.debug(
-                                    f"README conflict: preserving existing {item.name}, saving templated README as starter_pack_{base_name}{extension}"
+                                    f"{item.name} conflict: preserving existing {item.name}, saving templated {item.name} as starter_pack_{base_name}{extension}"
                                 )
                                 shutil.copy2(item, dest_item)
                         else:

tests/cli/commands/test_create_local.py

@@ -181,12 +181,107 @@ def test_parse_agent_spec_ignores_local_prefix() -> None:
     assert spec is None
 
 
-def test_readme_conflict_handling_logic(tmp_path: pathlib.Path) -> None:
-    """Test the basic README conflict detection logic (simplified version).
+def test_readme_and_pyproject_conflict_handling_in_folder_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Test conflict handling for in-folder updates - both README and pyproject.toml should be preserved."""
+    import shutil
+
+    # Set up directories
+    final_destination = tmp_path / "destination"
+    final_destination.mkdir(parents=True)
+    generated_project_dir = tmp_path / "generated"
+    generated_project_dir.mkdir(parents=True)
+
+    # Create existing README in destination
+    existing_readme_content = (
+        "# Existing Project\n\nThis is my existing README content."
+    )
+    (final_destination / "README.md").write_text(existing_readme_content)
+
+    # Create existing pyproject.toml in destination
+    existing_pyproject_content = """[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "existing-project"
+version = "0.1.0"
+"""
+    (final_destination / "pyproject.toml").write_text(existing_pyproject_content)
+
+    # Create templated README in generated project
+    templated_readme_content = "# Test Project\n\nThis is the templated README content."
+    (generated_project_dir / "README.md").write_text(templated_readme_content)
+
+    # Create templated pyproject.toml in generated project
+    templated_pyproject_content = """[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "templated-project"
+version = "0.1.0"
+"""
+    (generated_project_dir / "pyproject.toml").write_text(templated_pyproject_content)
+
+    # Also create a non-conflicting file
+    (generated_project_dir / "other_file.py").write_text("# Other file content")
+
+    # Simulate the in-folder copying logic from process_template (in_folder=True)
+    in_folder = True
+    for item in generated_project_dir.iterdir():
+        dest_item = final_destination / item.name
+
+        # Use the same logic as the updated process_template function
+        should_preserve_file = item.name.lower().startswith("readme") or (
+            item.name == "pyproject.toml" and in_folder
+        )
+        if should_preserve_file and (final_destination / item.name).exists():
+            # The existing file stays, save the templated one with a different name
+            base_name = item.stem
+            extension = item.suffix
+            dest_item = final_destination / f"starter_pack_{base_name}{extension}"
+
+        if item.is_dir():
+            if dest_item.exists():
+                shutil.rmtree(dest_item)
+            shutil.copytree(item, dest_item, dirs_exist_ok=True)
+        else:
+            shutil.copy2(item, dest_item)
+
+    # Verify results
+    original_readme = final_destination / "README.md"
+    templated_readme = final_destination / "starter_pack_README.md"
+    original_pyproject = final_destination / "pyproject.toml"
+    templated_pyproject = final_destination / "starter_pack_pyproject.toml"
+    other_file = final_destination / "other_file.py"
+
+    # Original README should be preserved with original content
+    assert original_readme.exists()
+    assert original_readme.read_text() == existing_readme_content
+
+    # Templated README should be saved with new name
+    assert templated_readme.exists()
+    assert templated_readme.read_text() == templated_readme_content
+
+    # Original pyproject.toml should be preserved with original content (in-folder mode)
+    assert original_pyproject.exists()
+    assert original_pyproject.read_text() == existing_pyproject_content
+
+    # Templated pyproject.toml should be saved with new name (in-folder mode)
+    assert templated_pyproject.exists()
+    assert templated_pyproject.read_text() == templated_pyproject_content
 
-    Note: This tests the conflict detection pattern, but the actual process_template
-    function now uses base template README instead of templated README when conflicts occur.
-    """
+    # Other files should copy normally
+    assert other_file.exists()
+    assert other_file.read_text() == "# Other file content"
+
+
+def test_readme_and_pyproject_conflict_handling_remote_template_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Test conflict handling for remote templates - README preserved, pyproject.toml should be overwritten."""
     import shutil
 
     # Set up directories
@@ -201,23 +296,46 @@ def test_readme_conflict_handling_logic(tmp_path: pathlib.Path) -> None:
     )
     (final_destination / "README.md").write_text(existing_readme_content)
 
+    # Create existing pyproject.toml in destination
+    existing_pyproject_content = """[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "existing-project"
+version = "0.1.0"
+"""
+    (final_destination / "pyproject.toml").write_text(existing_pyproject_content)
+
     # Create templated README in generated project
     templated_readme_content = "# Test Project\n\nThis is the templated README content."
     (generated_project_dir / "README.md").write_text(templated_readme_content)
 
+    # Create templated pyproject.toml in generated project
+    templated_pyproject_content = """[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "templated-project"
+version = "0.1.0"
+"""
+    (generated_project_dir / "pyproject.toml").write_text(templated_pyproject_content)
+
     # Also create a non-conflicting file
     (generated_project_dir / "other_file.py").write_text("# Other file content")
 
-    # Simulate the in-folder copying logic from process_template
+    # Simulate the remote template copying logic from process_template (in_folder=False)
+    in_folder = False
     for item in generated_project_dir.iterdir():
         dest_item = final_destination / item.name
 
-        # Special handling for README files - rename templated README if conflict exists
-        if (
-            item.name.lower().startswith("readme")
-            and (final_destination / item.name).exists()
-        ):
-            # The existing README stays, save the templated one with a different name
+        # Use the same logic as the updated process_template function
+        should_preserve_file = item.name.lower().startswith("readme") or (
+            item.name == "pyproject.toml" and in_folder
+        )
+        if should_preserve_file and (final_destination / item.name).exists():
+            # The existing file stays, save the templated one with a different name
             base_name = item.stem
             extension = item.suffix
             dest_item = final_destination / f"starter_pack_{base_name}{extension}"
@@ -232,6 +350,8 @@ def test_readme_conflict_handling_logic(tmp_path: pathlib.Path) -> None:
     # Verify results
     original_readme = final_destination / "README.md"
     templated_readme = final_destination / "starter_pack_README.md"
+    pyproject_file = final_destination / "pyproject.toml"
+    templated_pyproject_backup = final_destination / "starter_pack_pyproject.toml"
     other_file = final_destination / "other_file.py"
 
     # Original README should be preserved with original content
@@ -242,6 +362,13 @@ def test_readme_conflict_handling_logic(tmp_path: pathlib.Path) -> None:
     assert templated_readme.exists()
     assert templated_readme.read_text() == templated_readme_content
 
+    # pyproject.toml should be overwritten with templated content (remote template mode)
+    assert pyproject_file.exists()
+    assert pyproject_file.read_text() == templated_pyproject_content
+
+    # No backup pyproject.toml should exist (remote template mode)
+    assert not templated_pyproject_backup.exists()
+
     # Other files should copy normally
     assert other_file.exists()
     assert other_file.read_text() == "# Other file content"