@julioborges/gantry 0.1.0

package/.agents/skills/gantry/scripts/dashboard.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Serve a read-only, loopback-only, multi-Run kanban dashboard.
+
+The dashboard never writes to an Issue, a policy, a Run log, a branch or a worktree: every
+HTTP endpoint is a GET that renders data already produced by ``runlog.py``. Staleness is
+always derived from the ``staleAfterSeconds`` snapshot recorded on each Run's ``run.started``
+event, never from the current policy or a mutable dashboard action.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from runlog import read_valid_events
+from runlog import state_root as default_state_root
+
+COLUMNS = ["Ready", "Plan", "Implement", "Review", "Critic", "Integrate", "Done", "Blocked"]
+STATIC_DIR = Path(__file__).resolve().parent.parent / "dashboard" / "static"
+STATIC_FILES = {
+    "/": "index.html",
+    "/index.html": "index.html",
+    "/app.js": "app.js",
+    "/style.css": "style.css",
+}
+MIME_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+}
+IGNORED_FOR_ACTIVITY = {"policy.changed"}
+
+
+class DashboardError(ValueError):
+    """The dashboard cannot serve safely with the requested configuration."""
+
+
+def require_loopback_host(host: str) -> str:
+    """Refuse to bind anywhere but the local loopback address."""
+    if host != "127.0.0.1":
+        raise DashboardError(f"dashboard must bind 127.0.0.1 only, refusing host {host!r}")
+    return host
+
+
+def _parse_ts(value: str) -> float:
+    return datetime.datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+
+
+def build_run(unit_id: str, events: list[dict], now: float) -> dict:
+    """Reduce one Run's valid event stream into swimlane and Issue-column state."""
+    started = events[0]
+    data = started["data"]
+    stale_after = data["staleAfterSeconds"]
+
+    activity_events = [event for event in events if event["event"] not in IGNORED_FOR_ACTIVITY]
+    last_activity_ts = _parse_ts(activity_events[-1]["ts"]) if activity_events else _parse_ts(started["ts"])
+
+    issues: dict[str, dict] = {}
+    compaction_at = None
+    for event in events[1:]:
+        name = event["event"]
+        if name == "compaction":
+            compaction_at = event["ts"]
+            continue
+        issue = event.get("issue")
+        if issue is None:
+            continue
+        state = issues.setdefault(
+            issue,
+            {
+                "issue": issue,
+                "column": "Ready",
+                "branch": None,
+                "worktree": None,
+                "models": {},
+                "correctionBudget": None,
+                "phaseStartedAt": None,
+                "operatorWaiting": False,
+            },
+        )
+        edata = event.get("data") or {}
+        if name == "phase.started":
+            state["column"] = event["phase"]
+            state["phaseStartedAt"] = event["ts"]
+            if "branch" in edata:
+                state["branch"] = edata["branch"]
+            if "worktree" in edata:
+                state["worktree"] = edata["worktree"]
+            if "models" in edata:
+                state["models"] = dict(edata["models"])
+            if "correctionBudget" in edata:
+                state["correctionBudget"] = edata["correctionBudget"]
+            state["operatorWaiting"] = bool(edata.get("operatorWaiting", False))
+        elif name == "subagent.started":
+            role = edata.get("role")
+            if role:
+                state["models"][role] = edata.get("model")
+        elif name == "issue.done":
+            state["column"] = "Done"
+        elif name == "issue.blocked":
+            state["column"] = "Blocked"
+
+    for state in issues.values():
+        if state["phaseStartedAt"] is not None:
+            state["elapsedPhaseSeconds"] = max(0, int(now - _parse_ts(state["phaseStartedAt"])))
+        else:
+            state["elapsedPhaseSeconds"] = None
+
+    return {
+        "unitId": unit_id,
+        "run": started["run"],
+        "repositoryRoot": data["repositoryRoot"],
+        "tier": data["tier"],
+        "staleAfterSeconds": stale_after,
+        "lastActivityAt": activity_events[-1]["ts"] if activity_events else started["ts"],
+        "stale": (now - last_activity_ts) >= stale_after,
+        "compactionAt": compaction_at,
+        "issues": sorted(issues.values(), key=lambda item: item["issue"]),
+    }
+
+
+def collect_runs(root: Path, now: float | None = None) -> list[dict]:
+    """Read every Run log under every execution unit's state root."""
+    now = time.time() if now is None else now
+    runs: list[dict] = []
+    if not root.exists():
+        return runs
+    for unit_dir in sorted(path for path in root.iterdir() if path.is_dir()):
+        runs_dir = unit_dir / "runs"
+        if not runs_dir.exists():
+            continue
+        for log_path in sorted(runs_dir.glob("*.jsonl")):
+            events = read_valid_events(log_path)
+            if not events or events[0]["event"] != "run.started":
+                continue
+            runs.append(build_run(unit_dir.name, events, now))
+    return runs
+
+
+def make_handler(state_root: Path) -> type[BaseHTTPRequestHandler]:
+    class DashboardRequestHandler(BaseHTTPRequestHandler):
+        server_version = "GantryDashboard/1"
+
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A002 - stdlib signature
+            pass
+
+        def _send_json(self, status: int, payload: object) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _send_static(self, filename: str) -> None:
+            path = STATIC_DIR / filename
+            body = path.read_bytes()
+            self.send_response(200)
+            self.send_header("Content-Type", MIME_TYPES.get(path.suffix, "application/octet-stream"))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _send_not_found(self) -> None:
+            body = b"not found"
+            self.send_response(404)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:  # noqa: N802 - stdlib method name
+            path = self.path.split("?", 1)[0]
+            if path == "/api/state":
+                self._send_json(200, {"columns": COLUMNS, "runs": collect_runs(state_root)})
+                return
+            filename = STATIC_FILES.get(path)
+            if filename is not None:
+                self._send_static(filename)
+                return
+            self._send_not_found()
+
+    return DashboardRequestHandler
+
+
+def create_server(host: str, port: int, state_root: Path) -> ThreadingHTTPServer:
+    """Build a validated, loopback-only HTTP server for the dashboard."""
+    require_loopback_host(host)
+    handler = make_handler(state_root)
+    server = ThreadingHTTPServer((host, port), handler)
+    return server
+
+
+def serve(host: str, port: int, state_root: Path) -> None:
+    server = create_server(host, port, state_root)
+    print(json.dumps({"host": host, "port": server.server_port, "stateRoot": str(state_root)}))
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        thread.join()
+    except KeyboardInterrupt:
+        server.shutdown()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    serve_parser = subparsers.add_parser("serve", help="serve the read-only kanban dashboard")
+    serve_parser.add_argument("--host", default="127.0.0.1", help="must be 127.0.0.1")
+    serve_parser.add_argument("--port", type=int, default=4600, help="TCP port, 0 for an ephemeral port")
+    serve_parser.add_argument("--state-root", help="override ~/.gantry/state")
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        state_root = Path(args.state_root).expanduser().resolve() if args.state_root else default_state_root(None)
+        try:
+            serve(args.host, args.port, state_root)
+        except DashboardError as error:
+            print(f"dashboard error: {error}", file=sys.stderr)
+            return 1
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/gantry/scripts/frontier.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Compute ready Issue rounds from authoritative Markdown execution state."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from common import Issue, load_issues, load_policy_issues, normalise_ref, repo_root, roadmap_waves  # noqa: E402
+
+
+def select_scope(scopes: list[str], issues: dict[str, Issue], roadmap: str) -> tuple[set[str], list[str]]:
+    selected: set[str] = set()
+    errors: list[str] = []
+    waves = roadmap_waves(roadmap) if roadmap else {}
+    specs = {issue.spec for issue in issues.values()}
+    for raw in scopes:
+        scope = raw.strip()
+        if scope == "all":
+            selected |= {ref for ref, issue in issues.items() if not issue.done}
+        elif scope == "frontier":
+            selected |= {
+                ref for ref, issue in issues.items()
+                if not issue.done and (
+                    issue.parked
+                    or not issue.blocked_by
+                    or all(issues.get(blocker) and issues[blocker].done for blocker in issue.blocked_by)
+                )
+            }
+        elif scope.startswith("wave:"):
+            try:
+                wave = int(scope.split(":", 1)[1])
+            except ValueError:
+                errors.append(f"bad wave scope: {raw}")
+                continue
+            if wave not in waves:
+                errors.append(f"wave {wave} not found in ROADMAP.md")
+            else:
+                for ref in waves[wave]:
+                    if ref in issues and not issues[ref].done:
+                        selected.add(ref)
+                    elif ref not in issues:
+                        errors.append(f"ROADMAP.md wave {wave} lists {ref} but no issue file exists")
+        elif normalise_ref(scope):
+            ref = normalise_ref(scope)
+            if ref in issues:
+                selected.add(ref)
+            else:
+                errors.append(f"issue not found: {ref}")
+        elif scope in specs:
+            selected |= {ref for ref, issue in issues.items() if issue.spec == scope and not issue.done}
+        else:
+            errors.append(f"unknown scope: {raw} (not a spec slug, issue ref, wave:N, all or frontier)")
+    return selected, errors
+
+
+def find_cycles(nodes: set[str], issues: dict[str, Issue]) -> list[list[str]]:
+    index: dict[str, int] = {}
+    low: dict[str, int] = {}
+    stack: list[str] = []
+    on_stack: set[str] = set()
+    cycles: list[list[str]] = []
+    counter = 0
+
+    def visit(ref: str) -> None:
+        nonlocal counter
+        index[ref] = low[ref] = counter
+        counter += 1
+        stack.append(ref)
+        on_stack.add(ref)
+        for blocker in (blocker for blocker in issues[ref].blocked_by if blocker in nodes):
+            if blocker not in index:
+                visit(blocker)
+                low[ref] = min(low[ref], low[blocker])
+            elif blocker in on_stack:
+                low[ref] = min(low[ref], index[blocker])
+        if low[ref] == index[ref]:
+            component: list[str] = []
+            while True:
+                member = stack.pop()
+                on_stack.remove(member)
+                component.append(member)
+                if member == ref:
+                    break
+            if len(component) > 1 or ref in issues[ref].blocked_by:
+                cycles.append(component)
+
+    for ref in sorted(nodes):
+        if ref not in index:
+            visit(ref)
+    return cycles
+
+
+def validate_graph(issues: dict[str, Issue]) -> list[str]:
+    """Return errors that make the authoritative Issue graph invalid."""
+    errors = [
+        f"{ref} is blocked by {blocker}, which does not exist"
+        for ref in sorted(issues)
+        for blocker in issues[ref].blocked_by
+        if blocker not in issues
+    ]
+    for cycle in find_cycles(set(issues), issues):
+        errors.append("dependency cycle: " + " -> ".join(cycle + [cycle[0]]))
+    return errors
+
+
+def schedule(selected: set[str], issues: dict[str, Issue], limit: int | None) -> tuple[list[list[str]], dict[str, list[str]], list[str]]:
+    errors: list[str] = []
+    external = {
+        ref: [blocker for blocker in issues[ref].blocked_by if blocker in issues and blocker not in selected and not issues[blocker].done]
+        for ref in selected
+    }
+    external = {ref: blockers for ref, blockers in external.items() if blockers}
+    schedulable = selected - external.keys()
+    changed = True
+    while changed:
+        changed = False
+        for ref in list(schedulable):
+            blocked = [blocker for blocker in issues[ref].blocked_by if blocker in external]
+            if blocked:
+                external[ref] = [f"{blocker} (transitively blocked)" for blocker in blocked]
+                schedulable.remove(ref)
+                changed = True
+    done = {ref for ref, issue in issues.items() if issue.done}
+    rounds: list[list[str]] = []
+    placed: set[str] = set()
+    remaining = set(schedulable)
+    while remaining:
+        ready = sorted(
+            ref for ref in remaining
+            if all(blocker in done or blocker in placed for blocker in issues[ref].blocked_by if blocker in issues)
+        )
+        if not ready:
+            for cycle in find_cycles(remaining, issues):
+                errors.append("dependency cycle: " + " -> ".join(cycle + [cycle[0]]))
+            break
+        if limit:
+            ready = ready[:limit]
+        rounds.append(ready)
+        placed.update(ready)
+        remaining.difference_update(ready)
+    return rounds, external, errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--scope", action="append", default=[], help="scope selector (repeatable)")
+    parser.add_argument("--scratch", help="legacy Issue root override")
+    parser.add_argument("--roadmap", default="ROADMAP.md")
+    parser.add_argument("--limit", type=int, default=None, help="maximum Issues per round")
+    parser.add_argument("--include-parked", action="store_true", help="include blocked, needs-operator and draft Issues")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    root = repo_root()
+    issues = load_issues(root / args.scratch) if args.scratch else load_policy_issues(root)
+    if not issues:
+        location = root / args.scratch if args.scratch else "the effective artifacts.issues policy path"
+        print(f"no issues found under {location}", file=sys.stderr)
+        return 2
+    roadmap_path = root / args.roadmap
+    selected, errors = select_scope(args.scope or ["frontier"], issues, roadmap_path.read_text(encoding="utf-8") if roadmap_path.exists() else "")
+    errors.extend(validate_graph(issues))
+    parked = sorted(ref for ref in selected if issues[ref].parked)
+    if not args.include_parked:
+        selected.difference_update(parked)
+    rounds, external, schedule_errors = schedule(selected, issues, args.limit)
+    errors.extend(schedule_errors)
+    result = {
+        "scope": args.scope or ["frontier"], "selected": sorted(selected),
+        "already_done": sorted(ref for ref in selected if issues[ref].done),
+        "rounds": rounds, "externally_blocked": dict(sorted(external.items())),
+        "parked": {ref: issues[ref].status for ref in parked},
+        "issues": {ref: issues[ref].to_dict(root) for ref in sorted(selected)}, "errors": errors,
+    }
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"scope: {' '.join(result['scope'])} -> {len(selected)} issue(s), {len(rounds)} round(s)")
+        for number, members in enumerate(rounds, 1):
+            print(f"  round {number}: {', '.join(members)}")
+        for error in errors:
+            print(f"  ERROR: {error}")
+    if errors:
+        return 1
+    return 0 if selected or parked else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())