release: v0.11.0 — docs consolidation + PyPI restoration

Doc-only release. No source code changes. Three deliverables:

1. Per-version release notes for v0.5.0 through v0.10.0
   (docs/release-notes/v0.{5,6,7,7.1,8,9,10}.0.md). Previously
   only v0.2.0 had one. v0.7.1 is a thin stub pointing at v0.7.0
   (the surface those two share). docs/README.md release-notes
   index re-sorted newest-first.

2. PyPI publish job restored in .github/workflows/release.yml
   after sitting deferred since the v0.5.0 invalid-publisher
   incident. Uses pypa/gh-action-pypi-publish with OIDC trusted
   publishing — runs in parallel with github-release after build,
   so a PyPI outage doesn't block the GitHub Release upload (and
   vice versa). Stages wheel + sdist into dist-pypi/ so the SBOM
   JSON (which PyPI rejects) stays out of the upload.

   docs/release.md gained a "PyPI trusted-publisher setup" section
   walking through the one-time PyPI + GitHub Environment config.
   If either side is missing, publish-pypi fails with
   invalid-publisher but github-release still succeeds.

3. docs/architecture.md refreshed:
   - core/ listing now includes docker.py (v0.5), host_service.py
     (v0.9), version.py (eight detectors as of v0.8)
   - tools/ listing extended with the eight new tools shipped
     since v0.4 (ports, hosts, ssh, env, gpg, logs, db, stack,
     web/nginx, cron, tls, framework)
   - Added an "Adding a new tool" guidance block: which primitive
     to reach for by tool kind (CommandRunner / DockerEnv /
     HostService / atomic-write), sub-app parent convention
     (framework laravel, web nginx).

CHANGELOG entries for previous releases are unchanged — this
is append-only.

Gates: pytest 1027 passed, ruff clean, mypy strict clean.

The publish-pypi job will fail on this release's tag UNLESS the
trusted-publisher prerequisites in docs/release.md are completed
on PyPI first. github-release will still succeed regardless.

Author: imanimanyara

.github/workflows/release.yml

@@ -74,13 +74,50 @@ jobs:
           name: dist
           path: dist/
 
-  # PyPI publishing is deliberately disabled. Distribution for v0.2.x
-  # is via the GitHub Release page's wheel + sdist. To re-enable PyPI,
-  # restore the publish-pypi + bump-homebrew-tap jobs from git history
-  # and configure trusted publishing at
-  # https://pypi.org/manage/account/publishing/ (Owner=simtabi,
-  # Repository=shimkit, Workflow=release.yml, Environment=pypi,
-  # PyPI Project Name=shimkit).
+  # PyPI publishing — restored in v0.11.0 after sitting deferred from
+  # v0.5.0 through v0.10.0 (six releases shipped to GitHub Releases
+  # only). The job runs in the `pypi` GitHub Environment so trusted
+  # publishing (OIDC) can sign the upload without long-lived tokens.
+  #
+  # PREREQUISITES (one-time, on the user's side):
+  #   1. https://pypi.org/manage/account/publishing/ → add a pending
+  #      publisher: Owner=simtabi, Repository=shimkit,
+  #      Workflow=release.yml, Environment=pypi,
+  #      PyPI Project Name=shimkit
+  #   2. GitHub repo Settings → Environments → New environment "pypi".
+  #      No secrets required; OIDC provides credentials at runtime.
+  #
+  # If either step is missing the upload fails with `invalid-publisher`.
+  # See docs/release.md for the full restoration recipe.
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Stage wheel + sdist only for PyPI
+        # The SBOM lives in dist/ for GitHub Release upload but PyPI
+        # rejects unknown artifacts. Copy just *.whl + *.tar.gz into
+        # a separate dir.
+        run: |
+          mkdir -p dist-pypi
+          cp dist/*.whl dist-pypi/
+          cp dist/*.tar.gz dist-pypi/
+          ls -la dist-pypi/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-pypi/
+          # We already attest provenance in the build job above.
+          attestations: false
+          # Re-runs against an existing tag (workflow_dispatch path)
+          # would otherwise fail when the version is already on PyPI.
+          skip-existing: true
 
   github-release:
     needs: build

CHANGELOG.md

@@ -6,6 +6,41 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-05-15
+
+### Added
+
+- `docs/release-notes/v0.5.0.md` through `v0.10.0.md` — per-version
+  user-facing release notes. Previously only v0.2.0 had one.
+  v0.7.1 has a thin stub pointing at v0.7.0.
+- `docs/release.md` — PyPI trusted-publisher setup section
+  (one-time, by a maintainer with PyPI write access).
+
+### Changed
+
+- `.github/workflows/release.yml` — restored the `publish-pypi`
+  job using `pypa/gh-action-pypi-publish` with OIDC trusted
+  publishing. Runs in parallel with `github-release` after `build`
+  so a PyPI outage doesn't block the GitHub Release. Stages
+  wheel + sdist into `dist-pypi/` so the SBOM JSON (which PyPI
+  rejects) stays out of the upload.
+- `docs/architecture.md` — extended the `core/` directory listing
+  with `docker.py`, `host_service.py`, `version.py` (added across
+  v0.5-v0.9). Extended the `tools/` listing with the eight new
+  tools shipped since v0.4. Added an "Adding a new tool" guidance
+  block: which primitive to reach for by tool kind, sub-app
+  parent convention (framework laravel, web nginx).
+- `docs/README.md` — release-notes index lists v0.10 → v0.5.0
+  newest-first plus the v0.7.1 patch.
+
+### Notes
+
+This is a **doc-only release**. No source code changes. PyPI
+publishing for v0.11.0 itself requires the user to complete the
+trusted-publisher setup on PyPI first (see `docs/release.md`);
+the workflow will succeed for `github-release` and fail at
+`publish-pypi` with `invalid-publisher` otherwise.
+
 ## [0.10.0] — 2026-05-15
 
 ### Tests

docs/README.md

@@ -61,8 +61,27 @@ Top-level utilities (not tools):
 
 ## Release notes
 
-Per-version, user-facing summaries:
-
+Per-version, user-facing summaries (newest first):
+
+- **[`v0.10.0`](release-notes/v0.10.0.md)** — coverage push 74% → 85%
+  (+397 tests). No code changes.
+- **[`v0.9.0`](release-notes/v0.9.0.md)** — `shimkit db --on-host`
+  for mysql/mariadb/postgres. Manages existing host installs;
+  refuses to install packages (the audit-completion bit).
+- **[`v0.8.0`](release-notes/v0.8.0.md)** — `shimkit tls` (certbot
+  container-first cert lifecycle). State at
+  `~/.shimkit/data/tls/`; webroot ACME; daily renewal cron.
+- **[`v0.7.1`](release-notes/v0.7.1.md)** — version-drift recovery
+  for v0.7.0.
+- **[`v0.7.0`](release-notes/v0.7.0.md)** — `shimkit framework
+  laravel` (perms / env / cron-install / artisan). First framework
+  recipe under the new `framework` parent.
+- **[`v0.6.0`](release-notes/v0.6.0.md)** — `shimkit cron` (generic
+  user-crontab editor). Atomic write + backup-on-mutate.
+- **[`v0.5.0`](release-notes/v0.5.0.md)** — ubuntu/ migration:
+  three new sub-trees (`db`/`stack`/`web`), two new core
+  primitives (`core/docker`, `core/version`), 152 new tests. Five
+  Critical audit flags dissolved by Docker-first design.
 - **[`v0.2.0`](release-notes/v0.2.0.md)** — three new tools (`dns`,
   `adguard`, `docker-clean`); uniform CLI surface across all new
   subcommands; argv-list PM templates; container hardening + SBOM

docs/architecture.md

@@ -12,7 +12,9 @@ non-interactive methods, optional menu loop, Typer commands.
 >   pre-v0.5.0 snapshot.
 > - [`architecture-target.md`](../.design/architecture-target.md) —
 >   v0.5.0 layout with the new `db` / `stack` / `web` sub-trees and
->   the two new core primitives (`core/version`, `core/docker`).
+>   two new core primitives (`core/version`, `core/docker`). v0.6+
+>   additions (cron, framework, tls, host_service) follow the same
+>   patterns and slot into the same tree.
 > - [`version-constraints-spec.md`](../.design/version-constraints-spec.md) —
 >   how tool-version checks work.
 
@@ -46,12 +48,41 @@ src/shimkit/
     cli_flags.py      Shared Typer Option defaults so every tool's
                       subcommands have identical --dry-run/--json/
                       --quiet/--verbose/--log-file/--timeout semantics
+    docker.py         DockerEnv — single chokepoint for the docker-py
+                      SDK. Standardises container naming
+                      (shimkit-<scope>-<kind>-<id>) + volume layout.
+                      Refuses deletion outside ~/.shimkit/data/.
+                      Added in v0.5.0; gained run_oneshot() in v0.8.0.
+    host_service.py   HostService — cross-platform service-manager
+                      facade. SystemdHost (Linux) + BrewServicesHost
+                      (macOS). Added in v0.9.0 for `shimkit db
+                      --on-host`; available to any future tool that
+                      manages host daemons.
+    version.py        Tool-version detection + constraint enforcement.
+                      One source of truth (tools.versions registry)
+                      consulted at three points: install docs, runtime
+                      preflight, `shimkit doctor`. Eight built-in
+                      detectors: docker, nginx, git, gpg, python,
+                      php (v0.7), openssl (v0.8).
   tools/
     java/             OpenJDK manager (macOS + Linux)
-    shell/            Shell upgrader (bash/zsh/fish/ksh)
+    shell/            Shell upgrader (bash/zsh/fish/ksh) + colors
     dns/              macOS DNS resolver recovery (port of fixdns.sh)
     adguard/          AdGuard Home port-conflict fixer (Linux)
     docker_clean/     Docker resource cleanup (Linux + macOS + WSL)
+    ports/            TCP/UDP port owner lookup + kill (v0.3.0)
+    hosts/            /etc/hosts editor with atomic write (v0.3.0)
+    ssh/              SSH keys + agent + perms hygiene (v0.3.0)
+    env/              .env viewer + scaffolder, secret redaction (v0.4.0)
+    gpg/              GPG keys + git-signing config (v0.4.0)
+    logs/             System log tail/grep (macOS + Linux) (v0.4.0)
+    db/               Container-first databases (5 engines) (v0.5.0)
+                      + --on-host mode (v0.9.0)
+    stack/            Multi-container app recipes (LEMP today) (v0.5.0)
+    web/nginx/        Hardened nginx vhost generator (v0.5.0)
+    cron/             Generic user-crontab editor (v0.6.0)
+    tls/              TLS cert lifecycle via certbot container (v0.8.0)
+    framework/        Framework-specific helpers (Laravel today) (v0.7.0)
 ```
 
 ## The five load-bearing rules
@@ -220,6 +251,37 @@ ShimkitConfig instance (frozen pydantic v2)
    - CLI `--help` lists subcommands
    - At least one subcommand's exit-code contract
 5. Add `docs/tools/<name>.md` and link it from `docs/README.md`.
+6. Add a CHANGELOG entry under `[Unreleased]`.
+
+### Choosing the right primitives
+
+By tool kind:
+
+| Tool kind | Use |
+|-----------|-----|
+| Pure host shell-outs | `CommandRunner` + `Platform` (java, shell, dns) |
+| Container orchestration | `DockerEnv` + `Platform`, preflight via `version.preflight(("docker",))` (db, stack, web, tls) |
+| Manages a host daemon | `HostService.detect(platform)` (db --on-host) |
+| Reads/writes a system file | atomic-write pattern: tempfile + `sudo install`, with a backup-on-mutate sidecar (hosts, web/nginx vhost apply, cron) |
+| Wraps another shimkit tool | Import its `Manager` directly (framework laravel cron-install → cron) |
+
+### Sub-app parents
+
+Some tools have a sub-app parent (e.g. `framework laravel`, `web
+nginx vhost`). The convention:
+
+```
+tools/<parent>/
+  __init__.py
+  commands.py       Parent Typer app — registers children
+  <child>/
+    __init__.py
+    manager.py
+    commands.py     Child Typer app
+```
+
+Sub-apps inherit the same five rules. Each child remains independently
+testable, and the parent is mostly a Typer-glue file.
 
 A tool joins shimkit only if it shares ≥ 2 of `Platform` / `Shell` /
 `PackageManager` / `UI` / `Menu`. Otherwise it's a separate package.

docs/release-notes/v0.10.0.md

@@ -0,0 +1,110 @@
+# shimkit 0.10.0
+
+Internal quality release. Coverage push from 74% to 85%. **No
+source-code changes** outside one small lint-config tweak. For the
+full machine-readable changelog, see
+[`CHANGELOG.md`](../../CHANGELOG.md).
+
+---
+
+## TL;DR
+
+```
+test count:     630 → 1027     (+397)
+coverage:        74%  → 85%
+```
+
+Across 15 new test files targeting previously-thin code paths in
+the existing managers — no new tools, no new public APIs, no
+behavioural changes.
+
+---
+
+## What got covered
+
+| Module | Old → New | Notes |
+|--------|-----------|-------|
+| `core/command`     | 65% → 100% | sudo / has_sudo / CommandResult / exception paths |
+| `core/menu`        | 50% → ~95% | FallbackMenu select / confirm / checkbox edges |
+| `core/host_service`| 45% → ~95% | SystemdHost + BrewServicesHost state/start/stop |
+| `core/systemd`     | 58% → ~95% | lifecycle helpers, journal argv shape |
+| `core/platform`    | 77% → ~95% | WSL detection, container probes, brew-prefix linux |
+| `core/ui`          | 61% → ~85% | banner, spinner, quiet mode, color override |
+| `tools/java/manager` | 18% → ~85% | menu loop + all _menu_* branches |
+| `tools/java/scanner` | 21% → ~90% | scan / sdkman / JAVA_HOME / active_version |
+| `tools/java/installer` | 27% → ~85% | install/reinstall/uninstall/upgrade/switch |
+| `tools/java/brew`  | 37% → ~90% | prefix cache + lifecycle + outdated parse |
+| `tools/ssh/manager`| 57% → ~80% | keys + agent + known_hosts + perms + config |
+| `tools/ssh/scanner`| 73% → ~95% | pure parsers (agent / known_hosts / audit) |
+| `tools/adguard/manager` | 59% → ~70% | service / logs / rollback / config_validate |
+| `tools/dns/manager`| 70% → ~80% | diagnose / flush / show / test / set / reset / fix |
+| `tools/dns/fixer`  | 63% → ~75% | detect_interference / backup-dir safety / rollback |
+| `tools/db/manager` | 78% → ~85% | _to_status_row / --on-host JSON / dump-to-file |
+| `tools/gpg/manager`| 64% → ~75% | keys / git-signing / agent / run loop |
+| `tools/docker_clean/manager` | 64% → ~70% | dispatch / quick / nuke / inspect / compose-down |
+| `tools/tls/manager`| 76% → ~85% | revoke dry-run / renew failure / cron-install |
+| `tools/hosts/manager` | 70% → ~80% | _read_source / _back_up / _atomic_write fallback |
+| `tools/web/nginx/manager` | 73% → ~80% | list empty / apply + remove severe-token gates |
+| `cli`              | 73% → ~85% | doctor / config show/path/edit/validate / per-tool --help |
+
+---
+
+## Test pattern
+
+Same as the rest of the suite: mock at the boundary
+(`Platform.detect`, `CommandRunner.run`, `shutil.which`,
+component factories), no real subprocess or daemon access. The new
+tests follow the existing module convention — each
+`test_coverage_v010_*.py` covers a specific target area.
+
+---
+
+## Non-test changes
+
+One tweak to `pyproject.toml`:
+
+```toml
+[tool.ruff.lint.per-file-ignores]
+# Test stubs use throwaway classes to mock pydantic models; RUF012
+# (mutable class-attribute defaults need ClassVar) is real-code
+# advice that doesn't apply to dataclass-style test fakes.
+"tests/*" = ["RUF012"]
+```
+
+That's it. Zero source changes.
+
+---
+
+## What's left uncovered
+
+1,266 of 8,300 lines still uncovered (15%), mostly:
+
+- UI rendering paths in `adguard/manager` that branch on
+  `Menu.select` choices — exhaustive coverage would require
+  re-implementing each manager's dispatch table.
+- Linux-only paths in `dns/fixer` (`step_cycle_interface` for
+  non-Wi-Fi devices, `step_nuclear` plist removal) where the
+  test fixture would need to mock `airport_power` + `ifconfig`
+  + the SystemConfiguration plist tree.
+- macOS scutil + networksetup boundary modules — covered by the
+  manager-level tests but not exhaustively.
+
+---
+
+## Stats
+
+- Tests: 630 → 1027 (+397)
+- Files added: 15 (all under `tests/test_coverage_v010_*.py`)
+- Source LOC changes: 0
+- Gates: pytest 1027 passed, ruff clean, mypy strict clean
+
+---
+
+## Upgrading
+
+```bash
+uv tool upgrade shimkit
+pipx upgrade shimkit
+```
+
+No config changes, no breaking changes, no new dependencies.