feat(ports): add shimkit ports — cross-platform port owner + killer

First of three new tools for v0.3.0 (ports → hosts → ssh per
docs/plans/v0.3.0-new-tools.md). Smallest of the three; gets the
manager + commands + parser pattern right for the larger two.

Surface:

- `shimkit ports show [PORT]` — list listening TCP/UDP sockets via
  `lsof` on macOS or `ss` on Linux. `--json` emits a typed Event;
  positional PORT narrows the result.
- `shimkit ports kill PORT` — signal the holder(s) with a MODERATE
  prompt (`--yes` / `--force` / refused under `--no-input`).
  Allowed signals TERM/KILL/INT/HUP; anything else exits 1. PIDs
  below `tools.ports.system_pid_threshold` (default 100) require
  the severe-tier `--confirm KILL-INIT` token; pid 1 is refused at
  any token.

Internals:

- Pure parsers in `owners.py` for both `lsof -F pcnuP` and
  `ss -tulnpH`. Manager owns the CommandRunner shell-out; parsers
  are unit-testable without a subprocess.
- PortsConfig added to the typed config (system_pid_threshold,
  init_pid_severe_token, default_signal) with defaults in
  config/defaults.json.

Tests: 19 cases (252 total) — parser fixtures for both formats,
platform-gate exit 69, `lsof`/`ss`-missing exit 69, --json shape,
narrowed-port path, system-tier refusal, severe-token override,
dry-run no-side-effect, disallowed-signal rejection.

Gates: ruff clean, mypy strict clean. No new optional extras.

Author: imanimanyara

CHANGELOG.md

@@ -6,6 +6,19 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- `shimkit ports` — cross-platform TCP/UDP port owner inspector +
+  killer. `shimkit ports show [PORT]` lists every listening socket
+  via `lsof` on macOS or `ss` on Linux; `shimkit ports kill PORT`
+  signals the holder(s) with a MODERATE prompt. Allowed signals
+  `TERM/KILL/INT/HUP`; system-tier PIDs (below
+  `tools.ports.system_pid_threshold`, default 100) require the
+  severe-tier `--confirm KILL-INIT` token. No new optional extras —
+  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).
+
 ## [0.2.3] — 2026-05-14
 
 ### Removed

README.md

@@ -41,6 +41,9 @@ behaviour: [`docs/installation.md`](docs/installation.md).
 - **[`shimkit docker-clean`](docs/tools/docker-clean.md)** — Docker
   resource cleanup (Linux + macOS + WSL). Status, quick, prune-*, nuke,
   schedule-snippet emit.
+- **[`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.
 
 Plus three utilities:
 

docs/plans/v0.3.0-new-tools.md

@@ -0,0 +1,165 @@
+# v0.3.0 plan — three new tools (`ports`, `hosts`, `ssh`)
+
+> Scope per maintainer (2026-05-14): "add all of the above:
+> shimkit {ssh, hosts, ports, etc}". Charter is the host-machine
+> dev-workflow envelope; each of these fits.
+
+## Ordering
+
+Build in increasing complexity so the architecture decisions get
+exercised by the simplest tool first:
+
+1. **`shimkit ports`** (smallest, ~150 LOC manager + ~30 tests)
+2. **`shimkit hosts`** (medium, ~250 LOC manager + ~40 tests; reuses
+   atomic-write + backup from `adguard`)
+3. **`shimkit ssh`** (largest, ~400 LOC manager + ~60 tests; pulls
+   together everything from both)
+
+Each tool lands as its own commit on `main`; ship v0.3.0 once all
+three are in.
+
+## Architecture rules — same five from CONTRIBUTING.md
+
+1. All subprocess via `CommandRunner.run(...)` (argv-list, no `shell=True`).
+2. All output via `UI.*` — no `print`, no `typer.echo`.
+3. Config-driven values (defaults.json) for anything user-tunable.
+4. Builder pattern: `Manager.create().boot().run()`.
+5. Fluent `self` returns from builders.
+
+## Per-tool surface
+
+### `shimkit ports` — port owner inspector + killer
+
+```text
+shimkit ports                   # interactive menu (Manager.run)
+shimkit ports show [PORT]       # cross-platform: lsof on macOS, ss on Linux
+shimkit ports kill PORT         # MODERATE prompt; --yes/--force; --signal=TERM|KILL
+```
+
+- **Cross-platform**: `lsof -nP -iTCP -sTCP:LISTEN` on macOS,
+  `ss -tulnp` on Linux. Output normalised to a `PortOwner` model.
+- **JSON output**: `--json` emits `{status, data: [{port, proto, pid, name, user}]}`.
+- **MODERATE prompt** on `kill`. SEVERE prompt only if `pid == 1` or
+  `name == "systemd"` (refuse with `--confirm KILL-INIT`).
+- **No extra deps** — uses `CommandRunner.run` only. No `psutil`.
+
+### `shimkit hosts` — `/etc/hosts` editor with backup
+
+```text
+shimkit hosts                       # interactive menu
+shimkit hosts show [--json]
+shimkit hosts add IP NAME           # MODERATE prompt; atomic write
+shimkit hosts remove NAME           # MODERATE prompt
+shimkit hosts block DOMAIN          # add 127.0.0.1 entry
+shimkit hosts unblock DOMAIN
+shimkit hosts apply-list URL_OR_PATH  # SEVERE; --confirm APPLY-LIST
+shimkit hosts rollback              # restore latest /etc/hosts.bak-*
+```
+
+- **Atomic write**: parse → mutate in-memory → `install -m 644` to a
+  temp file → atomic move (reuse pattern from
+  `adguard/resolv.py::write_resolv_static`).
+- **Backup pattern**: `/etc/hosts.bak-YYYYMMDD-HHMMSS` (same as
+  `adguard`).
+- **Block list parser**: tolerant of comment lines + the StevenBlack
+  format (`0.0.0.0 example.com`). Caps applied entries per call
+  (configurable; default 5000).
+- **Needs root** for any mutator; exits 77 with the
+  `sudo shimkit hosts ...` hint matching `adguard`.
+
+### `shimkit ssh` — key + agent + perms hygiene
+
+```text
+shimkit ssh                              # interactive menu
+shimkit ssh keys list [--json]
+shimkit ssh keys generate NAME           # ed25519; MODERATE prompt; passphrase via stdin
+shimkit ssh keys rotate NAME             # generate new + load agent + print update steps
+shimkit ssh agent status [--json]
+shimkit ssh agent start                  # idempotent ssh-agent boot
+shimkit ssh agent add KEY_PATH           # ssh-add wrapper
+shimkit ssh known-hosts audit [--json]   # find duplicates + stale entries
+shimkit ssh known-hosts prune            # MODERATE prompt; remove duplicates
+shimkit ssh perms audit [--json]         # check ~/.ssh and key file modes
+shimkit ssh perms fix                    # MODERATE prompt; chmod 700/600/644
+shimkit ssh config show [HOST]           # parse ~/.ssh/config and show Host blocks
+```
+
+- **No extra deps** — `ssh-keygen`, `ssh-add`, `ssh-agent`, and
+  `ssh-keyscan` are all baseline.
+- **Passphrase handling**: prompt via Typer's `hide_input=True`; never
+  log; ssh-keygen consumes via `-N` (validated by length, not
+  content-pattern, so the value never hits the redaction layer).
+- **Perm matrix** lives in config (`tools.ssh.perms`):
+  - `~/.ssh` → 700
+  - `~/.ssh/config`, `known_hosts`, `authorized_keys` → 644
+  - Private keys (no `.pub` suffix) → 600
+  - Public keys (`.pub` suffix) → 644
+- **Agent state** parsed from `ssh-add -L` output; refusing-no-agent
+  exits 69 with a hint to run `shimkit ssh agent start`.
+
+## Test minimums per tool (CONTRIBUTING.md baseline)
+
+For each: `boot()` smoke, `boot()` 69 on wrong platform (if
+applicable), `boot()` 69 on missing extra (n/a — no extras), every
+non-interactive subcommand one happy + one sad path, `--json` parses,
+`--dry-run` makes zero `CommandRunner.run` calls (assert via
+monkeypatch), MODERATE prompts blocked under `--no-input`. Severe
+prompts abort without the right token.
+
+Mock at `CommandRunner.run`, `Platform.detect`, and Path-level
+filesystem fixtures via `tmp_path`. Never touch real `~/.ssh` or
+`/etc/hosts`.
+
+## Config additions to `defaults.json`
+
+```json
+{
+  "tools": {
+    "ports": {
+      "default_signal": "TERM",
+      "init_pid_severe_token": "KILL-INIT"
+    },
+    "hosts": {
+      "hosts_path": "/etc/hosts",
+      "apply_list_severe_token": "APPLY-LIST",
+      "max_entries_per_apply": 5000
+    },
+    "ssh": {
+      "ssh_dir": "~/.ssh",
+      "default_key_type": "ed25519",
+      "perms": {
+        "dir": "700",
+        "private_key": "600",
+        "public_key": "644",
+        "config": "644",
+        "known_hosts": "644",
+        "authorized_keys": "644"
+      }
+    }
+  }
+}
+```
+
+## Out of scope this cycle
+
+- **YubiKey / hardware-token SSH keys** — adds vendor SDKs; revisit
+  if there's demand.
+- **GPG keys** for git signing — separate `shimkit gpg` tool, not
+  bundled.
+- **Cloud DNS / hosts** (Route53 + Cloudflare etc.) — out of charter
+  (not host-machine).
+- **NetworkManager / nmcli wrappers beyond what `adguard` already
+  does** — would need its own tool.
+- **Windows support** — explicit charter exclusion.
+
+## Acceptance gates for v0.3.0
+
+- All five core architecture rules upheld in each new tool.
+- 233 → ~370 tests (the +130 baseline test floor across three tools).
+- Coverage stays above the 65% floor; aim to nudge toward 70%.
+- ruff + mypy strict still clean.
+- `shimkit --help` shows the three new sub-apps.
+- `docs/tools/{ports,hosts,ssh}.md` present, following the
+  established template.
+- README's tool list extended.
+- CHANGELOG `[0.3.0]` entry written.

docs/tools/ports.md

@@ -0,0 +1,112 @@
+# shimkit ports
+
+Cross-platform inspector + killer for the process holding a TCP or
+UDP port. Built for the day-to-day case of "port 5000 is in use" when
+you don't know what's holding it, or you do and you want it gone.
+
+macOS reads `lsof -nP -iTCP -sTCP:LISTEN -iUDP -F pcnuP`. Linux
+reads `ss -tulnpH`. Both outputs are normalised to a single
+`PortOwner` dataclass via the pure parsers in
+`src/shimkit/tools/ports/owners.py` (unit-testable without
+shelling out).
+
+## Commands
+
+| Command                                  | Purpose                                                              |
+|------------------------------------------|----------------------------------------------------------------------|
+| `shimkit ports`                          | Interactive menu (list-only — kill is subcommand-only).              |
+| `shimkit ports show`                     | List every listening socket and the process holding it.              |
+| `shimkit ports show <port>`              | Same, narrowed to one port.                                          |
+| `shimkit ports kill <port>`              | Signal the holder(s). MODERATE prompt by default.                    |
+
+Every command accepts the standard shared flags: `--quiet`,
+`--verbose`, `--log-file`, `--no-color`, `--color`, `--no-input`
+(place these before the subcommand). Per-command flags
+(`--json`, `--dry-run`, `--yes`, `--force`, `--confirm`,
+`--signal`) go after.
+
+## Killing a port
+
+```bash
+shimkit ports kill 5000              # interactive MODERATE prompt
+shimkit ports kill 5000 --yes        # skip the prompt
+shimkit ports kill 5000 --signal KILL --yes
+shimkit ports kill 5000 --dry-run    # show targets without signalling
+```
+
+Allowed signals: `TERM` (default), `KILL`, `INT`, `HUP`. Anything
+else is refused with exit 1 — this CLI is for stopping stuck dev
+servers, not for arbitrary IPC.
+
+## Severe tier — system processes
+
+Killing a process with a low PID (below
+`tools.ports.system_pid_threshold`, default `100`) requires the
+severe-tier token:
+
+```bash
+shimkit ports kill 53 --yes --confirm KILL-INIT
+```
+
+The default threshold catches systemd-side services on Linux
+(systemd-resolved, systemd-networkd, etc.) and the early-boot helpers
+on macOS. Bumping the threshold lower in `~/.config/shimkit/shimkit.json`
+trades safety for convenience.
+
+Killing pid 1 specifically is refused at any token — `init` is never
+the right answer.
+
+## JSON output
+
+```bash
+$ shimkit ports show --json
+{
+  "ts": "...",
+  "tool": "ports",
+  "step": "show",
+  "status": "ok",
+  "data": {
+    "port": null,
+    "owners": [
+      {"port": 80, "proto": "tcp", "pid": 1234,
+       "name": "nginx", "user": "nobody", "address": null}
+    ]
+  }
+}
+```
+
+`port` is `null` when the call was unfiltered. `address` is
+`null` for wildcard binds (`0.0.0.0`, `*`, `::`).
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "ports": {
+      "default_signal": "TERM",
+      "init_pid_severe_token": "KILL-INIT",
+      "system_pid_threshold": 100
+    }
+  }
+}
+```
+
+## Exit codes
+
+| Code | Meaning                                              |
+|-----:|------------------------------------------------------|
+| 0    | success / no-op (port empty / nothing to do)         |
+| 1    | generic failure (disallowed signal, refused tier, prompt cancelled) |
+| 2    | Typer usage error                                    |
+| 69   | EX_UNAVAILABLE — wrong platform or `lsof`/`ss` missing |
+| 130  | SIGINT                                               |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | ✓ via `lsof` (preinstalled on every supported macOS).               |
+| Linux    | ✓ via `ss` from `iproute2` (preinstalled on most distros).          |
+| WSL      | ✓ (Linux path).                                                     |
+| Windows  | ✗ — out of charter.                                                 |

src/shimkit/cli.py

@@ -18,6 +18,7 @@
 from shimkit.tools.dns.commands import dns_app
 from shimkit.tools.docker_clean.commands import docker_clean_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
 
 app = typer.Typer(
@@ -34,6 +35,7 @@
 app.add_typer(dns_app)
 app.add_typer(adguard_app)
 app.add_typer(docker_clean_app)
+app.add_typer(ports_app)
 
 
 # --- config -----------------------------------------------------------------

src/shimkit/config/defaults.json

@@ -109,6 +109,11 @@
       "kubernetes_image_patterns": ["registry.k8s.io", "kube-", "kubernetes", "desktop-"],
       "daemon_verify_timeout_seconds": 30,
       "default_buildx_prune_all": true
+    },
+    "ports": {
+      "default_signal": "TERM",
+      "init_pid_severe_token": "KILL-INIT",
+      "system_pid_threshold": 100
     }
   },
   "package_managers": {

src/shimkit/config/schema.py

@@ -152,12 +152,24 @@ class DockerCleanConfig(_StrictModel):
     default_buildx_prune_all: bool = True
 
 
+class PortsConfig(_StrictModel):
+    """Port owner inspection + killer — `shimkit ports`."""
+
+    default_signal: str = "TERM"
+    init_pid_severe_token: str = "KILL-INIT"
+    # Killing a PID below this threshold is treated as a system-process
+    # operation and prompts the severe-tier token. Linux services live
+    # below ~1000; user-launched dev servers are typically >1000.
+    system_pid_threshold: int = Field(default=100, ge=1, le=65535)
+
+
 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)
 
 
 class PackageManagerEntry(_StrictModel):

src/shimkit/tools/ports/__init__.py

@@ -0,0 +1,13 @@
+"""Port owner inspection + killer — ``shimkit ports``.
+
+Cross-platform listing of which process holds each TCP/UDP port and a
+prompted kill helper for stuck dev servers. ``lsof`` drives the macOS
+path; ``ss`` drives the Linux path. No third-party deps.
+"""
+
+from __future__ import annotations
+
+from .manager import PortsManager
+from .models import PortOwner
+
+__all__ = ["PortOwner", "PortsManager"]