forgeo-cli 0.7.0__tar.gz → 0.7.1__tar.gz

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-08-17
+
+### Added
+
+- An animated demo GIF in the README, showing Forgeo running a backlog task
+  end to end, plus an Open Graph social-preview image for the docs site.
+
+### Changed
+
+- The default agent prompt (used by `forgeo init`) now names `AGENTS.md` and
+  `CONTEXT.md` explicitly when telling the agent to keep project overview and
+  conventions up to date.
+
 ## [0.7.0] - 2026-08-16
 
 ### Added
@@ -308,7 +321,8 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/lucaGazzola/forgeo/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/lucaGazzola/forgeo/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/lucaGazzola/forgeo/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lucaGazzola/forgeo/compare/v0.4.0...v0.5.0

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.7.0
+Version: 0.7.1
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -64,6 +64,10 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/README.md

@@ -10,6 +10,10 @@
 [![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<div align="center">
+  <img src="docs/img/demo.gif" alt="Forgeo running a backlog task end to end" width="720">
+</div>
+
 **Forgeo is a software factory for your coding-agent.**
 You're already working with an AI coding agent, prompting it task by task
 or giving it a goal. Forgeo organizes your work in a structured way with

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/docs/agent-contract.md

@@ -135,8 +135,9 @@ agent_command: >
   Make the code changes requested below and nothing else. Do NOT run
   git commit, git push, or git add -A — Forgeo commits your work.
   Verify with the test suite where applicable.
-  Read AGENTS.md (and CONTEXT.md if present) at the start of the session;
-  if your change materially affects the project overview, keep them updated.
+  Read AGENTS.md at the start of the session, and CONTEXT.md if present;
+  if your change materially affects the project overview or conventions,
+  update AGENTS.md and CONTEXT.md accordingly.
   $FORGEO_TASK"
 ```
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/install.sh

@@ -14,7 +14,7 @@ set -eu
 
 REPO_OWNER="lucaGazzola"
 REPO_NAME="forgeo"
-DEFAULT_VERSION="0.7.0"
+DEFAULT_VERSION="0.7.1"
 MIN_PYTHON="3.11"
 PYPI_PACKAGE="forgeo-cli"
 PREFIX="${FORGEO_PREFIX:-${HOME:-}/.local}"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.7.0"
+version = "0.7.1"
 description = "A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input."
 readme = "README.md"
 requires-python = ">=3.11"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/__init__.py

@@ -7,4 +7,4 @@ try:
 
     __version__ = _pkg_version("forgeo-cli")
 except PackageNotFoundError:  # standalone binary: no installed package metadata
-    __version__ = "0.7.0"
+    __version__ = "0.7.1"

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/central.py

@@ -623,10 +623,21 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
                 logger.exception("Web request failed: %s", urlparse(self.path).path)
                 self._send_json(500, {"error": "internal server error"})
 
-        def do_GET(self) -> None:
+        def _dispatch(self, handler: Callable[[], None]) -> None:
+            """Authorize, then run one request handler safely.
+
+            Shared by the five HTTP verbs: a request is authorized first (a
+            missing or wrong bearer token answers ``401`` without reaching the
+            handler), then the handler runs under :meth:`_run_safely` so a
+            failure is answered with a JSON 500 instead of crashing the
+            server thread.
+            """
             if not self._maybe_authorize(self.path):
                 return
-            self._run_safely(self._do_get)
+            self._run_safely(handler)
+
+        def do_GET(self) -> None:
+            self._dispatch(self._do_get)
 
         def _do_get(self) -> None:
             parsed = urlparse(self.path)
@@ -652,9 +663,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_POST(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_post)
+            self._dispatch(self._do_post)
 
         def _do_post(self) -> None:
             parsed = urlparse(self.path)
@@ -666,9 +675,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_PATCH(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_patch)
+            self._dispatch(self._do_patch)
 
         def _do_patch(self) -> None:
             parsed = urlparse(self.path)
@@ -680,9 +687,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_DELETE(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_delete)
+            self._dispatch(self._do_delete)
 
         def _do_delete(self) -> None:
             parsed = urlparse(self.path)
@@ -694,9 +699,7 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
             self._send_not_found()
 
         def do_PUT(self) -> None:
-            if not self._maybe_authorize(self.path):
-                return
-            self._run_safely(self._do_put)
+            self._dispatch(self._do_put)
 
         def _do_put(self) -> None:
             parsed = urlparse(self.path)
@@ -1230,12 +1233,12 @@ def make_handler(token: str | None = None) -> type[BaseHTTPRequestHandler]:
                     )
                     return
                 recorder = RunRecorder(runs_path(info.config))
-                records = recorder.read(limit=limit, offset=offset)
+                records, total = recorder.read_with_total(limit=limit, offset=offset)
                 self._send_json(
                     200,
                     {
                         "runs": [r.model_dump(mode="json") for r in records],
-                        "total": recorder.total(),
+                        "total": total,
                         "offset": offset,
                         "limit": limit,
                     },
@@ -1367,26 +1370,14 @@ def stop_web(timeout: float = WEB_STOP_TIMEOUT_SECONDS) -> None:
             f"The lock file {lock.lock_path} records no PID; find the dashboard "
             f"with `pgrep -af forgeo` and stop it manually."
         )
-    logger.info("Stopping central dashboard (pid %s)...", pid)
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except ProcessLookupError:
-        if not lock.is_held():
-            logger.info("Central dashboard stopped.")
-            return
-        raise WebLockError(
-            f"Recorded pid {pid} is gone but the lock file is still held; "
-            f"check with `pgrep -af forgeo`."
-        )
-    except PermissionError:
-        raise WebLockError(f"No permission to stop process {pid}.")
-    if daemon_control.wait_for_lock_release(lock.lock_path, timeout, is_held=lock.is_held):
-        lock.release()
-        logger.info("Central dashboard stopped.")
-        return
-    raise WebLockError(
-        f"Central dashboard is still shutting down after {timeout:.0f}s; giving up."
+    daemon_control.signal_and_wait_for_release(
+        pid,
+        name="central dashboard",
+        is_held=lock.is_held,
+        timeout=timeout,
+        error_cls=WebLockError,
     )
+    lock.release()
 
 
 def start_web_detached(

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/cli.py

@@ -317,9 +317,7 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _add_config_or_name(
-    parser: argparse.ArgumentParser, *, default_config: Path = DEFAULT_CONFIG
-) -> None:
+def _add_config_or_name(parser: argparse.ArgumentParser) -> None:
     """Add a mutually-exclusive ``--config``/``--name`` option pair.
 
     ``--config`` keeps its default so plain ``forgeo start`` (etc.) keeps
@@ -330,7 +328,7 @@ def _add_config_or_name(
     group.add_argument(
         "--config",
         type=Path,
-        default=default_config,
+        default=DEFAULT_CONFIG,
         help="Forgeo YAML file (default: forgeo.yaml).",
     )
     group.add_argument(
@@ -654,20 +652,37 @@ def _run_worker_with_lock(
     return result
 
 
-def cmd_once(args: argparse.Namespace) -> int:
-    """Handle ``forgeo once``: run exactly one cycle and exit."""
+def _run_worker_once(
+    args: argparse.Namespace,
+    runner: Callable[[Forgeo], Coroutine[Any, Any, int]],
+) -> int:
+    """Prepare the worker and run one cycle through ``runner``.
+
+    Shared plumbing of ``forgeo once`` and ``forgeo run``: resolve the config,
+    take the per-forgeo lock, run the optional update check, execute exactly
+    one cycle via ``runner``, and release the lock on the way out.
+    """
     prepared = _prepare_worker(args)
     if prepared is None:
         return 1
     _config_path, _config, forgeo, lock = prepared
 
-    async def _run_once() -> int:
+    async def _execute() -> int:
         check_for_update(update_state_path(_config), print_fn=console.print)
+        return await runner(forgeo)
+
+    return _run_worker_with_lock(lock, _execute)
+
+
+def cmd_once(args: argparse.Namespace) -> int:
+    """Handle ``forgeo once``: run exactly one cycle and exit."""
+
+    async def _cycle(forgeo: Forgeo) -> int:
         outcome = await forgeo.run_cycle()
         console.print(f"[green]Cycle finished: {outcome}[/green]")
         return 0
 
-    return _run_worker_with_lock(lock, _run_once)
+    return _run_worker_once(args, _cycle)
 
 
 def cmd_run(args: argparse.Namespace) -> int:
@@ -680,14 +695,9 @@ def cmd_run(args: argparse.Namespace) -> int:
     overlaps them; it refuses (exit 1) when the task does not exist or is
     not ``OPEN``.
     """
-    prepared = _prepare_worker(args)
-    if prepared is None:
-        return 1
-    _config_path, _config, forgeo, lock = prepared
     task_id = args.task
 
-    async def _run_one() -> int:
-        check_for_update(update_state_path(_config), print_fn=console.print)
+    async def _one(forgeo: Forgeo) -> int:
         try:
             outcome = await forgeo.run_task_id(task_id)
         except TaskNotRunnableError as exc:
@@ -696,7 +706,7 @@ def cmd_run(args: argparse.Namespace) -> int:
         console.print(f"[green]Cycle finished: {outcome}[/green]")
         return 0
 
-    return _run_worker_with_lock(lock, _run_one)
+    return _run_worker_once(args, _one)
 
 
 def cmd_init(args: argparse.Namespace) -> int:

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/daemon_control.py

@@ -14,7 +14,6 @@ Everything here is lock-file driven and never touches the config-save flow.
 
 from __future__ import annotations
 
-import functools
 import logging
 import os
 import signal
@@ -65,26 +64,49 @@ def wait_for_process_ready(
     return None
 
 
-def wait_for_lock_release(
-    lock_path: Path,
-    timeout: float,
+def signal_and_wait_for_release(
+    pid: int,
     *,
-    is_held: Callable[[], bool] | None = None,
-) -> bool:
-    """Poll until the lock is released; False on timeout.
-
-    ``is_held`` defaults to the flock-based :func:`is_lock_held`; pass a
-    custom predicate (e.g. a PID-alive check for the web-dashboard lock) to
-    reuse the same wait loop for other lock kinds.
+    name: str,
+    is_held: Callable[[], bool],
+    timeout: float,
+    error_cls: type[Exception],
+    timeout_hint: str = "",
+) -> None:
+    """SIGTERM ``pid`` and wait for the lock it holds to be released.
+
+    Shared by the daemon and the central-dashboard stop commands: SIGTERM the
+    recorded PID, tolerate a process that already exited (as long as its lock
+    is gone too), refuse without permission, and wait for the lock to drop
+    within ``timeout`` (a cycle in progress finishes first). Any failure
+    raises ``error_cls`` — each caller's own error type — with a user-facing
+    message; on success ``name`` is logged as stopped.
     """
-    if is_held is None:
-        is_held = functools.partial(is_lock_held, lock_path)
+    logger.info("Stopping %s (pid %s)...", name, pid)
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        if not is_held():
+            logger.info("%s stopped.", name)
+            return
+        raise error_cls(
+            f"Recorded pid {pid} is gone but the lock is still held; "
+            f"check with `pgrep -af forgeo`."
+        ) from None
+    except PermissionError:
+        raise error_cls(f"No permission to stop process {pid}.") from None
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
         if not is_held():
-            return True
+            logger.info("%s stopped.", name)
+            return
         time.sleep(_POLL_SECONDS)
-    return not is_held()
+    if not is_held():
+        logger.info("%s stopped.", name)
+        return
+    raise error_cls(
+        f"{name} is still shutting down after {timeout:.0f}s{timeout_hint}; giving up."
+    )
 
 
 def stop_daemon(
@@ -103,25 +125,13 @@ def stop_daemon(
             f"The lock file {lock_path} records no PID; find the daemon "
             f"with `pgrep -af forgeo` and stop it manually."
         )
-    logger.info("Stopping forgeo %r (pid %s)...", config.name, pid)
-    try:
-        os.kill(pid, signal.SIGTERM)
-    except ProcessLookupError:
-        if not is_lock_held(lock_path):
-            logger.info("Forgeo %r stopped.", config.name)
-            return
-        raise DaemonError(
-            f"Recorded pid {pid} is gone but the lock is still held; "
-            f"check with `pgrep -af forgeo`."
-        )
-    except PermissionError:
-        raise DaemonError(f"No permission to stop process {pid}.")
-    if wait_for_lock_release(lock_path, timeout):
-        logger.info("Forgeo %r stopped.", config.name)
-        return
-    raise DaemonError(
-        f"Forgeo is still shutting down after {timeout:.0f}s "
-        f"(a cycle in progress finishes first); giving up."
+    signal_and_wait_for_release(
+        pid,
+        name=f"forgeo {config.name!r}",
+        is_held=lambda: is_lock_held(lock_path),
+        timeout=timeout,
+        error_cls=DaemonError,
+        timeout_hint=" (a cycle in progress finishes first)",
     )
 
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/forgeo.py

@@ -62,12 +62,12 @@ class TaskNotRunnableError(RuntimeError):
 
 
 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]
+    """Map an agent execution status onto a run record outcome.
+
+    The two enums share member names for the agent outcomes (SUCCESS, BLOCKED,
+    ERROR), so the mapping is a plain name lookup.
+    """
+    return RunOutcome[status.name]
 
 
 def _subject_label(task: Task, *, is_refactor: bool) -> str:
@@ -82,7 +82,6 @@ class BlockerEntry:
     task: Task
     result: ExecutionResult
     instruction: str
-    is_refactor: bool = False
 
 
 class Forgeo:
@@ -134,10 +133,7 @@ class Forgeo:
         tasks = await self.backlog.list_tasks()
         task = oldest_open_task(tasks)
         if task is not None:
-            if not await self._tree_clean_for(task):
-                return "dirty"
-            await self._run_task(task)
-            return "task"
+            return await self._run_task_clean(task)
 
         if self.config.blocker_file.exists():
             logger.info("Blocker file present; forgeo paused until it is resolved.")
@@ -182,10 +178,7 @@ class Forgeo:
                 f"Task {task_id!r} is {task.status.value}; only OPEN tasks can "
                 f"be run with `forgeo run`."
             )
-        if not await self._tree_clean_for(task):
-            return "dirty"
-        await self._run_task(task)
-        return "task"
+        return await self._run_task_clean(task)
 
     async def _begin_run(self) -> list[Task]:
         """Reset the run state and load the tasks for a new cycle."""
@@ -212,6 +205,18 @@ class Forgeo:
         )
         return False
 
+    async def _run_task_clean(self, task: Task) -> str:
+        """Run ``task`` when the working tree is clean; returns the outcome label.
+
+        Shared by the scheduled pick (:meth:`_run_cycle`) and the explicit
+        ``forgeo run`` (:meth:`_run_task_id`): a dirty tree is refused with a
+        ``dirty`` outcome, otherwise the task runs and the outcome is ``task``.
+        """
+        if not await self._tree_clean_for(task):
+            return "dirty"
+        await self._run_task(task)
+        return "task"
+
     # ------------------------------------------------------------------ #
     # Failed-task retries                                                 #
     # ------------------------------------------------------------------ #
@@ -496,7 +501,6 @@ class Forgeo:
                     task=task,
                     result=result,
                     instruction=instruction,
-                    is_refactor=is_refactor,
                 )
                 if is_refactor:
                     await self._write_blocker([entry])

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/runs.py

@@ -87,10 +87,36 @@ class RunRecorder:
         warning. ``limit=None`` returns every readable record after ``offset``
         (``offset=0`` starts at the newest).
         """
+        records, _ = self.read_with_total(limit, offset)
+        return records
+
+    def read_with_total(
+        self, limit: int | None = None, offset: int = 0
+    ) -> tuple[list[RunRecord], int]:
+        """Return ``(records, total)`` from a single pass over the history.
+
+        ``records`` are the newest ``limit`` records after skipping ``offset``
+        (same shape as :meth:`read`); ``total`` is the count of every readable
+        record, independent of the pagination. This is the pair the web API
+        needs, computed without reading and parsing the file twice.
+        """
+        records, total = self._read_all()
+        if offset > 0:
+            records = records[offset:]
+        if limit is None:
+            return records, total
+        return records[: max(0, limit)], total
+
+    def _read_all(self) -> tuple[list[RunRecord], int]:
+        """Parse the whole history once; returns records (newest first) and count.
+
+        A missing file yields ``([], 0)``; corrupt lines are skipped with a
+        warning, so they never count as records.
+        """
         try:
             text = self.path.read_text(encoding="utf-8", errors="replace")
         except OSError:
-            return []
+            return [], 0
         records: list[RunRecord] = []
         for line_no, line in enumerate(text.splitlines(), start=1):
             if not line.strip():
@@ -102,11 +128,7 @@ class RunRecorder:
                     "Skipping corrupt run record in %s on line %s", self.path, line_no
                 )
         records.sort(key=lambda record: record.finished_at, reverse=True)
-        if offset > 0:
-            records = records[offset:]
-        if limit is None:
-            return records
-        return records[: max(0, limit)]
+        return records, len(records)
 
     def total(self) -> int:
         """The number of readable records in the run history, or ``0``.
@@ -114,7 +136,8 @@ class RunRecorder:
         A missing, empty, or corrupt-only file counts as zero; corrupt lines
         are skipped with a warning, matching :meth:`read`.
         """
-        return len(self.read())
+        _, total = self._read_all()
+        return total
 
     def read_last(self) -> RunRecord | None:
         """Return the most recent record, or ``None`` when none exists."""

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/src/forgeo/setup.py

@@ -57,9 +57,10 @@ DEFAULT_AGENT_PROMPT = (
     "Make the code changes requested below and nothing else. Do NOT run\n"
     "git commit, git push, or git add -A — the forgeo commits your work\n"
     "itself. Verify with the test suite where applicable and, if needed,\n"
-    "update readme, docs and landing page. Read AGENTS.md (and CONTEXT.md\n"
-    "if present) at the start of the session; if your change materially\n"
-    "affects the project overview, keep them updated.\n"
+    "update readme, docs and landing page. Read AGENTS.md at the start of\n"
+    "the session, and CONTEXT.md if present; if your change materially\n"
+    "affects the project overview or conventions, update AGENTS.md and\n"
+    "CONTEXT.md accordingly.\n"
     "$FORGEO_TASK"
 )
 

{forgeo_cli-0.7.0 → forgeo_cli-0.7.1}/tests/test_install.py

@@ -23,7 +23,7 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parents[1]
 INSTALL_SH = REPO_ROOT / "install.sh"
 PYPI_PACKAGE = "forgeo-cli"
-VERSION = "0.7.0"
+VERSION = "0.7.1"
 SH = shutil.which("sh")
 assert SH, "sh must be available to run install.sh"