agent-starter-pack 0.7.1__py3-none-any.whl → 0.9.0__py3-none-any.whl

src/cli/commands/list.py

@@ -0,0 +1,158 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import pathlib
+
+import click
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from ..utils.remote_template import fetch_remote_template, parse_agent_spec
+from ..utils.template import get_available_agents
+
+console = Console()
+
+
+def display_agents_from_path(base_path: pathlib.Path, source_name: str) -> None:
+    """Scans a directory and displays available agents."""
+    table = Table(
+        title=f"Available agents in [bold blue]{source_name}[/]",
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Name", style="bold")
+    table.add_column("Path", style="cyan")
+    table.add_column("Description", style="dim")
+
+    if not base_path.is_dir():
+        console.print(f"Directory not found: {base_path}", style="bold red")
+        return
+
+    found_agents = False
+    # Search for templateconfig.yaml files to identify agents
+    for config_path in sorted(base_path.glob("**/templateconfig.yaml")):
+        try:
+            with open(config_path) as f:
+                config = yaml.safe_load(f)
+
+            agent_name = config.get("name", config_path.parent.parent.name)
+            description = config.get("description", "No description.")
+
+            # Display the agent's path relative to the scanned directory
+            relative_path = config_path.parent.parent.relative_to(base_path)
+
+            table.add_row(agent_name, f"/{relative_path}", description)
+            found_agents = True
+
+        except Exception as e:
+            logging.warning(
+                f"Could not load agent from {config_path.parent.parent}: {e}"
+            )
+
+    if not found_agents:
+        console.print(f"No agents found in {source_name}", style="yellow")
+    else:
+        console.print(table)
+
+
+def list_remote_agents(remote_source: str, scan_from_root: bool = False) -> None:
+    """Lists agents from a remote source (Git URL)."""
+    spec = parse_agent_spec(remote_source)
+    if not spec:
+        console.print(f"Invalid remote source: {remote_source}", style="bold red")
+        return
+
+    console.print(f"\nFetching agents from [bold blue]{remote_source}[/]...")
+
+    try:
+        # fetch_remote_template clones the repo and returns a path to the
+        # specific template directory within the repo.
+        template_dir_path = fetch_remote_template(spec)
+
+        if scan_from_root:
+            # For ADK, we want to scan the entire repo. We need to find the
+            # root of the repo and scan from there.
+            scan_path = template_dir_path
+            while not (scan_path / ".git").exists() and scan_path.parent != scan_path:
+                scan_path = scan_path.parent
+        else:
+            # For other git repos, respect the path given in the URL.
+            scan_path = template_dir_path
+
+        display_agents_from_path(scan_path, remote_source)
+
+    except (RuntimeError, FileNotFoundError) as e:
+        console.print(f"Error: {e}", style="bold red")
+
+
+@click.command("list")
+@click.option(
+    "--adk",
+    is_flag=True,
+    help="List agents from the official google/adk-samples repository.",
+)
+@click.option(
+    "--source",
+    "-s",
+    help="List agents from a local path or a remote Git URL.",
+)
+def list_agents(adk: bool, source: str | None) -> None:
+    """
+    Lists available agent templates.
+
+    Defaults to listing built-in agents if no options are provided.
+    """
+    if adk and source:
+        console.print(
+            "Error: --adk and --source are mutually exclusive.", style="bold red"
+        )
+        return
+
+    if adk:
+        list_remote_agents("https://github.com/google/adk-samples", scan_from_root=True)
+        return
+
+    if source:
+        source_path = pathlib.Path(source)
+        if source_path.is_dir():
+            display_agents_from_path(source_path, f"local directory '{source}'")
+        elif parse_agent_spec(source):
+            list_remote_agents(source)
+        else:
+            console.print(
+                f"Error: Source '{source}' is not a valid local directory or remote URL.",
+                style="bold red",
+            )
+        return
+
+    # Default behavior: list built-in agents
+    agents = get_available_agents()
+    if not agents:
+        console.print("No built-in agents found.", style="yellow")
+        return
+
+    table = Table(
+        title="Available built-in agents",
+        show_header=True,
+        header_style="bold magenta",
+    )
+    table.add_column("Number", style="dim", width=12)
+    table.add_column("Name", style="bold")
+    table.add_column("Description")
+
+    for i, (_, agent) in enumerate(agents.items()):
+        table.add_row(str(i + 1), agent["name"], agent["description"])
+    console.print(table)

src/cli/commands/setup_cicd.py

@@ -168,8 +168,8 @@ def update_build_triggers(tf_dir: Path) -> None:
 
         # Add repository dependency to all trigger resources
         modified_content = content.replace(
-            "depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.shared_services]",
-            "depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.shared_services, google_cloudbuildv2_repository.repo]",
+            "depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]",
+            "depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services, google_cloudbuildv2_repository.repo]",
         )
 
         # Update repository reference in all triggers

src/cli/main.py

@@ -18,6 +18,7 @@ import click
 from rich.console import Console
 
 from .commands.create import create
+from .commands.list import list_agents
 from .commands.setup_cicd import setup_cicd
 from .utils import display_update_message
 
@@ -53,6 +54,7 @@ def cli() -> None:
 # Register commands
 cli.add_command(create)
 cli.add_command(setup_cicd)
+cli.add_command(list_agents, name="list")
 
 
 if __name__ == "__main__":

src/cli/utils/cicd.py

@@ -228,9 +228,9 @@ def create_github_connection(
                                 "\n🔑 Authentication Required:", style="bold yellow"
                             )
                             console.print(
-                                f"Please visit [link={action_uri}]this page[/link] to authenticate Cloud Build with GitHub:"
+                                f"Please visit [link={action_uri}][bold blue]this page[/bold blue][/link] to authenticate Cloud Build with GitHub:"
                             )
-                            console.print(f"{action_uri}", style="bold blue")
+                            print(f"\n{action_uri}\n")
                             console.print(
                                 "(Copy and paste the link into your browser if clicking doesn't work)"
                             )

src/cli/utils/remote_template.py

@@ -0,0 +1,254 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+import os
+import pathlib
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class RemoteTemplateSpec:
+    """Parsed remote template specification."""
+
+    repo_url: str
+    template_path: str
+    git_ref: str
+    is_adk_samples: bool = False
+
+
+def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
+    """Parse agent specification to determine if it's a remote template.
+
+    Args:
+        agent_spec: Agent specification string
+
+    Returns:
+        RemoteTemplateSpec if remote template, None if local template
+    """
+    # Check for local@ prefix
+    if agent_spec.startswith("local@"):
+        return None
+
+    # Check for adk@ shortcut
+    if agent_spec.startswith("adk@"):
+        sample_name = agent_spec[4:]  # Remove "adk@" prefix
+        return RemoteTemplateSpec(
+            repo_url="https://github.com/google/adk-samples",
+            template_path=f"python/agents/{sample_name}",
+            git_ref="main",
+            is_adk_samples=True,
+        )
+
+    # GitHub /tree/ URL pattern
+    tree_pattern = r"^(https?://[^/]+/[^/]+/[^/]+)/tree/([^/]+)/(.*)$"
+    match = re.match(tree_pattern, agent_spec)
+    if match:
+        repo_url = match.group(1)
+        git_ref = match.group(2)
+        template_path = match.group(3)
+        return RemoteTemplateSpec(
+            repo_url=repo_url,
+            template_path=template_path.strip("/"),
+            git_ref=git_ref,
+        )
+
+    # General remote pattern: <repo_url>[/<path>][@<ref>]
+    # Handles github.com, gitlab.com, etc.
+    remote_pattern = r"^(https?://[^/]+/[^/]+/[^/]+)(?:/(.*?))?(?:@([^/]+))?/?$"
+    match = re.match(remote_pattern, agent_spec)
+    if match:
+        repo_url = match.group(1)
+        template_path_with_ref = match.group(2) or ""
+        git_ref_from_url = match.group(3)
+
+        # Separate path and ref if ref is part of the path
+        template_path = template_path_with_ref
+        git_ref = git_ref_from_url or "main"
+
+        if "@" in template_path:
+            path_parts = template_path.split("@")
+            template_path = path_parts[0]
+            git_ref = path_parts[1]
+
+        return RemoteTemplateSpec(
+            repo_url=repo_url,
+            template_path=template_path.strip("/"),
+            git_ref=git_ref,
+        )
+
+    # GitHub shorthand: <org>/<repo>[/<path>][@<ref>]
+    github_shorthand_pattern = r"^([^/]+)/([^/]+)(?:/(.*?))?(?:@([^/]+))?/?$"
+    match = re.match(github_shorthand_pattern, agent_spec)
+    if match and "/" in agent_spec:  # Ensure it has at least one slash
+        org = match.group(1)
+        repo = match.group(2)
+        template_path = match.group(3) or ""
+        git_ref = match.group(4) or "main"
+        return RemoteTemplateSpec(
+            repo_url=f"https://github.com/{org}/{repo}",
+            template_path=template_path,
+            git_ref=git_ref,
+        )
+
+    return None
+
+
+def fetch_remote_template(spec: RemoteTemplateSpec) -> pathlib.Path:
+    """Fetch remote template and return path to template directory.
+
+    Uses Git to clone the remote repository.
+
+    Args:
+        spec: Remote template specification
+
+    Returns:
+        Path to the fetched template directory
+    """
+    temp_dir = tempfile.mkdtemp(prefix="asp_remote_template_")
+    temp_path = pathlib.Path(temp_dir)
+    repo_path = temp_path / "repo"
+
+    # Attempt Git Clone
+    try:
+        clone_url = spec.repo_url
+        clone_cmd = [
+            "git",
+            "clone",
+            "--depth",
+            "1",
+            "--branch",
+            spec.git_ref,
+            clone_url,
+            str(repo_path),
+        ]
+        logging.debug(
+            f"Attempting to clone remote template with Git: {' '.join(clone_cmd)}"
+        )
+        # GIT_TERMINAL_PROMPT=0 prevents git from prompting for credentials
+        subprocess.run(
+            clone_cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            encoding="utf-8",
+            env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+        )
+        logging.debug("Git clone successful.")
+    except subprocess.CalledProcessError as e:
+        shutil.rmtree(temp_path, ignore_errors=True)
+        raise RuntimeError(f"Git clone failed: {e.stderr.strip()}") from e
+
+    # Process the successfully fetched template
+    try:
+        if spec.template_path:
+            template_dir = repo_path / spec.template_path
+        else:
+            template_dir = repo_path
+
+        if not template_dir.exists():
+            raise FileNotFoundError(
+                f"Template path not found in the repository: {spec.template_path}"
+            )
+
+        # Exclude Makefile and README.md from remote template to avoid conflicts
+        makefile_path = template_dir / "Makefile"
+        if makefile_path.exists():
+            logging.debug(f"Removing Makefile from remote template: {makefile_path}")
+            makefile_path.unlink()
+
+        readme_path = template_dir / "README.md"
+        if readme_path.exists():
+            logging.debug(f"Removing README.md from remote template: {readme_path}")
+            readme_path.unlink()
+
+        return template_dir
+    except Exception as e:
+        # Clean up on error
+        shutil.rmtree(temp_path, ignore_errors=True)
+        raise RuntimeError(
+            f"An unexpected error occurred after fetching remote template: {e}"
+        ) from e
+
+
+def load_remote_template_config(template_dir: pathlib.Path) -> dict[str, Any]:
+    """Load template configuration from remote template.
+
+    Args:
+        template_dir: Path to template directory
+
+    Returns:
+        Template configuration dictionary
+    """
+    config_path = template_dir / ".template" / "templateconfig.yaml"
+
+    if not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path) as f:
+            config = yaml.safe_load(f)
+            return config if config else {}
+    except Exception as e:
+        logging.error(f"Error loading remote template config: {e}")
+        return {}
+
+
+def get_base_template_name(config: dict[str, Any]) -> str:
+    """Get base template name from remote template config.
+
+    Args:
+        config: Template configuration dictionary
+
+    Returns:
+        Base template name (defaults to "adk_base")
+    """
+    return config.get("base_template", "adk_base")
+
+
+def merge_template_configs(
+    base_config: dict[str, Any], remote_config: dict[str, Any]
+) -> dict[str, Any]:
+    """Merge base template config with remote template config using a deep merge.
+
+    Args:
+        base_config: Base template configuration
+        remote_config: Remote template configuration
+
+    Returns:
+        Merged configuration with remote overriding base
+    """
+    import copy
+
+    def deep_merge(d1: dict[str, Any], d2: dict[str, Any]) -> dict[str, Any]:
+        """Recursively merges d2 into d1."""
+        for k, v in d2.items():
+            if k in d1 and isinstance(d1[k], dict) and isinstance(v, dict):
+                d1[k] = deep_merge(d1[k], v)
+            else:
+                d1[k] = v
+        return d1
+
+    # Start with a deep copy of the base to avoid modifying it
+    merged_config = copy.deepcopy(base_config)
+
+    # Perform the deep merge
+    return deep_merge(merged_config, remote_config)