ctrlrelay 0.10.0__py3-none-any.whl

ctrlrelay/dashboard/__init__.py

@@ -0,0 +1,5 @@
+"""Dashboard client for ctrlrelay."""
+
+from ctrlrelay.dashboard.client import DashboardClient, EventPayload, HeartbeatPayload
+
+__all__ = ["DashboardClient", "EventPayload", "HeartbeatPayload"]

ctrlrelay/dashboard/client.py

@@ -0,0 +1,159 @@
+"""Dashboard client for event push and heartbeat."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+
+from ctrlrelay import __version__
+
+
+class HeartbeatPayload(BaseModel):
+    """Payload for heartbeat endpoint."""
+
+    node_id: str
+    timestamp: str = ""
+    version: str = __version__
+    uptime_seconds: int = 0
+    platform: str = ""
+    active_sessions: list[dict[str, Any]] = []
+    last_github_poll: str | None = None
+    last_github_poll_status: str = "ok"
+    repos_configured: int = 0
+    repos_active: int = 0
+
+    def model_post_init(self, __context: Any) -> None:
+        if not self.timestamp:
+            object.__setattr__(self, "timestamp", datetime.now(timezone.utc).isoformat())
+
+
+class EventPayload(BaseModel):
+    """Payload for event endpoint."""
+
+    level: str  # info, warning, error
+    pipeline: str  # secops, dev
+    repo: str
+    message: str
+    session_id: str | None = None
+    timestamp: str = ""
+    details: dict[str, Any] = {}
+
+    def model_post_init(self, __context: Any) -> None:
+        if not self.timestamp:
+            object.__setattr__(
+                self, "timestamp", datetime.now(timezone.utc).isoformat()
+            )
+
+
+@dataclass
+class DashboardClient:
+    """Client for dashboard API with offline queue."""
+
+    url: str
+    auth_token: str
+    node_id: str
+    queue_dir: Path | None = None
+    timeout: int = 30
+    max_retries: int = 3
+    _queue: list[dict[str, Any]] = field(default_factory=list, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.queue_dir:
+            self.queue_dir = Path(self.queue_dir)
+            self.queue_dir.mkdir(parents=True, exist_ok=True)
+            self._load_queue()
+
+    def _load_queue(self) -> None:
+        """Load queued events from disk."""
+        if not self.queue_dir:
+            return
+        queue_file = self.queue_dir / "event_queue.json"
+        if queue_file.exists():
+            try:
+                self._queue = json.loads(queue_file.read_text())
+            except json.JSONDecodeError:
+                self._queue = []
+
+    def _save_queue(self) -> None:
+        """Save queued events to disk."""
+        if not self.queue_dir:
+            return
+        queue_file = self.queue_dir / "event_queue.json"
+        queue_file.write_text(json.dumps(self._queue))
+
+    def _queue_event(self, event: EventPayload) -> None:
+        """Add event to offline queue."""
+        self._queue.append(event.model_dump())
+        self._save_queue()
+
+    async def push_event(self, event: EventPayload) -> bool:
+        """Push event to dashboard, queue on failure."""
+        payload = event.model_dump()
+        payload["node_id"] = self.node_id
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    f"{self.url}/event",
+                    json=payload,
+                    headers={"Authorization": f"Bearer {self.auth_token}"},
+                )
+                response.raise_for_status()
+                return True
+        except (httpx.HTTPError, httpx.TimeoutException):
+            self._queue_event(event)
+            return False
+
+    async def heartbeat(self, payload: HeartbeatPayload) -> bool:
+        """Send heartbeat to dashboard."""
+        data = payload.model_dump()
+        data["node_id"] = self.node_id
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.post(
+                    f"{self.url}/heartbeat",
+                    json=data,
+                    headers={"Authorization": f"Bearer {self.auth_token}"},
+                )
+                response.raise_for_status()
+                return True
+        except (httpx.HTTPError, httpx.TimeoutException):
+            return False
+
+    async def drain_queue(self) -> int:
+        """Attempt to send queued events. Returns count of successfully sent."""
+        if not self._queue:
+            return 0
+
+        sent = 0
+        remaining = []
+
+        for event_data in self._queue:
+            try:
+                async with httpx.AsyncClient(timeout=self.timeout) as client:
+                    event_data["node_id"] = self.node_id
+                    response = await client.post(
+                        f"{self.url}/event",
+                        json=event_data,
+                        headers={"Authorization": f"Bearer {self.auth_token}"},
+                    )
+                    response.raise_for_status()
+                    sent += 1
+            except (httpx.HTTPError, httpx.TimeoutException):
+                remaining.append(event_data)
+
+        self._queue = remaining
+        self._save_queue()
+        return sent
+
+    @property
+    def queue_size(self) -> int:
+        """Number of events in offline queue."""
+        return len(self._queue)

ctrlrelay/gh_protocol.py

@@ -0,0 +1,47 @@
+"""Detect the git transport protocol the operator has configured for
+GitHub via the ``gh`` CLI.
+
+``ctrlrelay`` clones a handful of GitHub repos on the operator's
+behalf (project repos, the personalization repo). Hardcoding HTTPS
+for these clones breaks operators who've set ``gh config set
+git_protocol ssh`` and have no HTTPS credential helper wired up —
+``git`` then fails with "could not read Username" instead of using
+the SSH key ``gh`` already knows about.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+_VALID_PROTOCOLS = ("ssh", "https")
+
+
+def detect_git_protocol(*, default: str = "https") -> str:
+    """Return ``"ssh"`` or ``"https"``, per ``gh config get git_protocol``.
+
+    Falls back to ``default`` whenever ``gh`` isn't installed, isn't
+    configured, or returns something unexpected — this is a
+    convenience read, not a hard requirement, so any failure here
+    should degrade to the previous hardcoded-HTTPS behavior rather
+    than blocking a clone.
+    """
+    try:
+        proc = subprocess.run(
+            ["gh", "config", "get", "git_protocol"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return default
+    value = proc.stdout.strip().lower()
+    if proc.returncode == 0 and value in _VALID_PROTOCOLS:
+        return value
+    return default
+
+
+def github_clone_url(repo: str, *, protocol: str) -> str:
+    """Build a clone URL for ``owner/repo`` under the given protocol."""
+    if protocol == "ssh":
+        return f"git@github.com:{repo}.git"
+    return f"https://github.com/{repo}.git"

ctrlrelay/install.py

@@ -0,0 +1,203 @@
+"""Render and install service unit files (launchd, systemd) from
+in-package templates.
+
+The bridge and poller are meant to run as supervised long-lived
+services. Hand-writing platform unit files is error-prone (absolute
+paths, label/filename consistency, exit-timeout values that prevent
+mid-cleanup SIGKILL) and historically left operator boxes with
+hard-coded ``/Users/$ME/...`` strings — fine on one machine, broken
+on the next.
+
+This module ships templates inside the package and exposes a small
+substitution + write helper so ``ctrlrelay install launchd|systemd``
+can produce ready-to-load files for whoever is running it. No
+``sudo``, no daemon-level paths — everything lives under the user's
+home directory.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import re
+import shutil
+import string
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+_TEMPLATE_VAR_RE = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+
+
+def _read_template(platform: str, name: str) -> str:
+    pkg = f"ctrlrelay.templates.{platform}"
+    return resources.files(pkg).joinpath(name).read_text(encoding="utf-8")
+
+
+def _substitute(text: str, values: dict[str, str]) -> str:
+    # We use Template.safe_substitute over plain str.format because the
+    # plist/systemd templates contain literal braces that .format would
+    # interpret. safe_substitute leaves unknown ${VAR} references intact
+    # rather than raising — useful for the bot-token placeholder when the
+    # operator hasn't exported the env var at install time.
+    return string.Template(text).safe_substitute(values)
+
+
+def _missing_vars(rendered: str) -> list[str]:
+    return sorted(set(_TEMPLATE_VAR_RE.findall(rendered)))
+
+
+@dataclass(frozen=True)
+class RenderedUnit:
+    """A rendered unit file ready to write to disk."""
+
+    platform: str  # "launchd" | "systemd"
+    service: str  # "bridge" | "poller"
+    content: str
+    target_path: Path
+    # Variables that were left unsubstituted (e.g. CTRLRELAY_TELEGRAM_TOKEN
+    # when the env var wasn't set at render time). Caller decides whether
+    # to warn the operator or refuse to write.
+    unresolved: list[str]
+
+
+def _build_substitution_values(
+    *,
+    workdir: Path,
+    label_prefix: str,
+    poller_interval: int,
+    ctrlrelay_bin: str | None = None,
+) -> dict[str, str]:
+    bin_path = ctrlrelay_bin or shutil.which("ctrlrelay") or "ctrlrelay"
+    home = Path.home()
+    values = {
+        "USER": getpass.getuser(),
+        "HOME": str(home),
+        "CTRLRELAY_BIN": bin_path,
+        "WORKDIR": str(workdir.expanduser()),
+        "LABEL_PREFIX": label_prefix,
+        "POLLER_INTERVAL": str(poller_interval),
+    }
+    # Pass through the bot token from the current environment if the
+    # operator has it exported at install time. Leaving it out means the
+    # placeholder survives in the rendered file and the operator must
+    # edit by hand — ``unresolved`` flags this.
+    token = os.environ.get("CTRLRELAY_TELEGRAM_TOKEN")
+    if token:
+        values["CTRLRELAY_TELEGRAM_TOKEN"] = token
+    return values
+
+
+def render_launchd(
+    *,
+    workdir: Path,
+    label_prefix: str = "com.ctrlrelay",
+    poller_interval: int = 300,
+    ctrlrelay_bin: str | None = None,
+    target_dir: Path | None = None,
+) -> list[RenderedUnit]:
+    """Render the bridge and poller launchd plists.
+
+    ``target_dir`` defaults to ``~/Library/LaunchAgents`` — override
+    in tests. The filename uses ``{label_prefix}.ctrlrelay-{service}.plist``
+    so it lines up with the ``<Label>`` value inside the plist (launchd
+    won't load otherwise).
+    """
+    values = _build_substitution_values(
+        workdir=workdir,
+        label_prefix=label_prefix,
+        poller_interval=poller_interval,
+        ctrlrelay_bin=ctrlrelay_bin,
+    )
+    target_dir = target_dir or Path.home() / "Library" / "LaunchAgents"
+    units: list[RenderedUnit] = []
+    for service in ("bridge", "poller"):
+        raw = _read_template("launchd", f"{service}.plist.template")
+        rendered = _substitute(raw, values)
+        target = target_dir / f"{label_prefix}.ctrlrelay-{service}.plist"
+        units.append(
+            RenderedUnit(
+                platform="launchd",
+                service=service,
+                content=rendered,
+                target_path=target,
+                unresolved=_missing_vars(rendered),
+            )
+        )
+    return units
+
+
+def render_systemd(
+    *,
+    workdir: Path,
+    poller_interval: int = 300,
+    ctrlrelay_bin: str | None = None,
+    target_dir: Path | None = None,
+) -> list[RenderedUnit]:
+    """Render the bridge and poller systemd user unit files.
+
+    ``target_dir`` defaults to ``~/.config/systemd/user`` — the canonical
+    location for user-scoped units (no root needed). systemd doesn't
+    require label_prefix-style namespacing the way launchd does, so the
+    filenames are fixed: ``ctrlrelay-{bridge,poller}.service``.
+    """
+    values = _build_substitution_values(
+        workdir=workdir,
+        # systemd templates don't reference LABEL_PREFIX, but the helper
+        # still needs the key for uniformity — pass an unused literal.
+        label_prefix="ctrlrelay",
+        poller_interval=poller_interval,
+        ctrlrelay_bin=ctrlrelay_bin,
+    )
+    target_dir = target_dir or Path.home() / ".config" / "systemd" / "user"
+    units: list[RenderedUnit] = []
+    for service in ("bridge", "poller"):
+        raw = _read_template("systemd", f"{service}.service.template")
+        rendered = _substitute(raw, values)
+        target = target_dir / f"ctrlrelay-{service}.service"
+        units.append(
+            RenderedUnit(
+                platform="systemd",
+                service=service,
+                content=rendered,
+                target_path=target,
+                unresolved=_missing_vars(rendered),
+            )
+        )
+    return units
+
+
+def write_units(
+    units: list[RenderedUnit],
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Write rendered units to their target paths.
+
+    Refuses to clobber an existing file unless ``overwrite=True`` —
+    silently overwriting an operator's customised plist would be a foot-gun.
+    Returns the list of paths actually written. Raises ``FileExistsError``
+    if any target exists and overwrite is False.
+
+    Also ensures ``~/.ctrlrelay/logs/`` exists — both the launchd and
+    systemd templates set StandardOutput/StandardError paths under it,
+    and systemd refuses to start a unit at all (EXIT_STDOUT, code 209)
+    when the directory is missing; combined with ``Restart=always``
+    that's an immediate crash-loop (#137).
+
+    Unit files are chmod'd ``0600`` after writing since they embed
+    ``CTRLRELAY_TELEGRAM_TOKEN`` as plaintext.
+    """
+    (Path.home() / ".ctrlrelay" / "logs").mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for unit in units:
+        unit.target_path.parent.mkdir(parents=True, exist_ok=True)
+        if unit.target_path.exists() and not overwrite:
+            raise FileExistsError(
+                f"refusing to overwrite {unit.target_path}; "
+                "pass --force to replace it"
+            )
+        unit.target_path.write_text(unit.content, encoding="utf-8")
+        unit.target_path.chmod(0o600)
+        written.append(unit.target_path)
+    return written

ctrlrelay/personalization/__init__.py

@@ -0,0 +1,26 @@
+"""Personalization sync — operator state shared across machines.
+
+A separate (typically private) GitHub repo holds context that survives
+across sessions and computers but doesn't belong inside any project's
+own source tree: global Claude config, per-project memory, spec docs,
+workspace planning notes. ctrlrelay clones this repo once per machine
+and wires symlinks per the ``personalization.paths`` config so that
+agent and operator writes flow straight into the working tree of the
+checkout, ready to commit.
+
+See ``manager.PersonalizationManager`` for the lifecycle.
+"""
+
+from ctrlrelay.personalization.manager import PersonalizationManager
+from ctrlrelay.personalization.paths import (
+    TemplateContext,
+    encode_project_path,
+    resolve_template,
+)
+
+__all__ = [
+    "PersonalizationManager",
+    "TemplateContext",
+    "encode_project_path",
+    "resolve_template",
+]