click-agentcli 0.1.0__py3-none-any.whl

agentcli/skill_test.py

@@ -0,0 +1,385 @@
+"""`skill install|uninstall|status`, exercised against a throwaway home.
+
+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
+import sys
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from agentcli.skill import (
+    SHARED_DIR,
+    detected_tools,
+    packaged_skill,
+    skill_group,
+)
+
+NAME = "faketool"
+MANIFEST = f"---\nname: {NAME}\ndescription: router\n---\nbody\n"
+FOREIGN = "---\nname: someone-elses-skill\n---\nimportant work\n"
+
+
+@dataclass
+class Tool:
+    """A fake installed tool: importable package, checkout SKILL.md, home."""
+
+    runner: CliRunner
+    cli: click.Group
+    home: Path
+    source: Path
+    root: Path
+
+    def run(self, *args: str):
+        return self.runner.invoke(self.cli, list(args))
+
+    def shared(self) -> Path:
+        return self.home / SHARED_DIR / NAME
+
+
+@pytest.fixture
+def tool(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Tool]:
+    """Build the fake tool and point `Path.home` at a throwaway directory."""
+    root = tmp_path / "checkout"
+    package = root / "src" / NAME
+    package.mkdir(parents=True)
+    (package / "__init__.py").write_text("")
+    source = root / "SKILL.md"
+    source.write_text(MANIFEST)
+
+    # The package has to be genuinely importable: `packaged_skill` resolves it
+    # through `importlib.resources`, which is the part worth testing.
+    monkeypatch.syspath_prepend(str(root / "src"))
+    sys.modules.pop(NAME, None)
+    importlib.invalidate_caches()
+
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setattr(Path, "home", lambda: home)
+
+    yield Tool(
+        runner=CliRunner(),
+        cli=skill_group(name=NAME, package=NAME),
+        home=home,
+        source=source,
+        root=root,
+    )
+
+    sys.modules.pop(NAME, None)
+
+
+def _install_foreign(target: Path) -> Path:
+    """Someone else's skill directory, which we must never touch."""
+    target.mkdir(parents=True)
+    manifest = target / "SKILL.md"
+    manifest.write_text(FOREIGN)
+    return manifest
+
+
+def test_packaged_skill_prefers_the_wheel_copy(tool: Tool) -> None:
+    packaged = tool.root / "src" / NAME / "skills" / NAME / "SKILL.md"
+    packaged.parent.mkdir(parents=True)
+    packaged.write_text(MANIFEST)
+
+    assert packaged_skill(name=NAME, package=NAME) == packaged
+
+
+def test_packaged_skill_falls_back_to_the_checkout(tool: Tool) -> None:
+    assert packaged_skill(name=NAME, package=NAME) == tool.source
+
+
+def test_packaged_skill_reports_where_it_looked(tool: Tool) -> None:
+    tool.source.unlink()
+
+    with pytest.raises(Exception, match="SKILL.md not found"):
+        packaged_skill(name=NAME, package=NAME)
+
+
+def test_install_into_a_fresh_home(tool: Tool) -> None:
+    result = tool.run("install")
+
+    assert result.exit_code == 0
+    assert (tool.shared() / "SKILL.md").read_text() == MANIFEST
+    # Copy, not link, so `uv cache prune` cannot take the skill with it.
+    assert not (tool.shared() / "SKILL.md").is_symlink()
+
+
+def test_install_refuses_a_foreign_directory(tool: Tool) -> None:
+    skills = tool.home / "elsewhere"
+    manifest = _install_foreign(skills / NAME)
+
+    result = tool.run("install", "--to", str(skills))
+
+    assert result.exit_code == 1
+    assert "does not contain the faketool skill" in result.output
+    assert manifest.read_text() == FOREIGN
+
+
+def test_install_refreshes_our_own_copy(tool: Tool) -> None:
+    """Re-running install is how a stale skill gets updated, so it must work.
+
+    The packaged manifest is the source of truth, which makes replacing our
+    own copy idempotent rather than destructive.
+    """
+    tool.run("install")
+    (tool.shared() / "SKILL.md").write_text("stale\nname: faketool\n")
+
+    result = tool.run("install")
+
+    assert result.exit_code == 0
+    assert (tool.shared() / "SKILL.md").read_text() == MANIFEST
+
+
+def test_install_link_makes_a_symlink(tool: Tool) -> None:
+    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()
+
+
+def test_install_covers_detected_tools_without_a_flag(tool: Tool) -> None:
+    """Installing a skill everywhere it is wanted is the whole job."""
+    (tool.home / ".claude").mkdir()
+    (tool.home / ".gemini").mkdir()
+
+    result = tool.run("install")
+
+    assert result.exit_code == 0
+    for relative in (
+        SHARED_DIR,
+        Path(".claude") / "skills",
+        Path(".gemini") / "skills",
+        Path(".gemini") / "config" / "skills",
+    ):
+        assert (tool.home / relative / NAME / "SKILL.md").is_file()
+    # An undetected tool is never created.
+    assert not (tool.home / ".cursor").exists()
+
+
+def test_install_all_dedupes_an_overlapping_to(tool: Tool) -> None:
+    """`--to` naming a swept directory must not refuse itself."""
+    (tool.home / ".claude").mkdir()
+    skills = tool.home / ".claude" / "skills"
+
+    result = tool.run("install", "--to", str(skills))
+
+    assert result.exit_code == 0
+    assert result.output.count(str(skills / NAME)) == 1
+
+
+def test_install_dry_run_touches_nothing(tool: Tool) -> None:
+    result = tool.run("install", "--dry-run")
+
+    assert result.exit_code == 0
+    assert "would install" in result.output
+    assert not (tool.home / ".agents").exists()
+
+
+def test_install_dry_run_predicts_a_foreign_refusal(tool: Tool) -> None:
+    skills = tool.home / "elsewhere"
+    _install_foreign(skills / NAME)
+
+    result = tool.run("install", "--to", str(skills), "--dry-run")
+
+    assert result.exit_code == 0
+    assert "would REFUSE" in result.output
+    assert "does not contain the faketool skill" in result.output
+
+
+def test_install_dry_run_predicts_a_refresh(tool: Tool) -> None:
+    """Re-installing over our own copy is a plain install, not a refusal."""
+    tool.run("install")
+
+    result = tool.run("install", "--dry-run")
+
+    assert result.exit_code == 0
+    assert "would install" in result.output
+    assert "would REFUSE" not in result.output
+
+
+def test_uninstall_removes_our_own(tool: Tool) -> None:
+    tool.run("install")
+
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 0
+    assert not tool.shared().exists()
+
+
+def test_uninstall_refuses_a_foreign_directory(tool: Tool) -> None:
+    skills = tool.home / "elsewhere"
+    manifest = _install_foreign(skills / NAME)
+
+    result = tool.run("uninstall", "--to", str(skills))
+
+    assert result.exit_code == 1
+    assert "refusing to delete it" in result.output
+    assert manifest.read_text() == FOREIGN
+
+
+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()
+    manifest = tool.shared() / "SKILL.md"
+    assert manifest.is_symlink() and not manifest.exists()
+
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 0
+    assert not tool.shared().exists()
+
+
+def test_uninstall_sweeps_uninstalled_tools(tool: Tool) -> None:
+    """A removed tool can leave a skill behind; that is what needs sweeping."""
+    stale = tool.home / ".cursor" / "skills" / NAME
+    stale.mkdir(parents=True)
+    (stale / "SKILL.md").write_text(MANIFEST)
+
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 0
+    assert not stale.exists()
+
+
+def test_uninstall_dry_run_touches_nothing(tool: Tool) -> None:
+    tool.run("install")
+
+    result = tool.run("uninstall", "--dry-run")
+
+    assert result.exit_code == 0
+    assert "would remove" in result.output
+    assert (tool.shared() / "SKILL.md").is_file()
+
+
+def test_uninstall_reports_an_empty_sweep(tool: Tool) -> None:
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 0
+    assert result.output.strip() == "nothing to remove"
+
+
+def test_detected_tools_needs_the_marker(tool: Tool) -> None:
+    assert detected_tools(tool.home) == {}
+
+    (tool.home / ".gemini").mkdir()
+
+    assert set(detected_tools(tool.home)) == {"Gemini CLI", "Antigravity"}
+
+
+def test_status_json_is_one_object(tool: Tool) -> None:
+    tool.run("install")
+
+    result = tool.run("status", "--json")
+
+    assert result.exit_code == 0
+    assert len(result.output.strip().splitlines()) == 1
+    envelope = json.loads(result.output)
+    assert envelope["ok"] is True
+    payload = envelope["data"]
+    assert payload["skill"] == NAME
+    installed = [r for r in payload["locations"] if r["installed"]]
+    assert [r["path"] for r in installed] == [str(tool.shared())]
+
+
+def test_status_human_lists_every_location(tool: Tool) -> None:
+    result = tool.run("status")
+
+    assert result.exit_code == 0
+    assert "Claude Code" in result.output
+    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:
+    """A full disk is an error message, not a stack trace."""
+
+    def refuse(source, target):
+        raise OSError(28, "No space left on device")
+
+    monkeypatch.setattr(shutil, "copy2", refuse)
+
+    result = tool.run("install")
+
+    assert result.exit_code == 1
+    assert "could not install into" in result.output
+    assert "No space left on device" in result.output
+
+
+def test_uninstall_wraps_oserror(
+    tool: Tool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    tool.run("install")
+
+    def refuse(path):
+        raise OSError(13, "Permission denied")
+
+    monkeypatch.setattr(shutil, "rmtree", refuse)
+
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 1
+    assert "could not remove" in result.output
+    assert "Permission denied" in result.output
+
+
+def test_install_to_stays_scoped_to_one_directory(tool: Tool) -> None:
+    """`--to` is how you opt out of the sweep."""
+    (tool.home / ".claude").mkdir()
+    only = tool.home / "only"
+
+    result = tool.run("install", "--to", str(only))
+
+    assert result.exit_code == 0
+    assert (only / NAME / "SKILL.md").is_file()
+    assert not (tool.home / ".claude" / "skills").exists()
+    assert not tool.shared().exists()
+
+
+def test_uninstall_matches_what_install_wrote(tool: Tool) -> None:
+    """An asymmetric default would strand copies install had made."""
+    (tool.home / ".claude").mkdir()
+    (tool.home / ".gemini").mkdir()
+    tool.run("install")
+
+    result = tool.run("uninstall")
+
+    assert result.exit_code == 0
+    for relative in (
+        SHARED_DIR,
+        Path(".claude") / "skills",
+        Path(".gemini") / "skills",
+        Path(".gemini") / "config" / "skills",
+    ):
+        assert not (tool.home / relative / NAME).exists()

click_agentcli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+agentcli/__init__.py,sha256=Rger_jPCXj-JPvSBWlq7ka7Qgl3a8MVLPI79rKWXfrI,855
+agentcli/candidates.py,sha256=StcZ5SERMRihRtTfUGG-PKW5jGwwlQUvRGnXTsH-cSI,4532
+agentcli/candidates_test.py,sha256=_uFxXJLK-4u1w9c9gapB_u1dPWWGrbwnuCLzYGSmfhY,6352
+agentcli/exits.py,sha256=BDjdncmNgvC2PtYN19KUawTZowNV5MG8NSpxkEZdUIg,1602
+agentcli/exits_test.py,sha256=DJizSrQDJfs8xSK1LxmP2s7tBbNLQjJMZJg7lDUg9lI,1775
+agentcli/group.py,sha256=RZpnbebPkh2ny6i7HtWoKxbd2wXDPAbFvtupqSqXPFQ,2590
+agentcli/group_test.py,sha256=SCySCilYVnqa-vgYIhOhqCMf5Ep48Q2rsWOg0VziHqw,2392
+agentcli/guide.py,sha256=azKyaFabfvxM84FYbbYsM0UbTUJOo7WXEKxIwkhoBq0,579
+agentcli/guide_test.py,sha256=A1GWekxj7Rs7qogFFgY2UkLER1b-AaMmaTGHSnKh1_M,369
+agentcli/output.py,sha256=JBwpM8cbLkoS5w9yQCZ4ueF55NQQ0h_bGBZ_XbokSaM,2658
+agentcli/output_test.py,sha256=nVF7xQr1g4fSJ527LX1EnffVPmzFrrdb5MLE_eswXKA,2444
+agentcli/skill.py,sha256=rsZidUAHxky3sL16ug2VaKsoF413bh3vnETFkZ9obV8,13777
+agentcli/skill_test.py,sha256=vOWJ5HZi7LzoVSNAe5ObaWMMPiz45QG92cEWftVHf4k,11297
+click_agentcli-0.1.0.dist-info/METADATA,sha256=tXAtkx-NW_JdNZAMhLbinoAR9lbWMSWX_ez_NvPFVQs,4627
+click_agentcli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+click_agentcli-0.1.0.dist-info/licenses/LICENSE,sha256=LHFhXRfOqppxH3pCE8mWWr3RP_FWivgx5qgh927IFwM,1067
+click_agentcli-0.1.0.dist-info/RECORD,,

click_agentcli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

click_agentcli-0.1.0.dist-info/licenses/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.