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/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/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/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/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/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..809db53 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, @@ -212,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/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..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)) + 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/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/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.go b/internal/engine/engine.go index 1521a86..f9cb9fc 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 @@ -611,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 d557cba..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" @@ -15,10 +19,14 @@ 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/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) { @@ -252,6 +260,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 { @@ -673,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 1e0a973..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" @@ -442,6 +443,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 +1020,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) } @@ -1333,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") @@ -2021,6 +2294,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() @@ -2301,7 +2751,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) @@ -2309,8 +2762,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]) } } @@ -2524,3 +2977,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/get.go b/internal/engine/get.go index 8dd8e7c..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" @@ -73,6 +74,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 +236,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 { @@ -397,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. @@ -508,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 } @@ -521,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) { @@ -555,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/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/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/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/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/internal/engine/report.go b/internal/engine/report.go index 85cd7e0..f067598 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 @@ -28,6 +32,7 @@ const ( CommandVerify Command = "verify" CommandWhy Command = "why" + ActionAdopt = "adopt" ActionConflict = "conflict" ActionDrift = "drift" ActionInstall = "install" @@ -77,6 +82,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 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/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/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) { diff --git a/locales/en_US.po b/locales/en_US.po index fe689b5..7995b38 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)" @@ -436,9 +439,14 @@ 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/" +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" @@ -524,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" @@ -723,6 +735,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" @@ -730,6 +747,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" @@ -740,6 +761,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" @@ -882,8 +907,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" @@ -935,6 +964,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)" @@ -956,6 +1020,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" @@ -967,6 +1035,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: " @@ -974,6 +1047,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" @@ -985,6 +1061,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 226f6fc..be7e837 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 的别名)" @@ -429,9 +432,14 @@ 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" +msgstr "未找到 SKILL.md;已检查仓库根目录、skills/、.agents/s" +"kills 等 agent 技能目录,以及根目录下的技能目录" #, go-format msgid "engine.get.skill_name_matches_multiple" @@ -512,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" @@ -708,6 +719,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" @@ -715,6 +731,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 中没有声明条目" @@ -725,6 +745,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 "清理部分分享链接失败" @@ -865,7 +889,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" @@ -917,6 +947,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 记" "录已移除)" @@ -938,6 +1003,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 个条目将被安装或更新" @@ -949,6 +1018,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 "缺失: " @@ -956,6 +1029,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 清理" @@ -966,6 +1042,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/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 100de27..a68fac8 100644 --- a/skills/skillmod/references/automation.md +++ b/skills/skillmod/references/automation.md @@ -16,18 +16,25 @@ 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. | 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 @@ -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..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: @@ -113,20 +116,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 +193,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 +308,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 +339,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.