From 6215ac02d27b37ba87d6f55ae7eccbc7781f246a Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Sun, 20 Sep 2026 10:02:39 +0800 Subject: [PATCH 1/9] fix: split the missing-manifest advice by scope and offer --global MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A project command without SKILL.mod usually means the user is standing in the wrong directory — most often $HOME, whose installation directories are the global scope's — so the project advice now offers --global before suggesting init, and the global scope gets its own advice spelling skillmod --global init/get instead of reusing the project wording. Pins updated per the wording contract; adoption share behavior is unchanged. --- internal/engine/engine.go | 10 ++++++ internal/engine/manifest_advice_test.go | 45 +++++++++++++++++++++++++ internal/i18n/i18n_test.go | 3 +- locales/en_US.po | 8 +++-- locales/zh_CN.po | 8 ++++- 5 files changed, 70 insertions(+), 4 deletions(-) create mode 100644 internal/engine/manifest_advice_test.go diff --git a/internal/engine/engine.go b/internal/engine/engine.go index 1521a86..3fede0f 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -149,6 +149,16 @@ func (e *Engine) saveState(m *modfile.Mod, lock *modfile.Lock) error { func (e *Engine) loadMod() (*modfile.Mod, error) { m, err := modfile.LoadMod(e.manifestRoot()) if os.IsNotExist(err) { + // The advice differs by scope because the recovery paths differ. A + // project without a manifest usually means the user is standing in + // the wrong directory — most often $HOME, whose installation + // directories are the global scope's — so the project message offers + // --global as the likely intent before suggesting init. The global + // scope has exactly one recovery path, spelled with the same flag + // that selects it. + if e.ManifestRoot != "" { + return nil, fmt.Errorf("%s", i18n.Text("engine.skill_mod_found_advice_global")) + } return nil, fmt.Errorf("%s", i18n.Text("engine.skill_mod_found_advice")) } return m, err diff --git a/internal/engine/manifest_advice_test.go b/internal/engine/manifest_advice_test.go new file mode 100644 index 0000000..3cb3070 --- /dev/null +++ b/internal/engine/manifest_advice_test.go @@ -0,0 +1,45 @@ +// Copyright 2026 huija +// +// SPDX-License-Identifier: MIT + +package engine_test + +import ( + "path/filepath" + "strings" + "testing" + + "github.com/huija/skillmod/internal/engine" +) + +// The missing-manifest advice is a recovery contract: it must name the paths +// that actually recover the user. A project without a manifest is usually a +// user standing in $HOME — whose installation directories are the global +// scope's — so the project advice offers --global before suggesting init; +// the global advice spells the same flag the command already needs. Rewording +// either message also updates TestContractWordingIsPinned in the same change. +func TestMissingManifestAdviceNamesScopeRecoveryPaths(t *testing.T) { + project := newEngine(t, t.TempDir(), t.TempDir()) + _, err := project.Sync(ctx, engine.SyncOptions{}, testIO()) + if err == nil { + t.Fatal("Sync(project without manifest) = nil, want missing-manifest error") + } + for _, want := range []string{"SKILL.mod not found", "skillmod init", "--global"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("Sync(project without manifest) = %q, want advice containing %q", err, want) + } + } + + global := newEngine(t, t.TempDir(), t.TempDir()) + global.ManifestRoot = filepath.Join(global.Store.Root(), "global") + _, err = global.Sync(ctx, engine.SyncOptions{}, testIO()) + if err == nil { + t.Fatal("Sync(global without manifest) = nil, want missing-manifest error") + } + if !strings.Contains(err.Error(), "--global init") { + t.Errorf("Sync(global without manifest) = %q, want advice containing --global init", err) + } + if strings.Contains(err.Error(), "project") { + t.Errorf("Sync(global without manifest) = %q, want no project-scoped advice", err) + } +} diff --git a/internal/i18n/i18n_test.go b/internal/i18n/i18n_test.go index 8a7b3e6..14f27b7 100644 --- a/internal/i18n/i18n_test.go +++ b/internal/i18n/i18n_test.go @@ -183,7 +183,8 @@ func TestContractWordingIsPinned(t *testing.T) { english := englishCatalog(t) pinned := map[string]string{ "resolve.branch_not_lockable": "branches cannot be locked; use a tag or commit SHA (%q is a branch name)", - "engine.skill_mod_found_advice": "SKILL.mod not found\nAdvice: run skillmod init or skillmod get first", + "engine.skill_mod_found_advice": "SKILL.mod not found\nAdvice: run skillmod init or skillmod get to manage this directory as a project, or add --global to manage global skills", + "engine.skill_mod_found_advice_global": "SKILL.mod not found\nAdvice: run skillmod --global init or skillmod --global get to manage global skills", "engine.verify.skill_lock_found_advice": "SKILL.lock not found\nAdvice: run skillmod sync first to generate the lock file", "cli.get.use": "get [//][@]", "cli.remove.use": "remove [names…]", diff --git a/locales/en_US.po b/locales/en_US.po index fe689b5..370de0a 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -882,8 +882,12 @@ msgstr "SKILL.lock is tool-maintained; repair the listed entry by hand, or " "back up and delete the file, then re-run skillmod sync to regenerate it" msgid "engine.skill_mod_found_advice" -msgstr "SKILL.mod not found\nAdvice: run skillmod init or skillmod get firs" -"t" +msgstr "SKILL.mod not found\nAdvice: run skillmod init or skillmod get to m" +"anage this directory as a project, or add --global to manage global skills" + +msgid "engine.skill_mod_found_advice_global" +msgstr "SKILL.mod not found\nAdvice: run skillmod --global init or skillmod" +" --global get to manage global skills" #, go-format msgid "engine.skill_path_not_materializable" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index 226f6fc..9b6c736 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -865,7 +865,13 @@ msgstr "SKILL.lock 由工具维护;请手工修复出错的条目,或" "备份并删除该文件后重新运行 skillmod sync 重新生成" msgid "engine.skill_mod_found_advice" -msgstr "未找到 SKILL.mod\n建议先执行 skillmod init 或 skillmod get" +msgstr "未找到 SKILL.mod\n建议:执行 skillmod init 或 skillmod get" +" 将当前目录作为项目管理;若要管理全局技能,请在命" +"令中加入 --global" + +msgid "engine.skill_mod_found_advice_global" +msgstr "未找到 SKILL.mod\n建议先执行 skillmod --global init 或 ski" +"llmod --global get 管理全局技能" #, go-format msgid "engine.skill_path_not_materializable" From 314dc1176dae183b6ffda017449548902886dbf1 Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:40:12 +0800 Subject: [PATCH 2/9] feat: complete a bare owner/repo address with github.com A bare path like openai/skills used to become https://openai/skills, which only resolves when the first segment happens to be a host. Complete a two-segment path without a dotted first segment with github.com instead, because that is where skill repositories overwhelmingly live, so skillmod get openai/skills//gh-fix-ci now works. A first segment that carries a dot stays a host, a port or Windows drive letter is left alone, and filesystem paths are untouched. The manifest still records the short form, so the expansion is invisible in SKILL.mod. --- internal/address/address.go | 33 +++++++++++++++++--- internal/address/address_test.go | 14 +++++++++ internal/engine/engine_internal_test.go | 41 +++++++++++++++++++++++++ internal/engine/get.go | 16 ++++++++++ locales/en_US.po | 5 +++ locales/zh_CN.po | 5 +++ 6 files changed, 109 insertions(+), 5 deletions(-) diff --git a/internal/address/address.go b/internal/address/address.go index 328a1ac..fe897b3 100644 --- a/internal/address/address.go +++ b/internal/address/address.go @@ -20,6 +20,10 @@ type Address struct { Repo string // normalized Git address; bare paths include an https:// prefix Subdir string // subdirectory within the repository; empty means the repository root Ref string // explicit version reference; empty asks package resolve for the latest version + // Completed records that a bare owner/repo input was extended with the + // default host. The fetch failure of such an address names a URL the raw + // input never contained, so callers surface the resolution alongside it. + Completed bool } // String returns the canonical address. @@ -37,6 +41,9 @@ func (a *Address) String() string { // scpLike matches git@host:path addresses, where @ is not a version separator. var scpLike = regexp.MustCompile(`^[^/@\s:]+@[^/@\s:]+:`) +// defaultGitHubHost is the host a bare owner/repo path is resolved against. +const defaultGitHubHost = "github.com" + // Parse validates and normalizes an address without accessing the network. // Branch names are rejected later by package resolve using ls-remote data rather than string heuristics. func Parse(raw string) (*Address, error) { @@ -65,7 +72,7 @@ func Parse(raw string) (*Address, error) { if strings.ContainsAny(repo, " \t") { return nil, fmt.Errorf(i18n.Text("address.repository_whitespace"), repoaddr.Redact(repo)) } - repo = normalizeRepo(repo) + repo, completed := normalizeRepo(repo) repo, err = repoaddr.PersistedTransport(repo) if err != nil { return nil, err @@ -76,7 +83,7 @@ func Parse(raw string) (*Address, error) { return nil, err } } - return &Address{Repo: repo, Subdir: subdir, Ref: ref}, nil + return &Address{Repo: repo, Subdir: subdir, Ref: ref, Completed: completed}, nil } // splitRef splits at the final @ that acts as a version separator. Explicit @@ -122,11 +129,27 @@ func splitSubdir(s string) (repo, subdir string, err error) { } // normalizeRepo adds https:// to bare paths and preserves full URLs and scp-like addresses. -func normalizeRepo(repo string) string { +// A bare owner/repo path defaults to github.com, because that is where skill +// repositories overwhelmingly live; a first segment that already carries a dot +// is a host, and one that is empty, "." or ".." reads as a filesystem path. +// Neither of those two takes the github.com default, though both still come +// back with the https:// prefix that every bare path gains. +// The second result reports whether that default was applied. +func normalizeRepo(repo string) (string, bool) { if strings.Contains(repo, "://") || scpLike.MatchString(repo) { - return repo + return repo, false + } + if first, _, found := strings.Cut(repo, "/"); found { + switch { + case first == "" || first == "." || first == "..": + // A filesystem path, absolute or relative. + case strings.ContainsAny(first, ".:"): + // A host, possibly with a port, or a Windows drive letter. + default: + return "https://" + defaultGitHubHost + "/" + repo, true + } } - return "https://" + repo + return "https://" + repo, false } // ManifestSource returns the address form recorded in SKILL.mod and SKILL.lock. diff --git a/internal/address/address_test.go b/internal/address/address_test.go index 61eb640..546a97f 100644 --- a/internal/address/address_test.go +++ b/internal/address/address_test.go @@ -25,6 +25,18 @@ func TestParse(t *testing.T) { {"bare repository with subdirectory", "github.com/a/b//sub", &Address{Repo: "https://github.com/a/b", Subdir: "sub"}, ""}, {"bare repository with subdirectory and version", "github.com/a/b//sub@v1.2.0", &Address{Repo: "https://github.com/a/b", Subdir: "sub", Ref: "v1.2.0"}, ""}, {"bare repository with version", "github.com/a/b@v1.2.0", &Address{Repo: "https://github.com/a/b", Ref: "v1.2.0"}, ""}, + // A bare owner/repo path defaults to github.com, and the parse result + // records that the host was added, so a failed fetch can name it. + {"owner/repo defaults to github", "openai/skills", &Address{Repo: "https://github.com/openai/skills", Completed: true}, ""}, + {"owner/repo with subdirectory", "openai/skills//gh-fix-ci", &Address{Repo: "https://github.com/openai/skills", Subdir: "gh-fix-ci", Completed: true}, ""}, + {"owner/repo with version", "openai/skills@v1.0.0", &Address{Repo: "https://github.com/openai/skills", Ref: "v1.0.0", Completed: true}, ""}, + // Any other first segment is a host, not an owner. + {"host with port", "localhost:8080/a/b", &Address{Repo: "https://localhost:8080/a/b"}, ""}, + // A first segment that reads as a path is not an owner, so it is left + // alone rather than completed with a host that cannot exist. + {"relative current directory", "./a/b", &Address{Repo: "https://./a/b"}, ""}, + {"relative parent directory", "../a/b", &Address{Repo: "https://../a/b"}, ""}, + {"windows drive letter", "C:/x/y", &Address{Repo: "https://C:/x/y"}, ""}, // Preserve a complete URL. {"https", "https://github.com/a/b", &Address{Repo: "https://github.com/a/b"}, ""}, {"https with subdirectory", "https://github.com/a/b//sub/dir@v2.0.0", &Address{Repo: "https://github.com/a/b", Subdir: "sub/dir", Ref: "v2.0.0"}, ""}, @@ -122,6 +134,8 @@ func TestManifestSource_DropsImpliedHTTPSAndKeepsExplicitTransports(t *testing.T }{ {"bare path is already canonical", "github.com/a/b", "github.com/a/b"}, {"https prefix is not recorded", "https://github.com/a/b", "github.com/a/b"}, + {"owner/repo records the default host", "openai/skills", "github.com/openai/skills"}, + {"owner/repo with subdirectory", "openai/skills//gh-fix-ci", "github.com/openai/skills//gh-fix-ci"}, {"uppercase https prefix is not recorded", "HTTPS://github.com/a/b", "github.com/a/b"}, {"https with subdirectory", "https://github.com/a/b//sub/dir", "github.com/a/b//sub/dir"}, {"non-default port survives", "https://github.com:8443/a/b", "github.com:8443/a/b"}, diff --git a/internal/engine/engine_internal_test.go b/internal/engine/engine_internal_test.go index d557cba..4d7d2cb 100644 --- a/internal/engine/engine_internal_test.go +++ b/internal/engine/engine_internal_test.go @@ -15,6 +15,8 @@ import ( "testing" "time" + "github.com/huija/skillmod/internal/address" + "github.com/huija/skillmod/internal/config" "github.com/huija/skillmod/internal/dirhash" "github.com/huija/skillmod/internal/modfile" "github.com/huija/skillmod/internal/source" @@ -252,6 +254,45 @@ func TestCandidateAddress(t *testing.T) { } } +// TestShortAddressResolutionHint covers the hint that names the default host a +// short address was completed to. It exists because a failed fetch names a URL +// the user never typed, which is indistinguishable from "the repository moved" +// unless the resolution is stated. A completed address states it; an address +// that was never completed has nothing to add and returns nil. +func TestShortAddressResolutionHint(t *testing.T) { + short, err := address.Parse("acme/skills") + if err != nil { + t.Fatalf("Parse(\"acme/skills\"): %v", err) + } + if !short.Completed || short.Repo != "https://github.com/acme/skills" { + t.Fatalf("Parse = %+v, want the github.com completion recorded", short) + } + hint := shortAddressResolutionHint(short) + if hint == nil { + t.Fatal("hint = nil, want the resolution named") + } + if !strings.Contains(hint.Error(), "github.com/acme/skills") || + !strings.Contains(hint.Error(), "file://") { + t.Errorf("hint = %q, want the resolved host and the local-path remedy", hint) + } + + // An address the user spelled out needs no hint, including one that went + // through the same completion path and was then written in full. + for _, raw := range []string{ + "github.com/acme/skills", + "https://github.com/acme/skills", + "file:///tmp/acme/skills", + } { + full, parseErr := address.Parse(raw) + if parseErr != nil { + t.Fatalf("Parse(%q): %v", raw, parseErr) + } + if hint := shortAddressResolutionHint(full); hint != nil { + t.Errorf("hint(%q) = %q, want nil", raw, hint) + } + } +} + func TestCandidateDisplaySubdirs(t *testing.T) { root := t.TempDir() if err := os.Mkdir(filepath.Join(root, "occupied"), 0o755); err != nil { diff --git a/internal/engine/get.go b/internal/engine/get.go index 8dd8e7c..1574cde 100644 --- a/internal/engine/get.go +++ b/internal/engine/get.go @@ -73,6 +73,9 @@ func (e *Engine) Get(ctx context.Context, rawAddr, alias string, io IO, options resolved, err := e.resolveGetSkills(ctx, addr, io, run.All) if err != nil { + if hint := shortAddressResolutionHint(addr); hint != nil { + err = errors.Join(err, hint) + } return nil, err } if alias != "" && len(resolved) != 1 { @@ -232,6 +235,19 @@ func (e *Engine) Get(ctx context.Context, rawAddr, alias string, io IO, options return rep, partialError(rep, conflicts, skip) } +// shortAddressResolutionHint names the default host a bare owner/repo was +// extended with, for the run whose fetch then failed. The failure names a URL +// the raw input never contained, so a user who meant a local path needs the +// resolution stated. The normalized address is echoed rather than the raw +// input, which Redact would replace with a placeholder. An address that was +// never completed has nothing to state and returns nil. +func shortAddressResolutionHint(addr *address.Address) error { + if !addr.Completed { + return nil + } + return fmt.Errorf("%s", i18n.Format("engine.get.short_address_resolved", addr.Repo)) +} + func printGetDryRunReport(rep *Report, io IO) error { for _, entry := range rep.Entries { if err := io.printf(i18n.Text("engine.get.dry_run_entry"), entry.Name, entry.Version, entry.Action); err != nil { diff --git a/locales/en_US.po b/locales/en_US.po index 370de0a..35dba2d 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -436,6 +436,11 @@ msgstr "%s — %s\n %s" msgid "engine.get.reading_skill_metadata" msgstr "reading skill metadata" +#, go-format +msgid "engine.get.short_address_resolved" +msgstr "the short address was resolved as %s; for a local repository, use t" +"he file:// prefix" + msgid "engine.get.skill_md_missing_repository" msgstr "SKILL.md is missing from the repository root and every descendant o" "f skills/" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index 9b6c736..d979069 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -429,6 +429,11 @@ msgstr "%s — %s\n %s" msgid "engine.get.reading_skill_metadata" msgstr "正在读取 skill 元数据" +#, go-format +msgid "engine.get.short_address_resolved" +msgstr "简写地址已解析为 %s;若指本地仓库,请使用 file:/" +"/ 前缀" + msgid "engine.get.skill_md_missing_repository" msgstr "仓库根目录及 skills/ 下所有子目录中均未找到 SKILL." "md" From 6c0566c12d8a8cec57ef79f70ae0963f02cd08fc Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:42:37 +0800 Subject: [PATCH 3/9] feat: discover skills wherever a repository puts them Discovery used to look at the repository root and below skills/ only, so a repository that publishes its skills directly in the root, or under an agent directory such as .agents/skills or .claude/skills, was reported as having no SKILL.md at all. Scan the conventional collection roots plus every hidden /skills directory and the root-level directories as well, in a fixed order, with duplicates collapsed. An explicit subdirectory still wins over a name, and the name shorthand now resolves anywhere a skill was found, so a repository only has to look conventional to people who never type a path. --- internal/engine/engine_test.go | 213 ++++++++++++++++++++++++++++++++- internal/engine/get.go | 148 ++++++++++++++++++++--- locales/en_US.po | 4 +- locales/zh_CN.po | 4 +- 4 files changed, 349 insertions(+), 20 deletions(-) diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index 1e0a973..f66d6b5 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -442,6 +442,215 @@ func TestGet_AllInstallsAllDiscoveredNestedSkills(t *testing.T) { } } +// A repository without a skills/ collection publishes its skills directly in +// the root, or inside an agent skills directory such as .agents/skills; both +// layouts are discovered so only conventional repositories need a typed path. +func TestGet_DiscoversSkillsOutsideTheSkillsCollection(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "flat layout\n") + r.WriteSkill("cool-skill", "cool-skill") + r.WriteSkill("other-skill", "other-skill") + r.WriteSkill(".agents/skills/wrapped", "wrapped") + r.CommitAll("flat and agent layouts") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get flat layout with --all: %v", err) + } + mod, err := modfile.LoadMod(root) + if err != nil { + t.Fatal(err) + } + byName := map[string]modfile.ModSkill{} + for _, skill := range mod.Skills { + byName[skill.Name] = skill + } + for _, name := range []string{"cool-skill", "other-skill", "wrapped"} { + if _, ok := byName[name]; !ok { + t.Fatalf("skill %q was not discovered: %+v", name, mod.Skills) + } + } + if byName["cool-skill"].Source != r.URL+"//cool-skill" { + t.Errorf("root-level source = %q, want %q", byName["cool-skill"].Source, r.URL+"//cool-skill") + } + if byName["wrapped"].Source != r.URL+"//.agents/skills/wrapped" { + t.Errorf("agent-directory source = %q, want %q", byName["wrapped"].Source, r.URL+"//.agents/skills/wrapped") + } + + // The name shorthand resolves a discovered skill wherever it lives, and an + // exact subdirectory still wins over name matching. + root2 := t.TempDir() + eng2 := newEngine(t, root2, t.TempDir()) + if _, err := eng2.Get(ctx, r.URL+"//wrapped@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get discovered skill by name: %v", err) + } + lock := loadLockSkill(t, root2, "wrapped") + if lock.Source != r.URL+"//.agents/skills/wrapped" { + t.Errorf("name-shorthand lock source = %q, want %q", lock.Source, r.URL+"//.agents/skills/wrapped") + } + if _, err := os.Stat(filepath.Join(installedDir(root2, "wrapped"), "SKILL.md")); err != nil { + t.Fatalf("wrapped was not installed: %v", err) + } +} + +// One skill under an agent directory needs no selection even though the +// repository has no conventional layout at all. +func TestGet_AgentDirectoryRepositoryInstallsWithoutPrompting(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "single wrapped skill\n") + r.WriteSkill(".agent/skills/only", "only") + r.CommitAll("agent layout") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get single wrapped skill: %v", err) + } + if _, err := os.Stat(filepath.Join(installedDir(root, "only"), "SKILL.md")); err != nil { + t.Fatal("only was not installed") + } +} + +// TestGet_KeepsOneCandidateWhenAnAgentDirectoryMirrorsTheCollection covers a +// repository that publishes the same skills twice, once under skills/ and again +// under an agent directory such as .openclaw/skills or .claude/skills. Both +// would install into one directory under one name, so discovery keeps the copy +// from the layout a reader looks at first and offers the skill once. +func TestGet_KeepsOneCandidateWhenAnAgentDirectoryMirrorsTheCollection(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "mirrored collection\n") + for _, name := range []string{"ponytail", "ponytail-review"} { + r.WriteSkill("skills/"+name, name) + r.WriteSkill(".openclaw/skills/"+name, name) + } + r.CommitAll("mirror the collection under an agent directory") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get mirrored collection with --all: %v", err) + } + mod, err := modfile.LoadMod(root) + if err != nil { + t.Fatal(err) + } + if len(mod.Skills) != 2 { + t.Fatalf("declarations = %+v, want one entry per skill, not one per copy", mod.Skills) + } + for _, skill := range mod.Skills { + if !strings.HasPrefix(skill.Source, r.URL+"//skills/") { + t.Errorf("%s source = %q, want the conventional skills/ copy", skill.Name, skill.Source) + } + } + // The name shorthand resolves to the same copy, and a single skill from the + // mirrored repository needs no selection at all. + root2 := t.TempDir() + eng2 := newEngine(t, root2, t.TempDir()) + if _, err := eng2.Get(ctx, r.URL+"//ponytail-review@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get mirrored skill by name: %v", err) + } + if lock := loadLockSkill(t, root2, "ponytail-review"); lock.Source != r.URL+"//skills/ponytail-review" { + t.Errorf("name-shorthand source = %q, want the conventional skills/ copy", lock.Source) + } +} + +// TestGet_KeepsTheRootLevelCopyOverAnAgentDirectory covers the second step of +// the ranking: a skill a repository leaves in a root directory outranks the same +// skill in an agent mirror, because the root directory is the repository's own +// layout and the agent directory is a copy kept for one agent. +func TestGet_KeepsTheRootLevelCopyOverAnAgentDirectory(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "root copy beats agent copy\n") + r.WriteSkill("ponytail", "ponytail") + r.WriteSkill(".claude/skills/ponytail", "ponytail") + r.CommitAll("root copy alongside an agent copy") + r.Tag("v1.0.0") + r.Finish() + + // The agent copy alone still installs, which is what makes the ranking + // meaningful rather than a rule that only fires on the conventional layout. + solo := testutil.NewRepo(t) + solo.Write("README.md", "agent only\n") + solo.WriteSkill(".claude/skills/wrapped", "wrapped") + solo.CommitAll("agent only") + solo.Tag("v1.0.0") + solo.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get repository with a root copy and an agent copy: %v", err) + } + mod, err := modfile.LoadMod(root) + if err != nil { + t.Fatal(err) + } + if len(mod.Skills) != 1 || mod.Skills[0].Source != r.URL+"//ponytail" { + t.Fatalf("declarations = %+v, want the root-level copy once", mod.Skills) + } + if _, err := eng.Get(ctx, solo.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatal("only skill published under an agent directory") + } +} + +// TestGet_KeepsTheCollectionCopyOverEverythingElse covers the top of the +// ranking: a skill under skills/ is the one a repository publishes as its own, +// so it wins over a copy in a root directory and over an agent mirror alike. +func TestGet_KeepsTheCollectionCopyOverEverythingElse(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "the same skill in three places\n") + r.WriteSkill("skills/ponytail", "ponytail") + r.WriteSkill("ponytail", "ponytail") + r.WriteSkill(".openclaw/skills/ponytail", "ponytail") + r.CommitAll("one skill, three roots") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + // Discovery with no subdirectory: the ranking decides, because all three + // copies were found rather than typed as a path. + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get repository with one skill in three roots: %v", err) + } + mod, err := modfile.LoadMod(root) + if err != nil { + t.Fatal(err) + } + if len(mod.Skills) != 1 || mod.Skills[0].Source != r.URL+"//skills/ponytail" { + t.Fatalf("declarations = %+v, want the conventional skills/ copy", mod.Skills) + } +} + +// TestGet_TwoAgentDirectoriesAreNotRankedAgainstEachOther keeps the ambiguity a +// repository creates when two agent directories hold the same skill and neither +// outranks the other. Picking one silently would install a copy the caller never +// chose, so the run reports both paths the way it does for any other ambiguity. +func TestGet_TwoAgentDirectoriesAreNotRankedAgainstEachOther(t *testing.T) { + r := testutil.NewRepo(t) + r.Write("README.md", "two agent directories, one skill\n") + r.WriteSkill(".claude/skills/ponytail", "ponytail") + r.WriteSkill(".codex/skills/ponytail", "ponytail") + r.CommitAll("mirror for two agents") + r.Tag("v1.0.0") + r.Finish() + + eng := newEngine(t, t.TempDir(), t.TempDir()) + _, err := eng.Get(ctx, r.URL+"//ponytail@v1.0.0", "", testIO()) + if err == nil || !strings.Contains(err.Error(), "multiple subdirectories") || + !strings.Contains(err.Error(), ".claude/skills/ponytail") || + !strings.Contains(err.Error(), ".codex/skills/ponytail") { + t.Errorf("Get(ambiguous agent mirrors) error = %v, want both paths named", err) + } +} + type getSkillChooser struct { choices []int calls int @@ -810,7 +1019,9 @@ func TestGet_ExplicitLocalRepoVersionWinsOverNewSubdirTag(t *testing.T) { root := t.TempDir() eng := newEngine(t, root, t.TempDir()) - if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO()); err != nil { + // The repository publishes the root skill and beta as root-level skills, so + // the first get states the whole set instead of guessing one of them. + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { t.Fatal(err) } diff --git a/internal/engine/get.go b/internal/engine/get.go index 1574cde..76ed328 100644 --- a/internal/engine/get.go +++ b/internal/engine/get.go @@ -11,6 +11,7 @@ import ( "io/fs" "os" "path/filepath" + "sort" "strings" "github.com/huija/skillmod/internal/address" @@ -413,6 +414,30 @@ type skillCandidate struct { subdir string name string description string + origin candidateOrigin +} + +// candidateOrigin ranks the root a candidate was found under. A repository can +// publish the same skill under more than one conventional root — skills/ and an +// agent mirror such as .openclaw/skills is the common case — and the two would +// install into the same directory under the same name, so discovery keeps one of +// them. The ranking is the one a reader of the repository expects: the +// conventional skills/ collection, then a root-level directory, then the +// agent-specific collections, which are mirrors maintained for one agent rather +// than the repository's own layout. +type candidateOrigin int + +const ( + originRepositoryRoot candidateOrigin = iota // the repository itself is one skill + originCollection + originRootDirectory + originAgentCollection +) + +// takesPrecedenceOver reports whether this root outranks another, so the copy +// a repository keeps is the one from the layout a reader looks at first. +func (o candidateOrigin) takesPrecedenceOver(other candidateOrigin) bool { + return o < other } // chooseSkillCandidates lets an interactive caller choose one or more skills. @@ -524,9 +549,32 @@ func candidateDisplaySubdirs(root string, candidates []skillCandidate) []string return displaySubdirs } +// skillCandidates discovers the skills a repository publishes. Discovery order +// is the repository root itself (a standalone skill), the conventional skills/ +// collection, any agent-named hidden collection such as .agents/skills or +// .claude/skills, and the root-level directories as well. Those four are always +// scanned, in that order, because a repository that publishes a collection can +// still leave a skill sitting in another root directory, and a skill nobody +// asked for is what discovery is for; duplicates are collapsed. An explicit +// subdirectory always wins over discovery, so a repository only has to look +// conventional to users who never type a path. func skillCandidates(root string) ([]skillCandidate, error) { var candidates []skillCandidate - addCandidate := func(dir, subdir string) error { + // A skill name is the identity an installation directory and a //name address + // both use, so the same skill published under two roots cannot both be + // offered: they would install into one place under one name. The key pairs + // the folded name with the root it was found under, because two skills that + // share a name inside one collection are two skills, not a duplicate — they + // stay to be reported as the ambiguity they are. The map holds the position + // of the copy currently kept, so a copy from a higher-precedence root + // replaces it where the first one stood. + byName := map[string]int{} + seenSubdir := map[string]bool{} + addCandidate := func(dir, subdir string, origin candidateOrigin) error { + if seenSubdir[subdir] { + return nil + } + seenSubdir[subdir] = true if !hasSkillManifest(dir) { return nil } @@ -537,33 +585,107 @@ func skillCandidates(root string) ([]skillCandidate, error) { if err != nil { return err } - candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description}) + key := fsutil.FoldKey(metadata.Name) + if at, duplicate := byName[key]; duplicate { + switch { + case origin.takesPrecedenceOver(candidates[at].origin): + // A copy from the higher-precedence root replaces the one kept, + // in the position that one had taken. + candidates[at] = skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin} + case candidates[at].origin != origin: + // The kept copy's root outranks this one, so this copy is the + // duplicate and is dropped. + default: + // Neither outranks: the same name inside one collection, or two + // agent mirrors nobody ranks. Two skills rather than a duplicate, + // so both stay to be reported as the ambiguity they are. + candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin}) + } + return nil + } + byName[key] = len(candidates) + candidates = append(candidates, skillCandidate{subdir: subdir, name: metadata.Name, description: metadata.Description, origin: origin}) return nil } - if err := addCandidate(root, ""); err != nil { + if err := addCandidate(root, "", originRepositoryRoot); err != nil { return nil, err } - - skillsRoot := filepath.Join(root, "skills") - _, err := os.Stat(skillsRoot) - if os.IsNotExist(err) { - return candidates, nil + for _, collection := range collectionRoots(root) { + if err := walkCollection(root, collection.dir, collection.origin, addCandidate); err != nil { + return nil, err + } } + entries, err := os.ReadDir(root) if err != nil { return nil, err } - err = filepath.WalkDir(skillsRoot, func(path string, d fs.DirEntry, walkErr error) error { + for _, entry := range entries { + if !entry.IsDir() { + continue + } + if err := addCandidate(filepath.Join(root, entry.Name()), entry.Name(), originRootDirectory); err != nil { + return nil, err + } + } + return candidates, nil +} + +// collectionDirName is the directory name a skill collection is published +// under, both bare (skills/) and inside an agent directory (.agents/skills). +const collectionDirName = "skills" + +// collectionRoot is one directory a collection is published under, with the +// origin its skills carry. +type collectionRoot struct { + dir string + origin candidateOrigin +} + +// collectionRoots lists the collection directories a repository may publish +// under, in discovery order: the conventional skills/ directory and every +// hidden agent-named directory that holds one, such as .agents/skills, +// .claude/skills, or .agent/skills. A directory under a hidden one is a mirror +// kept for a single agent, so its skills carry the lower origin and lose to a +// same-named skill in the conventional collection. +func collectionRoots(root string) []collectionRoot { + var roots []collectionRoot + for _, pattern := range []string{ + filepath.Join(root, collectionDirName), + filepath.Join(root, ".*", collectionDirName), + } { + matches, err := filepath.Glob(pattern) + if err != nil { + continue // A malformed pattern is a programming error, not user input. + } + sort.Strings(matches) + for _, match := range matches { + origin := originCollection + if strings.HasPrefix(filepath.Base(filepath.Dir(match)), ".") { + origin = originAgentCollection + } + roots = append(roots, collectionRoot{dir: match, origin: origin}) + } + } + return roots +} + +// walkCollection adds every skill under one collection directory at any depth, +// stopping at a directory that is itself a skill. The origin every candidate +// carries is the one the collection itself has, so a skill inside an agent +// directory never outranks the same skill under skills/. +func walkCollection(root, collection string, origin candidateOrigin, addCandidate func(dir, subdir string, origin candidateOrigin) error) error { + return filepath.WalkDir(collection, func(path string, d fs.DirEntry, walkErr error) error { if walkErr != nil { return walkErr } - if !d.IsDir() || path == skillsRoot { + if !d.IsDir() || path == collection { return nil } rel, err := filepath.Rel(root, path) if err != nil { return err } - if err := addCandidate(path, filepath.ToSlash(rel)); err != nil { + if err := addCandidate(path, filepath.ToSlash(rel), origin); err != nil { return err } if hasSkillManifest(path) { @@ -571,10 +693,6 @@ func skillCandidates(root string) ([]skillCandidate, error) { } return nil }) - if err != nil { - return nil, err - } - return candidates, nil } func hasSkillManifest(dir string) bool { diff --git a/locales/en_US.po b/locales/en_US.po index 35dba2d..211e953 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -442,8 +442,8 @@ msgstr "the short address was resolved as %s; for a local repository, use t" "he file:// prefix" msgid "engine.get.skill_md_missing_repository" -msgstr "SKILL.md is missing from the repository root and every descendant o" -"f skills/" +msgstr "no SKILL.md found; looked in the repository root, skills/, agent sk" +"ill directories such as .agents/skills, and root-level skill directories" #, go-format msgid "engine.get.skill_name_matches_multiple" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index d979069..ed28d17 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -435,8 +435,8 @@ msgstr "简写地址已解析为 %s;若指本地仓库,请使用 file:/" "/ 前缀" msgid "engine.get.skill_md_missing_repository" -msgstr "仓库根目录及 skills/ 下所有子目录中均未找到 SKILL." -"md" +msgstr "未找到 SKILL.md;已检查仓库根目录、skills/、.agents/s" +"kills 等 agent 技能目录,以及根目录下的技能目录" #, go-format msgid "engine.get.skill_name_matches_multiple" From 084792e5e0dc92a9432aeffea34d36105dec1513 Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:51:18 +0800 Subject: [PATCH 4/9] feat: let remove take a repository selector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit remove only accepted skill names and aliases, so clearing everything that came from one repository meant naming each skill. A positional argument that contains a slash — which a skill name can never do — is now a repository selector: it matches the entries declared from that repository and, when more than one is declared, offers them interactively exactly like get offers a repository's skills. A single-entry repository needs no choice, a run with no channel to ask through lists the candidates instead, and a repository nothing comes from is reported by name. The --agent unlink path resolves the same selectors to names before delegating to share. --- internal/engine/engine_test.go | 177 +++++++++++++++++++++++++++++++ internal/engine/remove.go | 185 ++++++++++++++++++++++++++++++--- locales/en_US.po | 13 +++ locales/zh_CN.po | 13 +++ 4 files changed, 371 insertions(+), 17 deletions(-) diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index f66d6b5..f4c552d 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -2232,6 +2232,183 @@ func TestRemoveWithoutNamesNeedsASelection(t *testing.T) { assertStateDirs(t, root, "alpha") } +// TestRemoveAcceptsARepositorySelector covers remove's repository form: a +// repository that declares one skill needs no choice, several entries from one +// repository are offered interactively exactly like get's chooser, and a +// repository nothing comes from is reported instead of ignored. +func TestRemoveAcceptsARepositorySelector(t *testing.T) { + r := testutil.NewRepo(t) + r.WriteSkill("skills/alpha", "alpha") + r.WriteSkill("skills/beta", "beta") + r.CommitAll("collection") + r.Tag("v1.0.0") + r.Finish() + other := newHelloRepo(t) + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get collection: %v", err) + } + if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get hello: %v", err) + } + + // A single-entry repository removes without asking. + rep, err := eng.Remove(ctx, []string{other.URL}, testIO()) + if err != nil { + t.Fatalf("Remove(single-entry repository): %v", err) + } + if len(rep.Entries) != 1 || rep.Entries[0].Name != "hello" { + t.Fatalf("Remove report = %+v, want only hello", rep.Entries) + } + + // Several entries from one repository: the caller picks which. + chooser := &shareChooser{selections: [][]int{{1}}} + rep, err = eng.Remove(ctx, []string{r.URL}, engine.IO{Out: io.Discard, Confirm: chooser}) + if err != nil { + t.Fatalf("Remove(repository with several entries): %v", err) + } + if chooser.calls != 1 { + t.Fatalf("selector calls = %d, want one repository selection", chooser.calls) + } + if len(rep.Entries) != 1 || rep.Entries[0].Name != "beta" { + t.Fatalf("Remove report = %+v, want only the picked beta", rep.Entries) + } + if _, err := os.Stat(installedDir(root, "beta")); !os.IsNotExist(err) { + t.Errorf("picked installation error = %v, want not exist", err) + } + if _, err := os.Stat(installedDir(root, "alpha")); err != nil { + t.Errorf("unpicked installation = %v, want kept", err) + } + + // A repository nothing comes from is reported rather than silently ignored. + if _, err := eng.Remove(ctx, []string{"github.com/acme/other"}, testIO()); err == nil || + !strings.Contains(err.Error(), "github.com/acme/other") { + t.Errorf("Remove(unknown repository) error = %v, want the repository named", err) + } +} + +// TestRemoveRepositorySelectorWithoutAChannelListsCandidates refuses to guess +// between several entries from one repository when there is no terminal to ask +// through, and lists them the way get lists multiple skills. +func TestRemoveRepositorySelectorWithoutAChannelListsCandidates(t *testing.T) { + r := testutil.NewRepo(t) + r.WriteSkill("skills/alpha", "alpha") + r.WriteSkill("skills/beta", "beta") + r.CommitAll("collection") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get collection: %v", err) + } + _, err := eng.Remove(ctx, []string{r.URL}, testIO()) + if err == nil { + t.Fatal("Remove(repository) without a channel succeeded, want a candidate listing") + } + for _, want := range []string{"alpha", "beta"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("Remove error = %v, want %q listed", err, want) + } + } + assertStateDirs(t, root, "alpha", "beta") +} + +// TestRemoveRepositorySelectorWithAllTakesEveryEntry pins the non-interactive +// way to say "everything this repository brought in". --all expands a +// repository selector, so a run with no terminal deletes the whole set instead +// of stopping to list candidates, and entries from other repositories stay. +func TestRemoveRepositorySelectorWithAllTakesEveryEntry(t *testing.T) { + r := testutil.NewRepo(t) + r.WriteSkill("skills/alpha", "alpha") + r.WriteSkill("skills/beta", "beta") + r.CommitAll("collection") + r.Tag("v1.0.0") + r.Finish() + other := newHelloRepo(t) + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get collection: %v", err) + } + if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get hello: %v", err) + } + + rep, err := eng.Remove(ctx, []string{r.URL}, testIO(), engine.RemoveOptions{All: true}) + if err != nil { + t.Fatalf("Remove(repository, all): %v", err) + } + if len(rep.Entries) != 2 { + t.Fatalf("Remove report = %+v, want both collection entries", rep.Entries) + } + assertStateDirs(t, root, "hello") + + // --all states the set, so naming a skill alongside it is still refused + // rather than silently widened to the whole declaration. + if _, err := eng.Remove(ctx, []string{"hello"}, testIO(), engine.RemoveOptions{All: true}); err == nil || + !strings.Contains(err.Error(), "--all") { + t.Errorf("Remove(name, all) error = %v, want the combination refused", err) + } + assertStateDirs(t, root, "hello") +} + +// TestRemoveAgentWithAllAndARepositorySelector pins the --agent path's +// repository form. --all expands a repository selector there exactly as it does +// for a removal, so one non-interactive command unshares everything that +// repository declared; the expansion happens before the delegation to share, +// which is why share does not see a set stated twice and refuse it. +func TestRemoveAgentWithAllAndARepositorySelector(t *testing.T) { + r := testutil.NewRepo(t) + r.WriteSkill("skills/alpha", "alpha") + r.WriteSkill("skills/beta", "beta") + r.CommitAll("collection") + r.Tag("v1.0.0") + r.Finish() + other := newHelloRepo(t) + + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Get(ctx, r.URL+"@v1.0.0", "", testIO(), engine.GetOptions{All: true}); err != nil { + t.Fatalf("Get collection: %v", err) + } + if _, err := eng.Get(ctx, other.URL+"@v1.0.0", "", testIO()); err != nil { + t.Fatalf("Get hello: %v", err) + } + for _, name := range []string{"alpha", "beta", "hello"} { + if _, err := eng.Share(ctx, engine.ShareOptions{Skills: []string{name}, Agents: []string{"claude"}}, testIO()); err != nil { + t.Fatalf("Share(%s): %v", name, err) + } + } + + rep, err := eng.Remove(ctx, []string{r.URL}, testIO(), engine.RemoveOptions{All: true, Agents: []string{"claude"}}) + if err != nil { + t.Fatalf("Remove(repository, all, --agent claude): %v", err) + } + if len(rep.Entries) != 2 { + t.Fatalf("Remove report = %+v, want both collection entries", rep.Entries) + } + for _, name := range []string{"alpha", "beta"} { + if got := agentsOf(loadMod(t, root), name); len(got) != 0 { + t.Errorf("%s agents after unsharing the repository = %v, want none", name, got) + } + if _, err := os.Stat(filepath.Join(agentSkillsDir(root, "claude"), name)); !os.IsNotExist(err) { + t.Errorf("%s claude link = %v, want not exist", name, err) + } + } + // hello came from another repository, so it is left linked, and the managed + // copies stay either way: --agent only stops the sharing. + if got := agentsOf(loadMod(t, root), "hello"); len(got) != 1 || got[0] != "claude" { + t.Errorf("hello agents = %v, want [claude]", got) + } + assertStateDirs(t, root, "alpha", "beta", "hello") +} + +// TestRemoveKeepsModifiedInstallationAndReportsPartial covers the partial path. func TestRemoveKeepsModifiedInstallationAndReportsPartial(t *testing.T) { r := newHelloRepo(t) root := t.TempDir() diff --git a/internal/engine/remove.go b/internal/engine/remove.go index 7b302d3..8bd9f8e 100644 --- a/internal/engine/remove.go +++ b/internal/engine/remove.go @@ -8,10 +8,13 @@ import ( "context" "errors" "fmt" + "strings" + "github.com/huija/skillmod/internal/address" "github.com/huija/skillmod/internal/fsutil" "github.com/huija/skillmod/internal/i18n" "github.com/huija/skillmod/internal/modfile" + repoaddr "github.com/huija/skillmod/internal/repo" "github.com/huija/skillmod/internal/ui" ) @@ -30,16 +33,43 @@ func removeOptions(options []RemoveOptions) RemoveOptions { } // Remove deletes declarations and clean managed installations selected by -// published name or installation alias, by --all, or from the interactive -// selection when the run names nothing. Locally modified installations are -// kept and reported as partial completion. -func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...RemoveOptions) (*Report, error) { +// published name or installation alias, by repository, by --all, or from the +// interactive selection when the run names nothing. --all states the whole +// declared set, or the whole set that the repository selectors name, which is +// what makes "everything this repository brought in" sayable without a +// terminal. Locally modified installations are kept and reported as partial +// completion. +func (e *Engine) Remove(ctx context.Context, args []string, io IO, options ...RemoveOptions) (*Report, error) { run := removeOptions(options) - if run.All && len(names) > 0 { - return nil, fmt.Errorf("%s", i18n.Text("engine.remove.all_exclusive")) + if run.All { + // --all states the whole set, and a repository selector is a set it can + // expand; a skill name already names the entry, so stating both is + // refused rather than guessed at. + for _, arg := range args { + if !strings.Contains(arg, "/") { + return nil, fmt.Errorf("%s", i18n.Text("engine.remove.all_exclusive")) + } + } } if len(run.Agents) > 0 { - rep, err := e.Share(ctx, ShareOptions{Skills: names, All: run.All, Remove: run.Agents}, io, + // Unlinking names agents on an entry, so a repository selector resolves + // to the names of the entries it matches before the delegation. + m, err := e.loadMod() + if err != nil { + return nil, err + } + names, err := repositoryRemovalNames(m, args, io, run.All) + if err != nil { + return nil, err + } + // A repository selector expands to the names of every entry it declares, + // which states the set by itself; forwarding --all alongside those names + // would state it a second time, and share refuses a set stated twice. + // --all on its own still travels as --all. The refusal is share's, not + // this one, so a run that names skills next to --all is still rejected + // where the two collide, above. + all := run.All && len(names) == 0 + rep, err := e.Share(ctx, ShareOptions{Skills: names, All: all, Remove: run.Agents}, io, MutationOptions{DryRun: run.DryRun}) if rep != nil { rep.Action = CommandRemove @@ -59,7 +89,7 @@ func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...R if err != nil { return nil, err } - selected, err := selectRemovals(m, names, run.All, io) + selected, err := selectRemovals(m, args, run.All, io) if err != nil { return nil, err } @@ -180,13 +210,16 @@ func (e *Engine) Remove(ctx context.Context, names []string, io IO, options ...R } // selectRemovals resolves the entries a remove run acts on, keyed by folded -// installation directory. Names and --all state the set explicitly; with -// neither, an interactive caller picks from what the manifest declares, which -// is how every other selection in skillmod works. Removing deletes an -// installation outright, so the picker is only how the set is chosen — the -// confirmation that lists the directories still comes afterwards. -func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string]bool, error) { - if all { +// installation directory. Names and --all state the set explicitly, and --all +// also states the whole set a repository selector matches; a repository +// selector without it picks the entries declared from that repository and asks +// which of them when more than one is declared; with neither, an interactive +// caller picks from what the manifest declares, which is how every other +// selection in skillmod works. Removing deletes an installation outright, so +// the picker is only how the set is chosen — the confirmation that lists the +// directories still comes afterwards. +func selectRemovals(m *modfile.Mod, args []string, all bool, io IO) (map[string]bool, error) { + if all && len(args) == 0 { if len(m.Skills) == 0 { return nil, fmt.Errorf("%s", i18n.Text("engine.remove.nothing_declared")) } @@ -196,8 +229,34 @@ func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string } return selected, nil } + selected := map[string]bool{} + var names []string + for _, arg := range args { + // A skill name or alias can never contain a slash, so an argument that + // does is a repository selector. + if !strings.Contains(arg, "/") { + names = append(names, arg) + continue + } + fromRepo, err := repositoryRemovals(m, arg, io, all) + if err != nil { + return nil, err + } + for _, skill := range fromRepo { + selected[fsutil.FoldKey(skill.DirName())] = true + } + } if len(names) > 0 { - return namedRemovals(m, names) + named, err := namedRemovals(m, names) + if err != nil { + return nil, err + } + for key := range named { + selected[key] = true + } + } + if len(selected) > 0 { + return selected, nil } if len(m.Skills) == 0 { return nil, fmt.Errorf("%s", i18n.Text("engine.remove.nothing_declared")) @@ -221,13 +280,105 @@ func selectRemovals(m *modfile.Mod, names []string, all bool, io IO) (map[string if err != nil { return nil, err } - selected := make(map[string]bool, len(picked)) for _, index := range picked { selected[fsutil.FoldKey(m.Skills[index].DirName())] = true } return selected, nil } +// repositoryRemovals resolves one repository selector against the +// declarations. A repository that declares a single skill needs no choice, and +// all takes every entry it declares; several entries without either are +// offered interactively, or listed for a rerun when there is no channel to ask +// through. +func repositoryRemovals(m *modfile.Mod, raw string, io IO, all bool) ([]modfile.ModSkill, error) { + addr, err := address.Parse(raw) + if err != nil { + return nil, err + } + matched := entriesFromRepository(m, addr.Repo) + if len(matched) == 0 { + return nil, fmt.Errorf(i18n.Text("engine.remove.no_entry_from_repository"), raw) + } + if len(matched) == 1 || all { + return matched, nil + } + if io.Confirm == nil { + displayOptions := make([]string, len(matched)) + for i, skill := range matched { + displayOptions[i] = removalOption(skill).Label + } + return nil, &repositoryCandidatesError{Repo: raw, Candidates: displayOptions} + } + options := make([]ui.Option, len(matched)) + for i, skill := range matched { + options[i] = removalOption(skill) + } + picked, err := chooseIndices(io, + i18n.Format("engine.remove.select_from_repository", raw), + options, + func(index int) string { return i18n.Format("engine.remove.confirm_one", matched[index].DirName()) }, + i18n.Text("engine.remove.no_entries_selected")) + if err != nil { + return nil, err + } + out := make([]modfile.ModSkill, 0, len(picked)) + for _, index := range picked { + out = append(out, matched[index]) + } + return out, nil +} + +// repositoryRemovalNames resolves every repository selector in args and +// returns the names of the entries they match, with the remaining arguments +// passed through unchanged. It is what the --agent path uses, because +// unlinking addresses entries by name. +func repositoryRemovalNames(m *modfile.Mod, args []string, io IO, all bool) ([]string, error) { + names := make([]string, 0, len(args)) + for _, arg := range args { + if !strings.Contains(arg, "/") { + names = append(names, arg) + continue + } + fromRepo, err := repositoryRemovals(m, arg, io, all) + if err != nil { + return nil, err + } + for _, skill := range fromRepo { + names = append(names, skill.Name) + } + } + return names, nil +} + +// entriesFromRepository returns the declarations installed from one +// repository, in declaration order. Local entries never match. +func entriesFromRepository(m *modfile.Mod, repo string) []modfile.ModSkill { + var matched []modfile.ModSkill + for _, skill := range m.Skills { + if skill.Source == "" { + continue + } + entryRepo, _, err := splitSource(skill.Source) + if err != nil { + continue // A malformed declaration is reported by the commands that resolve it. + } + if repoaddr.Identity(entryRepo) == repoaddr.Identity(repo) { + matched = append(matched, skill) + } + } + return matched +} + +type repositoryCandidatesError struct { + Repo string + Candidates []string +} + +func (e *repositoryCandidatesError) Error() string { + return i18n.Format("engine.remove.multiple_from_repository", e.Repo, strings.Join(e.Candidates, ", ")) +} + // namedRemovals resolves the requested names against the declarations. A name // selects every entry that answers to it, whether it was published under that // name or installed under that alias, and a name that matches nothing is diff --git a/locales/en_US.po b/locales/en_US.po index 211e953..c02f6e0 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -728,6 +728,11 @@ msgstr "local entry, no version" msgid "engine.remove.locally_modified_kept" msgstr "locally modified; kept installed files: " +#, go-format +msgid "engine.remove.multiple_from_repository" +msgstr "multiple entries come from %s; rerun interactively to select one or" +" more, or name them: %s" + msgid "engine.remove.needs_selection" msgstr "no entries were requested; pass names or --all, or run remove in a " "terminal" @@ -735,6 +740,10 @@ msgstr "no entries were requested; pass names or --all, or run remove in a " msgid "engine.remove.no_entries_selected" msgstr "no entries were selected" +#, go-format +msgid "engine.remove.no_entry_from_repository" +msgstr "no entry in SKILL.mod comes from %s" + msgid "engine.remove.nothing_declared" msgstr "SKILL.mod declares no entries" @@ -745,6 +754,10 @@ msgstr "removed %d declarations and %d clean installation directories" msgid "engine.remove.select_entries" msgstr "select the entries to remove" +#, go-format +msgid "engine.remove.select_from_repository" +msgstr "multiple skills from %s; select one or more" + msgid "engine.remove.share_cleanup_failed" msgstr "failed to remove some share links" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index ed28d17..254fc6b 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -713,6 +713,11 @@ msgstr "本地条目,无版本" msgid "engine.remove.locally_modified_kept" msgstr "存在本地修改,已保留安装文件:" +#, go-format +msgid "engine.remove.multiple_from_repository" +msgstr "%s 中有多个条目;交互模式中选择一个或多个,或" +"直接指定:%s" + msgid "engine.remove.needs_selection" msgstr "未指定条目;请给出名称或传 --all,或在终端中运" "行 remove" @@ -720,6 +725,10 @@ msgstr "未指定条目;请给出名称或传 --all,或在终端中运" msgid "engine.remove.no_entries_selected" msgstr "未选择任何条目" +#, go-format +msgid "engine.remove.no_entry_from_repository" +msgstr "SKILL.mod 中没有来自 %s 的条目" + msgid "engine.remove.nothing_declared" msgstr "SKILL.mod 中没有声明条目" @@ -730,6 +739,10 @@ msgstr "已删除 %d 个声明和 %d 个内容未改动的安装目录" msgid "engine.remove.select_entries" msgstr "选择要删除的条目" +#, go-format +msgid "engine.remove.select_from_repository" +msgstr "%s 中有多个 skill;选择一个或多个" + msgid "engine.remove.share_cleanup_failed" msgstr "清理部分分享链接失败" From 6d589ef5b1004c88d1974b4668f1c21e1e7c0d3d Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:52:23 +0800 Subject: [PATCH 5/9] fix: make --json the only output and always emit one document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --json used to print the human summary on stderr alongside the document on stdout, so a terminal showed the same run twice in two formats, and a command that failed early — a refused selection, a missing manifest, a bad address — printed no document at all, which made the flag useless for automation. In JSON mode every human-readable channel is now closed: no summary, no progress, and one document on stdout whatever happens, with an error field naming the failure and the exit code unchanged. entries always marshals as an array so a consumer never special-cases null. A cobra usage error still exits 1 with plain text on stderr, because no command ran to produce a report. --- internal/cli/get.go | 2 +- internal/cli/init.go | 2 +- internal/cli/list.go | 2 +- internal/cli/prune.go | 2 +- internal/cli/remove.go | 2 +- internal/cli/root.go | 116 ++++++++++++++++++++++++------- internal/cli/root_test.go | 142 ++++++++++++++++++++++++++++++++++++-- internal/cli/share.go | 2 +- internal/cli/sync.go | 2 +- internal/cli/update.go | 2 +- internal/cli/upgrade.go | 4 +- internal/cli/verify.go | 2 +- internal/cli/why.go | 2 +- internal/engine/report.go | 21 +++++- 14 files changed, 259 insertions(+), 44 deletions(-) diff --git a/internal/cli/get.go b/internal/cli/get.go index 4da776c..5a0d185 100644 --- a/internal/cli/get.go +++ b/internal/cli/get.go @@ -28,7 +28,7 @@ func newGetCmd(options *rootOptions) *cobra.Command { rep, err := eng.Get(cmd.Context(), args[0], alias, options.newIO(cmd), engine.GetOptions{ All: all, DryRun: options.dryRun, }) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().StringVarP(&alias, "alias", "a", "", i18n.Text("cli.get.flag_alias")) diff --git a/internal/cli/init.go b/internal/cli/init.go index f25f3a1..bef5c4a 100644 --- a/internal/cli/init.go +++ b/internal/cli/init.go @@ -24,7 +24,7 @@ func newInitCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.Init(cmd.Context(), force, options.newIO(cmd), options.mutationOptions()) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().BoolVarP(&force, "force", "f", false, i18n.Text("cli.init.flag_force")) diff --git a/internal/cli/list.go b/internal/cli/list.go index eeb363a..0105093 100644 --- a/internal/cli/list.go +++ b/internal/cli/list.go @@ -22,7 +22,7 @@ func newListCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.List(cmd.Context(), options.newIO(cmd)) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } } diff --git a/internal/cli/prune.go b/internal/cli/prune.go index d1040c2..c3b312b 100644 --- a/internal/cli/prune.go +++ b/internal/cli/prune.go @@ -22,7 +22,7 @@ func newPruneCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.Prune(cmd.Context(), options.newIO(cmd), options.mutationOptions()) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } } diff --git a/internal/cli/remove.go b/internal/cli/remove.go index 38befe0..95038f9 100644 --- a/internal/cli/remove.go +++ b/internal/cli/remove.go @@ -38,7 +38,7 @@ func newRemoveCmd(options *rootOptions) *cobra.Command { rep, err := eng.Remove(cmd.Context(), names, options.newIO(cmd), engine.RemoveOptions{ All: all, DryRun: options.dryRun, Agents: targets, }) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().BoolVar(&all, "all", false, i18n.Text("cli.remove.flag_all")) diff --git a/internal/cli/root.go b/internal/cli/root.go index 22e3a18..1c2a3bd 100644 --- a/internal/cli/root.go +++ b/internal/cli/root.go @@ -10,6 +10,7 @@ import ( "encoding/json" "errors" "fmt" + "io" "os" "path/filepath" @@ -48,6 +49,14 @@ type rootOptions struct { // NewRootCmd assembles the root command and all subcommands. func NewRootCmd() *cobra.Command { + root, _ := newRootCmd() + return root +} + +// newRootCmd assembles the command tree and returns the flag state it owns, so +// the entry point can tell a --json run from a plain one when a handler fails +// before it reaches output. +func newRootCmd() (*cobra.Command, *rootOptions) { options := &rootOptions{} root := &cobra.Command{ Use: "skillmod", @@ -56,6 +65,12 @@ func NewRootCmd() *cobra.Command { Long: i18n.Text("cli.root.long"), SilenceUsage: true, SilenceErrors: true, + // Cobra parses the flags and resolves the subcommand before this runs, + // so recording the command here is what separates a failure inside a + // handler from one raised while parsing flags. + PersistentPreRun: func(cmd *cobra.Command, _ []string) { + handlerCmd = cmd + }, } // The persistent flags that appear on ordinary commands carry a one-letter // shorthand. --install-mode deliberately has none: "m" collides with the @@ -81,24 +96,62 @@ func NewRootCmd() *cobra.Command { newVerifyCmd(options), newUpgradeCmd(options), ) - return root + return root, options } // Execute runs the root command and maps errors to exit codes. func Execute() int { - if err := NewRootCmd().Execute(); err != nil { + root, options := newRootCmd() + return execute(root, options) +} + +// execute runs one command tree. It is separate from Execute so a test can +// point the tree at its own buffer and still exercise the failure paths. +func execute(root *cobra.Command, options *rootOptions) int { + jsonEmitted = false + handlerCmd = nil + if err := root.Execute(); err != nil { code := exitCode(err) // Drift and partial completion are expected operational outcomes. Their - // commands already emitted a human summary (or a JSON report), so only - // unexpected failures need an additional stderr diagnostic here. - if code == ExitError { - fmt.Fprintln(os.Stderr, err) + // commands already emitted a report — a JSON document under --json, a + // human summary otherwise — so only unexpected failures need an + // additional stderr diagnostic here. + if code == ExitError && !jsonEmitted { + // A handler that returns before reaching output — newEngine + // failing is the case — still owes --json its single document, so + // the same shape is written from here. A flag error reaches no + // handler and keeps the plain stderr text its contract documents. + if options.json && handlerCmd != nil { + if writeErr := options.output(handlerCmd, nil, err); writeErr != nil { + fmt.Fprintln(os.Stderr, writeErr) + } + } + if !jsonEmitted { + fmt.Fprintln(os.Stderr, err) + } } return code } return ExitOK } +// jsonEmitted records whether the current run already wrote its JSON document +// to stdout. It is reset per Execute call and set by output; a flag-parse or +// argument error, which no command handler reaches, stays plain text on +// stderr because no document was written. +// +// Known limitation: this is package-level state, so concurrent Execute calls +// in one process would race on it. The binary calls Execute exactly once per +// process, which is the only supported pattern; threading the flag through +// RunE's error return would couple every command to it for no gain. +var jsonEmitted bool + +// handlerCmd records the command cobra actually reached, which separates a +// failure raised inside a command handler from one cobra raised while parsing +// flags. Only the former owes --json a document. It is reset per Execute call +// and carries the same single-call limitation as jsonEmitted. +var handlerCmd *cobra.Command + func exitCode(err error) int { var outputErr *outputError if errors.As(err, &outputErr) { @@ -155,24 +208,26 @@ func (options *rootOptions) newEngine() (*engine.Engine, error) { } // newIO configures I/O channels from global flags and terminal state. -// In --json mode stdout must carry only the machine-readable report, so -// human-readable engine summaries are routed to stderr. +// In --json mode stdout carries only the machine-readable report, so every +// human-readable channel is closed: engine summaries go nowhere and the +// animated progress has no writer. Prompts still reach the terminal through +// stderr, because a person who asked for JSON in a terminal still has to +// answer them. func (options *rootOptions) newIO(cmd *cobra.Command) engine.IO { - out := cmd.OutOrStdout() - if options.json { - out = cmd.ErrOrStderr() - } - io := engine.IO{ - Out: out, + channels := engine.IO{ + Out: cmd.OutOrStdout(), Yes: options.yes, } + if options.json { + channels.Out = io.Discard + } if isTerminal(os.Stdin) { - io.Confirm = ui.Interactive(os.Stdin, cmd.ErrOrStderr()) + channels.Confirm = ui.Interactive(os.Stdin, cmd.ErrOrStderr()) } - if isTerminal(os.Stderr) { - io.Progress = ui.AnimatedProgress(cmd.ErrOrStderr()) + if !options.json && isTerminal(os.Stderr) { + channels.Progress = ui.AnimatedProgress(cmd.ErrOrStderr()) } - return io + return channels } func (options *rootOptions) mutationOptions() engine.MutationOptions { @@ -184,19 +239,28 @@ func isTerminal(f *os.File) bool { return term.IsTerminal(int(f.Fd())) } -// output renders structured JSON for --json; otherwise the engine has already printed a summary. -func (options *rootOptions) output(cmd *cobra.Command, rep *engine.Report) error { - if !options.json || rep == nil { +// output renders structured JSON for --json; otherwise the engine has already +// printed a human summary. A failing run still emits exactly one document: the +// report describes whatever completed, and the error names why the command +// stopped, so a job that parses --json never faces an empty stdout. +func (options *rootOptions) output(cmd *cobra.Command, rep *engine.Report, err error) error { + if !options.json || rep == nil && err == nil { return nil } - data, err := json.MarshalIndent(rep, "", " ") - if err != nil { - return &outputError{err: err} + if rep == nil { + rep = &engine.Report{Action: engine.Command(cmd.Name())} } - _, err = fmt.Fprintln(cmd.OutOrStdout(), string(data)) if err != nil { - return &outputError{err: err} + rep.Error = err.Error() + } + data, marshalErr := json.MarshalIndent(rep, "", " ") + if marshalErr != nil { + return &outputError{err: marshalErr} + } + if _, writeErr := fmt.Fprintln(cmd.OutOrStdout(), string(data)); writeErr != nil { + return &outputError{err: writeErr} } + jsonEmitted = true return nil } diff --git a/internal/cli/root_test.go b/internal/cli/root_test.go index 5435900..0d0c427 100644 --- a/internal/cli/root_test.go +++ b/internal/cli/root_test.go @@ -102,8 +102,11 @@ func TestNewEngineAndIO(t *testing.T) { } options.json = true got = options.newIO(cmd) - if got.Out != &stderr { - t.Fatalf("--json must route engine summaries to stderr; newIO = %+v", got) + if got.Out != io.Discard { + t.Fatalf("--json must discard engine summaries; newIO.Out = %+v", got.Out) + } + if got.Progress != nil { + t.Fatal("--json must not attach an interactive progress writer") } } @@ -113,7 +116,7 @@ func TestOutputJSON(t *testing.T) { var out bytes.Buffer cmd.SetOut(&out) rep := &engine.Report{Action: engine.CommandVerify, Entries: []engine.EntryReport{{Name: "demo", Action: engine.ActionInstalled}}} - if err := options.output(cmd, rep); err != nil { + if err := options.output(cmd, rep, nil); err != nil { t.Fatal(err) } var got engine.Report @@ -126,15 +129,72 @@ func TestOutputJSON(t *testing.T) { out.Reset() options.json = false - if err := options.output(cmd, rep); err != nil || out.Len() != 0 { + if err := options.output(cmd, rep, nil); err != nil || out.Len() != 0 { t.Fatalf("plain output = %q, err = %v", out.String(), err) } options.json = true - if err := options.output(cmd, nil); err != nil || out.Len() != 0 { + if err := options.output(cmd, nil, nil); err != nil || out.Len() != 0 { t.Fatalf("nil report output = %q, err = %v", out.String(), err) } } +// TestOutputJSONOnError pins the contract that makes --json usable in +// automation: a failing run still writes exactly one document, naming the +// failure, and the human error stays off stdout. +func TestOutputJSONOnError(t *testing.T) { + options := &rootOptions{json: true} + root := NewRootCmd() + verify, _, err := root.Find([]string{"verify"}) + if err != nil { + t.Fatal(err) + } + var out bytes.Buffer + verify.SetOut(&out) + + failure := errors.New("no SKILL.mod found") + // jsonEmitted is the signal execute reads to decide whether a stderr + // diagnostic is still owed, and execute is what resets it. Both directions + // are asserted from a known starting state, so neither depends on which + // test happened to run first. + jsonEmitted = false + options.json = false + if err := options.output(verify, nil, failure); err != nil { + t.Fatal(err) + } + if jsonEmitted { + t.Fatal("a plain run recorded that it emitted a JSON document") + } + + options.json = true + if err := options.output(verify, nil, failure); err != nil { + t.Fatal(err) + } + var got engine.Report + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("error output is not JSON: %v\n%s", err, out.String()) + } + if got.Action != engine.CommandVerify || got.Error != failure.Error() { + t.Fatalf("error report = %+v, want action %q and error %q", got, engine.CommandVerify, failure.Error()) + } + if !jsonEmitted { + t.Fatal("output did not record that it emitted a document") + } + + // A report that completed alongside an error keeps its entries and carries + // the reason the command failed. + out.Reset() + rep := &engine.Report{Action: engine.CommandSync, Entries: []engine.EntryReport{{Name: "demo", Action: engine.ActionInstall}}} + if err := options.output(verify, rep, &engine.PartialError{Report: rep}); err != nil { + t.Fatal(err) + } + if err := json.Unmarshal(out.Bytes(), &got); err != nil { + t.Fatalf("partial output is not JSON: %v\n%s", err, out.String()) + } + if len(got.Entries) != 1 || got.Error == "" { + t.Fatalf("partial report = %+v, want the entries and the error", got) + } +} + func TestJSONCommandsReturnOutputErrors(t *testing.T) { project, _ := isolateCLI(t) if err := modfile.SaveMod(project, &modfile.Mod{SchemaVersion: modfile.SchemaVersion}); err != nil { @@ -157,6 +217,78 @@ func TestJSONCommandsReturnOutputErrors(t *testing.T) { } } +// TestJSONFallbackDocumentForHandlerFailures pins the other half of the +// single-document contract: a handler that fails before reaching output — an +// unknown --install-mode is the reachable case, because its validation lives +// in newEngine rather than in a cobra flag — still writes the document, while +// a flag error, which reaches no handler at all, keeps its plain stderr text. +func TestJSONFallbackDocumentForHandlerFailures(t *testing.T) { + project, _ := isolateCLI(t) + if err := modfile.SaveState(project, + &modfile.Mod{SchemaVersion: modfile.SchemaVersion}, + &modfile.Lock{SchemaVersion: modfile.SchemaVersion}); err != nil { + t.Fatal(err) + } + + run := func(args ...string) (code int, stdout, stderr string) { + t.Helper() + cmd, options := newRootCmd() + var out, errOut bytes.Buffer + cmd.SetOut(&out) + cmd.SetErr(&errOut) + cmd.SetArgs(args) + return execute(cmd, options), out.String(), errOut.String() + } + + code, stdout, stderr := run("--json", "--install-mode", "bogus", "list") + if code != ExitError { + t.Fatalf("handler failure exit code = %d, want %d", code, ExitError) + } + var rep struct { + Action string `json:"action"` + Entries []any `json:"entries"` + Error string `json:"error"` + } + if err := json.Unmarshal([]byte(stdout), &rep); err != nil { + t.Fatalf("stdout is not exactly one JSON document: %v\n%s", err, stdout) + } + if rep.Action != "list" || rep.Error == "" { + t.Errorf("document = %+v, want the list action and the failure named", rep) + } + if rep.Entries == nil { + t.Errorf("document = %s, want an entries array", stdout) + } + if stderr != "" { + t.Errorf("stderr = %q, want the document to carry the failure", stderr) + } + + // A flag error never reaches a handler, so it stays plain text with an + // empty stdout — the contract the document explicitly exempts. The + // diagnostic goes to the process's stderr, so it is captured there rather + // than from the cobra buffer. + oldStderr := os.Stderr + pipe, write, pipeErr := os.Pipe() + if pipeErr != nil { + t.Fatal(pipeErr) + } + os.Stderr = write + code, stdout, _ = run("--json", "--no-such-flag", "list") + os.Stderr = oldStderr + if closeErr := write.Close(); closeErr != nil { + t.Fatal(closeErr) + } + diagnostic, readErr := io.ReadAll(pipe) + if readErr != nil { + t.Fatal(readErr) + } + if code != ExitError || stdout != "" { + t.Errorf("flag error: code = %d, stdout = %q, want a plain failure", code, stdout) + } + if !strings.Contains(string(diagnostic), "no-such-flag") { + t.Errorf("flag error stderr = %q, want the flag named", diagnostic) + } +} + func TestRootCommandsDoNotShareFlagState(t *testing.T) { project, _ := isolateCLI(t) if err := modfile.SaveState(project, diff --git a/internal/cli/share.go b/internal/cli/share.go index 8741fb6..c602c59 100644 --- a/internal/cli/share.go +++ b/internal/cli/share.go @@ -53,7 +53,7 @@ func newShareCmd(options *rootOptions) *cobra.Command { share.Remove, share.Agents = targets, nil } rep, err := eng.Share(cmd.Context(), share, options.newIO(cmd), options.mutationOptions()) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().StringArrayVarP(&skills, "skill", "s", nil, i18n.Text("cli.share.flag_skill")) diff --git a/internal/cli/sync.go b/internal/cli/sync.go index bd5b366..d9d3c5c 100644 --- a/internal/cli/sync.go +++ b/internal/cli/sync.go @@ -27,7 +27,7 @@ func newSyncCmd(options *rootOptions) *cobra.Command { rep, err := eng.Sync(cmd.Context(), engine.SyncOptions{ CheckOnly: check, Relink: relink, DryRun: options.dryRun, }, options.newIO(cmd)) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().BoolVarP(&check, "check", "c", false, i18n.Text("cli.sync.flag_check")) diff --git a/internal/cli/update.go b/internal/cli/update.go index f8daa57..9cd38e7 100644 --- a/internal/cli/update.go +++ b/internal/cli/update.go @@ -26,7 +26,7 @@ func newUpdateCmd(options *rootOptions) *cobra.Command { rep, err := eng.Update(cmd.Context(), args, engine.UpdateOptions{ AllowDowngrade: allowDowngrade, DryRun: options.dryRun, }, options.newIO(cmd)) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } // --allow-downgrade deliberately has no shorthand: it overrides a safety diff --git a/internal/cli/upgrade.go b/internal/cli/upgrade.go index 9e02d34..0c3cafe 100644 --- a/internal/cli/upgrade.go +++ b/internal/cli/upgrade.go @@ -58,9 +58,9 @@ func (options *rootOptions) upgrade(cmd *cobra.Command, tag string, check bool) // is skipped on failure, where Execute reports the error instead. rep := upgradeReport(result, target, options.dryRun, err != nil) if err != nil { - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) } - return errors.Join(options.output(cmd, rep), reportUpgrade(rep, io, result, options.dryRun)) + return errors.Join(options.output(cmd, rep, nil), reportUpgrade(rep, io, result, options.dryRun)) } // upgradeReport renders one upgrade attempt as a report entry. The action diff --git a/internal/cli/verify.go b/internal/cli/verify.go index 5d87d15..a36d02c 100644 --- a/internal/cli/verify.go +++ b/internal/cli/verify.go @@ -23,7 +23,7 @@ func newVerifyCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.Verify(cmd.Context(), options.newIO(cmd)) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } } diff --git a/internal/cli/why.go b/internal/cli/why.go index 2b5b912..0966040 100644 --- a/internal/cli/why.go +++ b/internal/cli/why.go @@ -22,7 +22,7 @@ func newWhyCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.Why(cmd.Context(), args[0], options.newIO(cmd)) - return errors.Join(err, options.output(cmd, rep)) + return errors.Join(err, options.output(cmd, rep, err)) }, } } diff --git a/internal/engine/report.go b/internal/engine/report.go index 85cd7e0..9ef0bd1 100644 --- a/internal/engine/report.go +++ b/internal/engine/report.go @@ -4,7 +4,11 @@ package engine -import "github.com/huija/skillmod/internal/i18n" +import ( + "encoding/json" + + "github.com/huija/skillmod/internal/i18n" +) // Command is the stable machine-readable command that produced a report. type Command string @@ -77,6 +81,21 @@ type Report struct { Action Command `json:"action"` Entries []EntryReport `json:"entries"` Notes []string `json:"notes,omitempty"` + // Error names why the run failed. It is filled in for --json output only, + // so a document always carries the reason its command exited non-zero; + // without --json the same text reaches stderr instead. + Error string `json:"error,omitempty"` +} + +// MarshalJSON renders entries as an array even when the command produced none, +// so a consumer iterating the field never has to special-case null. +func (r Report) MarshalJSON() ([]byte, error) { + type report Report // Shadow the type to drop the custom marshaler. + shadow := report(r) + if shadow.Entries == nil { + shadow.Entries = []EntryReport{} + } + return json.Marshal(shadow) } // PartialError reports that at least one installation target was safely From b2cad38506a122eb6150b1142b5ae894696d2262 Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:52:53 +0800 Subject: [PATCH 6/9] perf: answer list from the cached reference snapshot list refreshed every declared repository with ls-remote on each run, which is what made list --global slow with many skills. Cache each snapshot with the time it was taken and reuse one younger than fifteen minutes, so a repeated list is local-only; update stays the command that deliberately contacts the remote, and an absent, unreadable, or aged-out snapshot is refreshed exactly as before. The fetch time is rewritten on every ls-remote, even when the tags are unchanged, because it is what tells a reader how old its cache is. --- internal/engine/engine.go | 4 +- internal/engine/engine_internal_test.go | 113 ++++++++++++++++++++++++ internal/engine/engine_test.go | 9 +- internal/engine/list.go | 36 ++++++-- internal/store/store.go | 27 ++++-- internal/store/store_test.go | 32 ++++++- 6 files changed, 198 insertions(+), 23 deletions(-) diff --git a/internal/engine/engine.go b/internal/engine/engine.go index 3fede0f..f9cb9fc 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -621,8 +621,8 @@ func (e *Engine) resolveAndFetch(ctx context.Context, repo, subdir, ref string, // ls-remote returns repository-wide refs. If another subdirectory already queried the same repository, // an exact tag can reuse that snapshot, while latest and update still force a remote refresh. if !resolve.IsPseudoVersion(ref) { - if cachedRefs, ok, _ := e.Store.GetRepoRefs(repo); ok { - cachedRes, resolveErr := resolve.Resolve(resolve.Request{Repo: repo, Subdir: subdir, Ref: ref}, cachedRefs) + if cached, ok, _ := e.Store.GetRepoRefs(repo); ok { + cachedRes, resolveErr := resolve.Resolve(resolve.Request{Repo: repo, Subdir: subdir, Ref: ref}, cached.Refs) // For a monorepo, trust only the highest-priority / match. // A cached root-tag match may be stale if the remote later added a more specific subdirectory tag. cacheHit := resolveErr == nil && cachedRes.Kind == resolve.KindTag && diff --git a/internal/engine/engine_internal_test.go b/internal/engine/engine_internal_test.go index 4d7d2cb..184aa7d 100644 --- a/internal/engine/engine_internal_test.go +++ b/internal/engine/engine_internal_test.go @@ -6,7 +6,11 @@ package engine import ( "bytes" + "context" + "encoding/json" "errors" + "io" + "io/fs" "os" "path/filepath" "runtime" @@ -18,9 +22,11 @@ import ( "github.com/huija/skillmod/internal/address" "github.com/huija/skillmod/internal/config" "github.com/huija/skillmod/internal/dirhash" + "github.com/huija/skillmod/internal/install" "github.com/huija/skillmod/internal/modfile" "github.com/huija/skillmod/internal/source" "github.com/huija/skillmod/internal/store" + "github.com/huija/skillmod/internal/testutil" ) func TestIOPrintfPropagatesWriteError(t *testing.T) { @@ -714,3 +720,110 @@ func TestSaveState_RecordsCanonicalSource(t *testing.T) { } } } + +// TestListAnswersFromAFreshRefsCacheAndRefreshWhenAgedOut covers both halves of +// the freshness window. A cache younger than refsCacheMaxAge keeps list local, +// so a tag published after the install is not noticed yet; the same cache aged +// out is refreshed over the network, so the tag then produces the upgrade notice. +// Asserting the two halves on one cache is what distinguishes "read the cache" +// from "never looks upstream", which is why both live here rather than in +// engine_test. +func TestListAnswersFromAFreshRefsCacheAndRefreshWhenAgedOut(t *testing.T) { + original := refsCacheMaxAge + refsCacheMaxAge = 0 + t.Cleanup(func() { refsCacheMaxAge = original }) + + r := testutil.NewRepo(t) + r.WriteSkill("", "hello") + r.CommitAll("v1") + r.Tag("v1.0.0") + r.Finish() + + root := t.TempDir() + s := store.New(t.TempDir()) + eng := &Engine{ + Root: root, + Source: &source.Source{VCSRoot: s.VCSRoot()}, + Store: s, + Config: &config.Config{InstallMode: install.Copy}, + } + if _, err := eng.Get(context.Background(), r.URL+"@v1.0.0", "", IO{Out: io.Discard, Yes: true}); err != nil { + t.Fatalf("Get(%q): %v", r.URL+"@v1.0.0", err) + } + + r.Write("v2.md", "x\n") + r.CommitAll("v2") + r.Evolve("v2.0.0", false) + + rep, err := eng.List(context.Background(), IO{Out: io.Discard, Yes: true}) + if err != nil { + t.Fatalf("List(): %v", err) + } + if len(rep.Entries) != 1 || !strings.Contains(rep.Entries[0].Note, "upgrade available") { + t.Fatalf("List entries = %+v, want the upgrade notice after an aged-out cache", rep.Entries) + } + + // A snapshot written before the fetch time existed carries none, and an + // unknown age must read as stale: treating it as fresh would answer a + // repeated list from a snapshot that could be any age. The file is located + // by glob so the store keeps deciding where it lives. + r.Write("v3.md", "x\n") + r.CommitAll("v3") + r.Evolve("v3.0.0", false) + legacy, err := stripRefsFetchedAt(s) + if err != nil { + t.Fatalf("strip fetchedAt: %v", err) + } + rep, err = eng.List(context.Background(), IO{Out: io.Discard, Yes: true}) + if err != nil { + t.Fatalf("List(): %v", err) + } + if len(rep.Entries) != 1 || !strings.Contains(rep.Entries[0].Note, "v3.0.0") { + t.Fatalf("List entries = %+v, want the tag a cache with no fetch time still reports", rep.Entries) + } + if _, err := os.Stat(filepath.Join(legacy)); err != nil { + t.Errorf("refs cache after a refreshed list: %v", err) + } +} + +// stripRefsFetchedAt rewrites every cached ls-remote snapshot in the store as a +// version written before the fetch time was recorded, and returns the path it +// rewrote. It finds the caches by name, which is the store's business, and only +// edits what it finds. +func stripRefsFetchedAt(s *store.Store) (string, error) { + var matches []string + err := filepath.WalkDir(s.CacheRoot(), func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if !d.IsDir() && d.Name() == "refs.json" { + matches = append(matches, path) + } + return nil + }) + if err != nil { + return "", err + } + if len(matches) == 0 { + return "", errors.New("no cached ls-remote snapshot to rewrite") + } + for _, path := range matches { + var rec map[string]json.RawMessage + data, err := os.ReadFile(path) + if err != nil { + return "", err + } + if err := json.Unmarshal(data, &rec); err != nil { + return "", err + } + delete(rec, "fetchedAt") + out, err := json.Marshal(rec) + if err != nil { + return "", err + } + if err := os.WriteFile(path, out, 0o600); err != nil { + return "", err + } + } + return matches[0], nil +} diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index f4c552d..3e3b678 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -2689,7 +2689,10 @@ func TestList(t *testing.T) { if len(rep.Entries) != 1 || rep.Entries[0].Action != "installed" { t.Errorf("list = %+v", rep.Entries) } - // A new upstream version produces an upgrade notice. + // A repeated list answers from the reference snapshot the install wrote, so + // a new upstream tag is not noticed until that snapshot ages out; the aged-out + // half of the contract is asserted in TestListAnswersFromAFreshRefsCache, + // which can age the window and TestList cannot. update refreshes on demand. r.Write("v2.md", "x\n") r.CommitAll("v2") r.Evolve("v2.0.0", false) @@ -2697,8 +2700,8 @@ func TestList(t *testing.T) { if err != nil { t.Fatal(err) } - if !strings.Contains(rep.Entries[0].Note, "upgrade available → ") { - t.Errorf("list did not report an available upgrade: %+v", rep.Entries[0]) + if strings.Contains(rep.Entries[0].Note, "upgrade available") { + t.Errorf("list refreshed a cache that is still fresh: %+v", rep.Entries[0]) } } diff --git a/internal/engine/list.go b/internal/engine/list.go index 627c384..14ecb43 100644 --- a/internal/engine/list.go +++ b/internal/engine/list.go @@ -9,11 +9,20 @@ import ( "time" "github.com/huija/skillmod/internal/i18n" + repoaddr "github.com/huija/skillmod/internal/repo" "github.com/huija/skillmod/internal/resolve" ) +// refsCacheMaxAge is how long a cached ls-remote snapshot stays fresh for +// list's upgrade detection. list is a read-only inspection command: within +// this window it answers from the local cache, and skillmod update is the +// command that deliberately contacts the remote. It is a variable so tests can +// age a cache without waiting. +var refsCacheMaxAge = 15 * time.Minute + // List implements skillmod list by reporting every declared entry as installed, missing, drifted, or upgradable. -// It is read-only. Upgrade detection calls ls-remote once per unique repository and skips failures. +// It is read-only. Upgrade detection calls ls-remote once per unique repository whose cached reference +// snapshot has gone stale, and skips failures. func (e *Engine) List(ctx context.Context, io IO) (*Report, error) { unlock, err := e.lockState() if err != nil { @@ -29,21 +38,36 @@ func (e *Engine) List(ctx context.Context, io IO) (*Report, error) { return nil, err } - // Call ls-remote once per unique repository on a best-effort basis. + // Call ls-remote once per unique repository on a best-effort basis, and + // only for repositories whose cached reference snapshot is older than the + // freshness window: a warm cache makes repeated list runs local-only, and + // update remains the command that deliberately refreshes. type latestKey struct{ repo, subdir string } latestCache := map[latestKey]string{} memo := newOperationMemo(nil) - var repositories []string + queried := map[string]bool{} + var stale []string for _, skill := range m.Skills { if skill.Local || findLock(lock, skill) == nil || resolve.IsPseudoVersion(skill.Version) { continue } repo, _, err := splitSource(skill.Source) - if err == nil { - repositories = append(repositories, repo) + if err != nil { + continue + } + identity := repoaddr.Identity(repo) + if queried[identity] { + continue + } + queried[identity] = true + cached, ok, cacheErr := e.Store.GetRepoRefs(repo) + if cacheErr == nil && ok && time.Since(cached.FetchedAt) < refsCacheMaxAge { + memo.refs[identity] = refsResult{refs: cached.Refs} + continue } + stale = append(stale, repo) // Absent, unreadable, or aged out: refresh it. } - e.loadRefsBestEffort(ctx, repositories, memo, 10*time.Second) + e.loadRefsBestEffort(ctx, stale, memo, 10*time.Second) rep := &Report{Action: CommandList} for _, sk := range m.Skills { diff --git a/internal/store/store.go b/internal/store/store.go index bd6fa83..04baa4e 100644 --- a/internal/store/store.go +++ b/internal/store/store.go @@ -12,7 +12,6 @@ package store import ( - "bytes" "crypto/sha256" "encoding/json" "errors" @@ -24,6 +23,7 @@ import ( "path/filepath" "slices" "strings" + "time" "github.com/huija/skillmod/internal/dirhash" "github.com/huija/skillmod/internal/filelock" @@ -607,6 +607,16 @@ func makeReadOnly(root string) error { type repoRefsRecord struct { Repo string `json:"repo"` Refs resolve.Refs `json:"refs"` + // FetchedAt records when the snapshot was taken, so a reader can reuse a + // recent one instead of contacting the remote on every read-only command. + FetchedAt time.Time `json:"fetchedAt"` +} + +// RepoRefs is one cached ls-remote snapshot: the reference set and when it was +// taken. +type RepoRefs struct { + Refs *resolve.Refs + FetchedAt time.Time } func (s *Store) repoRefsPath(repo string) string { @@ -619,7 +629,7 @@ func (s *Store) repoRefsPath(repo string) string { // GetRepoRefs returns the last complete ls-remote snapshot for a logical repo. // Callers may use positive exact-tag matches locally; latest/update must refresh. -func (s *Store) GetRepoRefs(repo string) (*resolve.Refs, bool, error) { +func (s *Store) GetRepoRefs(repo string) (*RepoRefs, bool, error) { p := s.repoRefsPath(repo) data, err := os.ReadFile(p) if errors.Is(err, fs.ErrNotExist) { @@ -641,17 +651,19 @@ func (s *Store) GetRepoRefs(repo string) (*resolve.Refs, bool, error) { if rec.Refs.Heads == nil { rec.Refs.Heads = map[string]string{} } - return &rec.Refs, true, nil + return &RepoRefs{Refs: &rec.Refs, FetchedAt: rec.FetchedAt}, true, nil } -// PutRepoRefs atomically records one complete ls-remote snapshot. Equal content -// is left untouched so multiple skills from the same repo do not churn the file. +// PutRepoRefs atomically records one complete ls-remote snapshot together with +// the time it was taken. The fetch time is rewritten on every call, even when +// the reference set is unchanged, because it is what tells a reader how old +// its cache is. func (s *Store) PutRepoRefs(repo string, refs *resolve.Refs) error { if refs == nil { return fmt.Errorf("%s", i18n.Text("store.cache_nil")) } p := s.repoRefsPath(repo) - rec := repoRefsRecord{Repo: repoaddr.Identity(repo), Refs: *refs} + rec := repoRefsRecord{Repo: repoaddr.Identity(repo), Refs: *refs, FetchedAt: time.Now()} data, err := json.Marshal(rec) if err != nil { return err @@ -661,9 +673,6 @@ func (s *Store) PutRepoRefs(repo string, refs *resolve.Refs) error { return err } defer unlock() - if existing, err := os.ReadFile(p); err == nil && bytes.Equal(existing, data) { - return nil - } if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil { return err } diff --git a/internal/store/store_test.go b/internal/store/store_test.go index d911ac5..82b865f 100644 --- a/internal/store/store_test.go +++ b/internal/store/store_test.go @@ -321,8 +321,11 @@ func TestRepoRefs_RoundTripAndCanonicalIdentity(t *testing.T) { if err != nil || !ok { t.Fatalf("GetRepoRefs = %+v, %v, %v", got, ok, err) } - if !reflect.DeepEqual(got, want) { - t.Fatalf("GetRepoRefs = %+v, want %+v", got, want) + if !reflect.DeepEqual(got.Refs, want) { + t.Fatalf("GetRepoRefs = %+v, want %+v", got.Refs, want) + } + if got.FetchedAt.IsZero() { + t.Fatal("GetRepoRefs returned no fetch time") } if err := s.PutRepoRefs("ssh://git@example.com:22/acme/skills.git", want); err != nil { t.Fatal(err) @@ -658,9 +661,12 @@ func TestRepoRefsCacheValidation(t *testing.T) { t.Fatal(err) } refs, ok, err := s.GetRepoRefs(repo) - if err != nil || !ok || refs.Tags == nil || refs.Heads == nil { + if err != nil || !ok || refs.Refs.Tags == nil || refs.Refs.Heads == nil { t.Fatalf("normalized refs = %+v, %v, %v", refs, ok, err) } + if refs.FetchedAt.IsZero() { + t.Fatal("cached refs carry no fetch time") + } path := s.repoRefsPath(repo) if err := os.WriteFile(path, []byte("{"), 0o600); err != nil { @@ -681,6 +687,26 @@ func TestRepoRefsCacheValidation(t *testing.T) { if _, _, err := s.GetRepoRefs(repo); err == nil || !strings.Contains(err.Error(), "identity mismatch") { t.Fatalf("mismatched refs error = %v", err) } + + // A snapshot written before the fetch time was recorded carries none, which + // reads as stale rather than as fresh: refreshing one old file is safe, + // treating an unknown age as new silently answers from a snapshot that may + // be any age. The record is still valid, so the hit succeeds. + legacy := repoRefsRecord{Repo: repo, Refs: resolve.Refs{Tags: map[string]string{"v1.0.0": "refs/tags/v1.0.0"}}} + data, err = json.Marshal(legacy) + if err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, data, 0o600); err != nil { + t.Fatal(err) + } + refs, ok, err = s.GetRepoRefs(repo) + if err != nil || !ok { + t.Fatalf("legacy refs = %+v, %v, %v", refs, ok, err) + } + if !refs.FetchedAt.IsZero() { + t.Errorf("legacy refs FetchedAt = %v, want the zero time that reads as stale", refs.FetchedAt) + } } func TestStoreErrorDiagnostics(t *testing.T) { From a98a8afcaefa060e065ce360119859e5bc0c185d Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:53:57 +0800 Subject: [PATCH 7/9] feat: adopt skills added outside skillmod with sync --adopt Skills that appear in the installation directory after a manual copy, an npx install, or a hand edit were invisible to sync: no declaration, no baseline, nothing keeping them from drifting. sync --adopt now declares each one as a local entry with its current content as the lock baseline, which is what init does for a machine's existing skills. No file is rewritten, so a later edit shows up as local drift instead of being reset; a directory a stale lock record occupies is left for prune, and two names differing only in case are refused rather than written into a declaration no other machine can materialize. A run without the flag only names the undeclared skills and points at it, so the feature is discoverable from the command that would otherwise ignore them. The summary states a run's preserved local edits instead of printing the same stable no-change line as an idle one; drift stays informational, and verify is the command that judges it. --- docs_test.go | 10 +- internal/cli/global_test.go | 51 ++++ internal/cli/root_test.go | 1 + internal/cli/sync.go | 5 +- internal/engine/adopt.go | 185 +++++++++++++ internal/engine/engine_test.go | 322 +++++++++++++++++++++++ internal/engine/report.go | 1 + internal/engine/sync.go | 63 ++++- locales/en_US.po | 55 ++++ locales/zh_CN.po | 54 ++++ skills/skillmod/references/automation.md | 2 +- 11 files changed, 729 insertions(+), 20 deletions(-) create mode 100644 internal/engine/adopt.go diff --git a/docs_test.go b/docs_test.go index 3e6f835..a9ce56f 100644 --- a/docs_test.go +++ b/docs_test.go @@ -31,11 +31,11 @@ var ( string(engine.CommandWhy), } documentedEntryActions = []string{ - engine.ActionConflict, engine.ActionDrift, engine.ActionInstall, engine.ActionInstalled, - engine.ActionKeep, engine.ActionLocal, engine.ActionLocalDrift, engine.ActionMatched, - engine.ActionMissing, engine.ActionPartial, engine.ActionPrune, engine.ActionRemove, - engine.ActionSkip, engine.ActionStale, engine.ActionUnlocked, engine.ActionUnresolved, - engine.ActionUnverifiable, engine.ActionUpdate, + engine.ActionAdopt, engine.ActionConflict, engine.ActionDrift, engine.ActionInstall, + engine.ActionInstalled, engine.ActionKeep, engine.ActionLocal, engine.ActionLocalDrift, + engine.ActionMatched, engine.ActionMissing, engine.ActionPartial, engine.ActionPrune, + engine.ActionRemove, engine.ActionSkip, engine.ActionStale, engine.ActionUnlocked, + engine.ActionUnresolved, engine.ActionUnverifiable, engine.ActionUpdate, } documentedTargetActions = []string{ engine.ActionDrift, engine.ActionInstall, engine.ActionInstalled, engine.ActionKeep, diff --git a/internal/cli/global_test.go b/internal/cli/global_test.go index da91a4e..b5b3452 100644 --- a/internal/cli/global_test.go +++ b/internal/cli/global_test.go @@ -5,11 +5,14 @@ package cli import ( + "bytes" + "encoding/json" "io" "os" "path/filepath" "testing" + "github.com/huija/skillmod/internal/engine" "github.com/huija/skillmod/internal/modfile" ) @@ -87,3 +90,51 @@ func TestInstallModeOverrideAndRelinkFlags(t *testing.T) { t.Error("sync accepted --check and --relink together") } } + +// TestSyncAdoptFlagWiring pins the flag end to end: sync --adopt declares a +// locally added skill, and --check refuses the combination instead of +// silently ignoring it. +func TestSyncAdoptFlagWiring(t *testing.T) { + project, _ := isolateCLI(t) + // An empty declaration, so the skill on disk is genuinely undeclared when + // sync runs. + if err := modfile.SaveState(project, + &modfile.Mod{SchemaVersion: modfile.SchemaVersion}, + &modfile.Lock{SchemaVersion: modfile.SchemaVersion}); err != nil { + t.Fatal(err) + } + writeInstalledSkill(t, project, "hello") + cmd := NewRootCmd() + cmd.SetOut(io.Discard) + cmd.SetErr(io.Discard) + cmd.SetArgs([]string{"sync", "--check", "--adopt", "--yes"}) + if err := cmd.Execute(); err == nil { + t.Error("sync accepted --check with --adopt") + } + + cmd = NewRootCmd() + var out bytes.Buffer + cmd.SetOut(&out) + cmd.SetErr(io.Discard) + cmd.SetArgs([]string{"--json", "sync", "--adopt", "--yes"}) + if err := cmd.Execute(); err != nil { + t.Fatalf("Execute(sync --adopt --yes) = %v", err) + } + var rep engine.Report + if err := json.Unmarshal(out.Bytes(), &rep); err != nil { + t.Fatalf("sync --adopt --json output = %q: %v", out.String(), err) + } + if len(rep.Entries) != 1 || rep.Entries[0].Action != engine.ActionAdopt { + t.Fatalf("sync --adopt report = %+v, want one adopted local entry", rep.Entries) + } + m, err := modfile.LoadMod(project) + if err != nil { + t.Fatal(err) + } + if len(m.Skills) != 1 || !m.Skills[0].Local { + t.Errorf("declarations after sync --adopt = %+v, want one local entry", m.Skills) + } + if _, err := os.Stat(filepath.Join(project, ".agents", "skills", "hello", "SKILL.md")); err != nil { + t.Errorf("adopted skill lost its content: %v", err) + } +} diff --git a/internal/cli/root_test.go b/internal/cli/root_test.go index 0d0c427..809db53 100644 --- a/internal/cli/root_test.go +++ b/internal/cli/root_test.go @@ -344,6 +344,7 @@ func TestFlagsCarryShorthands(t *testing.T) { "allow-downgrade": "it overrides a safety check", "all": "the letter is taken by --agent, and the long form reads better", "on-conflict": "the policy names are long; a letter would hide the meaning", + "adopt": "it is typed rarely, and a letter would not say what it adopts", } root := NewRootCmd() check := func(cmd *cobra.Command) { diff --git a/internal/cli/sync.go b/internal/cli/sync.go index d9d3c5c..ad108cc 100644 --- a/internal/cli/sync.go +++ b/internal/cli/sync.go @@ -13,7 +13,7 @@ import ( ) func newSyncCmd(options *rootOptions) *cobra.Command { - var check, relink bool + var check, relink, adopt bool cmd := &cobra.Command{ Use: "sync", Short: i18n.Text("cli.sync.short"), @@ -25,13 +25,14 @@ func newSyncCmd(options *rootOptions) *cobra.Command { return err } rep, err := eng.Sync(cmd.Context(), engine.SyncOptions{ - CheckOnly: check, Relink: relink, DryRun: options.dryRun, + CheckOnly: check, Relink: relink, Adopt: adopt, DryRun: options.dryRun, }, options.newIO(cmd)) return errors.Join(err, options.output(cmd, rep, err)) }, } cmd.Flags().BoolVarP(&check, "check", "c", false, i18n.Text("cli.sync.flag_check")) cmd.Flags().BoolVarP(&relink, "relink", "r", false, i18n.Text("cli.sync.flag_relink")) + cmd.Flags().BoolVar(&adopt, "adopt", false, i18n.Text("cli.sync.flag_adopt")) cmd.MarkFlagsMutuallyExclusive("check", "relink") return cmd } diff --git a/internal/engine/adopt.go b/internal/engine/adopt.go new file mode 100644 index 0000000..1765b76 --- /dev/null +++ b/internal/engine/adopt.go @@ -0,0 +1,185 @@ +// Copyright 2026 huija +// +// SPDX-License-Identifier: MIT + +package engine + +import ( + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + + "github.com/huija/skillmod/internal/dirhash" + "github.com/huija/skillmod/internal/fsutil" + "github.com/huija/skillmod/internal/i18n" + "github.com/huija/skillmod/internal/modfile" + "github.com/huija/skillmod/internal/source" +) + +// adoptCandidate is one skill directory in the installation directory that +// neither SKILL.mod nor SKILL.lock knows about. +type adoptCandidate struct { + dirName string // directory name, which becomes the installation directory + name string // frontmatter name, or the directory name when it is unreadable + dir string + hash string // baseline dirhash recorded in the lock + note string // extra provenance to report with the entry +} + +// reconcileUndeclaredSkills takes stock of the skill directories that exist on +// disk but in neither SKILL.mod nor SKILL.lock — the skills another tool such +// as npx, or a manual copy, put there. With adopt set, each one becomes a +// local declaration, which is what init does for a machine's existing skills. +// Content is never written: an adopted skill keeps exactly the files it has, +// and its lock record is the hash of those files, so a later edit shows up as +// local drift instead of being silently reset. Without adopt the scan only +// leaves a hint naming the flag, so the feature is discoverable from the +// command that would otherwise ignore those skills. A dry run plans the +// adoption but never asks: printing the plan must not block on a prompt, so +// every candidate is listed as pending and the notes say how a real run +// proceeds. +func (e *Engine) reconcileUndeclaredSkills(adopt, dryRun bool, m, newMod *modfile.Mod, lock, newLock *modfile.Lock, io IO, rep *Report) (int, error) { + candidates, skipped, err := e.undeclaredSkillDirs(m, lock) + if err != nil { + return 0, err + } + rep.Notes = append(rep.Notes, skipped...) + if len(candidates) == 0 { + return 0, nil + } + if !adopt { + hint := i18n.Format("engine.sync.undeclared_skills_found", len(candidates)) + if writeErr := io.printf("%s", hint); writeErr != nil { + return 0, writeErr + } + rep.Notes = append(rep.Notes, hint) + return 0, nil + } + if !dryRun && !io.Yes { + // The confirmation per skill is the one init asks, for the same reason: + // provenance is being recorded, and a run with no channel to ask + // through is told how to state the intent instead of guessing it. + if io.Confirm == nil { + return 0, fmt.Errorf("%s", i18n.Format("engine.sync.adopt_needs_confirmation", len(candidates))) + } + var kept []adoptCandidate + for _, candidate := range candidates { + confirmed, confirmErr := io.Confirm.Confirm(i18n.Format("engine.sync.adopt_confirm", candidate.name, candidate.dir)) + if confirmErr != nil { + return 0, confirmErr + } + if confirmed { + kept = append(kept, candidate) + } + } + if len(kept) == 0 { + return 0, fmt.Errorf("%s", i18n.Text("engine.sync.no_skills_adopted")) + } + candidates = kept + } + + adopted := 0 + for _, candidate := range candidates { + alias := "" + if candidate.dirName != candidate.name { + alias = candidate.dirName + } + newMod.Skills = append(newMod.Skills, modfile.ModSkill{Name: candidate.name, Alias: alias, Local: true}) + upsertLock(newLock, modfile.LockSkill{Name: candidate.name, Dirhash: candidate.hash, Dir: alias}) + note := i18n.Text("engine.sync.adopted_local_entry") + if dryRun { + note = i18n.Text("engine.sync.adopt_dry_run_entry") + } + // The action names the adoption rather than the steady state the entry + // reaches afterwards: a report says what this run did, the next sync + // sees an ordinary local entry, and a --json consumer can tell a + // planned adoption from an existing local entry inside one document — + // which reading the note would have required. + entry := EntryReport{Name: candidate.name, Directory: candidate.dirName, Action: ActionAdopt, Note: note} + entry.Note = appendNote(entry.Note, candidate.note) + rep.Entries = append(rep.Entries, entry) + if err := io.printf(" %s: %s", candidate.name, entry.Note); err != nil { + return adopted, err + } + adopted++ + } + if dryRun && !io.Yes { + // A dry run lists every candidate without asking, so the notes must + // say how the real run turns the plan into declarations. + rep.Notes = append(rep.Notes, i18n.Text("engine.sync.adopt_dry_run_confirm")) + } + return adopted, nil +} + +// undeclaredSkillDirs scans the installation directory for skill directories +// that neither the declaration nor the lock records. Unreadable directories, +// and directories whose name cannot be an installation directory, are reported +// as skipped notes instead of failing the whole sync, which keeps one broken +// skill from blocking every other entry. +func (e *Engine) undeclaredSkillDirs(m *modfile.Mod, lock *modfile.Lock) (candidates []adoptCandidate, skipped []string, err error) { + base := e.skillsDir() + dents, readErr := os.ReadDir(base) + if errors.Is(readErr, fs.ErrNotExist) { + return nil, nil, nil + } + if readErr != nil { + return nil, nil, readErr + } + declared := make(map[string]bool, len(m.Skills)) + for _, skill := range m.Skills { + declared[fsutil.FoldKey(skill.DirName())] = true + } + locked := make(map[string]bool, len(lock.Skills)) + for _, lk := range lock.Skills { + locked[fsutil.FoldKey(lk.InstallDir())] = true + } + folded := make(map[string]string, len(dents)) + for _, dent := range dents { + dir := filepath.Join(base, dent.Name()) + // os.Stat follows a symlinked skill directory the way init does, so a + // link that points at real content is adopted rather than skipped. + st, statErr := os.Stat(dir) + if statErr != nil || !st.IsDir() { + continue + } + if !hasSkillManifest(dir) { + continue + } + key := fsutil.FoldKey(dent.Name()) + if declared[key] || locked[key] { + continue // Managed already, by a declaration or a stale lock record. + } + if previous, duplicate := folded[key]; duplicate { + // Two directories that differ only in letter case map to one + // installation directory on Windows and macOS; adopting both would + // write a declaration no other machine can materialize. + return nil, nil, fmt.Errorf(i18n.Text("engine.sync.adopt_case_collision"), previous, dent.Name()) + } + folded[key] = dent.Name() + + candidate := adoptCandidate{dirName: dent.Name(), dir: dir} + name, nameErr := source.SkillNameFromDir(dir) + switch { + case nameErr == nil: + candidate.name = name + case fsutil.ValidName(dent.Name()) == nil: + // An unreadable SKILL.md is still adopted under the directory name, + // which is the only identity the filesystem guarantees. + candidate.name = dent.Name() + candidate.note = i18n.Text("engine.init.failed_parse_skill_md") + default: + skipped = append(skipped, i18n.Format("engine.sync.adopt_skipped", dir, nameErr)) + continue + } + hash, hashErr := dirhash.HashDir(dir) + if hashErr != nil { + skipped = append(skipped, i18n.Format("engine.sync.adopt_skipped", dir, hashErr)) + continue + } + candidate.hash = hash + candidates = append(candidates, candidate) + } + return candidates, skipped, nil +} diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index 3e3b678..c3d36eb 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -2915,3 +2915,325 @@ func TestWhyReportsImmutableProvenanceAndTargetResults(t *testing.T) { t.Error("Why(missing) succeeded") } } + +// TestSyncAdoptsLocallyAddedSkills covers the sync form of init's local +// adoption: a skill another tool or a manual copy left in the installation +// directory becomes a local declaration with its content untouched, and a +// second run is a no-op rather than a re-adoption. +func TestSyncAdoptsLocallyAddedSkills(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "added-later", "echo hi\n") + + rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()) + if err != nil { + t.Fatalf("Sync(adopt): %v", err) + } + var adopted *engine.EntryReport + for i := range rep.Entries { + if rep.Entries[i].Name == "added-later" { + adopted = &rep.Entries[i] + } + } + if adopted == nil || adopted.Action != engine.ActionAdopt || !strings.Contains(adopted.Note, "adopted") { + t.Fatalf("Sync(adopt) report = %+v, want an adopted local entry", rep.Entries) + } + m := loadMod(t, root) + if len(m.Skills) != 1 || !m.Skills[0].Local || m.Skills[0].Name != "added-later" { + t.Fatalf("declarations after adoption = %+v, want one local entry", m.Skills) + } + lk := loadLockSkill(t, root, "added-later") + if lk.Source != "" || lk.Dirhash == "" { + t.Fatalf("lock after adoption = %+v, want a local baseline with a dirhash", lk) + } + // The adopted content is exactly what was on disk. + if got := readFileString(t, filepath.Join(installedDir(root, "added-later"), "run.sh")); got != "echo hi\n" { + t.Errorf("adopted run.sh = %q, want the local content preserved", got) + } + + // A second run adopts nothing new and reports the local entry as consistent. + rep, err = eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()) + if err != nil { + t.Fatalf("second Sync(adopt): %v", err) + } + for _, entry := range rep.Entries { + if entry.Name == "added-later" && strings.Contains(entry.Note, "adopted as") { + t.Errorf("second run re-adopted: %+v", entry) + } + } +} + +// TestSyncAdoptRecordsTheDirectoryAsAlias covers a directory whose frontmatter +// name is not its own directory name, which is what a skill installed under a +// local name looks like. The declaration keeps the published name and records +// the directory as the alias, which is the only identity the filesystem offers. +func TestSyncAdoptRecordsTheDirectoryAsAlias(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + dir := filepath.Join(root, ".agents", "skills", "vendored-copy") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), + []byte("---\nname: published-name\ndescription: test skill\n---\n# x\n"), 0o644); err != nil { + t.Fatal(err) + } + + if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil { + t.Fatalf("Sync(adopt): %v", err) + } + m := loadMod(t, root) + if len(m.Skills) != 1 { + t.Fatalf("declarations after adoption = %+v, want one entry", m.Skills) + } + if m.Skills[0].Name != "published-name" || m.Skills[0].Alias != "vendored-copy" { + t.Errorf("declaration = %+v, want the published name with the directory as alias", m.Skills[0]) + } + // The installation directory stays the one on disk, so the entry resolves + // back to the files it came from. + if got := m.Skills[0].DirName(); got != "vendored-copy" { + t.Errorf("DirName() = %q, want the directory it was found in", got) + } + if _, err := os.Stat(filepath.Join(installedDir(root, "vendored-copy"), "SKILL.md")); err != nil { + t.Errorf("installation = %v, want kept under its own directory", err) + } +} + +// TestSyncWithoutAdoptOnlyNamesUndeclaredSkills keeps a plain sync from +// changing the declaration while still telling the user the flag exists. +func TestSyncWithoutAdoptOnlyNamesUndeclaredSkills(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "added-later", "") + + var out bytes.Buffer + rep, err := eng.Sync(ctx, engine.SyncOptions{}, engine.IO{Out: &out, Yes: true}) + if err != nil { + t.Fatalf("Sync: %v", err) + } + if len(loadMod(t, root).Skills) != 0 { + t.Errorf("declarations after a plain sync = %+v, want none", loadMod(t, root).Skills) + } + joined := strings.Join(rep.Notes, "\n") + out.String() + if !strings.Contains(joined, "--adopt") { + t.Errorf("plain sync output = %q, want the --adopt hint", joined) + } +} + +// TestSyncAdoptNeedsAChannelOrYes refuses to record provenance on a real run +// that can neither ask nor state the intent. A dry run is exempt: it only +// prints the plan, so it never needs an answer +// (TestSyncAdoptDryRunPlansWithoutAsking). +func TestSyncAdoptNeedsAChannelOrYes(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "added-later", "") + if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, engine.IO{Out: io.Discard}); err == nil { + t.Fatal("Sync(adopt) without a channel succeeded, want a diagnostic") + } + if len(loadMod(t, root).Skills) != 0 { + t.Errorf("declarations after a refused adoption = %+v, want none", loadMod(t, root).Skills) + } +} + +// TestSyncAdoptCheckIsRefused: --check only verifies, so the adoption flag has +// nothing to act on and saying so beats silently ignoring it. +func TestSyncAdoptCheckIsRefused(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + if _, err := eng.Sync(ctx, engine.SyncOptions{CheckOnly: true, Adopt: true}, testIO()); err == nil { + t.Fatal("Sync(--check --adopt) succeeded, want a refusal") + } +} + +// dryRunAskRecorder fails a dry run that consults the confirmation channel: +// printing a plan must never wait on input. +type dryRunAskRecorder struct{ asked bool } + +func (r *dryRunAskRecorder) Confirm(string) (bool, error) { + r.asked = true + return false, nil +} + +func (*dryRunAskRecorder) Choose(string, []string) (int, error) { return 0, nil } + +// TestSyncAdoptDryRunPlansWithoutAsking keeps a dry run from blocking on the +// adoption prompt: the plan lists every candidate as pending, the manifests +// stay untouched, the confirmation channel is never consulted, and a run +// without any channel still prints the plan instead of refusing. +func TestSyncAdoptDryRunPlansWithoutAsking(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "added-later", "echo hi\n") + + ask := &dryRunAskRecorder{} + rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true, DryRun: true}, engine.IO{Out: io.Discard, Confirm: ask}) + if err != nil { + t.Fatalf("Sync(adopt, dry-run): %v", err) + } + if ask.asked { + t.Error("dry run consulted the confirmation channel") + } + if skills := loadMod(t, root).Skills; len(skills) != 0 { + t.Errorf("declarations after a dry run = %+v, want none", skills) + } + var planned *engine.EntryReport + for i := range rep.Entries { + if rep.Entries[i].Name == "added-later" { + planned = &rep.Entries[i] + } + } + // The plan carries the adoption action, so a --json consumer can tell a + // pending adoption from an existing local entry in the same document + // without parsing the note. + if planned == nil || planned.Action != engine.ActionAdopt || !strings.Contains(planned.Note, "will be adopted") { + t.Fatalf("dry-run report = %+v, want a pending adoption entry", rep.Entries) + } + if notes := strings.Join(rep.Notes, "\n"); !strings.Contains(notes, "--yes") { + t.Errorf("dry-run notes = %q, want the real-run hint", notes) + } + + // Without any channel the dry run still succeeds: refusing to ask is a + // real-run refusal, not a plan-time one. + rep, err = eng.Sync(ctx, engine.SyncOptions{Adopt: true, DryRun: true}, engine.IO{Out: io.Discard}) + if err != nil { + t.Fatalf("Sync(adopt, dry-run) without a channel: %v", err) + } + if skills := loadMod(t, root).Skills; len(skills) != 0 { + t.Errorf("declarations after a channel-less dry run = %+v, want none", skills) + } + if len(rep.Entries) == 0 { + t.Error("channel-less dry run produced no planned entries") + } +} + +// TestSyncAdoptRejectsCaseCollidingDirectories keeps the portability guard init +// applies: two directories that differ only in letter case map to one +// installation directory on Windows and macOS, so adopting both would write a +// declaration no other machine can materialize. The run is refused before +// either declaration is written, and the message says how to get past it. +func TestSyncAdoptRejectsCaseCollidingDirectories(t *testing.T) { + root := t.TempDir() + if caseInsensitiveFS(root) { + t.Skip("requires a case-sensitive filesystem") + } + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + for _, dirName := range []string{"Demo", "demo"} { + writeLocalSkill(t, root, dirName, "echo hi\n") + } + + _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()) + if err == nil { + t.Fatal("Sync(adopt) accepted installation directories that collide when case is folded") + } + for _, want := range []string{"Demo", "demo", "rename"} { + if !strings.Contains(err.Error(), want) { + t.Errorf("Sync error = %v, want %q named", err, want) + } + } + if skills := loadMod(t, root).Skills; len(skills) != 0 { + t.Errorf("declarations after a refused adoption = %+v, want none", skills) + } +} + +// TestSyncSummaryNamesLocalDrift keeps the human summary from claiming "no +// changes" on a run whose most important fact is a detected and preserved +// local edit; the detail stays in the report, the summary must name it. +func TestSyncSummaryNamesLocalDrift(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "added-later", "echo hi\n") + if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil { + t.Fatalf("Sync(adopt): %v", err) + } + + // Edit the adopted skill behind sync's back, then run a plain sync. + skillMd := filepath.Join(installedDir(root, "added-later"), "SKILL.md") + if err := os.WriteFile(skillMd, []byte("---\nname: added-later\ndescription: edited\n---\n"), 0o644); err != nil { + t.Fatal(err) + } + var out bytes.Buffer + rep, err := eng.Sync(ctx, engine.SyncOptions{}, engine.IO{Out: &out, Yes: true}) + if err != nil { + t.Fatalf("Sync: %v", err) + } + drifted := false + for _, entry := range rep.Entries { + if entry.Action == engine.ActionLocalDrift { + drifted = true + } + } + if !drifted { + t.Fatalf("Sync report = %+v, want a local-drift entry", rep.Entries) + } + joined := strings.Join(rep.Notes, "\n") + out.String() + if !strings.Contains(joined, "differ from their lock records") { + t.Errorf("sync summary = %q, want the local-drift line", joined) + } + if strings.Contains(joined, "no changes") { + t.Errorf("sync summary = %q, must not claim no changes while local edits exist", joined) + } + + // The drifted lock record is untouched: sync informs, it does not re-baseline. + if lk := loadLockSkill(t, root, "added-later"); lk.Dirhash == "" { + t.Errorf("lock after a drifted sync = %+v, want the original baseline kept", lk) + } +} + +// TestSyncAdoptLeavesStaleLockRecordsForPrune: a directory a lock record still +// occupies is not local content to adopt, it is a stale declaration's remains. +func TestSyncAdoptLeavesStaleLockRecordsForPrune(t *testing.T) { + root := t.TempDir() + eng := newEngine(t, root, t.TempDir()) + if _, err := eng.Init(ctx, false, testIO()); err != nil { + t.Fatalf("Init: %v", err) + } + writeLocalSkill(t, root, "declared", "") + if _, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()); err != nil { + t.Fatalf("Sync(adopt): %v", err) + } + // Hand-edit the declaration away, exactly the state prune exists for. + m := loadMod(t, root) + m.Skills = nil + if err := modfile.SaveMod(root, m); err != nil { + t.Fatal(err) + } + writeLocalSkill(t, root, "brand-new", "") + + rep, err := eng.Sync(ctx, engine.SyncOptions{Adopt: true}, testIO()) + if err != nil { + t.Fatalf("Sync(adopt) with a stale record: %v", err) + } + for _, entry := range rep.Entries { + if entry.Name == "declared" && strings.Contains(entry.Note, "adopted as") { + t.Errorf("stale lock record was adopted: %+v", entry) + } + } + if got := loadMod(t, root).Skills; len(got) != 1 || got[0].Name != "brand-new" { + t.Errorf("declarations = %+v, want only brand-new adopted", got) + } +} diff --git a/internal/engine/report.go b/internal/engine/report.go index 9ef0bd1..f067598 100644 --- a/internal/engine/report.go +++ b/internal/engine/report.go @@ -32,6 +32,7 @@ const ( CommandVerify Command = "verify" CommandWhy Command = "why" + ActionAdopt = "adopt" ActionConflict = "conflict" ActionDrift = "drift" ActionInstall = "install" diff --git a/internal/engine/sync.go b/internal/engine/sync.go index 84d5979..ec775f2 100644 --- a/internal/engine/sync.go +++ b/internal/engine/sync.go @@ -7,6 +7,7 @@ package engine import ( "context" "errors" + "fmt" "github.com/huija/skillmod/internal/dirhash" "github.com/huija/skillmod/internal/i18n" @@ -18,12 +19,18 @@ import ( type SyncOptions struct { CheckOnly bool Relink bool - DryRun bool + // Adopt declares the skill directories that exist on disk but in neither + // manifest as local entries, the way init adopts existing skills. + Adopt bool + DryRun bool } // Sync reconciles local skill directories with SKILL.lock: // it is idempotent and verifiable, rolls back on failure, and never deletes installed files automatically. func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, error) { + if options.CheckOnly && options.Adopt { + return nil, fmt.Errorf("%s", i18n.Text("engine.sync.adopt_with_check")) + } if options.CheckOnly { return e.Verify(ctx, io) // sync --check is an alias for verify and uses the same implementation. } @@ -45,6 +52,10 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, if err != nil { return nil, err } + // Adopted entries join the declaration here, so the saved mod carries them + // alongside the declared ones. An unchanged copy marshals to the same bytes + // saveState already read, so a sync that adopts nothing still writes nothing. + newMod := &modfile.Mod{SchemaVersion: m.SchemaVersion, Skills: append([]modfile.ModSkill(nil), m.Skills...)} rep := &Report{Action: CommandSync} var plans []plannedInstall var conflicts []conflict @@ -119,6 +130,16 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, } } + // Take stock of the skills another tool or a manual copy left in the + // installation directory. They are not failures and not drift, so this + // runs after the declared entries are classified and never touches files: + // --adopt declares them as local entries, and a plain sync only names them. + // A dry run plans the adoption without asking, so the plan never blocks. + adopted, err := e.reconcileUndeclaredSkills(options.Adopt, options.DryRun, m, newMod, lock, newLock, io, rep) + if err != nil { + return nil, err + } + // Leave stale entry files untouched and recommend prune. for _, lk := range staleEntries(m, lock) { rep.Entries = append(rep.Entries, EntryReport{ @@ -189,8 +210,8 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, } // Keep past destinations for cleanup, and record all currently declared // ones even when this machine did not have an installed copy before sync. - for _, skill := range m.Skills { - targets, err := e.shareTargetsFor(m, skill.DirName()) + for _, skill := range newMod.Skills { + targets, err := e.shareTargetsFor(newMod, skill.DirName()) if err != nil { return nil, err } @@ -212,7 +233,9 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, } skipped := skippedConflictCount(conflicts, skip) var writeErr error - if planned == 0 && skipped > 0 { + if planned == 0 && adopted > 0 { + writeErr = io.printf(i18n.Format("engine.sync.dry_run_adopt_planned", adopted)) + } else if planned == 0 && skipped > 0 { writeErr = io.printf(i18n.Format("engine.sync.dry_run_writes_planned", skipped)) } else if planned == 0 { writeErr = io.printf(i18n.Text("engine.sync.dry_run_everything_already")) @@ -227,7 +250,7 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, if err != nil { return nil, err } - if err := e.saveState(m, newLock); err != nil { + if err := e.saveState(newMod, newLock); err != nil { return nil, errors.Join(err, finalize(false)) } if err := finalize(true); err != nil { @@ -243,20 +266,36 @@ func (e *Engine) Sync(ctx context.Context, options SyncOptions, io IO) (*Report, } changed := 0 + drifted := 0 for _, en := range rep.Entries { if en.Action == ActionInstall || en.Action == ActionPartial { changed++ } - } - if changed == 0 { - if skipped := skippedConflictCount(conflicts, skip); skipped > 0 { - err = io.printf(i18n.Format("engine.sync.changes_conflicting_targets", skipped)) - } else { - err = io.printf(i18n.Text("engine.sync.changes")) // Idempotency requires a stable no-change result. + if en.Action == ActionLocalDrift { + drifted++ } - } else { + } + skipped := skippedConflictCount(conflicts, skip) + switch { + case changed == 0 && adopted > 0: + err = io.printf(i18n.Format("engine.sync.adopted_entries", adopted)) + case changed == 0 && skipped > 0: + err = io.printf(i18n.Format("engine.sync.changes_conflicting_targets", skipped)) + case changed == 0 && drifted == 0: + err = io.printf(i18n.Text("engine.sync.changes")) // Idempotency requires a stable no-change result. + case changed > 0: err = io.printf(i18n.Text("engine.sync.synchronized_entries"), changed) } + // A run with only drifted local entries prints the drift line alone; the + // four cases above all describe alignment work that did not happen. + if drifted > 0 { + // None of the summaries above name local edits: a run can report no + // changes, or install remote entries, while sync silently detected + // and preserved the modified local ones. State it explicitly; drift + // is the designed steady state for a local entry, not a failure — + // verify is the command that judges it. + err = errors.Join(err, io.printf(i18n.Format("engine.sync.local_drift_preserved", drifted))) + } return rep, errors.Join(err, partialError(rep, conflicts, skip)) } diff --git a/locales/en_US.po b/locales/en_US.po index c02f6e0..42897dc 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -213,6 +213,9 @@ msgstr "Record installed skills as linked into other agent directories" msgid "cli.share.use" msgstr "share [skills...]" +msgid "cli.sync.flag_adopt" +msgstr "declare skills added outside skillmod as local entries" + msgid "cli.sync.flag_check" msgstr "verify without modifying anything (alias for skillmod verify)" @@ -957,6 +960,41 @@ msgstr "restore %s: %w" msgid "engine.state.stage_removal" msgstr "stage removal of %s: %w" +#, go-format +msgid "engine.sync.adopt_case_collision" +msgstr "two skills differ only by letter case: %s and %s, which map to one " +"installation directory; rename one of the directories" + +#, go-format +msgid "engine.sync.adopt_confirm" +msgstr "adopt %s (%s) as a local entry?" + +msgid "engine.sync.adopt_dry_run_confirm" +msgstr "a real run confirms each one; pass --yes to adopt all" + +msgid "engine.sync.adopt_dry_run_entry" +msgstr "will be adopted as a local entry on a real run" + +#, go-format +msgid "engine.sync.adopt_needs_confirmation" +msgstr "found %d undeclared skills; pass --yes to adopt them all, or run in" +" a terminal to choose" + +#, go-format +msgid "engine.sync.adopt_skipped" +msgstr "skipped %s: %s" + +msgid "engine.sync.adopt_with_check" +msgstr "--adopt cannot be combined with --check, which only verifies and ne" +"ver writes" + +#, go-format +msgid "engine.sync.adopted_entries" +msgstr "adopted %d local entries" + +msgid "engine.sync.adopted_local_entry" +msgstr "adopted as a local entry" + msgid "engine.sync.baseline_re_established" msgstr "baseline re-established from the installed files (the previous remo" "te lock record was removed)" @@ -978,6 +1016,10 @@ msgstr "consistent" msgid "engine.sync.contents_match_baseline_local" msgstr "contents do not match the baseline (local changes)" +#, go-format +msgid "engine.sync.dry_run_adopt_planned" +msgstr "dry-run: %d undeclared skills would be adopted" + #, go-format msgid "engine.sync.dry_run_entries_installed" msgstr "dry-run: %d entries would be installed or updated" @@ -989,6 +1031,11 @@ msgstr "dry-run: everything is already consistent" msgid "engine.sync.dry_run_writes_planned" msgstr "dry-run: no writes planned; %d conflicting targets would be kept" +#, go-format +msgid "engine.sync.local_drift_preserved" +msgstr "%d local entries differ from their lock records; edits are kept as-" +"is" + msgid "engine.sync.missing" msgstr "missing: " @@ -996,6 +1043,9 @@ msgid "engine.sync.no_baseline" msgstr "no baseline in the lock; verification skipped (run init again to es" "tablish one)" +msgid "engine.sync.no_skills_adopted" +msgstr "no undeclared skills were adopted" + msgid "engine.sync.removed_mod_files_kept" msgstr "removed from the mod; files were kept—run skillmod prune to clean" " them" @@ -1007,6 +1057,11 @@ msgstr "recreating some share links failed; run sync again to retry" msgid "engine.sync.synchronized_entries" msgstr "synchronized %d entries; verification passed" +#, go-format +msgid "engine.sync.undeclared_skills_found" +msgstr "found %d undeclared skills; run skillmod sync --adopt to declare th" +"em as local entries" + msgid "engine.update.already_up_to_date" msgstr "already up to date" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index 254fc6b..2409c77 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -211,6 +211,9 @@ msgstr "把已安装技能记录为链接到其他 agent 目录" msgid "cli.share.use" msgstr "share [技能名...]" +msgid "cli.sync.flag_adopt" +msgstr "把 skillmod 之外新增的 skill 收录为本地条目" + msgid "cli.sync.flag_check" msgstr "只校验不修改(skillmod verify 的别名)" @@ -941,6 +944,41 @@ msgstr "恢复 %s 失败:%w" msgid "engine.state.stage_removal" msgstr "暂存删除 %s 失败:%w" +#, go-format +msgid "engine.sync.adopt_case_collision" +msgstr "两个 skill 仅大小写不同:%s 与 %s,会映射到同一个" +"安装目录;请重命名其中一个目录" + +#, go-format +msgid "engine.sync.adopt_confirm" +msgstr "将 %s(%s)收录为本地条目?" + +msgid "engine.sync.adopt_dry_run_confirm" +msgstr "真实运行将逐个确认;传 --yes 全部收录" + +msgid "engine.sync.adopt_dry_run_entry" +msgstr "真实运行将收录为本地条目" + +#, go-format +msgid "engine.sync.adopt_needs_confirmation" +msgstr "发现 %d 个未声明 skill;传 --yes 全部收录,或在终" +"端中选择" + +#, go-format +msgid "engine.sync.adopt_skipped" +msgstr "跳过 %s:%s" + +msgid "engine.sync.adopt_with_check" +msgstr "--adopt 不能与 --check 同时使用;--check 只校验、不写" +"任何文件" + +#, go-format +msgid "engine.sync.adopted_entries" +msgstr "已收录 %d 个本地条目" + +msgid "engine.sync.adopted_local_entry" +msgstr "已收录为本地条目" + msgid "engine.sync.baseline_re_established" msgstr "已从已安装文件重建本地基线(此前的 remote lock 记" "录已移除)" @@ -962,6 +1000,10 @@ msgstr "一致" msgid "engine.sync.contents_match_baseline_local" msgstr "内容与基线不符(本地改动)" +#, go-format +msgid "engine.sync.dry_run_adopt_planned" +msgstr "dry-run: 将收录 %d 个未声明 skill" + #, go-format msgid "engine.sync.dry_run_entries_installed" msgstr "dry-run: %d 个条目将被安装或更新" @@ -973,6 +1015,10 @@ msgstr "dry-run: 所有条目已一致" msgid "engine.sync.dry_run_writes_planned" msgstr "试运行:没有计划写入;将保留 %d 个冲突目标" +#, go-format +msgid "engine.sync.local_drift_preserved" +msgstr "%d 个本地条目与锁定记录不一致(改动保留)" + msgid "engine.sync.missing" msgstr "缺失: " @@ -980,6 +1026,9 @@ msgid "engine.sync.no_baseline" msgstr "lock 中无基线记录,跳过校验(重新 init 可建立基" "线)" +msgid "engine.sync.no_skills_adopted" +msgstr "没有收录任何未声明 skill" + msgid "engine.sync.removed_mod_files_kept" msgstr "已从 mod 移除,文件保留;运行 skillmod prune 清理" @@ -990,6 +1039,11 @@ msgstr "重建部分分享链接失败;再次运行 sync 可重试" msgid "engine.sync.synchronized_entries" msgstr "已同步 %d 项,校验通过" +#, go-format +msgid "engine.sync.undeclared_skills_found" +msgstr "发现 %d 个未声明 skill;运行 skillmod sync --adopt 可将" +"它们收录为本地条目" + msgid "engine.update.already_up_to_date" msgstr "已是最新" diff --git a/skills/skillmod/references/automation.md b/skills/skillmod/references/automation.md index 100de27..4111925 100644 --- a/skills/skillmod/references/automation.md +++ b/skills/skillmod/references/automation.md @@ -27,7 +27,7 @@ of each installation directory. | Field | Meaning | `action` values | | --- | --- | --- | | `action` | The command that produced the report | `get`, `init`, `list`, `prune`, `remove`, `share`, `sync`, `update`, `upgrade`, `verify`, `why` | -| `entries[].action` | The aggregate outcome of one declaration | `conflict`, `drift`, `install`, `installed`, `keep`, `local`, `local-drift`, `matched`, `missing`, `partial`, `prune`, `remove`, `skip`, `stale`, `unlocked`, `unresolved`, `unverifiable`, `update` | +| `entries[].action` | The aggregate outcome of one declaration | `adopt`, `conflict`, `drift`, `install`, `installed`, `keep`, `local`, `local-drift`, `matched`, `missing`, `partial`, `prune`, `remove`, `skip`, `stale`, `unlocked`, `unresolved`, `unverifiable`, `update` | | `entries[].targetResults[].action` | The outcome of one installation directory | `drift`, `install`, `installed`, `keep`, `missing`, `remove`, `skip`, `unlocked`, `unverifiable` | Per-directory facts appear only in `targetResults`, which is where a conflicting From 8b927c8d930748e1b844a8baa6aa3d5acfbcfa5a Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 15:54:33 +0800 Subject: [PATCH 8/9] docs: rewrite the front door in plain language and cover the new behavior The README and the agent skill read like a spec: long sentences, abstract nouns, and two sections that mostly repeated each other. Rewrite both in plain language, drop "Why this exists" and "What you get" into one short paragraph, and let the five-minute tour use the github.com default. The Chinese README keeps the same outline, as the structure test requires. The references are updated to match the behavior that changed with them: the address grammar and the discovery layouts in manifests.md, the reference-snapshot freshness window in storage.md, the repository selector and sync --adopt in use-cases.md, and the one-document --json contract with its error field in automation.md. CONTRIBUTING.md picks up the branch protection note that was sitting in the stash: changes reach main only through pull requests, so the tag landing procedure waits on the PR CI run rather than a direct push. --- CONTRIBUTING.md | 10 +- README.md | 257 +++++++++++------------ README_CN.md | 166 +++++++++------ skills/skillmod/SKILL.md | 134 ++++++------ skills/skillmod/references/automation.md | 31 ++- skills/skillmod/references/manifests.md | 36 +++- skills/skillmod/references/storage.md | 9 +- skills/skillmod/references/use-cases.md | 64 +++++- 8 files changed, 407 insertions(+), 300 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 958f3d0..796ee33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,8 @@ see [README.md](README.md) and the agent skill under - Go 1.26.6 or later, and `git` on `PATH`. - Run `make check` before opening a pull request; CI enforces the same gate. +- Changes reach `main` only through pull requests: branch protection requires + the CI checks to pass before a merge can land. ## The gate @@ -50,10 +52,10 @@ sees them: at its root, because `upgrade` locates the binary by base name. Because the archives are not built until the release run, the check that catches -a platform break before the tag is the ordinary one: land the change on `main`, -wait for CI to go green, and only then push the tag. The release workflow -re-runs every gate before publishing, so a failure there leaves a tag that has to -be deleted or moved. +a platform break before the tag is the ordinary one: merge the change through a +pull request, wait for CI to go green on `main`, and only then push the tag. The +release workflow re-runs every gate before publishing, so a failure there leaves +a tag that has to be deleted or moved. ## User-facing text diff --git a/README.md b/README.md index d15d127..0e8139a 100644 --- a/README.md +++ b/README.md @@ -2,107 +2,79 @@ English | [简体中文](README_CN.md) -A skill dependency manager for agent projects, in the spirit of Go modules: -**declare what the project needs in `SKILL.mod`, pin the exact content in -`SKILL.lock`, and let `skillmod sync` make every machine identical.** +skillmod manages Agent Skills the way Go modules manage dependencies. You +write down what a project needs in `SKILL.mod`, skillmod pins the exact +content in `SKILL.lock`, and `skillmod sync` makes every machine agree. -AGENTS.md tells an agent *how to behave*; `SKILL.mod` declares *which -capabilities it needs*. +AGENTS.md tells an agent how to behave. `SKILL.mod` says which skills it +needs to behave that way. ## What it does ```mermaid flowchart LR - mod["SKILL.mod
declare"] --> lock["SKILL.lock
pin content"] - lock --> sync["skillmod sync
reconcile"] + mod["SKILL.mod
what you need"] --> lock["SKILL.lock
exact content"] + lock --> sync["skillmod sync
make it so"] sync --> inst["installed skills
.agents/skills"] inst --> share["skillmod share
.claude .codex ..."] inst -.-> verify["skillmod verify
CI gate"] ``` -- **Declare** the skills a project needs in a reviewable `SKILL.mod`. -- **Sync** every machine into byte-identical agreement with the declaration — - idempotent, and never overwriting local edits. -- **Verify** that installed content still matches the lock; a drift fails the - build. -- **Share** installed skills with any agent through links in `./skills`. -- **Update** to the newest immutable version of a skill — no registry required; - publishing a skill is tagging a repository you already own. +- **Declare** the skills a project needs in `SKILL.mod`, a small file you + review and commit. +- **Sync** every machine to that declaration. Running it twice changes + nothing the second time, and it never throws away work you did locally. +- **Verify** that what is installed is still what the lock says. A drift + exits non-zero, so `verify` drops straight into CI. +- **Share** installed skills with other agents through links, so `.claude`, + `.codex`, and friends can use one installed set. +- **Update** a skill to its newest version. There is no registry to run: + publishing a skill means tagging a repository you already own. + +The problem it solves: skills shape what an agent does, but managing them by +hand leaves no record of what is installed, and copying them around is how +two machines end up behaving differently. skillmod keeps the declaration, +the exact content, and the installed copies in one place, and tells you when +they stop agreeing. ## When you need it -One skill on one machine needs none of this; the declaration pays for itself -as soon as any of the following holds: +One skill on one laptop needs none of this. It starts paying off as soon as +any of these is true: -- **More than one machine** works with the project — a teammate's checkout, a - CI job, your second laptop — and all of them should install the same skills, - byte for byte. -- **More than one consumer** trusts the declaration — CI must prove the - installed skills are exactly what was declared, so an edited or tampered - skill fails the build. -- **More than one agent** runs on one machine — `.claude`, `.codex`, - workbuddy, ... share one installed set, each with its own links. +- **More than one machine** works on the project — a teammate's checkout, a + CI job, your second laptop — and all of them should end up with the same + skills. +- **Something has to prove it** — CI checks that the installed skills are the + declared ones, so an edited or tampered skill fails the build. +- **More than one agent** runs on one machine and should share one installed + set, each with its own links. | When you want to | Use | | --- | --- | | Bring an existing project or machine under management | `init` | | Add a skill from any Git repository | `get` | -| Make every machine identical to the declaration | `sync` | +| Make every machine agree with the declaration | `sync` | | Fail the build when an installed skill drifted | `verify` | | Point other agents at installed skills | `share` | -| Explain where a skill came from and what state it is in | `why` | -| Move to the newest version, or back out cleanly | `update` / `remove` | - -## Why this exists - -Skills — packaged instructions and scripts — shape what an agent does, but -managing them is stuck in a pre-dependency-manager era. Manual copies leave no -record of what was installed. Git submodules make every consumer clone a whole -repository and run Git to obtain a folder of Markdown. Platform marketplaces -install into machine-local state, so a teammate's agent, a CI job, and your -laptop drift apart. The symptoms are always the same: agents behave -differently on different machines, "which version was in use" has no answer, -and an edited or tampered skill goes unnoticed. - -skillmod applies the Go module model: declarations in `SKILL.mod`, content -addressed by dirhash in `SKILL.lock`, idempotent reconciliation through -`skillmod sync`. There is no registry to run — publishing a skill means -creating a tag in a repository you already own. - -## What you get - -- **Every machine gets the same skills, byte for byte.** -- **"Which version was in use" has an answer** — the lock records the requested - version, the resolved commit, and the content hash. -- **Edits and tampering are caught** — `verify` exits non-zero on drift, which - is what makes it usable as a CI gate. -- **Local work is never silently overwritten** — a modified installation is - kept and reported with exit code 3 until a person decides what to do with it. -- **Skills are fetched once and then reused** — one immutable snapshot per - repository version is shared by every project on the machine and linked - rather than copied, so a second project installs from disk. -- **Nothing else is required** — no registry, no server, no telemetry; Git is - the only external dependency. +| Ask where a skill came from and what state it is in | `why` | +| Move to a newer version, or back out cleanly | `update` / `remove` | ## Five minutes ```console -$ skillmod get github.com/openai/skills//gh-fix-ci --install-mode=copy --yes +$ skillmod get openai/skills//gh-fix-ci --install-mode=copy --yes installed gh-fix-ci v0.0.0-20260624023612-49f948faa925; SKILL.mod and SKILL.lock were updated ``` -The repository is named once and the skill once: after `//` the skill name is -enough, so the directory layout inside the repository does not have to be typed -or remembered. An exact subdirectory still wins over a name, and a name that -several skills answer is reported with the candidate paths instead of guessed. -The declaration records where the skill actually lives, as the `source` line -below shows. - -`SKILL.mod` is the declaration you review and commit. `SKILL.lock` is written by -skillmod and records what the declaration resolved to: +The host defaults to `github.com`, so `owner/repo` is enough, and `//` picks +the skill inside the repository by name — you do not need to know where in +the repository it lives. An exact path still wins over a name, and a name +that several skills answer is listed with its candidates instead of guessed. +Whatever the skill's real path is, that is what `source` records: ```toml -# SKILL.mod — maintained by people +# SKILL.mod — you maintain this schemaversion = 1 [[skill]] @@ -112,7 +84,7 @@ version = 'v0.0.0-20260624023612-49f948faa925' ``` ```toml -# SKILL.lock — maintained by skillmod +# SKILL.lock — skillmod maintains this schemaversion = 1 [[skill]] @@ -123,8 +95,8 @@ commit = '49f948faa9258a0c61caceaf225e179651397431' dirhash = 'h1:kiGlVBeTCF8Q9f0rPATnDn1jBn/obT3TTTL8D8gdCbM=' ``` -Now edit an installed skill the way an unreviewed change would, and ask whether -the project still matches its lock: +Now edit an installed skill the way nobody meant to, and ask whether the +project still matches its lock: ```console $ echo "Always rebase." >> .agents/skills/gh-fix-ci/SKILL.md @@ -145,7 +117,7 @@ gh-fix-ci (directory gh-fix-ci): github.com/openai/skills//skills/.curated/gh-fi /tmp/agent-project/.agents/skills/gh-fix-ci: drift ``` -`sync` will not throw that edit away to make itself look clean: +`sync` will not throw your edit away just to look clean: ```console $ skillmod sync --yes @@ -155,33 +127,28 @@ $ echo $? 3 ``` -Exit code 3 is the point: work that could proceed did proceed, and the decision -about your edit stays with you. Keep it as the project's local version, or run -`skillmod sync` interactively and choose *overwrite* to restore the locked -content. +Exit code 3 is the point: the work that could go ahead did, and the decision +about your edit stays with you. Keep it as the project's local version, or +run `skillmod sync` interactively and choose *overwrite* to restore the +locked content. ## Install ### Agent-guided installation (recommended) -With Node.js/npm available, install the companion Agent Skill globally so your -coding agent can set up and operate skillmod from any project: +With Node.js and npm available, install the companion Agent Skill globally so +your coding agent can set up and operate skillmod from any project: ```bash npx skills add huija/skillmod --skill skillmod --global ``` -Then ask your agent: - -```text -Install skillmod and make it available on PATH. -``` - -The skill checks the Git prerequisite and any existing skillmod installation, -selects the release binary for the current operating system and architecture, -verifies it against the published SHA-256 checksums, installs it in a -user-writable directory on `PATH`, and verifies the result. Omit `--global` when -the guidance should be available only in the current project. +Then ask your agent to install skillmod and put it on your `PATH`. The skill +checks the Git prerequisite and any existing installation, picks the release +binary for your operating system and architecture, verifies it against the +published checksums, installs it somewhere `PATH` can see, and checks the +result. Drop `--global` when only the current project should get the +guidance. ### Manual installation @@ -195,71 +162,85 @@ With Go 1.26.6 or later: go install github.com/huija/skillmod@latest ``` -Either way, upgrade in place later with `skillmod upgrade`, which verifies the -download against the release checksums before it replaces the executable. +Either way, `skillmod upgrade` later replaces the executable in place, after +verifying the download against the release checksums. -For local development from a repository checkout, `make install` puts the binary -in `go env GOBIN`, or the first `GOPATH/bin` entry when `GOBIN` is unset, and -embeds the current Git revision. See [CONTRIBUTING.md](CONTRIBUTING.md). +For local development, `make install` builds the binary into `go env GOBIN` +(or the first `GOPATH/bin` entry) and embeds the current Git revision; see +[CONTRIBUTING.md](CONTRIBUTING.md). ## Prerequisites -skillmod invokes the system `git` executable to fetch sources, so Git must be -installed and on `PATH` (on Windows, install -[Git for Windows](https://gitforwindows.org/); it is not preinstalled). SSH -remotes additionally require `ssh` on `PATH`. +skillmod shells out to `git` to fetch skills, so Git must be installed and on +`PATH` (on Windows, install [Git for Windows](https://gitforwindows.org/) — +it does not come with the system). SSH remotes also need `ssh` on `PATH`. ## Everyday commands | Command | What it does | | --- | --- | -| `init` | Adopt skills that already exist on disk into `SKILL.mod` and `SKILL.lock` | +| `init` | Adopt the skills that already exist on disk into `SKILL.mod` and `SKILL.lock` | | `get
` | Add a skill and install it | -| `sync` | Reconcile installations with the lock; idempotent, and never overwrites local edits | +| `sync` | Bring installations in line with the lock; safe to run any number of times, and never overwrites local edits | | `share` | Link installed skills into agent directories such as `.claude` or `.codex`; see [Share with agents](#share-with-agents) | | `list` | Show every declaration, its version, and its installation status | | `why ` | Explain one entry: source, resolved version, commit, dirhash, and per-target status | -| `update [selector]` | Move entries to the newest immutable version — the highest tag wins and only tagless repositories track HEAD; refuses a silent downgrade of tag locks | +| `update [selector]` | Move entries to the newest immutable version — the highest tag wins, and only a tagless repository tracks HEAD | | `verify` | Check installed content against the lock; the CI gate | | `remove [selector]` | Delete declarations and clean managed installations; with `--agent`, unlink only those agents and keep the skills | | `prune` | Drop stale installations and lock records left behind by hand edits | | `upgrade` | Replace the running executable with a published release, verified against its checksums | -`skillmod --global init` declares the skills the user already has in -`~/.agents/skills/`; `skillmod init` declares the project's own. The two -adoptions are independent steps in either order, and the two manifests stay -independent, so a command reaches the machine only when it carries -`--global`; -[use-cases.md](skills/skillmod/references/use-cases.md) walks through both -scopes. - -Every command accepts `--json` (`-j`) for machine-readable output and `--global` -(`-g`) to operate on user-wide skills instead of the current project; mutations -accept `--dry-run` (`-n`) and `--yes` (`-y`). `get` also accepts `--alias` -(`-a`), `init` accepts `--force` (`-f`), `sync` accepts `--check` (`-c`) and -`--relink` (`-r`), `share` accepts `--skill` (`-s`), `--agent` (`-a`), and -`--remove` (`-r`), `remove` accepts `--skill` (`-s`) and `--agent` (`-a`), and `upgrade` accepts -`--check` (`-c`) and `--tag` (`-t`). - -`get`, `remove`, and `share` accept `--all`, which states the whole set instead -of asking for it: every skill the repository publishes, every declared entry, -and every installed skill respectively. `--yes` is the other half of that pair — -it answers the confirmations that follow a selection and never decides what the -selection is. `--all`, `--install-mode`, `--allow-downgrade`, and -`--on-conflict` deliberately have no shorthand: the obvious letters are -ambiguous or already taken, and the long forms read better. - -Command help, summaries, prompts, and errors follow `SKILLMOD_LANG` when it is -set and the system locale otherwise; JSON field names and action identifiers are -never translated. +`skillmod --global init` adopts the skills the user already has in +`~/.agents/skills/`; `skillmod init` adopts the project's own. The two scopes +are independent — separate manifests, either order — so a command reaches +the machine only when it carries `--global`. + +Every command accepts `--json` (`-j`) and `--global` (`-g`). Mutations accept +`--dry-run` (`-n`) and `--yes` (`-y`). `get` also accepts `--alias` (`-a`), +`init` accepts `--force` (`-f`), `sync` accepts `--check` (`-c`), +`--relink` (`-r`), and `--adopt`, `share` accepts `--skill` (`-s`), +`--agent` (`-a`), and `--remove` (`-r`), `remove` accepts `--skill` (`-s`) +and `--agent` (`-a`), and `upgrade` accepts `--check` (`-c`) and `--tag` +(`-t`). + +`--json` writes one machine-readable document to stdout and nothing else, +including when the command fails — a failed run carries an `error` field and +still exits with the same code. Human output disappears in that mode, so +scripts never have to tell the two apart. `--adopt` on `sync` takes stock of +skills that were added outside skillmod — by `npx`, by a copy, by hand — and +declares them as local entries with their current content as the baseline; +your files are never rewritten. A plain `sync` only names them and points at +the flag. + +`get`, `remove`, and `share` accept `--all`, which states the whole set +instead of asking for it: every skill the repository publishes, every +declared entry — or every entry a repository selector names — and every +installed skill respectively. `--yes` is the other +half of that pair — it answers the confirmations that follow a selection and +never decides what the selection is. `--all`, `--install-mode`, +`--allow-downgrade`, `--on-conflict`, and `--adopt` deliberately have no +shorthand: the obvious letters are ambiguous or already taken, and the long +forms read better. + +Both `get` and `remove` take a repository instead of a name. `get +owner/repo//name` installs one skill; `remove owner/repo` lists the skills +declared from that repository and lets you pick which ones go, exactly like +`get` lists the skills a repository publishes. Adding `--all` takes them all +without a terminal, which is how a script says "everything this repository +brought in". + +Command help, prompts, summaries, and errors follow `SKILLMOD_LANG` when it +is set and the system locale otherwise. JSON field names and action +identifiers are never translated. ## Share with agents An agent is named by one directory segment and reads its skills from `./skills`, so any agent works — well-known ones like `.claude` and -`.codex` and any other single-segment name alike. Each skill records the agents -it is linked to on its own entry in `SKILL.mod`, and `sync` recreates the -links on every machine: +`.codex` and any other single-segment name alike. Each skill records the +agents it is linked to on its own entry in `SKILL.mod`, and `sync` recreates +the links on every machine: ```console $ skillmod share --all --agent claude --agent workbuddy --yes @@ -270,8 +251,8 @@ $ skillmod share --all --agent claude --agent workbuddy --yes ## Where the details live -Rather than grow this README into a manual, the rules live with the Agent Skill -that operates skillmod. Both people and agents can read them: +This README stays a front door. The rules live with the Agent Skill that +operates skillmod, and both people and agents can read them: | Read | For | | --- | --- | @@ -286,9 +267,9 @@ that operates skillmod. Both people and agents can read them: ## Current limitations - No registry service; a skill is a Git repository, and publishing is tagging. -- No transitive dependencies and no version-constraint solving. Declarations are - flat, one entry per skill. -- No skill-content security scanning or telemetry. +- No transitive dependencies and no version-constraint solving. Declarations + are flat, one entry per skill. +- No skill-content security scanning and no telemetry. ## License diff --git a/README_CN.md b/README_CN.md index 67ecd96..e6da466 100644 --- a/README_CN.md +++ b/README_CN.md @@ -2,71 +2,67 @@ [English](README.md) | 简体中文 -面向 agent 项目的 skill 依赖管理器,设计血统来自 go mod: -**在 `SKILL.mod` 里声明项目需要什么,用 `SKILL.lock` 锁定内容,再由 `skillmod sync` 让每台机器完全一致。** +skillmod 用 go mod 的方式管理 Agent Skill:在 `SKILL.mod` 里写下项目需要什么, +skillmod 把确切的内容锁进 `SKILL.lock`,再由 `skillmod sync` 让每台机器保持一致。 -与 AGENTS.md 的关系:AGENTS.md 告诉 agent *怎么行为*,`SKILL.mod` 声明 agent *需要什么能力*。 +AGENTS.md 告诉 agent 该怎么做事;`SKILL.mod` 说明它做事需要哪些技能。 ## 它做什么 ```mermaid flowchart LR - mod["SKILL.mod
声明"] --> lock["SKILL.lock
锁定内容"] + mod["SKILL.mod
声明需要什么"] --> lock["SKILL.lock
锁定确切内容"] lock --> sync["skillmod sync
对齐安装"] sync --> inst["已安装技能
.agents/skills"] inst --> share["skillmod share
.claude .codex ..."] inst -.-> verify["skillmod verify
CI 关卡"] ``` -- **声明(Declare)**:在可评审的 `SKILL.mod` 里列出项目需要的技能。 -- **对齐(Sync)**:让每台机器与声明逐字节一致——幂等执行,且绝不覆盖本地修改。 -- **校验(Verify)**:检查已安装内容是否仍与锁文件一致;有漂移就让构建失败。 -- **分发(Share)**:通过 `.<名字>/skills` 里的链接,把已安装技能交给任意 agent。 -- **更新(Update)**:升级到技能最新的不可变版本——无需 registry;发布一个技能就是给自己的仓库打个 tag。 +- **声明**:把项目需要的技能写进 `SKILL.mod`,一个小文件,评审后提交。 +- **对齐**:`sync` 让每台机器符合这份声明。重复执行不会改变任何东西, + 本地做过的修改也不会被它丢掉。 +- **校验**:`verify` 检查已安装内容是否还和锁文件一致。有漂移就以非零码 + 退出,可以直接挂进 CI。 +- **分享**:通过链接把已安装的技能交给其他 agent,`.claude`、`.codex` + 都能共用同一套安装。 +- **更新**:`update` 把技能升级到最新版本。没有需要维护的 registry—— + 发布一个技能,就是给自己的仓库打个 tag。 + +它解决的问题是:技能决定 agent 的行为,但手工管理留不下"装了什么"的 +记录,靠拷贝分发,两台机器迟早行为不一致。skillmod 把声明、确切内容和 +已安装的副本放在一处,它们不再一致时会告诉你。 ## 什么时候需要它 -单机单技能并不需要它;以下任一情况成立,这份声明就开始回本: +一台机器、一个技能,用不上它。只要下面有一条成立,它就值回价钱: -- **不止一台机器**会用到这个项目——同事的检出、CI 任务、你的第二台笔记本——它们都应装出逐字节相同的技能。 -- **不止一个消费方**依赖这份声明——CI 必须证明已安装技能与声明的完全一致,被改过或篡改的技能会让构建失败。 -- **不止一个 agent**运行在同一台机器上——`.claude`、`.codex`、workbuddy……共用一套安装,各自持有自己的链接。 +- **不止一台机器**在做这个项目——同事的检出、CI、你的第二台笔记本—— + 它们最后应该拿到同一套技能。 +- **需要有人证明这件事**——CI 检查已安装技能就是声明的那批,被改过、 + 被篡改的技能会让构建失败。 +- **一台机器上跑着多个 agent**,它们共用一套安装,各自持有自己的链接。 | 你想做的事 | 用 | | --- | --- | | 把现有项目或机器纳入管理 | `init` | | 从任意 Git 仓库添加一个技能 | `get` | -| 让每台机器与声明完全一致 | `sync` | -| 技能有漂移时让构建失败 | `verify` | +| 让每台机器符合声明 | `sync` | +| 技能漂移时让构建失败 | `verify` | | 把已安装技能交给其他 agent | `share` | -| 说明一个技能从哪来、现在什么状态 | `why` | -| 升级到最新版本,或干净地退出 | `update` / `remove` | - -## 为什么需要它 - -skill(指令 + 脚本的打包单元)决定 agent 的行为,但它的管理停留在前依赖管理时代。手工拷贝留不下"装了什么"的记录;git submodule 让每个使用方都要克隆整仓、用 git 才能拿到一个 Markdown 目录;各平台市场把技能装进机器本地状态,于是同事的 agent、CI 和你自己的笔记本会悄悄分叉。症状是相同的:同团队不同机器行为不一致、"当时用的是哪个版本"回答不了、内容被改过或篡改也无法察觉。 - -skillmod 用 go mod 的同构方案解决:`SKILL.mod` 声明 + `SKILL.lock`(dirhash 内容寻址)锁定 + `skillmod sync` 幂等对齐。没有需要运维的 registry——发布一个 skill 就是在自己的仓库里打个 tag。 - -## 你能得到什么 - -- **每台机器拿到逐字节相同的技能。** -- **"当时用的是哪个版本"有答案**——锁文件记录请求的版本、解析出的 commit 和内容哈希。 -- **改动与篡改会被发现**——`verify` 在漂移时以非零码退出,因此可以直接当作 CI 关卡。 -- **本地修改不会被静默覆盖**——被改过的安装会保留下来并以退出码 3 报告,把决定权交回给人。 -- **技能只取一次,之后复用**——同一仓库版本的不可变快照在整机共享,安装用链接而不是拷贝,第二个项目直接从磁盘安装。 -- **不需要额外基础设施**——无 registry、无服务端、无遥测,外部依赖只有 Git。 +| 查一个技能从哪来、现在什么状态 | `why` | +| 升级到新版本,或干净地退出 | `update` / `remove` | ## 五分钟 ```console -$ skillmod get github.com/openai/skills//gh-fix-ci --install-mode=copy --yes +$ skillmod get openai/skills//gh-fix-ci --install-mode=copy --yes 已安装 gh-fix-ci v0.0.0-20260624023612-49f948faa925,SKILL.mod 与 SKILL.lock 已更新 ``` -仓库只写一次,技能名只写一次:`//` 后面直接用技能名即可,不需要记住或输入仓库内部的目录结构。精确存在的子目录仍然优先;同名技能有多个候选时,skillmod 会列出候选路径让用户选择,而不是自己猜。声明里记录的是技能真实所在的路径,也就是下面 `source` 那一行。 - -`SKILL.mod` 是人维护、需要提交的声明;`SKILL.lock` 由 skillmod 写入,记录声明解析出的结果: +主机名默认是 `github.com`,所以写 `owner/repo` 就够了;`//` 后面写技能名 +就能选中仓库里的技能,不需要知道它在仓库的哪个目录。确实存在的目录优先 +于名字;有多个技能同名时报出候选列表,不让它猜。无论技能实际在哪, +`source` 记下来的都是真实路径: ```toml # SKILL.mod —— 人维护 @@ -90,7 +86,8 @@ commit = '49f948faa9258a0c61caceaf225e179651397431' dirhash = 'h1:kiGlVBeTCF8Q9f0rPATnDn1jBn/obT3TTTL8D8gdCbM=' ``` -现在像"一次没人审查的修改"那样改动已安装的技能,再问项目是否仍与锁文件一致: +现在改一下已安装的技能——就像一次没人审批的修改那样——再问项目是否还和 +锁文件一致: ```console $ echo "先 rebase。" >> .agents/skills/gh-fix-ci/SKILL.md @@ -101,7 +98,7 @@ $ echo $? 2 ``` -`why` 解释这个条目的来源,以及它哪里不对: +`why` 说明这个条目从哪来、哪里不对: ```console $ skillmod why gh-fix-ci @@ -111,7 +108,7 @@ gh-fix-ci(目录 gh-fix-ci):github.com/openai/skills//skills/.curated/gh-f /tmp/agent-project/.agents/skills/gh-fix-ci:drift ``` -`sync` 不会为了让报告好看而丢掉这次修改: +`sync` 不会为了报告好看丢掉这次修改: ```console $ skillmod sync --yes @@ -121,43 +118,50 @@ $ echo $? 3 ``` -退出码 3 正是关键:能独立完成的工作已经完成,而关于这次修改的决定留给你。你可以把它当作项目的本地版本保留,也可以交互式运行 `skillmod sync` 并选择 *overwrite* 恢复锁定内容。 +退出码 3 正是关键:能独立完成的工作已经完成,这次修改怎么处置留给你。 +可以把它当作项目的本地版本留着,也可以交互式运行 `skillmod sync`,选择 +*overwrite* 恢复锁定的内容。 ## 安装 ### 使用 Agent 引导安装(推荐) -准备好 Node.js/npm 后,全局安装仓库内附带的 Agent Skill,让编码 Agent 可以在任意项目中安装和使用 skillmod: +准备好 Node.js 和 npm 后,全局安装仓库内附带的 Agent Skill,编码 Agent +就能在任意项目里安装和使用 skillmod: ```bash npx skills add huija/skillmod --skill skillmod --global ``` -然后告诉 Agent: - -```text -安装 skillmod,并确保它可以从 PATH 调用。 -``` - -该 Skill 会检查 Git 前置条件和已有的 skillmod 安装,识别当前操作系统与架构,选择对应的 Release Binary,使用发布的 SHA-256 校验和进行验证,将可执行文件安装到 `PATH` 中用户可写的目录,并验证安装结果。如果只希望当前项目使用这份引导,请省略 `--global`。 +然后让 Agent 把 skillmod 装好并加进 `PATH`。这个 Skill 会检查 Git 前置 +条件和已有的安装,识别当前操作系统与架构,选择对应的 Release 二进制, +按发布的校验和验证后装进 `PATH` 能访问的目录,并验证安装结果。只希望 +当前项目用上这份引导时,去掉 `--global`。 ### 手动安装 -不使用 Go 时,从 [GitHub Releases](https://github.com/huija/skillmod/releases) 下载对应平台的压缩包和 `checksums.txt`,校验压缩包后解压,并将 `skillmod` 放入 `PATH`。 +不用 Go 的话,从 [GitHub Releases](https://github.com/huija/skillmod/releases) +下载对应平台的压缩包和 `checksums.txt`,校验后解压,把 `skillmod` 放进 +`PATH`。 -使用 Go 1.26.6 或更高版本: +用 Go 1.26.6 或更高版本时: ```bash go install github.com/huija/skillmod@latest ``` -无论用哪种方式安装,之后都可以用 `skillmod upgrade` 原地升级:它会先按发布校验和验证下载内容,再替换可执行文件。 +两种方式之后都可以用 `skillmod upgrade` 原地升级:先按发布校验和验证 +下载内容,再替换可执行文件。 -从仓库源码本地开发时,`make install` 会把二进制装到 `go env GOBIN`;未设置 `GOBIN` 时用第一个 `GOPATH/bin`,并写入当前 Git revision。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 +本地开发时,`make install` 把二进制装到 `go env GOBIN`(未设置时用第一个 +`GOPATH/bin`),并写入当前 Git revision;详见 +[CONTRIBUTING.md](CONTRIBUTING.md)。 ## 前置条件 -skillmod 通过系统 `git` 可执行文件获取源码,因此必须安装 Git 并加入 `PATH`(Windows 请安装 [Git for Windows](https://gitforwindows.org/),系统默认不带);SSH 远程地址还需要 `PATH` 中有 `ssh`。 +skillmod 通过系统的 `git` 获取技能,所以必须安装 Git 并加入 `PATH` +(Windows 请安装 [Git for Windows](https://gitforwindows.org/),系统默认 +不带);SSH 远程地址还需要 `PATH` 里有 `ssh`。 ## 常用命令 @@ -165,37 +169,67 @@ skillmod 通过系统 `git` 可执行文件获取源码,因此必须安装 Git | --- | --- | | `init` | 把磁盘上已有的技能登记进 `SKILL.mod` 和 `SKILL.lock` | | `get <地址>` | 添加并安装一个技能 | -| `sync` | 按锁文件对齐安装,幂等,且不会覆盖本地修改 | +| `sync` | 按锁文件对齐安装;可以反复执行,且不会覆盖本地修改 | | `share` | 把已安装技能链接到 agent 目录(如 `.claude`、`.codex`);见[分享给 agent](#分享给-agent) | | `list` | 列出全部声明、版本和安装状态 | | `why <选择器>` | 说明单个条目:来源、解析版本、commit、dirhash 和各目标状态 | -| `update [选择器]` | 把条目更新到最新的不可变版本——最高标签优先,仅无标签仓库跟随 HEAD;拒绝标签锁的静默降级 | +| `update [选择器]` | 把条目更新到最新的不可变版本——最高 tag 优先,只有无 tag 的仓库跟随 HEAD | | `verify` | 校验已安装内容与锁文件是否一致,即 CI 关卡 | -| `remove [选择器]` | 删除声明和内容未改动的受管安装;带 `--agent` 时仅解除这些 agent 的分享,保留技能 | +| `remove [选择器]` | 删除声明和内容未改动的受管安装;带 `--agent` 时只解除这些 agent 的链接,保留技能 | | `prune` | 清理手工编辑后残留的过期安装和锁记录 | | `upgrade` | 用已发布的版本替换当前可执行文件,替换前按发布校验和验证 | -`skillmod --global init` 登记用户在 `~/.agents/skills/` 里已有的技能;`skillmod init` 登记项目自身的技能。两次纳管相互独立、先后随意;两份清单也相互独立,因此只有带 `--global` 的命令才作用于机器级;两个作用域的完整流程见 [use-cases.md](skills/skillmod/references/use-cases.md)。 - -所有命令都支持 `--json`(`-j`,机器可读输出)和 `--global`(`-g`,作用于用户级技能而非当前项目),写操作支持 `--dry-run`(`-n`)和 `--yes`(`-y`)。`get` 还支持 `--alias`(`-a`),`init` 支持 `--force`(`-f`),`sync` 支持 `--check`(`-c`)和 `--relink`(`-r`),`share` 支持 `--skill`(`-s`)、`--agent`(`-a`)和 `--remove`(`-r`),`remove` 支持 `--skill`(`-s`)和 `--agent`(`-a`),`upgrade` 支持 `--check`(`-c`)和 `--tag`(`-t`)。 - -`get`、`remove` 和 `share` 支持 `--all`,用于直接指认整批目标而不进入询问:分别是仓库发布的全部技能、全部已声明条目、全部已安装技能。`--yes` 是这条分工的另一半——它只回答选择之后的确认,从不用来决定选择什么。`--all`、`--install-mode`、`--allow-downgrade` 与 `--on-conflict` 刻意不设短写:显而易见的字母会产生歧义或已被占用,且长写更易读。 - -命令帮助、摘要、交互提示和错误信息优先采用 `SKILLMOD_LANG`,未设置时跟随系统 locale;JSON 的字段名和 action 标识不会翻译。 +`skillmod --global init` 登记用户在 `~/.agents/skills/` 里已有的技能; +`skillmod init` 登记项目自身的技能。两个作用域相互独立——各自的清单, +先后随意——所以只有带 `--global` 的命令才作用于整台机器。 + +所有命令都支持 `--json`(`-j`)和 `--global`(`-g`);写操作支持 +`--dry-run`(`-n`)和 `--yes`(`-y`)。`get` 还支持 `--alias`(`-a`), +`init` 支持 `--force`(`-f`),`sync` 支持 `--check`(`-c`)、 +`--relink`(`-r`)和 `--adopt`,`share` 支持 `--skill`(`-s`)、 +`--agent`(`-a`)和 `--remove`(`-r`),`remove` 支持 `--skill`(`-s`) +和 `--agent`(`-a`),`upgrade` 支持 `--check`(`-c`)和 `--tag`(`-t`)。 + +`--json` 只在 stdout 写一份机器可读的文档,其他什么都没有;命令失败时 +也一样——失败的那份带 `error` 字段,退出码不变。这个模式下不再输出人读的 +内容,脚本不必去分辨两种格式。`sync` 的 `--adopt` 处理 skillmod 之外新增的 +技能——npx 装的、拷贝来的、手动放的——把它们登记为本地条目,并用当前内容 +作为基线;文件本身一个字节都不会改。普通 `sync` 只提醒你有这些技能,并 +指出这个开关。 + +`get`、`remove` 和 `share` 支持 `--all`,直接指认整批目标而不进入询问: +分别是仓库发布的全部技能、全部已声明条目(传仓库时则是该仓库声明的全部 +条目)、全部已安装技能。`--yes` 是这条分工的另一半——它只回答选择之后的 +确认,从不用来决定选择什么。`--all`、`--install-mode`、 +`--allow-downgrade`、`--on-conflict` 和 `--adopt` 刻意不设短写:显而易见 +的字母会产生歧义或已被占用,且长写更易读。 + +`get` 和 `remove` 都可以直接传仓库。`get owner/repo//name` 安装一个技能; +`remove owner/repo` 列出这个仓库声明过的技能,让你像 `get` 选技能一样 +挑出要删的那些;加上 `--all` 则一次删光,无需终端,这是脚本表达"这个 +仓库带来的全部技能"的方式。 + +命令帮助、交互提示、摘要和错误信息优先采用 `SKILLMOD_LANG`,未设置时跟随 +系统 locale;JSON 的字段名和 action 标识不会翻译。 ## 分享给 agent -agent 用一个目录段命名,并从 `.<名字>/skills` 读取技能,因此任意 agent 都可用——`.claude`、`.codex` 这样的知名名字和其他任意单段名字一视同仁。每个技能在自己的 `SKILL.mod` 条目上记录链接到的 agent 名,由 `sync` 在每台机器上重建链接: +agent 用一个目录段命名,从 `.<名字>/skills` 读取技能,所以任意 agent 都能 +用——`.claude`、`.codex` 这样的知名名字和其他任意单段名字一视同仁。每个 +技能在自己的 `SKILL.mod` 条目上记录链接到哪些 agent,由 `sync` 在每台机器 +上重建链接: ```console $ skillmod share --all --agent claude --agent workbuddy --yes ``` -`share --remove --agent <名称>` 解除分享并保留技能;`remove --agent <名称>` 只解除一个 agent 的链接,不影响其他 agent。 +`share --remove --agent <名称>` 解除分享并保留技能; +`remove --agent <名称>` 只解除一个 agent 的链接,不影响其他 agent。 ## 详细文档在哪 -这份 README 不再扩写成手册:具体规则放在操作 skillmod 的那个 Agent Skill 里,人和 agent 都可以读。**这些参考文档目前只有英文版。** +这份 README 只当前门。具体规则放在操作 skillmod 的那个 Agent Skill 里, +人和 agent 都可以读: | 阅读 | 内容 | | --- | --- | diff --git a/skills/skillmod/SKILL.md b/skills/skillmod/SKILL.md index e0d8656..2fd7eb5 100644 --- a/skills/skillmod/SKILL.md +++ b/skills/skillmod/SKILL.md @@ -5,88 +5,72 @@ description: Install, configure, use, and troubleshoot skillmod, or prepare a we # skillmod -skillmod is a Git-based dependency manager for Agent Skills: `SKILL.mod` -declares what a project needs, `SKILL.lock` pins the exact content, and -`skillmod sync` makes every machine identical. Reach for it when the user -wants to share one skill set across machines, teammates, or CI, or to point -agent directories such as `.claude` or `.codex` at installed skills. +skillmod manages Agent Skills the way Go modules manage dependencies. The +project declares what it needs in `SKILL.mod`, skillmod pins the exact +content in `SKILL.lock`, and `skillmod sync` makes every machine agree. -Help users install and operate skillmod safely. Match the user's language and -experience level. Explain the outcome first, then show only the commands needed -for the current task. +Reach for it when skills have to be the same on more than one machine, when +CI has to prove the installed skills are the declared ones, or when several +agents on one machine should share one installed set. -## Route the request +Help the user install and run skillmod safely. Answer in their language, +match their experience, and lead with the outcome before the commands. -- For prerequisite checks, first-time installation, upgrades of the executable, - or PATH problems, read [references/setup.md](references/setup.md). -- For project/global setup, dependency operations, CI, inspection, updates, - removal, or troubleshooting, read - [references/use-cases.md](references/use-cases.md). -- For manifest rules, accepted address and version forms, aliases, and what the - files deliberately leave out, read - [references/manifests.md](references/manifests.md). -- For the shared cache, installation modes, configuration file, or where - declarations and installations live, read - [references/storage.md](references/storage.md). -- For exit codes and the JSON report vocabulary that scripts and CI branch on, - read [references/automation.md](references/automation.md). -- When the user explicitly wants to report a problem, or diagnosis strongly - indicates a skillmod defect, read - [references/issue-reporting.md](references/issue-reporting.md). +## Where to look -Read only the references needed for the current request. Installation is not -required before explaining concepts or drafting an issue. +| The request is about | Read | +| --- | --- | +| Installing or upgrading the executable, prerequisites, PATH problems | [references/setup.md](references/setup.md) | +| Setting up a project or the machine, adding or removing skills, CI, checking state | [references/use-cases.md](references/use-cases.md) | +| What belongs in `SKILL.mod`, address and version forms, aliases | [references/manifests.md](references/manifests.md) | +| Cache layout, install modes, the config file, where things live | [references/storage.md](references/storage.md) | +| Exit codes, `--json`, what a script should branch on | [references/automation.md](references/automation.md) | +| Reporting a bug | [references/issue-reporting.md](references/issue-reporting.md) | -## Core workflow +Read only what the current request needs. Explaining a concept or drafting an +issue does not require an installation. -1. Establish whether the user is operating on project scope or global scope. - Do not add `--global` unless the user wants user-wide skills. -2. At the start of setup or diagnosis, check that both `git` and `skillmod` are - available. Do not repeat those checks during ordinary operations when the - current session has already established them, and do not reinstall a working - executable merely because installation was mentioned in an earlier step. -3. Project and global scopes are independent: each has its own manifest, and - either can be adopted alone — `skillmod init` for the project, - `skillmod --global init` for the user-wide skills — in either order. Keep - the scopes straight afterwards: a command affects the machine only when - it carries `--global`. -4. Inspect existing `SKILL.mod`, `SKILL.lock`, configuration, and installed - directories before proposing a mutation. Preserve unrelated user changes. -5. Prefer `--dry-run` before `init --force`, `sync --relink`, `remove`, or - `prune` when the result is not already obvious to the user. -6. Run the smallest command that satisfies the request and verify its result. - Use `skillmod list`, `skillmod why `, or `skillmod verify` - rather than inferring state from directory names alone. +## How to work -## Invariants +1. Settle the scope first. Project is the default; add `--global` only when + the user means the skills for the whole machine. The two scopes have + separate manifests and never merge. +2. Before diagnosing, check that `git` and `skillmod` both run. After that, + don't re-check them or reinstall a working executable just because + installation came up earlier in the conversation. +3. Look before you touch: read `SKILL.mod`, `SKILL.lock`, the config file, + and the installed directories, and leave anything unrelated alone. +4. Run `--dry-run` first when the result isn't obvious — `init --force`, + `sync --relink`, `sync --adopt`, `remove`, `prune`. +5. Then run the smallest command that does the job and check what it did. + Use `list`, `why `, or `verify` rather than guessing from + directory names. -- Treat `SKILL.mod` as the human-maintained declaration and `SKILL.lock` as - tool-maintained state. Do not hand-edit `SKILL.lock` unless recovery is the - explicit task and a backup has been made. -- Do not silently overwrite a locally modified installation. Exit code 3 means - independent work completed while one or more targets were safely preserved; - inspect the report instead of treating it as total failure or total success. -- Exit code 2 from `verify` means drift. Exit code 1 is an operational error. -- Branch names are mutable and cannot be locked. Use a semantic-version tag, a - full 40-character commit SHA, or let skillmod resolve an immutable version. -- Keep repository addresses credential-free and free of an implied transport. A - password or token in the user information, a query string, or a fragment is - rejected instead of persisted, and `source` records `host/owner/repo` rather - than an `https://` spelling. The version belongs in the `version` field, not - as an `@version` suffix in `source`. Direct the user to a credential helper, - an SSH agent, or the environment for secrets. -- Installation directories are generated state. Preserve `SKILL.mod` and - `SKILL.lock` in version control; do not commit installed skill directories - unless the project deliberately chooses to do so. -- Shared snapshots may be referenced by links from multiple projects. Never - delete the cache as a shortcut for removing one dependency. -- Downloading executables, changing PATH, installing packages, authenticating - GitHub CLI, and creating an issue are external mutations. Confirm the user's - intent immediately before any such action not already explicitly requested. +## Rules worth keeping -## Reporting results +- `SKILL.mod` is for people and goes in version control. `SKILL.lock` is + skillmod's own; don't hand-edit it unless recovery is the task and a + backup exists. +- Never overwrite a locally edited installation to make a report look + clean. Exit code 3 means part of the work was done and some targets were + kept on purpose — read the report, don't retry blindly. Exit code 2 means + drift. Exit code 1 means something went wrong. +- Branch names can't be locked. Use a tag, a full 40-character commit, or + let skillmod pick an immutable version. +- Keep addresses credential-free: no passwords or tokens in the URL, no + query strings, no fragments. `source` records `host/owner/repo`, and the + host defaults to `github.com`, so `owner/repo` is enough. +- Installed skill directories are build output. Don't commit them unless the + project decided to. +- One installed copy can be linked from several projects. Never "fix" a + removal by deleting the cache. +- Downloading a binary, changing `PATH`, installing packages, or filing an + issue reaches outside the machine — confirm right before doing it, unless + the user already asked for it. -State which scope was affected, which declaration or installation changed, -whether verification passed, and whether anything was preserved because of a -conflict. For JSON workflows, make decisions from stable fields and action -values rather than localized `note` text. +## Reporting back + +Say which scope was affected, what changed, whether `verify` passed, and +whether anything was kept because of a conflict. For `--json` runs, decide +from the stable fields and action values, never from the translated `note` +text. diff --git a/skills/skillmod/references/automation.md b/skills/skillmod/references/automation.md index 4111925..a68fac8 100644 --- a/skills/skillmod/references/automation.md +++ b/skills/skillmod/references/automation.md @@ -16,11 +16,18 @@ skillmod run instead of a person reading its output. of overwriting it. That is not total failure and not total success; read the report to see what was preserved and why. -An in-progress command prints its human summary as usual. Add `--json` to also -emit a structured report on stdout. - ## JSON reports +`--json` (`-j`) writes exactly one document to stdout and nothing else — the +human summary is not printed in that mode, and a failing run writes a document +too, with an `error` field naming the failure and the same exit code it would +have had anyway. That holds whether the command failed partway through or +before it could report anything at all, so the document is the one place a job +has to look. A `grep` for `"error"` therefore tells the two outcomes apart +without parsing anything. Only a usage error, such as an unknown flag, stays +plain text on stderr with exit code 1, because no command ran to produce a +report. + A report separates the command that ran from the outcome of each declaration and of each installation directory. @@ -42,7 +49,8 @@ executable's own `targetResults[0].action` says what happened to the file: `keep` means it was left alone. The report is written even when the upgrade fails, so `--json` always decodes one document. -Add `--json` to `list`, `why`, and `verify` for the report shape shown below: +Every command takes `--json`. The shape is the same everywhere; the example is +a `verify` run: ```json { @@ -69,6 +77,21 @@ Add `--json` to `list`, `why`, and `verify` for the report shape shown below: } ``` +A failing run keeps the same shape and adds `"error": "..."` with the message +that would otherwise have gone to stderr: + +```json +{ + "action": "get", + "entries": [], + "error": "no skill named \"nope\" in github.com/openai/skills; the repository provides: gh-fix-ci" +} +``` + +`entries` is always an array, and a document with `error` has no entries for +the work that never started. Read the exit code for the outcome class, the +`action` field for the command, and `error` when the run failed. + Inspection reports (`list`, `why`, and `verify`) also carry `requestedVersion` for remote entries: it is the exact `SKILL.mod` value, while `version` is the installed version from `SKILL.lock`. An empty `requestedVersion` means the diff --git a/skills/skillmod/references/manifests.md b/skills/skillmod/references/manifests.md index 0cb2669..2436f4c 100644 --- a/skills/skillmod/references/manifests.md +++ b/skills/skillmod/references/manifests.md @@ -17,6 +17,12 @@ breaks a rule is reported instead of being halfway applied. changes how the repository is fetched. A file that still spells out `https://` works unchanged and is rewritten to the shorter form the next time skillmod writes it. +- A bare `owner/repo` path is completed with `github.com`, the host nearly + every skill repository lives on, so `openai/skills` and + `github.com/openai/skills` are the same repository. A first segment that + already carries a dot is a host, and so is one that carries a port. A first + segment that is empty, `.`, or `..` reads as a filesystem path — the same for + a Windows drive letter — and none of those take the `github.com` default. - `version` is optional. An entry without one tracks the latest immutable resolution, which `SKILL.lock` pins. An entry with one is pinned to that tag or commit until `update` runs. @@ -63,9 +69,33 @@ Git credential helper, an SSH agent, or the environment. When `//` is a single segment, skillmod first tries an exact subdirectory of the repository root, then falls back to a unique skill name -anywhere below `skills/`. Ambiguous names require the full path. Omitting -`//` makes `get` discover the root `SKILL.md` and every `SKILL.md` -below `skills/`. +found anywhere in the repository. Ambiguous names require the full path. +Omitting `//` makes `get` discover every `SKILL.md` the +repository publishes, wherever that is: the repository root itself, a `skills/` +collection at any depth, an agent collection such as `.agents/skills/` or +`.claude/skills/`, and the root-level directories. Those four are always +scanned, so a repository that publishes a collection can still leave a skill in +another root directory and have it installed. + +A repository sometimes publishes the same skill under more than one of those +roots — `skills/` alongside `.openclaw/skills/` is the common case, because an +agent directory is a mirror maintained for one agent. Both would install into +one directory under one name, so `get` keeps a single copy, from the root the +repository's own layout comes from first: + +| Kept copy | Discarded copies | +| --- | --- | +| `skills/` | a root-level `/`, and any agent collection | +| root-level `/` | any agent collection | +| an agent collection | nothing, for the same skill — no agent directory outranks another | + +Two agents holding the same skill, with no ranking between them, are not +collapsed: `get` reports both paths and asks, the way it does for any other +ambiguous name. Within one collection, two directories sharing a skill name are +two skills, not a duplicate, and are reported the same way. + +An exact subdirectory always wins over discovery, so a repository only has to +look conventional to people who never type a path. ## The per-skill `agents` list diff --git a/skills/skillmod/references/storage.md b/skills/skillmod/references/storage.md index e95d3af..23bc474 100644 --- a/skills/skillmod/references/storage.md +++ b/skills/skillmod/references/storage.md @@ -41,7 +41,14 @@ touching the remote. An explicit `@commit` reuses an existing snapshot of that commit the same way. Requesting latest, or running `skillmod update`, keeps online refresh semantics. -Set `SKILLMOD_HOME` to relocate the store. +Each `ls-remote` result is cached with the time it was taken. `list` reuses a +snapshot younger than 15 minutes instead of contacting every declared +repository again, which is what keeps `list --global` fast on a machine with +many skills; `update` is the command that deliberately refreshes, and a `list` +run after a new tag shows it. `why` and `verify` never contact the remote at +all — they answer from `SKILL.mod`, `SKILL.lock`, and the installed content — +so they report the local state rather than a snapshot. Set `SKILLMOD_HOME` to +relocate the store. `--dry-run` leaves manifests and installations untouched, though remote provenance verification may still populate the shared cache. diff --git a/skills/skillmod/references/use-cases.md b/skills/skillmod/references/use-cases.md index e6875a9..2993eb2 100644 --- a/skills/skillmod/references/use-cases.md +++ b/skills/skillmod/references/use-cases.md @@ -113,20 +113,28 @@ Addresses have this form: Examples: ```sh +skillmod get openai/skills//gh-fix-ci skillmod get github.com/acme/agent-skills//skills/review@v1.2.0 skillmod get github.com/acme/agent-skills//review skillmod get github.com/acme/single-skill ``` -The repository is always named; `//` then selects the skill inside it. The -second form writes the skill name in place of its path, so a collection is -addressed with two short words instead of the directory layout. An exact -subdirectory always wins over a name, and a unique name resolves to the skill's -real path, so `source` records +The repository is always named; `//` then selects the skill inside it. The host +defaults to `github.com`, so `openai/skills//gh-fix-ci` is the shortest +spelling of `github.com/openai/skills//gh-fix-ci`. `//review` writes the skill +name in place of its path, so a collection is addressed with two short words +instead of the directory layout, and `@v1.2.0` pins an explicit version on that +same form. An exact subdirectory always wins over a name, and a unique name +resolves to the skill's real path, so `source` records `github.com/acme/agent-skills//skills/review` rather than the shorthand that was typed. When several skills in the repository answer the same name, skillmod reports the candidate paths and refuses to guess. A repository that is itself a -single skill needs no `//`, as in the third form. +single skill needs no `//`, as `github.com/acme/single-skill` shows. + +Discovery does not assume a layout. A collection usually lives under `skills/`, +but a repository whose skills sit directly in the root, or under an agent +directory such as `.agents/skills/` or `.claude/skills/`, is scanned the same +way, so unusual repositories install without anyone typing an internal path. Omitting a version asks skillmod to resolve the latest immutable tag, with a pseudo-version fallback for an untagged repository. A branch name is rejected, @@ -182,6 +190,28 @@ skillmod sync --relink --dry-run skillmod sync --relink ``` +Use `sync --adopt` when skills appeared on disk outside skillmod — installed by +`npx`, copied in, or written by hand. It declares each one as a local entry and +records its current content as the lock baseline, which is the same thing `init` +does for a machine's existing skills. No file is rewritten, so a later edit +shows up as `local-drift` instead of being reset: + +```sh +skillmod sync --dry-run --adopt +skillmod sync --adopt --yes +``` + +Each adopted skill is confirmed in a terminal, and `--yes` adopts all of them. +A plain `sync` does not change the declaration; it names the undeclared skills +and points at the flag. A directory a stale lock record still occupies is left +for `prune`, never adopted. + +`sync --adopt` cannot be combined with `--check`: `--check` is `verify`, which +only reports drift and never writes. A non-interactive run without `--yes` is +refused and told to pass `--yes`, rather than adopting skills nobody approved; +`sync --adopt --dry-run` plans the whole set without asking, because printing a +plan must not block on a prompt. + ## Inspect state and provenance Use `list` for the complete declaration overview: @@ -275,8 +305,22 @@ skillmod remove --all skillmod remove ``` -`--all` takes every declared entry without asking. A bare `remove` picks from -the declarations interactively, so it needs a terminal; `--yes` is not a +A positional argument that contains a `/` is a repository selector instead, +which is the same distinction a skill name can never trip: names are single +portable segments. Name the repository and the skills declared from it are +selected, exactly the way `get` lists what a repository publishes — one entry +needs no choice, several are offered in a terminal, and a non-interactive run +lists them and exits: + +```sh +skillmod remove github.com/acme/agent-skills --dry-run +skillmod remove openai/skills +``` + +`--all` takes every declared entry without asking, and with a repository +selector it takes every entry that repository declares, which is how a script +says "everything this repository brought in". A bare `remove` picks from the +declarations interactively, so it needs a terminal; `--yes` is not a substitute for either, because it answers the deletion confirmation rather than choosing what to delete. @@ -292,7 +336,9 @@ skillmod remove --all --agent claude Without skill names, the picker offers only skills shared to the named agents and starts with nothing checked. With `--all`, all matching skills are unshared; skills shared only to other agents are unaffected. Agent values may repeat or -use comma-separated names. Names and `--all` cannot be combined. +use comma-separated names. A skill name and `--all` cannot be combined, because +each already states the set; a repository selector can, and `--all` then takes +everything it declares. Clean managed installations are removed transactionally. Locally modified or unverifiable directories are preserved and reported as partial completion. From af9e69fc2227de1bbc5434897f56f01eec227b37 Mon Sep 17 00:00:00 2001 From: huija <1150555483@qq.com> Date: Wed, 23 Sep 2026 23:48:38 +0800 Subject: [PATCH 9/9] fix: let init keep the empty-manifest report it just made A scan that found no skill reported that it had already generated an empty manifest and then returned from the shared non-interactive confirmation gate, which sits before the write phase. A script or CI run therefore claimed a write that never happened, and the prompt it stopped at is one a non-interactive environment cannot answer. An empty scan has nothing to accept, so the gate now applies only when the run has an entry to confirm; it still closes for a scan that found something, since silently accepting a candidate would declare a skill the user never approved. The empty-scan note picks its tense from the run it belongs to: the write path reports the manifest as generated, and a dry run reports the one it would generate, matching the "no files were written" note that follows it in the same report. TestInit_EmptyRunKeepsTheManifestItReports covers the empty write, the dry-run tense, and the still-closed gate, a path no test had reached. --- internal/engine/engine_test.go | 62 +++++++++++++++++++++++++ internal/engine/init.go | 14 +++++- locales/en_US.po | 4 ++ locales/zh_CN.po | 3 ++ skills/skillmod/references/use-cases.md | 3 ++ 5 files changed, 84 insertions(+), 2 deletions(-) diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index c3d36eb..5265d1b 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -22,6 +22,7 @@ import ( "github.com/huija/skillmod/internal/config" "github.com/huija/skillmod/internal/dirhash" "github.com/huija/skillmod/internal/engine" + "github.com/huija/skillmod/internal/i18n" "github.com/huija/skillmod/internal/install" "github.com/huija/skillmod/internal/modfile" "github.com/huija/skillmod/internal/resolve" @@ -1544,6 +1545,67 @@ func readFileString(t *testing.T, path string) string { return string(data) } +// Regression: the empty-candidate path used to report that it had generated an +// empty manifest and then fall into the shared non-interactive confirmation +// gate, which returned before the write phase. The report described a write +// that never happened, and a non-interactive environment could not get past the +// prompt it could not answer. An empty run has nothing to confirm, so it must +// reach the write phase and keep the promise its own note made. +func TestInit_EmptyRunKeepsTheManifestItReports(t *testing.T) { + t.Setenv(i18n.Env, "en") + // Confirm is nil and Yes is false: the shape a script or CI run sees. + unattended := engine.IO{Out: io.Discard} + + t.Run("writes the reported empty manifest", func(t *testing.T) { + root := t.TempDir() + rep, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended) + if err != nil { + t.Fatalf("an empty init should not require confirmation: %v", err) + } + if len(rep.Entries) != 0 { + t.Errorf("entries = %d, want 0", len(rep.Entries)) + } + if note := strings.Join(rep.Notes, "\n"); !strings.Contains(note, "generated an empty manifest") { + t.Errorf("notes = %q, want the manifest already reported as generated", note) + } + if _, err := os.Stat(filepath.Join(root, modfile.ModFileName)); err != nil { + t.Errorf("the reported manifest was not written: %v", err) + } + }) + + t.Run("dry run promises instead of claiming", func(t *testing.T) { + root := t.TempDir() + rep, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended, engine.MutationOptions{DryRun: true}) + if err != nil { + t.Fatalf("init --dry-run: %v", err) + } + if note := strings.Join(rep.Notes, "\n"); !strings.Contains(note, "will generate an empty manifest") { + t.Errorf("notes = %q, want the future tense for a run that writes nothing", note) + } + if _, err := os.Stat(filepath.Join(root, modfile.ModFileName)); !os.IsNotExist(err) { + t.Errorf("dry-run wrote SKILL.mod: %v", err) + } + }) + + // Widening the gate must stay scoped to an empty run: a run with a candidate + // still has something to confirm, and silently accepting it would install a + // skill the user never approved. + t.Run("a run with candidates still requires confirmation", func(t *testing.T) { + root := t.TempDir() + dir := installedDir(root, "local-skill") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + body := "---\nname: local-skill\ndescription: local\n---\n# local\n" + if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(body), 0o644); err != nil { + t.Fatal(err) + } + if _, err := newEngine(t, root, t.TempDir()).Init(ctx, false, unattended); err == nil { + t.Error("a run with candidates should still require confirmation") + } + }) +} + func TestInit_ScansTheManagedDirectory(t *testing.T) { root := t.TempDir() dir := filepath.Join(install.SkillsDir(root), "local-skill") diff --git a/internal/engine/init.go b/internal/engine/init.go index 6807607..13932a5 100644 --- a/internal/engine/init.go +++ b/internal/engine/init.go @@ -327,7 +327,13 @@ func (e *Engine) Init(ctx context.Context, force bool, io IO, options ...Mutatio } if len(rep.Entries) == 0 { - rep.Notes = append(rep.Notes, i18n.Text("engine.init.skills_found_generated_empty")) + // State the tense the run can keep: the manifest is written below, and + // a dry run never writes one. + note := i18n.Text("engine.init.skills_found_generated_empty") + if run.DryRun { + note = i18n.Text("engine.init.skills_found_will_generate_empty") + } + rep.Notes = append(rep.Notes, note) } if unresolved > 0 { rep.Notes = append(rep.Notes, i18n.Format("engine.init.unresolved_sources", unresolved)) @@ -358,7 +364,11 @@ func (e *Engine) Init(ctx context.Context, force bool, io IO, options ...Mutatio } // Confirm each entry individually so users can reject uncertain provenance. - if !io.Yes && io.Confirm == nil { + // An empty run has nothing to reject, so the gate stays open: a run that + // found no skill must still write the empty manifest it reported above, + // rather than stop at a prompt a non-interactive environment cannot + // answer. + if len(m.Skills) > 0 && !io.Yes && io.Confirm == nil { rep.Notes = append(rep.Notes, i18n.Text("engine.init.confirmed_non_interactive")) return rep, fmt.Errorf("%s", i18n.Text("engine.init.init_requires_confirmation")) } diff --git a/locales/en_US.po b/locales/en_US.po index 42897dc..7995b38 100644 --- a/locales/en_US.po +++ b/locales/en_US.po @@ -532,6 +532,10 @@ msgid "engine.init.skills_found_generated_empty" msgstr "no skills found; generated an empty manifest—use skillmod get to " "add one" +msgid "engine.init.skills_found_will_generate_empty" +msgstr "no skills found; will generate an empty manifest—use skillmod get" +" to add one" + #, go-format msgid "engine.init.source_unverified_local" msgstr "source could not be verified; kept as local: %v" diff --git a/locales/zh_CN.po b/locales/zh_CN.po index 2409c77..be7e837 100644 --- a/locales/zh_CN.po +++ b/locales/zh_CN.po @@ -520,6 +520,9 @@ msgstr "正在恢复已安装技能来源:%s" msgid "engine.init.skills_found_generated_empty" msgstr "未发现 skill,已生成空清单,可用 skillmod get 添加" +msgid "engine.init.skills_found_will_generate_empty" +msgstr "未发现 skill,将生成空清单,可用 skillmod get 添加" + #, go-format msgid "engine.init.source_unverified_local" msgstr "无法验证来源,保留为本地技能:%v" diff --git a/skills/skillmod/references/use-cases.md b/skills/skillmod/references/use-cases.md index 2993eb2..90f96e2 100644 --- a/skills/skillmod/references/use-cases.md +++ b/skills/skillmod/references/use-cases.md @@ -94,6 +94,9 @@ one unresolved entry does not discard the rest of the import. Import writes both `SKILL.mod` and `SKILL.lock`. Replacing an existing declaration requires `--force`, which first backs it up as `SKILL.mod.bak`. +Every detected entry is confirmed before the write, so a non-interactive +environment passes `--yes`; a scan that finds nothing has no entry to confirm +and writes the empty manifest rather than stopping at an unanswerable prompt. Use global scope only when requested: