click-agentcli 0.1.0__tar.gz

click_agentcli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # Pinned exactly: setup-uv dropped its floating major tags after v7,
+      # so v8 and later only exist as exact versions.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run test suite
+        run: uv run --python ${{ matrix.python-version }} pytest

click_agentcli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Test & Verify Suite
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # Pinned exactly: setup-uv dropped its floating major tags after v7,
+      # so v8 and later only exist as exact versions.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Run test suite
+        run: uv run pytest
+
+  build-and-publish:
+    name: Build & Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/click-agentcli
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publishing (OIDC)
+      contents: write  # Required for GitHub Release creation
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "latest"
+
+      - name: Build distributions (sdist & wheel)
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

click_agentcli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/

click_agentcli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owahltinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

click_agentcli-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: click-agentcli
+Version: 0.1.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
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,click,json,skill
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Description-Content-Type: text/markdown
+
+# 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.

click_agentcli-0.1.0/README.md

@@ -0,0 +1,92 @@
+# 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.

click_agentcli-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# The distribution name differs from the import name: PyPI rejects
+# "agentcli" as too similar to the existing "agent-cli". Importers still
+# write `import agentcli`.
+#
+# 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"
+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"
+license = "MIT"
+authors = [{ name = "owahltinez" }]
+keywords = ["click", "cli", "agent", "skill", "json"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "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",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+dependencies = ["click>=8.1"]
+
+[project.urls]
+Homepage = "https://github.com/owahltinez/click-agentcli"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentcli"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/agentcli"]
+python_files = ["*_test.py"]
+
+[tool.ruff]
+line-length = 79

click_agentcli-0.1.0/src/agentcli/__init__.py

@@ -0,0 +1,43 @@
+"""Shared conventions for agent-facing CLI tools."""
+
+from agentcli.candidates import (
+    KINDS,
+    MACRO_KEYS,
+    candidate,
+    macro_options,
+    matches,
+    rank,
+    unverifiable,
+)
+from agentcli.exits import (
+    AssertionFailure,
+    RemoteError,
+    StrictFailure,
+    UsageError,
+)
+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
+
+__all__ = [
+    "KINDS",
+    "MACRO_KEYS",
+    "AssertionFailure",
+    "JsonAwareGroup",
+    "RemoteError",
+    "StrictFailure",
+    "UsageError",
+    "candidate",
+    "dumps",
+    "emit",
+    "emit_error",
+    "guide_command",
+    "json_option",
+    "limit_option",
+    "macro_options",
+    "matches",
+    "rank",
+    "skill_group",
+    "unverifiable",
+]

click_agentcli-0.1.0/src/agentcli/candidates.py

@@ -0,0 +1,141 @@
+"""A thing you could eat, and the macros you would decide on.
+
+Two questions have the same shape — "what can I cook under 400 kcal a serving
+with 30 g of protein" and "where can I eat out under 800 kcal with 35 g" — so
+the tools that answer them emit the same record. A recipe and a restaurant dish
+differ in how they came to exist and in what detail they can show, not in what
+a decision needs from them.
+
+That shared part lives here so an orchestrator merges two JSON streams and
+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
+
+import click
+
+MACRO_KEYS = ("kcal", "protein", "fat", "carbs")
+
+KINDS = ("recipe", "meal")
+
+
+def candidate(
+    *,
+    kind: str,
+    identifier: str,
+    name: str,
+    per_serving: dict[str, float | None],
+    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.
+    """
+    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
+    }
+    return {
+        "kind": kind,
+        "id": identifier,
+        "name": name,
+        "per_serving": macros,
+        "complete": len(macros) == len(MACRO_KEYS),
+        "detail": detail or {},
+    }
+
+
+def macro_options(f: Callable[..., Any]) -> Callable[..., Any]:
+    """The two filters every candidate source accepts, spelled identically."""
+    f = click.option(
+        "--min-protein",
+        type=click.FloatRange(min=0),
+        help="Least protein, in grams per serving.",
+    )(f)
+    return click.option(
+        "--max-kcal",
+        type=click.FloatRange(min=0),
+        help="Most energy, in kcal per serving.",
+    )(f)
+
+
+def matches(
+    record: dict[str, Any],
+    *,
+    max_kcal: float | None = None,
+    min_protein: float | None = None,
+) -> bool:
+    """Whether a candidate provably satisfies the constraints.
+
+    A candidate missing the macro 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")
+
+    # A missing macro 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 (
+        protein is None or protein < min_protein
+    )
+
+    return not (over or under)
+
+
+def unverifiable(
+    record: dict[str, Any],
+    *,
+    max_kcal: float | None = None,
+    min_protein: float | None = None,
+) -> bool:
+    """Whether a filter was asked about a macro this candidate lacks."""
+    macros = record["per_serving"]
+    return (max_kcal is not None and macros.get("kcal") is None) or (
+        min_protein is not None and macros.get("protein") is None
+    )
+
+
+def rank(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Protein per 100 kcal, descending. Ties break by name, not file order.
+
+    One ranking for both kinds, so a merged list is ordered the same way
+    whoever produced it. Deterministic on every machine: no locale collation.
+    """
+
+    def key(record: dict[str, Any]) -> tuple[float, float, str]:
+        macros = record["per_serving"]
+
+        # `or 0.0` would be wrong here, and wrong in the one file that defines
+        # the missing-value contract: a published 0 kcal is a fact about black
+        # coffee, not an absent measurement. They coincide in the arithmetic
+        # below but must not coincide in the idiom.
+        kcal = macros.get("kcal")
+        protein = macros.get("protein")
+
+        density = (
+            protein / kcal * 100
+            if kcal is not None and protein is not None and kcal > 0
+            else 0.0
+        )
+
+        return (
+            -density,
+            -(protein if protein is not None else 0.0),
+            record["name"],
+        )
+
+    return sorted(records, key=key)