feat: ports with visibility

[parnexcodes]

Closes #22

What

Adds ports to the Python SDK: list, expose with visibility (public or private, private by default for a new port) and remove. The port type carries port, visibility, url and createdAt; unknown fields are tolerated. README section added.

Why

usedock/dock#92 added port visibility to POST /v1/docks/:id/ports and the port objects, and this SDK had no ports support. Exposing an already exposed port with a different visibility changes it; leaving it out keeps the current one. No ports scenario exists in sdk-scenarios, so scenarios are untouched.

How to verify

ruff check . && ruff format --check . && mypy && DOCK_SCENARIOS_DIR=<dock>/sdk-scenarios pytest -rs

Result: all pass, 103 passed and 9 skipped (live-API and CI-only).

Risk

Low. Additive API only; no existing method changes.

🤖 Generated with Claude Code

[parnexcodes]

Review: feat: ports with visibility

Verdict: SHIP

Verified against usedock/dock main (3b94716): GET /v1/docks/:id/ports (200, array), POST /v1/docks/:id/ports (201, body port 1..65535 + optional visibility public|private), DELETE /v1/docks/:id/ports/:port (200, { deleted: true }, 404 port_not_found). Port objects are { port, visibility, url (null while hosted ports are off), createdAt } inside the { ok, data } envelope; there is no hostname field. Omitted visibility: new port -> private, existing port -> unchanged (dock-ports.service.ts expose). Rows from before the visibility column default to public (migration 0008). All three routes are @AllowDockKey(), so dock-bound keys may call them for their own dock; the SDKs need nothing extra.

Blocking

None.

Non-blocking

1. src/usedock/errors.py - no typed subclass for port_not_found (404) / port_limit_reached (409) / ports_unavailable (503), unlike the connector and image codes. Callers can still match DockError.code.
2. README.md - port 2222 is reserved (400 validation_error) and the limit is 10 ports per dock (409 port_limit_reached); worth a sentence.
3. Cross-SDK: ports.remove returns None while JS returns { deleted }; the API only ever returns deleted: true on success, so nothing is lost.

Checks

• ruff check .: pass
• ruff format --check .: pass
• mypy: pass
• pytest (with sdk-scenarios): pass, 103 passed, 9 skipped
• CI: test (3.9, 3.13), cla, gitleaks all green