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

{base_cli-0.4.0 → base_cli-0.4.2}/.github/workflows/compatibility.yml

@@ -12,6 +12,31 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  typer-matrix:
+    name: Typer ${{ matrix.typer-version }} / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        typer-version: ["0.25.1", "0.26.0", "0.27.1"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install framework and exact Typer line
+        run: |
+          python -m pip install "setuptools<77" "wheel"
+          python -m pip install ".[dev]"
+          python -m pip install --upgrade "typer==${{ matrix.typer-version }}"
+      - name: Install Beacon fixture without dependency resolution
+        run: python -m pip install --no-deps compatibility/consumers/beacon_typer
+      - name: Run adapter and Beacon compatibility tests
+        run: python -m pytest tests/test_typer_adapter.py compatibility/consumers/beacon_typer/tests
+
   downstream:
     name: Install and test independent consumers
     runs-on: ubuntu-latest

base_cli-0.4.2/.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "README.md"
+      - "SECURITY.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "scripts/validate_docs.py"
+      - "tests/validate.sh"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "README.md"
+      - "SECURITY.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "scripts/validate_docs.py"
+      - "tests/validate.sh"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and validate documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Install documentation tools
+        run: python -m pip install ".[docs]"
+
+      - name: Validate repository links and examples
+        run: python scripts/validate_docs.py
+
+      - name: Build documentation with strict warnings
+        run: python -m mkdocs build --strict --site-dir site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: site
+
+  deploy:
+    name: Deploy documentation site
+    if: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main' }}
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e # v4.0.0

{base_cli-0.4.0 → base_cli-0.4.2}/.github/workflows/tests.yml

@@ -41,6 +41,8 @@ jobs:
         run: python -m pytest
       - name: Type-check public contract sample
         run: python -m mypy --strict examples/typed_consumer.py
+      - name: Type-check library
+        run: python -m mypy --strict lib/python/base_cli
 
   quality:
     name: Quality and security gates
@@ -56,11 +58,12 @@ jobs:
         run: python -m pip install ".[dev,typer,quality]"
       - name: Run formatting and lint checks
         run: |
-          ruff format --check scripts examples
+          ruff format --check lib/python/base_cli scripts examples tests
           ruff check lib/python/base_cli scripts examples tests
       - name: Run strict typing and documentation checks
         run: |
           python -m mypy --strict examples/typed_consumer.py
+          python -m mypy --strict lib/python/base_cli
           python scripts/validate_docs.py
           python scripts/benchmark_runtime.py --check
           python -m compileall -q examples

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

@@ -5,6 +5,92 @@ All notable changes to base-cli will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and versions are tracked in the repo-root `VERSION` file.
 
+## [Unreleased]
+
+### Planned
+
+- 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,
+security hardening, correctness fixes, and CI improvements after 0.4.0; it does
+not introduce a new API or JSON-contract compatibility boundary.
+
+### Added
+
+- Add the MkDocs documentation site configuration, strict documentation checks,
+  and GitHub Pages deployment workflow.
+- Add the importable, intentionally empty `base_cli.experimental` namespace for
+  future preview APIs without expanding the stable API surface.
+
+### Changed
+
+- Reclassify the project as Beta in package metadata to reflect its documented
+  API stability policy, compatibility suite, and production-adoption guidance.
+- Add a version, license, install, and release-notes strip to the README and
+  validate it against the repository version contract.
+- Extend the optional Typer adapter through Typer 0.27.x by selecting the
+  command tree's matching public or vendored Click dialect, with a Python 3.10
+  through 3.14 compatibility matrix covering Typer 0.25.1, 0.26.0, and 0.27.1.
+- Document the intentional opaque `Context.user_config` boundary and the
+  compatibility requirements for any future fourth context type parameter.
+
+- Expand CI quality gates with package-level strict mypy coverage, the full Ruff
+  format surface, and the updated benchmark percentile calculation.
+- Improve the public documentation for inspection envelopes, delegated display
+  labels, environment configuration, typed user configuration, Typer access,
+  release guidance, and contributor setup.
+
+### Security
+
+- Compact home-relative paths in diagnostic `run.json` and `identity.json`
+  metadata so retained support bundles disclose less local path information.
+
+### Fixed
+
+- Capture command output consistently when JSON mode is supplied through Click's
+  `default_map` or combined short flags, preserving the single-envelope stdout
+  contract.
+- Preserve every first-seen document column when rendering heterogeneous records
+  instead of silently dropping fields found only in later rows.
+- Compute a real interpolated p95 in the runtime benchmark instead of reporting
+  the maximum under two names.
+- Reject Unicode digit-like input that is not a decimal integer while retaining
+  the friendly positive-integer error message.
+- Reuse one history display-command resolver across contexts, profiles, and
+  history records.
+- Correct release-facing examples, changelog structure, API documentation,
+  contribution guidance, and package-level formatting coverage.
+
 ## [0.4.0] - 2026-08-05
 
 This is a pre-1.0 minor release and therefore a compatibility boundary. See
@@ -53,6 +139,7 @@ the API stability policy and migration guide before upgrading from `0.3.x`.
 
 ### Changed
 
+- Add README health and support badges for CI, downstream consumers, PyPI, and supported Python versions.
 - Normalize command returns, Click errors, aborts, interrupts, `SystemExit`, and
   unexpected exceptions through one core outcome model and clean `run_app()`
   process boundary.
@@ -95,12 +182,6 @@ the API stability policy and migration guide before upgrading from `0.3.x`.
 - Restore Click-native `--option=value` parsing, including redaction of
   sensitive equals-form values.
 
-## [Unreleased]
-
-### Planned
-
-- Continue compatibility hardening and adoption work for the next release.
-
 ## [0.3.0] - 2026-08-01
 
 ### Changed

{base_cli-0.4.0 → base_cli-0.4.2}/CONTRIBUTING.md

@@ -2,6 +2,29 @@
 
 Thank you for improving this project.
 
+Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+## Development setup
+
+The `basectl` shortcuts below are optional. Contributors working outside the
+Base workspace can run the same checks with the project’s standard Python
+tooling:
+
+```bash
+python3 -m pip install -e ".[dev,typer,quality]"
+python3 -m pytest
+ruff format --check scripts examples
+ruff check lib/python/base_cli scripts examples tests
+python3 -m mypy --strict examples/typed_consumer.py
+python3 scripts/validate_docs.py
+python3 -m compileall -q examples
+python3 -m build
+```
+
+Use the Python interpreter from your active virtual environment in place of
+`python3` when necessary. The strict mypy command covers the supported typed
+consumer fixture; the framework-wide typing gate is tracked separately.
+
 ## Workflow
 
 1. Create or choose a GitHub issue before starting implementation work.
@@ -42,6 +65,8 @@ Thank you for improving this project.
 
 Useful commands:
 
+These shortcuts are available to contributors using the Base workspace:
+
 ```bash
 basectl check base-cli
 basectl doctor base-cli

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

@@ -1,13 +1,15 @@
 Metadata-Version: 2.2
 Name: base-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: A small, consumer-neutral Python CLI framework
 Author: Base Foundry
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/basefoundry/base-cli
 Project-URL: Repository, https://github.com/basefoundry/base-cli
 Project-URL: Issues, https://github.com/basefoundry/base-cli/issues
-Classifier: Development Status :: 3 - Alpha
+Project-URL: Documentation, https://basefoundry.github.io/base-cli/
+Project-URL: Code of Conduct, https://github.com/basefoundry/base-cli/blob/main/CODE_OF_CONDUCT.md
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: MacOS
@@ -31,8 +33,9 @@ Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: hypothesis<7,>=6.100; extra == "dev"
 Requires-Dist: mypy<2,>=1.17; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
 Provides-Extra: typer
-Requires-Dist: typer<0.26,>=0.12; extra == "typer"
+Requires-Dist: typer<0.28,>=0.12; extra == "typer"
 Provides-Extra: rich
 Requires-Dist: rich<15,>=13.7; extra == "rich"
 Provides-Extra: telemetry
@@ -43,9 +46,20 @@ Requires-Dist: coverage[toml]<8,>=7.6; extra == "quality"
 Requires-Dist: pip-audit<3,>=2.7; extra == "quality"
 Requires-Dist: pytest-cov<7,>=5; extra == "quality"
 Requires-Dist: ruff<1,>=0.8; extra == "quality"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
 
 # `base-cli`
 
+[![Tests](https://img.shields.io/github/actions/workflow/status/basefoundry/base-cli/tests.yml?branch=main&label=tests)](https://github.com/basefoundry/base-cli/actions/workflows/tests.yml)
+[![Reference consumers](https://img.shields.io/github/actions/workflow/status/basefoundry/base-cli/compatibility.yml?branch=main&label=consumers)](https://github.com/basefoundry/base-cli/actions/workflows/compatibility.yml)
+[![PyPI](https://img.shields.io/pypi/v/base-cli.svg)](https://pypi.org/project/base-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/base-cli.svg)](https://pypi.org/project/base-cli/)
+
+| Version | License | Install | Release notes |
+| --- | --- | --- | --- |
+| `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`.
 
 Install it with:
@@ -54,8 +68,40 @@ Install it with:
 python -m pip install base-cli
 ```
 
+Read the complete documentation at
+<https://basefoundry.github.io/base-cli/>.
+
+## Quick start
+
+Create a small command with a consistent context, logging, and cleanup
+lifecycle:
+
+```python
+from __future__ import annotations
+
+import base_cli
+
+
+app = base_cli.App(name="hello", version="0.1.0")
+
+
+@app.command()
+@base_cli.option("--name", default="world", show_default=True)
+def hello(ctx: base_cli.Context, name: str) -> int:
+    ctx.log.info("greeting %s", name)
+    print(f"Hello, {name}!")
+    return base_cli.ExitCode.SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(base_cli.run_app(app))
+```
+
+Run it with `python hello.py --name Ada`. The full lifecycle and configuration
+options are documented below.
+
 Release builds, TestPyPI rehearsals, and protected PyPI publication are
-documented in [`docs/releasing.md`](docs/releasing.md). The package exposes
+documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/releasing/). The package exposes
 `base_cli.__version__`, which matches the distribution version.
 
 The package is distributed under the Apache License 2.0. Base itself remains
@@ -79,33 +125,33 @@ execution, while `base_cli` provides reusable lifecycle behavior:
 - test helpers built on Click's `CliRunner`
 
 Typer applications can opt into the same lifecycle with the optional
-`base-cli[typer]` extra. See [`docs/typer-adapter.md`](docs/typer-adapter.md)
+`base-cli[typer]` extra. See [`docs/typer-adapter.md`](https://basefoundry.github.io/base-cli/typer-adapter/)
 for the migration path; Typer remains optional and is never imported by the
 core Click integration.
 
 Automation-facing JSON output, errors, and logs are opt-in through the
-versioned contracts documented in [`docs/json-contracts.md`](docs/json-contracts.md).
+versioned contracts documented in [`docs/json-contracts.md`](https://basefoundry.github.io/base-cli/json-contracts/).
 Human output and Click error behavior remain the default.
 
 The supported public facade, compatibility promises, deprecation warning
 mechanism, and migration requirements are documented in
-[`docs/api-stability.md`](docs/api-stability.md) and
-[`docs/migrations.md`](docs/migrations.md).
+[`docs/api-stability.md`](https://basefoundry.github.io/base-cli/api-stability/) and
+[`docs/migrations.md`](https://basefoundry.github.io/base-cli/migrations/).
 
 Security reporting, runtime trust boundaries, threat assumptions, and the
 release security checklist are documented in [`SECURITY.md`](SECURITY.md),
-[`docs/security-threat-model.md`](docs/security-threat-model.md), and
-[`docs/security-review.md`](docs/security-review.md).
+[`docs/security-threat-model.md`](https://basefoundry.github.io/base-cli/security-threat-model/), and
+[`docs/security-review.md`](https://basefoundry.github.io/base-cli/security-review/).
 
 Shared record renderers keep machine output stable: CSV and TSV stream
 one-pass iterables without headers or footers, while terminal tables account
 for Unicode display width and safely truncate oversized cells. See
-[`docs/output-contracts.md`](docs/output-contracts.md) for the output rules and
+[`docs/output-contracts.md`](https://basefoundry.github.io/base-cli/output-contracts/) for the output rules and
 deterministic width controls.
 
 Optional Rich tables and OpenTelemetry lifecycle spans are available through
 separate extras; they are never imported or required by the default install.
-See [`docs/integrations.md`](docs/integrations.md) for opt-in configuration and
+See [`docs/integrations.md`](https://basefoundry.github.io/base-cli/integrations/) for opt-in configuration and
 graceful-degradation behavior.
 
 ## Design Goals
@@ -149,7 +195,7 @@ The generic profile has no manifest filename convention, no product-owned
 configuration directory, and no implicit history writer. Applications can
 provide those policies through callbacks or build their own profile. The
 consumer-owned adapters should supply any product-specific policies. See
-[`docs/consumer-profiles.md`](docs/consumer-profiles.md) for the boundary and
+[`docs/consumer-profiles.md`](https://basefoundry.github.io/base-cli/consumer-profiles/) for the boundary and
 migration guidance.
 
 ### Typed extension contracts
@@ -198,7 +244,7 @@ can opt into `base_cli.ExtensionDiscovery`. It recognizes the documented
 `base_cli.commands`, `base_cli.profiles`, and `base_cli.plugins` entry-point
 groups. Discovery is lazy and cached, duplicate names fail explicitly, broken
 extensions are isolated by `load_all()`, and consumers can disable discovery or
-provide an allowlist. See [`docs/extensions.md`](docs/extensions.md) for the
+provide an allowlist. See [`docs/extensions.md`](https://basefoundry.github.io/base-cli/extensions/) for the
 entry-point contracts and deterministic ordering rules.
 
 ## Public API
@@ -207,6 +253,8 @@ The supported facade is `import base_cli`. It exports the command lifecycle
 (`App`, `Context`, `run_app`, decorators, and logging helpers), command filters,
 and the structured command protocol helpers. Consumer-owned user configuration
 is passed through `Context.user_config`; the library does not impose a schema.
+See [`docs/user-config-typing.md`](https://basefoundry.github.io/base-cli/user-config-typing/) for the
+intentional opaque boundary and the recommended typed accessor pattern.
 The corresponding modules are also available as
 `base_cli.command_filters`, `base_cli.command_protocol`, and
 `base_cli.history`.
@@ -236,7 +284,7 @@ Typer, and automation/observability flows; each example has its own packaging,
 tests, completion, release, and troubleshooting guidance.
 
 Teams evaluating adoption can follow the [adopter readiness and migration
-guide](docs/adopter-readiness.md) and run the three independent
+guide](https://basefoundry.github.io/base-cli/adopter-readiness/) and run the three independent
 [downstream compatibility consumers](compatibility/README.md).
 
 ## Minimal Command
@@ -544,7 +592,7 @@ Every `base_cli.App` command gets these options:
 - `--log-file <path>`: write the persistent log to a specific file.
 - `--version`: shown when the `App` was created with a version.
 - `--json`: opt-in machine output, when `LifecycleOptions.json` is enabled;
-  emits the versioned envelopes described in [`docs/json-contracts.md`](docs/json-contracts.md).
+  emits the versioned envelopes described in [`docs/json-contracts.md`](https://basefoundry.github.io/base-cli/json-contracts/).
 
 `LifecycleOptions()` preserves this default set. Its `debug`, `quiet`,
 `environment`, `config`, `keep_temp`, `log_file`, and `version` fields are
@@ -865,7 +913,7 @@ available as a compatibility per-file policy; new applications should use
 Logs use a stable, human-readable shape:
 
 ```text
-2026-05-26 12:34:56 INFO    path/to/file.py:42 message
+2026-05-26 12:34:56 -0700 INFO    path/to/file.py:42 message
 ```
 
 Use either `ctx.log` directly:
@@ -992,7 +1040,7 @@ On POSIX, base-cli enforces owner-only `0600`/`0700` modes. On Windows, the
 default user-local cache root relies on inherited user-profile ACLs; consumers
 using a custom cache root must provide the appropriate ACL themselves.
 
-See [Platform support](docs/platform-support.md) for the supported Linux,
+See [Platform support](https://basefoundry.github.io/base-cli/platform-support/) for the supported Linux,
 WSL2, macOS, and native Windows boundaries. Native Windows support covers the
 generic `base-cli` framework; it does not imply native Windows support for
 Base or `basectl`.