release: v0.8.0 — shimkit tls (certbot)

Container-first TLS cert lifecycle helper. Second of the
deferred v0.5+ candidates from the ubuntu-migration validation
report (after `shimkit cron` in v0.6.0 and `shimkit framework
laravel` in v0.7.0).

Surface:

    shimkit tls request -d D [-d D2 ...] --email E --webroot PATH
        [--staging] (MODERATE prompt)
    shimkit tls list [--json]
    shimkit tls status DOMAIN [--json]
    shimkit tls renew [-d DOMAIN] [--force-renewal] (MODERATE)
    shimkit tls revoke -d DOMAIN --confirm REVOKE-TLS (SEVERE)
    shimkit tls cron-install [--schedule S] (MODERATE)

Every certbot invocation is a one-shot via the upstream
`certbot/certbot:v3.0.1` image. The `/etc/letsencrypt` directory
is bind-mounted from `~/.shimkit/data/tls/etc-letsencrypt/` so
account keys + cert state survive container exits — daily renewal
cron (default 03:17) reuses the same on-disk state.

`request` only wires the webroot ACME challenge today. DNS-01
(required for wildcards) is opt-in extras land in a future
release — each provider needs its own credential surface.

`status` and `list` parse the cert's `notAfter` by shelling out
to host `openssl x509 -enddate`; flags certs within 30 days of
expiry as `expiring_soon`.

Supporting changes:

- `core/docker.DockerEnv.run_oneshot(image, command, ...)` —
  detached-then-waited container run that captures exit code +
  stdout + stderr and auto-removes on exit. Used by `shimkit
  tls` for every certbot invocation; available to any future
  tool that needs one-shot container semantics. Image-pull is
  implicit (docker-py pulls if absent).
- `core/version.py` registers an `openssl` detector — the regex
  handles both OpenSSL and LibreSSL strings (macOS ships
  LibreSSL by default; brew can install OpenSSL alongside).
- `tools.versions.openssl` floor at `1.1`.
- `tools.tls` config block: `data_dir`, `certbot_image`,
  `default_method`, `default_email`, `renewal_schedule`,
  `revoke_severe_token`.

Tests: 48 new (561 → 609 total). Pure argv builders (request
with minimal/multiple/staging/dry-run/empty-domains/unsupported-
method; renew default/with-cert-name/force-and-dry-run; revoke
happy path + empty-name refusal; container_volumes shape with +
without webroot; cert_paths convention), domain validation
(parametrised valid + invalid sets), TlsManager boot creates
data dirs, request (rejects missing email / missing webroot /
invalid domain / passes argv + volumes to run_oneshot /
propagates non-zero exit / JSON includes domains+status), renew
(default / with-domain / --force-renewal), revoke (requires
severe token / requires existing cert / happy path with seeded
live dir), list/status (empty / with-fixture + stubbed openssl /
expiring-soon flag / missing cert refusal / JSON shape),
cron-install (delegates to CronManager with correct
name+schedule+command / custom schedule override), command
surface (--help lists all six subcommands; openssl detector
registered with min 1.1).

Gates: pytest 609 passed, ruff clean, mypy strict clean. No new
optional extras (reuses [docker-clean]'s docker package).

Author: imanimanyara

CHANGELOG.md

@@ -6,6 +6,42 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.8.0] — 2026-05-15
+
+### Added
+
+- `shimkit tls` — TLS cert lifecycle helper via container-first
+  certbot. Six commands: `request -d D [-d D2 ...] --email E
+  --webroot PATH [--staging]` (MODERATE — issuance via webroot
+  ACME challenge); `list [--json]` and `status DOMAIN [--json]`
+  (read-only enumeration with expiry parsing); `renew [-d
+  DOMAIN] [--force-renewal]` (MODERATE — defaults to all due);
+  `revoke -d DOMAIN --confirm REVOKE-TLS` (SEVERE); `cron-install
+  [--schedule S]` (MODERATE — installs daily `shimkit tls renew`
+  via `shimkit cron`). Replaces the ubuntu/ source script's
+  ad-hoc letsencrypt setup with a container-first lifecycle.
+  Persists `/etc/letsencrypt/` state at
+  `~/.shimkit/data/tls/etc-letsencrypt/` so account + cert
+  history survive container exits. Default image
+  `certbot/certbot:v3.0.1` (pinned, configurable). Cert expiry
+  parsed by shelling out to host `openssl x509 -enddate`;
+  `tools.versions.openssl` floor at `1.1`. Adds 48 tests (561 →
+  609 total). One of the deferred v0.5+ candidates from the
+  ubuntu migration's validation report. No new optional
+  dependency extras (reuses `[docker-clean]`'s `docker` package).
+  [`docs/tools/tls.md`](docs/tools/tls.md).
+
+### Changed
+
+- `core/docker.DockerEnv` gains `run_oneshot(image, command,
+  ...)` — detached-then-waited container run that captures exit
+  code + stdout + stderr and auto-removes the container on exit.
+  Used by `shimkit tls` for certbot invocations; available to
+  any future tool that needs one-shot container semantics.
+- `core/version.py` registers an `openssl` detector (parses both
+  `OpenSSL` and `LibreSSL` version strings — macOS ships
+  LibreSSL by default).
+
 ## [0.7.1] — 2026-05-15
 
 ### Fixed

README.md

@@ -20,6 +20,7 @@ shimkit
   db            Container-first databases (5 engines).
   stack         Multi-container app recipes (LEMP today).
   web           Web-server tooling (nginx vhost generator).
+  tls           TLS cert lifecycle via container-first certbot.
   framework     Framework-specific helpers (Laravel today).
   config        Inspect and edit shimkit configuration.
   doctor        Print system diagnostics useful for bug reports.
@@ -92,6 +93,11 @@ behaviour: [`docs/installation.md`](docs/installation.md).
   LEMP recipe (db + php-fpm + nginx). Bind-mounts `$cwd` at
   `/srv/app`. `up` / `down` / `status` / `logs` / `exec`. Multiple
   projects side-by-side via `--project`.
+- **[`shimkit tls`](docs/tools/tls.md)** — TLS cert lifecycle
+  helper via container-first certbot. `request` / `list` /
+  `status` / `renew` / `revoke` (SEVERE) / `cron-install`. State
+  persists under `~/.shimkit/data/tls/`; pair with `shimkit cron`
+  for daily renewals.
 - `shimkit shell colors` — 256-color ANSI palette diagnostic.
 
 ### Framework recipes
@@ -170,6 +176,7 @@ The repo root has the short version. The long version lives under
 | `shimkit db` deep-dive | [`docs/tools/db.md`](docs/tools/db.md) |
 | `shimkit stack` deep-dive | [`docs/tools/stack.md`](docs/tools/stack.md) |
 | `shimkit web nginx` deep-dive | [`docs/tools/web.md`](docs/tools/web.md) |
+| `shimkit tls` deep-dive | [`docs/tools/tls.md`](docs/tools/tls.md) |
 | `shimkit framework laravel` deep-dive | [`docs/tools/framework-laravel.md`](docs/tools/framework-laravel.md) |
 
 Project files:

docs/README.md

@@ -24,6 +24,9 @@ shimkit is a collection. Each tool gets its own page:
   fixer (Linux). API-first, ruamel.yaml fallback.
 - **[`shimkit docker-clean`](tools/docker-clean.md)** — Docker resource
   cleanup (Linux + macOS + WSL). docker-py SDK + buildx-aware prune.
+- **[`shimkit tls`](tools/tls.md)** — TLS cert lifecycle via
+  container-first certbot. request / list / status / renew /
+  revoke (SEVERE) / cron-install.
 - **[`shimkit framework laravel`](tools/framework-laravel.md)** —
   Laravel helpers: perms, `.env` scaffold, scheduler cron-install,
   artisan passthrough (host or LEMP container).

docs/tools/tls.md

@@ -0,0 +1,167 @@
+# shimkit tls
+
+TLS certificate lifecycle helper. Container-first: every certbot
+invocation is a one-shot through the upstream `certbot/certbot`
+image. The `/etc/letsencrypt` directory is bind-mounted at
+`~/.shimkit/data/tls/etc-letsencrypt/` so account + cert state
+survives container exits and host reboots.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `shimkit tls`                                                        | Menu. |
+| `shimkit tls request -d D [-d D2 ...] --email E --webroot PATH [--staging]` | MODERATE. Request a new cert via webroot ACME challenge. |
+| `shimkit tls list [--json]`                                          | Enumerate local certs with expiry dates. |
+| `shimkit tls status DOMAIN [--json]`                                 | Show one cert's paths + expiry. |
+| `shimkit tls renew [-d DOMAIN] [--force-renewal]`                    | MODERATE. Renew certs (all due, or one named). |
+| `shimkit tls revoke -d DOMAIN --confirm REVOKE-TLS`                  | SEVERE. Revoke a cert via the ACME CA. |
+| `shimkit tls cron-install [--schedule S]`                            | MODERATE. Install a daily `shimkit tls renew` cron entry. |
+
+Universal flags before the subcommand (`--quiet`, `--verbose`,
+`--log-file`, `--no-color`, `--color`, `--no-input`); per-command
+flags after (`--json`, `--dry-run`, `--yes`, `--force`).
+
+## How it works
+
+`shimkit tls request` runs:
+
+```
+docker run --rm \
+  -v ~/.shimkit/data/tls/etc-letsencrypt:/etc/letsencrypt \
+  -v ~/.shimkit/data/tls/var-lib-letsencrypt:/var/lib/letsencrypt \
+  -v <webroot>:/webroot:ro \
+  certbot/certbot:v3.0.1 \
+  certonly --non-interactive --agree-tos \
+  --email ops@example.com \
+  --webroot -w /webroot \
+  -d example.com [-d www.example.com] \
+  [--staging]
+```
+
+The webroot must already be served at
+`http://<domain>/.well-known/acme-challenge/` for the ACME challenge
+to succeed. The recommended layout for `shimkit web nginx vhost`-
+generated vhosts is the project root.
+
+`certbot/certbot:v3.0.1` is the default; override via
+`tools.tls.certbot_image` in your user config. Pinning to a
+specific version rather than `:latest` keeps renewal behaviour
+deterministic.
+
+## On-disk layout
+
+```
+~/.shimkit/data/tls/
+├── etc-letsencrypt/         # mounts to /etc/letsencrypt
+│   ├── live/<domain>/       # symlinks (fullchain.pem, privkey.pem, ...)
+│   ├── archive/<domain>/    # numbered cert history
+│   ├── accounts/            # ACME account keys + metadata
+│   └── renewal/             # renewal config per cert
+└── var-lib-letsencrypt/     # mounts to /var/lib/letsencrypt
+```
+
+Point nginx at `fullchain.pem` + `privkey.pem` from the `live/`
+directory — they're stable symlinks that get repointed each
+renewal, so nginx never needs to be told a new cert path.
+
+## Examples
+
+```bash
+# Request a cert in staging first (recommended — Let's Encrypt
+# rate-limits production aggressively, but staging is forgiving).
+shimkit tls request --yes --staging \
+    --email ops@example.com \
+    --webroot /var/www/example \
+    -d example.com -d www.example.com
+
+# Once staging works, request the real cert.
+shimkit tls request --yes \
+    --email ops@example.com \
+    --webroot /var/www/example \
+    -d example.com -d www.example.com
+
+# Enumerate local certs.
+shimkit tls list
+shimkit tls list --json
+
+# Inspect a single cert.
+shimkit tls status example.com
+shimkit tls status example.com --json
+
+# Renew everything that's within 30 days of expiry.
+shimkit tls renew --yes
+
+# Force a renewal even if the cert isn't due (test, key rotation).
+shimkit tls renew --yes --force-renewal -d example.com
+
+# Install the daily renewal cron entry (default: 03:17 every day).
+shimkit tls cron-install --yes
+
+# Custom schedule.
+shimkit tls cron-install --yes --schedule "0 4 * * *"
+
+# Revoke (SEVERE — confirm token required).
+shimkit tls revoke -d example.com --confirm REVOKE-TLS
+```
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "tls": {
+      "data_dir": "~/.shimkit/data/tls",
+      "certbot_image": "certbot/certbot:v3.0.1",
+      "default_method": "webroot",
+      "default_email": null,
+      "renewal_schedule": "17 3 * * *",
+      "revoke_severe_token": "REVOKE-TLS"
+    },
+    "versions": {
+      "openssl": {"min": "1.1"}
+    }
+  }
+}
+```
+
+`default_email` set in the user config lets you drop `--email`
+from every `shimkit tls request` invocation. `tools.versions.openssl`
+is the floor used by `shimkit doctor` and the cert-expiry parsing
+in `tls list` / `tls status` (which shells out to `openssl x509
+-enddate`).
+
+## Exit codes
+
+| Code | Meaning |
+|-----:|---------|
+| 0    | success |
+| 1    | invalid input, missing webroot, certbot failed, missing cert, missing severe token |
+| 2    | Typer usage error |
+| 69   | `EX_UNAVAILABLE` — docker missing / daemon unreachable / out-of-range |
+| 130  | SIGINT |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | full (Docker Desktop required). |
+| Linux    | full. |
+| WSL      | full (Docker Desktop or native Docker). |
+| Windows  | out of charter — use WSL. |
+
+## Notes
+
+- **Staging first.** Let's Encrypt's production rate limits are
+  punishing (5 failed validations / hour / hostname). Always
+  pass `--staging` for first runs; the resulting cert isn't
+  trusted but proves the webroot setup works.
+- **Webroot vs DNS-01.** Only webroot is wired today. DNS-01
+  (required for wildcard certs) lands as opt-in extras in a
+  future release — each provider needs its own credential
+  surface (`cloudflare`, `route53`, etc.).
+- **No PyPI extra.** This tool reuses the `[docker-clean]`
+  extra's `docker` package — no new install footprint.
+- **Renewal cadence.** Let's Encrypt certs are valid for 90 days;
+  certbot's `renew` only renews within 30 days of expiry, so the
+  daily cron is safe (and idempotent — no-op when nothing's due).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shimkit"
-version = "0.7.1"
+version = "0.8.0"
 description = "A toolkit of developer utilities — Java version manager, shell upgrader, and more. Python tools, shimmed by bash."
 readme = "README.md"
 license = { file = "LICENSE" }

src/shimkit/__init__.py

@@ -3,5 +3,5 @@
 Python tools, shimmed by bash.
 """
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"
 __all__ = ["__version__"]

src/shimkit/cli.py

@@ -29,6 +29,7 @@
 from shimkit.tools.shell.commands import shell_app
 from shimkit.tools.ssh.commands import ssh_app
 from shimkit.tools.stack.commands import stack_app
+from shimkit.tools.tls.commands import tls_app
 from shimkit.tools.web.commands import web_app
 
 app = typer.Typer(
@@ -55,6 +56,7 @@
 app.add_typer(stack_app)
 app.add_typer(web_app)
 app.add_typer(cron_app)
+app.add_typer(tls_app)
 app.add_typer(framework_app)
 
 

src/shimkit/config/defaults.json

@@ -185,6 +185,14 @@
       "backup_dir": "~/.shimkit/data/cron",
       "max_managed_entries": 200
     },
+    "tls": {
+      "data_dir": "~/.shimkit/data/tls",
+      "certbot_image": "certbot/certbot:v3.0.1",
+      "default_method": "webroot",
+      "default_email": null,
+      "renewal_schedule": "17 3 * * *",
+      "revoke_severe_token": "REVOKE-TLS"
+    },
     "framework": {
       "laravel": {
         "web_group": "www-data",
@@ -200,7 +208,8 @@
       "git":    {"min": "2.30"},
       "gpg":    {"min": "2.2"},
       "python": {"min": "3.10", "preferred": "3.12"},
-      "php":    {"min": "8.1"}
+      "php":    {"min": "8.1"},
+      "openssl":{"min": "1.1"}
     }
   },
   "package_managers": {

src/shimkit/config/schema.py

@@ -324,6 +324,7 @@ class VersionsConfig(_StrictModel):
     gpg: VersionConstraint = Field(default_factory=VersionConstraint)
     python: VersionConstraint = Field(default_factory=VersionConstraint)
     php: VersionConstraint = Field(default_factory=VersionConstraint)
+    openssl: VersionConstraint = Field(default_factory=VersionConstraint)
 
 
 class FrameworkLaravelConfig(_StrictModel):
@@ -350,6 +351,29 @@ class FrameworkConfig(_StrictModel):
     laravel: FrameworkLaravelConfig = Field(default_factory=FrameworkLaravelConfig)
 
 
+class TlsConfig(_StrictModel):
+    """`shimkit tls` — TLS cert lifecycle via container-first certbot."""
+
+    # Volume root for /etc/letsencrypt content. Persists across renewals.
+    data_dir: str = "~/.shimkit/data/tls"
+    # Certbot image to run one-shot. Pin to a known-good version rather
+    # than `:latest` so a registry-side image change can't break renewals
+    # silently.
+    certbot_image: str = "certbot/certbot:v3.0.1"
+    # Default ACME challenge method. Only `webroot` is wired today;
+    # `dns-cloudflare` etc. land as opt-in extras in a later release.
+    default_method: Literal["webroot"] = "webroot"
+    # ACME account email. Required by Let's Encrypt for issuance unless
+    # `--register-unsafely-without-email` is passed (we don't expose
+    # that flag). User config overrides per-install.
+    default_email: str | None = None
+    # Default cron schedule for `tls cron-install`. 03:17 daily — well
+    # outside business hours and offset from on-the-hour cron herd.
+    renewal_schedule: str = "17 3 * * *"
+    # SEVERE-tier token for `tls revoke`.
+    revoke_severe_token: str = "REVOKE-TLS"
+
+
 class CronConfig(_StrictModel):
     """`shimkit cron` — generic user-crontab editor."""
 
@@ -379,6 +403,7 @@ class ToolsConfig(_StrictModel):
     stack: StackConfig = Field(default_factory=StackConfig)
     web: WebConfig = Field(default_factory=WebConfig)
     cron: CronConfig = Field(default_factory=CronConfig)
+    tls: TlsConfig = Field(default_factory=TlsConfig)
     framework: FrameworkConfig = Field(default_factory=FrameworkConfig)
     versions: VersionsConfig = Field(default_factory=VersionsConfig)