feat(hosts): add shimkit hosts — /etc/hosts editor with atomic write + backups

Second of three new tools for v0.3.0 (ports → hosts → ssh per
docs/plans/v0.3.0-new-tools.md). Reuses the atomic-write +
timestamped-backup pattern from adguard.resolv.write_resolv_static.

Surface:

- `shimkit hosts show` — list entries (with --json).
- `shimkit hosts add IP NAME` — append, idempotent, MODERATE prompt.
  Refuses non-IPv4/non-IPv6 with exit 1.
- `shimkit hosts remove NAME` — remove all entries by hostname.
- `shimkit hosts block / unblock DOMAIN` — convenience aliases.
- `shimkit hosts apply-list SOURCE` — apply a StevenBlack-style
  list from a URL (https or http via stdlib urllib.request) or local
  file. SEVERE — `--confirm APPLY-LIST` required; capped at
  `tools.hosts.max_entries_per_apply` (default 5000).
- `shimkit hosts rollback` — restore the latest `.bak-*`.

Internals:

- Pure parser in `editor.py` (text-in/model-out, no I/O) — round-trips
  blank lines, comments, and multi-name lines.
- `HostsConfig` added to typed config (hosts_path,
  apply_list_severe_token, max_entries_per_apply,
  managed_block_marker).
- Manager owns the CommandRunner shell-outs: `sudo install -m 0644
  -o root <tmp> /etc/hosts` with a Python direct-write fallback for
  bind-mounted hosts files (containers).
- `--path PATH` flag on every subcommand for testing + chroot edits.
- URL fetch via stdlib urllib.request (scheme-gated to http/https;
  nosec B310 with a reason).

Tests: 20 cases (272 total) — parser round-trip, IP validator,
StevenBlack format, idempotent add, severe-token refusal +
acceptance, max-entries cap, rollback restore, no-input refuse.

Gates: ruff clean, mypy strict clean, bandit medium=0.

Author: imanimanyara

CHANGELOG.md

@@ -18,6 +18,17 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   uses `CommandRunner` only. Adds 19 tests (parser fixtures for
   both `lsof -F pcnuP` and `ss -tulnpH` output, plus CLI/manager
   coverage). [`docs/tools/ports.md`](docs/tools/ports.md).
+- `shimkit hosts` — `/etc/hosts` editor with atomic-write +
+  timestamped backups. `show`, `add IP NAME`, `remove NAME`,
+  `block DOMAIN` / `unblock DOMAIN` aliases, `apply-list SOURCE`
+  (SEVERE — `--confirm APPLY-LIST`), `rollback`. Pure parser
+  (`editor.py`) is text-in/model-out and unit-testable; manager
+  follows the same `sudo install` → bind-mount-fallback pattern
+  as `adguard.resolv.write_resolv_static`. URL fetch via stdlib
+  `urllib.request` — no extra deps. Adds 20 tests (parser
+  round-trip, IP validator, idempotent add, severe-token gate,
+  cap enforcement, rollback restore).
+  [`docs/tools/hosts.md`](docs/tools/hosts.md).
 
 ## [0.2.3] — 2026-05-14
 

README.md

@@ -44,6 +44,9 @@ behaviour: [`docs/installation.md`](docs/installation.md).
 - **[`shimkit ports`](docs/tools/ports.md)** — list / kill the process
   holding a TCP or UDP port (macOS + Linux). `lsof` on macOS, `ss` on
   Linux. MODERATE prompt on `kill`; severe token for system-tier PIDs.
+- **[`shimkit hosts`](docs/tools/hosts.md)** — `/etc/hosts` editor
+  with atomic-write + timestamped backups. add / remove / block /
+  unblock / apply-list (severe) / rollback. macOS + Linux.
 
 Plus three utilities:
 

docs/tools/hosts.md

@@ -0,0 +1,120 @@
+# shimkit hosts
+
+`/etc/hosts` editor with atomic-write + timestamped backups. Same
+atomic-replace pattern as `adguard.resolv.write_resolv_static`: write
+to a temp file, then `sudo install -m 0644 -o root <tmp> /etc/hosts`.
+Bind-mounted hosts files (typical inside containers) fall through to a
+Python direct-write through the existing inode.
+
+Pure parsing + mutation logic lives in
+`src/shimkit/tools/hosts/editor.py` (no I/O), so the model is
+unit-testable without touching the system hosts file.
+
+## Commands
+
+| Command                                | Purpose                                                            |
+|----------------------------------------|--------------------------------------------------------------------|
+| `shimkit hosts`                        | Interactive menu (list / rollback).                                |
+| `shimkit hosts show`                   | Print every entry.                                                 |
+| `shimkit hosts add IP NAME`            | Append. Idempotent. MODERATE prompt.                               |
+| `shimkit hosts remove NAME`            | Remove every entry whose hostname matches. MODERATE prompt.        |
+| `shimkit hosts block DOMAIN`           | Alias for `add 127.0.0.1 DOMAIN`.                                  |
+| `shimkit hosts unblock DOMAIN`         | Alias for `remove DOMAIN`.                                         |
+| `shimkit hosts apply-list SOURCE`      | Apply a StevenBlack-style list. **SEVERE** — token required.       |
+| `shimkit hosts rollback`               | Restore the most recent backup.                                    |
+
+`SOURCE` for `apply-list` is either `http(s)://...` (fetched via
+stdlib `urllib.request`, no extra deps) or a local file path.
+
+Universal flags (`--quiet`, `--verbose`, `--log-file`, `--no-color`,
+`--color`, `--no-input`) go before the subcommand. Per-command flags
+(`--dry-run`, `--yes`, `--force`, `--confirm`, `--path`) go after.
+
+## Safety + the SEVERE tier
+
+`apply-list` is the only severe-tier command. It can write thousands
+of entries at once, so the default token is `APPLY-LIST`:
+
+```bash
+shimkit hosts apply-list https://example.com/list.txt --confirm APPLY-LIST
+```
+
+The size cap (`tools.hosts.max_entries_per_apply`, default `5000`)
+refuses lists bigger than the threshold. Raise it in
+`~/.config/shimkit/shimkit.json` if you really want the full
+StevenBlack-extended list.
+
+`add` / `remove` / `block` / `unblock` are MODERATE-tier — they
+prompt `[y/N]` by default; `--yes` / `--force` skip; `--no-input`
+refuses with exit 1.
+
+## Atomic-write + backup
+
+Every mutator follows the same sequence:
+
+1. Parse the current file.
+2. Compute the new content in-memory.
+3. `sudo cp -a /etc/hosts /etc/hosts.bak-YYYYMMDDHHMMSS`.
+4. Write to a temp file, then `sudo install -m 0644 -o root` over
+   the target.
+5. If `install` fails (typical inside container bind-mounts), fall
+   back to a Python direct-write through the existing inode —
+   requires the process is already root.
+
+`rollback` restores the latest `*.bak-*` file.
+
+## JSON output
+
+```bash
+$ shimkit hosts show --json
+{
+  "ts": "...",
+  "tool": "hosts",
+  "step": "show",
+  "status": "ok",
+  "data": {
+    "path": "/etc/hosts",
+    "entries": [
+      {"ip": "127.0.0.1", "name": "localhost", "comment": null},
+      {"ip": "::1", "name": "localhost", "comment": null}
+    ]
+  }
+}
+```
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "hosts": {
+      "hosts_path": "/etc/hosts",
+      "apply_list_severe_token": "APPLY-LIST",
+      "max_entries_per_apply": 5000,
+      "managed_block_marker": "# === shimkit-managed ==="
+    }
+  }
+}
+```
+
+`--path PATH` overrides `hosts_path` for one invocation — useful for
+testing or for editing a chroot's hosts file from outside.
+
+## Exit codes
+
+| Code | Meaning                                              |
+|-----:|------------------------------------------------------|
+| 0    | success / no-op (entry already present / not present)|
+| 1    | generic failure (invalid IP, no backup, prompt cancelled, severe-token missing) |
+| 2    | Typer usage error                                    |
+| 69   | EX_UNAVAILABLE — wrong platform or hosts file missing |
+| 130  | SIGINT                                               |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | ✓ — `/etc/hosts` lives in the same place; same atomic-replace path. |
+| Linux    | ✓                                                                   |
+| WSL      | ✓ (Linux path).                                                     |
+| Windows  | ✗ — out of charter.                                                 |

src/shimkit/cli.py

@@ -17,6 +17,7 @@
 from shimkit.tools.adguard.commands import adguard_app
 from shimkit.tools.dns.commands import dns_app
 from shimkit.tools.docker_clean.commands import docker_clean_app
+from shimkit.tools.hosts.commands import hosts_app
 from shimkit.tools.java.commands import java_app
 from shimkit.tools.ports.commands import ports_app
 from shimkit.tools.shell.commands import shell_app
@@ -36,6 +37,7 @@
 app.add_typer(adguard_app)
 app.add_typer(docker_clean_app)
 app.add_typer(ports_app)
+app.add_typer(hosts_app)
 
 
 # --- config -----------------------------------------------------------------

src/shimkit/config/defaults.json

@@ -114,6 +114,12 @@
       "default_signal": "TERM",
       "init_pid_severe_token": "KILL-INIT",
       "system_pid_threshold": 100
+    },
+    "hosts": {
+      "hosts_path": "/etc/hosts",
+      "apply_list_severe_token": "APPLY-LIST",
+      "max_entries_per_apply": 5000,
+      "managed_block_marker": "# === shimkit-managed ==="
     }
   },
   "package_managers": {

src/shimkit/config/schema.py

@@ -163,13 +163,28 @@ class PortsConfig(_StrictModel):
     system_pid_threshold: int = Field(default=100, ge=1, le=65535)
 
 
+class HostsConfig(_StrictModel):
+    """/etc/hosts editor — `shimkit hosts`."""
+
+    hosts_path: str = "/etc/hosts"
+    apply_list_severe_token: str = "APPLY-LIST"
+    # Cap the size of a single `apply-list` call so a bad URL doesn't
+    # explode /etc/hosts. Tunable for power users who DO want huge
+    # ad-block lists; default is conservative.
+    max_entries_per_apply: int = Field(default=5000, ge=1, le=1_000_000)
+    # Marker we insert above shimkit-managed entries so future runs can
+    # find and update them without disturbing user-authored lines.
+    managed_block_marker: str = "# === shimkit-managed ==="
+
+
 class ToolsConfig(_StrictModel):
     java: JavaConfig
     shell: ShellToolConfig
     dns: DnsConfig = Field(default_factory=DnsConfig)
     adguard: AdGuardConfig = Field(default_factory=AdGuardConfig)
     docker_clean: DockerCleanConfig = Field(default_factory=DockerCleanConfig)
     ports: PortsConfig = Field(default_factory=PortsConfig)
+    hosts: HostsConfig = Field(default_factory=HostsConfig)
 
 
 class PackageManagerEntry(_StrictModel):

src/shimkit/tools/hosts/__init__.py

@@ -0,0 +1,14 @@
+"""``/etc/hosts`` editor with atomic-write + backups — ``shimkit hosts``.
+
+Add / remove / block / unblock individual entries, or apply a
+StevenBlack-style block list. Every mutator writes through a temp
+file (``install -m 644``) and creates a timestamped backup so
+``shimkit hosts rollback`` restores cleanly.
+"""
+
+from __future__ import annotations
+
+from .editor import Entry, HostsFile
+from .manager import HostsManager
+
+__all__ = ["Entry", "HostsFile", "HostsManager"]