issue-flow 0.4.3__tar.gz → 0.4.3.post3__tar.gz

{issue_flow-0.4.3 → issue_flow-0.4.3.post3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: issue-flow
-Version: 0.4.3
+Version: 0.4.3.post3
 Summary: Agents should behave. Let them follow the issue flow.
 Keywords: cursor,ai,agents,issue-tracking,workflow
 Author: jepegit

{issue_flow-0.4.3 → issue_flow-0.4.3.post3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "issue-flow"
-version = "0.4.3"
+version = "0.4.3.post3"
 description = "Agents should behave. Let them follow the issue flow."
 readme = "README.md"
 license = "MIT"

{issue_flow-0.4.3 → issue_flow-0.4.3.post3}/src/issue_flow/agent.py

@@ -545,6 +545,399 @@ def _render_version_plan_text(
         console.print(f"  [{style}]{escape(note)}[/{style}]")
 
 
+# ---------------------------------------------------------------------------
+# agent epic-status
+# ---------------------------------------------------------------------------
+
+
+def run_epic_status(
+    project_root: Path,
+    console: Console,
+    number: int,
+    local: bool,
+    as_json: bool,
+) -> int:
+    """Deterministic epic progress: stages, per-issue state, next candidates.
+
+    Read-only. Parses ``epic<N>_plan.md`` (the contract the /iflow-epic skill
+    writes) and — unless ``local`` — resolves each published issue's state via
+    ``gh``. A missing/unauthenticated ``gh`` degrades to ``state: "unknown"``
+    per issue rather than failing the command.
+    """
+    from issue_flow import epicplan
+
+    settings = Settings()
+    plan_path = (
+        project_root
+        / settings.issueflows_dir
+        / settings.epics_folder
+        / f"epic{number}_plan.md"
+    )
+    plan = epicplan.parse_epic_plan(plan_path)
+    if plan is None:
+        msg = f"no epic plan found at {plan_path}; draft one with /iflow-epic {number}."
+        if as_json:
+            _emit_json(console, {"epic": number, "error": msg})
+        else:
+            console.print(f"[red]error[/red]  {escape(msg)}")
+        return 1
+
+    repo_slug: str | None = None
+    owner_repo = gitutils.remote_owner_repo(project_root)
+    if owner_repo is not None:
+        repo_slug = f"{owner_repo[0]}/{owner_repo[1]}"
+
+    states: dict[int, str | None] = {}
+    if not local:
+        for stage in plan.stages:
+            for spec in stage.issues:
+                if spec.published is not None:
+                    states[spec.published] = gitutils.gh_issue_state(
+                        spec.published, project_root, repo_slug
+                    )
+
+    def spec_state(spec: epicplan.IssueSpec) -> str:
+        if spec.published is None:
+            return "unpublished"
+        if local:
+            return "published"
+        state = states.get(spec.published)
+        return state if state in ("open", "closed") else "unknown"
+
+    def dep_closed(dep: int) -> bool:
+        # A dependency counts as satisfied only when provably closed.
+        return (not local) and states.get(dep) == "closed"
+
+    stage_payloads: list[dict[str, Any]] = []
+    current_stage: int | None = None
+    next_candidates: list[int] = []
+    for stage in plan.stages:
+        issues: list[dict[str, Any]] = []
+        done = bool(stage.issues)
+        for spec in stage.issues:
+            state = spec_state(spec)
+            blocked_by = [dep for dep in spec.depends_on if not dep_closed(dep)]
+            issues.append(
+                {
+                    "number": spec.published,
+                    "title": spec.title,
+                    "state": state,
+                    "depends_on": spec.depends_on,
+                    "placeholder_deps": [
+                        f"stage {j} issue {k}" for j, k in spec.placeholder_deps
+                    ],
+                    "blocked_by": blocked_by,
+                    "yolo": spec.yolo,
+                }
+            )
+            if state != "closed":
+                done = False
+        stage_payloads.append(
+            {
+                "index": stage.index,
+                "title": stage.title,
+                "issues": issues,
+                "done": done,
+            }
+        )
+        if not done and current_stage is None:
+            current_stage = stage.index
+            for item in issues:
+                if (
+                    item["state"] == "open"
+                    and not item["blocked_by"]
+                    and not item["placeholder_deps"]
+                ):
+                    next_candidates.append(item["number"])
+
+    payload: dict[str, Any] = {
+        "epic": plan.number if plan.number is not None else number,
+        "title": plan.title,
+        "plan_status": plan.status,
+        "local": local,
+        "stages": stage_payloads,
+        "current_stage": current_stage,
+        "next_candidates": next_candidates,
+    }
+
+    if as_json:
+        _emit_json(console, payload)
+        return 0
+
+    console.print(
+        f"[bold]Epic #{payload['epic']}[/bold] — {escape(plan.title)} "
+        f"[dim](plan: {plan.status})[/dim]"
+    )
+    for stage in stage_payloads:
+        marker = (
+            "done"
+            if stage["done"]
+            else ("current" if stage["index"] == current_stage else "pending")
+        )
+        console.print(f"  Stage {stage['index']} — {escape(stage['title'])} [{marker}]")
+        for item in stage["issues"]:
+            number_str = f"#{item['number']}" if item["number"] else "(unpublished)"
+            flags = " yolo" if item["yolo"] else ""
+            blocked = (
+                f" blocked by {', '.join(f'#{d}' for d in item['blocked_by'])}"
+                if item["blocked_by"]
+                else ""
+            )
+            console.print(
+                f"    {number_str} [{item['state']}]{flags}{blocked} "
+                f"{escape(item['title'])}"
+            )
+    if next_candidates:
+        console.print(
+            "[bold]Next candidates[/bold]: "
+            + ", ".join(f"#{n}" for n in next_candidates)
+        )
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# agent queue
+# ---------------------------------------------------------------------------
+
+
+def _yolo_from_labels(labels: object) -> bool:
+    if not isinstance(labels, list):
+        return False
+    for label in labels:
+        name = label.get("name") if isinstance(label, dict) else label
+        if isinstance(name, str) and name.lower() == "yolo":
+            return True
+    return False
+
+
+def run_queue(
+    project_root: Path,
+    console: Console,
+    numbers: list[int],
+    label: str | None,
+    epic: int | None,
+    as_json: bool,
+) -> int:
+    """Plan an execution queue for the cycling workflow (read-only).
+
+    Exactly one source: explicit issue numbers, a label, or an epic's current
+    stage. Dependencies come from ``Depends on #N`` / ``Blocked by #N`` lines
+    (or the epic plan); the result is a deterministic topological order plus
+    blocked / skipped / independent sets. Cycles abort with exit 1.
+    """
+    from issue_flow import epicplan, queueplan
+
+    settings = Settings()
+    sources = sum(1 for source in (numbers, label, epic) if source)
+    if sources != 1:
+        msg = "give exactly one source: issue numbers, --label, or --epic."
+        if as_json:
+            _emit_json(console, {"error": msg})
+        else:
+            console.print(f"[red]error[/red]  {msg}")
+        return 2
+
+    repo_slug: str | None = None
+    owner_repo = gitutils.remote_owner_repo(project_root)
+    if owner_repo is not None:
+        repo_slug = f"{owner_repo[0]}/{owner_repo[1]}"
+
+    notes: list[str] = []
+    items: list[queueplan.QueueItem] = []
+    source: dict[str, Any]
+
+    if numbers:
+        source = {"type": "numbers", "value": numbers}
+        missing: list[int] = []
+        for number in numbers:
+            meta = gitutils.gh_issue_meta(number, project_root, repo_slug)
+            if meta is None:
+                missing.append(number)
+                continue
+            items.append(
+                queueplan.QueueItem(
+                    number=meta.get("number", number),
+                    title=meta.get("title", ""),
+                    state=str(meta.get("state", "unknown")).lower(),
+                    yolo=_yolo_from_labels(meta.get("labels")),
+                    depends_on=queueplan.parse_dependencies(meta.get("body") or ""),
+                )
+            )
+        if missing:
+            # A typo must never shrink the confirmed queue silently.
+            msg = (
+                "could not fetch issue(s) "
+                + ", ".join(f"#{n}" for n in missing)
+                + " (gh missing/unauthenticated, or wrong number); refusing to "
+                "plan a partial queue."
+            )
+            if as_json:
+                _emit_json(console, {"source": source, "error": msg})
+            else:
+                console.print(f"[red]error[/red]  {msg}")
+            return 1
+    elif label:
+        source = {"type": "label", "value": label}
+        listing = gitutils.gh_issue_list_meta(project_root, repo_slug, label=label)
+        if listing is None:
+            msg = "gh is unavailable or unauthenticated; cannot list issues."
+            if as_json:
+                _emit_json(console, {"source": source, "error": msg})
+            else:
+                console.print(f"[red]error[/red]  {msg}")
+            return 1
+        for meta in listing:
+            items.append(
+                queueplan.QueueItem(
+                    number=meta.get("number", 0),
+                    title=meta.get("title", ""),
+                    state=str(meta.get("state", "open")).lower(),
+                    yolo=_yolo_from_labels(meta.get("labels")),
+                    depends_on=queueplan.parse_dependencies(meta.get("body") or ""),
+                )
+            )
+    else:
+        source = {"type": "epic", "value": epic}
+        plan_path = (
+            project_root
+            / settings.issueflows_dir
+            / settings.epics_folder
+            / f"epic{epic}_plan.md"
+        )
+        epic_plan = epicplan.parse_epic_plan(plan_path)
+        if epic_plan is None:
+            msg = f"no epic plan found at {plan_path}."
+            if as_json:
+                _emit_json(console, {"source": source, "error": msg})
+            else:
+                console.print(f"[red]error[/red]  {msg}")
+            return 1
+        # Current stage: the first stage whose published specs are not all
+        # closed (or that still has unpublished specs).
+        states: dict[int, str] = {}
+        chosen = None
+        for stage in epic_plan.stages:
+            stage_done = bool(stage.issues)
+            for spec in stage.issues:
+                if spec.published is None:
+                    stage_done = False
+                    continue
+                state = gitutils.gh_issue_state(spec.published, project_root, repo_slug)
+                states[spec.published] = state or "unknown"
+                if state != "closed":
+                    stage_done = False
+            if not stage_done:
+                chosen = stage
+                break
+        if chosen is None:
+            notes.append("every stage of the epic is complete; nothing to queue.")
+        else:
+            source["stage"] = chosen.index
+            unpublished = [
+                spec.title for spec in chosen.issues if spec.published is None
+            ]
+            if unpublished:
+                notes.append(
+                    "unpublished specs are not queueable: "
+                    + "; ".join(unpublished)
+                    + " — run the epic publish action first."
+                )
+            for spec in chosen.issues:
+                if spec.published is None:
+                    continue
+                items.append(
+                    queueplan.QueueItem(
+                        number=spec.published,
+                        title=spec.title,
+                        state=states.get(spec.published, "unknown"),
+                        yolo=spec.yolo,
+                        depends_on=list(spec.depends_on),
+                    )
+                )
+
+    plan = queueplan.build_queue(items)
+
+    if plan.cycle:
+        payload = {
+            "source": source,
+            "error": "dependency cycle detected",
+            "cycle": plan.cycle,
+        }
+        if as_json:
+            _emit_json(console, payload)
+        else:
+            console.print(
+                "[red]error[/red]  dependency cycle detected among "
+                + ", ".join(f"#{n}" for n in plan.cycle)
+                + " — fix the Depends on lines; nothing was planned."
+            )
+        return 1
+
+    payload = {
+        "source": source,
+        "queue": [
+            {
+                "order": position + 1,
+                "number": item.number,
+                "title": item.title,
+                "yolo": item.yolo,
+                "depends_on": item.depends_on,
+            }
+            for position, item in enumerate(plan.ordered)
+        ],
+        "blocked": [
+            {
+                "number": item.number,
+                "title": item.title,
+                "open_external_deps": deps,
+            }
+            for item, deps in plan.blocked
+        ],
+        "skipped_closed": [item.number for item in plan.skipped_closed],
+        "independent": plan.independent,
+        "notes": notes,
+    }
+
+    if as_json:
+        _emit_json(console, payload)
+        return 0
+
+    if not plan.ordered:
+        console.print("[dim]Nothing to queue.[/dim]")
+    for entry in payload["queue"]:
+        flags = " [yolo]" if entry["yolo"] else ""
+        deps = (
+            f" (after {', '.join(f'#{d}' for d in entry['depends_on'])})"
+            if entry["depends_on"]
+            else ""
+        )
+        console.print(
+            f"  {entry['order']}. #{entry['number']}{flags} "
+            f"{escape(entry['title'])}{deps}"
+        )
+    for entry in payload["blocked"]:
+        console.print(
+            f"  [yellow]blocked[/yellow] #{entry['number']} "
+            f"{escape(entry['title'])} — waiting on "
+            + ", ".join(f"#{d}" for d in entry["open_external_deps"])
+        )
+    if plan.skipped_closed:
+        console.print(
+            "  [dim]skipped (closed): "
+            + ", ".join(f"#{n}" for n in payload["skipped_closed"])
+            + "[/dim]"
+        )
+    if plan.independent:
+        console.print(
+            "  [dim]independent (parallel-safe): "
+            + ", ".join(f"#{n}" for n in plan.independent)
+            + "[/dim]"
+        )
+    for note in notes:
+        console.print(f"  [dim]{escape(note)}[/dim]")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # workspace init
 # ---------------------------------------------------------------------------

{issue_flow-0.4.3 → issue_flow-0.4.3.post3}/src/issue_flow/cli.py

@@ -319,6 +319,86 @@ def agent_version_plan(
     )
 
 
+@agent_app.command("epic-status")
+def agent_epic_status(
+    number: int = typer.Argument(..., help="Epic anchor issue number."),
+    project_dir: Path = typer.Option(
+        Path("."),
+        "--project-dir",
+        "-C",
+        help="Project root directory (defaults to current directory).",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+    ),
+    local: bool = typer.Option(
+        False,
+        "--local",
+        help="Skip the GitHub state lookups; report only the local plan file.",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit a machine-readable JSON object."
+    ),
+) -> None:
+    """Deterministic epic progress (read-only).
+
+    Parses ``.issueflows/05-epics/epic<N>_plan.md`` (the structure written by
+    the /iflow-epic skill) and cross-references published issue states via
+    ``gh``: stages with per-issue state and blockers, the current stage, and
+    the next open, unblocked candidates. Exit 1 when no plan file exists.
+    """
+    from issue_flow.agent import run_epic_status
+
+    raise typer.Exit(
+        code=run_epic_status(project_dir, _console, number, local, json_output)
+    )
+
+
+@agent_app.command("queue")
+def agent_queue(
+    numbers: list[int] = typer.Argument(
+        None,
+        help="Explicit issue numbers to queue (alternative to --label/--epic).",
+    ),
+    project_dir: Path = typer.Option(
+        Path("."),
+        "--project-dir",
+        "-C",
+        help="Project root directory (defaults to current directory).",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+    ),
+    label: str | None = typer.Option(
+        None, "--label", help="Queue every open issue carrying this label."
+    ),
+    epic: int | None = typer.Option(
+        None,
+        "--epic",
+        help="Queue the current stage of this epic's plan file.",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit a machine-readable JSON object."
+    ),
+) -> None:
+    """Plan a hands-off execution queue (read-only).
+
+    Exactly one source — explicit numbers, ``--label``, or ``--epic`` — is
+    resolved, ``Depends on #N`` / ``Blocked by #N`` lines are parsed, and the
+    result is a deterministic topological order plus ``blocked`` (open
+    dependencies outside the queue), ``skipped_closed``, and ``independent``
+    (parallel-safe) sets. A dependency cycle aborts with exit 1, naming the
+    members; nothing is ever executed by this command.
+    """
+    from issue_flow.agent import run_queue
+
+    raise typer.Exit(
+        code=run_queue(
+            project_dir, _console, list(numbers or []), label, epic, json_output
+        )
+    )
+
+
 @agent_app.command("resolve")
 def agent_resolve(
     project_dir: Path = typer.Option(

{issue_flow-0.4.3 → issue_flow-0.4.3.post3}/src/issue_flow/config.py

@@ -67,6 +67,7 @@ class Settings:
     partly_solved_folder: str = "02-partly-solved-issues"
     solved_folder: str = "03-solved-issues"
     designs_folder: str = "04-designs-and-guides"
+    epics_folder: str = "05-epics"
 
     @property
     def issueflows_subdirs(self) -> list[str]:
@@ -76,6 +77,7 @@ class Settings:
             self.partly_solved_folder,
             self.solved_folder,
             self.designs_folder,
+            self.epics_folder,
         ]
 
     def agent_dir_for(self, profile: EditorProfile) -> str:
@@ -315,6 +317,7 @@ class Settings:
             "partly_solved_folder": self.partly_solved_folder,
             "solved_folder": self.solved_folder,
             "designs_folder": self.designs_folder,
+            "epics_folder": self.epics_folder,
             "project_name": project_name,
             "editor": profile.id,
             "editor_name": profile.name,

issue_flow-0.4.3.post3/src/issue_flow/epicplan.py

@@ -0,0 +1,163 @@
+"""Parser for staged epic plan files (``epic<N>_plan.md``).
+
+The ``/iflow-epic`` skill drafts a plan whose structure is a deliberate
+machine-readable contract (stages, ``### Issue:`` specs, ``Depends on:`` /
+``yolo:`` / ``Published: #<M>`` lines). This module encodes that contract
+once, so ``issue-flow agent epic-status`` (and later ``agent queue``) can
+give deterministic answers instead of every agent re-parsing markdown by
+hand. Read-only: nothing here writes files or talks to GitHub.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_TITLE_RE = re.compile(r"^#\s+Epic\s+#(\d+):\s*(.*)$")
+_STATUS_RE = re.compile(r"^Status:\s*(\w+)\s*$", re.IGNORECASE)
+# "## Stage 1 — title" (em dash, hyphen, or colon separators all accepted).
+_STAGE_RE = re.compile(r"^##\s+Stage\s+(\d+)\s*(?:[—:-]\s*)?(.*)$")
+_LATER_RE = re.compile(r"^##\s+Later\b")
+_ISSUE_RE = re.compile(r"^###\s+Issue:\s*(.*)$")
+_PUBLISHED_RE = re.compile(r"^-\s*Published:\s*#(\d+)\s*$")
+_DEPENDS_RE = re.compile(r"^-\s*Depends on:\s*(.*)$")
+_YOLO_RE = re.compile(r"^-\s*yolo:\s*(yes|no)\b", re.IGNORECASE)
+_DEP_NUMBER_RE = re.compile(r"#(\d+)")
+_DEP_PLACEHOLDER_RE = re.compile(r"stage\s+(\d+)\s+issue\s+(\d+)", re.IGNORECASE)
+
+
+@dataclass
+class IssueSpec:
+    """One ``### Issue:`` block inside a stage."""
+
+    title: str
+    stage: int
+    index: int  # 1-based position within the stage
+    published: int | None = None
+    depends_on: list[int] = field(default_factory=list)
+    placeholder_deps: list[tuple[int, int]] = field(default_factory=list)
+    yolo: bool = False
+
+
+@dataclass
+class Stage:
+    index: int
+    title: str
+    issues: list[IssueSpec] = field(default_factory=list)
+
+
+@dataclass
+class EpicPlan:
+    number: int | None
+    title: str
+    status: str  # "draft" | "confirmed" | anything else found
+    stages: list[Stage] = field(default_factory=list)
+
+    def resolve_placeholders(self) -> None:
+        """Fold ``stage <j> issue <k>`` placeholders into ``depends_on``
+        wherever the referenced spec has been published."""
+        by_position = {
+            (spec.stage, spec.index): spec
+            for stage in self.stages
+            for spec in stage.issues
+        }
+        for stage in self.stages:
+            for spec in stage.issues:
+                remaining: list[tuple[int, int]] = []
+                for position in spec.placeholder_deps:
+                    target = by_position.get(position)
+                    if target is not None and target.published is not None:
+                        if target.published not in spec.depends_on:
+                            spec.depends_on.append(target.published)
+                    else:
+                        remaining.append(position)
+                spec.placeholder_deps = remaining
+
+
+def parse_epic_plan(path: Path) -> EpicPlan | None:
+    """Parse an epic plan file, or ``None`` when unreadable.
+
+    Lenient by design: unknown lines are ignored, so hand-edited prose never
+    breaks parsing — only the marker lines above carry meaning.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    plan = EpicPlan(number=None, title="", status="draft")
+    current_stage: Stage | None = None
+    current_issue: IssueSpec | None = None
+    in_later = False
+
+    for line in text.splitlines():
+        stripped = line.strip()
+
+        title_match = _TITLE_RE.match(stripped)
+        if title_match:
+            plan.number = int(title_match.group(1))
+            plan.title = title_match.group(2).strip()
+            continue
+
+        status_match = _STATUS_RE.match(stripped)
+        if status_match:
+            plan.status = status_match.group(1).lower()
+            continue
+
+        if _LATER_RE.match(stripped):
+            in_later = True
+            current_stage = None
+            current_issue = None
+            continue
+
+        stage_match = _STAGE_RE.match(stripped)
+        if stage_match:
+            in_later = False
+            current_stage = Stage(
+                index=int(stage_match.group(1)),
+                title=stage_match.group(2).strip(),
+            )
+            plan.stages.append(current_stage)
+            current_issue = None
+            continue
+
+        if in_later or current_stage is None:
+            continue
+
+        issue_match = _ISSUE_RE.match(stripped)
+        if issue_match:
+            current_issue = IssueSpec(
+                title=issue_match.group(1).strip(),
+                stage=current_stage.index,
+                index=len(current_stage.issues) + 1,
+            )
+            current_stage.issues.append(current_issue)
+            continue
+
+        if current_issue is None:
+            continue
+
+        published_match = _PUBLISHED_RE.match(stripped)
+        if published_match:
+            current_issue.published = int(published_match.group(1))
+            continue
+
+        depends_match = _DEPENDS_RE.match(stripped)
+        if depends_match:
+            payload = depends_match.group(1)
+            current_issue.depends_on = [
+                int(number) for number in _DEP_NUMBER_RE.findall(payload)
+            ]
+            current_issue.placeholder_deps = [
+                (int(j), int(k)) for j, k in _DEP_PLACEHOLDER_RE.findall(payload)
+            ]
+            continue
+
+        yolo_match = _YOLO_RE.match(stripped)
+        if yolo_match:
+            current_issue.yolo = yolo_match.group(1).lower() == "yes"
+            continue
+
+    plan.resolve_placeholders()
+    return plan