Implement custom github URL scheme in Go

This is a reimplementation of the bash code in
#3937 (comment)

Signed-off-by: Jan Dubois <[email protected]>

Author: jandubois

pkg/limatmpl/locator.go

@@ -4,7 +4,9 @@
 package limatmpl
 
 import (
+	"cmp"
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
@@ -296,6 +298,109 @@ func InstNameFromYAMLPath(yamlPath string) (string, error) {
 	return s, nil
 }
 
+// transformGitHubURL transforms a github: URL to a raw.githubusercontent.com URL.
+// Input format: ORG/REPO[/PATH][@BRANCH]
+//
+// Examples:
+// - github:lima-vm/lima                      -> https://raw.githubusercontent.com/lima-vm/lima/master/lima.yaml
+// - github:lima-vm/lima/examples             -> https://raw.githubusercontent.com/lima-vm/lima/master/examples/lima.yaml
+// - github:lima-vm/[email protected]               -> https://raw.githubusercontent.com/lima-vm/lima/v1.0.0/lima.yaml
+// - github:lima-vm/lima/examples/docker.yaml -> https://raw.githubusercontent.com/lima-vm/lima/master/examples/docker.yaml
+func transformGitHubURL(ctx context.Context, input string) (string, error) {
+	// Check for explicit branch specification with @ at the end
+	var branch string
+	if idx := strings.LastIndex(input, "@"); idx != -1 {
+		branch = input[idx+1:]
+		input = input[:idx]
+	}
+
+	parts := strings.Split(input, "/")
+	if len(parts) < 2 {
+		return "", fmt.Errorf("github: URL must be at least ORG/REPO, got %q", input)
+	}
+
+	org := parts[0]
+	repo := parts[1]
+
+	// Extract path (everything after ORG/REPO)
+	var pathPart string
+	if len(parts) > 2 {
+		pathPart = strings.Join(parts[2:], "/")
+	} else {
+		pathPart = "lima"
+	}
+
+	// If path ends with /, it's a directory, so append lima
+	if strings.HasSuffix(pathPart, "/") {
+		pathPart += "lima"
+	}
+
+	// If the filename (last component) has no extension, add .yaml
+	filename := path.Base(pathPart)
+	if !strings.Contains(filename, ".") {
+		pathPart += ".yaml"
+	}
+
+	// Query default branch if no branch was specified
+	if branch == "" {
+		var err error
+		branch, err = getGitHubDefaultBranch(ctx, org, repo)
+		if err != nil {
+			return "", fmt.Errorf("failed to get default branch for %s/%s: %w", org, repo, err)
+		}
+	}
+
+	return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s/%s", org, repo, branch, pathPart), nil
+}
+
+// getGitHubDefaultBranch queries the GitHub API to get the default branch for a repository.
+func getGitHubDefaultBranch(ctx context.Context, org, repo string) (string, error) {
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/%s", org, repo)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, apiURL, http.NoBody)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", "lima")
+	req.Header.Set("Accept", "application/vnd.github.v3+json")
+
+	// Check for GitHub token in environment for authenticated requests (higher rate limit)
+	token := cmp.Or(os.Getenv("GH_TOKEN"), os.Getenv("GITHUB_TOKEN"))
+	if token != "" {
+		req.Header.Set("Authorization", "token "+token)
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to query GitHub API: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read GitHub API response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("GitHub API returned status %d: %s", resp.StatusCode, string(body))
+	}
+
+	var repoData struct {
+		DefaultBranch string `json:"default_branch"`
+	}
+
+	if err := json.Unmarshal(body, &repoData); err != nil {
+		return "", fmt.Errorf("failed to parse GitHub API response: %w", err)
+	}
+
+	if repoData.DefaultBranch == "" {
+		return "", fmt.Errorf("repository %s/%s has no default branch", org, repo)
+	}
+
+	return repoData.DefaultBranch, nil
+}
+
 func TransformCustomURL(ctx context.Context, locator string) (string, error) {
 	u, err := url.Parse(locator)
 	if err != nil || len(u.Scheme) <= 1 {
@@ -312,6 +417,15 @@ func TransformCustomURL(ctx context.Context, locator string) (string, error) {
 		return newLocator, nil
 	}
 
+	if u.Scheme == "github" {
+		newLocator, err := transformGitHubURL(ctx, u.Opaque)
+		if err != nil {
+			return "", err
+		}
+		logrus.Debugf("GitHub locator %q replaced with %q", locator, newLocator)
+		return newLocator, nil
+	}
+
 	plugin, err := plugins.Find("url-" + u.Scheme)
 	if err != nil {
 		return "", err

pkg/limatmpl/locator_test.go

@@ -123,3 +123,99 @@ func TestSeemsFileURL(t *testing.T) {
 		})
 	}
 }
+
+func TestTransformCustomURL_GitHub(t *testing.T) {
+	testCases := []struct {
+		name        string
+		input       string
+		expected    string
+		expectError bool
+	}{
+		{
+			name:     "basic org/repo with explicit branch",
+			input:    "github:lima-vm/lima@master",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/master/lima.yaml",
+		},
+		{
+			name:     "org/repo with path and explicit branch",
+			input:    "github:lima-vm/lima/templates/docker@master",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/master/templates/docker.yaml",
+		},
+		{
+			name:     "org/repo with path, extension, and explicit branch",
+			input:    "github:lima-vm/lima/templates/docker.yaml@master",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/master/templates/docker.yaml",
+		},
+		{
+			name:     "org/repo with trailing slash and explicit branch",
+			input:    "github:lima-vm/lima/templates/@main",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/main/templates/lima.yaml",
+		},
+		{
+			name:     "org/repo with tag version",
+			input:    "github:lima-vm/[email protected]",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/v1.0.0/lima.yaml",
+		},
+		{
+			name:     "org/repo with path and tag",
+			input:    "github:lima-vm/lima/templates/[email protected]",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/v2.0.0/templates/alpine.yaml",
+		},
+		{
+			name:        "invalid format - only org",
+			input:       "github:lima-vm",
+			expectError: true,
+		},
+		{
+			name:        "invalid format - empty",
+			input:       "github:",
+			expectError: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result, err := limatmpl.TransformCustomURL(t.Context(), tc.input)
+
+			if tc.expectError {
+				assert.Assert(t, err != nil, "expected error but got none")
+			} else {
+				assert.NilError(t, err)
+				assert.Equal(t, result, tc.expected)
+			}
+		})
+	}
+}
+
+func TestTransformCustomURL_GitHubWithDefaultBranch(t *testing.T) {
+	// These tests require network access and will query the GitHub API
+	// Skip if running in an environment without network access
+	if testing.Short() {
+		t.Skip("skipping network-dependent test in short mode")
+	}
+
+	testCases := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "basic org/repo queries default branch",
+			input:    "github:lima-vm/lima",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/master/lima.yaml",
+		},
+		{
+			name:     "org/repo with path queries default branch",
+			input:    "github:lima-vm/lima/templates/docker",
+			expected: "https://raw.githubusercontent.com/lima-vm/lima/master/templates/docker.yaml",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result, err := limatmpl.TransformCustomURL(t.Context(), tc.input)
+			assert.NilError(t, err)
+			assert.Equal(t, result, tc.expected)
+		})
+	}
+}