Skip to content
Merged
10 changes: 6 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
257 changes: 119 additions & 138 deletions README.md

Large diffs are not rendered by default.

166 changes: 100 additions & 66 deletions README_CN.md

Large diffs are not rendered by default.

10 changes: 5 additions & 5 deletions docs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
33 changes: 28 additions & 5 deletions internal/address/address.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) {
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
14 changes: 14 additions & 0 deletions internal/address/address_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"}, ""},
Expand Down Expand Up @@ -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"},
Expand Down
2 changes: 1 addition & 1 deletion internal/cli/get.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down
51 changes: 51 additions & 0 deletions internal/cli/global_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)

Expand Down Expand Up @@ -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)
}
}
2 changes: 1 addition & 1 deletion internal/cli/init.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down
2 changes: 1 addition & 1 deletion internal/cli/list.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
},
}
}
2 changes: 1 addition & 1 deletion internal/cli/prune.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
},
}
}
2 changes: 1 addition & 1 deletion internal/cli/remove.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"))
Expand Down
Loading
Loading