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

{click_agentcli-0.2.0 → click_agentcli-0.3.0}/.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: click-agentcli
-Version: 0.2.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,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 .

{click_agentcli-0.2.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.2.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.2.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.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.3.0}/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.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },