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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-agentcli
-Version: 0.3.0
+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,11 +183,16 @@ 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, 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`. 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.
@@ -174,7 +202,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
@@ -196,11 +224,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.3.0 → 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,11 +159,16 @@ 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, 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`. 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.
@@ -150,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
@@ -172,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.3.0 → 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.3.0"
+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.3.0 → click_agentcli-0.5.0}/src/agentcli/__init__.py

@@ -2,7 +2,6 @@
 
 from agentcli.candidates import (
     KINDS,
-    MACRO_KEYS,
     candidate,
     macro_options,
     matches,
@@ -18,14 +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",
-    "MACRO_KEYS",
     "AssertionFailure",
     "JsonAwareGroup",
     "RemoteError",
+    "SkillGroup",
     "StrictFailure",
     "UsageError",
     "candidate",
@@ -38,6 +37,7 @@ __all__ = [
     "macro_options",
     "matches",
     "rank",
+    "refresh_skill",
     "skill_group",
     "unverifiable",
 ]

{click_agentcli-0.3.0 → click_agentcli-0.5.0}/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.3.0 → click_agentcli-0.5.0}/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.5.0/src/agentcli/group.py

@@ -0,0 +1,144 @@
+"""A command group that keeps the `--json` promise even when it fails.
+
+Requesting JSON is a promise that stdout is parseable, and that has to hold for
+failures too. The hard case is a bad flag: click raises before any subcommand
+has parsed `--json`, so at that point nothing in the parsed context knows JSON
+was wanted. The raw argument list is the only place it is known that early.
+
+This lives here rather than in each tool because every tool has the same
+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
+
+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):
+    """Routes `click.ClickException` to the JSON error shape when asked."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._json_requested = False
+
+    # The overloads mirror `click.Group.main` exactly, so a caller holding a
+    # `click.Group` can call this the same way, positionals included.
+    @overload
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: Literal[True] = True,
+        **extra: Any,
+    ) -> NoReturn: ...
+
+    @overload
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = ...,
+        **extra: Any,
+    ) -> Any: ...
+
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        **extra: Any,
+    ) -> Any:
+        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,
+            complete_var,
+            standalone_mode,
+            **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.
+
+        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(f"{exc.format_message()}{hint}", json_output=True)
+            ctx.exit(exc.exit_code)