@danmoisan/drm-copilot-mcp 0.0.1

package/resources/scripts/dev_tools/potential_to_issue.py

@@ -0,0 +1,421 @@
+"""Promote a potential feature file to a GitHub issue using the gh CLI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+from dev_tools.potential_to_issue_content import (
+    BUG_SECTION_HEADINGS,
+    PLACEHOLDER,
+    build_body,
+    build_bug_body,
+    build_minor_audit_body,
+    extract_last_updated,
+    get_feature_name,
+    get_feature_path,
+    get_section,
+    normalize_smart_punctuation,
+    parse_issue_reference,
+    update_metadata_lines,
+)
+from dev_tools.prompt_mode_contract import (
+    ACCEPTED_WORK_MODES,
+    normalize_requested_work_mode,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+PROMOTION_TYPES = ("epic", "feature", "refactor", "bug")
+WORK_MODES = ACCEPTED_WORK_MODES
+TITLE_PREFIXES = {
+    "epic": "Epic",
+    "feature": "Feature",
+    "refactor": "Refactor",
+    "bug": "Bug",
+}
+FEATURE_LABEL_COLOR = "0e8a16"
+FEATURE_LABEL_DESCRIPTION = "Feature work"
+
+
+class PromotionError(Exception):
+    """Raised when a promotion precondition fails."""
+
+
+@dataclass
+class GhResult:
+    output: list[str]
+    exit_code: int
+
+
+class GhClient(Protocol):
+    def is_authenticated(self) -> bool: ...
+
+    def issue_create(self, title: str, body: str, promotion_type: str) -> GhResult: ...
+
+    def ensure_label(self, label: str) -> GhResult: ...
+
+    def issue_view(self, issue_number: str) -> GhResult: ...
+
+
+@dataclass
+class RealGhClient(GhClient):
+    gh_path: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.gh_path is None:
+            self.gh_path = shutil.which("gh")
+        if not self.gh_path:
+            raise FileNotFoundError(
+                "gh CLI not found on PATH. Install gh and authenticate first."
+            )
+
+    def is_authenticated(self) -> bool:
+        gh_exe = self.gh_path
+        if gh_exe is None:
+            return False
+
+        result = subprocess.run(  # noqa: S603 - static analysis can't verify runtime validation
+            [gh_exe, "auth", "status"],
+            capture_output=True,
+            check=False,
+        )
+        return result.returncode == 0
+
+    def _run(self, args: list[str], body: str | None = None) -> GhResult:
+        gh_exe = self.gh_path
+        if gh_exe is None:
+            raise RuntimeError("gh CLI path was not resolved")
+
+        proc: subprocess.CompletedProcess[str] = (
+            subprocess.run(  # noqa: S603 - static analysis can't verify runtime validation
+                [gh_exe, *args],
+                input=body,
+                text=True,
+                encoding="utf-8",
+                capture_output=True,
+                check=False,
+            )
+        )
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        combined = stdout + stderr
+        return GhResult(output=combined.splitlines(), exit_code=int(proc.returncode))
+
+    def issue_create(self, title: str, body: str, promotion_type: str) -> GhResult:
+        args = [
+            "issue",
+            "create",
+            "--title",
+            title,
+            "--body-file",
+            "-",
+            "--label",
+            promotion_type,
+        ]
+        return self._run(args, body)
+
+    def ensure_label(self, label: str) -> GhResult:
+        args = [
+            "label",
+            "create",
+            label,
+            "--color",
+            FEATURE_LABEL_COLOR,
+            "--description",
+            FEATURE_LABEL_DESCRIPTION,
+        ]
+        return self._run(args)
+
+    def issue_view(self, issue_number: str) -> GhResult:
+        args = [
+            "issue",
+            "view",
+            issue_number,
+            "--json",
+            "number,title,url,author,updatedAt",
+        ]
+        return self._run(args)
+
+
+class FileSystem(Protocol):
+    def resolve_path(self, path_str: str) -> Path: ...
+
+    def exists(self, path: Path) -> bool: ...
+
+    def read_text(self, path: Path) -> str: ...
+
+    def write_text(self, path: Path, content: str) -> None: ...
+
+    def write_lines(self, path: Path, lines: Iterable[str]) -> None: ...
+
+    def ensure_dir(self, path: Path) -> None: ...
+
+    def move(self, src: Path, dest: Path) -> None: ...
+
+
+@dataclass
+class RealFileSystem(FileSystem):
+    def resolve_path(self, path_str: str) -> Path:
+        return Path(path_str).expanduser().resolve()
+
+    def exists(self, path: Path) -> bool:
+        return path.exists()
+
+    def read_text(self, path: Path) -> str:
+        return path.read_text(encoding="utf-8")
+
+    def write_text(self, path: Path, content: str) -> None:
+        path.write_text(content, encoding="utf-8")
+
+    def write_lines(self, path: Path, lines: Iterable[str]) -> None:
+        joined = "\n".join(lines)
+        path.write_text(joined, encoding="utf-8")
+
+    def ensure_dir(self, path: Path) -> None:
+        path.mkdir(parents=True, exist_ok=True)
+
+    def move(self, src: Path, dest: Path) -> None:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src), str(dest))
+
+
+@dataclass
+class PromotionOutcome:
+    exit_code: int
+    messages: list[str]
+    destination: Path | None = None
+
+
+def _resolve_workspace() -> Path:
+    return Path.cwd()
+
+
+def _default(message: str) -> None:
+    print(message)
+
+
+def _is_missing_label_failure(output: list[str], label: str) -> bool:
+    """Return whether gh output reports a missing-label create failure."""
+    expected_fragment = f"could not add label: '{label}' not found"
+    return any(expected_fragment in line.lower() for line in output)
+
+
+def promote_potential(
+    potential_path: str,
+    promotion_type: str = "feature",
+    *,
+    fs: FileSystem | None = None,
+    gh: GhClient | None = None,
+    workspace: Path | None = None,
+    work_mode: str = "full",
+    emit: Callable[[str], None] = _default,
+) -> PromotionOutcome:
+    if promotion_type not in PROMOTION_TYPES:
+        raise PromotionError(f"Invalid promotion type: {promotion_type}")
+    if work_mode not in WORK_MODES:
+        raise PromotionError(f"Invalid work mode: {work_mode}")
+
+    filesystem = fs or RealFileSystem()
+    gh_client = gh or RealGhClient()
+    workspace_path = workspace or _resolve_workspace()
+
+    if not gh_client.is_authenticated():
+        raise PromotionError(
+            "GitHub CLI is not authenticated. Run 'gh auth login' first."
+        )
+
+    resolved = filesystem.resolve_path(potential_path)
+    if not filesystem.exists(resolved):
+        raise PromotionError(f"Potential file not found: {potential_path}")
+
+    content = filesystem.read_text(resolved)
+    if not content.strip():
+        raise PromotionError(f"Potential file is empty: {resolved}")
+
+    feature_name = get_feature_name(content, resolved)
+    feature_path = get_feature_path(feature_name)
+    prefix = TITLE_PREFIXES.get(promotion_type, "Feature")
+    issue_title = normalize_smart_punctuation(f"{prefix}: {feature_name}")
+
+    def _relative_path() -> str:
+        try:
+            return os.path.relpath(resolved, workspace_path)
+        except ValueError:
+            return str(resolved)
+
+    relative_path = Path(_relative_path()).as_posix()
+
+    try:
+        selected_mode = normalize_requested_work_mode(work_mode, promotion_type)
+    except ValueError as exc:
+        raise PromotionError(str(exc)) from exc
+    fallback_reason = ""
+
+    if selected_mode == "minor-audit":
+        problem = get_section(content, "Problem / Why") or PLACEHOLDER
+        implementation_intent = get_section(content, "Proposed Behavior") or PLACEHOLDER
+        acceptance_criteria = (
+            get_section(content, "Acceptance Criteria (early draft)") or PLACEHOLDER
+        )
+        dependencies_risks = get_section(content, "Constraints & Risks") or PLACEHOLDER
+        verification_steps = (
+            get_section(content, "Test Conditions to Consider") or PLACEHOLDER
+        )
+        evidence_checklist = get_section(content, "Evidence Checklist")
+        if not evidence_checklist:
+            evidence_checklist = (
+                "- [ ] Baseline\n- [ ] End-state\n- [ ] Targeted verification"
+            )
+        body = build_minor_audit_body(
+            selected_mode,
+            problem,
+            implementation_intent,
+            acceptance_criteria,
+            dependencies_risks,
+            verification_steps,
+            evidence_checklist,
+            relative_path,
+        )
+    elif promotion_type == "bug":
+        bug_sections = {
+            heading: get_section(content, heading) or PLACEHOLDER
+            for heading in BUG_SECTION_HEADINGS
+        }
+        body = build_bug_body(selected_mode, bug_sections, relative_path)
+    else:
+        problem = get_section(content, "Problem / Why") or PLACEHOLDER
+        behavior = get_section(content, "Proposed Behavior") or PLACEHOLDER
+        criteria = (
+            get_section(content, "Acceptance Criteria (early draft)") or PLACEHOLDER
+        )
+        constraints = get_section(content, "Constraints & Risks") or PLACEHOLDER
+        tests = get_section(content, "Test Conditions to Consider") or PLACEHOLDER
+        body = build_body(
+            selected_mode,
+            problem,
+            behavior,
+            criteria,
+            constraints,
+            tests,
+            relative_path,
+        )
+    body = normalize_smart_punctuation(body)
+
+    messages: list[str] = []
+
+    def _emit(msg: str) -> None:
+        messages.append(msg)
+        emit(msg)
+
+    _emit(f"Selected mode: {selected_mode}")
+    if fallback_reason:
+        _emit(f"Fallback reason: {fallback_reason}")
+    _emit(f"Creating issue: {issue_title} (label: {promotion_type})")
+    create_result = gh_client.issue_create(issue_title, body, promotion_type)
+
+    # Recover only from the known missing-label failure for the selected
+    # promotion label so other gh errors still fail fast with their original
+    # output.
+    if _is_missing_label_failure(create_result.output, promotion_type):
+        _emit("Missing promotion label detected; ensuring label exists and retrying.")
+        ensure_label_result = gh_client.ensure_label(promotion_type)
+        for line in ensure_label_result.output:
+            _emit(line)
+        if ensure_label_result.exit_code == 0:
+            create_result = gh_client.issue_create(issue_title, body, promotion_type)
+
+    if create_result.exit_code != 0:
+        output_lines = create_result.output or [
+            f"gh CLI exited with code {create_result.exit_code}"
+        ]
+        for line in output_lines:
+            _emit(line)
+        return PromotionOutcome(exit_code=create_result.exit_code, messages=messages)
+
+    for line in create_result.output:
+        _emit(line)
+
+    issue_url, issue_number = parse_issue_reference(create_result.output)
+
+    last_updated: str | None = None
+    if issue_number:
+        view_result = gh_client.issue_view(issue_number)
+        if view_result.exit_code == 0 and view_result.output:
+            last_updated = extract_last_updated("\n".join(view_result.output))
+
+    if issue_number and issue_url:
+        lines = content.splitlines()
+        updated_lines = update_metadata_lines(
+            lines,
+            feature_name,
+            issue_number,
+            issue_url,
+            last_updated,
+            feature_path,
+        )
+        filesystem.write_lines(resolved, updated_lines)
+        _emit(f"Updated potential file with issue metadata: {resolved}")
+
+    promoted_dir = workspace_path / "docs" / "features" / "potential" / "promoted"
+    filesystem.ensure_dir(promoted_dir)
+    dest_path = promoted_dir / resolved.name
+    filesystem.move(resolved, dest_path)
+    _emit(f"Moved potential file to promoted folder: {dest_path}")
+
+    return PromotionOutcome(exit_code=0, messages=messages, destination=dest_path)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a GitHub issue from a potential feature file using gh CLI.",
+    )
+    parser.add_argument(
+        "--potential-path",
+        required=True,
+        help="Path to the potential feature markdown file.",
+    )
+    parser.add_argument(
+        "--promotion-type",
+        choices=PROMOTION_TYPES,
+        default="feature",
+        help="Promotion type label to attach to the issue.",
+    )
+    parser.add_argument(
+        "--work-mode",
+        choices=WORK_MODES,
+        default="full",
+        help=(
+            "Work mode routing. Canonical values are minor-audit, full-feature, "
+            "and full-bug; full is accepted as a backward-compatible alias."
+        ),
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        outcome = promote_potential(
+            potential_path=args.potential_path,
+            promotion_type=args.promotion_type,
+            work_mode=args.work_mode,
+        )
+    except (PromotionError, FileNotFoundError) as exc:
+        print(str(exc))
+        raise SystemExit(1) from exc
+    except subprocess.SubprocessError as exc:  # pragma: no cover
+        print(f"gh CLI execution failed: {exc}")
+        raise SystemExit(1) from exc
+
+    raise SystemExit(outcome.exit_code)
+
+
+if __name__ == "__main__":
+    main()

package/resources/scripts/dev_tools/potential_to_issue_content.py

@@ -0,0 +1,212 @@
+"""Content and metadata helpers for potential-to-issue promotion workflows."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+PLACEHOLDER = "(not provided in potential file)"
+ISSUE_URL_PATTERN = re.compile(r"https?://\S+/issues/(\d+)")
+BUG_SECTION_HEADINGS = [
+    "Summary",
+    "Environment",
+    "Steps to Reproduce",
+    "Expected Behavior",
+    "Actual Behavior",
+    "Logs / Screenshots",
+    "Impact / Severity",
+]
+SMART_PUNCTUATION_MAP = {
+    "\u201c": '"',
+    "\u201d": '"',
+    "\u2018": "'",
+    "\u2019": "'",
+    "\u2013": "-",
+    "\u2014": "-",
+    "\u00a0": " ",
+}
+
+
+def strip_potential_marker(value: str) -> str:
+    """Remove `(Potential...)` suffix markers from heading values."""
+    cleaned = re.sub(r"\s*\(Potential[^)]*\)", "", value, flags=re.IGNORECASE).strip()
+    return cleaned or value.strip()
+
+
+def get_feature_name(content: str, file_path: Path) -> str:
+    """Derive feature name from markdown heading or filename fallback."""
+    heading_match = re.search(r"^\s*#\s+(.+)$", content, flags=re.MULTILINE)
+    if heading_match:
+        feature_name = strip_potential_marker(heading_match.group(1))
+        if feature_name:
+            return feature_name
+
+    name = file_path.name
+    return name[:-3] if name.lower().endswith(".md") else name
+
+
+def get_feature_path(feature_name: str) -> str:
+    """Convert feature name into a safe path token."""
+    replaced = re.sub(r"\s+", "_", feature_name)
+    return re.sub(r"[^A-Za-z0-9_-]", "", replaced)
+
+
+def get_section(content: str, heading: str) -> str:
+    """Extract markdown section body for a top-level `##` heading."""
+    escaped = re.escape(heading)
+    pattern = rf"^##\s+{escaped}\s*\r?\n(.*?)(?=^##\s+|\Z)"
+    match = re.search(pattern, content, flags=re.MULTILINE | re.DOTALL)
+    if not match:
+        return ""
+    return match.group(1).strip()
+
+
+def build_body(
+    work_mode: str,
+    problem: str,
+    behavior: str,
+    criteria: str,
+    constraints: str,
+    tests: str,
+    relative_path: str,
+) -> str:
+    """Construct the standard full-feature issue body."""
+    return (
+        f"- Work Mode: {work_mode}\n"
+        f"## Problem / Why\n{problem}\n\n"
+        f"## Proposed Behavior\n{behavior}\n\n"
+        f"## Acceptance Criteria\n{criteria}\n\n"
+        f"## Constraints & Risks\n{constraints}\n\n"
+        f"## Test Conditions\n{tests}\n\n"
+        f"## Source\nFrom: {relative_path}\n"
+    )
+
+
+def build_bug_body(work_mode: str, sections: dict[str, str], relative_path: str) -> str:
+    """Construct the bug issue body from canonical bug section headings."""
+    parts = [f"- Work Mode: {work_mode}"]
+    parts.extend(
+        f"## {heading}\n{sections[heading]}" for heading in BUG_SECTION_HEADINGS
+    )
+    parts.append(f"## Source\nFrom: {relative_path}")
+    return "\n\n".join(parts) + "\n"
+
+
+def evaluate_minor_audit_eligibility(content: str) -> tuple[bool, str]:
+    """Evaluate deterministic eligibility for minor-audit mode."""
+    lower = content.lower()
+    if "bootstrapped" in lower or "pre-cooked" in lower:
+        return True, "eligible: bootstrapped/pre-cooked"
+
+    production_files = len(
+        re.findall(r"^\s*-\s*(?:production\s+)?file\s*:", content, flags=re.MULTILINE)
+    )
+    has_low_risk = "low integration risk" in lower or "risk: low" in lower
+    if production_files <= 3 and has_low_risk:
+        return True, "eligible: <=3 production files and low integration risk"
+    if production_files > 3:
+        return False, "fallback: production file count exceeds 3"
+    return False, "fallback: missing low integration risk signal"
+
+
+def build_minor_audit_body(
+    work_mode: str,
+    problem: str,
+    implementation_intent: str,
+    acceptance_criteria: str,
+    dependencies_risks: str,
+    verification_steps: str,
+    evidence_checklist: str,
+    relative_path: str,
+) -> str:
+    """Build required issue sections for the minor-audit mode."""
+    return (
+        f"- Work Mode: {work_mode}\n"
+        f"## Problem / Why\n{problem}\n\n"
+        f"## Implementation Intent\n{implementation_intent}\n\n"
+        f"## Acceptance Criteria\n{acceptance_criteria}\n\n"
+        f"## Dependencies / Risks\n{dependencies_risks}\n\n"
+        f"## Verification Steps\n{verification_steps}\n\n"
+        f"## Evidence Checklist\n{evidence_checklist}\n\n"
+        f"## Source\nFrom: {relative_path}\n"
+    )
+
+
+def parse_issue_reference(output: list[str]) -> tuple[str | None, str | None]:
+    """Parse created issue URL and number from gh output lines."""
+    text = "\n".join(output)
+    match = ISSUE_URL_PATTERN.search(text)
+    if not match:
+        return None, None
+    return match.group(0), match.group(1)
+
+
+def extract_last_updated(issue_json: str) -> str | None:
+    """Extract issue updated date from gh JSON payload."""
+    try:
+        data = json.loads(issue_json)
+    except json.JSONDecodeError:
+        return None
+
+    updated_raw = data.get("updatedAt")
+    if not isinstance(updated_raw, str):
+        return None
+
+    try:
+        dt = datetime.fromisoformat(updated_raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return dt.date().isoformat()
+
+
+def find_meta_end(lines: list[str]) -> int:
+    """Locate insertion point where header metadata block ends."""
+    for idx, line in enumerate(lines):
+        if line.lstrip().startswith("## "):
+            return idx
+    return len(lines)
+
+
+def normalize_smart_punctuation(text: str) -> str:
+    """Replace common smart punctuation characters with ASCII equivalents."""
+    return text.translate(str.maketrans(SMART_PUNCTUATION_MAP))
+
+
+def set_line_value(lines: list[str], label: str, value: str, meta_end: int) -> int:
+    """Set or insert a metadata line and return updated metadata boundary index."""
+    pattern = re.compile(rf"^- {re.escape(label)}:")
+    for idx, line in enumerate(lines):
+        if pattern.match(line):
+            lines[idx] = f"- {label}: {value}"
+            return meta_end
+    lines.insert(meta_end, f"- {label}: {value}")
+    return meta_end + 1
+
+
+def update_metadata_lines(
+    lines: list[str],
+    feature_name: str,
+    issue_number: str,
+    issue_url: str,
+    last_updated: str | None,
+    feature_path: str,
+) -> list[str]:
+    """Apply issue metadata updates to potential markdown lines."""
+    if lines:
+        lines[0] = f"# {feature_name} (Issue #{issue_number})"
+
+    meta_end = find_meta_end(lines)
+    meta_end = set_line_value(lines, "Issue", f"#{issue_number}", meta_end)
+    meta_end = set_line_value(lines, "Issue URL", issue_url, meta_end)
+    if last_updated:
+        meta_end = set_line_value(lines, "Last Updated", last_updated, meta_end)
+    status_value = (
+        f"Promoted -> docs/features/active/{feature_path}/ (Issue #{issue_number})"
+    )
+    set_line_value(lines, "Status", status_value, meta_end)
+    return lines