engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/server_relay.py

@@ -0,0 +1,172 @@
+"""Server-owned lifecycle for the bounded Tailnet Console relay.
+
+The relay is an access adapter only: it forwards the Tailnet listener to the
+installed Server's loopback Console.  It owns no submission, project, File
+Inbox, Action or run state.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html import escape
+from pathlib import Path
+import shutil
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from .platform_components import PLATFORM_COMPONENT_BY_ID
+from .providers import LaunchdProvider, LocalProcessProvider
+from .resources import package_path
+
+
+RUNTIME_DIRECTORY = "runtime"
+RELAY_BINARY_FILENAME = "engineering-dashboard-relay"
+# This identifier is retained solely to migrate an already installed legacy
+# relay.  The canonical component model is the only active lifecycle owner.
+LEGACY_RELAY_LABEL = "com.djconnect.engineering-dashboard-relay"
+
+
+class RelayCutoverError(RuntimeError):
+    """Fail-closed error for the exact relay identity cutover."""
+
+
+@dataclass(frozen=True)
+class PreCutoverState:
+    legacy_plist_present: bool
+    legacy_loaded: bool
+    legacy_process_active: bool
+    legacy_functional_probe: bool | None
+
+
+def _definition_label() -> str:
+    label = PLATFORM_COMPONENT_BY_ID["dashboard_relay"].lifecycle_label
+    if not label:
+        raise RuntimeError("Dashboard Relay has no canonical lifecycle label.")
+    return label
+
+
+def relay_binary(data_root: Path) -> Path:
+    """Return the installation-owned relay binary path, never a checkout path."""
+    return data_root.resolve() / RUNTIME_DIRECTORY / RELAY_BINARY_FILENAME
+
+
+def build_relay(data_root: Path) -> Path:
+    """Compile the package-owned relay into the Server installation runtime."""
+    compiler = shutil.which("swiftc")
+    if compiler is None:
+        raise RuntimeError("Swift compiler is unavailable; Dashboard Relay cannot start.")
+    binary = relay_binary(data_root)
+    binary.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    completed = LocalProcessProvider().execute(
+        data_root.resolve(), (compiler, str(package_path("dashboard_supervisor.swift")), "-o", str(binary)),
+    )
+    if completed.returncode:
+        raise RuntimeError("Dashboard Relay compilation failed.")
+    binary.chmod(0o700)
+    return binary
+
+
+def launch_agent_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{_definition_label()}.plist"
+
+
+def legacy_launch_agent_path() -> Path:
+    """Return the one retired relay plist that may be migrated."""
+    return Path.home() / "Library" / "LaunchAgents" / f"{LEGACY_RELAY_LABEL}.plist"
+
+
+def relay_functional_probe() -> bool:
+    """Perform the bounded, token-free relay health check used for commit."""
+    try:
+        with urlopen("http://127.0.0.1:8765/health", timeout=2) as response:  # noqa: S310 -- fixed loopback endpoint
+            return 200 <= response.status < 300
+    except (OSError, URLError):
+        return False
+
+
+def pre_cutover_state(launchd: LaunchdProvider, *, probe=relay_functional_probe) -> PreCutoverState:
+    """Capture the non-secret legacy state that rollback must restore exactly."""
+    legacy = legacy_launch_agent_path()
+    loaded = launchd.inspect(LEGACY_RELAY_LABEL)
+    runtime = launchd.runtime_status(LEGACY_RELAY_LABEL) if loaded else None
+    active = bool(runtime and runtime.qualified)
+    return PreCutoverState(legacy.is_file(), loaded, active, probe() if active else None)
+
+
+def _unload_and_verify(launchd: LaunchdProvider, label: str, plist: Path, *, code: str) -> None:
+    if not launchd.inspect(label):
+        return
+    launchd.uninstall(plist)
+    if launchd.inspect(label):
+        raise RelayCutoverError(code)
+
+
+def _restore_legacy(launchd: LaunchdProvider, state: PreCutoverState, legacy: Path, neutral: Path, *, probe=relay_functional_probe) -> None:
+    """Restore exactly the captured legacy loaded state after neutral is absent."""
+    _unload_and_verify(launchd, _definition_label(), neutral, code="ROLLBACK_NEUTRAL_UNLOAD_UNVERIFIED")
+    neutral.unlink(missing_ok=True)
+    if state.legacy_loaded:
+        if not state.legacy_plist_present:
+            raise RelayCutoverError("ROLLBACK_LEGACY_PLIST_MISSING")
+        launchd.install(LEGACY_RELAY_LABEL, legacy)
+        if not launchd.inspect(LEGACY_RELAY_LABEL):
+            raise RelayCutoverError("ROLLBACK_LEGACY_LOAD_UNVERIFIED")
+        restored = launchd.runtime_status(LEGACY_RELAY_LABEL).qualified
+        if restored != state.legacy_process_active:
+            raise RelayCutoverError("ROLLBACK_LEGACY_PROCESS_STATE_MISMATCH")
+        if state.legacy_functional_probe is True and not probe():
+            raise RelayCutoverError("ROLLBACK_LEGACY_FUNCTIONAL_PROBE_FAILED")
+    elif launchd.inspect(LEGACY_RELAY_LABEL):
+        raise RelayCutoverError("ROLLBACK_LEGACY_STATE_MISMATCH")
+
+
+def render_launch_agent(binary: Path) -> Path:
+    """Render the one canonical Relay LaunchAgent from an installed binary."""
+    destination = launch_agent_path()
+    destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    destination.write_text(
+        f'<?xml version="1.0" encoding="UTF-8"?><plist version="1.0"><dict><key>Label</key><string>{_definition_label()}</string><key>ProgramArguments</key><array><string>{escape(str(binary))}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/></dict></plist>',
+        encoding="utf-8",
+    )
+    return destination
+
+
+def install(data_root: Path, *, probe=relay_functional_probe) -> dict[str, str]:
+    """Install the canonical relay and retire its single migration source.
+
+    The commit point is after neutral loaded/process/functional proof.  Before
+    that point the untouched legacy plist and captured lifecycle state are the
+    sole rollback authority.
+    """
+    binary = build_relay(data_root)
+    plist = render_launch_agent(binary)
+    launchd = LaunchdProvider()
+    legacy = legacy_launch_agent_path()
+    state = pre_cutover_state(launchd, probe=probe)
+    if launchd.inspect(_definition_label()):
+        raise RelayCutoverError("NEUTRAL_ALREADY_LOADED")
+    if state.legacy_loaded:
+        _unload_and_verify(launchd, LEGACY_RELAY_LABEL, legacy, code="LEGACY_UNLOAD_UNVERIFIED")
+    try:
+        launchd.install(_definition_label(), plist)
+        if not launchd.inspect(_definition_label()):
+            raise RelayCutoverError("NEUTRAL_LOAD_UNVERIFIED")
+        if not launchd.runtime_status(_definition_label()).qualified:
+            raise RelayCutoverError("NEUTRAL_PROCESS_UNHEALTHY")
+        if not probe():
+            raise RelayCutoverError("NEUTRAL_FUNCTIONAL_PROBE_FAILED")
+    except Exception as error:
+        _restore_legacy(launchd, state, legacy, plist, probe=probe)
+        raise RelayCutoverError("RELAY_CUTOVER_ROLLED_BACK") from error
+    # Commit point: legacy is proven inactive, and neutral is loaded, active,
+    # and functionally healthy. Only now may the migration source be retired.
+    if state.legacy_plist_present:
+        legacy.unlink()
+    return {"component": "dashboard_relay", "binary": str(binary), "launch_agent": str(plist)}
+
+
+def uninstall() -> dict[str, str]:
+    """Remove only the canonical relay LaunchAgent; Server data is untouched."""
+    plist = launch_agent_path()
+    LaunchdProvider().uninstall(plist)
+    plist.unlink(missing_ok=True)
+    return {"component": "dashboard_relay", "launch_agent": str(plist)}

engineering_platform/server_service.py

@@ -0,0 +1,122 @@
+"""macOS LaunchAgent lifecycle for the installed EP Server.
+
+The Server remains the lifecycle and CENTRAL authority.  This module only
+installs one fixed per-user supervisor for its foreground ``serve`` command;
+it never starts a second daemon or accepts arbitrary commands.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import plistlib
+import platform
+import subprocess
+import sys
+from typing import Callable, Mapping, Sequence
+
+
+LABEL = "com.engineeringplatform.server"
+DEFAULT_PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+
+class ServerServiceError(ValueError):
+    """Raised when the bounded EP Server service cannot be managed safely."""
+
+
+@dataclass(frozen=True)
+class ServicePaths:
+    data_root: Path
+    launch_agents_dir: Path
+
+    @property
+    def plist_path(self) -> Path:
+        return self.launch_agents_dir / f"{LABEL}.plist"
+
+    @property
+    def log_dir(self) -> Path:
+        return self.data_root / "runtime"
+
+    @property
+    def stderr_log(self) -> Path:
+        return self.log_dir / "server-launchagent.err.log"
+
+
+def default_paths(data_root: Path, home: Path | None = None) -> ServicePaths:
+    return ServicePaths(data_root.resolve(), (home or Path.home()).expanduser() / "Library" / "LaunchAgents")
+
+
+def _domain() -> str:
+    return f"gui/{os.getuid()}"
+
+
+Runner = Callable[[Sequence[str]], subprocess.CompletedProcess[str]]
+
+
+def _launchctl(arguments: Sequence[str], runner: Runner | None = None) -> subprocess.CompletedProcess[str]:
+    if platform.system() != "Darwin":
+        raise ServerServiceError("EP Server LaunchAgent lifecycle is supported only on macOS.")
+    return (runner or (lambda command: subprocess.run(command, capture_output=True, text=True, check=False)))(["launchctl", *arguments])
+
+
+def _installed_interpreter(candidate: str | Path | None = None) -> Path:
+    # Preserve a virtual-environment launcher symlink.  Resolving it would
+    # turn ``<venv>/bin/python`` into its base interpreter, which no longer
+    # has the EP package installed when launchd invokes it.
+    executable = Path(candidate or sys.executable).expanduser().absolute()
+    if not executable.is_file() or not os.access(executable, os.X_OK):
+        raise ServerServiceError("The EP Server interpreter is not an executable installed runtime.")
+    return executable
+
+
+def plist_payload(paths: ServicePaths, interpreter: Path) -> dict[str, object]:
+    return {
+        "Label": LABEL,
+        "ProgramArguments": [str(interpreter), "-m", "engineering_platform.server", "serve", "--data-root", str(paths.data_root)],
+        "WorkingDirectory": str(paths.data_root),
+        "RunAtLoad": True,
+        "KeepAlive": {"SuccessfulExit": False},
+        "ProcessType": "Background",
+        "EnvironmentVariables": {
+            "PATH": DEFAULT_PATH,
+            "PYTHONNOUSERSITE": "1",
+            "PYTHONSAFEPATH": "1",
+            "EP_SERVER_DATA_ROOT": str(paths.data_root),
+        },
+        "StandardOutPath": "/dev/null",
+        "StandardErrorPath": str(paths.stderr_log),
+    }
+
+
+def write_plist(paths: ServicePaths, interpreter: Path) -> Path:
+    paths.launch_agents_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    paths.log_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    content = plistlib.dumps(plist_payload(paths, interpreter), fmt=plistlib.FMT_XML, sort_keys=True)
+    temporary = paths.plist_path.with_suffix(".plist.tmp")
+    temporary.write_bytes(content)
+    temporary.chmod(0o644)
+    os.replace(temporary, paths.plist_path)
+    paths.plist_path.chmod(0o644)
+    return paths.plist_path
+
+
+def install(data_root: Path, *, interpreter: str | Path | None = None, home: Path | None = None,
+            runner: Runner | None = None) -> Mapping[str, str]:
+    paths = default_paths(data_root, home)
+    if not paths.data_root.is_dir() or not (paths.data_root / "server.json").is_file():
+        raise ServerServiceError("EP Server must be initialized before its LaunchAgent is installed.")
+    plist = write_plist(paths, _installed_interpreter(interpreter))
+    result = _launchctl(("bootstrap", _domain(), str(plist)), runner)
+    if result.returncode and "service already loaded" not in (result.stderr or "").lower():
+        raise ServerServiceError("Unable to bootstrap EP Server LaunchAgent.")
+    return {"state": "installed", "label": LABEL, "plist": str(plist), "data_root": str(paths.data_root), "stderr_log": str(paths.stderr_log)}
+
+
+def uninstall(data_root: Path, *, home: Path | None = None, runner: Runner | None = None) -> Mapping[str, str]:
+    paths = default_paths(data_root, home)
+    if paths.plist_path.exists():
+        result = _launchctl(("bootout", _domain(), str(paths.plist_path)), runner)
+        if result.returncode and not any(marker in (result.stderr or "").lower() for marker in ("could not find service", "no such process", "not found")):
+            raise ServerServiceError("Unable to unload EP Server LaunchAgent.")
+        paths.plist_path.unlink(missing_ok=True)
+    return {"state": "uninstalled", "label": LABEL, "plist": str(paths.plist_path), "data_root": str(paths.data_root)}

engineering_platform/status_model.py

@@ -0,0 +1,135 @@
+"""Canonical, bounded engineering-status model and atomic projections."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from .agent_state import redact_diagnostic
+from .platform_version import EngineeringPlatformManifest
+from .storage import open_storage, store_projection
+
+SCHEMA_VERSION = 1
+
+
+def build(manifest: EngineeringPlatformManifest, **values: object) -> dict[str, object]:
+    """Build the sole status payload; callers cannot publish arbitrary content."""
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "platform_version": manifest.platform_version,
+        "watcher_version": manifest.watcher_version,
+        "dashboard_version": manifest.dashboard_version,
+        "inbox_protocol": manifest.inbox_protocol,
+        "watcher_state": "WATCHER_IDLE",
+        "current_phase": None,
+        "current_action": None,
+        "run_id": None,
+        "job_id": None,
+        "runner_pid": None,
+        "submitted_filename": None,
+        "prompt_title": None,
+        "last_executed_filename": None,
+        "last_executed_title": None,
+        "last_executed_run": None,
+        "last_executed_phase": None,
+        "blocking_predecessor_run": None,
+        "blocking_predecessor_phase": None,
+        "blocking_predecessor_filename": None,
+        "blocking_predecessor_title": None,
+        "predecessor_recovery_action": None,
+        "received_timestamp": None,
+        "elapsed_seconds": 0,
+        "queue_depth": 0,
+        "queue_items": [],
+        "repair_iteration": 0,
+        "implementation_pr": None,
+        "finalization_pr": None,
+        "reconciliation_pr": None,
+        "implementation_state": None,
+        "finalization_state": None,
+        "validation_summary": None,
+        "merge_status_check": None,
+        "repository_state": "MERGED_RECONCILED",
+        "workspace_state": "WORKSPACE_READY",
+        "owner_authorized": False,
+        "resume_available": False,
+        "latest_report": None,
+        "latest_completed_run": None,
+        "diagnostic": None,
+        "last_update": datetime.now(timezone.utc).isoformat(),
+    }
+    payload.update({key: value for key, value in values.items() if key in payload})
+    payload["diagnostic"] = (
+        redact_diagnostic(str(payload["diagnostic"])) if payload["diagnostic"] else None
+    )
+    return payload
+
+
+def publish(root: Path, payload: dict[str, object]) -> None:
+    """Persist canonical watcher state, then publish derived JSON/Markdown."""
+    root.mkdir(mode=0o700, parents=True, exist_ok=True)
+    # Production callers pass ``<repository>/.engineering/status``.  Keep
+    # the public projector usable for an isolated status directory too (for
+    # recovery/export tooling), without accidentally resolving its datastore
+    # at filesystem root.
+    repository_root = (
+        root.parent.parent
+        if root.name == "status" and root.parent.name == ".engineering"
+        else root
+    )
+    connection = open_storage(repository_root)
+    try:
+        store_projection(connection, "watcher_status", payload)
+    finally:
+        connection.close()
+    markdown = "\n".join(
+        (
+            "# Engineering Platform",
+            "",
+            "## Current State",
+            f"`{payload['watcher_state']}` — `{payload['current_phase'] or 'idle'}`",
+            "",
+            "## Active Job",
+            f"Run: `{payload['run_id'] or 'none'}`  ",
+            f"File: `{payload['submitted_filename'] or 'none'}`  ",
+            f"Prompt: `{payload['prompt_title'] or 'none'}`",
+            f"Queue: `{payload['queue_depth']}`",
+            "",
+            "## Pull Requests",
+            f"Implementation: `{payload['implementation_pr'] or 'none'}`  ",
+            f"Finalization: `{payload['finalization_pr'] or 'none'}`",
+            f"Reconciliation: `{payload['reconciliation_pr'] or 'none'}`",
+            "",
+            "## Repository",
+            f"Repository: `{payload['repository_state']}`  ",
+            f"Workspace: `{payload['workspace_state']}`",
+            "",
+            "## Authorization",
+            f"Owner-authorized: `{payload['owner_authorized']}`; release and deployment authority: `absent`",
+            "",
+            "## Latest Report",
+            f"`{payload['latest_report'] or 'none'}`",
+            "",
+            "## Predecessor Gate",
+            f"Blocking run: `{payload['blocking_predecessor_run'] or 'none'}`  ",
+            f"Blocking prompt: `{payload['blocking_predecessor_title'] or payload['blocking_predecessor_filename'] or 'none'}`  ",
+            str(payload["predecessor_recovery_action"] or "none"),
+            "",
+            "## Diagnostic",
+            str(payload["diagnostic"] or "none"),
+            "",
+        )
+    )
+    for name, content in (
+        ("status.json", json.dumps(payload, indent=2, sort_keys=True) + "\n"),
+        ("status.md", markdown),
+    ):
+        descriptor, temporary = tempfile.mkstemp(prefix=f".{name}.", dir=root)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, root / name)

engineering_platform/status_reconciliation.py

@@ -0,0 +1,34 @@
+"""Fail-closed recognition of a stale rolling-status preflight block."""
+from __future__ import annotations
+
+import re
+
+from .agent_state import TransactionState
+
+
+_ROLLING_RECORDS = re.compile(r"\brolling(?:\s+status)?\s+records?\b", re.IGNORECASE)
+_STALE_STATUS_INDICATOR = re.compile(
+    r"\b(?:finalization|reconcil(?:e|iation|ed)|pending|stale|state)\b",
+    re.IGNORECASE,
+)
+
+
+def is_stale_rolling_status_block(state: TransactionState) -> bool:
+    """Recognize only the no-PR preflight block eligible for Finalization.
+
+    Diagnostics are advisory and are never delivery evidence.  They merely
+    identify the already blocked, no-PR transaction for the existing dedicated
+    governance-only Finalization path.  Any run-scoped PR evidence, a different
+    terminal state, or an unrelated diagnostic remains fail-closed.
+    """
+    diagnostic = state.diagnostic or ""
+    return (
+        state.phase == "BLOCKED"
+        and state.terminal_condition == "external_blocked"
+        and state.transaction_kind == "IMPLEMENTATION"
+        and state.pull_request is None
+        and state.implementation_pull_request is None
+        and state.finalization_pull_request is None
+        and bool(_ROLLING_RECORDS.search(diagnostic))
+        and bool(_STALE_STATUS_INDICATOR.search(diagnostic))
+    )