From ce6be175d4986ef73faef331c2c945be1b26c671 Mon Sep 17 00:00:00 2001 From: Willie Date: Wed, 8 Apr 2026 10:39:43 +0800 Subject: [PATCH] feat: add migration from old sidecar + registry to .metadata.json MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- internal/install/metadata_migrate.go | 280 +++++++++++++++++++++ internal/install/metadata_migrate_test.go | 288 ++++++++++++++++++++++ 2 files changed, 568 insertions(+) create mode 100644 internal/install/metadata_migrate.go create mode 100644 internal/install/metadata_migrate_test.go diff --git a/internal/install/metadata_migrate.go b/internal/install/metadata_migrate.go new file mode 100644 index 000000000..575847f9c --- /dev/null +++ b/internal/install/metadata_migrate.go @@ -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, ®); 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")) +} diff --git a/internal/install/metadata_migrate_test.go b/internal/install/metadata_migrate_test.go new file mode 100644 index 000000000..0be70f236 --- /dev/null +++ b/internal/install/metadata_migrate_test.go @@ -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) + } +}