feat: Add OCI artifact support for runtime configurations sharing

[JAORMX]

This commit implements comprehensive OCI artifact support for exporting and importing
runtime configurations, enabling users to store and share ToolHive configurations
as OCI artifacts in container registries. The implementation follows clean architecture
principles with proper separation of concerns.

Key Features

• Export to OCI: Export runtime configurations as OCI artifacts to registries
• Import from OCI: Automatically detect and load OCI runtime configuration artifacts
• Registry-Only Operations: OCI artifacts stored exclusively in registries (no local daemon)
• Automatic Detection: Smart detection of OCI references vs file paths

CLI Enhancements

• Extended thv export to support both file paths and OCI references

• Automatic detection of OCI references vs file paths

• Maintained backward compatibility with existing file-based exports

• Clear messaging: "to file" vs "to OCI registry"

• Modified thv run to automatically detect OCI runtime configuration artifacts

• Graceful fallback when OCI references aren't runtime config artifacts

• Seamless integration with existing container image and registry workflows

Architecture & Code Organization

Clean Separation of Concerns

• pkg/oci/ - General OCI registry operations and utilities

  • client.go: Generic OCI client with authentication
  • utils.go: Reference validation, tag extraction, utilities
  • Reusable across different artifact types

• pkg/runner/export/ - RunConfig-specific export/import operations

  • oci.go: Specialized OCI operations for runtime configurations
  • Custom media types and annotations for RunConfig artifacts
  • ORAS-based push/pull operations

Key Components

• OCI Client (pkg/oci/client.go):

  • CreateRepository(): Authenticated ORAS repository clients
  • Authentication bridge using existing keychain infrastructure
  • Generic, reusable for any OCI artifact operations

• OCI Utilities (pkg/oci/utils.go):

  • ValidateReference(): OCI reference validation
  • IsOCIReference(): Smart detection of OCI vs file references
  • ExtractTag(): Tag parsing utilities

• RunConfig Exporter (pkg/runner/export/oci.go):

  • PushRunConfig(): Push runtime configurations to registries
  • PullRunConfig(): Pull runtime configurations from registries
  • Custom media types: application/vnd.toolhive.runconfig.v1+json
  • Proper OCI annotations (creation time, version, description)

Implementation Details

Registry-Only Architecture

Following ORAS best practices, OCI artifacts are stored exclusively in registries:

• No local daemon storage for OCI artifacts
• Direct registry operations using ORAS
• Simplified architecture: OCI reference → registry, file path → local file

Authentication & Security

• Leverages existing go-containerregistry keychain infrastructure
• Secure handling of registry credentials
• Proper validation of OCI references and artifacts
• Input validation for all new parameters

Error Handling & User Experience

• Authentication Errors: Proper detection and reporting of auth failures
• Network Errors: Distinction between network issues and artifact problems
• Artifact Type Errors: Graceful handling when OCI refs aren't runtime configs
• Clear error messages for different failure scenarios
• Automatic fallback behavior for ambiguous references

Updated Components

• Export Command (cmd/thv/app/export.go):

  • Support for OCI references alongside file paths
  • Early validation using oci.ValidateReference()
  • Improved error handling and user messaging

• Run Command (cmd/thv/app/run.go):

  • Updated help text to document OCI runtime configuration support
  • Integration with retriever for automatic OCI artifact detection

• Retriever (pkg/runner/retriever/retriever.go):

  • Enhanced GetMCPServer() to try OCI artifacts before container images
  • Intelligent error handling to distinguish artifact types
  • Graceful fallback for non-runtime-config OCI references

• Run Flags (cmd/thv/app/run_flags.go):

  • Modified BuildRunnerConfig() to detect OCI runtime configurations
  • Seamless integration with existing configuration loading

Usage Examples

# Export to file (existing functionality)
thv export my-server ./config.json

# Export to OCI registry (new functionality)
thv export my-server registry.example.com/configs/my-server:latest

# Run from OCI artifact (new functionality)
thv run registry.example.com/configs/my-server:latest

# Run regular container image (existing functionality)
thv run registry.example.com/regular-image:latest

Dependencies & Technology

• Added oras.land/oras-go/v2 for OCI artifact operations
• Leveraged existing github.com/google/go-containerregistry for reference validation
• Clean integration with existing authentication infrastructure

Testing & Quality

• Comprehensive Test Coverage:

  • OCI package tests for general operations
  • Export package tests for RunConfig-specific functionality
  • Retriever tests for OCI artifact detection and loading
  • Integration tests for end-to-end workflows

• Code Quality:

  • All linting issues resolved
  • Proper error handling and logging
  • Clean separation of concerns
  • Comprehensive documentation

Documentation

• Updated CLI help text for thv export and thv run commands
• Updated documentation files (docs/cli/thv_export.md, docs/cli/thv.md)
• Added comprehensive examples and usage patterns

Backward Compatibility

• All existing functionality remains unchanged
• File-based export/import continues to work as before
• No breaking changes to existing CLI interfaces
• Graceful degradation when OCI features are not available

This implementation extends ToolHive's capabilities while maintaining its core principles
of simplicity, security, and reliability. The clean architecture ensures the codebase
remains maintainable and extensible for future OCI artifact types.

Signed-off-by: Juan Antonio Osorio ozz@stacklok.com