agent-tool-shared-cli 0.1.0__tar.gz

agent_tool_shared_cli-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: agent-tool-shared-cli
+Version: 0.1.0
+Summary: Shared chassis for agent-ready CLIs: the exit-code contract, JSON/table/markdown/CSV output with field projection, and keyring-backed credentials.
+Author: Zierhut IT, Alexander Zierhut
+License: MIT
+Project-URL: Homepage, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Repository, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Issues, https://github.com/alexander-zierhut/agent-tool-shared-cli/issues
+Keywords: cli,command-line,ai-agent,llm,automation,json-output,keyring,exit-codes,agent-ready
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: keyring>=25
+Requires-Dist: rich>=13
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+
+# agent-tool-shared-cli
+
+The shared chassis for the **`agent-tool-<x>-cli`** family — agent-ready command-line
+tools that an LLM can drive with no prior knowledge of them.
+
+Consumers: [`agent-tool-openproject-cli`](https://github.com/alexander-zierhut/agent-tool-openproject-cli),
+`agent-tool-drone-cli` (in progress).
+
+This repo also holds **[BLUEPRINT.md](BLUEPRINT.md)** — the engineering standard the
+whole family is built to. Read that first if you are standing up a new tool.
+
+```bash
+pip install agent-tool-shared-cli
+```
+
+## What's in it
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every tool,
+because an agent learns the contract once and applies it everywhere.
+
+| Module | What |
+|---|---|
+| `agentcli.errors` | The exit-code taxonomy (`0/1/3/4/5/6/7/130`) + `DryRun` |
+| `agentcli.output` | `Emitter`: json/table/markdown/csv, `--fields` projection, NDJSON streaming |
+| `agentcli.credentials` | Keyring storage with a `0600` fallback and an env override |
+| `agentcli.appspec` | `AppSpec` — the two strings that make all of the above tool-specific |
+
+```python
+from agentcli import AppSpec, Credentials, Emitter, OutputFormat, NotFoundError
+
+SPEC = AppSpec(name="drone-cli", env_prefix="DRONECLI")
+
+SPEC.config_dir()            # ~/.config/drone-cli  (or $DRONECLI_CONFIG_DIR)
+SPEC.env("TOKEN")            # "DRONECLI_TOKEN"
+
+Credentials(SPEC).get_token("default")     # env > keyring > 0600 file
+Emitter(OutputFormat.json, fields=["id", "status"]).emit(rows)
+raise NotFoundError("no such build")       # -> exit 5, JSON on stderr
+```
+
+## The exit-code contract
+
+Published API. You may leave a code unallocated, or repurpose one deliberately.
+**You may never renumber one** — agents branch on these, and they are documented in
+three places per tool (README, the in-binary `guide`, and the Claude skill).
+
+| Code | Meaning |
+|---|---|
+| 0 | success (including a successful `--dry-run`) |
+| 1 | generic error |
+| 2 | *reserved for Click/Typer usage errors — never allocate* |
+| 3 | config error |
+| 4 | auth error (401/403) |
+| 5 | not found (404) |
+| 6 | conflict (409 / optimistic locking) |
+| 7 | validation error (422) — see `fieldErrors` |
+| 8+ | per-tool, and only for a condition you have **observed** |
+| 130 | SIGINT |
+
+## What is deliberately NOT here
+
+`client.py`, `serialize.py`, `resolve.py` and the domain commands stay in each tool.
+They *look* shareable and are not:
+
+> OpenProject stops paginating on an authoritative `total` — "never stop on a short
+> page". Drone has no total, and a short page **is** the terminator. The rule that
+> inverts between tool #1 and tool #2 is exactly the rule you must not hoist.
+
+Auth schemes, retry matrices and error-body shapes are the same story. Pulling them in
+would make this a framework with a config object per tool, which is how shared-code
+projects die.
+
+**Share the contract, not the transport.**
+
+## Contributing
+
+You need nothing but Python:
+
+```bash
+pip install -e '.[test]'
+pytest                       # 74 tests, no network, no services
+```
+
+Changes here affect every downstream CLI. Two rules:
+
+1. **Never renumber an exit code, and never change an output shape** without treating
+   it as a breaking change — downstream agents depend on both.
+2. **Don't add a module because two tools happen to share it today.** Wait until a
+   third does, and until you can state the rule it obeys. `tests/test_contract.py`
+   is the tripwire: if a change makes you edit it, stop and think.
+
+## License
+
+MIT

agent_tool_shared_cli-0.1.0/README.md

@@ -0,0 +1,95 @@
+# agent-tool-shared-cli
+
+The shared chassis for the **`agent-tool-<x>-cli`** family — agent-ready command-line
+tools that an LLM can drive with no prior knowledge of them.
+
+Consumers: [`agent-tool-openproject-cli`](https://github.com/alexander-zierhut/agent-tool-openproject-cli),
+`agent-tool-drone-cli` (in progress).
+
+This repo also holds **[BLUEPRINT.md](BLUEPRINT.md)** — the engineering standard the
+whole family is built to. Read that first if you are standing up a new tool.
+
+```bash
+pip install agent-tool-shared-cli
+```
+
+## What's in it
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every tool,
+because an agent learns the contract once and applies it everywhere.
+
+| Module | What |
+|---|---|
+| `agentcli.errors` | The exit-code taxonomy (`0/1/3/4/5/6/7/130`) + `DryRun` |
+| `agentcli.output` | `Emitter`: json/table/markdown/csv, `--fields` projection, NDJSON streaming |
+| `agentcli.credentials` | Keyring storage with a `0600` fallback and an env override |
+| `agentcli.appspec` | `AppSpec` — the two strings that make all of the above tool-specific |
+
+```python
+from agentcli import AppSpec, Credentials, Emitter, OutputFormat, NotFoundError
+
+SPEC = AppSpec(name="drone-cli", env_prefix="DRONECLI")
+
+SPEC.config_dir()            # ~/.config/drone-cli  (or $DRONECLI_CONFIG_DIR)
+SPEC.env("TOKEN")            # "DRONECLI_TOKEN"
+
+Credentials(SPEC).get_token("default")     # env > keyring > 0600 file
+Emitter(OutputFormat.json, fields=["id", "status"]).emit(rows)
+raise NotFoundError("no such build")       # -> exit 5, JSON on stderr
+```
+
+## The exit-code contract
+
+Published API. You may leave a code unallocated, or repurpose one deliberately.
+**You may never renumber one** — agents branch on these, and they are documented in
+three places per tool (README, the in-binary `guide`, and the Claude skill).
+
+| Code | Meaning |
+|---|---|
+| 0 | success (including a successful `--dry-run`) |
+| 1 | generic error |
+| 2 | *reserved for Click/Typer usage errors — never allocate* |
+| 3 | config error |
+| 4 | auth error (401/403) |
+| 5 | not found (404) |
+| 6 | conflict (409 / optimistic locking) |
+| 7 | validation error (422) — see `fieldErrors` |
+| 8+ | per-tool, and only for a condition you have **observed** |
+| 130 | SIGINT |
+
+## What is deliberately NOT here
+
+`client.py`, `serialize.py`, `resolve.py` and the domain commands stay in each tool.
+They *look* shareable and are not:
+
+> OpenProject stops paginating on an authoritative `total` — "never stop on a short
+> page". Drone has no total, and a short page **is** the terminator. The rule that
+> inverts between tool #1 and tool #2 is exactly the rule you must not hoist.
+
+Auth schemes, retry matrices and error-body shapes are the same story. Pulling them in
+would make this a framework with a config object per tool, which is how shared-code
+projects die.
+
+**Share the contract, not the transport.**
+
+## Contributing
+
+You need nothing but Python:
+
+```bash
+pip install -e '.[test]'
+pytest                       # 74 tests, no network, no services
+```
+
+Changes here affect every downstream CLI. Two rules:
+
+1. **Never renumber an exit code, and never change an output shape** without treating
+   it as a breaking change — downstream agents depend on both.
+2. **Don't add a module because two tools happen to share it today.** Wait until a
+   third does, and until you can state the rule it obeys. `tests/test_contract.py`
+   is the tripwire: if a change makes you edit it, stop and think.
+
+## License
+
+MIT

agent_tool_shared_cli-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-tool-shared-cli"
+description = "Shared chassis for agent-ready CLIs: the exit-code contract, JSON/table/markdown/CSV output with field projection, and keyring-backed credentials."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Zierhut IT" }, { name = "Alexander Zierhut" }]
+dynamic = ["version"]
+keywords = [
+    "cli", "command-line", "ai-agent", "llm", "automation",
+    "json-output", "keyring", "exit-codes", "agent-ready",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "keyring>=25",
+    "rich>=13",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-timeout>=2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/alexander-zierhut/agent-tool-shared-cli"
+Repository = "https://github.com/alexander-zierhut/agent-tool-shared-cli"
+Issues = "https://github.com/alexander-zierhut/agent-tool-shared-cli/issues"
+
+# No [project.scripts]: this is a library, not a command.
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Single source of truth for the version — the scar opcli carries (it duplicates
+# the number in pyproject.toml AND __init__.py, so a bump can ship a wheel that
+# reports the wrong version in its User-Agent and in the skill it writes).
+[tool.setuptools.dynamic]
+version = { attr = "agentcli.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+timeout = 60

agent_tool_shared_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_tool_shared_cli-0.1.0/src/agent_tool_shared_cli.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: agent-tool-shared-cli
+Version: 0.1.0
+Summary: Shared chassis for agent-ready CLIs: the exit-code contract, JSON/table/markdown/CSV output with field projection, and keyring-backed credentials.
+Author: Zierhut IT, Alexander Zierhut
+License: MIT
+Project-URL: Homepage, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Repository, https://github.com/alexander-zierhut/agent-tool-shared-cli
+Project-URL: Issues, https://github.com/alexander-zierhut/agent-tool-shared-cli/issues
+Keywords: cli,command-line,ai-agent,llm,automation,json-output,keyring,exit-codes,agent-ready
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: keyring>=25
+Requires-Dist: rich>=13
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+
+# agent-tool-shared-cli
+
+The shared chassis for the **`agent-tool-<x>-cli`** family — agent-ready command-line
+tools that an LLM can drive with no prior knowledge of them.
+
+Consumers: [`agent-tool-openproject-cli`](https://github.com/alexander-zierhut/agent-tool-openproject-cli),
+`agent-tool-drone-cli` (in progress).
+
+This repo also holds **[BLUEPRINT.md](BLUEPRINT.md)** — the engineering standard the
+whole family is built to. Read that first if you are standing up a new tool.
+
+```bash
+pip install agent-tool-shared-cli
+```
+
+## What's in it
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every tool,
+because an agent learns the contract once and applies it everywhere.
+
+| Module | What |
+|---|---|
+| `agentcli.errors` | The exit-code taxonomy (`0/1/3/4/5/6/7/130`) + `DryRun` |
+| `agentcli.output` | `Emitter`: json/table/markdown/csv, `--fields` projection, NDJSON streaming |
+| `agentcli.credentials` | Keyring storage with a `0600` fallback and an env override |
+| `agentcli.appspec` | `AppSpec` — the two strings that make all of the above tool-specific |
+
+```python
+from agentcli import AppSpec, Credentials, Emitter, OutputFormat, NotFoundError
+
+SPEC = AppSpec(name="drone-cli", env_prefix="DRONECLI")
+
+SPEC.config_dir()            # ~/.config/drone-cli  (or $DRONECLI_CONFIG_DIR)
+SPEC.env("TOKEN")            # "DRONECLI_TOKEN"
+
+Credentials(SPEC).get_token("default")     # env > keyring > 0600 file
+Emitter(OutputFormat.json, fields=["id", "status"]).emit(rows)
+raise NotFoundError("no such build")       # -> exit 5, JSON on stderr
+```
+
+## The exit-code contract
+
+Published API. You may leave a code unallocated, or repurpose one deliberately.
+**You may never renumber one** — agents branch on these, and they are documented in
+three places per tool (README, the in-binary `guide`, and the Claude skill).
+
+| Code | Meaning |
+|---|---|
+| 0 | success (including a successful `--dry-run`) |
+| 1 | generic error |
+| 2 | *reserved for Click/Typer usage errors — never allocate* |
+| 3 | config error |
+| 4 | auth error (401/403) |
+| 5 | not found (404) |
+| 6 | conflict (409 / optimistic locking) |
+| 7 | validation error (422) — see `fieldErrors` |
+| 8+ | per-tool, and only for a condition you have **observed** |
+| 130 | SIGINT |
+
+## What is deliberately NOT here
+
+`client.py`, `serialize.py`, `resolve.py` and the domain commands stay in each tool.
+They *look* shareable and are not:
+
+> OpenProject stops paginating on an authoritative `total` — "never stop on a short
+> page". Drone has no total, and a short page **is** the terminator. The rule that
+> inverts between tool #1 and tool #2 is exactly the rule you must not hoist.
+
+Auth schemes, retry matrices and error-body shapes are the same story. Pulling them in
+would make this a framework with a config object per tool, which is how shared-code
+projects die.
+
+**Share the contract, not the transport.**
+
+## Contributing
+
+You need nothing but Python:
+
+```bash
+pip install -e '.[test]'
+pytest                       # 74 tests, no network, no services
+```
+
+Changes here affect every downstream CLI. Two rules:
+
+1. **Never renumber an exit code, and never change an output shape** without treating
+   it as a breaking change — downstream agents depend on both.
+2. **Don't add a module because two tools happen to share it today.** Wait until a
+   third does, and until you can state the rule it obeys. `tests/test_contract.py`
+   is the tripwire: if a change makes you edit it, stop and think.
+
+## License
+
+MIT

agent_tool_shared_cli-0.1.0/src/agent_tool_shared_cli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/agent_tool_shared_cli.egg-info/PKG-INFO
+src/agent_tool_shared_cli.egg-info/SOURCES.txt
+src/agent_tool_shared_cli.egg-info/dependency_links.txt
+src/agent_tool_shared_cli.egg-info/requires.txt
+src/agent_tool_shared_cli.egg-info/top_level.txt
+src/agentcli/__init__.py
+src/agentcli/appspec.py
+src/agentcli/credentials.py
+src/agentcli/errors.py
+src/agentcli/output.py
+tests/test_appspec.py
+tests/test_contract.py
+tests/test_credentials.py
+tests/test_output_render.py

agent_tool_shared_cli-0.1.0/src/agent_tool_shared_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_tool_shared_cli-0.1.0/src/agent_tool_shared_cli.egg-info/requires.txt

@@ -0,0 +1,6 @@
+keyring>=25
+rich>=13
+
+[test]
+pytest>=8
+pytest-timeout>=2.3

agent_tool_shared_cli-0.1.0/src/agent_tool_shared_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentcli

agent_tool_shared_cli-0.1.0/src/agentcli/__init__.py

@@ -0,0 +1,58 @@
+"""agentcli — the shared chassis for `agent-tool-<x>-cli` tools.
+
+This package is deliberately small. It holds **the agent contract** and the pure
+utilities that implement it — the things that must be *identical* across every
+tool we ship, because an agent learns the contract once and applies it everywhere:
+
+* :mod:`agentcli.errors`      — the exit-code taxonomy (0/1/3/4/5/6/7/130) + ``DryRun``
+* :mod:`agentcli.output`      — json/table/markdown/csv, ``--fields`` projection, NDJSON
+* :mod:`agentcli.credentials` — keyring with a 0600 fallback and an env override
+* :mod:`agentcli.appspec`     — the two strings that make the above tool-specific
+
+**What is deliberately NOT here**, and why it matters more than what is:
+
+``client.py``, ``serialize.py``, ``resolve.py`` and the domain command modules
+stay in each tool. They *look* shareable and are not — OpenProject's pagination
+stops on an authoritative ``total`` ("never stop on a short page"), while Drone
+has no total and a short page IS the terminator. The rule that inverts between
+tool #1 and tool #2 is exactly the rule you must not hoist. Auth schemes, retry
+matrices and error-body shapes are the same story.
+
+    Share the contract, not the transport.
+
+Pulling those in would turn this into a framework with a config object per tool,
+which is how shared-code projects die.
+"""
+
+from .appspec import AppSpec
+from .credentials import Credentials
+from .errors import (
+    ApiError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    DryRun,
+    NotFoundError,
+    OpError,
+    ValidationError,
+)
+from .output import Emitter, OutputFormat, print_error  # NDJSON is Emitter.stream_json()
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AppSpec",
+    "Credentials",
+    "Emitter",
+    "OutputFormat",
+    "print_error",
+    "OpError",
+    "ApiError",
+    "AuthError",
+    "ConfigError",
+    "ConflictError",
+    "NotFoundError",
+    "ValidationError",
+    "DryRun",
+    "__version__",
+]

agent_tool_shared_cli-0.1.0/src/agentcli/appspec.py

@@ -0,0 +1,96 @@
+"""`AppSpec` — the two strings that make a shared chassis tool-specific.
+
+Every tool in the `agent-tool-<x>-cli` family needs the same four things from
+its identity:
+
+* a **config directory**       ``~/.config/<name>/``
+* a **keyring service name**   ``<name>``
+* an **env-var namespace**     ``<PREFIX>_TOKEN``, ``<PREFIX>_CONFIG_DIR``, …
+* a **relocatable config dir**, so tests are hermetic
+
+So that is all `AppSpec` carries. It is deliberately not a plugin system, a
+registry or a settings framework — two strings and a few pure functions.
+
+Why this exists at all: in `opcli` the config-dir logic was **duplicated** in
+both ``config.py`` and ``credentials.py``. Two copies of "where do I live?" that
+nothing forced to agree — relocate one and the token and the profile end up in
+different directories. Here there is exactly one.
+
+    SPEC = AppSpec(name="op-cli", env_prefix="OPCLI")
+    SPEC.config_dir()          # -> ~/.config/op-cli   (or $OPCLI_CONFIG_DIR)
+    SPEC.env("TOKEN")          # -> "OPCLI_TOKEN"
+    SPEC.getenv("BASE_URL")    # -> os.environ.get("OPCLI_BASE_URL")
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AppSpec:
+    """Identity of one CLI. Frozen: this is configuration, not state."""
+
+    name: str
+    """Directory + keyring service name, e.g. ``op-cli``, ``drone-cli``."""
+
+    env_prefix: str
+    """Env-var namespace WITHOUT the trailing underscore, e.g. ``OPCLI``."""
+
+    def __post_init__(self) -> None:
+        # These two are the whole contract; a typo here silently relocates a
+        # user's config or splits their token from their profile.
+        if not self.name or "/" in self.name:
+            raise ValueError(f"AppSpec.name must be a bare directory name, got {self.name!r}")
+        if not self.env_prefix or not self.env_prefix.isupper():
+            raise ValueError(
+                f"AppSpec.env_prefix must be UPPERCASE and non-empty, got {self.env_prefix!r}"
+            )
+        if self.env_prefix.endswith("_"):
+            raise ValueError(
+                f"AppSpec.env_prefix must not end with '_' (it is added for you), got {self.env_prefix!r}"
+            )
+
+    # ---- env ---------------------------------------------------------
+
+    def env(self, suffix: str) -> str:
+        """The full env-var name for *suffix*: ``env("TOKEN") -> "OPCLI_TOKEN"``."""
+        return f"{self.env_prefix}_{suffix}"
+
+    def getenv(self, suffix: str, default: str | None = None) -> str | None:
+        """Read ``<PREFIX>_<SUFFIX>`` from the environment."""
+        return os.environ.get(self.env(suffix), default)
+
+    # ---- paths -------------------------------------------------------
+
+    def config_dir(self) -> Path:
+        """Where this tool's config lives.
+
+        A **function, not a module constant** — and that single property is what
+        makes the test suites hermetic. As a constant it would freeze at import
+        time, before a test could point ``<PREFIX>_CONFIG_DIR`` at a tmpdir, and
+        every test run would read and write the developer's real config.
+
+        Precedence: ``<PREFIX>_CONFIG_DIR`` > ``XDG_CONFIG_HOME``/<name> > ``~/.config/<name>``.
+        """
+        base = self.getenv("CONFIG_DIR")
+        if base:
+            return Path(base)
+        xdg = os.environ.get("XDG_CONFIG_HOME")
+        root = Path(xdg) if xdg else Path.home() / ".config"
+        return root / self.name
+
+    def config_file(self) -> Path:
+        return self.config_dir() / "config.json"
+
+    def credentials_file(self) -> Path:
+        """The 0600 fallback used only when no OS keyring is available."""
+        return self.config_dir() / "credentials.json"
+
+    # ---- keyring -----------------------------------------------------
+
+    @property
+    def keyring_service(self) -> str:
+        return self.name