alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/service_install.py

@@ -0,0 +1,616 @@
+"""Install / enable / disable host service units for alter-runtime.
+
+Handles three platforms:
+
+* **Linux** via systemd *user* units. We install to
+  ``~/.config/systemd/user/alter-runtime.service``, run
+  ``systemctl --user daemon-reload`` + ``systemctl --user enable --now``,
+  and tear down symmetrically on uninstall. User units avoid needing
+  sudo and match the per-user security model (JWT, XDG paths, etc.).
+* **macOS** via launchd *LaunchAgents*. We install to
+  ``~/Library/LaunchAgents/com.alter.runtime.plist``, bootstrap into
+  the current GUI session with ``launchctl bootstrap``, and log to
+  ``~/Library/Logs/alter-runtime/``.
+* **Windows** - stubbed out. Wave 3 stream 3b ships the ``pywin32``-based
+  Windows Service wrapper.
+
+The module exposes a small, testable surface:
+
+* :func:`render_systemd_unit` / :func:`render_launchd_plist` - pure string
+  templating (read the template, substitute placeholders, return the
+  rendered body). No filesystem writes, so tests can assert on the output.
+* :func:`install` / :func:`uninstall` - platform-dispatching wrappers
+  that call into the concrete implementations.
+* :func:`service_status` - reports whether the unit is installed /
+  loaded / running. Used by ``alter-runtime status``.
+
+All writes are idempotent; re-running ``install`` overwrites the existing
+unit file with a freshly rendered copy so operators can pick up template
+changes by re-running a single command.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from alter_runtime.services import (
+    launchd_template_path,
+    systemd_cf_access_dropin_template_path,
+    systemd_template_path,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "ServiceStatus",
+    "current_platform",
+    "install",
+    "launchd_plist_install_path",
+    "render_launchd_plist",
+    "render_systemd_cf_access_dropin",
+    "render_systemd_unit",
+    "resolve_runtime_binary",
+    "service_status",
+    "systemd_cf_access_dropin_install_path",
+    "systemd_unit_install_path",
+    "uninstall",
+]
+
+logger = logging.getLogger("alter_runtime.service_install")
+
+SYSTEMD_UNIT_NAME: str = "alter-runtime.service"
+LAUNCHD_LABEL: str = "com.alter.runtime"
+LAUNCHD_PLIST_NAME: str = f"{LAUNCHD_LABEL}.plist"
+
+
+# ---------------------------------------------------------------------------
+# Platform detection
+# ---------------------------------------------------------------------------
+
+
+def current_platform() -> str:
+    """Return one of ``"linux"``, ``"darwin"``, ``"windows"``, or ``"other"``.
+
+    Kept as a public helper so the CLI can produce helpful error messages
+    on unsupported platforms without duplicating the platform-check logic.
+    """
+    if sys.platform.startswith("linux"):
+        return "linux"
+    if sys.platform == "darwin":
+        return "darwin"
+    if sys.platform == "win32":
+        return "windows"
+    return "other"
+
+
+# ---------------------------------------------------------------------------
+# Binary resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_runtime_binary() -> Path:
+    """Return the absolute path of the installed ``alter-runtime`` entry point.
+
+    ``pip install alter-runtime`` drops a console script at whatever bin
+    directory the active Python environment is using; we find it via
+    ``shutil.which`` (which respects ``$PATH``) and fall back to
+    ``sys.executable + ` -m alter_runtime.cli``` semantics as a last
+    resort. Returning a ``Path`` (rather than a string) lets callers
+    cleanly assert on filesystem checks.
+    """
+    from_path = shutil.which("alter-runtime")
+    if from_path:
+        return Path(from_path).resolve()
+
+    # Fallback: try the same directory as the current Python interpreter.
+    sibling = Path(sys.executable).parent / "alter-runtime"
+    if sibling.exists():
+        return sibling.resolve()
+
+    raise FileNotFoundError(
+        "alter-runtime entry point not found on PATH or next to the current "
+        "Python interpreter. Install the package first with `pip install -e .` "
+        "from the packages/alter-runtime directory, or `pip install alter-runtime`."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Template rendering
+# ---------------------------------------------------------------------------
+
+
+def _substitute(body: str, mapping: dict[str, str]) -> str:
+    """Replace ``@KEY@`` placeholders in ``body`` using ``mapping``."""
+    out = body
+    for key, value in mapping.items():
+        out = out.replace(f"@{key}@", value)
+    return out
+
+
+def render_systemd_unit(
+    binary_path: Path | None = None,
+    home: Path | None = None,
+) -> str:
+    """Render the systemd unit template with the current binary path.
+
+    Parameters
+    ----------
+    binary_path:
+        Override for the ``@ALTER_RUNTIME_BIN@`` placeholder. Defaults to
+        :func:`resolve_runtime_binary`.
+    home:
+        Override for the ``@ALTER_RUNTIME_HOME@`` placeholder. Defaults to
+        ``Path.home()``.
+    """
+    binary_path = binary_path or resolve_runtime_binary()
+    home = home or Path.home()
+    template = systemd_template_path().read_text(encoding="utf-8")
+    return _substitute(
+        template,
+        {
+            "ALTER_RUNTIME_BIN": str(binary_path),
+            "ALTER_RUNTIME_HOME": str(home),
+        },
+    )
+
+
+def render_systemd_cf_access_dropin() -> str:
+    """Render the CF Access env drop-in template.
+
+    The template is a static drop-in for the main systemd user unit —
+    it pulls ``CF_ACCESS_CLIENT_ID`` + ``CF_ACCESS_CLIENT_SECRET`` from
+    ``~/.config/alter/cf-access.env`` into the daemon's process
+    environment so the httpx clients can inject the CF Access
+    service-token headers required by the production edge at
+    ``mcp.truealter.com``.
+
+    Currently the template has no placeholders (it uses systemd's ``%h``
+    specifier for the user home), but the function follows the same
+    shape as :func:`render_systemd_unit` for future-proofing — adding
+    placeholders later does not change the call sites.
+    """
+    return systemd_cf_access_dropin_template_path().read_text(encoding="utf-8")
+
+
+def render_launchd_plist(
+    binary_path: Path | None = None,
+    log_dir: Path | None = None,
+    home: Path | None = None,
+) -> str:
+    """Render the launchd plist template with the current binary path."""
+    binary_path = binary_path or resolve_runtime_binary()
+    home = home or Path.home()
+    log_dir = log_dir or (home / "Library" / "Logs" / "alter-runtime")
+    template = launchd_template_path().read_text(encoding="utf-8")
+    return _substitute(
+        template,
+        {
+            "ALTER_RUNTIME_BIN": str(binary_path),
+            "ALTER_RUNTIME_HOME": str(home),
+            "ALTER_RUNTIME_LOG_DIR": str(log_dir),
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Install paths
+# ---------------------------------------------------------------------------
+
+
+def systemd_unit_install_path() -> Path:
+    """Return the path where the systemd user unit should be written."""
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return base / "systemd" / "user" / SYSTEMD_UNIT_NAME
+
+
+def systemd_cf_access_dropin_install_path() -> Path:
+    """Return the path where the CF Access env drop-in should be written.
+
+    Drop-ins for a user unit live in ``<unit>.service.d/`` next to the
+    main unit file. systemd merges every ``*.conf`` in that directory
+    into the parent unit at daemon-reload time.
+    """
+    return systemd_unit_install_path().parent / (SYSTEMD_UNIT_NAME + ".d") / "cf-access-env.conf"
+
+
+def launchd_plist_install_path() -> Path:
+    """Return the path where the launchd LaunchAgent plist should be written."""
+    return Path.home() / "Library" / "LaunchAgents" / LAUNCHD_PLIST_NAME
+
+
+# ---------------------------------------------------------------------------
+# Install / uninstall
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InstallResult:
+    """Outcome of an :func:`install` call - what was written + what ran."""
+
+    platform: str
+    unit_path: Path
+    rendered: str
+    service_commands: list[list[str]]
+    command_results: list[tuple[list[str], int]]
+
+
+def install(
+    *,
+    enable: bool = True,
+    dry_run: bool = False,
+    binary_path: Path | None = None,
+    reinstall: bool = False,
+) -> InstallResult:
+    """Install the host service unit for the current platform.
+
+    Parameters
+    ----------
+    enable:
+        When ``True`` (the default), also run ``systemctl --user enable
+        --now`` (Linux) or ``launchctl bootstrap`` (macOS) to start the
+        daemon immediately. Set to ``False`` for a file-only install.
+    dry_run:
+        When ``True``, render + return the rendered unit body but do not
+        touch the filesystem or invoke any service manager command. Used
+        by the CLI to preview without side effects.
+    binary_path:
+        Override for the resolved ``alter-runtime`` binary - tests pass a
+        fake path to check templating without requiring the script to be
+        installed.
+    reinstall:
+        When ``True``, bypass the deletion-permanence tombstone check.
+        Corresponds to the ``--reinstall`` CLI flag.
+    """
+    platform = current_platform()
+    if platform == "linux":
+        return _install_systemd(
+            enable=enable, dry_run=dry_run, binary_path=binary_path, reinstall=reinstall
+        )
+    if platform == "darwin":
+        return _install_launchd(
+            enable=enable, dry_run=dry_run, binary_path=binary_path, reinstall=reinstall
+        )
+    if platform == "windows":
+        raise NotImplementedError("Windows Service install lands in Wave 3 stream 3b (D-RT1).")
+    raise NotImplementedError(f"unsupported platform: {sys.platform}")
+
+
+def uninstall() -> list[tuple[list[str], int]]:
+    """Disable + remove the host service unit for the current platform.
+
+    Returns a list of ``(command, exit_code)`` tuples for every shell
+    invocation the uninstaller ran (empty on platforms that only need a
+    file delete).
+    """
+    platform = current_platform()
+    if platform == "linux":
+        return _uninstall_systemd()
+    if platform == "darwin":
+        return _uninstall_launchd()
+    if platform == "windows":
+        raise NotImplementedError("Windows Service uninstall lands in Wave 3 stream 3b.")
+    raise NotImplementedError(f"unsupported platform: {sys.platform}")
+
+
+# ---------------------------------------------------------------------------
+# systemd (Linux)
+# ---------------------------------------------------------------------------
+
+
+def _install_systemd(
+    *,
+    enable: bool,
+    dry_run: bool,
+    binary_path: Path | None,
+    reinstall: bool = False,
+) -> InstallResult:
+    unit_body = render_systemd_unit(binary_path=binary_path)
+    unit_path = systemd_unit_install_path()
+
+    commands: list[list[str]] = [
+        ["systemctl", "--user", "daemon-reload"],
+    ]
+    if enable:
+        commands.append(
+            ["systemctl", "--user", "enable", "--now", SYSTEMD_UNIT_NAME],
+        )
+
+    if dry_run:
+        return InstallResult(
+            platform="linux",
+            unit_path=unit_path,
+            rendered=unit_body,
+            service_commands=commands,
+            command_results=[],
+        )
+
+    # C3 - deletion-permanence guard. Refuse to recreate a unit file the
+    # user previously removed unless --reinstall was passed explicitly.
+    if not reinstall:
+        from alter_runtime.consent import UserDeletedArtefact, is_tombstoned
+
+        if is_tombstoned(unit_path):
+            raise UserDeletedArtefact(unit_path)
+
+    unit_path.parent.mkdir(parents=True, exist_ok=True)
+    unit_path.write_text(unit_body, encoding="utf-8")
+    try:
+        unit_path.chmod(0o644)
+    except OSError:
+        pass
+    logger.info("wrote systemd unit to %s", unit_path)
+
+    # CF Access env drop-in (D-SUBSTRATE-UNIFIED-1 §2.3 Option A) — lands
+    # alongside the main unit so the daemon's httpx clients inherit the
+    # service-token env-vars from ~/.config/alter/cf-access.env on every
+    # restart. EnvironmentFile in the drop-in uses a leading "-" so a
+    # missing envfile is non-fatal; dev hosts without CF Access still
+    # boot cleanly.
+    dropin_body = render_systemd_cf_access_dropin()
+    dropin_path = systemd_cf_access_dropin_install_path()
+    dropin_path.parent.mkdir(parents=True, exist_ok=True)
+    dropin_path.write_text(dropin_body, encoding="utf-8")
+    try:
+        dropin_path.chmod(0o644)
+    except OSError:
+        pass
+    logger.info("wrote systemd CF Access drop-in to %s", dropin_path)
+
+    results = _run_commands(commands)
+    return InstallResult(
+        platform="linux",
+        unit_path=unit_path,
+        rendered=unit_body,
+        service_commands=commands,
+        command_results=results,
+    )
+
+
+def _uninstall_systemd() -> list[tuple[list[str], int]]:
+    results = _run_commands(
+        [
+            ["systemctl", "--user", "disable", "--now", SYSTEMD_UNIT_NAME],
+            ["systemctl", "--user", "daemon-reload"],
+        ]
+    )
+    unit_path = systemd_unit_install_path()
+    if unit_path.exists():
+        try:
+            unit_path.unlink()
+            logger.info("removed systemd unit %s", unit_path)
+        except OSError as exc:
+            logger.warning("could not delete %s: %s", unit_path, exc)
+    # Remove the CF Access drop-in we installed. The drop-in directory
+    # may hold other operator-authored drop-ins (memory caps, eBPF
+    # hardening, repo overrides); we only touch the one we wrote.
+    dropin_path = systemd_cf_access_dropin_install_path()
+    if dropin_path.exists():
+        try:
+            dropin_path.unlink()
+            logger.info("removed systemd CF Access drop-in %s", dropin_path)
+        except OSError as exc:
+            logger.warning("could not delete %s: %s", dropin_path, exc)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# launchd (macOS)
+# ---------------------------------------------------------------------------
+
+
+def _install_launchd(
+    *,
+    enable: bool,
+    dry_run: bool,
+    binary_path: Path | None,
+    reinstall: bool = False,
+) -> InstallResult:
+    plist_body = render_launchd_plist(binary_path=binary_path)
+    plist_path = launchd_plist_install_path()
+    log_dir = Path.home() / "Library" / "Logs" / "alter-runtime"
+
+    try:
+        uid = os.getuid()  # type: ignore[attr-defined]
+    except AttributeError:
+        uid = 0  # pragma: no cover - macOS always has getuid
+
+    commands: list[list[str]] = []
+    if enable:
+        commands.append(
+            ["launchctl", "bootstrap", f"gui/{uid}", str(plist_path)],
+        )
+        commands.append(
+            ["launchctl", "kickstart", "-k", f"gui/{uid}/{LAUNCHD_LABEL}"],
+        )
+
+    if dry_run:
+        return InstallResult(
+            platform="darwin",
+            unit_path=plist_path,
+            rendered=plist_body,
+            service_commands=commands,
+            command_results=[],
+        )
+
+    # C3 - deletion-permanence guard (launchd).
+    if not reinstall:
+        from alter_runtime.consent import UserDeletedArtefact, is_tombstoned
+
+        if is_tombstoned(plist_path):
+            raise UserDeletedArtefact(plist_path)
+
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    plist_path.write_text(plist_body, encoding="utf-8")
+    try:
+        plist_path.chmod(0o644)
+    except OSError:
+        pass
+    logger.info("wrote launchd plist to %s", plist_path)
+
+    results = _run_commands(commands)
+    return InstallResult(
+        platform="darwin",
+        unit_path=plist_path,
+        rendered=plist_body,
+        service_commands=commands,
+        command_results=results,
+    )
+
+
+def _uninstall_launchd() -> list[tuple[list[str], int]]:
+    try:
+        uid = os.getuid()  # type: ignore[attr-defined]
+    except AttributeError:
+        uid = 0
+
+    results = _run_commands(
+        [
+            ["launchctl", "bootout", f"gui/{uid}/{LAUNCHD_LABEL}"],
+        ]
+    )
+    plist_path = launchd_plist_install_path()
+    if plist_path.exists():
+        try:
+            plist_path.unlink()
+            logger.info("removed launchd plist %s", plist_path)
+        except OSError as exc:
+            logger.warning("could not delete %s: %s", plist_path, exc)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Status
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ServiceStatus:
+    """Snapshot of the host service's installation and running state."""
+
+    platform: str
+    installed: bool
+    active: bool
+    unit_path: Path
+    status_line: str
+
+
+def service_status() -> ServiceStatus:
+    """Report whether the service unit is installed + running.
+
+    The active-state probe is a best-effort ``systemctl is-active`` /
+    ``launchctl print`` call - if the service manager itself is missing
+    (e.g. headless container without systemd) we return
+    ``active=False`` and a status line explaining why.
+    """
+    platform = current_platform()
+    if platform == "linux":
+        unit_path = systemd_unit_install_path()
+        installed = unit_path.exists()
+        active = False
+        status_line = "not installed"
+        if installed:
+            exit_code, stdout = _capture(["systemctl", "--user", "is-active", SYSTEMD_UNIT_NAME])
+            active = exit_code == 0 and stdout.strip() == "active"
+            status_line = stdout.strip() or f"systemctl exit={exit_code}"
+        return ServiceStatus(
+            platform=platform,
+            installed=installed,
+            active=active,
+            unit_path=unit_path,
+            status_line=status_line,
+        )
+
+    if platform == "darwin":
+        plist_path = launchd_plist_install_path()
+        installed = plist_path.exists()
+        active = False
+        status_line = "not installed"
+        if installed:
+            try:
+                uid = os.getuid()  # type: ignore[attr-defined]
+            except AttributeError:
+                uid = 0
+            exit_code, stdout = _capture(["launchctl", "print", f"gui/{uid}/{LAUNCHD_LABEL}"])
+            active = exit_code == 0 and "state = running" in stdout
+            status_line = "running" if active else f"launchctl exit={exit_code}"
+        return ServiceStatus(
+            platform=platform,
+            installed=installed,
+            active=active,
+            unit_path=plist_path,
+            status_line=status_line,
+        )
+
+    return ServiceStatus(
+        platform=platform,
+        installed=False,
+        active=False,
+        unit_path=Path("/"),
+        status_line=f"unsupported platform: {sys.platform}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Subprocess helpers
+# ---------------------------------------------------------------------------
+
+
+def _run_commands(commands: Sequence[Sequence[str]]) -> list[tuple[list[str], int]]:
+    """Run each command in order, collecting exit codes. Non-fatal on failure.
+
+    We log warnings on non-zero exits rather than raising so that a missing
+    ``systemctl`` (e.g. inside a non-systemd container) doesn't crash
+    ``alter-runtime install`` - the file write still succeeds and the
+    operator can enable the unit manually.
+    """
+    results: list[tuple[list[str], int]] = []
+    for cmd in commands:
+        cmd_list = list(cmd)
+        try:
+            completed = subprocess.run(  # noqa: S603 - trusted args
+                cmd_list,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        except FileNotFoundError:
+            logger.warning("command not found: %s - skipping", cmd_list[0])
+            results.append((cmd_list, 127))
+            continue
+        if completed.returncode != 0:
+            logger.warning(
+                "%s exited %d stderr=%r",
+                " ".join(cmd_list),
+                completed.returncode,
+                completed.stderr.strip()[:256],
+            )
+        results.append((cmd_list, completed.returncode))
+    return results
+
+
+def _capture(cmd: Sequence[str]) -> tuple[int, str]:
+    """Run ``cmd`` and return ``(exit_code, stdout)``.
+
+    Missing binaries yield ``(127, "")`` so callers can treat them as
+    "not installed" without branching on ``FileNotFoundError``.
+    """
+    try:
+        completed = subprocess.run(  # noqa: S603
+            list(cmd),
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return 127, ""
+    return completed.returncode, completed.stdout

alter_runtime/services/__init__.py

@@ -0,0 +1,59 @@
+"""Host service unit templates for alter-runtime (Wave 2 stream 2c).
+
+Contains the platform-specific unit files that make the daemon a long-lived
+system service:
+
+* ``systemd/alter-runtime.service.in`` - template for a systemd *user* unit
+  installed to ``~/.config/systemd/user/alter-runtime.service``. User units
+  are preferred over system units because the daemon holds a user-scoped
+  JWT and writes into ``$XDG_RUNTIME_DIR`` / ``$XDG_DATA_HOME`` - both of
+  which live under the user's account.
+* ``launchd/com.alter.runtime.plist.in`` - template for a launchd
+  *LaunchAgent* installed to ``~/Library/LaunchAgents/com.alter.runtime.plist``
+  on macOS. Agents run at per-user login (as opposed to daemons which run
+  at boot and need elevated privileges).
+* ``windows/`` - reserved for the Windows Service wrapper shipped in Wave 3
+  stream 3b.
+
+The unit files are templates because the installed binary path is not
+known until install time: ``pip install alter-runtime`` drops the entry
+point at whatever ``scripts`` directory the active Python environment uses
+(``~/.local/bin``, ``$VIRTUAL_ENV/bin``, ``/usr/local/bin``, …), and a
+fixed ``ExecStart`` path would only work for one of those. The install
+helper in :mod:`alter_runtime.service_install` resolves the current
+binary via ``shutil.which`` and renders the template before writing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "SERVICES_DIR",
+    "launchd_template_path",
+    "systemd_cf_access_dropin_template_path",
+    "systemd_template_path",
+]
+
+SERVICES_DIR: Path = Path(__file__).parent
+
+
+def systemd_template_path() -> Path:
+    """Return the absolute path of the bundled systemd unit template."""
+    return SERVICES_DIR / "systemd" / "alter-runtime.service.in"
+
+
+def systemd_cf_access_dropin_template_path() -> Path:
+    """Return the absolute path of the bundled CF Access env drop-in template.
+
+    The drop-in loads ``~/.config/alter/cf-access.env`` into the daemon's
+    environment so the httpx clients can inject the CF Access
+    service-token headers required by ``mcp.truealter.com``. Installed
+    alongside the main unit by :func:`alter_runtime.service_install.install`.
+    """
+    return SERVICES_DIR / "systemd" / "cf-access-env.conf.in"
+
+
+def launchd_template_path() -> Path:
+    """Return the absolute path of the bundled launchd plist template."""
+    return SERVICES_DIR / "launchd" / "com.alter.runtime.plist.in"