feat: add migration from old sidecar + registry to .metadata.json

LoadMetadataWithMigration auto-detects old format on first load:
reads registry.yaml entries, merges sidecar .skillshare-meta.json
fields, writes unified .metadata.json, cleans up old files.
Idempotent — skips migration if .metadata.json already exists.
This commit is contained in:
Willie
2026-04-08 10:39:43 +08:00
parent fa5679d0c0
commit ce6be175d4
2 changed files with 568 additions and 0 deletions
+280
View File
@@ -0,0 +1,280 @@
package install
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"gopkg.in/yaml.v3"
)
// LoadMetadataWithMigration loads .metadata.json, or migrates from old format if needed.
// kind is "" for skills directories, "agent" for agents directories.
func LoadMetadataWithMigration(dir, kind string) (*MetadataStore, error) {
// Fast path: .metadata.json already exists
metaPath := filepath.Join(dir, MetadataFileName)
if _, err := os.Stat(metaPath); err == nil {
return LoadMetadata(dir)
}
store := NewMetadataStore()
// Phase 1: Migrate registry.yaml entries
migrateRegistryEntries(store, dir, kind)
// Phase 2: Migrate sidecar .skillshare-meta.json files
if kind == "agent" {
migrateAgentSidecars(store, dir)
} else {
migrateSkillSidecars(store, dir)
}
// Phase 3: Save if we found anything to migrate
if len(store.Entries) > 0 {
if err := store.Save(dir); err != nil {
return store, err
}
}
// Phase 4: Clean up old registry.yaml
cleanupOldRegistry(dir)
return store, nil
}
// localRegistryEntry mirrors config.SkillEntry without importing internal/config.
type localRegistryEntry struct {
Name string `yaml:"name"`
Kind string `yaml:"kind,omitempty"`
Source string `yaml:"source"`
Tracked bool `yaml:"tracked,omitempty"`
Group string `yaml:"group,omitempty"`
Branch string `yaml:"branch,omitempty"`
}
// localRegistry mirrors config.Registry without importing internal/config.
type localRegistry struct {
Skills []localRegistryEntry `yaml:"skills,omitempty"`
}
// migrateRegistryEntries reads registry.yaml in dir and merges matching entries into store.
// For skills dirs (kind=""), agent entries are skipped.
// For agents dirs (kind="agent"), skill entries are skipped.
func migrateRegistryEntries(store *MetadataStore, dir, kind string) {
registryPath := filepath.Join(dir, "registry.yaml")
data, err := os.ReadFile(registryPath)
if err != nil {
return
}
var reg localRegistry
if err := yaml.Unmarshal(data, &reg); err != nil {
return
}
for _, e := range reg.Skills {
if e.Name == "" || e.Source == "" {
continue
}
isAgent := e.Kind == "agent"
// Filter: skills dir skips agent entries, agents dir skips skill entries
if kind == "agent" && !isAgent {
continue
}
if kind == "" && isAgent {
continue
}
entry := store.Get(e.Name)
if entry == nil {
entry = &MetadataEntry{}
store.Set(e.Name, entry)
}
entry.Source = e.Source
entry.Kind = e.Kind
entry.Tracked = e.Tracked
entry.Group = e.Group
entry.Branch = e.Branch
}
}
// migrateSkillSidecars walks subdirectories of dir, looks for .skillshare-meta.json
// inside each, reads as SkillMeta, merges fields into store entry, and removes old sidecar.
func migrateSkillSidecars(store *MetadataStore, dir string) {
entries, err := os.ReadDir(dir)
if err != nil {
return
}
for _, de := range entries {
if !de.IsDir() {
continue
}
skillName := de.Name()
skillPath := filepath.Join(dir, skillName)
walkSkillDir(store, skillPath, skillName, "")
}
}
// walkSkillDir recursively walks a skill directory to find .skillshare-meta.json sidecars.
// group is the parent group prefix (empty for top-level skills).
func walkSkillDir(store *MetadataStore, skillPath, name, group string) {
sidecarPath := filepath.Join(skillPath, MetaFileName)
if _, err := os.Stat(sidecarPath); err == nil {
// This directory has a sidecar — it's a leaf skill
mergeSkillSidecar(store, name, group, sidecarPath)
os.Remove(sidecarPath)
return
}
// Check if this has subdirectories (nested skills)
subEntries, err := os.ReadDir(skillPath)
if err != nil {
return
}
for _, sub := range subEntries {
if sub.IsDir() {
subGroup := name
if group != "" {
subGroup = group + "/" + name
}
walkSkillDir(store, filepath.Join(skillPath, sub.Name()), sub.Name(), subGroup)
}
}
}
// mergeSkillSidecar reads a SkillMeta sidecar and merges its fields into the store.
func mergeSkillSidecar(store *MetadataStore, name, group, sidecarPath string) {
data, err := os.ReadFile(sidecarPath)
if err != nil {
return
}
var meta SkillMeta
if err := json.Unmarshal(data, &meta); err != nil {
return
}
entry := store.Get(name)
if entry == nil {
entry = &MetadataEntry{}
store.Set(name, entry)
}
// Merge sidecar fields — sidecar has richer data
if meta.Source != "" && entry.Source == "" {
entry.Source = meta.Source
}
if meta.Kind != "" {
entry.Kind = meta.Kind
}
if meta.Type != "" {
entry.Type = meta.Type
}
if !meta.InstalledAt.IsZero() {
entry.InstalledAt = meta.InstalledAt
}
if meta.RepoURL != "" {
entry.RepoURL = meta.RepoURL
}
if meta.Subdir != "" {
entry.Subdir = meta.Subdir
}
if meta.Version != "" {
entry.Version = meta.Version
}
if meta.TreeHash != "" {
entry.TreeHash = meta.TreeHash
}
if meta.FileHashes != nil {
entry.FileHashes = meta.FileHashes
}
if meta.Branch != "" && entry.Branch == "" {
entry.Branch = meta.Branch
}
if group != "" && entry.Group == "" {
entry.Group = group
}
}
// migrateAgentSidecars scans dir for *.skillshare-meta.json files, extracts agent name,
// reads as SkillMeta, merges into store with Kind="agent", removes old sidecar.
func migrateAgentSidecars(store *MetadataStore, dir string) {
entries, err := os.ReadDir(dir)
if err != nil {
return
}
const suffix = ".skillshare-meta.json"
for _, de := range entries {
if de.IsDir() {
continue
}
if !strings.HasSuffix(de.Name(), suffix) {
continue
}
agentName := strings.TrimSuffix(de.Name(), suffix)
if agentName == "" {
continue
}
sidecarPath := filepath.Join(dir, de.Name())
data, err := os.ReadFile(sidecarPath)
if err != nil {
continue
}
var meta SkillMeta
if err := json.Unmarshal(data, &meta); err != nil {
continue
}
entry := store.Get(agentName)
if entry == nil {
entry = &MetadataEntry{}
store.Set(agentName, entry)
}
if meta.Source != "" && entry.Source == "" {
entry.Source = meta.Source
}
entry.Kind = "agent"
if meta.Type != "" {
entry.Type = meta.Type
}
if !meta.InstalledAt.IsZero() {
entry.InstalledAt = meta.InstalledAt
}
if meta.RepoURL != "" {
entry.RepoURL = meta.RepoURL
}
if meta.Subdir != "" {
entry.Subdir = meta.Subdir
}
if meta.Version != "" {
entry.Version = meta.Version
}
if meta.TreeHash != "" {
entry.TreeHash = meta.TreeHash
}
if meta.FileHashes != nil {
entry.FileHashes = meta.FileHashes
}
if meta.Branch != "" && entry.Branch == "" {
entry.Branch = meta.Branch
}
os.Remove(sidecarPath)
}
}
// cleanupOldRegistry removes registry.yaml from dir (best-effort, ignores errors).
func cleanupOldRegistry(dir string) {
os.Remove(filepath.Join(dir, "registry.yaml"))
}
+288
View File
@@ -0,0 +1,288 @@
package install
import (
"encoding/json"
"os"
"path/filepath"
"testing"
"time"
)
// TestMigrateMetadata_FromSidecars verifies that a skill dir with a .skillshare-meta.json
// sidecar is migrated: entry appears in store, old sidecar removed, .metadata.json created.
func TestMigrateMetadata_FromSidecars(t *testing.T) {
dir := t.TempDir()
// Create skill dir with SKILL.md and sidecar
skillDir := filepath.Join(dir, "my-skill")
if err := os.MkdirAll(skillDir, 0755); err != nil {
t.Fatal(err)
}
os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("---\nname: my-skill\n---\n# Content"), 0644)
meta := &SkillMeta{
Source: "github.com/user/repo",
Type: "github",
RepoURL: "https://github.com/user/repo",
InstalledAt: time.Now(),
FileHashes: map[string]string{"SKILL.md": "sha256:abc123"},
}
writeSkillMetaSidecar(t, skillDir, meta)
store, err := LoadMetadataWithMigration(dir, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// Entry should be present
entry := store.Get("my-skill")
if entry == nil {
t.Fatal("expected entry 'my-skill' in store")
}
if entry.Source != "github.com/user/repo" {
t.Errorf("Source = %q, want %q", entry.Source, "github.com/user/repo")
}
if entry.RepoURL != "https://github.com/user/repo" {
t.Errorf("RepoURL = %q, want %q", entry.RepoURL, "https://github.com/user/repo")
}
if len(entry.FileHashes) == 0 {
t.Error("expected FileHashes to be populated")
}
// Old sidecar should be removed
sidecarPath := filepath.Join(skillDir, MetaFileName)
if _, err := os.Stat(sidecarPath); err == nil {
t.Error("expected old sidecar to be removed")
}
// .metadata.json should exist
if _, err := os.Stat(filepath.Join(dir, MetadataFileName)); err != nil {
t.Errorf(".metadata.json not created: %v", err)
}
}
// TestMigrateMetadata_FromRegistry verifies that registry.yaml entries are migrated
// and the old registry.yaml is removed.
func TestMigrateMetadata_FromRegistry(t *testing.T) {
dir := t.TempDir()
// Create skill dir (no sidecar)
skillDir := filepath.Join(dir, "team-skill")
if err := os.MkdirAll(skillDir, 0755); err != nil {
t.Fatal(err)
}
os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("---\nname: team-skill\n---\n"), 0644)
// Write registry.yaml
registryYAML := `skills:
- name: team-skill
source: github.com/org/repo
tracked: true
branch: main
`
os.WriteFile(filepath.Join(dir, "registry.yaml"), []byte(registryYAML), 0644)
store, err := LoadMetadataWithMigration(dir, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
entry := store.Get("team-skill")
if entry == nil {
t.Fatal("expected entry 'team-skill' in store")
}
if entry.Source != "github.com/org/repo" {
t.Errorf("Source = %q, want %q", entry.Source, "github.com/org/repo")
}
if !entry.Tracked {
t.Error("expected Tracked = true")
}
if entry.Branch != "main" {
t.Errorf("Branch = %q, want %q", entry.Branch, "main")
}
// Old registry.yaml should be removed
if _, err := os.Stat(filepath.Join(dir, "registry.yaml")); err == nil {
t.Error("expected old registry.yaml to be removed")
}
}
// TestMigrateMetadata_MergesRegistryAndSidecar verifies that registry fields (group, branch)
// and sidecar fields (repo_url, file_hashes) are merged into a single entry.
func TestMigrateMetadata_MergesRegistryAndSidecar(t *testing.T) {
dir := t.TempDir()
// Registry has group + branch
registryYAML := `skills:
- name: review
source: github.com/org/tools
group: frontend
branch: develop
`
os.WriteFile(filepath.Join(dir, "registry.yaml"), []byte(registryYAML), 0644)
// Sidecar has repo_url + file_hashes (inside group/name subdir)
skillDir := filepath.Join(dir, "review")
if err := os.MkdirAll(skillDir, 0755); err != nil {
t.Fatal(err)
}
meta := &SkillMeta{
Source: "github.com/org/tools",
Type: "github",
RepoURL: "https://github.com/org/tools",
FileHashes: map[string]string{"SKILL.md": "sha256:def456"},
}
writeSkillMetaSidecar(t, skillDir, meta)
store, err := LoadMetadataWithMigration(dir, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
entry := store.Get("review")
if entry == nil {
t.Fatal("expected entry 'review' in store")
}
// From registry
if entry.Group != "frontend" {
t.Errorf("Group = %q, want %q", entry.Group, "frontend")
}
if entry.Branch != "develop" {
t.Errorf("Branch = %q, want %q", entry.Branch, "develop")
}
// From sidecar
if entry.RepoURL != "https://github.com/org/tools" {
t.Errorf("RepoURL = %q, want %q", entry.RepoURL, "https://github.com/org/tools")
}
if len(entry.FileHashes) == 0 {
t.Error("expected FileHashes to be populated from sidecar")
}
}
// TestMigrateMetadata_Idempotent verifies that when .metadata.json already exists,
// it is loaded as-is without any migration being attempted.
func TestMigrateMetadata_Idempotent(t *testing.T) {
dir := t.TempDir()
// Pre-create .metadata.json with known content
existing := NewMetadataStore()
existing.Set("pre-existing", &MetadataEntry{
Source: "github.com/user/existing",
Kind: "skill",
})
if err := existing.Save(dir); err != nil {
t.Fatal(err)
}
// Also write a registry.yaml that should NOT be processed
registryYAML := `skills:
- name: new-skill
source: github.com/user/new
`
os.WriteFile(filepath.Join(dir, "registry.yaml"), []byte(registryYAML), 0644)
store, err := LoadMetadataWithMigration(dir, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// Should have the pre-existing entry
if !store.Has("pre-existing") {
t.Error("expected 'pre-existing' entry from .metadata.json")
}
// Should NOT have new-skill (migration was skipped)
if store.Has("new-skill") {
t.Error("migration should have been skipped — new-skill should not appear")
}
// registry.yaml should still exist (was not cleaned up)
if _, err := os.Stat(filepath.Join(dir, "registry.yaml")); err != nil {
t.Error("expected registry.yaml to still exist when migration was skipped")
}
}
// TestMigrateMetadata_AgentSidecars verifies that agent sidecar files
// (reviewer.skillshare-meta.json) are migrated with Kind="agent".
func TestMigrateMetadata_AgentSidecars(t *testing.T) {
dir := t.TempDir()
// Create reviewer.md (the agent file) and reviewer.skillshare-meta.json (sidecar)
os.WriteFile(filepath.Join(dir, "reviewer.md"), []byte("# Reviewer Agent"), 0644)
meta := &SkillMeta{
Source: "github.com/org/agents",
Type: "github",
RepoURL: "https://github.com/org/agents",
InstalledAt: time.Now(),
Version: "abc123",
}
sidecarPath := filepath.Join(dir, "reviewer"+".skillshare-meta.json")
data, err := json.MarshalIndent(meta, "", " ")
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(sidecarPath, data, 0644); err != nil {
t.Fatal(err)
}
store, err := LoadMetadataWithMigration(dir, "agent")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
entry := store.Get("reviewer")
if entry == nil {
t.Fatal("expected entry 'reviewer' in store")
}
if entry.Kind != "agent" {
t.Errorf("Kind = %q, want %q", entry.Kind, "agent")
}
if entry.RepoURL != "https://github.com/org/agents" {
t.Errorf("RepoURL = %q, want %q", entry.RepoURL, "https://github.com/org/agents")
}
if entry.Version != "abc123" {
t.Errorf("Version = %q, want %q", entry.Version, "abc123")
}
// Old sidecar should be removed
if _, err := os.Stat(sidecarPath); err == nil {
t.Error("expected agent sidecar to be removed after migration")
}
// .metadata.json should exist
if _, err := os.Stat(filepath.Join(dir, MetadataFileName)); err != nil {
t.Errorf(".metadata.json not created: %v", err)
}
}
// TestMigrateMetadata_EmptyDir verifies that an empty dir returns an empty store without error.
func TestMigrateMetadata_EmptyDir(t *testing.T) {
dir := t.TempDir()
store, err := LoadMetadataWithMigration(dir, "")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(store.Entries) != 0 {
t.Errorf("expected empty store, got %d entries", len(store.Entries))
}
// .metadata.json should NOT be created when nothing was migrated
if _, err := os.Stat(filepath.Join(dir, MetadataFileName)); err == nil {
t.Error("expected .metadata.json to not be created for empty dir")
}
}
// writeSkillMetaSidecar is a test helper that writes a .skillshare-meta.json sidecar
// inside the given skill directory.
func writeSkillMetaSidecar(t *testing.T, skillDir string, meta *SkillMeta) {
t.Helper()
data, err := json.MarshalIndent(meta, "", " ")
if err != nil {
t.Fatalf("marshal SkillMeta: %v", err)
}
path := filepath.Join(skillDir, MetaFileName)
if err := os.WriteFile(path, data, 0644); err != nil {
t.Fatalf("write sidecar: %v", err)
}
}