agent-tool-shared-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tool-shared-cli
-Version: 0.1.0
+Version: 0.1.1
 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

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/src/agent_tool_shared_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tool-shared-cli
-Version: 0.1.0
+Version: 0.1.1
 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

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/src/agentcli/__init__.py

@@ -38,7 +38,7 @@ from .errors import (
 )
 from .output import Emitter, OutputFormat, print_error  # NDJSON is Emitter.stream_json()
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     "AppSpec",

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/src/agentcli/appspec.py

@@ -39,6 +39,20 @@ class AppSpec:
     env_prefix: str
     """Env-var namespace WITHOUT the trailing underscore, e.g. ``OPCLI``."""
 
+    token_env_aliases: tuple[str, ...] = ()
+    """Extra token env vars to honour, in order, AFTER ``<PREFIX>_TOKEN``.
+
+    For wrapping a product that already has an established variable its users
+    export — Drone's ``DRONE_TOKEN``, Jira's ``JIRA_API_TOKEN``, GitLab's
+    ``GITLAB_TOKEN``. Adopting the ecosystem's name is worth more than prefix
+    purity: people (and their CI) already have it set.
+
+    Ours wins when both are present — the more specific name is the more
+    deliberate one. Note the hazard this creates and surface it in `auth status`:
+    an exported alias **silently overrides a keyring login**, and for Drone the
+    ``DRONE_*`` namespace is also what the runner injects into every build step.
+    """
+
     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.
@@ -59,6 +73,10 @@ class AppSpec:
         """The full env-var name for *suffix*: ``env("TOKEN") -> "OPCLI_TOKEN"``."""
         return f"{self.env_prefix}_{suffix}"
 
+    def token_env_names(self) -> tuple[str, ...]:
+        """Every token env var this tool honours, in precedence order."""
+        return (self.env("TOKEN"), *self.token_env_aliases)
+
     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)

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/src/agentcli/credentials.py

@@ -52,8 +52,24 @@ class Credentials:
 
     @property
     def env_token(self) -> str:
+        """The canonical token env var. See :meth:`_env_token_hit` for aliases."""
         return self.spec.env("TOKEN")
 
+    def _env_token_hit(self) -> tuple[str, str] | None:
+        """The first token env var that is set, as ``(name, value)``.
+
+        Checks ``<PREFIX>_TOKEN`` first, then any ecosystem aliases in order.
+        Returns the NAME as well as the value, because an operator who logged in
+        via the keyring and is unknowingly being overridden by an exported
+        variable needs to be told exactly which one — "it works on my machine"
+        lives here.
+        """
+        for name in self.spec.token_env_names():
+            val = os.environ.get(name)
+            if val:
+                return name, val
+        return None
+
     def _fallback_file(self) -> Path:
         return self.spec.credentials_file()
 
@@ -83,8 +99,9 @@ class Credentials:
 
     def backend_name(self) -> str:
         """Human-readable name of the active secret backend (for `auth status`)."""
-        if os.environ.get(self.env_token):
-            return f"environment variable ${self.env_token}"
+        hit = self._env_token_hit()
+        if hit:
+            return f"environment variable ${hit[0]}"
         if _keyring_available():
             try:
                 import keyring
@@ -115,10 +132,17 @@ class Credentials:
         return "file"
 
     def get_token(self, profile: str) -> str | None:
-        """Resolve the token for *profile*, honouring the env override first."""
-        env = os.environ.get(self.env_token)
-        if env:
-            return env
+        """Resolve the token for *profile*, honouring the env override first.
+
+        Precedence is **env > keyring > file**, deliberately: it is what lets a
+        tool run non-interactively in CI without touching a keyring that isn't
+        there. Do not invert it — but do surface it (`backend_name`), because an
+        exported variable silently beating a keyring login is confusing exactly
+        when you can least afford it.
+        """
+        hit = self._env_token_hit()
+        if hit:
+            return hit[1]
         if _keyring_available():
             try:
                 import keyring

{agent_tool_shared_cli-0.1.0 → agent_tool_shared_cli-0.1.1}/tests/test_credentials.py

@@ -14,7 +14,9 @@ from agentcli import AppSpec, Credentials
 from agentcli import credentials as credmod
 
 OP = AppSpec(name="op-cli", env_prefix="OPCLI")
-DRONE = AppSpec(name="drone-cli", env_prefix="DRONECLI")
+# Drone wraps a product whose users already export DRONE_TOKEN (the official Go
+# CLI uses it), so we honour it as an alias behind our own name.
+DRONE = AppSpec(name="drone-cli", env_prefix="DRONECLI", token_env_aliases=("DRONE_TOKEN",))
 
 
 @pytest.fixture(autouse=True)
@@ -25,6 +27,57 @@ def _hermetic(monkeypatch, tmp_path):
     monkeypatch.setenv("DRONECLI_CONFIG_DIR", str(tmp_path / "drone"))
     monkeypatch.delenv("OPCLI_TOKEN", raising=False)
     monkeypatch.delenv("DRONECLI_TOKEN", raising=False)
+    monkeypatch.delenv("DRONE_TOKEN", raising=False)
+
+
+# ---- ecosystem token aliases (DRONE_TOKEN, JIRA_API_TOKEN, …) --------
+
+def test_alias_env_var_is_honoured(monkeypatch):
+    """A user who already exports DRONE_TOKEN should just work."""
+    monkeypatch.setenv("DRONE_TOKEN", "from-drone-token")
+    assert Credentials(DRONE).get_token("default") == "from-drone-token"
+    assert "$DRONE_TOKEN" in Credentials(DRONE).backend_name()
+
+
+def test_our_own_name_beats_the_alias(monkeypatch):
+    """The more specific name is the more deliberate one."""
+    monkeypatch.setenv("DRONE_TOKEN", "ecosystem")
+    monkeypatch.setenv("DRONECLI_TOKEN", "ours")
+    assert Credentials(DRONE).get_token("default") == "ours"
+    assert "$DRONECLI_TOKEN" in Credentials(DRONE).backend_name()
+
+
+def test_alias_overrides_the_keyring_and_says_so(monkeypatch):
+    """The documented hazard: env beats a keyring login, silently.
+
+    We do not invert the precedence (CI depends on env winning) — but
+    backend_name() must name the variable that actually spoke, or the operator
+    is left debugging "why is it using the wrong account?".
+    """
+    c = Credentials(DRONE)
+    c.store_token("default", "from-keyring")
+    monkeypatch.setenv("DRONE_TOKEN", "from-env")
+    assert c.get_token("default") == "from-env"
+    assert c.backend_name() == "environment variable $DRONE_TOKEN"
+
+
+def test_tools_without_aliases_ignore_foreign_vars(monkeypatch):
+    """op-cli declares no aliases, so DRONE_TOKEN must mean nothing to it."""
+    monkeypatch.setenv("DRONE_TOKEN", "not-mine")
+    assert Credentials(OP).get_token("default") is None
+
+
+def test_token_env_names_order():
+    assert DRONE.token_env_names() == ("DRONECLI_TOKEN", "DRONE_TOKEN")
+    assert OP.token_env_names() == ("OPCLI_TOKEN",)
+
+
+def test_empty_env_var_is_not_a_token(monkeypatch):
+    """`export DRONE_TOKEN=` must fall through, not authenticate as ""."""
+    monkeypatch.setenv("DRONE_TOKEN", "")
+    c = Credentials(DRONE)
+    c.store_token("default", "from-keyring")
+    assert c.get_token("default") == "from-keyring"
 
 
 def test_env_token_wins_over_everything(monkeypatch):