forgeo-cli 0.3.0__py3-none-any.whl

forgeo/config.py

@@ -0,0 +1,36 @@
+"""Project configuration loading: YAML <-> :class:`ForgeoConfig`.
+
+Relative paths in the file are resolved against the file's own directory,
+so a config file can live anywhere and still point at sibling directories.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from forgeo.models import ForgeoConfig
+
+
+def load_config(path: str | Path) -> ForgeoConfig:
+    """Load and validate a Forgeo YAML file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        pydantic.ValidationError: If the payload does not match the schema.
+    """
+    config_path = Path(path)
+    payload = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    config = ForgeoConfig.model_validate(payload)
+    base = config_path.parent.resolve()
+    updates: dict[str, Path | str] = {}
+    if not config.repo.is_absolute():
+        updates["repo"] = base / config.repo
+    if not config.backlog.is_absolute():
+        updates["backlog"] = base / config.backlog
+    if not config.blocker_file.is_absolute():
+        updates["blocker_file"] = base / config.blocker_file
+    if not Path(config.log_file).is_absolute():
+        updates["log_file"] = str(base / config.log_file)
+    return config if not updates else config.model_copy(update=updates)

forgeo/daemon.py

@@ -0,0 +1,209 @@
+"""The scheduled forgeo daemon.
+
+Wakes up every ``interval_minutes``, runs one cycle of the :class:`Forgeo`,
+and sleeps. A lock file prevents two daemons from running on the same
+forgeo. A per-run lock prevents two agents from ever working on the same
+repository at the same time: when a run is still in progress at the next
+wake-up, that iteration is skipped instead of killing the running agent.
+Everything else is logged to the configured log file.
+
+Live state (pid, started at, last outcome, next run) is written to a small
+``daemon.state.json`` next to the backlog after every cycle, so external
+observers (the central dashboard, the CLI) can read it without the daemon
+serving any port. The file is written atomically; a crash mid-write never
+corrupts it, and a missing/stale file simply reads as unknown state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from forgeo.forgeo import Forgeo
+from forgeo.io import atomic_write_text
+from forgeo.models import ForgeoConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _take_flock(lock_path: str | Path) -> Any | None:
+    """Open the lock file and take a non-blocking exclusive flock.
+
+    Uses ``fcntl`` flock so the lock is released automatically when the
+    process exits (even on crash). Returns ``None`` when another process
+    holds the lock. Falls back to no locking when ``fcntl`` is unavailable.
+    The file is opened without truncation so a failed acquire keeps the
+    running holder's recorded PID intact (``forgeo stop`` needs it).
+    """
+    lock_file = Path(lock_path)
+    lock_file.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_file.open("a+")
+    try:
+        import fcntl
+    except ImportError:
+        handle.truncate(0)
+        handle.write(f"pid={os.getpid()}\n")
+        handle.flush()
+        return handle
+    try:
+        fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        handle.close()
+        return None
+    handle.truncate(0)
+    handle.write(f"pid={os.getpid()}\n")
+    handle.flush()
+    return handle
+
+
+def acquire_run_lock(lock_path: str | Path) -> Any:
+    """Take an exclusive, non-blocking lock; returns the handle or ``None``.
+
+    The lock is released automatically when the process exits (even on
+    crash). Returns ``None`` when another daemon holds the lock.
+    """
+    return _take_flock(lock_path)
+
+
+def read_lock_pid(lock_path: str | Path) -> int | None:
+    """Return the PID recorded in the lock file, or ``None`` when unknown."""
+    try:
+        text = Path(lock_path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    for line in text.splitlines():
+        if line.startswith("pid="):
+            try:
+                return int(line.removeprefix("pid=").strip())
+            except ValueError:
+                return None
+    return None
+
+
+def is_lock_held(lock_path: str | Path) -> bool:
+    """Return True when another process currently holds the exclusive flock.
+
+    Does not create the lock file when it is missing. A leftover file with
+    no live holder counts as not held.
+    """
+    lock_file = Path(lock_path)
+    if not lock_file.exists():
+        return False
+    try:
+        import fcntl
+    except ImportError:
+        return False
+    try:
+        handle = lock_file.open("r")
+    except OSError:
+        return False
+    try:
+        fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        fcntl.flock(handle, fcntl.LOCK_UN)
+        return False
+    except OSError:
+        return True
+    finally:
+        handle.close()
+
+
+class RunLock:
+    """Per-iteration lock: one agent run at a time per forgeo.
+
+    Held for the duration of one cycle so that a run still in progress (an
+    overlong agent, an orphaned process after a daemon restart) makes the
+    next iteration skip instead of starting a second agent on the same
+    repository.
+    """
+
+    def __init__(self, lock_path: str | Path) -> None:
+        self.lock_path = Path(lock_path)
+
+    @contextmanager
+    def held(self) -> Iterator[bool]:
+        """Acquire for the duration of the block; yields True when acquired."""
+        handle = _take_flock(self.lock_path)
+        try:
+            yield handle is not None
+        finally:
+            if handle is not None:
+                handle.close()
+
+
+class ForgeoDaemon:
+    """Runs :class:`Forgeo` cycles on a fixed schedule until stopped."""
+
+    def __init__(self, config: ForgeoConfig, forgeo: Forgeo) -> None:
+        self.config = config
+        self.forgeo = forgeo
+        self.interval_seconds: float = config.interval_minutes * 60.0
+        self.run_lock = RunLock(config.backlog.with_suffix(".run"))
+        self._stop_event = asyncio.Event()
+        self.pid: int = os.getpid()
+        self.started_at: datetime = datetime.now(UTC)
+        self.last_outcome: str | None = None
+        self.next_run_at: datetime | None = None
+
+    @property
+    def state_file(self) -> Path:
+        """The ``daemon.state.json`` path, next to the backlog's lock files."""
+        return self.config.backlog.with_suffix(".state.json")
+
+    def stop(self) -> None:
+        """Request a graceful shutdown after the current cycle."""
+        self._stop_event.set()
+
+    def write_state(self) -> None:
+        """Atomically persist the daemon's live state for external readers.
+
+        A missing or stale file is fine: readers treat it as unknown state.
+        """
+        payload = {
+            "pid": self.pid,
+            "started_at": self.started_at.isoformat(),
+            "last_outcome": self.last_outcome,
+            "next_run_at": (
+                self.next_run_at.isoformat() if self.next_run_at is not None else None
+            ),
+        }
+        path = self.state_file
+        atomic_write_text(path, json.dumps(payload, indent=2) + "\n")
+
+    async def run_forever(self) -> None:
+        """Wake up on the schedule interval until ``stop()`` is called."""
+        logger.info(
+            "Forgeo %r started (repo=%s, interval=%s min, branch=%s).",
+            self.config.name,
+            self.config.repo,
+            self.config.interval_minutes,
+            self.config.branch,
+        )
+        self.write_state()
+        while not self._stop_event.is_set():
+            try:
+                with self.run_lock.held() as acquired:
+                    if not acquired:
+                        logger.info("Previous run still in progress; skipping this iteration.")
+                        outcome = "skipped"
+                    else:
+                        outcome = await self.forgeo.run_cycle()
+                self.last_outcome = outcome
+                logger.info("Run finished: %s", outcome)
+            except Exception:
+                self.last_outcome = "error"
+                logger.exception("Run crashed; continuing on the next interval.")
+            self.next_run_at = datetime.now(UTC) + timedelta(seconds=self.interval_seconds)
+            self.write_state()
+            try:
+                await asyncio.wait_for(self._stop_event.wait(), timeout=self.interval_seconds)
+            except TimeoutError:
+                pass
+        self.write_state()
+        logger.info("Forgeo stopped.")

forgeo/forgeo.py

@@ -0,0 +1,446 @@
+"""Forgeo: one scheduled run of one repository.
+
+Each run does exactly one of three things:
+
+1. A ``BLOCKED`` task exists -> write the blocker file (the detailed
+   explanation of what the human must do) and pause.
+2. An ``OPEN`` task exists -> execute it with the agent, commit and push the
+   result on the main branch.
+3. The backlog has nothing runnable -> run the agent in refactoring mode on
+   the same branch, committing and pushing whatever it improves.
+
+Whenever the agent signals BLOCKED, its partial work is committed and pushed
+(no branches, nothing lost) and a ``BLOCKER.md`` file is written outside the
+repository with exactly what the human needs to do. Forgeo stays paused
+while that file exists.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from forgeo.agent import BaseAgent
+from forgeo.backlog import JSONBacklog
+from forgeo.git import GitError, GitManager
+from forgeo.models import (
+    ExecutionResult,
+    ExecutionStatus,
+    ForgeoConfig,
+    RepoContext,
+    RunKind,
+    RunOutcome,
+    RunRecord,
+    Task,
+    TaskStatus,
+)
+from forgeo.notify import BlockedNotice, send_blocked_notice
+from forgeo.runs import RunRecorder, runs_path_for
+
+logger = logging.getLogger(__name__)
+
+
+def _execution_outcome(status: ExecutionStatus) -> RunOutcome:
+    """Map an agent execution status onto a run record outcome."""
+    return {
+        ExecutionStatus.SUCCESS: RunOutcome.SUCCESS,
+        ExecutionStatus.BLOCKED: RunOutcome.BLOCKED,
+        ExecutionStatus.ERROR: RunOutcome.ERROR,
+    }[status]
+
+
+def _subject_label(task: Task, *, is_refactor: bool) -> str:
+    """Log subject naming the actor of a message."""
+    return "Refactoring pass" if is_refactor else f"Task {task.id}"
+
+
+@dataclass
+class BlockerEntry:
+    """One blocked run to explain in the blocker file."""
+
+    task: Task
+    result: ExecutionResult
+    instruction: str
+    is_refactor: bool = False
+
+
+class Forgeo:
+    """Executes one scheduled run against a single repository."""
+
+    def __init__(
+        self,
+        config: ForgeoConfig,
+        backlog: JSONBacklog,
+        agent: BaseAgent,
+        git: GitManager,
+    ) -> None:
+        self.config = config
+        self.backlog = backlog
+        self.agent = agent
+        self.git = git
+        self.recorder = RunRecorder(runs_path_for(config.backlog))
+        self._last_task: Task | None = None
+        self._last_agent_result: ExecutionResult | None = None
+        self._last_commit_sha: str | None = None
+        self._blocked_tasks: list[Task] = []
+
+    async def run_cycle(self) -> str:
+        """Execute one run; returns a short outcome label.
+
+        Outcomes: ``blocked``, ``task``, ``paused``, ``refactor``, ``dirty``.
+        Every completed cycle appends exactly one run record.
+        """
+        started_at = datetime.now(UTC)
+        outcome = await self._run_cycle()
+        self._record_run(outcome, started_at)
+        return outcome
+
+    async def _run_cycle(self) -> str:
+        """Execute one cycle without recording; returns its outcome label."""
+        self._last_task = None
+        self._last_agent_result = None
+        self._last_commit_sha = None
+        self._blocked_tasks = []
+        await self.git.a_ensure_branch(self.config.branch)
+        tasks = await self.backlog.list_tasks()
+        blocked = [t for t in tasks if t.status is TaskStatus.BLOCKED]
+        if blocked:
+            self._blocked_tasks = blocked
+            await self._write_blocker(
+                [
+                    BlockerEntry(
+                        task=task,
+                        result=ExecutionResult(
+                            status=ExecutionStatus.BLOCKED,
+                            questions=[f"Task {task.id} is blocked; see the backlog."],
+                        ),
+                        instruction=task.instruction,
+                    )
+                    for task in blocked
+                ]
+            )
+            return "blocked"
+
+        task = await self.backlog.fetch_next_task()
+        if task is not None:
+            if not await self.git.a_is_clean():
+                logger.error(
+                    "Working tree of %s is dirty; refusing to run task %s.",
+                    self.config.repo,
+                    task.id,
+                )
+                return "dirty"
+            await self._run_task(task)
+            return "task"
+
+        if self.config.blocker_file.exists():
+            logger.info("Blocker file present; forgeo paused until it is resolved.")
+            return "paused"
+
+        await self._refactor()
+        return "refactor"
+
+    # ------------------------------------------------------------------ #
+    # Run history                                                         #
+    # ------------------------------------------------------------------ #
+
+    def _record_run(self, outcome: str, started_at: datetime) -> None:
+        """Build and append the run record for a completed cycle."""
+        finished_at = datetime.now(UTC)
+        duration = round((finished_at - started_at).total_seconds(), 3)
+        self.recorder.append(
+            RunRecord(
+                started_at=started_at,
+                finished_at=finished_at,
+                kind=self._run_kind(outcome),
+                task_id=self._run_task_id(outcome),
+                task_title=self._run_task_title(outcome),
+                outcome=self._run_outcome(outcome),
+                agent_exit_code=self._run_exit_code(outcome),
+                commit_sha=self._last_commit_sha if outcome in ("task", "refactor") else None,
+                duration_seconds=duration,
+            )
+        )
+
+    def _run_kind(self, outcome: str) -> RunKind | None:
+        if outcome in ("task", "blocked"):
+            return RunKind.TASK
+        if outcome == "refactor":
+            return RunKind.REFACTOR
+        return None
+
+    def _cycle_task(self, outcome: str) -> Task | None:
+        """The task a finished cycle ran, when there is one to record."""
+        if outcome in ("task", "refactor"):
+            return self._last_task
+        if outcome == "blocked":
+            return self._blocked_tasks[0] if self._blocked_tasks else None
+        return None
+
+    def _run_task_id(self, outcome: str) -> str | None:
+        task = self._cycle_task(outcome)
+        return task.id if task is not None else None
+
+    def _run_task_title(self, outcome: str) -> str | None:
+        task = self._cycle_task(outcome)
+        return task.title if task is not None else None
+
+    def _run_outcome(self, outcome: str) -> RunOutcome:
+        if outcome in ("task", "refactor"):
+            result = self._last_agent_result
+            if result is None:
+                return RunOutcome.ERROR
+            return _execution_outcome(result.status)
+        return {
+            "blocked": RunOutcome.BLOCKED,
+            "paused": RunOutcome.PAUSED,
+            "dirty": RunOutcome.DIRTY,
+            "skipped": RunOutcome.SKIPPED,
+            "error": RunOutcome.ERROR,
+        }.get(outcome, RunOutcome.ERROR)
+
+    def _run_exit_code(self, outcome: str) -> int | None:
+        if outcome not in ("task", "refactor"):
+            return None
+        result = self._last_agent_result
+        return result.exit_code if result is not None else None
+
+    # ------------------------------------------------------------------ #
+    # Task execution                                                      #
+    # ------------------------------------------------------------------ #
+
+    async def _run_task(self, task: Task) -> None:
+        """Execute one task: agent run, then commit/push on the main branch."""
+        logger.info("Running task %s (%s)", task.id, task.title)
+        result, ok = await self._run_agent(
+            task,
+            instruction=task.instruction,
+            success_message=f"forgeo: {task.title} (#{task.id})",
+            blocked_message=f"forgeo: {task.title} (#{task.id}) [partial]",
+            command=task.agent_command,
+            timeout_seconds=task.agent_timeout_seconds,
+        )
+
+        if result.status is ExecutionStatus.BLOCKED:
+            await self.backlog.update_status(task.id, TaskStatus.BLOCKED)
+        if result.status is ExecutionStatus.SUCCESS and ok:
+            await self.backlog.update_status(task.id, TaskStatus.COMPLETED)
+            self.config.blocker_file.unlink(missing_ok=True)
+            logger.info("Task %s completed.", task.id)
+        elif result.status is ExecutionStatus.ERROR:
+            await self.backlog.update_status(task.id, TaskStatus.FAILED)
+
+    async def _run_agent(
+        self,
+        task: Task,
+        *,
+        instruction: str,
+        success_message: str,
+        blocked_message: str,
+        command: str | list[str] | None = None,
+        timeout_seconds: float | None = None,
+        is_refactor: bool = False,
+    ) -> tuple[ExecutionResult, bool]:
+        """Run the agent for one task or refactoring pass and apply the
+        shared SUCCESS / BLOCKED / ERROR side effects (see
+        :meth:`_handle_execution_result`).
+
+        Returns the execution result and whether the SUCCESS commit path
+        succeeded, so callers can apply backlog status transitions.
+        """
+        self._last_task = task
+        result = await self.agent.run_task(
+            task,
+            RepoContext(repo_path=self.config.repo, branch=self.config.branch),
+            command=command,
+            timeout_seconds=timeout_seconds,
+        )
+        self._last_agent_result = result
+        ok = await self._handle_execution_result(
+            result,
+            task=task,
+            success_message=success_message,
+            blocked_message=blocked_message,
+            instruction=instruction,
+            is_refactor=is_refactor,
+        )
+        return result, ok
+
+    async def _handle_execution_result(
+        self,
+        result: ExecutionResult,
+        *,
+        task: Task,
+        success_message: str,
+        blocked_message: str,
+        instruction: str,
+        is_refactor: bool = False,
+    ) -> bool:
+        """Apply shared SUCCESS / BLOCKED / ERROR side effects for an agent run.
+
+        * SUCCESS — commit and push ``success_message``.
+        * BLOCKED — commit partial work under ``blocked_message``, then write
+          the blocker file explaining what the human must do.
+        * ERROR — hard-reset the working tree and log the failure.
+
+        Returns ``True`` only when the result was SUCCESS and the commit path
+        succeeded, so callers can apply backlog status transitions. This
+        method does not update task status itself (except indirectly when
+        ``_commit_and_push`` fails and marks the task FAILED).
+        """
+        if result.status is ExecutionStatus.SUCCESS:
+            return await self._commit_and_push(success_message, task=task)
+
+        if result.status is ExecutionStatus.BLOCKED:
+            if await self._commit_and_push(blocked_message, task=task):
+                entry = BlockerEntry(
+                    task=task,
+                    result=result,
+                    instruction=instruction,
+                    is_refactor=is_refactor,
+                )
+                await self._write_blocker([entry])
+                self._notify_blocked(entry)
+            logger.warning(
+                "%s is BLOCKED; blocker file written.",
+                _subject_label(task, is_refactor=is_refactor),
+            )
+            return False
+
+        await self._discard_failed_work(task, result, is_refactor=is_refactor)
+        return False
+
+    async def _discard_failed_work(
+        self,
+        task: Task,
+        result: ExecutionResult,
+        *,
+        is_refactor: bool = False,
+    ) -> None:
+        """Hard-reset agent changes after ERROR and log the failure detail."""
+        label = _subject_label(task, is_refactor=is_refactor)
+        try:
+            await self.git.a_reset_hard()
+        except GitError as exc:
+            logger.error("Could not discard work for %s: %s", label, exc)
+        detail = result.error or "no error detail provided"
+        logger.error("%s FAILED: %s", label, detail)
+
+    async def _fail(self, task: Task, result: ExecutionResult) -> None:
+        """Discard the agent's work, mark the task FAILED, and log the error."""
+        await self._discard_failed_work(task, result)
+        await self.backlog.update_status(task.id, TaskStatus.FAILED)
+
+    async def _commit_and_push(self, message: str, *, task: Task) -> bool:
+        """Commit everything on the main branch and push when a remote is set.
+
+        Returns ``False`` (and marks the task FAILED) when git refuses to
+        cooperate.
+        """
+        try:
+            sha = await self.git.a_commit_all(message)
+        except GitError as exc:
+            self._last_commit_sha = None
+            await self._fail(
+                task,
+                ExecutionResult(status=ExecutionStatus.ERROR, error=f"git: {exc}"),
+            )
+            return False
+        if sha is None:
+            logger.info("No changes produced; nothing committed.")
+            return True
+        self._last_commit_sha = sha
+        logger.info("Committed %s: %s", sha, message)
+        if self.config.remote:
+            try:
+                await self.git.a_push(self.config.remote, self.config.branch)
+                logger.info("Pushed %s to %s/%s", sha, self.config.remote, self.config.branch)
+            except GitError as exc:
+                logger.error("Push failed (work stays committed locally): %s", exc)
+        return True
+
+    # ------------------------------------------------------------------ #
+    # Refactoring pass                                                    #
+    # ------------------------------------------------------------------ #
+
+    async def _refactor(self) -> None:
+        """Run the agent in refactoring mode; commit and push its changes."""
+        refactor_task = Task(
+            id="REFACTOR",
+            title="Refactoring pass",
+            description=self.config.refactor_prompt,
+        )
+        logger.info("Backlog empty; running refactoring pass.")
+        await self._run_agent(
+            refactor_task,
+            instruction=self.config.refactor_prompt,
+            success_message="forgeo: refactoring pass",
+            blocked_message="forgeo: refactoring pass [partial]",
+            is_refactor=True,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Blocker file                                                        #
+    # ------------------------------------------------------------------ #
+
+    def _notify_blocked(self, entry: BlockerEntry) -> None:
+        """Send a Telegram notification for a newly blocked task or refactor pass.
+
+        The message contains Forgeo name, the task id and title, and the
+        first lines of the blocker reason. Notifications are optional and never
+        change the outcome of the cycle: a failure is only logged.
+        """
+        reason = entry.result.questions or entry.result.output_logs
+        notice = BlockedNotice(
+            task_id=entry.task.id,
+            task_title=entry.task.title,
+            reason="\n".join(reason) if reason else "The agent did not explain what it needs.",
+        )
+        send_blocked_notice(self.config, notice)
+
+    async def _write_blocker(self, entries: list[BlockerEntry]) -> None:
+        """Write the blocker file with a detailed explanation of every block."""
+        sections: list[str] = [
+            "# BLOCKER: Forgeo needs your input",
+            "",
+            "The coding agent could not finish without a human decision. The",
+            f"forgeo is paused until this is resolved. Backlog: `{self.config.backlog}`.",
+            "",
+        ]
+        for entry in entries:
+            sections.append(self._render_entry(entry))
+            sections.append("")
+        self.config.blocker_file.parent.mkdir(parents=True, exist_ok=True)
+        self.config.blocker_file.write_text("\n".join(sections), encoding="utf-8")
+        logger.info("Blocker file written to %s", self.config.blocker_file)
+
+    def _render_entry(self, entry: BlockerEntry) -> str:
+        """Render the explanation and the required human action for one block."""
+        task = entry.task
+        lines = [f"## {task.id}: {task.title}", "", "### What the agent was asked to do", ""]
+        lines += [f"> {line}" for line in entry.instruction.splitlines()]
+        lines += ["", "### What the agent says it needs", ""]
+        questions = entry.result.questions or entry.result.output_logs
+        if not questions:
+            questions = ["The agent did not explain what it needs."]
+        lines += [f"> {line}" for line in questions[-10:]]
+        if entry.is_refactor:
+            lines += [
+                "",
+                "### What you must do",
+                "",
+                "Decide how to handle this refactoring question, then delete this file.",
+                "Forgeo will continue on the next scheduled run.",
+            ]
+        else:
+            lines += [
+                "",
+                "### What you must do",
+                "",
+                "1. Decide what the agent needs (edit the repository directly if required).",
+                f"2. Open `{self.config.backlog}` and set the status of `{task.id}` back to `OPEN`",
+                "   so Forgeo retries it — or delete the task if it should not be done.",
+                "3. Forgeo will retry on the next scheduled run.",
+            ]
+        return "\n".join(lines)