click-agentcli 0.4.1__tar.gz → 0.5.0__tar.gz

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-agentcli
-Version: 0.4.1
+Version: 0.5.0
 Summary: Shared CLI conventions for agent-facing tools: exit codes, JSON output, skill installation, and the in-binary guide.
 Project-URL: Homepage, https://github.com/owahltinez/click-agentcli
 Author: owahltinez
@@ -118,6 +118,29 @@ Add `@json_option` to each command that supports structured output and call
 `emit` once with both the data and its human renderer. `JsonAwareGroup` then
 keeps parse failures structured when `--json` was requested.
 
+## Upgrading
+
+Upgrading the package is the whole workflow:
+
+```sh
+uv tool upgrade --all
+```
+
+`JsonAwareGroup` rewrites any installed copy of the skill that differs from
+the packaged one, on the way into a command. It only ever rewrites a
+directory that already holds this skill: putting one somewhere new is
+`skill install`. Failures are silent, and `skill` itself is skipped so
+`skill status` still reports drift.
+
+Set `AGENTCLI_NO_SKILL_REFRESH=1` to switch it off. A top-level group that
+is not `JsonAwareGroup` asks for the refresh itself:
+
+```python
+from agentcli import refresh_skill
+
+refresh_skill(name="acme", package="acme")
+```
+
 ## Develop this package
 
 ```sh
@@ -160,13 +183,14 @@ The stable public surface is:
 
 - `UsageError`, `RemoteError`, `AssertionFailure`, and `StrictFailure`.
 - `dumps`, `emit`, `emit_error`, `json_option`, and `limit_option`.
-- `JsonAwareGroup` for every consuming tool's top-level group.
+- `JsonAwareGroup` for every consuming tool's top-level group. It also keeps
+  the installed skill in step with the packaged one.
+- `refresh_skill(name=..., package=...)` to do that from another group.
 - `skill_group(name=..., package=...)` for `skill install`, `uninstall`, and
   `status`. Installation refuses an unrelated destination, recognises owned
   broken symlinks an older version left, always copies, and supports `--to`
   and `--dry-run`. `status` compares each installed copy against the packaged
-  one and reports `current` or `stale`, because upgrading a package never
-  refreshes a skill already on disk. It never links: a link points into the environment, whose
+  one and reports `current` or `stale`. It never links: a link points into the environment, whose
   path carries the interpreter version, so a rebuild elsewhere leaves the
   skill silently absent rather than merely stale. With no options it installs everywhere the skill is wanted
   and refreshes its own earlier copies, so plain `install` is the whole

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/README.md

@@ -94,6 +94,29 @@ Add `@json_option` to each command that supports structured output and call
 `emit` once with both the data and its human renderer. `JsonAwareGroup` then
 keeps parse failures structured when `--json` was requested.
 
+## Upgrading
+
+Upgrading the package is the whole workflow:
+
+```sh
+uv tool upgrade --all
+```
+
+`JsonAwareGroup` rewrites any installed copy of the skill that differs from
+the packaged one, on the way into a command. It only ever rewrites a
+directory that already holds this skill: putting one somewhere new is
+`skill install`. Failures are silent, and `skill` itself is skipped so
+`skill status` still reports drift.
+
+Set `AGENTCLI_NO_SKILL_REFRESH=1` to switch it off. A top-level group that
+is not `JsonAwareGroup` asks for the refresh itself:
+
+```python
+from agentcli import refresh_skill
+
+refresh_skill(name="acme", package="acme")
+```
+
 ## Develop this package
 
 ```sh
@@ -136,13 +159,14 @@ The stable public surface is:
 
 - `UsageError`, `RemoteError`, `AssertionFailure`, and `StrictFailure`.
 - `dumps`, `emit`, `emit_error`, `json_option`, and `limit_option`.
-- `JsonAwareGroup` for every consuming tool's top-level group.
+- `JsonAwareGroup` for every consuming tool's top-level group. It also keeps
+  the installed skill in step with the packaged one.
+- `refresh_skill(name=..., package=...)` to do that from another group.
 - `skill_group(name=..., package=...)` for `skill install`, `uninstall`, and
   `status`. Installation refuses an unrelated destination, recognises owned
   broken symlinks an older version left, always copies, and supports `--to`
   and `--dry-run`. `status` compares each installed copy against the packaged
-  one and reports `current` or `stale`, because upgrading a package never
-  refreshes a skill already on disk. It never links: a link points into the environment, whose
+  one and reports `current` or `stale`. It never links: a link points into the environment, whose
   path carries the interpreter version, so a rebuild elsewhere leaves the
   skill silently absent rather than merely stale. With no options it installs everywhere the skill is wanted
   and refreshes its own earlier copies, so plain `install` is the whole

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "hatchling.build"
 # Dependents must name the distribution, not the import, in both their
 # dependencies and their [tool.uv.sources] key.
 name = "click-agentcli"
-version = "0.4.1"
+version = "0.5.0"
 description = "Shared CLI conventions for agent-facing tools: exit codes, JSON output, skill installation, and the in-binary guide."
 readme = "README.md"
 requires-python = ">=3.12"

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/src/agentcli/__init__.py

@@ -17,13 +17,14 @@ from agentcli.exits import (
 from agentcli.group import JsonAwareGroup
 from agentcli.guide import guide_command
 from agentcli.output import dumps, emit, emit_error, json_option, limit_option
-from agentcli.skill import skill_group
+from agentcli.skill import SkillGroup, refresh_skill, skill_group
 
 __all__ = [
     "KINDS",
     "AssertionFailure",
     "JsonAwareGroup",
     "RemoteError",
+    "SkillGroup",
     "StrictFailure",
     "UsageError",
     "candidate",
@@ -36,6 +37,7 @@ __all__ = [
     "macro_options",
     "matches",
     "rank",
+    "refresh_skill",
     "skill_group",
     "unverifiable",
 ]

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/src/agentcli/group.py

@@ -10,6 +10,7 @@ problem, and a tool that solves it locally is a tool the next one forgets to
 copy.
 """
 
+import os
 import sys
 from collections.abc import Sequence
 from typing import Any, Literal, NoReturn, overload
@@ -17,6 +18,10 @@ from typing import Any, Literal, NoReturn, overload
 import click
 
 from agentcli.output import emit_error
+from agentcli.skill import SkillGroup
+
+# Set to any non-empty value to keep a run from touching the skills on disk.
+NO_REFRESH_ENV = "AGENTCLI_NO_SKILL_REFRESH"
 
 
 class JsonAwareGroup(click.Group):
@@ -59,6 +64,13 @@ class JsonAwareGroup(click.Group):
         arguments = list(sys.argv[1:] if args is None else args)
         self._json_requested = "--json" in arguments
 
+        # Only when this process *is* the tool's command line, which is what
+        # reading `sys.argv` means. A caller passing its own arguments -- an
+        # embedding, or a consumer's `CliRunner` test -- gets no writes under
+        # `~` it never asked for.
+        if args is None:
+            self._refresh_skill(arguments)
+
         return super().main(
             arguments,
             prog_name,
@@ -67,6 +79,28 @@ class JsonAwareGroup(click.Group):
             **extra,
         )
 
+    def _refresh_skill(self, arguments: Sequence[str]) -> None:
+        """Bring already-installed copies of this tool's skill up to date.
+
+        Upgrading a package never touched a skill already on disk, so the copy
+        an agent read could sit releases behind the binary it documents, and
+        nothing said so. Doing it here makes `uv tool upgrade` the whole
+        workflow: no second command per tool to remember.
+
+        Not done for `skill` itself. That group is where drift is reported and
+        acted on, and a `skill status` that silently repaired what it was
+        about to describe would have nothing left to report.
+        """
+        if os.environ.get(NO_REFRESH_ENV):
+            return
+
+        if "skill" in arguments:
+            return
+
+        skill = self.commands.get("skill")
+        if isinstance(skill, SkillGroup):
+            skill.refresh()
+
     def _drift_hint(self, ctx: click.Context, exc: Exception) -> str:
         """Why a name this caller expected might not exist.
 

click_agentcli-0.5.0/src/agentcli/group_test.py

@@ -0,0 +1,231 @@
+"""A bad flag must still honour `--json`, before click has parsed it."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from agentcli import JsonAwareGroup, UsageError, emit, skill_group
+from agentcli.group import NO_REFRESH_ENV
+from agentcli.skill import SHARED_DIR
+
+MANIFEST = "---\nname: faketool\ndescription: router\n---\nbody\n"
+
+
+@pytest.fixture(autouse=True)
+def throwaway_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Every run refreshes the skills under `~`, so no test may see a real one."""
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setattr(Path, "home", lambda: home)
+    return home
+
+
+@click.group(cls=JsonAwareGroup)
+def cli() -> None:
+    """Fixture tool."""
+
+
+@click.command("go")
+@click.option("--limit", type=click.IntRange(min=0), default=10)
+@click.option("--json", "json_output", is_flag=True)
+@click.option("--boom", is_flag=True)
+def go(limit: int, json_output: bool, boom: bool) -> None:
+    if boom:
+        raise UsageError("refused on purpose")
+    emit({"limit": limit}, json_output=json_output, human=lambda d: ["ok"])
+
+
+cli.add_command(go)
+
+
+def _run(*args: str):
+    return CliRunner().invoke(cli, list(args))
+
+
+def test_success_is_enveloped() -> None:
+    result = _run("go", "--json")
+
+    assert result.exit_code == 0
+    assert json.loads(result.output) == {"ok": True, "data": {"limit": 10}}
+
+
+def test_raised_failure_is_enveloped() -> None:
+    result = _run("go", "--json", "--boom")
+
+    assert result.exit_code == 1
+    assert json.loads(result.output) == {
+        "ok": False,
+        "error": {"message": "refused on purpose"},
+    }
+
+
+def test_parse_failure_is_enveloped_though_json_never_parsed() -> None:
+    """The hard case: click refuses before the subcommand sees --json."""
+    result = _run("go", "--json", "--limit", "-1")
+
+    assert result.exit_code == 1
+    payload = json.loads(result.output)
+    assert payload["ok"] is False
+    assert "-1" in payload["error"]["message"]
+
+
+def test_unknown_option_is_enveloped() -> None:
+    result = _run("go", "--json", "--nonexistent")
+
+    assert result.exit_code == 1
+    assert json.loads(result.output)["ok"] is False
+
+
+def test_human_path_keeps_clicks_own_usage_block() -> None:
+    """Without --json a person gets click's output, not a uniform shape."""
+    result = _run("go", "--limit", "-1")
+
+    assert result.exit_code == 1
+    assert "Usage:" in result.output
+
+
+def test_main_accepts_clicks_own_positional_arguments(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A caller holding a `click.Group` may pass click's own positionals."""
+    group: click.Group = cli
+
+    group.main(["go", "--json"], "tool", None, False)
+
+    assert json.loads(capsys.readouterr().out) == {
+        "ok": True,
+        "data": {"limit": 10},
+    }
+
+
+@click.group(cls=JsonAwareGroup)
+def skilled() -> None:
+    """A tool that ships a skill."""
+
+
+skilled.add_command(go)
+skilled.add_command(skill_group(name="faketool", package="agentcli"))
+
+
+@pytest.mark.parametrize(
+    ("args", "hinted"),
+    [
+        (["go", "--nope"], True),
+        (["nosuchcommand"], True),
+        (["go", "--limit"], False),
+        (["go", "--limit", "-1"], False),
+    ],
+)
+def test_an_unknown_name_suggests_a_stale_skill(args, hinted: bool) -> None:
+    """A caller reading a skill older than the binary asks for a name the
+    binary dropped. No other failure looks like that, so nothing else hints."""
+    result = CliRunner().invoke(skilled, args)
+
+    assert result.exit_code != 0
+    assert ("skill install" in result.output) is hinted
+
+
+def test_a_tool_without_a_skill_suggests_nothing() -> None:
+    result = CliRunner().invoke(cli, ["nosuchcommand"])
+
+    assert result.exit_code != 0
+    assert "skill install" not in result.output
+
+
+def _install_stale(home: Path) -> Path:
+    """A skill on disk from before the manifest this package now ships."""
+    target = home / SHARED_DIR / "faketool"
+    target.mkdir(parents=True)
+    (target / "SKILL.md").write_text(MANIFEST)
+    return target / "SKILL.md"
+
+
+@pytest.fixture
+def shipped(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """The manifest `skilled` would install, as a newer release ships it."""
+    source = tmp_path / "SKILL.md"
+    source.write_text(MANIFEST + "a section added since\n")
+    monkeypatch.setattr(
+        "agentcli.skill.packaged_skill", lambda **kwargs: source
+    )
+    return source
+
+
+def _as_the_command_line(
+    group: click.Group, argv: list[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Run `group` the way its console script does: from `sys.argv`.
+
+    The refresh happens only when the process *is* the tool's command line,
+    so a `CliRunner` -- which always hands click an argument list -- cannot
+    reach it, and neither can a consumer's test suite.
+    """
+    monkeypatch.setattr(sys, "argv", ["tool", *argv])
+    group.main(standalone_mode=False)
+
+
+def test_running_any_command_refreshes_a_stale_skill(
+    throwaway_home: Path, shipped: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Upgrading the package is the whole workflow: no second command."""
+    installed = _install_stale(throwaway_home)
+
+    _as_the_command_line(skilled, ["go"], monkeypatch)
+
+    assert installed.read_text() == shipped.read_text()
+
+
+def test_a_passed_argument_list_touches_no_skills(
+    throwaway_home: Path, shipped: Path
+) -> None:
+    """A consumer's own `CliRunner` tests must not rewrite the skills under
+    the developer's real home."""
+    installed = _install_stale(throwaway_home)
+
+    result = CliRunner().invoke(skilled, ["go"])
+
+    assert result.exit_code == 0
+    assert installed.read_text() == MANIFEST
+
+
+def test_the_skill_command_reports_drift_rather_than_hiding_it(
+    throwaway_home: Path,
+    shipped: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """`skill status` describing a copy it had just silently repaired would
+    have nothing left to report."""
+    installed = _install_stale(throwaway_home)
+
+    _as_the_command_line(skilled, ["skill", "status"], monkeypatch)
+
+    assert "stale" in capsys.readouterr().out
+    assert installed.read_text() == MANIFEST
+
+
+def test_refresh_can_be_switched_off(
+    throwaway_home: Path, shipped: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(NO_REFRESH_ENV, "1")
+    installed = _install_stale(throwaway_home)
+
+    _as_the_command_line(skilled, ["go"], monkeypatch)
+
+    assert installed.read_text() == MANIFEST
+
+
+def test_a_tool_without_a_skill_group_still_runs(
+    throwaway_home: Path,
+    shipped: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """The refresh is opportunistic; nothing to refresh is not an error."""
+    _as_the_command_line(cli, ["go", "--json"], monkeypatch)
+
+    assert json.loads(capsys.readouterr().out)["ok"] is True

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/src/agentcli/skill.py

@@ -8,10 +8,15 @@ directory it can see, with the command to cover those too.
 
 Parameterised by skill name and package because the two hand-written copies
 this replaces had already drifted apart in exactly the guards that matter.
+
+`refresh_skill` closes the gap that made `install` a chore: upgrading a
+package never touched a skill already on disk, so the copy an agent reads
+could sit releases behind the binary it documents.
 """
 
 import shutil
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
+from functools import partial
 from importlib import resources
 from pathlib import Path
 from typing import Any
@@ -73,6 +78,19 @@ def packaged_skill(*, name: str, package: str) -> Path:
     raise click.ClickException(f"SKILL.md not found; looked in {looked}")
 
 
+def _known_locations(home: Path, name: str) -> list[tuple[str, Path]]:
+    """Every location this tool manages, shared first, present or not.
+
+    One list, because a location missing from one of `status`, `uninstall`,
+    or `refresh_skill` is a copy that is reported but never cleaned, or
+    cleaned but never refreshed.
+    """
+    return [("Shared (.agents)", home / SHARED_DIR / name)] + [
+        (label, home / skills / name)
+        for label, (_, skills) in TOOL_DIRS.items()
+    ]
+
+
 def detected_tools(home: Path) -> dict[str, Path]:
     """Return skills directories for the agent tools present on this machine."""
     return {
@@ -157,9 +175,8 @@ def _place(source: Path, target: Path, *, name: str) -> str:
     Always a copy. A link points into the environment this CLI was installed
     into, and that path is not stable: it carries the interpreter version, so
     an environment rebuilt on another Python leaves a dangling link and the
-    skill silently disappears. Copying costs a stale skill after an upgrade,
-    which is the louder failure and the cheaper one -- the skill is a router,
-    and the manual it routes to (`<tool> guide`) ships in the binary.
+    skill silently disappears. What a copy used to cost -- a skill left stale
+    by an upgrade -- `refresh_skill` now pays back on the next run.
     """
     refusal = _refusal(target, name=name)
     if refusal is not None:
@@ -200,11 +217,7 @@ def _status_rows(
     home: Path, name: str, source: Path | None = None
 ) -> list[dict[str, Any]]:
     """One row per known location, shared first, whether present or not."""
-    locations = [("Shared (.agents)", home / SHARED_DIR / name)]
-    locations += [
-        (label, home / skills / name)
-        for label, (_, skills) in TOOL_DIRS.items()
-    ]
+    locations = _known_locations(home, name)
 
     rows = []
     for label, path in locations:
@@ -233,7 +246,60 @@ def _status_lines(payload: dict[str, Any]) -> Iterable[str]:
         )
 
 
-def skill_group(*, name: str, package: str) -> click.Group:
+def refresh_skill(
+    *, name: str, package: str, home: Path | None = None
+) -> list[Path]:
+    """Recopy every installed copy of this skill the package has moved past.
+
+    Installing a package never refreshed a skill already on disk, so an agent
+    could read a manifest several releases behind the binary it documents,
+    with nothing to say so. Running this on the way into a command makes the
+    upgrade the whole workflow.
+
+    Only ever touches a directory that already holds *this* skill. Putting a
+    skill somewhere new stays an explicit `skill install`, so this can never
+    resurrect a location the user deliberately cleared.
+
+    Best effort throughout: a package whose manifest cannot be found, or a
+    skills directory that cannot be written, is not a reason to fail the
+    command the caller actually asked for.
+    """
+    try:
+        source = packaged_skill(name=name, package=package)
+    except click.ClickException:
+        return []
+
+    refreshed = []
+    for _, target in _known_locations(home or Path.home(), name):
+        # `stale` is reached only for a directory holding our own skill whose
+        # bytes differ, which is exactly the set worth rewriting.
+        if _state(target, source, name=name) != "stale":
+            continue
+
+        try:
+            shutil.copy2(source, target / "SKILL.md")
+        except OSError:
+            continue
+
+        refreshed.append(target)
+
+    return refreshed
+
+
+class SkillGroup(click.Group):
+    """The `skill` group, carrying the refresh its root group runs.
+
+    The refresh happens on the way into every *other* command, and the root
+    group that runs it there knows neither the skill name nor the package.
+    Carrying the bound call here is how it reaches that code without every
+    consumer wiring it up by hand -- which is the mistake this module exists
+    to stop repeating.
+    """
+
+    refresh: Callable[[], list[Path]]
+
+
+def skill_group(*, name: str, package: str) -> SkillGroup:
     """Build the `skill` command group for one tool.
 
     `name` is both the skill name and the binary that carries it, so it also
@@ -245,7 +311,7 @@ def skill_group(*, name: str, package: str) -> click.Group:
     )
     dry_run_help = "Print what would happen without touching the filesystem."
 
-    @click.group("skill")
+    @click.group("skill", cls=SkillGroup)
     def skill() -> None:
         """Install the packaged Agent Skill so agents can discover this tool."""
 
@@ -339,9 +405,7 @@ def skill_group(*, name: str, package: str) -> click.Group:
         # present: an uninstalled tool can leave a skill behind, and that is
         # exactly what needs removing. Missing ones are skipped quietly.
         if destination is None:
-            targets += [
-                home / skills / name for _, skills in TOOL_DIRS.values()
-            ]
+            targets += [path for _, path in _known_locations(home, name)]
 
         removed = 0
         for target in dict.fromkeys(targets):
@@ -384,4 +448,6 @@ def skill_group(*, name: str, package: str) -> click.Group:
         }
         emit(payload, json_output=json_output, human=_status_lines)
 
+    skill.refresh = partial(refresh_skill, name=name, package=package)
+
     return skill

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/src/agentcli/skill_test.py

@@ -18,8 +18,10 @@ from click.testing import CliRunner
 
 from agentcli.skill import (
     SHARED_DIR,
+    SkillGroup,
     detected_tools,
     packaged_skill,
+    refresh_skill,
     skill_group,
 )
 
@@ -395,3 +397,89 @@ def test_status_still_answers_for_an_absent_location(tool: Tool) -> None:
     rows = json.loads(result.output)["data"]["locations"]
     assert all(row["state"] == "absent" for row in rows)
     assert all(row["installed"] is False for row in rows)
+
+
+def test_refresh_updates_a_stale_copy(tool: Tool) -> None:
+    """The whole point: an upgraded package leaves no stale skill behind."""
+    tool.run("install")
+    tool.source.write_text(MANIFEST + "a section added since\n")
+
+    refreshed = refresh_skill(name=NAME, package=NAME, home=tool.home)
+
+    assert refreshed == [tool.shared()]
+    assert (tool.shared() / "SKILL.md").read_text() == tool.source.read_text()
+
+
+def test_refresh_leaves_a_current_copy_alone(tool: Tool) -> None:
+    tool.run("install")
+
+    assert refresh_skill(name=NAME, package=NAME, home=tool.home) == []
+
+
+def test_refresh_never_creates_a_location(tool: Tool) -> None:
+    """Placing a skill somewhere new stays an explicit `skill install`, so an
+    uninstall cannot be undone by the next command that happens to run."""
+    (tool.home / ".claude").mkdir()
+
+    assert refresh_skill(name=NAME, package=NAME, home=tool.home) == []
+    assert not tool.shared().exists()
+    assert not (tool.home / ".claude" / "skills").exists()
+
+
+def test_refresh_leaves_a_foreign_directory_alone(tool: Tool) -> None:
+    """The install guard has to hold for the unattended path too."""
+    target = tool.home / SHARED_DIR / NAME
+    manifest = _install_foreign(target)
+
+    assert refresh_skill(name=NAME, package=NAME, home=tool.home) == []
+    assert manifest.read_text() == FOREIGN
+
+
+def test_refresh_covers_every_known_location(tool: Tool) -> None:
+    """Including a tool since uninstalled: its copy is still one agents read."""
+    (tool.home / ".claude").mkdir()
+    tool.run("install")
+    stale = tool.home / ".cursor" / "skills" / NAME
+    stale.mkdir(parents=True)
+    (stale / "SKILL.md").write_text(MANIFEST)
+    tool.source.write_text(MANIFEST + "a section added since\n")
+
+    refreshed = refresh_skill(name=NAME, package=NAME, home=tool.home)
+
+    assert stale in refreshed
+    assert (tool.home / ".claude" / "skills" / NAME) in refreshed
+    for target in refreshed:
+        assert (target / "SKILL.md").read_text() == tool.source.read_text()
+
+
+def test_refresh_survives_an_unwritable_directory(
+    tool: Tool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A skills directory the user has locked down is their arrangement, not
+    a reason to fail the command they actually ran."""
+    tool.run("install")
+    tool.source.write_text(MANIFEST + "a section added since\n")
+
+    def refuse(source, target):
+        raise OSError(13, "Permission denied")
+
+    monkeypatch.setattr(shutil, "copy2", refuse)
+
+    assert refresh_skill(name=NAME, package=NAME, home=tool.home) == []
+
+
+def test_refresh_survives_a_missing_manifest(tool: Tool) -> None:
+    """Nothing to copy from is nothing to do, not a traceback."""
+    tool.run("install")
+    tool.source.unlink()
+
+    assert refresh_skill(name=NAME, package=NAME, home=tool.home) == []
+
+
+def test_skill_group_carries_its_bound_refresh(tool: Tool) -> None:
+    """How the root group reaches a refresh it knows no name or package for."""
+    tool.run("install")
+    tool.source.write_text(MANIFEST + "a section added since\n")
+
+    assert isinstance(tool.cli, SkillGroup)
+    assert tool.cli.refresh() == [tool.shared()]

{click_agentcli-0.4.1 → click_agentcli-0.5.0}/uv.lock

@@ -16,7 +16,7 @@ wheels = [
 
 [[package]]
 name = "click-agentcli"
-version = "0.4.1"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

click_agentcli-0.4.1/src/agentcli/group_test.py

@@ -1,121 +0,0 @@
-"""A bad flag must still honour `--json`, before click has parsed it."""
-
-import json
-
-import click
-import pytest
-from click.testing import CliRunner
-
-from agentcli import JsonAwareGroup, UsageError, emit, skill_group
-
-
-@click.group(cls=JsonAwareGroup)
-def cli() -> None:
-    """Fixture tool."""
-
-
-@click.command("go")
-@click.option("--limit", type=click.IntRange(min=0), default=10)
-@click.option("--json", "json_output", is_flag=True)
-@click.option("--boom", is_flag=True)
-def go(limit: int, json_output: bool, boom: bool) -> None:
-    if boom:
-        raise UsageError("refused on purpose")
-    emit({"limit": limit}, json_output=json_output, human=lambda d: ["ok"])
-
-
-cli.add_command(go)
-
-
-def _run(*args: str):
-    return CliRunner().invoke(cli, list(args))
-
-
-def test_success_is_enveloped() -> None:
-    result = _run("go", "--json")
-
-    assert result.exit_code == 0
-    assert json.loads(result.output) == {"ok": True, "data": {"limit": 10}}
-
-
-def test_raised_failure_is_enveloped() -> None:
-    result = _run("go", "--json", "--boom")
-
-    assert result.exit_code == 1
-    assert json.loads(result.output) == {
-        "ok": False,
-        "error": {"message": "refused on purpose"},
-    }
-
-
-def test_parse_failure_is_enveloped_though_json_never_parsed() -> None:
-    """The hard case: click refuses before the subcommand sees --json."""
-    result = _run("go", "--json", "--limit", "-1")
-
-    assert result.exit_code == 1
-    payload = json.loads(result.output)
-    assert payload["ok"] is False
-    assert "-1" in payload["error"]["message"]
-
-
-def test_unknown_option_is_enveloped() -> None:
-    result = _run("go", "--json", "--nonexistent")
-
-    assert result.exit_code == 1
-    assert json.loads(result.output)["ok"] is False
-
-
-def test_human_path_keeps_clicks_own_usage_block() -> None:
-    """Without --json a person gets click's output, not a uniform shape."""
-    result = _run("go", "--limit", "-1")
-
-    assert result.exit_code == 1
-    assert "Usage:" in result.output
-
-
-def test_main_accepts_clicks_own_positional_arguments(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
-    """A caller holding a `click.Group` may pass click's own positionals."""
-    group: click.Group = cli
-
-    group.main(["go", "--json"], "tool", None, False)
-
-    assert json.loads(capsys.readouterr().out) == {
-        "ok": True,
-        "data": {"limit": 10},
-    }
-
-
-@click.group(cls=JsonAwareGroup)
-def skilled() -> None:
-    """A tool that ships a skill."""
-
-
-skilled.add_command(go)
-skilled.add_command(skill_group(name="faketool", package="agentcli"))
-
-
-@pytest.mark.parametrize(
-    ("args", "hinted"),
-    [
-        (["go", "--nope"], True),
-        (["nosuchcommand"], True),
-        (["go", "--limit"], False),
-        (["go", "--limit", "-1"], False),
-    ],
-)
-def test_an_unknown_name_suggests_a_stale_skill(args, hinted: bool) -> None:
-    """A caller reading a skill older than the binary asks for a name the
-    binary dropped. No other failure looks like that, so nothing else hints."""
-    result = CliRunner().invoke(skilled, args)
-
-    assert result.exit_code != 0
-    assert ("skill install" in result.output) is hinted
-
-
-def test_a_tool_without_a_skill_suggests_nothing() -> None:
-    result = CliRunner().invoke(cli, ["nosuchcommand"])
-
-    assert result.exit_code != 0
-    assert "skill install" not in result.output