forgeo-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-24
+
+### Added
+
+- `forgeo init` now asks for **backlog provider** (`file`/`github`/`gitlab`/`jira`/`http`). For `github` it auto-detects `owner/repo` from `git remote origin`, prompts for `token_env` (`GITHUB_TOKEN`) and can persist a pasted classic PAT (`ghp_...`, scope `repo`) to `~/.config/forgeo/github_token_env.sh` (600, wired to `~/.bashrc`). Same for `gitlab` (`GITLAB_TOKEN`, base URL) and `jira`/`http`. The wizard writes `backlog: https://api.github.com`, `backlog_provider: github`, `github: {repo, auth: {token_env}}` and `state_dir: .forgeo` automatically.
+- Web console now treats `jira`/`github`/`gitlab` as a **read-mostly mirror** instead of a replacement: the home page cards show `Open in Jira/GitHub/GitLab ↗` (via `external_board_url`/`external_board_label`), the instance page shows a top banner linking to the native board, and each task card/modal links to the native issue (`external_url`). Document backlogs (`file`/`http`) keep the existing primary-editor behaviour. Creating/editing still works through the dashboard, but triage is expected in the native tracker where Forgeo-specific state (BLOCKED/FAILED reasons, `agent_response`, retry budget) is now surfaced on the mirror.
+- Central API now exposes `backlog_provider`, `backlog`, `backlog_is_issue_provider`, `external_board_url`/`external_board_label` on `GET /api/instances` and `GET /api/instances/<name>/status`, and `external_url` per task on `GET /api/instances/<name>/tasks` (+ single-task) for issue providers. Covers `https://api.github.com` → `https://github.com` and `https://…/api/v3` → web base mapping for GitHub Enterprise, and `https://jira…/issues/?jql=` / `https://gitlab…/{repo}/-/issues` board links.
+
+### Fixed
+
+- GitHub provider now encodes `owner/repo` as two path segments (`quote` per segment, keeping `/`) instead of `quote(repo, safe='')` which produced `owner%2Frepo` and 404 on every `GET /repos/{owner%2Frepo}/issues`.
+
+### Changed
+
+- `README`, `docs/backlog.md`, `docs/getting-started.md` and `docs/web-console-api.md` document the mirror vs editor split and the new `external_*` API fields.
+- `src/forgeo/central.py` deduplicates provider metadata via `_backlog_meta()` and centralises GitHub web-base handling; `instance-card` is now a `div[role=link]` to allow nested external links without invalid HTML.
+- `README`, `docs/getting-started.md` and `docs/cli-reference.md` document the new backlog-provider step in `forgeo init` and the `GITHUB_TOKEN` PAT setup (`https://github.com/settings/tokens/new`, scope `repo`).
+
 ## [0.9.0] - 2026-08-23
 
 ### Added
@@ -389,7 +407,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.9.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/lucaGazzola/forgeo/compare/v0.7.3...v0.8.0
 [0.7.3]: https://github.com/lucaGazzola/forgeo/compare/v0.7.2...v0.7.3

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.9.0
+Version: 0.10.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
@@ -110,6 +110,10 @@ forgeo init
 
 Guided wizard, run from your project root. Writes `forgeo.yaml` (the
 config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+The wizard asks for the backlog provider (`file` for a local JSON file, or
+`github`/`gitlab`/`jira`/`http` for an external tracker — for `github` it
+auto-detects `owner/repo` from `git remote` and can persist a pasted
+`GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`).
 
 The base flow is then three steps: fill the backlog, check the
 configuration, start the daemon.
@@ -121,8 +125,10 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` / `github` / `gitlab` and set `backlog` to the provider base URL
-# (see the backlog documentation for Jira/GitHub/GitLab).
+# Or: pick github/gitlab/jira in forgeo init (or configure forgeo.yaml
+# manually): set backlog_provider: github and backlog: https://api.github.com
+# with github.repo + token_env, then export GITHUB_TOKEN and run
+# forgeo validate. See backlog docs for Jira/GitHub/GitLab.
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -226,6 +232,12 @@ individually with workflow state and engine metadata stored on the issue. A *fil
 restored automatically if it is ever found corrupt — a bad write never loses
 your tasks.
 
+The central dashboard (`forgeo web`) mirrors every instance: for `file`/`http` it is the primary editor; for
+`jira`/`github`/`gitlab` it is a read-mostly mirror of the native tracker — each task card and its detail modal link
+to the native issue (`Open in Jira/GitHub/GitLab ↗`), a top banner links to the native board, and the board surfaces
+Forgeo-specific state the native UI does not (BLOCKED/FAILED reasons, `agent_response`, retry budget) — triage stays in
+the tracker (see [Web console & HTTP API](docs/web-console-api.md)).
+
 ## Develop
 
 ```bash

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/README.md

@@ -56,6 +56,10 @@ forgeo init
 
 Guided wizard, run from your project root. Writes `forgeo.yaml` (the
 config) and a `.forgeo/` folder for the backlog, logs and blocker files.
+The wizard asks for the backlog provider (`file` for a local JSON file, or
+`github`/`gitlab`/`jira`/`http` for an external tracker — for `github` it
+auto-detects `owner/repo` from `git remote` and can persist a pasted
+`GITHUB_TOKEN` to `~/.config/forgeo/github_token_env.sh`).
 
 The base flow is then three steps: fill the backlog, check the
 configuration, start the daemon.
@@ -67,8 +71,10 @@ configuration, start the daemon.
 # Backlog format), created on first use:
 #   .forgeo/backlog.json
 
-# Or: configure `backlog_provider: jira` / `github` / `gitlab` and set `backlog` to the provider base URL
-# (see the backlog documentation for Jira/GitHub/GitLab).
+# Or: pick github/gitlab/jira in forgeo init (or configure forgeo.yaml
+# manually): set backlog_provider: github and backlog: https://api.github.com
+# with github.repo + token_env, then export GITHUB_TOKEN and run
+# forgeo validate. See backlog docs for Jira/GitHub/GitLab.
 
 # Or: add tasks from the web console once your forgeo is registered
 # (first `forgeo start` registers it automatically):
@@ -172,6 +178,12 @@ individually with workflow state and engine metadata stored on the issue. A *fil
 restored automatically if it is ever found corrupt — a bad write never loses
 your tasks.
 
+The central dashboard (`forgeo web`) mirrors every instance: for `file`/`http` it is the primary editor; for
+`jira`/`github`/`gitlab` it is a read-mostly mirror of the native tracker — each task card and its detail modal link
+to the native issue (`Open in Jira/GitHub/GitLab ↗`), a top banner links to the native board, and the board surfaces
+Forgeo-specific state the native UI does not (BLOCKED/FAILED reasons, `agent_response`, retry budget) — triage stays in
+the tracker (see [Web console & HTTP API](docs/web-console-api.md)).
+
 ## Develop
 
 ```bash

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/docs/backlog.md

@@ -144,6 +144,11 @@ You add, remove, or reopen tasks by editing the file directly — or use the
 the task detail modal's **Edit** button updates an existing task's fields
 (`PATCH /api/instances/<name>/tasks/<id>`), while its **Delete** button
 removes an `OPEN` or `BLOCKED` task (`DELETE /api/instances/<name>/tasks/<id>`).
+For `file`/`http` backlogs this is the primary editor; for `jira`/`github`/`gitlab` the web console is a
+read-mostly **mirror** of the native tracker — a top banner links to the external board, each task card/modal
+links to the native issue (`Open in Jira/GitHub/GitLab ↗`), and the board surfaces Forgeo-specific state
+(`blocker_reason`, `failure_reason`, `agent_response`, retry budget) that the tracker does not — triage stays in
+Jira/GitHub/GitLab, Forgeo reflects it (see [Web console & HTTP API](web-console-api.md)).
 
 ### Resolving a blocked task
 

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/docs/cli-reference.md

@@ -23,6 +23,8 @@ Guided first-time setup: interactively write a `forgeo.yaml`.
 | <span style="white-space: nowrap">`--config <file>`</span> | Where to write the config (default `forgeo.yaml`). |
 | <span style="white-space: nowrap">`--force`</span> | Overwrite an existing config file. |
 
+The wizard asks for: Forgeo folder, backlog provider (`file`/`github`/`gitlab`/`jira`/`http` — for `github` it auto-detects `owner/repo` from `git remote` and can persist `GITHUB_TOKEN`), coding agent command, and refactor prompt.
+
 Exit codes:
 
 - `0` — config written.

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/docs/getting-started.md

@@ -56,20 +56,29 @@ Run the guided wizard from your project root:
 forgeo init
 ```
 
-The wizard asks for three things:
+The wizard asks for:
 
 1. **Forgeo folder** — where the backlog, `BLOCKER.md` and the log live
    (default `.forgeo`). It is gitignored by default.
-2. **Coding agent command** — the bare command that launches your coding
+2. **Backlog provider** — where tasks live: `file` (local `.forgeo/backlog.json`),
+   `github` / `gitlab` / `jira` / `http`. For `github` it auto-detects
+   `owner/repo` from `git remote origin`, asks for `token_env` (default
+   `GITHUB_TOKEN`) and can persist a pasted classic PAT (`ghp_...`, scope `repo`)
+   to `~/.config/forgeo/github_token_env.sh` (600, wired to `~/.bashrc`). Same
+   for `gitlab` (`GITLAB_TOKEN`, base URL) and `jira`/`http`.
+3. **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
+4. **Refactor prompt** — the instruction used when the backlog is empty; the
    default is offered, or you can paste a custom one.
 
 `forgeo init` writes `forgeo.yaml`, creates Forgeo folder, and appends
-`<folder>/` to `.gitignore` (unless you opt out).
+`<folder>/` to `.gitignore` (unless you opt out). For `github`/`gitlab`/`jira`
+set `backlog_provider` + `backlog` URL + provider block is written automatically
+and `state_dir` is set to the Forgeo folder so runtime files stay beside the
+config.
 
 ```bash
 forgeo init --force    # overwrite an existing forgeo.yaml
@@ -77,18 +86,25 @@ forgeo init --force    # overwrite an existing forgeo.yaml
 
 ## 3. Create your first backlog
 
-The backlog is a plain JSON file (see [Backlog format](backlog.md)). Create
-the file configured as `backlog:` in your `forgeo.yaml` — by default
-`.forgeo/backlog.json`. Once Forgeo is running you can also add tasks
-from the [web console](web-console-api.md) — no file editing needed. (If your
-tasks already live in another application, `backlog:` also accepts an
-[HTTP endpoint](backlog.md#a-backlog-over-http) or a [Jira source](backlog.md#a-jira-backlog)
-instead of a file.)
-
-For Jira, set `backlog_provider: jira`, point `backlog:` at the Jira base URL,
-configure `jira.jql` and the workflow mappings, export the credentials named in
-`jira.auth`, and run `forgeo validate` before starting the daemon. See [Jira
-backlogs](backlog.md#a-jira-backlog) for the complete configuration.
+If you chose `file` in the wizard, the backlog is a plain JSON file (see
+[Backlog format](backlog.md)) — by default `.forgeo/backlog.json`. Once Forgeo
+is running you can also add tasks from the [web console](web-console-api.md) — no
+file editing needed.
+
+If you chose `github`/`gitlab`/`jira`/`http` in the wizard, your `forgeo.yaml`
+already points at the provider (`backlog: https://api.github.com` etc.).
+For `github` create a classic PAT at `https://github.com/settings/tokens/new`
+(scope `repo`), `export GITHUB_TOKEN=ghp_...` (or let the wizard persist it),
+then `forgeo validate` before `forgeo start`. Same for `gitlab` (`GITLAB_TOKEN`)
+and `jira`. See [Backlog format](backlog.md) for provider details.
+
+For `jira`/`github`/`gitlab`, set `backlog_provider:` to the provider, point `backlog:` at its base URL
+(`https://jira.example.com`, `https://api.github.com` / `https://github.example.com/api/v3`,
+`https://gitlab.example.com`), configure the provider block (`jira.jql` / `github.repo` / `gitlab.repo` and auth),
+export the credentials named in `*_auth.token_env`, and run `forgeo validate` before starting the daemon.
+The dashboard for these providers is a read-mostly mirror: a banner links to the native board, each card links to
+the native issue, and Forgeo-specific state (BLOCKED/FAILED reasons, `agent_response`) is surfaced on the board — triage
+stays in Jira/GitHub/GitLab. See [Backlog: Jira/GitHub/GitLab](backlog.md) for the complete configuration.
 
 ```json
 {

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/docs/web-console-api.md

@@ -66,11 +66,20 @@ open-by-default behavior.
 
 - `GET /` — home page listing every registered instance: name, repository,
   daemon state (lock held), last outcome, next run, and per-status backlog
-  counts, each linking to its instance page.
+  counts, each linking to its instance page. For issue-backed instances
+  (`jira`/`github`/`gitlab`) the card also shows an **Open in Jira/GitHub/GitLab ↗**
+  link to the native board.
 - `GET /instances/<name>/` — one instance's page: a kanban backlog, a
   **Create** tab with a form to add tasks (including an optional *Run at*
   date/time input for a one-shot schedule), plus tabs for **logs**, **history**,
-  **blocker** and **config**. The header carries a **DAEMON** section with the
+  **blocker** and **config**. For document backlogs (`file`/`http`) this board
+  is the primary editor; for issue providers (`jira`/`github`/`gitlab`) it is a
+  read-mostly **mirror** of the native tracker: a banner at the top links to
+  the external board (`Jira`/`GitHub`/`GitLab`), each task card and its detail
+  modal carry an **Open in external ↗** link to the native issue, and the board
+  surfaces Forgeo-specific state that the native UI does not (BLOCKED/FAILED
+  reasons, `agent_response`, retry budget). Creating/editing still works via
+  the dashboard, but triage is expected in the native tool. The header carries a **DAEMON** section with the
   daemon status tag (`running`/`stopped`) and **Start**/**Stop**/**Restart**
   buttons that call `POST /api/instances/<name>/start|stop|restart`; the
   buttons reflect the current state (Start is disabled while running, Stop
@@ -152,15 +161,19 @@ outcome, next run, and backlog counts.
 curl http://127.0.0.1:8790/api/instances
 ```
 
-Each row also carries `backlog_error`: `null` normally, and the reason when
-that instance's remote backlog could not be read. Its counts are zero in that
-case — the row reports a backlog it could not reach, not an empty one. One
-unreachable provider never fails the whole listing.
+Each row also carries `backlog_provider` (`file`/`http`/`jira`/`github`/`gitlab`),
+`backlog` (path or base URL), `backlog_is_issue_provider`, and for issue
+providers `external_board_url`/`external_board_label` (the native board link
+shown on the home cards). It also carries `backlog_error`: `null` normally,
+and the reason when that instance's remote backlog could not be read. Its
+counts are zero in that case — the row reports a backlog it could not reach,
+not an empty one. One unreachable provider never fails the whole listing.
 
 ### `GET /api/instances/<name>/tasks`
 
 List every task in that instance's backlog, in creation order. Each task
-carries extra `unsatisfied_dependencies` and retry fields (see below).
+carries extra `unsatisfied_dependencies`, retry fields (see below), and for
+issue providers `external_url` (link to the native Jira/GitHub/GitLab issue).
 
 ```bash
 curl http://127.0.0.1:8790/api/instances/my-repo/tasks
@@ -400,7 +413,10 @@ Errors:
 ### `GET /api/instances/<name>/status`
 
 Daemon status: name, repo, interval, `daemon_running` (whether the instance's
-lock is held), the recorded PID, `last_outcome`, and the `next_run_at`.
+lock is held), the recorded PID, `last_outcome`, and the `next_run_at`. Also
+carries `backlog_provider`, `backlog`, `backlog_is_issue_provider`,
+`external_board_url`/`external_board_label` so the instance page can render the
+issue-provider banner and per-task external links.
 
 ```bash
 curl http://127.0.0.1:8790/api/instances/my-repo/status
@@ -414,7 +430,12 @@ curl http://127.0.0.1:8790/api/instances/my-repo/status
   "daemon_running": true,
   "pid": 4242,
   "last_outcome": "task",
-  "next_run_at": "2026-08-01T12:00:00+00:00"
+  "next_run_at": "2026-08-01T12:00:00+00:00",
+  "backlog_provider": "github",
+  "backlog": "https://api.github.com",
+  "backlog_is_issue_provider": true,
+  "external_board_url": "https://github.com/owner/repo/issues",
+  "external_board_label": "GitHub"
 }
 ```
 

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/install.sh

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

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.9.0"
+version = "0.10.0"
 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.9.0 → forgeo_cli-0.10.0}/src/forgeo/__init__.py

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

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/src/forgeo/agent.py

@@ -206,7 +206,26 @@ class ShellAgent(BaseAgent):
         except TimeoutError:
             timed_out = True
             _kill_process_group(proc)
-            await proc.wait()
+            # ``proc.wait()`` waits for both process exit *and* pipe closure
+            # (see ``BaseSubprocessTransport._try_finish``).  A grandchild that
+            # called ``setsid()`` and holds the write end of the pipe keeps it
+            # open forever, so the wait would hang past the drain deadline.
+            # Bound it by ``drain_timeout_seconds`` and force-close the
+            # transport if it still hangs.
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=self.drain_timeout_seconds)
+            except TimeoutError:
+                try:
+                    proc._transport.close()  # type: ignore[attr-defined]
+                except Exception:  # noqa: BLE001, S110 - close must not fail the task
+                    pass
+                try:
+                    await asyncio.wait_for(proc.wait(), timeout=1.0)
+                except TimeoutError:
+                    logs.append(
+                        f"[{self.name}] Process did not exit within "
+                        f"{self.drain_timeout_seconds:g}s after kill; proceeding."
+                    )
         # 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
@@ -215,6 +234,11 @@ class ShellAgent(BaseAgent):
         try:
             await asyncio.wait_for(readers, timeout=self.drain_timeout_seconds)
         except TimeoutError:
+            readers.cancel()
+            try:
+                await readers
+            except asyncio.CancelledError:
+                pass
             logs.append(
                 f"[{self.name}] Output streams stayed open beyond "
                 f"{self.drain_timeout_seconds:g}s; proceeding without them."

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/src/forgeo/backlog_github.py

@@ -111,6 +111,11 @@ class GithubClient:
             ) from exc
         return data
 
+    def _repo_path(self) -> str:
+        # GitHub API expects owner/repo as two separate path segments;
+        # encode each segment but keep the slash between them.
+        return "/".join(quote(part, safe="") for part in self.config.repo.split("/"))
+
     def search_issues(
         self,
         *,
@@ -118,8 +123,7 @@ class GithubClient:
         per_page: int = 30,
         state: str = "all",
     ) -> list[dict[str, Any]]:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues"
+        path = f"/repos/{self._repo_path()}/issues"
         query: dict[str, Any] = {"state": state, "per_page": per_page, "page": page}
         data = self._request("GET", path, query=query)
         if isinstance(data, list):
@@ -127,28 +131,23 @@ class GithubClient:
         return []
 
     def get_issue(self, issue_number: int) -> dict[str, Any]:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues/{issue_number}"
+        path = f"/repos/{self._repo_path()}/issues/{issue_number}"
         return self._request("GET", path)  # type: ignore[no-any-return]
 
     def create_issue(self, fields: dict[str, Any]) -> dict[str, Any]:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues"
+        path = f"/repos/{self._repo_path()}/issues"
         return self._request("POST", path, payload=fields)  # type: ignore[no-any-return]
 
     def update_issue(self, issue_number: int, fields: dict[str, Any]) -> dict[str, Any]:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues/{issue_number}"
+        path = f"/repos/{self._repo_path()}/issues/{issue_number}"
         return self._request("PATCH", path, payload=fields)  # type: ignore[no-any-return]
 
     def add_comment(self, issue_number: int, body: str) -> None:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues/{issue_number}/comments"
+        path = f"/repos/{self._repo_path()}/issues/{issue_number}/comments"
         self._request("POST", path, payload={"body": body})
 
     def delete_issue(self, issue_number: int) -> None:
-        repo = self.config.repo
-        path = f"/repos/{quote(repo, safe='')}/issues/{issue_number}"
+        path = f"/repos/{self._repo_path()}/issues/{issue_number}"
         self._request("PATCH", path, payload={"state": "closed"})
 
 

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/src/forgeo/central.py

@@ -68,7 +68,7 @@ from datetime import datetime, timedelta
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any
-from urllib.parse import parse_qs, unquote, urlparse
+from urllib.parse import parse_qs, quote, unquote, urlparse
 
 from pydantic import ValidationError
 from rich.console import Console
@@ -88,7 +88,7 @@ from forgeo.instances import (
     list_instances,
     registry_path,
 )
-from forgeo.models import ForgeoConfig, Task, TaskStatus
+from forgeo.models import ISSUE_PROVIDERS, ForgeoConfig, Task, TaskStatus
 from forgeo.paths import daemon_state_path, lock_path, runs_path
 from forgeo.runs import RunRecorder
 from forgeo.web_common import (
@@ -119,6 +119,71 @@ DEFAULT_FORGEO_CONFIG_DIR = Path.home() / ".config" / "forgeo"
 _HOME_PAGE = "/central/index.html"
 _INSTANCE_PAGE = "/central/instance.html"
 
+_ISSUE_PROVIDER_LABELS: dict[str, str] = {
+    "jira": "Jira",
+    "github": "GitHub",
+    "gitlab": "GitLab",
+}
+
+
+def _github_web_base(api_base: str) -> str:
+    """Derive the web base from a GitHub API base URL.
+
+    ``https://api.github.com`` → ``https://github.com``,
+    ``https://github.example.com/api/v3`` → ``https://github.example.com``,
+    otherwise the base itself when already a web URL.
+    """
+    base = api_base.rstrip("/")
+    if base.endswith("/api/v3"):
+        return base[:-7].rstrip("/")
+    if "api.github.com" in base:
+        return base.replace("api.github.com", "github.com")
+    return base
+
+
+def _external_board_url(config: ForgeoConfig | None) -> str | None:
+    """The native backlog URL for an issue provider, or ``None`` for documents."""
+    if config is None or not isinstance(config.backlog, str):
+        return None
+    provider = config.effective_backlog_provider
+    base = config.backlog.rstrip("/")
+    if provider == "jira":
+        if config.jira is None:
+            return base
+        return f"{base}/issues/?jql={quote(config.jira.jql, safe='')}"
+    if provider == "github" and config.github is not None:
+        web_base = _github_web_base(base)
+        repo = config.github.repo.strip("/")
+        return f"{web_base}/{repo}/issues"
+    if provider == "gitlab" and config.gitlab is not None:
+        repo = config.gitlab.repo.strip("/")
+        if repo.isdigit():
+            return f"{base}/-/issues"
+        return f"{base}/{repo}/-/issues"
+    return None
+
+
+def _external_issue_url(config: ForgeoConfig | None, task_id: str) -> str | None:
+    """The native issue URL for one task, or ``None`` for document providers."""
+    if config is None or not isinstance(config.backlog, str) or not task_id:
+        return None
+    provider = config.effective_backlog_provider
+    base = config.backlog.rstrip("/")
+    if provider == "jira":
+        return f"{base}/browse/{quote(task_id, safe='')}"
+    if provider == "github" and config.github is not None:
+        web_base = _github_web_base(base)
+        repo = config.github.repo.strip("/")
+        # GitHub ids are numeric; a stale WEB-### prefix is stripped for the URL.
+        issue_num = task_id.split("-")[-1] if "-" in task_id and task_id.rsplit("-", 1)[-1].isdigit() else task_id
+        return f"{web_base}/{repo}/issues/{issue_num}"
+    if provider == "gitlab" and config.gitlab is not None:
+        repo = config.gitlab.repo.strip("/")
+        if repo.isdigit():
+            return f"{base}/-/issues/{task_id}"
+        return f"{base}/{repo}/-/issues/{task_id}"
+    return None
+
 _WEB_TASK_ID_RE = re.compile(r"^WEB-(\d+)$")
 
 
@@ -412,7 +477,7 @@ def _task_payload(
     tasks: list[Task],
     config: ForgeoConfig | None = None,
 ) -> dict[str, Any]:
-    """Serialize a task for the API, annotating its unsatisfied dependencies.
+    """Serialize a task for the API, annotating dependencies and external links.
 
     The extra ``unsatisfied_dependencies`` field lists every dependency id
     that is not ``COMPLETED`` yet (with its current status, or ``missing``
@@ -422,6 +487,8 @@ def _task_payload(
     (``retry_budget``, the per-task ``retries_left`` override falling back to
     the config's ``failed_retry_max``) and ``retries_remaining`` so the
     console can show whether a FAILED task will be retried automatically.
+    For issue providers the payload also carries ``external_url`` pointing at
+    the native issue page.
     """
     payload = task.model_dump(mode="json")
     payload["unsatisfied_dependencies"] = unsatisfied_dependencies(tasks, task)
@@ -429,6 +496,9 @@ def _task_payload(
         budget = task.retries_left if task.retries_left is not None else config.failed_retry_max
         payload["retry_budget"] = budget
         payload["retries_remaining"] = max(0, budget - task.retry_count)
+        external = _external_issue_url(config, task.id)
+        if external is not None:
+            payload["external_url"] = external
     return payload
 
 
@@ -481,6 +551,29 @@ def _next_run(info: InstanceInfo, config: ForgeoConfig | None) -> str | None:
     return iso(estimate)
 
 
+def _backlog_meta(config: ForgeoConfig | None) -> dict[str, Any]:
+    """Provider and external URL for a config, or document defaults."""
+    if config is None:
+        return {
+            "backlog_provider": None,
+            "backlog": None,
+            "backlog_is_issue_provider": False,
+            "external_board_url": None,
+            "external_board_label": None,
+        }
+    provider = config.effective_backlog_provider
+    is_issue = provider in ISSUE_PROVIDERS
+    label = _ISSUE_PROVIDER_LABELS.get(provider) if is_issue else None
+    backlog_value = str(config.backlog)
+    return {
+        "backlog_provider": provider,
+        "backlog": backlog_value,
+        "backlog_is_issue_provider": is_issue,
+        "external_board_url": _external_board_url(config),
+        "external_board_label": label,
+    }
+
+
 def _status_payload(info: InstanceInfo) -> dict[str, Any]:
     """The per-instance status payload."""
     config = info.config
@@ -493,6 +586,7 @@ def _status_payload(info: InstanceInfo) -> dict[str, Any]:
             "pid": None,
             "last_outcome": None,
             "next_run_at": None,
+            **_backlog_meta(None),
         }
     state = _daemon_state(config)
     pid: int | None = read_lock_pid(lock_path(config))
@@ -508,6 +602,7 @@ def _status_payload(info: InstanceInfo) -> dict[str, Any]:
         "pid": pid,
         "last_outcome": _last_outcome(config),
         "next_run_at": _next_run(info, config),
+        **_backlog_meta(config),
     }
 
 
@@ -524,6 +619,7 @@ def _summary(info: InstanceInfo) -> dict[str, Any]:
             "next_run_at": None,
             "backlog_counts": {status.value: 0 for status in TaskStatus},
             "backlog_error": None,
+            **_backlog_meta(None),
         }
     tasks, backlog_error = _read_tasks_or_error(config)
     return {
@@ -535,6 +631,7 @@ def _summary(info: InstanceInfo) -> dict[str, Any]:
         "next_run_at": _next_run(info, config),
         "backlog_counts": backlog_status_counts(tasks),
         "backlog_error": backlog_error,
+        **_backlog_meta(config),
     }
 
 
@@ -1294,7 +1391,7 @@ class CentralWebServer:
             return False
         self._httpd = httpd
         thread = threading.Thread(
-            target=httpd.serve_forever,
+            target=lambda: httpd.serve_forever(poll_interval=0.05),
             name="forgeo-central-web",
             daemon=True,
         )

{forgeo_cli-0.9.0 → forgeo_cli-0.10.0}/src/forgeo/daemon_control.py

@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
 
 STOP_TIMEOUT_SECONDS = 600.0
 START_TIMEOUT_SECONDS = 15.0
-_POLL_SECONDS = 0.5
+_POLL_SECONDS = 0.05
 
 
 class DaemonError(Exception):