feat: Add OCI artifact support for runtime configurations with clean architecture

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.

- **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

- 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

- **`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

- **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)

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

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

- **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

- **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

```bash
thv export my-server ./config.json

thv export my-server registry.example.com/configs/my-server:latest
```

```bash
thv run registry.example.com/configs/my-server:latest

thv run registry.example.com/regular-image:latest
```

- 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

- **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

- 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

- 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>

Author: JAORMX

cmd/thv/app/export.go

@@ -1,46 +1,93 @@
 package app
 
 import (
+	"context"
 	"fmt"
 	"os"
 	"path/filepath"
 
 	"github.com/spf13/cobra"
 
+	"github.com/stacklok/toolhive/pkg/container/images"
+	"github.com/stacklok/toolhive/pkg/oci"
 	"github.com/stacklok/toolhive/pkg/runner"
+	"github.com/stacklok/toolhive/pkg/runner/export"
 )
 
 func newExportCmd() *cobra.Command {
-	return &cobra.Command{
-		Use:   "export <workload name> <path>",
-		Short: "Export a workload's run configuration to a file",
-		Long: `Export a workload's run configuration to a file for sharing or backup.
+	cmd := &cobra.Command{
+		Use:   "export <workload name> <path|oci-reference>",
+		Short: "Export a workload's run configuration to a file or OCI artifact",
+		Long: `Export a workload's run configuration to a file or OCI artifact for sharing or backup.
 
-	The exported configuration can be used with 'thv run --from-config <path>' to recreate
-	the same workload with identical settings.
+	The exported configuration can be used with 'thv run --from-config <path>' or
+	'thv run --from-config <oci-reference>' to recreate the same workload with identical settings.
+
+	When exporting to an OCI reference, the artifact is pushed to the remote registry.
+	When exporting to a file path, the configuration is saved as a JSON file.
 
 	Examples:
 	# Export a workload configuration to a file
 	thv export my-server ./my-server-config.json
 
 	# Export to a specific directory
-	thv export github-mcp /tmp/configs/github-config.json`,
+	thv export github-mcp /tmp/configs/github-config.json
+
+	# Export to an OCI artifact (pushes to registry)
+	thv export my-server registry.example.com/configs/my-server:latest`,
 		Args: cobra.ExactArgs(2),
 		RunE: exportCmdFunc,
 	}
+
+	return cmd
 }
 
 func exportCmdFunc(cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
 	workloadName := args[0]
-	outputPath := args[1]
+	destination := args[1]
 
 	// Load the saved run configuration
 	runnerInstance, err := runner.LoadState(ctx, workloadName)
 	if err != nil {
 		return fmt.Errorf("failed to load run configuration for workload '%s': %w", workloadName, err)
 	}
 
+	// Determine if destination is an OCI reference or file path
+	if oci.IsOCIReference(destination) {
+		return exportToOCI(ctx, runnerInstance.Config, workloadName, destination)
+	}
+
+	return exportToFile(runnerInstance.Config, workloadName, destination)
+}
+
+// exportToOCI exports the configuration to an OCI artifact
+func exportToOCI(ctx context.Context, config *runner.RunConfig, workloadName, ref string) error {
+	// Validate the OCI reference early
+	if err := oci.ValidateReference(ref); err != nil {
+		return fmt.Errorf("invalid OCI reference: %w", err)
+	}
+
+	imageManager := images.NewImageManager(ctx)
+	ociClient := oci.NewClient(imageManager)
+	exporter := export.NewOCIExporter(ociClient)
+
+	// Push directly to registry (no local storage for OCI artifacts)
+	if err := exporter.PushRunConfig(ctx, config, ref); err != nil {
+		return fmt.Errorf("failed to push configuration to OCI registry: %w", err)
+	}
+	fmt.Printf("Successfully exported run configuration for '%s' to OCI registry '%s'\n", workloadName, ref)
+
+	return nil
+}
+
+// exportToFile exports the configuration to a local file
+func exportToFile(config *runner.RunConfig, workloadName, outputPath string) error {
+	// Validate input
+	if config == nil {
+		return fmt.Errorf("configuration cannot be nil")
+	}
+
 	// Ensure the output directory exists
 	outputDir := filepath.Dir(outputPath)
 	if err := os.MkdirAll(outputDir, 0750); err != nil {
@@ -56,10 +103,10 @@ func exportCmdFunc(cmd *cobra.Command, args []string) error {
 	defer outputFile.Close()
 
 	// Write the configuration to the file
-	if err := runnerInstance.Config.WriteJSON(outputFile); err != nil {
+	if err := config.WriteJSON(outputFile); err != nil {
 		return fmt.Errorf("failed to write configuration to file: %w", err)
 	}
 
-	fmt.Printf("Successfully exported run configuration for '%s' to '%s'\n", workloadName, outputPath)
+	fmt.Printf("Successfully exported run configuration for '%s' to file '%s'\n", workloadName, outputPath)
 	return nil
 }

cmd/thv/app/export_test.go

@@ -0,0 +1,32 @@
+package app
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/stacklok/toolhive/pkg/runner"
+)
+
+func TestExportToFile_InvalidPath(t *testing.T) {
+	t.Parallel()
+
+	// Create a valid config for testing
+	config := &runner.RunConfig{
+		Name:  "test-config",
+		Image: "test-image:latest",
+	}
+
+	// Test with invalid directory path
+	err := exportToFile(config, "test", "/invalid/path/that/does/not/exist/config.json")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to create output directory")
+}
+
+func TestExportToFile_NilConfig(t *testing.T) {
+	t.Parallel()
+
+	// Test with nil config
+	err := exportToFile(nil, "test", "/tmp/test-config.json")
+	assert.Error(t, err)
+}

cmd/thv/app/run.go

@@ -24,7 +24,7 @@ var runCmd = &cobra.Command{
 	Short: "Run an MCP server",
 	Long: `Run an MCP server with the specified name, image, or protocol scheme.
 
-ToolHive supports four ways to run an MCP server:
+ToolHive supports five ways to run an MCP server:
 
 1. From the registry:
    $ thv run server-name [-- args...]
@@ -45,7 +45,12 @@ ToolHive supports four ways to run an MCP server:
    or go (Golang). For Go, you can also specify local paths starting
    with './' or '../' to build and run local Go projects.
 
-4. From an exported configuration:
+4. From an OCI runtime configuration artifact:
+   $ thv run registry.example.com/configs/my-server:latest
+   Runs an MCP server using a runtime configuration stored as an OCI artifact.
+   The system automatically detects and loads the configuration.
+
+5. From an exported configuration:
    $ thv run --from-config <path>
    Runs an MCP server using a previously exported configuration file.
 

cmd/thv/app/run_flags.go

@@ -8,10 +8,14 @@ import (
 
 	cfg "github.com/stacklok/toolhive/pkg/config"
 	"github.com/stacklok/toolhive/pkg/container"
+	"github.com/stacklok/toolhive/pkg/container/images"
 	"github.com/stacklok/toolhive/pkg/container/runtime"
+	"github.com/stacklok/toolhive/pkg/logger"
+	"github.com/stacklok/toolhive/pkg/oci"
 	"github.com/stacklok/toolhive/pkg/process"
 	"github.com/stacklok/toolhive/pkg/registry"
 	"github.com/stacklok/toolhive/pkg/runner"
+	"github.com/stacklok/toolhive/pkg/runner/export"
 	"github.com/stacklok/toolhive/pkg/runner/retriever"
 	"github.com/stacklok/toolhive/pkg/transport"
 	"github.com/stacklok/toolhive/pkg/transport/types"
@@ -317,3 +321,59 @@ func getTelemetryFromFlags(cmd *cobra.Command, config *cfg.Config, otelEndpoint
 
 	return finalOtelEndpoint, finalOtelSamplingRate, finalOtelEnvironmentVariables
 }
+
+// isOCIRuntimeConfigArtifact checks if the serverOrImage is an OCI runtime configuration artifact
+func isOCIRuntimeConfigArtifact(ctx context.Context, serverOrImage string) bool {
+	// Try to parse as OCI reference first
+	if !oci.IsOCIReference(serverOrImage) {
+		return false
+	}
+
+	// Try to load as runtime configuration
+	imageManager := images.NewImageManager(ctx)
+	ociClient := oci.NewClient(imageManager)
+	exporter := export.NewOCIExporter(ociClient)
+	_, err := exporter.PullRunConfig(ctx, serverOrImage)
+	return err == nil
+}
+
+// loadAndMergeOCIRunConfig loads a runtime configuration from OCI and merges with command-line flags
+func loadAndMergeOCIRunConfig(ctx context.Context, ref string, flags *RunFlags, debugMode bool) (*runner.RunConfig, error) {
+	// Load the runtime configuration from OCI
+	imageManager := images.NewImageManager(ctx)
+	ociClient := oci.NewClient(imageManager)
+	exporter := export.NewOCIExporter(ociClient)
+	ociConfig, err := exporter.PullRunConfig(ctx, ref)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load runtime configuration from OCI artifact: %w", err)
+	}
+
+	// Create container runtime
+	rt, err := container.NewFactory().Create(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create container runtime: %v", err)
+	}
+
+	// Set the runtime in the config
+	ociConfig.Deployer = rt
+
+	// Override with any command-line flags that were explicitly set
+	// This allows users to override specific settings from the OCI config
+	if flags.Name != "" {
+		ociConfig.Name = flags.Name
+	}
+	if flags.Host != "" {
+		ociConfig.Host = flags.Host
+	}
+	if flags.ProxyPort != 0 {
+		ociConfig.Port = flags.ProxyPort
+	}
+	if debugMode {
+		ociConfig.Debug = true
+	}
+
+	logger.Infof("Successfully loaded runtime configuration from OCI artifact: %s", ref)
+	logger.Infof("Using image: %s", ociConfig.Image)
+
+	return ociConfig, nil
+}