feat: remote template lock (#344)

Author: eliasecchig

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

@@ -231,6 +231,57 @@ dependencies = [
 
 **Best Practice:** Always include a `uv.lock` file for reproducible builds.
 
+### Version Locking for Guaranteed Compatibility
+
+For maximum compatibility and stability, you can lock your remote template to a specific version of the Agent Starter Pack. This ensures that your template will always be processed with the exact version it was designed for, preventing potential breaking changes from affecting your users.
+
+**To enable version locking:**
+
+1. **Add agent-starter-pack as a dev dependency** in your `pyproject.toml`:
+   ```toml
+   [dependency-groups]
+   dev = [
+       "agent-starter-pack==0.14.1",  # Lock to specific version
+       # ... your other dev dependencies
+   ]
+   ```
+
+2. **Generate the lock file:**
+   ```bash
+   uv lock
+   ```
+
+3. **Commit both files:**
+   ```bash
+   git add pyproject.toml uv.lock
+   git commit -m "Lock agent-starter-pack version for compatibility"
+   ```
+
+**How it works:**
+- When users fetch your remote template, the starter pack automatically detects the locked version in `uv.lock`
+- It then executes `uvx agent-starter-pack==VERSION` with the locked version (requires `uv` to be installed)
+- This guarantees your template is processed with the exact version you tested it with
+
+**Requirements:**
+- Users must have `uv` installed to use version-locked templates
+- If `uv` is not available, the command will fail with installation instructions
+
+**When to use version locking:**
+- ✅ Your template uses specific starter pack features that might change
+- ✅ You want to guarantee long-term stability for your users
+- ✅ Your template is critical infrastructure that needs predictable behavior
+- ❌ You always want the latest starter pack features (trade-off: potential breaking changes)
+
+**Example user experience:**
+```bash
+uvx agent-starter-pack create my-project -a github.com/you/your-template
+
+# Output:
+# 🔒 Remote template specifies agent-starter-pack version 0.14.1 in uv.lock
+# 📦 Executing nested command: uvx agent-starter-pack==0.14.1
+# [continues with locked version]
+```
+
 ### Makefile Customization
 
 If your template includes a `Makefile`, it will be intelligently merged:

docs/remote-templates/index.md

@@ -37,9 +37,10 @@ uvx agent-starter-pack create test-agent -a https://github.com/you/your-template
 
 Remote templates work by:
 1. **Fetching** template repositories from Git
-2. **Applying** intelligent defaults based on repository structure  
-3. **Merging** template files with base agent infrastructure
-4. **Generating** complete, production-ready agent projects
+2. **Version locking** - automatically uses the exact starter pack version specified by the template for guaranteed compatibility
+3. **Applying** intelligent defaults based on repository structure  
+4. **Merging** template files with base agent infrastructure
+5. **Generating** complete, production-ready agent projects
 
 Any Git repository can become a template - the system handles the complexity automatically.
 

docs/remote-templates/using-remote-templates.md

@@ -7,9 +7,10 @@ Remote templates let you instantly create production-ready AI agents from Git re
 When you use a remote template, the system:
 
 1. **Fetches** the template repository from Git
-2. **Applies intelligent defaults** based on repository structure
-3. **Merges** template files with base agent infrastructure
-4. **Generates** a complete, production-ready agent project
+2. **Checks for version locking** - if the template specifies a starter pack version in `uv.lock`, automatically uses that version for guaranteed compatibility
+3. **Applies intelligent defaults** based on repository structure
+4. **Merges** template files with base agent infrastructure
+5. **Generates** a complete, production-ready agent project
 
 The file merging follows this priority order:
 1. Base template files (foundation)

src/cli/commands/create.py

@@ -226,6 +226,20 @@ def normalize_project_name(project_name: str) -> str:
     help="Template files directly into the current directory instead of creating a new project directory",
     default=False,
 )
+@click.option(
+    "--skip-welcome",
+    is_flag=True,
+    hidden=True,
+    help="Skip the welcome banner",
+    default=False,
+)
+@click.option(
+    "--locked",
+    is_flag=True,
+    hidden=True,
+    help="Internal flag for version-locked remote templates",
+    default=False,
+)
 @shared_template_options
 @handle_cli_error
 def create(
@@ -247,6 +261,7 @@ def create(
     agent_garden: bool = False,
     base_template: str | None = None,
     skip_welcome: bool = False,
+    locked: bool = False,
     cli_overrides: dict | None = None,
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
@@ -337,8 +352,22 @@ def create(
                     ignore=get_standard_ignore_patterns(),
                 )
 
+                # Check for version lock and execute nested command if found
+                from ..utils.remote_template import check_and_execute_with_version_lock
+
+                if check_and_execute_with_version_lock(
+                    template_source_path, agent, locked
+                ):
+                    # If we executed with locked version, cleanup and exit
+                    shutil.rmtree(temp_dir, ignore_errors=True)
+                    return
+
                 selected_agent = f"local_{template_source_path.name}"
-                console.print(f"Using local template: {local_path}")
+                if locked:
+                    # In locked mode, show a nicer message
+                    console.print("✅ Using version-locked template", style="green")
+                else:
+                    console.print(f"Using local template: {local_path}")
                 logging.debug(
                     f"Copied local template to temporary dir: {template_source_path}"
                 )
@@ -354,7 +383,7 @@ def create(
                     else:
                         console.print(f"Fetching remote template: {agent}")
                     template_source_path, temp_dir_path = fetch_remote_template(
-                        remote_spec
+                        remote_spec, agent, locked
                     )
                     temp_dir_to_clean = str(temp_dir_path)
                     selected_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
@@ -416,7 +445,7 @@ def create(
                     else:
                         console.print(f"Fetching remote template: {agent}")
                     template_source_path, temp_dir_path = fetch_remote_template(
-                        remote_spec
+                        remote_spec, agent, locked
                     )
                     temp_dir_to_clean = str(temp_dir_path)
                     final_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template

src/cli/utils/remote_template.py

@@ -28,8 +28,11 @@
 else:
     import tomli as tomllib
 from jinja2 import Environment
+from packaging import version as pkg_version
 from rich.console import Console
 
+from src.cli.utils.version import get_current_version
+
 
 @dataclass
 class RemoteTemplateSpec:
@@ -127,15 +130,113 @@ def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
     return None
 
 
+def check_and_execute_with_version_lock(
+    template_dir: pathlib.Path,
+    original_agent_spec: str | None = None,
+    locked: bool = False,
+) -> bool:
+    """Check if remote template has agent-starter-pack version lock and execute if found.
+
+    Args:
+        template_dir: Path to the fetched template directory
+        original_agent_spec: The original agent spec (remote URL) to replace with local path
+        locked: Whether this is already a locked execution (prevents recursion)
+
+    Returns:
+        True if version lock was found and executed, False otherwise
+    """
+    # Skip version locking if we're already in a locked execution (prevents recursion)
+    if locked:
+        return False
+    uv_lock_path = template_dir / "uv.lock"
+    version = parse_agent_starter_pack_version_from_lock(uv_lock_path)
+
+    if version:
+        console = Console()
+        console.print(
+            f"🔒 Remote template requires agent-starter-pack version {version}",
+            style="bold blue",
+        )
+        console.print(
+            f"📦 Switching to version {version}...",
+            style="dim",
+        )
+
+        # Reconstruct the original command but with version constraint
+        import sys
+
+        original_args = sys.argv[1:]  # Skip 'agent-starter-pack' or script name
+
+        # Add version lock specific parameters and handle remote URL replacement
+        if original_agent_spec:
+            # Replace remote agent spec with local path
+            modified_args = []
+            for arg in original_args:
+                if arg == original_agent_spec:
+                    # Replace remote URL with local template directory
+                    modified_args.append(f"local@{template_dir}")
+                else:
+                    modified_args.append(arg)
+            original_args = modified_args
+
+        # Add version lock flags only for ASP versions 0.14.1 and above
+        current_version = get_current_version()
+        if pkg_version.parse(current_version) > pkg_version.parse("0.14.1"):
+            original_args.extend(["--skip-welcome", "--locked"])
+
+        try:
+            # Check if uvx is available
+            subprocess.run(["uvx", "--version"], capture_output=True, check=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            console.print(
+                f"❌ Remote template requires agent-starter-pack version {version}, but 'uvx' is not installed",
+                style="bold red",
+            )
+            console.print(
+                "💡 Install uv to use version-locked remote templates:",
+                style="bold blue",
+            )
+            console.print("   curl -LsSf https://astral.sh/uv/install.sh | sh")
+            console.print(
+                "   OR visit: https://docs.astral.sh/uv/getting-started/installation/"
+            )
+            sys.exit(1)
+
+        try:
+            # Execute uvx with the locked version
+            cmd = ["uvx", f"agent-starter-pack=={version}", *original_args]
+            logging.debug(f"Executing nested command: {' '.join(cmd)}")
+            subprocess.run(cmd, check=True)
+            return True
+
+        except subprocess.CalledProcessError as e:
+            console.print(
+                f"❌ Failed to execute with locked version {version}: {e}",
+                style="bold red",
+            )
+            console.print(
+                "⚠️  Continuing with current version, but compatibility is not guaranteed",
+                style="yellow",
+            )
+            # Continue with current execution instead of failing completely
+
+    return False
+
+
 def fetch_remote_template(
     spec: RemoteTemplateSpec,
+    original_agent_spec: str | None = None,
+    locked: bool = False,
 ) -> tuple[pathlib.Path, pathlib.Path]:
     """Fetch remote template and return path to template directory.
 
-    Uses Git to clone the remote repository.
+    Uses Git to clone the remote repository. If the template contains a uv.lock
+    with agent-starter-pack version constraint, will execute nested uvx command.
 
     Args:
         spec: Remote template specification
+        original_agent_spec: Original agent spec string (used to prevent recursion)
+        locked: Whether this is already a locked execution (prevents recursion)
 
     Returns:
         A tuple containing:
@@ -188,6 +289,16 @@ def fetch_remote_template(
                 f"Template path not found in the repository: {spec.template_path}"
             )
 
+        # Check for version lock and execute nested command if found
+        if check_and_execute_with_version_lock(
+            template_dir, original_agent_spec, locked
+        ):
+            # If we executed with locked version, the nested process will handle everything
+            # Clean up and exit successfully
+            shutil.rmtree(temp_path, ignore_errors=True)
+            # Exit with success since the nested command will handle the rest
+            sys.exit(0)
+
         return template_dir, temp_path
     except Exception as e:
         # Clean up on error
@@ -458,6 +569,41 @@ def display_adk_caveat_if_needed(agents: dict[int, dict[str, Any]]) -> None:
         )
 
 
+def parse_agent_starter_pack_version_from_lock(
+    uv_lock_path: pathlib.Path,
+) -> str | None:
+    """Parse agent-starter-pack version from uv.lock file.
+
+    Args:
+        uv_lock_path: Path to uv.lock file
+
+    Returns:
+        Version string if found, None otherwise
+    """
+    if not uv_lock_path.exists():
+        return None
+
+    try:
+        with open(uv_lock_path, "rb") as f:
+            lock_data = tomllib.load(f)
+
+        # Look for agent-starter-pack in the packages section
+        packages = lock_data.get("package", [])
+        for package in packages:
+            if package.get("name") == "agent-starter-pack":
+                version = package.get("version")
+                if version:
+                    logging.debug(
+                        f"Found agent-starter-pack version {version} in uv.lock"
+                    )
+                    return version
+
+    except Exception as e:
+        logging.warning(f"Error parsing uv.lock file {uv_lock_path}: {e}")
+
+    return None
+
+
 def render_and_merge_makefiles(
     base_template_path: pathlib.Path,
     final_destination: pathlib.Path,