From ce9593e98e8e4da28d4e452fb89d0f49e2d85b11 Mon Sep 17 00:00:00 2001 From: zishuo Date: Tue, 26 May 2026 18:49:18 +0800 Subject: [PATCH] feat(install): add Gitea platform support with API fast path Support Gitea (gitea.com and self-hosted instances) as a git hosting platform for installing skills. Includes both core platform integration and a Gitea Contents API fast path for direct file downloads without full git clone. Platform support (P0): - auth.go: add PlatformGitea, detect gitea hosts, resolve GITEA_TOKEN - config.go / project.go: add gitea_hosts config field with normalization, env var merge (SKILLSHARE_GITEA_HOSTS), and EffectiveGiteaHosts() - source.go: add isGiteaHost() and GiteaHosts to ParseOptions - install.go: pass GiteaHosts from config to source parsing - install_git.go: include GITEA_TOKEN in auth error hints API fast path (P1): - gitea_download.go: Gitea Contents API recursive directory download (GET /api/v1/repos/{owner}/{repo}/contents/{path}), matching the GitHub Contents API pattern - install_apply.go / install_discovery.go: hook Gitea API fallback after sparse checkout, before full clone --- cmd/skillshare/install.go | 2 + internal/config/config.go | 21 ++ internal/config/project.go | 13 ++ internal/install/auth.go | 10 +- internal/install/gitea_download.go | 286 ++++++++++++++++++++++++++ internal/install/install_apply.go | 15 ++ internal/install/install_discovery.go | 27 +++ internal/install/install_git.go | 2 +- internal/install/source.go | 6 + 9 files changed, 380 insertions(+), 2 deletions(-) create mode 100644 internal/install/gitea_download.go diff --git a/cmd/skillshare/install.go b/cmd/skillshare/install.go index f1308b26f..33840aaed 100644 --- a/cmd/skillshare/install.go +++ b/cmd/skillshare/install.go @@ -253,6 +253,7 @@ func parseOptsFromConfig(cfg *config.Config) install.ParseOptions { GitLabHosts: cfg.EffectiveGitLabHosts(), AzureHosts: cfg.EffectiveAzureHosts(), CNBHosts: cfg.EffectiveCNBHosts(), + GiteaHosts: cfg.EffectiveGiteaHosts(), } } @@ -262,6 +263,7 @@ func parseOptsFromProjectConfig(cfg *config.ProjectConfig) install.ParseOptions GitLabHosts: cfg.EffectiveGitLabHosts(), AzureHosts: cfg.EffectiveAzureHosts(), CNBHosts: cfg.EffectiveCNBHosts(), + GiteaHosts: cfg.EffectiveGiteaHosts(), } } diff --git a/internal/config/config.go b/internal/config/config.go index 53f5ed918..682c097fc 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -279,6 +279,7 @@ type Config struct { GitLabHosts []string `yaml:"gitlab_hosts,omitempty"` AzureHosts []string `yaml:"azure_hosts,omitempty"` CNBHosts []string `yaml:"cnb_hosts,omitempty"` + GiteaHosts []string `yaml:"gitea_hosts,omitempty"` // PreserveTildeOnSave folds $HOME prefixes back to ~ when serializing the // config to YAML. Useful when the config is shared via dotfiles across @@ -364,6 +365,11 @@ func (c *Config) EffectiveCNBHosts() []string { return mergeCNBHostsFromEnv(c.CNBHosts) } +// EffectiveGiteaHosts returns GiteaHosts merged with SKILLSHARE_GITEA_HOSTS env var. +func (c *Config) EffectiveGiteaHosts() []string { + return mergeGiteaHostsFromEnv(c.GiteaHosts) +} + // IsTUIEnabled reports whether interactive TUI is enabled. // nil (absent from config) is treated as true for backward compatibility. func (c *Config) IsTUIEnabled() bool { @@ -512,6 +518,13 @@ func Load() (*Config, error) { } cfg.CNBHosts = cnbHosts + // Validate and normalize gitea_hosts + giteaHosts, err := normalizeGiteaHosts(cfg.GiteaHosts) + if err != nil { + return nil, err + } + cfg.GiteaHosts = giteaHosts + // Migrate legacy flat target fields to skills: sub-key (one-time, persisted immediately) if migrateTargetConfigs(cfg.Targets) { if data, err := marshalYAML(&cfg); err == nil { @@ -775,6 +788,10 @@ func normalizeCNBHosts(hosts []string) ([]string, error) { return normalizeHostList(hosts, "cnb_hosts") } +func normalizeGiteaHosts(hosts []string) ([]string, error) { + return normalizeHostList(hosts, "gitea_hosts") +} + // mergeHostsFromEnv merges comma-separated env var entries with config file hosts. // Invalid entries in the env var are silently skipped. func mergeHostsFromEnv(configHosts []string, envKey string) []string { @@ -812,6 +829,10 @@ func mergeCNBHostsFromEnv(configHosts []string) []string { return mergeHostsFromEnv(configHosts, "SKILLSHARE_CNB_HOSTS") } +func mergeGiteaHostsFromEnv(configHosts []string) []string { + return mergeHostsFromEnv(configHosts, "SKILLSHARE_GITEA_HOSTS") +} + func normalizeAuditBlockThreshold(v string) (string, error) { threshold := strings.ToUpper(strings.TrimSpace(v)) if threshold == "" { diff --git a/internal/config/project.go b/internal/config/project.go index 342a37a76..24f3bfc9c 100644 --- a/internal/config/project.go +++ b/internal/config/project.go @@ -274,6 +274,7 @@ type ProjectConfig struct { GitLabHosts []string `yaml:"gitlab_hosts,omitempty"` AzureHosts []string `yaml:"azure_hosts,omitempty"` CNBHosts []string `yaml:"cnb_hosts,omitempty"` + GiteaHosts []string `yaml:"gitea_hosts,omitempty"` } // EffectiveSkillsSource returns the resolved skills source directory. @@ -345,6 +346,11 @@ func (c *ProjectConfig) EffectiveCNBHosts() []string { return mergeCNBHostsFromEnv(c.CNBHosts) } +// EffectiveGiteaHosts returns GiteaHosts merged with SKILLSHARE_GITEA_HOSTS env var. +func (c *ProjectConfig) EffectiveGiteaHosts() []string { + return mergeGiteaHostsFromEnv(c.GiteaHosts) +} + // ProjectConfigPath returns the project config path for the given root. func ProjectConfigPath(projectRoot string) string { return filepath.Join(projectRoot, ".skillshare", "config.yaml") @@ -394,6 +400,13 @@ func LoadProject(projectRoot string) (*ProjectConfig, error) { } cfg.CNBHosts = cnbHosts + // Validate and normalize gitea_hosts + giteaHosts, err := normalizeGiteaHosts(cfg.GiteaHosts) + if err != nil { + return nil, fmt.Errorf("project config: %w", err) + } + cfg.GiteaHosts = giteaHosts + for _, target := range cfg.Targets { if strings.TrimSpace(target.Name) == "" { return nil, fmt.Errorf("project config has target with empty name") diff --git a/internal/install/auth.go b/internal/install/auth.go index 9bf2a4f74..948e344a4 100644 --- a/internal/install/auth.go +++ b/internal/install/auth.go @@ -18,6 +18,7 @@ const ( PlatformBitbucket // bitbucket.org PlatformAzureDevOps // dev.azure.com and visualstudio.com PlatformCNB // cnb.cool and self-hosted CNB instances + PlatformGitea // gitea.com and self-hosted Gitea instances ) // extractHost returns the hostname from a clone URL. @@ -66,6 +67,9 @@ func detectPlatform(cloneURL string) Platform { if strings.Contains(host, "cnb.cool") { return PlatformCNB } + if strings.Contains(host, "gitea") { + return PlatformGitea + } return PlatformUnknown } @@ -106,6 +110,10 @@ func resolveToken(cloneURL string) (token, username string) { if t := os.Getenv("CNB_TOKEN"); t != "" { return t, "cnb" } + case PlatformGitea: + if t := os.Getenv("GITEA_TOKEN"); t != "" { + return t, "x-access-token" + } } // Generic fallback — use platform-appropriate username, or preserve @@ -203,7 +211,7 @@ func sanitizeTokens(text string) string { vars := []string{ "GITHUB_TOKEN", "GH_TOKEN", "GITLAB_TOKEN", "BITBUCKET_TOKEN", "AZURE_DEVOPS_TOKEN", "SKILLSHARE_GIT_TOKEN", "BITBUCKET_USERNAME", - "CNB_TOKEN", + "CNB_TOKEN", "GITEA_TOKEN", } for _, v := range vars { if t := os.Getenv(v); t != "" { diff --git a/internal/install/gitea_download.go b/internal/install/gitea_download.go new file mode 100644 index 000000000..2e76a3295 --- /dev/null +++ b/internal/install/gitea_download.go @@ -0,0 +1,286 @@ +package install + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "os" + "path/filepath" + "strings" + "time" +) + +type giteaContentItem struct { + Type string `json:"type"` + Name string `json:"name"` + Path string `json:"path"` + DownloadURL string `json:"download_url"` +} + +type giteaCommit struct { + SHA string `json:"sha"` +} + +// isGiteaAPISource reports whether the source is a Gitea instance that supports +// the Contents API for direct file downloads. +func isGiteaAPISource(source *Source) bool { + if source == nil { + return false + } + host := strings.ToLower(extractHost(source.CloneURL)) + return strings.Contains(host, "gitea") +} + +// downloadGiteaDir downloads a repository subdirectory via the Gitea Contents API. +func downloadGiteaDir(owner, repo, path, destDir string, source *Source, onProgress ProgressCallback) (string, error) { + if owner == "" || repo == "" { + return "", fmt.Errorf("gitea download requires owner and repo") + } + + apiBase := giteaAPIBase(source) + if err := os.MkdirAll(destDir, 0755); err != nil { + return "", err + } + + if onProgress != nil { + onProgress("Downloading via Gitea API...") + } + + client := &http.Client{Timeout: 30 * time.Second} + if err := giteaDownloadDirRecursive(client, apiBase, owner, repo, strings.Trim(path, "/"), destDir, onProgress); err != nil { + return "", err + } + + commitHash, err := giteaFetchLatestCommitHash(apiBase, owner, repo, source) + if err != nil { + return "", nil + } + return shortCommitHash(commitHash), nil +} + +// giteaAPIBase returns the base API URL for a Gitea instance. +func giteaAPIBase(source *Source) string { + host := strings.ToLower(extractHost(source.CloneURL)) + scheme := "https" + // For standard gitea.com, use api.gitea.com convention + // For self-hosted, use https://{host}/api/v1 + if host == "gitea.com" { + return "https://gitea.com/api/v1" + } + return fmt.Sprintf("%s://%s/api/v1", scheme, host) +} + +// giteaDownloadDirRecursive recursively downloads a directory via the Gitea Contents API. +func giteaDownloadDirRecursive(client *http.Client, apiBase, owner, repo, path, destDir string, onProgress ProgressCallback) error { + contentsURL := fmt.Sprintf("%s/repos/%s/%s/contents/%s", + strings.TrimRight(apiBase, "/"), owner, repo, url.PathEscape(path)) + + req, err := giteaNewRequest(contentsURL) + if err != nil { + return err + } + + resp, err := client.Do(req) + if err != nil { + return fmt.Errorf("Gitea API request failed: %w", err) + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + return fmt.Errorf("Gitea contents API returned %d for %s", resp.StatusCode, path) + } + + var raw json.RawMessage + if err := json.NewDecoder(resp.Body).Decode(&raw); err != nil { + return fmt.Errorf("failed to parse Gitea contents response: %w", err) + } + + trimmed := bytes.TrimSpace(raw) + if len(trimmed) == 0 { + return fmt.Errorf("empty Gitea contents response for %q", path) + } + + // Single file response: {type, name, path, download_url, ...} + if trimmed[0] == '{' { + var item giteaContentItem + if err := json.Unmarshal(trimmed, &item); err != nil { + return err + } + if item.Type != "file" { + return fmt.Errorf("unsupported Gitea content type %q", item.Type) + } + fileName, err := giteaSanitizeName(item.Name) + if err != nil { + return err + } + target := filepath.Join(destDir, fileName) + if onProgress != nil { + onProgress(fmt.Sprintf("Downloading %s", item.Path)) + } + return giteaDownloadFile(client, item.DownloadURL, target) + } + + // Directory listing response: [{type, name, path, download_url, ...}] + if trimmed[0] == '[' { + var items []giteaContentItem + if err := json.Unmarshal(trimmed, &items); err != nil { + return err + } + for _, item := range items { + name, err := giteaSanitizeName(item.Name) + if err != nil { + return err + } + switch item.Type { + case "dir": + childDir := filepath.Join(destDir, name) + if err := os.MkdirAll(childDir, 0755); err != nil { + return err + } + if err := giteaDownloadDirRecursive(client, apiBase, owner, repo, item.Path, childDir, onProgress); err != nil { + return err + } + case "file": + target := filepath.Join(destDir, name) + if onProgress != nil { + onProgress(fmt.Sprintf("Downloading %s", item.Path)) + } + if err := giteaDownloadFile(client, item.DownloadURL, target); err != nil { + return err + } + } + } + return nil + } + + return fmt.Errorf("unexpected Gitea contents payload for %q", path) +} + +// giteaDownloadFile downloads a single file from a URL. +func giteaDownloadFile(client *http.Client, fileURL, destPath string) error { + req, err := giteaNewRequest(fileURL) + if err != nil { + return err + } + + resp, err := client.Do(req) + if err != nil { + return err + } + defer resp.Body.Close() + + if resp.StatusCode != http.StatusOK { + return fmt.Errorf("download returned %d", resp.StatusCode) + } + + if err := os.MkdirAll(filepath.Dir(destPath), 0755); err != nil { + return err + } + + f, err := os.OpenFile(destPath, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644) + if err != nil { + return err + } + defer f.Close() + + _, err = io.Copy(f, resp.Body) + return err +} + +// giteaNewRequest creates a GET request with Gitea API headers and optional +// token authentication (GITEA_TOKEN or platform-resolved token). +func giteaNewRequest(reqURL string) (*http.Request, error) { + req, err := http.NewRequest(http.MethodGet, reqURL, nil) + if err != nil { + return nil, err + } + + req.Header.Set("Accept", "application/json") + + // Try GITEA_TOKEN first, then SKILLSHARE_GIT_TOKEN + token := os.Getenv("GITEA_TOKEN") + if token == "" { + token = os.Getenv("SKILLSHARE_GIT_TOKEN") + } + if token != "" { + req.Header.Set("Authorization", "token "+token) + } + + return req, nil +} + +// giteaFetchLatestCommitHash retrieves the latest commit SHA from a Gitea repo. +func giteaFetchLatestCommitHash(apiBase, owner, repo string, source *Source) (string, error) { + commitsURL := fmt.Sprintf("%s/repos/%s/%s/commits?per_page=1", + strings.TrimRight(apiBase, "/"), owner, repo) + + req, err := giteaNewRequest(commitsURL) + if err != nil { + return "", err + } + + client := &http.Client{Timeout: 15 * time.Second} + resp, err := client.Do(req) + if err != nil { + return "", err + } + defer resp.Body.Close() + + if resp.StatusCode == http.StatusOK { + var commits []giteaCommit + if decodeErr := json.NewDecoder(resp.Body).Decode(&commits); decodeErr == nil && len(commits) > 0 { + return commits[0].SHA, nil + } + } + + // Fallback: use git ls-remote + if source != nil && source.CloneURL != "" { + return getRemoteHeadCommit(source.CloneURL) + } + + return "", fmt.Errorf("failed to fetch latest commit hash") +} + +// giteaSanitizeName validates a Gitea file/directory name. +func giteaSanitizeName(name string) (string, error) { + name = strings.TrimSpace(name) + if name == "" || name == "." || name == ".." || strings.Contains(name, "/") || strings.Contains(name, "\\") { + return "", fmt.Errorf("invalid Gitea item name %q", name) + } + return name, nil +} + +// giteaOwnerRepo extracts the owner and repo name from a Gitea clone URL. +// Clone URLs are in the format: https://host/owner/repo.git or git@host:owner/repo.git +func giteaOwnerRepo(cloneURL string) (owner, repo string) { + u := strings.TrimSpace(cloneURL) + u = strings.TrimSuffix(u, ".git") + u = strings.TrimSuffix(u, "/") + + // SSH: git@host:owner/repo + if strings.HasPrefix(u, "git@") { + parts := strings.Split(u, ":") + if len(parts) == 2 { + segments := strings.Split(parts[1], "/") + if len(segments) >= 2 { + return segments[0], segments[1] + } + } + return "", "" + } + + // HTTPS: https://host/owner/repo + parsed, err := url.Parse(u) + if err != nil { + return "", "" + } + path := strings.Trim(parsed.Path, "/") + segments := strings.Split(path, "/") + if len(segments) >= 2 { + return segments[0], segments[1] + } + return "", "" +} diff --git a/internal/install/install_apply.go b/internal/install/install_apply.go index f825d21f5..f793fd760 100644 --- a/internal/install/install_apply.go +++ b/internal/install/install_apply.go @@ -492,6 +492,21 @@ func installFromGitSubdir(source *Source, destPath string, result *InstallResult } } + // Fast path 2b: Gitea Contents API + if subdirPath == "" && isGiteaAPISource(source) { + owner, repo := giteaOwnerRepo(source.CloneURL) + resolved = source.Subdir + subdirPath = filepath.Join(tempRepoPath, resolved) + hash, dlErr := downloadGiteaDir(owner, repo, source.Subdir, subdirPath, source, opts.OnProgress) + if dlErr == nil { + commitHash = hash + } else { + result.Warnings = append(result.Warnings, fmt.Sprintf("Gitea API install fallback: %v", dlErr)) + subdirPath = "" + _ = os.RemoveAll(tempRepoPath) + } + } + // Fallback: full clone + fuzzy subdir resolution if subdirPath == "" { _ = os.RemoveAll(tempRepoPath) diff --git a/internal/install/install_discovery.go b/internal/install/install_discovery.go index d7a30ea2a..ccc11675e 100644 --- a/internal/install/install_discovery.go +++ b/internal/install/install_discovery.go @@ -389,6 +389,33 @@ func discoverFromGitSubdirWithProgressImpl(source *Source, onProgress ProgressCa subdirPath = "" } + // Fast path 2b: Gitea Contents API + if subdirPath == "" && isGiteaAPISource(source) { + owner, repo := giteaOwnerRepo(source.CloneURL) + subdirPath = filepath.Join(repoPath, source.Subdir) + hash, dlErr := downloadGiteaDir(owner, repo, source.Subdir, subdirPath, source, onProgress) + if dlErr == nil { + commitHash = hash + skills := discoverSkills(subdirPath, true) + agents := discoverAgents(subdirPath, len(skills) > 0) + skills, agents, err = constrainDiscoveryToExplicitSkill(source, skills, agents) + if err != nil { + _ = os.RemoveAll(tempDir) + return nil, err + } + return &DiscoveryResult{ + RepoPath: tempDir, + Skills: skills, + Agents: agents, + Source: source, + CommitHash: commitHash, + }, nil + } + warnings = append(warnings, fmt.Sprintf("Gitea API discovery fallback: %v", dlErr)) + _ = os.RemoveAll(repoPath) + subdirPath = "" + } + // Fallback: full clone + fuzzy subdir resolution _ = os.RemoveAll(repoPath) if onProgress != nil { diff --git a/internal/install/install_git.go b/internal/install/install_git.go index 5224ee351..5b1554fab 100644 --- a/internal/install/install_git.go +++ b/internal/install/install_git.go @@ -74,7 +74,7 @@ func WrapGitError(stderr string, err error, tokenAuthAttempted bool) error { } return fmt.Errorf("authentication required — options:\n"+ " 1. SSH URL: git@:/.git\n"+ - " 2. Token env var: GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, AZURE_DEVOPS_TOKEN, CNB_TOKEN, or SKILLSHARE_GIT_TOKEN\n"+ + " 2. Token env var: GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_TOKEN, AZURE_DEVOPS_TOKEN, CNB_TOKEN, GITEA_TOKEN, or SKILLSHARE_GIT_TOKEN\n"+ " 3. Git credential helper: gh auth login\n %s", s) } if s != "" { diff --git a/internal/install/source.go b/internal/install/source.go index faa19a8c2..1b4300c72 100644 --- a/internal/install/source.go +++ b/internal/install/source.go @@ -82,6 +82,7 @@ type ParseOptions struct { GitLabHosts []string // extra hostnames to treat as GitLab (nested subgroup support) AzureHosts []string // extra hostnames to treat as Azure DevOps on-premises CNBHosts []string // extra hostnames to treat as CNB instances + GiteaHosts []string // extra hostnames to treat as Gitea instances } // ParseSource analyzes the input string and returns a Source struct. @@ -468,6 +469,11 @@ func isCNBHost(host string, extraHosts []string) bool { return strings.Contains(host, "cnb.cool") || hostMatchesAny(host, extraHosts) } +// isGiteaHost returns true if the host should be treated as a Gitea instance. +func isGiteaHost(host string, extraHosts []string) bool { + return strings.Contains(host, "gitea") || hostMatchesAny(host, extraHosts) +} + // stripGitBranchPrefix removes platform-specific branch path segments from web URLs. // Bitbucket: src/{branch}/path → path // GitLab: -/tree/{branch}/path → path, -/blob/{branch}/path → path