forgeo-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-10
+
+### Added
+
+- Delete OPEN tasks from the web console: a Delete button (with
+  confirmation) in the task detail modal, backed by `DELETE
+  /api/instances/<name>/tasks/<id>` and `JSONBacklog.delete_task`.
+- Resolve BLOCKED tasks from the web console: the task modal shows the
+  blocker reason and can reopen the task (back to `OPEN`) via `POST
+  /api/instances/<name>/tasks/<id>/reopen`.
+- The web console stays usable with many tasks: non-OPEN columns collapse
+  behind count badges with an expand toggle, so a long backlog no longer
+  renders every task as a tall card up front.
+- The failure/block reason is shown prominently in the task detail modal.
+- Config editing from the web console: `PUT /api/instances/<name>/config`
+  validates and persists `forgeo.yaml` changes, and a new Config tab in the
+  instance page edits the fields in a form (with a restart hint).
+- Daemon control from the web console: start, stop, and restart an
+  instance's daemon from the top bar via `POST
+  /api/instances/<name>/{start,stop,restart}`.
+- `forgeo init` now asks only for the bare agent command and appends the
+  task prompt automatically.
+
+### Changed
+
+- Commit messages no longer carry the `forgeo: ` prefix.
+- The instance is registered before the run lock is taken, so a `--name`
+  lookup never fails while starting.
+- README revised for clarity and formatting.
+
+## [0.3.0] - 2026-08-07
+
 ### Added
 
 - `forgeo web [--host HOST] [--port PORT]` — a standalone central dashboard
@@ -22,6 +54,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Task editing in the web console: the task detail modal gained an **Edit**
   mode (Save/Cancel), backed by a new `PATCH
   /api/instances/<name>/tasks/<id>` endpoint and `JSONBacklog.update_task`.
+- PyPI publishing: tagging a release now also publishes the `forgeo-cli`
+  wheel and sdist to PyPI via trusted publishing.
 
 ### Changed
 
@@ -108,7 +142,9 @@ 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.2.1...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.3.0...HEAD
+[0.4.0]: https://github.com/lucaGazzola/forgeo/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.3.0
 [0.2.1]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/lucaGazzola/forgeo/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/lucaGazzola/forgeo/releases/tag/v0.1.0

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forgeo-cli
-Version: 0.3.0
+Version: 0.4.0
 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,32 +64,30 @@ 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)
 
-**Forgeo is an autonomous software forgeo for people with ideas, not teams.**
-You have a product idea — an app, a website, an internal automation — but no
-developers on staff. With Forgeo you don't need any: you write down what needs
-to be built as a simple list of tasks, and an AI coding agent works through the
-list on its own, writing the code and committing it to your repository. No
-branches, no pull requests, no developer to hire.
+**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
+a backlog, and it decides what to work on next, runs your
+agent on it, and commits the result. Progress, pending decisions, and history
+are tracked in plain files you can inspect at any time, plus a web dashboard.
+Forgeo only interrupts you when a decision is genuinely yours to
+make, everything else happens autonomously.
 
 All you need is basic comfort with a terminal, a git repository, and any coding
-agent CLI — Claude Code, aider, opencode, or your own script. Forgeo works with
-all of them.
-
-Forgeo decides what to do next on its own: while tasks are left it implements
-the oldest one and commits the result, and when the backlog is empty it reviews
-the codebase and cleans it up. It only interrupts you when a decision is
-genuinely yours to make — everything else happens autonomously.
+agent CLI.
 
 ## Quickstart
 
-Requires a git repository (no Python needed — the one-liner downloads a
-prebuilt binary for your OS, or `pipx install forgeo-cli` works too). The full
-walkthrough is in [Getting started](docs/getting-started.md).
+The full walkthrough is in [Getting started](docs/getting-started.md).
 
 ```bash
 # 1. Install
 curl -fsSL https://forgeo.org/install.sh | bash
 
+or
+
+pipx install forgeo-cli
+
 # 2. Create your Forgeo (guided wizard, run from your project root)
 forgeo init
 
@@ -98,18 +96,17 @@ forgeo start   # run forever: every interval_minutes, implement the oldest OPEN
 ```
 
 `forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
-and logs, gitignored for you. Fill the backlog with plain JSON tasks (see
-[Backlog format](docs/backlog.md)) — or add them from the web console while
-it runs — and Forgeo does the rest. The daemon binds no ports; open the
-dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+and logs. Fill the backlog with plain JSON tasks (see
+[Backlog format](docs/backlog.md)) or add them from the web console while
+it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
 
 ![Forgeo web console](docs/img/console.png)
 
 One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo stop`, `forgeo restart` — every command is in the
+`forgeo stop`, `forgeo restart`, every command is in the
 [CLI reference](docs/cli-reference.md).
 
-You can run several factories at once, one per repository — each config is
+You can run several factories at once, one per repository, each config is
 fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
 in the instance registry with `forgeo instance add NAME --config PATH`,
 manage any of them by name with `forgeo start/status/stop --name NAME`,

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/README.md

@@ -10,32 +10,30 @@
 [![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)
 
-**Forgeo is an autonomous software forgeo for people with ideas, not teams.**
-You have a product idea — an app, a website, an internal automation — but no
-developers on staff. With Forgeo you don't need any: you write down what needs
-to be built as a simple list of tasks, and an AI coding agent works through the
-list on its own, writing the code and committing it to your repository. No
-branches, no pull requests, no developer to hire.
+**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
+a backlog, and it decides what to work on next, runs your
+agent on it, and commits the result. Progress, pending decisions, and history
+are tracked in plain files you can inspect at any time, plus a web dashboard.
+Forgeo only interrupts you when a decision is genuinely yours to
+make, everything else happens autonomously.
 
 All you need is basic comfort with a terminal, a git repository, and any coding
-agent CLI — Claude Code, aider, opencode, or your own script. Forgeo works with
-all of them.
-
-Forgeo decides what to do next on its own: while tasks are left it implements
-the oldest one and commits the result, and when the backlog is empty it reviews
-the codebase and cleans it up. It only interrupts you when a decision is
-genuinely yours to make — everything else happens autonomously.
+agent CLI.
 
 ## Quickstart
 
-Requires a git repository (no Python needed — the one-liner downloads a
-prebuilt binary for your OS, or `pipx install forgeo-cli` works too). The full
-walkthrough is in [Getting started](docs/getting-started.md).
+The full walkthrough is in [Getting started](docs/getting-started.md).
 
 ```bash
 # 1. Install
 curl -fsSL https://forgeo.org/install.sh | bash
 
+or
+
+pipx install forgeo-cli
+
 # 2. Create your Forgeo (guided wizard, run from your project root)
 forgeo init
 
@@ -44,18 +42,17 @@ forgeo start   # run forever: every interval_minutes, implement the oldest OPEN
 ```
 
 `forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
-and logs, gitignored for you. Fill the backlog with plain JSON tasks (see
-[Backlog format](docs/backlog.md)) — or add them from the web console while
-it runs — and Forgeo does the rest. The daemon binds no ports; open the
-dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+and logs. Fill the backlog with plain JSON tasks (see
+[Backlog format](docs/backlog.md)) or add them from the web console while
+it runs, Forgeo does the rest. Open the dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
 
 ![Forgeo web console](docs/img/console.png)
 
 One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
-`forgeo stop`, `forgeo restart` — every command is in the
+`forgeo stop`, `forgeo restart`, every command is in the
 [CLI reference](docs/cli-reference.md).
 
-You can run several factories at once, one per repository — each config is
+You can run several factories at once, one per repository, each config is
 fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
 in the instance registry with `forgeo instance add NAME --config PATH`,
 manage any of them by name with `forgeo start/status/stop --name NAME`,

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/docs/agent-contract.md

@@ -1,7 +1,6 @@
 # Agent contract
 
-The coding agent is **any shell command** — a CLI coding tool (aider, Claude
-Code, a custom script) or a plain command. It must be able to:
+The coding agent is **any shell command**: a CLI coding tool or a plain command. It must be able to:
 
 1. read the task from the `FORGEO_TASK` environment variable,
 2. work on the repository from the current working directory,
@@ -39,8 +38,8 @@ The exit code decides the outcome of the run:
 
 | Exit code | Outcome | What happens |
 | --- | --- | --- |
-| `0` | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `forgeo: <title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
-| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `forgeo: <title> (#<id>) [partial]`, `BLOCKER.md` is written explaining what you must do, an optional Telegram notification is sent, and the task is marked `BLOCKED`. |
+| `0` | **SUCCESS** | Everything is committed (`git add -A && git commit`) with the message `<title> (#<id>)`, pushed when a remote is set, and the task is marked `COMPLETED`. |
+| `blocked_exit_code` (default `2`) | **BLOCKED** | The agent needs a human decision. Partial work is committed as `<title> (#<id>) [partial]`, the agent's reason is persisted on the task (`blocker_reason`), an optional Telegram notification is sent, and the task is marked `BLOCKED`. `BLOCKER.md` is rendered from the backlog's `BLOCKED` tasks on the next cycle — real per-task reasons, never generic text — and disappears once the last one is resolved (reopen it from the web console). |
 | anything else | **ERROR** | Changes are discarded (`git reset --hard` + `git clean -fd`), the failure is logged, and the task is marked `FAILED`. |
 
 The blocked exit code is configurable via `blocked_exit_code` in
@@ -73,8 +72,9 @@ interrupted.
 The agent's stdout and stderr are captured live, prefixed with `[stdout]` /
 `[stderr]`, and retained in the run result. To keep memory bounded, only the
 **last 1000 lines** are kept for a chatty agent. On a BLOCKED result, the
-captured output lines are used as the "what the agent needs" section of
-`BLOCKER.md` (up to the last 10 lines).
+agent's questions (falling back to the captured output lines) are stored on
+the task as `blocker_reason` and become the "what the agent needs" section of
+`BLOCKER.md` (up to the last 10 lines), rendered on the next cycle.
 
 ## Git contract
 

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/docs/backlog.md

@@ -37,6 +37,9 @@ Each entry in `tasks` is a task object:
 | `files_to_modify` | list[string] | `[]` | Informational; hints for the agent. |
 | `agent_command` | string / list[string] | — | Override the configured `agent_command` for this task (e.g. route it to a different model). Validated like the global key; falls back to the config default when omitted. |
 | `agent_timeout_seconds` | number | — | Override the configured `agent_timeout_seconds` for this task (must be positive). Falls back to the config default when omitted. |
+| `blocker_reason` | list[string] | `[]` | Engine-managed: the agent's explanation (its questions, falling back to captured output) when the task becomes `BLOCKED`. Cleared on reopen; not editable via `PATCH`. |
+| `blocked_count` | integer | `0` | Engine-managed: how many times the task has transitioned into `BLOCKED`. Kept as history when the task is reopened, so you can see a task that keeps blocking needs splitting or rewriting rather than a blind retry. Not editable via `PATCH`. |
+| `failure_reason` | list[string] | `[]` | Engine-managed: the agent's error when the task becomes `FAILED` (e.g. a timeout message or a non-zero exit code). Shown in the web console's task modal so you can see why a task failed without opening the logs. Cleared when the task leaves the `FAILED` state; not editable via `PATCH`. |
 
 Only `id`, `title`, `description`, and `status` (optionally) are required;
 every other field is optional.
@@ -74,14 +77,33 @@ cheap/fast model and hard ones to a frontier model:
 | `OPEN` | To be picked by Forgeo. |
 | `BLOCKED` | Waiting on a human decision; Forgeo pauses while any task is blocked. |
 | `COMPLETED` | The agent finished and the work was committed (and pushed). |
-| `FAILED` | The agent errored; changes were discarded. |
+| `FAILED` | The agent errored; changes were discarded and the reason is recorded in `failure_reason`. |
 
 You add, remove, or reopen tasks by editing the file directly — or use the
 [web console](web-console-api.md): the **new-task form** (`POST
 /api/instances/<name>/tasks`) assigns the next free `WEB-###` id for you, and
 the task detail modal's **Edit** button updates an existing task's fields
-(`PATCH /api/instances/<name>/tasks/<id>`). To retry a `BLOCKED` task, set its
-status back to `OPEN` — Forgeo picks it up on the next scheduled run.
+(`PATCH /api/instances/<name>/tasks/<id>`), while its **Delete** button
+removes an `OPEN` or `BLOCKED` task (`DELETE /api/instances/<name>/tasks/<id>`).
+
+### Resolving a blocked task
+
+When the agent signals BLOCKED, Forgeo commits its partial work as a
+`[partial]` commit on `main` and marks the task `BLOCKED`, recording the
+agent's reason in `blocker_reason`. `BLOCKER.md` is a *derived view* of the
+backlog's `BLOCKED` tasks — it is re-rendered every cycle with the real
+per-task reasons and disappears automatically once the last `BLOCKED` task is
+resolved.
+
+To retry a `BLOCKED` task, **reopen** it: in the web console, open the task
+card and press **Reopen** (edit the task first if you want to correct
+something — editing is optional). Reopen is also available as `POST
+/api/instances/<name>/tasks/<id>/reopen`; either way the status goes back to
+`OPEN`, `blocker_reason` is cleared, and `blocked_count` is kept. Forgeo
+picks the task up on the next scheduled run, building on the preserved
+partial work. Reopening by hand is the same as setting the status back to
+`OPEN` in this file — but that does *not* clear `blocker_reason`, so prefer
+the web console's Reopen when the task was blocked by the agent.
 
 ## Oldest-first ordering
 

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/docs/cli-reference.md

@@ -74,7 +74,7 @@ Outcomes a cycle can produce:
 | --- | --- |
 | `task` | A task ran and finished. |
 | `refactor` | A refactoring pass ran (backlog was empty). |
-| `blocked` | A `BLOCKED` task exists; `BLOCKER.md` was rewritten; paused. |
+| `blocked` | A `BLOCKED` task exists; `BLOCKER.md` re-rendered from the backlog; paused. |
 | `paused` | A blocker file exists; nothing ran. |
 | `dirty` | The working tree was dirty; the task was not started. |
 | `skipped` | A previous run was still in progress (daemon only). |

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/docs/getting-started.md

@@ -43,8 +43,11 @@ The wizard asks for three things:
 
 1. **Forgeo folder** — where the backlog, `BLOCKER.md` and the log live
    (default `.forgeo`). It is gitignored by default.
-2. **Coding agent command** — any shell command that reads `$FORGEO_TASK` and
-   works in the repository (default `aider --message "$FORGEO_TASK"`).
+2. **Coding agent command** — the bare command that launches your coding
+   agent (default `opencode run --auto`). Forgeo appends the standard task
+   prompt (which ends in `$FORGEO_TASK`) automatically, so you never type
+   it. Enter a command that already references `$FORGEO_TASK` and it is
+   kept verbatim.
 3. **Refactor prompt** — the instruction used when the backlog is empty; the
    default is offered, or you can paste a custom one.
 

{forgeo_cli-0.3.0 → forgeo_cli-0.4.0}/docs/index.md

@@ -8,8 +8,10 @@ A **scheduled, agent-driven software forgeo** for one repository. Every
    directly on the single configured branch — no branches, no PRs;
 2. if the backlog is empty, runs the agent in **refactoring mode** and commits
    whatever it improves;
-3. if the agent signals it needs a human decision, writes a `BLOCKER.md` with
-   what you must do, and pauses until you resolve it.
+3. if the agent signals it needs a human decision, the task is marked
+   `BLOCKED` with the agent's reason preserved, `BLOCKER.md` is rendered from
+   the backlog's blocked tasks, and Forgeo pauses until you resolve it (reopen
+   it from the web console).
 
 ## What Forgeo is
 
@@ -37,7 +39,7 @@ forgeo.yaml ──► forgeo start (daemon)
                      ▼
                  Forgeo.run_cycle()
                      │
-                     ├── BLOCKED task exists ──► write BLOCKER.md, pause
+                     ├── BLOCKED task exists ──► render BLOCKER.md from backlog, pause
                      │
                      ├── oldest OPEN task ──► run agent ──► commit & push ──► COMPLETED
                      │
@@ -45,7 +47,8 @@ forgeo.yaml ──► forgeo start (daemon)
                                                 │
             exit 0                              │            exit blocked_exit_code
         commit & push ──────── ShellAgent ──────┴─────► partial work committed,
-            task COMPLETED   (FORGEO_TASK env)          BLOCKER.md written,
+            task COMPLETED   (FORGEO_TASK env)          reason persisted on task,
+                                                         BLOCKER.md rendered next cycle
                                                          task BLOCKED
 ```
 
@@ -55,6 +58,7 @@ forgeo.yaml ──► forgeo start (daemon)
 | --- | --- | --- |
 | `forgeo.cli` | `src/forgeo/cli.py` | `init`, `start`, `once`, `status`, `stop`, `restart` commands. |
 | `forgeo.daemon` | `src/forgeo/daemon.py` | The scheduled worker: wakes every `interval_minutes`, holds the run locks, records `last_outcome`. |
+| `forgeo.daemon_control` | `src/forgeo/daemon_control.py` | Daemon lifecycle shared by the CLI and web console: SIGTERM + wait, detached start/restart. |
 | `forgeo.forgeo` | `src/forgeo/forgeo.py` | One cycle of work: task run, refactor pass, blocker handling, git side effects. |
 | `forgeo.backlog` | `src/forgeo/backlog.py` | JSON backlog read/write; picks the oldest `OPEN` task. |
 | `forgeo.agent` | `src/forgeo/agent.py` | `ShellAgent`: runs your command, maps exit codes to outcomes, delivers `FORGEO_TASK`. |
@@ -71,9 +75,11 @@ forgeo.yaml ──► forgeo start (daemon)
    `once` is refused while it is held.
 2. `Forgeo.run_cycle()` ensures the configured branch exists and is checked
    out.
-3. If any task is `BLOCKED`, Forgeo rewrites `BLOCKER.md` and pauses
-   (`blocked` outcome) — it will not start new work until the human resolves
-   the block.
+3. If any task is `BLOCKED`, Forgeo re-renders `BLOCKER.md` from the backlog
+   (real per-task reasons, never generic text) and pauses (`blocked` outcome)
+   — it will not start new work until the block is resolved. Once the last
+   `BLOCKED` task is reopened, the file disappears automatically on the next
+   cycle.
 4. Otherwise it takes the oldest `OPEN` task. If the working tree is dirty the
    cycle aborts (`dirty`) rather than running over manual changes.
 5. The agent runs with the repository as its working directory and the task in