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

{click_agentcli-0.2.0 → click_agentcli-0.4.1}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.13", "3.14"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v7

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-agentcli
-Version: 0.2.0
+Version: 0.4.1
 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
@@ -13,11 +13,12 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
-Requires-Python: >=3.13
+Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Description-Content-Type: text/markdown
 
@@ -27,7 +28,97 @@ Shared conventions for command-line tools whose primary callers are agents.
 It owns no food domain: it owns predictable errors, JSON output, skills,
 in-binary guides, and the candidate record used for composition.
 
-## Install and test
+## Use it in a package
+
+Install the distribution (the import name remains `agentcli`):
+
+```sh
+uv add click-agentcli
+```
+
+Register the shared output, guide, and skill commands on a Click CLI:
+
+```python
+import click
+
+from agentcli import (
+    JsonAwareGroup,
+    emit,
+    guide_command,
+    json_option,
+    skill_group,
+)
+
+GUIDE = """# acme guide
+
+Use `acme hello` to print a greeting.
+"""
+
+
+@click.group(cls=JsonAwareGroup)
+def cli() -> None:
+    """Acme's agent-facing CLI."""
+
+
+@cli.command()
+@json_option
+def hello(json_output: bool) -> None:
+    """Print a greeting."""
+    emit(
+        {"message": "hello"},
+        json_output=json_output,
+        human=lambda result: [result["message"]],
+    )
+
+
+cli.add_command(guide_command(GUIDE))
+cli.add_command(skill_group(name="acme", package="acme"))
+```
+
+The command has readable output for people and one stable document for agents:
+
+```console
+$ acme hello
+hello
+$ acme hello --json
+{"ok":true,"data":{"message":"hello"}}
+$ acme guide
+# acme guide
+...
+$ acme skill install
+copied  /home/me/.agents/skills/acme
+```
+
+Declare the entry point and ship the skill inside the import package. For
+Hatchling, a project-root `SKILL.md` can be mapped into the required wheel
+location like this:
+
+```toml
+[project.scripts]
+acme = "acme.cli:cli"
+
+[tool.hatch.build.targets.wheel.force-include]
+"SKILL.md" = "acme/skills/acme/SKILL.md"
+```
+
+`skill_group(name="acme", package="acme")` expects an installed wheel to
+contain `acme/skills/acme/SKILL.md`. The same file may stay at the repository
+root for source-checkout use. Its frontmatter name must match the skill name:
+
+```markdown
+---
+name: acme
+description: Use Acme from an agent.
+---
+
+Run `acme guide` for the complete manual.
+```
+
+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.
+
+## Develop this package
 
 ```sh
 uv sync --project .
@@ -72,8 +163,12 @@ The stable public surface is:
 - `JsonAwareGroup` for every consuming tool's top-level group.
 - `skill_group(name=..., package=...)` for `skill install`, `uninstall`, and
   `status`. Installation refuses an unrelated destination, recognises owned
-  broken symlinks, copies by default, and supports `--link`, `--to`, and
-  `--dry-run`. With no options it installs everywhere the skill is wanted
+  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
+  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
   job; a directory holding somebody else's skill is still refused.
 - `guide_command(text)` for a complete manual available without a network.
@@ -83,7 +178,7 @@ The stable public surface is:
 ## Candidate contract
 
 Candidate sources answer the same question: filter things someone could eat by
-per-serving macros, then rank them with provenance. Recipes and restaurant
+per-serving figures, then rank them with provenance. Recipes and restaurant
 meals therefore emit the same record:
 
 ```json
@@ -105,11 +200,15 @@ Sources accept `macro_options` (`--max-kcal`, `--min-protein`) and use `rank`.
 The rank key is unrounded protein per 100 kcal, then absolute protein, then
 name. `--max-kcal 0` is valid because zero-calorie records exist.
 
-`per_serving` contains only macros actually known by the source. Missing is
-never filled with zero. `complete` exposes whether the full shape is present;
-a candidate missing a requested filter macro is excluded and returned in the
-source's `unverifiable` or equivalent bucket. Every source emits that bucket,
-even when its loader makes it structurally empty.
+`per_serving` contains only figures actually known by the source, whatever
+they are — a source that also publishes fibre or sodium puts them here.
+Missing is never filled with zero. `candidate` takes the keys that count as a
+full set from its caller as `required`, because this package does not know what
+a macro is; callers answering the same question share that tuple so `complete`
+keeps meaning the same thing across them. A candidate missing a requested
+filter figure is excluded and returned in the source's `unverifiable` or
+equivalent bucket. Every source emits that bucket, even when its loader makes
+it structurally empty.
 
 This contract is the reason the tools can be independent packages: an
 orchestrator can merge and rank results without knowing which source answered.

click_agentcli-0.4.1/README.md

@@ -0,0 +1,190 @@
+# agentcli
+
+Shared conventions for command-line tools whose primary callers are agents.
+It owns no food domain: it owns predictable errors, JSON output, skills,
+in-binary guides, and the candidate record used for composition.
+
+## Use it in a package
+
+Install the distribution (the import name remains `agentcli`):
+
+```sh
+uv add click-agentcli
+```
+
+Register the shared output, guide, and skill commands on a Click CLI:
+
+```python
+import click
+
+from agentcli import (
+    JsonAwareGroup,
+    emit,
+    guide_command,
+    json_option,
+    skill_group,
+)
+
+GUIDE = """# acme guide
+
+Use `acme hello` to print a greeting.
+"""
+
+
+@click.group(cls=JsonAwareGroup)
+def cli() -> None:
+    """Acme's agent-facing CLI."""
+
+
+@cli.command()
+@json_option
+def hello(json_output: bool) -> None:
+    """Print a greeting."""
+    emit(
+        {"message": "hello"},
+        json_output=json_output,
+        human=lambda result: [result["message"]],
+    )
+
+
+cli.add_command(guide_command(GUIDE))
+cli.add_command(skill_group(name="acme", package="acme"))
+```
+
+The command has readable output for people and one stable document for agents:
+
+```console
+$ acme hello
+hello
+$ acme hello --json
+{"ok":true,"data":{"message":"hello"}}
+$ acme guide
+# acme guide
+...
+$ acme skill install
+copied  /home/me/.agents/skills/acme
+```
+
+Declare the entry point and ship the skill inside the import package. For
+Hatchling, a project-root `SKILL.md` can be mapped into the required wheel
+location like this:
+
+```toml
+[project.scripts]
+acme = "acme.cli:cli"
+
+[tool.hatch.build.targets.wheel.force-include]
+"SKILL.md" = "acme/skills/acme/SKILL.md"
+```
+
+`skill_group(name="acme", package="acme")` expects an installed wheel to
+contain `acme/skills/acme/SKILL.md`. The same file may stay at the repository
+root for source-checkout use. Its frontmatter name must match the skill name:
+
+```markdown
+---
+name: acme
+description: Use Acme from an agent.
+---
+
+Run `acme guide` for the complete manual.
+```
+
+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.
+
+## Develop this package
+
+```sh
+uv sync --project .
+uv run --project . pytest -q
+```
+
+## CLI contract
+
+Every consuming tool uses `click`, declares `--json` per command with
+`json_option`, and makes its top-level group `JsonAwareGroup`. The group scans
+raw arguments so even parse failures that happen before a subcommand exists
+honour a `--json` request. Importing `agentcli.exits` also changes Click's own
+usage-error code from 2 to 1; consumers must not repeat that correction.
+
+| code | meaning |
+| --- | --- |
+| 0 | success |
+| 1 | usage error or a caller-liftable refusal |
+| 2 | remote, network, or site failure after allowed retries |
+| 3 | a caller-stated assertion did not hold |
+| 4 | a data-quality warning escalated by `--strict` |
+
+An exhausted request budget is code 1, because the caller can lift it. A
+proportional recipe fit with no solution is code 3.
+
+`--json` emits exactly one JSON object on stdout and nothing else. Success and
+failure are symmetric:
+
+```json
+{"ok":true,"data":{}}
+{"ok":false,"error":{"message":"..."}}
+```
+
+A search with no matches is successful with an empty list. Under `--json`,
+errors go to stdout so a caller never has to merge streams to recover the one
+promised document. Human errors go to stderr.
+
+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.
+- `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
+  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
+  job; a directory holding somebody else's skill is still refused.
+- `guide_command(text)` for a complete manual available without a network.
+- `candidate`, `macro_options`, `matches`, `rank`, and `unverifiable` for the
+  shared composition record and filters below.
+
+## Candidate contract
+
+Candidate sources answer the same question: filter things someone could eat by
+per-serving figures, then rank them with provenance. Recipes and restaurant
+meals therefore emit the same record:
+
+```json
+{
+  "kind":"recipe",
+  "id":"sourdough-pizza",
+  "name":"Sourdough Pizza",
+  "per_serving":{"kcal":384.2,"protein":31.5,"fat":12.1,"carbs":38.4},
+  "complete":true,
+  "detail":{}
+}
+```
+
+`kind` is `recipe` or `meal`. `id` is accepted back by the emitting tool;
+display-only slugs are not identifiers. Source-specific fields live under
+`detail`, which shared code never reads.
+
+Sources accept `macro_options` (`--max-kcal`, `--min-protein`) and use `rank`.
+The rank key is unrounded protein per 100 kcal, then absolute protein, then
+name. `--max-kcal 0` is valid because zero-calorie records exist.
+
+`per_serving` contains only figures actually known by the source, whatever
+they are — a source that also publishes fibre or sodium puts them here.
+Missing is never filled with zero. `candidate` takes the keys that count as a
+full set from its caller as `required`, because this package does not know what
+a macro is; callers answering the same question share that tuple so `complete`
+keeps meaning the same thing across them. A candidate missing a requested
+filter figure is excluded and returned in the source's `unverifiable` or
+equivalent bucket. Every source emits that bucket, even when its loader makes
+it structurally empty.
+
+This contract is the reason the tools can be independent packages: an
+orchestrator can merge and rank results without knowing which source answered.

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

@@ -10,10 +10,10 @@ 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.2.0"
+version = "0.4.1"
 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.13"
+requires-python = ">=3.12"
 license = "MIT"
 authors = [{ name = "owahltinez" }]
 keywords = ["click", "cli", "agent", "skill", "json"]
@@ -24,6 +24,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries",

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

@@ -2,7 +2,6 @@
 
 from agentcli.candidates import (
     KINDS,
-    MACRO_KEYS,
     candidate,
     macro_options,
     matches,
@@ -22,7 +21,6 @@ from agentcli.skill import skill_group
 
 __all__ = [
     "KINDS",
-    "MACRO_KEYS",
     "AssertionFailure",
     "JsonAwareGroup",
     "RemoteError",

{click_agentcli-0.2.0 → click_agentcli-0.4.1}/src/agentcli/candidates.py

@@ -16,8 +16,6 @@ from typing import Any
 
 import click
 
-MACRO_KEYS = ("kcal", "protein", "fat", "carbs")
-
 KINDS = ("recipe", "meal")
 
 
@@ -27,29 +25,34 @@ def candidate(
     identifier: str,
     name: str,
     per_serving: dict[str, float | None],
+    required: tuple[str, ...],
     detail: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """One comparable option, per serving.
 
-    `per_serving` carries every macro the source published and omits the rest.
-    A macro is never defaulted to zero to fill the shape: a dish whose fat was
-    never measured is not a fat-free dish, and `complete` is what tells them
-    apart.
+    `per_serving` carries every figure the source published, whatever they are,
+    and omits the rest. A figure is never defaulted to zero to fill the shape:
+    a dish whose fat was never measured is not a fat-free dish, and `complete`
+    is what tells them apart.
+
+    `required` is the caller's -- which figures it considers a full set. This
+    module does not know what a macro is, and a source that publishes fibre or
+    sodium should be able to say so without asking permission here. Callers
+    that answer the same question share the tuple so `complete` keeps meaning
+    the same thing across them.
     """
     if kind not in KINDS:
         raise ValueError(f"unknown candidate kind: {kind}")
 
-    macros = {
-        key: per_serving[key]
-        for key in MACRO_KEYS
-        if per_serving.get(key) is not None
+    published = {
+        key: value for key, value in per_serving.items() if value is not None
     }
     return {
         "kind": kind,
         "id": identifier,
         "name": name,
-        "per_serving": macros,
-        "complete": len(macros) == len(MACRO_KEYS),
+        "per_serving": published,
+        "complete": all(key in published for key in required),
         "detail": detail or {},
     }
 
@@ -76,15 +79,15 @@ def matches(
 ) -> bool:
     """Whether a candidate provably satisfies the constraints.
 
-    A candidate missing the macro a filter asks about is excluded, because it
+    A candidate missing the figure a filter asks about is excluded, because it
     cannot be shown to pass. Callers report those separately rather than
     dropping them silently — "no results" and "three results I could not check"
     are different answers.
     """
-    macros = record["per_serving"]
-    kcal, protein = macros.get("kcal"), macros.get("protein")
+    published = record["per_serving"]
+    kcal, protein = published.get("kcal"), published.get("protein")
 
-    # A missing macro fails the filter that asks about it rather than being
+    # A missing figure fails the filter that asks about it rather than being
     # treated as zero, which would pass every ceiling and fail every floor.
     over = max_kcal is not None and (kcal is None or kcal > max_kcal)
     under = min_protein is not None and (

{click_agentcli-0.2.0 → click_agentcli-0.4.1}/src/agentcli/candidates_test.py

@@ -17,6 +17,10 @@ from agentcli.candidates import (
 FULL = {"kcal": 384.2, "protein": 31.5, "fat": 12.1, "carbs": 38.4}
 PARTIAL = {"kcal": 540.0, "protein": 45.8, "fat": None, "carbs": None}
 
+# What the nutrition tools happen to require. This module does not define it --
+# it is a caller's tuple, and these tests stand in for a caller.
+REQUIRED = ("kcal", "protein", "fat", "carbs")
+
 
 def make(kind: str = "recipe", name: str = "Thing", **macros: object) -> dict:
     return candidate(
@@ -24,13 +28,18 @@ def make(kind: str = "recipe", name: str = "Thing", **macros: object) -> dict:
         identifier=name.lower(),
         name=name,
         per_serving=macros or FULL,
+        required=REQUIRED,
     )
 
 
 def test_an_unpublished_macro_is_omitted_rather_than_zeroed() -> None:
     """A dish whose fat was never measured is not a fat-free dish."""
     partial = candidate(
-        kind="meal", identifier="x", name="Bowl", per_serving=PARTIAL
+        kind="meal",
+        identifier="x",
+        name="Bowl",
+        per_serving=PARTIAL,
+        required=REQUIRED,
     )
 
     assert partial["per_serving"] == {"kcal": 540.0, "protein": 45.8}
@@ -38,11 +47,44 @@ def test_an_unpublished_macro_is_omitted_rather_than_zeroed() -> None:
     assert partial["complete"] is False
 
 
-def test_complete_means_all_four_macros_present() -> None:
+def test_complete_means_every_figure_the_caller_required() -> None:
     assert make()["complete"] is True
     assert make(kcal=1.0, protein=1.0, fat=1.0)["complete"] is False
 
 
+def test_a_figure_the_caller_did_not_require_is_still_carried() -> None:
+    """A source publishing fibre should not have to ask permission here.
+
+    Filtering to a fixed set of keys meant a tool that had resolved a fibre
+    figure could not publish it, and an agent following the documented rule
+    -- look for it in `per_serving` -- concluded it was unavailable.
+    """
+    record = candidate(
+        kind="recipe",
+        identifier="soup",
+        name="Soup",
+        per_serving={**FULL, "dietary_fiber": 4.1, "sodium": 0.4},
+        required=REQUIRED,
+    )
+
+    assert record["per_serving"]["dietary_fiber"] == 4.1
+    assert record["per_serving"]["sodium"] == 0.4
+    assert record["complete"] is True
+
+
+def test_a_caller_requiring_less_is_complete_with_less() -> None:
+    """Two tools answer different questions; neither defines the other's set."""
+    record = candidate(
+        kind="meal",
+        identifier="x",
+        name="X",
+        per_serving={"kcal": 540.0, "protein": 45.8},
+        required=("kcal", "protein"),
+    )
+
+    assert record["complete"] is True
+
+
 def test_detail_is_where_the_kinds_differ() -> None:
     """Nothing shared reads `detail`, so the kinds cannot collide in it."""
     meal = candidate(
@@ -50,6 +92,7 @@ def test_detail_is_where_the_kinds_differ() -> None:
         identifier="crust-margherita",
         name="Margherita",
         per_serving=FULL,
+        required=REQUIRED,
         detail={"restaurant": "Crust Pizza", "distance_km": 1.5},
     )
 
@@ -67,7 +110,13 @@ def test_detail_is_where_the_kinds_differ() -> None:
 def test_an_unknown_kind_is_refused() -> None:
     """A third kind is a decision, not something a caller slips in."""
     with pytest.raises(ValueError, match="unknown candidate kind"):
-        candidate(kind="snack", identifier="x", name="X", per_serving=FULL)
+        candidate(
+            kind="snack",
+            identifier="x",
+            name="X",
+            per_serving=FULL,
+            required=REQUIRED,
+        )
 
 
 @pytest.mark.parametrize(
@@ -102,7 +151,11 @@ def test_a_missing_macro_fails_the_filter_that_asks_about_it() -> None:
 
 def test_no_filters_matches_everything_including_incomplete() -> None:
     partial = candidate(
-        kind="meal", identifier="x", name="Bowl", per_serving=PARTIAL
+        kind="meal",
+        identifier="x",
+        name="Bowl",
+        per_serving=PARTIAL,
+        required=REQUIRED,
     )
 
     assert matches(partial) is True
@@ -170,12 +223,14 @@ def test_a_published_zero_is_not_a_missing_measurement() -> None:
         identifier="coffee",
         name="Black Coffee",
         per_serving={"kcal": 0.0, "protein": 0.0, "fat": 0.0, "carbs": 0.0},
+        required=REQUIRED,
     )
     unmeasured = candidate(
         kind="meal",
         identifier="mystery",
         name="Mystery",
         per_serving={"protein": 0.0, "fat": 0.0, "carbs": 0.0},
+        required=REQUIRED,
     )
 
     assert measured["per_serving"]["kcal"] == 0.0

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

@@ -67,14 +67,44 @@ class JsonAwareGroup(click.Group):
             **extra,
         )
 
+    def _drift_hint(self, ctx: click.Context, exc: Exception) -> str:
+        """Why a name this caller expected might not exist.
+
+        A caller reading a skill older than the binary asks for a command the
+        binary has since renamed or dropped, and no other failure looks like
+        this. The hint lives here rather than in the skill because the skill
+        is the thing that went stale, while the binary is what was upgraded.
+        """
+        if not isinstance(exc, click.NoSuchOption | click.UsageError):
+            return ""
+        if "No such command" not in str(exc) and not isinstance(
+            exc, click.NoSuchOption
+        ):
+            return ""
+        if "skill" not in self.commands:
+            return ""
+        tool = ctx.find_root().info_name or "this tool"
+        return (
+            f" If this was documented, the installed skill predates this "
+            f"version; run `{tool} skill install`."
+        )
+
     def invoke(self, ctx: click.Context) -> Any:
         try:
             return super().invoke(ctx)
         except click.ClickException as exc:
+            hint = self._drift_hint(ctx, exc)
             # The human path stays click's own, which prints the usage block
             # too: worth more to a person than a uniform shape.
             if not self._json_requested:
+                if hint:
+                    # Re-raised rather than edited: click marks the message
+                    # final, and a UsageError still prints usage and exits 2.
+                    raise click.UsageError(
+                        f"{exc.format_message()}{hint}",
+                        ctx=getattr(exc, "ctx", None),
+                    ) from exc
                 raise
 
-            emit_error(exc.format_message(), json_output=True)
+            emit_error(f"{exc.format_message()}{hint}", json_output=True)
             ctx.exit(exc.exit_code)

{click_agentcli-0.2.0 → click_agentcli-0.4.1}/src/agentcli/group_test.py

@@ -6,7 +6,7 @@ import click
 import pytest
 from click.testing import CliRunner
 
-from agentcli import JsonAwareGroup, UsageError, emit
+from agentcli import JsonAwareGroup, UsageError, emit, skill_group
 
 
 @click.group(cls=JsonAwareGroup)
@@ -85,3 +85,37 @@ def test_main_accepts_clicks_own_positional_arguments(
         "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

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

@@ -96,9 +96,9 @@ def _primary_target(destination: Path | None, home: Path, name: str) -> Path:
 def _is_our_skill(target: Path, *, name: str) -> bool:
     """Does this directory actually hold the skill we installed?
 
-    A broken symlink counts. `--link` into a `uvx` environment dies on
-    `uv cache prune`, and refusing to clean up exactly that wreckage would be
-    perverse -- the directory is still one this tool created.
+    A broken symlink counts. Older versions could install one, and refusing to
+    clean up exactly that wreckage would be perverse -- the directory is still
+    one this tool created.
     """
     manifest = target / "SKILL.md"
     if manifest.is_symlink() and not manifest.exists():
@@ -151,14 +151,15 @@ def _refusal(target: Path, *, name: str) -> str | None:
     return None
 
 
-def _place(source: Path, target: Path, *, name: str, link: bool) -> str:
+def _place(source: Path, target: Path, *, name: str) -> str:
     """Place SKILL.md into a skill directory of its own.
 
-    Copying is the default because a link points into the environment this CLI
-    was installed into: run under `uvx`, that is a prunable cache, so the skill
-    works today and vanishes after `uv cache prune`. Copying costs a stale
-    skill after an upgrade, which is cheap here -- the skill is a router, and
-    the manual it routes to (`<tool> guide`) ships in the binary.
+    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.
     """
     refusal = _refusal(target, name=name)
     if refusal is not None:
@@ -167,27 +168,37 @@ def _place(source: Path, target: Path, *, name: str, link: bool) -> str:
     if target.exists() or target.is_symlink():
         _remove(target)
 
-    # The directory is always real, and named for the skill as the spec
-    # requires; only its contents are ever linked.
+    # The directory is named for the skill, as the spec requires.
     target.mkdir(parents=True, exist_ok=True)
-    manifest = target / "SKILL.md"
-
-    if link:
-        try:
-            manifest.symlink_to(source)
-        except OSError as exc:
-            # Windows needs Developer Mode or admin rights for symlinks. A
-            # copy is a worse answer than a link but a much better one than
-            # a traceback.
-            click.echo(f"# symlink failed ({exc}); copying instead", err=True)
-        else:
-            return f"linked  {manifest} -> {source}"
-
-    shutil.copy2(source, manifest)
+    shutil.copy2(source, target / "SKILL.md")
     return f"copied  {target}"
 
 
-def _status_rows(home: Path, name: str) -> list[dict[str, Any]]:
+def _state(path: Path, source: Path | None, *, name: str) -> str:
+    """Whether a location holds this skill, and whether it is the current one.
+
+    Presence alone said `installed` for a copy many releases old, because
+    upgrading a package never refreshes a skill already on disk. Comparing the
+    bytes is what makes that drift visible instead of silent.
+    """
+    if not _is_our_skill(path, name=name):
+        return "absent"
+    if source is None or not source.is_file():
+        return "installed"
+    installed = path / "SKILL.md"
+    try:
+        return (
+            "current"
+            if installed.read_bytes() == source.read_bytes()
+            else "stale"
+        )
+    except OSError:
+        return "installed"
+
+
+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 += [
@@ -195,22 +206,32 @@ def _status_rows(home: Path, name: str) -> list[dict[str, Any]]:
         for label, (_, skills) in TOOL_DIRS.items()
     ]
 
-    return [
-        {
-            "tool": label,
-            "path": str(path),
-            "installed": _is_our_skill(path, name=name),
-        }
-        for label, path in locations
-    ]
+    rows = []
+    for label, path in locations:
+        state = _state(path, source, name=name)
+        rows.append(
+            {
+                "tool": label,
+                "path": str(path),
+                "installed": state != "absent",
+                "state": state,
+            }
+        )
+    return rows
 
 
 def _status_lines(payload: dict[str, Any]) -> Iterable[str]:
     """Render `status` for a human: fixed columns, no table drawing."""
     for row in payload["locations"]:
-        mark = "installed" if row["installed"] else "-"
+        mark = "-" if row["state"] == "absent" else row["state"]
         yield f"{mark:<10} {row['tool']:<16} {row['path']}"
 
+    if any(row["state"] == "stale" for row in payload["locations"]):
+        yield (
+            f"A stale copy predates this version. Run "
+            f"`{payload['skill']} skill install` to refresh it."
+        )
+
 
 def skill_group(*, name: str, package: str) -> click.Group:
     """Build the `skill` command group for one tool.
@@ -235,8 +256,7 @@ def skill_group(*, name: str, package: str) -> click.Group:
 \b
   {name} skill install                       # everywhere it is wanted
   {name} skill install --to ~/.claude/skills # just this one
-  {name} skill install --to .agents/skills   # this repository only
-  {name} skill install --link                # track package upgrades""",
+  {name} skill install --to .agents/skills   # this repository only""",
     )
     @click.option(
         "--to",
@@ -244,19 +264,9 @@ def skill_group(*, name: str, package: str) -> click.Group:
         type=click.Path(file_okay=False, path_type=Path),
         help=target_help,
     )
-    @click.option(
-        "--link",
-        is_flag=True,
-        help="Symlink instead of copying, so package upgrades take effect "
-        "immediately. Only safe for a durable install and a private skills "
-        "directory: a link into a `uvx` environment dies on `uv cache "
-        "prune`, and one committed to a repository is broken for everyone "
-        "else. Re-running install is the portable way to refresh.",
-    )
     @click.option("--dry-run", is_flag=True, help=dry_run_help)
     def install_command(
         destination: Path | None,
-        link: bool,
         dry_run: bool,
     ) -> None:
         """Install the Agent Skill into an agent's skills directory.
@@ -291,7 +301,7 @@ def skill_group(*, name: str, package: str) -> click.Group:
                 continue
 
             try:
-                click.echo(_place(source, target, name=name, link=link))
+                click.echo(_place(source, target, name=name))
             except OSError as exc:
                 raise click.ClickException(
                     f"could not install into {target}: {exc.strerror or exc}"
@@ -364,9 +374,13 @@ def skill_group(*, name: str, package: str) -> click.Group:
     @json_option
     def status_command(json_output: bool) -> None:
         """Show every known location and whether the skill is installed."""
+        try:
+            source: Path | None = packaged_skill(name=name, package=package)
+        except click.ClickException:
+            source = None
         payload = {
             "skill": name,
-            "locations": _status_rows(Path.home(), name),
+            "locations": _status_rows(Path.home(), name, source),
         }
         emit(payload, json_output=json_output, human=_status_lines)
 

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

@@ -138,13 +138,13 @@ def test_install_refreshes_our_own_copy(tool: Tool) -> None:
     assert (tool.shared() / "SKILL.md").read_text() == MANIFEST
 
 
-def test_install_link_makes_a_symlink(tool: Tool) -> None:
+def test_install_refuses_to_link(tool: Tool) -> None:
+    """A link points into the environment, whose path carries the interpreter
+    version, so a rebuild elsewhere leaves the skill silently absent."""
     result = tool.run("install", "--link")
 
-    assert result.exit_code == 0
-    manifest = tool.shared() / "SKILL.md"
-    assert manifest.is_symlink()
-    assert manifest.resolve() == tool.source.resolve()
+    assert result.exit_code != 0
+    assert "--link" in result.output
 
 
 def test_install_covers_detected_tools_without_a_flag(tool: Tool) -> None:
@@ -228,10 +228,12 @@ def test_uninstall_refuses_a_foreign_directory(tool: Tool) -> None:
 
 
 def test_uninstall_removes_a_broken_symlink(tool: Tool) -> None:
-    """A `--link` install survived `uv cache prune`; clean it up anyway."""
-    tool.run("install", "--link")
-    tool.source.unlink()
+    """A link an older version installed, now dangling. Still ours to clean."""
+    tool.run("install")
     manifest = tool.shared() / "SKILL.md"
+    manifest.unlink()
+    manifest.symlink_to(tool.source)
+    tool.source.unlink()
     assert manifest.is_symlink() and not manifest.exists()
 
     result = tool.run("uninstall")
@@ -300,24 +302,6 @@ def test_status_human_lists_every_location(tool: Tool) -> None:
     assert "installed" not in result.output
 
 
-def test_install_link_failure_falls_back_to_copying(
-    tool: Tool, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    """Windows without Developer Mode: a copy beats a traceback."""
-
-    def refuse(self, target, **kwargs):
-        raise OSError("symlinks need a privilege you do not have")
-
-    monkeypatch.setattr(Path, "symlink_to", refuse)
-
-    result = tool.run("install", "--link")
-
-    assert result.exit_code == 0
-    manifest = tool.shared() / "SKILL.md"
-    assert not manifest.is_symlink()
-    assert manifest.read_text() == MANIFEST
-
-
 def test_install_wraps_oserror(
     tool: Tool, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -381,3 +365,33 @@ def test_uninstall_matches_what_install_wrote(tool: Tool) -> None:
         Path(".gemini") / "config" / "skills",
     ):
         assert not (tool.home / relative / NAME).exists()
+
+
+def test_status_calls_a_matching_copy_current(tool: Tool) -> None:
+    tool.run("install")
+
+    result = tool.run("status", "--json")
+
+    rows = json.loads(result.output)["data"]["locations"]
+    shared = next(r for r in rows if r["tool"].startswith("Shared"))
+    assert shared["state"] == "current"
+
+
+def test_status_reports_a_copy_the_package_has_moved_past(tool: Tool) -> None:
+    """Upgrading a package never refreshes a skill already on disk, so
+    presence alone reported `installed` for a copy releases out of date."""
+    tool.run("install")
+    tool.source.write_text(MANIFEST + "a section added since\n")
+
+    result = tool.run("status")
+
+    assert "stale" in result.output
+    assert "skill install" in result.output
+
+
+def test_status_still_answers_for_an_absent_location(tool: Tool) -> None:
+    result = tool.run("status", "--json")
+
+    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)

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

@@ -1,6 +1,6 @@
 version = 1
 revision = 3
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 
 [[package]]
 name = "click"
@@ -16,7 +16,7 @@ wheels = [
 
 [[package]]
 name = "click-agentcli"
-version = "0.2.0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

click_agentcli-0.2.0/README.md

@@ -1,92 +0,0 @@
-# agentcli
-
-Shared conventions for command-line tools whose primary callers are agents.
-It owns no food domain: it owns predictable errors, JSON output, skills,
-in-binary guides, and the candidate record used for composition.
-
-## Install and test
-
-```sh
-uv sync --project .
-uv run --project . pytest -q
-```
-
-## CLI contract
-
-Every consuming tool uses `click`, declares `--json` per command with
-`json_option`, and makes its top-level group `JsonAwareGroup`. The group scans
-raw arguments so even parse failures that happen before a subcommand exists
-honour a `--json` request. Importing `agentcli.exits` also changes Click's own
-usage-error code from 2 to 1; consumers must not repeat that correction.
-
-| code | meaning |
-| --- | --- |
-| 0 | success |
-| 1 | usage error or a caller-liftable refusal |
-| 2 | remote, network, or site failure after allowed retries |
-| 3 | a caller-stated assertion did not hold |
-| 4 | a data-quality warning escalated by `--strict` |
-
-An exhausted request budget is code 1, because the caller can lift it. A
-proportional recipe fit with no solution is code 3.
-
-`--json` emits exactly one JSON object on stdout and nothing else. Success and
-failure are symmetric:
-
-```json
-{"ok":true,"data":{}}
-{"ok":false,"error":{"message":"..."}}
-```
-
-A search with no matches is successful with an empty list. Under `--json`,
-errors go to stdout so a caller never has to merge streams to recover the one
-promised document. Human errors go to stderr.
-
-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.
-- `skill_group(name=..., package=...)` for `skill install`, `uninstall`, and
-  `status`. Installation refuses an unrelated destination, recognises owned
-  broken symlinks, copies by default, and supports `--link`, `--to`, and
-  `--dry-run`. With no options it installs everywhere the skill is wanted
-  and refreshes its own earlier copies, so plain `install` is the whole
-  job; a directory holding somebody else's skill is still refused.
-- `guide_command(text)` for a complete manual available without a network.
-- `candidate`, `macro_options`, `matches`, `rank`, and `unverifiable` for the
-  shared composition record and filters below.
-
-## Candidate contract
-
-Candidate sources answer the same question: filter things someone could eat by
-per-serving macros, then rank them with provenance. Recipes and restaurant
-meals therefore emit the same record:
-
-```json
-{
-  "kind":"recipe",
-  "id":"sourdough-pizza",
-  "name":"Sourdough Pizza",
-  "per_serving":{"kcal":384.2,"protein":31.5,"fat":12.1,"carbs":38.4},
-  "complete":true,
-  "detail":{}
-}
-```
-
-`kind` is `recipe` or `meal`. `id` is accepted back by the emitting tool;
-display-only slugs are not identifiers. Source-specific fields live under
-`detail`, which shared code never reads.
-
-Sources accept `macro_options` (`--max-kcal`, `--min-protein`) and use `rank`.
-The rank key is unrounded protein per 100 kcal, then absolute protein, then
-name. `--max-kcal 0` is valid because zero-calorie records exist.
-
-`per_serving` contains only macros actually known by the source. Missing is
-never filled with zero. `complete` exposes whether the full shape is present;
-a candidate missing a requested filter macro is excluded and returned in the
-source's `unverifiable` or equivalent bucket. Every source emits that bucket,
-even when its loader makes it structurally empty.
-
-This contract is the reason the tools can be independent packages: an
-orchestrator can merge and rank results without knowing which source answered.