agentic-devtools 0.2.332__py3-none-any.whl → 0.2.334__py3-none-any.whl

agentic_devtools/orchestration/nodes/_helpers.py

@@ -0,0 +1,261 @@
+"""Shared helper utilities for work-on-issue node implementations.
+
+Provides issue key parsing, provider detection, LLM call wrappers,
+and repository context discovery helpers.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now() -> str:
+    """Return the current UTC time as an ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# Issue key parsing and provider detection
+# ---------------------------------------------------------------------------
+
+_JIRA_KEY_PATTERN = re.compile(r"^[A-Z][A-Z0-9]+-\d+$")
+
+
+def detect_issue_provider(issue_key: str) -> str:
+    """Detect whether an issue key is Jira or GitHub format.
+
+    Args:
+        issue_key: The issue key to classify.
+
+    Returns:
+        ``"jira"`` for PROJECT-NNN format, ``"github"`` for numeric or #N format.
+    """
+    cleaned_issue_key = issue_key.strip()
+    if not cleaned_issue_key:
+        return "github"
+    # Strip leading # for GitHub issues
+    normalized = cleaned_issue_key.lstrip("#")
+    if normalized.isdigit():
+        return "github"
+    jira_candidate = cleaned_issue_key.upper()
+    if _JIRA_KEY_PATTERN.match(jira_candidate):
+        return "jira"
+    return "github"
+
+
+def normalize_issue_key(issue_key: str) -> str:
+    """Normalize an issue key for consistent usage.
+
+    Strips leading ``#`` characters from GitHub issue numbers.
+
+    Args:
+        issue_key: Raw issue key input.
+
+    Returns:
+        Normalized issue key string.
+    """
+    cleaned_issue_key = issue_key.strip()
+    if cleaned_issue_key.startswith("#"):
+        return cleaned_issue_key.lstrip("#")
+    return cleaned_issue_key
+
+
+# ---------------------------------------------------------------------------
+# Subprocess helpers
+# ---------------------------------------------------------------------------
+
+
+def run_command(
+    args: list[str],
+    *,
+    capture_output: bool = True,
+    timeout: int = 300,
+    cwd: str | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess command with standard error handling.
+
+    Args:
+        args: Command and arguments to run.
+        capture_output: Whether to capture stdout/stderr.
+        timeout: Timeout in seconds.
+        cwd: Working directory for the command.
+
+    Returns:
+        CompletedProcess with return code and output.
+    """
+
+    def _to_text(value: bytes | str | None) -> str:
+        if isinstance(value, bytes):
+            return value.decode("utf-8", errors="replace")
+        if isinstance(value, str):
+            return value
+        return ""
+
+    try:
+        return subprocess.run(
+            args,
+            capture_output=capture_output,
+            text=True,
+            timeout=timeout,
+            cwd=cwd,
+            shell=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        partial_stdout = _to_text(exc.stdout if exc.stdout is not None else exc.output)
+        partial_stderr = _to_text(exc.stderr) if exc.stderr is not None else ""
+        timeout_msg = f"Command timed out after {timeout}s: {' '.join(args)}"
+        return subprocess.CompletedProcess(
+            args=args,
+            returncode=124,
+            stdout=partial_stdout,
+            stderr=f"{timeout_msg}\n{partial_stderr}".rstrip(),
+        )
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(
+            args=args,
+            returncode=127,
+            stdout="",
+            stderr=f"Command not found: {args[0] if args else '<empty command>'}",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Repository context discovery (FR-010)
+# ---------------------------------------------------------------------------
+
+
+def scan_directory_structure(
+    root: Path,
+    *,
+    max_depth: int = 3,
+    exclude_patterns: tuple[str, ...] = (
+        "__pycache__",
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        ".agdt",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+    ),
+) -> list[str]:
+    """Scan directory structure for repository context.
+
+    Args:
+        root: Root directory to scan.
+        max_depth: Maximum directory depth to traverse.
+        exclude_patterns: Directory names to exclude.
+
+    Returns:
+        List of relative file paths found.
+    """
+    if max_depth <= 0:
+        return []
+
+    paths: list[str] = []
+    _scan_recursive(root, root, 0, max_depth, exclude_patterns, paths)
+    return sorted(paths)
+
+
+def _scan_recursive(
+    root: Path,
+    current: Path,
+    depth: int,
+    max_depth: int,
+    exclude_patterns: tuple[str, ...],
+    results: list[str],
+) -> None:
+    """Recursively scan directory tree."""
+    if depth >= max_depth:
+        return
+    try:
+        entries = sorted(current.iterdir())
+    except (PermissionError, FileNotFoundError):
+        return
+    for entry in entries:
+        if entry.name in exclude_patterns:
+            continue
+        relative = str(entry.relative_to(root))
+        if entry.is_file():
+            results.append(relative)
+        elif entry.is_dir():
+            results.append(relative + "/")
+            _scan_recursive(root, entry, depth + 1, max_depth, exclude_patterns, results)
+
+
+def detect_test_conventions(root: Path) -> dict[str, Any]:
+    """Detect testing conventions in the repository.
+
+    Checks for 1:1:1 test layout (tests/unit/) and common test patterns.
+
+    Args:
+        root: Repository root path.
+
+    Returns:
+        Dictionary describing detected test conventions.
+    """
+    conventions: dict[str, Any] = {
+        "has_tests_unit": (root / "tests" / "unit").is_dir(),
+        "has_tests_dir": (root / "tests").is_dir(),
+        "test_layout": "unknown",
+    }
+    if conventions["has_tests_unit"]:
+        conventions["test_layout"] = "1:1:1"
+    elif conventions["has_tests_dir"]:
+        conventions["test_layout"] = "flat"
+    return conventions
+
+
+def _to_nonneg_int(value: Any) -> int:
+    """Coerce a potentially-corrupted state value to a non-negative integer.
+
+    Handles ``None``, ``bool``, ``str``, and numeric inputs from checkpoints
+    that may have been corrupted or migrated from older state schemas.
+    ``bool`` is checked before ``int`` because ``bool`` is a subclass of
+    ``int`` and ``True``/``False`` should not be treated as ``1``/``0``.
+
+    Args:
+        value: Arbitrary value from workflow state.
+
+    Returns:
+        Non-negative integer (0 if coercion fails or result is negative).
+    """
+    if isinstance(value, bool):
+        return 0
+    if isinstance(value, int):
+        return max(0, value)
+    if isinstance(value, float):
+        return max(0, int(value))
+    if isinstance(value, str):
+        try:
+            return max(0, int(value))
+        except ValueError:
+            return 0
+    return 0
+
+
+def read_file_content(path: Path, *, max_chars: int = 10000) -> str:
+    """Read file content with a character budget.
+
+    Args:
+        path: File path to read.
+        max_chars: Maximum characters to return.
+
+    Returns:
+        File content truncated to at most max_chars characters.
+    """
+    _suffix = "\n... [truncated]"
+    try:
+        content = path.read_text(encoding="utf-8")
+        if len(content) > max_chars:
+            if max_chars <= len(_suffix):
+                return content[:max_chars]
+            return content[: max_chars - len(_suffix)] + _suffix
+        return content
+    except (OSError, UnicodeDecodeError):
+        return ""

agentic_devtools/orchestration/nodes/checklist_creation.py

@@ -0,0 +1,139 @@
+"""Checklist creation node: generate structured checklist from plan.
+
+Calls the LLM to decompose the implementation plan into discrete,
+actionable checklist items with acceptance criteria.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agentic_devtools.orchestration.execution.context_factory import _run_async
+from agentic_devtools.orchestration.nodes._helpers import _to_nonneg_int, utc_now
+from agentic_devtools.orchestration.state_schema import WorkOnIssueState
+
+
+def checklist_creation_node(state: WorkOnIssueState) -> dict[str, Any]:
+    """Generate structured checklist from the implementation plan.
+
+    Calls LLM with plan context to produce a list of ChecklistItem entries.
+    """
+    plan = state.get("plan", "")
+    issue_key = state.get("issue_key", "")
+
+    if not plan:
+        return {
+            "step": "checklist_creation",
+            "error": "No plan available to generate checklist from.",
+            "events": [
+                {
+                    "event": "checklist_creation_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "no_plan"},
+                }
+            ],
+        }
+
+    try:
+        checklist_result = _generate_checklist(issue_key, plan)
+    except Exception as exc:
+        return {
+            "step": "checklist_creation",
+            "error": f"Checklist generation failed: {exc}",
+            "events": [
+                {
+                    "event": "checklist_creation_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": str(exc)},
+                }
+            ],
+        }
+
+    checklist_items = checklist_result.get("items", [])
+    token_usage = checklist_result.get("token_usage", {})
+
+    return {
+        "step": "checklist_creation",
+        "error": None,
+        "checklist_items": checklist_items,
+        "checklist_created": True,
+        "token_usage_prompt": _to_nonneg_int(state.get("token_usage_prompt"))
+        + _to_nonneg_int(token_usage.get("prompt_tokens")),
+        "token_usage_completion": _to_nonneg_int(state.get("token_usage_completion"))
+        + _to_nonneg_int(token_usage.get("completion_tokens")),
+        "events": [
+            {
+                "event": "checklist_creation_completed",
+                "timestamp": utc_now(),
+                "signals": {"item_count": len(checklist_items)},
+            }
+        ],
+    }
+
+
+def _generate_checklist(issue_key: str, plan: str) -> dict[str, Any]:
+    """Generate checklist items via LLM provider.
+
+    Returns dict with keys: items (list of dicts), token_usage.
+    """
+    from agentic_devtools.orchestration.llm.factory import ProviderFactory
+
+    factory = ProviderFactory()
+    provider = factory.get_provider("checklist_creation", "work_on_issue")
+
+    system_prompt = (
+        "You are an implementation checklist generator. Given an implementation plan, "
+        "break it down into discrete, actionable checklist items. Each item should be "
+        "small enough to implement in a single TDD cycle (write test, implement, verify).\n\n"
+        "Respond with a JSON object containing:\n"
+        '- "items": list of objects, each with:\n'
+        '  - "description": what needs to be done\n'
+        '  - "acceptance_criteria": how to verify completion\n'
+        '  - "estimated_complexity": "low", "medium", or "high"\n'
+        '  - "is_complete": false\n'
+    )
+
+    user_prompt = f"Issue: {issue_key}\n\nImplementation Plan:\n{plan}"
+
+    async def _call_llm():
+        from agentic_devtools.orchestration.llm.types import LLMMessage
+
+        messages = [
+            LLMMessage(role="system", content=system_prompt),
+            LLMMessage(role="user", content=user_prompt),
+        ]
+        response = await provider.complete(messages)
+        return response
+
+    response = _run_async(_call_llm())
+
+    token_usage = {}
+    if response.usage:
+        token_usage = {
+            "prompt_tokens": response.usage.input_tokens,
+            "completion_tokens": response.usage.output_tokens,
+        }
+
+    _FALLBACK_ITEM = [
+        {
+            "description": "Implement the plan as described",
+            "acceptance_criteria": "All tests pass",
+            "estimated_complexity": "medium",
+            "is_complete": False,
+        }
+    ]
+
+    try:
+        parsed = json.loads(response.text)
+        if isinstance(parsed, dict):
+            items = parsed.get("items", [])
+            if not (isinstance(items, list) and items):
+                items = _FALLBACK_ITEM
+        else:
+            items = _FALLBACK_ITEM
+    except (json.JSONDecodeError, TypeError):
+        # Fallback: create a single item from the plan
+        items = _FALLBACK_ITEM
+
+    return {"items": items, "token_usage": token_usage}

agentic_devtools/orchestration/nodes/commit.py

@@ -0,0 +1,169 @@
+"""Commit node: generate commit message and invoke agdt-git-save-work.
+
+Creates a conventional commit message following ``type(#NNN): summary``
+for GitHub issues or ``type(PROJECT-NNN): summary`` for Jira keys,
+and uses ``agdt-git-save-work`` which handles smart amend detection.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from agentic_devtools.orchestration.nodes._helpers import (
+    normalize_issue_key,
+    run_command,
+    utc_now,
+)
+from agentic_devtools.orchestration.state_schema import WorkOnIssueState
+
+
+def commit_node(state: WorkOnIssueState) -> dict[str, Any]:
+    """Generate commit message and save work.
+
+    Builds a conventional commit message and invokes ``agdt-git-save-work``
+    which handles smart amend detection automatically.
+
+    Fails fast when ``issue_key`` is missing, blank, or not a string so a
+    corrupted/resumed checkpoint cannot generate an invalid ``feat():``
+    commit or raise ``AttributeError`` inside ``normalize_issue_key()``.
+    """
+    issue_key = state.get("issue_key", "")
+    if not isinstance(issue_key, str) or not issue_key.strip():
+        return {
+            "step": "commit",
+            "error": "issue_key is required and must be a non-empty string",
+            "events": [
+                {
+                    "event": "commit_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "missing_issue_key"},
+                }
+            ],
+        }
+    normalized_key = normalize_issue_key(issue_key)
+    if not normalized_key:
+        return {
+            "step": "commit",
+            "error": "issue_key must normalize to a non-empty issue identifier",
+            "events": [
+                {
+                    "event": "commit_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": "invalid_issue_key"},
+                }
+            ],
+        }
+    plan = state.get("plan", "")
+    issue_data = state.get("issue_data", {})
+
+    # Generate commit message
+    issue_provider = state.get("issue_provider")
+    commit_message = _generate_commit_message(normalized_key, plan, issue_data, issue_provider)
+
+    # Invoke agdt-git-save-work
+    result = run_command(
+        ["agdt-git-save-work", "--commit-message", commit_message],
+        timeout=120,
+    )
+
+    if result.returncode != 0:
+        return {
+            "step": "commit",
+            "error": f"git save-work failed: {result.stderr.strip()}",
+            "commit_message": commit_message,
+            "events": [
+                {
+                    "event": "commit_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": result.stderr.strip()},
+                }
+            ],
+        }
+
+    # Wait for background task
+    wait_result = run_command(["agdt-task-wait"], timeout=120)
+    if wait_result.returncode != 0:
+        return {
+            "step": "commit",
+            "error": f"agdt-task-wait failed after commit: {wait_result.stderr.strip()}",
+            "commit_message": commit_message,
+            "events": [
+                {
+                    "event": "commit_wait_failed",
+                    "timestamp": utc_now(),
+                    "signals": {"error": wait_result.stderr.strip()},
+                }
+            ],
+        }
+
+    return {
+        "step": "commit",
+        "error": None,
+        "commit_created": True,
+        "branch_pushed": True,
+        "commit_message": commit_message,
+        "events": [
+            {
+                "event": "commit_completed",
+                "timestamp": utc_now(),
+                "signals": {"commit_created": True, "branch_pushed": True},
+            }
+        ],
+    }
+
+
+def _generate_commit_message(
+    issue_key: str,
+    plan: str,
+    issue_data: Any,
+    issue_provider: str | None = None,
+) -> str:
+    """Generate a conventional commit message.
+
+    Format: ``feat(#NNN): summary\\n\\nbody\\n\\n#NNN`` for GitHub issues or
+    ``feat(PROJECT-NNN): summary\\n\\nbody\\n\\n[PROJECT-NNN](https://<jira>/browse/PROJECT-NNN)``
+    for Jira keys.
+    """
+    summary = ""
+    if isinstance(issue_data, dict):
+        raw_summary = issue_data.get("summary", "")
+        if isinstance(raw_summary, str):
+            summary = raw_summary
+
+    if not isinstance(plan, str):
+        plan = ""
+
+    if not summary:
+        # Extract from plan if available
+        summary = "implement autonomous workflow"
+        if plan:
+            first_line = plan.split("\n")[0][:50]
+            if first_line:
+                summary = first_line.lower()
+
+    # Determine scope prefix
+    normalized = issue_key.lstrip("#")
+    if normalized.isdigit():
+        scope = f"#{normalized}"
+        provider = "github"
+    else:
+        scope = normalized
+        provider = "jira"
+
+    if isinstance(issue_provider, str) and issue_provider in {"github", "jira"}:
+        provider = issue_provider
+
+    footer = scope
+    if provider == "jira":
+        jira_base_url = os.environ.get("JIRA_BASE_URL", "https://jira.swica.ch").rstrip("/")
+        footer = f"[{scope}]({jira_base_url}/browse/{scope})"
+
+    title = f"feat({scope}): {summary}"
+    # Ensure title is not too long
+    if len(title) > 72:
+        title = title[:69] + "..."
+
+    body = f"Autonomous implementation via LangChain work-on-issue workflow.\n\n{footer}"
+
+    return f"{title}\n\n{body}"