claude-code-generator 0.1.0__py3-none-any.whl

code_generator/gh.py

@@ -0,0 +1,331 @@
+"""Thin subprocess wrapper around the `gh` CLI.
+
+All GitHub operations in the orchestrator go through this module.
+No direct subprocess.run() for gh is allowed outside this file.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+# ---------------------------------------------------------------------------
+# Exception
+# ---------------------------------------------------------------------------
+
+
+class GhError(RuntimeError):
+    """Raised when a `gh` subprocess exits with a non-zero return code.
+
+    Attributes:
+        returncode: The exit code from the gh process.
+        stderr: The stderr output from the gh process.
+    """
+
+    def __init__(self, returncode: int, stderr: str) -> None:
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"gh exited with code {returncode}: {stderr!r}")
+
+
+# ---------------------------------------------------------------------------
+# Internal helper
+# ---------------------------------------------------------------------------
+
+
+def _run(argv: list[str], *, input: str | None = None) -> str:  # noqa: A002
+    """Run a gh sub-command and return stdout on success.
+
+    Args:
+        argv: Full argument list including the ``gh`` binary, e.g.
+            ``["gh", "issue", "list"]``.
+        input: Optional string piped to stdin.
+
+    Returns:
+        Stripped stdout string.
+
+    Raises:
+        GhError: When the process exits with a non-zero return code.
+    """
+    result = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        check=False,
+        input=input,
+    )
+    if result.returncode != 0:
+        raise GhError(result.returncode, result.stderr)
+    return result.stdout.strip()
+
+
+# ---------------------------------------------------------------------------
+# Repository discovery helper
+# ---------------------------------------------------------------------------
+
+
+def _repo_name_with_owner() -> str:
+    """Return the ``owner/repo`` string for the current repository.
+
+    Returns:
+        A string like ``"SilvioBaratto/code-generator"``.
+
+    Raises:
+        GhError: When gh cannot determine the repo.
+    """
+    return _run(["gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"])
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def create_issue(
+    title: str,
+    body: str,
+    labels: list[str],
+    *,
+    milestone: str | None = None,
+    assignee: str = "@me",
+) -> int:
+    """Create a GitHub issue and return its number.
+
+    Args:
+        title: Issue title.
+        body: Issue body (Markdown).
+        labels: List of label names to attach.
+        milestone: Optional milestone title to assign the issue to.
+        assignee: GitHub username or ``"@me"`` (default).
+
+    Returns:
+        The integer issue number parsed from the returned URL.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    argv = [
+        "gh", "issue", "create",
+        "--title", title,
+        "--body", body,
+        "--label", ",".join(labels),
+        "--assignee", assignee,
+    ]
+    if milestone is not None:
+        argv += ["--milestone", milestone]
+
+    url = _run(argv)
+    # URL looks like: https://github.com/owner/repo/issues/42
+    return int(url.rstrip("/").split("/")[-1])
+
+
+def view_issue(number: int) -> dict:  # type: ignore[type-arg]
+    """Fetch a single issue as a dict.
+
+    Args:
+        number: The issue number.
+
+    Returns:
+        Parsed JSON dict with keys ``title``, ``body``, ``state``,
+        ``labels``, and ``number``.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    raw = _run([
+        "gh", "issue", "view", str(number),
+        "--json", "title,body,state,labels,number",
+    ])
+    return json.loads(raw)  # type: ignore[no-any-return]
+
+
+def close_issue(
+    number: int,
+    *,
+    reason: str = "completed",
+    comment: str | None = None,
+) -> None:
+    """Close an issue.
+
+    Args:
+        number: The issue number.
+        reason: Close reason — ``"completed"`` or ``"not planned"``.
+        comment: Optional comment to post alongside closure.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    argv = ["gh", "issue", "close", str(number), "--reason", reason]
+    if comment is not None:
+        argv += ["--comment", comment]
+    _run(argv)
+
+
+def list_issues(
+    *,
+    milestone: str | None = None,
+    state: str = "open",
+) -> list[dict]:  # type: ignore[type-arg]
+    """List issues, optionally filtered by milestone.
+
+    Args:
+        milestone: Milestone title to filter by.
+        state: Issue state — ``"open"``, ``"closed"``, or ``"all"``.
+
+    Returns:
+        List of dicts with keys ``number``, ``title``, ``state``,
+        ``labels``.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    argv = [
+        "gh", "issue", "list",
+        "--state", state,
+        "--json", "number,title,state,labels",
+    ]
+    if milestone is not None:
+        argv += ["--milestone", milestone]
+
+    raw = _run(argv)
+    return json.loads(raw)  # type: ignore[no-any-return]
+
+
+def create_milestone(title: str, description: str = "") -> int:
+    """Create a GitHub milestone via the API and return its number.
+
+    Args:
+        title: Milestone title.
+        description: Optional description.
+
+    Returns:
+        The integer milestone number from the API response.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    nwo = _repo_name_with_owner()
+    raw = _run([
+        "gh", "api",
+        "--method", "POST",
+        f"repos/{nwo}/milestones",
+        "-f", f"title={title}",
+        "-f", f"description={description}",
+        "-f", "state=open",
+    ])
+    data = json.loads(raw)
+    return int(data["number"])
+
+
+def close_milestone(number: int) -> None:
+    """Close a GitHub milestone via the API.
+
+    Args:
+        number: The milestone number.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    nwo = _repo_name_with_owner()
+    _run([
+        "gh", "api",
+        "--method", "PATCH",
+        f"repos/{nwo}/milestones/{number}",
+        "-f", "state=closed",
+    ])
+
+
+def ensure_label(name: str, color: str, description: str) -> None:
+    """Create a label, ignoring "already exists" errors.
+
+    Args:
+        name: Label name, e.g. ``"priority:high"``.
+        color: Hex colour without leading ``#``, e.g. ``"FF0000"``.
+        description: Human-readable description.
+
+    Raises:
+        GhError: On any error other than "already exists".
+    """
+    try:
+        _run([
+            "gh", "label", "create", name,
+            "--color", color,
+            "--description", description,
+        ])
+    except GhError as exc:
+        if "already exists" in exc.stderr.lower():
+            return
+        raise
+
+
+def add_label(issue_number: int, label: str) -> None:
+    """Add a label to an existing issue.
+
+    Args:
+        issue_number: The issue number.
+        label: Label name to add.
+
+    Raises:
+        GhError: When gh fails.
+    """
+    _run(["gh", "issue", "edit", str(issue_number), "--add-label", label])
+
+
+def ensure_standard_labels() -> None:
+    """Seed the repository with the standard label taxonomy.
+
+    Creates all labels defined in requirements.md §8. Idempotent —
+    "already exists" errors are silently ignored.
+
+    Labels created:
+    - ``priority:{high,medium,low}``
+    - ``area:{cli,orchestrator,runner,state,prompts,gh,tests,docs,api,
+      frontend,database,auth,infra}``
+    - ``phase:{plan,implement,review,test}``
+    - ``agent:<name>`` for every agent in the §7 selection matrix
+
+    Raises:
+        GhError: On unexpected gh failures.
+    """
+    # priority labels
+    for priority, color in [
+        ("high", "FF0000"),
+        ("medium", "FBCA04"),
+        ("low", "0E8A16"),
+    ]:
+        ensure_label(f"priority:{priority}", color, f"{priority.capitalize()} priority")
+
+    # area labels
+    area_color = "0052CC"
+    for area in [
+        "cli", "orchestrator", "runner", "state", "prompts",
+        "gh", "tests", "docs", "api", "frontend", "database", "auth", "infra",
+    ]:
+        ensure_label(f"area:{area}", area_color, f"Area: {area}")
+
+    # phase labels
+    phase_color = "D4C5F9"
+    for phase in ["plan", "implement", "review", "test"]:
+        ensure_label(f"phase:{phase}", phase_color, f"Phase: {phase}")
+
+    # agent labels  (color: 7057FF per spec)
+    agent_color = "7057FF"
+    agents = [
+        # Angular
+        "frontend-developer",
+        "typescript-pro",
+        "tailwind-patterns",
+        "ui-ux-designer",
+        # FastAPI
+        "python-pro",
+        "fastapi-expert-agent",
+        "supabase-connection-expert",
+        # NestJS
+        "nestjs-expert",
+        # BAML
+        "baml-expert-agent",
+        # Portfolio/Finance
+        "riskfolio-expert",
+    ]
+    for agent in agents:
+        ensure_label(f"agent:{agent}", agent_color, f"Agent: {agent}")

code_generator/logging_setup.py

@@ -0,0 +1,73 @@
+"""Per-phase structured logging for the code-generator orchestrator.
+
+Each phase gets its own log file under .code-generator/logs/ and a shared
+RichHandler for colour-coded console output. The setup is idempotent: calling
+setup_phase_logger() twice for the same phase does not duplicate handlers.
+"""
+
+import logging
+from pathlib import Path
+
+from rich.logging import RichHandler
+
+_FILE_FORMATTER = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+
+
+def setup_phase_logger(
+    phase_name: str,
+    project_dir: Path,
+    *,
+    level: int = logging.INFO,
+) -> logging.Logger:
+    """Configure and return a logger for a single orchestration phase.
+
+    The logger writes to both a phase-specific log file and the console via
+    Rich. A second call for the same phase_name returns the existing logger
+    without adding duplicate handlers.
+
+    Args:
+        phase_name: Short identifier for the phase (e.g. ``"planning"``).
+        project_dir: Root directory of the user's project. Logs are written to
+            ``project_dir / ".code-generator" / "logs" / f"{phase_name}.log"``.
+        level: Python logging level applied to the logger. Defaults to INFO.
+
+    Returns:
+        Configured :class:`logging.Logger` instance.
+    """
+    logger = logging.getLogger(f"code_generator.phase.{phase_name}")
+
+    if _already_configured(logger):
+        return logger
+
+    logger.setLevel(level)
+    logger.propagate = False
+
+    _attach_file_handler(logger, project_dir, phase_name)
+    _attach_rich_handler(logger)
+
+    return logger
+
+
+def _already_configured(logger: logging.Logger) -> bool:
+    """Return True when the logger already has handlers attached."""
+    return bool(logger.handlers)
+
+
+def _attach_file_handler(
+    logger: logging.Logger,
+    project_dir: Path,
+    phase_name: str,
+) -> None:
+    log_dir = project_dir / ".code-generator" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    handler = logging.FileHandler(log_dir / f"{phase_name}.log", encoding="utf-8")
+    handler.setLevel(logging.DEBUG)
+    handler.setFormatter(_FILE_FORMATTER)
+    logger.addHandler(handler)
+
+
+def _attach_rich_handler(logger: logging.Logger) -> None:
+    handler = RichHandler(show_time=False, show_path=False)
+    handler.setLevel(logging.INFO)
+    logger.addHandler(handler)

code_generator/orchestrator/__init__.py

@@ -0,0 +1,4 @@
+"""Orchestrator package — one module per pipeline phase.
+
+Phase modules expose a single async ``run(...)`` coroutine each.
+"""