forgeo-cli 0.3.0__py3-none-any.whl

forgeo/__init__.py

@@ -0,0 +1,10 @@
+"""Forgeo: a scheduled software forgeo that executes backlog tasks
+on the main branch and refactors when idle."""
+
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("forgeo-cli")
+except PackageNotFoundError:  # standalone binary: no installed package metadata
+    __version__ = "0.3.0"

forgeo/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running Forgeo as a module: ``python -m forgeo``."""
+
+from forgeo.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

forgeo/agent.py

@@ -0,0 +1,332 @@
+"""The coding agent: any shell command that implements the task.
+
+The configured command is run with the repository as its working directory.
+The task is delivered to the agent as the ``FORGEO_TASK`` environment
+variable (title, description, acceptance criteria) so any CLI coding tool
+(aider, claude, a custom script, ...) can consume it. The exit code decides
+the outcome:
+
+* ``0`` — SUCCESS, the work is committed and pushed,
+* ``blocked_exit_code`` (default ``2``) — BLOCKED, the agent needs human
+  input; its output ends up in the blocker file,
+* anything else — ERROR, the task fails and the agent's changes are
+  discarded.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import signal
+from abc import ABC, abstractmethod
+from collections import deque
+
+from forgeo.models import ExecutionResult, ExecutionStatus, RepoContext, Task
+
+# Keep only the most recent process output lines so a chatty agent cannot
+# blow memory; header/footer status lines are added around this window.
+_MAX_OUTPUT_LINES = 1000
+
+# Hard cap on how long we wait for the output streams to reach EOF after the
+# process is done (or killed). Grandchildren that escaped the process group
+# (daemonized agents, docker containers) may hold the pipes open forever;
+# Forgeo must never hang on that.
+_DEFAULT_DRAIN_TIMEOUT_SECONDS = 30.0
+
+
+def _kill_process_group(proc: asyncio.subprocess.Process) -> None:
+    """SIGKILL the whole process group of a spawned agent.
+
+    ``proc.kill()`` only kills the direct child (for a string command, the
+    shell); the real agent often runs as a grandchild, which would survive
+    as an orphan and keep the output pipes open. The agent is spawned in its
+    own session (``start_new_session=True``), so ``proc.pid`` is its process
+    group id and killing the group reaps the entire process tree. Falls back
+    to killing just the direct child when the group is already gone.
+    """
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        proc.kill()
+    except PermissionError:
+        proc.kill()
+
+
+class SandboxUnavailableError(RuntimeError):
+    """The configured sandbox backend cannot run on this host."""
+
+
+class BaseAgent(ABC):
+    """Uniform interface for invoking a coding agent on a task."""
+
+    name: str = "base"
+
+    @abstractmethod
+    async def run_task(
+        self,
+        task: Task,
+        context: RepoContext,
+        *,
+        command: str | list[str] | None = None,
+        timeout_seconds: float | None = None,
+    ) -> ExecutionResult:
+        """Execute one task and return its result.
+
+        ``command`` and ``timeout_seconds`` optionally override the agent's
+        configured values for this single task; ``None`` means "use the
+        configured default".
+
+        Implementations must never raise for expected agent failures — they
+        should encode them as ``ExecutionResult(status=ERROR)``.
+        """
+
+
+class ShellAgent(BaseAgent):
+    """Runs ``ForgeoConfig.agent_command`` in a subprocess."""
+
+    name = "shell"
+
+    def __init__(
+        self,
+        command: str | list[str],
+        *,
+        timeout_seconds: float | None = None,
+        drain_timeout_seconds: float = _DEFAULT_DRAIN_TIMEOUT_SECONDS,
+        env: dict[str, str] | None = None,
+        blocked_exit_code: int = 2,
+    ) -> None:
+        self.command = command
+        self.timeout_seconds = timeout_seconds
+        self.drain_timeout_seconds = drain_timeout_seconds
+        self.env = dict(env or {})
+        self.blocked_exit_code = blocked_exit_code
+
+    @staticmethod
+    async def _drain_stream(
+        stream: asyncio.StreamReader | None,
+        prefix: str,
+        lines: deque[str],
+    ) -> None:
+        """Read ``stream`` line-by-line into ``lines`` until EOF."""
+        if stream is None:
+            return
+        while True:
+            raw = await stream.readline()
+            if not raw:
+                break
+            text = raw.decode(errors="replace").rstrip("\r\n")
+            lines.append(f"[{prefix}] {text}")
+
+    async def _spawn(
+        self,
+        command: str | list[str],
+        cwd: str,
+        env: dict[str, str],
+    ) -> asyncio.subprocess.Process:
+        """Start the agent process; returns a handle to it.
+
+        Subclasses (e.g. sandboxes) override this to change *how* the command
+        runs; the exit-code contract and output handling stay in ``run_task``.
+        """
+        if isinstance(command, str):
+            return await asyncio.create_subprocess_shell(
+                command,
+                cwd=cwd,
+                env=env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                start_new_session=True,
+            )
+        return await asyncio.create_subprocess_exec(
+            *command,
+            cwd=cwd,
+            env=env,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+        )
+
+    async def run_task(
+        self,
+        task: Task,
+        context: RepoContext,
+        *,
+        command: str | list[str] | None = None,
+        timeout_seconds: float | None = None,
+    ) -> ExecutionResult:
+        """Run the configured command once for the task.
+
+        ``command`` and ``timeout_seconds`` override this agent's configured
+        values for this run when given; otherwise the configured defaults are
+        used.
+        """
+        command = command if command is not None else self.command
+        timeout = timeout_seconds if timeout_seconds is not None else self.timeout_seconds
+        logs: list[str] = [f"[{self.name}] Running task {task.id} ({task.title})"]
+        env = {
+            **os.environ,
+            **self.env,
+            "FORGEO_TASK": task.instruction,
+            "FORGEO_REPO": str(context.repo_path),
+            "FORGEO_BRANCH": context.branch,
+        }
+
+        try:
+            proc = await self._spawn(command, str(context.repo_path), env)
+        except FileNotFoundError as exc:
+            logs.append(f"[{self.name}] Command not found: {exc}")
+            return ExecutionResult(
+                status=ExecutionStatus.ERROR,
+                output_logs=logs,
+                error=f"command not found: {exc}",
+            )
+
+        stream_lines: deque[str] = deque(maxlen=_MAX_OUTPUT_LINES)
+        readers = asyncio.gather(
+            self._drain_stream(proc.stdout, "stdout", stream_lines),
+            self._drain_stream(proc.stderr, "stderr", stream_lines),
+        )
+
+        timed_out = False
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=timeout)
+        except TimeoutError:
+            timed_out = True
+            _kill_process_group(proc)
+            await proc.wait()
+        # Always finish draining so lines already written (and any residual
+        # after kill) are captured before we build the result. Bounded: a
+        # grandchild that escaped the process group (daemonized agent, docker
+        # container) may hold the pipes open, and Forgeo must never hang
+        # waiting for EOF that will not come.
+        try:
+            await asyncio.wait_for(readers, timeout=self.drain_timeout_seconds)
+        except TimeoutError:
+            logs.append(
+                f"[{self.name}] Output streams stayed open beyond "
+                f"{self.drain_timeout_seconds:g}s; proceeding without them."
+            )
+        logs.extend(stream_lines)
+
+        if timed_out:
+            label = f" after {timeout:g}s" if timeout is not None else ""
+            logs.append(f"[{self.name}] Execution timed out{label}; process killed.")
+            return ExecutionResult(
+                status=ExecutionStatus.ERROR,
+                output_logs=logs,
+                error=f"timed out{label}",
+            )
+
+        if proc.returncode == 0:
+            logs.append(f"[{self.name}] Task {task.id} finished successfully (exit 0).")
+            return ExecutionResult(
+                status=ExecutionStatus.SUCCESS,
+                output_logs=logs,
+                exit_code=proc.returncode,
+            )
+
+        if proc.returncode == self.blocked_exit_code:
+            logs.append(f"[{self.name}] Task {task.id} needs human input (exit {proc.returncode}).")
+            return ExecutionResult(
+                status=ExecutionStatus.BLOCKED,
+                output_logs=logs,
+                questions=[line for line in logs if line.startswith(("[stdout]", "[stderr]"))],
+                exit_code=proc.returncode,
+            )
+
+        logs.append(f"[{self.name}] Task {task.id} failed with exit code {proc.returncode}.")
+        return ExecutionResult(
+            status=ExecutionStatus.ERROR,
+            output_logs=logs,
+            error=f"exit code {proc.returncode}",
+            exit_code=proc.returncode,
+        )
+
+
+# Environment variables set by ``run_task`` and forwarded into the container.
+_SANDBOX_FORWARDED_ENV = ("FORGEO_TASK", "FORGEO_REPO", "FORGEO_BRANCH")
+
+
+class DockerSandboxAgent(ShellAgent):
+    """Runs the agent command inside a ``docker run --rm`` container.
+
+    The repository is bind-mounted at its absolute path (so the agent's edits
+    land on the host checkout), ``FORGEO_TASK`` and ``agent_env`` are passed
+    through as environment variables, and networking is disabled
+    (``--network none``) unless a network is configured explicitly. Agent
+    credentials/config are only visible inside the container when listed in
+    ``mounts`` (mounted read-only at the same path). The container exit code
+    is mapped exactly like the shell agent's: ``0`` success,
+    ``blocked_exit_code`` needs human input, anything else is an error.
+
+    The image is expected to contain the agent CLI (e.g. ``claude``) and a
+    POSIX shell (``sh``) for string commands.
+    """
+
+    name = "docker"
+
+    def __init__(
+        self,
+        command: str | list[str],
+        *,
+        image: str,
+        network: str = "none",
+        mounts: list[str] | None = None,
+        timeout_seconds: float | None = None,
+        env: dict[str, str] | None = None,
+        blocked_exit_code: int = 2,
+    ) -> None:
+        if not (image or "").strip():
+            raise ValueError("docker sandbox requires an image")
+        if shutil.which("docker") is None:
+            raise SandboxUnavailableError(
+                "agent_sandbox: docker is configured but the `docker` binary was "
+                "not found on PATH."
+            )
+        super().__init__(
+            command,
+            timeout_seconds=timeout_seconds,
+            env=env,
+            blocked_exit_code=blocked_exit_code,
+        )
+        self.image = image
+        self.network = network
+        self.mounts = [mount for mount in (mounts or []) if mount]
+
+    def _docker_args(
+        self,
+        command: str | list[str],
+        cwd: str,
+        env: dict[str, str],
+    ) -> list[str]:
+        """Build the ``docker run`` argv for one agent execution."""
+        args = ["docker", "run", "--rm", "--network", self.network, "-w", cwd]
+        args += ["-v", f"{cwd}:{cwd}"]
+        forwarded = set(_SANDBOX_FORWARDED_ENV) | set(self.env)
+        for key in sorted(forwarded):
+            if key in env:
+                args += ["-e", f"{key}={env[key]}"]
+        for mount in self.mounts:
+            args += ["-v", f"{mount}:{mount}:ro"]
+        args.append(self.image)
+        if isinstance(command, str):
+            args += ["sh", "-c", command]
+        else:
+            args += list(command)
+        return args
+
+    async def _spawn(
+        self,
+        command: str | list[str],
+        cwd: str,
+        env: dict[str, str],
+    ) -> asyncio.subprocess.Process:
+        return await asyncio.create_subprocess_exec(
+            *self._docker_args(command, cwd, env),
+            cwd=cwd,
+            env=env,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+        )

forgeo/backlog.py

@@ -0,0 +1,206 @@
+"""The backlog: a single human-readable JSON file of tasks.
+
+Forgeo pulls the oldest ``OPEN`` task from here. Edit this file
+directly to add, remove, or reopen tasks (e.g. set a ``BLOCKED`` task back
+to ``OPEN`` once the human input has been provided). Writes are atomic and
+serialized through an asyncio lock.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+
+from forgeo.io import atomic_write_text
+from forgeo.models import Task, TaskStatus
+
+logger = logging.getLogger(__name__)
+
+#: The task fields the web console may edit through ``update_task``.
+EDITABLE_TASK_FIELDS = frozenset(
+    {
+        "title",
+        "description",
+        "acceptance_criteria",
+        "dependencies",
+        "files_to_modify",
+        "agent_command",
+        "agent_timeout_seconds",
+    }
+)
+
+
+def oldest_open_task(tasks: list[Task]) -> Task | None:
+    """Return the oldest OPEN task (smallest ``created_at``), or ``None``."""
+    open_tasks = [task for task in tasks if task.status is TaskStatus.OPEN]
+    if not open_tasks:
+        return None
+    return min(open_tasks, key=lambda task: task.created_at)
+
+
+def backlog_status_counts(tasks: list[Task]) -> dict[str, int]:
+    """Count tasks by status; always includes every known status key."""
+    counts = {status.value: 0 for status in TaskStatus}
+    counts.update(Counter(task.status.value for task in tasks))
+    return counts
+
+
+class JSONBacklog:
+    """A backlog stored in a single JSON document on disk."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self._lock = asyncio.Lock()
+
+    async def list_tasks(self) -> list[Task]:
+        """Return all tasks, in the order they were created."""
+        store = await self._read()
+        return [self._to_task(entry) for entry in store["tasks"]]
+
+    async def fetch_next_task(self) -> Task | None:
+        """Return the oldest OPEN task, or ``None`` when there is none."""
+        return oldest_open_task(await self.list_tasks())
+
+    async def get_task(self, task_id: str) -> Task | None:
+        """Return a task by id, or ``None`` if it does not exist."""
+        store = await self._read()
+        for entry in store["tasks"]:
+            if entry["id"] == task_id:
+                return self._to_task(entry)
+        return None
+
+    async def create_task(self, task: Task) -> Task:
+        """Persist ``task``, rejecting duplicate ids with a ``ValueError``."""
+        async with self._lock:
+            store = await self._read()
+            if any(entry["id"] == task.id for entry in store["tasks"]):
+                raise ValueError(f"Task id already exists in backlog: {task.id!r}")
+            store["tasks"].append(task.model_dump(mode="json"))
+            await self._write(store)
+        return task
+
+    async def update_status(self, task_id: str, status: TaskStatus) -> Task | None:
+        """Transition a task's status, bumping its ``updated_at`` timestamp."""
+        async with self._lock:
+            store = await self._read()
+            updated: Task | None = None
+            for entry in store["tasks"]:
+                if entry["id"] == task_id:
+                    entry["status"] = status.value
+                    entry["updated_at"] = datetime.now(UTC).isoformat()
+                    updated = self._to_task(entry)
+                    break
+            if updated is not None:
+                await self._write(store)
+        return updated
+
+    async def update_task(
+        self, task_id: str, updates: dict[str, Any]
+    ) -> Task | None:
+        """Update a task's editable fields, bumping its ``updated_at``.
+
+        ``updates`` may contain any of :data:`EDITABLE_TASK_FIELDS`; ``id``,
+        ``status``, ``created_at`` and ``updated_at`` are never replaced
+        (except ``updated_at``, bumped to now). Unknown fields and invalid
+        values raise a ``ValueError``; an unknown ``task_id`` returns ``None``
+        (mirroring :meth:`update_status`). Writes go through the same lock
+        and atomic-replace path as the other mutators.
+        """
+        if not isinstance(updates, dict):
+            raise TypeError("updates must be a dict of task fields")
+        unknown = set(updates) - EDITABLE_TASK_FIELDS
+        if unknown:
+            raise ValueError(
+                f"unknown task field(s): {', '.join(sorted(unknown))}"
+            )
+        for field in ("title", "description"):
+            if field in updates and not isinstance(updates[field], str):
+                raise ValueError(f"{field} must be a string")
+        if "title" in updates and not updates["title"].strip():
+            raise ValueError("title must be a non-blank string")
+        if "description" in updates and not updates["description"].strip():
+            raise ValueError("description must be a non-blank string")
+        for field in ("acceptance_criteria", "dependencies", "files_to_modify"):
+            if field in updates and (
+                not isinstance(updates[field], list)
+                or not all(isinstance(item, str) for item in updates[field])
+            ):
+                raise ValueError(f"{field} must be a list of strings")
+
+        async with self._lock:
+            store = await self._read()
+            for entry in store["tasks"]:
+                if entry["id"] != task_id:
+                    continue
+                candidate = dict(entry)
+                candidate.update(updates)
+                candidate["updated_at"] = datetime.now(UTC).isoformat()
+                try:
+                    task = Task.model_validate(candidate)
+                except ValidationError as exc:
+                    raise ValueError(f"invalid task field(s): {exc}") from exc
+                normalized = task.model_dump(mode="json")
+                for field in updates:
+                    entry[field] = normalized[field]
+                entry["updated_at"] = normalized["updated_at"]
+                await self._write(store)
+                return task
+        return None
+
+    # ------------------------------------------------------------------ #
+    # Internal persistence helpers                                        #
+    # ------------------------------------------------------------------ #
+
+    async def _read(self) -> dict[str, Any]:
+        """Load the store from disk, tolerating a missing or corrupt file."""
+        if not self.path.exists():
+            return {"tasks": []}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%f")
+            corrupt_path = self.path.with_name(f"{self.path.name}.corrupt-{timestamp}")
+            try:
+                self.path.rename(corrupt_path)
+                logger.warning(
+                    "Corrupt backlog at %s renamed to %s; starting with empty store",
+                    self.path,
+                    corrupt_path,
+                )
+            except OSError:
+                logger.warning(
+                    "Corrupt backlog at %s could not be preserved; starting with empty store",
+                    self.path,
+                )
+            return {"tasks": []}
+        if not isinstance(data, dict):
+            return {"tasks": []}
+        tasks = data.get("tasks")
+        return {"tasks": tasks if isinstance(tasks, list) else []}
+
+    async def _write(self, store: dict[str, Any]) -> None:
+        """Atomically persist the store (temp file + rename)."""
+        atomic_write_text(
+            self.path,
+            json.dumps(store, indent=2, ensure_ascii=False) + "\n",
+        )
+
+    @staticmethod
+    def _to_task(entry: dict[str, Any]) -> Task:
+        """Validate a stored dictionary back into a Task, skipping corrupt rows."""
+        try:
+            return Task.model_validate(entry)
+        except ValidationError:
+            return Task(
+                id=str(entry.get("id", "<unknown>")),
+                title="<unparsable task>",
+                description="<unparsable task>",
+                status=TaskStatus.FAILED,
+            )