Struct TemplateContextBuilder 

pub struct TemplateContextBuilder { /* private fields */ }

Template context builder for AGPM resource installation.

This struct is responsible for building the template context that will be available to Markdown templates during rendering. It collects data from the manifest, lockfile, and current resource being processed.

Context Structure

The built context follows this structure:

{
  "agpm": {
    "resource": {
      "type": "agent",
      "name": "example-agent",
      "install_path": ".claude/agents/example.md",
      "source": "community",
      "version": "v1.0.0",
      "resolved_commit": "abc123...",
      "checksum": "sha256:...",
      "path": "agents/example.md"
    },
    "deps": {
      "agents": {
        "helper": {
          "install_path": ".claude/agents/helper.md",
          "version": "v1.0.0",
          "resolved_commit": "def456...",
          "checksum": "sha256:...",
          "source": "community",
          "path": "agents/helper.md"
        }
      },
      "snippets": { ... },
      "commands": { ... }
    }
  }
}

Implementations

impl TemplateContextBuilder

pub fn new( lockfile: Arc<LockFile>, project_config: Option<ProjectConfig>, cache: Arc<Cache>, project_dir: PathBuf, ) -> Self

Create a new template context builder.

Arguments

• lockfile - The resolved lockfile, wrapped in Arc for efficient sharing
• project_config - Optional project-specific template variables from the manifest
• cache - Cache instance for reading source files during content extraction
• project_dir - Project root directory for resolving local file paths

pub fn clear_render_cache(&self)

Clear the render cache.

Should be called after installation completes to free memory and ensure next installation starts with a fresh cache.

pub fn clear_custom_names_cache(&self)

Clear the custom names cache.

Should be called after installation completes to free memory and ensure next installation starts with a fresh cache.

pub fn clear_dependency_specs_cache(&self)

Clear the dependency specs cache.

Should be called after installation completes to free memory and ensure next installation starts with a fresh cache.

pub fn render_cache_stats(&self) -> Option<(usize, usize, f64)>

Get render cache statistics.

Returns (hits, misses, hit_rate) where hit_rate is a percentage.

pub async fn build_context( &self, resource_id: &ResourceId, variant_inputs: &Value, ) -> Result<(TeraContext, Option<String>)>

Build the complete template context for a specific resource.

Arguments

• resource_name - Name of the resource being rendered
• resource_type - Type of the resource (agents, snippets, etc.)
• template_vars_override - Optional template variable overrides for this specific resource. Overrides are deep-merged into the base context, preserving unmodified fields.

Returns

Returns a Tera Context containing all available template variables.

Template Variable Override Behavior

When template_vars_override is provided, it is deep-merged into the base template context:

• Objects: Recursively merged, preserving fields not present in override
• Primitives/Arrays: Completely replaced by override value
• Null values: Replace existing value with JSON null (may cause template errors)
• Empty objects: No-op (no changes applied)

Special handling for project namespace: Updates both agpm.project (canonical) and top-level project (convenience alias) to maintain consistency.

Examples

// Base context has project.name = "agpm" and project.language = "rust"
let overrides = json!({
    "project": {
        "language": "python",  // Replaces existing value
        "framework": "fastapi" // Adds new field
    }
});

use agpm_cli::lockfile::ResourceId;
use agpm_cli::utils::compute_variant_inputs_hash;
// Create ResourceId with template_vars and ResourceType included
let variant_hash = compute_variant_inputs_hash(&overrides).unwrap_or_default();
let resource_id = ResourceId::new("agent", None::<String>, Some("claude-code"), ResourceType::Agent, variant_hash);
let (context, _context_checksum) = builder
    .build_context(&resource_id, &overrides)
    .await?;

// Result: project.name preserved, language replaced, framework added

pub fn compute_context_digest(&self) -> Result<String>

Compute a stable digest of the template context data.

This method creates a deterministic hash of all lockfile metadata that could affect template rendering. The digest is used as part of the cache key to ensure that changes to dependency versions or metadata properly invalidate the cache.

Returns

Returns a hex-encoded string containing the first 16 characters of the SHA-256 hash of the serialized template context data. This is sufficient to uniquely identify context changes while keeping the digest compact.

What’s Included

The digest includes all lockfile metadata that affects rendering:

• Resource names, types, and installation paths
• Dependency versions and resolved commits
• Checksums and source information

Determinism

The hash is stable across runs because:

• Resources are sorted by type and name before hashing
• JSON serialization uses consistent ordering (BTreeMap)
• Only metadata fields that affect rendering are included

Examples

use agpm_cli::templating::TemplateContextBuilder;
use agpm_cli::lockfile::LockFile;
use std::path::{Path, PathBuf};
use std::sync::Arc;

let lockfile = LockFile::load(Path::new("agpm.lock"))?;
let cache = Arc::new(agpm_cli::cache::Cache::new()?);
let project_dir = std::env::current_dir()?;
let builder = TemplateContextBuilder::new(
    Arc::new(lockfile),
    None,
    cache,
    project_dir
);

let digest = builder.compute_context_digest()?;
println!("Template context digest: {}", digest);