create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/egregore_runtime/sync.py

@@ -0,0 +1,218 @@
+"""Git-backed provenance transport for canonical organizational state."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Sequence
+
+from .contracts import SyncStatus
+
+
+class GitSyncError(RuntimeError):
+    """The configured canonical Git repository could not be synchronized."""
+
+
+class LocalGitSyncTransport:
+    """Commit exact canonical paths and optionally use today's Git transport.
+
+    Path-aware commits prevent a ritual from absorbing unrelated user edits.
+    GitHub is only the current remote transport; the domain contract exposes
+    no GitHub identity or API detail and can be replaced independently later.
+    """
+
+    def __init__(self, repository: Path, *, push_remote: bool = True) -> None:
+        self.repository = repository.resolve()
+        self.push_remote = push_remote
+        self.async_remote_push = os.environ.get("EGREGORE_ASYNC_REMOTE_PUSH") == "1"
+
+    def _run(self, *arguments: str, timeout: int = 60) -> subprocess.CompletedProcess[str]:
+        completed = subprocess.run(
+            ("git", "-C", str(self.repository), *arguments),
+            text=True,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+        return completed
+
+    def _required(self, *arguments: str, timeout: int = 60) -> str:
+        completed = self._run(*arguments, timeout=timeout)
+        if completed.returncode != 0:
+            detail = (completed.stderr or completed.stdout).strip()
+            raise GitSyncError(detail or f"git {' '.join(arguments)} failed")
+        return completed.stdout.strip()
+
+    def _revision(self) -> str:
+        return self._required("rev-parse", "HEAD")
+
+    def _remote_revision(self) -> str | None:
+        branch = self._required("branch", "--show-current")
+        if not branch:
+            return None
+        completed = self._run("rev-parse", f"origin/{branch}")
+        return completed.stdout.strip() if completed.returncode == 0 else None
+
+    def _push_remote_background(self) -> str | None:
+        environment = dict(os.environ)
+        environment["GIT_TERMINAL_PROMPT"] = "0"
+        try:
+            subprocess.Popen(
+                (
+                    "git",
+                    "-c",
+                    "http.lowSpeedLimit=1",
+                    "-c",
+                    "http.lowSpeedTime=15",
+                    "-C",
+                    str(self.repository),
+                    "push",
+                    "origin",
+                    "HEAD",
+                ),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                env=environment,
+                start_new_session=True,
+            )
+        except OSError as exc:
+            return f"remote push could not be queued: {exc}"
+        return None
+
+    def _status(
+        self,
+        warnings: Sequence[str] = (),
+        *,
+        changed: bool = False,
+    ) -> SyncStatus:
+        dirty = bool(self._required("status", "--porcelain"))
+        remote_revision = self._remote_revision()
+        current = True
+        if remote_revision is not None:
+            current = self._run(
+                "merge-base", "--is-ancestor", remote_revision, "HEAD"
+            ).returncode == 0
+        return SyncStatus(
+            transport="git",
+            local_revision=f"git:{self._revision()}",
+            remote_revision=f"git:{remote_revision}" if remote_revision else None,
+            clean=not dirty,
+            warnings=tuple(warnings),
+            current=current,
+            changed=changed,
+        )
+
+    def _relative_paths(self, paths: Sequence[str]) -> tuple[str, ...]:
+        relative: list[str] = []
+        for raw in paths:
+            candidate = Path(raw)
+            if not candidate.is_absolute():
+                candidate = self.repository / candidate
+            resolved = candidate.resolve()
+            try:
+                item = resolved.relative_to(self.repository).as_posix()
+            except ValueError as exc:
+                raise GitSyncError(f"sync path is outside canonical repository: {raw}") from exc
+            if item and item not in relative:
+                relative.append(item)
+        return tuple(relative)
+
+    @staticmethod
+    def _provenance_trailers() -> tuple[str, ...]:
+        session_id = os.environ.get("EGREGORE_SESSION_ID", "unknown")
+        runtime = os.environ.get("EGREGORE_RUNTIME", "shell").strip().lower()
+        coauthors = {
+            "codex": "OpenAI Codex <noreply@openai.com>",
+            "claude": "Claude Code <noreply@anthropic.com>",
+            "claude-code": "Claude Code <noreply@anthropic.com>",
+            "pi": "Pi Egregore Runtime <noreply@egregore.xyz>",
+            "prime": "Prime Agent <noreply@egregore.xyz>",
+        }
+        trailers = [
+            f"Egregore-Session: {session_id}",
+            f"Egregore-Harness: {runtime}",
+        ]
+        if coauthor := coauthors.get(runtime):
+            trailers.append(f"Co-Authored-By: {coauthor}")
+        return tuple(trailers)
+
+    def status(self) -> SyncStatus:
+        return self._status()
+
+    def pull(self) -> SyncStatus:
+        before = self._revision()
+        if self._run("remote", "get-url", "origin").returncode != 0:
+            return self._status(("no origin remote configured; canonical history is local",))
+        branch = self._required("branch", "--show-current")
+        if not branch:
+            raise GitSyncError("canonical Git repository is on a detached HEAD")
+        # EGREGORE_SYNC_FETCH_FRESH=1 means the caller proved a successful
+        # fetch of this repository moments ago (the attendant's warm marker is
+        # stamped only after its fetches succeed). Reuse that remote-tracking
+        # ref instead of paying a second network round; if the ref is absent
+        # the claim is void and the fetch happens anyway. Integration below is
+        # unchanged — currency is still judged against the remote revision.
+        fetch_is_fresh = (
+            os.environ.get("EGREGORE_SYNC_FETCH_FRESH") == "1"
+            and self._remote_revision() is not None
+        )
+        if not fetch_is_fresh:
+            self._required("fetch", "origin", branch, timeout=180)
+        remote_revision = self._remote_revision()
+        if remote_revision is None:
+            raise GitSyncError(f"origin/{branch} is unavailable after fetch")
+
+        # A dirty canonical checkout is safe when it is already current or
+        # locally ahead: no working-tree mutation is needed. Only ask Git to
+        # integrate when the fetched remote is not already contained in HEAD.
+        remote_is_ancestor = self._run(
+            "merge-base", "--is-ancestor", remote_revision, "HEAD"
+        ).returncode == 0
+        if not remote_is_ancestor:
+            if self._required("status", "--porcelain"):
+                raise GitSyncError(
+                    "canonical Git repository has incoming changes and local "
+                    "working-tree edits; commit or resolve them before sync"
+                )
+            self._required("rebase", remote_revision, timeout=180)
+        return self._status(changed=self._revision() != before)
+
+    def push(self, *, message: str, paths: Sequence[str] = ()) -> SyncStatus:
+        selected = self._relative_paths(paths)
+        if not selected:
+            raise GitSyncError("path-aware canonical sync requires at least one artifact path")
+
+        self._required("add", "--", *selected)
+        staged = self._run("diff", "--cached", "--quiet", "--", *selected)
+        if staged.returncode not in (0, 1):
+            raise GitSyncError((staged.stderr or staged.stdout).strip() or "git diff failed")
+        if staged.returncode == 1:
+            arguments = [
+                "commit",
+                "--only",
+                "-m",
+                message,
+                "-m",
+                "Record the authorized canonical artifact and its provenance.",
+            ]
+            for trailer in self._provenance_trailers():
+                arguments.extend(("-m", trailer))
+            arguments.extend(("--", *selected))
+            self._required(*arguments)
+
+        warnings: list[str] = []
+        if self.push_remote:
+            if self._run("remote", "get-url", "origin").returncode == 0:
+                if self.async_remote_push:
+                    if warning := self._push_remote_background():
+                        warnings.append(warning)
+                else:
+                    pushed = self._run("push", "origin", "HEAD", timeout=180)
+                    if pushed.returncode != 0:
+                        detail = (pushed.stderr or pushed.stdout).strip()
+                        warnings.append(f"remote push failed: {detail or 'git push failed'}")
+            else:
+                warnings.append("no origin remote configured; canonical history is local")
+        return self._status(warnings)

package/runtime/claude/egregore_runtime/teamsync.py

@@ -0,0 +1,139 @@
+"""Team-memory synchronization truth for user-facing surfaces.
+
+Maps the canonical memory repository's Git state to the six plain states
+Settings shows. Git synchronization and semantic readiness are deliberately
+independent: this module never consults retrieval state, and "up to date
+with the team" is claimed only when a fetch actually succeeded and local
+history is neither ahead of nor behind its upstream, with nothing
+unpublished. Meaning-search freshness is reported elsewhere.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+STATE_UP_TO_DATE = "up-to-date"
+STATE_UPDATES_AVAILABLE = "updates-available"
+STATE_UNSHARED_WORK = "unshared-work"
+STATE_DIVERGED = "diverged"
+STATE_ATTENTION = "attention"
+STATE_OFFLINE = "offline"
+
+LABELS = {
+    STATE_UP_TO_DATE: "Up to date with the team",
+    STATE_UPDATES_AVAILABLE: "Team updates available",
+    STATE_UNSHARED_WORK: "Your latest work has not been shared",
+    STATE_DIVERGED: "Sync needs attention",
+    STATE_ATTENTION: "Sync needs attention",
+    STATE_OFFLINE: "Offline; showing last synchronized state",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class TeamSync:
+    state: str
+    label: str
+    ahead: int
+    behind: int
+    dirty: bool
+    fetched: bool
+    local_revision: str
+    remote_revision: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "state": self.state,
+            "label": self.label,
+            "ahead": self.ahead,
+            "behind": self.behind,
+            "dirty": self.dirty,
+            "fetched": self.fetched,
+            "local_revision": self.local_revision,
+            "remote_revision": self.remote_revision,
+        }
+
+
+def _git(root: Path, *args: str, timeout: int = 30) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ("git", "-C", str(root), *args),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def team_sync(memory_root: Path, *, fetch: bool = True) -> TeamSync:
+    """Compute the honest sync state for the canonical memory repository.
+
+    ``fetch=True`` attempts a real fetch first; a failed fetch yields the
+    offline state (last synchronized information, clearly labeled) rather
+    than a phantom "up to date". ``fetch=False`` reads local refs only and
+    never claims up-to-date — surfaces that skip the network must present
+    cached knowledge as cached.
+    """
+    branch = _git(memory_root, "branch", "--show-current").stdout.strip()
+    local = _git(memory_root, "rev-parse", "HEAD").stdout.strip()
+    dirty = bool(_git(memory_root, "status", "--porcelain").stdout.strip())
+    has_origin = _git(memory_root, "remote", "get-url", "origin").returncode == 0
+
+    fetched = False
+    if fetch and branch and has_origin:
+        fetched = _git(memory_root, "fetch", "origin", branch, timeout=60).returncode == 0
+
+    upstream = f"origin/{branch}" if branch else ""
+    remote = _git(memory_root, "rev-parse", upstream).stdout.strip() if upstream else ""
+
+    ahead = behind = 0
+    if remote:
+        counts = _git(memory_root, "rev-list", "--left-right", "--count", f"HEAD...{upstream}")
+        if counts.returncode == 0 and counts.stdout.strip():
+            left, _, right = counts.stdout.strip().partition("\t")
+            ahead = int(left or 0)
+            behind = int(right or 0)
+
+    if not branch or not local or not has_origin:
+        # No branch, no history, or nothing to synchronize with — this needs
+        # a person, not a retry.
+        state = STATE_ATTENTION
+    elif fetch and not fetched:
+        state = STATE_OFFLINE
+    elif not remote:
+        state = STATE_ATTENTION
+    elif ahead and behind:
+        state = STATE_DIVERGED
+    elif dirty or ahead:
+        state = STATE_UNSHARED_WORK
+    elif behind:
+        state = STATE_UPDATES_AVAILABLE
+    elif not fetch:
+        # Local refs alone cannot prove currency with the team.
+        state = STATE_OFFLINE
+    else:
+        state = STATE_UP_TO_DATE
+
+    return TeamSync(
+        state=state,
+        label=LABELS[state],
+        ahead=ahead,
+        behind=behind,
+        dirty=dirty,
+        fetched=fetched,
+        local_revision=local[:12],
+        remote_revision=remote[:12],
+    )
+
+
+__all__ = [
+    "LABELS",
+    "STATE_ATTENTION",
+    "STATE_DIVERGED",
+    "STATE_OFFLINE",
+    "STATE_UNSHARED_WORK",
+    "STATE_UPDATES_AVAILABLE",
+    "STATE_UP_TO_DATE",
+    "TeamSync",
+    "team_sync",
+]