feat(coderd/templatebuilder): add module rendering and agent name extraction (#26347)

> [!NOTE]
> This PR was authored by Coder Agents on behalf of @jeremyruppel.

Part 1 of DEVEX-277 (POST /api/v2/templatebuilder/compose).

Adds module rendering support and agent resource name extraction to the template builder, preparing for the compose endpoint.

- `ModuleRenderContext` and `RenderModuleTemplate` for rendering module `.tf.tmpl` files with registry URL, pinned version, agent resource name, and variable values. Nil-guards the Variables map to prevent panics.
- Extract shared `renderTemplate` with `missingkey=error` so missing variable keys fail loudly instead of producing `<no value>` in rendered HCL.
- `ExtractAgentResourceName` uses a regex to find the `coder_agent` resource name from rendered base HCL. Errors unless exactly one agent is found.
- `ModuleTemplateFS` exposes module template files from the embedded catalog, with validation that the expected `.tf.tmpl` file exists (`fs.Sub` on `embed.FS` silently succeeds for nonexistent paths).

coderd/templatebuilder/render.go

@@ -2,6 +2,9 @@ package templatebuilder
 
 import (
 	"bytes"
+	"io/fs"
+	"regexp"
+	"text/template"
 
 	"golang.org/x/xerrors"
 )
@@ -19,10 +22,29 @@ type BaseRenderContext struct {
 	Variables      map[string]string
 }
 
+// ModuleRenderContext is the data passed to module .tf.tmpl files.
+type ModuleRenderContext struct {
+	// RegistryBase is the module registry URL from the deployment config
+	// (CODER_TEMPLATE_BUILDER_REGISTRY_URL).
+	RegistryBase string
+	// PinnedVersion is the module version from the catalog manifest.
+	PinnedVersion string
+	// AgentResourceName is the Terraform resource name of the coder_agent
+	// declared in the base template (e.g. "main" or "dev").
+	AgentResourceName string
+	// Variables maps variable names to their HCL expressions.
+	Variables map[string]string
+}
+
 // RenderBaseTemplate executes a pre-parsed .tf.tmpl template for the given
 // base, applying the provided render context. Templates are parsed once at
-// startup; parse errors surface on first access rather than at render time.
+// first access via sync.OnceValues, so parse errors surface early instead
+// of at render time.
 func RenderBaseTemplate(exampleID, templatePath string, renderCtx BaseRenderContext) ([]byte, error) {
+	if renderCtx.Variables == nil {
+		renderCtx.Variables = make(map[string]string)
+	}
+
 	bases, err := loadBases()
 	if err != nil {
 		return nil, xerrors.Errorf("load base catalog: %w", err)
@@ -45,3 +67,59 @@ func RenderBaseTemplate(exampleID, templatePath string, renderCtx BaseRenderCont
 
 	return buf.Bytes(), nil
 }
+
+// RenderModuleTemplate parses and executes a module .tf.tmpl file from
+// the given filesystem, applying the provided render context.
+func RenderModuleTemplate(fsys fs.FS, templatePath string, renderCtx ModuleRenderContext) ([]byte, error) {
+	if renderCtx.Variables == nil {
+		renderCtx.Variables = make(map[string]string)
+	}
+	return renderTemplate(fsys, templatePath, renderCtx)
+}
+
+// renderTemplate is the shared implementation for module template rendering.
+// It sets missingkey=error so that references to undefined variable keys fail
+// loudly instead of producing "<no value>".
+func renderTemplate(fsys fs.FS, templatePath string, data any) ([]byte, error) {
+	raw, err := fs.ReadFile(fsys, templatePath)
+	if err != nil {
+		return nil, xerrors.Errorf("read template %s: %w", templatePath, err)
+	}
+
+	tmpl, err := template.New(templatePath).Option("missingkey=error").Parse(string(raw))
+	if err != nil {
+		return nil, xerrors.Errorf("parse template %s: %w", templatePath, err)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return nil, xerrors.Errorf("execute template %s: %w", templatePath, err)
+	}
+
+	return buf.Bytes(), nil
+}
+
+// agentResourcePattern matches `resource "coder_agent" "<name>"` in HCL.
+var agentResourcePattern = regexp.MustCompile(`resource\s+"coder_agent"\s+"(\w+)"`)
+
+// ExtractAgentResourceName finds the coder_agent resource declaration in
+// rendered HCL and returns its name. Returns an error unless exactly
+// one coder_agent resource is found; the builder only supports
+// single-agent templates. The input is expected to be rendered output
+// from our own curated base templates, not arbitrary user HCL.
+func ExtractAgentResourceName(hcl []byte) (string, error) {
+	matches := agentResourcePattern.FindAllSubmatch(hcl, -1)
+	switch len(matches) {
+	case 0:
+		return "", xerrors.New("no coder_agent resource found in rendered template")
+	case 1:
+		return string(matches[0][1]), nil
+	default:
+		names := make([]string, 0, len(matches))
+		for _, m := range matches {
+			names = append(names, string(m[1]))
+		}
+		return "", xerrors.Errorf("expected exactly one coder_agent resource, found %d: %v",
+			len(matches), names)
+	}
+}