Address PR psss#469 review from @kwk

- List `token_command` in the gitlab and jira config examples, next
  to the `token` and `token_file` entries that were already there
- Clarify that the token command inherits did's environment (so
  `BW_SESSION` and friends work) and only loses shell expansion
- Include the command line in the `FileNotFoundError` and
  `CalledProcessError` messages, matching the timeout message
- Document why caching the token for the process lifetime does not
  widen exposure of the secret
- Reword a test comment that read as a typo

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ammachado

did/base.py

@@ -554,16 +554,22 @@ def _run_token_command(command: str) -> str:
     """
     Run `command` and return its stripped stdout.
 
-    The command line is parsed with `shlex.split` and executed without
-    a shell, so config files cannot inject shell metacharacters. A
-    30-second timeout protects against secret managers that block on
-    interactive prompts (e.g. an expired ``op`` session). Non-zero
-    exit, missing binary or timeout each raise `ConfigError`; stdout
-    is never logged because it is the secret.
-
-    Results are memoized for the lifetime of the process so that
+    The command line is parsed with `shlex.split` and executed
+    directly, without a shell, so config files cannot inject shell
+    metacharacters. The command inherits the environment of `did`
+    (so variables such as ``BW_SESSION`` are visible to it) but gets
+    no shell expansion. A 30-second timeout protects against secret
+    managers that block on interactive prompts (e.g. an expired ``op``
+    session). Non-zero exit, missing binary or timeout each raise
+    `ConfigError`; stdout is never logged because it is the secret.
+
+    Results are cached for the lifetime of the process so that
     multiple config sections sharing the same command string only
-    invoke the external tool once per run. Failures are not cached.
+    invoke the external tool once per run. This does not widen the
+    exposure of the secret: `did` is a short-lived command and the
+    token is already held in memory by every caller of `get_token`.
+    Nothing is written to disk and the cache dies with the process.
+    Failures are not cached, so a transient error can be retried.
     """
     try:
         result = subprocess.run(
@@ -573,14 +579,14 @@ def _run_token_command(command: str) -> str:
             )
     except FileNotFoundError as exc:
         raise ConfigError(
-            f"Token command not found: {exc.filename}") from exc
+            f"Token command not found: {exc.filename}: {command}") from exc
     except subprocess.TimeoutExpired as exc:
         raise ConfigError(
             f"Token command timed out after {exc.timeout}s: {command}"
             ) from exc
     except subprocess.CalledProcessError as exc:
         raise ConfigError(
-            f"Token command failed (exit {exc.returncode}): "
+            f"Token command failed (exit {exc.returncode}): {command}: "
             f"{exc.stderr.strip()}") from exc
     return result.stdout.strip()
 

did/plugins/gitlab.py

@@ -8,6 +8,7 @@
     url = https://gitlab.com/
     token = <authentication-token>
     token_file = <authentication-token-file>
+    token_command = <command-to-fetch-token>
     login = <username>
     ssl_verify = true
 

did/plugins/jira.py

@@ -9,6 +9,7 @@
     url = https://issues.redhat.com/
     auth_type = token
     token_file = ~/.did/jira_api_token
+    token_command = <command-to-fetch-token>
     token_expiration = 7
     token_name = did-token
 
@@ -27,7 +28,11 @@
     Shell-style command line whose stdout is used as the token, e.g.
     ``bw get password did-jira`` or
     ``op read op://Personal/Jira/token``. The command is parsed with
-    ``shlex`` and executed without a shell.
+    ``shlex`` and executed directly, without a shell. It inherits the
+    environment of ``did``, so variables such as ``BW_SESSION`` are
+    visible to it, but there is no shell expansion: pipes, redirects,
+    ``$VAR`` substitution and globs are not interpreted. Wrap the
+    command in ``sh -c '...'`` if you need any of those.
 
 token_expiration
     Print warning if token with provided ``token_name`` expires within

tests/unit/test_base.py

@@ -306,7 +306,7 @@ class TestGetToken(unittest.TestCase):
     """ Tests for the `get_token` function """
 
     def setUp(self) -> None:
-        # Clear the per-process token-command cache so memoized results
+        # Clear the per-process token-command cache so cached results
         # from previous tests do not bleed into this one.
         # pylint: disable=protected-access
         did.base._run_token_command.cache_clear()