Add proposal for generalized template customization system

[JAORMX]

Summary

This PR introduces a comprehensive proposal for a generalized template customization system in ToolHive, addressing issue #1737.

Problem

Currently, ToolHive doesn't support specifying custom package registries (NPM, PyPI, Go proxy) when running MCP servers. This is a critical limitation for enterprise environments that use private registries.

Solution

The proposal introduces a flexible, extensible configuration system that:

• Works with all package managers (npm, pip/uv, go)
• Respects Docker's multi-stage build patterns
• Supports multiple configuration methods (profiles, CLI flags, config files)
• Keeps secrets secure (only in builder stage)
• Maintains backward compatibility

Key Features

1. Stage-Aware Configuration

• Separate configuration for builder and runtime stages
• Ensures package manager config happens before installation
• Prevents secrets from leaking to runtime images

2. Multiple Configuration Methods

# Using profiles
thv run npx://@company/tool --profile npm-private --var NPM_REGISTRY_URL=https://npm.company.com

# Building with configuration
thv build npx://@company/tool --profile npm-private --tag company/tool:latest

# Using config files
thv run npx://@company/tool --config-file .toolhive/config.yaml

3. Extensible Profile System

• Built-in profiles for common scenarios (npm-private, pypi-private, go-corporate)
• Custom profiles via configuration files
• Profile inheritance and composition

Implementation Plan

The proposal includes a detailed 5-phase implementation plan:

1. Core infrastructure (data structures, template engine)
2. Template updates (npx.tmpl, uvx.tmpl, go.tmpl)
3. CLI integration (both thv run and thv build commands)
4. Built-in profiles
5. Testing and documentation

Benefits

• For Users: Simple cases stay simple, complex requirements handled via configuration
• For Maintainers: No code changes needed for new registry types, clear separation of concerns
• Security: Proper secret handling, audit trails, network isolation

Related Issues

Fixes #1737

Documentation

The proposal document includes:

• Detailed technical design
• Code examples for implementation
• Testing strategies
• Migration path
• Security considerations

Next Steps

Once this proposal is reviewed and approved, implementation can begin following the phased approach outlined in the document.

---

Note: This proposal is designed to be implemented by an LLM, with clear structure and examples throughout.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 40.56%. Comparing base (02c003c) to head (70dd7a7).
⚠️ Report is 20 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1767   +/-   ##
=======================================
  Coverage   40.56%   40.56%           
=======================================
  Files         184      184           
  Lines       21380    21380           
=======================================
  Hits         8672     8672           
  Misses      12056    12056           
  Partials      652      652           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[eleftherias]

I like the idea of making it more generic.
What if we let users give us their own Dockerfile template?

A user also mentioned using a custom base image, which the current proposal doesn't cover. I wonder if we'll have to make the template data model so configurable that it'll end up being easier for users to just give us the Dockerfile.

[JAORMX]

@eleftherias That's the other way to go. Both have pros and cons:

This proposal is a little more complex but allows for paved paths so folks could add some needed extensions. I could probably extend it do make the base images customizable.

Allowing for folks to override the template caters for more use-cases. But we wouldn't know what folks are really doing, and thus support becomes harder to do; since there is more probability of someone not doing the right thing.

So... I'm torn. We probably could discuss this further before making a decision.

[yrobla]

one concern i have is about the security of templates, variable expansion, etc... are we thinking in some mechanism of validation/security for it?

[dmjb]

Per discussion offline: I think this proposal is too generic of a solution to the problem we need to solve. I think we should explore a model for injecting env vars into the Dockerfile.