From fcbfd39be2d6095788bbfdf64f22e1373c3c7647 Mon Sep 17 00:00:00 2001 From: Willie Date: Fri, 29 May 2026 10:27:19 +0800 Subject: [PATCH] refactor(extensions): describe and rename built-ins by output md2codex / md2gemini named the *input* (markdown) and read poorly. Rename the bundled extensions after what they produce: codex-agents and gemini-commands. Turn the BuiltinExtensions catalog into structs carrying a human-readable description so the dashboard can explain each one before install, and propagate the new names across tests and docs. --- cmd/skillshare/extension_resolve_test.go | 4 +-- internal/config/config_resource_test.go | 6 ++-- internal/install/extension_install.go | 32 ++++++++++++++++---- internal/install/extension_install_test.go | 11 ++++--- internal/server/handler_extensions.go | 14 +++++---- internal/server/handler_extensions_test.go | 24 ++++++++------- internal/server/handler_extras_test.go | 34 +++++++++++----------- internal/sync/extension_test.go | 12 ++++---- website/docs/reference/commands/extras.md | 10 +++---- 9 files changed, 89 insertions(+), 58 deletions(-) diff --git a/cmd/skillshare/extension_resolve_test.go b/cmd/skillshare/extension_resolve_test.go index de9274309..218063103 100644 --- a/cmd/skillshare/extension_resolve_test.go +++ b/cmd/skillshare/extension_resolve_test.go @@ -29,7 +29,7 @@ func TestValidateExtensionMode(t *testing.T) { func TestResolveExtension_BareNameInDir(t *testing.T) { dir := t.TempDir() - extDir := filepath.Join(dir, "md2gemini") + extDir := filepath.Join(dir, "gemini-commands") if err := os.MkdirAll(extDir, 0755); err != nil { t.Fatal(err) } @@ -37,7 +37,7 @@ func TestResolveExtension_BareNameInDir(t *testing.T) { []byte("run: [\"cat\"]\noutput_ext: toml\n"), 0644); err != nil { t.Fatal(err) } - spec, err := resolveExtension("md2gemini", dir) + spec, err := resolveExtension("gemini-commands", dir) if err != nil { t.Fatalf("resolveExtension: %v", err) } diff --git a/internal/config/config_resource_test.go b/internal/config/config_resource_test.go index c8619ea5f..d0522ee09 100644 --- a/internal/config/config_resource_test.go +++ b/internal/config/config_resource_test.go @@ -180,12 +180,12 @@ func TestMigrateTargetConfigs_MixedFormat_NoOverwrite(t *testing.T) { } func TestExtraTargetConfig_ExtensionField(t *testing.T) { - data := []byte("path: .gemini/commands\nextension: md2gemini\n") + data := []byte("path: .gemini/commands\nextension: gemini-commands\n") var tc ExtraTargetConfig if err := yaml.Unmarshal(data, &tc); err != nil { t.Fatalf("unmarshal: %v", err) } - if tc.Extension != "md2gemini" { - t.Errorf("Extension = %q, want %q", tc.Extension, "md2gemini") + if tc.Extension != "gemini-commands" { + t.Errorf("Extension = %q, want %q", tc.Extension, "gemini-commands") } } diff --git a/internal/install/extension_install.go b/internal/install/extension_install.go index e2589feb8..089b24215 100644 --- a/internal/install/extension_install.go +++ b/internal/install/extension_install.go @@ -6,15 +6,37 @@ import ( "slices" ) -// BuiltinExtensions lists the transform extensions bundled in the skillshare -// repo under extensions/. The dashboard offers these for one-click install so -// users don't have to copy the reference scripts by hand. -var BuiltinExtensions = []string{"md2codex", "md2gemini"} +// BuiltinExtension is one transform extension bundled in the skillshare repo +// under extensions/, with a human-readable description so the dashboard can +// explain what it does before it is installed. +type BuiltinExtension struct { + Name string + Description string +} + +// BuiltinExtensions is the catalog of bundled transform extensions. The +// dashboard offers these for one-click install so users don't have to copy the +// reference scripts by hand. +var BuiltinExtensions = []BuiltinExtension{ + {Name: "codex-agents", Description: "Convert Markdown subagents (Claude format) into Codex CLI TOML agents"}, + {Name: "gemini-commands", Description: "Convert Markdown slash-commands (Claude/Cursor format) into Gemini CLI TOML commands"}, +} // IsBuiltinExtension reports whether name is a known bundled extension. It // doubles as a whitelist guard against path traversal in download requests. func IsBuiltinExtension(name string) bool { - return slices.Contains(BuiltinExtensions, name) + return slices.ContainsFunc(BuiltinExtensions, func(b BuiltinExtension) bool { return b.Name == name }) +} + +// BuiltinExtensionDescription returns the catalog description for name, or an +// empty string if name is not a bundled extension. +func BuiltinExtensionDescription(name string) string { + for _, b := range BuiltinExtensions { + if b.Name == name { + return b.Description + } + } + return "" } // InstallBuiltinExtension downloads the bundled extension `name` from the diff --git a/internal/install/extension_install_test.go b/internal/install/extension_install_test.go index a2002dee3..0648a4cfe 100644 --- a/internal/install/extension_install_test.go +++ b/internal/install/extension_install_test.go @@ -3,12 +3,15 @@ package install import "testing" func TestIsBuiltinExtension(t *testing.T) { - for _, name := range BuiltinExtensions { - if !IsBuiltinExtension(name) { - t.Errorf("%q should be a built-in extension", name) + for _, b := range BuiltinExtensions { + if !IsBuiltinExtension(b.Name) { + t.Errorf("%q should be a built-in extension", b.Name) + } + if b.Description == "" { + t.Errorf("built-in %q must have a catalog description", b.Name) } } - for _, bad := range []string{"", "../evil", "md2codex/..", "unknown"} { + for _, bad := range []string{"", "../evil", "codex-agents/..", "unknown"} { if IsBuiltinExtension(bad) { t.Errorf("%q must not be reported as built-in", bad) } diff --git a/internal/server/handler_extensions.go b/internal/server/handler_extensions.go index 16dd6c876..4fc1ea5d0 100644 --- a/internal/server/handler_extensions.go +++ b/internal/server/handler_extensions.go @@ -44,23 +44,27 @@ func (s *Server) handleExtensionsList(w http.ResponseWriter, r *http.Request) { seen := make(map[string]bool, len(names)) for _, name := range names { info := extensionInfo{Name: name, Builtin: install.IsBuiltinExtension(name), Installed: true} - if spec, derr := syncpkg.LoadExtensionSpec(filepath.Join(dir, name), name); derr == nil { + // Built-ins use the catalog description (consistent, formal wording); + // local extensions fall back to their own extension.yaml description. + if info.Builtin { + info.Description = install.BuiltinExtensionDescription(name) + } else if spec, derr := syncpkg.LoadExtensionSpec(filepath.Join(dir, name), name); derr == nil { info.Description = spec.Description } infos = append(infos, info) seen[name] = true } // Append built-ins that aren't installed yet (available to download). - for _, name := range install.BuiltinExtensions { - if !seen[name] { - infos = append(infos, extensionInfo{Name: name, Builtin: true, Installed: false}) + for _, b := range install.BuiltinExtensions { + if !seen[b.Name] { + infos = append(infos, extensionInfo{Name: b.Name, Description: b.Description, Builtin: true, Installed: false}) } } writeJSON(w, map[string]any{"extensions": infos}) } -// handleExtensionsInstall — POST /api/extensions/install {"name": "md2codex"} +// handleExtensionsInstall — POST /api/extensions/install {"name": "codex-agents"} // Downloads a built-in extension into the current mode's extensions directory. func (s *Server) handleExtensionsInstall(w http.ResponseWriter, r *http.Request) { start := time.Now() diff --git a/internal/server/handler_extensions_test.go b/internal/server/handler_extensions_test.go index 83c325bac..aa72de608 100644 --- a/internal/server/handler_extensions_test.go +++ b/internal/server/handler_extensions_test.go @@ -10,6 +10,7 @@ import ( "testing" "skillshare/internal/config" + "skillshare/internal/install" ) // writeExtensionWithDescription creates a directory-form extension carrying a @@ -33,8 +34,8 @@ func TestHandleExtensionsList(t *testing.T) { s, _ := newTestServerWithExtras(t, nil, "") extRoot := filepath.Join(filepath.Dir(config.ConfigPath()), "extensions") - // One installed built-in (md2codex) and one installed local extension. - writeExtensionWithDescription(t, extRoot, "md2codex", "Markdown to Codex") + // One installed built-in (codex-agents) and one installed local extension. + writeExtensionWithDescription(t, extRoot, "codex-agents", "Markdown to Codex") writeExtensionWithDescription(t, extRoot, "my-local", "Local transform") req := httptest.NewRequest(http.MethodGet, "/api/extensions", nil) @@ -56,11 +57,12 @@ func TestHandleExtensionsList(t *testing.T) { byName[e.Name] = e } - // Installed built-in: installed + builtin + description. - if got, ok := byName["md2codex"]; !ok { - t.Error("md2codex missing from list") - } else if !got.Installed || !got.Builtin || got.Description != "Markdown to Codex" { - t.Errorf("md2codex = %+v, want installed builtin with description", got) + // Installed built-in: installed + builtin + catalog description (the + // catalog wins over the on-disk extension.yaml for built-ins). + if got, ok := byName["codex-agents"]; !ok { + t.Error("codex-agents missing from list") + } else if !got.Installed || !got.Builtin || got.Description != install.BuiltinExtensionDescription("codex-agents") { + t.Errorf("codex-agents = %+v, want installed builtin with catalog description", got) } // Installed local extension: installed, NOT builtin. @@ -70,11 +72,11 @@ func TestHandleExtensionsList(t *testing.T) { t.Errorf("my-local = %+v, want installed non-builtin", got) } - // Built-in not installed yet (md2gemini): available to download. - if got, ok := byName["md2gemini"]; !ok { - t.Error("md2gemini missing from list (should appear as available built-in)") + // Built-in not installed yet (gemini-commands): available to download. + if got, ok := byName["gemini-commands"]; !ok { + t.Error("gemini-commands missing from list (should appear as available built-in)") } else if got.Installed || !got.Builtin { - t.Errorf("md2gemini = %+v, want builtin and not installed", got) + t.Errorf("gemini-commands = %+v, want builtin and not installed", got) } } diff --git a/internal/server/handler_extras_test.go b/internal/server/handler_extras_test.go index 1bf1647ff..3223593be 100644 --- a/internal/server/handler_extras_test.go +++ b/internal/server/handler_extras_test.go @@ -260,7 +260,7 @@ func TestHandleExtrasCreate_WithExtension(t *testing.T) { targetDir := t.TempDir() // Request mode "merge" but with an extension — should be coerced to copy. - body := `{"name":"agents","targets":[{"path":"` + targetDir + `","mode":"merge","extension":"md2codex"}]}` + body := `{"name":"agents","targets":[{"path":"` + targetDir + `","mode":"merge","extension":"codex-agents"}]}` req := httptest.NewRequest(http.MethodPost, "/api/extras", strings.NewReader(body)) rr := httptest.NewRecorder() s.handler.ServeHTTP(rr, req) @@ -283,8 +283,8 @@ func TestHandleExtrasCreate_WithExtension(t *testing.T) { t.Fatalf("expected 1 target, got %d", len(e.Targets)) } tt := e.Targets[0] - if tt.Extension != "md2codex" { - t.Errorf("extension = %q, want md2codex", tt.Extension) + if tt.Extension != "codex-agents" { + t.Errorf("extension = %q, want codex-agents", tt.Extension) } if tt.Mode != "copy" { t.Errorf("mode = %q, want copy (extension implies copy)", tt.Mode) @@ -410,8 +410,8 @@ func TestHandleExtrasExtensions(t *testing.T) { s, _ := newTestServerWithExtras(t, nil, "") extRoot := filepath.Join(filepath.Dir(config.ConfigPath()), "extensions") - writeExtension(t, extRoot, "md2codex") - writeExtension(t, extRoot, "md2gemini") + writeExtension(t, extRoot, "codex-agents") + writeExtension(t, extRoot, "gemini-commands") req := httptest.NewRequest(http.MethodGet, "/api/extras/extensions", nil) rr := httptest.NewRecorder() @@ -426,8 +426,8 @@ func TestHandleExtrasExtensions(t *testing.T) { if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil { t.Fatalf("parse: %v", err) } - if len(resp.Extensions) != 2 || resp.Extensions[0] != "md2codex" || resp.Extensions[1] != "md2gemini" { - t.Errorf("got %v, want [md2codex md2gemini]", resp.Extensions) + if len(resp.Extensions) != 2 || resp.Extensions[0] != "codex-agents" || resp.Extensions[1] != "gemini-commands" { + t.Errorf("got %v, want [codex-agents gemini-commands]", resp.Extensions) } } @@ -437,7 +437,7 @@ func TestHandleExtrasExtensions_ProjectMode(t *testing.T) { s, projectRoot := newTestProjectServerWithExtras(t, nil) extRoot := filepath.Join(projectRoot, ".skillshare", "extensions") - writeExtension(t, extRoot, "md2codex") + writeExtension(t, extRoot, "codex-agents") req := httptest.NewRequest(http.MethodGet, "/api/extras/extensions", nil) rr := httptest.NewRecorder() @@ -452,8 +452,8 @@ func TestHandleExtrasExtensions_ProjectMode(t *testing.T) { if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil { t.Fatalf("parse: %v", err) } - if len(resp.Extensions) != 1 || resp.Extensions[0] != "md2codex" { - t.Errorf("got %v, want [md2codex]", resp.Extensions) + if len(resp.Extensions) != 1 || resp.Extensions[0] != "codex-agents" { + t.Errorf("got %v, want [codex-agents]", resp.Extensions) } } @@ -467,7 +467,7 @@ func TestHandleExtrasMode_ExtensionImpliesCopy(t *testing.T) { }} s, _ := newTestServerWithExtras(t, extras, "") - body := `{"target":"` + targetDir + `","extension":"md2codex"}` + body := `{"target":"` + targetDir + `","extension":"codex-agents"}` req := httptest.NewRequest(http.MethodPatch, "/api/extras/agents/mode", strings.NewReader(body)) rr := httptest.NewRecorder() s.handler.ServeHTTP(rr, req) @@ -479,8 +479,8 @@ func TestHandleExtrasMode_ExtensionImpliesCopy(t *testing.T) { s.mu.RLock() tt := s.cfg.Extras[0].Targets[0] s.mu.RUnlock() - if tt.Extension != "md2codex" { - t.Errorf("extension = %q, want md2codex", tt.Extension) + if tt.Extension != "codex-agents" { + t.Errorf("extension = %q, want codex-agents", tt.Extension) } if tt.Mode != "copy" { t.Errorf("mode = %q, want copy (extension implies copy)", tt.Mode) @@ -497,7 +497,7 @@ func TestHandleExtrasMode_ExtensionRejectsNonCopy(t *testing.T) { }} s, _ := newTestServerWithExtras(t, extras, "") - body := `{"target":"` + targetDir + `","mode":"symlink","extension":"md2codex"}` + body := `{"target":"` + targetDir + `","mode":"symlink","extension":"codex-agents"}` req := httptest.NewRequest(http.MethodPatch, "/api/extras/agents/mode", strings.NewReader(body)) rr := httptest.NewRecorder() s.handler.ServeHTTP(rr, req) @@ -513,7 +513,7 @@ func TestHandleExtras_IncludesExtension(t *testing.T) { targetDir := t.TempDir() extras := []config.ExtraConfig{{ Name: "agents", - Targets: []config.ExtraTargetConfig{{Path: targetDir, Mode: "copy", Extension: "md2codex"}}, + Targets: []config.ExtraTargetConfig{{Path: targetDir, Mode: "copy", Extension: "codex-agents"}}, }} s, _ := newTestServerWithExtras(t, extras, "") @@ -537,8 +537,8 @@ func TestHandleExtras_IncludesExtension(t *testing.T) { if len(resp.Extras) != 1 || len(resp.Extras[0].Targets) != 1 { t.Fatalf("unexpected shape: %s", rr.Body.String()) } - if resp.Extras[0].Targets[0].Extension != "md2codex" { - t.Errorf("extension = %q, want md2codex", resp.Extras[0].Targets[0].Extension) + if resp.Extras[0].Targets[0].Extension != "codex-agents" { + t.Errorf("extension = %q, want codex-agents", resp.Extras[0].Targets[0].Extension) } } diff --git a/internal/sync/extension_test.go b/internal/sync/extension_test.go index 3ef49451a..6eb86743b 100644 --- a/internal/sync/extension_test.go +++ b/internal/sync/extension_test.go @@ -9,7 +9,7 @@ import ( func TestLoadExtensionSpec_Directory(t *testing.T) { dir := t.TempDir() - extDir := filepath.Join(dir, "md2gemini") + extDir := filepath.Join(dir, "gemini-commands") if err := os.MkdirAll(extDir, 0755); err != nil { t.Fatal(err) } @@ -18,7 +18,7 @@ func TestLoadExtensionSpec_Directory(t *testing.T) { t.Fatal(err) } - spec, err := LoadExtensionSpec(extDir, "md2gemini") + spec, err := LoadExtensionSpec(extDir, "gemini-commands") if err != nil { t.Fatalf("LoadExtensionSpec: %v", err) } @@ -61,11 +61,11 @@ func TestListExtensions(t *testing.T) { dir := t.TempDir() // (a) directory-form extension (has extension.yaml) - md2gemini := filepath.Join(dir, "md2gemini") - if err := os.MkdirAll(md2gemini, 0755); err != nil { + geminiDir := filepath.Join(dir, "gemini-commands") + if err := os.MkdirAll(geminiDir, 0755); err != nil { t.Fatal(err) } - if err := os.WriteFile(filepath.Join(md2gemini, "extension.yaml"), []byte("run: [\"cat\"]\n"), 0644); err != nil { + if err := os.WriteFile(filepath.Join(geminiDir, "extension.yaml"), []byte("run: [\"cat\"]\n"), 0644); err != nil { t.Fatal(err) } // (b) single-file executable extension @@ -85,7 +85,7 @@ func TestListExtensions(t *testing.T) { if err != nil { t.Fatalf("ListExtensions: %v", err) } - want := []string{"conv.sh", "md2gemini"} // sorted + want := []string{"conv.sh", "gemini-commands"} // sorted if len(got) != len(want) { t.Fatalf("got %v, want %v", got, want) } diff --git a/website/docs/reference/commands/extras.md b/website/docs/reference/commands/extras.md index bd7fa8b09..2fc027a2a 100644 --- a/website/docs/reference/commands/extras.md +++ b/website/docs/reference/commands/extras.md @@ -275,7 +275,7 @@ extras: targets: - path: .claude/commands # no extension — synced as-is - path: .gemini/commands - extension: md2gemini # transform during sync + extension: gemini-commands # transform during sync ``` **Resolution** — a bare name resolves under the extensions directory (`~/.config/skillshare/extensions/` global, `.skillshare/extensions/` project); a path (`./x.sh`, `/abs/x`) is used directly. @@ -289,7 +289,7 @@ extras: A single executable, or a directory with a manifest: ``` -.skillshare/extensions/md2gemini/ +.skillshare/extensions/gemini-commands/ ├── extension.yaml └── convert.js ``` @@ -316,11 +316,11 @@ The mechanism is cross-platform; whether an extension runs depends on its interp ### Reference extensions -The skillshare repo ships example extensions under `extensions/` (`md2gemini`, `md2codex`). Copy one into your extensions directory and adapt it — they are references, not installed automatically. +The skillshare repo ships example extensions under `extensions/` (`gemini-commands`, `codex-agents`). Copy one into your extensions directory and adapt it — they are references, not installed automatically. ### Recipe: Codex agents -Codex CLI expects TOML agents rather than markdown. Because a `source` can point at any directory, you can reuse your agents source as an extras source and transform it with `md2codex`: +Codex CLI expects TOML agents rather than markdown. Because a `source` can point at any directory, you can reuse your agents source as an extras source and transform it with `codex-agents`: ```yaml extras: @@ -328,7 +328,7 @@ extras: source: ~/.config/skillshare/agents # reuse the agents source targets: - path: ~/.codex/agents - extension: md2codex + extension: codex-agents ``` `skillshare sync extras` converts each `.md` into `~/.codex/agents/.toml`, mapping frontmatter `name`, `description`, and `model` and folding the markdown body into `developer_instructions` (other frontmatter keys are dropped). No separate copy of the agents is needed.