Files
skillshare/internal/server/handler_update.go
T
a352b8d243 feat(install): pin skills to a tag or commit from their web URL (#293)
* feat(install): pin GitHub tree/blob URLs to their ref

Hub entries only carry a source URL, so a team hub had no way to pin a
third-party skill to a reviewed tag or commit. The parser already read
tree/<ref>/ and blob/<ref>/ URLs but discarded the ref, installing from
the default branch instead of the version the URL names.

Keep that ref as Source.Branch. An explicit --branch (CLI) or branch
(API body) still overrides it; the server handlers now only override
when a branch is given. Batch installs group by repo and ref so two
pinned versions of one repo get separate clones.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(install): describe pinning hub sources to a tag or commit

Explain that a GitHub tree/<ref>/ source URL pins the install, in both
the hub index guide and the install reference.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(install): pin GitLab/Bitbucket URLs and resolve refs containing "/"

Pinning should not depend on the host, so GitLab (-/tree/<ref>/) and
Bitbucket (src/<ref>/) web URLs now keep their ref too.

Taking the first path segment as the ref broke branch names containing
"/": tree/feature/x/skills/foo cloned branch "feature" and failed. When
the first segment is not a branch or tag on the remote, the longest
matching one is used instead. A ref the remote does not have fails
with a hint to use --branch, rather than silently installing the
default branch. A saved branch that covers more of the path (from
--branch or config) moves the subdir without asking the remote.

The grouped-install round-trip test pinned -/tree/main/ against a repo
on master; the ref used to be ignored, so its branch is now renamed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(install): cover GitLab, Bitbucket and "/" branches in URL pinning

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(install): keep web URL refs correct on reinstall, --branch and grouping

Review of the slash-branch resolution found four gaps:

- A saved branch equal to the whole URL tail (tree/feature/x) did not
  move the subdir back, so every reinstall or update looked for "x".
- An unrelated --branch with a slash-branch URL kept the parse-time
  subdir (x/skills/foo) instead of the URL's real one.
- Grouped installs copy the source to a repo root; resolution then put
  the subdir back and discovery looked under a doubled path. Grouping
  also keyed on the unresolved first segment, so tree/feature/x and
  tree/feature/y could share one clone. Web URLs with a ref now install
  on their own, and resolution leaves a repo-root copy at its root.
- A skill named after the parse-time subdir kept that name once the
  path turned out to be all ref (tree/feature/x named the skill "x").

The unknown-ref error now reads as a missing ref first, since a stale
ref (tree/master after a rename) is more common than a slash branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(update): keep legacy installs on the default branch

Skills installed before URL refs were honoured got the default branch
and recorded no branch. Single-skill update re-parses the recorded
source, so it moved them to the URL's ref (or failed on a stale one,
with a hint to pass --branch, which update does not accept), while
update --all rebuilds from RepoURL and kept the default branch.

ApplyRecordedBranch treats an empty recorded branch as the remote
default and drops the URL's ref. It replaces the branch handling at
every site that reinstalls from recorded metadata: CLI and server
update for skills and agents, and tracked-repo rehydration.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* perf(search): share one clone across pinned hub skills from a repo

Any web URL with a path after its ref installed on its own, so a hub
listing many tree/<tag>/ skills from one repo cloned it once per skill.

groupByRepo now resolves each URL's ref before grouping, with a
RemoteRefs cache that lists each remote's refs once, and groups by
repo and resolved ref. Only refs containing "/" (whose subdir the
discovery match cannot re-derive) and refs that fail to resolve still
install alone. A resolved source is marked settled so the grouped
clone does not resolve it again, and ApplyRecordedBranch settles the
subdir from a recorded branch without asking the remote.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Willie <egg358358@gmail.com>
2026-09-28 22:08:16 +08:00

611 lines
18 KiB
Go

package server
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"path/filepath"
"strings"
"time"
"skillshare/internal/audit"
"skillshare/internal/config"
"skillshare/internal/git"
"skillshare/internal/install"
"skillshare/internal/utils"
)
type updateRequest struct {
Name string `json:"name"`
Kind string `json:"kind,omitempty"`
Force bool `json:"force"`
All bool `json:"all"`
SkipAudit bool `json:"skipAudit"`
}
// missingTrackedRepoInfo describes a tracked repo declared in metadata whose
// clone directory is absent on disk. Carried in update responses so the UI can
// warn and offer rehydration (issue #212).
type missingTrackedRepoInfo struct {
Name string `json:"name"`
Source string `json:"source"`
Branch string `json:"branch,omitempty"`
}
// missingTrackedRepos returns tracked repos declared in metadata but absent on disk.
func (s *Server) missingTrackedRepos() []missingTrackedRepoInfo {
repos, err := install.GetMissingTrackedRepos(s.cfg.EffectiveSkillsSource())
if err != nil || len(repos) == 0 {
return nil
}
out := make([]missingTrackedRepoInfo, 0, len(repos))
for _, r := range repos {
out = append(out, missingTrackedRepoInfo{Name: r.Name, Source: r.Source, Branch: r.Branch})
}
return out
}
type updateResultItem struct {
Name string `json:"name"`
Action string `json:"action"` // "updated", "up-to-date", "skipped", "error", "blocked"
Message string `json:"message,omitempty"`
IsRepo bool `json:"isRepo"`
AuditRiskScore int `json:"auditRiskScore,omitempty"`
AuditRiskLabel string `json:"auditRiskLabel,omitempty"`
Kind string `json:"kind,omitempty"`
}
func (s *Server) updateAuditThreshold() string {
if s.IsProjectMode() && s.projectCfg != nil {
if threshold, err := audit.NormalizeThreshold(s.projectCfg.Audit.BlockThreshold); err == nil {
return threshold
}
return audit.DefaultThreshold()
}
if s.cfg != nil {
if threshold, err := audit.NormalizeThreshold(s.cfg.Audit.BlockThreshold); err == nil {
return threshold
}
}
return audit.DefaultThreshold()
}
func (s *Server) handleUpdate(w http.ResponseWriter, r *http.Request) {
start := time.Now()
s.mu.Lock()
defer s.mu.Unlock()
defer s.trackProjectLock()()
var body updateRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeError(w, http.StatusBadRequest, "invalid JSON body")
return
}
if body.All {
results := s.updateAll(body.Force, body.SkipAudit)
total := len(results)
failed := 0
blocked := 0
for _, item := range results {
if item.Action == "error" {
failed++
} else if item.Action == "blocked" {
blocked++
}
}
status := "ok"
msg := ""
if blocked > 0 {
status = "partial"
msg = fmt.Sprintf("%d update(s) blocked by security audit", blocked)
}
if failed > 0 {
status = "partial"
if msg != "" {
msg += fmt.Sprintf(", %d update(s) failed", failed)
} else {
msg = fmt.Sprintf("%d update(s) failed", failed)
}
}
s.writeOpsLog("update", status, start, map[string]any{
"name": "--all",
"force": body.Force,
"skip_audit": body.SkipAudit,
"results_total": total,
"results_failed": failed,
"results_blocked": blocked,
"scope": "ui",
}, msg)
writeJSON(w, map[string]any{"results": results, "missingTrackedRepos": s.missingTrackedRepos()})
return
}
if body.Name == "" {
writeError(w, http.StatusBadRequest, "name is required (or use all: true)")
return
}
if body.Kind != "" && body.Kind != "skill" && body.Kind != "agent" {
writeError(w, http.StatusBadRequest, "invalid kind: "+body.Kind)
return
}
result := s.updateSingleByKind(body.Name, body.Kind, body.Force, body.SkipAudit)
status := "ok"
msg := ""
if result.Action == "error" {
status = "error"
msg = result.Message
} else if result.Action == "blocked" {
status = "error"
msg = result.Message
} else if result.Action == "skipped" {
status = "partial"
msg = result.Message
}
s.writeOpsLog("update", status, start, map[string]any{
"name": body.Name,
"force": body.Force,
"skip_audit": body.SkipAudit,
"scope": "ui",
}, msg)
writeJSON(w, map[string]any{"results": []updateResultItem{result}})
}
func (s *Server) updateSingle(name string, force, skipAudit bool) updateResultItem {
return s.updateSingleByKind(name, "", force, skipAudit)
}
func (s *Server) updateSingleByKind(name, kind string, force, skipAudit bool) updateResultItem {
if kind == "agent" {
return s.updateAgent(name, force, skipAudit)
}
// Try exact skill path first (prevents basename collision with nested repos)
skillPath := filepath.Join(s.cfg.EffectiveSkillsSource(), name)
if entry := s.skillsStore.GetByPath(name); entry != nil && entry.Source != "" {
return s.updateRegularSkill(name, skillPath, force, skipAudit)
}
// Try tracked repo (flat, nested, or basename fallback)
repoName, repoPath, err := s.resolveTrackedRepo(name)
if err != nil {
return updateResultItem{Name: name, Action: "error", Message: err.Error()}
}
if repoPath != "" {
return s.updateTrackedRepo(repoName, repoPath, force, skipAudit)
}
return updateResultItem{
Name: name,
Action: "error",
Message: fmt.Sprintf("'%s' not found as tracked repo or updatable skill", name),
}
}
func (s *Server) updateAgent(name string, force, skipAudit bool) updateResultItem {
agentsSource := s.agentsSource()
if agentsSource == "" {
return updateResultItem{Name: name, Kind: "agent", Action: "error", Message: "agents source is not configured"}
}
localAgent, err := resolveAgentResource(agentsSource, name)
if err != nil {
return updateResultItem{Name: name, Kind: "agent", Action: "error", Message: err.Error()}
}
if localAgent.RepoRelPath != "" {
repoPath := filepath.Join(agentsSource, filepath.FromSlash(localAgent.RepoRelPath))
return s.updateTrackedRepo(agentMetaKey(localAgent.RelPath), repoPath, force, skipAudit)
}
metaKey := agentMetaKey(localAgent.RelPath)
entry := s.agentsStore.GetByPath(metaKey)
if entry == nil || entry.Source == "" {
return updateResultItem{
Name: metaKey,
Kind: "agent",
Action: "skipped",
Message: "agent is local and has no update source",
}
}
source, err := install.ParseSourceWithOptions(entry.Source, s.parseOpts())
if err != nil {
return updateResultItem{Name: metaKey, Kind: "agent", Action: "error", Message: "invalid source: " + err.Error()}
}
source.ApplyRecordedBranch(entry.Branch)
repoSubdir := strings.TrimSuffix(source.Subdir, entry.Subdir)
repoSubdir = strings.TrimRight(repoSubdir, "/")
source.Subdir = repoSubdir
var discovery *install.DiscoveryResult
if source.HasSubdir() {
discovery, err = install.DiscoverFromGitSubdir(source)
} else {
discovery, err = install.DiscoverFromGit(source)
}
if err != nil {
return updateResultItem{Name: metaKey, Kind: "agent", Action: "error", Message: err.Error()}
}
defer install.CleanupDiscovery(discovery)
if discovery.CommitHash != "" && discovery.CommitHash == entry.Version {
return updateResultItem{Name: metaKey, Kind: "agent", Action: "up-to-date"}
}
var target *install.AgentInfo
for i := range discovery.Agents {
candidate := discovery.Agents[i]
if candidate.Path == entry.Subdir ||
candidate.FileName == filepath.Base(localAgent.RelPath) ||
candidate.Name == filepath.Base(metaKey) {
target = &discovery.Agents[i]
break
}
}
if target == nil {
return updateResultItem{
Name: metaKey,
Kind: "agent",
Action: "error",
Message: fmt.Sprintf("agent path %q not found in repository", entry.Subdir),
}
}
destDir := agentsSource
opts := install.InstallOptions{
Kind: "agent",
Force: force,
Update: true,
SkipAudit: skipAudit,
AuditThreshold: s.updateAuditThreshold(),
SourceDir: agentsSource,
}
if s.IsProjectMode() {
opts.AuditProjectRoot = s.projectRoot
}
res, err := install.UpdateAgentFromDiscovery(discovery, *target, destDir, opts)
if err != nil {
return updateResultItem{Name: metaKey, Kind: "agent", Action: "error", Message: err.Error()}
}
if st, loadErr := install.LoadMetadataWithMigration(agentsSource, install.MetadataKindAgent); loadErr == nil && st != nil {
s.agentsStore = st
}
message := res.Action
if message == "" {
message = "updated"
}
return updateResultItem{
Name: metaKey,
Kind: "agent",
Action: "updated",
Message: message,
}
}
func (s *Server) updateTrackedRepo(name, repoPath string, force, skipAudit bool) updateResultItem {
// Check for uncommitted changes
if isDirty, _ := git.IsDirty(repoPath); isDirty {
if !force {
return updateResultItem{
Name: name,
Action: "skipped",
Message: "has uncommitted changes (use force to discard)",
IsRepo: true,
}
}
if err := git.Restore(repoPath); err != nil {
return updateResultItem{
Name: name,
Action: "error",
Message: "failed to discard changes: " + err.Error(),
IsRepo: true,
}
}
}
var info *git.UpdateInfo
var err error
if force {
info, err = git.ForcePullWithAuth(repoPath)
} else {
info, err = git.PullWithAuth(repoPath)
}
if err != nil {
msg := err.Error()
if !force {
msg += " (try force update)"
}
return updateResultItem{
Name: name,
Action: "error",
Message: msg,
IsRepo: true,
}
}
if info.UpToDate {
return updateResultItem{Name: name, Action: "up-to-date", IsRepo: true}
}
// Post-pull audit gate
item := updateResultItem{
Name: name,
Action: "updated",
Message: fmt.Sprintf("%d commits, %d files changed", len(info.Commits), info.Stats.FilesChanged),
IsRepo: true,
}
if !skipAudit {
blocked, auditResult := s.auditGateTrackedRepo(name, repoPath, info.BeforeHash, force, s.updateAuditThreshold())
if blocked != nil {
return *blocked
}
if auditResult != nil {
item.AuditRiskScore = auditResult.RiskScore
item.AuditRiskLabel = auditResult.RiskLabel
}
}
return item
}
// auditGateTrackedRepo scans a tracked repo after pull and rolls back if findings are detected
// at or above the active threshold.
// Returns (blocked item, audit result). blocked is non-nil when the update should be rejected.
func (s *Server) auditGateTrackedRepo(name, repoPath, beforeHash string, force bool, threshold string) (*updateResultItem, *audit.Result) {
var result *audit.Result
var err error
if s.IsProjectMode() {
result, err = audit.ScanSkillForProject(repoPath, s.projectRoot)
} else {
result, err = audit.ScanSkill(repoPath)
}
if err != nil {
msg := "security audit failed: " + err.Error()
if beforeHash == "" {
msg += " (rollback commit unavailable, repository state is unknown)"
} else if resetErr := git.ResetHard(repoPath, beforeHash); resetErr != nil {
msg += " (WARNING: rollback also failed: " + resetErr.Error() + " — malicious content may remain)"
} else {
msg += " (rolled back)"
}
return &updateResultItem{
Name: name,
Action: "blocked",
Message: msg,
IsRepo: true,
}, nil
}
if result.HasSeverityAtOrAbove(threshold) && !force {
msg := fmt.Sprintf("blocked by security audit — findings at/above %s detected", threshold)
if beforeHash == "" {
msg += " (rollback commit unavailable, repository state is unknown)"
} else if resetErr := git.ResetHard(repoPath, beforeHash); resetErr != nil {
msg += " (WARNING: rollback failed: " + resetErr.Error() + " — malicious content may remain)"
} else {
msg += ", rolled back"
}
return &updateResultItem{
Name: name,
Action: "blocked",
Message: msg,
IsRepo: true,
}, result
}
return nil, result
}
func (s *Server) updateRegularSkill(name, skillPath string, force, skipAudit bool) updateResultItem {
entry := s.skillsStore.GetByPath(name)
if entry == nil {
return updateResultItem{Name: name, Action: "error", Message: "no metadata found"}
}
source, err := install.ParseSourceWithOptions(entry.Source, s.parseOpts())
if err != nil {
return updateResultItem{
Name: name,
Action: "error",
Message: "invalid source: " + err.Error(),
}
}
source.ApplyRecordedBranch(entry.Branch)
sourceDir := s.cfg.EffectiveSkillsSource()
opts := install.InstallOptions{
Force: true,
AuditOverride: force,
Update: true,
SkipAudit: skipAudit,
AuditThreshold: s.updateAuditThreshold(),
SourceDir: sourceDir,
}
if s.IsProjectMode() {
opts.AuditProjectRoot = s.projectRoot
}
result, err := install.Install(source, skillPath, opts)
if err != nil {
return updateResultItem{
Name: name,
Action: "error",
Message: err.Error(),
}
}
if st, loadErr := install.LoadMetadataWithMigration(sourceDir, ""); loadErr == nil && st != nil {
s.skillsStore = st
}
item := updateResultItem{
Name: name,
Action: "updated",
Message: "reinstalled from source",
}
if result != nil && result.AuditRiskLabel != "" {
item.AuditRiskScore = result.AuditRiskScore
item.AuditRiskLabel = result.AuditRiskLabel
}
return item
}
func (s *Server) updateAll(force, skipAudit bool) []updateResultItem {
var results []updateResultItem
// Update tracked repos
repos, err := install.GetTrackedRepos(s.cfg.EffectiveSkillsSource())
if err == nil {
for _, repo := range repos {
repoPath := filepath.Join(s.cfg.EffectiveSkillsSource(), repo)
results = append(results, s.updateTrackedRepo(repo, repoPath, force, skipAudit))
}
}
// Update regular skills with source metadata
skills, err := getServerUpdatableSkills(s.cfg.EffectiveSkillsSource(), s.skillsStore)
if err == nil {
for _, skill := range skills {
skillPath := filepath.Join(s.cfg.EffectiveSkillsSource(), skill)
results = append(results, s.updateRegularSkill(skill, skillPath, force, skipAudit))
}
}
return results
}
// handleMissingTrackedRepos returns tracked repos declared in metadata whose
// clone directories are absent on disk (issue #212), so the UI can warn on load.
func (s *Server) handleMissingTrackedRepos(w http.ResponseWriter, r *http.Request) {
s.mu.RLock()
repos := s.missingTrackedRepos()
s.mu.RUnlock()
if repos == nil {
repos = []missingTrackedRepoInfo{}
}
writeJSON(w, map[string]any{"repos": repos})
}
// handleRehydrateTrackedRepos re-clones tracked repos declared in metadata whose
// clone directories are absent on disk (issue #212). Mirrors bare CLI install.
func (s *Server) handleRehydrateTrackedRepos(w http.ResponseWriter, r *http.Request) {
start := time.Now()
s.mu.Lock()
defer s.mu.Unlock()
sourceDir := s.cfg.EffectiveSkillsSource()
opts := install.InstallOptions{
AuditThreshold: s.updateAuditThreshold(),
SourceDir: sourceDir,
}
if s.IsProjectMode() {
opts.AuditProjectRoot = s.projectRoot
}
results, err := install.RehydrateMissingTrackedRepos(sourceDir, s.parseOpts(), opts)
if err != nil {
writeError(w, http.StatusInternalServerError, err.Error())
return
}
// Reload metadata + reconcile config so newly cloned repos register.
if st, lerr := install.LoadMetadataWithMigration(sourceDir, ""); lerr == nil && st != nil {
s.skillsStore = st
}
if s.IsProjectMode() {
if rErr := config.ReconcileProjectSkills(s.projectRoot, s.projectCfg, s.skillsStore, sourceDir); rErr != nil {
log.Printf("warning: failed to reconcile project skills config: %v", rErr)
}
} else {
if rErr := config.ReconcileGlobalSkills(s.cfg, s.skillsStore); rErr != nil {
log.Printf("warning: failed to reconcile global skills config: %v", rErr)
}
}
rehydrated, failed := 0, 0
for _, res := range results {
if res.Action == "rehydrated" {
rehydrated++
} else {
failed++
}
}
status, msg := "ok", ""
if failed > 0 {
status = "partial"
msg = fmt.Sprintf("%d repo(s) failed to rehydrate", failed)
}
s.writeOpsLog("install", status, start, map[string]any{
"name": "--rehydrate",
"tracked": true,
"scope": "ui",
"rehydrated": rehydrated,
"failed": failed,
}, msg)
writeJSON(w, map[string]any{"results": results})
}
// getServerUpdatableSkills returns relative paths of skills that have metadata with a remote source.
// It walks the source directory recursively to find nested skills (e.g. utils/ascii-box-check).
func getServerUpdatableSkills(sourceDir string, store *install.MetadataStore) ([]string, error) {
var skills []string
walkRoot := utils.ResolveSymlink(sourceDir)
err := filepath.WalkDir(walkRoot, func(path string, d os.DirEntry, err error) error {
if err != nil {
return nil
}
if path == walkRoot {
return nil
}
if !d.IsDir() {
return nil
}
name := d.Name()
// Skip hidden directories and .git
if name == ".git" || (len(name) > 0 && name[0] == '.') {
return filepath.SkipDir
}
// Skip tracked repos (_ prefix with .git inside)
if len(name) > 0 && name[0] == '_' {
return filepath.SkipDir
}
// Check if this directory has updatable metadata
relName := filepath.Base(path)
if relP, relErr2 := filepath.Rel(walkRoot, path); relErr2 == nil {
relName = filepath.ToSlash(relP)
}
entry := store.GetByPath(relName)
if entry == nil || entry.Source == "" {
return nil // continue walking into subdirectories
}
relPath, relErr := filepath.Rel(walkRoot, path)
if relErr == nil {
skills = append(skills, filepath.ToSlash(relPath))
}
return filepath.SkipDir // don't recurse into skill directories
})
if err != nil {
return nil, err
}
return skills, nil
}
// trackProjectLock returns a function for defer: it moves the lockfile pins of
// the skills the request changed. Global mode has no lockfile.
func (s *Server) trackProjectLock() func() {
if !s.IsProjectMode() {
return func() {}
}
done := config.TrackProjectLock(s.projectRoot, s.projectCfg, s.cfg.EffectiveSkillsSource())
return func() {
if err := done(); err != nil {
log.Printf("warning: failed to update %s: %v", install.LockFileName, err)
}
}
}