taskswarm-cli 0.1.0__py3-none-any.whl

taskswarm/cli.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""
+Argument-parsing entry point. Ported from src/cli.ts (which uses
+`commander`); this port uses the stdlib `argparse` to avoid a CLI-framework
+dependency. Subcommands, flags, and `--json` output shapes are kept
+equivalent to the npm CLI's `--help` output and behavior. Console entry
+points: `taskswarm` / `taskswarm-cli`, both installed via
+python/pyproject.toml's `[project.scripts]`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .adapters.claude_code_adapter import install_claude_code_hooks
+from .adapters.generic_adapter import GenericAdapter
+from .adapters.types import AdapterValidationError
+from .client.api_client import ApiClientError, get_sessions, post_event
+from .client.tasks_registry import TaskRecord, add_task, list_tasks
+from .schema.events import AGENT_STATUSES, AGENT_TYPES
+from .server.config import load_or_create_config, rotate_token
+from .server.server import start_server
+
+PACKAGE_VERSION = "0.1.0"
+
+
+def _print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2))
+
+
+def _fail(message: str, as_json: bool = False) -> None:
+    """Reports a command failure and sets a non-zero exit code. Honors the
+    CLI's `--json` contract: when the invocation requested `--json`, the
+    error is printed as parseable `{"error": "<message>"}` on stdout (never
+    stderr, so a caller piping/parsing stdout still gets valid JSON) instead
+    of the plain-text `Error: ...` message."""
+    if as_json:
+        _print_json({"error": message})
+    else:
+        print(f"Error: {message}", file=sys.stderr)
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    try:
+        running = start_server()
+    except OSError as error:
+        _fail(f"failed to start server: {error}", args.json)
+        return 1
+
+    if args.json:
+        _print_json({"url": running.url, "host": running.config.host, "port": running.config.port})
+    else:
+        print(f"TaskSwarm server listening on http://{running.config.host}:{running.config.port}")
+        print(f"Live status page: {running.url}")
+        print("Press Ctrl+C to stop.")
+
+    try:
+        while True:
+            import time
+
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        running.close()
+        return 0
+
+
+def _cmd_task_add(args: argparse.Namespace) -> int:
+    record = TaskRecord(
+        id=str(uuid.uuid4()),
+        title=args.title,
+        repo=args.repo,
+        created_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    )
+    try:
+        add_task(record)
+    except OSError as error:
+        _fail(f"failed to save task: {error}", args.json)
+        return 1
+
+    if args.json:
+        _print_json(record.to_dict())
+    else:
+        print(f"Task created: {record.id}")
+        print(f"  title: {record.title}")
+        print(f"  repo:  {record.repo}")
+    return 0
+
+
+def _cmd_task_list(args: argparse.Namespace) -> int:
+    tasks = list_tasks()
+    status_by_id: Dict[str, str] = {}
+    try:
+        config = load_or_create_config()
+        sessions = get_sessions(config.to_dict())
+        for session in sessions:
+            status_by_id[session["session_id"]] = session["latest"]["status"]
+    except ApiClientError:
+        # Server not running (or unreachable) -- task list still works, just
+        # without live status enrichment.
+        pass
+
+    rows = [{**task, "status": status_by_id.get(task["id"], "unknown")} for task in tasks]
+
+    if args.json:
+        _print_json(rows)
+        return 0
+    if len(rows) == 0:
+        print("No tasks yet. Create one with `taskswarm task add --title <t> --repo <path>`.")
+        return 0
+    for row in rows:
+        print(f"{row['id']}  [{row['status']}]  {row['title']}  ({row['repo']})")
+    return 0
+
+
+def _cmd_agent_report_status(args: argparse.Namespace) -> int:
+    adapter = GenericAdapter()
+    raw_input: Dict[str, Any] = {
+        "session_id": args.task,
+        "repo": args.repo,
+        "status": args.state,
+        "agent_type": args.agent_type,
+    }
+    if args.blocked_reason:
+        raw_input["blocked_reason"] = args.blocked_reason
+
+    try:
+        input_data = adapter.to_event_input(raw_input)
+        config = load_or_create_config()
+        event = post_event(config.to_dict(), input_data)
+    except (AdapterValidationError, ApiClientError) as error:
+        _fail(str(error), args.json)
+        return 1
+
+    if args.json:
+        _print_json(event)
+    else:
+        print(f"Reported {event['session_id']} -> {event['status']}")
+    return 0
+
+
+def _cmd_token_rotate(args: argparse.Namespace) -> int:
+    try:
+        new_token = rotate_token()
+    except OSError as error:
+        _fail(f"failed to rotate token: {error}", args.json)
+        return 1
+
+    if args.json:
+        _print_json({"token": new_token})
+    else:
+        print("Bearer token rotated. Update any configured clients/hooks with the new value:")
+        print(new_token)
+    return 0
+
+
+def _cmd_hooks_install(args: argparse.Namespace) -> int:
+    if args.adapter != "claude-code":
+        _fail(f'unknown adapter "{args.adapter}". Supported adapters: claude-code', args.json)
+        return 1
+    try:
+        result = install_claude_code_hooks(
+            scope=args.scope,
+            project_dir=args.project_dir,
+            home_dir=os.path.expanduser("~"),
+        )
+    except (AdapterValidationError, OSError) as error:
+        _fail(f"failed to install hooks: {error}", args.json)
+        return 1
+
+    if args.json:
+        _print_json(result.to_dict())
+    elif result.changed:
+        print(f"Installed Claude Code Stop/Notification hooks -> {result.settings_path}")
+    else:
+        print(f"Claude Code hooks already installed at {result.settings_path}")
+    return 0
+
+
+def _cmd_hooks_claude_code_relay(args: argparse.Namespace) -> int:
+    """Reads a Claude Code hook payload from stdin and relays it to the
+    local TaskSwarm server. Installed automatically by `taskswarm hooks
+    install claude-code`; not meant to be run by hand. This command must
+    never fail the hook (which could interrupt the coding session), so
+    every error path logs to stderr and still exits 0."""
+    from .adapters.claude_code_adapter import ClaudeCodeAdapter
+
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw)
+        adapter = ClaudeCodeAdapter()
+        input_data = adapter.to_event_input(payload)
+        config = load_or_create_config()
+        post_event(config.to_dict(), input_data)
+    except Exception as error:  # noqa: BLE001 -- must never propagate a nonzero exit into the hook
+        sys.stderr.write(f"taskswarm hook relay: {error}\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="taskswarm",
+        description=(
+            "Self-hosted, event-driven coordination for parallel coding-agent sessions "
+            "(Claude Code, Codex, Cursor)."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"taskswarm {PACKAGE_VERSION}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    start_parser = subparsers.add_parser(
+        "start", help="Start the TaskSwarm server and print the live status page URL"
+    )
+    start_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    start_parser.set_defaults(func=_cmd_start)
+
+    task_parser = subparsers.add_parser("task", help="Manage locally tracked tasks")
+    task_subparsers = task_parser.add_subparsers(dest="task_command")
+
+    task_add_parser = task_subparsers.add_parser("add", help="Register a new task")
+    task_add_parser.add_argument("--title", required=True, help="human-readable task title")
+    task_add_parser.add_argument("--repo", required=True, help="path to the repository the task operates on")
+    task_add_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    task_add_parser.set_defaults(func=_cmd_task_add)
+
+    task_list_parser = task_subparsers.add_parser(
+        "list", help="List tracked tasks, enriched with live status when the server is reachable"
+    )
+    task_list_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    task_list_parser.set_defaults(func=_cmd_task_list)
+
+    agent_parser = subparsers.add_parser("agent", help="Report agent session status")
+    agent_subparsers = agent_parser.add_subparsers(dest="agent_command")
+
+    report_status_parser = agent_subparsers.add_parser(
+        "report-status",
+        help="Report a status transition for a task/session to the local TaskSwarm server",
+    )
+    report_status_parser.add_argument("--task", required=True, help="task/session id (the id returned by `task add`)")
+    report_status_parser.add_argument("--repo", required=True, help="path to the repository the session operates on")
+    report_status_parser.add_argument("--state", required=True, choices=AGENT_STATUSES, help="new status")
+    report_status_parser.add_argument(
+        "--blocked-reason", dest="blocked_reason", default=None,
+        help="reason, shown when status is blocked/needs-review/failed",
+    )
+    report_status_parser.add_argument(
+        "--agent-type", dest="agent_type", choices=AGENT_TYPES, default="generic", help="reporting agent"
+    )
+    report_status_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    report_status_parser.set_defaults(func=_cmd_agent_report_status)
+
+    token_parser = subparsers.add_parser("token", help="Manage the API bearer token")
+    token_subparsers = token_parser.add_subparsers(dest="token_command")
+
+    token_rotate_parser = token_subparsers.add_parser(
+        "rotate", help="Generate a new bearer token, invalidating the old one"
+    )
+    token_rotate_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    token_rotate_parser.set_defaults(func=_cmd_token_rotate)
+
+    hooks_parser = subparsers.add_parser("hooks", help="Manage agent hook integrations")
+    hooks_subparsers = hooks_parser.add_subparsers(dest="hooks_command")
+
+    hooks_install_parser = hooks_subparsers.add_parser(
+        "install", help="Install TaskSwarm hooks for an agent integration (currently: claude-code)"
+    )
+    hooks_install_parser.add_argument("adapter", help="adapter name, e.g. claude-code")
+    hooks_install_parser.add_argument(
+        "--scope", choices=["project", "local", "user"], default="project",
+        help="settings.json scope to write hooks into",
+    )
+    hooks_install_parser.add_argument(
+        "--project-dir", dest="project_dir", default=os.getcwd(),
+        help="project directory (for project/local scope)",
+    )
+    hooks_install_parser.add_argument("--json", action="store_true", help="output machine-readable JSON")
+    hooks_install_parser.set_defaults(func=_cmd_hooks_install)
+
+    hooks_relay_parser = hooks_subparsers.add_parser(
+        "claude-code-relay",
+        help=(
+            "Internal: reads a Claude Code hook payload from stdin and relays it to the "
+            "local TaskSwarm server. Installed automatically by `taskswarm hooks install "
+            "claude-code`; not meant to be run by hand."
+        ),
+    )
+    hooks_relay_parser.set_defaults(func=_cmd_hooks_claude_code_relay)
+
+    return parser
+
+
+def run_cli(argv: List[str]) -> int:
+    """`argv` follows the sys.argv convention: argv[0] is the program name,
+    the real arguments start at argv[1]. Returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv[1:])
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+def main() -> None:
+    try:
+        code = run_cli(sys.argv)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as error:  # noqa: BLE001 -- top-level crash guard, mirrors src/cli.ts's catch-all
+        print(str(error), file=sys.stderr)
+        sys.exit(1)
+    else:
+        sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

taskswarm/client/api_client.py

@@ -0,0 +1,61 @@
+"""Talks to the local TaskSwarm server over HTTP. Ported from
+src/cli/api-client.ts. Uses only `urllib.request` -- no HTTP client
+dependency, matching the zero-runtime-dependency goal of this package."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List
+
+
+class ApiClientError(Exception):
+    def __init__(self, message: str, context: Any = None) -> None:
+        super().__init__(message)
+        self.context = context
+
+
+def _base_url(host: str, port: int) -> str:
+    return f"http://{host}:{port}"
+
+
+def post_event(config: Dict[str, Any], input_data: Dict[str, Any]) -> Dict[str, Any]:
+    """POSTs an event to the local TaskSwarm server. Raises ApiClientError on any failure."""
+    base_url = _base_url(config["host"], config["port"])
+    request = urllib.request.Request(
+        f"{base_url}/events",
+        data=json.dumps(input_data).encode("utf-8"),
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {config['token']}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        body = error.read().decode("utf-8", errors="replace")
+        raise ApiClientError(f"server rejected event ({error.code}): {body}") from error
+    except urllib.error.URLError as error:
+        raise ApiClientError(
+            f"could not reach TaskSwarm server at {base_url} -- is it running? (`taskswarm start`)",
+            error,
+        ) from error
+
+
+def get_sessions(config: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """GETs current session states from the local TaskSwarm server."""
+    base_url = _base_url(config["host"], config["port"])
+    request = urllib.request.Request(
+        f"{base_url}/events",
+        headers={"Authorization": f"Bearer {config['token']}"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            data = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        raise ApiClientError(f"server returned {error.code}") from error
+    except urllib.error.URLError as error:
+        raise ApiClientError(f"could not reach TaskSwarm server at {base_url}", error) from error
+    return data.get("sessions", [])

taskswarm/client/tasks_registry.py

@@ -0,0 +1,119 @@
+"""Local, server-independent registry of tasks the user has created via
+`taskswarm task add`. TaskSwarm's wire schema (AgentEvent) is intentionally
+generic and has no `title` field, so human-friendly titles live here rather
+than on the server -- `task add` works even before the server has ever been
+started. Ported from src/cli/tasks-registry.ts."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..server.config import get_taskswarm_home
+from ..util.sync_sleep import sleep_sync_ms
+
+
+@dataclass
+class TaskRecord:
+    id: str
+    title: str
+    repo: str
+    created_at: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def get_tasks_registry_path() -> str:
+    return str(Path(get_taskswarm_home()) / "tasks.json")
+
+
+def _ensure_home_dir(path: str) -> None:
+    directory = os.path.dirname(path)
+    if directory and not os.path.exists(directory):
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+
+
+def list_tasks() -> List[Dict[str, Any]]:
+    path = get_tasks_registry_path()
+    if not os.path.exists(path):
+        return []
+    raw = Path(path).read_text(encoding="utf-8").strip()
+    if len(raw) == 0:
+        return []
+    return json.loads(raw)
+
+
+_LOCK_RETRY_DELAY_MS = 10
+_LOCK_TIMEOUT_MS = 5000
+# A lock older than this is assumed to be left behind by a crashed process.
+_STALE_LOCK_MS = 10000
+
+
+def _lock_path_for(registry_path: str) -> str:
+    return f"{registry_path}.lock"
+
+
+def _acquire_lock(lock_path: str) -> None:
+    """Acquires an exclusive lock by atomically creating `lock_path`
+    (O_CREAT|O_EXCL, so exactly one concurrent caller can win). Retries with
+    backoff while the lock is held by someone else, reclaiming it if it
+    looks abandoned (e.g. the holder crashed before releasing it) so a dead
+    lock file can never wedge the CLI forever."""
+    deadline = time.monotonic() + (_LOCK_TIMEOUT_MS / 1000.0)
+    while True:
+        try:
+            fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.close(fd)
+            return
+        except FileExistsError:
+            try:
+                age_ms = (time.time() - os.stat(lock_path).st_mtime) * 1000
+                if age_ms > _STALE_LOCK_MS:
+                    os.unlink(lock_path)
+                    continue
+            except FileNotFoundError:
+                # Lock vanished between our EEXIST and this stat (the holder
+                # just finished) -- loop around and try to acquire it again.
+                continue
+            if time.monotonic() > deadline:
+                raise TimeoutError(
+                    f"timed out waiting for the tasks registry lock at {lock_path} "
+                    "(another taskswarm process may be stuck)"
+                )
+            sleep_sync_ms(_LOCK_RETRY_DELAY_MS)
+
+
+def _release_lock(lock_path: str) -> None:
+    try:
+        os.unlink(lock_path)
+    except FileNotFoundError:
+        # best-effort: if it's already gone (e.g. reclaimed as stale by
+        # another waiter) there's nothing left to release.
+        pass
+
+
+def add_task(record: TaskRecord) -> None:
+    """Registers a new task. Guarded by a lockfile around the
+    read-modify-write cycle so concurrent add_task() calls (e.g. several
+    agent sessions starting at once) never race: without it, two callers
+    can both read the same on-disk list, each append their own record in
+    memory, and the second write silently overwrites the first caller's
+    write, dropping a task with no error."""
+    path = get_tasks_registry_path()
+    _ensure_home_dir(path)
+    lock_path = _lock_path_for(path)
+    _acquire_lock(lock_path)
+    try:
+        tasks = list_tasks()
+        tasks.append(record.to_dict())
+        Path(path).write_text(json.dumps(tasks, indent=2) + "\n", encoding="utf-8")
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+    finally:
+        _release_lock(lock_path)

taskswarm/notifications/__init__.py

@@ -0,0 +1,3 @@
+from .dispatch import NotifyOptions, notify, should_notify
+
+__all__ = ["NotifyOptions", "notify", "should_notify"]

taskswarm/notifications/dispatch.py

@@ -0,0 +1,88 @@
+"""Decides whether a status transition warrants a notification, and fires
+the enabled channels. Ported from src/notify/index.ts."""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional
+
+from ..schema.events import AgentEvent, NOTIFY_ON_STATUSES
+from .ntfy import send_ntfy_notification
+from .os_notify import send_os_notification
+
+
+@dataclass
+class NotifyOptions:
+    ntfy: Optional[Dict[str, Any]] = None
+    # Injectable for tests; defaults to the real OS notifier.
+    os_notifier: Optional[Callable[[str, str], None]] = None
+    # Injectable for tests; defaults to the real ntfy.sh sender.
+    ntfy_sender: Optional[Callable[[str, str, str], None]] = None
+    # Called whenever the ntfy channel raises, so failures never crash the server.
+    on_ntfy_error: Optional[Callable[[BaseException], None]] = None
+
+
+def should_notify(
+    status: str,
+    previous_status: Optional[str],
+    blocked_reason: Optional[str] = None,
+    previous_blocked_reason: Optional[str] = None,
+) -> bool:
+    """True if a transition from `previous_status`/`previous_blocked_reason`
+    to `status`/`blocked_reason` should notify.
+
+    Dedup keys on the (status, blocked_reason) pair, not status alone: two
+    different permission prompts in a row are both 'needs-review', and two
+    distinct idle nudges in a row are both 'blocked', but each carries a
+    different (or newly-present) blocked_reason and is a genuinely new event
+    a human should see -- not a duplicate to swallow. Only a same-status
+    event whose blocked_reason also didn't change is treated as a repeat."""
+    if status not in NOTIFY_ON_STATUSES:
+        return False
+    if status != previous_status:
+        return True
+    return blocked_reason != previous_blocked_reason
+
+
+def _format_message(event: AgentEvent) -> "tuple[str, str]":
+    title = f"TaskSwarm: {event.session_id} {event.status}"
+    parts = [f"repo: {event.repo}", f"agent: {event.agent_type}"]
+    if event.blocked_reason:
+        parts.append(f"reason: {event.blocked_reason}")
+    return title, " | ".join(parts)
+
+
+def notify(
+    event: AgentEvent,
+    previous_status: Optional[str],
+    previous_blocked_reason: Optional[str],
+    options: Optional[NotifyOptions] = None,
+) -> None:
+    """Evaluates an event against its session's previous status/
+    blocked_reason and fires the enabled notification channels if the
+    transition warrants it. Local OS notification is always-on; ntfy.sh
+    only fires when explicitly opted in."""
+    options = options or NotifyOptions()
+    if not should_notify(event.status, previous_status, event.blocked_reason, previous_blocked_reason):
+        return
+
+    title, message = _format_message(event)
+    os_notifier = options.os_notifier or send_os_notification
+    os_notifier(title, message)
+
+    ntfy_config = options.ntfy or {}
+    if ntfy_config.get("enabled") and ntfy_config.get("topicUrl"):
+        ntfy_sender = options.ntfy_sender or send_ntfy_notification
+
+        def _fire() -> None:
+            try:
+                ntfy_sender(ntfy_config["topicUrl"], title, message)
+            except Exception as error:  # noqa: BLE001 -- notification channel must never raise into the caller
+                if options.on_ntfy_error:
+                    options.on_ntfy_error(error)
+
+        # Fire-and-forget, same as the TS version's un-awaited
+        # `ntfySender(...).catch(...)`: the network call to ntfy.sh must
+        # never block the HTTP response path for the /events POST that
+        # triggered it.
+        threading.Thread(target=_fire, daemon=True).start()

taskswarm/notifications/ntfy.py

@@ -0,0 +1,61 @@
+"""ntfy.sh channel -- explicitly opt-in only. Never called unless the caller
+has an enabled ntfy config with a topic URL; TaskSwarm's "self-hosted by
+default" claim depends on this never firing implicitly. Ported from
+src/notify/ntfy.ts."""
+from __future__ import annotations
+
+import re
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+_PRIVATE_OR_LINK_LOCAL_IPV4 = [
+    re.compile(r"^10\."),
+    re.compile(r"^172\.(1[6-9]|2\d|3[01])\."),
+    re.compile(r"^192\.168\."),
+    re.compile(r"^169\.254\."),  # includes cloud metadata endpoints, e.g. 169.254.169.254
+    re.compile(r"^0\."),
+]
+
+
+def validate_ntfy_url(topic_url: str):
+    """Rejects a topic URL that isn't https (unless it targets loopback,
+    useful for a local self-hosted ntfy instance during testing) or that
+    targets a private/link-local address -- guards against a misconfigured
+    or tampered config.json silently sending event data in plaintext or to
+    an internal/metadata endpoint."""
+    parsed = urlparse(topic_url)
+    if not parsed.scheme or not parsed.hostname:
+        raise ValueError(f'invalid ntfy topic URL: "{topic_url}"')
+    hostname = parsed.hostname
+    is_loopback = hostname in ("localhost", "127.0.0.1", "::1")
+    if parsed.scheme != "https" and not is_loopback:
+        raise ValueError(
+            f'ntfy topic URL must use https:// (got "{parsed.scheme}") -- plaintext http:// '
+            "is only allowed for a loopback host, to avoid sending notification content "
+            "unencrypted over a network"
+        )
+    if not is_loopback and any(pattern.match(hostname) for pattern in _PRIVATE_OR_LINK_LOCAL_IPV4):
+        raise ValueError(
+            f'ntfy topic URL host "{hostname}" is a private/link-local address -- refusing to '
+            "send notifications there by default"
+        )
+    return parsed
+
+
+def send_ntfy_notification(topic_url: str, title: str, message: str) -> None:
+    validate_ntfy_url(topic_url)
+    request = urllib.request.Request(
+        topic_url,
+        data=message.encode("utf-8"),
+        method="POST",
+        headers={"Title": title, "Priority": "default"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            if response.status >= 400:
+                raise RuntimeError(f"ntfy.sh notification failed: {response.status}")
+    except urllib.error.HTTPError as error:
+        raise RuntimeError(f"ntfy.sh notification failed: {error.code} {error.reason}") from error
+    except urllib.error.URLError as error:
+        raise RuntimeError(f"ntfy.sh notification failed: {error.reason}") from error