forgeo-cli 0.3.0__py3-none-any.whl

forgeo/git.py

@@ -0,0 +1,100 @@
+"""Git operations for Forgeo.
+
+Everything happens on a single branch (``main`` by default): commit whatever
+the agent changed, then push. No branches, no PRs, no merge strategies.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class GitError(RuntimeError):
+    """Raised when a git command cannot be executed or fails."""
+
+
+class GitManager:
+    """Run git commands against a single repository (via the git CLI)."""
+
+    def __init__(
+        self, repo_path: str | Path, *, timeout_seconds: float = 120
+    ) -> None:
+        self.repo_path = Path(repo_path)
+        self.timeout_seconds = timeout_seconds
+
+    def _run(self, *args: str, check: bool = True) -> str:
+        """Execute ``git -C <repo> <args>`` and return combined output."""
+        if not shutil.which("git"):
+            raise GitError("the 'git' executable was not found on PATH")
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(self.repo_path), *args],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=self.timeout_seconds,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise GitError(f"git {args[0]} timed out") from exc
+        if check and proc.returncode != 0:
+            raise GitError(
+                f"git {args[0]} failed (exit {proc.returncode}): {proc.stderr.strip() or proc.stdout.strip()}"
+            )
+        return proc.stdout.strip()
+
+    def ensure_branch(self, branch: str) -> None:
+        """Switch to ``branch``, creating it from HEAD when it does not exist."""
+        try:
+            self._run("rev-parse", "--verify", f"refs/heads/{branch}")
+        except GitError:
+            self._run("switch", "-c", branch)
+            return
+        self._run("switch", branch)
+
+    def is_clean(self) -> bool:
+        """Return whether the working tree has no changes."""
+        return not bool(self._run("status", "--porcelain"))
+
+    def commit_all(self, message: str) -> str | None:
+        """Stage all changes and commit; returns the short sha, or ``None`` if nothing to commit."""
+        self._run("add", "-A")
+        if not bool(self._run("status", "--porcelain")):
+            return None
+        self._run("commit", "-m", message)
+        return self._run("rev-parse", "--short", "HEAD")
+
+    def push(self, remote: str, branch: str) -> None:
+        """Push ``branch`` to ``remote``."""
+        self._run("push", remote, branch)
+
+    def reset_hard(self) -> None:
+        """Discard all uncommitted changes in the working tree.
+
+        Reverts tracked files and removes untracked ones (Forgeo only
+        ever discards work after having verified the tree was clean, so
+        everything removed here was produced by the agent).
+        """
+        self._run("reset", "--hard", "HEAD")
+        self._run("clean", "-fd")
+
+    # ------------------------------------------------------------------ #
+    # Async wrappers (run git in a worker thread)                         #
+    # ------------------------------------------------------------------ #
+
+    async def a_ensure_branch(self, branch: str) -> None:
+        await asyncio.to_thread(self.ensure_branch, branch)
+
+    async def a_is_clean(self) -> bool:
+        return await asyncio.to_thread(self.is_clean)
+
+    async def a_commit_all(self, message: str) -> str | None:
+        return await asyncio.to_thread(self.commit_all, message)
+
+    async def a_push(self, remote: str, branch: str) -> None:
+        await asyncio.to_thread(self.push, remote, branch)
+
+    async def a_reset_hard(self) -> None:
+        await asyncio.to_thread(self.reset_hard)

forgeo/instances.py

@@ -0,0 +1,187 @@
+"""Instance registry: a stable name for every configured forgeo.
+
+Each forgeo is configured by its own ``forgeo.yaml`` and runs as its own
+daemon process, but nothing on the host knows how many factories exist or
+how to find their configs. The registry gives every forgeo a unique name
+mapped to the absolute path of its ``forgeo.yaml``, so the CLI can resolve
+a config by name and a single command can enumerate every forgeo.
+
+The registry is a YAML file mapping instance names to config paths. It
+lives at ``$FORGEO_REGISTRY`` or ``~/.config/forgeo/instances.yaml`` and is
+created on the first write. Writes are atomic (temp file + rename), so a
+crash mid-write never corrupts the registry.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from forgeo.config import load_config
+from forgeo.daemon import is_lock_held
+from forgeo.io import atomic_write_text
+from forgeo.models import ForgeoConfig
+
+INSTANCE_NAME_RE = re.compile(r"^[a-zA-Z0-9._-]+$")
+
+DEFAULT_REGISTRY = Path.home() / ".config" / "forgeo" / "instances.yaml"
+
+
+def registry_path() -> Path:
+    """Path of the registry file: ``$FORGEO_REGISTRY`` or the default."""
+    env = os.environ.get("FORGEO_REGISTRY")
+    if env:
+        return Path(env).expanduser()
+    return DEFAULT_REGISTRY
+
+
+def load_registry() -> dict[str, str]:
+    """Load the registry as ``{instance name: absolute config path}``.
+
+    A missing or unreadable file reads as an empty registry.
+    """
+    path = registry_path()
+    if not path.exists():
+        return {}
+    payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        str(name): str(config)
+        for name, config in payload.items()
+        if isinstance(name, str) and isinstance(config, str)
+    }
+
+
+def save_registry(registry: dict[str, str]) -> None:
+    """Persist ``registry`` atomically (temp file + rename)."""
+    atomic_write_text(
+        registry_path(),
+        yaml.safe_dump(dict(sorted(registry.items())), sort_keys=False),
+    )
+
+
+def resolve_instance(name: str) -> Path | None:
+    """Absolute config path for ``name``, or ``None`` when it is not registered."""
+    config_path = load_registry().get(name)
+    return Path(config_path) if config_path else None
+
+
+def _validate_name(name: str) -> None:
+    """Raise ``ValueError`` unless ``name`` matches the allowed pattern."""
+    if not INSTANCE_NAME_RE.fullmatch(name):
+        raise ValueError(
+            f"invalid instance name {name!r}: must match ^[a-zA-Z0-9._-]+$"
+        )
+
+
+def add_instance(name: str, config_path: str | Path) -> str:
+    """Register ``name`` -> the absolute path of ``config_path``.
+
+    Validates that the name is well-formed, that it is not already
+    registered, and that the config file loads. Returns ``name``.
+
+    Raises:
+        ValueError: Invalid or duplicate name, or a config that fails to
+            load (a bad payload raises pydantic's ``ValidationError``).
+        FileNotFoundError: The config file does not exist.
+    """
+    _validate_name(name)
+    registry = load_registry()
+    if name in registry:
+        raise ValueError(f"instance {name!r} is already registered")
+    absolute = Path(config_path).expanduser().resolve()
+    load_config(absolute)
+    registry[name] = str(absolute)
+    save_registry(registry)
+    return name
+
+
+def ensure_registered(name: str, config_path: str | Path) -> bool:
+    """Register ``name`` -> the absolute path of ``config_path`` when missing.
+
+    Unlike :func:`add_instance` this never raises: a name that is already
+    registered (whatever it points at), fails the instance-name pattern, or
+    maps to a config that cannot be loaded is left untouched. Returns
+    ``True`` only when the instance was newly registered.
+    """
+    if name in load_registry():
+        return False
+    if not INSTANCE_NAME_RE.fullmatch(name):
+        return False
+    try:
+        add_instance(name, config_path)
+    except (ValueError, FileNotFoundError, yaml.YAMLError):
+        return False
+    return True
+
+
+def remove_instance(name: str) -> bool:
+    """Unregister ``name``; never touches its config file or repository.
+
+    Returns ``True`` when the instance was registered and removed.
+    """
+    registry = load_registry()
+    if name not in registry:
+        return False
+    del registry[name]
+    save_registry(registry)
+    return True
+
+
+@dataclass(frozen=True)
+class InstanceInfo:
+    """One registered instance plus its live state."""
+
+    name: str
+    config_path: Path
+    repo: Path | None
+    daemon_running: bool
+    config: ForgeoConfig | None = None
+
+
+def _load_info(name: str, config_path: Path) -> InstanceInfo:
+    """Build the live state for one registered instance."""
+    try:
+        config = load_config(config_path)
+    except (ValueError, OSError, yaml.YAMLError):
+        return InstanceInfo(name, config_path, repo=None, daemon_running=False)
+    return InstanceInfo(
+        name=name,
+        config_path=config_path,
+        repo=config.repo,
+        daemon_running=is_lock_held(config.backlog.with_suffix(".lock")),
+        config=config,
+    )
+
+
+def get_instance(name: str) -> InstanceInfo | None:
+    """Build the live state for one registered instance, or ``None``.
+
+    Equivalent to looking up a single entry of :func:`list_instances`; an
+    instance whose config can no longer be loaded is still returned, with
+    ``repo=None``, ``daemon_running=False`` and ``config=None``.
+    """
+    config_path = resolve_instance(name)
+    if config_path is None:
+        return None
+    return _load_info(name, config_path)
+
+
+def list_instances() -> list[InstanceInfo]:
+    """Return every registered instance, sorted by name.
+
+    Each entry carries the config path, the configured repository, and
+    whether that instance's daemon currently holds its backlog lock. An
+    instance whose config can no longer be loaded is still listed, with
+    ``repo=None`` and ``daemon_running=False``.
+    """
+    registry = load_registry()
+    return [
+        _load_info(name, Path(config_path))
+        for name, config_path in sorted(registry.items())
+    ]

forgeo/io.py

@@ -0,0 +1,30 @@
+"""Small filesystem helpers shared across Forgeo modules."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: str | Path, content: str) -> None:
+    """Atomically write ``content`` to ``path`` (temp file + rename).
+
+    A crash mid-write never leaves a partial file at ``path``: the content is
+    first written to a temporary file in the same directory and then moved
+    over ``path`` with ``os.replace``. The parent directory is created when
+    missing. The temporary file is cleaned up if the write fails.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+        os.replace(tmp_name, path)
+    except BaseException:
+        if os.path.exists(tmp_name):
+            os.unlink(tmp_name)
+        raise

forgeo/models.py

@@ -0,0 +1,252 @@
+"""The only data contracts Forgeo needs.
+
+A task lives in the backlog, gets executed by the agent, and changes status
+exactly once per run. A forgeo config describes one repository and how the
+forgeo should work on it.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+DEFAULT_REFACTOR_PROMPT = (
+    "Review the codebase for improvement opportunities that do not change "
+    "behavior: dead code, duplication, overly complex functions, missing "
+    "tests, outdated comments. Apply the safe improvements you find and run "
+    "the test suite to verify nothing broke. If nothing needs refactoring, "
+    "make no changes."
+)
+
+
+def _validate_agent_command(value: str | list[str] | None) -> str | list[str] | None:
+    """Shared validation: an agent command must be a non-blank string or list."""
+    if value is None:
+        return value
+    if isinstance(value, str) and not value.strip():
+        raise ValueError("agent_command must not be blank")
+    if isinstance(value, list) and not value:
+        raise ValueError("agent_command must not be an empty list")
+    return value
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class TaskStatus(str, enum.Enum):
+    OPEN = "OPEN"
+    BLOCKED = "BLOCKED"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+
+class ExecutionStatus(str, enum.Enum):
+    SUCCESS = "SUCCESS"
+    BLOCKED = "BLOCKED"
+    ERROR = "ERROR"
+
+
+class SandboxMode(str, enum.Enum):
+    """How the agent process is isolated from the host machine.
+
+    ``NONE`` runs the agent directly on the host with the user's full
+    privileges (the default, unchanged behavior); ``DOCKER`` runs the agent
+    inside a ``docker run --rm`` container.
+    """
+
+    NONE = "none"
+    DOCKER = "docker"
+
+
+class RunKind(str, enum.Enum):
+    """What kind of work a finished cycle performed."""
+
+    TASK = "task"
+    REFACTOR = "refactor"
+
+
+class RunOutcome(str, enum.Enum):
+    """The outcome of a finished cycle.
+
+    ``SUCCESS``, ``BLOCKED`` and ``ERROR`` mirror the agent execution status;
+    the remaining values cover cycles that paused or never ran the agent.
+    """
+
+    SUCCESS = "SUCCESS"
+    BLOCKED = "BLOCKED"
+    ERROR = "ERROR"
+    PAUSED = "PAUSED"
+    DIRTY = "DIRTY"
+    SKIPPED = "SKIPPED"
+
+
+class RunRecord(BaseModel):
+    """A durable, queryable record of one finished forgeo cycle.
+
+    One JSON object per line in ``runs.jsonl``, next to the backlog.
+    """
+
+    started_at: datetime
+    finished_at: datetime
+    kind: RunKind | None = None
+    task_id: str | None = None
+    task_title: str | None = None
+    outcome: RunOutcome
+    agent_exit_code: int | None = None
+    commit_sha: str | None = None
+    duration_seconds: float
+
+
+class Task(BaseModel):
+    """A unit of work Forgeo executes with the coding agent."""
+
+    id: str
+    title: str
+    description: str
+    dependencies: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    files_to_modify: list[str] = Field(default_factory=list)
+    status: TaskStatus = TaskStatus.OPEN
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    agent_command: str | list[str] | None = Field(default=None)
+    agent_timeout_seconds: float | None = Field(default=None, gt=0)
+
+    @property
+    def instruction(self) -> str:
+        """The full instruction handed to the agent for this task."""
+        lines = [self.title, ""]
+        if self.description:
+            lines.append(self.description)
+        if self.acceptance_criteria:
+            lines.append("Acceptance criteria:")
+            lines.extend(f"- {criterion}" for criterion in self.acceptance_criteria)
+        return "\n".join(lines)
+
+    @field_validator("description")
+    @classmethod
+    def _description_not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("description must be a non-blank string")
+        return value
+
+    @field_validator("agent_command")
+    @classmethod
+    def _command_not_blank(cls, value: str | list[str] | None) -> str | list[str] | None:
+        return _validate_agent_command(value)
+
+
+class ExecutionResult(BaseModel):
+    """The outcome of one agent run."""
+
+    status: ExecutionStatus
+    output_logs: list[str] = Field(default_factory=list)
+    questions: list[str] = Field(default_factory=list)
+    error: str | None = None
+    exit_code: int | None = None
+
+
+class RepoContext(BaseModel):
+    """Where the agent works: the repository checkout and its branch."""
+
+    repo_path: Path = Path(".")
+    branch: str = "main"
+
+
+class ForgeoConfig(BaseModel):
+    """Everything needed to run one forgeo on one repository.
+
+    Attributes:
+        name: Display name of this forgeo (used in logs and commit messages).
+        repo: Path of the git repository Forgeo works on.
+        interval_minutes: How often a scheduled run happens.
+        backlog: Path of the JSON backlog file (created on first use).
+        blocker_file: Where ``BLOCKER.md`` is written when the agent needs
+            human input. Keep it outside the repository so it is never
+            committed.
+        agent_command: Shell command (or argv list) that runs the coding
+            agent. Exit 0 = success, ``blocked_exit_code`` = needs human
+            input, anything else = error. The task is available to the
+            process as the ``FORGEO_TASK`` environment variable.
+        agent_timeout_seconds: Kill the agent process after this many seconds
+            (``None`` = never; a run that overruns the interval simply makes
+            the next iteration skip).
+        agent_env: Extra environment variables for the agent process.
+        agent_sandbox: Isolation mode for the agent process: ``none`` (the
+            default, runs directly on the host) or ``docker`` (runs inside a
+            container). See the README for the docker image expectations.
+        agent_sandbox_image: Container image used when ``agent_sandbox`` is
+            ``docker``. Required in that mode; it must contain the agent CLI
+            and a POSIX shell.
+        agent_sandbox_network: Docker network for the sandboxed agent
+            (``--network``). Default ``none`` (networking disabled); set to
+            e.g. ``bridge`` or ``host`` to re-enable it.
+        agent_sandbox_mounts: Host paths mounted read-only into the sandboxed
+            container at the same absolute path (agent credentials/config).
+            Nothing is mounted unless listed here.
+        blocked_exit_code: Exit code the agent uses to signal that it needs
+            human input.
+        remote: Git remote to push to (e.g. ``origin``). When omitted the
+            forgeo only commits locally.
+        branch: Branch everything is committed to (default ``main``).
+        git_timeout_seconds: Kill a git subprocess after this many seconds
+            (default 120). Raise for slow remotes.
+        refactor_prompt: Instruction used for the refactoring run that
+            happens when the backlog has no runnable task.
+        log_file: Where the scheduled forgeo writes its log.
+        telegram_bot_token: Telegram bot token for blocked-run
+            notifications. Disabled unless ``telegram_chat_id`` is also set.
+        telegram_chat_id: Chat ID that receives blocked-run notifications.
+            Disabled unless ``telegram_bot_token`` is also set.
+    """
+
+    name: str = "forgeo"
+    repo: Path = Field(default=Path("."))
+    interval_minutes: int = Field(default=60, ge=1)
+    backlog: Path = Field(default=Path("backlog.json"))
+    blocker_file: Path = Field(default=Path("BLOCKER.md"))
+    agent_command: str | list[str]
+    agent_timeout_seconds: float | None = Field(default=None, gt=0)
+    agent_env: dict[str, str] = Field(default_factory=dict)
+    agent_sandbox: SandboxMode = SandboxMode.NONE
+    agent_sandbox_image: str | None = None
+    agent_sandbox_network: str = "none"
+    agent_sandbox_mounts: list[str] = Field(default_factory=list)
+    blocked_exit_code: int = Field(default=2)
+    remote: str | None = None
+    branch: str = "main"
+    git_timeout_seconds: float = Field(default=120, gt=0)
+    refactor_prompt: str = DEFAULT_REFACTOR_PROMPT
+    log_file: str = "forgeo.log"
+    telegram_bot_token: str | None = None
+    telegram_chat_id: str | None = None
+
+    @field_validator("agent_command")
+    @classmethod
+    def _command_not_blank(cls, value: str | list[str]) -> str | list[str] | None:
+        return _validate_agent_command(value)
+
+    @field_validator("agent_sandbox_network")
+    @classmethod
+    def _network_not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("agent_sandbox_network must not be blank")
+        return value
+
+    @field_validator("agent_sandbox_mounts")
+    @classmethod
+    def _mounts_not_blank(cls, value: list[str]) -> list[str]:
+        for mount in value:
+            if not mount.strip():
+                raise ValueError("agent_sandbox_mounts must not contain blank paths")
+        return value
+
+    @model_validator(mode="after")
+    def _docker_requires_image(self) -> ForgeoConfig:
+        if self.agent_sandbox is SandboxMode.DOCKER and not (self.agent_sandbox_image or "").strip():
+            raise ValueError("agent_sandbox_image is required when agent_sandbox is 'docker'")
+        return self

forgeo/notify.py

@@ -0,0 +1,77 @@
+"""Optional Telegram notifications for blocked runs.
+
+The feature is disabled unless both ``telegram_bot_token`` and
+``telegram_chat_id`` are set in Forgeo config. Uses only the standard
+library and never raises: a failing notification is logged as a warning and
+the outcome of Forgeo cycle is left unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+from forgeo.models import ForgeoConfig
+
+logger = logging.getLogger(__name__)
+
+SEND_MESSAGE_URL = "https://api.telegram.org/bot{token}/sendMessage"
+REQUEST_TIMEOUT = 5.0
+REASON_LINES = 8
+
+
+@dataclass
+class BlockedNotice:
+    """The payload of one blocked-run notification."""
+
+    task_id: str
+    task_title: str
+    reason: str
+
+
+def blocked_notice_text(forgeo_name: str, notice: BlockedNotice) -> str:
+    """Compose the message body: forgeo name, task id/title, and the reason."""
+    lines = [
+        f"\u26d4 {forgeo_name} is blocked",
+        f"Task {notice.task_id}: {notice.task_title}",
+        "",
+        *notice.reason.splitlines()[:REASON_LINES],
+    ]
+    return "\n".join(lines)
+
+
+def send_blocked_notice(config: ForgeoConfig, notice: BlockedNotice) -> bool:
+    """Send one ``sendMessage`` request; returns True when delivered.
+
+    Returns ``False`` without a warning when the feature is not configured
+    (no notification is expected). Returns ``False`` and logs a warning when
+    Telegram rejects or is unreachable — a notification failure never changes
+    the outcome of Forgeo cycle.
+    """
+    if not config.telegram_bot_token or not config.telegram_chat_id:
+        return False
+    payload = {
+        "chat_id": config.telegram_chat_id,
+        "text": blocked_notice_text(config.name, notice),
+    }
+    url = SEND_MESSAGE_URL.format(token=config.telegram_bot_token)
+    request = urllib.request.Request(
+        url,
+        data=urllib.parse.urlencode(payload).encode("utf-8"),
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT) as response:
+            if response.status != 200:
+                logger.warning(
+                    "Telegram notification failed: HTTP %s from %s.",
+                    response.status,
+                    url,
+                )
+                return False
+    except (OSError, ValueError) as exc:
+        logger.warning("Telegram notification failed: %s", exc)
+        return False
+    logger.info("Telegram notification sent for blocked run of task %s.", notice.task_id)
+    return True