coloph-sync 0.3.1__py3-none-any.whl

coloph_sync/__init__.py

@@ -0,0 +1 @@
+"""The supported public interface is the coloph-sync executable."""

coloph_sync/cli.py

@@ -0,0 +1,261 @@
+"""CLI and agent-facing status contract."""
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from importlib.resources import files
+from pathlib import Path
+
+from .config import load_config
+from .engine import Engine
+from .hooks import check, install, uninstall
+from .state import CommitState, read_state
+from .storage import read_json, write_json
+
+SKILLS = ("contributor", "operator", "finish")
+CONFIG_TEMPLATE = """main_ref = "main"
+remote = "origin"
+commit_check = ["./scripts/check", "commit"]
+merge_check = ["./scripts/check", "merge"]
+integration_check = ["./scripts/check", "integration"]
+deploy_command = ["./scripts/deploy"]
+"""
+
+
+def _skill_files(root: Path):
+    return {
+        root / "skills" / f"coloph-sync-{name}" / "SKILL.md": files("coloph_sync")
+        .joinpath("skills", name, "SKILL.md")
+        .read_text(encoding="utf-8")
+        for name in SKILLS
+    }
+
+
+def install_skills(root: Path):
+    skill_files = _skill_files(root)
+    for path, content in skill_files.items():
+        if path.exists() and path.read_text(encoding="utf-8") != content:
+            raise ValueError(f"Skill file differs: {path}; reconcile or move it before installing")
+    created = []
+    for path, content in skill_files.items():
+        if not path.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            created.append(path)
+    return created
+
+
+def initialize(config: Path):
+    root = config.parent
+    skill_files = _skill_files(root)
+    for path, content in skill_files.items():
+        if path.exists() and path.read_text(encoding="utf-8") != content:
+            raise ValueError(f"Skill file differs: {path}; reconcile or move it before initializing")
+    created = []
+    if not config.exists():
+        config.write_text(CONFIG_TEMPLATE, encoding="utf-8")
+        created.append(config)
+    created.extend(install_skills(root))
+    return created
+
+
+def status(engine, branch=None, commit=None):
+    git = engine.git
+    branch = branch or git.out("branch", "--show-current")
+    sha = git.resolve(commit or branch)
+    if not sha:
+        raise ValueError("Specify an existing branch or commit")
+    report = read_json(engine.report_path)
+    entry = report.get("branches", {}).get(branch, {})
+    main = git.resolve(engine.config.main_ref)
+    deployed = engine.deployed()
+    merged = bool(main and git.ancestor(sha, main))
+    delivered = bool(deployed and git.ancestor(sha, deployed))
+    state = read_state(git.message(sha))
+    reason = None
+    if not merged:
+        if state in (CommitState.WIP, CommitState.FAILED, CommitState.DONT_MERGE):
+            reason = state.value
+        elif entry.get("branch_sha") == sha:
+            reason = entry.get("merge_reason")
+    actionable = bool(reason and entry.get("reason_code") != "barrier")
+    error = report.get("error")
+    checks = report.get("checks_status")
+    verdict = (
+        "action needed"
+        if checks == "failed"
+        else "deployed"
+        if delivered
+        else "action needed"
+        if actionable or error
+        else "merged"
+        if merged
+        else "pending"
+    )
+    return {
+        "branch": branch,
+        "commit": sha,
+        "merged": merged,
+        "deployed": delivered,
+        "verdict": verdict,
+        "reason": reason,
+        "last_sync": report.get("timestamp"),
+        "phase": report.get("current_phase"),
+        "error": error,
+        "checks": checks,
+        "last_merge_attempt": entry.get("last_merge_attempt"),
+        "publication_pending": read_json(engine.delivery_path).get("attempt", {}).get("status") == "completed",
+    }
+
+
+def render(value):
+    print(
+        f"Verdict: {value['verdict']}\nBranch: {value['branch']}\nMerged: {'yes' if value['merged'] else 'no'}\n"
+        f"Deployed: {'yes' if value['deployed'] else 'no'}"
+    )
+    print(f"Tip: {value['commit']}")
+    if value["reason"]:
+        print(f"Reason: {value['reason']}")
+    if value["phase"]:
+        print(f"Sync loop phase: {value['phase']}")
+    if value["checks"]:
+        print(f"Checks: {value['checks']}")
+    if value["error"]:
+        print(f"Last sync error: {value['error']['message']}")
+    if value["publication_pending"]:
+        print("Deployment confirmed; publication pending")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Commit checks, integration, and deployment coordination")
+    parser.add_argument("--config", type=Path)
+    parser.add_argument("--json", action="store_true")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("init", help="Create configuration and install host-project agent workflows")
+    run = sub.add_parser("run")
+    run.add_argument("--once", action="store_true")
+    run.add_argument("--branch", help="Restrict integration to one local worktree branch")
+    run.add_argument("--push-deploy-only", action="store_true", help="Skip merges, then check, push, and deploy main")
+    deploy = sub.add_parser("deploy", help="Deploy through the shared coordinator")
+    deploy.add_argument("--commit")
+    deploy.add_argument("--rollback", action="store_true", help="Explicit operator recovery; never used by the loop")
+    sub.add_parser("stop", help="Drain the current cycle and prevent the next cycle")
+    sub.add_parser("logs")
+    sub.add_parser("install-skills", help="Install agent workflows in the host project")
+    sub.add_parser("install-hooks")
+    sub.add_parser("uninstall-hooks")
+    sub.add_parser("message-state", help="Read a commit message from stdin and print its state")
+    hook = sub.add_parser("hook")
+    hook.add_argument("message", type=Path)
+    state = sub.add_parser("state", help="Read the typed commit state")
+    state.add_argument("ref", nargs="?", default="HEAD")
+    skill = sub.add_parser("skill", help="Print the bundled operating instructions")
+    skill.add_argument("name", choices=SKILLS)
+    for name in ("status", "wait"):
+        p = sub.add_parser(name)
+        p.add_argument("--branch")
+        p.add_argument("--commit")
+        p.add_argument("--all", action="store_true")
+        p.add_argument("--until", choices=["merged", "deployed"], default="deployed")
+        p.add_argument("--timeout", type=int, default=14400)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "init":
+            config = args.config.resolve() if args.config else Path.cwd() / "coloph-sync.toml"
+            root = config.parent
+            created = initialize(config)
+            if args.json:
+                print(json.dumps({"created": [str(path.relative_to(root)) for path in created]}))
+            else:
+                for path in created:
+                    print(f"Created {path.relative_to(root)}")
+                if not created:
+                    print("Project files are already initialized")
+                print("Install hooks after configuring real project commands: coloph-sync install-hooks")
+            return 0
+        if args.command == "message-state":
+            state = read_state(sys.stdin.read())
+            print(state.value if state else "unmarked")
+            return 0
+        if args.command == "skill":
+            print(files("coloph_sync").joinpath("skills", args.name, "SKILL.md").read_text())
+            return 0
+        if args.command == "install-skills":
+            root = args.config.resolve().parent if args.config else Path.cwd()
+            created = install_skills(root)
+            for path in created:
+                print(f"Installed {path.relative_to(root)}")
+            if not created:
+                print("Agent workflows are already installed")
+            return 0
+        config = load_config(args.config)
+        if args.command == "hook":
+            return check(config, args.message.resolve())
+        if args.command == "install-hooks":
+            install(config)
+            print("Installed commit-msg hook. Run coloph-sync init to install the agent workflows")
+            return 0
+        if args.command == "uninstall-hooks":
+            uninstall(config)
+            return 0
+        engine = Engine(config)
+        if args.command in ("run", "deploy"):
+            engine.manual_sha = getattr(args, "commit", None)
+            engine.rollback = getattr(args, "rollback", False)
+            engine.mode = args.command
+            engine.branch = getattr(args, "branch", None)
+            if engine.rollback and not engine.manual_sha:
+                raise ValueError("An explicit rollback requires --commit")
+            engine.run(
+                once=getattr(args, "once", False),
+                deploy_only=args.command == "deploy",
+                push_deploy_only=getattr(args, "push_deploy_only", False),
+            )
+        elif args.command == "stop":
+            owner = read_json(engine.owner_path)
+            if not owner:
+                print("No coordinator is running")
+            else:
+                write_json(engine.stop_path, {"id": owner["id"]})
+                print("Stop requested: the current cycle will finish")
+        elif args.command == "logs":
+            logs = sorted(engine.directory.glob("coloph-sync-*.log"), key=lambda path: path.stat().st_mtime)
+            if logs:
+                print(logs[-1].read_text(), end="")
+        elif args.command == "state":
+            value = read_state(engine.git.message(args.ref))
+            print(value.value if value else "unmarked")
+        else:
+            deadline = time.monotonic() + args.timeout
+            while True:
+                branches = (
+                    engine.git.out("for-each-ref", "--format=%(refname:short)", "refs/heads/").splitlines()
+                    if args.all
+                    else [args.branch]
+                )
+                values = [status(engine, branch, args.commit) for branch in branches]
+                if args.json:
+                    print(json.dumps(values if args.all else values[0]))
+                else:
+                    for value in values:
+                        render(value)
+                if args.command != "wait" or all(value[args.until] for value in values):
+                    return 0
+                if any(value["verdict"] == "action needed" for value in values):
+                    return 1
+                if time.monotonic() >= deadline:
+                    return 1
+                time.sleep(min(5, max(0, deadline - time.monotonic())))
+        return 0
+    except (ValueError, RuntimeError, OSError, subprocess.SubprocessError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("Interrupted; reconcile any unfinished deploy attempt before resuming", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

coloph_sync/config.py

@@ -0,0 +1,51 @@
+"""TOML configuration."""
+
+import tomllib
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+    commit_check: tuple[str, ...]
+    deploy_command: tuple[str, ...]
+    merge_check: tuple[str, ...] = ()
+    integration_check: tuple[str, ...] = ()
+    preflight_command: tuple[str, ...] = ()
+    main_ref: str = "main"
+    remote: str = "origin"
+    deployed_ref: str = "deployed"
+    deploy_tag_prefix: str = "deploy"
+    check_timeout: int = 14400
+    deploy_timeout: int = 14400
+    merge_timeout: int = 1500
+    interval: int = 60
+
+
+def load_config(path: Path | None = None) -> Config:
+    path = path.resolve() if path else Path.cwd() / "coloph-sync.toml"
+    root = path.parent
+    with path.open("rb") as stream:
+        raw = tomllib.load(stream)
+    local = root / "coloph-sync.local.toml"
+    if local.exists() and local != path:
+        with local.open("rb") as stream:
+            raw.update(tomllib.load(stream))
+    unknown = set(raw) - {field.name for field in fields(Config) if field.name != "root"}
+    if unknown:
+        raise ValueError(f"Unknown configuration keys: {sorted(unknown)}")
+    for name in ("commit_check", "merge_check", "integration_check", "deploy_command", "preflight_command"):
+        value = raw.get(name, [])
+        if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+            raise ValueError(f"{name} must be an argument array")
+        if name in ("commit_check", "deploy_command") and not value:
+            raise ValueError(f"{name} is required")
+        raw[name] = tuple(value)
+    for name in ("check_timeout", "deploy_timeout", "merge_timeout", "interval"):
+        if name in raw and (type(raw[name]) is not int or raw[name] <= 0):
+            raise ValueError(f"{name} must be a positive integer")
+    for name in ("main_ref", "remote", "deployed_ref", "deploy_tag_prefix"):
+        if name in raw and (not isinstance(raw[name], str) or not raw[name] or raw[name].startswith("-")):
+            raise ValueError(f"Invalid {name}")
+    return Config(root=root, **raw)

coloph_sync/engine.py

@@ -0,0 +1,345 @@
+"""Local integration and deployment engine.
+
+Project commands own checks and deployment internals.
+"""
+
+import os
+import signal
+import subprocess
+import time
+import uuid
+from datetime import UTC, datetime
+
+from .config import Config
+from .git import Git, run_checked
+from .state import CommitState, read_state
+from .storage import lock, read_json, write_json
+
+
+def now():
+    return datetime.now(UTC).isoformat()
+
+
+class Engine:
+    def __init__(self, config: Config):
+        self.config = config
+        self.git = Git(config.root)
+        self.directory = self.git.common_dir()
+        self.report_path = self.directory / "sync-report.json"
+        self.delivery_path = self.directory / "coloph-sync-delivery.json"
+        self.stop_path = self.directory / "coloph-sync-stop.json"
+        self.owner_path = self.directory / "coloph-sync-owner.json"
+        self.report = read_json(self.report_path)
+        self.run_id = f"sync-{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}-{uuid.uuid4().hex[:8]}"
+        self.draining = False
+        self.rollback = False
+        self.manual_sha = None
+        self.mode = "run"
+        self.branch = None
+
+    def save(self, phase=None):
+        self.report.update(timestamp=now(), sync_run_id=self.run_id)
+        if phase:
+            self.report.update(current_phase=phase, phase_started_at=now())
+            self.report.pop("error", None)
+        write_json(self.report_path, self.report)
+
+    def deployed(self):
+        delivery = read_json(self.delivery_path)
+        if delivery.get("attempt", {}).get("status") == "completed":
+            return delivery["attempt"]["sha"]
+        return delivery.get("deployed_sha") or self.git.resolve(f"refs/tags/{self.config.deployed_ref}")
+
+    def command(self, command, context, *, sha=None, attempt=None, timeout=None):
+        env = {
+            **os.environ,
+            "COLOPH_SYNC_CONTEXT": context,
+            "COLOPH_SYNC_RUN_ID": self.run_id,
+            "COLOPH_SYNC_COMMIT": sha or self.git.out("rev-parse", "HEAD"),
+            "COLOPH_SYNC_ATTEMPT_ID": attempt or "",
+            "COLOPH_SYNC_DEPLOYED_COMMIT": self.deployed() or "",
+            "COLOPH_SYNC_ROLLBACK": "1" if self.rollback else "0",
+            "COLOPH_SYNC_MODE": self.mode,
+        }
+        log = self.directory / f"coloph-sync-{self.run_id}.log"
+        with log.open("a") as stream:
+            stream.write(f"\n[{now()}] {context}\n")
+            stream.flush()
+
+            def output(line):
+                stream.write(line)
+                stream.flush()
+                print(line, end="", flush=True)
+
+            result = run_checked(
+                command, cwd=self.config.root, env=env, timeout=timeout or self.config.check_timeout, output=output
+            )
+        result.check_returncode()
+
+    def barrier(self, branch, deployed):
+        # Original pending_deploy_barrier algorithm, using typed body states.
+        for sha in self.git.commits(f"{deployed}..{branch}" if deployed else branch):
+            if read_state(self.git.message(sha)) != CommitState.DEPLOY_BARRIER:
+                continue
+            parent = self.git.out("rev-parse", f"{sha}^")
+            if deployed and self.git.ancestor(parent, deployed):
+                continue
+            return sha, parent
+        return None
+
+    def metadata_errors(self, range_spec):
+        errors = []
+        for sha in self.git.commits(range_spec):
+            try:
+                state = read_state(self.git.message(sha))
+                if state is None:
+                    errors.append(f"{sha[:10]} missing Sync-State")
+                if state == CommitState.DEPLOY_BARRIER:
+                    parents = self.git.out("rev-list", "--parents", "-n", "1", sha).split()[1:]
+                    if len(parents) != 1 or self.git.out("rev-parse", f"{sha}^{{tree}}") != self.git.out(
+                        "rev-parse", f"{parents[0]}^{{tree}}"
+                    ):
+                        errors.append(f"{sha[:10]} deployment barrier must be empty with one parent")
+            except ValueError as exc:
+                errors.append(f"{sha[:10]} {exc}")
+        return errors
+
+    def merge_in(self):
+        self.save("merge")
+        entries = self.report.setdefault("branches", {})
+        for branch in sorted(self.git.worktrees()):
+            if branch == self.config.main_ref:
+                continue
+            if self.branch is not None and branch != self.branch:
+                continue
+            target = self.git.out("rev-parse", "HEAD")
+            tip = self.git.resolve(branch)
+            if tip is None:
+                entries[branch] = {
+                    **entries.get(branch, {}),
+                    "last_sync_run_id": self.run_id,
+                    "last_merge_attempt": {"at": now(), "outcome": "skipped", "reason": "branch disappeared"},
+                }
+                self.save()
+                continue
+            previous = entries.get(branch, {})
+            entry = {
+                **previous,
+                "branch_sha": tip,
+                "merge_target_sha": target,
+                "last_seen_at": now(),
+                "last_sync_run_id": self.run_id,
+            }
+            entries[branch] = entry
+            reason = None
+            outcome = "skipped"
+            if self.git.ancestor(tip, target):
+                outcome = "already_merged"
+            elif (
+                previous.get("branch_sha") == tip
+                and previous.get("merge_status") == "not_merged"
+                and (
+                    previous.get("reason_code") == "metadata"
+                    or (previous.get("reason_code") == "conflict" and previous.get("merge_target_sha") == target)
+                )
+            ):
+                reason = previous["merge_reason"]
+                outcome = "unchanged"
+            else:
+                try:
+                    state = read_state(self.git.message(tip))
+                    if state in (CommitState.WIP, CommitState.FAILED, CommitState.DONT_MERGE):
+                        reason = state.value
+                        entry["reason_code"] = "state"
+                    else:
+                        barrier = self.barrier(tip, self.deployed())
+                        merge_sha = barrier[1] if barrier else tip
+                        base = self.git.out("merge-base", target, merge_sha)
+                        errors = self.metadata_errors(f"{base}..{merge_sha}")
+                        if errors:
+                            reason = "metadata guard failed: " + "; ".join(errors)
+                            entry["reason_code"] = "metadata"
+                        else:
+                            if not self.git.ancestor(merge_sha, target):
+                                environment = {**os.environ, "COLOPH_SYNC_AUTOMATIC_MERGE": "1"}
+                                result = run_checked(
+                                    ["git", "merge", "--no-edit", merge_sha],
+                                    cwd=self.config.root,
+                                    env=environment,
+                                    timeout=self.config.merge_timeout,
+                                    output=lambda line: print(line, end="", flush=True),
+                                )
+                                result.check_returncode()
+                                if read_state(self.git.message("HEAD")) not in (
+                                    CommitState.PASSED,
+                                    CommitState.DEPLOY_BARRIER,
+                                ):
+                                    raise RuntimeError(
+                                        "The merge did not produce a passed commit; install the commit hook and repair before resuming"
+                                    )
+                            if barrier:
+                                reason = f"merged up to {merge_sha[:10]} due to deployment barrier {barrier[0][:10]}; waiting for deployment"
+                                outcome = "partial_merged"
+                                entry["reason_code"] = "barrier"
+                            else:
+                                outcome = "merged"
+                except ValueError as exc:
+                    reason = f"metadata guard failed: {exc}"
+                    entry["reason_code"] = "metadata"
+                except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as exc:
+                    if self.git.resolve("MERGE_HEAD"):
+                        self.git.out("merge", "--abort")
+                    reason = "merge timed out" if isinstance(exc, subprocess.TimeoutExpired) else "merge failed"
+                    entry["reason_code"] = "timeout" if isinstance(exc, subprocess.TimeoutExpired) else "conflict"
+                    outcome = "failed"
+            entry.update(
+                merge_status="not_merged" if reason else "merged",
+                merge_reason=reason,
+                last_merge_attempt={"at": now(), "outcome": outcome},
+            )
+            if not reason:
+                entry.pop("reason_code", None)
+                entry["merged_at"] = now()
+            self.save()
+
+    def remote_ref(self, ref):
+        output = self.git.out("ls-remote", self.config.remote, ref)
+        for line in output.splitlines():
+            sha, name = line.split()
+            if name == ref:
+                return sha
+        return None
+
+    def publish(self, delivery):
+        attempt = delivery["attempt"]
+        sha = attempt["sha"]
+        immutable = f"refs/tags/{self.config.deploy_tag_prefix}/{attempt['id']}"
+        floating = f"refs/tags/{self.config.deployed_ref}"
+        found = self.remote_ref(immutable)
+        if found not in (None, sha):
+            raise RuntimeError(f"Deployment tag conflict: {immutable}")
+        self.git.out("update-ref", immutable, sha)
+        if found is None:
+            self.git.out("push", self.config.remote, f"{immutable}:{immutable}", timeout=120)
+        previous = attempt["previous_remote"]
+        found = self.remote_ref(floating)
+        if found != sha:
+            if found != previous:
+                raise RuntimeError("Deployed ref changed concurrently; reconcile before resuming")
+            self.git.out(
+                "push",
+                f"--force-with-lease={floating}:{previous or ''}",
+                self.config.remote,
+                f"{sha}:{floating}",
+                timeout=120,
+            )
+        self.git.out("update-ref", floating, sha)
+        attempt["status"] = "published"
+        delivery["deployed_sha"] = sha
+        write_json(self.delivery_path, delivery)
+        self.report["deploy_sha"] = sha
+        self.save("done")
+
+    def deploy(self, sha):
+        delivery = read_json(self.delivery_path)
+        previous = delivery.get("attempt", {})
+        if previous and previous["status"] != "published":
+            if previous["sha"] != sha:
+                raise RuntimeError(
+                    f"Resolve deploy attempt {previous['id']} for {previous['sha']} before deploying another commit"
+                )
+            attempt = previous
+            self.rollback = attempt.get("rollback", False)
+        else:
+            deployed = self.deployed()
+            if deployed and not self.rollback and not self.git.ancestor(deployed, sha):
+                raise RuntimeError("Automatic rollback is not supported; reconcile deployment state explicitly")
+            if deployed == sha:
+                self.report["deploy_sha"] = sha
+                self.save("done")
+                return
+            attempt = {
+                "id": f"{self.run_id}-{uuid.uuid4().hex[:8]}",
+                "sha": sha,
+                "status": "running",
+                "previous_remote": self.remote_ref(f"refs/tags/{self.config.deployed_ref}"),
+                "rollback": self.rollback,
+            }
+            delivery["attempt"] = attempt
+            write_json(self.delivery_path, delivery)
+        if attempt["status"] != "completed":
+            self.save("deploy")
+            self.command(
+                self.config.deploy_command, "deploy", sha=sha, attempt=attempt["id"], timeout=self.config.deploy_timeout
+            )
+            attempt.update(status="completed", completed_at=now())
+            write_json(self.delivery_path, delivery)
+        self.save("publish")
+        self.publish(delivery)
+
+    def cycle(self, *, deploy_only=False, push_deploy_only=False):
+        if self.git.out("branch", "--show-current") != self.config.main_ref:
+            raise RuntimeError(f"Run the coordinator on {self.config.main_ref}")
+        if self.git.out("status", "--porcelain"):
+            raise RuntimeError("The coordinator checkout must be clean")
+        if read_state(self.git.message("HEAD")) not in (CommitState.PASSED, CommitState.DEPLOY_BARRIER):
+            raise RuntimeError("The integration branch must have a checked commit before running")
+        pending = read_json(self.delivery_path).get("attempt", {})
+        if pending and pending["status"] != "published":
+            self.deploy(pending["sha"])
+            return
+        if self.config.preflight_command:
+            self.save("preflight")
+            self.command(self.config.preflight_command, "preflight")
+        if not deploy_only:
+            if not push_deploy_only:
+                self.merge_in()
+            self.save("verify")
+            self.report["checks_status"] = "running"
+            self.save()
+            self.command(self.config.integration_check or self.config.commit_check, "integration")
+            self.report["checks_status"] = "passed"
+            self.save()
+        sha = self.git.resolve(self.manual_sha) if self.manual_sha else self.git.out("rev-parse", "HEAD")
+        if not sha:
+            raise ValueError("Deployment target does not exist")
+        if not deploy_only:
+            self.save("push")
+            self.git.out("push", self.config.remote, self.config.main_ref)
+        else:
+            self.git.out("fetch", self.config.remote, self.config.main_ref)
+            if not self.git.ancestor(sha, f"{self.config.remote}/{self.config.main_ref}"):
+                raise RuntimeError("Push the deployment target before a manual deploy")
+        self.deploy(sha)
+
+    def run(self, *, once=False, deploy_only=False, push_deploy_only=False):
+        with lock(self.directory / "sync-test-push.lock"):
+            owner = {"pid": os.getpid(), "id": self.run_id}
+            write_json(self.owner_path, owner)
+            old_signal = signal.signal(signal.SIGTERM, lambda *_: setattr(self, "draining", True))
+            try:
+                while True:
+                    try:
+                        self.cycle(deploy_only=deploy_only, push_deploy_only=push_deploy_only)
+                    except (RuntimeError, ValueError, OSError, subprocess.SubprocessError, KeyboardInterrupt) as exc:
+                        phase = self.report.get("current_phase", "startup")
+                        if phase == "verify":
+                            self.report["checks_status"] = "failed"
+                        self.report.update(
+                            current_phase="error", error={"phase": phase, "at": now(), "message": str(exc)}
+                        )
+                        self.save()
+                        raise
+                    if once or deploy_only or push_deploy_only:
+                        return
+                    deadline = time.monotonic() + self.config.interval
+                    while time.monotonic() < deadline:
+                        if self.draining or read_json(self.stop_path).get("id") == owner["id"]:
+                            return
+                        time.sleep(min(0.2, max(0, deadline - time.monotonic())))
+                    if self.draining or read_json(self.stop_path).get("id") == owner["id"]:
+                        return
+                    self.run_id = f"sync-{uuid.uuid4().hex}"
+            finally:
+                signal.signal(signal.SIGTERM, old_signal)
+                self.owner_path.unlink(missing_ok=True)