stargate-cli 1.0.0__py3-none-any.whl

stargate/core.py

@@ -0,0 +1,341 @@
+"""Errors, the run's shared state, and the two things everything shells out to:
+a subprocess runner that streams and stays killable, and git."""
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import shlex
+import signal
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TextIO
+
+
+class StargateError(RuntimeError):
+    pass
+
+
+class Terminated(KeyboardInterrupt):
+    """A terminating signal that follows the already-safe interrupt path."""
+
+    def __init__(self, signum: int) -> None:
+        super().__init__(f"signal {signum} ({signal.Signals(signum).name})")
+        self.signum = signum
+
+
+@dataclass(frozen=True)
+class Detected:
+    command: str
+    source: str
+
+
+@dataclass
+class RunContext:
+    repo: Path
+    config: dict[str, Any]
+    run_id: str
+    slug: str
+    branch: str
+    base_ref: str
+    base_commit: str
+    worktree: Path
+    artifacts: Path
+    task: str = ""
+    stage: str = "init"
+    done: set[str] = field(default_factory=set)
+    tokens_used: int = 0
+    tag: str = ""
+    named_by_user: bool = False
+    test_command: str = ""
+    test_source: str = ""
+    detected: list[Detected] = field(default_factory=list)
+    test_artifacts: set[str] = field(default_factory=set)
+    commit: str = ""
+    commit_error: str = ""
+    mode: str = "linear"
+    fanout: dict[str, Any] = field(default_factory=dict)
+    review: dict[str, Any] = field(default_factory=dict)
+    # `review` is a checkpoint: control state for re-entering an interrupted
+    # loop, cleared once the run finishes. `findings` is a report: it has to
+    # survive to the terminal state, so it cannot share that dict.
+    findings: list[dict[str, Any]] = field(default_factory=list)
+    # Provenance survives every stage and resume independently of the task text.
+    task_source: str = ""
+
+
+# How often a running agent prints that it is still alive.
+HEARTBEAT_SECONDS = 30
+
+
+# Cleanup must not turn a terminating signal into an indefinite wait.
+KILL_GRACE_SECONDS = 10
+
+
+_ACTIVE_PROCESS_LOCK = threading.RLock()
+_ACTIVE_PROCESSES: set[subprocess.Popen[str]] = set()
+_TERMINATION_REQUESTED = threading.Event()
+_OUTPUT_LOCK = threading.RLock()
+
+
+def print_output(
+    message: str,
+    *,
+    end: str = "\n",
+    file: TextIO | None = None,
+) -> None:
+    """Write one complete status message without another worker splicing it."""
+    stream = sys.stdout if file is None else file
+    with _OUTPUT_LOCK:
+        stream.write(message + end)
+        stream.flush()
+
+
+def _kill_process_group(proc: subprocess.Popen[str]) -> None:
+    """Kill a tracked command and descendants that kept its process group."""
+    if proc.poll() is not None:
+        # Already reaped, so its PID is free for the kernel to reissue, and
+        # killpg would signal a whole unrelated group under that number.
+        return
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    except OSError:
+        # The Popen child remains the minimum cleanup guarantee if a platform
+        # cannot address the new session as a process group.
+        with contextlib.suppress(OSError):
+            proc.kill()
+
+
+def terminate_active_processes() -> None:
+    """Kill all tracked process groups before fan-out workers unwind."""
+    _TERMINATION_REQUESTED.set()
+    with _ACTIVE_PROCESS_LOCK:
+        processes = list(_ACTIVE_PROCESSES)
+    for proc in processes:
+        _kill_process_group(proc)
+
+    # Reap every direct child against one shared deadline. Waiting a full
+    # grace period for each concurrent worker would serialize shutdown.
+    deadline = time.monotonic() + KILL_GRACE_SECONDS
+    for proc in processes:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        with contextlib.suppress(subprocess.TimeoutExpired, OSError):
+            proc.wait(timeout=remaining)
+
+
+def termination_requested() -> bool:
+    return _TERMINATION_REQUESTED.is_set()
+
+
+def wait_for_termination(timeout: float) -> bool:
+    """Wait up to timeout seconds, returning early when shutdown starts."""
+    return _TERMINATION_REQUESTED.wait(timeout)
+
+
+def run_process(
+    args: list[str],
+    cwd: Path,
+    *,
+    capture: bool = True,
+    check: bool = True,
+    timeout: float | None = None,
+    log_path: Path | None = None,
+    env: dict[str, str] | None = None,
+    timeout_is_error: bool = True,
+    output_label: str | None = None,
+    display_args: list[str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    if termination_requested():
+        raise StargateError("Orchestrator is terminating.")
+    prefix = f"[{output_label}] " if output_label else ""
+    # Callers may hide credentials in diagnostics without changing execution.
+    command = shlex.join(args if display_args is None else display_args)
+    print_output(f"\n{prefix}$ {command}")
+    if log_path is not None:
+        # Straight to disk, so a silent multi-minute agent can be tailed live
+        # instead of surfacing only once the process exits.
+        with log_path.open("w") as handle:
+            proc: subprocess.Popen[str] | None = None
+            try:
+                proc = subprocess.Popen(
+                    args,
+                    cwd=str(cwd),
+                    text=True,
+                    stdout=handle,
+                    stderr=subprocess.STDOUT,
+                    stdin=subprocess.DEVNULL,
+                    env=env,
+                    start_new_session=True,
+                )
+                with _ACTIVE_PROCESS_LOCK:
+                    _ACTIVE_PROCESSES.add(proc)
+                if termination_requested():
+                    _kill_process_group(proc)
+                started = time.monotonic()
+                deadline = None if timeout is None else started + timeout
+                timed_out = False
+                while True:
+                    # Clamped to what is left of the deadline, not a fixed
+                    # heartbeat: waiting the full interval means a timeout
+                    # shorter than one heartbeat is not enforced until one has
+                    # passed, and a process that exits inside that window
+                    # breaks out before the deadline is ever consulted.
+                    remaining = (
+                        HEARTBEAT_SECONDS if deadline is None
+                        else max(0.0, min(HEARTBEAT_SECONDS, deadline - time.monotonic()))
+                    )
+                    try:
+                        proc.wait(timeout=remaining)
+                        break
+                    except subprocess.TimeoutExpired:
+                        pass
+                    if deadline is not None and time.monotonic() >= deadline:
+                        _kill_process_group(proc)
+                        proc.wait()
+                        if timeout_is_error:
+                            raise StargateError(
+                                f"Command timed out after {timeout}s "
+                                f"(partial trace in {log_path}): {command}"
+                            )
+                        timed_out = True
+                        break
+                    # Growing byte count is the "still moving, not hung" signal;
+                    # the trace itself stays out of the terminal.
+                    size = log_path.stat().st_size if log_path.exists() else 0
+                    elapsed = time.monotonic() - started
+                    print_output(
+                        f"{prefix}  ... {elapsed:.0f}s elapsed, "
+                        f"{size:,} bytes written"
+                    )
+            except BaseException:
+                # A signal reaches the orchestrator, not necessarily the agent.
+                # Leaving it alive would let it keep editing during a resume.
+                if proc is not None:
+                    _kill_process_group(proc)
+                    # The signal handler already reaps all active children
+                    # against one shared deadline. Keep standalone interrupt
+                    # cleanup bounded when no orchestrator signal was handled.
+                    if not termination_requested():
+                        with contextlib.suppress(
+                            subprocess.TimeoutExpired, OSError
+                        ):
+                            proc.wait(timeout=KILL_GRACE_SECONDS)
+                raise
+            finally:
+                if proc is not None:
+                    with _ACTIVE_PROCESS_LOCK:
+                        _ACTIVE_PROCESSES.discard(proc)
+        if proc is None:  # pragma: no cover - Popen either returns or raises
+            raise StargateError(f"Could not start command: {command}")
+        output = log_path.read_text() if log_path.exists() else ""
+        returncode = 124 if timed_out else proc.returncode
+        if check and returncode != 0:
+            raise StargateError(
+                f"Command failed with exit code {returncode} "
+                f"(trace in {log_path}): {command}"
+            )
+        return subprocess.CompletedProcess(args, returncode, output, None)
+    try:
+        proc = subprocess.run(
+            args,
+            cwd=str(cwd),
+            text=True,
+            stdout=subprocess.PIPE if capture else None,
+            stderr=subprocess.STDOUT if capture else None,
+            stdin=subprocess.DEVNULL,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise StargateError(
+            f"Command timed out after {timeout}s: {command}"
+        ) from exc
+    if capture and proc.stdout:
+        print_output(proc.stdout, end="" if proc.stdout.endswith("\n") else "\n")
+    if check and proc.returncode != 0:
+        raise StargateError(
+            f"Command failed with exit code {proc.returncode}: {command}"
+        )
+    return proc
+
+
+def git(repo: Path, *args: str, capture: bool = True, check: bool = True):
+    return run_process(["git", *args], repo, capture=capture, check=check)
+
+
+def repo_root(start: Path) -> Path:
+    proc = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=str(start),
+        text=True,
+        capture_output=True,
+    )
+    if proc.returncode != 0:
+        raise StargateError("Current directory is not inside a Git repository.")
+    return Path(proc.stdout.strip()).resolve()
+
+
+def slugify(text: str, max_len: int = 42) -> str:
+    text = re.sub(r"[^a-zA-Z0-9]+", "-", text).strip("-").lower()
+    return (text or "task")[:max_len].rstrip("-")
+
+
+BRANCH_NAME_WORDS = 5
+
+
+BRANCH_NAME_CHARS = 32
+
+
+def short_name(text: str) -> str:
+    """Return a short slug made only from whole words."""
+    words = [word.lower() for word in re.findall(r"[a-zA-Z0-9]+", text)]
+    kept: list[str] = []
+    for word in words[:BRANCH_NAME_WORDS]:
+        candidate = "-".join([*kept, word])
+        if len(candidate) > BRANCH_NAME_CHARS:
+            break
+        kept.append(word)
+    return "-".join(kept)
+
+
+NAME_PREFIX = "NAME:"
+
+
+def split_plan_name(plan: str) -> tuple[str, str]:
+    """Extract an optional first-line name without damaging older plans.
+
+    Only a valid name on the first non-empty line is removed. Custom and frozen
+    prompts predate this contract, and an ignored or malformed instruction must
+    keep flowing verbatim instead of turning a compatible run into a failure.
+    """
+    lines = plan.splitlines()
+    first = next((index for index, line in enumerate(lines) if line.strip()), None)
+    if first is None:
+        return "", plan
+    line = lines[first].strip()
+    if not line.startswith(NAME_PREFIX):
+        return "", plan
+    name = short_name(line[len(NAME_PREFIX):].strip())
+    if not name:
+        return "", plan
+    return name, "\n".join([*lines[:first], *lines[first + 1:]]).strip()
+
+
+def git_quiet(repo: Path, *args: str) -> str:
+    """Read Git state without burying run output under a full printed diff."""
+    proc = subprocess.run(
+        ["git", *args], cwd=str(repo), text=True, capture_output=True
+    )
+    if proc.returncode:
+        raise StargateError(
+            f"git {' '.join(args)} failed in {repo}: {proc.stderr.strip()}"
+        )
+    return proc.stdout

stargate/detect.py

@@ -0,0 +1,140 @@
+"""Guessing the project's test command from what is checked in, and deciding
+whether a guess may run."""
+from __future__ import annotations
+
+import contextlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from .core import Detected, StargateError
+
+DETECTION_MODES = ("report", "auto", "off")
+
+
+DETECTION_READ_LIMIT = 65536
+
+
+# A detected command is input the user never wrote. It may run unattended after
+# every fixer, influence the review verdict and set the process exit code; a bad
+# guess can also be a deploy-ish Make target or a watcher that only ends at the
+# timeout. The default therefore fixes the dangerous silence by reporting the
+# guess and its evidence, without executing it. Users who accept that risk can
+# opt into `auto`; `off` records that the repository intentionally has no test.
+def detection_mode(config: dict[str, Any]) -> str:
+    settings = config.get("settings", {})
+    mode = str(settings.get("test_command_detection", "report") or "report")
+    mode = mode.strip().lower()
+    if mode not in DETECTION_MODES:
+        raise StargateError(
+            "settings.test_command_detection must be one of report, auto, off"
+        )
+    return mode
+
+
+def read_detection_file(path: Path) -> str | None:
+    """Read enough evidence for detection without trusting project file size."""
+    try:
+        with path.open(encoding="utf-8") as handle:
+            return handle.read(DETECTION_READ_LIMIT)
+    except (OSError, UnicodeError, ValueError):
+        return None
+
+
+def is_file(path: Path) -> bool:
+    with contextlib.suppress(OSError):
+        return path.is_file()
+    return False
+
+
+def detect_test_commands(root: Path) -> list[Detected]:
+    """Return all likely commands in a deliberate, user-visible priority."""
+    detected: list[Detected] = []
+
+    # A hand-written project entry point commonly wraps the native runner, so
+    # it outranks language metadata. All lower-ranked matches are still shown.
+    for name in ("Makefile", "makefile", "GNUmakefile"):
+        text = read_detection_file(root / name)
+        if text is not None and re.search(r"(?m)^test\s*:(?!=)", text):
+            detected.append(Detected("make test", f"{name}: test target"))
+            break
+
+    package = read_detection_file(root / "package.json")
+    if package is not None:
+        with contextlib.suppress(json.JSONDecodeError, TypeError, AttributeError):
+            script = json.loads(package).get("scripts", {}).get("test", "")
+            script = script.strip() if isinstance(script, str) else ""
+            if script and "error: no test specified" not in script.lower():
+                runner = (
+                    "pnpm" if is_file(root / "pnpm-lock.yaml")
+                    else "yarn" if is_file(root / "yarn.lock")
+                    else "npm"
+                )
+                detected.append(Detected(
+                    f"{runner} test", "package.json: scripts.test"
+                ))
+
+    for filename, command in (
+        ("Cargo.toml", "cargo test"),
+        ("go.mod", "go test ./..."),
+        ("Package.swift", "swift test"),
+    ):
+        if is_file(root / filename):
+            detected.append(Detected(command, filename))
+
+    pytest_source = ""
+    pyproject = read_detection_file(root / "pyproject.toml")
+    if pyproject is not None:
+        if re.search(r"(?im)^\s*\[tool\.pytest(?:\.|\])", pyproject):
+            pytest_source = "pyproject.toml: tool.pytest"
+        elif (
+            re.search(r"(?im)^\s*pytest(?:[-_.][\w.-]+)?\s*=", pyproject)
+            or re.search(
+                r'''(?i)["']pytest(?:[-_.][\w.-]+)?(?:[<>=~!][^"']*)?["']''',
+                pyproject,
+            )
+        ):
+            pytest_source = "pyproject.toml: pytest dependency"
+    if not pytest_source and is_file(root / "pytest.ini"):
+        pytest_source = "pytest.ini"
+    if not pytest_source:
+        for filename in ("setup.cfg", "tox.ini"):
+            text = read_detection_file(root / filename)
+            if text is not None and re.search(r"(?im)^\s*\[tool:pytest\]", text):
+                pytest_source = f"{filename}: tool:pytest"
+                break
+    if not pytest_source:
+        tests = root / "tests"
+        with contextlib.suppress(OSError):
+            if tests.is_dir() and any(path.is_file() for path in tests.rglob("test_*.py")):
+                pytest_source = "tests/: test_*.py"
+    # A root-level test_*.py is not enough evidence: this repository's smoke
+    # test takes a custom argument and pytest collection would fail. That false
+    # positive is exactly why detection reports rather than runs by default.
+    if pytest_source:
+        detected.append(Detected("pytest -q", pytest_source))
+
+    return detected
+
+
+def selected_test_command(
+    config: dict[str, Any], root: Path
+) -> tuple[str, list[Detected]]:
+    """The command stargate would run, plus every detected candidate.
+
+    Report-only detection intentionally grants nothing: its candidate is input
+    the user has not approved, so letting an agent execute it would defeat the
+    mode even if the orchestrator itself abstained.
+    """
+    settings = config.get("settings", {})
+    configured = str(settings.get("test_command", "") or "").strip()
+    if configured:
+        return configured, []
+    mode = detection_mode(config)
+    if mode == "off":
+        return "", []
+    detected = detect_test_commands(root)
+    if mode == "auto" and detected:
+        return detected[0].command, detected
+    return "", detected