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

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/.github/workflows/ci.yml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-agentcli
-Version: 0.1.0
+Version: 0.3.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
@@ -13,12 +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.11
 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.11
+Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Description-Content-Type: text/markdown
 
@@ -28,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 .

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/README.md

@@ -4,7 +4,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 .

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/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.1.0"
+version = "0.3.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.11"
+requires-python = ">=3.12"
 license = "MIT"
 authors = [{ name = "owahltinez" }]
 keywords = ["click", "cli", "agent", "skill", "json"]
@@ -24,9 +24,9 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries",
     "Topic :: Utilities",
 ]

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/candidates.py

@@ -11,8 +11,6 @@ ranks, instead of special-casing each tool. Everything kind-specific goes under
 `detail`, which nothing shared ever reads.
 """
 
-from __future__ import annotations
-
 from collections.abc import Callable
 from typing import Any
 

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/candidates_test.py

@@ -1,7 +1,5 @@
 """The contract two independent tools have to agree on without talking."""
 
-from __future__ import annotations
-
 import itertools
 
 import click

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/exits.py

@@ -10,8 +10,6 @@
 with a nonzero status; only the code differs per class.
 """
 
-from __future__ import annotations
-
 import click
 
 # Click exits 2 for its own parse failures, which this table documents as a

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/exits_test.py

@@ -1,7 +1,5 @@
 """Exit codes are the contract an agent reads instead of prose."""
 
-from __future__ import annotations
-
 import click
 import pytest
 from click.testing import CliRunner

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/group.py

@@ -10,8 +10,6 @@ problem, and a tool that solves it locally is a tool the next one forgets to
 copy.
 """
 
-from __future__ import annotations
-
 import sys
 from collections.abc import Sequence
 from typing import Any, Literal, NoReturn, overload

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/group_test.py

@@ -1,7 +1,5 @@
 """A bad flag must still honour `--json`, before click has parsed it."""
 
-from __future__ import annotations
-
 import json
 
 import click

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/guide.py

@@ -5,8 +5,6 @@ skill installed once goes stale, while the guide is upgraded with the package
 that implements it.
 """
 
-from __future__ import annotations
-
 import click
 
 

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/guide_test.py

@@ -1,7 +1,5 @@
 """The manual ships in the binary, so it cannot go stale."""
 
-from __future__ import annotations
-
 from click.testing import CliRunner
 
 from agentcli.guide import guide_command

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/output.py

@@ -15,8 +15,6 @@ shaped object on failure -- makes every caller special-case both, which is how
 four tools end up with four contracts.
 """
 
-from __future__ import annotations
-
 import json
 from collections.abc import Callable, Iterable
 from typing import Any

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/output_test.py

@@ -1,7 +1,5 @@
 """One JSON object on stdout, or human text. Never both."""
 
-from __future__ import annotations
-
 import json
 
 import click

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/skill.py

@@ -10,8 +10,6 @@ Parameterised by skill name and package because the two hand-written copies
 this replaces had already drifted apart in exactly the guards that matter.
 """
 
-from __future__ import annotations
-
 import shutil
 from collections.abc import Iterable
 from importlib import resources

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/src/agentcli/skill_test.py

@@ -4,8 +4,6 @@ No test may touch a real `~/.agents` or `~/.claude`, so every one of them runs
 against a `tmp_path` home and a fake installed tool.
 """
 
-from __future__ import annotations
-
 import importlib
 import json
 import shutil

{click_agentcli-0.1.0 → click_agentcli-0.3.0}/uv.lock

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