base-cli 0.4.1__tar.gz → 0.4.2__tar.gz

{base_cli-0.4.1 → base_cli-0.4.2}/CHANGELOG.md

@@ -11,6 +11,34 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Continue compatibility hardening and adoption work for the next release.
 
+## [0.4.2] - 2026-08-08
+
+This is a compatible pre-1.0 patch release. It contains correctness fixes,
+security hardening, documentation improvements, and adoption polish after
+0.4.1; it does not introduce a new API or JSON-contract compatibility
+boundary.
+
+### Changed
+
+- Apply the profile-resolved display command to ambient production invocation
+  metadata so logs and history match the documented wrapper-label contract.
+
+### Security
+
+- Compact the launcher path in retained invocation logs so diagnostic bundles
+  do not disclose the local user's home directory or username.
+
+### Fixed
+
+- Fix the published documentation link to the reference applications.
+- Classify a command that returns exit code `130` as `nonzero_return`; the
+  `interrupted` outcome remains reserved for actual interrupt exceptions.
+
+### Documentation
+
+- Document the exported history, command-protocol, and context APIs and enforce
+  public-symbol docstrings in the API tests.
+
 ## [0.4.1] - 2026-08-07
 
 This is a compatible pre-1.0 patch release. It contains adoption polish,

{base_cli-0.4.1 → base_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: base-cli
-Version: 0.4.1
+Version: 0.4.2
 Summary: A small, consumer-neutral Python CLI framework
 Author: Base Foundry
 License: Apache-2.0
@@ -58,7 +58,7 @@ Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.1](https://github.com/basefoundry/base-cli/releases/tag/v0.4.1) |
+| `0.4.2` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.2](https://github.com/basefoundry/base-cli/releases/tag/v0.4.2) |
 
 `base-cli` is the PyPI distribution; import it in Python as `base_cli`.
 

{base_cli-0.4.1 → base_cli-0.4.2}/README.md

@@ -7,7 +7,7 @@
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.1](https://github.com/basefoundry/base-cli/releases/tag/v0.4.1) |
+| `0.4.2` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.2](https://github.com/basefoundry/base-cli/releases/tag/v0.4.2) |
 
 `base-cli` is the PyPI distribution; import it in Python as `base_cli`.
 

base_cli-0.4.2/VERSION

@@ -0,0 +1 @@
+0.4.2

{base_cli-0.4.1 → base_cli-0.4.2}/docs/index.md

@@ -71,6 +71,7 @@ Continue with the framework guides:
 
 - [API overview](api-stability.md) for the supported public surface and
   compatibility policy.
-- [Reference applications](../examples/) for complete consumer patterns.
+- [Reference applications](https://github.com/basefoundry/base-cli/tree/main/examples)
+  for complete consumer patterns.
 - [Installation and packaging](adopter-readiness.md) for dependency extras,
   distribution checks, and release guidance.

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/_lifecycle.py

@@ -116,8 +116,6 @@ def outcome_from_exit_code(exit_code: int) -> InvocationOutcome:
         return InvocationOutcome("success", "ok", exit_code)
     if exit_code == ExitCode.USAGE_ERROR:
         return InvocationOutcome("usage_error", "error", exit_code)
-    if exit_code == ExitCode.INTERRUPTED:
-        return InvocationOutcome("interrupted", "error", exit_code)
     return InvocationOutcome("nonzero_return", "error", exit_code)
 
 

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/app.py

@@ -2740,7 +2740,6 @@ def run_app(
         print(f"ERROR: {exc}", file=sys.stderr)
         return ExitCode.FAILURE
 
-    explicit_argv = argv is not None
     args = list(sys.argv[1:] if argv is None else argv)
     leading_debug, leading_quiet = _leading_output_flags(
         args,
@@ -2760,7 +2759,7 @@ def run_app(
     try:
         try:
             display_command = app.profile.display_command()
-            invocation_argv = _effective_invocation_argv(app, args, explicit_argv, display_command)
+            invocation_argv = _effective_invocation_argv(app, args, display_command)
             command = app.click_command
             click = dialect_for_command(command)
             invocation_token = _INVOCATION_ARGV.set(invocation_argv)
@@ -3038,11 +3037,8 @@ def _leading_output_flags(
 def _effective_invocation_argv(
     app: App,
     args: list[str],
-    explicit_argv: bool,
     display_command: str | None,
 ) -> list[str]:
-    if not explicit_argv:
-        return list(sys.argv)
     return [display_command or app.name, *args]
 
 

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/command_protocol.py

@@ -26,11 +26,15 @@ MAX_RECORD_COUNT = 1_000_000
 
 
 class CommandProtocolError(ValueError):
+    """Raised when a command-protocol schema or payload violates its contract."""
+
     pass
 
 
 @dataclass(frozen=True)
 class FieldSpec:
+    """Describe the wire type and nullability of one command-record field."""
+
     value_type: str
     nullable: bool = False
 
@@ -138,6 +142,7 @@ def dumps_record(
     protocol_header: str = PROTOCOL_HEADER,
     registry: CommandSchemaRegistry | None = None,
 ) -> str:
+    """Serialize one typed command record using the protocol framing."""
     return dumps_records(
         record_type,
         (record,),
@@ -153,6 +158,7 @@ def dumps_records(
     protocol_header: str = PROTOCOL_HEADER,
     registry: CommandSchemaRegistry | None = None,
 ) -> str:
+    """Serialize a sequence of typed command records using the protocol framing."""
     active_registry = registry or DEFAULT_SCHEMA_REGISTRY
     schema = active_registry.schema(record_type)
     if len(records) > MAX_RECORD_COUNT:
@@ -180,6 +186,7 @@ def loads_records(
     protocol_header: str = PROTOCOL_HEADER,
     registry: CommandSchemaRegistry | None = None,
 ) -> tuple[str, tuple[dict[str, RecordValue], ...]]:
+    """Validate and decode protocol-framed command records."""
     active_registry = registry or DEFAULT_SCHEMA_REGISTRY
     # The wire framing is LF-delimited. `str.splitlines()` also accepts CR,
     # vertical tab, form feed, and Unicode separators, which would make the

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/context.py

@@ -167,10 +167,12 @@ class Context(Generic[ConfigT, ApplicationStateT, ServicesT]):
 def set_current_context(
     context: Context[Any, Any, Any] | None,
 ) -> contextvars.Token[Context[Any, Any, Any] | None]:
+    """Set the active context and return a token that can restore the prior value."""
     return _current_context.set(context)
 
 
 def reset_current_context(token: contextvars.Token[Context[Any, Any, Any] | None]) -> None:
+    """Restore the context associated with a token, recovering safely if needed."""
     try:
         _current_context.reset(token)
     except BaseException:  # pylint: disable=broad-exception-caught
@@ -178,11 +180,13 @@ def reset_current_context(token: contextvars.Token[Context[Any, Any, Any] | None
 
 
 def recover_current_context(token: contextvars.Token[Context[Any, Any, Any] | None]) -> None:
+    """Best-effort restoration used when normal context-token reset fails."""
     previous = token.old_value
     _current_context.set(None if previous is contextvars.Token.MISSING else previous)
 
 
 def get_current_context() -> Context[Any, Any, Any]:
+    """Return the active command context or raise when called outside a command."""
     context = _current_context.get()
     if context is None:
         raise RuntimeError("base_cli context is not active. Run inside a base_cli.App command.")

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/history.py

@@ -52,6 +52,7 @@ HISTORY_SCOPE_INTERNAL = "internal"
 
 
 def utc_now() -> datetime:
+    """Return the current time as a timezone-aware UTC datetime."""
     return datetime.now(timezone.utc)
 
 
@@ -62,6 +63,7 @@ def build_finished_record(
     started_at: datetime,
     exit_code: int,
 ) -> dict[str, Any]:
+    """Build a redacted finished-invocation record from an active context."""
     ended_at = utc_now()
     safe_argv = redact_history_argv(argv, sensitive_options)
     record: dict[str, Any] = {
@@ -248,20 +250,24 @@ def write_all(fd: int, data: bytes) -> None:
 
 
 def format_timestamp(value: datetime) -> str:
+    """Format a datetime as a second-precision UTC ISO-8601 timestamp."""
     normalized = value.astimezone(timezone.utc)
     return normalized.isoformat(timespec="seconds").replace("+00:00", "Z")
 
 
 def duration_ms(started_at: datetime, ended_at: datetime) -> int:
+    """Return the non-negative elapsed duration between two datetimes in milliseconds."""
     return max(0, round((ended_at - started_at).total_seconds() * 1000))
 
 
 def display_command(cli_name: str, argv: list[str]) -> str:
+    """Return the stable, human-readable command label used in history."""
     del argv
     return cli_name.replace("_", "-")
 
 
 def parse_positive_int(option: str, value: str) -> int:
+    """Parse a decimal option value and require it to be greater than zero."""
     if not value.isdecimal():
         raise ValueError(f"Option '{option}' must be a positive integer.")
     amount = int(value)
@@ -271,6 +277,7 @@ def parse_positive_int(option: str, value: str) -> int:
 
 
 def parse_finished_history_record_line(line: str) -> dict[str, Any] | None:
+    """Decode a line when it is a valid finished record for this schema version."""
     try:
         payload = json.loads(line)
     except json.JSONDecodeError:
@@ -283,10 +290,12 @@ def parse_finished_history_record_line(line: str) -> dict[str, Any] | None:
 
 
 def optional_string(value: Any) -> str | None:
+    """Return a non-empty string value, or ``None`` for other values."""
     return value if isinstance(value, str) and value else None
 
 
 def optional_int(value: Any) -> int | None:
+    """Return an integer value, or ``None`` when the value has another type."""
     return value if isinstance(value, int) else None
 
 
@@ -304,10 +313,12 @@ def current_shell() -> str | None:
 
 
 def redact_history_argv(argv: list[str], sensitive_options: set[str]) -> list[str]:
+    """Redact sensitive arguments and compact home paths for history storage."""
     return [redact_history_text(arg) for arg in redact_argv(argv, sensitive_options)]
 
 
 def redact_history_text(value: str) -> str:
+    """Redact sensitive option values and compact home paths in text."""
     key, separator, _value = value.partition("=")
     if separator and is_secret_key(option_name_to_parameter(key)):
         return f"{key}={REDACTED}"
@@ -315,16 +326,19 @@ def redact_history_text(value: str) -> str:
 
 
 def compact_optional_path(path: Path | None, *, home: Path | str | None = None) -> str | None:
+    """Return a compact path string, preserving ``None`` for absent paths."""
     if path is None:
         return None
     return compact_path(path, home=home)
 
 
 def compact_path(path: Path, *, home: Path | str | None = None) -> str:
+    """Resolve a path and replace the user's home directory with ``~``."""
     return compact_home_text(str(path.expanduser().resolve(strict=False)), home=home)
 
 
 def compact_home_text(value: str, *, home: Path | str | None = None) -> str:
+    """Replace a home-directory prefix in text with the portable ``~`` marker."""
     home_text = str(home) if home is not None else str(Path.home().expanduser().resolve(strict=False))
     normalized_value = value.replace("\\", "/")
     normalized_home = home_text.replace("\\", "/").rstrip("/")

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli/logging.py

@@ -21,6 +21,7 @@ except ImportError:  # pragma: no cover - msvcrt is unavailable outside Windows.
 
 from ._private_files import restrict_file
 from .context import get_current_context
+from .history import compact_home_text
 from .json_contracts import JsonLogFormatter
 from .paths import current_working_dir
 from .redaction import redact_argv
@@ -261,6 +262,11 @@ def log_invocation(
     sensitive_options: set[str] | None,
 ) -> None:
     safe_argv = list(argv) if sensitive_options is None else redact_argv(argv, sensitive_options)
+    if safe_argv:
+        # Invocation logs are retained in diagnostic bundles.  Keep the
+        # launcher path useful while avoiding disclosure of the local user's
+        # home directory and username.
+        safe_argv[0] = compact_home_text(safe_argv[0])
     logger.debug("argv=%s", safe_argv)
     logger.debug("platform=%s %s", platform.system(), platform.machine())
     logger.debug("python=%s", sys.version.replace("\n", " "))

{base_cli-0.4.1 → base_cli-0.4.2}/lib/python/base_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: base-cli
-Version: 0.4.1
+Version: 0.4.2
 Summary: A small, consumer-neutral Python CLI framework
 Author: Base Foundry
 License: Apache-2.0
@@ -58,7 +58,7 @@ Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.1](https://github.com/basefoundry/base-cli/releases/tag/v0.4.1) |
+| `0.4.2` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.2](https://github.com/basefoundry/base-cli/releases/tag/v0.4.2) |
 
 `base-cli` is the PyPI distribution; import it in Python as `base_cli`.
 

{base_cli-0.4.1 → base_cli-0.4.2}/tests/test_app_run_metadata.py

@@ -84,6 +84,7 @@ class AppRunMetadataTests(unittest.TestCase):
             ("zero", 0, 0, "ok", "success"),
             ("usage", 2, 2, "error", "usage_error"),
             ("nonzero", 7, 7, "error", "nonzero_return"),
+            ("returned-interrupted", 130, 130, "error", "nonzero_return"),
         )
         for name, returned, expected_code, expected_status, expected_outcome in cases:
             with self.subTest(name=name), tempfile.TemporaryDirectory() as tmpdir:
@@ -237,6 +238,7 @@ class AppRunMetadataTests(unittest.TestCase):
 
         cases = (
             ("click", click.exceptions.Exit(9), 9, "error", "nonzero_return", ""),
+            ("click-interrupted-code", click.exceptions.Exit(130), 130, "error", "nonzero_return", ""),
             ("system-none", SystemExit(None), 0, "ok", "system_exit", ""),
             ("system-success", SystemExit(0), 0, "ok", "system_exit", ""),
             ("system-failure", SystemExit(5), 5, "error", "system_exit", ""),

{base_cli-0.4.1 → base_cli-0.4.2}/tests/test_invocation_parity.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from unittest import mock
 
 import base_cli
+import base_cli.app as app_module
 from base_cli.testing import invoke
 
 
@@ -125,7 +126,7 @@ def _load_run_artifacts(home: Path) -> tuple[dict[str, object], list[str], str]:
     return metadata, logged_argv, log_text
 
 
-def _observe_production(app: base_cli.App, args: list[str], home: Path) -> _Observation:
+def _observe_production(app: base_cli.App, args: list[str] | None, home: Path) -> _Observation:
     stdout = io.StringIO()
     stderr = io.StringIO()
     with mock.patch.dict(os.environ, _isolated_environment(home)), redirect_stdout(stdout), redirect_stderr(stderr):
@@ -171,6 +172,62 @@ def _stable_stderr(observation: _Observation) -> str:
 
 @unittest.skipUnless(importlib.util.find_spec("click"), "Click is not installed")
 class InvocationParityTests(unittest.TestCase):
+    def test_ambient_invocation_uses_display_command_in_logs_and_history(self) -> None:
+        observed_history_argv: list[str] = []
+
+        def history_writer(
+            _ctx: base_cli.Context,
+            argv: list[str],
+            _sensitive: set[str],
+            _started: object,
+            _exit_code: int,
+        ) -> None:
+            observed_history_argv.extend(argv)
+
+        profile = replace(_profile(), history_writer=history_writer)
+        app = base_cli.App(name="internal-tool", profile=profile)
+
+        @app.command()
+        @base_cli.option("--name", required=True)
+        def main(ctx: base_cli.Context, name: str) -> None:
+            del ctx
+            print(f"hello {name}")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            home = (Path(tmpdir) / "home").resolve()
+            home.mkdir()
+            launcher = home / ".venv" / "bin" / "internal-tool"
+            with mock.patch.object(app_module.sys, "argv", [str(launcher), "--name=Ada"]):
+                observation = _observe_production(app, None, home)
+
+        expected_argv = ["parity-tool", "--name=Ada"]
+        self.assertEqual(observation.logged_argv, expected_argv)
+        self.assertEqual(observed_history_argv, expected_argv)
+        self.assertNotIn(str(home), observation.log_text)
+
+    def test_production_compacts_launcher_home_path_in_retained_log(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            home = (Path(tmpdir) / "home").resolve()
+            home.mkdir()
+            launcher = home / ".venv" / "bin" / "parity-tool"
+            profile = replace(
+                base_cli.CliProfile.generic(),
+                display_command=lambda: str(launcher),
+            )
+            app = base_cli.App(name="parity-tool", profile=profile)
+
+            @app.command()
+            @base_cli.option("--name", required=True)
+            def main(ctx: base_cli.Context, name: str) -> None:
+                del ctx
+                print(f"hello {name}")
+
+            with mock.patch.object(app_module.sys, "argv", [str(launcher), "--name=Ada"]):
+                observation = _observe_production(app, None, home)
+
+        self.assertEqual(observation.logged_argv[0], "~/.venv/bin/parity-tool")
+        self.assertNotIn(str(home), observation.log_text)
+
     def test_production_and_testing_match_parser_usage_errors_without_bundles(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             root = Path(tmpdir)

{base_cli-0.4.1 → base_cli-0.4.2}/tests/test_public_api.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import inspect
 import tempfile
 import unittest
 from pathlib import Path
@@ -11,6 +12,7 @@ from base_cli import (
     command_filters,
     command_protocol,
     config,
+    context,
     deprecations,
     experimental,
     history,
@@ -173,6 +175,15 @@ class PublicApiTests(unittest.TestCase):
         self.assertTrue(base_cli.get_command_app.__doc__)
         self.assertTrue(base_cli.run_app.__doc__)
 
+    def test_exported_callables_have_docstrings(self) -> None:
+        for module in (history, command_protocol, context):
+            for name in module.__all__:
+                exported = getattr(module, name)
+                if not (inspect.isclass(exported) or inspect.isfunction(exported)):
+                    continue
+                with self.subTest(module=module.__name__, name=name):
+                    self.assertTrue(inspect.getdoc(exported), f"{module.__name__}.{name} needs a docstring")
+
 
 if __name__ == "__main__":
     unittest.main()

base_cli-0.4.1/VERSION

@@ -1 +0,0 @@
-0.4.1